diff --git a/.gitignore b/.gitignore
index 29489633104..8c0ce9c23d5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,8 @@
 .DS_Store
 /venv/
 /venv.old/
+/venv.stale.runtime-*/
+/.hermes-runtime/
 /_pycache/
 *.pyc*
 __pycache__/
diff --git a/acp_adapter/entry.py b/acp_adapter/entry.py
index 55773536122..fb9ed95450c 100644
--- a/acp_adapter/entry.py
+++ b/acp_adapter/entry.py
@@ -32,6 +32,7 @@ else:
 import argparse
 import asyncio
 import logging
+import os
 import sys
 from pathlib import Path
 from hermes_constants import get_hermes_home
@@ -251,11 +252,13 @@ def main(argv: list[str] | None = None) -> None:
     # MCP servers dynamically via asyncio.to_thread inside the event
     # loop; that path is unaffected.)  Moved from model_tools.py module
     # scope to avoid freezing the gateway's loop on lazy import (#16856).
-    try:
-        from tools.mcp_tool import discover_mcp_tools
-        discover_mcp_tools()
-    except Exception:
-        logger.debug("MCP tool discovery failed at ACP startup", exc_info=True)
+    # Metadata-only hosts can opt out of unrelated global MCP startup.
+    if os.environ.get("HERMES_ACP_SKIP_CONFIGURED_MCP", "").strip() != "1":
+        try:
+            from tools.mcp_tool import discover_mcp_tools
+            discover_mcp_tools()
+        except Exception:
+            logger.debug("MCP tool discovery failed at ACP startup", exc_info=True)
 
     agent = HermesACPAgent()
     try:
diff --git a/acp_adapter/server.py b/acp_adapter/server.py
index 3e79bdcd38a..7fee2d932f8 100644
--- a/acp_adapter/server.py
+++ b/acp_adapter/server.py
@@ -85,6 +85,110 @@ from tools.approval import (
 
 logger = logging.getLogger(__name__)
 
+
+def _named_custom_provider_catalogs() -> list[tuple[str, str, list[tuple[str, str]]]]:
+    """Return ``(slug, label, [(model_id, description), ...])`` for named endpoints.
+
+    Covers both the v12 ``providers:`` mapping and the legacy
+    ``custom_providers:`` list.  These endpoints never appear in canonical
+    provider enumeration, so without this the ACP model selector hides every
+    named endpoint that the TUI ``/model`` picker already renders (#47039
+    implemented named-endpoint rows for the TUI surface only).
+
+    Model lists come from the entry's declared models (``default_model`` +
+    ``models``), refreshed from the endpoint's live ``/models`` listing when a
+    credential is available and ``discover_models`` is not disabled.  Declared
+    models are kept even when live discovery fails — some OpenAI-compatible
+    endpoints (e.g. Bedrock Mantle Responses) expose no ``/models`` route at
+    all yet serve the declared models fine.
+
+    Slugs use the ``custom:<name>`` shape that ``parse_model_input`` and
+    ``resolve_runtime_provider`` already resolve, so encoded choice ids
+    (``custom:<name>:<model>``) round-trip through ``set_session_model``
+    unchanged.
+    """
+    try:
+        from hermes_cli.config import (
+            get_compatible_custom_providers,
+            is_provider_enabled,
+            load_config,
+        )
+        from hermes_cli.models import fetch_api_models
+    except ImportError:
+        return []
+
+    try:
+        cfg = load_config()
+        entries = get_compatible_custom_providers(cfg)
+    except Exception:
+        logger.debug("Could not load named custom providers", exc_info=True)
+        return []
+
+    # ``get_compatible_custom_providers`` drops the ``enabled`` flag during
+    # normalization, so collect explicitly disabled provider keys from the
+    # raw config and skip their entries below.
+    disabled_keys: set[str] = set()
+    raw_providers = cfg.get("providers") if isinstance(cfg, dict) else None
+    if isinstance(raw_providers, dict):
+        for raw_key, raw_entry in raw_providers.items():
+            if isinstance(raw_entry, dict) and not is_provider_enabled(raw_entry):
+                disabled_keys.add(str(raw_key).strip().lower())
+
+    catalogs: list[tuple[str, str, list[tuple[str, str]]]] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        provider_key = str(entry.get("provider_key", "") or "").strip()
+        if provider_key.lower() in disabled_keys:
+            continue
+        name = str(entry.get("name", "") or "").strip()
+        base_url = str(entry.get("base_url", "") or "").strip()
+        if not name or not base_url:
+            continue
+        slug_source = provider_key or name
+        slug = "custom:" + slug_source.strip().lower().replace(" ", "-")
+
+        api_key = str(entry.get("api_key", "") or "").strip()
+        if not api_key:
+            key_env = str(entry.get("key_env", "") or "").strip()
+            api_key = os.environ.get(key_env, "").strip() if key_env else ""
+
+        declared: list[str] = []
+        default_model = str(entry.get("model", "") or "").strip()
+        if default_model:
+            declared.append(default_model)
+        models_cfg = entry.get("models")
+        if isinstance(models_cfg, dict):
+            for mid in models_cfg:
+                mid = str(mid or "").strip()
+                if mid and mid not in declared:
+                    declared.append(mid)
+
+        if not api_key and not declared:
+            # No credential to discover with and nothing declared:
+            # not addressable from the selector.
+            continue
+
+        model_ids = list(declared)
+        discover = entry.get("discover_models", True)
+        if isinstance(discover, str):
+            discover = discover.lower() not in {"false", "no", "0"}
+        if discover and api_key:
+            try:
+                live = fetch_api_models(
+                    api_key, base_url, api_mode=entry.get("api_mode")
+                )
+            except Exception:
+                live = None
+            if live:
+                model_ids = declared + [m for m in live if m not in declared]
+
+        if not model_ids:
+            continue
+        catalogs.append((slug, name, [(mid, "") for mid in model_ids]))
+
+    return catalogs
+
 try:
     from hermes_cli import __version__ as HERMES_VERSION
 except Exception:
@@ -97,6 +201,13 @@ _executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="acp-agent")
 # does not expose a client-side limit, so this is a fixed cap that clients
 # paginate against using `cursor` / `next_cursor`.
 _LIST_SESSIONS_PAGE_SIZE = 50
+# Per-provider cap for the ACP model selector. ACP clients (Zed, Buzz) render
+# the whole `availableModels` array in one dropdown, so an unbounded
+# cross-provider catalog degrades the picker. Mirrors the cap the MoA picker
+# already uses (`hermes_cli/moa_cmd.py`). This bounds each provider's row, not
+# the total; aggregator providers stay intentionally uncapped inside the shared
+# inventory, and the current model is always kept via the fallback insert below.
+ACP_MAX_MODELS_PER_PROVIDER = 200
 _MAX_ACP_RESOURCE_BYTES = 512 * 1024
 _TEXT_RESOURCE_MIME_PREFIXES = ("text/",)
 _TEXT_RESOURCE_MIME_TYPES = {
@@ -585,46 +696,108 @@ class HermesACPAgent(acp.Agent):
         return f"{raw_provider}:{raw_model}"
 
     def _build_model_state(self, state: SessionState) -> SessionModelState | None:
-        """Return the ACP model selector payload for editors like Zed."""
+        """Return authenticated providers and their models for ACP clients.
+
+        The shared Hermes inventory is also used by ``hermes model``, the TUI,
+        and the dashboard. Keeping ACP on that substrate prevents its selector
+        from silently collapsing to the current provider's curated list.
+        """
         model = str(state.model or getattr(state.agent, "model", "") or "").strip()
         provider = getattr(state.agent, "provider", None) or detect_provider() or "openrouter"
 
         try:
-            from hermes_cli.models import curated_models_for_provider, normalize_provider, provider_label
+            from hermes_cli.inventory import build_models_payload, load_picker_context
+            from hermes_cli.models import normalize_provider, provider_label
 
             normalized_provider = normalize_provider(provider)
-            provider_name = provider_label(normalized_provider)
+            context = load_picker_context().with_overrides(
+                current_provider=normalized_provider,
+                current_model=model,
+                current_base_url=str(getattr(state.agent, "base_url", "") or ""),
+            )
+            payload = build_models_payload(
+                context,
+                explicit_only=True,
+                include_unconfigured=False,
+                picker_hints=False,
+                canonical_order=True,
+                pricing=False,
+                capabilities=False,
+                refresh=False,
+                probe_custom_providers=False,
+                probe_current_custom_provider=False,
+                max_models=ACP_MAX_MODELS_PER_PROVIDER,
+            )
+
             available_models: list[ModelInfo] = []
             seen_ids: set[str] = set()
-
-            for model_id, description in curated_models_for_provider(normalized_provider):
-                rendered_model = str(model_id or "").strip()
-                if not rendered_model:
+            for row in payload.get("providers") or []:
+                row_provider = normalize_provider(str(row.get("slug") or "").strip())
+                if not row_provider:
                     continue
-                choice_id = self._encode_model_choice(normalized_provider, rendered_model)
-                if choice_id in seen_ids:
-                    continue
-                desc_parts = [f"Provider: {provider_name}"]
-                if description:
-                    desc_parts.append(str(description).strip())
-                if rendered_model == model:
-                    desc_parts.append("current")
-                available_models.append(
-                    ModelInfo(
-                        model_id=choice_id,
-                        name=rendered_model,
-                        description=" • ".join(part for part in desc_parts if part),
-                    )
+                provider_name = str(row.get("name") or "").strip() or provider_label(
+                    row_provider
                 )
-                seen_ids.add(choice_id)
+                for model_entry in row.get("models") or []:
+                    if isinstance(model_entry, dict):
+                        rendered_model = str(
+                            model_entry.get("id")
+                            or model_entry.get("model")
+                            or model_entry.get("name")
+                            or ""
+                        ).strip()
+                    else:
+                        rendered_model = str(model_entry or "").strip()
+                    if not rendered_model:
+                        continue
+                    choice_id = self._encode_model_choice(row_provider, rendered_model)
+                    if choice_id in seen_ids:
+                        continue
+                    is_current = (
+                        row_provider == normalized_provider and rendered_model == model
+                    )
+                    description = f"Provider: {provider_name}"
+                    if is_current:
+                        description += " • current"
+                    available_models.append(
+                        ModelInfo(
+                            model_id=choice_id,
+                            name=f"{provider_name} · {rendered_model}",
+                            description=description,
+                        )
+                    )
+                    seen_ids.add(choice_id)
+
+            # Named user-defined endpoints (providers: / custom_providers:)
+            # are invisible to canonical provider enumeration — append them
+            # so editor clients can select them like the TUI /model picker.
+            for named_slug, named_label, named_catalog in _named_custom_provider_catalogs():
+                for named_model, named_desc in named_catalog:
+                    named_choice = self._encode_model_choice(named_slug, named_model)
+                    if not named_choice or named_choice in seen_ids:
+                        continue
+                    named_parts = [f"Provider: {named_label}"]
+                    if named_desc:
+                        named_parts.append(str(named_desc).strip())
+                    if named_slug == normalized_provider and named_model == model:
+                        named_parts.append("current")
+                    available_models.append(
+                        ModelInfo(
+                            model_id=named_choice,
+                            name=named_model,
+                            description=" • ".join(part for part in named_parts if part),
+                        )
+                    )
+                    seen_ids.add(named_choice)
 
             current_model_id = self._encode_model_choice(normalized_provider, model)
             if current_model_id and current_model_id not in seen_ids:
+                provider_name = provider_label(normalized_provider)
                 available_models.insert(
                     0,
                     ModelInfo(
                         model_id=current_model_id,
-                        name=model,
+                        name=f"{provider_name} · {model}",
                         description=f"Provider: {provider_name} • current",
                     ),
                 )
@@ -1588,7 +1761,16 @@ class HermesACPAgent(acp.Agent):
                     clear_session_vars,
                     set_session_vars,
                 )
-                session_tokens = set_session_vars(session_key=session_id)
+                # ``cwd`` pins the logical working directory for this context,
+                # which is what the system prompt's "Current working directory"
+                # line reports (agent/prompt_builder.py -> resolve_agent_cwd).
+                # Without it the prompt advertises the global Hermes workspace
+                # while the tools are rooted at the client's project, so the
+                # model emits absolute paths under ~/.hermes/workspace and the
+                # edit silently lands outside the editor's workspace.
+                session_tokens = set_session_vars(
+                    session_key=session_id, cwd=state.cwd,
+                )
             except Exception:
                 session_tokens = None
                 clear_session_vars = None  # type: ignore[assignment]
@@ -1875,8 +2057,26 @@ class HermesACPAgent(acp.Agent):
         if handler is None:
             return None  # not a known command — let the LLM handle it
 
-        try:
+        # Slash handlers run on the event-loop thread, OUTSIDE the per-turn
+        # contextvars.copy_context() that pins the session cwd for the agent
+        # call. ``/compress`` and ``/model`` reach code that REBUILDS the
+        # system prompt (agent._build_system_prompt -> resolve_agent_cwd), so
+        # an unpinned handler bakes the Hermes install tree into the session's
+        # cached prompt — persisted, and therefore poisoning every later turn
+        # even though the turn itself is pinned. Pin inside a fresh context so
+        # the write can't leak into other concurrent ACP sessions and needs no
+        # teardown.
+        def _dispatch() -> str | None:
+            try:
+                from agent.runtime_cwd import set_session_cwd
+
+                set_session_cwd(state.cwd)
+            except Exception:
+                logger.debug("Could not pin ACP session cwd for slash command", exc_info=True)
             return handler(args, state)
+
+        try:
+            return contextvars.copy_context().run(_dispatch)
         except Exception as e:
             logger.error("Slash command /%s error: %s", cmd, e, exc_info=True)
             return f"Error executing /{cmd}: {e}"
diff --git a/agent/agent_init.py b/agent/agent_init.py
index 241d3689ebd..955ca11cff8 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -69,6 +69,43 @@ def _ra():
     return run_agent
 
 
+def _moa_reference_output_allowed(agent: Any) -> bool:
+    """Keep MoA display events off only the machine-readable ``-Q`` surface."""
+    return not (
+        getattr(agent, "platform", None) == "cli"
+        and getattr(agent, "tool_progress_mode", "all") == "off"
+    )
+
+
+def _relay_moa_reference_event(agent: Any, event: str, **kwargs: Any) -> None:
+    """Relay MoA display events while preserving the ``-Q`` stdout contract."""
+    if not _moa_reference_output_allowed(agent):
+        return
+    cb = getattr(agent, "tool_progress_callback", None)
+    if cb is None:
+        return
+    try:
+        if event == "moa.reference":
+            cb(
+                "moa.reference",
+                str(kwargs.get("label") or ""),
+                str(kwargs.get("text") or ""),
+                None,
+                moa_index=kwargs.get("index"),
+                moa_count=kwargs.get("count"),
+            )
+        elif event == "moa.aggregating":
+            cb(
+                "moa.aggregating",
+                str(kwargs.get("aggregator") or ""),
+                None,
+                None,
+                moa_ref_count=kwargs.get("ref_count"),
+            )
+    except Exception:
+        pass
+
+
 def _normalize_route_base_url(base_url: Any) -> str:
     """Canonicalize an endpoint URL for model-route identity comparisons."""
     return normalize_route_base_url(base_url)
@@ -786,9 +823,10 @@ def init_agent(
     # Anthropic prompt caching: auto-enabled for Claude models on native
     # Anthropic, OpenRouter, and third-party gateways that speak the
     # Anthropic protocol (``api_mode == 'anthropic_messages'``). Reduces
-    # input costs by ~75% on multi-turn conversations. Uses system_and_3
-    # strategy (4 breakpoints). See ``_anthropic_prompt_cache_policy``
-    # for the layout-vs-transport decision.
+    # input costs by ~75% on multi-turn conversations. Uses four breakpoints:
+    # the static system prefix, full system prompt, and last two messages
+    # (falling back to system-and-3 when no static prefix is available). See
+    # ``_anthropic_prompt_cache_policy`` for the layout-vs-transport decision.
     agent._use_prompt_caching, agent._use_native_cache_layout = (
         agent._anthropic_prompt_cache_policy()
     )
@@ -1025,49 +1063,20 @@ def init_agent(
                 elif isinstance(effective_key, str) and len(effective_key) > 12:
                     print(f"🔑 Using token: {effective_key[:8]}...{effective_key[-4:]}")
     elif agent.provider == "moa":
-        from agent.moa_loop import MoAClient
+        from agent.moa_loop import build_moa_facade
         agent.api_mode = "chat_completions"
 
-        # Route reference-model outputs to the agent's tool_progress_callback so
+        # build_moa_facade wires the reference relay that routes
+        # reference-model outputs to the agent's tool_progress_callback so
         # every surface that already consumes it (CLI spinner/scrollback, TUI,
-        # desktop, gateway) can show each reference's answer as a labelled block
-        # before the aggregator acts. The facade emits "moa.reference" and
-        # "moa.aggregating" events; we forward them through the same callback
-        # the tool lifecycle uses. Best-effort and cache-safe — these are
-        # display-only events, they never touch the message history.
-        def _moa_reference_relay(event: str, **kwargs: Any) -> None:
-            cb = getattr(agent, "tool_progress_callback", None)
-            if cb is None:
-                return
-            try:
-                if event == "moa.reference":
-                    label = str(kwargs.get("label") or "")
-                    text = str(kwargs.get("text") or "")
-                    idx = kwargs.get("index")
-                    count = kwargs.get("count")
-                    cb(
-                        "moa.reference",
-                        label,
-                        text,
-                        None,
-                        moa_index=idx,
-                        moa_count=count,
-                    )
-                elif event == "moa.aggregating":
-                    cb(
-                        "moa.aggregating",
-                        str(kwargs.get("aggregator") or ""),
-                        None,
-                        None,
-                        moa_ref_count=kwargs.get("ref_count"),
-                    )
-            except Exception:
-                pass
-
-        agent.client = MoAClient(
-            agent.model or "default",
-            reference_callback=_moa_reference_relay,
-        )
+        # desktop, gateway) can show each reference's answer as a labelled
+        # block before the aggregator acts. The facade emits "moa.reference",
+        # "moa.progress", "moa.phase", and "moa.aggregating" events, forwarded
+        # through the same callback the tool lifecycle uses. Best-effort and
+        # cache-safe — display-only events, they never touch the message
+        # history. The factory is shared with the fallback-restore/recovery
+        # paths so a restored facade keeps emitting these events (#53802).
+        agent.client = build_moa_facade(agent, agent.model)
         agent._client_kwargs = {}
         agent.api_key = api_key or "moa-virtual-provider"
         agent.base_url = "moa://local"
@@ -1333,6 +1342,13 @@ def init_agent(
                     print("⚠️  Warning: API key appears invalid or missing")
         except Exception as e:
             raise RuntimeError(f"Failed to initialize OpenAI client: {e}")
+
+    # Keep a stable identity for the pool entry that supplied this runtime.
+    # OAuth refreshes can replace the runtime token before a failed request is
+    # recovered, so the mutable API-key value alone cannot reliably attribute
+    # the failure to its source entry.
+    from agent.agent_runtime_helpers import sync_credential_pool_entry_id
+    sync_credential_pool_entry_id(agent)
     
     # Provider fallback chain — ordered list of backup providers tried
     # when the primary is exhausted (rate-limit, overload, connection
@@ -1479,6 +1495,9 @@ def init_agent(
     
     # Cached system prompt -- built once per session, only rebuilt on compression
     agent._cached_system_prompt: Optional[str] = None
+    # Cross-session-stable prefix of the cached prompt. It remains separate
+    # from the persisted string and is used only to place an early cache marker.
+    agent._cached_system_prompt_static: Optional[str] = None
     
     # Filesystem checkpoint manager (transparent — not a tool)
     from tools.checkpoint_manager import CheckpointManager
@@ -1810,6 +1829,28 @@ def init_agent(
     compression_enabled = str(_compression_cfg.get("enabled", True)).lower() in {"true", "1", "yes"}
     compression_target_ratio = float(_compression_cfg.get("target_ratio", 0.20))
     compression_protect_last = int(_compression_cfg.get("protect_last_n", 20))
+    # Minimum REAL (actionable) user messages guaranteed to survive in the
+    # uncompressed tail (compression.min_tail_user_messages).  Default 1
+    # preserves current behavior exactly — the existing single-user tail
+    # anchor.  Values > 1 extend the guarantee to the last N actionable
+    # user turns.  Booleans rejected (bool subclasses int), non-int-like
+    # values fall back to 1, floor at 1.
+    _raw_min_tail_users = _compression_cfg.get("min_tail_user_messages", 1)
+    if isinstance(_raw_min_tail_users, bool):
+        compression_min_tail_users = 1
+    elif isinstance(_raw_min_tail_users, int):
+        compression_min_tail_users = _raw_min_tail_users
+    elif isinstance(_raw_min_tail_users, float):
+        compression_min_tail_users = (
+            int(_raw_min_tail_users) if _raw_min_tail_users.is_integer() else 1
+        )
+    else:
+        try:
+            compression_min_tail_users = int(str(_raw_min_tail_users).strip())
+        except (TypeError, ValueError):
+            compression_min_tail_users = 1
+    if compression_min_tail_users < 1:
+        compression_min_tail_users = 1
     # Cap on compression retry rounds before a turn gives up with "max
     # compression attempts reached" (compression.max_attempts).  Hardcoding 3
     # strands sessions that legitimately need more rounds — e.g. a restart
@@ -1838,6 +1879,39 @@ def init_agent(
     if compression_max_attempts < 1:
         compression_max_attempts = 3
     compression_max_attempts = min(compression_max_attempts, 10)
+
+    def _parse_prune_int(raw, default):
+        # Same parser semantics as compression.max_attempts above: reject
+        # booleans (bool subclasses int — YAML `true` would coerce to 1),
+        # reject fractional floats rather than truncating them, accept
+        # integral floats and numeric strings, fall back to the default on
+        # anything else.
+        if isinstance(raw, bool):
+            return default
+        if isinstance(raw, int):
+            return raw
+        if isinstance(raw, float):
+            return int(raw) if raw.is_integer() else default
+        try:
+            return int(str(raw).strip())
+        except (TypeError, ValueError):
+            return default
+
+    # Opt-in proactive tool-result prune trigger (0 = disabled — the
+    # default, so an unset key is behavior-neutral).  Negative values are
+    # treated as disabled rather than erroring.
+    compression_proactive_prune_tokens = max(
+        0, _parse_prune_int(_compression_cfg.get("proactive_prune_tokens", 0), 0)
+    )
+    compression_proactive_prune_min_chars = _parse_prune_int(
+        _compression_cfg.get("proactive_prune_min_result_chars", 8000), 8000
+    )
+    compression_proactive_prune_min_reclaim = max(
+        0,
+        _parse_prune_int(
+            _compression_cfg.get("proactive_prune_min_reclaim_tokens", 4096), 4096
+        ),
+    )
     # protect_first_n is the number of non-system messages to protect at
     # the head, in addition to the system prompt (which is always
     # implicitly protected by the compressor).  Floor at 0 — a value of
@@ -2312,6 +2386,10 @@ def init_agent(
             max_tokens=agent.max_tokens,
             model_thresholds=compression_model_thresholds,
             threshold_tokens_cap=compression_threshold_tokens,
+            proactive_prune_tokens=compression_proactive_prune_tokens,
+            proactive_prune_min_result_chars=compression_proactive_prune_min_chars,
+            proactive_prune_min_reclaim_tokens=compression_proactive_prune_min_reclaim,
+            min_tail_user_messages=compression_min_tail_users,
         )
     _bind_session_state = getattr(agent.context_compressor, "bind_session_state", None)
     if callable(_bind_session_state):
diff --git a/agent/agent_runtime_helpers.py b/agent/agent_runtime_helpers.py
index 9bd59daa0cc..b70afabfc4e 100644
--- a/agent/agent_runtime_helpers.py
+++ b/agent/agent_runtime_helpers.py
@@ -850,6 +850,25 @@ def strip_think_blocks(agent, content: str) -> str:
 
 
 
+def sync_credential_pool_entry_id(agent) -> None:
+    """Rebind ``agent._credential_pool_entry_id`` from the current pool + key.
+
+    OAuth refreshes can replace the runtime token before a failed request is
+    recovered, so the mutable API-key value alone cannot reliably attribute
+    the failure to its source entry.  This resolves the stable pool-entry ID
+    for the agent's current ``api_key`` and clears it when no pool is bound.
+    """
+    pool = getattr(agent, "_credential_pool", None)
+    try:
+        agent._credential_pool_entry_id = (
+            pool.entry_id_for_api_key(getattr(agent, "api_key", None))
+            if pool is not None
+            else None
+        )
+    except Exception:
+        agent._credential_pool_entry_id = None
+
+
 def recover_with_credential_pool(
     agent,
     *,
@@ -934,10 +953,30 @@ def recover_with_credential_pool(
     # failing entry exactly; fall back to current()'s key only when the agent
     # carries no key at all.
     _api_key_hint = getattr(agent, "api_key", None) or None
+    _raw_credential_id = getattr(agent, "_credential_pool_entry_id", None)
+    _credential_id = (
+        _raw_credential_id
+        if isinstance(_raw_credential_id, str) and _raw_credential_id
+        else None
+    )
     if not _api_key_hint:
         _cur = pool.current()
         if _cur:
             _api_key_hint = getattr(_cur, "runtime_api_key", None)
+            if not _credential_id:
+                _current_id = getattr(_cur, "id", None)
+                if isinstance(_current_id, str) and _current_id:
+                    _credential_id = _current_id
+
+    def _rotate_failed_credential(rotate_status: int):
+        kwargs = {
+            "status_code": rotate_status,
+            "error_context": error_context,
+            "api_key_hint": _api_key_hint,
+        }
+        if _credential_id:
+            kwargs["credential_id"] = _credential_id
+        return pool.mark_exhausted_and_rotate(**kwargs)
 
     effective_reason = classified_reason
     if effective_reason is None:
@@ -972,11 +1011,7 @@ def recover_with_credential_pool(
         # Runtime credentials can be resolved by a separate pool instance,
         # leaving this recovery pool without ``current_id``. Match the key
         # that actually failed instead of quarantining a different account.
-        next_entry = pool.mark_exhausted_and_rotate(
-            status_code=rotate_status,
-            error_context=error_context,
-            api_key_hint=_api_key_hint,
-        )
+        next_entry = _rotate_failed_credential(rotate_status)
         if next_entry is not None:
             _ra().logger.info(
                 "Credential %s (billing) — rotated to pool entry %s",
@@ -995,8 +1030,13 @@ def recover_with_credential_pool(
         # Prefer the entry matching the failing key over the shared current()
         # pointer, for the same attribution reason as above.
         current_entry = None
-        if _api_key_hint:
+        if _credential_id:
             current_entry = next(
+                (e for e in pool.entries() if e.id == _credential_id),
+                None,
+            )
+        if _api_key_hint:
+            current_entry = current_entry or next(
                 (e for e in pool.entries() if e.runtime_api_key == _api_key_hint),
                 None,
             )
@@ -1009,11 +1049,7 @@ def recover_with_credential_pool(
                 current_last_status,
             )
             rotate_status = status_code if status_code is not None else 429
-            next_entry = pool.mark_exhausted_and_rotate(
-                status_code=rotate_status,
-                error_context=error_context,
-                api_key_hint=_api_key_hint,
-            )
+            next_entry = _rotate_failed_credential(rotate_status)
             if next_entry is not None:
                 _ra().logger.info(
                     "Credential %s (rate limit, pre-exhausted) — rotated to pool entry %s",
@@ -1037,11 +1073,7 @@ def recover_with_credential_pool(
         if not has_retried_429 and not usage_limit_reached:
             return False, True
         rotate_status = status_code if status_code is not None else 429
-        next_entry = pool.mark_exhausted_and_rotate(
-            status_code=rotate_status,
-            error_context=error_context,
-            api_key_hint=_api_key_hint,
-        )
+        next_entry = _rotate_failed_credential(rotate_status)
         if next_entry is not None:
             _ra().logger.info(
                 "Credential %s (rate limit) — rotated to pool entry %s",
@@ -1113,7 +1145,10 @@ def recover_with_credential_pool(
         # the shared pointer can reference a different, healthy entry, and
         # refreshing it would consume that entry's single-use refresh token
         # (or mark it exhausted on failure) for a failure it never had.
-        refreshed = pool.try_refresh_matching(api_key_hint=_api_key_hint)
+        refresh_kwargs = {"api_key_hint": _api_key_hint}
+        if _credential_id:
+            refresh_kwargs["credential_id"] = _credential_id
+        refreshed = pool.try_refresh_matching(**refresh_kwargs)
         if refreshed is not None:
             # ``try_refresh_matching()`` re-mints a fresh OAuth token and reports
             # success even when the upstream keeps rejecting it — a single-entry
@@ -1145,11 +1180,7 @@ def recover_with_credential_pool(
         # Refresh failed — rotate to next credential instead of giving up.
         # The failed entry is already marked exhausted by the refresh attempt.
         rotate_status = status_code if status_code is not None else 401
-        next_entry = pool.mark_exhausted_and_rotate(
-            status_code=rotate_status,
-            error_context=error_context,
-            api_key_hint=_api_key_hint,
-        )
+        next_entry = _rotate_failed_credential(rotate_status)
         if next_entry is not None:
             _ra().logger.info(
                 "Credential %s (auth refresh failed) — rotated to pool entry %s",
@@ -1194,11 +1225,17 @@ def try_recover_primary_transport(
         return False
 
     try:
-        # Close existing client to release stale connections
+        # Retire the existing client to release stale connections. #70773:
+        # never hard-close the shared client here — this runs on the
+        # conversation-loop thread while workers from stale-killed streaming
+        # attempts may still be unwinding their SSL BIOs on the old pool.
+        # ``_retire_shared_openai_client`` shuts the sockets down (FD-safe
+        # from any thread) and defers the FD release to GC, which cannot
+        # complete until every borrowing thread has unwound.
         if getattr(agent, "client", None) is not None:
             try:
-                agent._close_openai_client(
-                    agent.client, reason="primary_recovery", shared=True,
+                agent._retire_shared_openai_client(
+                    agent.client, reason="primary_recovery",
                 )
             except Exception:
                 pass
@@ -1225,6 +1262,14 @@ def try_recover_primary_transport(
             )
             agent._is_anthropic_oauth = rt["is_anthropic_oauth"]
             agent.client = None
+        elif (agent.provider or "").strip().lower() == "moa":
+            # MoA is a virtual provider with empty client_kwargs — rebuilding
+            # via _create_openai_client would raise "api_key client option
+            # must be set". Recreate the facade through the shared factory so
+            # the reference_callback relay survives recovery (#53802).
+            from agent.moa_loop import build_moa_facade
+
+            agent.client = build_moa_facade(agent, agent.model)
         else:
             agent.client = agent._create_openai_client(
                 dict(rt["client_kwargs"]),
@@ -1388,7 +1433,18 @@ def restore_primary_runtime(agent) -> bool:
         )
 
         # ── Rebuild client for the primary provider ──
-        if agent.api_mode == "anthropic_messages":
+        if agent.provider == "moa":
+            # MoA is a virtual chat-completions provider.  It never has real
+            # OpenAI client kwargs; restoring it after a fallback must recreate
+            # the facade, not call OpenAI() with an empty api_key.  Use the
+            # shared factory so the restored facade keeps the reference_callback
+            # relay wired at init — a bare MoAClient() would silently stop
+            # emitting moa.reference/moa.aggregating display events (#53802).
+            from agent.moa_loop import build_moa_facade
+
+            agent.client = build_moa_facade(agent, agent.model)
+            agent._anthropic_client = None
+        elif agent.api_mode == "anthropic_messages":
             from agent.anthropic_adapter import build_anthropic_client
             agent._anthropic_api_key = rt["anthropic_api_key"]
             agent._anthropic_base_url = rt["anthropic_base_url"]
@@ -1441,6 +1497,7 @@ def restore_primary_runtime(agent) -> bool:
                 pool_matches_primary = False
         if pool is not None and pool_provider and not pool_matches_primary:
             agent._credential_pool = None
+            agent._credential_pool_entry_id = None
             try:
                 from agent.credential_pool import load_pool
 
@@ -1460,6 +1517,7 @@ def restore_primary_runtime(agent) -> bool:
         # the pool for its current best entry and swap the live credential in.
         # When the pool is absent, empty, or the entry has no usable key, we
         # keep the snapshot key (the existing behavior).  Fixes #25205.
+        agent._credential_pool_entry_id = None
         pool = getattr(agent, "_credential_pool", None)
         if pool is not None and pool.has_available():
             entry = pool.select()
@@ -2056,6 +2114,9 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
     # restore the original pool (issue #52727: pool reload is part of this
     # switch and must be reversible on rollback).
     _snapshot["_credential_pool"] = getattr(agent, "_credential_pool", _MISSING)
+    _snapshot["_credential_pool_entry_id"] = getattr(
+        agent, "_credential_pool_entry_id", _MISSING
+    )
 
     try:
         # Clear the per-config context_length override so the new model's
@@ -2112,6 +2173,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
             # A pool bound to the old provider is worse than no pool: the
             # recovery guard rejects it and every later 401/429 skips rotation.
             agent._credential_pool = None
+            agent._credential_pool_entry_id = None
             try:
                 from agent.credential_pool import load_pool
                 agent._credential_pool = load_pool(new_provider)
@@ -2121,10 +2183,9 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
                     "continuing without pool rotation this turn",
                     new_provider, _pool_exc,
                 )
-
         # ── Build new client ──
         if (new_provider or "").strip().lower() == "moa":
-            from agent.moa_loop import MoAClient
+            from agent.moa_loop import build_moa_facade
 
             # The MoA virtual provider speaks only chat.completions via the
             # MoAClient facade — the aggregator's real transport
@@ -2141,7 +2202,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
             agent.api_key = api_key or "moa-virtual-provider"
             agent.base_url = "moa://local"
             agent._client_kwargs = {}
-            agent.client = MoAClient(agent.model or "default")
+            agent.client = build_moa_facade(agent, agent.model)
         elif api_mode == "anthropic_messages":
             from agent.anthropic_adapter import (
                 build_anthropic_client,
@@ -2217,6 +2278,8 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
                 reason="switch_model",
                 shared=True,
             )
+
+        sync_credential_pool_entry_id(agent)
     except Exception:
         # Rollback every mutated field to the pre-swap snapshot so the agent
         # is left consistent (old model + old provider + old client) and the
diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index 38431a8c1f5..7fa3ba391fd 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -368,7 +368,7 @@ def _detect_claude_code_version() -> str:
         try:
             result = _sp.run(
                 [cmd, "--version"],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             )
             if result.returncode == 0 and result.stdout.strip():
                 # Output is like "2.1.74 (Claude Code)" or just "2.1.74"
@@ -914,7 +914,7 @@ def _read_claude_code_credentials_from_keychain() -> Optional[Dict[str, Any]]:
              "-s", "Claude Code-credentials",
              "-w"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=5,
             stdin=subprocess.DEVNULL,
         )
@@ -1920,10 +1920,18 @@ def _sanitize_replay_block(b: Dict[str, Any]) -> Optional[Dict[str, Any]]:
         return None
     btype = b.get("type")
     if btype == "text":
-        # Coerce empty/whitespace-only text to a non-whitespace placeholder;
-        # the Messages input schema rejects blank text blocks (#69512), and a
-        # blank block stored in history replays on every turn → permanent 400.
-        out: Dict[str, Any] = {"type": "text", "text": _safe_text(b.get("text", ""))}
+        text_val = b.get("text", "")
+        # Bedrock and strict Anthropic-compatible endpoints reject text
+        # blocks where "text" is empty or whitespace-only (#69512). Drop the
+        # blank block (the caller relocates any cache_control it carried and
+        # falls back to a non-whitespace placeholder when nothing survives)
+        # rather than coercing in place — a coerced "(empty)" block would be
+        # model-visible noise next to surviving thinking/tool_use blocks.
+        # Type-safe: captured blocks can carry text=None from an invalid
+        # upstream payload, which a bare .strip() would crash on.
+        if not isinstance(text_val, str) or not text_val.strip():
+            return None
+        out: Dict[str, Any] = {"type": "text", "text": text_val}
         # citations is input-valid ONLY when it's a non-empty list; the SDK
         # emits citations=None on responses, which the input schema rejects.
         cits = b.get("citations")
@@ -2011,9 +2019,17 @@ def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
                 parsed_args = {}
             redacted_input_by_id[_sanitize_tool_id(tc.get("id", ""))] = parsed_args
         replayed: List[Dict[str, Any]] = []
+        _relocated_replay_cache_control = None
+        _dropped_blank_text = False
         for b in ordered_blocks:
             clean = _sanitize_replay_block(b)
             if clean is None:
+                if isinstance(b, dict) and b.get("type") == "text":
+                    _dropped_blank_text = True
+                if isinstance(b, dict) and isinstance(b.get("cache_control"), dict):
+                    # A dropped blank text block can still carry the cache
+                    # breakpoint marker -- relocate it rather than losing it.
+                    _relocated_replay_cache_control = b["cache_control"]
                 continue
             if clean.get("type") == "tool_use":
                 # Override raw (un-redacted) input with the redacted copy when
@@ -2023,20 +2039,68 @@ def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
                 if redacted is not None:
                     clean["input"] = redacted
             replayed.append(clean)
+        # When every text block was blank and nothing cacheable survived
+        # (e.g. signed thinking + a blank text block, or a SOLE blank
+        # cache-marked block), emit the non-whitespace placeholder so the
+        # replayed message stays schema-valid (#69512) and a relocated cache
+        # marker still has a carrier instead of being silently lost.
+        _has_cacheable_replay = any(
+            isinstance(b, dict) and b.get("type") in {"text", "tool_use"}
+            for b in replayed
+        )
+        if not _has_cacheable_replay and (
+            _dropped_blank_text or _relocated_replay_cache_control is not None
+        ):
+            replayed.append({"type": "text", "text": _EMPTY_TEXT_PLACEHOLDER})
         if replayed:
+            if _relocated_replay_cache_control is not None:
+                _apply_assistant_cache_control_to_last_cacheable_block(
+                    replayed, _relocated_replay_cache_control
+                )
             _apply_assistant_cache_control_to_last_cacheable_block(
                 replayed, m.get("cache_control")
             )
             return {"role": "assistant", "content": replayed}
 
     blocks = _extract_preserved_thinking_blocks(m)
+    # Cache markers dropped along with a blank block are relocated onto the
+    # last surviving cacheable block below (via
+    # _apply_assistant_cache_control_to_last_cacheable_block), rather than
+    # lost -- prompt_caching.py's _apply_cache_marker() sets cache_control
+    # directly on content[-1] for list content, so if that last part happens
+    # to be blank text, dropping it silently would lose the breakpoint.
+    _relocated_cache_control = None
     if content:
         if isinstance(content, list):
             converted_content = _convert_content_to_anthropic(content)
             if isinstance(converted_content, list):
-                blocks.extend(converted_content)
+                # Bedrock and strict Anthropic-compatible endpoints reject
+                # text blocks where "text" is empty or whitespace-only. The
+                # ordered-replay path enforces the same invariant via
+                # _sanitize_replay_block(). Type-safe against ANY invalid
+                # "text" value from an upstream payload -- None, or a
+                # truthy non-string like an int -- not just None: checking
+                # isinstance() first (rather than `blk.get("text") or ""`)
+                # means a non-string value is treated as blank/invalid
+                # instead of reaching .strip() and raising AttributeError.
+                for blk in converted_content:
+                    _blk_text = blk.get("text") if isinstance(blk, dict) else None
+                    if (
+                        isinstance(blk, dict)
+                        and blk.get("type") == "text"
+                        and (not isinstance(_blk_text, str) or not _blk_text.strip())
+                    ):
+                        if isinstance(blk.get("cache_control"), dict):
+                            _relocated_cache_control = blk["cache_control"]
+                        continue
+                    blocks.append(blk)
         else:
-            blocks.append({"type": "text", "text": str(content)})
+            # Scalar (non-list) content: a whitespace-only string is the
+            # same invalid-payload case as an empty list block -- drop it
+            # rather than emitting a blank text block.
+            text_str = str(content)
+            if text_str.strip():
+                blocks.append({"type": "text", "text": text_str})
     for tc in m.get("tool_calls", []):
         if not tc or not isinstance(tc, dict):
             continue
@@ -2052,9 +2116,6 @@ def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
             "name": fn.get("name", ""),
             "input": parsed_args,
         })
-    _apply_assistant_cache_control_to_last_cacheable_block(
-        blocks, m.get("cache_control")
-    )
     # Kimi's /coding endpoint (Anthropic protocol) requires assistant
     # tool-call messages to carry reasoning_content when thinking is
     # enabled server-side.  Preserve it as a thinking block so Kimi
@@ -2080,19 +2141,26 @@ def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
     )
     if isinstance(reasoning_content, str) and not _already_has_thinking:
         blocks.insert(0, {"type": "thinking", "thinking": reasoning_content})
-    # Anthropic rejects empty assistant content
-    effective = blocks or content
-    if not effective or effective == "":
-        effective = [{"type": "text", "text": _EMPTY_TEXT_PLACEHOLDER}]
-    elif isinstance(effective, list):
-        # The all-empty guard above misses a list that still contains a
-        # whitespace-only text block (e.g. from a content array of blank parts,
-        # or compression). Those also trip "text content blocks must contain
-        # non-whitespace text" (#69512). Coerce text blocks in place; other
-        # block types (thinking/tool_use/image) are left untouched.
-        for blk in effective:
-            if isinstance(blk, dict) and blk.get("type") == "text":
-                blk["text"] = _safe_text(blk.get("text", ""))
+    # Anthropic rejects empty assistant content. IMPORTANT: fall back only
+    # to the placeholder, never to the raw `content` variable -- `content`
+    # is the UNFILTERED original message content, and can itself be exactly
+    # the blank/whitespace-only payload the filtering above just removed
+    # (a sole blank text block, or scalar whitespace with no tool_calls).
+    # `blocks or content` there would silently restore the invalid provider
+    # payload this function exists to prevent (#69512).
+    effective = blocks if blocks else [{"type": "text", "text": _EMPTY_TEXT_PLACEHOLDER}]
+    # Applied here (after the empty-fallback resolution) rather than
+    # earlier against `blocks` directly, so a cache_control relocated from
+    # a dropped blank block that was the ONLY block still lands on the
+    # (empty) placeholder instead of being silently lost when blocks was
+    # empty at the point the marker would otherwise have been applied.
+    if _relocated_cache_control is not None:
+        _apply_assistant_cache_control_to_last_cacheable_block(
+            effective, _relocated_cache_control
+        )
+    _apply_assistant_cache_control_to_last_cacheable_block(
+        effective, m.get("cache_control")
+    )
     return {"role": "assistant", "content": effective}
 
 
@@ -2825,6 +2893,7 @@ def create_anthropic_message(
     *,
     log_prefix: str = "",
     prefer_stream: bool = True,
+    on_stream_event=None,
 ) -> Any:
     """Create an Anthropic message, aggregating via stream when available.
 
@@ -2834,6 +2903,13 @@ def create_anthropic_message(
     crash on ``.content``.  Prefer ``messages.stream().get_final_message()`` to
     match the main turn path, falling back to ``create()`` only for providers
     that explicitly do not support streaming, such as restricted Bedrock roles.
+
+    ``on_stream_event``: optional callable invoked once per streamed event
+    (best-effort, exceptions swallowed). Lets callers report forward progress
+    to liveness watchdogs — e.g. the auxiliary compression path ticking its
+    progress hook so a slow-but-generating summary model isn't treated as
+    hung. Only fires on the streaming path; the ``create()`` fallback has no
+    events to report.
     """
     sanitize_anthropic_kwargs(api_kwargs, log_prefix=log_prefix)
 
@@ -2844,6 +2920,18 @@ def create_anthropic_message(
         stream_kwargs.pop("stream", None)
         try:
             with stream_fn(**stream_kwargs) as stream:
+                if callable(on_stream_event):
+                    # Consume the event stream manually so each event can
+                    # tick the caller's progress callback; get_final_message
+                    # then returns the accumulated snapshot.
+                    for _event in stream:
+                        try:
+                            on_stream_event(_event)
+                        except Exception:
+                            logger.debug(
+                                "%son_stream_event callback failed",
+                                log_prefix, exc_info=True,
+                            )
                 return stream.get_final_message()
         except Exception as exc:
             if not _is_stream_unavailable_error(exc):
diff --git a/agent/auxiliary_client.py b/agent/auxiliary_client.py
index bb64d16810e..b31d90e7880 100644
--- a/agent/auxiliary_client.py
+++ b/agent/auxiliary_client.py
@@ -54,7 +54,7 @@ import time
 import uuid
 from pathlib import Path  # noqa: F401 — used by test mocks
 from types import SimpleNamespace
-from typing import Any, Dict, List, Optional, Tuple, TYPE_CHECKING
+from typing import Any, Callable, Dict, List, Optional, Tuple, TYPE_CHECKING
 from urllib.parse import urlparse, parse_qs, urlunparse
 
 # NOTE: `from openai import OpenAI` is deliberately NOT at module top — the
@@ -249,6 +249,50 @@ def aux_interrupt_protection(active: bool = True):
         _aux_interrupt_protection.active = prev
 
 
+# ── Forward-progress hook for streamed auxiliary calls ───────────────────
+# Long auxiliary calls (context compression is the prime case) are watched by
+# wall-clock deadlines in their hosts (gateway session hygiene). A fixed
+# deadline punishes SLOW summary models exactly as hard as HUNG ones: a
+# reasoning model happily streaming a large summary is killed mid-generation.
+# This thread-local hook lets the host observe liveness instead: the wire
+# consumers below tick it on every streamed token/SSE event, and the host
+# extends its deadline while tokens are moving (see gateway/run.py session
+# hygiene + CompressionCommitFence.touch_progress). Thread-local matches the
+# call topology — the aux call and its stream consumption run synchronously
+# on the thread that installed the hook.
+_aux_progress = threading.local()
+
+
+def _notify_aux_progress() -> None:
+    """Tick the installed forward-progress hook, if any. Never raises."""
+    hook = getattr(_aux_progress, "hook", None)
+    if hook is None:
+        return
+    try:
+        hook()
+    except Exception:
+        logger.debug("aux progress hook failed", exc_info=True)
+
+
+def _aux_progress_active() -> bool:
+    return getattr(_aux_progress, "hook", None) is not None
+
+
+@contextlib.contextmanager
+def aux_progress_hook(hook):
+    """Install *hook* as the current thread's aux forward-progress callback.
+
+    ``hook=None`` is a no-op passthrough so callers can wire it
+    unconditionally. Re-entrant-safe: restores the previous hook on exit.
+    """
+    prev = getattr(_aux_progress, "hook", None)
+    _aux_progress.hook = hook if callable(hook) else prev
+    try:
+        yield
+    finally:
+        _aux_progress.hook = prev
+
+
 def _safe_isinstance(obj: Any, maybe_type: Any) -> bool:
     """Return False instead of raising when a patched symbol is not a type."""
     try:
@@ -1060,16 +1104,29 @@ class _CodexCompletionsAdapter:
         # key in extra_body (not top-level) and GitHub/Copilot Responses opts
         # out of cache-key routing entirely — for those hosts, skip it here.
         try:
-            from agent.transports.codex import _content_cache_key
+            from agent.transports.codex import (
+                _content_cache_key,
+                _default_prompt_cache_retention_for_request,
+            )
             from utils import base_url_host_matches
 
             _host_src = str(getattr(self._client, "base_url", "") or "")
             _is_xai = base_url_host_matches(_host_src, "x.ai") or base_url_host_matches(_host_src, "api.x.ai")
-            _is_github = base_url_host_matches(_host_src, "githubcopilot.com")
+            _is_github = (
+                base_url_host_matches(_host_src, "githubcopilot.com")
+                or base_url_host_matches(_host_src, "models.github.ai")
+            )
             if not _is_xai and not _is_github and "prompt_cache_key" not in resp_kwargs:
                 _cache_key = _content_cache_key(instructions, resp_kwargs.get("tools"))
                 if _cache_key:
                     resp_kwargs["prompt_cache_key"] = _cache_key
+            if "prompt_cache_retention" not in resp_kwargs:
+                _cache_retention = _default_prompt_cache_retention_for_request(
+                    model,
+                    _host_src,
+                )
+                if _cache_retention:
+                    resp_kwargs["prompt_cache_retention"] = _cache_retention
         except Exception:
             logger.debug(
                 "Codex auxiliary: prompt_cache_key derivation skipped", exc_info=True
@@ -1151,6 +1208,10 @@ class _CodexCompletionsAdapter:
             def _on_each_event(_event: Any) -> None:
                 # Re-check timeout/cancellation per event, matching the
                 # cadence the old in-line ``_check_cancelled()`` used.
+                # Each SSE event is also forward progress for hosts watching
+                # a progress hook (gateway session hygiene): a reasoning
+                # model streaming a long summary must not look hung.
+                _notify_aux_progress()
                 _check_cancelled()
 
             event_stream = self._client.responses.create(**stream_kwargs)
@@ -1392,7 +1453,18 @@ class _AnthropicCompletionsAdapter:
                     existing = {}
                 anthropic_kwargs["extra_body"] = {**existing, **passthrough}
 
-        response = create_anthropic_message(self._client, anthropic_kwargs)
+        response = create_anthropic_message(
+            self._client,
+            anthropic_kwargs,
+            # Tick the aux forward-progress hook per streamed event so hosts
+            # watching liveness (gateway session hygiene) don't kill a
+            # slow-but-generating summary model. No-op when no hook is
+            # installed (None keeps the fast get_final_message path).
+            on_stream_event=(
+                (lambda _event: _notify_aux_progress())
+                if _aux_progress_active() else None
+            ),
+        )
         _transport = get_transport("anthropic_messages")
         _nr = _transport.normalize_response(
             response, strip_tool_prefix=self._is_oauth
@@ -1705,7 +1777,7 @@ def _read_nous_auth() -> Optional[dict]:
     try:
         if not _AUTH_JSON_PATH.is_file():
             return None
-        data = json.loads(_AUTH_JSON_PATH.read_text())
+        data = json.loads(_AUTH_JSON_PATH.read_text(encoding="utf-8"))
         if data.get("active_provider") != "nous":
             return None
         provider = data.get("providers", {}).get("nous", {})
@@ -2489,16 +2561,18 @@ def _relay_sync_completion(
     *,
     provider: str | None = None,
     api_mode: str | None = None,
+    create: Callable[[dict[str, Any]], Any] | None = None,
 ) -> Any:
+    callback = create or (lambda request: client.chat.completions.create(**request))
     route = _relay_auxiliary_metadata(provider=provider, api_mode=api_mode)
     if route is None:
-        return client.chat.completions.create(**kwargs)
+        return callback(kwargs)
     provider_name, fallback_model, metadata = route
     from agent import relay_llm
 
     return relay_llm.execute_current(
         kwargs,
-        lambda request: client.chat.completions.create(**request),
+        callback,
         name=provider_name,
         model_name=str(kwargs.get("model") or fallback_model),
         metadata=metadata,
@@ -2512,16 +2586,18 @@ async def _relay_async_completion(
     *,
     provider: str | None = None,
     api_mode: str | None = None,
+    create: Callable[[dict[str, Any]], Any] | None = None,
 ) -> Any:
+    callback = create or (lambda request: client.chat.completions.create(**request))
     route = _relay_auxiliary_metadata(provider=provider, api_mode=api_mode)
     if route is None:
-        return await client.chat.completions.create(**kwargs)
+        return await callback(kwargs)
     provider_name, fallback_model, metadata = route
     from agent import relay_llm
 
     return await relay_llm.execute_current_async(
         kwargs,
-        lambda request: client.chat.completions.create(**request),
+        callback,
         name=provider_name,
         model_name=str(kwargs.get("model") or fallback_model),
         metadata=metadata,
@@ -3807,6 +3883,7 @@ def _retry_same_provider_sync(
     effective_timeout: float,
     effective_extra_body: dict,
     reasoning_config: Optional[dict],
+    extra_headers: Optional[Dict[str, str]] = None,
 ) -> Any:
     if task == "vision":
         _, retry_client, retry_model = resolve_vision_provider_client(
@@ -3842,7 +3919,13 @@ def _retry_same_provider_sync(
         extra_body=effective_extra_body,
         reasoning_config=reasoning_config,
         base_url=retry_base or resolved_base_url,
+        task=task,
     )
+    # Preserve per-request attribution headers (e.g. Copilot's
+    # ``x-initiator: user``) across the rebuilt-client retry — dropping them
+    # here would let a recovery retry silently lose capability gating (#60293).
+    if extra_headers:
+        retry_kwargs["extra_headers"] = dict(extra_headers)
     if _is_anthropic_compat_endpoint(resolved_provider, retry_base):
         retry_kwargs["messages"] = _convert_openai_images_to_anthropic(retry_kwargs["messages"])
     return _validate_llm_response(
@@ -3872,6 +3955,7 @@ async def _retry_same_provider_async(
     effective_timeout: float,
     effective_extra_body: dict,
     reasoning_config: Optional[dict],
+    extra_headers: Optional[Dict[str, str]] = None,
 ) -> Any:
     if task == "vision":
         _, retry_client, retry_model = resolve_vision_provider_client(
@@ -3907,7 +3991,12 @@ async def _retry_same_provider_async(
         extra_body=effective_extra_body,
         reasoning_config=reasoning_config,
         base_url=retry_base or resolved_base_url,
+        task=task,
     )
+    # Preserve per-request attribution headers across the rebuilt-client
+    # retry — see the sync variant above (#60293).
+    if extra_headers:
+        retry_kwargs["extra_headers"] = dict(extra_headers)
     if _is_anthropic_compat_endpoint(resolved_provider, retry_base):
         retry_kwargs["messages"] = _convert_openai_images_to_anthropic(retry_kwargs["messages"])
     return _validate_llm_response(
@@ -3988,6 +4077,24 @@ def _refresh_provider_credentials(provider: str) -> bool:
                 return False
             _evict_cached_clients(normalized)
             return True
+        if normalized == "vertex":
+            # Mirrors run_agent.py's _try_refresh_vertex_client_credentials
+            # for the main conversation loop. Without this branch, an
+            # auxiliary Vertex client (vision, title generation, reflection,
+            # context compression, ...) that 401s on its ~1h token expiry
+            # falls through to the final `return False` below: the stale
+            # client is never evicted from _client_cache (whose cache key
+            # ignores the rotating bearer token), so every subsequent
+            # auxiliary Vertex call keeps 401ing until process restart.
+            from agent.vertex_adapter import get_vertex_config
+
+            token, base_url = get_vertex_config()
+            if not isinstance(token, str) or not token.strip():
+                return False
+            if not isinstance(base_url, str) or not base_url.strip():
+                return False
+            _evict_cached_clients(normalized)
+            return True
     except Exception as exc:
         logger.debug("Auxiliary provider credential refresh failed for %s: %s", normalized, exc)
         return False
@@ -4101,7 +4208,7 @@ def _call_fallback_candidate_sync(
         temperature=temperature, max_tokens=max_tokens,
         tools=tools, timeout=effective_timeout,
         extra_body=effective_extra_body, reasoning_config=reasoning_config,
-        base_url=fb_base)
+        base_url=fb_base, task=task)
     try:
         return _validate_llm_response(
             _relay_sync_completion(fb_client, fb_kwargs, provider=fb_label), task)
@@ -4118,7 +4225,7 @@ def _call_fallback_candidate_sync(
                     tools=tools, timeout=effective_timeout,
                     extra_body=effective_extra_body,
                     reasoning_config=reasoning_config,
-                    base_url=str(getattr(retry_client, "base_url", "") or fb_base))
+                    base_url=str(getattr(retry_client, "base_url", "") or fb_base), task=task)
                 try:
                     return _validate_llm_response(
                         _relay_sync_completion(
@@ -4173,7 +4280,7 @@ async def _call_fallback_candidate_async(
         temperature=temperature, max_tokens=max_tokens,
         tools=tools, timeout=effective_timeout,
         extra_body=effective_extra_body, reasoning_config=reasoning_config,
-        base_url=fb_base)
+        base_url=fb_base, task=task)
     try:
         return _validate_llm_response(
             await _relay_async_completion(
@@ -4197,7 +4304,7 @@ async def _call_fallback_candidate_async(
                     tools=tools, timeout=effective_timeout,
                     extra_body=effective_extra_body,
                     reasoning_config=reasoning_config,
-                    base_url=str(getattr(retry_client, "base_url", "") or fb_base))
+                    base_url=str(getattr(retry_client, "base_url", "") or fb_base), task=task)
                 try:
                     return _validate_llm_response(
                         await _relay_async_completion(
@@ -6965,6 +7072,7 @@ def _build_call_kwargs(
     extra_body: Optional[dict] = None,
     reasoning_config: Optional[dict] = None,
     base_url: Optional[str] = None,
+    task: Optional[str] = None,
 ) -> dict:
     """Build kwargs for .chat.completions.create() with model/provider adjustments."""
     kwargs: Dict[str, Any] = {
@@ -7019,11 +7127,32 @@ def _build_call_kwargs(
             _provider_norm in {"nvidia", "nvidia-nim", "nim", "build-nvidia", "nemotron"}
             or base_url_host_matches(_effective_base, "integrate.api.nvidia.com")
         )
+        _is_moa = bool(task) and str(task) == "moa_reference"
+        # Gemini's native generateContent maps max_tokens → maxOutputTokens and,
+        # when it is omitted, applies a fixed 65,535-token ceiling rather than
+        # "the model's full budget" (see gemini_native_adapter.build_gemini_request).
+        # So an explicit cap is both safe and the ONLY way to honor it here —
+        # dropping max_tokens silently makes MoA's reference_max_tokens a no-op
+        # for gemini advisors (they run effectively uncapped).
+        _is_gemini_native = _provider_norm in {
+            "gemini", "google", "google-gemini", "google-ai-studio",
+        }
+        if not _is_gemini_native and _effective_base:
+            try:
+                from agent.gemini_native_adapter import is_native_gemini_base_url
+                _is_gemini_native = is_native_gemini_base_url(_effective_base)
+            except Exception:
+                pass
         if (
             _is_anthropic_compat_endpoint(provider, _effective_base)
             or _is_nvidia_nim
+            or _is_moa
+            or _is_gemini_native
         ):
-            kwargs["max_tokens"] = max_tokens
+            # Use auxiliary_max_tokens_param() so models that require
+            # max_completion_tokens (GPT-5 family, Copilot) get the right
+            # parameter name instead of a hardcoded max_tokens that 400s.
+            kwargs.update(auxiliary_max_tokens_param(max_tokens, model=model))
 
     if tools:
         # Defensive dedup: providers like Google Vertex, Azure, and Bedrock
@@ -7266,6 +7395,346 @@ def _obj_get(obj: Any, key: str, default: Any = None) -> Any:
     return value
 
 
+# ── Streamed aggregation for progress-hooked auxiliary calls ─────────────
+# When a forward-progress hook is installed (aux_progress_hook — today only
+# by context compression), the primary chat.completions attempt is upgraded
+# to a streamed request that is aggregated back into a complete response.
+# Two effects, both deliberate:
+#   1. The configured ``timeout`` becomes an INTER-CHUNK idle timeout instead
+#      of a total budget (httpx applies the read timeout per stream read), so
+#      a slow-but-generating summary model is never killed mid-generation
+#      while tokens are moving — only a genuinely silent connection dies.
+#   2. Every arriving chunk ticks the progress hook, letting outer watchdogs
+#      (gateway session hygiene) extend their deadlines on liveness instead
+#      of guessing with a fixed wall clock.
+# A total ceiling still bounds the pathological 1-token-per-idle-window
+# stream; see _aux_stream_total_ceiling().
+
+_AUX_STREAM_CEILING_FLOOR_SECONDS = 600.0
+_AUX_STREAM_CEILING_MULTIPLIER = 4.0
+
+
+def _aux_stream_total_ceiling(effective_timeout: Optional[float]) -> float:
+    """Absolute wall-clock bound for a progress-hooked streamed aux call.
+
+    Generous by design — the idle timeout is the real guard; this only stops
+    a degenerate stream that trickles one token per idle window forever.
+    """
+    try:
+        timeout = float(effective_timeout) if effective_timeout is not None else 0.0
+    except (TypeError, ValueError):
+        timeout = 0.0
+    return max(_AUX_STREAM_CEILING_FLOOR_SECONDS,
+               _AUX_STREAM_CEILING_MULTIPLIER * timeout)
+
+
+def _client_streams_internally(client: Any) -> bool:
+    """Wire adapters that consume a stream inside .create() already tick the
+    progress hook themselves (Codex per SSE event, Anthropic per stream
+    event); Bedrock's Converse shim cannot stream at all. None of them
+    accept chat-completions ``stream=True`` semantics from us."""
+    return isinstance(client, (
+        CodexAuxiliaryClient,
+        AnthropicAuxiliaryClient,
+        BedrockAuxiliaryClient,
+    ))
+
+
+def _is_streaming_rejected_error(exc: Exception) -> bool:
+    """Provider explicitly refused a streamed chat.completions request."""
+    err = str(exc).lower()
+    if "stream_options" in err:
+        return True
+    return "stream" in err and (
+        "not supported" in err
+        or "unsupported" in err
+        or "not allowed" in err
+        or "disabled" in err
+    )
+
+
+def _provider_requires_stream(provider: str, base_url: Optional[str]) -> bool:
+    """Detect providers that only accept streaming (non-stream = HTTP 400).
+
+    Some OpenAI-compatible endpoints reject non-streaming chat requests
+    outright — e.g. Tencent Copilot returns
+    ``{"code": 11101, "msg": "Non-stream chat request is currently not
+    supported"}``. The main conversation loop already streams, so interactive
+    chat works; auxiliary tasks (title generation, compression, web extract)
+    used the non-streaming path and failed on every call. When this returns
+    True the auxiliary client sends ``stream=True`` and aggregates the chunks
+    itself (see :func:`_aggregate_chat_stream`). Credit @kudi88 (PR #60686).
+
+    Beyond the known-host list, users can mark ANY custom endpoint as
+    stream-only via ``auxiliary.stream_only_base_urls`` in config.yaml
+    (list of substrings matched against the endpoint URL).
+    """
+    _url = str(base_url or "").lower()
+    if not _url:
+        return False
+    # Tencent Copilot — "Non-stream chat request is currently not supported"
+    if base_url_host_matches(_url, "copilot.tencent.com"):
+        return True
+    try:
+        from hermes_cli.config import load_config
+        aux_cfg = (load_config() or {}).get("auxiliary", {})
+        markers = aux_cfg.get("stream_only_base_urls") or []
+        if isinstance(markers, (list, tuple)):
+            for marker in markers:
+                if isinstance(marker, str) and marker.strip() and marker.strip().lower() in _url:
+                    return True
+    except Exception:
+        # Config read is best-effort; never break an aux call over it.
+        pass
+    return False
+
+
+def _create_with_progress(
+    client: Any,
+    kwargs: Dict[str, Any],
+    task: Optional[str] = None,
+    *,
+    force_stream: bool = False,
+) -> Any:
+    """chat.completions.create() that streams when a progress hook is active
+    or the provider only accepts streamed requests.
+
+    Behavior is byte-for-byte identical to a plain ``create(**kwargs)`` when
+    neither trigger applies (every existing caller/task) or when the client's
+    wire adapter streams internally. With a hook + a chunk-capable client,
+    the request is sent with ``stream=True`` and aggregated, ticking the hook
+    per chunk — so the configured ``timeout`` acts per stream read (idle)
+    rather than as a total budget, and outer liveness watchdogs see tokens
+    moving. ``force_stream=True`` (stream-only providers such as Tencent
+    Copilot — credit @kudi88, PR #60686) takes the same streamed path even
+    without a hook. Providers that reject the streamed request fall back to
+    the plain non-streaming call — except under ``force_stream``, where a
+    stream-only provider rejects the plain call by definition, so the
+    original error is surfaced to the normal recovery chains instead.
+    """
+    _notify_aux_progress()  # request dispatched counts as progress
+    if (not _aux_progress_active() and not force_stream) or _client_streams_internally(client):
+        return client.chat.completions.create(**kwargs)
+
+    total_ceiling = _aux_stream_total_ceiling(kwargs.get("timeout"))
+    stream_kwargs = dict(kwargs)
+    stream_kwargs["stream"] = True
+    stream_kwargs["stream_options"] = {"include_usage": True}
+    try:
+        chunks = client.chat.completions.create(**stream_kwargs)
+    except Exception as exc:
+        # Genuine provider failures (auth, credit, rate limit, network) are
+        # not streaming's fault — surface them unchanged so the existing
+        # recovery chains (credential refresh, pool rotation, provider
+        # fallback) see the same error they would on a plain call.
+        if (
+            force_stream
+            or _is_transient_transport_error(exc)
+            or _is_auth_error(exc)
+            or _is_payment_error(exc)
+            or _is_rate_limit_error(exc)
+        ):
+            raise
+        # Anything else may be a streaming-specific rejection (explicit
+        # "stream not supported", stream_options 400, or an idiosyncratic
+        # 4xx). Retry non-streaming once; if the request itself is bad the
+        # plain call reproduces the real error for the normal except-chains.
+        logger.debug(
+            "Auxiliary %s: streamed request failed (%s); retrying "
+            "non-streaming", task or "call", exc,
+        )
+        return client.chat.completions.create(**kwargs)
+
+    # Some shims (MoA virtual provider under quiet mode, defensive adapters)
+    # return a complete response even when stream=True was requested.
+    if hasattr(chunks, "choices"):
+        _notify_aux_progress()
+        return chunks
+    return _aggregate_chat_stream(
+        chunks, model=str(kwargs.get("model") or ""), total_ceiling=total_ceiling,
+    )
+
+
+def _aggregate_chat_stream(
+    chunks: Any,
+    *,
+    model: str = "",
+    total_ceiling: Optional[float] = None,
+) -> Any:
+    """Consume a chat.completions chunk stream into a complete response.
+
+    Ticks the thread-local aux progress hook on every chunk. Raises
+    TimeoutError when *total_ceiling* seconds elapse before the stream
+    finishes — phrased with "timed out" so existing timeout classification
+    (``_is_timeout_error``) treats it exactly like a request timeout.
+    Accumulation is shared with the async mirror via
+    :class:`_ChatStreamAccumulator`.
+    """
+    acc = _ChatStreamAccumulator(model=model, total_ceiling=total_ceiling)
+    try:
+        for chunk in chunks:
+            acc.feed(chunk)
+    finally:
+        close_fn = getattr(chunks, "close", None)
+        if callable(close_fn):
+            try:
+                close_fn()
+            except Exception:
+                pass
+    return acc.finish()
+
+
+class _ChatStreamAccumulator:
+    """Shared per-chunk accumulation for sync and async stream aggregation.
+
+    Mirrors :func:`_aggregate_chat_stream`'s chunk handling so the async
+    consumer below cannot drift from the sync one (same content/reasoning/
+    tool-call delta reassembly, same "timed out" ceiling phrasing).
+    """
+
+    def __init__(self, model: str = "", total_ceiling: Optional[float] = None):
+        self._started = time.monotonic()
+        self._total_ceiling = total_ceiling
+        self.content_parts: List[str] = []
+        self.reasoning_parts: List[str] = []
+        self.tool_calls_acc: Dict[int, Dict[str, Any]] = {}
+        self.finish_reason = None
+        self.usage = None
+        self.resp_id = ""
+        self.resp_model = model or ""
+
+    def feed(self, chunk: Any) -> None:
+        _notify_aux_progress()
+        if (
+            self._total_ceiling is not None
+            and (time.monotonic() - self._started) >= self._total_ceiling
+        ):
+            raise TimeoutError(
+                f"Auxiliary streamed call timed out after {self._total_ceiling:.0f}s "
+                "total ceiling (stream still open but over budget)"
+            )
+        self.resp_id = getattr(chunk, "id", None) or self.resp_id
+        self.resp_model = getattr(chunk, "model", None) or self.resp_model
+        chunk_usage = getattr(chunk, "usage", None)
+        if chunk_usage:
+            self.usage = chunk_usage
+        choices = getattr(chunk, "choices", None) or []
+        if not choices:
+            return
+        choice = choices[0]
+        self.finish_reason = getattr(choice, "finish_reason", None) or self.finish_reason
+        delta = getattr(choice, "delta", None)
+        if delta is None:
+            return
+        piece = getattr(delta, "content", None)
+        if piece:
+            self.content_parts.append(piece)
+        reasoning_piece = (
+            getattr(delta, "reasoning", None)
+            or getattr(delta, "reasoning_content", None)
+        )
+        if reasoning_piece and isinstance(reasoning_piece, str):
+            self.reasoning_parts.append(reasoning_piece)
+        for tc in (getattr(delta, "tool_calls", None) or []):
+            idx = getattr(tc, "index", 0) or 0
+            acc = self.tool_calls_acc.setdefault(
+                idx, {"id": "", "name": "", "arguments": []}
+            )
+            if getattr(tc, "id", None):
+                acc["id"] = tc.id
+            fn = getattr(tc, "function", None)
+            if fn is not None:
+                if getattr(fn, "name", None):
+                    acc["name"] = fn.name
+                if getattr(fn, "arguments", None):
+                    acc["arguments"].append(fn.arguments)
+
+    def finish(self) -> Any:
+        tool_calls = None
+        if self.tool_calls_acc:
+            tool_calls = [
+                SimpleNamespace(
+                    id=acc["id"],
+                    type="function",
+                    function=SimpleNamespace(
+                        name=acc["name"],
+                        arguments="".join(acc["arguments"]),
+                    ),
+                )
+                for _idx, acc in sorted(self.tool_calls_acc.items())
+            ]
+        message = SimpleNamespace(
+            role="assistant",
+            content="".join(self.content_parts),
+            tool_calls=tool_calls,
+            reasoning="".join(self.reasoning_parts) or None,
+        )
+        choice = SimpleNamespace(
+            index=0,
+            message=message,
+            finish_reason=self.finish_reason or "stop",
+        )
+        return SimpleNamespace(
+            id=self.resp_id,
+            model=self.resp_model,
+            object="chat.completion",
+            choices=[choice],
+            usage=self.usage,
+        )
+
+
+async def _aggregate_chat_stream_async(
+    chunks: Any,
+    *,
+    model: str = "",
+    total_ceiling: Optional[float] = None,
+) -> Any:
+    """Async mirror of :func:`_aggregate_chat_stream` (``async for`` consumer).
+
+    The AsyncOpenAI stream contract is an async iterator — consuming it with
+    the sync helper raises. Same accumulation and ceiling semantics via
+    :class:`_ChatStreamAccumulator`.
+    """
+    acc = _ChatStreamAccumulator(model=model, total_ceiling=total_ceiling)
+    try:
+        async for chunk in chunks:
+            acc.feed(chunk)
+    finally:
+        close_fn = getattr(chunks, "close", None) or getattr(chunks, "aclose", None)
+        if callable(close_fn):
+            try:
+                result = close_fn()
+                if inspect.isawaitable(result):
+                    await result
+            except Exception:
+                pass
+    return acc.finish()
+
+
+async def _acreate_with_stream(
+    client: Any,
+    kwargs: Dict[str, Any],
+    task: Optional[str] = None,
+) -> Any:
+    """Async chat.completions.create() for stream-only providers.
+
+    Sends ``stream=True`` and aggregates the async chunk stream into a
+    complete response (credit @kudi88, PR #60686 — async contract fixed to
+    ``async for`` and tool-call deltas preserved per sweeper review).
+    """
+    total_ceiling = _aux_stream_total_ceiling(kwargs.get("timeout"))
+    stream_kwargs = dict(kwargs)
+    stream_kwargs["stream"] = True
+    stream_kwargs["stream_options"] = {"include_usage": True}
+    chunks = await client.chat.completions.create(**stream_kwargs)
+    # Defensive: shims may hand back a complete response despite stream=True.
+    if hasattr(chunks, "choices"):
+        return chunks
+    return await _aggregate_chat_stream_async(
+        chunks, model=str(kwargs.get("model") or ""), total_ceiling=total_ceiling,
+    )
+
+
 @_relay_auxiliary_call
 def call_llm(
     task: str = None,
@@ -7282,6 +7751,7 @@ def call_llm(
     timeout: float = None,
     extra_body: dict = None,
     reasoning_config: Optional[dict] = None,
+    extra_headers: Optional[Dict[str, str]] = None,
     api_mode: str = None,
     stream: bool = False,
     stream_options: dict = None,
@@ -7307,6 +7777,9 @@ def call_llm(
         extra_body: Additional request body fields.
         reasoning_config: Optional Hermes reasoning config for direct model calls
               such as MoA reference/aggregator slots.
+        extra_headers: Additional per-request HTTP headers. These override
+            client-level defaults for providers that gate capabilities on
+            request attribution (for example Copilot's ``x-initiator``).
         stream: When True, return the raw SDK streaming iterator instead of a
             validated complete response. The caller is responsible for consuming
             chunks (and for any fallback). Used by the MoA aggregator so its
@@ -7424,7 +7897,9 @@ def call_llm(
         temperature=temperature, max_tokens=max_tokens,
         tools=tools, timeout=effective_timeout, extra_body=effective_extra_body,
         reasoning_config=reasoning_config,
-        base_url=_base_info or resolved_base_url)
+        base_url=_base_info or resolved_base_url, task=task)
+    if extra_headers:
+        kwargs["extra_headers"] = dict(extra_headers)
 
     # Convert image blocks for Anthropic-compatible endpoints (e.g. MiniMax)
     _client_base = str(getattr(client, "base_url", "") or "")
@@ -7476,7 +7951,16 @@ def call_llm(
                     kwargs,
                     provider=resolved_provider,
                     api_mode=resolved_api_mode,
-                ), task,
+                    create=lambda request: _create_with_progress(
+                        client,
+                        request,
+                        task,
+                        force_stream=_provider_requires_stream(
+                            resolved_provider, _base_info or resolved_base_url,
+                        ),
+                    ),
+                ),
+                task,
                 provider=resolved_provider, base_url=_base_info)
         except Exception as transient_err:
             if not _is_transient_transport_error(transient_err):
@@ -7514,7 +7998,17 @@ def call_llm(
                             kwargs,
                             provider=resolved_provider,
                             api_mode=resolved_api_mode,
-                        ), task)
+                            create=lambda request: _create_with_progress(
+                                client,
+                                request,
+                                task,
+                                force_stream=_provider_requires_stream(
+                                    resolved_provider,
+                                    _base_info or resolved_base_url,
+                                ),
+                            ),
+                        ),
+                        task)
                 except Exception as retry_transient:
                     if not _is_transient_transport_error(retry_transient):
                         raise
@@ -7718,6 +8212,7 @@ def call_llm(
                     effective_timeout=effective_timeout,
                     effective_extra_body=effective_extra_body,
                     reasoning_config=reasoning_config,
+                    extra_headers=extra_headers,
                 )
 
         # ── Same-provider credential-pool recovery ─────────────────────
@@ -7766,6 +8261,7 @@ def call_llm(
                         effective_timeout=effective_timeout,
                         effective_extra_body=effective_extra_body,
                         reasoning_config=reasoning_config,
+                        extra_headers=extra_headers,
                     )
                 except Exception as retry2_err:
                     # The rotated key also hit a quota/auth wall.  Mark it
@@ -8091,7 +8587,7 @@ async def async_call_llm(
         temperature=temperature, max_tokens=max_tokens,
         tools=tools, timeout=effective_timeout, extra_body=effective_extra_body,
         reasoning_config=reasoning_config,
-        base_url=_client_base or resolved_base_url)
+        base_url=_client_base or resolved_base_url, task=task)
 
     # Convert image blocks for Anthropic-compatible endpoints (e.g. MiniMax)
     if _is_anthropic_compat_endpoint(resolved_provider, _client_base):
@@ -8101,6 +8597,22 @@ async def async_call_llm(
         # Retry ONCE on the same provider for a transient transport blip
         # before the except-chain escalates to fallback — see call_llm()
         # for the rationale. (PR #16587)
+        _force_stream_async = (
+            _provider_requires_stream(
+                resolved_provider, _client_base or resolved_base_url,
+            )
+            and not isinstance(client, (
+                AsyncCodexAuxiliaryClient,
+                AsyncAnthropicAuxiliaryClient,
+                AsyncBedrockAuxiliaryClient,
+            ))
+        )
+
+        async def _acreate(_kwargs: Dict[str, Any]) -> Any:
+            if _force_stream_async:
+                return await _acreate_with_stream(client, _kwargs, task)
+            return await client.chat.completions.create(**_kwargs)
+
         try:
             return _validate_llm_response(
                 await _relay_async_completion(
@@ -8108,7 +8620,9 @@ async def async_call_llm(
                     kwargs,
                     provider=resolved_provider,
                     api_mode=resolved_api_mode,
-                ), task,
+                    create=_acreate,
+                ),
+                task,
                 provider=resolved_provider, base_url=_client_base)
         except Exception as transient_err:
             if not _is_transient_transport_error(transient_err):
@@ -8134,7 +8648,9 @@ async def async_call_llm(
                     kwargs,
                     provider=resolved_provider,
                     api_mode=resolved_api_mode,
-                ), task)
+                    create=_acreate,
+                ),
+                task)
     except Exception as first_err:
         if "temperature" in kwargs and _is_unsupported_temperature_error(first_err):
             retry_kwargs = dict(kwargs)
diff --git a/agent/background_review.py b/agent/background_review.py
index c2ea87bd94e..a0dbd4a99e2 100644
--- a/agent/background_review.py
+++ b/agent/background_review.py
@@ -209,7 +209,10 @@ _SKILL_REVIEW_PROMPT = (
     "conversation for skills the user loaded via /skill-name or you "
     "read via skill_view. If any of them covers the territory of the "
     "new learning, PATCH that one first. It is the skill that was in "
-    "play, so it's the right one to extend.\n"
+    "play, so it's the right one to extend — but only if it is "
+    "curator-managed. Bundled, hub, pinned, and user-owned skills are "
+    "off-limits to you no matter how relevant (see Protected skills "
+    "below); for those, fall through to the next option.\n"
     "  2. UPDATE AN EXISTING UMBRELLA (via skills_list + skill_view). "
     "If no loaded skill fits but an existing class-level skill does, "
     "patch it. Add a subsection, a pitfall, or broaden a trigger.\n"
@@ -251,10 +254,18 @@ _SKILL_REVIEW_PROMPT = (
     "Protected skills (DO NOT edit these):\n"
     "  • Bundled skills (shipped with Hermes, e.g. 'hermes-agent').\n"
     "  • Hub-installed skills (installed via 'hermes skills install').\n"
-    "Pinned skills (marked via 'hermes curator pin') CAN be improved — "
-    "pin only blocks deletion/archive/consolidation by the curator, not "
-    "content updates. Patch them when a pitfall or missing step turns up, "
-    "same as any other agent-created skill.\n"
+    "  • Skills in skills.external_dirs (externally owned).\n"
+    "  • PINNED skills (marked via 'hermes curator pin'). You are an "
+    "autonomous no-user-present actor, so pin blocks your writes too — "
+    "content updates included. Only the user, in a foreground session, "
+    "can change a pinned skill.\n"
+    "  • USER-OWNED skills — anything not curator-managed. A skill the "
+    "user hand-wrote, installed by URL, or asked a foreground agent to "
+    "create is theirs, not yours; your writes to it WILL be refused. "
+    "This includes skills that were loaded or consulted this session: "
+    "being in play does not make one yours to edit. If such a skill is "
+    "wrong or outdated, say so in your reply and recommend "
+    "'hermes curator adopt <name>' — do not try to patch it.\n"
     "If the only skills that need updating are protected, say\n"
     "'Nothing to save.' and stop.\n\n"
     "Do NOT capture (these become persistent self-imposed constraints "
@@ -309,7 +320,9 @@ _COMBINED_REVIEW_PROMPT = (
     "  1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were "
     "loaded via /skill-name or skill_view in the conversation. If one "
     "of them covers the learning, PATCH it first. It was in play; "
-    "it's the right place.\n"
+    "it's the right place — provided it is curator-managed. Protected "
+    "and user-owned skills are off-limits however relevant; fall "
+    "through when one of those is the best fit.\n"
     "  2. UPDATE AN EXISTING UMBRELLA (skills_list + skill_view to "
     "find the right one). Patch it.\n"
     "  3. ADD A SUPPORT FILE under an existing umbrella via "
@@ -337,10 +350,15 @@ _COMBINED_REVIEW_PROMPT = (
     "Protected skills (DO NOT edit these):\n"
     "  • Bundled skills (shipped with Hermes, e.g. 'hermes-agent').\n"
     "  • Hub-installed skills (installed via 'hermes skills install').\n"
-    "Pinned skills (marked via 'hermes curator pin') CAN be improved — "
-    "pin only blocks deletion/archive/consolidation by the curator, not "
-    "content updates. Patch them when a pitfall or missing step turns up, "
-    "same as any other agent-created skill.\n"
+    "  • Skills in skills.external_dirs (externally owned).\n"
+    "  • PINNED skills (marked via 'hermes curator pin'). Pin blocks "
+    "autonomous writes entirely — content updates included — because no "
+    "user is present to consent. Only a foreground session can change one.\n"
+    "  • USER-OWNED skills — anything not curator-managed (hand-written, "
+    "URL-installed, or created by a foreground agent at the user's "
+    "request). Your writes to these WILL be refused, including to skills "
+    "loaded or consulted this session. If one is wrong, say so in your "
+    "reply and recommend 'hermes curator adopt <name>' instead.\n"
     "If the only skills that need updating are protected, say\n"
     "'Nothing to save.' and stop.\n\n"
     "Do NOT capture as skills (these become persistent self-imposed "
diff --git a/agent/chat_completion_helpers.py b/agent/chat_completion_helpers.py
index 409df6604a6..15161ea11d4 100644
--- a/agent/chat_completion_helpers.py
+++ b/agent/chat_completion_helpers.py
@@ -1083,6 +1083,7 @@ def build_api_kwargs(agent, api_messages: list) -> dict:
             tools=tools_for_api,
             reasoning_config=agent.reasoning_config,
             session_id=getattr(agent, "session_id", None),
+            base_url=agent.base_url,
             max_tokens=agent.max_tokens,
             timeout=agent._resolved_api_call_timeout(),
             request_overrides=agent.request_overrides,
@@ -1520,6 +1521,45 @@ def _fallback_entry_key(fb: dict) -> tuple[str, str, str]:
     )
 
 
+def _fallback_entry_is_same_backend_by_base_url(
+    *,
+    current_provider: str,
+    fb_provider: str,
+    current_base_url: str,
+    fb_base_url: str,
+    current_model: str,
+    fb_model: str,
+) -> bool:
+    """True when base_url+model identity means the fallback is the same backend.
+
+    Issue #22548: two ``custom_providers`` aliases that point at the same shim
+    URL with the same model must be skipped, or failover loops on the dead
+    backend.  First-class providers that share a host while using different
+    auth (``xai-oauth`` vs ``xai``, ``openai-codex`` vs ``openai-api``) are
+    distinct credential surfaces — skipping them strands configured failover
+    when primary and fallback reuse the same model slug on that host.
+    """
+    if not (
+        fb_base_url
+        and current_base_url
+        and fb_base_url == current_base_url
+        and fb_model == current_model
+    ):
+        return False
+    if fb_provider == current_provider:
+        return True
+    try:
+        from hermes_cli.auth import PROVIDER_REGISTRY
+
+        # Both sides are registered first-class providers → different auth
+        # identities even when the inference host matches. Allow failover.
+        if current_provider in PROVIDER_REGISTRY and fb_provider in PROVIDER_REGISTRY:
+            return False
+    except Exception:
+        pass
+    return True
+
+
 def _fallback_entry_unavailable_without_network(agent, fb: dict) -> Optional[str]:
     """Return a skip reason for fallback entries known to be unusable locally."""
     fb_provider = (fb.get("provider") or "").strip().lower()
@@ -1608,7 +1648,9 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None) -> bool
     # Skip entries that resolve to the current (provider, model) — falling
     # back to the same backend that just failed loops the failure. Compare
     # base_url too so two distinct custom_providers entries pointing at the
-    # same shim/proxy URL also dedup. See issue #22548.
+    # same shim/proxy URL also dedup. See issue #22548. Do NOT treat
+    # first-class providers that share a host (xai-oauth vs xai) as the same
+    # backend — they use different credentials.
     current_provider = (getattr(agent, "provider", "") or "").strip().lower()
     current_model = (getattr(agent, "model", "") or "").strip()
     current_base_url = str(getattr(agent, "base_url", "") or "").rstrip("/").lower()
@@ -1619,11 +1661,13 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None) -> bool
             fb_provider, fb_model,
         )
         return agent._try_activate_fallback(reason)
-    if (
-        fb_base_url_for_dedup
-        and current_base_url
-        and fb_base_url_for_dedup == current_base_url
-        and fb_model == current_model
+    if _fallback_entry_is_same_backend_by_base_url(
+        current_provider=current_provider,
+        fb_provider=fb_provider,
+        current_base_url=current_base_url,
+        fb_base_url=fb_base_url_for_dedup,
+        current_model=current_model,
+        fb_model=fb_model,
     ):
         logger.warning(
             "Fallback skip: chain entry base_url %s matches current backend",
@@ -1746,6 +1790,7 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None) -> bool
                     fb_provider, fb_model, _pool_provider,
                 )
                 agent._credential_pool = None
+                agent._credential_pool_entry_id = None
         if getattr(agent, "_credential_pool", None) is None:
             try:
                 from agent.credential_pool import load_pool
@@ -1808,6 +1853,9 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None) -> bool
                 # not only after a later credential-rotation rebuild.
                 agent._replace_primary_openai_client(reason="fallback_timeout_apply")
 
+        from agent.agent_runtime_helpers import sync_credential_pool_entry_id
+        sync_credential_pool_entry_id(agent)
+
         # Re-evaluate prompt caching for the new provider/model
         agent._use_prompt_caching, agent._use_native_cache_layout = (
             agent._anthropic_prompt_cache_policy(
@@ -1975,7 +2023,17 @@ def handle_max_iterations(agent, messages: list, api_call_count: int) -> str:
             for internal_key in [k for k in api_msg if isinstance(k, str) and k.startswith("_")]:
                 api_msg.pop(internal_key, None)
             if _needs_sanitize:
-                agent._sanitize_tool_calls_for_strict_api(api_msg, model=agent.model)
+                # In MoA mode, agent.model is the virtual preset name,
+                # not the actual aggregator model.  Resolve the real
+                # aggregator model so Gemini preserves thought_signature.
+                _sanitize_model = agent.model
+                if agent.provider == "moa":
+                    _moa_client = getattr(agent, "client", None)
+                    if _moa_client is not None:
+                        _agg_slot = getattr(_moa_client, "last_aggregator_slot", None)
+                        if _agg_slot and _agg_slot.get("model"):
+                            _sanitize_model = _agg_slot["model"]
+                agent._sanitize_tool_calls_for_strict_api(api_msg, model=_sanitize_model)
             api_messages.append(api_msg)
 
         effective_system = agent._cached_system_prompt or ""
@@ -2568,7 +2626,11 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
     request_client_holder = {"client": None, "diag": None, "owner_tid": None}
     # Transport kind of the registered request client — see the non-streaming
     # variant. Routes _close_request_client_once to anthropic vs openai abort/
-    # close helpers (#67142).
+    # close helpers (#67142). ``kind="stream"`` registers a per-request
+    # *stream handle* instead of a client — used under the MoA facade, whose
+    # singleton client has no per-request sockets to abort
+    # (_abort_request_openai_client is a no-op on it), so interrupts must
+    # close the stream object itself (#57354).
     request_client_kind = {"value": "openai"}
     request_client_lock = threading.Lock()
     # Request-local cancellation flag — see interruptible_api_call for the full
@@ -2588,6 +2650,44 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
             request_client_holder["owner_tid"] = threading.get_ident()
         return client
 
+    def _stream_close_callable(stream):
+        close = getattr(stream, "close", None)
+        if callable(close):
+            return close
+        response = getattr(stream, "response", None)
+        close = getattr(response, "close", None)
+        if callable(close):
+            return close
+        return None
+
+    def _set_request_stream_handle(stream):
+        # Register the per-request *stream* under kind="stream" so an
+        # interrupt closes the stream handle itself. Under the MoA facade the
+        # registered "client" is the shared facade singleton whose
+        # per-request abort helpers are no-ops, leaving the underlying HTTP
+        # stream open until the provider drained it (#57354).
+        if _stream_close_callable(stream) is None:
+            return stream
+        with request_client_lock:
+            request_client_holder["client"] = stream
+            request_client_kind["value"] = "stream"
+            request_client_holder["owner_tid"] = threading.get_ident()
+        return stream
+
+    def _close_request_stream_handle(stream, reason: str) -> None:
+        close = _stream_close_callable(stream)
+        if close is None:
+            return
+        try:
+            close()
+            logger.info("Streaming response handle closed (%s)", reason)
+        except Exception as exc:
+            logger.debug(
+                "Streaming response handle close failed (%s): %s",
+                reason,
+                exc,
+            )
+
     def _close_request_client_once(reason: str) -> None:
         # See #29507 explanation in the non-streaming variant above. A
         # stranger thread (the interrupt-check / stale-stream detector loop)
@@ -2595,9 +2695,15 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
         # so the worker thread retains ownership of the FD release.
         with request_client_lock:
             request_client = request_client_holder.get("client")
+            request_kind = request_client_kind.get("value", "openai")
             owner_tid = request_client_holder.get("owner_tid")
+            # A registered stream handle (kind="stream", MoA facade path) is
+            # safe to close from any thread — closing IS the abort — so the
+            # stranger-thread ownership carve-out only applies to real
+            # per-request clients (#57354).
             stranger_thread = (
-                request_client is not None
+                request_kind != "stream"
+                and request_client is not None
                 and owner_tid is not None
                 and owner_tid != threading.get_ident()
             )
@@ -2606,8 +2712,9 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                 request_client_holder["owner_tid"] = None
         if request_client is None:
             return
-        kind = request_client_kind.get("value", "openai")
-        if kind == "anthropic_messages":
+        if request_kind == "stream":
+            _close_request_stream_handle(request_client, reason)
+        elif request_kind == "anthropic_messages":
             if stranger_thread:
                 agent._abort_request_anthropic_client(request_client, reason=reason)
             else:
@@ -2897,6 +3004,10 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                 defer_logical_completion=True,
             )
         )
+        if agent.provider == "moa":
+            # Hermes interrupts the managed stream; Relay retains sole
+            # ownership of closing the underlying provider stream.
+            _set_request_stream_handle(stream)
         for chunk in stream:
             last_chunk_time["t"] = time.time()
             agent._touch_activity("receiving stream response")
@@ -3567,13 +3678,9 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                         # already worker-owned-closed by _close_request_client_once
                         # above; the next attempt builds a fresh one. The shared
                         # _anthropic_client is never closed from inside a request.
-                        if agent.api_mode != "anthropic_messages":
-                            try:
-                                agent._replace_primary_openai_client(
-                                    reason="stream_mid_tool_retry_pool_cleanup"
-                                )
-                            except Exception:
-                                pass
+                        # #70773: same FD-recycle corruption vector for OpenAI.
+                        # The shared client will be replaced lazily by
+                        # _ensure_primary_openai_client on the next attempt.
                         continue
 
                     # SSE error events from proxies (e.g. OpenRouter sends
@@ -3632,13 +3739,9 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                             # above; next attempt builds fresh), so the shared
                             # _anthropic_client is never closed from inside a
                             # request — only the OpenAI-wire primary is refreshed.
-                            if agent.api_mode != "anthropic_messages":
-                                try:
-                                    agent._replace_primary_openai_client(
-                                        reason="stream_retry_pool_cleanup"
-                                    )
-                                except Exception:
-                                    pass
+                            # #70773: same FD-recycle corruption vector for OpenAI.
+                            # The shared client will be replaced lazily by
+                            # _ensure_primary_openai_client on the next attempt.
                             continue
                         # Retries exhausted. Log the final failure with
                         # full diagnostic detail (chain, headers,
@@ -3882,10 +3985,15 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                 # FD-recycle corruption vector. Nothing further is needed.
                 pass
             else:
-                try:
-                    agent._replace_primary_openai_client(reason="stale_stream_pool_cleanup")
-                except Exception:
-                    pass
+                # #70773: same FD-recycle corruption vector as #67142.
+                # The shared OpenAI client's connection pool must NOT be
+                # closed from this watchdog/poll thread — worker threads
+                # from previous stale-killed attempts may still be
+                # unwinding their SSL BIOs.  The request-local client is
+                # already closed above via _close_request_client_once.
+                # The shared client will be replaced lazily by
+                # _ensure_primary_openai_client on the next request.
+                pass
             # Reset the timer so we don't kill repeatedly while
             # the inner thread processes the closure.
             last_chunk_time["t"] = time.time()
diff --git a/agent/codex_responses_adapter.py b/agent/codex_responses_adapter.py
index bce372ebb5d..ee75f4190e6 100644
--- a/agent/codex_responses_adapter.py
+++ b/agent/codex_responses_adapter.py
@@ -912,7 +912,8 @@ def _preflight_codex_api_kwargs(
     allowed_keys = {
         "model", "instructions", "input", "tools", "store",
         "reasoning", "include", "max_output_tokens", "temperature",
-        "tool_choice", "parallel_tool_calls", "prompt_cache_key", "service_tier",
+        "tool_choice", "parallel_tool_calls", "prompt_cache_key",
+        "prompt_cache_retention", "service_tier",
         "extra_headers", "extra_body", "timeout",
     }
     normalized: Dict[str, Any] = {
@@ -950,8 +951,13 @@ def _preflight_codex_api_kwargs(
     if isinstance(temperature, (int, float)):
         normalized["temperature"] = float(temperature)
 
-    # Pass through tool_choice, parallel_tool_calls, prompt_cache_key
-    for passthrough_key in ("tool_choice", "parallel_tool_calls", "prompt_cache_key"):
+    # Pass through cache routing/retention and tool-dispatch hints.
+    for passthrough_key in (
+        "tool_choice",
+        "parallel_tool_calls",
+        "prompt_cache_key",
+        "prompt_cache_retention",
+    ):
         val = api_kwargs.get(passthrough_key)
         if val is not None:
             normalized[passthrough_key] = val
diff --git a/agent/coding_context.py b/agent/coding_context.py
index 4a0cb841030..fabbdb48e07 100644
--- a/agent/coding_context.py
+++ b/agent/coding_context.py
@@ -520,30 +520,46 @@ class RuntimeMode:
             return None
         return [self.profile.toolset, *_enabled_mcp_servers(config)]
 
-    def system_blocks(self) -> list[str]:
-        """Stable system-prompt blocks for this posture (brief + workspace).
+    def system_prompt_parts(self) -> tuple[list[str], list[str], list[str]]:
+        """Return prefix, workspace, and trailing posture blocks separately.
 
         The operating brief carries a model-family edit-format nudge appended
         to it (one cached string, not a separate block) so the model is steered
         toward the `patch` mode it handles best — see ``_edit_format_line``.
+
+        The three lists preserve the historical flat prompt order: the brief,
+        the live workspace snapshot, then configured operator instructions.
+        Prompt assembly can therefore put a cache boundary before the snapshot
+        without changing the persisted system-prompt bytes.
         """
         if not self.is_coding:
-            return []
-        blocks: list[str] = []
+            return [], [], []
+        prefix: list[str] = []
+        workspace_parts: list[str] = []
+        trailing: list[str] = []
         if self.profile.guidance:
             brief = self.profile.guidance
             edit_line = _edit_format_line(self.model)
             if edit_line:
                 brief = f"{brief}\n{edit_line}"
-            blocks.append(brief)
+            prefix.append(brief)
         workspace = build_coding_workspace_block(self.cwd)
         if workspace:
-            blocks.append(workspace)
+            workspace_parts.append(workspace)
         # Operator instructions ride their own block so the brief (block 0) stays
         # byte-stable and cache-keyed independently of user config.
         if self.instructions:
-            blocks.append(f"Operator instructions (from config):\n{self.instructions}")
-        return blocks
+            trailing.append(f"Operator instructions (from config):\n{self.instructions}")
+        return prefix, workspace_parts, trailing
+
+    def system_blocks(self) -> list[str]:
+        """Return posture blocks in their historical display order.
+
+        ``system_prompt_parts`` is the cache-aware API. This compatibility
+        helper retains the public flat list for callers outside prompt assembly.
+        """
+        prefix, workspace, trailing = self.system_prompt_parts()
+        return [*prefix, *workspace, *trailing]
 
     def compact_skill_categories(self) -> frozenset[str]:
         """Skill categories to demote to names-only in the prompt's skill index.
@@ -644,6 +660,19 @@ def coding_system_blocks(
     ).system_blocks()
 
 
+def coding_system_prompt_parts(
+    *,
+    platform: Optional[str] = None,
+    cwd: Optional[str | Path] = None,
+    config: Optional[dict[str, Any]] = None,
+    model: Optional[str] = None,
+) -> tuple[list[str], list[str], list[str]]:
+    """Return coding prefix, workspace snapshot, and trailing guidance."""
+    return resolve_runtime_mode(
+        platform=platform, cwd=cwd, config=config, model=model
+    ).system_prompt_parts()
+
+
 def coding_compact_skill_categories(
     *,
     platform: Optional[str] = None,
diff --git a/agent/context_compressor.py b/agent/context_compressor.py
index e282a6c7a45..73fa1e36f21 100644
--- a/agent/context_compressor.py
+++ b/agent/context_compressor.py
@@ -90,9 +90,6 @@ def _is_summary_access_or_quota_error(exc: Exception) -> bool:
 
 
 HISTORICAL_TASK_HEADING = "## Historical Task Snapshot"
-HISTORICAL_IN_PROGRESS_HEADING = "## Historical In-Progress State"
-HISTORICAL_PENDING_ASKS_HEADING = "## Historical Pending User Asks"
-HISTORICAL_REMAINING_WORK_HEADING = "## Historical Remaining Work"
 
 
 SUMMARY_PREFIX = (
@@ -107,9 +104,7 @@ SUMMARY_PREFIX = (
     "Topic overlap with the summary does NOT mean you should resume its "
     "task: even on similar topics, the latest user message WINS. Treat ONLY "
     "the latest message as the active task and discard stale items from "
-    f"'{HISTORICAL_TASK_HEADING}' / '{HISTORICAL_IN_PROGRESS_HEADING}' / "
-    f"'{HISTORICAL_PENDING_ASKS_HEADING}' / "
-    f"'{HISTORICAL_REMAINING_WORK_HEADING}' entirely — do not 'wrap up' or "
+    f"'{HISTORICAL_TASK_HEADING}' entirely — do not 'wrap up' or "
     "'finish' work described there unless the latest message explicitly "
     "asks for it. "
     "Reverse signals in the latest message (e.g. 'stop', 'undo', 'roll "
@@ -219,8 +214,45 @@ _MERGED_SUMMARY_DELIMITER = "[END OF PRIOR CONTEXT — COMPACTION SUMMARY BELOW]
 # stale directive it carried (e.g. "resume exactly from Active Task") survives
 # embedded in the body and keeps hijacking replies. Keep newest-first; entries
 # are matched literally. Add a frozen copy here whenever SUMMARY_PREFIX changes.
+# NEVER mutate or reorder an existing entry — each one is the exact wire text a
+# shipped build persisted, so editing it silently un-normalizes every summary
+# written by that build generation; prepend only. tests/agent/
+# test_summary_prefix_semantics.py byte-pins every entry to enforce this.
 _HISTORICAL_SUMMARY_PREFIXES = (
-    # Jul 2026 (#65848 class): identical to the current prefix except it
+    # Pre-#69619: identical to the current prefix except the stale-item
+    # discard clause named all four historical headings (the three
+    # section headers removed by #69619 were still in the template).
+    # Summaries persisted by builds immediately before #69619 carry this
+    # exact text and must remain detectable/strippable on resume.
+    "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted "
+    "into the summary below. This is a handoff from a previous context "
+    "window — treat it as background reference, NOT as active instructions. "
+    "Do NOT answer questions or fulfill requests mentioned in this summary; "
+    "they were already addressed. "
+    "Respond ONLY to the latest user message that appears AFTER this "
+    "summary — that message is the single source of truth for what to do "
+    "right now. "
+    "Topic overlap with the summary does NOT mean you should resume its "
+    "task: even on similar topics, the latest user message WINS. Treat ONLY "
+    "the latest message as the active task and discard stale items from "
+    "'## Historical Task Snapshot' / '## Historical In-Progress State' / "
+    "'## Historical Pending User Asks' / "
+    "'## Historical Remaining Work' entirely — do not 'wrap up' or "
+    "'finish' work described there unless the latest message explicitly "
+    "asks for it. "
+    "Reverse signals in the latest message (e.g. 'stop', 'undo', 'roll "
+    "back', 'just verify', 'don't do that anymore', 'never mind', a new "
+    "topic) must immediately end any in-flight work described in the "
+    "summary; do not re-surface it in later turns. "
+    "IMPORTANT: Your persistent memory (MEMORY.md, USER.md) in the system "
+    "prompt is ALWAYS authoritative and active — never ignore or deprioritize "
+    "memory content due to this compaction note. "
+    "None of the above restricts HOW you work: your tools remain fully "
+    "active — keep calling them normally for the active task (edit files, "
+    "run commands, search) instead of merely narrating what you would do. "
+    "The current session state (files, config, etc.) may reflect work "
+    "described here — avoid repeating it:",
+    # Jul 2026 (#65848 class): identical to the pre-#69619 prefix except it
     # lacked the explicit "tools remain fully active" clause — the strong
     # REFERENCE ONLY framing bled into general tool-use suppression
     # (observed: 7 consecutive narration-only turns immediately after a
@@ -236,9 +268,9 @@ _HISTORICAL_SUMMARY_PREFIXES = (
     "Topic overlap with the summary does NOT mean you should resume its "
     "task: even on similar topics, the latest user message WINS. Treat ONLY "
     "the latest message as the active task and discard stale items from "
-    f"'{HISTORICAL_TASK_HEADING}' / '{HISTORICAL_IN_PROGRESS_HEADING}' / "
-    f"'{HISTORICAL_PENDING_ASKS_HEADING}' / "
-    f"'{HISTORICAL_REMAINING_WORK_HEADING}' entirely — do not 'wrap up' or "
+    "'## Historical Task Snapshot' / '## Historical In-Progress State' / "
+    "'## Historical Pending User Asks' / "
+    "'## Historical Remaining Work' entirely — do not 'wrap up' or "
     "'finish' work described there unless the latest message explicitly "
     "asks for it. "
     "Reverse signals in the latest message (e.g. 'stop', 'undo', 'roll "
@@ -303,9 +335,238 @@ _SUMMARY_RATIO = 0.20
 # itself a context-pressure source and slows every compaction.
 _SUMMARY_TOKENS_CEILING = 10_000
 
+# Aggregate cap on the serialized turn block fed to the summarizer prompt
+# (chars). Per-message truncation (_CONTENT_MAX / _TOOL_ARGS_MAX) alone is
+# not enough: a compression window with hundreds of already-truncated turns
+# can still produce a multi-hundred-KB prompt that blows past slow auxiliary
+# backends' context limits or timeouts (Codex Responses fallback paths
+# especially). 160K chars ≈ 40K tokens — comfortably inside every supported
+# aux model's window while leaving room for the template + previous summary.
+# Applied AFTER per-message truncation, with head+tail retention and an
+# explicit omitted-middle marker (see _bound_summary_input). This is a
+# prompt-side bound only — NEVER add a max_tokens wire cap on the summary
+# call (see the no-wire-cap contract test in
+# test_compression_small_ctx_threshold_floor.py).
+_SUMMARY_INPUT_MAX_CHARS = 160_000
+
 # Placeholder used when pruning old tool results
 _PRUNED_TOOL_PLACEHOLDER = "[Old tool output cleared to save context space]"
 
+# Ghost-skill defense (#32106): when compaction reduces an old ``skill_view``
+# result to a 1-line metadata summary, the model still believes the skill is
+# loaded even though its instructions are gone. The marker below is the ONE
+# canonical prune signal — ``_skill_pruned_marker()`` builds it and every
+# presence check matches against the same string, so the emit side and the
+# check side can never drift apart (the original PR #44166 emitted
+# ``[SKILL_PRUNED:`` but presence-checked ``[SKILL_PRUNED]``, making
+# re-injection fire even when the marker had survived).
+SKILL_PRUNED_MARKER_PREFIX = "[SKILL_PRUNED:"
+# skill_view results at or below this size stay verbatim in pruned
+# summaries — small skills are cheap to keep and their loss is unlikely to
+# ghost the model. Shared by the emit site and the summarizer-input scan.
+_SKILL_VIEW_PRUNE_MIN_CHARS = 5000
+# Cap for the deterministic marker re-injection list — keeps a very long
+# session from growing an unbounded "## Pruned Skills" block in every
+# iterative summary update. Newest-referenced skills win.
+_MAX_PRUNED_SKILL_MARKERS = 20
+
+
+def _skill_pruned_marker(skill_name: str) -> str:
+    """Return the canonical prune marker for *skill_name*.
+
+    Used verbatim by BOTH the emit sites (tool-result summarization,
+    summary re-injection) and the survival check in
+    ``_reinject_pruned_skill_markers`` — one string, no drift.
+    """
+    return (
+        f"{SKILL_PRUNED_MARKER_PREFIX} content lost in compression; "
+        f"reload with skill_view(name='{skill_name}')]"
+    )
+
+
+# Matches the canonical marker and captures the skill name. Anchored on the
+# shared prefix constant so a wording change to the marker body updates the
+# emit helper and this extractor together.
+_SKILL_PRUNED_MARKER_RE = re.compile(
+    re.escape(SKILL_PRUNED_MARKER_PREFIX)
+    + r"[^\]]*?reload with skill_view\(name='([^']+)'\)"
+)
+
+
+def _extract_pruned_skill_names(text: str) -> list[str]:
+    """Return skill names referenced by prune markers in *text*, in order."""
+    names: list[str] = []
+    for match in _SKILL_PRUNED_MARKER_RE.finditer(text or ""):
+        name = match.group(1)
+        if name not in names:
+            names.append(name)
+    return names
+
+
+def _collect_ghosted_skill_names(turns: List[Dict[str, Any]]) -> list[str]:
+    """Skill names whose instructions are about to be lost in compaction.
+
+    Covers BOTH shapes a compacted middle window can carry:
+
+    - a ``skill_view`` result already demoted by Phase-1 pruning — the
+      canonical ``[SKILL_PRUNED: ...]`` marker is in the row content;
+    - a RAW ``skill_view`` body that was never demoted (it sat inside the
+      protected tail of an earlier prune, then aged into the compression
+      window). The summarizer will paraphrase the instructions away, which
+      is exactly the ghost-skill failure — so it needs a marker too.
+    """
+    names: list[str] = []
+
+    def _add(name: str) -> None:
+        if name and name not in names:
+            names.append(name)
+
+    call_id_to_skill: dict[str, str] = {}
+    for idx, skill in _skill_view_call_sites(turns):
+        msg = turns[idx]
+        for tc in msg.get("tool_calls") or []:
+            tc_fn = tc.get("function", {}) if isinstance(tc, dict) else getattr(tc, "function", None)
+            tc_name = tc_fn.get("name", "") if isinstance(tc_fn, dict) else getattr(tc_fn, "name", "")
+            if tc_name != "skill_view":
+                continue
+            cid = tc.get("id", "") if isinstance(tc, dict) else (getattr(tc, "id", "") or "")
+            if cid:
+                call_id_to_skill[cid] = skill
+    for msg in turns:
+        content = msg.get("content")
+        text = content if isinstance(content, str) else _content_text_for_contains(content)
+        for name in _extract_pruned_skill_names(text):
+            _add(name)
+        if (
+            msg.get("role") == "tool"
+            and isinstance(content, str)
+            and len(content) > _SKILL_VIEW_PRUNE_MIN_CHARS
+        ):
+            skill = call_id_to_skill.get(str(msg.get("tool_call_id") or ""))
+            if skill:
+                _add(skill)
+    return names
+
+
+_PRUNED_SKILLS_SECTION_HEADING = "## Pruned Skills"
+
+
+def _reinject_pruned_skill_markers(summary: str, skill_names: list[str]) -> str:
+    """Deterministically restore prune markers the summarizer dropped.
+
+    ``skill_names`` was extracted from the summarizer INPUT before the LLM
+    call. For every skill whose canonical marker (``_skill_pruned_marker``)
+    is absent from the model's output, append it under a ``## Pruned
+    Skills`` section. Presence is checked against the SAME canonical string
+    the emit sites produce — a paraphrased or renamed marker counts as
+    dropped and is restored (the original PR checked the literal
+    ``[SKILL_PRUNED]``, which never matches the emitted ``[SKILL_PRUNED:``
+    form, so it duplicated markers that HAD survived).
+
+    The appended block is plain body text: it never carries a handoff
+    prefix, the merged-summary delimiter, or a start-of-content scaffolding
+    marker, so ``classify_summary_content`` / todo-snapshot flag handling
+    are unaffected. The block is routed through ``_redact_compaction_text``
+    like every other compaction-boundary text.
+    """
+    if not skill_names:
+        return summary
+    missing = [
+        name for name in skill_names
+        if _skill_pruned_marker(name) not in summary
+    ]
+    if not missing:
+        return summary
+    lines = [_skill_pruned_marker(name) for name in missing]
+    block = (
+        "\n\n" + _PRUNED_SKILLS_SECTION_HEADING + "\n"
+        + "\n".join(lines)
+        + "\n(The listed skills' instructions were pruned during context "
+        "compression. Reload with the skill_view call in each marker before "
+        "relying on that skill; one reload per skill is enough — ignore any "
+        "older markers for the same skill.)"
+    )
+    return summary + _redact_compaction_text(block)
+
+
+# A skill_view call within this many trailing messages counts as "just
+# loaded": its full instruction body must survive the Phase-1 prune even when
+# the token-budget boundary would otherwise demote it (#32106). Distinct from
+# the protected-tail boundary, which is token-based and can land immediately
+# after a bulky just-loaded skill body.
+_SKILL_PRUNE_RECENT_WINDOW = 10
+
+
+def _skill_view_call_sites(
+    messages: List[Dict[str, Any]],
+) -> list[tuple[int, str]]:
+    """Yield ``(message_index, skill_name)`` for every skill_view tool call."""
+    sites: list[tuple[int, str]] = []
+    for i, msg in enumerate(messages):
+        if msg.get("role") != "assistant":
+            continue
+        for tc in msg.get("tool_calls") or []:
+            if isinstance(tc, dict):
+                fn = tc.get("function", {})
+                name = fn.get("name", "") if isinstance(fn, dict) else ""
+                args_str = fn.get("arguments", "") if isinstance(fn, dict) else ""
+            else:
+                fn = getattr(tc, "function", None)
+                name = getattr(fn, "name", "") if fn else ""
+                args_str = getattr(fn, "arguments", "") if fn else ""
+            if name != "skill_view" or not isinstance(args_str, str) or not args_str:
+                continue
+            try:
+                args = json.loads(args_str)
+            except (json.JSONDecodeError, TypeError):
+                continue
+            if isinstance(args, dict):
+                skill = args.get("name", "")
+                if isinstance(skill, str) and skill:
+                    sites.append((i, skill))
+    return sites
+
+
+def _collect_protected_skill_names(
+    messages: List[Dict[str, Any]], prune_boundary: int,
+) -> set[str]:
+    """Skill names whose skill_view bodies must survive Phase-1 demotion.
+
+    A skill is protected (lower-cased set) when any of these hold:
+
+    - its most recent ``skill_view`` call sits within the last
+      ``_SKILL_PRUNE_RECENT_WINDOW`` messages (just loaded / just reloaded);
+    - its most recent ``skill_view`` call sits inside the protected tail
+      (at or after *prune_boundary*);
+    - its name is mentioned in a user message inside the protected tail
+      (the user is actively steering work that depends on it).
+
+    Protection applies to the ordinary Phase-1/2 prune only. The Pass-4
+    pressure demotion deliberately ignores it: when the protected region
+    itself exceeds the soft budget, exempting skill bodies would recreate
+    the #61932 dead-end shape.
+    """
+    total = len(messages)
+    if not total:
+        return set()
+    recent_start = max(0, total - _SKILL_PRUNE_RECENT_WINDOW)
+    tail_start = max(0, prune_boundary)
+    tail_user_texts: list[str] = []
+    for msg in messages[tail_start:]:
+        if msg.get("role") != "user":
+            continue
+        content = msg.get("content")
+        if isinstance(content, str) and content:
+            tail_user_texts.append(content.lower())
+    protected: set[str] = set()
+    for idx, skill in _skill_view_call_sites(messages):
+        key = skill.lower()
+        if idx >= recent_start or idx >= tail_start:
+            protected.add(key)
+        elif any(key in text for text in tail_user_texts):
+            protected.add(key)
+    return protected
+
 # Chars per token rough estimate
 _CHARS_PER_TOKEN = 4
 # Flat token cost per attached image part.  Real cost varies by provider and
@@ -877,7 +1138,19 @@ def _summarize_tool_result_unguarded(tool_name: str, tool_args: str, tool_conten
             code_preview += "..."
         return f"[execute_code] `{code_preview}` ({line_count} lines output)"
 
-    if tool_name in {"skill_view", "skills_list", "skill_manage"}:
+    if tool_name == "skill_view":
+        name = args.get("name", "?")
+        if content_len > _SKILL_VIEW_PRUNE_MIN_CHARS:
+            # Ghost-skill defense (#32106): a metadata-only summary makes the
+            # model believe the skill is still loaded. The canonical marker
+            # tells it the instructions are gone AND how to get them back.
+            return (
+                f"[skill_view] name={name} ({content_len:,} chars) "
+                + _skill_pruned_marker(str(name))
+            )
+        return f"[skill_view] name={name} ({content_len:,} chars)"
+
+    if tool_name in {"skills_list", "skill_manage"}:
         name = args.get("name", "?")
         return f"[{tool_name}] name={name} ({content_len:,} chars)"
 
@@ -972,6 +1245,7 @@ class ContextCompressor(ContextEngine):
         self._last_aux_model_failure_model = None
         self._last_compression_savings_pct = 100.0
         self._ineffective_compression_count = 0
+        self._anti_thrash_recovery_deadline = 0.0
         self._fallback_compression_streak = 0
         self._verify_compaction_cleared_threshold = False
         self._last_compression_made_progress = False
@@ -1109,6 +1383,7 @@ class ContextCompressor(ContextEngine):
         self._last_aux_model_failure_model = None
         self._last_compression_savings_pct = 100.0
         self._ineffective_compression_count = 0
+        self._anti_thrash_recovery_deadline = 0.0
         self._fallback_compression_streak = 0
         self._verify_compaction_cleared_threshold = False
         self._last_compression_made_progress = False
@@ -1135,6 +1410,7 @@ class ContextCompressor(ContextEngine):
         self._consecutive_timeout_failures = 0
         self._fallback_compression_streak = 0
         self._ineffective_compression_count = 0
+        self._anti_thrash_recovery_deadline = 0.0
         self.get_active_compression_failure_cooldown()
         self._load_fallback_compression_streak()
         self._load_ineffective_compression_count()
@@ -1506,6 +1782,15 @@ class ContextCompressor(ContextEngine):
     # rationale as the gpt-5.5/Codex 85% autoraise.
     _MIN_CTX_TRIGGER_RATIO = 0.85
 
+    # Anti-thrash recovery window (#14694): once the ineffective/fallback
+    # breaker trips, automatic compaction stays blocked for this long, then
+    # ONE probe attempt is allowed (counters drop to 1 strike, so another
+    # ineffective pass re-trips immediately). Long enough that a genuinely
+    # incompressible session isn't compacting in a loop; short enough that a
+    # session which has since grown real compressible material recovers well
+    # before it rides into the provider's hard context limit.
+    _ANTI_THRASH_RECOVERY_SECONDS = 300.0
+
     @staticmethod
     def _coerce_max_tokens(value: Any) -> int | None:
         """Normalize a max_tokens value to a positive int or None.
@@ -1629,6 +1914,10 @@ class ContextCompressor(ContextEngine):
         max_tokens: int | None = None,
         model_thresholds: dict[str, float] | None = None,
         threshold_tokens_cap: Any = None,
+        proactive_prune_tokens: int = 0,
+        proactive_prune_min_result_chars: int = 8000,
+        proactive_prune_min_reclaim_tokens: int = 4096,
+        min_tail_user_messages: int = 1,
     ):
         self.model = model
         self.base_url = base_url
@@ -1658,6 +1947,32 @@ class ContextCompressor(ContextEngine):
         )
         self.protect_first_n = protect_first_n
         self.protect_last_n = protect_last_n
+        # Proactive tool-result pruning (cost-oriented; runs INDEPENDENTLY of the
+        # full-compression trigger, via prune_tool_results_only()). 0 = disabled.
+        self.proactive_prune_tokens = int(proactive_prune_tokens or 0)
+        # Floor the summarize threshold at 200 chars (matching
+        # _prune_old_tool_results' dedup floor). Below ~200 a generated summary
+        # can be longer than the floor it replaces, so Pass 2 would re-summarize
+        # its own output every turn (corrupting it and never converging); a
+        # negative value would strip every non-tail tool result outright. A
+        # configured 0 keeps the 8000 default via `or`. Keep the floor well above
+        # typical summary length (default 8000) to stay idempotent.
+        self.proactive_prune_min_result_chars = max(
+            200, int(proactive_prune_min_result_chars or 8000)
+        )
+        # Minimum estimated token reclaim before a proactive prune COMMITS.
+        # Every commit rewrites messages the provider has already seen, which
+        # invalidates the prompt-cache prefix from the earliest rewritten
+        # message forward. Without this gate a busy tool loop would re-fire
+        # the prune nearly every iteration (each new tool pair ages an old one
+        # out of the protected tail), breaking the cache per turn. Requiring a
+        # meaningful batch of reclaimable tokens makes fires episodic and
+        # amortized — the same way full compression is the one sanctioned
+        # cache break. 0 disables the gate (commit any non-zero prune).
+        self.proactive_prune_min_reclaim_tokens = max(
+            0, int(proactive_prune_min_reclaim_tokens or 0)
+        )
+        self.min_tail_user_messages = min_tail_user_messages
         self.summary_target_ratio = max(0.10, min(summary_target_ratio, 0.80))
         self.quiet_mode = quiet_mode
         # Output-token reservation: the provider carves max_tokens out of the
@@ -1745,6 +2060,12 @@ class ContextCompressor(ContextEngine):
         # Anti-thrashing: track whether last compression was effective
         self._last_compression_savings_pct: float = 100.0
         self._ineffective_compression_count: int = 0
+        # Monotonic deadline after which a tripped anti-thrash guard grants
+        # one probation probe (#14694). 0.0 = clock not armed. Armed lazily on
+        # the first blocked evaluation; deliberately NOT durable, so a process
+        # restart with a persisted tripped counter (#69872) waits a full fresh
+        # window before probing (#54923: restart must never disarm a guard).
+        self._anti_thrash_recovery_deadline: float = 0.0
         # Consecutive completed deterministic-fallback boundaries. Unlike the
         # real-usage effectiveness counter, ordinary fitting responses must not
         # reset this breaker; only a healthy completed summary does.
@@ -1856,6 +2177,16 @@ class ContextCompressor(ContextEngine):
         self._verify_compaction_cleared_threshold = False
         self.awaiting_real_usage_after_compression = False
 
+    def snapshot_preflight_display_tokens(self) -> int:
+        """Capture the display token count before a speculative preflight seed."""
+        return self.last_prompt_tokens
+
+    def rollback_interrupted_preflight_display_tokens(self, snapshot: int) -> None:
+        """Restore a speculative display seed without touching compaction state."""
+        if self.awaiting_real_usage_after_compression and self.last_prompt_tokens == -1:
+            return
+        self.last_prompt_tokens = snapshot
+
     def should_defer_preflight_to_real_usage(self, rough_tokens: int) -> bool:
         """Return True when a high rough preflight estimate is known-noisy.
 
@@ -2025,21 +2356,66 @@ class ContextCompressor(ContextEngine):
                     _cooldown_remaining,
                 )
             return True
-        # Anti-thrashing: back off if recent compressions were ineffective
+        # Anti-thrashing: back off if recent compressions were ineffective.
+        # The back-off must not be permanent (#14694): the tripped state was
+        # judged against the transcript as it existed THEN (e.g. a middle
+        # region too small to matter), but the conversation keeps growing and
+        # can accumulate plenty of compressible material later. Without a
+        # recovery path the session never auto-compacts again and rides into
+        # the provider's hard context limit. Recovery is a probation probe:
+        # after _ANTI_THRASH_RECOVERY_SECONDS of continuous block, allow ONE
+        # attempt by dropping the tripped counter(s) to 1 strike (persisted,
+        # so sibling agents on the same session row unblock too). If the probe
+        # is ineffective again the very next verdict re-trips the guard, so
+        # the worst case in the truly-incompressible state is one compaction
+        # attempt per recovery window — bounded, not thrash.
+        #
+        # The clock is armed lazily on the first BLOCKED evaluation rather
+        # than persisted at trip time: a fresh process that loads a durable
+        # tripped counter (#69872) therefore starts a full window blocked,
+        # preserving the restart-must-not-disarm contract (#54923).
         if (
             self._ineffective_compression_count >= 2
             or self._fallback_compression_streak >= 2
         ):
+            _now = time.monotonic()
+            if self._anti_thrash_recovery_deadline <= 0.0:
+                self._anti_thrash_recovery_deadline = (
+                    _now + self._ANTI_THRASH_RECOVERY_SECONDS
+                )
+            elif _now >= self._anti_thrash_recovery_deadline:
+                self._anti_thrash_recovery_deadline = 0.0
+                if self._ineffective_compression_count >= 2:
+                    self._record_ineffective_compression_verdict(1)
+                if self._fallback_compression_streak >= 2:
+                    self._fallback_compression_streak = 1
+                    self._persist_fallback_compression_streak()
+                if not self.quiet_mode:
+                    logger.info(
+                        "Anti-thrashing recovery: %.0fs elapsed since the "
+                        "guard tripped — allowing one compaction probe "
+                        "(ineffective=%d fallback=%d).",
+                        self._ANTI_THRASH_RECOVERY_SECONDS,
+                        self._ineffective_compression_count,
+                        self._fallback_compression_streak,
+                    )
+                return False
             if not self.quiet_mode:
                 logger.warning(
                     "Compression skipped — repeated compaction attempts did not "
                     "restore healthy context. ineffective=%d fallback=%d. "
-                    "Consider /new to start fresh, or /compress <topic> for "
-                    "focused compression.",
+                    "Auto-compaction will retry once in %.0fs. Consider /new "
+                    "to start fresh, or /compress <topic> for focused "
+                    "compression.",
                     self._ineffective_compression_count,
                     self._fallback_compression_streak,
+                    max(0.0, self._anti_thrash_recovery_deadline - _now),
                 )
             return True
+        # Guard not tripped (counters were cleared by an effective compaction
+        # or a fitting real-usage reading) — disarm any pending recovery clock
+        # so a LATER trip starts its own full window.
+        self._anti_thrash_recovery_deadline = 0.0
         return False
 
     # ------------------------------------------------------------------
@@ -2049,6 +2425,7 @@ class ContextCompressor(ContextEngine):
     def _prune_old_tool_results(
         self, messages: List[Dict[str, Any]], protect_tail_count: int,
         protect_tail_tokens: int | None = None,
+        min_prune_chars: int = 200,
     ) -> tuple[List[Dict[str, Any]], int]:
         """Replace old tool result contents with informative 1-line summaries.
 
@@ -2158,7 +2535,14 @@ class ContextCompressor(ContextEngine):
             else:
                 content_hashes[h] = (i, msg.get("tool_call_id", "?"))
 
-        def _demote_tool_result_at(idx: int) -> bool:
+        # Ghost-skill defense (#32106): skills just loaded (or actively
+        # referenced in the protected tail) keep their full skill_view
+        # bodies through the ordinary prune passes. Without this, a skill
+        # loaded moments before a compaction can be demoted to metadata
+        # while the model still believes its instructions are in context.
+        protected_skills = _collect_protected_skill_names(result, prune_boundary)
+
+        def _demote_tool_result_at(idx: int, *, spare_protected_skills: bool = True) -> bool:
             """Replace a bulky tool result at ``idx`` with a 1-line summary.
 
             Returns True when the message was modified.
@@ -2191,10 +2575,22 @@ class ContextCompressor(ContextEngine):
                 return False
             if content.startswith("[screenshot removed"):
                 return False
-            if len(content) <= 200:
+            # Only prune if the content is substantial (default >200 chars; the
+            # proactive path raises this floor via min_prune_chars).
+            if len(content) <= min_prune_chars:
                 return False
             call_id = msg.get("tool_call_id", "")
             tool_name, tool_args = call_id_to_tool.get(call_id, ("unknown", ""))
+            if spare_protected_skills and tool_name == "skill_view" and protected_skills:
+                # Just-loaded / actively-referenced skills survive verbatim
+                # (#32106). Pass-4 pressure demotion overrides this.
+                try:
+                    _args = json.loads(tool_args) if tool_args else {}
+                except (json.JSONDecodeError, TypeError):
+                    _args = {}
+                _skill = _args.get("name", "") if isinstance(_args, dict) else ""
+                if isinstance(_skill, str) and _skill.lower() in protected_skills:
+                    return False
             summary = _summarize_tool_result(tool_name, tool_args, content)
             result[idx] = {**msg, "content": summary}
             pruned += 1
@@ -2259,7 +2655,10 @@ class ContextCompressor(ContextEngine):
             if demote_end > prune_boundary and _protected_region_tokens() > soft_ceiling:
                 pressure_hits = 0
                 for i in range(max(0, prune_boundary), demote_end):
-                    if _demote_tool_result_at(i):
+                    # Pressure passes override the just-loaded-skill guard:
+                    # when the protected region itself blows the soft budget,
+                    # sparing skill bodies would recreate the #61932 dead-end.
+                    if _demote_tool_result_at(i, spare_protected_skills=False):
                         pressure_hits += 1
                     if _truncate_tool_call_args_at(i):
                         pressure_hits += 1
@@ -2279,7 +2678,7 @@ class ContextCompressor(ContextEngine):
                         if last_tool_idx is not None and i == last_tool_idx:
                             continue
                         if result[i].get("role") == "tool":
-                            if _demote_tool_result_at(i):
+                            if _demote_tool_result_at(i, spare_protected_skills=False):
                                 pressure_hits += 1
                         elif result[i].get("role") == "assistant":
                             if _truncate_tool_call_args_at(i):
@@ -2293,7 +2692,9 @@ class ContextCompressor(ContextEngine):
                         and last_tool_idx >= prune_boundary
                         and _protected_region_tokens() > soft_ceiling
                     ):
-                        if _demote_tool_result_at(last_tool_idx):
+                        if _demote_tool_result_at(
+                            last_tool_idx, spare_protected_skills=False
+                        ):
                             pressure_hits += 1
                 if pressure_hits and not self.quiet_mode:
                     logger.info(
@@ -2307,6 +2708,75 @@ class ContextCompressor(ContextEngine):
 
         return result, pruned
 
+    def prune_tool_results_only(
+        self, messages: List[Dict[str, Any]], current_tokens: int | None = None,
+    ) -> tuple[List[Dict[str, Any]], int]:
+        """Deterministic, no-LLM tool-result prune for the cost-oriented path.
+
+        Runs the Phase-1 prune (``_prune_old_tool_results``) WITHOUT the
+        compression summary phase, gated on ``proactive_prune_tokens`` rather
+        than the (much higher) full-compression threshold. On large-window
+        models ``should_compress()`` (≈50% of the window) rarely fires, so old
+        tool outputs otherwise ride in history and are re-sent verbatim on every
+        subsequent turn; this reclaims them early with no quality-risky LLM
+        summarization.
+
+        Protects the recent tail by message COUNT (``protect_last_n``), never by
+        ``tail_token_budget`` — the latter is derived from the 50% compression
+        threshold (≈100K tokens on a 1M window) and would protect the entire
+        session, pruning nothing.
+
+        ``_prune_old_tool_results`` runs all three deterministic passes:
+        (1) dedup byte-identical tool results — keeps the newest full copy and
+        back-references older exact duplicates ANYWHERE in the list (including
+        the protected tail), so no unique content is ever lost; (2) summarize
+        non-tail tool results larger than ``min_prune_chars``; (3) truncate
+        oversized tool_call arguments on non-tail assistant messages. Only
+        pass (2)'s floor is raised by ``proactive_prune_min_result_chars``;
+        passes (1) and (3) keep their own fixed floors. The recent-tail
+        protection applies to passes (2) and (3); pass (1) is tail-agnostic by
+        design because dedup is lossless.
+
+        PROMPT-CACHE CONTRACT: a committed prune rewrites message bodies the
+        provider has already seen, invalidating the cached prefix from the
+        earliest rewritten message forward — exactly like a compression
+        boundary. To keep that break episodic rather than per-turn, the prune
+        only COMMITS when the estimated reclaim meets
+        ``proactive_prune_min_reclaim_tokens`` (measured on the actual pruned
+        output, not guessed up front). Below the gate the INPUT list object is
+        returned unchanged — the standard no-op caller contract (callers gate
+        bookkeeping on ``result is not input``).
+
+        Returns ``(messages, 0)`` — the input object — when disabled, below
+        the trigger, or when the reclaim gate rejects the commit.
+        """
+        if self.proactive_prune_tokens <= 0:
+            return messages, 0
+        if current_tokens is not None and current_tokens < self.proactive_prune_tokens:
+            return messages, 0
+        # Nothing to reclaim until there are messages outside the protected tail.
+        if len(messages) <= self.protect_last_n + self._protect_head_size(messages) + 1:
+            return messages, 0
+        pruned_msgs, pruned_count = self._prune_old_tool_results(
+            messages,
+            protect_tail_count=self.protect_last_n,
+            protect_tail_tokens=None,
+            min_prune_chars=self.proactive_prune_min_result_chars,
+        )
+        if not pruned_count:
+            # Standard no-op contract: hand back the INPUT object so callers
+            # can gate bookkeeping on `result is not input`.
+            return messages, 0
+        # Measured-savings gate (prompt-cache hysteresis): only commit when
+        # the prune reclaims a meaningful batch of tokens. Estimated on the
+        # real before/after messages so dedup + arg truncation count too.
+        if self.proactive_prune_min_reclaim_tokens > 0:
+            before = sum(_estimate_msg_budget_tokens(m) for m in messages)
+            after = sum(_estimate_msg_budget_tokens(m) for m in pruned_msgs)
+            if (before - after) < self.proactive_prune_min_reclaim_tokens:
+                return messages, 0
+        return pruned_msgs, pruned_count
+
     # ------------------------------------------------------------------
     # Summarization
     # ------------------------------------------------------------------
@@ -2330,6 +2800,10 @@ class ContextCompressor(ContextEngine):
     _CONTENT_TAIL = 1500      # chars kept from the end
     _TOOL_ARGS_MAX = 1500     # tool call argument chars
     _TOOL_ARGS_HEAD = 1200    # kept from the start of tool args
+    # Aggregate cap over the whole serialized block, applied AFTER the
+    # per-message limits above. Alias of the module-level constant (which
+    # carries the full rationale) so subclasses/tests can override per-class.
+    _SUMMARY_INPUT_MAX_CHARS = _SUMMARY_INPUT_MAX_CHARS
 
     def _serialize_for_summary(self, turns: List[Dict[str, Any]]) -> str:
         """Serialize conversation turns into labeled text for the summarizer.
@@ -2589,12 +3063,6 @@ Recovered from a deterministic fallback because the LLM context summarizer was u
 ## Active State
 Unknown from deterministic fallback. Inspect current repository/session state if needed.
 
-{HISTORICAL_IN_PROGRESS_HEADING}
-Unknown from deterministic fallback — the latest user ask is recorded once under
-"{HISTORICAL_TASK_HEADING}" above as historical context only. Do NOT treat it as an
-unfulfilled instruction to re-answer; verify current state and continue from the
-protected recent messages after this summary.
-
 ## Blocked
 {_bullets(blockers, limit=5)}
 
@@ -2604,27 +3072,62 @@ None recoverable from deterministic fallback.
 ## Resolved Questions
 None recoverable from deterministic fallback.
 
-{HISTORICAL_PENDING_ASKS_HEADING}
-None recoverable from deterministic fallback. (The latest user ask is preserved once
-under "{HISTORICAL_TASK_HEADING}" as historical context — it is NOT necessarily
-outstanding.)
-
 ## Relevant Files
 {_bullets(relevant_files, limit=12)}
 
-{HISTORICAL_REMAINING_WORK_HEADING}
-Continue from the most recent unfulfilled user ask and protected tail messages. Verify state with tools before making claims.
-
 ## Last Dropped Turns
 {_bullets(last_dropped_turns, limit=8)}
 
 ## Critical Context
 Summary generation was unavailable, so this is a best-effort deterministic fallback for {len(turns_to_summarize)} compacted message(s).{reason_text}"""
+        # Ghost-skill defense (#32106): the fallback's per-turn truncation
+        # (``_FALLBACK_TURN_MAX_CHARS``) routinely cuts [SKILL_PRUNED: ...]
+        # markers out of the compacted turns. Re-derive the ghosted skills
+        # from the raw turn contents and re-inject deterministically,
+        # exactly like the LLM-summary path.
+        _pruned_names = _collect_ghosted_skill_names(turns_to_summarize)
+        del _pruned_names[_MAX_PRUNED_SKILL_MARKERS:]
         summary = self._with_summary_prefix(_redact_compaction_text(body.strip()))
         if len(summary) > _FALLBACK_SUMMARY_MAX_CHARS:
             summary = summary[: _FALLBACK_SUMMARY_MAX_CHARS - 42].rstrip() + "\n...[fallback summary truncated]"
+        # Re-inject AFTER the size cap: the markers live at the end of the
+        # body, exactly where the truncation above cuts.
+        summary = _reinject_pruned_skill_markers(summary, _pruned_names)
         return summary
 
+    @classmethod
+    def _bound_summary_input(cls, content: str) -> str:
+        """Cap total summarizer input while preserving beginning and recent tail.
+
+        Per-message truncation alone is not enough for very long sessions: a
+        compression window with hundreds of messages can still produce a huge
+        single prompt that slow auxiliary backends time out on. Keep both edges
+        because the beginning often has task setup and the tail has the most
+        recent state; explicitly mark the omitted middle so the summarizer knows
+        context was intentionally compressed before it saw the prompt.
+        """
+        if len(content) <= cls._SUMMARY_INPUT_MAX_CHARS:
+            return content
+
+        marker_template = (
+            "\n\n...[summary input truncated: omitted "
+            "{omitted:,} chars from the middle to keep compression prompt bounded]...\n\n"
+        )
+        # Estimate once, then rebuild with the exact omitted span after the
+        # head/tail split is known. The second marker can differ by a few chars
+        # if the comma-formatted number changes width, so recompute once.
+        marker = marker_template.format(omitted=len(content))
+        remaining = max(cls._SUMMARY_INPUT_MAX_CHARS - len(marker), 0)
+        head_chars = int(remaining * 0.45)
+        tail_chars = remaining - head_chars
+        omitted = max(len(content) - head_chars - tail_chars, 0)
+        marker = marker_template.format(omitted=omitted)
+        remaining = max(cls._SUMMARY_INPUT_MAX_CHARS - len(marker), 0)
+        head_chars = int(remaining * 0.45)
+        tail_chars = remaining - head_chars
+        tail = content[-tail_chars:].lstrip() if tail_chars else ""
+        return content[:head_chars].rstrip() + marker + tail
+
     def _fallback_to_main_for_compression(self, e: Exception, reason: str) -> None:
         """Switch from a separate ``summary_model`` back to the main model.
 
@@ -2698,6 +3201,23 @@ Summary generation was unavailable, so this is a best-effort deterministic fallb
 
         summary_budget = self._compute_summary_budget(turns_to_summarize)
         content_to_summarize = self._serialize_for_summary(turns_to_summarize)
+        # P2 ghost-skill defense (#32106): [SKILL_PRUNED: ...] markers entering
+        # the summarizer are prompt INPUT only — LLMs routinely paraphrase them
+        # into vague prose ("some skills were loaded"), which erases the reload
+        # instruction. Collect the ghosted skills deterministically BEFORE the
+        # call (both already-pruned marker rows AND raw skill_view bodies whose
+        # instructions are about to be summarized away);
+        # ``_reinject_pruned_skill_markers`` restores any marker the model
+        # dropped AFTER the call. Markers already carried by the previous
+        # summary must survive iterative rewrites the same way. Collection
+        # walks the turn LIST, so the serialized input bound below cannot
+        # hide a marker in its omitted middle.
+        _pruned_skill_names = _collect_ghosted_skill_names(turns_to_summarize)
+        for _name in _extract_pruned_skill_names(self._previous_summary or ""):
+            if _name not in _pruned_skill_names:
+                _pruned_skill_names.append(_name)
+        del _pruned_skill_names[_MAX_PRUNED_SKILL_MARKERS:]
+        content_to_summarize = self._bound_summary_input(content_to_summarize)
         _sanitized_memory_context = sanitize_memory_context(memory_context)
         _serialized_memory_context = json.dumps(
             _sanitized_memory_context,
@@ -2865,9 +3385,6 @@ Be specific with file paths, commands, line numbers, and results.]
 - Any running processes or servers
 - Environment details that matter]
 
-{HISTORICAL_IN_PROGRESS_HEADING}
-[Work currently underway — what was being done when compaction fired]
-
 ## Blocked
 [Any blockers, errors, or issues not yet resolved. Include exact error messages.]
 
@@ -2877,30 +3394,39 @@ Be specific with file paths, commands, line numbers, and results.]
 ## Resolved Questions
 {_resolved_questions_instructions}
 
-{HISTORICAL_PENDING_ASKS_HEADING}
-{_pending_asks_instructions}
-
 ## Relevant Files
 [Files read, modified, or created — with brief note on each]
 
-{HISTORICAL_REMAINING_WORK_HEADING}
-[What remains to be done — framed as STALE context for reference only. The agent must NOT resume this work unless the latest user message explicitly asks for it.]
-
 ## Critical Context
 [Any specific values, error messages, configuration details, or data that would be lost without explicit preservation. NEVER include API keys, tokens, passwords, or credentials — write [REDACTED] instead.]
 
+{_PRUNED_SKILLS_SECTION_HEADING}
+[If any [SKILL_PRUNED: ...reload with skill_view(...)] markers appear in the input,
+repeat each one verbatim here — copy the exact text, do NOT paraphrase, summarize,
+or describe them. These markers tell the agent which skills must be reloaded before
+use. If none appear, omit this section entirely.]
+
 Target ~{summary_budget} tokens. Be CONCRETE — include file paths, command outputs, error messages, line numbers, and specific values. Avoid vague descriptions like "made some changes" — say exactly what changed.
 {_temporal_anchoring_rule}
 Write only the summary body. Do not include any preamble or prefix."""
 
         if self._previous_summary:
-            # Iterative update: preserve existing info, add new progress
+            # Iterative update: preserve existing info, add new progress.
+            # Bound the previous-summary block with the same aggregate cap as
+            # the serialized new turns: a normal summary is far below the cap
+            # (the output side is held to a ~10K-token ceiling), but a
+            # pathological handoff rehydrated from a persisted session can be
+            # arbitrarily large — the iterative prompt (previous summary +
+            # new turns) must stay bounded too.
+            _bounded_previous_summary = self._bound_summary_input(
+                self._previous_summary
+            )
             prompt = f"""{_summarizer_preamble}
 
 You are updating a context compaction summary. A previous compaction produced the summary below. New conversation turns have occurred since then and need to be incorporated.
 
 PREVIOUS SUMMARY:
-{self._previous_summary}
+{_bounded_previous_summary}
 
 NEW TURNS TO INCORPORATE:
 {content_to_summarize}{_memory_section}
@@ -3031,6 +3557,9 @@ This compaction should PRIORITISE preserving all information related to the focu
             # Redact the summary output as well — the summarizer LLM may
             # ignore prompt instructions and echo back secrets verbatim.
             summary = _redact_compaction_text(content.strip())
+            # P2 ghost-skill defense (#32106): deterministically restore any
+            # [SKILL_PRUNED: ...] marker the summarizer paraphrased away.
+            summary = _reinject_pruned_skill_markers(summary, _pruned_skill_names)
             summary = self._ground_historical_task_snapshot(summary, turns_to_summarize)
             self._validate_summary_user_provenance(summary, has_user_turn)
             # Store for iterative updates on next compaction
@@ -4091,6 +4620,69 @@ This compaction should PRIORITISE preserving all information related to the focu
             return max(pair_end, head_end + 1)
         return adjusted
 
+    def _ensure_last_n_user_messages_in_tail(
+        self,
+        messages: List[Dict[str, Any]],
+        cut_idx: int,
+        head_end: int,
+        n: int,
+    ) -> int:
+        """Guarantee the last N actionable user messages are in the protected tail.
+
+        Generalizes ``_ensure_last_user_message_in_tail`` to preserve an
+        arbitrary number of recent user messages.  This prevents the token-
+        budget-based tail cut from consuming recent conversation turns
+        when large tool outputs fill the budget.
+
+        When *n* <= 1, delegates directly to the existing single-message
+        method for byte-identical regression safety.
+
+        If the conversation has fewer than *n* user messages, the earliest
+        available user message is used without error.
+
+        Only REAL actionable user turns count toward N — the collector uses
+        the same ``_is_actionable_user_turn`` /
+        ``_is_synthetic_compression_user_turn`` pair as
+        ``_find_last_user_message_idx``, so blank platform echoes, compaction
+        handoffs, continuation markers, and todo-snapshot rows never consume
+        a slot (#69291 bug class).
+
+        A user message is already a clean boundary — there is no
+        tool_call/result group that spans across it, so
+        ``_align_boundary_backward`` is intentionally NOT called.
+        Calling it can pull the cut past the user message into the
+        preceding assistant(tool_calls)→tool group and split it (#22566).
+        """
+        if n <= 1:
+            return self._ensure_last_user_message_in_tail(messages, cut_idx, head_end)
+
+        # Collect real user message indices walking backward from end.
+        # Mirror _find_last_user_message_idx's filters: compaction handoffs,
+        # blank platform echoes, and synthetic continuation/todo rows are
+        # continuity artifacts, not real user turns.
+        user_indices = []
+        for i in range(len(messages) - 1, head_end - 1, -1):
+            msg = messages[i]
+            if (
+                self._is_actionable_user_turn(msg)
+                and not self._is_synthetic_compression_user_turn(msg)
+            ):
+                user_indices.append(i)
+
+        if len(user_indices) == 0:
+            return cut_idx
+
+        if len(user_indices) < n:
+            target_idx = user_indices[-1]
+        else:
+            target_idx = user_indices[n - 1]
+
+        if target_idx >= cut_idx:
+            return cut_idx
+
+        cut_idx = target_idx
+        return max(cut_idx, head_end + 1)
+
     def _find_turn_pair_end(
         self,
         messages: List[Dict[str, Any]],
@@ -4220,6 +4812,26 @@ This compaction should PRIORITISE preserving all information related to the focu
         # monotonic — the tail can only grow, never shrink.
         cut_idx = self._ensure_last_assistant_message_in_tail(messages, cut_idx, head_end)
 
+        # Extend to the last N actionable user messages when configured
+        # (compression.min_tail_user_messages > 1).  This prevents the
+        # token-budget tail from consuming recent turns when large tool
+        # outputs fill the budget.  The anchor only walks ``cut_idx``
+        # backward (monotonic — the tail can only grow, never shrink), and
+        # a user message is a clean boundary, so the forward re-alignment
+        # below remains a no-op for the anchored index.  Gated at the call
+        # site so the default (1) path is byte-identical to the historical
+        # single-anchor pipeline — the single-user anchor already ran above,
+        # and re-invoking it here could re-trigger the causal-coupling
+        # forward push (#22523) after the assistant anchor adjusted the cut.
+        # getattr-guarded: bare ``ContextCompressor.__new__`` test doubles
+        # (and plugin engines) skip __init__, so the attribute may be absent
+        # (see the compression-path test-double pitfall).
+        _min_tail_users = getattr(self, "min_tail_user_messages", 1)
+        if isinstance(_min_tail_users, int) and not isinstance(_min_tail_users, bool) and _min_tail_users > 1:
+            cut_idx = self._ensure_last_n_user_messages_in_tail(
+                messages, cut_idx, head_end, _min_tail_users,
+            )
+
         # The floor guarantees forward progress — compression must always claim
         # at least one message or the caller's compress_start >= compress_end
         # guard turns the pass into a no-op that re-runs forever (the same loop
@@ -4521,6 +5133,39 @@ This compaction should PRIORITISE preserving all information related to the focu
         )
         telemetry["chunk_count"] = 1 if turns_to_summarize else 0
 
+        if not turns_to_summarize:
+            # The newest handoff summary consumed the entire compressible
+            # window (every window row was a standalone handoff that strips
+            # to None, and nothing follows it before compress_end) — there
+            # is nothing new to summarize.  Skip the summary call entirely:
+            # without this guard the empty window still reached
+            # _generate_summary, wasting an aux LLM call that aborts
+            # noisily on empty input (#59496).  Mirrors the sibling
+            # "no compressable window" guard above (#40803): record an
+            # ineffective strike through the durable write-through helper
+            # so the anti-thrash breaker in should_compress() can stop the
+            # loop — this shape cannot shrink, so every subsequent turn
+            # would otherwise re-fire the same no-op.  The rehydrated
+            # _previous_summary is deliberately KEPT (not rolled back as
+            # the summary-abort path does for #57835): it came from a
+            # handoff genuinely present in this transcript, which is
+            # returned unchanged.
+            telemetry["failure_class"] = "empty_post_handoff_window"
+            self._record_ineffective_compression_verdict(
+                self._ineffective_compression_count + 1,
+            )
+            self._last_compression_savings_pct = 0.0
+            if not self.quiet_mode:
+                logger.warning(
+                    "Compression skipped: latest context summary leaves no "
+                    "new turns to summarize in window %d-%d. "
+                    "ineffective_compression_count=%d",
+                    compress_start,
+                    compress_end,
+                    self._ineffective_compression_count,
+                )
+            return messages
+
         if not self.quiet_mode:
             logger.info(
                 "Context compression triggered (%d tokens >= %d threshold)",
diff --git a/agent/context_engine.py b/agent/context_engine.py
index 28d41e43161..b772125c0cb 100644
--- a/agent/context_engine.py
+++ b/agent/context_engine.py
@@ -189,6 +189,144 @@ class ContextEngine(ABC):
                 host filters unsupported optional arguments by signature.
         """
 
+    # -- Optional: proactive tool-result prune -----------------------------
+
+    def prune_tool_results_only(
+        self,
+        messages: List[Dict[str, Any]],
+        current_tokens: int | None = None,
+    ) -> tuple[List[Dict[str, Any]], int]:
+        """Deterministically trim old tool-result payloads without an LLM call.
+
+        Runs on a low, cost-oriented trigger independent of ``should_compress``
+        so large-window engines can reclaim re-sent tool output long before full
+        compaction would fire. Returns ``(messages, n_pruned)``.
+
+        Default is a safe no-op: the list is returned unchanged with ``0``
+        pruned. Engines that don't implement a cheap prune — and any engine that
+        predates this hook — inherit this default, so the agent loop's
+        post-tool-call prune path never raises ``AttributeError`` on them. The
+        built-in ContextCompressor overrides this with the real implementation.
+        """
+        return messages, 0
+
+    # -- Optional: per-turn context selection (distinct from compression) --
+
+    def select_context(
+        self,
+        request_messages: List[Dict[str, Any]],
+        *,
+        conversation_messages: List[Dict[str, Any]] = None,
+        incoming_message: Dict[str, Any] = None,
+        budget_tokens: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """Optionally choose/replace the context for THIS request, pre-generation.
+
+        Called every turn after the request message list is assembled and
+        before it is dispatched to the provider — independent of
+        ``should_compress()``. This lets an engine *select* which context
+        enters the prompt (retrieval, topic routing, role/branch switching)
+        rather than *shrink* context that is already there. The two verbs are
+        orthogonal:
+
+          - ``compress()``      : context is too long  -> make it shorter.
+          - ``select_context()``: this turn belongs to a different context
+                                  -> use that one instead.
+
+        Without this hook, engines that need per-turn access to the message
+        list have to force ``should_compress()`` to return ``True`` so that
+        ``compress()`` is invoked every turn purely as a callback — which
+        conflates selection with compression and degrades behaviour when the
+        engine's backend is unavailable. ``select_context()`` removes the need
+        for that workaround.
+
+        The returned list is request-only: it replaces the messages sent to
+        the provider for this single call and MUST NOT be treated as persisted
+        transcript state. The conversation history in the session DB is left
+        untouched, so nothing leaks across turns. Return ``None`` to leave the
+        request unchanged.
+
+        Unlike the ``pre_llm_call`` plugin hook (which appends to the user
+        message and intentionally never rewrites the list, to preserve the
+        cache prefix), ``select_context()`` may *replace* the message list.
+
+        Ordering / cache contract: the host runs this hook **before** prompt
+        cache-control and **before** every request sanitizer (orphaned-tool
+        cleanup, thinking-only/role normalization, whitespace/JSON
+        normalization). So (a) whatever the hook returns still passes through
+        the same validation as any request — a malformed replacement cannot
+        reach the provider — and (b) prompt-cache stability (an AGENTS.md
+        invariant) is preserved: the default no-op leaves the request
+        byte-identical, so cache behaviour is unchanged for the built-in
+        compressor and any non-implementing engine. An engine that *does*
+        replace the list changes its own cache prefix by definition; that is
+        the engine's concern, and cache-control breakpoints are re-derived on
+        the selected list. The hook is evaluated per provider request (so it
+        re-runs on retries within a turn), consistent with "select the context
+        for THIS request".
+
+        Args:
+            request_messages: The assembled request message list (system
+                prompt + history + any ephemeral prefill), in OpenAI format.
+            conversation_messages: The unmodified persisted conversation
+                history, for reference only (do not mutate).
+            incoming_message: The current turn's user message, if available.
+            budget_tokens: The active model's context length, or 0 if unknown.
+
+        Default returns ``None`` (no-op) — zero impact on the built-in
+        compressor or any existing engine.
+        """
+        return None
+
+    def on_turn_complete(
+        self,
+        messages: List[Dict[str, Any]],
+        usage: Dict[str, Any] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Observe a finished user turn (post-turn ingestion / observation).
+
+        Called from the standard turn-finalization path once the assistant/tool
+        loop completes, with the finalized in-memory transcript snapshot. This
+        is the complement to ``select_context()``: selection happens *before*
+        the request, while observation happens *after* the turn. It lets an
+        engine ingest, index, summarize, or update routing / topic / session
+        state from what actually happened — so the next ``select_context()``
+        can act on it.
+
+        Coverage: this fires from the normal finalization seam. Some abnormal
+        early-return paths in the loop (e.g. a content-policy block or a
+        provider terminal failure) persist and return without routing through
+        finalization, and therefore do not currently emit this hook. Treat it
+        as a best-effort post-turn observation for completed turns, not a
+        guaranteed callback for every possible early exit; unifying all
+        terminal paths behind one finalization seam is a separate follow-up.
+
+        Together the two hooks remove the need to abuse ``should_compress()`` /
+        ``compress()`` as a generic per-turn callback just to observe history,
+        and they cover the case where a turn finishes and there may be no next
+        request from which to infer the previous turn.
+
+        ``messages`` is a shallow copy and should be treated as read-only:
+        return values are ignored and this hook must not rely on transcript
+        mutation for persistence. ``kwargs`` may include ``turn_id``,
+        ``task_id``, ``api_call_count``, ``interrupted``, ``failed``, and
+        ``turn_exit_reason``.
+
+        ``usage`` carries the completed turn's canonical token usage (the same
+        dict shape passed to ``update_from_response`` — ``prompt_tokens`` /
+        ``completion_tokens`` / ``total_tokens`` plus the canonical
+        ``input_tokens`` / ``output_tokens`` / ``cache_read_tokens`` /
+        ``cache_write_tokens`` / ``reasoning_tokens`` buckets) so an engine can
+        weigh how large/expensive the selected context actually was when
+        deciding the next ``select_context()``. It is ``None`` on finalized
+        turns that never reached a provider response (e.g. interrupt); engines
+        must treat it as optional.
+
+        Default is a no-op.
+        """
+        return None
+
     # -- Optional: pre-flight check ----------------------------------------
 
     def should_compress_preflight(self, messages: List[Dict[str, Any]]) -> bool:
diff --git a/agent/context_references.py b/agent/context_references.py
index eea16ae52b4..8981aa472f5 100644
--- a/agent/context_references.py
+++ b/agent/context_references.py
@@ -19,6 +19,7 @@ REFERENCE_PATTERN = re.compile(
     rf"(?<![\w/])@(?:(?P<simple>diff|staged)\b|(?P<kind>file|folder|git|url):(?P<value>{_QUOTED_REFERENCE_VALUE}(?::\d+(?:-\d+)?)?|\S+))"
 )
 TRAILING_PUNCTUATION = ",.;!?"
+_NEEDS_QUOTING = re.compile(r"""[\s()\[\]{}<>"'`]""")
 _SENSITIVE_HOME_DIRS = (".ssh", ".aws", ".gnupg", ".kube", ".docker", ".azure", ".config/gh")
 _SENSITIVE_HERMES_DIRS = (Path("skills") / ".hub",)
 _SENSITIVE_HOME_FILES = (
@@ -60,6 +61,21 @@ class ContextReferenceResult:
     blocked: bool = False
 
 
+def format_reference_value(value: str) -> str:
+    """Quote a reference value so ``REFERENCE_PATTERN`` reads it back whole.
+
+    The unquoted alternative in the pattern is ``\\S+``, so a path containing a
+    space parses as a truncated ref with the tail left behind as loose text.
+    Mirrors ``formatRefValue`` in the desktop's directive-text.tsx.
+    """
+    if not _NEEDS_QUOTING.search(value):
+        return value
+    for quote in ("`", '"', "'"):
+        if quote not in value:
+            return f"{quote}{value}{quote}"
+    return value
+
+
 def parse_context_references(message: str) -> list[ContextReference]:
     refs: list[ContextReference] = []
     if not message:
@@ -308,7 +324,7 @@ def _expand_git_reference(
             ["git", *args],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=30,
             stdin=subprocess.DEVNULL,
             **_popen_kwargs,
@@ -534,7 +550,7 @@ def _rg_files(path: Path, cwd: Path, limit: int) -> list[Path] | None:
             ["rg", "--files", str(path.relative_to(cwd))],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
             stdin=subprocess.DEVNULL,
             **_popen_kwargs,
diff --git a/agent/conversation_compression.py b/agent/conversation_compression.py
index b2357d26be5..d2df6f25a39 100644
--- a/agent/conversation_compression.py
+++ b/agent/conversation_compression.py
@@ -40,7 +40,7 @@ import uuid
 import threading
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 
 from agent.context_engine import (
     automatic_compaction_status_message,
@@ -221,6 +221,25 @@ class CompressionCommitFence:
         self._lock = threading.Lock()
         self._cancelled = False
         self._commit_started = False
+        # Forward-progress telemetry: the compression worker touches this
+        # whenever the streamed summary call produces a token (see
+        # ContextCompressor._call_summary_llm). Waiters use it to distinguish
+        # a SLOW-but-alive summary model from a HUNG one, so slow models are
+        # not killed by a fixed wall-clock deadline while tokens are moving.
+        self._last_progress = time.monotonic()
+
+    def touch_progress(self) -> None:
+        """Record forward progress (e.g. a streamed summary token arriving).
+
+        Called from the compression worker thread; read by async waiters via
+        :meth:`seconds_since_progress`. A bare float store is atomic in
+        CPython, so no lock is needed.
+        """
+        self._last_progress = time.monotonic()
+
+    def seconds_since_progress(self) -> float:
+        """Seconds since the worker last reported forward progress."""
+        return max(0.0, time.monotonic() - self._last_progress)
 
     def cancel_before_commit(self) -> bool:
         """Cancel a pending commit, or wait for an active commit to finish.
@@ -355,6 +374,143 @@ def _emit_compression_attempt_telemetry(
         logger.debug("failed to emit compression attempt telemetry: %s", exc)
 
 
+def compression_skipped_due_to_lock(agent: Any) -> bool:
+    """Type-pinned read of the #69870 lock-skip signal.
+
+    ``agent._compression_skipped_due_to_lock`` is set by ``compress_context``
+    when a compression pass no-ops because another path holds the per-session
+    compression lock (holder string when the holder was confirmed, ``True``
+    otherwise) and cleared to ``None`` at the entry of every call.
+
+    The read MUST be type-pinned (``is True or isinstance(x, str)``), never
+    bare truthiness: MagicMock test-double agents auto-create truthy
+    attributes, and a bare ``if getattr(agent, ...)`` would hijack every
+    mocked agent in sibling suites into the lock-skip branch (the
+    #69870 × #69840 type-ahead incident).
+    """
+    _sig = getattr(agent, "_compression_skipped_due_to_lock", None)
+    return _sig is True or isinstance(_sig, str)
+
+
+def _adopt_live_compression_child(
+    agent: Any,
+    session_db: Any,
+    parent_session_id: str,
+) -> Optional[List[Dict[str, Any]]]:
+    """Move a stale compression contender onto the unique durable child.
+
+    Resolve and load first, then mutate the live agent. This ordering keeps the
+    stale contender fail-closed when lineage is ambiguous or the compacted
+    handoff cannot be read.
+    """
+    finder = getattr(type(session_db), "find_live_compression_child", None)
+    loader = getattr(type(session_db), "get_messages_as_conversation", None)
+    if not callable(finder) or not callable(loader):
+        return None
+    child = finder(session_db, parent_session_id)
+    if not child or not child.get("id"):
+        return None
+    child_session_id = str(child["id"])
+    recovered = loader(session_db, child_session_id)
+    if not isinstance(recovered, list) or not recovered:
+        return None
+    # Revalidate after loading: the child may have rotated or a competing
+    # continuation may have appeared between the two DB reads.
+    confirmed = finder(session_db, parent_session_id)
+    if not confirmed or str(confirmed.get("id") or "") != child_session_id:
+        return None
+
+    agent.session_id = child_session_id
+    try:
+        from gateway.session_context import set_current_session_id
+
+        set_current_session_id(child_session_id)
+    except Exception:
+        os.environ["HERMES_SESSION_ID"] = child_session_id
+    try:
+        from hermes_logging import set_session_context
+
+        set_session_context(child_session_id)
+    except Exception:
+        pass
+
+    agent._session_db_created = True
+    if child.get("system_prompt"):
+        agent._cached_system_prompt = child["system_prompt"]
+    agent._last_flushed_db_idx = len(recovered)
+    agent._flushed_db_message_session_id = child_session_id
+    agent._flushed_db_message_ids = {
+        id(message) for message in recovered if isinstance(message, dict)
+    }
+
+    on_session_start = getattr(agent.context_compressor, "on_session_start", None)
+    if callable(on_session_start):
+        try:
+            on_session_start(
+                child_session_id,
+                boundary_reason="compression",
+                old_session_id=parent_session_id,
+                session_db=session_db,
+                platform=getattr(agent, "platform", None) or "cli",
+                conversation_id=getattr(agent, "_gateway_session_key", None),
+            )
+        except Exception as exc:
+            logger.debug("context engine compression-child adoption failed: %s", exc)
+    else:
+        bind_state = getattr(agent.context_compressor, "bind_session_state", None)
+        if callable(bind_state):
+            try:
+                bind_state(session_db=session_db, session_id=child_session_id)
+            except Exception:
+                pass
+    try:
+        if agent._memory_manager:
+            agent._memory_manager.on_session_switch(
+                child_session_id,
+                parent_session_id=parent_session_id,
+                reset=False,
+                reason="compression",
+            )
+    except Exception as exc:
+        logger.debug("memory manager compression-child adoption failed: %s", exc)
+
+    return recovered
+
+
+def recover_rotated_compression_session(
+    agent: Any,
+) -> Optional[List[Dict[str, Any]]]:
+    """Recover a stale live agent before a new turn writes to its old parent."""
+    session_db = getattr(agent, "_session_db", None)
+    session_id = getattr(agent, "session_id", None) or ""
+    if session_db is None or not session_id:
+        return None
+    try:
+        if not _session_was_rotated_by_compression(session_db, session_id):
+            return None
+        # Rotation publication holds the parent compression lease until the
+        # child handoff is durable. A concurrent turn waits briefly rather than
+        # observing the intentional parent-ended/child-empty intermediate state.
+        holder_getter = getattr(session_db, "get_compression_lock_holder", None)
+        for attempt in range(21):
+            recovered = _adopt_live_compression_child(agent, session_db, session_id)
+            if recovered is not None:
+                return recovered
+            holder = holder_getter(session_id) if callable(holder_getter) else None
+            if not holder or attempt == 20:
+                return None
+            time.sleep(0.05)
+        return None
+    except Exception as exc:
+        logger.warning(
+            "compression session recovery failed for session=%s (%s: %s)",
+            session_id,
+            type(exc).__name__,
+            exc,
+        )
+        return None
+
+
 def _compression_lock_holder(agent: Any) -> str:
     """Build a unique holder id for the lock: pid:tid:agent-instance:uuid.
 
@@ -515,7 +671,17 @@ class _CompressionLockLeaseRefresher:
         # by the TTL the acquirer set — the lock can never be held past its TTL
         # by a stuck refresher.
         consecutive_failures = 0
-        while not self._stop.wait(self._refresh_interval_seconds):
+        # First refresh happens immediately, not one interval late. Everything
+        # between try_acquire() and start() (the rotation-ownership lookup, the
+        # durable-breaker re-read, thread startup) is charged against the very
+        # first lease, so on a short TTL under load the lock could already be
+        # expired — and reclaimable by a competing path — before tick #1.
+        first = True
+        while first or not self._stop.wait(self._refresh_interval_seconds):
+            if first:
+                first = False
+                if self._stop.is_set():
+                    break
             try:
                 refreshed = self._db.refresh_compression_lock(
                     self._session_id,
@@ -874,6 +1040,7 @@ _SYNTHETIC_USER_FLAGS = (
     "_empty_recovery_synthetic",
     "_verification_stop_synthetic",
     "_pre_verify_synthetic",
+    "_dropped_toolcall_nudge",
 )
 
 
@@ -1143,6 +1310,14 @@ def compress_context(
     # boundary, so the previous flush baseline remains authoritative.
     agent._last_compression_attempt_recorded = True
     agent._last_compression_attempt_in_place = None
+    # Clear the lock-skip signal at the VERY TOP, before the codex route and
+    # the breaker gates below can early-return (per-attempt state rule,
+    # #58630/#69853). A stale ``True``/holder value from a prior lock-skip
+    # must never make a later breaker/codex no-op look like lock contention
+    # to the automatic-path consumers (compression_deferred, #49874) — the
+    # second clear before lock acquisition below stays for the same reason
+    # it was added in #69870 and is simply idempotent now.
+    agent._compression_skipped_due_to_lock = None
 
     _attempt_started_at = time.monotonic()
     _attempt_id = uuid.uuid4().hex
@@ -1226,7 +1401,7 @@ def compress_context(
     # parent_session_id child, no
     # `name #N` renumber, no contextvar/env/logging re-sync, no memory/context-
     # engine session-switch. The conversation keeps one durable id for life,
-    # eliminating the session-rotation bug cluster. Default False during rollout.
+    # eliminating the session-rotation bug cluster. Default True (2107b86024).
     in_place = bool(getattr(agent, "compression_in_place", False))
     # Set True once the in-place DB write actually completes (the DB block can
     # raise and skip it). Surfaced to the gateway via agent._last_compaction_in_place.
@@ -1434,6 +1609,8 @@ def compress_context(
         if _lock_released:
             return
         _lock_released = True
+        if getattr(agent, "_active_compression_lock_holder", None) == _lock_holder:
+            agent._active_compression_lock_holder = None
         if _lock_refresher is not None:
             try:
                 _lock_refresher.stop()
@@ -1445,6 +1622,9 @@ def compress_context(
             except Exception as _rel_err:
                 logger.debug("compression lock release failed: %s", _rel_err)
 
+    if _lock_holder is not None:
+        agent._active_compression_lock_holder = _lock_holder
+
     # A delayed contender can acquire the parent lock after the winning path
     # has released it and completed rotation. The lock serializes work but does
     # not by itself prove that this stale agent still owns a live parent.
@@ -1467,15 +1647,25 @@ def compress_context(
                 _existing_sp = agent._build_system_prompt(system_message)
             return messages, _existing_sp
         if _parent_already_rotated:
-            logger.info(
-                "compression skipped: session=%s was already rotated by "
-                "another compression path",
-                _lock_sid,
+            recovered_messages = _adopt_live_compression_child(
+                agent, _lock_db, _lock_sid
             )
             _release_lock()
             _existing_sp = getattr(agent, "_cached_system_prompt", None)
             if not _existing_sp:
                 _existing_sp = agent._build_system_prompt(system_message)
+            if recovered_messages is not None:
+                logger.warning(
+                    "compression recovery: stale session=%s adopted live child=%s",
+                    _lock_sid,
+                    agent.session_id,
+                )
+                return recovered_messages, _existing_sp
+            logger.warning(
+                "compression skipped: session=%s was already rotated by "
+                "another compression path, but no unique live child could be adopted",
+                _lock_sid,
+            )
             return messages, _existing_sp
 
     # The agent may have been constructed before another path completed an
@@ -1509,6 +1699,37 @@ def compress_context(
             )
             _lock_refresher.start()
 
+        # The caller's history snapshot predates lease acquisition. Reload the
+        # durable parent after the lease is live; MORE durable rows than the
+        # snapshot carries means a frontend/background writer committed a turn
+        # in that window, so publishing from this snapshot would omit it.
+        # Deliberately a LENGTH check, not content equality: in-memory
+        # mutation of past turns is legal (multimodal compression, retry
+        # history replacement, think-tag stripping), and a content-equality
+        # abort would permanently wedge compression on such sessions — the
+        # #14694 failure shape.
+        # Rotation-only: in-place compaction (archive_and_compact) is
+        # non-destructive — pre-compaction rows are soft-archived (active=0,
+        # compacted=1), stay searchable and recoverable, so snapshot/durable
+        # drift cannot lose data there and must not abort compaction.
+        if not in_place and _lock_db is not None and _lock_sid:
+            durable_loader = getattr(
+                type(_lock_db), "get_messages_as_conversation", None
+            )
+            if callable(durable_loader):
+                durable_parent = durable_loader(_lock_db, _lock_sid)
+                if isinstance(durable_parent, list) and len(durable_parent) > len(messages):
+                    logger.warning(
+                        "compression aborted: session=%s changed before lease "
+                        "acquisition; preserving newer durable messages",
+                        _lock_sid,
+                    )
+                    _release_lock()
+                    existing_prompt = getattr(agent, "_cached_system_prompt", None)
+                    if not existing_prompt:
+                        existing_prompt = agent._build_system_prompt(system_message)
+                    return messages, existing_prompt
+
         # Notify external memory provider before compression discards context.
         # The provider's on_pre_compress() may return a string of insights it
         # wants surfaced inside the compression summary; capture and forward it
@@ -1549,7 +1770,29 @@ def compress_context(
 
         messages_before_compression = copy.deepcopy(messages)
         _activity_heartbeat = _CompressionActivityHeartbeat(agent).start()
-        compressed = compress_fn(messages, **compress_kwargs)
+        # Publish forward progress to the commit fence while the summary LLM
+        # call streams. Async hosts (gateway session hygiene) poll
+        # ``commit_fence.seconds_since_progress()`` to extend their deadline
+        # while tokens are moving — so a SLOW summary model is only killed
+        # when it is actually silent, not merely thorough. The hook is
+        # thread-local and the compress call is synchronous on this thread,
+        # so it cannot leak into unrelated auxiliary calls.
+        #
+        # Fenceless callers (CLI /compress, in-loop auto-compress) install a
+        # no-op hook: nobody polls their progress, but an ACTIVE hook is what
+        # switches the summary call onto the streamed path — giving every
+        # compression path the same two guarantees: the configured timeout
+        # acts on inactivity (slow models finish), and a byte-trickling
+        # provider that keeps the connection alive forever is cut off at the
+        # streamed total ceiling (see _aux_stream_total_ceiling) instead of
+        # outliving the SDK's inactivity timeout indefinitely.
+        from agent.auxiliary_client import aux_progress_hook
+        _progress_hook = (
+            commit_fence.touch_progress if commit_fence is not None
+            else (lambda: None)
+        )
+        with aux_progress_hook(_progress_hook):
+            compressed = compress_fn(messages, **compress_kwargs)
     except BaseException as _compress_exc:
         # ANY exception after lock acquisition — memory hook, capability
         # inspection, engine lookup, or compress() — must release the lock so
@@ -1777,6 +2020,21 @@ def compress_context(
         ):
             new_system_prompt = cached_system_prompt
             agent._cached_system_prompt = cached_system_prompt
+            # _invalidate_system_prompt() above also cleared the
+            # cross-session-stable prefix marker boundary. The kept prompt
+            # is byte-identical, so reconstruct the stable tier and reuse
+            # it ONLY when the kept prompt still literally starts with it
+            # (same startswith gate as the restore path); otherwise the
+            # request layer falls back to the legacy single-breakpoint
+            # layout with the prompt bytes untouched.
+            try:
+                from agent.system_prompt import build_system_prompt_parts as _build_parts
+
+                _static = _build_parts(agent, system_message=system_message)["stable"]
+                if _static and cached_system_prompt.startswith(_static):
+                    agent._cached_system_prompt_static = _static
+            except Exception:
+                pass
         else:
             new_system_prompt = agent._build_system_prompt(system_message)
             agent._cached_system_prompt = new_system_prompt
@@ -1853,81 +2111,54 @@ def compress_context(
                         )
                     except Exception:
                         pass  # best-effort — don't block compression on a flush error
-                    # Propagate title to the new session with auto-numbering
+                    # Publish parent closure + child row + compacted handoff in
+                    # one transaction. No reader can observe a missing/empty child.
+                    # The rotation child must stay on the parent's profile —
+                    # mirror _ensure_db_session's stamp ("default" persists as
+                    # NULL). publish_compression_child additionally COALESCEs
+                    # from the parent row, covering app-global remote sessions
+                    # whose thread lacks the HERMES_HOME context.
+                    try:
+                        from hermes_cli.profiles import get_active_profile_name
+
+                        _profile_for_child = get_active_profile_name()
+                        if _profile_for_child == "default":
+                            _profile_for_child = None
+                    except Exception:
+                        _profile_for_child = None
                     old_title = agent._session_db.get_session_title(agent.session_id)
-                    agent._session_db.end_session(agent.session_id, "compression")
                     old_session_id = agent.session_id
-                    agent.session_id = f"{datetime.now().strftime('%Y%m%d_%H%M%S')}_{uuid.uuid4().hex[:6]}"
-                    # Ordering contract: the agent thread updates the contextvar here;
-                    # the gateway propagates to SessionEntry after run_in_executor returns.
+                    new_session_id = (
+                        f"{datetime.now().strftime('%Y%m%d_%H%M%S')}_"
+                        f"{uuid.uuid4().hex[:6]}"
+                    )
+                    agent._session_db.publish_compression_child(
+                        parent_session_id=old_session_id,
+                        child_session_id=new_session_id,
+                        source=agent.platform
+                        or os.environ.get("HERMES_SESSION_SOURCE", "cli"),
+                        model=agent.model,
+                        model_config=agent._session_init_model_config,
+                        system_prompt=new_system_prompt,
+                        messages=compressed,
+                        cwd=getattr(agent, "working_directory", None),
+                        profile_name=_profile_for_child,
+                        compression_lock_holder=_lock_holder,
+                        require_compression_lease=_lock_holder is not None,
+                    )
+                    agent.session_id = new_session_id
                     try:
                         from gateway.session_context import set_current_session_id
 
                         set_current_session_id(agent.session_id)
                     except Exception:
                         os.environ["HERMES_SESSION_ID"] = agent.session_id
-                    # The gateway/tools session context (ContextVar + env) and the
-                    # logging session context are SEPARATE mechanisms. The call above
-                    # moves the former; the ``[session_id]`` tag on log lines comes
-                    # from ``hermes_logging._session_context`` (set once per turn in
-                    # conversation_loop.py). Without this, post-rotation log lines in
-                    # the same turn keep the STALE old id while the message/DB/gateway
-                    # state carry the new one — breaking log correlation exactly at the
-                    # compaction boundary (see #34089). Guarded separately so a logging
-                    # failure can never regress the routing update above.
                     try:
                         from hermes_logging import set_session_context
 
                         set_session_context(agent.session_id)
                     except Exception:
                         pass
-                    agent._session_db_created = False
-                    try:
-                        agent._session_db.create_session(
-                            session_id=agent.session_id,
-                            source=agent.platform or os.environ.get("HERMES_SESSION_SOURCE", "cli"),
-                            model=agent.model,
-                            model_config=agent._session_init_model_config,
-                            parent_session_id=old_session_id,
-                        )
-                    except Exception as _cs_err:
-                        # The child row could not be created (e.g. FK constraint,
-                        # contended write). Previously the outer handler simply
-                        # warned and let the agent continue on the NEW id — which
-                        # has no row in state.db, producing an orphan: the parent
-                        # is ended, the child is never indexed, and every
-                        # subsequent message is attributed to a session that
-                        # doesn't exist (#33906/#33907). Roll the live id back to
-                        # the parent so the conversation stays attached to a real,
-                        # indexed session instead of a phantom.
-                        logger.warning(
-                            "Compression child session create failed (%s) — "
-                            "rolling back to parent session %s to avoid an orphan.",
-                            _cs_err, old_session_id,
-                        )
-                        agent.session_id = old_session_id
-                        try:
-                            from gateway.session_context import set_current_session_id
-                            set_current_session_id(agent.session_id)
-                        except Exception:
-                            os.environ["HERMES_SESSION_ID"] = agent.session_id
-                        try:
-                            from hermes_logging import set_session_context
-                            set_session_context(agent.session_id)
-                        except Exception:
-                            pass
-                        # Re-open the parent: it was ended above, but we're
-                        # continuing on it, so it must not stay closed.
-                        try:
-                            agent._session_db.reopen_session(old_session_id)
-                        except Exception:
-                            pass
-                        old_session_id = None  # no rotation happened
-                        # The parent row already exists in state.db, so mark the
-                        # session as created — _ensure_db_session would otherwise
-                        # retry a (harmless INSERT OR IGNORE) create next turn.
-                        agent._session_db_created = True
-                        raise
                     agent._session_db_created = True
                     split_status = "rotated_committed"
                     # Carry a persistent /goal onto the continuation session.
@@ -1947,18 +2178,14 @@ def compress_context(
                         except (ValueError, Exception) as e:
                             logger.debug("Could not propagate title on compression: %s", e)
 
-                # Shared post-write steps (both modes target agent.session_id, which
-                # in-place keeps and rotation has already reassigned to the new id):
-                # refresh the stored system prompt and reset the flush cursor so the
-                # next turn re-bases its append diff.
-                agent._session_db.update_system_prompt(agent.session_id, new_system_prompt)
+                # In-place mode still updates/replaces the current row here.
+                # Rotation already published prompt + compacted handoff atomically.
                 if in_place:
+                    agent._session_db.update_system_prompt(
+                        agent.session_id, new_system_prompt
+                    )
                     agent._last_flushed_db_idx = 0
                 else:
-                    # A headless turn can be killed before its finalizer. Persist
-                    # the rotated child's compacted handoff at the boundary so
-                    # the new session is immediately resumable.
-                    agent._session_db.replace_messages(agent.session_id, compressed)
                     agent._last_flushed_db_idx = len(compressed)
                     agent._flushed_db_message_session_id = agent.session_id
                     agent._flushed_db_message_ids = {
@@ -1968,7 +2195,22 @@ def compress_context(
                     }
                 _session_commit_succeeded = True
             except Exception as e:
-                split_status = "aborted" if locals().get("old_session_id") is None and not in_place else "failed_not_indexed"
+                if (
+                    not in_place
+                    and locals().get("old_session_id")
+                    and agent.session_id == old_session_id
+                ):
+                    # Atomic publication failed (including lease loss): keep the
+                    # parent live and discard the stale compacted snapshot.
+                    old_session_id = None
+                    messages[:] = copy.deepcopy(messages_before_compression)
+                    compressed = messages
+                    _compression_made_progress = False
+                split_status = (
+                    "aborted"
+                    if locals().get("old_session_id") is None and not in_place
+                    else "failed_not_indexed"
+                )
                 # If the rotation rolled back to the parent (orphan-avoidance
                 # above), agent.session_id is the still-indexed parent and
                 # old_session_id was cleared — so this is recovery, not an
diff --git a/agent/conversation_loop.py b/agent/conversation_loop.py
index d952f092795..fb3d7978b93 100644
--- a/agent/conversation_loop.py
+++ b/agent/conversation_loop.py
@@ -34,6 +34,7 @@ from agent.conversation_compression import (
     COMPRESSION_RETRY_TOKENS_STATUS_TEMPLATE,
     COMPRESSION_RETRY_TOO_LARGE_STATUS_TEMPLATE,
     PRE_API_COMPRESSION_STATUS_TEMPLATE,
+    compression_skipped_due_to_lock,
     conversation_history_after_compression,
 )
 from agent.context_engine import automatic_compaction_status_message
@@ -47,6 +48,7 @@ from agent.turn_context import (
     reanchor_current_turn_user_idx,
 )
 from agent.turn_retry_state import TurnRetryState
+from agent.runtime_cwd import resolve_agent_cwd
 from agent.message_sanitization import (
     close_interrupted_tool_sequence,
     _repair_tool_call_arguments,
@@ -435,6 +437,37 @@ def _restore_or_build_system_prompt(agent, system_message, conversation_history)
         # Continuing session — reuse the exact system prompt from the
         # previous turn so the Anthropic cache prefix matches.
         agent._cached_system_prompt = stored_prompt
+        # Reconstruct the cross-session-stable prefix for the early cache
+        # breakpoint. The static prefix is not persisted (only the full
+        # prompt is), so gateway surfaces that build a fresh AIAgent per
+        # turn would otherwise lose the two-block system layout after the
+        # first turn — flip-flopping the wire shape mid-conversation and
+        # silently degrading to the legacy single-breakpoint layout.
+        #
+        # Safety: the rebuilt stable tier is used ONLY when the restored
+        # prompt literally starts with it (checked here AND re-checked by
+        # ``_apply_system_cache_markers``'s ``startswith`` gate). If any
+        # stable-tier input changed since the prompt was persisted (skills
+        # edited, identity changed), the prefix mismatches, ``_static``
+        # stays None, and the request falls back to the legacy layout with
+        # the restored prompt bytes untouched — never a rewritten prompt.
+        #
+        # Gated on ``_use_prompt_caching`` so non-Anthropic routes skip the
+        # rebuild entirely (the static prefix is only consumed by
+        # ``apply_anthropic_cache_control``).
+        if getattr(agent, "_use_prompt_caching", False):
+            try:
+                from agent.system_prompt import build_system_prompt_parts as _build_parts
+
+                _static = _build_parts(agent, system_message=system_message)["stable"]
+                if _static and stored_prompt.startswith(_static):
+                    agent._cached_system_prompt_static = _static
+            except Exception:
+                # Fail-open: restore continues with the legacy cache layout.
+                logger.debug(
+                    "static system-prefix reconstruction failed on restore",
+                    exc_info=True,
+                )
         return
     if stored_prompt:
         stored_state = "stale_runtime"
@@ -507,9 +540,17 @@ def _restore_or_build_system_prompt(agent, system_message, conversation_history)
 
 
 def _stored_prompt_matches_runtime(agent, prompt: str) -> bool:
-    """Return False when the persisted Model/Provider lines are stale."""
+    """Return False when the persisted runtime-identity lines are stale."""
 
     def line_value(label: str) -> str:
+        """Last matching line wins.
+
+        Safe ONLY for fields emitted in the volatile tier at the very END of
+        the prompt (Model / Provider / Platform). User-supplied project
+        context (AGENTS.md / CLAUDE.md / .cursorrules) is embedded in the
+        middle context tier, so a last-match scan lets project prose shadow
+        any field emitted EARLIER — see ``host_info_value``.
+        """
         prefix = f"{label}:"
         value = ""
         for line in prompt.splitlines():
@@ -517,6 +558,32 @@ def _stored_prompt_matches_runtime(agent, prompt: str) -> bool:
                 value = line[len(prefix):].strip()
         return value
 
+    def host_info_value(label: str) -> str:
+        """Read a field from the prompt's own host-info block.
+
+        The host-info block (``build_environment_hints``) sits in the STABLE
+        tier, ahead of the embedded project context files. A bare scan of the
+        whole prompt would therefore match a user's ``AGENTS.md`` that merely
+        contains a line starting with the same label, comparing runtime state
+        against project prose. That mismatch never clears, so the check would
+        reject the stored prompt on EVERY turn — rebuilding the system prompt
+        each message and destroying the prefix cache for the whole session,
+        which is far worse than the staleness this function guards against.
+
+        Anchor on the ``User home directory:`` line that immediately precedes
+        the working-directory line in that block, and take the FIRST such
+        occurrence, so only Hermes' own emitted block can satisfy the read.
+        """
+        prefix = f"{label}:"
+        lines = prompt.splitlines()
+        for idx, line in enumerate(lines):
+            if not line.startswith("User home directory:"):
+                continue
+            for candidate in lines[idx + 1: idx + 4]:
+                if candidate.startswith(prefix):
+                    return candidate[len(prefix):].strip()
+        return ""
+
     stored_model = line_value("Model")
     current_model = str(getattr(agent, "model", "") or "").strip()
     if stored_model and current_model and stored_model != current_model:
@@ -527,6 +594,24 @@ def _stored_prompt_matches_runtime(agent, prompt: str) -> bool:
     if stored_provider and current_provider and stored_provider != current_provider:
         return False
 
+    # Detect cwd drift: if the stored prompt was built in a different working
+    # directory, reuse would silently inject a stale path into the prefix cache.
+    # Compare against resolve_agent_cwd() — the SAME resolver used to build the
+    # prompt — so gateway/TUI sessions that set TERMINAL_CWD are not falsely
+    # rejected (they would always differ from the launch dir's os.getcwd()).
+    stored_cwd = host_info_value("Current working directory")
+    if stored_cwd:
+        if stored_cwd != str(resolve_agent_cwd()):
+            return False
+
+    # Detect runtime-surface drift: the stored prompt records which platform it
+    # was built for (e.g. "desktop" vs "cli"). Reusing a desktop-built prompt on
+    # a terminal session (or vice versa) would inject the wrong runtime hints.
+    stored_platform = line_value("Platform")
+    current_platform = str(getattr(agent, "platform", "") or "").strip()
+    if stored_platform and current_platform and stored_platform != current_platform:
+        return False
+
     return True
 
 
@@ -640,6 +725,55 @@ def _content_policy_blocked_result(
     }
 
 
+def _compression_deferred_result(
+    agent,
+    messages: List[Dict],
+    api_call_count: int,
+) -> Dict[str, Any]:
+    """Build the soft turn result for a lock-contended compression defer.
+
+    Another path (a sibling turn, a background review fork, a manual
+    ``/compress``) holds this session's compression lock, so every
+    compression pass this turn no-oped and the request still does not fit.
+    This is a TEMPORARY condition — the lock winner is actively shrinking
+    the same session — so the turn must end as a soft defer
+    (``compression_deferred``), never as ``compression_exhausted``: the
+    gateway auto-resets (wipes) the session on exhaustion (#9893/#35809),
+    which would destroy a session that the concurrent compressor is about
+    to make healthy again.
+
+    ``failed`` stays False so the gateway persists the user turn (transient
+    branch) and retry-next-message semantics apply.
+    """
+    holder = getattr(agent, "_compression_skipped_due_to_lock", None)
+    logger.info(
+        "turn deferred: compression lock held by another path "
+        "(session=%s holder=%s) — not counting as compression exhaustion",
+        agent.session_id or "none",
+        holder if isinstance(holder, str) else "unconfirmed",
+    )
+    try:
+        agent._flush_status_buffer()
+    except Exception:
+        pass
+    _final = (
+        "Context compression is already running for this session. "
+        "Please retry in a moment — your next message will be processed "
+        "once the concurrent compression finishes."
+    )
+    return {
+        "final_response": _final,
+        "messages": messages,
+        "completed": False,
+        "api_calls": api_call_count,
+        "error": _final,
+        "partial": True,
+        "failed": False,
+        "compression_deferred": True,
+        "session_id": agent.session_id,
+    }
+
+
 def _sync_failover_system_message(agent, api_messages, active_system_prompt):
     """Refresh the in-flight system message after a provider failover.
 
@@ -666,6 +800,136 @@ def _sync_failover_system_message(agent, api_messages, active_system_prompt):
     return sp
 
 
+def _apply_context_engine_selection(
+    agent: Any,
+    api_messages: List[Dict[str, Any]],
+    conversation_messages: List[Dict[str, Any]],
+    incoming_message: Optional[Dict[str, Any]],
+    *,
+    logger: Any,
+) -> List[Dict[str, Any]]:
+    """Run the optional per-turn ``ContextEngine.select_context()`` hook.
+
+    Returns the (possibly replaced) request message list. The hook is for
+    context *selection / routing* (retrieval, topic routing, role switching),
+    which is distinct from compression and fires every turn independent of
+    ``should_compress()``.
+
+    Fail-open by design: a missing hook, any exception, or an invalid return
+    value yields the unmodified ``api_messages``. The result is request-only —
+    persisted conversation history is never mutated here.
+    """
+    engine = getattr(agent, "context_compressor", None)
+    if engine is None or not hasattr(engine, "select_context"):
+        return api_messages
+
+    # Skip the no-op base implementation so non-implementing engines —
+    # including the built-in ContextCompressor — pay nothing per request:
+    # no history copies below, no call. ``hasattr`` alone is not enough,
+    # because the ABC defines a default ``select_context`` that every engine
+    # inherits. Mirrors the base-method short-circuit in
+    # ``_notify_context_engine_turn_complete``. Lazy import avoids any import
+    # cycle with agent.context_engine.
+    try:
+        from agent.context_engine import ContextEngine as _CE
+        if getattr(engine.select_context, "__func__", None) is _CE.select_context:
+            return api_messages
+    except Exception:
+        pass
+
+    session_label = getattr(agent, "session_id", None) or "-"
+    # Pass shallow copies of the reference-only inputs so an engine that
+    # mutates them in place cannot alter persisted transcript state. Only
+    # ``request_messages`` (the per-call request list) is meant to be acted on,
+    # and it may be replaced wholesale via the return value — never mutated in
+    # place either. ``conversation_messages`` / ``incoming_message`` are
+    # read-only context; copying enforces the request-only contract rather than
+    # merely documenting it.
+    _conv_copy = [dict(m) if isinstance(m, dict) else m for m in conversation_messages] \
+        if conversation_messages is not None else None
+    _incoming_copy = dict(incoming_message) if isinstance(incoming_message, dict) else incoming_message
+    try:
+        selected = engine.select_context(
+            api_messages,
+            conversation_messages=_conv_copy,
+            incoming_message=_incoming_copy,
+            budget_tokens=getattr(engine, "context_length", 0) or 0,
+        )
+    except Exception:
+        logger.warning(
+            "Context engine select_context hook failed; using unmodified "
+            "request messages (session=%s)",
+            session_label,
+            exc_info=True,
+        )
+        return api_messages
+
+    if selected is None:
+        return api_messages
+    # Require a NON-EMPTY list of dicts. An empty list must fall open to the
+    # original request: ``all([])`` is ``True``, so without the emptiness check
+    # a ``[]`` returned by a buggy/failing engine would replace a valid request
+    # with an empty message list that the downstream sanitizers cannot restore,
+    # reaching the provider as an invalid request instead of failing open.
+    if isinstance(selected, list) and selected and all(isinstance(m, dict) for m in selected):
+        return selected
+
+    logger.warning(
+        "Context engine select_context returned an invalid value "
+        "(not a non-empty list of dicts); ignoring (session=%s)",
+        session_label,
+    )
+    return api_messages
+
+
+def _notify_context_engine_turn_complete(
+    agent: Any,
+    messages: List[Dict[str, Any]],
+    *,
+    usage: Optional[Dict[str, Any]] = None,
+    logger: Any,
+    **meta: Any,
+) -> None:
+    """Notify the active context engine that a user turn has finished.
+
+    Calls the optional ``ContextEngine.on_turn_complete()`` observation hook
+    once per turn, after the assistant/tool loop has produced the finalized
+    transcript. The complement to ``select_context()`` (pre-request selection):
+    this lets an engine ingest / index / summarize the completed turn.
+
+    Fail-open: a missing or no-op hook, or any exception, is swallowed.
+    ``messages`` is passed as a shallow copy so the engine cannot mutate the
+    persisted transcript.
+    """
+    engine = getattr(agent, "context_compressor", None)
+    hook = getattr(engine, "on_turn_complete", None)
+    if engine is None or not callable(hook):
+        return
+
+    # Skip the no-op base implementation so non-implementing engines (incl.
+    # the built-in compressor) pay nothing per turn. Lazy import avoids any
+    # import cycle with agent.context_engine.
+    try:
+        from agent.context_engine import ContextEngine as _CE
+        if getattr(hook, "__func__", None) is _CE.on_turn_complete:
+            return
+    except Exception:
+        pass
+
+    try:
+        hook(
+            [dict(m) if isinstance(m, dict) else m for m in messages],
+            usage=usage,
+            **meta,
+        )
+    except Exception:
+        logger.warning(
+            "Context engine on_turn_complete hook failed (session=%s)",
+            getattr(agent, "session_id", None) or "-",
+            exc_info=True,
+        )
+
+
 def run_conversation(
     agent,
     user_message: Any,
@@ -805,6 +1069,13 @@ def run_conversation(
     # over instead of spinning. Reset here so each turn starts fresh. See #26080.
     agent._auth_pool_refresh_counts = {}
 
+    # Reset the per-turn usage holder forwarded to the context engine's
+    # on_turn_complete() observation hook. Set after each successful provider
+    # response (see below); left as None on turns that never reach a response
+    # (early failure / interrupt) so the hook receives None rather than a
+    # stale prior turn's usage.
+    agent._last_turn_usage = None
+
     # Optional opt-in runtime: if api_mode == codex_app_server, hand the
     # turn to the codex app-server subprocess (terminal/file ops/patching
     # all run inside Codex). Default Hermes path is bypassed entirely.
@@ -1053,7 +1324,28 @@ def run_conversation(
             # Uses new dicts so the internal messages list retains the fields
             # for Codex Responses compatibility.
             if agent._should_sanitize_tool_calls():
-                agent._sanitize_tool_calls_for_strict_api(api_msg, model=agent.model)
+                # In MoA mode, agent.model is the virtual preset name
+                # (e.g. "closed"), not the actual aggregator model.  Use
+                # the resolved aggregator model so Gemini aggregators
+                # correctly preserve thought_signature (extra_content).
+                _sanitize_model = agent.model
+                if agent.provider == "moa":
+                    if moa_config:
+                        _agg = moa_config.get("aggregator") or {}
+                        if _agg.get("model"):
+                            _sanitize_model = _agg["model"]
+                    if _sanitize_model == agent.model:
+                        # Virtual-provider mode: no moa_config is threaded
+                        # through run_conversation — the facade resolves the
+                        # preset internally. Ask the facade for the resolved
+                        # aggregator slot from the previous create() instead
+                        # (set before any history replay that could carry
+                        # thought_signature).
+                        _moa_client = getattr(agent, "client", None)
+                        _agg_slot = getattr(_moa_client, "last_aggregator_slot", None)
+                        if _agg_slot and _agg_slot.get("model"):
+                            _sanitize_model = _agg_slot["model"]
+                agent._sanitize_tool_calls_for_strict_api(api_msg, model=_sanitize_model)
             # Keep 'reasoning_details' - OpenRouter uses this for multi-turn reasoning context
             # The signature field helps maintain reasoning continuity
             api_messages.append(api_msg)
@@ -1070,9 +1362,9 @@ def run_conversation(
         #
         # Hermes invariant: the system prompt is built ONCE per session
         # (cached on ``_cached_system_prompt``) and replayed verbatim on
-        # every turn.  We send it as a single content string so the
-        # bytes are byte-stable across turns and upstream prompt caches
-        # stay warm.
+        # every turn. ``apply_anthropic_cache_control`` may split its stable
+        # prefix into content blocks on the wire, but the stored string and
+        # its byte-stability remain unchanged.
         effective_system = active_system_prompt or ""
         if agent.ephemeral_system_prompt:
             effective_system = (effective_system + "\n\n" + agent.ephemeral_system_prompt).strip()
@@ -1099,7 +1391,18 @@ def run_conversation(
                     aggregator=moa_config.get("aggregator") or {},
                     temperature=_preset_temperature(moa_config, "reference_temperature"),
                     aggregator_temperature=_preset_temperature(moa_config, "aggregator_temperature"),
-                    max_tokens=moa_config.get("reference_max_tokens"),
+                    reference_max_tokens=moa_config.get("reference_max_tokens"),
+                    # None = no per-preset override; inherit
+                    # auxiliary.moa_reference.timeout via call_llm.
+                    reference_timeout=(
+                        float(moa_config["reference_timeout"])
+                        if moa_config.get("reference_timeout")
+                        else None
+                    ),
+                    degraded_reference_policy=str(
+                        moa_config.get("degraded_reference_policy") or "loud"
+                    ),
+                    agent=agent,
                 )
                 if _moa_context:
                     for _msg in reversed(api_messages):
@@ -1126,18 +1429,25 @@ def run_conversation(
             for idx, pfm in enumerate(agent.prefill_messages):
                 api_messages.insert(sys_offset + idx, pfm.copy())
 
-        # Apply Anthropic prompt caching for Claude models on native
-        # Anthropic, OpenRouter, and third-party Anthropic-compatible
-        # gateways. Auto-detected: if ``_use_prompt_caching`` is set,
-        # inject cache_control breakpoints (system + last 3 messages)
-        # to reduce input token costs by ~75% on multi-turn
-        # conversations.
-        if agent._use_prompt_caching:
-            api_messages = apply_anthropic_cache_control(
-                api_messages,
-                cache_ttl=agent._cache_ttl,
-                native_anthropic=agent._use_native_cache_layout,
-            )
+        # Per-turn context selection hook (additive, no-op by default).
+        # Lets a context engine select/replace which context enters the
+        # prompt for THIS call only — retrieval, topic routing, role/branch
+        # switching — distinct from compression and independent of
+        # should_compress(). Request-only: persisted history is untouched, so
+        # caching/sanitization below operate on whatever the engine selected.
+        # Fail-open (see _apply_context_engine_selection).
+        _sel_incoming = (
+            messages[current_turn_user_idx]
+            if 0 <= current_turn_user_idx < len(messages)
+            else None
+        )
+        api_messages = _apply_context_engine_selection(
+            agent,
+            api_messages,
+            messages,
+            _sel_incoming,
+            logger=request_logger,
+        )
 
         # Safety net: strip orphaned tool results / add stubs for missing
         # results before sending to the API.  Runs unconditionally — not
@@ -1197,6 +1507,39 @@ def run_conversation(
         # the OpenAI SDK. Sanitizing here prevents the 3-retry cycle.
         _sanitize_messages_surrogates(api_messages)
 
+        # Apply Anthropic prompt caching for Claude models on native
+        # Anthropic, OpenRouter, and third-party Anthropic-compatible
+        # gateways. Auto-detected: if ``_use_prompt_caching`` is set, inject
+        # cache_control breakpoints for the static system prefix, full system
+        # prompt, and last two messages (or the legacy system-and-3 layout
+        # when no static prefix is available).
+        #
+        # Runs LAST, after every message mutation above. Marking earlier
+        # defeats the prefix stability the mutations exist to create:
+        # ``_apply_cache_marker`` rewrites ``content`` from a plain string
+        # into a ``[{"type": "text", ...}]`` block, so the marked messages
+        # no longer match the ``isinstance(content, str)`` test in the
+        # whitespace-normalization pass and silently keep their raw
+        # leading/trailing whitespace. A tool result ending in "\n" is
+        # therefore sent unstripped while it sits in the last-3 window and
+        # stripped once it rolls out of it — the same message, different
+        # bytes on consecutive turns, which breaks the prefix match at
+        # exactly the point the breakpoints were meant to protect. Marking
+        # last also keeps breakpoints off messages that the orphan sweep or
+        # the thinking-only drop is about to remove or merge away.
+        if agent._use_prompt_caching:
+            _static_system_prefix = getattr(agent, "_cached_system_prompt_static", None)
+            api_messages = apply_anthropic_cache_control(
+                api_messages,
+                cache_ttl=agent._cache_ttl,
+                native_anthropic=agent._use_native_cache_layout,
+                static_system_prefix=(
+                    _static_system_prefix
+                    if isinstance(_static_system_prefix, str)
+                    else None
+                ),
+            )
+
         # Build a persistent-MoA request before measuring compression pressure.
         # MoA reference output is injected into the aggregator prompt, but it
         # is deliberately ephemeral and therefore absent from ``messages``.
@@ -1354,36 +1697,52 @@ def run_conversation(
             if _pre_api_status:
                 agent._emit_status(_pre_api_status)
             _last_preflight_pressure = request_pressure_tokens
+            _pre_api_input = messages
             messages, active_system_prompt = agent._compress_context(
                 messages,
                 system_message,
                 approx_tokens=request_pressure_tokens,
                 task_id=effective_task_id,
             )
-            # Reset retry/empty-response state so the compacted request
-            # gets a fresh chance instead of inheriting stale recovery
-            # counters from the pre-compaction history.
-            agent._empty_content_retries = 0
-            agent._thinking_prefill_retries = 0
-            agent._last_content_with_tools = None
-            agent._last_content_tools_all_housekeeping = False
-            agent._mute_post_response = False
-            # Re-baseline the flush cursor for the compaction mode that just
-            # ran. Legacy session-rotation returns None (the child session has
-            # not seen the compacted transcript, so the next flush writes it
-            # whole); in-place compaction returns list(messages) because the
-            # compacted rows are already persisted under the same session id —
-            # leaving None there would re-append them, doubling the active
-            # context and retriggering compression. Mirrors the post-response
-            # and preflight compaction sites; see
-            # conversation_history_after_compression().
-            conversation_history = conversation_history_after_compression(
-                agent, messages, conversation_history
-            )
-            api_call_count -= 1
-            agent._api_call_count = api_call_count
-            agent.iteration_budget.refund()
-            continue
+            if messages is _pre_api_input and compression_skipped_due_to_lock(agent):
+                # #69870 lock-skip: another path holds this session's
+                # compression lock, so this pass no-oped. That is a temporary
+                # DEFER, not evidence about compressibility — refund the
+                # attempt (it must not burn the shared overflow-recovery
+                # budget toward compression_exhausted → gateway auto-reset,
+                # #9893/#35809) and leave the insufficient-progress blocker
+                # unarmed. Proceed with the current request: if it truly does
+                # not fit, the provider's 413/overflow handler returns the
+                # soft compression_deferred result with that stronger signal.
+                compression_attempts -= 1
+                _last_preflight_pressure = None
+                if pending_moa_prepared_request is _moa_prepared_request:
+                    pending_moa_prepared_request = None
+            else:
+                # Reset retry/empty-response state so the compacted request
+                # gets a fresh chance instead of inheriting stale recovery
+                # counters from the pre-compaction history.
+                agent._empty_content_retries = 0
+                agent._thinking_prefill_retries = 0
+                agent._last_content_with_tools = None
+                agent._last_content_tools_all_housekeeping = False
+                agent._mute_post_response = False
+                # Re-baseline the flush cursor for the compaction mode that just
+                # ran. Legacy session-rotation returns None (the child session has
+                # not seen the compacted transcript, so the next flush writes it
+                # whole); in-place compaction returns list(messages) because the
+                # compacted rows are already persisted under the same session id —
+                # leaving None there would re-append them, doubling the active
+                # context and retriggering compression. Mirrors the post-response
+                # and preflight compaction sites; see
+                # conversation_history_after_compression().
+                conversation_history = conversation_history_after_compression(
+                    agent, messages, conversation_history
+                )
+                api_call_count -= 1
+                agent._api_call_count = api_call_count
+                agent.iteration_budget.refund()
+                continue
         elif (
             agent.compression_enabled
             and len(messages) > 1
@@ -2021,6 +2380,8 @@ def run_conversation(
                             )
                     continue  # Retry the API call
 
+                agent._turn_received_provider_response = True
+
                 # Check finish_reason before proceeding
                 if agent.api_mode == "codex_responses":
                     status = getattr(response, "status", None)
@@ -2542,6 +2903,14 @@ def run_conversation(
                         "reasoning_tokens": canonical_usage.reasoning_tokens,
                     }
                     agent.context_compressor.update_from_response(usage_dict)
+
+                    # Stash this response's canonical usage so the post-turn
+                    # on_turn_complete() observation hook can forward it (the
+                    # same dict shape passed to update_from_response). A turn
+                    # may make several API calls; the engine's per-turn signal
+                    # of interest is the cost/size of the latest assembled
+                    # request, so we keep the most recent call's usage.
+                    agent._last_turn_usage = dict(usage_dict)
                 elif getattr(
                     agent.context_compressor,
                     "awaiting_real_usage_after_compression",
@@ -3869,10 +4238,23 @@ def run_conversation(
 
                     original_len = len(messages)
                     original_tokens = estimate_messages_tokens_rough(messages)
+                    _overflow_input = messages
                     messages, active_system_prompt = agent._compress_context(
                         messages, system_message, approx_tokens=approx_tokens,
                         task_id=effective_task_id,
                     )
+                    if messages is _overflow_input and compression_skipped_due_to_lock(agent):
+                        # #69870 lock-skip: the provider proved the request
+                        # does not fit, but this compression pass no-oped only
+                        # because another path holds the session's compression
+                        # lock. Temporary defer, not exhaustion — refund the
+                        # attempt and end the turn softly so the gateway does
+                        # NOT auto-reset the session (#9893/#35809).
+                        compression_attempts -= 1
+                        agent._persist_session(messages, conversation_history)
+                        return _compression_deferred_result(
+                            agent, messages, api_call_count
+                        )
                     conversation_history = conversation_history_after_compression(
                         agent, messages, conversation_history
                     )
@@ -4110,10 +4492,23 @@ def run_conversation(
 
                     original_len = len(messages)
                     original_tokens = estimate_messages_tokens_rough(messages)
+                    _overflow_input = messages
                     messages, active_system_prompt = agent._compress_context(
                         messages, system_message, approx_tokens=approx_tokens,
                         task_id=effective_task_id,
                     )
+                    if messages is _overflow_input and compression_skipped_due_to_lock(agent):
+                        # #69870 lock-skip: the provider proved the request
+                        # does not fit, but this compression pass no-oped only
+                        # because another path holds the session's compression
+                        # lock. Temporary defer, not exhaustion — refund the
+                        # attempt and end the turn softly so the gateway does
+                        # NOT auto-reset the session (#9893/#35809).
+                        compression_attempts -= 1
+                        agent._persist_session(messages, conversation_history)
+                        return _compression_deferred_result(
+                            agent, messages, api_call_count
+                        )
                     conversation_history = conversation_history_after_compression(
                         agent, messages, conversation_history
                     )
@@ -5354,6 +5749,10 @@ def run_conversation(
                 # flag so it can fire again if the model goes empty on
                 # a LATER tool round.
                 agent._post_tool_empty_retried = False
+                # A landed tool call means any earlier dropped-tool-call stall
+                # was recovered — refresh that budget too so it guards each
+                # stall independently rather than capping the whole run.
+                agent._dropped_toolcall_retries = 0
 
                 previous_msg = messages[-1] if messages else None
                 current_interim_visible = agent._interim_assistant_visible_text(assistant_msg)
@@ -5516,14 +5915,27 @@ def run_conversation(
                     if callable(_clear_warn):
                         _clear_warn()
                     agent._safe_print("  ⟳ compacting context…")
+                    _post_tool_input = messages
                     messages, active_system_prompt = agent._compress_context(
                         messages, system_message,
                         approx_tokens=agent.context_compressor.last_prompt_tokens,
                         task_id=effective_task_id,
                     )
-                    conversation_history = conversation_history_after_compression(
-                        agent, messages, conversation_history
-                    )
+                    if (
+                        messages is _post_tool_input
+                        and compression_skipped_due_to_lock(agent)
+                    ):
+                        # #69870 lock-skip: this pass no-oped because another
+                        # path holds the session's compression lock — a
+                        # temporary defer, not evidence about compressibility.
+                        # Refund the attempt so a lock-loser tool loop does not
+                        # burn the shared per-turn budget toward
+                        # compression_exhausted (#9893/#35809).
+                        compression_attempts -= 1
+                    else:
+                        conversation_history = conversation_history_after_compression(
+                            agent, messages, conversation_history
+                        )
                 elif agent.compression_enabled:
                     # Over threshold but compression is blocked (summary-LLM
                     # cooldown or anti-thrashing). Surface a deduped warning so
@@ -5543,15 +5955,72 @@ def run_conversation(
                             _real_tokens,
                             int(getattr(_compressor, "threshold_tokens", 0) or 0),
                         )
+                    # Proactive tool-result prune: reclaim re-sent history on
+                    # large-window models long before should_compress() (≈50% of
+                    # the window) would ever fire. Deterministic, no LLM call;
+                    # protects the recent tail. No-op unless proactive_prune_tokens
+                    # is configured and _real_tokens is above it — and even then
+                    # the prune only commits when it reclaims at least
+                    # proactive_prune_min_reclaim_tokens, so prompt-cache breaks
+                    # stay episodic like compression's (the one sanctioned cache
+                    # break) instead of firing every tool iteration. See
+                    # ContextCompressor.prune_tool_results_only.
+                    # getattr guard: plugin context engines predating the hook and
+                    # minimal test doubles (SimpleNamespace compressors) lack the
+                    # method — treat absence as a no-op.
+                    _prune = getattr(_compressor, "prune_tool_results_only", None)
+                    if callable(_prune):
+                        try:
+                            _pruned_msgs, _pruned_n = _prune(
+                                messages, current_tokens=_real_tokens
+                            )
+                        except Exception:
+                            logger.debug(
+                                "proactive tool-result prune failed; skipping",
+                                exc_info=True,
+                            )
+                            _pruned_msgs, _pruned_n = messages, 0
+                        # Standard no-op caller contract: only commit when the
+                        # engine returned a NEW list object with a non-zero count.
+                        if _pruned_n and _pruned_msgs is not messages:
+                            # Do NOT rebuild conversation_history here. Unlike the
+                            # compression branch, the prune neither rotates the session
+                            # nor calls archive_and_compact(), so there is no new
+                            # persistence baseline to establish. _prune_old_tool_results
+                            # returns per-message copies that preserve the
+                            # _DB_PERSISTED_MARKER, so the marker-based flush dedup (see
+                            # _flush_messages_to_session_db) already prevents both
+                            # duplicate writes and dropped rows. Calling
+                            # conversation_history_after_compression (a compaction-only
+                            # helper keyed on the _last_compaction_in_place flag) would be
+                            # a no-op at best, and on a stale in-place flag could seed
+                            # this turn's fresh, not-yet-persisted rows into history_ids
+                            # and skip writing them.
+                            messages = _pruned_msgs
                 
                 # Save session log incrementally (so progress is visible even if interrupted)
                 agent._session_messages = messages
                 
+                # Touch activity before continuing so the gateway's
+                # inactivity monitor never sees a stale timestamp
+                # between tool completion and the start of the next
+                # API call.  Without this, a tool-call result (which
+                # takes ~0s to process) followed by slow post-tool
+                # processing (compression, persist) and a slow
+                # follow-up API call can exceed the gateway inactivity
+                # timeout (HERMES_AGENT_TIMEOUT, default 1800s) and the
+                # gateway kills the session before the next activity
+                # touch fires (#69559, #69131).
+                agent._touch_activity(f"tool results posted, continuing iteration #{api_call_count}")
                 # Continue loop for next response
                 continue
             
             else:
-                # No tool calls - this is the final response
+                # No tool calls - this is the final response.
+                # (Dropped tool-call recovery — finish_reason=="tool_calls" with
+                # an empty tool_calls array — is handled at the finalization
+                # chokepoint below, after final_msg is built, so it catches
+                # every path that reaches turn finalization, not just this one.)
                 final_response = assistant_message.content or ""
                 
                 # Fix: unmute output when entering the no-tool-call branch
@@ -5883,6 +6352,64 @@ def run_conversation(
                 
                 final_msg = agent._build_assistant_message(assistant_message, finish_reason)
 
+                # ── Dropped tool-call recovery (copilot/Claude) ────────
+                # Some providers (observed: claude-opus-4.8 / claude-sonnet-4.5
+                # on GitHub Copilot, ~2026-07) return finish_reason="tool_calls"
+                # while the parsed tool_calls array is empty — the model
+                # signalled it wanted to act but the payload shipped no call.
+                # Reaching finalization with that mismatch means the turn is
+                # about to end with the task unstarted (the narration, which may
+                # be in content or only in the reasoning field, gets treated as
+                # the final answer). Re-prompt (bounded to 3 CONSECUTIVE stalls;
+                # the budget resets after any successful tool round) to make the
+                # model emit the call instead of exiting. finish_reason="stop"
+                # text finishes never enter this guard.
+                if (
+                    finish_reason == "tool_calls"
+                    and not assistant_message.tool_calls
+                    and getattr(agent, "_dropped_toolcall_retries", 0) < 3
+                ):
+                    agent._dropped_toolcall_retries = getattr(agent, "_dropped_toolcall_retries", 0) + 1
+                    logger.warning(
+                        "finish_reason=tool_calls with empty tool_calls array "
+                        "(narration only) — re-prompting to emit the call "
+                        "(retry %d/3, model=%s provider=%s)",
+                        agent._dropped_toolcall_retries, agent.model, agent.provider,
+                    )
+                    agent._emit_status(
+                        "↻ Model signaled a tool call but sent none — "
+                        f"re-prompting ({agent._dropped_toolcall_retries}/3)"
+                    )
+                    # Both halves of the re-prompt pair are ephemeral recovery
+                    # scaffolding (mirrors the empty-response nudge pattern):
+                    # the interim narration-only assistant turn exists solely to
+                    # keep role alternation valid for the nudge, and the nudge
+                    # exists solely to drive the retry. Flag both so the
+                    # persistence layer never writes them to the durable
+                    # transcript and the finalization pop below can strip an
+                    # unanswered tail pair. A recovered (answered) pair stays
+                    # buried mid-list in live memory but is skipped by the
+                    # flush regardless of position.
+                    final_msg["_dropped_toolcall_nudge"] = True
+                    messages.append(final_msg)
+                    messages.append({
+                        "role": "user",
+                        "content": (
+                            "Your previous turn indicated a tool call but none was "
+                            "included. Do not narrate a plan or restate intent — issue "
+                            "the actual tool call now to continue the task."
+                        ),
+                        "_dropped_toolcall_nudge": True,
+                    })
+                    agent._session_messages = messages
+                    final_response = None
+                    continue
+
+                # Reached finalization without the dropped-tool-call mismatch —
+                # a genuine turn end. Clear the consecutive-stall budget so the
+                # next turn starts fresh.
+                agent._dropped_toolcall_retries = 0
+
                 # Pop thinking-only prefill and empty-response retry
                 # scaffolding before appending either a final response or a
                 # verification-stop follow-up. These internal turns are only
@@ -5895,6 +6422,7 @@ def run_conversation(
                         messages[-1].get("_thinking_prefill")
                         or messages[-1].get("_empty_recovery_synthetic")
                         or messages[-1].get("_empty_terminal_sentinel")
+                        or messages[-1].get("_dropped_toolcall_nudge")
                     )
                 ):
                     messages.pop()
diff --git a/agent/copilot_acp_client.py b/agent/copilot_acp_client.py
index 662facc2dfe..9cbdcd34944 100644
--- a/agent/copilot_acp_client.py
+++ b/agent/copilot_acp_client.py
@@ -512,7 +512,7 @@ class CopilotACPClient:
                 stdin=subprocess.PIPE,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.PIPE,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 bufsize=1,
                 cwd=self._acp_cwd,
                 env=_build_subprocess_env(),
@@ -708,7 +708,7 @@ class CopilotACPClient:
                 if block_error:
                     raise PermissionError(block_error)
                 try:
-                    content = path.read_text()
+                    content = path.read_text(encoding="utf-8")
                 except FileNotFoundError:
                     content = ""
                 line = params.get("line")
@@ -736,7 +736,7 @@ class CopilotACPClient:
                 if denied:
                     raise PermissionError(denied)
                 path.parent.mkdir(parents=True, exist_ok=True)
-                path.write_text(str(params.get("content") or ""))
+                path.write_text(str(params.get("content") or ""), encoding="utf-8")
                 response = {
                     "jsonrpc": "2.0",
                     "id": message_id,
diff --git a/agent/credential_pool.py b/agent/credential_pool.py
index d5d652ad741..08b0c0ea6b9 100644
--- a/agent/credential_pool.py
+++ b/agent/credential_pool.py
@@ -594,6 +594,14 @@ class CredentialPool:
         # Re-armed to None on every successful selection so a recover→re-exhaust
         # transition logs promptly instead of being swallowed by a stale window.
         self._last_no_entries_log_at: Optional[float] = None
+        # #70401: consecutive mark_exhausted_and_rotate() calls whose supplied
+        # credential identity matched no pool entry (OAuth wrappers whose
+        # runtime key rotates, entries pruned by another process, ...).  These
+        # rotations mark nothing exhausted, so without a cap the pool can
+        # never converge to "no available entries" and the caller's 401 retry
+        # loop runs unbounded and non-interruptible.  Reset whenever a real
+        # entry is identified or an escape path returns None.
+        self._unmatched_rotation_streak: int = 0
 
     def has_credentials(self) -> bool:
         with self._lock:
@@ -622,6 +630,28 @@ class CredentialPool:
         with self._lock:
             return self._current_unlocked()
 
+    def entry_id_for_api_key(self, api_key_hint: Any = None) -> Optional[str]:
+        """Return the stable id for the runtime credential in use.
+
+        Prefer the current selection when it still supplies ``api_key_hint``.
+        If the cursor was cleared, fall back to an unambiguous key match.
+        """
+        with self._lock:
+            current = self._current_unlocked()
+            if current is not None and (
+                api_key_hint is None
+                or current.runtime_api_key == api_key_hint
+            ):
+                return current.id
+            if api_key_hint is None:
+                return None
+            matches = [
+                entry
+                for entry in self._entries
+                if entry.runtime_api_key == api_key_hint
+            ]
+            return matches[0].id if len(matches) == 1 else None
+
     def _replace_entry(self, old: PooledCredential, new: PooledCredential) -> None:
         """Swap an entry in-place by id, preserving sort order."""
         for idx, entry in enumerate(self._entries):
@@ -1562,7 +1592,13 @@ class CredentialPool:
 
     def select(self) -> Optional[PooledCredential]:
         with self._lock:
-            return self._select_unlocked()
+            entry = self._select_unlocked()
+            if entry is not None:
+                # A normal (non-recovery) selection starts a fresh episode —
+                # don't let a leftover unmatched-rotation streak from an old
+                # failure trip the #70401 bound early next time.
+                self._unmatched_rotation_streak = 0
+            return entry
 
     def _available_entries(self, *, clear_expired: bool = False, refresh: bool = False) -> List[PooledCredential]:
         """Return entries not currently in exhaustion cooldown.
@@ -1763,10 +1799,17 @@ class CredentialPool:
         status_code: Optional[int],
         error_context: Optional[Dict[str, Any]] = None,
         api_key_hint: Optional[str] = None,
+        credential_id: Optional[str] = None,
     ) -> Optional[PooledCredential]:
         with self._lock:
             entry = None
-            if api_key_hint:
+            identity_supplied = bool(credential_id or api_key_hint)
+            if credential_id:
+                entry = next(
+                    (e for e in self._entries if e.id == credential_id),
+                    None,
+                )
+            if entry is None and api_key_hint:
                 # Prefer the specific entry whose API key matches the one that
                 # actually failed.  When this pool was freshly loaded from disk
                 # (another process already rotated), current() is None and
@@ -1775,20 +1818,59 @@ class CredentialPool:
                     (e for e in self._entries if e.runtime_api_key == api_key_hint),
                     None,
                 )
-                if entry is None:
-                    # The failed key is identifiable but matches no entry
-                    # (rotated away, or a wrapper whose runtime key differs).
-                    # Falling through to current()/_select_unlocked() would
-                    # mark an INNOCENT healthy key exhausted for the full
-                    # cooldown TTL.  Don't guess — just hand back a fresh
-                    # selection so the caller can retry.
-                    logger.info(
-                        "credential pool: failed key hint matched no %s entry; "
-                        "rotating without marking any credential exhausted",
+            if entry is None and identity_supplied:
+                # The failed credential is identifiable but matches no entry
+                # (rotated away, or a wrapper whose runtime key differs).
+                # Falling through to current()/_select_unlocked() would mark an
+                # innocent healthy key exhausted for the full cooldown TTL.
+                #
+                # #70401: this branch must still be BOUNDED. With OAuth-token
+                # auth the upstream 401's key hint never matches any entry's
+                # ``runtime_api_key``, so every retry lands here, nothing is
+                # ever marked exhausted, and the pool can never reach the
+                # "no available entries" state — the caller retries the same
+                # dead token forever (~6/sec, starving the event loop so chat
+                # interrupts are never processed). The single-entry case
+                # below already escapes; multi-entry pools could still
+                # ping-pong A→B→A indefinitely without marking anything.
+                # Cap consecutive no-mark rotations at one full lap of the
+                # available entries: past that, every candidate has been
+                # handed back at least once without recovery, so stop
+                # guessing and surface the error (no cooldown is written for
+                # anybody — healthy keys stay available for the next turn).
+                self._unmatched_rotation_streak += 1
+                available_count = len(self._available_entries())
+                if self._unmatched_rotation_streak > max(available_count, 1):
+                    logger.warning(
+                        "credential pool: failed credential identity matched no "
+                        "%s entry for %d consecutive rotations (pool size %d) — "
+                        "surfacing the error instead of rotating again",
                         self.provider,
+                        self._unmatched_rotation_streak,
+                        available_count,
                     )
+                    self._unmatched_rotation_streak = 0
                     self._current_id = None
-                    return self._select_unlocked()
+                    return None
+                logger.info(
+                    "credential pool: failed credential identity matched no %s "
+                    "entry; rotating without marking any credential exhausted",
+                    self.provider,
+                )
+                self._current_id = None
+                next_entry = self._select_unlocked()
+                if next_entry is not None and len(self._available_entries()) == 1:
+                    # A single-entry pool cannot rotate. Returning its only
+                    # entry reports a successful recovery without changing
+                    # the credential, so the caller retries the same 401
+                    # indefinitely. Let fallback/error propagation proceed.
+                    self._unmatched_rotation_streak = 0
+                    self._current_id = None
+                    return None
+                return next_entry
+            # A real entry was identified — any prior unmatched-rotation
+            # streak is stale (this mark WILL advance pool state).
+            self._unmatched_rotation_streak = 0
             if entry is None:
                 entry = self._current_unlocked() or self._select_unlocked()
             if entry is None:
@@ -1806,12 +1888,13 @@ class CredentialPool:
             # disconnects (a ~2.5min hang with no error surfaced to the user).
             # Mark every entry sharing the failed key so the pool can reach the
             # "no available entries" state and let the error propagate.
-            if api_key_hint:
+            failed_runtime_key = getattr(entry, "runtime_api_key", None)
+            if identity_supplied and failed_runtime_key:
                 siblings_marked = False
                 for sibling in self._entries:
                     if sibling.id == entry.id:
                         continue
-                    if sibling.runtime_api_key == api_key_hint:
+                    if sibling.runtime_api_key == failed_runtime_key:
                         self._mark_exhausted(
                             sibling, status_code, error_context, persist=False
                         )
@@ -1885,9 +1968,11 @@ class CredentialPool:
             return self._try_refresh_current_unlocked()
 
     def try_refresh_matching(
-        self, api_key_hint: Optional[str] = None
+        self,
+        api_key_hint: Optional[str] = None,
+        credential_id: Optional[str] = None,
     ) -> Optional[PooledCredential]:
-        """Force-refresh the entry that supplied ``api_key_hint``.
+        """Force-refresh the entry that supplied the failed request.
 
         Direct provider integrations may reload the pool after a request has
         already failed, so they cannot rely on ``current_id`` identifying the
@@ -1897,17 +1982,29 @@ class CredentialPool:
         """
         with self._lock:
             entry = None
-            if api_key_hint:
+            if credential_id:
                 entry = next(
                     (
                         candidate
                         for candidate in self._entries
-                        if candidate.runtime_api_key == api_key_hint
+                        if candidate.id == credential_id
                     ),
                     None,
                 )
-            else:
-                entry = self._current_unlocked() or self._select_unlocked(refresh=False)
+            if entry is None:
+                if api_key_hint:
+                    entry = next(
+                        (
+                            candidate
+                            for candidate in self._entries
+                            if candidate.runtime_api_key == api_key_hint
+                        ),
+                        None,
+                    )
+                else:
+                    entry = self._current_unlocked() or self._select_unlocked(
+                        refresh=False
+                    )
             if entry is None:
                 return None
             self._current_id = entry.id
diff --git a/agent/credential_sources.py b/agent/credential_sources.py
index 18f0823ba84..32cd5e01a80 100644
--- a/agent/credential_sources.py
+++ b/agent/credential_sources.py
@@ -164,7 +164,7 @@ def _remove_env_source(provider: str, removed) -> RemovalResult:
         if env_path.exists():
             env_in_dotenv = any(
                 line.strip().startswith(f"{env_var}=")
-                for line in env_path.read_text(errors="replace").splitlines()
+                for line in env_path.read_text(errors="replace", encoding="utf-8").splitlines()
             )
     except OSError:
         pass
diff --git a/agent/curator.py b/agent/curator.py
index ada93248e24..975ed102de0 100644
--- a/agent/curator.py
+++ b/agent/curator.py
@@ -325,7 +325,7 @@ def apply_automatic_transitions(now: Optional[datetime] = None) -> Dict[str, int
 
     counts = {"marked_stale": 0, "archived": 0, "reactivated": 0, "checked": 0, "seeded": 0}
 
-    for row in _u.agent_created_report():
+    for row in _u.curated_report():
         counts["checked"] += 1
         name = row["name"]
         if row.get("pinned"):
@@ -422,7 +422,9 @@ CURATOR_REVIEW_PROMPT = (
     "INSTRUCTIONS AND EXPERIENTIAL KNOWLEDGE. A collection of hundreds of "
     "narrow skills where each one captures one session's specific bug is "
     "a FAILURE of the library — not a feature. An agent searching skills "
-    "matches on descriptions, not on exact names; one broad umbrella "
+    "matches on descriptions, not on exact names (note: long descriptions "
+    "are truncated to 57 chars in the system prompt skill index — keep the "
+    "trigger class in that window). One broad umbrella "
     "skill with labeled subsections beats five narrow siblings for "
     "discoverability, not the other way around.\n\n"
     "The right target shape is CLASS-LEVEL skills with rich SKILL.md "
@@ -1470,15 +1472,16 @@ def _render_report_markdown(p: Dict[str, Any]) -> str:
 # ---------------------------------------------------------------------------
 
 def _render_candidate_list() -> str:
-    """Human/agent-readable list of agent-created skills with usage stats."""
-    rows = skill_usage.agent_created_report()
+    """Human/agent-readable list of curator-managed skills with usage stats."""
+    rows = skill_usage.curated_report()
     if not rows:
-        return "No agent-created skills to review."
+        return "No curator-managed skills to review."
     cron_referenced = _cron_referenced_skills()
-    lines = [f"Agent-created skills ({len(rows)}):\n"]
+    lines = [f"Curator-managed skills ({len(rows)}):\n"]
     for r in rows:
         lines.append(
             f"- {r['name']}  "
+            f"provenance={r.get('provenance', 'agent')}  "
             f"state={r['state']}  "
             f"pinned={'yes' if r.get('pinned') else 'no'}  "
             f"cron={'yes' if r['name'] in cron_referenced else 'no'}  "
@@ -1531,7 +1534,7 @@ def run_curator_review(
     if dry_run:
         # Count candidates without mutating state.
         try:
-            report = skill_usage.agent_created_report()
+            report = skill_usage.curated_report()
             counts = {
                 "checked": len(report),
                 "marked_stale": 0,
@@ -1584,7 +1587,7 @@ def run_curator_review(
         nonlocal auto_summary
         # Snapshot skill state BEFORE the LLM pass so the report can diff.
         try:
-            before_report = skill_usage.agent_created_report()
+            before_report = skill_usage.curated_report()
         except Exception:
             before_report = []
         before_names = {r.get("name") for r in before_report if isinstance(r, dict)}
@@ -1610,7 +1613,7 @@ def run_curator_review(
             state2["last_run_duration_seconds"] = elapsed
             state2["last_run_summary"] = final_summary
             try:
-                after_report = skill_usage.agent_created_report()
+                after_report = skill_usage.curated_report()
             except Exception:
                 after_report = []
             try:
@@ -1697,7 +1700,7 @@ def run_curator_review(
         try:
             rename_lines = _build_rename_summary(
                 before_names=before_names,
-                after_report=skill_usage.agent_created_report(),
+                after_report=skill_usage.curated_report(),
                 tool_calls=llm_meta.get("tool_calls", []) or [],
                 model_final=llm_meta.get("final", "") or "",
             )
@@ -1715,7 +1718,7 @@ def run_curator_review(
         # reporting bug never breaks the curator itself. Report path is
         # recorded in state so `hermes curator status` can point at it.
         try:
-            after_report = skill_usage.agent_created_report()
+            after_report = skill_usage.curated_report()
         except Exception:
             after_report = []
         try:
diff --git a/agent/gemini_native_adapter.py b/agent/gemini_native_adapter.py
index 1c25f1e6cf0..b4f6e6386e7 100644
--- a/agent/gemini_native_adapter.py
+++ b/agent/gemini_native_adapter.py
@@ -270,8 +270,12 @@ def _translate_tool_call_to_gemini(tool_call: Dict[str, Any]) -> Dict[str, Any]:
         }
     }
     thought_signature = _tool_call_extra_signature(tool_call)
-    if thought_signature:
-        part["thoughtSignature"] = thought_signature
+    # Fallback sentinel for cross-provider tool_calls (e.g. fallback from
+    # xAI/Anthropic to Gemini, where the original tool_call carries no
+    # Gemini thoughtSignature). Mirrors gemini_cloudcode_adapter.py:106.
+    # Without this, Gemini 3 thinking models reject replayed history with
+    # 400 INVALID_ARGUMENT on the missing thoughtSignature.
+    part["thoughtSignature"] = thought_signature or "skip_thought_signature_validator"
     return part
 
 
diff --git a/agent/i18n.py b/agent/i18n.py
index b55b8128c92..24f8ab0a023 100644
--- a/agent/i18n.py
+++ b/agent/i18n.py
@@ -25,7 +25,8 @@ Language resolution order:
     3. ``display.language`` from config.yaml
     4. ``"en"`` (baseline)
 
-Supported languages: en, zh, ja, de, es, fr, tr, uk.  Unknown values fall back to en.
+Supported languages: en, zh, zh-hant, ja, de, es, fr, tr, uk, af, ko, it, ga,
+pt, ru, hu, ar.  Unknown values fall back to en.
 """
 
 from __future__ import annotations
@@ -41,7 +42,7 @@ logger = logging.getLogger(__name__)
 
 SUPPORTED_LANGUAGES: tuple[str, ...] = (
     "en", "zh", "zh-hant", "ja", "de", "es", "fr", "tr", "uk",
-    "af", "ko", "it", "ga", "pt", "ru", "hu",
+    "af", "ko", "it", "ga", "pt", "ru", "hu", "ar",
 )
 DEFAULT_LANGUAGE = "en"
 
@@ -78,6 +79,9 @@ _LANGUAGE_ALIASES: dict[str, str] = {
     "russian": "ru", "русский": "ru", "ru-ru": "ru",
     # Hungarian
     "hungarian": "hu", "magyar": "hu", "hu-hu": "hu",
+    # Arabic — bare "arabic"/endonym plus the common regional BCP-47 tags.
+    "arabic": "ar", "العربية": "ar",
+    "ar-sa": "ar", "ar-eg": "ar", "ar-ae": "ar", "ar-ma": "ar", "ar-dz": "ar",
 }
 
 _catalog_cache: dict[str, dict[str, str]] = {}
diff --git a/agent/lsp/client.py b/agent/lsp/client.py
index 9207cb75bda..3411f5300b3 100644
--- a/agent/lsp/client.py
+++ b/agent/lsp/client.py
@@ -56,6 +56,8 @@ from pathlib import Path
 from typing import Any, Awaitable, Callable, Dict, List, Optional, Set
 from urllib.parse import quote, unquote
 
+from hermes_cli._subprocess_compat import windows_hide_flags
+
 from agent.lsp.protocol import (
     ERROR_CONTENT_MODIFIED,
     ERROR_METHOD_NOT_FOUND,
@@ -294,6 +296,12 @@ class LSPClient:
         cmd = self._command
         if sys.platform == "win32":
             cmd = self._win_wrap_cmd(cmd)
+        # Suppress the cmd.exe console window that would otherwise flash
+        # every time we launch a ``.cmd``-wrapped language server
+        # (e.g. pyright-langserver.CMD) from a console-less host such as
+        # a VS Code/Zed extension running the ACP adapter.
+        # windows_hide_flags() is CREATE_NO_WINDOW on Windows, 0 on POSIX.
+        creationflags = windows_hide_flags()
 
         try:
             # start_new_session=True detaches the LSP server into its own
@@ -312,6 +320,7 @@ class LSPClient:
                 env=env,
                 cwd=self._cwd,
                 start_new_session=True,
+                creationflags=creationflags,
             )
         except FileNotFoundError as e:
             raise LSPProtocolError(
diff --git a/agent/lsp/install.py b/agent/lsp/install.py
index 079033b772a..da8f1fd7788 100644
--- a/agent/lsp/install.py
+++ b/agent/lsp/install.py
@@ -35,6 +35,8 @@ import threading
 from pathlib import Path
 from typing import Any, Dict, Optional
 
+from hermes_cli._subprocess_compat import windows_hide_flags
+
 logger = logging.getLogger("agent.lsp.install")
 
 # Package-name → install-strategy hint registry.  Each entry is a
@@ -265,9 +267,10 @@ def _install_npm(
             [npm, "install", "--prefix", str(staging), "--silent", "--no-fund", "--no-audit", *install_targets],
             check=False,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=300,
             stdin=subprocess.DEVNULL,
+            creationflags=windows_hide_flags(),
         )
         if proc.returncode != 0:
             logger.warning(
@@ -313,10 +316,11 @@ def _install_go(pkg: str, bin_name: str) -> Optional[str]:
             [go, "install", pkg],
             check=False,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=600,
             env=env,
             stdin=subprocess.DEVNULL,
+            creationflags=windows_hide_flags(),
         )
         if proc.returncode != 0:
             logger.warning(
diff --git a/agent/memory_manager.py b/agent/memory_manager.py
index 3909f2ebcd3..6f3bbadd6f0 100644
--- a/agent/memory_manager.py
+++ b/agent/memory_manager.py
@@ -80,8 +80,17 @@ def normalize_tool_schema(schema: Any) -> Optional[Dict[str, Any]]:
     return schema
 
 
-def memory_provider_tools_enabled(enabled_toolsets: Optional[List[str]]) -> bool:
+def memory_provider_tools_enabled(
+    enabled_toolsets: Optional[List[str]],
+    disabled_toolsets: Optional[List[str]] = None,
+    *,
+    memory_tool_present: bool = False,
+) -> bool:
     """Return whether external memory-provider tools should be exposed."""
+    if disabled_toolsets and "memory" in disabled_toolsets:
+        return False
+    if memory_tool_present:
+        return True
     if enabled_toolsets is None:
         return True
     if not enabled_toolsets:
@@ -110,9 +119,10 @@ def inject_memory_provider_tools(agent: Any) -> int:
         for tool in tools
         if isinstance(tool, dict)
     }
-    if (
-        "memory" not in existing_tool_names
-        and not memory_provider_tools_enabled(getattr(agent, "enabled_toolsets", None))
+    if not memory_provider_tools_enabled(
+        getattr(agent, "enabled_toolsets", None),
+        getattr(agent, "disabled_toolsets", None),
+        memory_tool_present="memory" in existing_tool_names,
     ):
         return 0
 
diff --git a/agent/moa_loop.py b/agent/moa_loop.py
index e075b001807..ed0f41a817a 100644
--- a/agent/moa_loop.py
+++ b/agent/moa_loop.py
@@ -10,7 +10,9 @@ from __future__ import annotations
 
 import hashlib
 import logging
-from concurrent.futures import ThreadPoolExecutor
+import re
+import threading
+from concurrent.futures import ThreadPoolExecutor, wait as _futures_wait
 from typing import Any
 
 from agent.auxiliary_client import call_llm
@@ -19,6 +21,136 @@ from agent.transports import get_transport
 
 logger = logging.getLogger(__name__)
 
+# --- MoA privacy filter (config: moa.privacy_filter — '' | display | full) ---
+#
+# Advisor (reference) outputs can echo PII from the conversation — emails,
+# phone numbers, credentials pasted by the user — into surfaces the user may
+# not expect: the labelled reference blocks rendered in the UI, saved MoA
+# trace files, and (in `full` mode) the guidance block injected into the
+# aggregator prompt (issue #59959). Secret/credential shapes (API-key
+# prefixes, JWTs, private keys, DB connection strings, E.164 phone numbers)
+# are handled by the repo's central redactor, ``agent.redact
+# .redact_sensitive_text`` — the MoA filter never re-implements those. The
+# two patterns below cover the PII classes the central redactor deliberately
+# leaves alone for log/tool output (emails and formatted phone numbers).
+#
+# Pattern safety: advisory text is frequently code-review-shaped — line
+# numbers, timestamps, git SHAs, IDs, IP addresses. A bare 10-digit match
+# would mangle all of those, so the phone pattern requires clearly delimited
+# formatting: a parenthesized area code and/or explicit `-`/`.` separators
+# between groups ((555) 123-4567, 555-123-4567, 555.123.4567, +1 555-123-4567).
+# Undelimited digit runs (5551234567), dates (2026-07-12), times (12:34:56),
+# hex IDs, and dotted quads never match. International numbers in E.164 form
+# (+14155551234) are already masked by the central redactor.
+_MOA_EMAIL_RE = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
+_MOA_PHONE_RE = re.compile(
+    r"(?<![\w.+-])"                    # no leading word char / dot / + / - (kills IPs, IDs, versions)
+    r"(?:\+?1[ .-])?"                  # optional NA country code
+    r"(?:\(\d{3}\)[ .-]?|\d{3}[.-])"   # delimited area code: (555) or 555- / 555.
+    r"\d{3}[.-]\d{4}"                  # exchange-subscriber with explicit separator
+    r"(?![\w-])"                       # no trailing word char / hyphen
+)
+
+
+def _redact_reference_text(text: Any) -> Any:
+    """Redact secrets + PII from one advisor/reference text surface.
+
+    Centralized secret shapes first (force=True: the MoA privacy filter is
+    its own explicit opt-in, independent of the global log-redaction toggle;
+    code_file=True: advisory text is prose/code, so the ENV/JSON assignment
+    heuristics that mangle source snippets stay off), then the MoA-specific
+    email/formatted-phone patterns. Non-string inputs pass through unchanged.
+    """
+    if not isinstance(text, str) or not text:
+        return text
+    from agent.redact import redact_sensitive_text
+
+    text = redact_sensitive_text(text, force=True, code_file=True)
+    text = _MOA_EMAIL_RE.sub("[redacted email]", text)
+    text = _MOA_PHONE_RE.sub("[redacted phone]", text)
+    return text
+
+
+def _moa_privacy_mode(moa_raw: Any) -> str:
+    """Resolve the normalized privacy-filter mode from a raw ``moa`` config."""
+    from hermes_cli.moa_config import coerce_privacy_filter
+
+    raw = moa_raw if isinstance(moa_raw, dict) else {}
+    return coerce_privacy_filter(raw.get("privacy_filter"))
+
+
+def _redact_reference_outputs(
+    reference_outputs: list[tuple[str, str, Any]],
+) -> list[tuple[str, str, Any]]:
+    """Return reference-output tuples with their advisor text redacted.
+
+    The ``_RefAccounting`` third slot is left as-is — accounting fields carry
+    no advisor text; the full-output/input trace fields are redacted
+    separately at trace-stash time (see create()) so the LIVE cache keeps raw
+    accounting objects untouched.
+    """
+    return [
+        (label, _redact_reference_text(text), acct)
+        for label, text, acct in reference_outputs
+    ]
+
+
+def _redact_trace_messages(messages: Any) -> Any:
+    """Redact message copies destined for trace persistence.
+
+    Handles both string content and structured content-part lists (e.g.
+    cache_control-decorated text parts). Unknown shapes pass through.
+    """
+    if not isinstance(messages, list):
+        return messages
+    out: list[Any] = []
+    for m in messages:
+        if not isinstance(m, dict):
+            out.append(m)
+            continue
+        content = m.get("content")
+        if isinstance(content, str):
+            out.append({**m, "content": _redact_reference_text(content)})
+        elif isinstance(content, list):
+            out.append(
+                {
+                    **m,
+                    "content": [
+                        {**p, "text": _redact_reference_text(p.get("text"))}
+                        if isinstance(p, dict) and isinstance(p.get("text"), str)
+                        else p
+                        for p in content
+                    ],
+                }
+            )
+        else:
+            out.append(m)
+    return out
+
+
+def _redact_trace_accounting(acct: Any) -> Any:
+    """Return a copy of a ``_RefAccounting`` with its trace text redacted.
+
+    Traces persist the advisor's FULL input messages and output to disk, so a
+    privacy-filtered run must not write raw PII there. Usage/cost fields are
+    copied verbatim (numbers, no text). Non-accounting objects pass through.
+    """
+    if not isinstance(acct, _RefAccounting):
+        return acct
+    return _RefAccounting(
+        acct.usage,
+        acct.cost_usd,
+        acct.cost_status,
+        acct.cost_source,
+        messages=_redact_trace_messages(acct.messages),
+        output=_redact_reference_text(acct.output),
+        model=acct.model,
+        provider=acct.provider,
+        temperature=acct.temperature,
+    )
+
+
+
 # Upper bound on concurrent reference-model calls. References are independent
 # advisory calls (no tools, no inter-dependence), so we fan them out the same
 # way delegate_task runs a batch: all in flight at once, results collected when
@@ -105,6 +237,16 @@ _REFERENCE_SYSTEM_PROMPT = (
     "you should not try to or apologize for being unable to. A separate "
     "aggregator/orchestrator model holds those capabilities and will take the "
     "actual actions.\n\n"
+    "CRITICAL: You must NEVER claim or imply that you have executed a command, "
+    "downloaded a file, accessed a URL, or performed any action. You can only "
+    "analyze and advise based on the conversation context. Examples of what to "
+    "avoid:\n"
+    "- Bad: \"I ran curl and got 404.\"\n"
+    "- Bad: \"I downloaded the file successfully.\"\n"
+    "- Bad: \"I checked the repository and found...\"\n"
+    "- Good: \"Based on the error pattern, a curl request to that URL would likely return 404.\"\n"
+    "- Good: \"The conversation suggests downloading this file may help.\"\n"
+    "- Good: \"From the context, checking the repository would reveal...\"\n\n"
     "The conversation below is the current state of a task handled by that "
     "acting agent. Your job is to give your most intelligent analysis of that "
     "state: understand the goal, reason about the problem, and advise on what "
@@ -115,7 +257,8 @@ _REFERENCE_SYSTEM_PROMPT = (
     "asking for access.\n\n"
     "Respond with your advice directly — no preamble, no disclaimers about "
     "tools or access. Your response is private guidance handed to the "
-    "aggregator, not an answer shown to the user."
+    "aggregator, not an answer shown to the user. NEVER claim to have executed "
+    "anything."
 )
 
 
@@ -245,10 +388,10 @@ def _maybe_apply_moa_cache_control(
 
     Reuses the SAME policy function as the main agent loop
     (``anthropic_prompt_cache_policy``) resolved against the slot's own
-    provider/base_url/api_mode/model, and the SAME breakpoint layout
-    (``apply_anthropic_cache_control``, system_and_3). This keeps advisor and
-    aggregator calls decorated exactly like an acting agent on that provider
-    would be — no MoA-specific caching logic to drift.
+    provider/base_url/api_mode/model and shared marker helper
+    (``apply_anthropic_cache_control``). MoA has no per-session static prefix,
+    so it uses the helper's legacy system-and-3 fallback without carrying a
+    separate caching strategy.
 
     Returns the messages unchanged on any resolution error or when the
     policy says the route doesn't honor markers.
@@ -281,13 +424,15 @@ def _maybe_apply_moa_cache_control(
 
 
 def _run_reference(
-    slot: dict[str, str],
+    slot: dict[str, Any],
     ref_messages: list[dict[str, Any]],
     *,
     temperature: float | None = None,
     max_tokens: int | None = None,
+    reference_timeout: float | None = None,
+    context_length_cache: Any = None,
 ) -> tuple[str, str, Any]:
-    """Call one reference model and return ``(label, text, usage)``.
+    """Call one reference model and return ``(label, text, accounting)``.
 
     The slot is resolved to its provider's real runtime (via ``_slot_runtime``)
     and called through the same ``call_llm`` request-building path any model
@@ -321,10 +466,25 @@ def _run_reference(
         # trimmed view (_reference_messages) already strips the agent's own
         # system prompt, so this is the only system message the reference sees.
         messages = [{"role": "system", "content": _REFERENCE_SYSTEM_PROMPT}, *ref_messages]
-        # Apply the same Anthropic-style prompt-caching decoration the main
-        # agent loop applies (system_and_3 breakpoints). The advisory view is
-        # append-only across iterations (new turns append before the trailing
-        # synthetic marker), so on cache-honoring routes (Claude via
+        # Trim to fit THIS reference model's context window. Reference models
+        # may have a smaller window than the aggregator (e.g. kimi-k2.7-code
+        # @ 262K advising a glm-5.2 @ 1M conversation); without this trim the
+        # provider returns a hard HTTP 400 which the except below silently
+        # converts to a [failed: …] note (issue #60345). Estimated AFTER the
+        # advisory system prompt is prepended so its tokens count against the
+        # budget too.
+        messages = _trim_messages_for_reference(
+            messages,
+            slot,
+            runtime,
+            reserve_output_tokens=max_tokens,
+            context_length_cache=context_length_cache,
+        )
+        # Apply the Anthropic-style prompt-caching decoration used by the main
+        # agent loop. This fixed reference prompt has no session-specific
+        # prefix split, so the helper uses its legacy system-and-3 fallback.
+        # The advisory view is append-only across iterations (new turns append
+        # before the trailing synthetic marker), so on cache-honoring routes (Claude via
         # OpenRouter/native, MiniMax, Qwen/DashScope) iteration N+1's prefix
         # replays iteration N's cached prefix. Without this, Claude advisors
         # served ZERO cache reads across an entire benchmark run (measured:
@@ -333,12 +493,38 @@ def _run_reference(
         # (their caching is automatic; markers are ignored harmlessly, but we
         # only decorate when the policy says the route honors them).
         messages = _maybe_apply_moa_cache_control(messages, runtime)
+        # Per-slot max_tokens takes precedence over the preset-level
+        # reference_max_tokens passed in by the caller. This lets each
+        # reference model have its own output cap independently.
+        _slot_max_tokens: int | None = slot.get("max_tokens")
+        _effective_max_tokens = _slot_max_tokens if _slot_max_tokens is not None else max_tokens
+        extra_headers = None
+        # Normalize provider aliases (github, github-copilot, github-models,
+        # ...) through the auxiliary client's canonical alias table so slot
+        # configs that spell Copilot differently still get the header.
+        from agent.auxiliary_client import _normalize_aux_provider
+
+        if _normalize_aux_provider(str(runtime.get("provider") or "")) in (
+            "copilot",
+            "copilot-acp",
+        ):
+            # Copilot Pro/Pro+ gates some premium chat models on request
+            # attribution. The main agent marks the first API request of a
+            # user turn as ``x-initiator: user``; MoA reference fan-out is also
+            # directly serving the user's current turn, not a background agent
+            # task, so mirror that header here. Without it, Claude/Gemini
+            # Copilot advisors can be rejected as unavailable to the
+            # ``copilot-language-server`` integrator even though standalone
+            # Copilot calls work.
+            extra_headers = {"x-initiator": "user"}
         response = call_llm(
             task="moa_reference",
             messages=messages,
             temperature=temperature,
-            max_tokens=max_tokens,
+            max_tokens=_effective_max_tokens,
+            timeout=reference_timeout,
             reasoning_config=_slot_reasoning_config(slot),
+            extra_headers=extra_headers,
             **runtime,
         )
         usage = CanonicalUsage()
@@ -397,12 +583,162 @@ def _run_reference(
         )
 
 
+# Output-token headroom reserved inside the reference's context window when
+# the preset does not cap advisor output (reference_max_tokens=None). Roughly
+# one long-form advisory answer; generous enough for thinking models' visible
+# output without starving the input budget.
+_REFERENCE_DEFAULT_OUTPUT_RESERVE = 8192
+
+# Additional estimation slack: estimate_messages_tokens_rough is a rough
+# chars/4 heuristic and providers tokenize less favorably on code/JSON-heavy
+# transcripts, so keep a safety fraction of the window unbudgeted.
+_REFERENCE_TRIM_SAFETY_FRACTION = 0.10
+
+
+def _trim_messages_for_reference(
+    messages: list[dict[str, Any]],
+    slot: dict[str, str],
+    runtime: dict[str, Any],
+    *,
+    reserve_output_tokens: int | None = None,
+    context_length_cache: Any = None,
+) -> list[dict[str, Any]]:
+    """Trim an advisory request to fit within a reference model's context window.
+
+    Reference models may have a smaller context window than the aggregator or
+    the main conversation. Without this trim, a reference whose window is
+    exceeded gets a hard HTTP 400 from the provider, which ``_run_reference``'s
+    try/except silently converts to a ``[failed: …]`` note — the MoA turn
+    silently degrades to fewer references (issue #60345).
+
+    ``messages`` is the FULL request as it will be sent — the advisory system
+    prompt already prepended — so the estimate covers everything the provider
+    will count. The budget reserves ``reserve_output_tokens`` (the preset's
+    ``reference_max_tokens`` when set, else a sane constant) for the model's
+    response plus a safety fraction for estimator error.
+
+    Trimming drops the OLDEST conversation frames (right after the system
+    prompt) and preserves two invariants of the advisory view, which is
+    text-only user/assistant turns (``_reference_messages`` renders tool
+    calls/results inline, so there are no tool-result frames to orphan):
+
+      - the system prompt (index 0) is always kept;
+      - the first non-system message stays ``user``-first — after each pop,
+        any now-leading assistant turns are popped too, so no provider ever
+        sees an assistant-first conversation;
+      - the trailing user turn (the synthetic judge-the-state marker) and at
+        least one preceding turn are always kept, even if still over budget —
+        a too-long-but-recent view beats an empty request.
+
+    ``context_length_cache`` is an optional per-turn dict keyed by
+    ``(provider, model)`` so one fan-out (and every iteration reusing the
+    cache) resolves each model's window at most once instead of re-probing
+    metadata sources per-reference-per-iteration. When the window cannot be
+    resolved, messages are returned unchanged.
+    """
+    if not messages:
+        return messages
+
+    from agent.model_metadata import (
+        estimate_messages_tokens_rough,
+        get_model_context_length,
+    )
+
+    model = str(slot.get("model") or "")
+    provider = str(runtime.get("provider") or slot.get("provider") or "")
+    if not model:
+        return messages
+
+    cache_key = (provider, model)
+    context_length: int | None = None
+    if isinstance(context_length_cache, dict) and cache_key in context_length_cache:
+        context_length = context_length_cache[cache_key]
+    else:
+        try:
+            context_length = get_model_context_length(
+                model=model,
+                base_url=str(runtime.get("base_url") or ""),
+                api_key=str(runtime.get("api_key") or ""),
+                provider=provider,
+            )
+        except Exception:
+            logger.debug(
+                "MoA reference context-length resolution failed for %s",
+                _slot_label(slot),
+            )
+            context_length = None
+        if isinstance(context_length_cache, dict):
+            # Cache failures too (as None) — a flaky metadata source should
+            # not be re-probed for every reference of every iteration.
+            context_length_cache[cache_key] = context_length
+
+    if not isinstance(context_length, int) or context_length <= 0:
+        return messages
+
+    reserve = (
+        int(reserve_output_tokens)
+        if isinstance(reserve_output_tokens, int) and reserve_output_tokens > 0
+        else _REFERENCE_DEFAULT_OUTPUT_RESERVE
+    )
+    budget = int(context_length * (1.0 - _REFERENCE_TRIM_SAFETY_FRACTION)) - reserve
+    if budget <= 0:
+        return messages
+
+    estimated = estimate_messages_tokens_rough(messages)
+    if estimated <= budget:
+        return messages
+
+    has_system = bool(messages) and messages[0].get("role") == "system"
+    head = [messages[0]] if has_system else []
+    body = list(messages[1:] if has_system else messages)
+
+    # Keep the trailing user turn plus at least one preceding turn.
+    while len(body) > 2 and estimate_messages_tokens_rough(head + body) > budget:
+        body.pop(0)
+        # Preserve the user-first invariant: never leave the advisory
+        # conversation starting on an assistant turn after a pop.
+        while len(body) > 2 and body[0].get("role") == "assistant":
+            body.pop(0)
+    # The loop can stop with two frames left where the first is an
+    # assistant turn — enforce user-first even then (a lone trailing user
+    # turn is a valid request; an assistant-first one is not).
+    while len(body) > 1 and body[0].get("role") == "assistant":
+        body.pop(0)
+
+    trimmed = head + body
+    dropped = len(messages) - len(trimmed)
+    if dropped:
+        logger.info(
+            "MoA reference %s: estimated %d tokens exceeds budget %d "
+            "(window %d, output reserve %d); dropped %d oldest message(s).",
+            _slot_label(slot),
+            estimated,
+            budget,
+            context_length,
+            reserve,
+            dropped,
+        )
+    return trimmed
+
+
+_REFERENCE_POLL_INTERVAL_S = 5.0
+
+# Sentinel text for a reference slot whose wait was aborted by a user
+# interrupt. Shared by _run_references_parallel (which writes it) and the
+# facade cache logic (which must never cache it as real advice).
+_INTERRUPTED_REFERENCE_NOTE = "[skipped: interrupted by user]"
+
+
 def _run_references_parallel(
-    reference_models: list[dict[str, str]],
+    reference_models: list[dict[str, Any]],
     ref_messages: list[dict[str, Any]],
     *,
     temperature: float | None = None,
     max_tokens: int | None = None,
+    progress_callback: Any = None,
+    reference_timeout: float | None = None,
+    agent: Any = None,
+    late_accounting_sink: Any = None,
 ) -> list[tuple[str, str, Any]]:
     """Fan out all reference models in parallel, returning outputs in order.
 
@@ -412,8 +748,30 @@ def _run_references_parallel(
     ``Reference {idx}`` labelling stays stable. MoA presets that reference
     another MoA preset are skipped here (recursion guard) with a labelled note.
 
-    Each element is ``(label, text, usage)`` where usage is a
-    ``CanonicalUsage`` (zeroed for skipped/failed references).
+    If ``progress_callback`` is provided it is invoked as each reference
+    completes: ``progress_callback(refs_done, refs_total, label)``. The total
+    matches ``len(reference_models)`` so listeners can render a status-bar
+    progress like ``MOA: 2/3 refs done``. Best-effort — failures are logged
+    but never break the fan-out (display must never block a turn).
+
+    Each element is ``(label, text, accounting)`` where accounting is a
+    ``_RefAccounting`` object (zeroed for skipped/failed/interrupted
+    references).
+
+    When *agent* is given, the fan-out is interruptible: waiting for the
+    batch is broken into ``_REFERENCE_POLL_INTERVAL_S``-second polls (instead
+    of one blocking ``future.result()`` per reference) so a user interrupt
+    mid-turn can abort the wait — mirroring the same interrupt check
+    ``agent.tool_executor`` already applies to its own concurrent tool
+    batch. This does not add or change any per-reference *timeout* (that is
+    ``reference_timeout`` / ``auxiliary.moa_reference.timeout``, resolved
+    elsewhere) — it only lets the caller stop waiting early. References
+    already in flight cannot be forcibly killed (``call_llm`` is a blocking
+    HTTP call with no interrupt hook of its own, same limitation
+    tool_executor has for tools without an interrupt check); an interrupted
+    reference's own timeout still reaps its thread independently. *agent* is
+    optional and defaults to ``None``, preserving the uninterruptible
+    blocking behavior for any caller that doesn't pass it.
     """
     from agent.usage_pricing import CanonicalUsage
 
@@ -421,7 +779,7 @@ def _run_references_parallel(
         return []
 
     results: list[tuple[str, str, Any] | None] = [None] * len(reference_models)
-    futures = {}
+    futures: dict[Any, int] = {}
     workers = min(_MAX_REFERENCE_WORKERS, len(reference_models))
     # Reference slots run on bare executor threads, which start with an empty
     # contextvars.Context — propagate the parent turn's context (approval
@@ -429,7 +787,16 @@ def _run_references_parallel(
     # advisor calls attribute to the same conversation as the acting turn.
     from tools.thread_context import propagate_context_to_thread
 
-    with ThreadPoolExecutor(max_workers=workers) as executor:
+    total = len(reference_models)
+    completed = 0
+    executor = ThreadPoolExecutor(max_workers=workers)
+    interrupted = False
+    # Per-fan-out context-length cache shared by every reference worker, so
+    # duplicate (provider, model) slots resolve their window once per turn
+    # instead of re-probing metadata sources per reference (dict get/set is
+    # GIL-atomic; a rare duplicate probe on a first-use race is harmless).
+    _ctx_len_cache: dict[tuple[str, str], int | None] = {}
+    try:
         for idx, slot in enumerate(reference_models):
             if slot.get("provider") == "moa":
                 results[idx] = (
@@ -445,12 +812,79 @@ def _run_references_parallel(
                     ref_messages,
                     temperature=temperature,
                     max_tokens=max_tokens,
+                    reference_timeout=reference_timeout,
+                    context_length_cache=_ctx_len_cache,
                 )
             ] = idx
+
         # Collect every reference before returning — the aggregator needs the
-        # complete set, so there is no early-exit / first-completed path here.
-        for future, idx in futures.items():
-            results[idx] = future.result()
+        # complete set, so there is no early-exit / first-completed path
+        # here, other than a user interrupt. Progress callbacks fire as each
+        # reference completes so frontends can render "MOA: k/n refs done".
+        pending = set(futures)
+        while pending:
+            done, pending = _futures_wait(pending, timeout=_REFERENCE_POLL_INTERVAL_S)
+            for future in done:
+                idx = futures[future]
+                results[idx] = future.result()
+                completed += 1
+                if progress_callback is not None:
+                    try:
+                        label = _slot_label(reference_models[idx])
+                        progress_callback(completed, total, label)
+                    except Exception as exc:  # pragma: no cover - display must never break
+                        logger.debug("MoA progress_callback failed: %s", exc)
+            if not pending:
+                break
+            if agent is not None and getattr(agent, "_interrupt_requested", False):
+                interrupted = True
+                break
+
+        if interrupted:
+            for future, idx in futures.items():
+                if results[idx] is not None:
+                    continue
+                if future.cancel():
+                    # Never dispatched — genuinely nothing was billed.
+                    results[idx] = (
+                        _slot_label(reference_models[idx]),
+                        _INTERRUPTED_REFERENCE_NOTE,
+                        _RefAccounting(CanonicalUsage()),
+                    )
+                elif future.done():
+                    # Finished between the interrupt check and now — the call
+                    # completed and billed, so keep its REAL output and
+                    # accounting rather than zeroing it with a placeholder.
+                    results[idx] = future.result()
+                else:
+                    # Already running — cannot be force-killed (see
+                    # docstring); leave it be so the caller isn't blocked,
+                    # and note that its output was abandoned. The provider
+                    # call is still in flight and WILL bill when it
+                    # completes, so hand its eventual accounting to the
+                    # caller's sink instead of silently dropping it.
+                    label = _slot_label(reference_models[idx])
+                    results[idx] = (
+                        label,
+                        _INTERRUPTED_REFERENCE_NOTE,
+                        _RefAccounting(CanonicalUsage()),
+                    )
+                    if late_accounting_sink is not None:
+                        def _record_late(f: Any, _label: str = label) -> None:
+                            try:
+                                _lbl, _txt, _acct = f.result()
+                            except Exception:  # pragma: no cover - defensive
+                                return
+                            try:
+                                late_accounting_sink(_label, _acct)
+                            except Exception:  # pragma: no cover - defensive
+                                logger.debug(
+                                    "MoA: late accounting sink failed for %s",
+                                    _label,
+                                )
+                        future.add_done_callback(_record_late)
+    finally:
+        executor.shutdown(wait=not interrupted, cancel_futures=interrupted)
 
     return [r for r in results if r is not None]
 
@@ -475,21 +909,35 @@ def _render_tool_calls(tool_calls: Any) -> str:
     The advisory view cannot carry real ``tool_calls`` payloads (strict
     providers reject tool_calls the reference never produced), so the agent's
     actions are flattened to text the reference can read and reason about.
+
+    Tolerates both dict-shaped and ``SimpleNamespace``-shaped entries (with a
+    nested ``function`` of either kind), so the helper works uniformly against
+    an OpenAI-style transport and against SDK-style stream-stitched responses.
+    Without this shape tolerance, a SimpleNamespace-sourced entry rendered as
+    ``[called tool: tool]`` and silently lost the function name.
     """
     lines: list[str] = []
     for tc in tool_calls or []:
-        fn = (tc.get("function") or {}) if isinstance(tc, dict) else {}
-        name = fn.get("name") or (tc.get("name") if isinstance(tc, dict) else "") or "tool"
-        args = fn.get("arguments")
-        if isinstance(args, str):
-            args_text = args
-        elif args is not None:
+        if isinstance(tc, dict):
+            fn = tc.get("function") or {}
+            fn_name = fn.get("name") if isinstance(fn, dict) else getattr(fn, "name", None)
+            fn_args = fn.get("arguments") if isinstance(fn, dict) else getattr(fn, "arguments", None)
+            top_name = tc.get("name")
+        else:
+            fn = getattr(tc, "function", None)
+            fn_name = getattr(fn, "name", None) if fn is not None else None
+            fn_args = getattr(fn, "arguments", None) if fn is not None else None
+            top_name = getattr(tc, "name", None)
+        name = fn_name or top_name or "tool"
+        if isinstance(fn_args, str):
+            args_text = fn_args
+        elif fn_args is not None:
             try:
                 import json
 
-                args_text = json.dumps(args, ensure_ascii=False)
+                args_text = json.dumps(fn_args, ensure_ascii=False)
             except Exception:
-                args_text = str(args)
+                args_text = str(fn_args)
         else:
             args_text = ""
         lines.append(f"[called tool: {name}({args_text})]" if args_text else f"[called tool: {name}]")
@@ -679,45 +1127,128 @@ def _preset_temperature(preset: dict[str, Any], key: str) -> float | None:
         return None
 
 
+def _is_failed_reference(text: str) -> bool:
+    """Return whether a reference output is an internal failure/skip sentinel.
+
+    Covers both the ``[failed: …]`` notes produced when a reference call
+    raises (which may embed raw provider error text) and the
+    ``[skipped: …]`` recursion-guard notes — neither is real advice, so
+    neither belongs in the aggregator prompt.
+    """
+    sentinel = text.lstrip().lower()
+    return sentinel.startswith("[failed:") or sentinel.startswith("[skipped:")
+
+
+def _successful_references(
+    reference_outputs: list[tuple[str, str, Any]],
+) -> list[tuple[str, str, Any]]:
+    """Filter failed advice while preserving each accounting payload."""
+    return [output for output in reference_outputs if not _is_failed_reference(output[1])]
+
+
+def _failed_reference_labels(
+    reference_outputs: list[tuple[str, str, Any]],
+) -> list[str]:
+    return [label for label, text, _accounting in reference_outputs if _is_failed_reference(text)]
+
+
+def _degraded_notice(failed_labels: list[str], policy: str) -> str:
+    if not failed_labels or policy.strip().lower() == "silent":
+        return ""
+    return f"[Reference models unavailable: {', '.join(failed_labels)}]"
+
+
 def aggregate_moa_context(
     *,
     user_prompt: str,
     api_messages: list[dict[str, Any]],
-    reference_models: list[dict[str, str]],
-    aggregator: dict[str, str],
+    reference_models: list[dict[str, Any]],
+    aggregator: dict[str, Any],
     temperature: float | None = None,
     aggregator_temperature: float | None = None,
-    max_tokens: int | None = None,
+    reference_max_tokens: int | None = None,
+    reference_timeout: float | None = None,
+    degraded_reference_policy: str = "loud",
+    agent: Any = None,
 ) -> str:
     """Run configured reference models and synthesize their advice.
 
     Failures are returned as model-specific notes instead of aborting the normal
     agent loop; the main model can still act with partial context.
 
-    ``max_tokens`` is ``None`` by default: MoA does not cap reference or
-    aggregator output, so each model uses its own maximum. ``call_llm`` omits
-    the parameter entirely when it is ``None`` (see its docstring), which also
-    sidesteps providers that reject ``max_tokens`` outright. A hardcoded cap
-    here previously truncated long aggregator syntheses.
+    ``reference_max_tokens`` applies ONLY to the reference fan-out — the
+    aggregator's own synthesis call is never capped, so it always uses its
+    model's own maximum. ``call_llm`` omits the parameter entirely when it
+    is ``None`` (see its docstring), which also sidesteps providers that
+    reject ``max_tokens`` outright. A hardcoded cap on the aggregator call
+    previously truncated long aggregator syntheses (#53580) — passing
+    ``reference_max_tokens`` to both calls here would silently reintroduce
+    that regression.
 
     ``temperature`` / ``aggregator_temperature`` are ``None`` by default:
-    like max_tokens, ``call_llm`` omits temperature when None so the
-    provider default applies — matching single-model agent behavior. Presets
-    may still pin explicit values.
+    like ``reference_max_tokens``, ``call_llm`` omits temperature when None
+    so the provider default applies — matching single-model agent behavior.
+    Presets may still pin explicit values.
+
+    ``agent``, when passed, lets the reference fan-out be aborted early on a
+    user interrupt — see ``_run_references_parallel``'s docstring.
     """
+    reference_models = [slot for slot in reference_models if slot.get("enabled", True)]
     reference_outputs: list[tuple[str, str, Any]] = []
     ref_messages = _reference_messages(api_messages)
     reference_outputs = _run_references_parallel(
         reference_models,
         ref_messages,
         temperature=temperature,
-        max_tokens=max_tokens,
+        max_tokens=reference_max_tokens,
+        reference_timeout=reference_timeout,
+        agent=agent,
     )
 
+    successful_outputs = _successful_references(reference_outputs)
+    failed_labels = _failed_reference_labels(reference_outputs)
+
+    # 'full' privacy mode (moa.privacy_filter) also covers this one-shot /moa
+    # synthesis path: advisor text is redacted before it reaches the
+    # synthesizing aggregator. 'display' does not apply here — this path has
+    # no user-visible reference blocks or trace records of its own. Redaction
+    # runs on the successful outputs only (failed refs are already filtered
+    # into the degraded notice).
+    try:
+        from hermes_cli.config import load_config as _load_config
+
+        if _moa_privacy_mode((_load_config() or {}).get("moa")) == "full":
+            successful_outputs = _redact_reference_outputs(successful_outputs)
+    except Exception:  # pragma: no cover - privacy filter must never break a turn
+        logger.debug("MoA privacy filter check failed", exc_info=True)
+
     joined = "\n\n".join(
         f"Reference {idx} — {label}:\n{text}"
-        for idx, (label, text, _usage) in enumerate(reference_outputs, start=1)
+        for idx, (label, text, _accounting) in enumerate(successful_outputs, start=1)
     )
+    degraded = _degraded_notice(failed_labels, degraded_reference_policy)
+    if degraded:
+        joined = f"{joined}\n\n{degraded}" if joined else degraded
+
+    # Skip the aggregator call when every reference failed or was skipped —
+    # synthesising over zero real advice wastes tokens and can block for the
+    # full provider timeout (observed: ~6 min on SenseNova) before returning
+    # a non-retryable error that leaves the session hanging. The early return
+    # carries only the sanitized unavailability notice (never raw provider
+    # error text) so the main agent loop can still act in single-model mode.
+    if reference_outputs and not successful_outputs:
+        logger.warning(
+            "MoA: all %d reference(s) failed — skipping aggregator synthesis",
+            len(reference_outputs),
+        )
+        notice = degraded or "[Reference models unavailable]"
+        return (
+            "[Mixture of Agents context — all reference models failed. "
+            "Proceeding without aggregated guidance.]\n"
+            f"References: {', '.join(_slot_label(slot) for slot in reference_models)}\n\n"
+            f"{notice}"
+        )
+
     synth_prompt = (
         "You are the aggregator in a Mixture of Agents process. Synthesize the "
         "reference responses into concise, actionable guidance for the main "
@@ -748,7 +1279,6 @@ def aggregate_moa_context(
             task="moa_aggregator",
             messages=agg_messages,
             temperature=aggregator_temperature,
-            max_tokens=max_tokens,
             reasoning_config=_aggregator_reasoning_config(aggregator),
             **agg_runtime,
         )
@@ -810,7 +1340,7 @@ def _attach_reference_guidance(agg_messages: list[dict[str, Any]], guidance: str
 class MoAChatCompletions:
     """OpenAI-chat-compatible facade where the aggregator is the acting model."""
 
-    def __init__(self, preset_name: str, reference_callback: Any = None):
+    def __init__(self, preset_name: str, reference_callback: Any = None, agent: Any = None):
         self.preset_name = preset_name or "default"
         # Optional display hook. Called as reference outputs become available so
         # frontends can show each reference model's answer as a labelled block
@@ -818,9 +1348,22 @@ class MoAChatCompletions:
         #   reference_callback(event, **kwargs)
         # where event is one of:
         #   "moa.reference"   kwargs: index, count, label, text
+        #   "moa.progress"    kwargs: refs_done, refs_total, label
+        #                       (fired once per reference completion — drives
+        #                        status-bar progress like ``MOA: 2/3 refs done``)
+        #   "moa.phase"       kwargs: phase, refs_done, refs_total, aggregator
+        #                       (fired on phase transitions, currently
+        #                        phase="aggregator" right before the aggregator
+        #                        acts; phase="reference" mirrors ``moa.progress``
+        #                        so listeners can rely on a single event family)
         #   "moa.aggregating" kwargs: aggregator (label), ref_count
         # Never raises into the model call — display is best-effort.
         self.reference_callback = reference_callback
+        # Back-reference to the owning AIAgent, so the reference fan-out can
+        # check agent._interrupt_requested (see _run_references_parallel).
+        # Optional — a caller that doesn't pass it just keeps the fan-out
+        # uninterruptible, as it was before.
+        self._agent = agent
         # State-scoped reference cache. The agent loop calls create() once per
         # tool-loop iteration; references should re-run whenever the task STATE
         # advances — i.e. on every new user message AND every new tool result —
@@ -842,6 +1385,10 @@ class MoAChatCompletions:
 
         self._pending_reference_usage: Any = CanonicalUsage()
         self._pending_reference_cost: Any = None
+        # Guards pending usage/cost against concurrent late-accounting
+        # callbacks (see _record_late_reference_accounting), which fire on
+        # executor worker threads after an interrupted fan-out returns.
+        self._accounting_lock = threading.Lock()
         # Resolved aggregator slot ({provider, model, ...}) from the most recent
         # create(); read by session cost accounting to price the aggregator's
         # acting turn at its real model instead of the virtual preset name.
@@ -850,6 +1397,18 @@ class MoAChatCompletions:
         # caller to stitch in the live session_id + resolved aggregator output
         # and flush to the trace file (only when moa.save_traces is on).
         self._pending_trace: Any = None
+        # every_n fan-out cadence state. The iteration counter is scoped to a
+        # single USER TURN (not the facade lifetime): it counts create() calls
+        # since the last new user message and resets whenever the user-turn
+        # signature changes, so cadence position never leaks across turns —
+        # iteration 1 of every turn is always on-cadence (fresh advice for a
+        # fresh request). See the fanout handling in create().
+        self._fanout_iteration_count = 0
+        self._fanout_turn_sig: str | None = None
+        self._fanout_last_state_sig: str | None = None
+        # Normalized moa.privacy_filter mode for the current turn ('' |
+        # 'display' | 'full'), refreshed from config on every create().
+        self._privacy_mode: str = ""
 
     def consume_reference_usage(self) -> tuple[Any, Any]:
         """Pop pending reference-fan-out usage + cost, resetting both to empty.
@@ -862,12 +1421,42 @@ class MoAChatCompletions:
         """
         from agent.usage_pricing import CanonicalUsage
 
-        usage = self._pending_reference_usage or CanonicalUsage()
-        cost = self._pending_reference_cost
-        self._pending_reference_usage = CanonicalUsage()
-        self._pending_reference_cost = None
+        with self._accounting_lock:
+            usage = self._pending_reference_usage or CanonicalUsage()
+            cost = self._pending_reference_cost
+            self._pending_reference_usage = CanonicalUsage()
+            self._pending_reference_cost = None
         return usage, cost
 
+    def _record_late_reference_accounting(self, label: str, accounting: Any) -> None:
+        """Fold a late-completing interrupted reference's real spend in.
+
+        When a user interrupt aborts the fan-out wait, references already in
+        flight keep running (they cannot be force-killed) and DO bill when
+        they complete. Their placeholder results carry zeroed accounting, so
+        without this hook that spend would vanish from session accounting.
+        The fan-out registers this as a done-callback on abandoned futures;
+        it folds the eventual real usage/cost into the pending totals, where
+        the next ``consume_reference_usage`` pick-up records it. Thread-safe:
+        done-callbacks fire on executor worker threads.
+        """
+        from agent.usage_pricing import CanonicalUsage
+
+        if not isinstance(accounting, _RefAccounting):
+            return
+        with self._accounting_lock:
+            if isinstance(accounting.usage, CanonicalUsage):
+                self._pending_reference_usage = (
+                    self._pending_reference_usage or CanonicalUsage()
+                ) + accounting.usage
+            if accounting.cost_usd is not None:
+                self._pending_reference_cost = (
+                    self._pending_reference_cost or 0
+                ) + accounting.cost_usd
+        logger.debug(
+            "MoA: recorded late accounting for interrupted reference %s", label
+        )
+
     def consume_and_save_trace(
         self, session_id: Any = None, aggregator_output_fallback: Any = None
     ) -> None:
@@ -965,9 +1554,17 @@ class MoAChatCompletions:
         extra_body: Any = agg_kwargs.get("extra_body")
         # Record the exact aggregator INPUT (incl. the injected reference
         # context) into the pending trace so a trace captures what the
-        # aggregator actually saw, not a reconstruction.
+        # aggregator actually saw, not a reconstruction. Traces are a
+        # persisted surface: when the privacy filter is active, the stored
+        # COPY is redacted ('display' mode's live aggregator input stays raw —
+        # only the on-disk record is filtered; 'full' mode's input is already
+        # redacted upstream, so this is a near no-op there).
         if self._pending_trace is not None:
-            self._pending_trace["aggregator_input_messages"] = agg_messages
+            self._pending_trace["aggregator_input_messages"] = (
+                _redact_trace_messages([dict(m) for m in agg_messages])
+                if getattr(self, "_privacy_mode", "")
+                else agg_messages
+            )
             self._pending_trace["aggregator_label"] = _slot_label(aggregator)
         # The aggregator is the acting model. Resolve its slot to the provider's
         # real runtime (base_url/api_key/api_mode) and call it through the same
@@ -1043,9 +1640,20 @@ class MoAChatCompletions:
         from hermes_cli.config import load_config
         from hermes_cli.moa_config import resolve_moa_preset
 
-        preset = resolve_moa_preset(load_config().get("moa") or {}, self.preset_name)
+        _moa_raw = load_config().get("moa") or {}
+        preset = resolve_moa_preset(_moa_raw, self.preset_name)
+        # Privacy filter mode: '' (off, default) | 'display' | 'full'. See
+        # coerce_privacy_filter / the pattern block at the top of this module.
+        # Remembered on self so _call_prepared_aggregator (which may run on a
+        # later prepared-request call without re-reading config) redacts the
+        # trace's aggregator input consistently with this turn's fan-out.
+        privacy_mode = _moa_privacy_mode(_moa_raw)
+        self._privacy_mode = privacy_mode
         messages = list(api_kwargs.get("messages") or [])
-        reference_models = preset.get("reference_models") or []
+        reference_models = [
+            slot for slot in (preset.get("reference_models") or [])
+            if slot.get("enabled", True)
+        ]
         aggregator = preset.get("aggregator") or {}
         # Expose the resolved aggregator slot so session cost accounting can
         # price the aggregator's acting turn at its REAL model/provider. The
@@ -1070,6 +1678,16 @@ class MoAChatCompletions:
         # explicit values. See _preset_temperature.
         temperature = _preset_temperature(preset, "reference_temperature")
         aggregator_temperature = _preset_temperature(preset, "aggregator_temperature")
+        # None (the default) = no per-preset override; the fan-out inherits
+        # auxiliary.moa_reference.timeout (900s default) via call_llm's own
+        # per-task timeout resolution. Explicit per-preset values are honored.
+        raw_reference_timeout = preset.get("reference_timeout")
+        reference_timeout = (
+            float(raw_reference_timeout) if raw_reference_timeout else None
+        )
+        degraded_reference_policy = str(
+            preset.get("degraded_reference_policy") or "loud"
+        )
         if aggregator_temperature is None and api_kwargs.get("temperature") is not None:
             # The acting agent's own configured temperature (if any) still
             # applies to the aggregator, which IS the acting model.
@@ -1086,17 +1704,39 @@ class MoAChatCompletions:
         reference_outputs: list[tuple[str, str, Any]] = []
         ref_messages = _reference_messages(messages)
 
-        # Fan-out cadence. "per_iteration" (default): advisors re-run whenever
-        # the advisory view changes — i.e. every tool iteration, since the
-        # view grows with each tool result. "user_turn": advisors run ONCE per
-        # user turn; subsequent tool iterations reuse that turn's advice and
-        # the aggregator acts alone (the original MoA shape: synthesize at the
-        # start, then let the acting model work). Implemented by hashing only
-        # the prefix up to the LAST USER message so mid-turn growth doesn't
-        # change the signature — iteration 2+ becomes a cache HIT.
-        fanout_mode = str(preset.get("fanout") or "per_iteration").strip().lower()
+        # Fan-out cadence. "user_turn" (default — cheapest cadence, #67199):
+        # advisors run ONCE per user turn; subsequent tool iterations reuse
+        # that turn's advice and the aggregator acts alone (the original MoA
+        # shape: synthesize at the start, then let the acting model work).
+        # Implemented by hashing only the prefix up to the LAST USER message
+        # so mid-turn growth doesn't change the signature — iteration 2+
+        # becomes a cache HIT. "per_iteration": advisors re-run whenever the
+        # advisory view changes — i.e. every tool iteration, since the view
+        # grows with each tool result; advice tracks live task state at the
+        # cost of multiplying advisor latency/spend by tool-loop depth.
+        # "every_n:<N>" (N >= 2): the middle ground (issue #63393 — advisor
+        # fan-out multiplies latency/cost by the tool-iteration count).
+        # Advisors run on iteration 1 of a user turn and then every Nth tool
+        # iteration; the iterations in between REUSE the cached guidance from
+        # the last on-cadence run (same mechanism as user_turn's cache HIT —
+        # the aggregator still gets advice every iteration, it's just not
+        # refreshed against the very latest tool results). The iteration
+        # counter is scoped per user turn and resets on a new user message,
+        # so every turn starts with fresh advice.
+        fanout_mode = str(preset.get("fanout") or "user_turn").strip().lower()
+        every_n = 0
+        if fanout_mode.startswith("every_n:"):
+            try:
+                every_n = int(fanout_mode.split(":", 1)[1])
+            except (TypeError, ValueError):
+                every_n = 0
+            if every_n < 2:
+                # every_n:1 semantically IS per-iteration; degrade there,
+                # mirroring _coerce_fanout's collapse of degenerate N.
+                fanout_mode = "per_iteration"
         sig_messages = ref_messages
-        if fanout_mode == "user_turn":
+        turn_prefix = ref_messages
+        if fanout_mode in ("user_turn",) or every_n >= 2:
             # Find the last REAL user message. The advisory view appends a
             # synthetic user marker (_ADVISORY_INSTRUCTION) when it ends on an
             # assistant turn — i.e. on every tool iteration after the first —
@@ -1111,19 +1751,51 @@ class MoAChatCompletions:
                     last_user_idx = _i
                     break
             if last_user_idx is not None:
-                sig_messages = ref_messages[: last_user_idx + 1]
+                turn_prefix = ref_messages[: last_user_idx + 1]
+            if fanout_mode == "user_turn":
+                sig_messages = turn_prefix
+
+        def _hash_messages(msgs: list[dict[str, Any]]) -> str:
+            return hashlib.sha256(
+                "\u0000".join(
+                    f"{m.get('role')}:{m.get('content')}" for m in msgs
+                ).encode("utf-8", "replace")
+            ).hexdigest()
+
+        # every_n cadence bookkeeping: advance the per-turn iteration counter
+        # only when the advisory STATE actually advanced (a redundant create()
+        # with identical state — e.g. a streaming retry — must not consume a
+        # cadence slot), and reset it whenever the user-turn prefix changes.
+        _every_n_reuse = False
+        if every_n >= 2:
+            _turn_sig = _hash_messages(turn_prefix)
+            if _turn_sig != self._fanout_turn_sig:
+                self._fanout_turn_sig = _turn_sig
+                self._fanout_iteration_count = 0
+                self._fanout_last_state_sig = None
+            _state_sig = _hash_messages(ref_messages)
+            if _state_sig != self._fanout_last_state_sig:
+                self._fanout_last_state_sig = _state_sig
+                self._fanout_iteration_count += 1
+            # Iteration 1 is on-cadence; then every Nth iteration after it.
+            _on_cadence = (self._fanout_iteration_count - 1) % every_n == 0
+            _every_n_reuse = not _on_cadence and bool(self._ref_cache_outputs)
 
         # Turn-scoped cache: only run + display references when the advisory
         # view changed (i.e. a new user turn). Within one turn the agent loop
         # calls create() once per tool iteration; in user_turn mode the
         # signature is stable across those iterations (prefix hash above), so
         # the fan-out runs once per user turn and iterations reuse the advice.
-        _sig = hashlib.sha256(
-            "\u0000".join(
-                f"{m.get('role')}:{m.get('content')}" for m in sig_messages
-            ).encode("utf-8", "replace")
-        ).hexdigest()
+        _sig = _hash_messages(sig_messages)
         _cache_key = (self.preset_name, _sig, tuple(_slot_label(s) for s in reference_models))
+        if _every_n_reuse:
+            # Off-cadence every_n iteration: pin the key to the last
+            # on-cadence run so the lookup below is a HIT and its guidance is
+            # reused (no advisor calls, no double accounting, no re-emit) —
+            # exactly the user_turn cache-HIT path. When the cache is empty
+            # (defensive; a new turn resets the counter to on-cadence) the
+            # flag above stays False and the references run normally.
+            _cache_key = self._ref_cache_key
         _refs_from_cache = _cache_key == self._ref_cache_key and bool(self._ref_cache_outputs)
 
         if _refs_from_cache:
@@ -1131,22 +1803,54 @@ class MoAChatCompletions:
             # References already ran (and were accounted) earlier this turn;
             # this create() is a repeat tool-iteration reusing the cached
             # advice. Charging their tokens/cost again here would multiply
-            # advisor spend by the tool-iteration count, so pending is zero.
-            self._pending_reference_usage = CanonicalUsage()
-            self._pending_reference_cost = None
+            # advisor spend by the tool-iteration count, so nothing new is
+            # deposited — but do NOT zero the pending totals: a
+            # late-completing interrupted reference may have deposited its
+            # real spend since the last consume(), and that must survive
+            # until the next consume_reference_usage() pick-up.
             # Likewise no trace on a cache HIT — the full turn was already
             # traced on the MISS that ran the references. A repeat iteration is
             # not a new MoA turn.
             self._pending_trace = None
         else:
+            # Per-reference progress callback: emits ``moa.progress`` so
+            # listeners can render ``MOA: N/M refs done`` in the status bar as
+            # each reference completes. The callback is bound to self so it
+            # goes through the same display hook as the existing
+            # ``moa.reference`` / ``moa.aggregating`` events.
+            def _progress(done: int, total: int, label: str) -> None:
+                self._emit(
+                    "moa.progress",
+                    refs_done=done,
+                    refs_total=total,
+                    label=label,
+                )
+
             reference_outputs = _run_references_parallel(
                 reference_models,
                 ref_messages,
                 temperature=temperature,
                 max_tokens=reference_max_tokens,
+                progress_callback=_progress,
+                reference_timeout=reference_timeout,
+                agent=self._agent,
+                late_accounting_sink=self._record_late_reference_accounting,
             )
-            self._ref_cache_key = _cache_key
-            self._ref_cache_outputs = list(reference_outputs)
+            interrupted_any = any(
+                text == _INTERRUPTED_REFERENCE_NOTE
+                for _lbl, text, _acct in reference_outputs
+            )
+            if interrupted_any:
+                # An interrupted fan-out is a partial snapshot, not real
+                # advice for this state. Caching it would replay the
+                # placeholder notes on every subsequent iteration of the
+                # turn (a cache HIT never re-runs the references), so leave
+                # the cache empty and let the next create() re-run them.
+                self._ref_cache_key = None
+                self._ref_cache_outputs = []
+            else:
+                self._ref_cache_key = _cache_key
+                self._ref_cache_outputs = list(reference_outputs)
             # Sum the advisor fan-out's token usage AND cost so the caller can
             # fold advisor spend into session accounting exactly once per turn.
             # Only the freshly run references (cache MISS) contribute; a cache
@@ -1163,16 +1867,35 @@ class MoAChatCompletions:
                         _ref_usage = _ref_usage + _acct.usage
                     if _acct.cost_usd is not None:
                         _ref_cost = (_ref_cost or 0) + _acct.cost_usd
-            self._pending_reference_usage = _ref_usage
-            self._pending_reference_cost = _ref_cost
+            with self._accounting_lock:
+                # Fold (don't overwrite): a late-completing interrupted
+                # reference from a PREVIOUS turn may have deposited its real
+                # spend here between consume() calls — keep it.
+                self._pending_reference_usage = (
+                    self._pending_reference_usage or CanonicalUsage()
+                ) + _ref_usage
+                if _ref_cost is not None:
+                    self._pending_reference_cost = (
+                        self._pending_reference_cost or 0
+                    ) + _ref_cost
             # Stash the full reference fan-out for trace persistence. The
             # aggregator input/label are filled in below once agg_messages is
             # built; the aggregator OUTPUT is stitched in by the caller
             # (consume_and_save_trace) once the response resolves — the caller
             # holds the live session_id and the resolved aggregator response.
+            # Traces are a persisted, user-readable surface, so ANY active
+            # privacy mode ('display' or 'full') redacts the advisor text and
+            # the full per-advisor input/output carried by _RefAccounting.
+            if privacy_mode:
+                _trace_refs = [
+                    (label, _redact_reference_text(text), _redact_trace_accounting(acct))
+                    for label, text, acct in reference_outputs
+                ]
+            else:
+                _trace_refs = list(reference_outputs)
             self._pending_trace = {
                 "preset": self.preset_name,
-                "reference_outputs": list(reference_outputs),
+                "reference_outputs": _trace_refs,
                 "aggregator_slot": aggregator,
                 "aggregator_temperature": aggregator_temperature,
             }
@@ -1182,17 +1905,31 @@ class MoAChatCompletions:
             # actually ran them). The user sees one labelled block per
             # reference (rendered like a thinking block) so the MoA process is
             # visible rather than a silent pause. Best-effort: never blocks the
-            # turn.
+            # turn. Reference blocks are a user-visible surface: both privacy
+            # modes redact them (the cache keeps the RAW text — redaction
+            # always happens at the consuming surface, so a mid-session mode
+            # change never leaks or double-redacts).
             _ref_count = len(reference_outputs)
-            for _idx, (_label, _text, _usage) in enumerate(reference_outputs, start=1):
+            for _idx, (_label, _text, _accounting) in enumerate(reference_outputs, start=1):
                 self._emit(
                     "moa.reference",
                     index=_idx,
                     count=_ref_count,
                     label=_label,
-                    text=_text,
+                    text=_redact_reference_text(_text) if privacy_mode else _text,
                 )
             if _ref_count:
+                # Phase transition: reference fan-out is complete, the
+                # aggregator is about to act. Listeners that prefer a single
+                # event family for phase tracking can switch on ``phase``
+                # instead of subscribing to ``moa.aggregating`` separately.
+                self._emit(
+                    "moa.phase",
+                    phase="aggregator",
+                    refs_done=_ref_count,
+                    refs_total=_ref_count,
+                    aggregator=_slot_label(aggregator),
+                )
                 self._emit(
                     "moa.aggregating",
                     aggregator=_slot_label(aggregator),
@@ -1201,16 +1938,58 @@ class MoAChatCompletions:
 
         guidance: str | None = None
         agg_messages = [dict(m) for m in messages]
-        if reference_outputs:
+        successful_outputs = _successful_references(reference_outputs)
+        failed_labels = _failed_reference_labels(reference_outputs)
+        joined = ""
+        _agg_refs: list = []
+        if successful_outputs:
+            # 'full' privacy mode: redact the advisor text that reaches the
+            # AGGREGATOR too (issue #59959's literal ask). 'display' leaves
+            # the aggregator input raw so synthesis quality is unaffected.
+            # The redaction is applied to a per-call copy — the cache always
+            # holds raw advisor text (see the emit comment above). Failed
+            # refs are already filtered out; only successful advisor text is
+            # joined (and redacted when requested).
+            _agg_refs = (
+                _redact_reference_outputs(successful_outputs)
+                if privacy_mode == "full"
+                else successful_outputs
+            )
             joined = "\n\n".join(
                 f"Reference {idx} — {label}:\n{text}"
-                for idx, (label, text, _usage) in enumerate(reference_outputs, start=1)
+                for idx, (label, text, _usage) in enumerate(_agg_refs, start=1)
             )
+        degraded = _degraded_notice(failed_labels, degraded_reference_policy)
+        if reference_outputs and not successful_outputs:
+            # Every reference failed or was skipped: don't wrap a wall of
+            # failure sentinels in "use the reference responses below"
+            # guidance — the aggregator IS the acting model, so it simply
+            # acts alone this turn. Under the loud policy it still gets the
+            # sanitized unavailability notice so it can disclose degraded
+            # mode; under silent it gets nothing.
+            logger.warning(
+                "MoA: all %d reference(s) failed — acting aggregator-alone "
+                "without reference guidance",
+                len(reference_outputs),
+            )
+            if degraded:
+                guidance = (
+                    "[Mixture of Agents reference context]\n"
+                    f"Preset: {self.preset_name}\n"
+                    f"Aggregator/acting model: {_slot_label(aggregator)}\n\n"
+                    "All reference models failed this turn — no advisory "
+                    "guidance is available. Act on your own judgment.\n\n"
+                    f"{degraded}"
+                )
+                _attach_reference_guidance(agg_messages, guidance)
+        elif joined or degraded:
+            if degraded:
+                joined = f"{joined}\n\n{degraded}" if joined else degraded
             guidance = (
                 "[Mixture of Agents reference context]\n"
                 f"Preset: {self.preset_name}\n"
                 f"Aggregator/acting model: {_slot_label(aggregator)}\n"
-                f"References: {', '.join(label for label, _, _ in reference_outputs)}\n\n"
+                f"References: {', '.join(label for label, _, _ in _agg_refs)}\n\n"
                 "Use the reference responses below as private context. You are the aggregator and acting model: "
                 "answer the user directly or call tools as needed.\n\n"
                 f"{joined}"
@@ -1229,9 +2008,11 @@ class MoAChatCompletions:
 
 
 class MoAClient:
-    def __init__(self, preset_name: str, reference_callback: Any = None):
+    def __init__(self, preset_name: str, reference_callback: Any = None, agent: Any = None):
         self.chat = type("_MoAChat", (), {})()
-        self.chat.completions = MoAChatCompletions(preset_name, reference_callback=reference_callback)
+        self.chat.completions = MoAChatCompletions(
+            preset_name, reference_callback=reference_callback, agent=agent,
+        )
 
     def consume_reference_usage(self) -> Any:
         """Pop the pending reference-fan-out usage from the completions facade.
@@ -1261,3 +2042,85 @@ class MoAClient:
         return self.chat.completions.consume_and_save_trace(
             session_id, aggregator_output_fallback=aggregator_output_fallback
         )
+
+
+def build_moa_facade(agent, preset_name: Any = None) -> MoAClient:
+    """Build the MoA facade client for ``agent``, wiring the reference relay.
+
+    Single construction point for ``MoAClient`` wherever the agent's shared
+    client is (re)built: initial setup (``agent_init``), turn-start fallback
+    restore (``restore_primary_runtime``), transient transport recovery
+    (``try_recover_primary_transport``), and mid-session model switches
+    (``switch_model``).
+
+    Constructing a bare ``MoAClient(preset)`` at any of those sites silently
+    drops the ``reference_callback`` relay that ``agent_init`` wires to
+    ``agent.tool_progress_callback`` — after a fallback+restore cycle the
+    facade would still work, but every frontend (CLI spinner, TUI, desktop,
+    gateway) would stop receiving ``moa.reference`` / ``moa.aggregating``
+    display events for the rest of the session (#53802).
+
+    The relay reads ``agent.tool_progress_callback`` at *emit* time, so a
+    callback attached after client construction is picked up automatically.
+    Best-effort and display-only — it never raises into the model call.
+    """
+    def _moa_reference_relay(event: str, **kwargs: Any) -> None:
+        cb = getattr(agent, "tool_progress_callback", None)
+        if cb is None:
+            return
+        try:
+            if event == "moa.reference":
+                label = str(kwargs.get("label") or "")
+                text = str(kwargs.get("text") or "")
+                idx = kwargs.get("index")
+                count = kwargs.get("count")
+                cb(
+                    "moa.reference",
+                    label,
+                    text,
+                    None,
+                    moa_index=idx,
+                    moa_count=count,
+                )
+            elif event == "moa.progress":
+                # Per-reference completion. Frontends render this as a
+                # status-bar progress indicator like ``MOA: N/M refs done``.
+                cb(
+                    "moa.progress",
+                    str(kwargs.get("label") or ""),
+                    None,
+                    None,
+                    moa_refs_done=kwargs.get("refs_done"),
+                    moa_refs_total=kwargs.get("refs_total"),
+                )
+            elif event == "moa.phase":
+                # Phase transition (currently only ``phase="aggregator"``
+                # fires once the fan-out is done). Subscribers can switch
+                # on ``moa_phase`` to know which phase is active.
+                cb(
+                    "moa.phase",
+                    str(kwargs.get("aggregator") or ""),
+                    None,
+                    None,
+                    moa_phase=kwargs.get("phase"),
+                    moa_refs_done=kwargs.get("refs_done"),
+                    moa_refs_total=kwargs.get("refs_total"),
+                )
+            elif event == "moa.aggregating":
+                cb(
+                    "moa.aggregating",
+                    str(kwargs.get("aggregator") or ""),
+                    None,
+                    None,
+                    moa_ref_count=kwargs.get("ref_count"),
+                )
+        except Exception:
+            pass
+
+    return MoAClient(
+        str(preset_name or getattr(agent, "model", None) or "default"),
+        reference_callback=_moa_reference_relay,
+        # Thread the agent through so the reference fan-out wait can be
+        # aborted on a user interrupt (see _run_references_parallel).
+        agent=agent,
+    )
diff --git a/agent/model_metadata.py b/agent/model_metadata.py
index 288083628e0..296fe0aedca 100644
--- a/agent/model_metadata.py
+++ b/agent/model_metadata.py
@@ -215,6 +215,7 @@ DEFAULT_CONTEXT_LENGTHS = {
     # OpenRouter-prefixed models resolve via OpenRouter live API or models.dev.
     "claude-fable-5": 1000000,
     "claude-fable": 1000000,
+    "claude-opus-5": 1000000,
     "claude-sonnet-5": 1000000,
     "claude-opus-4-8": 1000000,
     "claude-opus-4.8": 1000000,
diff --git a/agent/nous_rate_guard.py b/agent/nous_rate_guard.py
index 415d367ca17..0234eef2ea2 100644
--- a/agent/nous_rate_guard.py
+++ b/agent/nous_rate_guard.py
@@ -117,7 +117,7 @@ def record_nous_rate_limit(
         # Atomic write: write to temp file + rename
         fd, tmp_path = tempfile.mkstemp(dir=state_dir, suffix=".tmp")
         try:
-            with os.fdopen(fd, "w") as f:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
                 json.dump(state, f)
             atomic_replace(tmp_path, path)
         except Exception:
diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py
index fc94ca2a6b2..845e4260ddb 100644
--- a/agent/prompt_builder.py
+++ b/agent/prompt_builder.py
@@ -192,7 +192,13 @@ SKILLS_GUIDANCE = (
     "skill with skill_manage so you can reuse it next time.\n"
     "When using a skill and finding it outdated, incomplete, or wrong, "
     "patch it immediately with skill_manage(action='patch') — don't wait to be asked. "
-    "Skills that aren't maintained become liabilities."
+    "Skills that aren't maintained become liabilities.\n"
+    "\n"
+    "## Skill Safety Rule\n"
+    "1. **UNAVAILABLE** — If a skill placeholder contains `[SKILL_PRUNED]`, the skill content was lost in compression and is inaccessible.\n"
+    "2. **RELOAD** — Before performing any action that depends on a skill, re-check its content with `skill_view(name='...')` if it shows `[SKILL_PRUNED]`.\n"
+    "3. **WAIT** — If a skill is loading or was just pruned, wait for the reload confirmation before proceeding.\n"
+    "4. **DEDUP** — After reloading a pruned skill, **ignore any remaining `[SKILL_PRUNED]` markers for that same skill** — they are historical artifacts from previous compactions and do not need further action."
 )
 
 KANBAN_GUIDANCE = (
diff --git a/agent/prompt_caching.py b/agent/prompt_caching.py
index 9a2fdf4ccce..09b51e61d01 100644
--- a/agent/prompt_caching.py
+++ b/agent/prompt_caching.py
@@ -1,9 +1,11 @@
 """Anthropic prompt caching strategy.
 
-Single layout: ``system_and_3``. 4 cache_control breakpoints — system
-prompt + last 3 non-system messages, all at the same TTL (5m or 1h).
-Reduces input token costs by ~75% on multi-turn conversations within a
-single session.
+The default layout uses 4 cache_control breakpoints: the static system
+prefix, the end of the system prompt, and the last 2 non-system messages.
+When a static system prefix is unavailable, it falls back to one system
+breakpoint plus the last 3 messages. All markers use the same TTL (5m or 1h).
+This preserves intra-session caching while allowing new sessions to reuse the
+stable system-prompt prefix.
 
 Pure functions -- no class state, no AIAgent dependency.
 """
@@ -81,15 +83,55 @@ def _build_marker(ttl: str) -> Dict[str, str]:
     return marker
 
 
+def _apply_system_cache_markers(
+    message: dict,
+    cache_marker: dict,
+    static_system_prefix: str | None,
+    *,
+    native_anthropic: bool,
+) -> int:
+    """Mark the static system prefix and full prompt when they can be split.
+
+    The system prompt remains one stored string. Splitting it only in the
+    outgoing request keeps session persistence and non-Anthropic transports
+    unchanged while making the stable prefix independently cacheable.
+    """
+    content = message.get("content")
+    if (
+        isinstance(static_system_prefix, str)
+        and static_system_prefix
+        and isinstance(content, str)
+        and content.startswith(static_system_prefix)
+    ):
+        suffix = content[len(static_system_prefix):]
+        if suffix:
+            message["content"] = [
+                {
+                    "type": "text",
+                    "text": static_system_prefix,
+                    "cache_control": cache_marker,
+                },
+                {"type": "text", "text": suffix, "cache_control": cache_marker},
+            ]
+            return 2
+
+    _apply_cache_marker(message, cache_marker, native_anthropic=native_anthropic)
+    return 1
+
+
 def apply_anthropic_cache_control(
     api_messages: List[Dict[str, Any]],
     cache_ttl: str = "5m",
     native_anthropic: bool = False,
+    static_system_prefix: str | None = None,
 ) -> List[Dict[str, Any]]:
-    """Apply system_and_3 caching strategy to messages for Anthropic models.
+    """Apply Anthropic cache-control markers to API messages.
 
-    Places up to 4 cache_control breakpoints: system prompt + last 3 non-system
-    messages, all at the same TTL.
+    When ``static_system_prefix`` exactly matches the beginning of a string
+    system prompt, it receives an early marker and the full system prompt gets
+    a trailing marker. The remaining two markers target the latest cacheable
+    non-system messages. Without that prefix, the legacy system-and-3 layout
+    is retained.
 
     Returns:
         Deep copy of messages with cache_control breakpoints injected.
@@ -103,8 +145,12 @@ def apply_anthropic_cache_control(
     breakpoints_used = 0
 
     if messages[0].get("role") == "system":
-        _apply_cache_marker(messages[0], marker, native_anthropic=native_anthropic)
-        breakpoints_used += 1
+        breakpoints_used = _apply_system_cache_markers(
+            messages[0],
+            marker,
+            static_system_prefix,
+            native_anthropic=native_anthropic,
+        )
 
     remaining = 4 - breakpoints_used
     non_sys = [
diff --git a/agent/proxy_sources/__init__.py b/agent/proxy_sources/__init__.py
new file mode 100644
index 00000000000..34af31ca6fb
--- /dev/null
+++ b/agent/proxy_sources/__init__.py
@@ -0,0 +1,8 @@
+"""Egress proxy integrations.
+
+Currently ships an iron-proxy (ironsh/iron-proxy) wrapper that intercepts
+outbound traffic from remote terminal sandboxes and swaps proxy tokens
+for real upstream credentials at the network edge.
+
+Design notes live in :mod:`agent.proxy_sources.iron_proxy`.
+"""
diff --git a/agent/proxy_sources/iron_proxy.py b/agent/proxy_sources/iron_proxy.py
new file mode 100644
index 00000000000..277cd018654
--- /dev/null
+++ b/agent/proxy_sources/iron_proxy.py
@@ -0,0 +1,2494 @@
+"""iron-proxy (`ironsh/iron-proxy`) integration for credential-injecting egress control.
+
+Why
+---
+
+Remote terminal sandboxes (Docker, Modal, SSH) currently see real upstream
+API credentials.  A prompt-injected agent inside one of these sandboxes can
+``cat ~/.config/openrouter/auth.json`` or ``printenv | grep -i key`` and
+exfiltrate them.
+
+iron-proxy is a TLS-intercepting egress firewall (Apache-2.0, Go binary, by
+ironsh).  It sits between the sandbox and the internet, enforces a default-deny
+allowlist on outbound hosts, and *swaps proxy tokens for real credentials*
+on the way out.  The sandbox only ever holds opaque proxy tokens — leaking
+them is useless, since they only work behind the configured trusted proxy
+boundary (the CA private key and proxy endpoint integrity are part of that
+boundary: if traffic can be redirected to attacker-controlled proxy
+infrastructure, the guarantee no longer holds).
+
+Design summary
+--------------
+
+* The ``iron-proxy`` binary is auto-installed into ``<hermes_home>/bin/iron-proxy``
+  on first use.  Hermes pins one upstream version (``_IRON_PROXY_VERSION``)
+  and downloads the matching tar.gz from the official GitHub Releases page,
+  verifying the SHA-256 against the release's ``checksums.txt``.
+
+* A long-lived CA at ``<hermes_home>/proxy/ca.{crt,key}`` is generated on
+  first ``hermes egress setup``.  Sandboxes trust this CA so iron-proxy can
+  terminate TLS and rewrite headers.
+
+* The proxy config lives at ``<hermes_home>/proxy/proxy.yaml``.  It enumerates
+  the per-provider allowlists and the ``secrets`` transform that does the
+  Authorization-header swap.
+
+* Token mappings (proxy token -> real credential lookup) live alongside the
+  config.  The real credential is **never** written to the config — iron-proxy
+  reads it from its own environment via ``{type: env, var: NAME}``.  When
+  Bitwarden Secrets Manager is configured, the real value is pulled there
+  at proxy startup instead.
+
+* The proxy runs as a managed subprocess (``hermes egress start``), pidfile
+  at ``<hermes_home>/proxy/iron-proxy.pid``.  Daemon output (including
+  per-request records on v0.39) goes to ``<hermes_home>/proxy/iron-proxy.log``;
+  ``audit.log`` is pre-created but reserved for a future pin that supports
+  ``log.audit_path``.
+
+* Failures (binary missing, port collision, bad config) emit a one-line
+  warning and do *not* block agent startup.  The Docker backend refuses to
+  start a sandbox with the proxy enabled-but-down, with a clear error.
+
+This module is intentionally subprocess-driven rather than depending on any
+iron-proxy Python bindings — a single cross-platform binary is easier to
+lazy-install than a wheels-with-extension dependency, and we keep maintenance
+to a "bump the pinned version" loop.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import json
+import logging
+import os
+import platform
+import shutil
+import signal
+import stat
+import subprocess
+import tarfile
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Configuration constants
+# ---------------------------------------------------------------------------
+
+# Pinned upstream version.  Bump in a follow-up PR — never auto-resolve "latest"
+# because upstream YAML schema is allowed to change between releases and we
+# want updates to be deliberate.
+_IRON_PROXY_VERSION = "0.39.0"
+
+_IRON_PROXY_RELEASE_BASE = (
+    f"https://github.com/ironsh/iron-proxy/releases/download/v{_IRON_PROXY_VERSION}"
+)
+_IRON_PROXY_CHECKSUM_NAME = "checksums.txt"
+# Detached signature for checksums.txt + the signing public key, both shipped on
+# the release. Used for optional GPG verification of the release channel
+# (maxpetrusenko P1): SHA-256 only protects the archive if checksums.txt itself
+# came from an uncompromised channel; verifying its signature closes that gap.
+_IRON_PROXY_CHECKSUM_SIG_NAME = "checksums.txt.asc"
+_IRON_PROXY_PUBKEY_NAME = "public-key.asc"
+
+# How long to wait for HTTP downloads and subprocess interactions, in seconds.
+_DOWNLOAD_TIMEOUT = 120  # binary is ~16MB
+_RUN_TIMEOUT = 30
+_STARTUP_GRACE_SECONDS = 5
+
+# Management (operator) API.  iron-proxy v0.39 ships an authenticated
+# loopback HTTP endpoint (``management.listen`` + ``management.api_key_env``)
+# whose ``POST /v1/reload`` re-reads proxy.yaml and atomically swaps the
+# transform pipeline in-place — no restart, no dropped connections.  We
+# always enable it on generated configs: it binds loopback only and every
+# request needs the bearer key below.  ``hermes egress reload`` is the
+# client.
+#
+# The key is minted at setup time, stored at
+# ``<hermes_home>/proxy/management.token`` (0600), and injected into the
+# daemon's env under this name at start.  v0.39 validates at startup that
+# the named env var is non-empty when management.listen is set.
+_MGMT_API_KEY_ENV = "HERMES_IRON_PROXY_MGMT_KEY"
+# The management listener binds loopback at tunnel_port + 2 (tunnel_port
+# is CONNECT/MITM, +1 is the plain-HTTP forward listener).
+_MGMT_PORT_OFFSET = 2
+_MGMT_RELOAD_TIMEOUT = 15
+
+# Default listen ports.  HTTPS_PROXY semantics use a single CONNECT tunnel,
+# so we expose only the tunnel listener for v1 — no need to put the sandbox
+# DNS at the iron-proxy IP.  This greatly simplifies wiring.
+_DEFAULT_TUNNEL_PORT = 9090
+
+# Hosts allowed by default for AI inference traffic.  Anything else is 403'd.
+_DEFAULT_ALLOWED_HOSTS: Tuple[str, ...] = (
+    "openrouter.ai",
+    "*.openrouter.ai",
+    "api.openai.com",
+    "api.anthropic.com",
+    "generativelanguage.googleapis.com",
+    "api.x.ai",
+    "api.mistral.ai",
+    "api.groq.com",
+    "api.together.xyz",
+    "api.deepseek.com",
+    "inference.nousresearch.com",
+)
+
+# Provider env-var name -> upstream host (or list of hosts) on which the
+# Authorization Bearer token should be swapped.
+_BEARER_PROVIDERS: Dict[str, Tuple[str, ...]] = {
+    "OPENROUTER_API_KEY": ("openrouter.ai", "*.openrouter.ai"),
+    "OPENAI_API_KEY": ("api.openai.com",),
+    "GROQ_API_KEY": ("api.groq.com",),
+    "TOGETHER_API_KEY": ("api.together.xyz",),
+    "DEEPSEEK_API_KEY": ("api.deepseek.com",),
+    "MISTRAL_API_KEY": ("api.mistral.ai",),
+    "XAI_API_KEY": ("api.x.ai",),
+    "NOUS_API_KEY": ("inference.nousresearch.com",),
+}
+
+
+# Providers whose API authenticates with a NON-Authorization header.
+# iron-proxy v0.39's ``secrets.replace.match_headers`` targets arbitrary
+# header names (case-insensitive; confirmed by the iron-proxy author on
+# PR #30179 and verified in the pinned v0.39.0 source — ``swapHeaders``
+# + ``parseHeaderMatchers``), so these are first-class swapped providers,
+# not "uncovered".
+#
+# ``aliases`` are interchangeable env-var names for the SAME upstream
+# credential (Hermes' auth.py keys Google on both GEMINI_API_KEY and
+# GOOGLE_API_KEY).  Aliased names MUST collapse into a single mapping:
+# every rule carries ``require: true``, and two require-rules on the same
+# host reject each other's requests (each rule whose own token isn't
+# present returns ActionReject).  The sandbox receives the minted token
+# under the canonical name AND every alias so SDKs reading either work.
+_HEADER_AUTH_PROVIDERS: Dict[str, Dict[str, Tuple[str, ...]]] = {
+    # Anthropic native: x-api-key.  Authorization is also matched so an
+    # SDK sending the token as a Bearer (OAuth-style) still swaps.
+    "ANTHROPIC_API_KEY": {
+        "hosts": ("api.anthropic.com",),
+        "match_headers": ("x-api-key", "Authorization"),
+        "aliases": (),
+    },
+    # Azure OpenAI: api-key header (AAD bearer flows use Authorization).
+    "AZURE_OPENAI_API_KEY": {
+        "hosts": (
+            "*.openai.azure.com",
+            "*.cognitiveservices.azure.com",
+            "*.services.ai.azure.com",
+        ),
+        "match_headers": ("api-key", "Authorization"),
+        "aliases": (),
+    },
+    # Google AI Studio (Gemini): x-goog-api-key header; the SDKs that pass
+    # ``?key=<token>`` as a query param are covered by match_query, which
+    # scans every query parameter for the token value.
+    "GEMINI_API_KEY": {
+        "hosts": ("generativelanguage.googleapis.com",),
+        "match_headers": ("x-goog-api-key",),
+        "aliases": ("GOOGLE_API_KEY",),
+    },
+}
+
+
+# Providers whose env-var names we recognize but whose auth genuinely cannot
+# be swapped by a static header/query replacement (SigV4 request signing,
+# OAuth tokens minted by an SDK from a service-account file).  Presence is
+# surfaced as a warning at setup/status time — these are generic cloud creds
+# that are usually present for unrelated tooling (terraform, gcloud, aws-cli),
+# so they never block the proxy from starting.
+#
+# NOTE: this list used to include Anthropic / Azure OpenAI / Gemini, with an
+# LLM-specific fail-closed tier (``proxy.fail_on_uncovered_providers``).
+# Those providers moved to ``_HEADER_AUTH_PROVIDERS`` once we wired
+# ``match_headers`` (upstream confirmed support on the pinned v0.39.0), which
+# emptied the fail-closed tier — the flag and its refuse-start path were
+# deleted rather than kept as a dead toggle.
+_NON_BEARER_PROVIDERS: Tuple[str, ...] = (
+    # AWS Bedrock / SageMaker: SigV4-signed requests.
+    "AWS_ACCESS_KEY_ID",
+    "AWS_SECRET_ACCESS_KEY",
+    # GCP Vertex AI: OAuth bearer minted by the SDK from a service-account
+    # file, not a static env key.
+    "GOOGLE_APPLICATION_CREDENTIALS",
+)
+
+
+# Default SSRF-protection deny list applied to the proxy's outbound traffic.
+# Mirrors the public docs promise ("cloud metadata IPs are refused by default
+# regardless of allowlist").  Tests / dev setups that need loopback can pass
+# an explicit override (e.g. [] to disable, or a smaller subset).
+_DEFAULT_UPSTREAM_DENY_CIDRS: Tuple[str, ...] = (
+    "127.0.0.0/8",        # IPv4 loopback
+    "::1/128",            # IPv6 loopback
+    "169.254.0.0/16",     # IPv4 link-local incl. AWS/GCP/Azure IMDS
+    "fe80::/10",          # IPv6 link-local
+    "10.0.0.0/8",         # RFC1918
+    "172.16.0.0/12",      # RFC1918
+    "192.168.0.0/16",     # RFC1918
+    "fc00::/7",           # IPv6 ULA
+    # IPv4-mapped IPv6 (``::ffff:0:0/96``) covers the dual-stack case
+    # where an upstream resolves to e.g. ``::ffff:169.254.169.254`` and
+    # the kernel hands the v4-mapped form to the socket — that would
+    # otherwise be a clean SSRF bypass to IMDS through the v6 path.
+    "::ffff:0:0/96",
+    # RFC6598 / CGNAT — used by AWS VPC for shared services, K8s pod
+    # networks, many cloud overlays.  Not strictly RFC1918 but operators
+    # universally want it denied for the same reasons.
+    "100.64.0.0/10",
+    # RFC2544 benchmark range — rare in practice but occasionally used
+    # for internal services and never legitimate as an upstream.
+    "198.18.0.0/15",
+)
+
+
+# Min env vars the iron-proxy subprocess actually needs.  Everything else
+# is stripped — see ``_build_proxy_subprocess_env`` for the rationale.
+_PROXY_SUBPROCESS_ENV_ALLOWLIST: Tuple[str, ...] = (
+    "PATH",
+    "HOME",
+    "TMPDIR",
+    "TZ",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "NO_COLOR",
+    "SSL_CERT_DIR",
+    "SSL_CERT_FILE",
+    "SYSTEMROOT",  # Windows
+    "USERPROFILE",  # Windows
+)
+
+
+# Env vars that must be stripped from the subprocess env even if they're on
+# the allowlist or named in mappings — these would either recurse the proxy
+# back through itself or send its traffic through a corporate proxy.
+_PROXY_SUBPROCESS_ENV_STRIP: Tuple[str, ...] = (
+    "HTTPS_PROXY", "https_proxy",
+    "HTTP_PROXY", "http_proxy",
+    "ALL_PROXY", "all_proxy",
+    "NO_PROXY", "no_proxy",
+)
+
+
+# SIGKILL doesn't exist on Windows.  We fall back to SIGTERM there, which the
+# OS treats as a hard terminate via TerminateProcess() — equivalent semantics.
+_KILL_SIGNAL = getattr(signal, "SIGKILL", signal.SIGTERM)
+
+
+# Cached ``iron-proxy --version`` output keyed by binary path.  ``get_status``
+# is invoked per Docker-container-create; the version string is constant for
+# a given binary so a one-shot subprocess call is plenty.
+_VERSION_CACHE: Dict[str, str] = {}
+
+
+# ---------------------------------------------------------------------------
+# Public dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ProxyStatus:
+    """Snapshot of the iron-proxy installation + runtime state."""
+
+    enabled: bool = False
+    binary_path: Optional[Path] = None
+    binary_version: Optional[str] = None
+    config_path: Optional[Path] = None
+    ca_cert_path: Optional[Path] = None
+    pid: Optional[int] = None
+    listening: bool = False
+    tunnel_port: int = _DEFAULT_TUNNEL_PORT
+    warnings: List[str] = field(default_factory=list)
+
+    @property
+    def installed(self) -> bool:
+        return self.binary_path is not None and self.binary_path.exists()
+
+    @property
+    def configured(self) -> bool:
+        return (
+            self.config_path is not None
+            and self.config_path.exists()
+            and self.ca_cert_path is not None
+            and self.ca_cert_path.exists()
+        )
+
+
+@dataclass
+class TokenMapping:
+    """Map a sandbox-visible proxy token to a real upstream credential lookup.
+
+    ``real_env_name`` is the env-var name iron-proxy reads at egress time.
+    When Bitwarden is configured as the credential source for the proxy,
+    iron-proxy's *own* environment is populated from bws on startup — the
+    sandbox still sees only ``proxy_token``.
+
+    ``match_headers`` names the request headers iron-proxy scans for the
+    proxy token (default: ``Authorization`` for bearer providers; e.g.
+    ``("x-api-key", "Authorization")`` for Anthropic native).
+
+    ``alias_env_names`` are additional env-var names the SANDBOX receives
+    the same proxy token under (e.g. ``GOOGLE_API_KEY`` for
+    ``GEMINI_API_KEY``).  They do not appear in the iron-proxy config —
+    only one secrets rule is emitted per mapping, keyed on
+    ``real_env_name``.
+    """
+
+    proxy_token: str
+    real_env_name: str
+    upstream_hosts: Tuple[str, ...]
+    match_headers: Tuple[str, ...] = ("Authorization",)
+    alias_env_names: Tuple[str, ...] = ()
+
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+
+def _hermes_bin_dir() -> Path:
+    from hermes_constants import get_hermes_home
+
+    return get_hermes_home() / "bin"
+
+
+def _proxy_state_dir_ro() -> Path:
+    """Return the proxy state dir without creating it.
+
+    Read-only callers (status probes, pidfile reads, version queries) use
+    this — there's no reason to materialize ``~/.hermes/proxy/`` just to
+    check whether a pidfile exists.
+    """
+    from hermes_constants import get_hermes_home
+
+    return get_hermes_home() / "proxy"
+
+
+def _proxy_state_dir() -> Path:
+    """Return the proxy state dir, creating it with 0o700 if absent.
+
+    Writable callers (CA gen, config write, mappings write, start_proxy)
+    use this.  We force 0o700 — the dir holds the CA signing key, audit
+    log, and pidfile, so traversal by other local users is undesirable.
+    The chmod is unconditional so a pre-existing dir with a slack umask
+    gets tightened on first access.
+    """
+    d = _proxy_state_dir_ro()
+    d.mkdir(parents=True, exist_ok=True)
+    try:
+        d.chmod(0o700)
+    except OSError:
+        # On Windows the chmod is a no-op for POSIX modes; on shared
+        # filesystems we may not own the dir.  Don't fail here — the
+        # individual files still get explicit perms.
+        pass
+    return d
+
+
+def _platform_binary_name() -> str:
+    return "iron-proxy.exe" if platform.system() == "Windows" else "iron-proxy"
+
+
+def _platform_asset_name() -> str:
+    """Map (uname, arch) → upstream release asset filename.
+
+    iron-proxy ships ``iron-proxy_<version>_<os>_<arch>.tar.gz``.
+    Windows builds aren't published upstream as of v0.39.0; we raise a
+    clear error for callers on Windows.
+    """
+
+    system = platform.system()
+    machine = platform.machine().lower()
+
+    if system == "Linux":
+        arch = "arm64" if machine in ("arm64", "aarch64") else "amd64"
+        return f"iron-proxy_{_IRON_PROXY_VERSION}_linux_{arch}.tar.gz"
+    if system == "Darwin":
+        arch = "arm64" if machine in ("arm64", "aarch64") else "amd64"
+        return f"iron-proxy_{_IRON_PROXY_VERSION}_darwin_{arch}.tar.gz"
+    if system == "Windows":
+        raise RuntimeError(
+            "iron-proxy does not ship native Windows binaries as of "
+            f"v{_IRON_PROXY_VERSION}. Run the proxy on a Linux/macOS host, "
+            "or inside WSL."
+        )
+
+    raise RuntimeError(
+        f"Unsupported platform for iron-proxy auto-install: {system} {machine}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Binary discovery + lazy install
+# ---------------------------------------------------------------------------
+
+
+def find_iron_proxy(*, install_if_missing: bool = False) -> Optional[Path]:
+    """Return a path to a usable ``iron-proxy`` binary, or None.
+
+    Resolution order:
+      1. ``<hermes_home>/bin/iron-proxy``  (our managed copy — preferred)
+      2. ``shutil.which("iron-proxy")``    (system PATH)
+
+    When ``install_if_missing`` is True and neither resolves, calls
+    :func:`install_iron_proxy` to download and verify the pinned version.
+    """
+
+    managed = _hermes_bin_dir() / _platform_binary_name()
+    if managed.exists() and os.access(managed, os.X_OK):
+        return managed
+
+    system = shutil.which("iron-proxy")
+    if system:
+        return Path(system)
+
+    if install_if_missing:
+        try:
+            return install_iron_proxy()
+        except Exception as exc:  # noqa: BLE001 — never block startup
+            logger.warning("iron-proxy auto-install failed: %s", exc)
+            return None
+    return None
+
+
+def install_iron_proxy(*, force: bool = False) -> Path:
+    """Download, verify, and install the pinned ``iron-proxy`` binary.
+
+    Returns the path to the installed executable.  Raises on any failure
+    (network, checksum, extraction).  Callers in the auto-install path catch
+    these; the user-facing ``hermes proxy install`` surface lets them
+    propagate so the wizard can show a clear error.
+    """
+
+    bin_dir = _hermes_bin_dir()
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    target = bin_dir / _platform_binary_name()
+
+    if target.exists() and not force:
+        return target
+
+    asset_name = _platform_asset_name()
+    asset_url = f"{_IRON_PROXY_RELEASE_BASE}/{asset_name}"
+    checksum_url = f"{_IRON_PROXY_RELEASE_BASE}/{_IRON_PROXY_CHECKSUM_NAME}"
+
+    with tempfile.TemporaryDirectory(prefix="hermes-iron-proxy-") as tmpdir:
+        tmp = Path(tmpdir)
+        archive_path = tmp / asset_name
+        checksum_path = tmp / _IRON_PROXY_CHECKSUM_NAME
+
+        logger.info("Downloading %s", asset_url)
+        _http_download(asset_url, archive_path)
+        _http_download(checksum_url, checksum_path)
+
+        # Defense-in-depth (maxpetrusenko P1): verify the GPG signature of
+        # checksums.txt before trusting it. The archive download honors ambient
+        # proxy env (urllib), so a compromised channel could serve a matching
+        # binary + checksums pair; the detached signature + pinned public key
+        # close that release-channel tamper gap. Best-effort: if gpg or the
+        # signature assets aren't available we log and fall back to the SHA-256
+        # check alone rather than hard-failing offline installs.
+        _verify_checksums_signature(tmp, checksum_path)
+
+        expected = _expected_sha256(checksum_path, asset_name)
+        actual = _sha256_file(archive_path)
+        if expected.lower() != actual.lower():
+            raise RuntimeError(
+                f"Checksum mismatch for {asset_name}: "
+                f"expected {expected}, got {actual}"
+            )
+
+        with tarfile.open(archive_path, "r:gz") as tf:
+            member = _pick_tar_member(tf, _platform_binary_name())
+            # PEP 706 data filter — strips ownership/mode replay (we set
+            # chmod explicitly below) AND rejects symlink/hardlink members
+            # that escape the extraction dir.  Required on 3.12+ to silence
+            # the deprecation warning and on 3.14+ to opt into the
+            # tarbomb-rejecting default.
+            try:
+                tf.extract(member, tmp, filter="data")  # noqa: S202
+            except TypeError:
+                # Python < 3.12 — filter kw didn't exist yet; the
+                # _pick_tar_member sanitization already rejects path
+                # traversal so this is acceptable.
+                tf.extract(member, tmp)  # noqa: S202
+            extracted = tmp / member.name
+
+        # Stage into the final directory then atomically rename so the new
+        # binary is never visible half-written.
+        fd, staged = tempfile.mkstemp(dir=str(bin_dir), prefix=".iron-proxy_")
+        os.close(fd)
+        shutil.copy2(extracted, staged)
+        os.chmod(
+            staged,
+            stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR
+            | stat.S_IRGRP | stat.S_IXGRP
+            | stat.S_IROTH | stat.S_IXOTH,
+        )
+        os.replace(staged, target)
+
+    # Invalidate the version cache so a freshly-installed binary
+    # re-probes ``--version`` on the next ``get_status()`` call instead
+    # of returning the pre-upgrade string.  Long-lived processes that
+    # bump the pinned version via ``force=True`` need this.
+    _VERSION_CACHE.pop(str(target), None)
+
+    logger.info("Installed iron-proxy %s at %s", _IRON_PROXY_VERSION, target)
+    return target
+
+
+def _http_download(url: str, dest: Path) -> None:
+    req = urllib.request.Request(url, headers={"User-Agent": "hermes-agent"})
+    try:
+        with urllib.request.urlopen(req, timeout=_DOWNLOAD_TIMEOUT) as resp:  # noqa: S310
+            with open(dest, "wb") as f:
+                shutil.copyfileobj(resp, f)
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Failed to download {url}: {exc}") from exc
+
+
+def _verify_checksums_signature(tmp: Path, checksum_path: Path) -> bool:
+    """Best-effort GPG verification of ``checksums.txt`` (maxpetrusenko P1).
+
+    Downloads the detached signature (``checksums.txt.asc``) and the release
+    signing key (``public-key.asc``), imports the key into an ephemeral
+    keyring, and verifies the signature over ``checksum_path``.
+
+    Returns True when the signature is verified. Returns False (with a warning)
+    when verification is unavailable — ``gpg`` not installed, or the signature /
+    public-key assets are missing from the release. Raises RuntimeError ONLY
+    when verification actively FAILS (a present-but-bad signature), which is a
+    tamper signal we must not ignore.
+
+    Rationale for graceful degradation on "unavailable": the SHA-256 check
+    against ``checksums.txt`` remains in force regardless, and many install
+    hosts (CI, minimal containers) won't have gpg. We harden when we can and
+    never make gpg a hard dependency for a working install.
+    """
+    gpg = shutil.which("gpg")
+    if not gpg:
+        logger.warning(
+            "gpg not found on PATH — skipping iron-proxy release-signature "
+            "verification (SHA-256 checksum check still enforced)."
+        )
+        return False
+
+    sig_url = f"{_IRON_PROXY_RELEASE_BASE}/{_IRON_PROXY_CHECKSUM_SIG_NAME}"
+    pubkey_url = f"{_IRON_PROXY_RELEASE_BASE}/{_IRON_PROXY_PUBKEY_NAME}"
+    sig_path = tmp / _IRON_PROXY_CHECKSUM_SIG_NAME
+    pubkey_path = tmp / _IRON_PROXY_PUBKEY_NAME
+
+    try:
+        _http_download(sig_url, sig_path)
+        _http_download(pubkey_url, pubkey_path)
+    except RuntimeError as exc:
+        logger.warning(
+            "iron-proxy release signature assets unavailable (%s) — skipping "
+            "GPG verification (SHA-256 checksum check still enforced).", exc,
+        )
+        return False
+
+    # Ephemeral keyring so we never touch the user's real GPG home.
+    gnupg_home = tmp / "gnupg"
+    gnupg_home.mkdir(mode=0o700, exist_ok=True)
+    base_cmd = [gpg, "--homedir", str(gnupg_home), "--batch", "--no-tty"]
+
+    imp = subprocess.run(  # noqa: S603 — gpg path from trusted PATH lookup
+        [*base_cmd, "--import", str(pubkey_path)],
+        capture_output=True, timeout=60,
+    )
+    if imp.returncode != 0:
+        logger.warning(
+            "Could not import iron-proxy signing key — skipping GPG "
+            "verification (SHA-256 still enforced): %s",
+            imp.stderr.decode("utf-8", "replace")[:200],
+        )
+        return False
+
+    verify = subprocess.run(  # noqa: S603
+        [*base_cmd, "--verify", str(sig_path), str(checksum_path)],
+        capture_output=True, timeout=60,
+    )
+    if verify.returncode != 0:
+        # A present signature that does NOT verify is a tamper signal — fail hard.
+        raise RuntimeError(
+            "iron-proxy checksums.txt failed GPG signature verification — "
+            "refusing to install (possible release-channel tampering). "
+            f"gpg: {verify.stderr.decode('utf-8', 'replace')[:300]}"
+        )
+    logger.info("Verified iron-proxy checksums.txt GPG signature.")
+    return True
+
+
+def _expected_sha256(checksum_file: Path, asset_name: str) -> str:
+    """Parse the standard ``sha256sum`` output: ``<hex>  <filename>``."""
+
+    text = checksum_file.read_text(encoding="utf-8", errors="replace")
+    for line in text.splitlines():
+        parts = line.strip().split()
+        if len(parts) >= 2 and parts[-1] == asset_name:
+            return parts[0]
+    raise RuntimeError(
+        f"No checksum entry for {asset_name} in {checksum_file.name}"
+    )
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _pick_tar_member(tf: tarfile.TarFile, binary_name: str) -> tarfile.TarInfo:
+    """Find the binary inside the upstream tar.
+
+    iron-proxy's archive is typically flat (binary at root) but we tolerate
+    a top-level directory.  Members must be regular files with a leaf name
+    matching ``binary_name``, no absolute paths, and no ``..`` traversal.
+    """
+
+    candidates: List[tarfile.TarInfo] = []
+    for member in tf.getmembers():
+        if not member.isfile():
+            continue
+        if member.name.startswith("/") or ".." in Path(member.name).parts:
+            continue
+        if Path(member.name).name == binary_name:
+            candidates.append(member)
+    if not candidates:
+        raise RuntimeError(
+            f"Could not find {binary_name} inside downloaded archive "
+            f"(members: {[m.name for m in tf.getmembers()[:5]]}...)"
+        )
+    candidates.sort(key=lambda m: len(m.name))
+    return candidates[0]
+
+
+def iron_proxy_version(binary: Path) -> str:
+    """Return ``iron-proxy --version`` output, stripped.  Empty on failure.
+
+    Cached by binary path: ``get_status`` is called per Docker container
+    create, but the version string is constant for a given binary.  A
+    single subprocess invocation is plenty.
+    """
+
+    key = str(binary)
+    cached = _VERSION_CACHE.get(key)
+    if cached is not None:
+        return cached
+
+    try:
+        # Build a minimal env: only PATH, HOME, and locale vars.
+        # The version probe is a one-shot subprocess — forwarding
+        # the full host env (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
+        # to a PATH-resolved or unverified binary is an unnecessary
+        # credential leak.  Reuse the same allowlist the daemon
+        # subprocess uses (see _build_proxy_subprocess_env).
+        minimal_env: Dict[str, str] = {}
+        parent = os.environ
+        for name in _PROXY_SUBPROCESS_ENV_ALLOWLIST:
+            if name in parent:
+                minimal_env[name] = parent[name]
+        # The S603 warning is legitimate for the PATH-fallback case
+        # (find_iron_proxy → shutil.which), but --version with a
+        # scrubbed env is safe regardless of binary provenance.
+        res = subprocess.run(  # noqa: S603
+            [str(binary), "--version"],
+            capture_output=True,
+            text=True, encoding="utf-8", errors="replace",
+            timeout=_RUN_TIMEOUT,
+            env=minimal_env,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    out = (res.stdout or res.stderr or "").strip()
+    # Don't cache empty output — that would poison ``hermes egress
+    # status`` for the lifetime of the process if the first probe hit a
+    # corrupt binary or a flag-rename in a newer upstream.  Re-probe on
+    # the next call instead.
+    if out:
+        _VERSION_CACHE[key] = out
+    return out
+
+
+# ---------------------------------------------------------------------------
+# CA cert generation
+# ---------------------------------------------------------------------------
+
+
+def ensure_ca_cert(*, force: bool = False) -> Tuple[Path, Path]:
+    """Generate (or return existing) iron-proxy CA cert + key.
+
+    Uses the host's ``openssl`` binary.  We don't try to bind to a Python
+    crypto library — openssl is universally available on the platforms we
+    support, and it sidesteps cryptography-package licensing/distribution
+    surface.
+    """
+
+    state = _proxy_state_dir()
+    ca_crt = state / "ca.crt"
+    ca_key = state / "ca.key"
+
+    if ca_crt.exists() and ca_key.exists() and not force:
+        return ca_crt, ca_key
+
+    if shutil.which("openssl") is None:
+        raise RuntimeError(
+            "openssl not found on PATH. Install OpenSSL (apt: `openssl`, "
+            "brew: `openssl`) to generate the iron-proxy CA cert."
+        )
+
+    # 10-year cert.  iron-proxy mints short-lived leaf certs from this CA,
+    # so the CA itself only rotates when the user explicitly forces it.
+    with tempfile.TemporaryDirectory(prefix="hermes-proxy-ca-") as tmpdir:
+        tmp = Path(tmpdir)
+        tmp_key = tmp / "ca.key"
+        tmp_crt = tmp / "ca.crt"
+
+        subprocess.run(  # noqa: S603 — openssl path is trusted PATH lookup
+            ["openssl", "genrsa", "-out", str(tmp_key), "4096"],
+            check=True,
+            capture_output=True,
+            timeout=60,
+        )
+        subprocess.run(  # noqa: S603
+            [
+                "openssl", "req", "-x509", "-new", "-nodes",
+                "-key", str(tmp_key),
+                "-sha256", "-days", "3650",
+                "-subj", "/CN=hermes iron-proxy CA",
+                "-addext", "basicConstraints=critical,CA:TRUE",
+                "-addext", "keyUsage=critical,keyCertSign",
+                "-out", str(tmp_crt),
+            ],
+            check=True,
+            capture_output=True,
+            timeout=60,
+        )
+
+        # Move into place with private permissions.  CRITICAL: the key
+        # has to be created with 0o600 from the very first byte — a
+        # ``shutil.copy2`` followed by ``os.chmod`` leaves a TOCTOU window
+        # where the private key is world-readable on multi-user hosts.
+        key_bytes = tmp_key.read_bytes()
+        crt_bytes = tmp_crt.read_bytes()
+
+        # Stage with explicit 0o600, then atomically rename into place.
+        # O_NOFOLLOW guards against a symlink at ca_key (defence-in-depth
+        # — the state dir is 0o700-owned but a malicious local user with
+        # the same uid could pre-create one).
+        key_staged = ca_key.with_suffix(ca_key.suffix + ".staged")
+        open_flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+        # O_NOFOLLOW exists on POSIX; on Windows we just rely on the
+        # default semantics.
+        if hasattr(os, "O_NOFOLLOW"):
+            open_flags |= os.O_NOFOLLOW
+        # Best-effort: pre-unlink any existing staged file so the open
+        # with O_CREAT is always against a fresh inode.
+        try:
+            key_staged.unlink()
+        except FileNotFoundError:
+            pass
+        fd = os.open(str(key_staged), open_flags, 0o600)
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(key_bytes)
+        except Exception:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+            raise
+        os.replace(key_staged, ca_key)
+
+        # Cert is public — 0o644 is fine and matches typical PEM layout.
+        ca_crt.write_bytes(crt_bytes)
+        os.chmod(ca_crt, stat.S_IRUSR | stat.S_IWUSR | stat.S_IRGRP | stat.S_IROTH)
+
+    logger.info("Generated iron-proxy CA at %s", ca_crt)
+    return ca_crt, ca_key
+
+
+# ---------------------------------------------------------------------------
+# Proxy config + token mapping generation
+# ---------------------------------------------------------------------------
+
+
+def mint_proxy_token(prefix: str = "hermes-proxy") -> str:
+    """Mint a fresh opaque token to hand to the sandbox.
+
+    The token has no internal structure beyond a recognizable prefix —
+    iron-proxy matches on exact equality.  We use a 128-bit random suffix
+    (32 hex chars from a SHA-256 of 32 bytes of os.urandom).  At that
+    entropy the birthday-bound collision probability is below 2^-64 for
+    up to 2^32 tokens, which is plenty for a proxy-scoped namespace.
+    """
+
+    return f"{prefix}-{hashlib.sha256(os.urandom(32)).hexdigest()[:32]}"
+
+
+def _management_token_path() -> Path:
+    return _proxy_state_dir() / "management.token"
+
+
+def ensure_management_token(*, force: bool = False) -> str:
+    """Return the management-API bearer key, minting it on first call.
+
+    Stored at ``<hermes_home>/proxy/management.token`` with 0600 perms.
+    The daemon receives it via the ``HERMES_IRON_PROXY_MGMT_KEY`` env var
+    (named in the generated config's ``management.api_key_env``);
+    ``hermes egress reload`` reads the same file to authenticate.
+    """
+
+    p = _management_token_path()
+    if not force and p.exists():
+        try:
+            existing = p.read_text(encoding="utf-8").strip()
+            if existing:
+                return existing
+        except OSError:
+            pass
+    token = mint_proxy_token(prefix="hermes-mgmt")
+    fd = os.open(
+        str(p),
+        os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0),
+        0o600,
+    )
+    try:
+        os.fchmod(fd, 0o600)
+    except (OSError, AttributeError):
+        pass
+    try:
+        os.write(fd, token.encode("utf-8"))
+    finally:
+        os.close(fd)
+    return token
+
+
+def _read_management_token() -> Optional[str]:
+    p = _proxy_state_dir_ro() / "management.token"
+    try:
+        token = p.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    return token or None
+
+
+def _read_management_listen_from_config(
+    config_path: Optional[Path] = None,
+) -> Optional[Tuple[str, int]]:
+    """Return ``(host, port)`` of the management listener, if configured."""
+
+    cfg = config_path or (_proxy_state_dir_ro() / "proxy.yaml")
+    if not cfg.exists():
+        return None
+    try:
+        import yaml
+    except ImportError:
+        return None
+    try:
+        data = yaml.safe_load(cfg.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    listen = ((data or {}).get("management") or {}).get("listen") or ""
+    if not isinstance(listen, str) or ":" not in listen:
+        return None
+    host, _, port_s = listen.rpartition(":")
+    try:
+        port = int(port_s)
+    except ValueError:
+        return None
+    return (host or "127.0.0.1", port)
+
+
+def reload_proxy() -> bool:
+    """Hot-reload the running daemon's ruleset via the management API.
+
+    POSTs to ``/v1/reload`` on the loopback management listener; the daemon
+    re-reads proxy.yaml and atomically swaps the transform pipeline —
+    validation failures leave the running config untouched (HTTP 422).
+
+    Returns True on a successful reload.  Raises ``RuntimeError`` with an
+    actionable message when the daemon isn't running, the config predates
+    management-API support (no ``management`` block → restart required),
+    or the reload is rejected.
+    """
+
+    pid = _read_pid()
+    if not pid or not _pid_alive(pid):
+        raise RuntimeError(
+            "iron-proxy is not running — nothing to reload.  "
+            "Run `hermes egress start`."
+        )
+    mgmt = _read_management_listen_from_config()
+    if mgmt is None:
+        raise RuntimeError(
+            "The generated proxy.yaml has no management listener (written "
+            "before reload support).  Re-run `hermes egress setup` and use "
+            "`hermes egress restart` this one time."
+        )
+    token = _read_management_token()
+    if not token:
+        raise RuntimeError(
+            "management.token is missing — re-run `hermes egress setup`, "
+            "then `hermes egress restart`."
+        )
+
+    import urllib.error
+    import urllib.request
+
+    host, port = mgmt
+    req = urllib.request.Request(
+        f"http://{host}:{port}/v1/reload",
+        method="POST",
+        headers={"Authorization": f"Bearer {token}"},
+        data=b"",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_MGMT_RELOAD_TIMEOUT) as resp:
+            if resp.status == 200:
+                return True
+            raise RuntimeError(
+                f"management API returned unexpected status {resp.status}"
+            )
+    except urllib.error.HTTPError as exc:
+        body = ""
+        try:
+            body = exc.read().decode("utf-8", errors="replace")[:500]
+        except OSError:
+            pass
+        if exc.code == 422:
+            raise RuntimeError(
+                f"iron-proxy rejected the new config (validation failed; "
+                f"the running ruleset is unchanged): {body}"
+            ) from exc
+        if exc.code == 401:
+            raise RuntimeError(
+                "management API rejected our key (401).  The running "
+                "daemon was started with a different management.token — "
+                "run `hermes egress restart`."
+            ) from exc
+        raise RuntimeError(
+            f"management reload failed (HTTP {exc.code}): {body}"
+        ) from exc
+    except (urllib.error.URLError, OSError) as exc:
+        # A daemon started from a pre-management config is alive but has
+        # no listener on the management port.
+        raise RuntimeError(
+            f"could not reach the management API at {host}:{port} ({exc}).  "
+            "If the daemon was started before reload support, run "
+            "`hermes egress restart` once."
+        ) from exc
+
+
+def _default_http_listen(tunnel_port: int) -> List[str]:
+    """Build the single host:port bind the proxy should listen on.
+
+    iron-proxy v0.39 supports exactly ONE ``proxy.http_listen`` bind per
+    daemon process, so this returns a one-element list and the choice of
+    host matters:
+
+    * **Linux:** bind the docker bridge gateway (``172.17.0.1`` by
+      default).  Sandboxes reach the proxy via
+      ``host.docker.internal:host-gateway``, which Docker resolves to
+      exactly this bridge gateway IP on Linux — a loopback-only bind is
+      unreachable from inside containers there.  The bridge IP is still
+      host-local (it's an address on the host's ``docker0`` interface),
+      so host-side tooling and the status probe can reach it too.  When
+      no docker bridge is detected (docker not installed / not started),
+      fall back to loopback — there are no sandboxes to serve in that
+      state, and the operator gets a warning.
+    * **macOS / Windows Docker Desktop:** ``host.docker.internal``
+      resolves via VPNkit to the host, so a loopback bind is reachable
+      from containers and is the least-exposed choice.
+
+    We never bind ``0.0.0.0`` — that would expose the proxy (and, with a
+    leaked sandbox token, the user's API quota) to anyone on the local
+    network.  The bridge-gateway bind is reachable by other containers
+    on the default bridge network, which is unavoidable given v0.39's
+    single-bind limit; requests still require a minted proxy token and
+    an allowlisted upstream.
+    """
+
+    if platform.system() == "Linux":
+        bridge_ip = _detect_docker_bridge_ip()
+        if bridge_ip and bridge_ip != "127.0.0.1":
+            return [f"{bridge_ip}:{tunnel_port}"]
+        logger.warning(
+            "No docker bridge (docker0) detected — binding iron-proxy to "
+            "loopback only.  Docker sandboxes will NOT be able to reach "
+            "the proxy until it is restarted with docker running."
+        )
+    return [f"127.0.0.1:{tunnel_port}"]
+
+
+def _detect_docker_bridge_ip() -> Optional[str]:
+    """Return the docker0 bridge IPv4, if present, else None.
+
+    Best-effort: we try ``ip -4 addr show docker0`` first.  Anything that
+    fails, doesn't parse as a strict IPv4, or parses as an address we
+    must NOT bind to (unspecified, loopback, multicast, reserved, public)
+    returns None — callers handle that as "no bridge bind".
+
+    SECURITY: a hostile ``ip`` shim earlier on the operator's PATH used
+    to be able to inject ``0.0.0.0`` here and re-open INADDR_ANY binding
+    that the rest of the bind-policy work explicitly closed.  We
+    validate via :mod:`ipaddress` and reject anything that isn't
+    plausibly a docker bridge IP (private + non-special).
+    """
+
+    candidate: Optional[str] = None
+    try:
+        res = subprocess.run(  # noqa: S603 — ip is a system binary
+            ["ip", "-4", "-o", "addr", "show", "docker0"],
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=2,
+        )
+        if res.returncode == 0:
+            for line in res.stdout.splitlines():
+                parts = line.split()
+                # Expected: "<n>: docker0  inet 172.17.0.1/16 ..."
+                for i, tok in enumerate(parts):
+                    if tok == "inet" and i + 1 < len(parts):
+                        candidate = parts[i + 1].split("/")[0]
+                        break
+                if candidate is not None:
+                    break
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+    if not candidate:
+        return None
+
+    # Stdlib validation: rejects garbage strings AND special-purpose
+    # addresses that must not be used as a bind target.
+    try:
+        addr = ipaddress.IPv4Address(candidate)
+    except (ipaddress.AddressValueError, ValueError):
+        return None
+    # Reject:
+    # - 0.0.0.0 / INADDR_ANY  (is_unspecified)
+    # - 127.0.0.0/8           (is_loopback — already in deny list)
+    # - 224.0.0.0/4           (is_multicast)
+    # - 240.0.0.0/4           (is_reserved)
+    # - 169.254.0.0/16        (is_link_local — IMDS range, never docker0)
+    # - global / public IPs   (is_global — docker0 must be RFC1918)
+    if (
+        addr.is_unspecified
+        or addr.is_loopback
+        or addr.is_multicast
+        or addr.is_reserved
+        or addr.is_link_local
+        or addr.is_global
+    ):
+        logger.warning(
+            "Refusing suspicious docker bridge IP %s reported by `ip`; "
+            "skipping bridge bind.", candidate,
+        )
+        return None
+
+    return str(addr)
+
+
+def build_proxy_config(
+    *,
+    mappings: List[TokenMapping],
+    ca_cert: Path,
+    ca_key: Path,
+    tunnel_port: int = _DEFAULT_TUNNEL_PORT,
+    audit_log: Optional[Path] = None,
+    allowed_hosts: Optional[List[str]] = None,
+    upstream_deny_cidrs: Optional[List[str]] = None,
+    http_listen: Optional[List[str]] = None,
+) -> Dict:
+    """Build the iron-proxy YAML config (as a dict) for a given mapping set.
+
+    The dict is YAML-serializable via ``yaml.safe_dump``.  iron-proxy reads
+    real secrets from its OWN environment via ``source: {type: env, var: ...}``;
+    the sandbox never sees them.
+
+    Bind policy: the sandbox-facing listeners (``tunnel_listen`` on
+    ``tunnel_port``, plain-HTTP ``http_listen`` on ``tunnel_port + 1``)
+    bind the docker bridge gateway on Linux (``172.17.0.1`` or whatever
+    ``docker0`` resolves to — that's what ``host.docker.internal``
+    resolves to inside containers there) and loopback on macOS / Windows
+    Docker Desktop.  We do NOT bind ``0.0.0.0`` — a LAN peer with a
+    leaked sandbox token could otherwise spend the operator's API quota
+    against any allowlisted upstream.
+
+    SSRF policy: ``upstream_deny_cidrs`` defaults to a conservative deny
+    list covering loopback, link-local (incl. AWS/GCP/Azure IMDS at
+    169.254.169.254), and RFC1918.  Pass an explicit ``[]`` to opt out of
+    the deny list entirely (only sensible in hermetic tests).
+
+    Schema mirrors the official iron-proxy schema as of v0.39.0.  Notable
+    points:
+
+    * The ``dns`` section is required by the binary even when we only use the
+      CONNECT tunnel.  We point it at loopback so it doesn't conflict with
+      anything else and disable the listener.
+    * The ``proxy.tunnel_listen`` is what sandboxes hit via ``HTTPS_PROXY``.
+      ``http_listen`` / ``https_listen`` are present (loopback only) so the
+      proxy boots; sandboxes never route directly to them.
+    * ``allowlist`` transform takes ``domains:`` and ``cidrs:``, not ``hosts:``.
+    * ``secrets`` transform takes ``secrets:`` (plural), each with a
+      ``source``, a ``replace.proxy_value`` (the sandbox-visible token), and
+      a list of ``rules`` saying which hosts the swap should fire on.
+    """
+
+    hosts: List[str] = list(allowed_hosts or _DEFAULT_ALLOWED_HOSTS)
+    for m in mappings:
+        for h in m.upstream_hosts:
+            if h not in hosts:
+                hosts.append(h)
+
+    secrets_rules = []
+    for m in mappings:
+        match_headers = list(m.match_headers or ("Authorization",))
+        secrets_rules.append({
+            "source": {"type": "env", "var": m.real_env_name},
+            "replace": {
+                "proxy_value": m.proxy_token,
+                # Per-provider header set: bearer providers match only
+                # Authorization; header-auth providers (Anthropic native
+                # x-api-key, Azure api-key, Gemini x-goog-api-key) match
+                # their native header (+ Authorization where the provider
+                # also accepts bearer flows).  v0.39 matches header names
+                # case-insensitively — see parseHeaderMatchers upstream.
+                "match_headers": match_headers,
+                # The token is also accepted as a query param — v0.39 scans
+                # every query parameter for the token value, which covers
+                # SDKs that pass ``?key=<token>`` (Gemini) as well as
+                # bearer-in-query styles.  Body matching is off — we
+                # don't want body inspection forced for every request.
+                "match_query": True,
+                "match_body": False,
+                # Fail closed (maxpetrusenko P1): when a request reaches an
+                # allowlisted upstream WITHOUT the proxy token present in a
+                # matched location, reject it instead of forwarding as-is.
+                # Without this, a real provider key that a sandbox process
+                # sent directly (not via the minted token) would still pass
+                # the proxy boundary to the allowed host. With require=true,
+                # iron-proxy returns ActionReject when no token swap fired
+                # (v0.39 secrets transform: replaceConfig.Require, enforced in
+                # TransformRequest — verified present in the pinned version).
+                "require": True,
+            },
+            "rules": [{"host": h} for h in m.upstream_hosts],
+        })
+
+    # SSRF protection: default-deny cloud metadata + loopback + RFC1918.
+    # Callers can pass [] to opt out entirely (hermetic tests need this for
+    # talking to a loopback upstream).  None means "use the default".
+    deny_cidrs: List[str]
+    if upstream_deny_cidrs is None:
+        deny_cidrs = list(_DEFAULT_UPSTREAM_DENY_CIDRS)
+    else:
+        deny_cidrs = list(upstream_deny_cidrs)
+
+    # Listen addresses.  iron-proxy v0.39 takes a single string per
+    # listener field — there is no plural ``http_listens`` form, despite
+    # earlier drafts of this module claiming v0.39 accepts both.  An
+    # empirical strings(1) audit + a live "start the binary and observe
+    # the YAML unmarshal error" confirms the singular form is the only
+    # one the binary accepts.
+    #
+    # LISTENER ROLES (verified live against the v0.39 binary):
+    # * ``tunnel_listen`` is the CONNECT + MITM listener.  HTTPS through
+    #   ``HTTPS_PROXY`` issues CONNECT — this is the listener sandboxes
+    #   must reach.  A CONNECT sent to ``http_listen`` is NOT terminated:
+    #   v0.39 forwards it upstream as a regular request and the upstream
+    #   responds 400.
+    # * ``http_listen`` is the absolute-form plain-HTTP forward listener
+    #   (``HTTP_PROXY`` for ``http://`` URLs).  Transforms fire here too.
+    # Both get the sandbox-facing bind host: tunnel on ``tunnel_port``,
+    # plain HTTP on ``tunnel_port + 1``.
+    #
+    # The bind host comes from _default_http_listen: the docker bridge
+    # gateway on Linux (containers reach the proxy via
+    # host.docker.internal, which maps to the bridge gateway there —
+    # loopback would be unreachable from inside sandboxes) and loopback
+    # on macOS/Windows Docker Desktop (where host.docker.internal routes
+    # to the host via VPNkit).
+    listens = list(http_listen) if http_listen else _default_http_listen(tunnel_port)
+    primary_listen = listens[0] if listens else f"127.0.0.1:{tunnel_port}"
+    bind_host = primary_listen.rsplit(":", 1)[0] or "127.0.0.1"
+    plain_http_listen = f"{bind_host}:{tunnel_port + 1}"
+
+    log_block: Dict = {"level": "info"}
+    # NOTE: ``log.audit_path`` is NOT a field in iron-proxy v0.39's
+    # ``config.Log`` struct — the binary rejects it with
+    # ``field audit_path not found in type config.Log``.  Per-request
+    # audit records are written to the same log destination as
+    # everything else at this binary version; the operator-facing
+    # ``audit.log`` file we pre-create is still useful as a sentinel
+    # for monitoring (logrotate target, downstream tail watchers) but
+    # the daemon does not write to it directly.  The kwarg is kept so
+    # we're forward-compatible with a future v0.40+ that adds the
+    # field; if you upgrade _IRON_PROXY_VERSION and the upstream gains
+    # ``log.audit_path``, re-enable the line below.
+    # if audit_log is not None:
+    #     log_block["audit_path"] = str(audit_log)
+    _ = audit_log  # consumed by ensure_audit_log() / docs only on v0.39
+
+    return {
+        # DNS section is required by the binary's config parser, but we run
+        # in tunnel-only mode so the DNS listener never binds an exposed port.
+        # Sandboxes reach the proxy via HTTPS_PROXY/CONNECT, not via DNS
+        # redirection.
+        "dns": {
+            "listen": "127.0.0.1:0",   # ephemeral loopback — effectively disabled
+            "proxy_ip": "127.0.0.1",
+        },
+        "proxy": {
+            # tunnel_listen is the CONNECT/MITM listener — what sandboxes
+            # hit via `HTTPS_PROXY=http://host:tunnel_port` for HTTPS
+            # upstreams (curl/requests/node issue CONNECT through it).
+            # http_listen handles absolute-form plain-HTTP forwards
+            # (`HTTP_PROXY` for http:// URLs) on tunnel_port+1.  Both
+            # bind the docker bridge gateway on Linux / loopback on
+            # Docker Desktop — NEVER 0.0.0.0.  LAN peers with a leaked
+            # sandbox token would otherwise be able to spend the
+            # operator's API quota against any allowlisted upstream.
+            "tunnel_listen": primary_listen,
+            "http_listen": plain_http_listen,
+            # The HTTPS-listener (direct TLS termination, no CONNECT)
+            # gets a loopback ephemeral port — we don't expose it.
+            "https_listen": "127.0.0.1:0",
+            "max_request_body_bytes": 16 * 1024 * 1024,
+            "max_response_body_bytes": 0,
+            "upstream_response_header_timeout": "120s",
+            # SSRF protection: deny outbound to cloud metadata + loopback by
+            # default.  An empty list opts out entirely.
+            "upstream_deny_cidrs": deny_cidrs,
+        },
+        # iron-proxy v0.39 starts a Prometheus-style metrics server by
+        # default on ``:9090`` — which is the SAME port as our default
+        # ``tunnel_port: 9090``, causing a guaranteed bind collision on
+        # startup.  Pin the metrics listener to an ephemeral loopback
+        # port (``127.0.0.1:0``) so the metrics binding can't collide
+        # with the proxy listener regardless of what tunnel_port the
+        # operator chose.  NOTE: ``:0`` means the kernel picks a fresh
+        # random port each start and nothing records it — metrics are
+        # effectively disabled/undiscoverable at this pin.  If we want
+        # scrapable metrics later, allocate a fixed port and surface it
+        # in ``ProxyStatus`` / ``hermes egress status``.
+        "metrics": {
+            "listen": "127.0.0.1:0",
+        },
+        # Operator-facing management API — loopback only, bearer-key
+        # authenticated (key read from the env var named below; injected
+        # by ``start_proxy`` from ``management.token``).  ``POST /v1/reload``
+        # re-reads THIS config file and atomically swaps the transform
+        # pipeline — `hermes egress reload` applies allowlist/token/mapping
+        # changes without a restart.  Loopback deliberately: sandboxes must
+        # never reach the management surface, so it does NOT bind the
+        # docker bridge like the traffic listeners do.
+        "management": {
+            "listen": f"127.0.0.1:{tunnel_port + _MGMT_PORT_OFFSET}",
+            "api_key_env": _MGMT_API_KEY_ENV,
+        },
+        "tls": {
+            "ca_cert": str(ca_cert),
+            "ca_key": str(ca_key),
+            "cert_cache_size": 1000,
+            "leaf_cert_expiry_hours": 168,
+        },
+        "transforms": [
+            {
+                "name": "allowlist",
+                "config": {"domains": hosts},
+            },
+            {
+                "name": "secrets",
+                "config": {"secrets": secrets_rules},
+            },
+        ],
+        "log": log_block,
+    }
+
+
+def ensure_audit_log(audit_path: Path) -> None:
+    """Create the audit log file with private permissions (0o600).
+
+    Called from the wizard right before ``start_proxy``.  On the pinned
+    v0.39 the daemon never writes this file (no ``log.audit_path``
+    config field), so the pre-create is purely forward-compat: when the
+    pin moves to a version that supports a dedicated audit stream, the
+    file already exists with tight permissions and the daemon inherits
+    them instead of creating it under the default umask.
+
+    Raises :class:`RuntimeError` on any OSError (planted symlink,
+    immutable parent dir, full disk) so the caller can decide how to
+    surface it.  The wizard treats this as a WARNING on v0.39 — the
+    file is non-load-bearing until the version bump — but the qualified
+    message keeps operators from wiring monitoring to a path that can't
+    exist.
+    """
+
+    try:
+        # Use os.open + O_CREAT to avoid races on the chmod.
+        open_flags = os.O_WRONLY | os.O_CREAT | os.O_APPEND
+        if hasattr(os, "O_NOFOLLOW"):
+            open_flags |= os.O_NOFOLLOW
+        fd = os.open(str(audit_path), open_flags, 0o600)
+        try:
+            # Tighten perms even if the file already existed under a
+            # slacker umask.
+            os.fchmod(fd, 0o600)
+        finally:
+            os.close(fd)
+    except OSError as exc:
+        raise RuntimeError(
+            f"Refusing to start: could not pre-create audit log "
+            f"{audit_path} with restrictive permissions ({exc}).  "
+            f"Move or chmod any existing file at that path and retry."
+        ) from exc
+
+
+def write_proxy_config(config: Dict) -> Path:
+    """Serialize the config dict to ``<hermes_home>/proxy/proxy.yaml``.
+
+    Uses ``yaml.safe_dump`` so we never emit Python tags.
+    """
+
+    try:
+        import yaml  # PyYAML is already a Hermes dep
+    except ImportError as exc:
+        raise RuntimeError(
+            "PyYAML is required to write the iron-proxy config but is not "
+            "installed."
+        ) from exc
+
+    state = _proxy_state_dir()
+    out = state / "proxy.yaml"
+    tmp_path = state / ".proxy.yaml.tmp"
+    with open(tmp_path, "w", encoding="utf-8") as f:
+        yaml.safe_dump(config, f, default_flow_style=False, sort_keys=False)
+    # Tighten perms on the temp file BEFORE the atomic replace so the
+    # final path is never briefly world-readable under a slack umask
+    # (the config embeds proxy token values).  chmod-after-replace would
+    # leave a TOCTOU window; the 0o700 state dir mitigates but same-uid
+    # processes could still race.
+    os.chmod(tmp_path, stat.S_IRUSR | stat.S_IWUSR)
+    os.replace(tmp_path, out)
+    return out
+
+
+def write_mappings(mappings: List[TokenMapping]) -> Path:
+    """Persist the sandbox-visible proxy tokens to ``mappings.json``.
+
+    The Docker backend reads this file to inject the right tokens as env
+    vars when starting a sandbox.  The file is NOT read by iron-proxy
+    itself — the mapping is already baked into ``proxy.yaml``.
+    """
+
+    state = _proxy_state_dir()
+    out = state / "mappings.json"
+    payload = {
+        "version": 1,
+        "tokens": [
+            {
+                "proxy_token": m.proxy_token,
+                "env_name": m.real_env_name,
+                "upstream_hosts": list(m.upstream_hosts),
+                "match_headers": list(m.match_headers),
+                "alias_env_names": list(m.alias_env_names),
+            }
+            for m in mappings
+        ],
+    }
+    tmp_path = state / ".mappings.json.tmp"
+    with open(tmp_path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2)
+    # chmod before the atomic replace — see write_proxy_config.  The
+    # mappings file holds proxy token values, so close the TOCTOU window
+    # rather than chmod-ing after the file is already at its final path.
+    os.chmod(tmp_path, stat.S_IRUSR | stat.S_IWUSR)
+    os.replace(tmp_path, out)
+    return out
+
+
+def load_mappings() -> List[TokenMapping]:
+    """Read mappings.json, if it exists.  Empty list on any error."""
+
+    state = _proxy_state_dir()
+    f = state / "mappings.json"
+    if not f.exists():
+        return []
+    try:
+        payload = json.loads(f.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.warning("Failed to read iron-proxy mappings.json: %s", exc)
+        return []
+    out: List[TokenMapping] = []
+    for item in payload.get("tokens", []):
+        try:
+            out.append(TokenMapping(
+                proxy_token=item["proxy_token"],
+                real_env_name=item["env_name"],
+                upstream_hosts=tuple(item.get("upstream_hosts") or ()),
+                # Pre-header-auth mappings.json files (written before the
+                # match_headers/alias fields existed) load with the bearer
+                # defaults — identical to their behavior at write time.
+                match_headers=tuple(item.get("match_headers") or ("Authorization",)),
+                alias_env_names=tuple(item.get("alias_env_names") or ()),
+            ))
+        except (KeyError, TypeError):
+            continue
+    return out
+
+
+def discover_provider_mappings(
+    *,
+    available_env_names: Optional[List[str]] = None,
+) -> List[TokenMapping]:
+    """Mint a TokenMapping for every known provider whose env var is set.
+
+    Pass ``available_env_names`` to override the lookup source (used by the
+    Bitwarden adapter so we mint mappings for keys that *will* be in the
+    proxy's environment even if they aren't in the host process env right
+    now).
+    """
+
+    if available_env_names is not None:
+        names = set(available_env_names)
+    else:
+        names = {k for k, v in os.environ.items() if v}
+
+    mappings: List[TokenMapping] = []
+    for env_name, hosts in _BEARER_PROVIDERS.items():
+        if env_name not in names:
+            continue
+        mappings.append(TokenMapping(
+            proxy_token=mint_proxy_token(prefix=env_name.lower().replace("_api_key", "")),
+            real_env_name=env_name,
+            upstream_hosts=hosts,
+        ))
+    for env_name, spec in _HEADER_AUTH_PROVIDERS.items():
+        aliases = tuple(spec.get("aliases") or ())
+        # A mapping is minted when the canonical name OR any alias is
+        # available.  Aliases collapse into ONE mapping (single secrets
+        # rule) because two require-rules on the same host would reject
+        # each other's requests.  The canonical env name is what
+        # iron-proxy reads — when only the alias is set in the host env,
+        # the subprocess-env builder mirrors it (see
+        # ``_build_proxy_subprocess_env``).
+        if env_name not in names and not any(a in names for a in aliases):
+            continue
+        mappings.append(TokenMapping(
+            proxy_token=mint_proxy_token(prefix=env_name.lower().replace("_api_key", "")),
+            real_env_name=env_name,
+            upstream_hosts=tuple(spec["hosts"]),
+            match_headers=tuple(spec["match_headers"]),
+            alias_env_names=aliases,
+        ))
+    return mappings
+
+
+def discover_uncovered_providers(
+    *,
+    available_env_names: Optional[List[str]] = None,
+) -> List[str]:
+    """Return env-var names for providers we recognize but can't proxy.
+
+    AWS Bedrock (SigV4) and GCP Vertex (SDK-minted OAuth) can't be swapped
+    by a static header replacement.  When any of these are configured, the
+    sandbox is holding real credentials that the proxy can't strip — the
+    isolation guarantee is incomplete for those providers.
+
+    The wizard and ``hermes egress status`` use this to print a warning.
+    (Anthropic / Azure OpenAI / Gemini used to be here; they're now
+    first-class swapped providers via ``_HEADER_AUTH_PROVIDERS``.)
+    """
+
+    if available_env_names is not None:
+        names = set(available_env_names)
+    else:
+        names = {k for k, v in os.environ.items() if v}
+
+    return [n for n in _NON_BEARER_PROVIDERS if n in names]
+
+
+def merge_mappings(
+    *,
+    existing: List[TokenMapping],
+    discovered: List[TokenMapping],
+    rotate: bool = False,
+) -> List[TokenMapping]:
+    """Combine an existing mapping set with freshly discovered providers.
+
+    By default this PRESERVES tokens for providers already in ``existing`` —
+    re-running ``hermes egress setup`` should not invalidate the tokens
+    baked into containers that are already running.  Only newly added
+    providers get freshly minted tokens.
+
+    When ``rotate=True``, every token in the result is freshly minted
+    regardless of overlap.  The wizard exposes this via ``--rotate-tokens``
+    for the rare case where the operator wants to roll all tokens
+    deliberately (e.g. after a suspected token leak).
+
+    Providers that are in ``existing`` but no longer in ``discovered``
+    (operator removed the env var since last setup) are dropped.
+    """
+
+    by_name = {m.real_env_name: m for m in existing}
+    out: List[TokenMapping] = []
+    for d in discovered:
+        prior = by_name.get(d.real_env_name)
+        if prior is not None and not rotate:
+            # Preserve the token; refresh hosts/headers/aliases in case
+            # the provider spec changed since last setup (new upstreams,
+            # a provider moving from uncovered to header-auth, etc).
+            out.append(TokenMapping(
+                proxy_token=prior.proxy_token,
+                real_env_name=prior.real_env_name,
+                upstream_hosts=d.upstream_hosts,
+                match_headers=d.match_headers,
+                alias_env_names=d.alias_env_names,
+            ))
+        else:
+            out.append(d)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Subprocess lifecycle
+# ---------------------------------------------------------------------------
+
+
+def _pidfile() -> Path:
+    return _proxy_state_dir() / "iron-proxy.pid"
+
+
+def _read_pid() -> Optional[int]:
+    # Use the read-only path: don't create the proxy dir just to read the
+    # pidfile.  If neither pid file nor dir exists, the daemon is plainly
+    # not running.
+    pf = _proxy_state_dir_ro() / "iron-proxy.pid"
+    if not pf.exists():
+        return None
+    try:
+        pid = int(pf.read_text(encoding="utf-8").strip())
+    except (OSError, ValueError):
+        return None
+    return pid if pid > 0 else None
+
+
+# Nonce env-var set in the iron-proxy subprocess at start_proxy time.  Used
+# by ``_pid_alive`` to confirm a candidate PID still refers to *our* managed
+# binary even across PID recycling (a fresh process can't inherit our
+# arbitrary env value).
+_HERMES_IRON_PROXY_NONCE_ENV = "HERMES_IRON_PROXY_NONCE"
+_proxy_nonce: Optional[str] = None
+
+
+def _pid_proc_starttime(pid: int) -> Optional[str]:
+    """Return /proc/<pid>/stat[21] (starttime) on Linux, else None.
+
+    Comparing starttime is the standard cheap way to detect PID recycling
+    without relying on cmdline scanning.  When None, callers fall back to
+    the cmdline + nonce check.
+    """
+    try:
+        text = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8")
+    except OSError:
+        return None
+    # /proc/<pid>/stat: pid (comm-with-parens) state ppid ... fields[21]=starttime
+    # The "comm" field can contain spaces and parens, so split from the
+    # right parenthesis instead of using shlex.
+    rparen = text.rfind(")")
+    if rparen < 0:
+        return None
+    fields = text[rparen + 1:].split()
+    # field index in the post-")" tail: original 3..n become fields[0..n-3]
+    # starttime is original field 22 (1-indexed) → tail index 22-3 = 19
+    if len(fields) <= 19:
+        return None
+    return fields[19]
+
+
+def _persisted_nonce_path() -> Path:
+    """Path to the on-disk sibling of the pidfile that stores the nonce.
+
+    Written by ``_write_pidfile_safely`` after ``start_proxy`` plants
+    the nonce in the iron-proxy child env, read by ``_pid_alive`` in a
+    later CLI invocation (``stop`` / ``status``) so cross-process
+    PID-recycling defense holds.
+    """
+    return _proxy_state_dir_ro() / "iron-proxy.nonce"
+
+
+def _read_persisted_nonce() -> Optional[str]:
+    """Read the on-disk nonce written next to the pidfile.
+
+    Returns None when the file is missing, unreadable, or empty —
+    callers fall back to argv0 basename matching in that case.
+    """
+    p = _persisted_nonce_path()
+    try:
+        # O_NOFOLLOW: defence-in-depth against a planted symlink at the
+        # nonce path; same-uid required to plant one but worth defending
+        # since the nonce read here decides whether stop_proxy will
+        # SIGKILL a candidate PID.
+        flags = os.O_RDONLY
+        if hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+        fd = os.open(str(p), flags)
+    except OSError:
+        return None
+    try:
+        # Ownership check — if the file isn't owned by us, ignore it.
+        # Same threat model as the pidfile uid check.
+        try:
+            st = os.fstat(fd)
+            if hasattr(os, "getuid") and st.st_uid != os.getuid():
+                return None
+        except AttributeError:
+            pass
+        data = os.read(fd, 256).decode("utf-8", errors="ignore").strip()
+        return data or None
+    finally:
+        os.close(fd)
+
+
+def _pid_alive(pid: int) -> bool:
+    """Return True iff ``pid`` is alive AND is an iron-proxy process.
+
+    Defends against PID reuse via three signals (in priority order):
+    1. ``/proc/<pid>/environ`` contains our nonce  (most reliable, Linux)
+    2. ``/proc/<pid>/cmdline`` basename matches the managed binary
+    3. ``ps -p <pid>`` command line contains the binary path
+
+    The legacy ``"iron-proxy" in cmdline`` match was loose enough to match
+    ``tail iron-proxy.log`` or an editor with that file open.  We tighten
+    on argv[0] basename plus an in-process nonce instead.
+    """
+
+    if pid <= 0:
+        return False
+    try:
+        # Use psutil.pid_exists when available — it's a no-op on Windows
+        # whereas os.kill(pid, 0) on Windows is actually a hard kill
+        # (CTRL_C_EVENT to the target's console process group).  See
+        # bpo-14484.  windows-footgun: ok — we explicitly skip the
+        # os.kill probe on Windows below.
+        import psutil  # type: ignore
+        if not psutil.pid_exists(pid):
+            return False
+    except ImportError:
+        if platform.system() == "Windows":
+            # On Windows without psutil we can't safely probe — assume
+            # the pidfile content is fresh and confirm via the cmdline
+            # path below.  os.kill(pid, 0) is NOT safe here.
+            pass
+        else:
+            try:
+                os.kill(pid, 0)  # windows-footgun: ok — POSIX-only branch
+            except (ProcessLookupError, PermissionError, OSError):
+                return False
+
+    # Strong proof: nonce env var matches.  /proc/<pid>/environ is null-
+    # separated KEY=VALUE pairs; substring search is safe.
+    #
+    # The nonce can come from either:
+    #   1. the module-global ``_proxy_nonce`` set during this process's
+    #      own ``start_proxy`` call (same-process case);
+    #   2. the on-disk ``iron-proxy.nonce`` file written by
+    #      ``_write_pidfile_safely``, used when ``start`` and ``stop``
+    #      run in separate CLI invocations (cross-process case).
+    # Either source provides the same defeat-PID-recycling guarantee.
+    nonce_candidates: List[str] = []
+    if _proxy_nonce:
+        nonce_candidates.append(_proxy_nonce)
+    on_disk = _read_persisted_nonce()
+    if on_disk and on_disk not in nonce_candidates:
+        nonce_candidates.append(on_disk)
+    if nonce_candidates:
+        try:
+            env_bytes = Path(f"/proc/{pid}/environ").read_bytes()
+            for nonce in nonce_candidates:
+                needle = f"{_HERMES_IRON_PROXY_NONCE_ENV}={nonce}".encode()
+                if needle in env_bytes:
+                    return True
+        except OSError:
+            pass
+
+    # Fallback: cmdline basename match.  argv[0] is the first null-
+    # separated token in /proc/<pid>/cmdline.
+    try:
+        cmdline_path = Path(f"/proc/{pid}/cmdline")
+        if cmdline_path.exists():
+            tokens = cmdline_path.read_bytes().split(b"\x00")
+            if tokens:
+                argv0 = tokens[0].decode("utf-8", errors="ignore")
+                argv0_base = os.path.basename(argv0)
+                if argv0_base.startswith("iron-proxy"):
+                    return True
+            return False
+    except OSError:
+        pass
+
+    # macOS / non-Linux fallback: ``ps`` command basename.
+    try:
+        res = subprocess.run(  # noqa: S603
+            ["ps", "-p", str(pid), "-o", "comm="],
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=2,
+        )
+        if res.returncode == 0:
+            comm = (res.stdout or "").strip()
+            return os.path.basename(comm).startswith("iron-proxy")
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+    # Exotic platforms: be conservative — if the OS says alive we believe
+    # it.  This restores the previous behaviour for non-Linux/non-macOS.
+    return True
+
+
+def start_proxy(
+    *,
+    binary: Optional[Path] = None,
+    config_path: Optional[Path] = None,
+    extra_env: Optional[Dict[str, str]] = None,
+    install_if_missing: bool = True,
+    refresh_secrets_from_bitwarden: bool = False,
+    bitwarden_config: Optional[Dict] = None,
+) -> ProxyStatus:
+    """Spawn iron-proxy as a managed background subprocess.
+
+    Idempotent — if the proxy is already running with the expected PID,
+    just returns the live status.
+
+    ``refresh_secrets_from_bitwarden=True`` re-fetches upstream secrets
+    via ``bws secret list`` at startup and injects them into the child
+    env.  This delivers the rotation promise that distinguishes
+    ``credential_source: bitwarden`` from ``credential_source: env``.
+    Without this flag (or with ``bitwarden_config=None``) the proxy still
+    starts but uses whatever the host process env happens to contain.
+    """
+
+    global _proxy_nonce
+
+    existing = _read_pid()
+    if existing and _pid_alive(existing):
+        return get_status()
+
+    bin_path = binary or find_iron_proxy(install_if_missing=install_if_missing)
+    if bin_path is None:
+        raise RuntimeError(
+            "iron-proxy binary not available — run `hermes egress install`."
+        )
+
+    cfg = config_path or (_proxy_state_dir() / "proxy.yaml")
+    if not cfg.exists():
+        raise RuntimeError(
+            f"iron-proxy config not found at {cfg}. "
+            "Run `hermes egress setup` first."
+        )
+
+    # Build a minimal subprocess env.  os.environ.copy() would ship every
+    # secret in the operator's shell to the proxy — /proc/<pid>/environ
+    # would then expose OPENAI_API_KEY, AWS keys, etc. to any same-uid
+    # local process.  Defeats the threat model the proxy exists to
+    # mitigate.
+    env = _build_proxy_subprocess_env(
+        extra_env=extra_env,
+        refresh_from_bitwarden=refresh_secrets_from_bitwarden,
+        bitwarden_config=bitwarden_config,
+    )
+
+    # If the generated config enables the management API, the daemon
+    # validates at startup that the api_key_env is non-empty.  Inject the
+    # persisted key (minting it if this is a config written by a newer
+    # setup but the token file was removed).
+    if _read_management_listen_from_config(cfg) is not None:
+        env[_MGMT_API_KEY_ENV] = ensure_management_token()
+
+    # Plant a per-start nonce in the child env so ``_pid_alive`` can
+    # confirm a candidate PID still refers to *our* binary across PID
+    # recycling.  Module-global is fine — only one managed proxy per
+    # Hermes process.
+    _proxy_nonce = hashlib.sha256(os.urandom(16)).hexdigest()
+    env[_HERMES_IRON_PROXY_NONCE_ENV] = _proxy_nonce
+
+    log_path = _proxy_state_dir() / "iron-proxy.log"
+    # Keep ownership of the fd tight: open with explicit 0o600 so the
+    # log doesn't get world-readable under a slack umask, then close it
+    # immediately after Popen (the child has its own dup).  Without the
+    # close-on-success path, every restart leaked one fd in the Hermes
+    # process.
+    #
+    # O_NOFOLLOW (defence-in-depth, same threat model as the pidfile
+    # path): a same-uid attacker who plants ``iron-proxy.log`` as a
+    # symlink to e.g. ``~/.ssh/authorized_keys`` would otherwise cause
+    # every restart to append daemon diagnostics to that file.
+    log_open_flags = os.O_WRONLY | os.O_CREAT | os.O_APPEND
+    if hasattr(os, "O_NOFOLLOW"):
+        log_open_flags |= os.O_NOFOLLOW
+    try:
+        log_fd = os.open(str(log_path), log_open_flags, 0o600)
+    except OSError as exc:
+        # ELOOP from a planted symlink — refuse with a clear error.
+        raise RuntimeError(
+            f"Refusing to write iron-proxy log {log_path}: {exc}.  "
+            "Remove that path manually and retry."
+        ) from exc
+    try:
+        os.fchmod(log_fd, 0o600)  # tighten if file pre-existed
+    except OSError:
+        pass
+    # Verify ownership — same st_uid check the pidfile uses.
+    try:
+        st = os.fstat(log_fd)
+        if hasattr(os, "getuid") and st.st_uid != os.getuid():
+            os.close(log_fd)
+            raise RuntimeError(
+                f"iron-proxy log {log_path} has unexpected owner "
+                f"uid={st.st_uid}; refusing to write."
+            )
+    except AttributeError:
+        pass  # Windows
+
+    try:
+        # Use the fd directly via the dup mechanism; Popen will dup() it
+        # into the child so we can close ours unconditionally below.
+        # NOTE: on Windows ``start_new_session`` is invalid; we don't
+        # support Windows for the proxy (the binary itself doesn't ship)
+        # but the kwarg is POSIX-only and silently ignored on Win.
+        popen_kwargs: Dict = dict(
+            env=env,
+            stdin=subprocess.DEVNULL,
+            stdout=log_fd,
+            stderr=subprocess.STDOUT,
+        )
+        if platform.system() != "Windows":
+            popen_kwargs["start_new_session"] = True
+        proc = subprocess.Popen(  # noqa: S603 — binary path is trusted
+            [str(bin_path), "-config", str(cfg)],
+            **popen_kwargs,
+        )
+    except OSError as exc:
+        os.close(log_fd)
+        raise RuntimeError(f"failed to spawn iron-proxy: {exc}") from exc
+    finally:
+        # Close our copy of the fd whether Popen raised or succeeded.
+        # The child has its own dup via Popen, so it's still writing.
+        try:
+            os.close(log_fd)
+        except OSError:
+            pass
+
+    # Write the pidfile IMMEDIATELY after Popen, BEFORE the listening
+    # verification.  If the parent dies during the poll loop (SIGINT,
+    # OOM, kernel pause), the pidfile is still on disk so the next
+    # ``hermes egress stop`` can clean up the orphan.  Failure paths
+    # below unlink the pidfile when they kill the child.
+    pidfile = _pidfile()
+    try:
+        _write_pidfile_safely(pidfile, proc.pid)
+    except RuntimeError:
+        # Kill the orphan so we don't leave a daemon nobody can stop.
+        _kill_and_wait(proc, grace_seconds=2)
+        raise
+
+    # Poll-with-timeout instead of an unconditional 5s sleep.  The Go
+    # binary normally comes up in <200ms; falling through within 100ms
+    # of liveness keeps Docker container creation snappy.
+    #
+    # We scope a Ctrl-C handler around the poll loop so an operator who
+    # hits Ctrl-C while waiting for ``hermes egress start`` doesn't leak
+    # an orphan with the port bound.
+    #
+    # Probe the CONFIGURED bind host, not loopback unconditionally — on
+    # Linux the daemon binds the docker bridge gateway, where a loopback
+    # connect never succeeds and we'd kill a healthy daemon as "never
+    # came up".
+    listen_hp = _read_http_listen_from_config()
+    if listen_hp is not None:
+        probe_host, tunnel_port = listen_hp
+    else:
+        probe_host, tunnel_port = "127.0.0.1", _DEFAULT_TUNNEL_PORT
+    listening = False
+
+    def _interrupt_handler(_signum, _frame):  # pragma: no cover - signal path
+        # Kill the child and unlink the pidfile, then re-raise so the
+        # caller sees the interrupt.
+        _kill_and_wait(proc, grace_seconds=2)
+        try:
+            pidfile.unlink()
+        except FileNotFoundError:
+            pass
+        raise KeyboardInterrupt()
+
+    prev_sigint = None
+    prev_sigterm = None
+    install_handlers = (
+        platform.system() != "Windows"
+        and threading.current_thread() is threading.main_thread()
+    )
+    if install_handlers:
+        prev_sigint = signal.signal(signal.SIGINT, _interrupt_handler)
+        prev_sigterm = signal.signal(signal.SIGTERM, _interrupt_handler)
+    try:
+        deadline = time.time() + _STARTUP_GRACE_SECONDS
+        # Do-while shape: check listening at least once even when the
+        # grace window is 0 (test harness / synchronous fast-path).
+        while True:
+            if proc.poll() is not None:
+                tail = _tail_log(log_path, lines=20)
+                try:
+                    pidfile.unlink()
+                except FileNotFoundError:
+                    pass
+                raise RuntimeError(
+                    f"iron-proxy exited immediately (code {proc.returncode}). "
+                    f"Last log lines:\n{tail}"
+                )
+            if _port_listening(probe_host, tunnel_port):
+                listening = True
+                break
+            if time.time() >= deadline:
+                break
+            time.sleep(0.1)
+    finally:
+        if install_handlers:
+            signal.signal(signal.SIGINT, prev_sigint)
+            signal.signal(signal.SIGTERM, prev_sigterm)
+
+    # Final exit check — process may have died right at deadline.
+    if proc.poll() is not None:
+        tail = _tail_log(log_path, lines=20)
+        try:
+            pidfile.unlink()
+        except FileNotFoundError:
+            pass
+        raise RuntimeError(
+            f"iron-proxy exited immediately (code {proc.returncode}). "
+            f"Last log lines:\n{tail}"
+        )
+
+    # The previous version of this code treated "process still alive at
+    # deadline" as success.  That left iron-proxy running but
+    # non-listening on the port, with a pidfile pointing at it —
+    # subsequent restarts would fail with "address in use" because the
+    # orphan still held the port.  Require port-listening for success.
+    if not listening:
+        tail = _tail_log(log_path, lines=20)
+        _kill_and_wait(proc, grace_seconds=2)
+        try:
+            pidfile.unlink()
+        except FileNotFoundError:
+            pass
+        raise RuntimeError(
+            f"iron-proxy did not bind {probe_host}:{tunnel_port} within "
+            f"{_STARTUP_GRACE_SECONDS}s.  Process was killed.  "
+            f"Last log lines:\n{tail}"
+        )
+
+    logger.info("Started iron-proxy pid=%s config=%s", proc.pid, cfg)
+    return get_status()
+
+
+def _write_pidfile_safely(pidfile: Path, pid: int) -> None:
+    """Write ``pid`` to ``pidfile`` with O_EXCL + O_NOFOLLOW + ownership check.
+
+    O_EXCL means "another start is in progress" if the file already
+    exists with a live owner — we cleanly fail rather than racing.  When
+    the existing pidfile points at a dead pid (stale crash), we
+    explicitly unlink it before retrying once.
+
+    Side effect: also persists the in-process nonce to disk so
+    cross-CLI-invocation ``_pid_alive`` checks (start in one process,
+    stop in another) can still defeat PID recycling.
+    """
+    open_flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        open_flags |= os.O_NOFOLLOW
+    try:
+        fd = os.open(str(pidfile), open_flags, 0o600)
+    except FileExistsError:
+        # Pidfile already exists.  If it points at a live iron-proxy,
+        # caller's _read_pid + _pid_alive at the top of start_proxy
+        # should already have returned.  Reaching here means EITHER
+        # the previous _pid_alive check raced (rare; another start in
+        # flight), OR a stale pidfile survived a crash.  Discriminate
+        # and retry once with O_TRUNC if stale.
+        existing_pid = _read_pid()
+        if existing_pid and _pid_alive(existing_pid):
+            raise RuntimeError(
+                f"Another iron-proxy start appears to be in progress "
+                f"(pidfile {pidfile} -> pid {existing_pid}).  "
+                f"Run `hermes egress stop` if that proxy is stuck."
+            )
+        # Stale — unlink and retry.
+        try:
+            pidfile.unlink()
+        except FileNotFoundError:
+            pass
+        fd = os.open(str(pidfile), open_flags, 0o600)
+    except OSError as exc:
+        # ELOOP from a planted symlink at the pidfile path.
+        raise RuntimeError(
+            f"Refusing to write pidfile {pidfile}: {exc}.  "
+            "Remove that path manually and retry."
+        ) from exc
+
+    try:
+        # Ownership check — same st_uid pattern the log file uses.
+        try:
+            st = os.fstat(fd)
+            if hasattr(os, "getuid") and st.st_uid != os.getuid():
+                raise RuntimeError(
+                    f"pidfile {pidfile} has unexpected owner uid={st.st_uid}"
+                )
+        except AttributeError:
+            pass  # Windows
+        os.write(fd, str(pid).encode("utf-8"))
+    finally:
+        os.close(fd)
+
+    # Persist the nonce next to the pidfile (sibling, 0o600).
+    # ``stop_proxy`` in a separate CLI invocation can read this and use
+    # it to confirm the pid still refers to our binary even though the
+    # module-global ``_proxy_nonce`` is fresh in the new process.
+    if _proxy_nonce:
+        noncefile = pidfile.with_suffix(".nonce")
+        nfd = -1
+        try:
+            nopen = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+            if hasattr(os, "O_NOFOLLOW"):
+                nopen |= os.O_NOFOLLOW
+            nfd = os.open(str(noncefile), nopen, 0o600)
+            os.write(nfd, _proxy_nonce.encode("utf-8"))
+        except OSError:
+            # Best-effort.  Without the nonce file we fall back to
+            # argv0-basename matching, which is what we did before.
+            pass
+        finally:
+            if nfd >= 0:
+                try:
+                    os.close(nfd)
+                except OSError:
+                    pass
+
+
+def _kill_and_wait(proc: "subprocess.Popen", *, grace_seconds: int = 2) -> None:
+    """Best-effort SIGTERM → wait → SIGKILL for a child we own."""
+    try:
+        proc.terminate()
+    except OSError:
+        return
+    try:
+        proc.wait(timeout=grace_seconds)
+    except subprocess.TimeoutExpired:
+        try:
+            proc.kill()
+        except OSError:
+            pass
+        try:
+            proc.wait(timeout=grace_seconds)
+        except subprocess.TimeoutExpired:
+            pass
+
+
+def _build_proxy_subprocess_env(
+    *,
+    extra_env: Optional[Dict[str, str]] = None,
+    refresh_from_bitwarden: bool = False,
+    bitwarden_config: Optional[Dict] = None,
+) -> Dict[str, str]:
+    """Construct the minimal env for the iron-proxy subprocess.
+
+    Allowlists infrastructure vars (PATH, HOME, locale) plus the env vars
+    named in ``load_mappings()`` (the real upstream secrets the proxy
+    needs to do the swap).  Everything else is stripped — see
+    ``_PROXY_SUBPROCESS_ENV_STRIP`` for proxy chain protection.
+
+    When ``refresh_from_bitwarden=True`` AND ``bitwarden_config`` is
+    populated, fetches upstream secrets via the BSM SDK at startup and
+    merges them in.  This is what delivers the rotation guarantee
+    promised by ``credential_source: bitwarden`` — without it, rotating
+    a key in the Bitwarden web app doesn't reach the proxy.
+    """
+
+    env: Dict[str, str] = {}
+    parent = os.environ
+    for name in _PROXY_SUBPROCESS_ENV_ALLOWLIST:
+        if name in parent:
+            env[name] = parent[name]
+
+    # The proxy reads the real upstream secrets from its OWN env, indexed
+    # by ``m.real_env_name`` in the YAML config's ``secrets.source.var``
+    # field.  Forward those — but only those.  For alias providers
+    # (GEMINI_API_KEY / GOOGLE_API_KEY), the rule is keyed on the canonical
+    # name; when only the alias is set in the host env, mirror its value
+    # into the canonical name so the swap still has a real secret.
+    alias_sources: Dict[str, Tuple[str, ...]] = {}
+    needed = set()
+    for m in load_mappings():
+        needed.add(m.real_env_name)
+        if m.alias_env_names:
+            alias_sources[m.real_env_name] = tuple(m.alias_env_names)
+    for name in needed:
+        if name in parent:
+            env[name] = parent[name]
+        else:
+            for alias in alias_sources.get(name, ()):
+                if parent.get(alias):
+                    env[name] = parent[alias]
+                    break
+
+    # Optional Bitwarden refresh path.  Pulled lazily so the proxy module
+    # doesn't hard-depend on the bitwarden module being importable in
+    # every install.
+    if refresh_from_bitwarden and bitwarden_config:
+        try:
+            from agent.secret_sources import bitwarden as bw
+            access_token_name = bitwarden_config.get(
+                "access_token_env", "BWS_ACCESS_TOKEN"
+            )
+            access_token = parent.get(access_token_name, "").strip()
+            project_id = bitwarden_config.get("project_id", "")
+            if access_token and project_id:
+                secrets, warnings = bw.fetch_bitwarden_secrets(
+                    access_token=access_token,
+                    project_id=project_id,
+                    cache_ttl_seconds=0,
+                    use_cache=False,
+                )
+                # Only inject env names we have a mapping for — extra
+                # secrets in the BW project shouldn't leak into the proxy
+                # process unless they're going to be used by the swap.
+                missing = sorted(needed - set(secrets))
+                for n in needed:
+                    if n in secrets:
+                        env[n] = secrets[n]
+                if missing:
+                    # stephenschoettler #1: don't silently keep stale
+                    # host-env values when BWS mode was explicitly
+                    # selected.  An operator on credential_source=bitwarden
+                    # picked it specifically to get rotation; falling back
+                    # to parent env reintroduces the bug class the mode
+                    # is supposed to defeat.  ``allow_env_fallback`` is the
+                    # documented, deliberate opt-out — honor it here exactly
+                    # as the empty-token branch below does (the error
+                    # message tells operators to set it, so it must work).
+                    if not (bitwarden_config or {}).get("allow_env_fallback"):
+                        raise RuntimeError(
+                            f"Bitwarden refresh did not return secrets for "
+                            f"{missing}.  Either add the secrets to your BWS "
+                            f"project, switch to credential_source: env via "
+                            f"`hermes egress setup --no-bitwarden`, or set "
+                            f"`proxy.allow_env_fallback: true` in config.yaml "
+                            f"to opt into the legacy host-env fallback."
+                        )
+                    logger.warning(
+                        "Bitwarden refresh did not return secrets for %s — "
+                        "falling back to host env for those names "
+                        "(allow_env_fallback=true).",
+                        missing,
+                    )
+                # bws warnings are non-secret status messages (e.g. "no
+                # project found", "rate limited"), but the taint analyzer
+                # can't tell that — log the count and let the operator
+                # rerun under verbose if they need detail.
+                if warnings:
+                    logger.warning(
+                        "Bitwarden refresh produced %d warning(s); "
+                        "run `hermes secrets bitwarden status` for detail.",
+                        len(warnings),
+                    )
+            else:
+                # NOTE: deliberately do not interpolate access_token_name
+                # in the log message — CodeQL's taint analyzer treats
+                # bitwarden_config values as secret-tainted (it can't
+                # distinguish the env-var NAME from the env-var VALUE).
+                # The name is non-secret but logging it just trips the
+                # check for no real benefit.
+                if not (bitwarden_config or {}).get("allow_env_fallback"):
+                    raise RuntimeError(
+                        "credential_source=bitwarden but the access-token "
+                        "env or project_id is empty.  Either set both, "
+                        "switch to credential_source: env, or set "
+                        "`proxy.allow_env_fallback: true` to opt into "
+                        "the legacy fallback behaviour."
+                    )
+                logger.warning(
+                    "credential_source=bitwarden but access-token env or "
+                    "project_id is empty — proxy will fall back to parent env "
+                    "(allow_env_fallback=true).",
+                )
+        except (ImportError,) as exc:
+            # The BWS module or one of its runtime deps isn't importable.
+            # Mirror the sibling branches: if allow_env_fallback isn't
+            # explicitly enabled, fail closed — credential_source=bitwarden
+            # with a unavailable module should not silently degrade to host
+            # env.  A wizard-time check can't catch a dependency that goes
+            # missing between setup and a later restart.
+            if not (bitwarden_config or {}).get("allow_env_fallback"):
+                raise RuntimeError(
+                    "Bitwarden refresh module unavailable at proxy start "
+                    "(credential_source=bitwarden with "
+                    "proxy.allow_env_fallback: false).  Either fix the "
+                    "import, switch to credential_source: env, or set "
+                    "`proxy.allow_env_fallback: true` to opt into the "
+                    "legacy fallback behaviour."
+                ) from exc
+            logger.warning(
+                "Bitwarden refresh module unavailable at proxy start, "
+                "falling back to parent env (allow_env_fallback=true): %s",
+                exc,
+            )
+
+    # Caller-supplied overrides win.  This is intentionally last so the
+    # wizard can inject ad-hoc test secrets without recomputing the BW
+    # path.
+    if extra_env:
+        env.update(extra_env)
+
+    # Strip proxy-recursion-risk vars regardless of how they got in.
+    for name in _PROXY_SUBPROCESS_ENV_STRIP:
+        env.pop(name, None)
+
+    env.setdefault("NO_COLOR", "1")
+    return env
+
+
+def stop_proxy() -> bool:
+    """Stop the managed iron-proxy.  Returns True if it was running."""
+
+    global _proxy_nonce
+
+    def _cleanup_state_files() -> None:
+        """Best-effort cleanup of pidfile + persisted nonce."""
+        _pidfile().unlink(missing_ok=True)
+        try:
+            _persisted_nonce_path().unlink()
+        except FileNotFoundError:
+            pass
+        except OSError:
+            pass
+
+    pid = _read_pid()
+    if not pid or not _pid_alive(pid):
+        _cleanup_state_files()
+        _proxy_nonce = None
+        return False
+
+    # Capture starttime BEFORE signalling so we can compare after the
+    # grace window — if the pid got recycled mid-wait, the starttime
+    # changes and we abort the SIGKILL.
+    starttime_before = _pid_proc_starttime(pid)
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        _cleanup_state_files()
+        _proxy_nonce = None
+        return False
+
+    # Wait up to 5s for graceful exit, then SIGKILL.
+    deadline = time.time() + 5.0
+    while time.time() < deadline:
+        if not _pid_alive(pid):
+            break
+        time.sleep(0.1)
+    else:
+        # Verify the pid hasn't been recycled before delivering SIGKILL.
+        # Two checks:
+        #   1. /proc/<pid>/stat starttime is unchanged (Linux)
+        #   2. _pid_alive() still says it's an iron-proxy process
+        starttime_after = _pid_proc_starttime(pid)
+        recycled = (
+            starttime_before is not None
+            and starttime_after is not None
+            and starttime_before != starttime_after
+        ) or not _pid_alive(pid)
+        if recycled:
+            logger.warning(
+                "iron-proxy pid=%s appears recycled before SIGKILL; "
+                "not killing.", pid,
+            )
+        else:
+            try:
+                os.kill(pid, _KILL_SIGNAL)
+            except ProcessLookupError:
+                pass
+
+    _cleanup_state_files()
+    _proxy_nonce = None
+    logger.info("Stopped iron-proxy pid=%s", pid)
+    return True
+
+
+def get_status() -> ProxyStatus:
+    """Snapshot the current proxy state — does NOT start anything.
+
+    Crucially, this is called per Docker-container-create when egress
+    enforcement is on.  It must not have side-effects (no mkdir, no
+    binary version subprocess that takes 30s on a hung binary).  The
+    state dir is read-only here.
+    """
+
+    status = ProxyStatus()
+    listen_hp = _read_http_listen_from_config()
+    if listen_hp is not None:
+        probe_host, status.tunnel_port = listen_hp
+    else:
+        probe_host = "127.0.0.1"
+        status.tunnel_port = _DEFAULT_TUNNEL_PORT
+
+    binary = find_iron_proxy(install_if_missing=False)
+    if binary:
+        status.binary_path = binary
+        # Cached — see iron_proxy_version().  First call still costs one
+        # subprocess; subsequent calls in the same process are dict
+        # lookups.
+        status.binary_version = iron_proxy_version(binary)
+
+    state = _proxy_state_dir_ro()
+    cfg = state / "proxy.yaml"
+    ca = state / "ca.crt"
+    if cfg.exists():
+        status.config_path = cfg
+    if ca.exists():
+        status.ca_cert_path = ca
+
+    pid = _read_pid()
+    if pid and _pid_alive(pid):
+        status.pid = pid
+        # Probe the configured bind host — on Linux that's the docker
+        # bridge gateway, where a loopback connect would report a healthy
+        # daemon as "not listening".
+        status.listening = _port_listening(probe_host, status.tunnel_port)
+
+    return status
+
+
+def _read_tunnel_port_from_config() -> Optional[int]:
+    listen = _read_http_listen_from_config()
+    if listen is None:
+        return None
+    return listen[1]
+
+
+def _read_http_listen_from_config() -> Optional[Tuple[str, int]]:
+    """Return ``(host, port)`` of the configured sandbox-facing listener.
+
+    Reads ``proxy.tunnel_listen`` — the CONNECT/MITM listener sandboxes
+    hit via ``HTTPS_PROXY`` — falling back to ``proxy.http_listen`` for
+    configs written before the tunnel/http listener-role split.
+
+    The bind host matters for liveness probes: on Linux the daemon binds
+    the docker bridge gateway (e.g. ``172.17.0.1``), where a loopback
+    connect would report "not listening" for a perfectly healthy daemon.
+    """
+
+    cfg = _proxy_state_dir_ro() / "proxy.yaml"
+    if not cfg.exists():
+        return None
+    try:
+        import yaml
+    except ImportError:
+        return None
+    try:
+        data = yaml.safe_load(cfg.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    proxy_block = (data or {}).get("proxy") or {}
+    # The CLI/Docker side calls this "the tunnel port" because that's how
+    # sandboxes use it (HTTPS_PROXY) — on the iron-proxy side it's the
+    # tunnel_listen (CONNECT + MITM).  http_listen is the plain-HTTP
+    # forward listener on tunnel_port+1.
+    listen = proxy_block.get("tunnel_listen") or proxy_block.get("http_listen") or ""
+    if not isinstance(listen, str) or ":" not in listen:
+        return None
+    host, _, port_s = listen.rpartition(":")
+    try:
+        port = int(port_s)
+    except ValueError:
+        return None
+    return (host or "127.0.0.1", port)
+
+
+def _port_listening(host: str, port: int) -> bool:
+    """Cheap TCP connect probe — True iff something accepts on host:port."""
+
+    import socket
+
+    try:
+        with socket.create_connection((host, port), timeout=0.5):
+            return True
+    except OSError:
+        return False
+
+
+def _tail_log(path: Path, *, lines: int = 20) -> str:
+    if not path.exists():
+        return "(no log file)"
+    try:
+        data = path.read_bytes()[-8192:]
+        return "\n".join(data.decode("utf-8", errors="replace").splitlines()[-lines:])
+    except OSError as exc:
+        return f"(could not read log: {exc})"
+
+
+# ---------------------------------------------------------------------------
+# Test hook
+# ---------------------------------------------------------------------------
+
+
+def _reset_for_tests() -> None:
+    """Clear module-level caches so tests get a fresh start.
+
+    This module owns two mutable globals that need reset between tests:
+    - ``_VERSION_CACHE`` — subprocess output cache keyed by binary path.
+    - ``_proxy_nonce`` — the strong-proof token written by ``start_proxy``
+      and read by ``_pid_alive`` to defeat PID recycling.
+
+    Today the repo's tests run each file in its own subprocess (per
+    AGENTS.md) so leakage is bounded, but any in-process caller
+    (notebooks, ad-hoc scripts, ``pytest -p no:xdist``) would otherwise
+    see whichever values were probed first regardless of subsequent
+    ``install_iron_proxy(force=True)`` or ``start_proxy`` calls.
+    """
+
+    global _proxy_nonce
+    _VERSION_CACHE.clear()
+    _proxy_nonce = None
+
+
+# Make a small set of symbols available without underscored access.
+__all__ = [
+    "ProxyStatus",
+    "TokenMapping",
+    "build_proxy_config",
+    "discover_provider_mappings",
+    "discover_uncovered_providers",
+    "ensure_audit_log",
+    "ensure_ca_cert",
+    "ensure_management_token",
+    "find_iron_proxy",
+    "get_status",
+    "install_iron_proxy",
+    "iron_proxy_version",
+    "load_mappings",
+    "merge_mappings",
+    "mint_proxy_token",
+    "reload_proxy",
+    "start_proxy",
+    "stop_proxy",
+    "write_mappings",
+    "write_proxy_config",
+]
diff --git a/agent/reasoning_timeouts.py b/agent/reasoning_timeouts.py
index 13df836b110..8af5ab799f4 100644
--- a/agent/reasoning_timeouts.py
+++ b/agent/reasoning_timeouts.py
@@ -102,6 +102,7 @@ _REASONING_STALE_TIMEOUT_FLOORS: tuple[tuple[str, int], ...] = (
     # ``claude-opus-4`` so non-thinking Claude 3.x or future
     # non-reasoning Claude variants don't match.
     ("claude-opus-4", 240),
+    ("claude-opus-5", 240),
     ("claude-sonnet-5", 180),
     ("claude-sonnet-4.5", 180),
     ("claude-sonnet-4.6", 180),
diff --git a/agent/secret_sources/base.py b/agent/secret_sources/base.py
index d4ead7d3f26..070051e046b 100644
--- a/agent/secret_sources/base.py
+++ b/agent/secret_sources/base.py
@@ -295,7 +295,7 @@ def run_secret_cli(
             list(argv),
             env=env,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=timeout,
             stdin=subprocess.DEVNULL,
         )
diff --git a/agent/secret_sources/bitwarden.py b/agent/secret_sources/bitwarden.py
index 8b047880be1..2d993f396c2 100644
--- a/agent/secret_sources/bitwarden.py
+++ b/agent/secret_sources/bitwarden.py
@@ -200,7 +200,7 @@ def _platform_asset_name() -> str:
             res = subprocess.run(
                 ["ldd", "--version"],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=2,
                 stdin=subprocess.DEVNULL,
             )
@@ -684,7 +684,7 @@ def _run_bws_list(
             cmd,
             env=env,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=_BWS_RUN_TIMEOUT,
             stdin=subprocess.DEVNULL,
         )
diff --git a/agent/shell_hooks.py b/agent/shell_hooks.py
index c1cec81df33..80453bc3713 100644
--- a/agent/shell_hooks.py
+++ b/agent/shell_hooks.py
@@ -464,7 +464,7 @@ def _spawn(spec: ShellHookSpec, stdin_json: str) -> Dict[str, Any]:
             input=stdin_json,
             capture_output=True,
             timeout=spec.timeout,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             shell=False,
             **_popen_kwargs,
         )
@@ -632,7 +632,7 @@ def allowlist_path() -> Path:
 def load_allowlist() -> Dict[str, Any]:
     """Return the parsed allowlist, or an empty skeleton if absent."""
     try:
-        raw = json.loads(allowlist_path().read_text())
+        raw = json.loads(allowlist_path().read_text(encoding="utf-8"))
     except (FileNotFoundError, json.JSONDecodeError, OSError):
         return {"approvals": []}
     if not isinstance(raw, dict):
diff --git a/agent/skill_commands.py b/agent/skill_commands.py
index 11d425b91a5..294ca2b1754 100644
--- a/agent/skill_commands.py
+++ b/agent/skill_commands.py
@@ -54,6 +54,21 @@ _BUNDLE_MARKER = " skill bundle,"
 _BUNDLE_USER_INSTRUCTION = "\nUser instruction: "
 _BUNDLE_FIRST_SKILL_BLOCK = "\n\n[Loaded as part of the "
 
+# The skill name sits in the first quoted span of the activation note, for both
+# the single-skill and the bundle header ("work" / "/clean /work").
+_SKILL_NAME_RE = re.compile(re.escape(_SKILL_INVOCATION_PREFIX) + r'"([^"]*)"')
+
+# SQL LIKE pattern matching a skill-expanded turn, for listing queries that
+# have to recognize scaffolding before the row reaches Python. The prefix
+# contains no LIKE wildcards (`%`, `_`), so it needs no ESCAPE clause.
+SKILL_SCAFFOLD_SQL_LIKE = _SKILL_INVOCATION_PREFIX + "%"
+
+# Marks where a preview query joined the head and tail of a long scaffolded
+# message. ``describe_skill_invocation`` may hand back a span that runs across
+# the joint (a bundle instruction cut off by the head window); callers cut the
+# description there rather than show the skill body on the far side.
+SKILL_EXCERPT_JOINT = "\x1e"
+
 
 def extract_user_instruction_from_skill_message(content: Any) -> Optional[str]:
     """Recover the user's instruction from a slash-skill-expanded turn.
@@ -82,6 +97,41 @@ def extract_user_instruction_from_skill_message(content: Any) -> Optional[str]:
     return None
 
 
+def describe_skill_invocation(content: Any) -> Optional[str]:
+    """Render a slash-skill-expanded turn the way the user typed it.
+
+    The expanded message embeds the whole skill body, so any surface that
+    summarizes a user turn from its raw content — session titles, sidebar
+    previews, the ``/rewind`` picker — otherwise shows the skill's own prose
+    as if the user had written it. That is how a skill's opening line ends up
+    as a session title.
+
+    Returns ``"/work — fix the title leak"``, or ``"/work"`` for a bare
+    invocation, or ``None`` when *content* is not skill scaffolding (the
+    caller should then summarize it as an ordinary message).
+    """
+    if not isinstance(content, str) or not content.startswith(_SKILL_INVOCATION_PREFIX):
+        return None
+
+    match = _SKILL_NAME_RE.match(content)
+    name = (match.group(1) if match else "").strip()
+    # Bundle headers already carry their typed "/a /b" keys; a single skill is
+    # a bare name.
+    label = name if name.startswith("/") else f"/{name}"
+
+    instruction = extract_user_instruction_from_skill_message(content)
+    if instruction and instruction is not content:
+        # An excerpted message (head + tail, joined by SKILL_EXCERPT_JOINT) can
+        # put the joint inside the matched span — keep only the side the
+        # instruction marker was found on.
+        instruction = instruction.split(SKILL_EXCERPT_JOINT)[0]
+        instruction = " ".join(instruction.split())
+        if instruction:
+            return f"{label} — {instruction}" if name else instruction
+
+    return label if name else None
+
+
 def _extract_single_skill_user_instruction(message: str) -> Optional[str]:
     # Single-skill format appends the user instruction after the skill body, so
     # the last occurrence is the user-provided one; the body may quote this text.
@@ -453,8 +503,8 @@ def reload_skills() -> Dict[str, Any]:
             }
 
         ``description`` is the skill's full SKILL.md frontmatter
-        ``description:`` field — the same string the system prompt renders
-        as ``    - name: description`` for pre-existing skills.
+        ``description:`` field. Note: the system prompt skill index
+        truncates this to the first 57 chars; see ``extract_skill_description``.
     """
     # Snapshot pre-reload state (name -> description) from the current
     # slash-command cache. Using dicts lets the post-rescan diff carry
diff --git a/agent/skill_preprocessing.py b/agent/skill_preprocessing.py
index bd0386d5805..19c6eeb80fb 100644
--- a/agent/skill_preprocessing.py
+++ b/agent/skill_preprocessing.py
@@ -74,7 +74,7 @@ def run_inline_shell(command: str, cwd: Path | None, timeout: int) -> str:
             ["bash", "-c", command],
             cwd=str(cwd) if cwd else None,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=max(1, int(timeout)),
             check=False,
             stdin=subprocess.DEVNULL,
diff --git a/agent/skill_utils.py b/agent/skill_utils.py
index f96238b9bd9..df0f933317f 100644
--- a/agent/skill_utils.py
+++ b/agent/skill_utils.py
@@ -779,18 +779,31 @@ def resolve_skill_config_values(
 
 # ── Description extraction ────────────────────────────────────────────────
 
+SKILL_PROMPT_DESC_LIMIT = 60
+
+
+def _normalize_skill_description(frontmatter: Dict[str, Any]) -> str:
+    """Normalize a skill's description field for comparison/truncation."""
+    raw_desc = frontmatter.get("description", "")
+    return str(raw_desc).strip().strip("'\"") if raw_desc else ""
+
 
 def extract_skill_description(frontmatter: Dict[str, Any]) -> str:
-    """Extract a truncated description from parsed frontmatter."""
-    raw_desc = frontmatter.get("description", "")
-    if not raw_desc:
+    """Extract a system-prompt-length description from parsed frontmatter."""
+    desc = _normalize_skill_description(frontmatter)
+    if not desc:
         return ""
-    desc = str(raw_desc).strip().strip("'\"")
-    if len(desc) > 60:
-        return desc[:57] + "..."
+    if len(desc) > SKILL_PROMPT_DESC_LIMIT:
+        return desc[:SKILL_PROMPT_DESC_LIMIT - 3] + "..."
     return desc
 
 
+def is_skill_description_truncated_for_prompt(frontmatter: Dict[str, Any]) -> bool:
+    """True when the description will be truncated in the system prompt skill index."""
+    desc = _normalize_skill_description(frontmatter)
+    return len(desc) > SKILL_PROMPT_DESC_LIMIT
+
+
 # ── File iteration ────────────────────────────────────────────────────────
 
 
diff --git a/agent/ssl_guard.py b/agent/ssl_guard.py
index 557f8566c32..ac1b7841b2d 100644
--- a/agent/ssl_guard.py
+++ b/agent/ssl_guard.py
@@ -31,7 +31,8 @@ def _skip_ssl_guard_enabled() -> bool:
 
 def _repair_hint() -> str:
     return (
-        "Repair: python -m pip install --force-reinstall certifi openai httpx\n"
+        "Repair: run `hermes doctor --fix` (auto-reinstalls certifi), or "
+        "manually: python -m pip install --force-reinstall certifi openai httpx\n"
         "If you configured a custom corporate CA bundle, fix or unset the "
         "broken CA bundle environment variable."
     )
diff --git a/agent/system_prompt.py b/agent/system_prompt.py
index aab34cb799e..d92072d1ac1 100644
--- a/agent/system_prompt.py
+++ b/agent/system_prompt.py
@@ -12,9 +12,11 @@ Three tiers are joined with ``\\n\\n``:
 * ``stable``   — identity (SOUL.md or DEFAULT_AGENT_IDENTITY), tool
   guidance, computer-use guidance, nous subscription block, tool-use
   enforcement guidance + per-model operational guidance, skills prompt,
-  alibaba model-name workaround, environment hints, platform hints.
+  alibaba model-name workaround, environment hints, coding guidance,
+  platform hints.
 * ``context``  — caller-supplied ``system_message`` plus context files
-  (AGENTS.md / .cursorrules / etc.) discovered under ``TERMINAL_CWD``.
+  (AGENTS.md / .cursorrules / etc.) discovered under ``TERMINAL_CWD``,
+  plus the session's coding-workspace snapshot.
 * ``volatile`` — memory snapshot, USER.md profile, external memory
   provider block, timestamp/session/model/provider line.
 
@@ -145,14 +147,14 @@ def _tui_embedded_pane_clarifier(hint: str) -> str:
 
 
 def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None) -> Dict[str, str]:
-    """Assemble the system prompt as three ordered parts.
+    """Assemble the system prompt as three ordered cache tiers.
 
     Returns a dict with three keys:
-      * ``stable``   — identity, tool guidance, skills prompt,
-        environment hints, platform hints, model-family operational
-        guidance.
-      * ``context``  — context files (AGENTS.md, .cursorrules, etc.)
-        and caller-supplied system_message.
+      * ``stable``   — the cross-session-stable prefix, through the coding
+        operating brief when a workspace snapshot follows.
+      * ``context``  — the workspace snapshot followed by the remaining
+        session-stable guidance, context files, and caller-supplied
+        system_message.
       * ``volatile`` — memory snapshot, user profile, external
         memory provider block, timestamp line.
 
@@ -345,25 +347,35 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
         stable_parts.append(_env_hints)
 
     # Coding posture (base Hermes, any interactive coding surface in a code
-    # workspace — see agent/coding_context.py). The operating brief + the live
-    # git/workspace snapshot are built once here and cached for the session;
-    # the snapshot is never re-probed per turn (that would break the prompt
-    # cache), so the brief tells the model to re-check git before relying on it.
+    # workspace — see agent/coding_context.py). Keep the operating brief in
+    # the cross-session-stable prefix, while placing the live git/workspace
+    # snapshot behind its own cache boundary. The post-snapshot blocks must
+    # stay in their historical position after the workspace snapshot.
+    coding_workspace_parts: List[str] = []
+    coding_trailing_parts: List[str] = []
     if agent.valid_tool_names:
         try:
-            from agent.coding_context import coding_system_blocks
+            from agent.coding_context import coding_system_prompt_parts
 
-            stable_parts.extend(
-                coding_system_blocks(
-                    platform=agent.platform,
-                    cwd=resolve_context_cwd(),
-                    model=agent.model,
-                )
+            coding_prefix_parts, coding_workspace_parts, coding_trailing_parts = coding_system_prompt_parts(
+                platform=agent.platform,
+                cwd=resolve_context_cwd(),
+                model=agent.model,
             )
+            stable_parts.extend(coding_prefix_parts)
         except Exception:
             # Coding-context probing must never block prompt build.
             pass
 
+    # Guidance assembled after the coding posture historically followed the
+    # workspace snapshot. With no snapshot, the coding tail instead remains
+    # directly after the coding prefix in the cacheable prefix.
+    if coding_workspace_parts:
+        post_workspace_parts: List[str] = []
+    else:
+        stable_parts.extend(coding_trailing_parts)
+        post_workspace_parts = stable_parts
+
     # Local Python toolchain probe — names python/pip/uv/PEP-668 state when
     # something is non-default so the model can pick the right install
     # strategy without discovering by failure.  Emits a single line; emits
@@ -376,7 +388,7 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
             from tools.env_probe import get_environment_probe_line
             _probe_line = get_environment_probe_line()
             if _probe_line:
-                stable_parts.append(_probe_line)
+                post_workspace_parts.append(_probe_line)
         except Exception:
             # Probe failure must never block prompt build.
             pass
@@ -394,7 +406,7 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
     except Exception:
         active_profile = "default"
     if active_profile == "default":
-        stable_parts.append(
+        post_workspace_parts.append(
             "Active Hermes profile: default. Other profiles (if any) live "
             "under " + str(get_hermes_home()) + "/profiles/<name>/. Each profile has its own "
             "skills/, plugins/, cron/, and memories/ that affect a different "
@@ -403,7 +415,7 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
             "you to."
         )
     else:
-        stable_parts.append(
+        post_workspace_parts.append(
             f"Active Hermes profile: {active_profile}. This session reads "
             f"and writes {get_hermes_home()}/profiles/{active_profile}/. The default "
             f"profile's data lives at {get_hermes_home()}/skills/, {get_hermes_home()}/plugins/, "
@@ -449,11 +461,16 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
     if platform_key == "tui" and _effective_hint:
         _effective_hint = _tui_embedded_pane_clarifier(_effective_hint)
     if _effective_hint:
-        stable_parts.append(_effective_hint)
+        post_workspace_parts.append(_effective_hint)
 
     # ── Context tier (cwd-dependent, may change between sessions) ─
     context_parts: List[str] = []
 
+    if coding_workspace_parts:
+        context_parts.extend(coding_workspace_parts)
+        context_parts.extend(coding_trailing_parts)
+        context_parts.extend(post_workspace_parts)
+
     # Note: ephemeral_system_prompt is NOT included here. It's injected at
     # API-call time only so it stays out of the cached/stored system prompt.
     if system_message is not None:
@@ -515,6 +532,8 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
         timestamp_line += f"\nModel: {agent.model}"
     if agent.provider:
         timestamp_line += f"\nProvider: {agent.provider}"
+    if agent.platform:
+        timestamp_line += f"\nPlatform: {agent.platform}"
     volatile_parts.append(timestamp_line)
 
     return {
@@ -541,6 +560,7 @@ def build_system_prompt(agent: Any, system_message: Optional[str] = None) -> str
     """
     parts = build_system_prompt_parts(agent, system_message=system_message)
     joined = "\n\n".join(p for p in (parts["stable"], parts["context"], parts["volatile"]) if p)
+    agent._cached_system_prompt_static = parts["stable"]
 
     # Surface context-file truncation warnings through the normal agent status
     # channel so gateway/CLI users see them in chat instead of only in logs.
@@ -557,6 +577,7 @@ def invalidate_system_prompt(agent: Any) -> None:
     so the rebuilt prompt captures any writes from this session.
     """
     agent._cached_system_prompt = None
+    agent._cached_system_prompt_static = None
     if agent._memory_store:
         agent._memory_store.load_from_disk()
 
diff --git a/agent/title_generator.py b/agent/title_generator.py
index 7469a665bfc..bb44da276ec 100644
--- a/agent/title_generator.py
+++ b/agent/title_generator.py
@@ -71,6 +71,27 @@ def _auto_title_enabled() -> bool:
         return True
 
 
+def _summarize_user_message(user_message: str) -> str:
+    """Collapse a slash-skill-expanded turn back to what the user typed.
+
+    A ``/skill`` invocation expands into a message that embeds the whole skill
+    body, so feeding it to the titler verbatim titles the session after the
+    *skill's* prose — "Kick off a task in a fresh isolated git worktree" — not
+    after the user's request. Reuse the canonical scaffolding parser so the
+    model sees ``/work — fix the title leak`` instead.
+    """
+    if not user_message:
+        return ""
+    try:
+        from agent.skill_commands import describe_skill_invocation
+
+        described = describe_skill_invocation(user_message)
+    except Exception:
+        logger.debug("Skill-scaffolding summary failed; titling raw", exc_info=True)
+        return user_message
+    return described if described is not None else user_message
+
+
 def generate_title(
     user_message: str,
     assistant_response: str,
@@ -110,7 +131,7 @@ def generate_title(
             logger.debug("Title runtime validator raised; proceeding", exc_info=True)
 
     # Truncate long messages to keep the request small
-    user_snippet = user_message[:500] if user_message else ""
+    user_snippet = _summarize_user_message(user_message)[:500]
     assistant_snippet = assistant_response[:500] if assistant_response else ""
 
     language = _title_language()
@@ -143,6 +164,11 @@ def generate_title(
         title = title.strip('"\'')
         if title.lower().startswith("title:"):
             title = title[6:].strip()
+        # A title is one line. A model that ignores "return ONLY the title" and
+        # answers the prompt instead (a shell transcript, a bulleted plan) would
+        # otherwise be stored verbatim and truncated mid-command. Keep the first
+        # non-empty line — the closest thing to a title in that response.
+        title = next((line.strip() for line in title.splitlines() if line.strip()), "")
         # Enforce reasonable length
         if len(title) > 80:
             title = title[:77] + "..."
diff --git a/agent/tool_executor.py b/agent/tool_executor.py
index 16b9f0f4dd5..1db855573f0 100644
--- a/agent/tool_executor.py
+++ b/agent/tool_executor.py
@@ -1204,7 +1204,8 @@ def execute_tool_calls_concurrent(agent, assistant_message, messages: list, effe
                 print(f"  ✅ Tool {i+1} completed in {tool_duration:.2f}s - {response_preview}")
 
         agent._current_tool = None
-        agent._touch_activity(f"tool completed: {name} ({tool_duration:.1f}s)")
+        _status_suffix = " (error)" if is_error else ""
+        agent._touch_activity(f"tool completed: {name} ({tool_duration:.1f}s){_status_suffix}")
 
         if not blocked and agent.tool_complete_callback:
             try:
@@ -1826,7 +1827,8 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
                 logging.debug(f"Tool progress callback error: {cb_err}")
 
         agent._current_tool = None
-        agent._touch_activity(f"tool completed: {function_name} ({tool_duration:.1f}s)")
+        _status_suffix = " (error)" if _is_error_result else ""
+        agent._touch_activity(f"tool completed: {function_name} ({tool_duration:.1f}s){_status_suffix}")
 
         if agent.verbose_logging:
             logging.debug(f"Tool {function_name} completed in {tool_duration:.2f}s")
diff --git a/agent/trace_upload.py b/agent/trace_upload.py
index f65547440c7..404d9be70b1 100644
--- a/agent/trace_upload.py
+++ b/agent/trace_upload.py
@@ -162,7 +162,7 @@ def build_trace_jsonl(
         if cwd:
             r = subprocess.run(
                 ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-                capture_output=True, text=True, timeout=3, cwd=cwd,
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=3, cwd=cwd,
             )
             if r.returncode == 0:
                 git_branch = r.stdout.strip()
diff --git a/agent/transports/codex.py b/agent/transports/codex.py
index 5855fcfe9c5..15dd3409e3f 100644
--- a/agent/transports/codex.py
+++ b/agent/transports/codex.py
@@ -7,6 +7,7 @@ streaming, or the _run_codex_stream() call path.
 
 import hashlib
 import json
+import re
 from typing import Any, Dict, List, Optional
 
 from agent.transports.base import ProviderTransport
@@ -27,6 +28,49 @@ def _bounded_prompt_cache_key(value: Any) -> Optional[str]:
     return f"pck_{digest}"
 
 
+_EXTENDED_PROMPT_CACHE_MODELS = (
+    "gpt-5.5-pro",
+    "gpt-5.5",
+    "gpt-5.4",
+    "gpt-5.2",
+    "gpt-5.1-codex-max",
+    "gpt-5.1-codex-mini",
+    "gpt-5.1-chat-latest",
+    "gpt-5.1-codex",
+    "gpt-5.1",
+    "gpt-5-codex",
+    "gpt-5",
+    "gpt-4.1",
+)
+_EXTENDED_PROMPT_CACHE_MODEL_RE = re.compile(
+    rf"(?:^|[./:])(?:{'|'.join(re.escape(name) for name in _EXTENDED_PROMPT_CACHE_MODELS)})"
+    r"(?:-\d{4}-\d{2}-\d{2})?$"
+)
+
+
+def _default_prompt_cache_retention_for_request(
+    model: str,
+    base_url: Any,
+) -> Optional[str]:
+    """Return ``24h`` for supported models on Amazon Bedrock Mantle."""
+    from utils import base_url_hostname
+
+    hostname_parts = base_url_hostname(str(base_url or "")).split(".")
+    is_bedrock_mantle = (
+        len(hostname_parts) == 4
+        and hostname_parts[0] == "bedrock-mantle"
+        and bool(hostname_parts[1])
+        and hostname_parts[2:] == ["api", "aws"]
+    )
+    if not is_bedrock_mantle:
+        return None
+
+    normalized = str(model or "").strip().lower().replace("_", "-")
+    if _EXTENDED_PROMPT_CACHE_MODEL_RE.search(normalized):
+        return "24h"
+    return None
+
+
 def _content_cache_key(instructions: str, tools: Optional[List[Dict[str, Any]]]) -> Optional[str]:
     """Content-address the prompt cache key from the static request prefix.
 
@@ -284,6 +328,13 @@ class ResponsesApiTransport(ProviderTransport):
         if not is_github_responses and not is_xai_responses and cache_key:
             kwargs["prompt_cache_key"] = cache_key
 
+        cache_retention = _default_prompt_cache_retention_for_request(
+            model,
+            params.get("base_url"),
+        )
+        if cache_retention:
+            kwargs.setdefault("prompt_cache_retention", cache_retention)
+
         if reasoning_enabled and is_xai_responses:
             from agent.model_metadata import grok_supports_reasoning_effort
 
diff --git a/agent/transports/codex_app_server.py b/agent/transports/codex_app_server.py
index 7f5831f2a3e..c23ff836ed8 100644
--- a/agent/transports/codex_app_server.py
+++ b/agent/transports/codex_app_server.py
@@ -394,7 +394,7 @@ def check_codex_binary(
         proc = subprocess.run(
             [codex_bin, "--version"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
             stdin=subprocess.DEVNULL,
         )
diff --git a/agent/turn_context.py b/agent/turn_context.py
index 498f68771c1..5a006894887 100644
--- a/agent/turn_context.py
+++ b/agent/turn_context.py
@@ -34,7 +34,9 @@ from typing import Any, Dict, List, Mapping, Optional
 from agent.conversation_compression import (
     IDLE_COMPACTION_STATUS_TEMPLATE,
     PREFLIGHT_COMPRESSION_STATUS_TEMPLATE,
+    compression_skipped_due_to_lock,
     conversation_history_after_compression,
+    recover_rotated_compression_session,
 )
 from agent.context_engine import automatic_compaction_status_message
 from agent.iteration_budget import IterationBudget
@@ -352,6 +354,13 @@ def build_turn_context(
     # Guard stdio against OSError from broken pipes (systemd/headless/daemon).
     install_safe_stdio()
 
+    # Recover a session rotated by another path before binding log/turn ids or
+    # copying client-supplied history. Everything in this turn must consistently
+    # belong to the canonical child, including observability metadata.
+    recovered_history = recover_rotated_compression_session(agent)
+    if recovered_history is not None:
+        conversation_history = recovered_history
+
     # NOTE: the DB session row is created later, AFTER the system prompt is
     # restored/built (see _ensure_db_session() below the system-prompt block).
     # Creating it here — before _cached_system_prompt is populated — inserts a
@@ -710,6 +719,8 @@ def build_turn_context(
     # issue #27405 (a few very large messages slipping past the count gate).
     _preflight_compressed = False
     _preflight_compression_blocked = False
+    agent._turn_received_provider_response = False
+    agent._turn_preflight_display_snapshot = None
     if agent.compression_enabled and _should_run_preflight_estimate(
         messages,
         agent.context_compressor.protect_first_n,
@@ -722,6 +733,21 @@ def build_turn_context(
             tools=agent.tools or None,
         )
         _compressor = agent.context_compressor
+        # getattr guard: minimal compressor doubles (SimpleNamespace in the
+        # engine-preflight tests) and plugin context engines lack this
+        # ContextCompressor-only method — absence means no snapshot, and the
+        # finalizer's rollback stays disarmed for the turn (display-only).
+        _snapshot_fn = getattr(
+            _compressor, "snapshot_preflight_display_tokens", None
+        )
+        if callable(_snapshot_fn):
+            _snapshot_val = _snapshot_fn()
+            # Type pin: MagicMock compressors return truthy Mock objects —
+            # only a real int snapshot may arm the interrupted-turn rollback.
+            if isinstance(_snapshot_val, int) and not isinstance(
+                _snapshot_val, bool
+            ):
+                agent._turn_preflight_display_snapshot = _snapshot_val
         _defer_preflight = getattr(
             _compressor,
             "should_defer_preflight_to_real_usage",
@@ -838,10 +864,29 @@ def build_turn_context(
             for _pass in range(_max_preflight_passes):
                 _orig_len = len(messages)
                 _orig_tokens = _preflight_tokens
+                _preflight_input = messages
                 messages, active_system_prompt = agent._compress_context(
                     messages, system_message, approx_tokens=_preflight_tokens,
                     task_id=effective_task_id,
                 )
+                if (
+                    messages is _preflight_input
+                    and compression_skipped_due_to_lock(agent)
+                ):
+                    # #69870 lock-skip: another path holds this session's
+                    # compression lock, so the pass no-oped. That is a
+                    # temporary DEFER, not proof the transcript cannot
+                    # compress — do NOT arm the insufficient-progress
+                    # blocker (the loop's error handlers must keep their
+                    # provider-proven retry budget) and stop preflight
+                    # passes for this turn; the lock winner is shrinking
+                    # the same session concurrently.
+                    logger.info(
+                        "Preflight compression deferred: compression lock "
+                        "held by another path (session %s)",
+                        agent.session_id or "none",
+                    )
+                    break
                 # Re-estimate now so size-only compression (same row count,
                 # lower token count — e.g. summarising tool outputs) is
                 # recognised as progress instead of being misread as
diff --git a/agent/turn_finalizer.py b/agent/turn_finalizer.py
index 7bf4ee4bbe5..0f636c1dd24 100644
--- a/agent/turn_finalizer.py
+++ b/agent/turn_finalizer.py
@@ -201,6 +201,36 @@ def finalize_turn(
         )
     )
 
+    # Preflight can seed the display count before the provider receives the
+    # request. Roll that estimate back only when an interrupt wins the race
+    # before any successful provider response. Compaction state remains owned
+    # by the real-usage/post-compaction path, including its ``-1`` sentinel.
+    # Guard rules (test-double density on this path is high):
+    #  - snapshot is type-pinned to a real int — MagicMock agents auto-create
+    #    truthy Mock attributes that must never arm the rollback;
+    #  - the received-response flag is pinned to ``is not True`` — its real
+    #    domain is True/False, and only a literal True means a provider
+    #    response completed;
+    #  - the compressor method gets a getattr+callable guard — SimpleNamespace
+    #    compressor doubles and plugin context engines lack it.
+    _preflight_snapshot = getattr(
+        agent, "_turn_preflight_display_snapshot", None
+    )
+    if (
+        interrupted is True
+        and isinstance(_preflight_snapshot, int)
+        and not isinstance(_preflight_snapshot, bool)
+        and getattr(agent, "_turn_received_provider_response", False) is not True
+        and getattr(agent, "context_compressor", None) is not None
+    ):
+        _rollback_fn = getattr(
+            agent.context_compressor,
+            "rollback_interrupted_preflight_display_tokens",
+            None,
+        )
+        if callable(_rollback_fn):
+            _rollback_fn(_preflight_snapshot)
+
     # Post-loop cleanup must never lose the response.  Trajectory save,
     # resource teardown, and session persistence all touch fallible
     # surfaces — file I/O / JSON serialization (_save_trajectory), remote
@@ -495,6 +525,34 @@ def finalize_turn(
         except Exception as exc:
             logger.warning("post_llm_call hook failed: %s", exc)
 
+    # Context engine observation hook: notify the active engine that this
+    # turn has finished, with the finalized transcript. Complements the
+    # per-request select_context() hook (selection before the request;
+    # observation after the turn). No-op default, fail-open.
+    try:
+        from agent.conversation_loop import _notify_context_engine_turn_complete
+        # Forward the turn's canonical usage when the host has it. The loop
+        # stashes the most recent API response's usage dict (the same
+        # canonical buckets fed to ``update_from_response``) on the agent as
+        # ``_last_turn_usage``. It is ``None`` on turns that never reached a
+        # provider response (early failure / interrupt), which is exactly the
+        # contract: real usage when available, ``None`` otherwise.
+        _turn_usage = getattr(agent, "_last_turn_usage", None)
+        _notify_context_engine_turn_complete(
+            agent,
+            messages,
+            usage=_turn_usage,
+            logger=logger,
+            turn_id=turn_id,
+            task_id=effective_task_id,
+            api_call_count=api_call_count,
+            interrupted=interrupted,
+            failed=failed,
+            turn_exit_reason=_turn_exit_reason,
+        )
+    except Exception as exc:
+        logger.warning("on_turn_complete notification failed: %s", exc)
+
     # Extract reasoning from the CURRENT turn only.  Walk backwards
     # but stop at the user message that started this turn — anything
     # earlier is from a prior turn and must not leak into the reasoning
@@ -627,4 +685,7 @@ def finalize_turn(
     except Exception as exc:
         logger.warning("on_session_end hook failed: %s", exc)
 
+    agent._turn_preflight_display_snapshot = None
+    agent._turn_received_provider_response = False
+
     return result
diff --git a/agent/verification_evidence.py b/agent/verification_evidence.py
index c3154378f5e..2c8d1f85efa 100644
--- a/agent/verification_evidence.py
+++ b/agent/verification_evidence.py
@@ -13,10 +13,11 @@ import shlex
 import sqlite3
 import tempfile
 import threading
+from contextlib import contextmanager
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Iterator, Optional
 
 from hermes_constants import get_hermes_home
 
@@ -65,13 +66,38 @@ def _connect() -> sqlite3.Connection:
     path = _db_path()
     path.parent.mkdir(parents=True, exist_ok=True)
     conn = sqlite3.connect(path)
-    apply_wal_with_fallback(conn, db_label="verification_evidence.db")
-    conn.execute("PRAGMA busy_timeout=5000")
     conn.row_factory = sqlite3.Row
-    _ensure_schema(conn)
+    try:
+        apply_wal_with_fallback(conn, db_label="verification_evidence.db")
+        conn.execute("PRAGMA busy_timeout=5000")
+        _ensure_schema(conn)
+    except Exception:
+        # A PRAGMA/DDL failure after a successful connect() must not leak the
+        # just-opened connection back to the caller.
+        conn.close()
+        raise
     return conn
 
 
+@contextmanager
+def _transaction() -> Iterator[sqlite3.Connection]:
+    """Open a connection, commit/rollback on exit, and ALWAYS close it.
+
+    ``sqlite3.Connection.__enter__``/``__exit__`` only commit or roll back the
+    transaction; they do not close the connection. Using ``with _connect()``
+    alone therefore leaks a connection — and its WAL/SHM file descriptors — on
+    every call, deferring the close to the garbage collector, which over a
+    long-running process can exhaust ``RLIMIT_NOFILE`` (the cron-ledger sibling
+    of this bug was #69567 / PR #69594).
+    """
+    conn = _connect()
+    try:
+        with conn:
+            yield conn
+    finally:
+        conn.close()
+
+
 def _ensure_schema(conn: sqlite3.Connection) -> None:
     conn.execute(
         """
@@ -454,7 +480,7 @@ def record_terminal_result(
 
     created_at = _utc_now()
     with _DB_LOCK:
-        with _connect() as conn:
+        with _transaction() as conn:
             cur = conn.execute(
                 """
                 INSERT INTO verification_events(
@@ -520,7 +546,7 @@ def mark_workspace_edited(
     edited_at = _utc_now()
 
     with _DB_LOCK:
-        with _connect() as conn:
+        with _transaction() as conn:
             row = conn.execute(
                 """
                 SELECT changed_paths_json FROM verification_state
@@ -570,7 +596,7 @@ def verification_status(
     sid = str(session_id or "default")
     root = str(facts.get("root") or Path(cwd or ".").resolve())
     with _DB_LOCK:
-        with _connect() as conn:
+        with _transaction() as conn:
             state = conn.execute(
                 """
                 SELECT last_event_id, last_edit_at, changed_paths_json
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index a1da176726d..706611acb1a 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -30,7 +30,7 @@ Already have the Hermes CLI? Just run:
 hermes desktop
 ```
 
-It builds and launches the GUI against your existing install — same config, keys, sessions, and skills. On first launch Hermes walks you through picking a provider and model; nothing else to configure.
+It builds and launches the GUI against your existing install — same config, keys, sessions, and skills. If Desktop cannot find a usable runtime or saved remote connection, first launch lets you connect to an existing Hermes gateway or install Hermes locally. Local onboarding then walks you through choosing a provider and model.
 
 ### Prebuilt installers
 
@@ -134,6 +134,19 @@ Desktop supports a managed local backend, explicit remote gateways, and Hermes
 Cloud connections. Remote and cloud modes use the same remote-capability path;
 authentication and discovery differ, not the renderer feature model.
 
+When no usable local runtime or saved remote connection exists, the first-run
+screen offers **Connect to existing Hermes** before starting the local installer.
+Desktop probes the gateway to discover token or OAuth authentication, requires a
+successful HTTP and WebSocket connection test, and saves the connection using
+the same encrypted Desktop configuration used by Settings. A saved remote
+connection bypasses this choice on later launches. The regular Desktop build
+still includes the local-install option; this is a remote operating mode, not a
+separate client-only application.
+
+In remote mode the gateway host is the execution boundary: agent tools,
+terminal commands, and file operations run against the remote Hermes host, not
+the computer displaying the Desktop UI.
+
 Projects are the workspace abstraction. A project may own multiple folders,
 repositories, worktrees, and sessions; a bare new chat remains detached unless
 the user enters a project or configures a default project directory. Use the
diff --git a/apps/desktop/e2e/correction-session-switch.spec.ts b/apps/desktop/e2e/correction-session-switch.spec.ts
index dd32caa61e7..dc435b1d538 100644
--- a/apps/desktop/e2e/correction-session-switch.spec.ts
+++ b/apps/desktop/e2e/correction-session-switch.spec.ts
@@ -21,8 +21,16 @@ const INFERENCE_SWITCH_TRIGGER = 'E2E_INFERENCE_SWITCH_TRIGGER'
 const INFERENCE_PROMPT = `${INFERENCE_SWITCH_TRIGGER}: original inference prompt must remain singular.`
 const INFERENCE_CORRECTION = `${INFERENCE_SWITCH_TRIGGER}: correction sent while inference is live.`
 
+// Inactive tabs stay mounted under a data-pane-hidden ancestor. Match the
+// renderer's keep-alive visibility policy instead of relying on DOM order.
+const SURFACE = '[data-composer-target]:not([data-pane-hidden] [data-composer-target])'
+
+function activeSurface(page: Page) {
+  return page.locator(SURFACE).last()
+}
+
 async function send(page: Page, text: string): Promise<void> {
-  const composer = page.locator('[contenteditable="true"]').first()
+  const composer = activeSurface(page).locator('[contenteditable="true"]').first()
   await composer.waitFor({ state: 'visible', timeout: 15_000 })
   await composer.click()
   await composer.type(text, { delay: 5 })
@@ -30,8 +38,9 @@ async function send(page: Page, text: string): Promise<void> {
 }
 
 async function steer(page: Page, text: string): Promise<void> {
-  const composer = page.locator('[contenteditable="true"]').first()
-  const primary = page.locator('[data-slot="composer-root"] button[type="submit"]')
+  const surface = activeSurface(page)
+  const composer = surface.locator('[contenteditable="true"]').first()
+  const primary = surface.locator('[data-slot="composer-root"] button[type="submit"]')
 
   await composer.waitFor({ state: 'visible', timeout: 15_000 })
   await composer.click()
@@ -42,55 +51,80 @@ async function steer(page: Page, text: string): Promise<void> {
 
 async function waitForTranscriptText(page: Page, text: string): Promise<void> {
   await page.waitForFunction(
-    (expected: string) => (document.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? '').includes(expected),
-    text,
+    ([expected, surfaceSelector]: [string, string]) => {
+      const surfaces = document.querySelectorAll(surfaceSelector)
+      const active = surfaces[surfaces.length - 1]
+
+      return (active?.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? '').includes(expected)
+    },
+    [text, SURFACE] as [string, string],
     { timeout: 30_000 },
   )
 }
 
 async function textNodeOccurrences(page: Page, text: string): Promise<number> {
-  return page.evaluate((expected: string) => {
-    const viewport = document.querySelector('[data-slot="aui_thread-viewport"]')
-    if (!viewport) return 0
+  return page.evaluate(
+    ([expected, surfaceSelector]: [string, string]) => {
+      const surfaces = document.querySelectorAll(surfaceSelector)
+      const viewport = surfaces[surfaces.length - 1]?.querySelector('[data-slot="aui_thread-viewport"]')
+      if (!viewport) return 0
 
-    const walker = document.createTreeWalker(viewport, NodeFilter.SHOW_TEXT)
-    let count = 0
-    while (walker.nextNode()) {
-      if (walker.currentNode.textContent?.includes(expected)) {
-        count += 1
+      const walker = document.createTreeWalker(viewport, NodeFilter.SHOW_TEXT)
+      let count = 0
+      while (walker.nextNode()) {
+        if (walker.currentNode.textContent?.includes(expected)) {
+          count += 1
+        }
       }
-    }
-    return count
-  }, text)
+      return count
+    },
+    [text, SURFACE] as [string, string],
+  )
 }
 
 async function transcriptTextOrder(page: Page): Promise<string[]> {
-  return page.evaluate(() => {
-    const viewport = document.querySelector('[data-slot="aui_thread-viewport"]')
+  return page.evaluate((surfaceSelector: string) => {
+    const surfaces = document.querySelectorAll(surfaceSelector)
+    const viewport = surfaces[surfaces.length - 1]?.querySelector('[data-slot="aui_thread-viewport"]')
     if (!viewport) return []
 
     return Array.from(viewport.querySelectorAll<HTMLElement>('[data-role="message"], [data-message-id]'))
       .map(message => message.textContent?.trim() ?? '')
       .filter(Boolean)
-  })
+  }, SURFACE)
 }
 
 async function transcriptMessageOrder(page: Page): Promise<string[]> {
-  return page.evaluate(() => {
-    const viewport = document.querySelector('[data-slot="aui_thread-viewport"]')
+  return page.evaluate((surfaceSelector: string) => {
+    const surfaces = document.querySelectorAll(surfaceSelector)
+    const viewport = surfaces[surfaces.length - 1]?.querySelector('[data-slot="aui_thread-viewport"]')
     if (!viewport) return []
 
-    return Array.from(viewport.querySelectorAll<HTMLElement>('[data-role="user"], [data-role="assistant"]'))
+    return Array.from(
+      viewport.querySelectorAll<HTMLElement>('[data-role="user"], [data-role="assistant"], [data-role="system"]'),
+    )
       .map(message => message.textContent?.trim() ?? '')
       .filter(Boolean)
-  })
+  }, SURFACE)
 }
 
+/**
+ * The sidebar "+" opens a NEW TAB beside the current chat rather than
+ * replacing it, so the prior session stays mounted in its own surface. Wait
+ * for the newly-mounted surface to show an empty transcript instead of waiting
+ * for the old text to disappear from the page (it never will).
+ */
 async function openFreshDraft(page: Page, priorSessionText: string): Promise<void> {
   await page.locator('[data-slot="sidebar"] button[aria-label="New session"]').first().click()
   await page.waitForFunction(
-    (priorText: string) => !(document.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? '').includes(priorText),
-    priorSessionText,
+    ([priorText, surfaceSelector]: [string, string]) => {
+      const surfaces = document.querySelectorAll(surfaceSelector)
+      const active = surfaces[surfaces.length - 1]
+      const transcript = active?.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? ''
+
+      return surfaces.length > 0 && !transcript.includes(priorText)
+    },
+    [priorSessionText, SURFACE] as [string, string],
     { timeout: 15_000 },
   )
 }
@@ -116,7 +150,12 @@ async function reopenInferenceSession(page: Page): Promise<void> {
 }
 
 function relevantOrder(messages: string[]): string[] {
-  return messages.filter(message => message.includes(ORIGINAL_PROMPT) || message.includes(CORRECTION))
+  return messages.flatMap(message => {
+    if (message.includes(ORIGINAL_PROMPT)) return [ORIGINAL_PROMPT]
+    if (message.includes(CORRECTION)) return [CORRECTION]
+
+    return []
+  })
 }
 
 function steerTurnOrder(messages: string[]): string[] {
diff --git a/apps/desktop/e2e/image-attachment-resume.spec.ts b/apps/desktop/e2e/image-attachment-resume.spec.ts
new file mode 100644
index 00000000000..a4f8da68e39
--- /dev/null
+++ b/apps/desktop/e2e/image-attachment-resume.spec.ts
@@ -0,0 +1,197 @@
+/**
+ * Regression coverage for an attached image in a durable session. The gateway
+ * persists the turn, the builder exits, and desktop renders it from SessionDB
+ * for the first time — the "quit and relaunch" case, where the transcript used
+ * to come back as vision-enrichment prose instead of a thumbnail.
+ *
+ * The fixture pins `image_input_mode: native` because that is the majority
+ * routing path (any vision-capable model) and the one where a text-only
+ * persist override is silently dropped. The image also sits behind directory
+ * and file names containing spaces, mirroring the macOS composer's
+ * `~/Library/Application Support/...` staging path.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import {
+  buildAppEnv,
+  createSandbox,
+  launchDesktop,
+  type Sandbox,
+  waitForAppReady,
+  writeEnvFile,
+  writeMockProviderConfig,
+} from './fixtures'
+import { type MockServer, startMockServer } from './mock-server'
+import { RealSessionBuilder } from './real-session-builder'
+import { type ElectronApplication, expect, type Page, test } from './test'
+
+// A seeded session has no generated title, so every label falls back to the
+// session preview — the first 60 characters of the first user message.
+const SESSION_TITLE = 'E2E attached image session'
+const CAPTION = 'E2E attached image must survive a relaunch'
+const IMAGE_DIR = 'Application Support/e2e shots'
+const IMAGE_NAME = 'e2e capture.png'
+const NATIVE_IMAGE_CONFIG = 'agent:\n  image_input_mode: native'
+
+/** A 160x100 framed magenta block — small, but visible in the screenshots. */
+const PNG_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAKAAAABkCAIAAACO1KzYAAAA30lEQVR42u3dwQ2AIBAAQTAWAx1iBXYI7diCuWhEMvP2dZsj+CL30hLr2oxAYARGYARGYARGYIERGIH53n7nozpOk5rQqIcNdkQjMAIjMNPeomP3N54V+5exwY5oBEZgBEZgBEZggREYgREYgREYgQVGYARGYARGYARGYIERGIERGIERGIEFRmAERmAERmAEFhiBERiBERiBERiBBUZgBEZgBEZgBBYYgREYgREYgRFYYCMQGIERmPSj94Njb9ligxEYgRFYYJaQe2mmYIMRGIERGIERGIEFRmAERmDedAFtjAtAGWDnoAAAAABJRU5ErkJggg=='
+
+interface SeededFixture {
+  app: ElectronApplication
+  mock: MockServer
+  page: Page
+  sandbox: Sandbox
+  cleanup: () => Promise<void>
+}
+
+function writeImage(sandbox: Sandbox): string {
+  const dir = path.join(sandbox.root, IMAGE_DIR)
+  fs.mkdirSync(dir, { recursive: true })
+
+  const imagePath = path.join(dir, IMAGE_NAME)
+  fs.writeFileSync(imagePath, Buffer.from(PNG_BASE64, 'base64'))
+
+  return imagePath
+}
+
+async function setupSeededDesktop(): Promise<SeededFixture> {
+  const mock = await startMockServer()
+  const sandbox = createSandbox('image-attachment')
+  writeMockProviderConfig(sandbox.hermesHome, mock.url, undefined, NATIVE_IMAGE_CONFIG)
+  writeEnvFile(sandbox.hermesHome)
+
+  const builder = await RealSessionBuilder.start(sandbox.hermesHome)
+
+  try {
+    await builder.createSession({
+      title: SESSION_TITLE,
+      turns: [{ images: [writeImage(sandbox)], text: CAPTION }],
+    })
+  } finally {
+    await builder.close()
+  }
+
+  const { app, page } = await launchDesktop(buildAppEnv(sandbox))
+
+  return {
+    app,
+    mock,
+    page,
+    sandbox,
+    cleanup: async () => {
+      await app.close().catch(() => undefined)
+      await mock.close()
+      sandbox.cleanup()
+    },
+  }
+}
+
+function sessionRow(page: Page) {
+  return page.locator('[data-slot="sidebar"] button').filter({ hasText: CAPTION }).first()
+}
+
+// Inactive tabs stay mounted under a data-pane-hidden ancestor. Match the
+// renderer's keep-alive visibility policy instead of relying on DOM order.
+const SURFACE = '[data-composer-target]:not([data-pane-hidden] [data-composer-target])'
+
+function activeViewportText(surfaceSelector: string): string {
+  const surfaces = document.querySelectorAll(surfaceSelector)
+
+  return surfaces[surfaces.length - 1]?.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? ''
+}
+
+async function openSeededSession(page: Page): Promise<void> {
+  const row = sessionRow(page)
+  await row.waitFor({ state: 'visible', timeout: 60_000 })
+  await row.click()
+  await page.waitForFunction(
+    ([expected, surfaceSelector]: [string, string]) => {
+      const surfaces = document.querySelectorAll(surfaceSelector)
+      const text = surfaces[surfaces.length - 1]?.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? ''
+
+      return text.includes(expected)
+    },
+    [CAPTION, SURFACE] as [string, string],
+    { timeout: 30_000 },
+  )
+}
+
+/**
+ * The sidebar "+" opens a NEW TAB beside the current chat instead of replacing
+ * it, so the seeded session stays mounted in its own surface. Assert the new
+ * surface is empty rather than waiting for the old caption to leave the page.
+ */
+async function openNewSession(page: Page): Promise<void> {
+  await page.locator('[data-slot="sidebar"] button[aria-label="New session"]').first().click()
+  await page.waitForFunction(
+    ([expected, surfaceSelector]: [string, string]) => {
+      const surfaces = document.querySelectorAll(surfaceSelector)
+      const text = surfaces[surfaces.length - 1]?.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? ''
+
+      return surfaces.length > 0 && !text.includes(expected)
+    },
+    [CAPTION, SURFACE] as [string, string],
+    { timeout: 15_000 },
+  )
+}
+
+async function transcriptText(page: Page): Promise<string> {
+  return page.evaluate(activeViewportText, SURFACE)
+}
+
+async function assertRendersThumbnail(page: Page, label: string): Promise<void> {
+  const thumbnail = page.locator('[data-slot="aui_directive-image"] img')
+  await expect(thumbnail, `${label}: the attachment should render as an image`).toHaveCount(1)
+  await expect(thumbnail, `${label}: the thumbnail should resolve off disk`).toHaveAttribute('src', /^data:image\//)
+
+  const text = await transcriptText(page)
+  expect(text, `${label}: the caption should survive alongside the image`).toContain(CAPTION)
+  // A broken ref falls back to a chip whose label leaks the path, and a
+  // flattened multimodal turn leaves the agent's placeholder behind.
+  expect(text, `${label}: the raw image path should not leak into the transcript`).not.toContain(IMAGE_NAME)
+  expect(text, `${label}: the image directive should not render literally`).not.toContain('@image:')
+  expect(text, `${label}: the flattening placeholder should not render`).not.toContain('[screenshot]')
+}
+
+test.describe('attached image resume', () => {
+  let fixture: SeededFixture | null = null
+
+  test.afterEach(async () => {
+    await fixture?.cleanup()
+    fixture = null
+  })
+
+  test('renders a persisted attachment as a thumbnail on first open and after a cold reload', async ({}, testInfo) => {
+    // Seeding through the real gateway plus two full app boots does not fit the
+    // default per-test budget on a cold runner.
+    test.slow()
+
+    fixture = await setupSeededDesktop()
+    await waitForAppReady(fixture, 120_000)
+
+    // The sidebar labels a session by its preview, so the caption has to lead
+    // the persisted turn — a leading directive reads as a truncated file path.
+    const row = sessionRow(fixture.page)
+    await row.waitFor({ state: 'visible', timeout: 60_000 })
+
+    const label = (await row.textContent())?.trim() ?? ''
+    expect(label.startsWith(CAPTION), `sidebar label should open with the caption: ${label}`).toBe(true)
+
+    await openSeededSession(fixture.page)
+    await assertRendersThumbnail(fixture.page, 'first open')
+    await fixture.page.screenshot({ path: testInfo.outputPath('attachment-first-open.png') })
+
+    // A reload drops every cached attachment ref, so the transcript has to come
+    // back from the persisted turn alone.
+    await fixture.page.reload()
+    await waitForAppReady(fixture, 120_000)
+    await openNewSession(fixture.page)
+
+    await openSeededSession(fixture.page)
+    await assertRendersThumbnail(fixture.page, 'cold reload')
+    await fixture.page.screenshot({ path: testInfo.outputPath('attachment-cold-reload.png') })
+  })
+})
diff --git a/apps/desktop/e2e/mock-server.ts b/apps/desktop/e2e/mock-server.ts
index a198ff8989c..ce4665d1775 100644
--- a/apps/desktop/e2e/mock-server.ts
+++ b/apps/desktop/e2e/mock-server.ts
@@ -14,8 +14,11 @@
  * prove the full boot → gateway → inference → renderer chain works.
  */
 
+import fs from 'node:fs'
 import http from 'node:http'
 import type { ServerResponse } from 'node:http'
+import os from 'node:os'
+import nodePath from 'node:path'
 
 /** A canned assistant reply used for every chat completion request. */
 export const MOCK_REPLY = 'Hello from the mock inference server! The full boot chain is working.'
@@ -27,6 +30,14 @@ export interface MockServerOptions {
 holdFirstCompletionContaining?: string
 /** Absolute sandbox path written by the verify-on-stop scripted tool call. */
 verificationWritePath?: string
+/**
+ * Sentinel path that ends the E2E_SIDEBAR_CROSS background process.
+ *
+ * Without it that process is a bare `sleep 5`, which races the agent turn and
+ * the 4s auto-dismiss linger — see `createBackgroundReleaseHandle`. Pass a
+ * handle's `path` to let the test decide when the process exits.
+ */
+backgroundReleasePath?: string
 }
 
 export interface MockServer {
@@ -167,37 +178,68 @@ const SIDEBAR_SCRIPT: ScriptedTurn[] = [
 
 // ─── Sidebar cross-session script ──────────────────────────────────────
 //
-// E2E_SIDEBAR_CROSS trigger uses a longer background process (sleep 5) so
-// the "background running" dot is visible long enough for the test to:
+// E2E_SIDEBAR_CROSS starts a long background process plus a subagent so the
+// tests can:
 //   1. See the background dot while the subagent runs.
 //   2. Open a different session and see session A's dot transition to
 //      "finished unread" when the background process completes.
+//
+// The background process must outlive the agent turn — the whole point is a
+// dot that is still "running" after the final answer lands. A fixed `sleep`
+// cannot guarantee that: on a loaded CI runner the turn (two model round
+// trips + a real subagent delegation) can take longer than the sleep, the
+// process exits early, the 4s success linger elapses, and the dot is gone
+// before the test looks. That is a wall-clock race between three independent
+// timers, and it made this the flakiest spec in the suite.
+//
+// When `backgroundReleasePath` is set the process instead blocks until the
+// test creates that sentinel file, so the test — not the clock — decides when
+// the dot clears. `sleep 5` remains the fallback for callers that don't pass
+// a handle.
+function sidebarCrossBgCommand(releasePath?: string): string {
+  if (!releasePath) {
+    return 'echo "long bg output" && sleep 5 && echo "finished"'
+  }
+  // Bounded wait (60s): if a test forgets to release (or crashes mid-way),
+  // the process still exits instead of hanging the worker until the suite
+  // times out.
+  const quoted = JSON.stringify(releasePath)
+  return [
+    'echo "long bg output"',
+    `for _ in $(seq 1 600); do [ -e ${quoted} ] && break; sleep 0.1; done`,
+    'echo "finished"',
+  ].join(' && ')
+}
 
-const SIDEBAR_CROSS_SCRIPT: ScriptedTurn[] = [
-  {
-    text: 'Starting a long background task and delegating work.',
-    toolCalls: [
-      {
-        name: 'terminal',
-        args: {
-          command: 'echo "long bg output" && sleep 5 && echo "finished"',
-          background: true,
-          notify_on_complete: true,
+function sidebarCrossScript(releasePath?: string): ScriptedTurn[] {
+  return [
+    {
+      text: 'Starting a long background task and delegating work.',
+      toolCalls: [
+        {
+          name: 'terminal',
+          args: {
+            command: sidebarCrossBgCommand(releasePath),
+            background: true,
+            notify_on_complete: true,
+          },
         },
-      },
-      {
-        name: 'delegate_task',
-        args: {
-          goal: 'Analyze cross-session state',
-          context: 'Testing that the background dot updates across sessions.',
+        {
+          name: 'delegate_task',
+          args: {
+            goal: 'Analyze cross-session state',
+            context: 'Testing that the background dot updates across sessions.',
+          },
         },
-      },
-    ],
-  },
-  {
-    text: 'Both tasks are running in the background now.',
-  },
-]
+      ],
+    },
+    {
+      text: 'Both tasks are running in the background now.',
+    },
+  ]
+}
+
+const SIDEBAR_CROSS_SCRIPT: ScriptedTurn[] = sidebarCrossScript()
 
 const QUEUE_STOP_SCRIPT: ScriptedTurn[] = [
   {
@@ -423,7 +465,8 @@ export function startMockServer(options: MockServerOptions = {}): Promise<MockSe
           }
 
           if (isSidebarCrossTrigger) {
-            const turn = SIDEBAR_CROSS_SCRIPT[_sidebarCrossIndex] ?? SIDEBAR_CROSS_SCRIPT[SIDEBAR_CROSS_SCRIPT.length - 1]
+            const script = sidebarCrossScript(options.backgroundReleasePath)
+            const turn = script[_sidebarCrossIndex] ?? script[script.length - 1]
             _sidebarCrossIndex++
 
             if (stream) {
@@ -722,6 +765,65 @@ export function restartMockServer(): void {
   resetScriptIndex()
 }
 
+/** Test-controlled lifetime for the E2E_SIDEBAR_CROSS background process. */
+export interface BackgroundReleaseHandle {
+  /** Sentinel path — pass as `backgroundReleasePath` to `startMockServer`. */
+  path: string
+  /** End the background process now (creates the sentinel). */
+  release: () => void
+  /** Remove the sentinel if it still exists. Safe to call twice. */
+  cleanup: () => void
+}
+
+/**
+ * Create a sentinel that keeps the E2E_SIDEBAR_CROSS background process alive
+ * until the test explicitly releases it.
+ *
+ * The cross-session sidebar tests need a background process that is still
+ * RUNNING after the agent turn finishes — that is the state under test (a
+ * session whose turn is done but whose background work is not). With a fixed
+ * `sleep`, three independent clocks race: the sleep, the agent turn (two model
+ * round trips plus a real subagent delegation), and the 4s success linger
+ * before a finished task auto-dismisses. When a loaded CI runner makes the
+ * turn slower than the sleep, the process is already gone and the assertion
+ * samples an empty sidebar. Observed on CI 2026-07-26 across two unrelated
+ * PRs: the "should appear" poll needed 7.5s to see the dot, by which point
+ * `sleep 5` had exited.
+ *
+ * With a sentinel there is one clock and the test owns it:
+ *
+ * ```ts
+ * const release = createBackgroundReleaseHandle()
+ * const mock = await startMockServer({ backgroundReleasePath: release.path })
+ * // ... assert the dot is visible; it cannot vanish on its own ...
+ * release.release()   // now, and only now, the process exits
+ * ```
+ */
+export function createBackgroundReleaseHandle(): BackgroundReleaseHandle {
+  const path = nodePath.join(
+    os.tmpdir(),
+    `hermes-e2e-bg-release-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  )
+  return {
+    path,
+    release: () => {
+      try {
+        fs.writeFileSync(path, 'release')
+      } catch {
+        // The process also has a bounded fallback wait; a failed write must
+        // not crash the test before its real assertions run.
+      }
+    },
+    cleanup: () => {
+      try {
+        fs.rmSync(path, { force: true })
+      } catch {
+        // Best-effort — the sentinel lives in the OS temp dir.
+      }
+    },
+  }
+}
+
 /**
  * The interim script's text constants, exported for test assertions.
  * Each entry is the visible text of one turn. Turns with empty text
@@ -756,8 +858,12 @@ export const SIDEBAR_CROSS_TEXTS = {
   interimText: SIDEBAR_CROSS_SCRIPT[0].text,
   /** The final answer text. */
   finalText: SIDEBAR_CROSS_SCRIPT[SIDEBAR_CROSS_SCRIPT.length - 1].text,
-  /** The longer background process command (sleep 5). */
-  bgCommand: 'echo "long bg output" && sleep 5 && echo "finished"',
+  /**
+   * The default (unheld) background process command. Tests that pass a
+   * `backgroundReleasePath` get a sentinel-waiting command instead — see
+   * `createBackgroundReleaseHandle`.
+   */
+  bgCommand: sidebarCrossBgCommand(),
   /** The subagent's goal. */
   subagentGoal: 'Analyze cross-session state',
 } as const
diff --git a/apps/desktop/e2e/real-session-builder.ts b/apps/desktop/e2e/real-session-builder.ts
index 488291695b5..0f670e9698b 100644
--- a/apps/desktop/e2e/real-session-builder.ts
+++ b/apps/desktop/e2e/real-session-builder.ts
@@ -28,11 +28,18 @@ interface CreatedSession {
   stored_session_id: string
 }
 
+export interface RealSessionTurn {
+  /** Local image paths attached before the prompt, as the composer would. */
+  images?: readonly string[]
+  text: string
+}
+
 export interface RealSessionSpec {
-  /** Human-visible sidebar title, persisted by the first completed turn. */
+  /** Session label. The durable row stores no title, so clients fall back to
+   * the preview (the first 60 characters of the first user message). */
   title: string
   /** Each item becomes one real user prompt followed by the mock provider's reply. */
-  turns: readonly string[]
+  turns: readonly (RealSessionTurn | string)[]
 }
 
 export interface RealSession {
@@ -107,7 +114,13 @@ export class RealSessionBuilder {
     const runtimeId = requireString(created, 'session_id')
     const sessionId = requireString(created, 'stored_session_id')
 
-    for (const text of spec.turns) {
+    for (const turn of spec.turns) {
+      const { images = [], text } = typeof turn === 'string' ? { text: turn } : turn
+
+      for (const image of images) {
+        await this.request('image.attach', { session_id: runtimeId, path: image })
+      }
+
       const completion = this.waitForEvent(
         frame => frame.params?.type === 'message.complete' && frame.params.session_id === runtimeId,
       )
diff --git a/apps/desktop/e2e/session-compression-and-queue-stop.spec.ts b/apps/desktop/e2e/session-compression-and-queue-stop.spec.ts
index f15b8d0befc..911f15c7840 100644
--- a/apps/desktop/e2e/session-compression-and-queue-stop.spec.ts
+++ b/apps/desktop/e2e/session-compression-and-queue-stop.spec.ts
@@ -122,11 +122,16 @@ auxiliary:
     // A normal message crosses the tiny configured context budget. The mock
     // blocks only the resulting summary request, so these assertions run
     // during automatic compaction rather than a slash-command path.
+    // The payload must cross threshold_tokens (22k) on its OWN weight
+    // (~12k tokens) on top of the system prompt. Do not shrink it: at
+    // repeat(500) the trigger only worked because the ambient system prompt
+    // (skills index + tool schemas) happened to carry it over the line, and
+    // a 160-token skills-index cleanup on main broke the test for a day.
     await pasteAndSend(page, 'E2E_COMPACTION_HISTORY_ONE '.repeat(5))
     await waitForTranscript(page, MOCK_REPLY)
     await pasteAndSend(page, 'E2E_COMPACTION_HISTORY_TWO '.repeat(5))
     await waitForTranscript(page, MOCK_REPLY)
-    await pasteAndSend(page, 'E2E_TRIGGER_AUTOMATIC_COMPACTION '.repeat(500))
+    await pasteAndSend(page, 'E2E_TRIGGER_AUTOMATIC_COMPACTION '.repeat(1500))
     await fixture.mock.waitForHeldCompletion()
     await expect(page.getByRole('status', { name: 'Summarizing thread' }).last()).toBeVisible()
 
diff --git a/apps/desktop/e2e/sidebar-states.spec.ts b/apps/desktop/e2e/sidebar-states.spec.ts
index 051efda3543..6d8c0c2c9c9 100644
--- a/apps/desktop/e2e/sidebar-states.spec.ts
+++ b/apps/desktop/e2e/sidebar-states.spec.ts
@@ -16,7 +16,12 @@ import {
   setupMockBackend,
   waitForAppReady,
 } from './fixtures'
-import { SIDEBAR_CROSS_TEXTS, SIDEBAR_TEXTS, restartMockServer } from './mock-server'
+import {
+  createBackgroundReleaseHandle,
+  restartMockServer,
+  SIDEBAR_CROSS_TEXTS,
+  SIDEBAR_TEXTS,
+} from './mock-server'
 
 /** Background-running dot aria-label (from i18n en.ts). */
 const BG_DOT_LABEL = 'Background task running'
@@ -176,21 +181,30 @@ test.describe('sidebar states — cross-session dot transition', () => {
   test.describe.configure({ mode: 'serial' })
 
   let fixture: MockBackendFixture
+  // Keeps the background process alive until this test releases it, so the
+  // "still running after the turn finished" state can't expire on its own.
+  const bgRelease = createBackgroundReleaseHandle()
 
   test.beforeAll(async () => {
     restartMockServer()
-    fixture = await setupMockBackend()
+    fixture = await setupMockBackend({
+      mockServer: { backgroundReleasePath: bgRelease.path },
+    })
     await waitForAppReady(fixture, 120_000)
   })
 
   test.afterAll(async () => {
+    // Release first so the process exits even if the test failed early,
+    // then drop the sentinel file.
+    bgRelease.release()
     await fixture?.cleanup()
+    bgRelease.cleanup()
   })
 
   test('background dot transitions to finished when viewing another session', async () => {
     const page = fixture.page
 
-    // Start a turn with a long background process (sleep 5).
+    // Start a turn whose background process runs until we release it.
     const composer = page.locator('[contenteditable="true"]').first()
     await composer.waitFor({ state: 'visible', timeout: 10_000 })
     await composer.click()
@@ -212,8 +226,9 @@ test.describe('sidebar states — cross-session dot transition', () => {
       { timeout: 90_000 },
     )
 
-    // The background dot should still be visible (sleep 5 hasn't finished yet,
-    // or auto-dismiss hasn't fired).
+    // The background dot must still be visible: the turn is done but the
+    // process is held open by the sentinel, so this is a stable state rather
+    // than a window we have to catch in time.
     const bgDuringTurn = await page.locator(`[aria-label="${BG_DOT_LABEL}"]`).count()
     expect(bgDuringTurn, 'background dot should still be visible after turn completes').toBeGreaterThan(0)
 
@@ -225,8 +240,9 @@ test.describe('sidebar states — cross-session dot transition', () => {
     await page.locator('button:has-text("New session")').first().click()
     await page.waitForTimeout(2000)
 
-    // Now wait for the background process to finish (sleep 5 + auto-dismiss).
-    // The session A dot should transition away from "background running".
+    // Now let the background process finish. The session A dot should
+    // transition away from "background running".
+    bgRelease.release()
     await expect
       .poll(
         () => page.locator(`[aria-label="${BG_DOT_LABEL}"]`).count(),
diff --git a/apps/desktop/e2e/tile-unread-bug.spec.ts b/apps/desktop/e2e/tile-unread-bug.spec.ts
index cd87a2eb681..fa614a21d2f 100644
--- a/apps/desktop/e2e/tile-unread-bug.spec.ts
+++ b/apps/desktop/e2e/tile-unread-bug.spec.ts
@@ -22,7 +22,12 @@ import {
   setupMockBackend,
   waitForAppReady,
 } from './fixtures'
-import { SIDEBAR_CROSS_TEXTS, restartMockServer } from './mock-server'
+import {
+  type BackgroundReleaseHandle,
+  createBackgroundReleaseHandle,
+  restartMockServer,
+  SIDEBAR_CROSS_TEXTS,
+} from './mock-server'
 
 /** Finished-unread dot aria-label. */
 const UNREAD_DOT_LABEL = 'Finished — unread'
@@ -34,7 +39,7 @@ function sessionRow(page: import('@playwright/test').Page, text: string) {
   return page.locator('[data-slot="sidebar"] button').filter({ hasText: text }).first()
 }
 
-/** Common setup: start a turn with a sleep 5 bg process + subagent, wait for
+/** Common setup: start a turn with a held bg process + subagent, wait for
  *  the turn to complete, then switch to a new session so the first session is
  *  no longer $selectedStoredSessionId (required before opening a tile). */
 async function startTurnAndSwitchAway(page: import('@playwright/test').Page) {
@@ -67,7 +72,9 @@ async function startTurnAndSwitchAway(page: import('@playwright/test').Page) {
     { timeout: 90_000 },
   )
 
-  // The background dot should still be visible (sleep 5 hasn't finished).
+  // The background dot must still be visible: the turn is done but the
+  // process is held open by the sentinel, so this is a stable state rather
+  // than a window we have to catch in time.
   const bgDuringTurn = await page.locator(`[aria-label="${BG_DOT_LABEL}"]`).count()
   expect(bgDuringTurn, 'background dot should still be visible after turn completes').toBeGreaterThan(0)
 
@@ -77,8 +84,12 @@ async function startTurnAndSwitchAway(page: import('@playwright/test').Page) {
   await page.waitForTimeout(2000)
 }
 
-/** Wait for the background process to finish (sleep 5 + auto-dismiss). */
-async function waitForBgProcessToFinish(page: import('@playwright/test').Page) {
+/** Release the held background process, then wait for its dot to clear. */
+async function waitForBgProcessToFinish(
+  page: import('@playwright/test').Page,
+  release?: BackgroundReleaseHandle,
+) {
+  release?.release()
   await expect
     .poll(
       () => page.locator(`[aria-label="${BG_DOT_LABEL}"]`).count(),
@@ -95,15 +106,20 @@ test.describe('sidebar states — tab (hidden) unread is correct', () => {
   test.describe.configure({ mode: 'serial' })
 
   let fixture: MockBackendFixture
+  const bgRelease = createBackgroundReleaseHandle()
 
   test.beforeAll(async () => {
     restartMockServer()
-    fixture = await setupMockBackend()
+    fixture = await setupMockBackend({
+      mockServer: { backgroundReleasePath: bgRelease.path },
+    })
     await waitForAppReady(fixture, 120_000)
   })
 
   test.afterAll(async () => {
+    bgRelease.release()
     await fixture?.cleanup()
+    bgRelease.cleanup()
   })
 
   test('session opened as a tab (not visible) correctly gets unread dot', async () => {
@@ -123,12 +139,21 @@ test.describe('sidebar states — tab (hidden) unread is correct', () => {
     // Evidence: the tab is open but the session is not visible on screen.
     await page.screenshot({ path: 'test-results/tile-bug-tab-opened.png' })
 
-    await waitForBgProcessToFinish(page)
+    await waitForBgProcessToFinish(page, bgRelease)
 
     // A tab that's not the active tab IS hidden — the unread dot is correct.
     // The user is NOT looking at it, so marking it "unread" is right.
-    const unreadCount = await page.locator(`[aria-label="${UNREAD_DOT_LABEL}"]`).count()
-    expect(unreadCount, 'hidden tab should be marked unread').toBeGreaterThan(0)
+    //
+    // Poll rather than sampling once: "finished-unread" is an event-driven
+    // transition that lands slightly after the running dot clears, and with a
+    // released (rather than slowly-expiring) process there is no incidental
+    // slack between the two. Same reasoning as the cross-session spec.
+    await expect
+      .poll(
+        () => page.locator(`[aria-label="${UNREAD_DOT_LABEL}"]`).count(),
+        { timeout: 30_000, message: 'hidden tab should be marked unread' },
+      )
+      .toBeGreaterThan(0)
 
     await page.screenshot({ path: 'test-results/tile-bug-tab-unread-correct.png' })
   })
@@ -142,15 +167,20 @@ test.describe.skip('sidebar states — split (visible) unread bug (RED)', () =>
   test.describe.configure({ mode: 'serial' })
 
   let fixture: MockBackendFixture
+  const bgRelease = createBackgroundReleaseHandle()
 
   test.beforeAll(async () => {
     restartMockServer()
-    fixture = await setupMockBackend()
+    fixture = await setupMockBackend({
+      mockServer: { backgroundReleasePath: bgRelease.path },
+    })
     await waitForAppReady(fixture, 120_000)
   })
 
   test.afterAll(async () => {
+    bgRelease.release()
     await fixture?.cleanup()
+    bgRelease.cleanup()
   })
 
   test('session visible in a split tile does NOT get unread dot when it finishes', async () => {
@@ -196,7 +226,7 @@ test.describe.skip('sidebar states — split (visible) unread bug (RED)', () =>
     // Evidence: the split tile is now open side-by-side — both sessions visible.
     await page.screenshot({ path: 'test-results/tile-bug-split-opened.png' })
 
-    await waitForBgProcessToFinish(page)
+    await waitForBgProcessToFinish(page, bgRelease)
 
     // THE BUG: the session visible in the split tile should NOT have the green
     // "finished unread" dot — the user is looking right at it. This assertion
diff --git a/apps/desktop/e2e/warm-resume-jitter.spec.ts b/apps/desktop/e2e/warm-resume-jitter.spec.ts
index 72e71087d69..dbc0fe5dd11 100644
--- a/apps/desktop/e2e/warm-resume-jitter.spec.ts
+++ b/apps/desktop/e2e/warm-resume-jitter.spec.ts
@@ -24,6 +24,8 @@
  *    MutationObserver burst), but `$messages` was still set twice.
  *
  * The test passes when bursts === 1 AND reconciles === 0.
+ * The sidebar "+" keeps the session warm in another tab. Its reactivation
+ * follows the same contract: one additive paint and zero reconciles.
  *
  * Prerequisite: `npm run build` must have been run so dist/ exists.
  */
@@ -43,6 +45,11 @@ import { startMockServer } from './mock-server'
 import { RealSessionBuilder } from './real-session-builder'
 
 const SESSION_TITLE = 'E2E Warm Resume Jitter Test'
+
+// Inactive tabs stay mounted under a data-pane-hidden ancestor. Match the
+// renderer's keep-alive visibility policy instead of relying on DOM order.
+const SURFACE = '[data-composer-target]:not([data-pane-hidden] [data-composer-target])'
+const ALL_SURFACES = '[data-composer-target]'
 /** 32 messages (16 user/assistant pairs) — enough DOM churn for detection. */
 const MESSAGE_COUNT = 32
 /** Seeded PRNG so the generated content is deterministic across runs. */
@@ -154,15 +161,29 @@ test.afterAll(async () => {
  *   after the initial paint, catching key-based reconciles that don't
  *   add/remove nodes.
  */
-async function installRenderCounter(page: import('@playwright/test').Page): Promise<void> {
-  await page.evaluate(() => {
-    const viewport = document.querySelector('[data-slot="aui_thread-viewport"]')
+async function installRenderCounter(
+  page: import('@playwright/test').Page,
+  transcriptText?: string,
+): Promise<void> {
+  await page.evaluate(([visibleSelector, allSelector, expected]: [string, string, string | undefined]) => {
+    const surfaces = [...document.querySelectorAll(expected ? allSelector : visibleSelector)]
+    const surface = expected
+      ? surfaces.find(candidate =>
+          (candidate.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? '').includes(expected),
+        )
+      : surfaces.at(-1)
+    const viewport = surface?.querySelector('[data-slot="aui_thread-viewport"]')
     if (!viewport) {
       throw new Error('Thread viewport not found before warm resume')
     }
 
     const state = { bursts: 0, mutations: 0, timeline: [] as number[], stopped: false, reconciles: 0 }
-    ;(window as unknown as { __RENDER_COUNT__: typeof state }).__RENDER_COUNT__ = state
+    const debugWindow = window as unknown as {
+      __RENDER_COUNT__: typeof state
+      __RENDER_VIEWPORT__: Element
+    }
+    debugWindow.__RENDER_COUNT__ = state
+    debugWindow.__RENDER_VIEWPORT__ = viewport
 
     let currentBatch = 0
     let flushTimer: ReturnType<typeof setTimeout> | null = null
@@ -224,7 +245,53 @@ async function installRenderCounter(page: import('@playwright/test').Page): Prom
         hasMessages = true
       }
     }, 2)
-  })
+  }, [SURFACE, ALL_SURFACES, transcriptText] as [string, string, string | undefined])
+}
+
+/** Wait until the ACTIVE chat surface's transcript contains `text`. */
+async function waitForActiveTranscriptText(
+  page: import('@playwright/test').Page,
+  text: string,
+  timeout = 30_000,
+): Promise<void> {
+  await page.waitForFunction(
+    ([expected, surfaceSelector]: [string, string]) => {
+      const surfaces = document.querySelectorAll(surfaceSelector)
+      const active = surfaces[surfaces.length - 1]
+
+      return (active?.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? '').includes(expected)
+    },
+    [text, SURFACE] as [string, string],
+    { timeout },
+  )
+}
+
+async function waitForActiveTranscriptWithoutText(
+  page: import('@playwright/test').Page,
+  text: string,
+): Promise<void> {
+  await page.waitForFunction(
+    ([expected, surfaceSelector]: [string, string]) => {
+      const surfaces = document.querySelectorAll(surfaceSelector)
+      const active = surfaces[surfaces.length - 1]
+
+      return !(active?.querySelector('[data-slot="aui_thread-viewport"]')?.textContent ?? '').includes(expected)
+    },
+    [text, SURFACE] as [string, string],
+    { timeout: 15_000 },
+  )
+}
+
+/** Replace the primary surface with a draft while retaining its warm cache. */
+async function openFreshDraft(page: import('@playwright/test').Page, priorText: string): Promise<void> {
+  await page.keyboard.press(process.platform === 'darwin' ? 'Meta+N' : 'Control+N')
+  await waitForActiveTranscriptWithoutText(page, priorText)
+}
+
+/** Stack an empty tab while leaving the current transcript mounted and warm. */
+async function openNewSessionTab(page: import('@playwright/test').Page, priorText: string): Promise<void> {
+  await page.locator('[data-slot="sidebar"] button[aria-label="New session"]').first().click()
+  await waitForActiveTranscriptWithoutText(page, priorText)
 }
 
 /** Stop the render counter and return the recorded burst/reconcile counts. */
@@ -245,6 +312,30 @@ async function readRenderCount(page: import('@playwright/test').Page): Promise<{
   })
 }
 
+async function observedViewportIsActive(page: import('@playwright/test').Page): Promise<boolean> {
+  return page.evaluate((surfaceSelector: string) => {
+    const surfaces = document.querySelectorAll(surfaceSelector)
+    const activeViewport = surfaces[surfaces.length - 1]?.querySelector('[data-slot="aui_thread-viewport"]')
+    const observedViewport = (window as unknown as { __RENDER_VIEWPORT__?: Element }).__RENDER_VIEWPORT__
+
+    return activeViewport === observedViewport
+  }, SURFACE)
+}
+
+/** A kept-alive tab must become visible without rebuilding its transcript. */
+function assertNoRepaint(result: { bursts: number; mutations: number; timeline: number[]; reconciles: number } | null): void {
+  expect(result, 'MutationObserver should have recorded render data').toBeTruthy()
+  expect(
+    result!.bursts,
+    `Expected no additive render bursts for a kept-alive tab, but got ${result!.bursts}. ` +
+      `Mutation timeline: ${JSON.stringify(result!.timeline)}.`,
+  ).toBe(0)
+  expect(
+    result!.reconciles,
+    `Expected no transcript reconciles for a kept-alive tab, but got ${result!.reconciles}.`,
+  ).toBe(0)
+}
+
 /** Assert the render counter shows exactly one paint with no re-renders. */
 function assertNoJitter(result: { bursts: number; mutations: number; timeline: number[]; reconciles: number } | null): void {
   expect(result, 'MutationObserver should have recorded render data').toBeTruthy()
@@ -261,7 +352,7 @@ function assertNoJitter(result: { bursts: number; mutations: number; timeline: n
   ).toBe(0)
 }
 
-test('warm-route resume paints transcript exactly once (no jitter)', async ({}, testInfo) => {
+test('tab reactivation preserves the mounted transcript without repainting', async ({}, testInfo) => {
   const page = fixture!.page
 
   // Wait for the sidebar to populate with our seeded session.
@@ -277,63 +368,29 @@ test('warm-route resume paints transcript exactly once (no jitter)', async ({},
 
   // Wait for the transcript to appear — the first user message text confirms
   // the cold-path prefetch painted.
-  await page.waitForFunction(
-    (text: string) =>
-      document.querySelector('[data-slot="aui_thread-viewport"]')?.textContent?.includes(text) ??
-      false,
-    FIRST_USER_MSG,
-    { timeout: 30_000 },
-  )
+  await waitForActiveTranscriptText(page, FIRST_USER_MSG)
 
   // Wait for the session to fully settle (cold-path RPC + reconciliation).
   await page.waitForTimeout(2_000)
 
-  // Step 2: Navigate away to a new chat — this does NOT evict the warm cache.
-  const newSessionButton = page
-    .locator('[data-slot="sidebar"] button[aria-label="New session"]')
-    .first()
-  await newSessionButton.click()
-
-  // Wait for the new-chat empty state.
-  await page.waitForFunction(
-    (firstMsg: string) => {
-      const viewport = document.querySelector('[data-slot="aui_thread-viewport"]')
-      if (!viewport) return false
-      const text = viewport.textContent ?? ''
-      return !text.includes(firstMsg)
-    },
-    FIRST_USER_MSG,
-    { timeout: 15_000 },
-  )
-
+  // Stack a new tab, then observe the seeded transcript while it is hidden.
+  // Installing after the switch isolates reactivation from mutations caused
+  // while the new tab was being created.
+  await openNewSessionTab(page, FIRST_USER_MSG)
   await page.waitForTimeout(500)
+  await installRenderCounter(page, FIRST_USER_MSG)
 
-  // Step 3: Install render counter, click back (warm resume), wait, assert.
-  await installRenderCounter(page)
+  // Step 3: Click back and verify the same kept-alive viewport becomes active
+  // without rebuilding or reconciling its transcript.
   await sessionRow.click()
 
-  await page.waitForFunction(
-    (text: string) =>
-      document.querySelector('[data-slot="aui_thread-viewport"]')?.textContent?.includes(text) ??
-      false,
-    FIRST_USER_MSG,
-    { timeout: 30_000 },
-  )
-
-  // Wait for at least 1 burst, then settle.
-  await page.waitForFunction(
-    () => {
-      const w = window as unknown as { __RENDER_COUNT__?: { bursts: number } }
-      return Boolean(w.__RENDER_COUNT__ && w.__RENDER_COUNT__.bursts > 0)
-    },
-    undefined,
-    { timeout: 10_000 },
-  )
+  await waitForActiveTranscriptText(page, FIRST_USER_MSG)
   await page.waitForTimeout(2_000)
+  expect(await observedViewportIsActive(page), 'Reactivation should reveal the observed kept-alive viewport').toBe(true)
 
   const result = await readRenderCount(page)
   await page.screenshot({ path: testInfo.outputPath('warm-resume-idle.png') })
-  assertNoJitter(result)
+  assertNoRepaint(result)
 })
 
 test('warm-route resume after background inference completes (no jitter)', async ({}, testInfo) => {
@@ -354,13 +411,7 @@ test('warm-route resume after background inference completes (no jitter)', async
 
   // Step 1: Cold resume — populate the warm cache.
   await sessionRow.click()
-  await page.waitForFunction(
-    (text: string) =>
-      document.querySelector('[data-slot="aui_thread-viewport"]')?.textContent?.includes(text) ??
-      false,
-    FIRST_USER_MSG,
-    { timeout: 30_000 },
-  )
+  await waitForActiveTranscriptText(page, FIRST_USER_MSG)
   await page.waitForTimeout(2_000)
 
   // Step 2: Send a message — triggers inference via the mock server.
@@ -373,34 +424,15 @@ test('warm-route resume after background inference completes (no jitter)', async
   // Wait for the mock response to appear in the transcript, confirming
   // the turn completed and message.complete fired (which updates the warm
   // cache via updateSessionState).
-  await page.waitForFunction(
-    () => {
-      const viewport = document.querySelector('[data-slot="aui_thread-viewport"]')
-      return viewport?.textContent?.includes('mock inference server') ?? false
-    },
-    undefined,
-    { timeout: 60_000 },
-  )
+  await waitForActiveTranscriptText(page, 'mock inference server', 60_000)
   // Extra settle for message.complete → updateSessionState → cache write.
   await page.waitForTimeout(2_000)
 
   // Verify the prompt was received by the mock server.
   expect(mock.receivedPrompts).toContain(PROMPT)
 
-  // Step 3: Navigate away — the warm cache retains the updated messages.
-  const newSessionButton = page
-    .locator('[data-slot="sidebar"] button[aria-label="New session"]')
-    .first()
-  await newSessionButton.click()
-  await page.waitForFunction(
-    (prompt: string) => {
-      const viewport = document.querySelector('[data-slot="aui_thread-viewport"]')
-      if (!viewport) return false
-      return !(viewport.textContent ?? '').includes(prompt)
-    },
-    PROMPT,
-    { timeout: 15_000 },
-  )
+  // Step 3: Replace the primary chat; the warm cache retains the updated messages.
+  await openFreshDraft(page, PROMPT)
   await page.waitForTimeout(500)
 
   // Step 4: Install render counter, click back (warm resume), wait, assert.
@@ -409,13 +441,7 @@ test('warm-route resume after background inference completes (no jitter)', async
 
   // Wait for the transcript to reappear — the warm cache should already
   // have the completed turn (updated by message.complete events).
-  await page.waitForFunction(
-    (text: string) =>
-      document.querySelector('[data-slot="aui_thread-viewport"]')?.textContent?.includes(text) ??
-      false,
-    FIRST_USER_MSG,
-    { timeout: 30_000 },
-  )
+  await waitForActiveTranscriptText(page, FIRST_USER_MSG)
 
   // Wait for at least 1 burst, then settle.
   await page.waitForFunction(
diff --git a/apps/desktop/electron/backend-env.test.ts b/apps/desktop/electron/backend-env.test.ts
index e24a66ee396..a92ce6e062e 100644
--- a/apps/desktop/electron/backend-env.test.ts
+++ b/apps/desktop/electron/backend-env.test.ts
@@ -68,6 +68,26 @@ test('buildDesktopBackendEnv extends PYTHONPATH and backend PATH together', () =
   assert.ok(env.PATH.includes('/opt/homebrew/bin'))
 })
 
+test('buildDesktopBackendEnv forces PYTHONUTF8 unless the user set it explicitly', () => {
+  const defaulted = buildDesktopBackendEnv({
+    hermesHome: '/Users/test/.hermes',
+    currentEnv: { PATH: '/usr/bin' },
+    platform: 'darwin',
+    pathModule: path.posix
+  })
+
+  assert.equal(defaulted.PYTHONUTF8, '1')
+
+  const optedOut = buildDesktopBackendEnv({
+    hermesHome: '/Users/test/.hermes',
+    currentEnv: { PATH: '/usr/bin', PYTHONUTF8: '0' },
+    platform: 'darwin',
+    pathModule: path.posix
+  })
+
+  assert.equal(optedOut.PYTHONUTF8, '0')
+})
+
 test('normalizeHermesHomeRoot maps profile homes back to the global Hermes root', () => {
   assert.equal(
     normalizeHermesHomeRoot('/Users/test/.hermes/profiles/oracle', { pathModule: path.posix }),
diff --git a/apps/desktop/electron/backend-env.ts b/apps/desktop/electron/backend-env.ts
index a225e238177..3db4a19d034 100644
--- a/apps/desktop/electron/backend-env.ts
+++ b/apps/desktop/electron/backend-env.ts
@@ -104,6 +104,13 @@ function buildDesktopBackendEnv({
 
   return {
     PYTHONPATH: appendUniquePathEntries([...pythonPathEntries, currentPythonPath], { delimiter }),
+    // Force PEP 540 UTF-8 mode in the spawned Python backend so its stdio and
+    // subprocess defaults are UTF-8 even on non-UTF-8 Windows locales (GBK,
+    // cp1252, ...). hermes_bootstrap sets this inside the child too, but only
+    // after import — anything emitted earlier (interpreter startup errors,
+    // pre-bootstrap tracebacks) still decodes with the locale default without
+    // this. User's explicit setting wins. Re-port of PR #56499 (echoriver89).
+    PYTHONUTF8: currentEnv?.PYTHONUTF8 ?? '1',
     [key]: buildDesktopBackendPath({
       hermesHome,
       venvRoot,
diff --git a/apps/desktop/electron/backend-health.test.ts b/apps/desktop/electron/backend-health.test.ts
new file mode 100644
index 00000000000..8d29ea1988d
--- /dev/null
+++ b/apps/desktop/electron/backend-health.test.ts
@@ -0,0 +1,340 @@
+import assert from 'node:assert/strict'
+
+import { test } from 'vitest'
+
+import {
+  DEFAULT_HEALTH_PROBE_TIMEOUT_MS,
+  isAuthRejectionError,
+  isGatedMissingHealthError,
+  isMissingHealthEndpointError,
+  isReauthRequiredError,
+  waitForHermesReady
+} from './backend-health'
+
+const GATE_401 = '401: {"error":"unauthenticated","detail":"Unauthorized","reason":"no_cookie","login_url":"/login"}'
+
+test('uses lightweight /api/health for current backends', async () => {
+  const calls: string[][] = []
+
+  await waitForHermesReady('http://127.0.0.1:9000/', {
+    token: 'secret-token',
+    fetchPublicJson: async url => {
+      calls.push(['public', url])
+
+      return { ok: true }
+    },
+    fetchJson: async url => {
+      calls.push(['token', url])
+      throw new Error('status should not be called')
+    },
+    sleep: async () => {},
+    timeoutMs: 100,
+    pollMs: 1
+  })
+
+  assert.deepEqual(calls, [['public', 'http://127.0.0.1:9000/api/health']])
+})
+
+test('falls back to /api/status only for old backends without /api/health', async () => {
+  const calls: string[][] = []
+
+  await waitForHermesReady('http://127.0.0.1:9000', {
+    token: 'secret-token',
+    fetchPublicJson: async url => {
+      calls.push(['public', url])
+
+      throw new Error('404: {"detail":"Not Found"}')
+    },
+    fetchJson: async (url, token) => {
+      calls.push(['token', url, token ?? ''])
+
+      return { version: 'old' }
+    },
+    sleep: async () => {},
+    timeoutMs: 100,
+    pollMs: 1
+  })
+
+  assert.deepEqual(calls, [
+    ['public', 'http://127.0.0.1:9000/api/health'],
+    ['token', 'http://127.0.0.1:9000/api/status', 'secret-token']
+  ])
+})
+
+test('does not fall back to heavyweight /api/status for transient health failures', async () => {
+  const calls: string[][] = []
+  let currentTime = 0
+
+  await assert.rejects(
+    waitForHermesReady('http://127.0.0.1:9000', {
+      fetchPublicJson: async url => {
+        calls.push(['public', url])
+        throw new Error('Timed out connecting to Hermes backend after 15000ms')
+      },
+      fetchJson: async url => {
+        calls.push(['token', url])
+      },
+      sleep: async () => {},
+      now: () => {
+        currentTime += 20
+
+        return currentTime
+      },
+      timeoutMs: 50,
+      pollMs: 1
+    }),
+    /Timed out connecting/
+  )
+
+  assert.ok(calls.length > 0)
+  assert.ok(calls.every(call => call[0] === 'public' && call[1].endsWith('/api/health')))
+})
+
+test('probes health on a short timeout but leaves the legacy fallback its own', async () => {
+  const timeouts: (number | undefined)[] = []
+
+  await waitForHermesReady('http://127.0.0.1:9000', {
+    fetchPublicJson: async (_url, options) => {
+      timeouts.push(options?.timeoutMs)
+
+      throw new Error('404: {"detail":"Not Found"}')
+    },
+    fetchJson: async (_url, _token, options) => {
+      timeouts.push(options?.timeoutMs)
+
+      return { version: 'old' }
+    },
+    sleep: async () => {},
+    timeoutMs: 100,
+    pollMs: 1
+  })
+
+  assert.deepEqual(timeouts, [DEFAULT_HEALTH_PROBE_TIMEOUT_MS, undefined])
+})
+
+test('aborts as superseded when the bootstrap signal fires', async () => {
+  const controller = new AbortController()
+  controller.abort()
+
+  await assert.rejects(
+    waitForHermesReady('http://127.0.0.1:9000', {
+      signal: controller.signal,
+      fetchPublicJson: async () => {
+        throw new Error('should not probe after abort')
+      },
+      fetchJson: async () => {
+        throw new Error('should not probe after abort')
+      },
+      timeoutMs: 100,
+      pollMs: 1
+    }),
+    (error: any) => error.kind === 'superseded'
+  )
+})
+
+test('recognizes missing-route shapes only', () => {
+  assert.equal(isMissingHealthEndpointError(new Error('404: {"detail":"Not Found"}')), true)
+  assert.equal(
+    isMissingHealthEndpointError(
+      new Error('Expected JSON from /api/health but got HTML. The endpoint is likely missing on the Hermes backend.')
+    ),
+    true
+  )
+  assert.equal(isMissingHealthEndpointError(new Error('Timed out connecting to Hermes backend after 15000ms')), false)
+  assert.equal(isMissingHealthEndpointError(new Error('500: boom')), false)
+})
+
+// --- Gated backends that predate /api/health (release 0.19.0 and earlier) ---
+//
+// The dashboard auth gate runs ahead of the SPA catch-all, so on a backend
+// without the route an ANONYMOUS probe is rejected as unauthenticated rather
+// than 404 — verified against a simulated 0.19.0 backend:
+//   credential-free: /api/health -> 401 no_cookie, /api/status -> 200
+//   credentialed:    /api/health -> 404,           /api/sessions -> 200
+
+test('anonymous gate-shaped 401 falls back to /api/status (backend predates /api/health)', async () => {
+  const calls: string[][] = []
+
+  await waitForHermesReady('http://192.168.1.132:9119', {
+    token: null,
+    fetchPublicJson: async url => {
+      calls.push(['public', url])
+      throw new Error(GATE_401)
+    },
+    fetchJson: async (url, token) => {
+      calls.push(['token', url, token == null ? 'null' : token])
+
+      return { version: '0.19.0', auth_required: true }
+    },
+    sleep: async () => {},
+    timeoutMs: 100,
+    pollMs: 1
+  })
+
+  assert.deepEqual(calls, [
+    ['public', 'http://192.168.1.132:9119/api/health'],
+    ['token', 'http://192.168.1.132:9119/api/status', 'null']
+  ])
+})
+
+test('a credentialed 401 fails fast for reauth instead of reporting a dead session ready', async () => {
+  // The regression a blanket 401->fallback introduces: /api/status is public,
+  // so an expired session would answer 200 and boot would report "ready",
+  // deferring the no_cookie to the first real API call.
+  const calls: string[][] = []
+
+  await assert.rejects(
+    waitForHermesReady('https://gateway.example', {
+      token: 'session-token',
+      fetchPublicJson: async () => {
+        throw new Error('public probe must not be used when credentialed')
+      },
+      fetchJson: async url => {
+        calls.push(['status', url])
+
+        return { version: '0.19.0' }
+      },
+      probeHealth: async url => {
+        calls.push(['probe', url])
+        throw new Error(GATE_401)
+      },
+      probeIsCredentialed: true,
+      sleep: async () => {},
+      timeoutMs: 100,
+      pollMs: 1
+    }),
+    (error: any) => {
+      assert.equal(isReauthRequiredError(error), true)
+      assert.equal(error.needsOauthLogin, true)
+      assert.match(error.message, /remote gateway session has expired/i)
+
+      return true
+    }
+  )
+
+  // Fail fast: never reached the public /api/status leg.
+  assert.deepEqual(calls, [['probe', 'https://gateway.example/api/health']])
+})
+
+test('a credentialed 403 is also a terminal reauth failure', async () => {
+  await assert.rejects(
+    waitForHermesReady('https://gateway.example', {
+      fetchPublicJson: async () => ({}),
+      fetchJson: async () => ({}),
+      probeHealth: async () => {
+        throw new Error('403: {"detail":"Forbidden"}')
+      },
+      probeIsCredentialed: true,
+      sleep: async () => {},
+      timeoutMs: 100,
+      pollMs: 1
+    }),
+    (error: any) => isReauthRequiredError(error)
+  )
+})
+
+test('a credentialed probe still uses the 404 fallback for a genuinely missing route', async () => {
+  // With credentials the gate lets the request through to the SPA catch-all,
+  // so an old backend answers a real 404 — that must still fall back, not be
+  // mistaken for a rejected session.
+  const calls: string[][] = []
+
+  await waitForHermesReady('https://gateway.example', {
+    token: 'session-token',
+    fetchPublicJson: async () => {
+      throw new Error('public probe must not be used when credentialed')
+    },
+    fetchJson: async url => {
+      calls.push(['status', url])
+
+      return { version: '0.19.0' }
+    },
+    probeHealth: async url => {
+      calls.push(['probe', url])
+      throw new Error('404: {"detail":"Not Found"}')
+    },
+    probeIsCredentialed: true,
+    sleep: async () => {},
+    timeoutMs: 100,
+    pollMs: 1
+  })
+
+  assert.deepEqual(calls, [
+    ['probe', 'https://gateway.example/api/health'],
+    ['status', 'https://gateway.example/api/status']
+  ])
+})
+
+test('a non-gate 401 keeps polling rather than skipping a misconfigured health route', async () => {
+  const calls: string[][] = []
+  let currentTime = 0
+
+  await assert.rejects(
+    waitForHermesReady('http://127.0.0.1:9000', {
+      fetchPublicJson: async url => {
+        calls.push(['public', url])
+        throw new Error('401: {"detail":"Unauthorized"}')
+      },
+      fetchJson: async url => {
+        calls.push(['token', url])
+      },
+      sleep: async () => {},
+      now: () => {
+        currentTime += 20
+
+        return currentTime
+      },
+      timeoutMs: 50,
+      pollMs: 1
+    }),
+    /401: \{"detail":"Unauthorized"\}/
+  )
+
+  assert.ok(calls.length > 0)
+  assert.ok(calls.every(call => call[0] === 'public' && call[1].endsWith('/api/health')))
+})
+
+test('credentialed 5xx and 429 keep polling — only 401/403 are terminal', async () => {
+  for (const transient of ['500: boom', '429: {"detail":"Too Many Requests"}']) {
+    let attempts = 0
+    let currentTime = 0
+
+    await assert.rejects(
+      waitForHermesReady('https://gateway.example', {
+        fetchPublicJson: async () => ({}),
+        fetchJson: async () => ({}),
+        probeHealth: async () => {
+          attempts += 1
+          throw new Error(transient)
+        },
+        probeIsCredentialed: true,
+        sleep: async () => {},
+        now: () => {
+          currentTime += 20
+
+          return currentTime
+        },
+        timeoutMs: 100,
+        pollMs: 1
+      }),
+      (error: any) => isReauthRequiredError(error) === false
+    )
+
+    assert.ok(attempts > 1, `${transient} should have retried, got ${attempts} attempt(s)`)
+  }
+})
+
+test('error-shape predicates', () => {
+  assert.equal(isGatedMissingHealthError(new Error(GATE_401)), true)
+  assert.equal(isGatedMissingHealthError(new Error('401: {"detail":"Unauthorized"}')), false)
+  assert.equal(isGatedMissingHealthError(new Error('404: {"detail":"Not Found"}')), false)
+
+  assert.equal(isAuthRejectionError(new Error(GATE_401)), true)
+  assert.equal(isAuthRejectionError(new Error('403: {"detail":"Forbidden"}')), true)
+  assert.equal(isAuthRejectionError(new Error('404: {"detail":"Not Found"}')), false)
+  assert.equal(isAuthRejectionError(new Error('429: slow down')), false)
+  assert.equal(isAuthRejectionError(new Error('500: boom')), false)
+
+  // A gated 401 must NOT be conflated with a missing route by the 404 predicate.
+  assert.equal(isMissingHealthEndpointError(new Error(GATE_401)), false)
+})
diff --git a/apps/desktop/electron/backend-health.ts b/apps/desktop/electron/backend-health.ts
new file mode 100644
index 00000000000..3da6c7a80fa
--- /dev/null
+++ b/apps/desktop/electron/backend-health.ts
@@ -0,0 +1,169 @@
+export const DEFAULT_BACKEND_READY_TIMEOUT_MS = 45_000
+export const DEFAULT_BACKEND_READY_POLL_MS = 500
+// A cold backend can stall its event loop for tens of seconds while Windows
+// scans and byte-compiles the gateway import tree. At the default 15s socket
+// timeout only three probes fit in the budget; a short one keeps retrying
+// across the stall. Health only — the legacy /api/status fallback is genuinely
+// slow to answer and keeps the caller's default timeout.
+export const DEFAULT_HEALTH_PROBE_TIMEOUT_MS = 5_000
+
+type FetchPublicJson = (url: string, options?: { timeoutMs?: number }) => Promise<unknown>
+type FetchJson = (url: string, token?: string | null, options?: { timeoutMs?: number }) => Promise<unknown>
+
+export interface HermesReadyOptions {
+  fetchPublicJson: FetchPublicJson
+  fetchJson: FetchJson
+  token?: string | null
+  signal?: AbortSignal
+  timeoutMs?: number
+  pollMs?: number
+  healthProbeTimeoutMs?: number
+  sleep?: (ms: number) => Promise<void>
+  now?: () => number
+  /**
+   * Credentialed health probe. When supplied, readiness is probed with the
+   * connection's own credentials instead of anonymously — which is what lets
+   * a gated backend answer 404 for a genuinely missing /api/health, and what
+   * makes a 401 from this probe mean "session rejected" rather than "route
+   * behind a gate". Defaults to the credential-free `fetchPublicJson`.
+   */
+  probeHealth?: (url: string, options?: { timeoutMs?: number }) => Promise<unknown>
+  /**
+   * Whether `probeHealth` actually presents credentials. Distinguishes the
+   * two very different meanings of a 401 (see `waitForHermesReady`).
+   */
+  probeIsCredentialed?: boolean
+}
+
+export const REMOTE_SESSION_EXPIRED_MESSAGE =
+  'Your remote gateway session has expired. Open Settings → Gateway and click "Sign in" again.'
+
+export function isMissingHealthEndpointError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error ?? '')
+
+  return /^404:/.test(message) || message.includes('endpoint is likely missing')
+}
+
+/**
+ * True for a hard auth rejection (401/403) as opposed to a transient failure.
+ * Deliberately shape-based: 429 is a throttle and 5xx is a server fault, and
+ * both must keep polling.
+ */
+export function isAuthRejectionError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error ?? '')
+
+  return /^40[13]:/.test(message)
+}
+
+/**
+ * True for an auth rejection carrying the dashboard gate's "no session at all"
+ * shape. On a backend that predates `/api/health`, the gate runs ahead of the
+ * SPA catch-all, so an unknown `/api/*` path is rejected as unauthenticated
+ * instead of 404 — this is the signal that an ANONYMOUS probe cannot reach the
+ * route, and the reason a credential-free 401 must fall back to `/api/status`
+ * rather than be reported as a boot failure.
+ */
+export function isGatedMissingHealthError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error ?? '')
+
+  return isAuthRejectionError(error) && message.includes('no_cookie')
+}
+
+/** Tag a terminal reauth failure the main process latches and the overlay keys on. */
+export function makeReauthRequiredError(detail?: string): Error {
+  const error = new Error(REMOTE_SESSION_EXPIRED_MESSAGE) as any
+  error.needsOauthLogin = true
+  error.isReauthRequired = true
+
+  if (detail) {
+    error.detail = detail
+  }
+
+  return error
+}
+
+export function isReauthRequiredError(error: unknown): boolean {
+  return Boolean((error as any)?.isReauthRequired)
+}
+
+function supersededError() {
+  const error: any = new Error('SSH bootstrap was superseded by newer connection settings.')
+  error.kind = 'superseded'
+
+  return error
+}
+
+export async function waitForHermesReady(baseUrl: string, options: HermesReadyOptions): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_BACKEND_READY_TIMEOUT_MS
+  const pollMs = options.pollMs ?? DEFAULT_BACKEND_READY_POLL_MS
+  const healthProbeTimeoutMs = options.healthProbeTimeoutMs ?? DEFAULT_HEALTH_PROBE_TIMEOUT_MS
+  const now = options.now ?? Date.now
+  const signal = options.signal
+
+  const sleep =
+    options.sleep ??
+    (ms =>
+      new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(resolve, ms)
+        signal?.addEventListener(
+          'abort',
+          () => {
+            clearTimeout(timer)
+            reject(supersededError())
+          },
+          { once: true }
+        )
+      }))
+
+  const base = baseUrl.replace(/\/+$/, '')
+  const deadline = now() + timeoutMs
+  const probeHealth = options.probeHealth ?? options.fetchPublicJson
+  const probeIsCredentialed = Boolean(options.probeIsCredentialed)
+  let lastError: unknown = null
+  let useStatusFallback = false
+
+  while (now() < deadline) {
+    if (signal?.aborted) {
+      throw supersededError()
+    }
+
+    try {
+      if (useStatusFallback) {
+        await options.fetchJson(`${base}/api/status`, options.token)
+      } else {
+        await probeHealth(`${base}/api/health`, { timeoutMs: healthProbeTimeoutMs })
+      }
+
+      return
+    } catch (error) {
+      lastError = error
+
+      // A confirmed 401/403 from a CREDENTIALED probe means the session was
+      // rejected, not that the route is missing. Fail fast into a reauth
+      // state: falling back to the public /api/status would answer 200 and
+      // report a dead session as "ready", deferring the failure to the first
+      // real API call. Applies to the /api/status leg too — it is routed
+      // through the same credentials.
+      if (probeIsCredentialed && isAuthRejectionError(error)) {
+        throw makeReauthRequiredError(error instanceof Error ? error.message : String(error))
+      }
+
+      // An explicitly missing route means the backend predates /api/health.
+      // So does a gate-shaped 401 on an ANONYMOUS probe: the dashboard auth
+      // gate runs ahead of the SPA catch-all, so a pre-/api/health backend
+      // rejects the unknown path as unauthenticated instead of 404 and a
+      // credential-free probe can never observe the 404. Timeouts, 5xx, 429,
+      // and non-gate 401s keep polling health.
+      if (!useStatusFallback && (isMissingHealthEndpointError(error) || isGatedMissingHealthError(error))) {
+        useStatusFallback = true
+
+        continue
+      }
+
+      await sleep(pollMs)
+    }
+  }
+
+  const detail = lastError instanceof Error ? lastError.message : 'timeout'
+  throw new Error(`Hermes backend did not become ready: ${detail}`)
+}
diff --git a/apps/desktop/electron/backend-start-failure.test.ts b/apps/desktop/electron/backend-start-failure.test.ts
index 0888d65fbc4..36d352d66cc 100644
--- a/apps/desktop/electron/backend-start-failure.test.ts
+++ b/apps/desktop/electron/backend-start-failure.test.ts
@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
 
 import { test } from 'vitest'
 
-import { shouldLatchBackendStartFailure } from './backend-start-failure'
+import { shouldLatchBackendStartFailure, shouldLatchRemoteReauthFailure } from './backend-start-failure'
 
 test('latches a LOCAL backend failure so the install-retry loop is broken', () => {
   assert.equal(shouldLatchBackendStartFailure({ attemptedRemote: false }), true)
@@ -21,3 +21,32 @@ test('the two branches are mutually exclusive (a failure either latches or stays
     assert.equal(latched, !attemptedRemote)
   }
 })
+
+test('latches a CONFIRMED remote reauth failure so the overlay stays clickable', () => {
+  // Without this the non-latching remote path re-runs startHermes on every
+  // getConnection/api call, re-emits running:true, and the overlay hides
+  // itself — the "Sign in" button flickers away before it can be clicked.
+  assert.equal(shouldLatchRemoteReauthFailure({ attemptedRemote: true, isReauth: true }), true)
+})
+
+test('does not latch a transient remote failure as reauth', () => {
+  // A mint timeout or a host unreachable across sleep must still self-heal.
+  assert.equal(shouldLatchRemoteReauthFailure({ attemptedRemote: true, isReauth: false }), false)
+})
+
+test('never latches a LOCAL failure as reauth (that is backendStartFailure job)', () => {
+  assert.equal(shouldLatchRemoteReauthFailure({ attemptedRemote: false, isReauth: true }), false)
+  assert.equal(shouldLatchRemoteReauthFailure({ attemptedRemote: false, isReauth: false }), false)
+})
+
+test('the two latches never fire for the same failure', () => {
+  // They are complementary, not overlapping: local failures latch via
+  // backendStartFailure, confirmed remote reauth latches via its own flag.
+  for (const attemptedRemote of [true, false]) {
+    for (const isReauth of [true, false]) {
+      const start = shouldLatchBackendStartFailure({ attemptedRemote })
+      const reauth = shouldLatchRemoteReauthFailure({ attemptedRemote, isReauth })
+      assert.ok(!(start && reauth), `both latched for remote=${attemptedRemote} reauth=${isReauth}`)
+    }
+  }
+})
diff --git a/apps/desktop/electron/backend-start-failure.ts b/apps/desktop/electron/backend-start-failure.ts
index 4998b0164a7..3c5ffdbcad9 100644
--- a/apps/desktop/electron/backend-start-failure.ts
+++ b/apps/desktop/electron/backend-start-failure.ts
@@ -39,3 +39,34 @@ export interface BackendStartFailureContext {
 export function shouldLatchBackendStartFailure(context: BackendStartFailureContext): boolean {
   return !context.attemptedRemote
 }
+
+export interface RemoteReauthFailureContext {
+  /** True when the boot that just failed was dialing a REMOTE (or cloud) backend. */
+  attemptedRemote: boolean
+  /**
+   * True when the failure was a CONFIRMED auth rejection (a credentialed
+   * probe got 401/403), not a transient connectivity fault.
+   */
+  isReauth: boolean
+}
+
+/**
+ * Whether a failed remote boot should latch as a reauth failure.
+ *
+ * This is the deliberate counterpart to `shouldLatchBackendStartFailure`,
+ * which never latches a remote failure because remote faults are usually
+ * transient and must stay retryable. A *confirmed* reauth rejection is the
+ * exception: it cannot self-heal, because nothing will change until the user
+ * signs in again.
+ *
+ * Without a latch, the non-latching remote path actively prevents recovery.
+ * Every subsequent `getConnection`/`api` call re-runs `startHermes`, re-emits
+ * `running: true`, and the boot-failure overlay (`visible = Boolean(boot.error)
+ * && !boot.running`) hides itself — so the "Sign in" button flickers out from
+ * under the user before they can click it. Latching holds the overlay still
+ * and clickable. Cleared on every recovery path (reset, repair, apply-config,
+ * and a confirmed sign-in) so a fresh session boots normally.
+ */
+export function shouldLatchRemoteReauthFailure(context: RemoteReauthFailureContext): boolean {
+  return context.attemptedRemote && context.isReauth
+}
diff --git a/apps/desktop/electron/connection-apply.ts b/apps/desktop/electron/connection-apply.ts
index 5764b9091e7..579af1a79e9 100644
--- a/apps/desktop/electron/connection-apply.ts
+++ b/apps/desktop/electron/connection-apply.ts
@@ -1,6 +1,7 @@
 async function applyConnectionChange({
   cancelAndWait,
   isPrimary,
+  rehomePrimary = null,
   scope,
   sendApplied,
   stopPool,
@@ -16,6 +17,12 @@ async function applyConnectionChange({
     return
   }
 
+  if (rehomePrimary) {
+    await rehomePrimary()
+
+    return
+  }
+
   await teardownPrimary()
   sendApplied()
 }
diff --git a/apps/desktop/electron/find-git-bash.test.ts b/apps/desktop/electron/find-git-bash.test.ts
new file mode 100644
index 00000000000..63e00b3c3d6
--- /dev/null
+++ b/apps/desktop/electron/find-git-bash.test.ts
@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict'
+
+import { test } from 'vitest'
+
+import { findGitBash } from './find-git-bash'
+
+const yes = () => true
+const no = () => false
+
+test('HERMES_GIT_BASH_PATH override takes precedence', () => {
+  const result = findGitBash({
+    isWindows: true,
+    env: { HERMES_GIT_BASH_PATH: 'D:\\CustomGit\\bin\\bash.exe' },
+    fileExists: yes,
+    findOnPath: () => null
+  })
+
+  assert.equal(result, 'D:\\CustomGit\\bin\\bash.exe')
+})
+
+test('HERMES_GIT_BASH_PATH invalid path falls through to candidates', () => {
+  const env = {
+    HERMES_GIT_BASH_PATH: 'X:\\Missing\\bash.exe',
+    LOCALAPPDATA: 'C:\\Users\\test\\AppData\\Local',
+    ProgramFiles: 'C:\\Program Files',
+    'ProgramFiles(x86)': 'C:\\Program Files (x86)'
+  }
+
+  const fileExists = (p: string) => p !== 'X:\\Missing\\bash.exe' && p.includes('Program Files\\Git\\bin\\bash.exe')
+  const result = findGitBash({ isWindows: true, env, fileExists, findOnPath: () => null })
+  assert.equal(result, 'C:\\Program Files\\Git\\bin\\bash.exe')
+})
+
+test('HERMES_GIT_BASH_PATH empty string is ignored', () => {
+  const result = findGitBash({
+    isWindows: true,
+    env: { HERMES_GIT_BASH_PATH: '', LOCALAPPDATA: '' },
+    fileExists: no,
+    findOnPath: () => 'C:\\msys64\\usr\\bin\\bash.exe'
+  })
+
+  assert.equal(result, 'C:\\msys64\\usr\\bin\\bash.exe')
+})
+
+test('non-Windows uses findOnPath', () => {
+  const result = findGitBash({
+    isWindows: false,
+    env: {},
+    fileExists: no,
+    findOnPath: () => '/usr/bin/bash'
+  })
+
+  assert.equal(result, '/usr/bin/bash')
+})
diff --git a/apps/desktop/electron/find-git-bash.ts b/apps/desktop/electron/find-git-bash.ts
new file mode 100644
index 00000000000..62369e9bad6
--- /dev/null
+++ b/apps/desktop/electron/find-git-bash.ts
@@ -0,0 +1,67 @@
+import path from 'node:path'
+
+export interface GitBashOptions {
+  isWindows: boolean
+  env: Record<string, string | undefined>
+  fileExists: (filePath: string) => boolean
+  findOnPath?: (command: string) => string | null
+}
+
+/**
+ * Locate bash.exe on Windows.
+ * Resolution order (first match wins):
+ *   1. HERMES_GIT_BASH_PATH env var override
+ *   2. PortableGit under %LOCALAPPDATA%\hermes\git\ (install.ps1)
+ *   3. Standard Git for Windows install locations
+ *   4. %LOCALAPPDATA%\Programs\Git\ (user-scoped)
+ *   5. bash on PATH
+ */
+export function findGitBash(opts: GitBashOptions): string | null {
+  const { isWindows, env, fileExists, findOnPath } = opts
+
+  if (!isWindows) {
+    return findOnPath ? findOnPath('bash') : null
+  }
+
+  // Respect HERMES_GIT_BASH_PATH if set (mirrors tools/environments/local.py:_find_bash).
+  const gitBashPath = env.HERMES_GIT_BASH_PATH
+
+  if (gitBashPath && fileExists(gitBashPath)) {
+    return gitBashPath
+  }
+
+  const localAppData = env.LOCALAPPDATA || ''
+  const candidates: string[] = []
+
+  // Candidate paths are Windows paths regardless of host platform (tests run
+  // on POSIX CI hosts too), so join with win32 semantics explicitly.
+  const joinWin = path.win32.join
+
+  if (localAppData) {
+    candidates.push(joinWin(localAppData, 'hermes', 'git', 'bin', 'bash.exe'))
+    candidates.push(joinWin(localAppData, 'hermes', 'git', 'usr', 'bin', 'bash.exe'))
+  }
+
+  candidates.push(joinWin(env['ProgramFiles'] || 'C:\\Program Files', 'Git', 'bin', 'bash.exe'))
+  candidates.push(joinWin(env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)', 'Git', 'bin', 'bash.exe'))
+
+  if (localAppData) {
+    candidates.push(joinWin(localAppData, 'Programs', 'Git', 'bin', 'bash.exe'))
+  }
+
+  for (const candidate of candidates) {
+    if (fileExists(candidate)) {
+      return candidate
+    }
+  }
+
+  if (findOnPath) {
+    const onPath = findOnPath('bash')
+
+    if (onPath) {
+      return onPath
+    }
+  }
+
+  return null
+}
diff --git a/apps/desktop/electron/first-run-setup-gate.test.ts b/apps/desktop/electron/first-run-setup-gate.test.ts
new file mode 100644
index 00000000000..f8b53525f0f
--- /dev/null
+++ b/apps/desktop/electron/first-run-setup-gate.test.ts
@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict'
+
+import { test } from 'vitest'
+
+import { createFirstRunSetupGate } from './first-run-setup-gate'
+
+const bootstrapBackend = {
+  activeRoot: '/tmp/hermes-home/hermes-agent',
+  kind: 'bootstrap-needed',
+  platform: 'linux'
+}
+
+function delay(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function settledState(promise: Promise<unknown>) {
+  return Promise.race([promise.then(() => 'resolved'), delay(10).then(() => 'pending')])
+}
+
+test('first-run setup gate skips non-bootstrap backends', async () => {
+  const prompts = []
+  const gate = createFirstRunSetupGate({ promptChoice: backend => prompts.push(backend), stuckAfterMs: 0 })
+
+  await gate.wait({ kind: 'remote' })
+  await gate.wait(null)
+
+  assert.deepEqual(prompts, [])
+  assert.equal(gate.hasWaiter(), false)
+})
+
+test('first-run setup gate prompts once for concurrent waits', async () => {
+  const prompts = []
+  const gate = createFirstRunSetupGate({ promptChoice: backend => prompts.push(backend), stuckAfterMs: 0 })
+
+  const first = gate.wait(bootstrapBackend)
+  const second = gate.wait(bootstrapBackend)
+
+  assert.equal(gate.hasWaiter(), true)
+  assert.equal(prompts.length, 1)
+  assert.equal(await settledState(first), 'pending')
+
+  gate.continueLocal()
+
+  assert.deepEqual(await Promise.all([first, second]), ['continue-local', 'continue-local'])
+  assert.equal(gate.hasWaiter(), false)
+  assert.equal(gate.isLocalBootstrapConfirmed(), true)
+})
+
+test('continueLocal keeps the setup choice visible until bootstrap owns the overlay', async () => {
+  let hidden = 0
+  const gate = createFirstRunSetupGate({ hideChoice: () => hidden++, stuckAfterMs: 0 })
+  const pending = gate.wait(bootstrapBackend)
+
+  gate.continueLocal()
+
+  assert.equal(await pending, 'continue-local')
+  assert.equal(hidden, 0)
+  assert.equal(gate.isLocalBootstrapConfirmed(), true)
+})
+
+test('retry reset preserves the local install confirmation', async () => {
+  const prompts = []
+  const gate = createFirstRunSetupGate({ promptChoice: backend => prompts.push(backend), stuckAfterMs: 0 })
+
+  const pending = gate.wait(bootstrapBackend)
+  gate.continueLocal()
+  await pending
+
+  gate.resetForRetry()
+  await gate.wait(bootstrapBackend)
+
+  assert.equal(gate.isLocalBootstrapConfirmed(), true)
+  assert.equal(prompts.length, 1)
+  assert.equal(gate.hasWaiter(), false)
+})
+
+test('retry reset explicitly settles an active waiter without allowing local bootstrap', async () => {
+  const gate = createFirstRunSetupGate({ stuckAfterMs: 0 })
+  const pending = gate.wait(bootstrapBackend)
+
+  gate.resetForRetry()
+
+  assert.equal(await pending, 'reset')
+  assert.equal(gate.hasWaiter(), false)
+  assert.equal(gate.isLocalBootstrapConfirmed(), false)
+})
+
+test('repair reset clears the local install confirmation and shows the gate again', async () => {
+  const prompts = []
+  const gate = createFirstRunSetupGate({ promptChoice: backend => prompts.push(backend), stuckAfterMs: 0 })
+
+  const pending = gate.wait(bootstrapBackend)
+  gate.continueLocal()
+  await pending
+
+  gate.resetForRepair()
+  const next = gate.wait(bootstrapBackend)
+
+  assert.equal(gate.isLocalBootstrapConfirmed(), false)
+  assert.equal(prompts.length, 2)
+  assert.equal(gate.hasWaiter(), true)
+
+  gate.continueLocal()
+  await next
+})
+
+test('remote apply settles the gated boot for remote re-resolution and hides the choice', async () => {
+  let hidden = 0
+  const gate = createFirstRunSetupGate({ hideChoice: () => hidden++, stuckAfterMs: 0 })
+  const pending = gate.wait(bootstrapBackend)
+
+  const resumedWaiter = gate.abandonForRemoteApply()
+
+  assert.equal(resumedWaiter, true)
+  assert.equal(hidden, 1)
+  assert.equal(gate.hasWaiter(), false)
+  assert.equal(gate.isLocalBootstrapConfirmed(), false)
+  assert.equal(await pending, 'remote-applied')
+})
+
+test('remote apply without a waiter has no first-run side effects', async () => {
+  let hidden = 0
+  const gate = createFirstRunSetupGate({ hideChoice: () => hidden++, stuckAfterMs: 0 })
+  const pending = gate.wait(bootstrapBackend)
+
+  gate.continueLocal()
+  await pending
+
+  assert.equal(gate.abandonForRemoteApply(), false)
+  assert.equal(hidden, 0)
+  assert.equal(gate.isLocalBootstrapConfirmed(), true)
+})
diff --git a/apps/desktop/electron/first-run-setup-gate.ts b/apps/desktop/electron/first-run-setup-gate.ts
new file mode 100644
index 00000000000..2d83cbeafe6
--- /dev/null
+++ b/apps/desktop/electron/first-run-setup-gate.ts
@@ -0,0 +1,146 @@
+interface FirstRunSetupBackend {
+  activeRoot?: string
+  kind?: string
+  platform?: string
+}
+
+interface FirstRunSetupGateOptions {
+  hideChoice?: () => void
+  log?: (message: string) => void
+  onStuck?: (backend: FirstRunSetupBackend, stuckAfterMs: number) => void
+  promptChoice?: (backend: FirstRunSetupBackend) => void
+  stuckAfterMs?: number
+}
+
+export type FirstRunSetupDecision = 'continue-local' | 'remote-applied' | 'reset'
+
+export function createFirstRunSetupGate({
+  hideChoice,
+  log,
+  onStuck,
+  promptChoice,
+  stuckAfterMs = 120000
+}: FirstRunSetupGateOptions = {}) {
+  let localBootstrapConfirmed = false
+
+  let waiter: {
+    promise: Promise<FirstRunSetupDecision>
+    resolve: (decision: FirstRunSetupDecision) => void
+  } | null = null
+
+  let stuckTimer: ReturnType<typeof setTimeout> | null = null
+
+  const clearStuckTimer = () => {
+    if (stuckTimer) {
+      clearTimeout(stuckTimer)
+      stuckTimer = null
+    }
+  }
+
+  const armStuckTimer = (backend: FirstRunSetupBackend) => {
+    clearStuckTimer()
+
+    if (!Number.isFinite(stuckAfterMs) || stuckAfterMs <= 0 || typeof log !== 'function') {
+      return
+    }
+
+    stuckTimer = setTimeout(() => {
+      onStuck?.(backend, stuckAfterMs)
+      log(
+        `[bootstrap] still waiting for first-run setup choice after ${Math.round(stuckAfterMs / 1000)}s ` +
+          `(platform=${backend?.platform || 'unknown'})`
+      )
+    }, stuckAfterMs)
+
+    if (typeof stuckTimer.unref === 'function') {
+      stuckTimer.unref()
+    }
+  }
+
+  const shouldGate = (backend?: FirstRunSetupBackend | null) =>
+    Boolean(backend && backend.kind === 'bootstrap-needed' && !localBootstrapConfirmed)
+
+  const wait = async (backend?: FirstRunSetupBackend | null) => {
+    if (!shouldGate(backend)) {
+      return 'continue-local' as const
+    }
+
+    if (waiter) {
+      return waiter.promise
+    }
+
+    promptChoice?.(backend)
+    armStuckTimer(backend)
+
+    let resolveWaiter: (decision: FirstRunSetupDecision) => void = () => {}
+
+    const promise = new Promise<FirstRunSetupDecision>(resolve => {
+      resolveWaiter = resolve
+    })
+
+    waiter = { promise, resolve: resolveWaiter }
+
+    return promise
+  }
+
+  const settleWaiter = (decision: FirstRunSetupDecision) => {
+    clearStuckTimer()
+
+    if (!waiter) {
+      return false
+    }
+
+    const activeWaiter = waiter
+    waiter = null
+    activeWaiter.resolve(decision)
+
+    return true
+  }
+
+  const continueLocal = () => {
+    localBootstrapConfirmed = true
+    settleWaiter('continue-local')
+  }
+
+  const resetForRetry = () => {
+    // Reset paths are followed by a renderer reload / fresh startHermes() call.
+    // Settle the old boot explicitly so it cannot fall through into local
+    // bootstrap and cannot leak a forever-pending connection promise.
+    settleWaiter('reset')
+  }
+
+  const resetForRepair = () => {
+    resetForRetry()
+    localBootstrapConfirmed = false
+  }
+
+  const abandonForRemoteApply = () => {
+    // Resume the gated startHermes() with an explicit remote decision. The
+    // caller re-resolves the newly-persisted remote config instead of falling
+    // through into local bootstrap or leaking the original connection promise.
+    const resumedWaiter = settleWaiter('remote-applied')
+
+    if (!resumedWaiter) {
+      return false
+    }
+
+    localBootstrapConfirmed = false
+    hideChoice?.()
+
+    return true
+  }
+
+  const isLocalBootstrapConfirmed = () => localBootstrapConfirmed
+  const hasWaiter = () => Boolean(waiter)
+
+  return {
+    abandonForRemoteApply,
+    continueLocal,
+    hasWaiter,
+    isLocalBootstrapConfirmed,
+    resetForRepair,
+    resetForRetry,
+    shouldGate,
+    wait
+  }
+}
diff --git a/apps/desktop/electron/first-run-setup-main-process.test.ts b/apps/desktop/electron/first-run-setup-main-process.test.ts
new file mode 100644
index 00000000000..1dc1b920ef6
--- /dev/null
+++ b/apps/desktop/electron/first-run-setup-main-process.test.ts
@@ -0,0 +1,119 @@
+import assert from 'node:assert/strict'
+
+import { test, vi } from 'vitest'
+
+import { applyConnectionChange } from './connection-apply'
+import { createFirstRunSetupGate } from './first-run-setup-gate'
+import { runPrimaryBackendStartup } from './primary-backend-startup'
+import { rehomePrimaryConnection } from './primary-connection-rehome'
+
+test('a first-run bootstrap-needed remote apply connects without ensuring or bootstrapping locally', async () => {
+  const gate = createFirstRunSetupGate({ stuckAfterMs: 0 })
+
+  const bootstrapBackend = {
+    activeRoot: '/tmp/hermes-home/hermes-agent',
+    kind: 'bootstrap-needed',
+    platform: 'linux'
+  }
+
+  const candidateRemote = {
+    authMode: 'token',
+    baseUrl: 'https://gateway.example.com/hermes',
+    source: 'settings',
+    token: 'secret',
+    wsUrl: 'wss://gateway.example.com/hermes/api/ws?token=secret'
+  }
+
+  let savedRemote: typeof candidateRemote | null = null
+
+  const resolveRemote = vi.fn(async () => savedRemote)
+  const connectRemote = vi.fn(async remote => ({ ...remote, mode: 'remote' as const }))
+  const runBootstrap = vi.fn()
+
+  const ensureLocalRuntime = vi.fn(async backend => {
+    await runBootstrap()
+
+    return { ...backend, command: 'hermes' }
+  })
+
+  const teardownPrimaryBackend = vi.fn(async () => {})
+  const cancelSshBootstrap = vi.fn(async () => {})
+  const teardownSsh = vi.fn(async () => {})
+  const clearLocalBootstrapFailure = vi.fn()
+  const notifyConnectionApplied = vi.fn()
+  const waitForLocalStart = vi.fn(async () => {})
+  const prepareLocalBackend = vi.fn(async () => bootstrapBackend)
+
+  const pendingConnection = runPrimaryBackendStartup({
+    connectRemote,
+    ensureLocalRuntime,
+    prepareLocalBackend,
+    resolveRemote,
+    waitForDecision: gate.wait,
+    waitForLocalStart
+  })
+
+  await vi.waitFor(() => assert.equal(gate.hasWaiter(), true))
+
+  // Mirrors the IPC handler's production ordering: persist the tested config,
+  // then re-home. The pending start must re-resolve this saved value.
+  savedRemote = candidateRemote
+
+  await applyConnectionChange({
+    cancelAndWait: cancelSshBootstrap,
+    isPrimary: true,
+    rehomePrimary: () =>
+      rehomePrimaryConnection({
+        clearLocalBootstrapFailure,
+        mode: 'remote',
+        notifyConnectionApplied,
+        resumeFirstRunRemote: gate.abandonForRemoteApply,
+        teardownPrimaryBackend
+      }),
+    scope: '',
+    sendApplied: notifyConnectionApplied,
+    stopPool: vi.fn(),
+    teardownPrimary: teardownPrimaryBackend,
+    teardownSsh
+  })
+
+  assert.deepEqual(await pendingConnection, {
+    kind: 'remote',
+    connection: { ...candidateRemote, mode: 'remote' }
+  })
+  assert.deepEqual(resolveRemote.mock.calls, [[], []])
+  assert.deepEqual(connectRemote.mock.calls, [[candidateRemote]])
+  assert.deepEqual(waitForLocalStart.mock.calls, [[]])
+  assert.deepEqual(prepareLocalBackend.mock.calls, [[]])
+  assert.equal(ensureLocalRuntime.mock.calls.length, 0)
+  assert.equal(runBootstrap.mock.calls.length, 0)
+  assert.deepEqual(cancelSshBootstrap.mock.calls, [['']])
+  assert.deepEqual(teardownSsh.mock.calls, [['']])
+  assert.equal(teardownPrimaryBackend.mock.calls.length, 0)
+  assert.equal(clearLocalBootstrapFailure.mock.calls.length, 1)
+  assert.equal(notifyConnectionApplied.mock.calls.length, 0)
+})
+
+test('a primary apply without an active first-run gate tears down before reconnect notification', async () => {
+  const order: string[] = []
+  const clearLocalBootstrapFailure = vi.fn(() => order.push('clear-failure'))
+
+  const teardownPrimaryBackend = vi.fn(async () => {
+    order.push('teardown')
+  })
+
+  const notifyConnectionApplied = vi.fn(() => order.push('notify'))
+
+  assert.deepEqual(
+    await rehomePrimaryConnection({
+      clearLocalBootstrapFailure,
+      mode: 'remote',
+      notifyConnectionApplied,
+      resumeFirstRunRemote: () => false,
+      teardownPrimaryBackend
+    }),
+    { resumedFirstRunRemote: false }
+  )
+  assert.deepEqual(teardownPrimaryBackend.mock.calls, [[{ soft: true }]])
+  assert.deepEqual(order, ['clear-failure', 'teardown', 'notify'])
+})
diff --git a/apps/desktop/electron/main.ts b/apps/desktop/electron/main.ts
index 3856cd2abc2..f967aa24c3b 100644
--- a/apps/desktop/electron/main.ts
+++ b/apps/desktop/electron/main.ts
@@ -34,9 +34,10 @@ import { stopBackendChild as stopBackendChildImpl } from './backend-child'
 import { dashboardFallbackArgs, sourceDeclaresServe } from './backend-command'
 import { createBackendConnectionState } from './backend-connection-state'
 import { buildDesktopBackendEnv, normalizeHermesHomeRoot } from './backend-env'
+import { isReauthRequiredError, waitForHermesReady } from './backend-health'
 import { canImportHermesCli, shouldTrustHermesOverride, verifyHermesCli } from './backend-probes'
 import { waitForDashboardPortAnnouncement } from './backend-ready'
-import { shouldLatchBackendStartFailure } from './backend-start-failure'
+import { shouldLatchBackendStartFailure, shouldLatchRemoteReauthFailure } from './backend-start-failure'
 import { detectRemoteDisplay, isWindowsBinaryPathInWsl, isWslEnvironment } from './bootstrap-platform'
 import { runBootstrap } from './bootstrap-runner'
 import { applyConnectionChange, resolveTerminalConnection } from './connection-apply'
@@ -78,6 +79,8 @@ import {
 } from './desktop-uninstall'
 import { installEmbedReferer } from './embed-referer'
 import { createEventDeduper } from './event-dedupe'
+import { findGitBash as _findGitBash } from './find-git-bash'
+import { createFirstRunSetupGate } from './first-run-setup-gate'
 import { readDirForIpc } from './fs-read-dir'
 import { probeGatewayWebSocket } from './gateway-ws-probe'
 import { scanGitRepos } from './git-repo-scan'
@@ -116,7 +119,13 @@ import {
 } from './hardening'
 import { createLinkTitleWindow, guardLinkTitleSession, readLinkTitleWindowTitle } from './link-title-window'
 import { ensureMainWindow } from './main-window-lifecycle'
-import { oauthSessionIsLive, resolveJsonBody, resolveOauthRestAuth } from './native-auth-decisions'
+import {
+  oauthGuardMayHardFail,
+  oauthSessionIsLive,
+  resolveJsonBody,
+  resolveOauthRestAuth,
+  resolveReadinessProbeAuth
+} from './native-auth-decisions'
 import {
   nativeRefreshUrl,
   type NativeTokenSet,
@@ -127,6 +136,8 @@ import {
 import { runNativeLogin } from './native-oauth-login'
 import { serializeJsonBody, setJsonRequestHeaders } from './oauth-net-request'
 import { createKeepAwake } from './power-save'
+import { FirstRunSetupResetError, runPrimaryBackendStartup } from './primary-backend-startup'
+import { rehomePrimaryConnection } from './primary-connection-rehome'
 import { decideProfileDeleteAction, profileNameFromDeleteRequest, resolveRouteProfile } from './profile-delete-routing'
 import * as remoteLifecycle from './remote-lifecycle'
 import { RemoteLivenessTracker, RemoteRevalidationCoordinator, revalidateRemoteConnection } from './remote-liveness'
@@ -1011,6 +1022,13 @@ let bootstrapFailure = null
 // Latched non-bootstrap backend spawn failure — stops getConnection() from
 // respawning hermes serve backend children in a tight loop while boot is broken.
 let backendStartFailure = null
+// Latched CONFIRMED remote reauth failure. Remote failures deliberately do not
+// latch via backendStartFailure (they're usually transient and must stay
+// retryable), but a rejected session cannot self-heal — and the non-latching
+// path actively breaks recovery: each retry re-emits running:true and hides
+// the boot-failure overlay, so the "Sign in" button flickers away before it
+// can be clicked. Cleared on every recovery path and on a confirmed sign-in.
+let remoteReauthFailure = null
 // Active first-launch install, so the renderer's Cancel button (and app quit)
 // can abort the in-flight install.sh/ps1 instead of leaving it running.
 let bootstrapAbortController = null
@@ -1398,13 +1416,17 @@ let bootstrapState = {
   log: [],
   startedAt: null,
   completedAt: null,
+  setupChoice: null,
   unsupportedPlatform: null
 }
 
+let firstRunSetupGate = null
+
 function broadcastBootstrapEvent(ev) {
   if (ev.type === 'manifest') {
     bootstrapState.manifest = ev
     bootstrapState.active = true
+    bootstrapState.setupChoice = null
     bootstrapState.startedAt = bootstrapState.startedAt || Date.now()
     bootstrapState.stages = {}
 
@@ -1432,14 +1454,30 @@ function broadcastBootstrapEvent(ev) {
   } else if (ev.type === 'failed') {
     bootstrapState.active = false
     bootstrapState.error = ev.error || 'unknown error'
+    bootstrapState.setupChoice = null
   } else if (ev.type === 'unsupported-platform') {
     bootstrapState.active = false
+    bootstrapState.setupChoice = null
     bootstrapState.unsupportedPlatform = {
       platform: ev.platform,
       activeRoot: ev.activeRoot,
       installCommand: ev.installCommand,
       docsUrl: ev.docsUrl
     }
+  } else if (ev.type === 'setup-choice') {
+    bootstrapState.active = false
+    bootstrapState.error = null
+    bootstrapState.manifest = null
+    bootstrapState.stages = {}
+    bootstrapState.setupChoice = ev.active
+      ? {
+          platform: ev.platform,
+          activeRoot: ev.activeRoot
+        }
+      : null
+    bootstrapState.unsupportedPlatform = null
+  } else if (ev.type === 'dismissed') {
+    resetBootstrapSnapshot()
   }
 
   if (!mainWindow || mainWindow.isDestroyed()) {
@@ -1459,6 +1497,100 @@ function getBootstrapState() {
   return bootstrapState
 }
 
+function resetBootstrapSnapshot() {
+  bootstrapState = {
+    active: false,
+    manifest: null,
+    stages: {},
+    error: null,
+    log: [],
+    startedAt: null,
+    completedAt: null,
+    setupChoice: null,
+    unsupportedPlatform: null
+  }
+}
+
+function promptFirstRunSetupChoice(backend) {
+  broadcastBootstrapEvent({
+    type: 'setup-choice',
+    active: true,
+    platform: backend.platform || process.platform,
+    activeRoot: backend.activeRoot || ACTIVE_HERMES_ROOT
+  })
+}
+
+function hideFirstRunSetupChoice() {
+  if (bootstrapState.setupChoice) {
+    broadcastBootstrapEvent({ type: 'setup-choice', active: false })
+  }
+}
+
+function getFirstRunSetupGate() {
+  if (!firstRunSetupGate) {
+    firstRunSetupGate = createFirstRunSetupGate({
+      hideChoice: hideFirstRunSetupChoice,
+      log: rememberLog,
+      onStuck: (_backend, stuckAfterMs) => {
+        updateBootProgress(
+          {
+            error: null,
+            message: `Still waiting for first-run setup choice after ${Math.round(stuckAfterMs / 1000)} seconds`,
+            phase: 'bootstrap.choice',
+            progress: 12,
+            running: true
+          },
+          { allowDecrease: true }
+        )
+      },
+      promptChoice: promptFirstRunSetupChoice
+    })
+  }
+
+  return firstRunSetupGate
+}
+
+async function waitForFirstRunSetupChoice(backend) {
+  const gate = getFirstRunSetupGate()
+
+  if (!gate.shouldGate(backend)) {
+    return 'continue-local'
+  }
+
+  updateBootProgress(
+    {
+      error: null,
+      message: 'Waiting for first-run setup choice',
+      phase: 'bootstrap.choice',
+      progress: 12,
+      running: true
+    },
+    { allowDecrease: true }
+  )
+
+  return gate.wait(backend)
+}
+
+function continueFirstRunLocalBootstrap() {
+  getFirstRunSetupGate().continueLocal()
+}
+
+function abandonFirstRunSetupChoiceForRemoteApply() {
+  const gate = getFirstRunSetupGate()
+
+  if (!gate.hasWaiter()) {
+    return false
+  }
+
+  const resumedGatedConnection = gate.abandonForRemoteApply()
+
+  if (resumedGatedConnection) {
+    broadcastBootstrapEvent({ type: 'dismissed' })
+  }
+
+  return resumedGatedConnection
+}
+
 function updateBootProgress(update, options: { allowDecrease?: boolean } = {}) {
   const nextProgressRaw =
     typeof update.progress === 'number' ? clampBootProgress(update.progress) : bootProgressState.progress
@@ -1915,48 +2047,16 @@ function findSystemPython() {
   return null
 }
 
-// findGitBash — locate bash.exe on Windows. Hermes' terminal tool requires
-// bash (POSIX shell), and on Windows that's almost always Git for Windows'
-// bundled Git Bash. We check the same set of locations tools/environments/
-// local.py:_find_bash() checks at runtime, so a positive result here means
-// the agent will be able to start a terminal too.
-//
-// On non-Windows hosts bash is part of the OS and this just returns the
-// first bash on PATH.
+// findGitBash — locate bash.exe on Windows. Resolves HERMES_GIT_BASH_PATH
+// first (mirrors tools/environments/local.py:_find_bash), then PortableGit,
+// standard install locations, and finally PATH.
 function findGitBash() {
-  if (!IS_WINDOWS) {
-    return findOnPath('bash')
-  }
-
-  // install.ps1 drops PortableGit at %LOCALAPPDATA%\hermes\git\... — checked
-  // first so users who installed via install.ps1 are detected before we
-  // start probing system-wide locations.
-  const localAppData = process.env.LOCALAPPDATA || ''
-  const candidates = []
-
-  if (localAppData) {
-    candidates.push(path.join(localAppData, 'hermes', 'git', 'bin', 'bash.exe'))
-    candidates.push(path.join(localAppData, 'hermes', 'git', 'usr', 'bin', 'bash.exe'))
-  }
-
-  // Standard Git for Windows install locations.
-  candidates.push(path.join(process.env['ProgramFiles'] || 'C:\\Program Files', 'Git', 'bin', 'bash.exe'))
-  candidates.push(path.join(process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)', 'Git', 'bin', 'bash.exe'))
-
-  if (localAppData) {
-    candidates.push(path.join(localAppData, 'Programs', 'Git', 'bin', 'bash.exe'))
-  }
-
-  for (const candidate of candidates) {
-    if (fileExists(candidate)) {
-      return candidate
-    }
-  }
-
-  // Last resort — bash on PATH (covers WSL bash, MSYS2, custom installs).
-  // On WSL hosts findOnPath itself filters out Windows-binary paths via
-  // isWindowsBinaryPathInWsl, so we won't hand back a wsl.exe shim either.
-  return findOnPath('bash')
+  return _findGitBash({
+    isWindows: IS_WINDOWS,
+    env: process.env,
+    fileExists,
+    findOnPath
+  })
 }
 
 function getVenvPython(venvRoot) {
@@ -2686,6 +2786,11 @@ async function applyUpdates(opts = {}) {
 
     const venvBin = path.join(updateRoot, 'venv', IS_WINDOWS ? 'Scripts' : 'bin')
 
+    // ── Pre-flight state.db integrity guard (#68474) ─────────────────
+    // Emergency backup and header verification before the update touches
+    // anything.  Runs while the backend is still alive.
+    preflightStateDb(HERMES_HOME, rememberLog)
+
     // Stop our own backend(s) and wait for the venv shim to unlock BEFORE we
     // spawn the updater. Without this the updater races a still-locked
     // hermes.exe (held by the backend child / its grandchildren) and the update
@@ -2883,6 +2988,92 @@ function runningAppBundle() {
   return dir.endsWith('.app') ? dir : null
 }
 
+// ── Pre-flight state.db integrity guard (#68474) ─────────────────────
+// Take an emergency snapshot of state.db and verify the live copy is
+// intact before any update process mutates the install.  Runs in the
+// desktop Electron process itself, before the backend is killed and
+// before the updater is spawned — a separate safety net from the
+// Python-level pre-update snapshot inside `hermes update`.
+function preflightStateDb(hermesHome, rememberLog) {
+  const stateDbPath = path.join(hermesHome, 'state.db')
+
+  if (!fileExists(stateDbPath)) {
+    rememberLog('[updates] state.db pre-flight: not found (fresh install?)')
+
+    return
+  }
+
+  try {
+    const stat = fs.statSync(stateDbPath)
+
+    if (stat.size > 100) {
+      const fd = fs.openSync(stateDbPath, 'r')
+      const header = Buffer.alloc(16)
+
+      fs.readSync(fd, header, 0, 16, 0)
+      fs.closeSync(fd)
+
+      const expectedHeader = Buffer.from('SQLite format 3\0')
+      const headerOk = header.equals(expectedHeader)
+
+      rememberLog(
+        `[updates] state.db pre-flight: size=${stat.size}, ` +
+          `headerOk=${headerOk}, headerHex=${header.toString('hex')}`
+      )
+
+      if (!headerOk) {
+        rememberLog(
+          '[updates] state.db header is INVALID before update — ' +
+            'this indicates pre-existing corruption or a concurrent write issue'
+        )
+      }
+
+      // Emergency timestamped backup, separate from the Python-level snapshot.
+      const ts = new Date().toISOString().replace(/[:.]/g, '-')
+
+      const emergencyPath = path.join(hermesHome, `state.db.pre-update-emergency-${ts}.bak`)
+
+      try {
+        fs.copyFileSync(stateDbPath, emergencyPath)
+        const emergStat = fs.statSync(emergencyPath)
+
+        rememberLog(`[updates] emergency state.db backup: ${emergencyPath} ` + `(${emergStat.size} bytes)`)
+
+        // Prune to the 2 most recent emergency backups.
+        try {
+          const homeDir = fs.readdirSync(hermesHome)
+
+          const backups = homeDir
+            .filter(
+              f =>
+                f.startsWith('state.db.pre-update-emergency-') &&
+                f.endsWith('.bak') &&
+                f !== path.basename(emergencyPath)
+            )
+            .sort()
+            .reverse()
+
+          for (const old of backups.slice(2)) {
+            try {
+              fs.unlinkSync(path.join(hermesHome, old))
+            } catch {
+              void 0
+            }
+          }
+        } catch {
+          void 0
+        }
+      } catch (copyErr) {
+        rememberLog(`[updates] emergency state.db backup failed: ${copyErr.message}`)
+      }
+    } else {
+      rememberLog(`[updates] state.db too small (${stat.size} bytes) for a valid SQLite database`)
+    }
+  } catch (statErr) {
+    rememberLog(`[updates] could not stat state.db before update: ${statErr.message}`)
+  }
+}
+
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`
 }
@@ -2901,9 +3092,12 @@ async function applyUpdatesPosixInApp(opts: any) {
     return { ok: true, manual: true, command: 'hermes update', hermesRoot: updateRoot }
   }
 
+  // ── Pre-flight state.db integrity guard (#68474) ──
+  preflightStateDb(HERMES_HOME, rememberLog)
+
   // Put the Hermes-managed Node and the venv on PATH so `hermes desktop`'s
   // npm build can find them on a machine with no system Node. Windows portable
-  // Node lives directly under %LOCALAPPDATA%\hermes\node, not node\bin.
+  // Node lives directly under %LOCALAPPDATA%\\hermes\\node, not node\\bin.
   // PYTHONUNBUFFERED: `hermes update` writes to a pipe here, so CPython
   // block-buffers stdout and long quiet steps (the pre-update backup can zip
   // multi-GB archives for minutes) stream nothing to the progress UI — users
@@ -4634,40 +4828,88 @@ function closePreviewWatchers() {
   }
 }
 
-async function waitForHermes(baseUrl, token, signal?) {
-  const deadline = Date.now() + 45_000
-  let lastError = null
+// Best-effort read of a gateway's advertised auth providers, cached per base
+// URL for the life of the process. Used by the oauth pre-flight guard to tell
+// a password-provider gateway (which cannot satisfy the bearer/cookie checks
+// by design) from a real OAuth one. Any failure returns [] so callers keep the
+// strict guard — backends predating /api/auth/providers are unaffected.
+const gatewayAuthProvidersCache = new Map<string, any[]>()
 
-  while (Date.now() < deadline) {
-    if (signal?.aborted) {
-      const error: any = new Error('SSH bootstrap was superseded by newer connection settings.')
-      error.kind = 'superseded'
-      throw error
+async function gatewayAuthProviders(baseUrl) {
+  const cached = gatewayAuthProvidersCache.get(baseUrl)
+
+  if (cached) {
+    return cached
+  }
+
+  let providers = []
+
+  try {
+    const body = (await fetchPublicJson(`${baseUrl}/api/auth/providers`, { timeoutMs: 8_000 })) as any
+
+    if (Array.isArray(body?.providers)) {
+      providers = body.providers
+        .filter(p => p && typeof p === 'object')
+        .map(p => ({ name: String(p.name || ''), supportsPassword: Boolean(p.supports_password) }))
+        .filter(p => p.name)
     }
+  } catch {
+    // Optional metadata — an unreadable list keeps the strict guard.
+  }
 
-    try {
-      await fetchJson(`${baseUrl}/api/status`, token)
+  gatewayAuthProvidersCache.set(baseUrl, providers)
 
-      return
-    } catch (error) {
-      lastError = error
-      await new Promise((resolve, reject) => {
-        const timer = setTimeout(resolve, 500)
-        signal?.addEventListener(
-          'abort',
-          () => {
-            clearTimeout(timer)
-            const aborted: any = new Error('SSH bootstrap was superseded by newer connection settings.')
-            aborted.kind = 'superseded'
-            reject(aborted)
-          },
-          { once: true }
-        )
-      })
+  return providers
+}
+
+// Build the readiness probe for a connection's auth mode. A gated gateway
+// must be probed with the SAME credentials the rest of the connection uses:
+// an anonymous probe 401s forever against a live session, and it can never
+// see the 404 that identifies a backend predating /api/health (the auth gate
+// answers before the SPA catch-all). `probeIsCredentialed` tells
+// waitForHermesReady how to read a 401 — rejected session vs gated route.
+async function buildReadinessHealthProbe(baseUrl, authMode, token) {
+  const nativeAt = authMode === 'oauth' ? await ensureNativeAccessToken(baseUrl).catch(() => null) : null
+  const probeAuth = resolveReadinessProbeAuth(authMode, nativeAt, token)
+
+  if (probeAuth.kind === 'bearer') {
+    return {
+      // fetchJson takes the bearer via `options.bearer` — a raw `headers`
+      // option is ignored, so passing one here would silently probe
+      // uncredentialed and reintroduce the 401 loop.
+      probeHealth: (url, options: any = {}) => fetchJson(url, null, { ...options, bearer: probeAuth.token }),
+      probeIsCredentialed: true
     }
   }
 
-  throw new Error(`Hermes backend did not become ready: ${lastError?.message || 'timeout'}`)
+  if (probeAuth.kind === 'cookie') {
+    return {
+      probeHealth: (url, options: any = {}) => fetchJsonViaOauthSession(url, options),
+      probeIsCredentialed: true
+    }
+  }
+
+  if (probeAuth.kind === 'token' && probeAuth.token) {
+    return {
+      probeHealth: (url, options: any = {}) => fetchJson(url, probeAuth.token, options),
+      probeIsCredentialed: true
+    }
+  }
+
+  return { probeHealth: fetchPublicJson, probeIsCredentialed: false }
+}
+
+async function waitForHermes(baseUrl, token, signal?, authMode?) {
+  const { probeHealth, probeIsCredentialed } = await buildReadinessHealthProbe(baseUrl, authMode, token)
+
+  return waitForHermesReady(baseUrl, {
+    token,
+    signal,
+    fetchPublicJson,
+    fetchJson: probeIsCredentialed ? (url, _token, options) => probeHealth(url, options) : fetchJson,
+    probeHealth,
+    probeIsCredentialed
+  })
 }
 
 function getWindowButtonPosition() {
@@ -6668,7 +6910,10 @@ async function buildRemoteConnection(
     // here would reject a freshly-completed native sign-in and loop the UI back
     // into "not signed in" even though mintGatewayWsTicket would succeed with
     // the stored bearer.
-    if (!oauthSessionIsLive(hasNativeSession(baseUrl), await hasLiveOauthSession(baseUrl))) {
+    if (
+      !oauthSessionIsLive(hasNativeSession(baseUrl), await hasLiveOauthSession(baseUrl)) &&
+      oauthGuardMayHardFail(await gatewayAuthProviders(baseUrl))
+    ) {
       const err = new Error(
         'Remote Hermes gateway uses OAuth, but you are not signed in. ' +
           'Open Settings → Gateway and click "Sign in", or switch back to Local.'
@@ -6909,7 +7154,7 @@ async function bootstrapSshConnectionInner(profile, sshConfig, reuseToken, sourc
       forward: (localPort, remotePort) => ssh.forward(localPort, remotePort),
       cancelForward: (localPort, remotePort) => ssh.cancelForward(localPort, remotePort),
       pickLocalPort,
-      waitForHermes: (baseUrl, token) => waitForHermes(baseUrl, token, lease.signal),
+      waitForHermes: (baseUrl, token) => waitForHermes(baseUrl, token, lease.signal, 'token'),
       probeReuseProof: sshProbeReuseProof,
       adoptServedToken: adoptServedDashboardToken,
       rememberLog: sshRememberLog,
@@ -7382,6 +7627,7 @@ function stopBackendChild(child) {
 // switch / crash recovery), which still resets boot progress + reloads.
 function resetHermesConnection({ soft = false } = {}) {
   backendStartFailure = null
+  remoteReauthFailure = null
   remoteLiveness.clear()
   const hermesProcess = backendConnectionState.invalidate()
   stopBackendChild(hermesProcess)
@@ -7582,7 +7828,7 @@ async function spawnPoolBackend(profile, entry) {
   const remote = await resolveRemoteBackend(profile)
 
   if (remote) {
-    await waitForHermes(remote.baseUrl, remote.token)
+    await waitForHermes(remote.baseUrl, remote.token, undefined, remote.authMode)
 
     return {
       ...remote,
@@ -7774,6 +8020,13 @@ async function startHermes() {
     throw backendStartFailure
   }
 
+  // A confirmed remote reauth rejection is terminal until the user signs in.
+  // Short-circuiting here keeps the boot-failure overlay latched and its
+  // "Sign in" button clickable, instead of re-driving boot on every retry.
+  if (remoteReauthFailure) {
+    throw remoteReauthFailure
+  }
+
   // E2E: simulate a boot failure without breaking the real backend. The boot
   // progresses a few steps, then fails with the given error message.
   if (BOOT_FAKE_ERROR) {
@@ -7798,16 +8051,9 @@ async function startHermes() {
   let attemptedRemote = primaryBackendIsRemote()
 
   const connectionPromise = (async () => {
-    await advanceBootProgress('backend.resolve', 'Resolving Hermes backend', 8)
-    // Resolve for the desktop's primary profile so a per-profile remote
-    // override on the active profile is honored (falls back to env / global).
-    // Re-read once resolved so the classification tracks the value actually used.
-    attemptedRemote = primaryBackendIsRemote()
-    const remote = await resolveRemoteBackend(primaryProfileKey())
-
-    if (remote) {
+    const connectRemote = async remote => {
       await advanceBootProgress('backend.remote', `Connecting to remote Hermes backend at ${remote.baseUrl}`, 24)
-      await waitForHermes(remote.baseUrl, remote.token)
+      await waitForHermes(remote.baseUrl, remote.token, undefined, remote.authMode)
       updateBootProgress({
         phase: 'backend.ready',
         message: 'Remote Hermes backend is ready',
@@ -7831,14 +8077,9 @@ async function startHermes() {
       }
     }
 
-    // Mutual exclusion with an in-app update (#50238). If this instance was
-    // relaunched while the Tauri updater is still applying an update, spawning
-    // a local backend now re-locks the venv shim and gets killed by the
-    // updater's straggler cleanup — looping. Park until the update finishes (or
-    // is detected stale), THEN start the backend. Local backends only; remote
-    // connections returned above and never touch the install tree.
-    await waitForUpdateToFinish()
-
+    await advanceBootProgress('backend.resolve', 'Resolving Hermes backend', 8)
+    // Resolve for the desktop's primary profile so a per-profile remote
+    // override on the active profile is honored (falls back to env / global).
     const token = crypto.randomBytes(32).toString('base64url')
     // --port 0: the OS assigns an ephemeral port; the child announces it on stdout.
     const backendArgs = ['serve', '--host', '127.0.0.1', '--port', '0']
@@ -7853,8 +8094,32 @@ async function startHermes() {
       backendArgs.unshift('--profile', activeProfile)
     }
 
-    await advanceBootProgress('backend.runtime', 'Resolving Hermes runtime', 28)
-    const backend = await ensureRuntime(resolveHermesBackend(backendArgs))
+    const setup = await runPrimaryBackendStartup({
+      connectRemote,
+      ensureLocalRuntime: ensureRuntime,
+      prepareLocalBackend: async () => {
+        await advanceBootProgress('backend.runtime', 'Resolving Hermes runtime', 28)
+
+        return resolveHermesBackend(backendArgs)
+      },
+      resolveRemote: () => {
+        // Classify immediately before each throwing resolve. This callback runs
+        // both for an already-saved remote and after first-run remote Apply.
+        attemptedRemote = primaryBackendIsRemote()
+
+        return resolveRemoteBackend(primaryProfileKey())
+      },
+      waitForDecision: waitForFirstRunSetupChoice,
+      // Mutual exclusion with an in-app update (#50238). Remote connections
+      // return before this waiter; local starts park until the updater exits.
+      waitForLocalStart: waitForUpdateToFinish
+    })
+
+    if (setup.kind === 'remote') {
+      return setup.connection
+    }
+
+    const backend = setup.backend
     // Route old runtimes (no `serve`) through the legacy `dashboard --no-open`.
     backend.args = getBackendArgsForRuntime(backend)
     const hermesCwd = resolveHermesCwd()
@@ -8010,6 +8275,10 @@ async function startHermes() {
       throw error
     }
 
+    if (error instanceof FirstRunSetupResetError) {
+      throw error
+    }
+
     const message = error instanceof Error ? error.message : String(error)
 
     // Only latch LOCAL boot failures. A remote failure (lapsed session / mint
@@ -8021,6 +8290,12 @@ async function startHermes() {
       backendStartFailure = error instanceof Error ? error : new Error(message)
     }
 
+    // A confirmed reauth rejection latches separately: it can't self-heal, and
+    // leaving it unlatched hides the overlay's "Sign in" button on every retry.
+    if (shouldLatchRemoteReauthFailure({ attemptedRemote, isReauth: isReauthRequiredError(error) })) {
+      remoteReauthFailure = error instanceof Error ? error : new Error(message)
+    }
+
     updateBootProgress(
       {
         error: message,
@@ -8824,16 +9099,9 @@ ipcMain.handle('hermes:bootstrap:reset', async () => {
   await teardownPrimaryBackendAndWait()
   bootstrapFailure = null
   backendStartFailure = null
-  bootstrapState = {
-    active: false,
-    manifest: null,
-    stages: {},
-    error: null,
-    log: [],
-    startedAt: null,
-    completedAt: null,
-    unsupportedPlatform: null
-  }
+  remoteReauthFailure = null
+  getFirstRunSetupGate().resetForRetry()
+  resetBootstrapSnapshot()
 
   return { ok: true }
 })
@@ -8854,10 +9122,18 @@ ipcMain.handle('hermes:bootstrap:repair', async () => {
 
   bootstrapFailure = null
   backendStartFailure = null
+  remoteReauthFailure = null
+  getFirstRunSetupGate().resetForRepair()
   resetHermesConnection()
 
   return { ok: true }
 })
+ipcMain.handle('hermes:bootstrap:continue-local', async () => {
+  rememberLog('[bootstrap] local install selected by renderer; continuing first-launch bootstrap')
+  continueFirstRunLocalBootstrap()
+
+  return { ok: true }
+})
 ipcMain.handle('hermes:bootstrap:cancel', async () => {
   // Renderer's Cancel button during first-launch install. Abort the running
   // install script (SIGTERM via the runner's abortSignal). runBootstrap
@@ -8956,6 +9232,9 @@ ipcMain.handle('hermes:connection-config:oauth-login', async (_event, rawUrl) =>
       })
 
       _storeNativeTokens(baseUrl, tokens)
+      // Confirmed sign-in — release the reauth latch so the next
+      // startHermes() re-dials instead of replaying the stale rejection.
+      remoteReauthFailure = null
 
       return { ok: true, baseUrl, connected: true }
     } catch (error) {
@@ -8972,7 +9251,16 @@ ipcMain.handle('hermes:connection-config:oauth-login', async (_event, rawUrl) =>
   // Legacy embedded-webview cookie flow.
   await openOauthLoginWindow(baseUrl)
 
-  return { ok: true, baseUrl, connected: await hasOauthSessionCookie(baseUrl) }
+  const connected = await hasOauthSessionCookie(baseUrl)
+
+  // Only a CONFIRMED sign-in releases the latch. A cancelled/closed login
+  // window must leave it set, or the overlay's "Sign in" button starts
+  // flickering again on the next retry.
+  if (connected) {
+    remoteReauthFailure = null
+  }
+
+  return { ok: true, baseUrl, connected }
 })
 ipcMain.handle('hermes:connection-config:oauth-logout', async (_event, rawUrl) => {
   const baseUrl = rawUrl ? normalizeRemoteBaseUrl(rawUrl) : ''
@@ -9036,6 +9324,18 @@ ipcMain.handle('hermes:connection-config:apply', async (_event, payload) => {
   await applyConnectionChange({
     cancelAndWait: value => sshBootstrapCoordinator.cancelAndWait(value),
     isPrimary: !key || key === primaryProfileKey(),
+    rehomePrimary: () =>
+      rehomePrimaryConnection({
+        clearLocalBootstrapFailure: () => {
+          // A remote connection bypasses local runtime/bootstrap failures. Clear
+          // the local-install latch so unsupported/failure escape paths can re-home.
+          bootstrapFailure = null
+        },
+        mode: config.mode,
+        notifyConnectionApplied: sendConnectionApplied,
+        resumeFirstRunRemote: abandonFirstRunSetupChoiceForRemoteApply,
+        teardownPrimaryBackend: teardownPrimaryBackendAndWait
+      }),
     scope,
     sendApplied: sendConnectionApplied,
     stopPool: stopPoolBackend,
diff --git a/apps/desktop/electron/native-auth-decisions.test.ts b/apps/desktop/electron/native-auth-decisions.test.ts
index 09f648c8719..d4cfc068cd6 100644
--- a/apps/desktop/electron/native-auth-decisions.test.ts
+++ b/apps/desktop/electron/native-auth-decisions.test.ts
@@ -1,7 +1,7 @@
 /**
- * Regression tests for electron/native-auth-decisions.ts — the three pure
- * decision seams behind the RFC 8252 native-app auth flow, each of which was a
- * real runtime bug that the mocked flow tests could not catch.
+ * Regression tests for electron/native-auth-decisions.ts — the pure decision
+ * seams behind the RFC 8252 native-app auth flow, each of which was a real
+ * runtime bug that the mocked flow tests could not catch.
  *
  * Run via the vitest `electron` project (electron/**\/*.test.ts).
  */
@@ -10,7 +10,13 @@ import assert from 'node:assert/strict'
 
 import { test } from 'vitest'
 
-import { oauthSessionIsLive, resolveJsonBody, resolveOauthRestAuth } from './native-auth-decisions'
+import {
+  oauthGuardMayHardFail,
+  oauthSessionIsLive,
+  resolveJsonBody,
+  resolveOauthRestAuth,
+  resolveReadinessProbeAuth
+} from './native-auth-decisions'
 
 // --- 1. body encoding (guards the double-JSON.stringify 422) ---
 
@@ -66,3 +72,61 @@ test('resolveOauthRestAuth falls back to cookie when there is no native token',
   // Empty string is not a usable bearer — must fall back, not send "Bearer ".
   assert.deepEqual(resolveOauthRestAuth(''), { kind: 'cookie' })
 })
+
+// --- 4. readiness-probe auth (guards the credential-free 401 boot loop) ---
+
+test('resolveReadinessProbeAuth reuses the oauth bearer-vs-cookie choice', () => {
+  assert.deepEqual(resolveReadinessProbeAuth('oauth', 'native-at'), { kind: 'bearer', token: 'native-at' })
+  assert.deepEqual(resolveReadinessProbeAuth('oauth', null), { kind: 'cookie' })
+  assert.deepEqual(resolveReadinessProbeAuth('oauth', ''), { kind: 'cookie' })
+})
+
+test('resolveReadinessProbeAuth sends the session token for a token gateway', () => {
+  assert.deepEqual(resolveReadinessProbeAuth('token', null, 'session-token'), {
+    kind: 'token',
+    token: 'session-token'
+  })
+  assert.deepEqual(resolveReadinessProbeAuth('token', null, null), { kind: 'token', token: null })
+})
+
+test('resolveReadinessProbeAuth stays public for local and unknown modes', () => {
+  // A loopback backend has no gate; sending credentials it never issued is
+  // meaningless, and an unknown mode must not invent a credential.
+  assert.deepEqual(resolveReadinessProbeAuth('local', 'native-at', 'session-token'), { kind: 'public' })
+  assert.deepEqual(resolveReadinessProbeAuth(undefined, 'native-at', 'session-token'), { kind: 'public' })
+  assert.deepEqual(resolveReadinessProbeAuth('something-new', null, null), { kind: 'public' })
+})
+
+// --- 5. oauth guard vs password gateways (guards the false "not signed in") ---
+
+test('oauthGuardMayHardFail is false only when EVERY provider is password-based', () => {
+  assert.equal(oauthGuardMayHardFail([{ name: 'basic', supportsPassword: true }]), false)
+  assert.equal(
+    oauthGuardMayHardFail([
+      { name: 'basic', supportsPassword: true },
+      { name: 'ldap', supportsPassword: true }
+    ]),
+    false
+  )
+})
+
+test('oauthGuardMayHardFail keeps the strict guard for oauth and mixed deployments', () => {
+  assert.equal(oauthGuardMayHardFail([{ name: 'nous', supportsPassword: false }]), true)
+  assert.equal(
+    oauthGuardMayHardFail([
+      { name: 'nous', supportsPassword: false },
+      { name: 'basic', supportsPassword: true }
+    ]),
+    true
+  )
+})
+
+test('oauthGuardMayHardFail keeps the strict guard when the list is unusable', () => {
+  // Backends predating /api/auth/providers, or an unreachable probe, must not
+  // silently weaken the guard.
+  assert.equal(oauthGuardMayHardFail([]), true)
+  assert.equal(oauthGuardMayHardFail(null), true)
+  assert.equal(oauthGuardMayHardFail(undefined), true)
+  assert.equal(oauthGuardMayHardFail('nonsense' as any), true)
+  assert.equal(oauthGuardMayHardFail([{ supportsPassword: true }]), true)
+})
diff --git a/apps/desktop/electron/native-auth-decisions.ts b/apps/desktop/electron/native-auth-decisions.ts
index d76746f669a..c0978c3ecdd 100644
--- a/apps/desktop/electron/native-auth-decisions.ts
+++ b/apps/desktop/electron/native-auth-decisions.ts
@@ -21,7 +21,17 @@
  *      native bearer when present, else the cookie partition. Cookie-only
  *      routing returns 401 no_cookie for a cookieless native session.
  *
- * All three are trivial once named; the value is the test that pins the
+ *   4. resolveReadinessProbeAuth — the boot readiness probe must authenticate
+ *      the same way the rest of the connection does. A credential-free probe
+ *      against a gated gateway 401s forever; worse, it cannot tell a missing
+ *      route from a rejected session (see backend-health.ts).
+ *
+ *   5. oauthGuardMayHardFail — `auth_required: true` means "this gateway is
+ *      gated", NOT "this gateway speaks OAuth". A password-provider gateway
+ *      can satisfy neither the native-bearer nor the OAuth-partition-cookie
+ *      check by design, so the pre-flight guard must not hard-fail it.
+ *
+ * All five are trivial once named; the value is the test that pins the
  * contract so the god-file call sites can't drift back to the buggy shape.
  */
 
@@ -60,3 +70,75 @@ export function resolveOauthRestAuth(nativeAccessToken: string | null | undefine
 
   return { kind: 'cookie' }
 }
+
+export type ReadinessProbeAuth = OauthRestAuth | { kind: 'token'; token: string | null } | { kind: 'public' }
+
+/**
+ * Decide how the boot readiness probe authenticates.
+ *
+ * The probe must present the SAME credentials the rest of the connection
+ * will use. A credential-free probe against a gated gateway 401s until the
+ * boot deadline even though the session is perfectly valid — and because the
+ * dashboard auth gate runs ahead of the SPA catch-all, an unknown `/api/*`
+ * path answers 401 rather than 404, so the probe also cannot detect a backend
+ * that predates `/api/health`. Sending credentials is what lets a missing
+ * route surface as a real 404 (see `isMissingHealthEndpointError`).
+ *
+ * `oauth` reuses `resolveOauthRestAuth` so the probe and every other oauth
+ * REST call make the identical bearer-vs-cookie choice. `token` presents the
+ * connection's session token. `local` (and anything unrecognized) stays
+ * public: a loopback backend has no gate, and sending credentials it never
+ * issued would be meaningless.
+ */
+export function resolveReadinessProbeAuth(
+  authMode: string | null | undefined,
+  nativeAccessToken?: string | null,
+  connectionToken?: string | null
+): ReadinessProbeAuth {
+  if (authMode === 'oauth') {
+    return resolveOauthRestAuth(nativeAccessToken)
+  }
+
+  if (authMode === 'token') {
+    return { kind: 'token', token: connectionToken ?? null }
+  }
+
+  return { kind: 'public' }
+}
+
+export interface AdvertisedAuthProvider {
+  name?: string
+  supportsPassword?: boolean
+}
+
+/**
+ * Whether the oauth pre-flight guard may hard-fail a connection for "not
+ * signed in".
+ *
+ * `authModeFromStatus` maps the gateway's `auth_required: true` onto
+ * `'oauth'`, but that flag only means the dashboard is GATED — it says
+ * nothing about how you authenticate. A gateway whose providers are all
+ * username/password cannot satisfy the guard's checks by construction:
+ * `start_login` raises NotImplementedError, `/auth/native/authorize` rejects
+ * password providers, and its cookies are set by a plain password-login POST
+ * rather than the `/auth/callback` redirect the OAuth partition is primed
+ * for. Hard-failing there rejects a live session one line before the
+ * ws-ticket mint that would have succeeded against that very partition.
+ *
+ * Returns false only when EVERY advertised provider is password-based. An
+ * unknown or empty list keeps the strict guard, so backends that predate
+ * `/api/auth/providers` are unaffected.
+ */
+export function oauthGuardMayHardFail(providers: AdvertisedAuthProvider[] | null | undefined): boolean {
+  if (!Array.isArray(providers) || providers.length === 0) {
+    return true
+  }
+
+  const named = providers.filter(provider => provider && typeof provider === 'object' && provider.name)
+
+  if (named.length === 0) {
+    return true
+  }
+
+  return !named.every(provider => provider.supportsPassword)
+}
diff --git a/apps/desktop/electron/preload.ts b/apps/desktop/electron/preload.ts
index 7652a7688dd..47d854a1938 100644
--- a/apps/desktop/electron/preload.ts
+++ b/apps/desktop/electron/preload.ts
@@ -237,6 +237,7 @@ contextBridge.exposeInMainWorld('hermesDesktop', {
   // current snapshot via getBootstrapState() to recover after a devtools
   // reload mid-bootstrap.
   getBootstrapState: () => ipcRenderer.invoke('hermes:bootstrap:get'),
+  continueBootstrapLocal: () => ipcRenderer.invoke('hermes:bootstrap:continue-local'),
   resetBootstrap: () => ipcRenderer.invoke('hermes:bootstrap:reset'),
   repairBootstrap: () => ipcRenderer.invoke('hermes:bootstrap:repair'),
   cancelBootstrap: () => ipcRenderer.invoke('hermes:bootstrap:cancel'),
diff --git a/apps/desktop/electron/primary-backend-startup.test.ts b/apps/desktop/electron/primary-backend-startup.test.ts
new file mode 100644
index 00000000000..6d3f5c8f44d
--- /dev/null
+++ b/apps/desktop/electron/primary-backend-startup.test.ts
@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict'
+
+import { test, vi } from 'vitest'
+
+import { createFirstRunSetupGate } from './first-run-setup-gate'
+import { FirstRunSetupResetError, runPrimaryBackendStartup } from './primary-backend-startup'
+
+const bootstrapBackend = {
+  activeRoot: '/tmp/hermes-home/hermes-agent',
+  kind: 'bootstrap-needed',
+  platform: 'linux'
+}
+
+function startupOptions(overrides: Record<string, unknown> = {}) {
+  return {
+    connectRemote: vi.fn(async remote => ({ baseUrl: remote.baseUrl, mode: 'remote' as const })),
+    ensureLocalRuntime: vi.fn(async backend => ({ ...backend, command: 'hermes' })),
+    prepareLocalBackend: vi.fn(async () => bootstrapBackend),
+    resolveRemote: vi.fn(async () => null),
+    waitForDecision: vi.fn(async () => 'continue-local' as const),
+    waitForLocalStart: vi.fn(async () => {}),
+    ...overrides
+  }
+}
+
+test('remote apply re-resolves the saved connection without ensuring a local runtime', async () => {
+  const gate = createFirstRunSetupGate({ stuckAfterMs: 0 })
+  const savedRemote = { baseUrl: 'https://gateway.example.com/hermes' }
+  let configuredRemote: typeof savedRemote | null = null
+
+  const options = startupOptions({
+    resolveRemote: vi.fn(async () => configuredRemote),
+    waitForDecision: gate.wait
+  })
+
+  const pending = runPrimaryBackendStartup(options)
+
+  await vi.waitFor(() => assert.equal(gate.hasWaiter(), true))
+  configuredRemote = savedRemote
+  assert.equal(gate.abandonForRemoteApply(), true)
+
+  assert.deepEqual(await pending, {
+    kind: 'remote',
+    connection: { baseUrl: savedRemote.baseUrl, mode: 'remote' }
+  })
+  assert.deepEqual(options.resolveRemote.mock.calls, [[], []])
+  assert.deepEqual(options.connectRemote.mock.calls, [[savedRemote]])
+  assert.equal(options.ensureLocalRuntime.mock.calls.length, 0)
+})
+
+test('an already-saved remote bypasses every local startup step', async () => {
+  const savedRemote = { baseUrl: 'https://gateway.example.com/hermes' }
+  const options = startupOptions({ resolveRemote: vi.fn(async () => savedRemote) })
+
+  assert.deepEqual(await runPrimaryBackendStartup(options), {
+    kind: 'remote',
+    connection: { baseUrl: savedRemote.baseUrl, mode: 'remote' }
+  })
+  assert.equal(options.waitForLocalStart.mock.calls.length, 0)
+  assert.equal(options.prepareLocalBackend.mock.calls.length, 0)
+  assert.equal(options.waitForDecision.mock.calls.length, 0)
+  assert.equal(options.ensureLocalRuntime.mock.calls.length, 0)
+})
+
+test('remote apply fails clearly when no saved remote can be resolved', async () => {
+  const gate = createFirstRunSetupGate({ stuckAfterMs: 0 })
+  const options = startupOptions({ waitForDecision: gate.wait })
+  const pending = runPrimaryBackendStartup(options)
+
+  await vi.waitFor(() => assert.equal(gate.hasWaiter(), true))
+  gate.abandonForRemoteApply()
+
+  await assert.rejects(pending, /without a saved remote backend/)
+  assert.equal(options.connectRemote.mock.calls.length, 0)
+  assert.equal(options.ensureLocalRuntime.mock.calls.length, 0)
+})
+
+test('continue local waits for update exclusion and ensures the prepared runtime exactly once', async () => {
+  const gate = createFirstRunSetupGate({ stuckAfterMs: 0 })
+  const runtimeBackend = { ...bootstrapBackend, command: 'hermes' }
+
+  const options = startupOptions({
+    ensureLocalRuntime: vi.fn(async () => runtimeBackend),
+    waitForDecision: gate.wait
+  })
+
+  const pending = runPrimaryBackendStartup(options)
+
+  await vi.waitFor(() => assert.equal(gate.hasWaiter(), true))
+  gate.continueLocal()
+
+  assert.deepEqual(await pending, { kind: 'local', backend: runtimeBackend })
+  assert.deepEqual(options.waitForLocalStart.mock.calls, [[]])
+  assert.deepEqual(options.prepareLocalBackend.mock.calls, [[]])
+  assert.deepEqual(options.ensureLocalRuntime.mock.calls, [[bootstrapBackend]])
+  assert.deepEqual(options.resolveRemote.mock.calls, [[]])
+})
+
+test('reset rejects with a typed error and never enters either backend', async () => {
+  const gate = createFirstRunSetupGate({ stuckAfterMs: 0 })
+  const options = startupOptions({ waitForDecision: gate.wait })
+  const pending = runPrimaryBackendStartup(options)
+
+  await vi.waitFor(() => assert.equal(gate.hasWaiter(), true))
+  gate.resetForRetry()
+
+  await assert.rejects(pending, error => error instanceof FirstRunSetupResetError && error.firstRunSetupReset)
+  assert.equal(options.connectRemote.mock.calls.length, 0)
+  assert.equal(options.ensureLocalRuntime.mock.calls.length, 0)
+})
diff --git a/apps/desktop/electron/primary-backend-startup.ts b/apps/desktop/electron/primary-backend-startup.ts
new file mode 100644
index 00000000000..edbe5167b05
--- /dev/null
+++ b/apps/desktop/electron/primary-backend-startup.ts
@@ -0,0 +1,66 @@
+import type { FirstRunSetupDecision } from './first-run-setup-gate'
+
+export interface PrimaryBackendStartupOptions<Backend, RuntimeBackend, Remote, Connection> {
+  connectRemote: (remote: Remote) => Promise<Connection>
+  ensureLocalRuntime: (backend: Backend) => Promise<RuntimeBackend>
+  prepareLocalBackend: () => Backend | Promise<Backend>
+  resolveRemote: () => Promise<Remote | null>
+  waitForDecision: (backend: Backend) => Promise<FirstRunSetupDecision>
+  waitForLocalStart: () => Promise<unknown>
+}
+
+export type PrimaryBackendStartupResult<RuntimeBackend, Connection> =
+  | { kind: 'local'; backend: RuntimeBackend }
+  | { kind: 'remote'; connection: Connection }
+
+export class FirstRunSetupResetError extends Error {
+  readonly firstRunSetupReset = true
+
+  constructor() {
+    super('First-run setup was reset before a choice completed.')
+    this.name = 'FirstRunSetupResetError'
+  }
+}
+
+// Owns the production startHermes path up to the local process spawn. Keeping
+// the full ordering here makes the first-run remote boundary executable in a
+// test: an already-saved remote wins immediately; otherwise update exclusion
+// and local backend resolution happen before the setup gate, and a remote Apply
+// re-resolves persisted config without ever entering ensureRuntime/bootstrap.
+export async function runPrimaryBackendStartup<Backend, RuntimeBackend, Remote, Connection>({
+  connectRemote,
+  ensureLocalRuntime,
+  prepareLocalBackend,
+  resolveRemote,
+  waitForDecision,
+  waitForLocalStart
+}: PrimaryBackendStartupOptions<Backend, RuntimeBackend, Remote, Connection>): Promise<
+  PrimaryBackendStartupResult<RuntimeBackend, Connection>
+> {
+  const savedRemote = await resolveRemote()
+
+  if (savedRemote) {
+    return { kind: 'remote', connection: await connectRemote(savedRemote) }
+  }
+
+  await waitForLocalStart()
+
+  const backend = await prepareLocalBackend()
+  const decision = await waitForDecision(backend)
+
+  if (decision === 'remote-applied') {
+    const appliedRemote = await resolveRemote()
+
+    if (!appliedRemote) {
+      throw new Error('First-run remote setup completed without a saved remote backend.')
+    }
+
+    return { kind: 'remote', connection: await connectRemote(appliedRemote) }
+  }
+
+  if (decision === 'reset') {
+    throw new FirstRunSetupResetError()
+  }
+
+  return { kind: 'local', backend: await ensureLocalRuntime(backend) }
+}
diff --git a/apps/desktop/electron/primary-connection-rehome.ts b/apps/desktop/electron/primary-connection-rehome.ts
new file mode 100644
index 00000000000..4952b8a9028
--- /dev/null
+++ b/apps/desktop/electron/primary-connection-rehome.ts
@@ -0,0 +1,35 @@
+export interface PrimaryConnectionRehomeOptions {
+  clearLocalBootstrapFailure: () => void
+  mode: string
+  notifyConnectionApplied: () => void
+  resumeFirstRunRemote: () => boolean
+  teardownPrimaryBackend: (options: { soft: boolean }) => Promise<void>
+}
+
+// Production seam shared by the connection-config IPC handler and the
+// first-run integration test. A remote apply that resumes the active setup
+// gate must keep that connection attempt alive; ordinary mode changes tear the
+// current backend down before the renderer is told to reconnect.
+export async function rehomePrimaryConnection({
+  clearLocalBootstrapFailure,
+  mode,
+  notifyConnectionApplied,
+  resumeFirstRunRemote,
+  teardownPrimaryBackend
+}: PrimaryConnectionRehomeOptions): Promise<{ resumedFirstRunRemote: boolean }> {
+  let resumedFirstRunRemote = false
+
+  if (mode === 'remote') {
+    resumedFirstRunRemote = resumeFirstRunRemote()
+    clearLocalBootstrapFailure()
+  }
+
+  if (resumedFirstRunRemote) {
+    return { resumedFirstRunRemote: true }
+  }
+
+  await teardownPrimaryBackend({ soft: true })
+  notifyConnectionApplied()
+
+  return { resumedFirstRunRemote: false }
+}
diff --git a/apps/desktop/electron/spawn-helper-perms.test.ts b/apps/desktop/electron/spawn-helper-perms.test.ts
index 26cb1fefaa4..d8c9ca034b5 100644
--- a/apps/desktop/electron/spawn-helper-perms.test.ts
+++ b/apps/desktop/electron/spawn-helper-perms.test.ts
@@ -8,7 +8,8 @@ import {
   needsExecBit,
   spawnHelperCandidates,
   type SpawnHelperFs,
-  withExecBits
+  withExecBits,
+  writableNodePtyRoot
 } from './spawn-helper-perms'
 
 interface FakeFile {
@@ -56,6 +57,30 @@ function fakeFs(
   }
 }
 
+test('rewrites an archived node-pty root to the matching unpacked tree exactly once', () => {
+  assert.equal(
+    writableNodePtyRoot('/Hermes.app/Contents/Resources/app.asar/dist/node_modules/node-pty'),
+    '/Hermes.app/Contents/Resources/app.asar.unpacked/dist/node_modules/node-pty'
+  )
+  assert.equal(
+    writableNodePtyRoot('/Hermes.app/Contents/Resources/app.asar.unpacked/dist/node_modules/node-pty'),
+    '/Hermes.app/Contents/Resources/app.asar.unpacked/dist/node_modules/node-pty'
+  )
+})
+
+test('uses the unpacked helper when resolution reports an app.asar node-pty root', () => {
+  const archivedRoot = '/Hermes.app/Contents/Resources/app.asar/dist/node_modules/node-pty'
+  const unpackedRoot = writableNodePtyRoot(archivedRoot)
+  const helper = join(unpackedRoot, 'prebuilds', 'darwin-arm64', 'spawn-helper')
+  const fs = fakeFs({ [helper]: { mode: 0o644 } }, { [join(unpackedRoot, 'prebuilds')]: ['darwin-arm64'] })
+
+  const result = ensureSpawnHelperExecutable(archivedRoot, fs)
+
+  assert.deepEqual(result.fixed, [helper])
+  assert.deepEqual(result.errors, [])
+  assert.deepEqual(fs.chmods, [{ path: helper, mode: 0o755 }])
+})
+
 test('needsExecBit / withExecBits treat any missing exec bit as non-executable', () => {
   assert.equal(needsExecBit(0o644), true)
   assert.equal(needsExecBit(0o755), false)
diff --git a/apps/desktop/electron/spawn-helper-perms.ts b/apps/desktop/electron/spawn-helper-perms.ts
index 6dfd484dc80..684b77096ba 100644
--- a/apps/desktop/electron/spawn-helper-perms.ts
+++ b/apps/desktop/electron/spawn-helper-perms.ts
@@ -18,6 +18,14 @@ import { join } from 'node:path'
 
 const EXEC_BITS = 0o111
 
+// Electron exposes module paths inside app.asar even when electron-builder has
+// unpacked the native payload beside it. `stat` can read an archived path, but
+// chmod cannot mutate it (ENOTDIR). Native node-pty helpers belong in the
+// writable app.asar.unpacked tree; leave an already-unpacked path unchanged.
+export function writableNodePtyRoot(nodePtyRoot: string): string {
+  return nodePtyRoot.replace(/app\.asar(?!\.unpacked)/, 'app.asar.unpacked')
+}
+
 export interface SpawnHelperFs {
   existsSync(path: string): boolean
   readdirSync(path: string): string[]
@@ -81,8 +89,9 @@ export function ensureSpawnHelperExecutable(
   fs: SpawnHelperFs = defaultFs
 ): EnsureSpawnHelperResult {
   const result: EnsureSpawnHelperResult = { fixed: [], errors: [] }
+  const writableRoot = writableNodePtyRoot(nodePtyRoot)
 
-  for (const path of spawnHelperCandidates(nodePtyRoot, fs)) {
+  for (const path of spawnHelperCandidates(writableRoot, fs)) {
     if (!fs.existsSync(path)) {
       continue
     }
diff --git a/apps/desktop/eslint.config.mjs b/apps/desktop/eslint.config.mjs
index 61abc0c90a0..7e02d1d7936 100644
--- a/apps/desktop/eslint.config.mjs
+++ b/apps/desktop/eslint.config.mjs
@@ -39,5 +39,43 @@ export default [
     rules: {
       'no-restricted-globals': ['warn', 'document']
     }
+  },
+  {
+    // Ban mirroring reactive values into refs via useEffect — the "atom-mirrored
+    // ref" antipattern. A ref synced from a nanostores atom via useEffect lags the
+    // atom by one render, which creates stale-read bugs in callbacks that read the
+    // ref (cancelRun sent session.interrupt to the wrong session; steerPrompt,
+    // restoreToMessage, editMessage all had closure-priority stale reads). The fix
+    // is to read $atom.get() directly in callbacks instead. This rule catches the
+    // mirroring effect at lint time so the pattern can't reappear. Legitimate
+    // non-atom ref writes inside useEffect (DOM instance refs, mount flags, request
+    // tokens, prop mirrors) get an eslint-disable-next-line with a comment.
+    files: ['src/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-syntax': [
+        'error',
+        {
+          // useEffect(() => { someRef.current = value }, [value])
+          selector:
+            'CallExpression[callee.name="useEffect"] > ArrowFunctionExpression[body.type="AssignmentExpression"][body.left.type="MemberExpression"][body.left.property.name="current"]',
+          message:
+            'Do not mirror reactive values into refs via useEffect. Read $atom.get() directly in callbacks instead — refs synced from atoms lag one render and cause stale-read bugs.'
+        },
+        {
+          // useEffect(() => { someRef.current = value; ... }, [value])
+          selector:
+            'CallExpression[callee.name="useEffect"] > ArrowFunctionExpression[body.type="BlockStatement"]:has(AssignmentExpression[left.type="MemberExpression"][left.property.name="current"])',
+          message:
+            'Do not mirror reactive values into refs via useEffect. Read $atom.get() directly in callbacks instead — refs synced from atoms lag one render and cause stale-read bugs.'
+        },
+        {
+          // useEffect(() => { setMutableRef(ref, value) }, [value])
+          selector:
+            'CallExpression[callee.name="useEffect"] > ArrowFunctionExpression[body.type="BlockStatement"]:has(CallExpression[callee.name="setMutableRef"])',
+          message:
+            'Do not mirror reactive values into refs via useEffect (setMutableRef included). Read $atom.get() directly in callbacks instead — refs synced from atoms lag one render and cause stale-read bugs.'
+        }
+      ]
+    }
   }
 ]
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index e40be3df818..0d2c07756af 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -111,7 +111,7 @@
     "motion": "^12.38.0",
     "nanostores": "^1.3.0",
     "node-pty": "1.1.0",
-    "radix-ui": "^1.4.3",
+    "radix-ui": "^1.6.5",
     "react": "^19.2.5",
     "react-arborist": "^3.5.0",
     "react-dnd-html5-backend": "^14.0.3",
diff --git a/apps/desktop/scripts/before-pack.mjs b/apps/desktop/scripts/before-pack.mjs
index 8b2359dfba6..b76acfe32d2 100644
--- a/apps/desktop/scripts/before-pack.mjs
+++ b/apps/desktop/scripts/before-pack.mjs
@@ -57,7 +57,8 @@
  *   - electronPlatformName: 'win32' | 'darwin' | 'linux'
  *   - arch:                 Arch enum (0=ia32, 1=x64, 2=armv7l, 3=arm64, 4=universal)
  */
-import { existsSync, rmSync } from 'node:fs'
+import { existsSync, rmSync, renameSync } from 'node:fs'
+import path from 'node:path'
 import { Arch } from 'electron-builder'
 import { stageNodePty } from './stage-native-deps.mjs'
 
@@ -75,10 +76,52 @@ export function cleanStaleAppOutDir(appOutDir) {
   return true
 }
 
+/**
+ * Windows rollback material (#69179): before wiping the previous unpacked
+ * tree, preserve it as `<appOutDir>.bak` — but ONLY when it holds the product
+ * exe (i.e. it is a previously-working build, not the corrupted partial state
+ * cleanStaleAppOutDir exists to remove). If the fresh pack then produces a
+ * Hermes.exe that Windows can't load (truncated PE from a corrupt cached
+ * Electron zip, wrong arch), the updater's integrity gate in
+ * `hermes desktop --build-only` (hermes_cli/main.py
+ * `_ensure_desktop_exe_launchable`) restores this .bak instead of leaving the
+ * user with "This app can't run on your computer".
+ *
+ * Returns true when the tree was preserved (appOutDir no longer exists), false
+ * when there was nothing worth preserving (caller falls through to the wipe).
+ * A rename failure (AV holding a handle) also returns false — the wipe is the
+ * safe fallback and matches pre-#69179 behavior exactly.
+ */
+export function preserveRollbackBackup(appOutDir, productExeName = 'Hermes.exe') {
+  if (!appOutDir || typeof appOutDir !== 'string' || !existsSync(appOutDir)) {
+    return false
+  }
+  if (!existsSync(path.join(appOutDir, productExeName))) {
+    // Partial/corrupt tree (interrupted prior pack) — not rollback material.
+    return false
+  }
+  const backupDir = `${appOutDir}.bak`
+  try {
+    rmSync(backupDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+    renameSync(appOutDir, backupDir)
+    return true
+  } catch {
+    return false
+  }
+}
+
 export default async function beforePack(context) {
   const appOutDir = context && context.appOutDir
+  const platformName = context && context.electronPlatformName
   try {
-    if (cleanStaleAppOutDir(appOutDir)) {
+    // Windows: keep the previous working build as rollback material for the
+    // post-build integrity gate (#69179) instead of destroying it. Falls
+    // through to the plain wipe when the old tree is partial/corrupt or the
+    // rename fails.
+    const productExe = `${(context && context.packager?.appInfo?.productFilename) || 'Hermes'}.exe`
+    if (platformName === 'win32' && preserveRollbackBackup(appOutDir, productExe)) {
+      console.log(`[before-pack] preserved previous unpacked dir for rollback: ${appOutDir}.bak`)
+    } else if (cleanStaleAppOutDir(appOutDir)) {
       console.log(`[before-pack] removed stale unpacked dir before staging: ${appOutDir}`)
     }
   } catch (err) {
diff --git a/apps/desktop/scripts/before-pack.test.mjs b/apps/desktop/scripts/before-pack.test.mjs
index 44adf961618..d082ec4d2ad 100644
--- a/apps/desktop/scripts/before-pack.test.mjs
+++ b/apps/desktop/scripts/before-pack.test.mjs
@@ -4,7 +4,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { test } from 'vitest'
 
-import beforePack, { cleanStaleAppOutDir } from '../scripts/before-pack.mjs'
+import beforePack, { cleanStaleAppOutDir, preserveRollbackBackup } from '../scripts/before-pack.mjs'
 
 test('cleanStaleAppOutDir removes a populated unpacked directory', () => {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-before-pack-'))
@@ -50,3 +50,106 @@ test('beforePack default export resolves even when cleanup throws', async () =>
   // remove; the contract under test is that the hook never rejects.
   await assert.doesNotReject(beforePack({ appOutDir: '', electronPlatformName: 'linux' }))
 })
+
+// ─── Windows rollback preservation (#69179) ────────────────────────────────
+
+test('preserveRollbackBackup moves a working build to .bak', () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-before-pack-'))
+  try {
+    const appOutDir = path.join(tempRoot, 'win-unpacked')
+    fs.mkdirSync(appOutDir, { recursive: true })
+    fs.writeFileSync(path.join(appOutDir, 'Hermes.exe'), 'MZ-old-build', 'utf8')
+    fs.writeFileSync(path.join(appOutDir, 'resources.pak'), 'x', 'utf8')
+
+    const preserved = preserveRollbackBackup(appOutDir, 'Hermes.exe')
+
+    assert.equal(preserved, true)
+    // Original slot vacated so electron-builder stages into a clean tree...
+    assert.equal(fs.existsSync(appOutDir), false)
+    // ...and the previous working build is intact under .bak for rollback.
+    assert.equal(
+      fs.readFileSync(path.join(`${appOutDir}.bak`, 'Hermes.exe'), 'utf8'),
+      'MZ-old-build'
+    )
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  }
+})
+
+test('preserveRollbackBackup replaces a stale .bak from an older update', () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-before-pack-'))
+  try {
+    const appOutDir = path.join(tempRoot, 'win-unpacked')
+    fs.mkdirSync(appOutDir, { recursive: true })
+    fs.writeFileSync(path.join(appOutDir, 'Hermes.exe'), 'current', 'utf8')
+    fs.mkdirSync(`${appOutDir}.bak`, { recursive: true })
+    fs.writeFileSync(path.join(`${appOutDir}.bak`, 'Hermes.exe'), 'two-updates-ago', 'utf8')
+
+    assert.equal(preserveRollbackBackup(appOutDir, 'Hermes.exe'), true)
+    assert.equal(fs.readFileSync(path.join(`${appOutDir}.bak`, 'Hermes.exe'), 'utf8'), 'current')
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  }
+})
+
+test('preserveRollbackBackup refuses a partial tree missing the product exe', () => {
+  // The corrupted partial state (interrupted prior pack) must NOT become
+  // rollback material — it is exactly what cleanStaleAppOutDir exists to wipe.
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-before-pack-'))
+  try {
+    const appOutDir = path.join(tempRoot, 'win-unpacked')
+    fs.mkdirSync(appOutDir, { recursive: true })
+    fs.writeFileSync(path.join(appOutDir, 'LICENSE.electron.txt'), 'x', 'utf8')
+
+    assert.equal(preserveRollbackBackup(appOutDir, 'Hermes.exe'), false)
+    // Tree untouched; the caller's wipe path handles it.
+    assert.equal(fs.existsSync(appOutDir), true)
+    assert.equal(fs.existsSync(`${appOutDir}.bak`), false)
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  }
+})
+
+test('preserveRollbackBackup ignores missing or invalid input', () => {
+  assert.equal(preserveRollbackBackup(''), false)
+  assert.equal(preserveRollbackBackup(undefined), false)
+  assert.equal(preserveRollbackBackup(null), false)
+  assert.equal(preserveRollbackBackup(path.join(os.tmpdir(), 'does-not-exist-xyz')), false)
+})
+
+test('beforePack on win32 preserves the previous build instead of wiping it', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-before-pack-'))
+  try {
+    const appOutDir = path.join(tempRoot, 'win-unpacked')
+    fs.mkdirSync(appOutDir, { recursive: true })
+    fs.writeFileSync(path.join(appOutDir, 'Hermes.exe'), 'MZ-working', 'utf8')
+
+    // No packager info in the context → default 'Hermes.exe' product name.
+    // node-pty staging is skipped because arch is not a number here.
+    await beforePack({ appOutDir, electronPlatformName: 'win32' })
+
+    assert.equal(fs.existsSync(appOutDir), false)
+    assert.equal(
+      fs.readFileSync(path.join(`${appOutDir}.bak`, 'Hermes.exe'), 'utf8'),
+      'MZ-working'
+    )
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  }
+})
+
+test('beforePack on linux keeps the plain wipe (no .bak)', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-before-pack-'))
+  try {
+    const appOutDir = path.join(tempRoot, 'linux-unpacked')
+    fs.mkdirSync(appOutDir, { recursive: true })
+    fs.writeFileSync(path.join(appOutDir, 'Hermes.exe'), 'x', 'utf8')
+
+    await beforePack({ appOutDir, electronPlatformName: 'linux' })
+
+    assert.equal(fs.existsSync(appOutDir), false)
+    assert.equal(fs.existsSync(`${appOutDir}.bak`), false)
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  }
+})
diff --git a/apps/desktop/scripts/perf/scenarios/index.mjs b/apps/desktop/scripts/perf/scenarios/index.mjs
index d9aeece1eff..d69ecce2fbc 100644
--- a/apps/desktop/scripts/perf/scenarios/index.mjs
+++ b/apps/desktop/scripts/perf/scenarios/index.mjs
@@ -4,16 +4,20 @@
 import coldStart from './cold-start.mjs'
 import firstToken from './first-token.mjs'
 import keystroke from './keystroke.mjs'
+import multitab from './multitab.mjs'
 import profileSwitch from './profile-switch.mjs'
 import sessionSwitch from './session-switch.mjs'
 import stream from './stream.mjs'
+import streamHistory from './stream-history.mjs'
 import submit from './submit.mjs'
 import transcript from './transcript.mjs'
 
 export const SCENARIOS = {
   [stream.name]: stream,
+  [streamHistory.name]: streamHistory,
   [keystroke.name]: keystroke,
   [transcript.name]: transcript,
+  [multitab.name]: multitab,
   [coldStart.name]: coldStart,
   [firstToken.name]: firstToken,
   [submit.name]: submit,
diff --git a/apps/desktop/scripts/perf/scenarios/multitab.mjs b/apps/desktop/scripts/perf/scenarios/multitab.mjs
new file mode 100644
index 00000000000..d93116f1285
--- /dev/null
+++ b/apps/desktop/scripts/perf/scenarios/multitab.mjs
@@ -0,0 +1,246 @@
+// Multi-tab working sessions: N session tiles stacked as tabs in the main
+// zone, EVERY tab mounted (keep-alive), all streaming concurrently — the
+// "5 tabs doing PR review" workload. Measures frame pacing + longtasks while
+// the whole stack streams, which is where multitab renderers crawl.
+//
+// Drives the real pipeline synthetically (no backend, no credits):
+// publishSessionState per session per flush — exactly what the gateway's
+// delta flush does — via the __HERMES_SESSION_TILES__ hook.
+//
+//   node scripts/perf/run.mjs multitab --spawn [--tiles 5] [--tokens 240]
+
+import { sleep } from '../lib/cdp.mjs'
+import { frameHistogram, percentile } from '../lib/stats.mjs'
+
+// Same recorder pattern as stream.mjs (generation-guarded rAF + longtasks).
+const RECORDERS = `
+  (() => {
+    window.__FT_GEN__ = (window.__FT_GEN__ || 0) + 1
+    const ftGen = window.__FT_GEN__
+    window.__FT__ = { times: [], stop: false }
+    let last = performance.now()
+    const tick = () => {
+      if (window.__FT_GEN__ !== ftGen || window.__FT__.stop) return
+      const now = performance.now()
+      window.__FT__.times.push(now - last)
+      last = now
+      requestAnimationFrame(tick)
+    }
+    requestAnimationFrame(tick)
+
+    window.__LT__ = { entries: [], stop: false }
+    try {
+      const po = new PerformanceObserver((list) => {
+        if (window.__LT__.stop) return
+        for (const e of list.getEntries()) window.__LT__.entries.push({ duration: e.duration, startTime: e.startTime })
+      })
+      po.observe({ entryTypes: ['longtask'] })
+      window.__LT__.po = po
+    } catch {}
+    return 'armed'
+  })()
+`
+
+const COLLECT = `
+  (() => {
+    window.__FT__.stop = true
+    window.__LT__.stop = true
+    try { window.__LT__.po && window.__LT__.po.disconnect() } catch {}
+    return JSON.stringify({ frames: window.__FT__.times, longtasks: window.__LT__.entries })
+  })()
+`
+
+/** Page-side setup: open `tiles` session tiles stacked into the main zone,
+ *  bind fake runtime ids, and seed each with a realistic transcript. */
+const setup = (tiles, seedTurns, streamSeed) => `
+  (() => {
+    const hook = window.__HERMES_SESSION_TILES__
+    if (!hook) return 'no-hook'
+
+    const turn = (sid, i) => ([
+      { id: sid + '-u' + i, role: 'user', timestamp: Date.now(),
+        parts: [{ type: 'text', text: 'Review question ' + i + ': does the diff in module ' + i + ' handle the error path?' }] },
+      { id: sid + '-a' + i, role: 'assistant', timestamp: Date.now(), pending: false,
+        parts: [{ type: 'text', text: [
+          '## Finding ' + i, '',
+          'The handler swallows the rejection. Key points for hunk \\\`' + i + '\\\`:', '',
+          '- The catch block drops the original error.',
+          '- Retries are unbounded — see [the loop](https://example.com/loop).', '',
+          '\\\`\\\`\\\`ts',
+          'async function retry' + i + '(fn: () => Promise<void>) {',
+          '  for (;;) { try { return await fn() } catch {} }',
+          '}',
+          '\\\`\\\`\\\`', '',
+          '| path | covered |', '|---|---|', '| happy | yes |', '| error | no |', ''
+        ].join('\\n') }] }
+    ])
+
+    const state = (sid, rid) => {
+      const messages = []
+      for (let i = 0; i < ${seedTurns}; i++) messages.push(...turn(sid, i))
+      // Streaming tail the driver grows (--code seeds an open fence).
+      messages.push({ id: sid + '-stream', role: 'assistant', timestamp: Date.now(), pending: true,
+        parts: [{ type: 'text', text: ${JSON.stringify(streamSeed)} }] })
+      return {
+        storedSessionId: sid, messages, branch: '', cwd: '', model: '', provider: '',
+        reasoningEffort: '', serviceTier: '', fast: false, yolo: false, personality: '',
+        busy: true, awaitingResponse: false, streamId: sid + '-stream', sawAssistantPayload: true,
+        pendingBranchGroup: null, interrupted: false, interimBoundaryPending: false,
+        needsInput: false, turnStartedAt: Date.now(), usage: null
+      }
+    }
+
+    window.__MT__ = { ids: [], timer: null }
+    for (let n = 1; n <= ${tiles}; n++) {
+      const sid = 'perf-tile-' + n
+      const rid = 'perf-rt-' + n
+      window.__MT__.ids.push({ sid, rid })
+      hook.open(sid, 'center')
+      hook.patch(sid, { runtimeId: rid })
+      hook.publish(rid, state(sid, rid))
+    }
+    return 'ok'
+  })()
+`
+
+// Activate every tab once so keep-alive mounts the full stack (lazy mount:
+// a never-activated tab stays unmounted, which would understate the cost).
+const reveal = sid => `window.__HERMES_LAYOUT_TREE__.reveal(${JSON.stringify(`session-tile:${sid}`)})`
+
+/** Page-side driver: grow every tile's streaming tail by `chunk` each
+ *  `intervalMs`, through the same publish path the gateway flush uses. */
+const drive = (chunk, intervalMs, totalTokens) => `
+  (() => {
+    const hook = window.__HERMES_SESSION_TILES__
+    let pushed = 0
+    const tick = () => {
+      const states = hook.states()
+      for (const { rid } of window.__MT__.ids) {
+        const prev = states[rid]
+        if (!prev) continue
+        const messages = prev.messages.map(m => {
+          if (m.id !== prev.streamId) return m
+          const head = m.parts.slice(0, -1)
+          const last = m.parts[m.parts.length - 1]
+          return { ...m, parts: [...head, { type: 'text', text: last.text + ${JSON.stringify(chunk)} }] }
+        })
+        hook.publish(rid, { ...prev, messages })
+      }
+      pushed += 1
+      if (pushed < ${totalTokens}) window.__MT__.timer = setTimeout(tick, ${intervalMs})
+      else window.__MT__.done = true
+    }
+    window.__MT__.timer = setTimeout(tick, ${intervalMs})
+    return 'driving'
+  })()
+`
+
+const CLEANUP = `
+  (() => {
+    if (window.__MT__) {
+      clearTimeout(window.__MT__.timer)
+      for (const { sid, rid } of window.__MT__.ids) {
+        window.__HERMES_SESSION_TILES__.publish(rid, {
+          ...window.__HERMES_SESSION_TILES__.states()[rid], busy: false, streamId: null
+        })
+        window.__HERMES_SESSION_TILES__.close(sid)
+      }
+      window.__MT__ = null
+    }
+    return 'cleaned'
+  })()
+`
+
+export default {
+  name: 'multitab',
+  tier: 'ci',
+  description: 'N mounted session-tile tabs all streaming: frame pacing + longtasks.',
+  async run(cdp, opts = {}) {
+    const tiles = Number(opts.tiles ?? 5)
+    const seedTurns = Number(opts.turns ?? 20)
+    const tokens = Number(opts.tokens ?? 240)
+    // Matches STREAM_DELTA_FLUSH_MS — one publish per session per real flush.
+    const intervalMs = Number(opts.intervalMs ?? 33)
+    // --code: every tile grows ONE giant fenced code block with no settle
+    // boundaries — what a coding agent streams. The block re-parses and
+    // re-renders fully every flush (block memoization can't settle it), the
+    // documented worst case and the "5 tabs all coding" crawl.
+    const chunk = opts.code
+      ? '  const value = await resolve(ctx, { retry: true }) // step\n'
+      : (opts.chunk ?? 'A streamed review sentence with **bold**, `code`, and ordinary prose.\n\n')
+    const streamSeed = opts.code ? '```ts\n' : ''
+
+    await cdp.send('Runtime.enable')
+
+    const ok = await cdp.eval(setup(tiles, seedTurns, streamSeed))
+
+    if (ok !== 'ok') {
+      throw new Error(`multitab setup failed (${ok}) — dev hooks missing? (needs a dev/probe renderer)`)
+    }
+
+    // Mount every tab (keep-alive mounts on first activation), then settle.
+    for (let n = 1; n <= tiles; n++) {
+      await cdp.eval(reveal(`perf-tile-${n}`))
+      await sleep(350)
+    }
+
+    await sleep(1000)
+    await cdp.eval(RECORDERS)
+    await cdp.eval(drive(chunk, intervalMs, tokens))
+    await sleep(tokens * intervalMs + 1500)
+
+    const data = JSON.parse(await cdp.eval(COLLECT))
+    await cdp.eval(CLEANUP)
+
+    // Drop the first 500ms (recorder install + settle).
+    const frames = []
+    let acc = 0
+
+    for (const f of data.frames) {
+      acc += f
+
+      if (acc >= 500) {
+        frames.push(f)
+      }
+    }
+
+    const ltDurations = data.longtasks.map(e => e.duration)
+    const windowS = frames.reduce((a, b) => a + b, 0) / 1000
+    // The felt numbers: sustained fps over the window, and the fps of the
+    // worst 1-second slice (a 333ms frame IS "3fps" even if the average looks
+    // fine). Worst slice = max summed frame time in any sliding 1s window.
+    const avgFps = windowS ? frames.length / windowS : 0
+    let worstFps = avgFps
+
+    for (let i = 0, j = 0, sum = 0; j < frames.length; j++) {
+      sum += frames[j]
+
+      while (sum > 1000) {
+        sum -= frames[i++]
+      }
+
+      // Only a window that actually spans ~1s counts; short prefixes don't.
+      if (sum >= 900) {
+        worstFps = Math.min(worstFps, ((j - i + 1) / sum) * 1000)
+      }
+    }
+
+    return {
+      metrics: {
+        longtasks_n: data.longtasks.length,
+        longtask_max_ms: Math.round((ltDurations.length ? Math.max(...ltDurations) : 0) * 10) / 10,
+        frame_p95_ms: Math.round(percentile(frames, 0.95) * 10) / 10,
+        frame_p99_ms: Math.round(percentile(frames, 0.99) * 10) / 10,
+        slow_frames_33: frames.filter(f => f > 33).length
+      },
+      detail: {
+        tiles,
+        code: Boolean(opts.code),
+        windowS: Math.round(windowS * 10) / 10,
+        avgFps: Math.round(avgFps * 10) / 10,
+        worstSecondFps: Math.round(worstFps * 10) / 10,
+        frameHistogram: frameHistogram(frames)
+      }
+    }
+  }
+}
diff --git a/apps/desktop/scripts/perf/scenarios/stream-history.mjs b/apps/desktop/scripts/perf/scenarios/stream-history.mjs
new file mode 100644
index 00000000000..d807f3f3573
--- /dev/null
+++ b/apps/desktop/scripts/perf/scenarios/stream-history.mjs
@@ -0,0 +1,18 @@
+// Streaming into an ALREADY-LONG transcript. Same measurement as `stream`, but
+// the history is mounted and allowed to settle before the recorders start, so
+// what it captures is the per-delta cost that scales with transcript length —
+// the regression reported in #69120.
+//
+// Report-only (tier: manual): the number depends on how much history the host
+// can mount, so it is not gated against the committed baseline.
+
+import stream from './stream.mjs'
+
+export default {
+  name: 'stream-history',
+  tier: 'manual',
+  description: 'Streaming cost with a long settled transcript already mounted.',
+  run(cdp, opts = {}) {
+    return stream.run(cdp, { ...opts, historyTurns: Number(opts.historyTurns ?? 200) })
+  }
+}
diff --git a/apps/desktop/scripts/perf/scenarios/stream.mjs b/apps/desktop/scripts/perf/scenarios/stream.mjs
index 66ae3ca58d5..f32a4831b1e 100644
--- a/apps/desktop/scripts/perf/scenarios/stream.mjs
+++ b/apps/desktop/scripts/perf/scenarios/stream.mjs
@@ -70,7 +70,7 @@ const COLLECT = `
   })()
 `
 
-function analyze(data, warmupMs) {
+function analyze(data, warmupMs, extra = {}) {
   // Drop warm-up frames (recorder installs before the stream starts).
   const frames = []
   let acc = 0
@@ -102,6 +102,7 @@ function analyze(data, warmupMs) {
       intermut_p95_ms: Math.round(percentile(interMut, 0.95) * 10) / 10
     },
     detail: {
+      ...extra,
       windowS: Math.round(windowS * 10) / 10,
       avgFps: windowS ? Math.round((frames.length / windowS) * 10) / 10 : 0,
       frameHistogram: frameHistogram(frames),
@@ -128,13 +129,36 @@ export default {
     // noise unrelated to render cost).
     const chunk = opts.chunk ?? 'A streamed sentence with **bold**, `code`, and ordinary prose like a normal reply.\n\n'
     const real = Boolean(opts.real)
+    const historyTurns = Number(opts.historyTurns ?? 0)
+    const historySettleMs = Number(opts.historySettleMs ?? 1500)
 
     await cdp.send('Runtime.enable')
+
+    // Mount the settled history BEFORE the recorders start, so the measurement
+    // window contains only streaming work — not the one-off mount cost.
+    if (historyTurns > 0) {
+      if (real) {
+        throw new Error('--historyTurns is only supported by the synthetic stream path')
+      }
+
+      await cdp.eval(`window.__PERF_DRIVE__.loadTranscript(${historyTurns})`)
+      await sleep(historySettleMs)
+
+      const mounted = Number(await cdp.eval('window.__PERF_DRIVE__.snapshotMsgs()'))
+      const expected = historyTurns * 2
+
+      if (mounted !== expected) {
+        throw new Error(`expected ${expected} preloaded history messages, got ${mounted}`)
+      }
+    }
+
     await cdp.eval(RECORDERS)
 
     if (real) {
       // Backend path: fire a real prompt and wait for the stream to appear.
-      const baseCount = await cdp.eval(`document.querySelectorAll(${JSON.stringify(SELECTORS.assistantMessage)}).length`)
+      const baseCount = await cdp.eval(
+        `document.querySelectorAll(${JSON.stringify(SELECTORS.assistantMessage)}).length`
+      )
       await typeIntoComposer(cdp, opts.prompt ?? 'count from 1 to 80, one number per line', { cps: 40 })
       await cdp.eval(`(() => {
         const el = document.querySelector(${JSON.stringify(SELECTORS.composer)})
@@ -186,6 +210,6 @@ export default {
       await cdp.eval('window.__PERF_DRIVE__.reset()')
     }
 
-    return analyze(data, real ? 0 : 500)
+    return analyze(data, real ? 0 : 500, { historyTurns })
   }
 }
diff --git a/apps/desktop/scripts/probe-model-picker.mjs b/apps/desktop/scripts/probe-model-picker.mjs
new file mode 100644
index 00000000000..d5585a36835
--- /dev/null
+++ b/apps/desktop/scripts/probe-model-picker.mjs
@@ -0,0 +1,80 @@
+// Model picker open latency probe: click the composer model pill, time until
+// the dropdown/dialog content paints, repeat. Run with --cpuprofile via the
+// harness runner once promoted; standalone for iteration.
+//   node scripts/perf/probe-model-picker.mjs [--port 9222] [--rounds 5]
+import { CDP } from './perf/lib/cdp.mjs'
+
+const args = process.argv.slice(2)
+const flag = name => {
+  const i = args.indexOf(`--${name}`)
+  return i >= 0 ? args[i + 1] : undefined
+}
+const port = Number(flag('port') ?? 9222)
+const rounds = Number(flag('rounds') ?? 5)
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+const cdp = await CDP.connect({ port })
+await cdp.send('Runtime.enable')
+
+// Find the pill (dropdown path) — the composer model selector button.
+const PILL = `(() => {
+  const btns = [...document.querySelectorAll('button[aria-label]')]
+  const pill = btns.find(b => /model/i.test(b.getAttribute('aria-label') || '') && b.closest('[data-slot]'))
+  return pill ? (pill.getAttribute('aria-label') || 'found') : null
+})()`
+
+console.log('pill:', await cdp.eval(PILL))
+
+const MEASURE = `
+  (async () => {
+    const btns = [...document.querySelectorAll('button[aria-label]')]
+    const pill = btns.find(b => /model/i.test(b.getAttribute('aria-label') || ''))
+    if (!pill) return JSON.stringify({ error: 'no pill' })
+
+    const t0 = performance.now()
+    pill.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }))
+    pill.dispatchEvent(new PointerEvent('pointerup', { bubbles: true }))
+    pill.click()
+
+    // Wait for menu/dialog content to exist AND paint (double rAF after found).
+    const found = await new Promise(resolve => {
+      const deadline = performance.now() + 5000
+      const check = () => {
+        const menu = document.querySelector('[role="menu"], [role="dialog"] [cmdk-list]')
+        if (menu && menu.childElementCount > 0) {
+          requestAnimationFrame(() => requestAnimationFrame(() => resolve(performance.now())))
+          return
+        }
+        if (performance.now() > deadline) { resolve(null); return }
+        requestAnimationFrame(check)
+      }
+      check()
+    })
+
+    const openMs = found ? found - t0 : null
+    const rows = document.querySelectorAll('[role="menu"] [role="menuitem"], [cmdk-item]').length
+
+    // Close: Escape.
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    const menu = document.querySelector('[role="menu"], [role="dialog"]')
+    menu?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    await new Promise(r => setTimeout(r, 300))
+
+    return JSON.stringify({ openMs, rows })
+  })()
+`
+
+const samples = []
+
+for (let i = 0; i < rounds; i++) {
+  const raw = await cdp.eval(MEASURE, { awaitPromise: true })
+  const r = JSON.parse(raw)
+  console.log(`round ${i}:`, r)
+  if (typeof r.openMs === 'number') samples.push(r.openMs)
+  await sleep(500)
+}
+
+samples.sort((a, b) => a - b)
+console.log('\nopen latency ms — min/median/max:',
+  Math.round(samples[0]), '/', Math.round(samples[Math.floor(samples.length / 2)]), '/', Math.round(samples.at(-1)))
+cdp.close()
diff --git a/apps/desktop/scripts/profile-model-picker.mjs b/apps/desktop/scripts/profile-model-picker.mjs
new file mode 100644
index 00000000000..26e16d6e7c9
--- /dev/null
+++ b/apps/desktop/scripts/profile-model-picker.mjs
@@ -0,0 +1,60 @@
+// CPU-profile one model-picker open.
+//   node scripts/profile-model-picker.mjs [--port 9222]
+import { writeFileSync } from 'node:fs'
+
+import { CDP } from './perf/lib/cdp.mjs'
+import { cpuProfileTopSelf } from './perf/lib/stats.mjs'
+
+const port = Number(process.argv.includes('--port') ? process.argv[process.argv.indexOf('--port') + 1] : 9222)
+const cdp = await CDP.connect({ port })
+await cdp.send('Runtime.enable')
+await cdp.send('Profiler.enable')
+await cdp.send('Profiler.setSamplingInterval', { interval: 100 })
+
+const OPEN = `
+  (async () => {
+    // Reset: close any open menu first.
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    await new Promise(r => setTimeout(r, 250))
+
+    const btns = [...document.querySelectorAll('button[aria-label]')]
+    const pill = btns.find(b => /model/i.test(b.getAttribute('aria-label') || ''))
+    if (!pill) return -1
+    const t0 = performance.now()
+    pill.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }))
+    pill.dispatchEvent(new PointerEvent('pointerup', { bubbles: true }))
+    pill.click()
+    const found = await new Promise(resolve => {
+      const deadline = performance.now() + 8000
+      const check = () => {
+        const menu = document.querySelector('[role="menu"]')
+        if (menu && menu.childElementCount > 0) {
+          requestAnimationFrame(() => requestAnimationFrame(() => resolve(performance.now())))
+          return
+        }
+        if (performance.now() > deadline) { resolve(-1); return }
+        requestAnimationFrame(check)
+      }
+      check()
+    })
+    return found < 0 ? -1 : found - t0
+  })()
+`
+
+await cdp.send('Profiler.start')
+const openMs = await cdp.eval(OPEN)
+const { profile } = await cdp.send('Profiler.stop')
+
+console.log('openMs:', Math.round(openMs))
+const out = `/tmp/model-picker-open.cpuprofile`
+writeFileSync(out, JSON.stringify(profile))
+console.log('wrote', out)
+console.log('top self-time (ms):')
+
+for (const r of cpuProfileTopSelf(profile, 20)) {
+  console.log(`  ${r.ms.toFixed(1).padStart(7)}  ${r.name.padEnd(44)}  ${r.url.split('/').slice(-2).join('/')}:${r.line}`)
+}
+
+// Close the menu again.
+await cdp.eval(`document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))`)
+cdp.close()
diff --git a/apps/desktop/src/app/chat/composer/composer-utils.ts b/apps/desktop/src/app/chat/composer/composer-utils.ts
index 7939be35b6b..547a210f06f 100644
--- a/apps/desktop/src/app/chat/composer/composer-utils.ts
+++ b/apps/desktop/src/app/chat/composer/composer-utils.ts
@@ -50,6 +50,9 @@ export function slashChipKindForItem(item: Unstable_TriggerItem): SlashChipKind
   return 'command'
 }
 
+/** True for a skill completion — the only kind offered mid-message. */
+export const isSkillItem = (item: Unstable_TriggerItem) => slashChipKindForItem(item) === 'skill'
+
 /** A `/` query is at its arg stage once it's past the command name. */
 export const slashArgStage = (query: string) => query.includes(' ')
 
diff --git a/apps/desktop/src/app/chat/composer/focus.test.ts b/apps/desktop/src/app/chat/composer/focus.test.ts
new file mode 100644
index 00000000000..f3987982274
--- /dev/null
+++ b/apps/desktop/src/app/chat/composer/focus.test.ts
@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { blurComposerInput } from './focus'
+import { RICH_INPUT_SLOT } from './rich-editor'
+
+/**
+ * Inactive tabs keep their composer mounted, so an unscoped lookup can blur a
+ * background input and leave the one the user is typing in focused.
+ */
+
+/** A composer input inside its own pane layer, hidden or not. */
+function mountInput(hidden = false) {
+  const layer = document.createElement('div')
+  const input = document.createElement('div')
+  input.dataset.slot = RICH_INPUT_SLOT
+  input.tabIndex = 0
+  layer.toggleAttribute('data-pane-hidden', hidden)
+  layer.append(input)
+  document.body.append(layer)
+
+  return input
+}
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('blurComposerInput', () => {
+  it('blurs the foreground composer while a hidden tab matches first', () => {
+    const background = mountInput(true)
+    const foreground = mountInput()
+
+    foreground.focus()
+    blurComposerInput()
+
+    expect(document.activeElement).not.toBe(foreground)
+    expect(document.activeElement).not.toBe(background)
+  })
+
+  it('leaves focus alone when the composer does not hold it', () => {
+    const outside = document.createElement('button')
+    document.body.append(outside)
+    mountInput()
+
+    outside.focus()
+    blurComposerInput()
+
+    expect(document.activeElement).toBe(outside)
+  })
+})
diff --git a/apps/desktop/src/app/chat/composer/focus.ts b/apps/desktop/src/app/chat/composer/focus.ts
index a470edfcd95..7120fde2b1a 100644
--- a/apps/desktop/src/app/chat/composer/focus.ts
+++ b/apps/desktop/src/app/chat/composer/focus.ts
@@ -10,6 +10,8 @@
  * steal focus from the composer effect.
  */
 
+import { queryVisible } from '@/components/pane-shell/pane-visibility'
+
 import type { InlineRefInput } from './inline-refs'
 import { RICH_INPUT_SLOT } from './rich-editor'
 
@@ -175,9 +177,11 @@ export const focusComposerInput = (el: HTMLElement | null) => {
   window.setTimeout(focus, 0)
 }
 
-/** Drop focus from the main composer input (status-stack chrome, sidebar, etc.). */
+/** Drop focus from the main composer input (status-stack chrome, sidebar, etc.).
+ *  Skips inactive tabs — they stay mounted, so an unscoped lookup can land on a
+ *  background composer and leave the visible one focused. */
 export const blurComposerInput = () => {
-  const el = document.querySelector(`[data-slot="${RICH_INPUT_SLOT}"]`) as HTMLElement | null
+  const el = queryVisible(`[data-slot="${RICH_INPUT_SLOT}"]`)
 
   if (el && document.activeElement === el) {
     el.blur()
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-draft.test.tsx b/apps/desktop/src/app/chat/composer/hooks/use-composer-draft.test.tsx
new file mode 100644
index 00000000000..81401482f69
--- /dev/null
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-draft.test.tsx
@@ -0,0 +1,130 @@
+import { act, cleanup, render } from '@testing-library/react'
+import { useLayoutEffect } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { type ComposerAttachment, mainComposerScope, stashSessionDraft } from '@/store/composer'
+
+import type { QueueEditState } from '../composer-utils'
+
+import { useComposerDraft } from './use-composer-draft'
+
+const mockComposerApi = { setText: vi.fn() }
+
+vi.mock('@assistant-ui/react', () => ({
+  useAui: () => ({ composer: () => mockComposerApi }),
+  useAuiState: (selector: (state: { composer: { text: string } }) => unknown) => selector({ composer: { text: '' } }),
+  useComposerRuntime: () => ({
+    getState: () => ({ text: '' }),
+    subscribe: () => () => undefined
+  })
+}))
+
+interface ProbeHarnessProps {
+  activeQueueSessionKey: string | null
+  onLayoutSnapshot: (attachments: ComposerAttachment[]) => void
+  sessionId: string
+}
+
+function ProbeHarness({ activeQueueSessionKey, onLayoutSnapshot, sessionId }: ProbeHarnessProps) {
+  useComposerDraft({
+    activeQueueSessionKey,
+    focusKey: null,
+    inputDisabled: false,
+    queueEditRef: { current: null as QueueEditState | null },
+    sessionId
+  })
+
+  // useLayoutEffect fires synchronously right after the DOM commit, BEFORE
+  // the hook's per-thread scope-swap useEffect (a passive effect) has a
+  // chance to swap attachmentScope.$attachments over to the new session. A
+  // synchronous read here — the same read ChatBar's `attachments` prop
+  // performs at render time — observes the OUTGOING session's attachments.
+  useLayoutEffect(() => {
+    onLayoutSnapshot(mainComposerScope.$attachments.get())
+  })
+
+  return null
+}
+
+describe('useComposerDraft — attachment scope stays coherent with the committed session on switch (#59305)', () => {
+  afterEach(() => {
+    cleanup()
+    mainComposerScope.clear()
+  })
+
+  it('clears the outgoing session attachments by the layout phase right after switching sessions', () => {
+    const attachmentA: ComposerAttachment = { id: 'url-A', kind: 'url', label: 'A' }
+    stashSessionDraft('session-A', 'hi from A', [attachmentA])
+
+    const snapshots: ComposerAttachment[][] = []
+
+    const { rerender } = render(
+      <ProbeHarness activeQueueSessionKey="session-A" onLayoutSnapshot={s => snapshots.push(s)} sessionId="session-A" />
+    )
+
+    // Mount loads session A's stashed attachment into the (module-level) main
+    // scope — confirms the fixture actually seeded the leak precondition.
+    expect(mainComposerScope.$attachments.get()).toEqual([attachmentA])
+
+    snapshots.length = 0 // drop the initial-mount snapshot; only the switch matters
+
+    act(() => {
+      rerender(
+        <ProbeHarness
+          activeQueueSessionKey="session-B"
+          onLayoutSnapshot={s => snapshots.push(s)}
+          sessionId="session-B"
+        />
+      )
+    })
+
+    // By the layout phase the scope must already be B's (empty) — a submit
+    // fired the instant B renders must never ship session A's attachment.
+    expect(snapshots[0]).toEqual([])
+  })
+})
+
+describe('useComposerDraft — rehydrate diagnostic log stays redacted', () => {
+  afterEach(() => {
+    cleanup()
+    mainComposerScope.clear()
+    vi.restoreAllMocks()
+  })
+
+  it('logs counts/kinds/scope on restore but never the raw url, refText, or label', () => {
+    const secretUrl = 'https://secret.example.com/private-workspace-path'
+
+    const attachment: ComposerAttachment = {
+      id: 'url-secret',
+      kind: 'url',
+      label: 'do-not-leak-label',
+      refText: `@url:${secretUrl}`
+    }
+
+    stashSessionDraft('session-secret', '', [attachment])
+
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => undefined)
+
+    render(
+      <ProbeHarness
+        activeQueueSessionKey="session-secret"
+        onLayoutSnapshot={() => undefined}
+        sessionId="session-secret"
+      />
+    )
+
+    const rehydrateCalls = debugSpy.mock.calls.filter(call => call[0] === '[composer-rehydrate]')
+    expect(rehydrateCalls.length).toBeGreaterThan(0)
+
+    const serialized = JSON.stringify(rehydrateCalls)
+    expect(serialized).not.toContain(secretUrl)
+    expect(serialized).not.toContain(attachment.label)
+    expect(serialized).not.toContain(attachment.refText)
+
+    expect(rehydrateCalls[0]?.[1]).toMatchObject({
+      attachmentCount: 1,
+      attachmentKinds: ['url'],
+      scope: 'session-secret'
+    })
+  })
+})
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-draft.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-draft.ts
index 11dc9534df0..11aa35dfaf7 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-draft.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-draft.ts
@@ -1,5 +1,5 @@
 import { useAui, useAuiState, useComposerRuntime } from '@assistant-ui/react'
-import { type RefObject, useCallback, useEffect, useRef, useState } from 'react'
+import { type RefObject, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 
 import { SLASH_COMMAND_RE } from '@/lib/chat-runtime'
 import { type ComposerAttachment, stashSessionDraft, takeSessionDraft } from '@/store/composer'
@@ -20,7 +20,7 @@ import {
   onComposerInsertRequest
 } from '../focus'
 import { type InlineRefInput, insertInlineRefsIntoEditor } from '../inline-refs'
-import { composerPlainText, placeCaretEnd, renderComposerContents } from '../rich-editor'
+import { composerPlainText, placeCaretEnd, REF_RE, renderComposerContents } from '../rich-editor'
 import { useComposerScope } from '../scope'
 import type { ChatBarProps } from '../types'
 
@@ -189,6 +189,21 @@ export function useComposerDraft({
     stashSessionDraft(scope, text, attachments)
 
   const loadIntoComposer = (text: string, attachments: ComposerAttachment[]) => {
+    // Diagnostic breadcrumb for #59305-class reports: identifies WHAT kind of
+    // state got restored into the composer (session switch, queue-edit
+    // restore, history browse) without logging any raw content. REF_RE has the
+    // global flag — testing against a throwaway clone avoids mutating the
+    // shared instance's lastIndex, which would otherwise corrupt this check on
+    // the next call.
+    if (attachments.length > 0 || new RegExp(REF_RE.source, REF_RE.flags).test(text)) {
+      console.debug('[composer-rehydrate]', {
+        attachmentCount: attachments.length,
+        attachmentKinds: attachments.map(a => a.kind),
+        hasTextRefs: new RegExp(REF_RE.source, REF_RE.flags).test(text),
+        scope: activeQueueSessionKeyRef.current
+      })
+    }
+
     attachmentScope.$attachments.set(cloneAttachments(attachments))
     paintDraft(text, false)
   }
@@ -231,6 +246,7 @@ export function useComposerDraft({
   // source otherwise), and (3) schedule the debounced per-session stash.
   // Browsing history / editing a queued prompt suppress the stash so recalled
   // text never clobbers the draft.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const sync = () => {
       const text = composerRuntime.getState().text
@@ -318,7 +334,17 @@ export function useComposerDraft({
   // Per-thread draft swap — the composer's only session coupling. Lifecycle
   // never clears composer state; this effect alone stashes on leave, restores
   // on enter. Keyed writes are idempotent, so no skip-sentinel.
-  useEffect(() => {
+  //
+  // MUST be a layout effect, not a passive one: it swaps attachmentScope's
+  // module-level $attachments atom, and a passive effect fires only after the
+  // browser paints the new session's view — leaving a window where the DOM
+  // already shows session B while $attachments (and therefore ChatBar's
+  // `attachments` prop) still holds session A's chips. A submit fired in that
+  // window (e.g. a fast session switch immediately followed by Enter) would
+  // ship A's attachments into B's turn (#59305). useLayoutEffect closes the
+  // window by running before paint.
+
+  useLayoutEffect(() => {
     // A pending debounce timer from the outgoing session is now stale — its
     // scope was correct when scheduled, but the authoritative stash below
     // (and the cleanup on the way out) already covers that text. Letting it
@@ -344,6 +370,7 @@ export function useComposerDraft({
 
   // pagehide is load-bearing: React skips effect cleanups on reload, so Cmd+R
   // inside the debounce/rAF window would drop trailing keystrokes without this.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const flushPendingDraftPersist = () => {
       const scope = draftScopeRef.current
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-metrics.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-metrics.ts
index 318802bbab8..228758dd905 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-metrics.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-metrics.ts
@@ -1,6 +1,12 @@
 import { useAuiState } from '@assistant-ui/react'
 import { type RefObject, useCallback, useEffect, useRef, useState } from 'react'
 
+import {
+  clearSurfaceVar,
+  COMPOSER_HEIGHT_VAR,
+  COMPOSER_SURFACE_HEIGHT_VAR,
+  setSurfaceVar
+} from '@/app/chat/surface-vars'
 import { useMediaQuery } from '@/hooks/use-media-query'
 import { useResizeObserver } from '@/hooks/use-resize-observer'
 import { $composerPoppedOut } from '@/store/composer-popout'
@@ -89,18 +95,16 @@ export function useComposerMetrics({ composerRef, composerSurfaceRef, editorRef,
     // (Read globals here so the callback stays stable; mirror the popoutAllowed
     // gate since secondary windows are forced docked.)
     if ($composerPoppedOut.get() && !isSecondaryWindow()) {
-      const root = document.documentElement
       lastBucketedHeightRef.current = 0
       lastBucketedSurfaceHeightRef.current = 0
-      root.style.setProperty('--composer-measured-height', '0px')
-      root.style.setProperty('--composer-surface-measured-height', '0px')
+      setSurfaceVar(composer, COMPOSER_HEIGHT_VAR, '0px')
+      setSurfaceVar(composer, COMPOSER_SURFACE_HEIGHT_VAR, '0px')
 
       return
     }
 
     const { height, width } = composer.getBoundingClientRect()
     const surfaceHeight = composerSurfaceRef.current?.getBoundingClientRect().height
-    const root = document.documentElement
 
     if (width > 0) {
       const nextTight = width < COMPOSER_STACK_BREAKPOINT_PX
@@ -135,7 +139,7 @@ export function useComposerMetrics({ composerRef, composerSurfaceRef, editorRef,
 
       if (bucket !== lastBucketedHeightRef.current) {
         lastBucketedHeightRef.current = bucket
-        root.style.setProperty('--composer-measured-height', `${bucket}px`)
+        setSurfaceVar(composer, COMPOSER_HEIGHT_VAR, `${bucket}px`)
       }
     }
 
@@ -144,7 +148,7 @@ export function useComposerMetrics({ composerRef, composerSurfaceRef, editorRef,
 
       if (bucket !== lastBucketedSurfaceHeightRef.current) {
         lastBucketedSurfaceHeightRef.current = bucket
-        root.style.setProperty('--composer-surface-measured-height', `${bucket}px`)
+        setSurfaceVar(composer, COMPOSER_SURFACE_HEIGHT_VAR, `${bucket}px`)
       }
     }
   }, [composerRef, composerSurfaceRef, editorRef])
@@ -160,12 +164,13 @@ export function useComposerMetrics({ composerRef, composerSurfaceRef, editorRef,
   }, [poppedOut, syncComposerMetrics])
 
   useEffect(() => {
+    const composer = composerRef.current
+
     return () => {
-      const root = document.documentElement
-      root.style.removeProperty('--composer-measured-height')
-      root.style.removeProperty('--composer-surface-measured-height')
+      clearSurfaceVar(composer, COMPOSER_HEIGHT_VAR)
+      clearSurfaceVar(composer, COMPOSER_SURFACE_HEIGHT_VAR)
     }
-  }, [])
+  }, [composerRef])
 
   // Pill compacts on real width (tile/pane), OR when stacked for any reason
   // (viewport-narrow / wrapped) so the controls row never over-runs.
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-placeholder.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-placeholder.ts
index 0c2e4b61927..8d1bf8c1ee5 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-placeholder.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-placeholder.ts
@@ -29,6 +29,7 @@ export function useComposerPlaceholder({ disabled, reconnecting, sessionId }: Us
 
   const prevSessionIdRef = useRef(sessionId)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const prev = prevSessionIdRef.current
     prevSessionIdRef.current = sessionId
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-queue.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-queue.ts
index 4e813f548ae..dff3804bb69 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-queue.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-queue.ts
@@ -322,6 +322,7 @@ export function useComposerQueue({
   // never churns, so a change there is a real session switch and must NOT
   // migrate; only the runtime-derived key (queueSessionKey falsy → key is
   // sessionId) churns on a backend bounce/resume of the same conversation.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const prev = prevQueueKeyRef.current
     prevQueueKeyRef.current = activeQueueSessionKey
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
index a09cd10ef29..b3bcaaa463e 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
@@ -113,7 +113,9 @@ describe('useComposerSubmit busy-turn routing', () => {
       hook.result.current.submitDraft()
     })
 
-    await waitFor(() => expect(onSubmit).toHaveBeenCalledWith('/compress preserve context'))
+    await waitFor(() =>
+      expect(onSubmit).toHaveBeenCalledWith('/compress preserve context', { composerScope: 'stored-session' })
+    )
     expect(clearDraft).toHaveBeenCalledTimes(1)
     expect(onSteer).not.toHaveBeenCalled()
     expect(queueCurrentDraft).not.toHaveBeenCalled()
@@ -159,9 +161,26 @@ describe('useComposerSubmit busy-turn routing', () => {
       hook.result.current.submitDraft()
     })
 
-    await waitFor(() => expect(onSubmit).toHaveBeenCalledWith('ordinary question', { attachments: [] }))
+    await waitFor(() =>
+      expect(onSubmit).toHaveBeenCalledWith('ordinary question', {
+        attachments: [],
+        composerScope: 'stored-session'
+      })
+    )
     expect(onSteer).not.toHaveBeenCalled()
     expect(queueCurrentDraft).not.toHaveBeenCalled()
     expect(onCancel).not.toHaveBeenCalled()
   })
+
+  it('threads the loaded composer scope through onSubmit for the #59305 submit-time guard', async () => {
+    const { hook, onSubmit } = renderSubmitHook({ text: 'hello' })
+
+    act(() => {
+      hook.result.current.submitDraft()
+    })
+
+    await waitFor(() =>
+      expect(onSubmit).toHaveBeenCalledWith('hello', expect.objectContaining({ composerScope: 'stored-session' }))
+    )
+  })
 })
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.ts
index fb1cec2cf04..315157a96e5 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.ts
@@ -89,7 +89,11 @@ export function useComposerSubmit({
       stashAt(submittedScope, text, submittedAttachments)
     }
 
-    void Promise.resolve(attachments ? onSubmit(text, { attachments }) : onSubmit(text))
+    void Promise.resolve(
+      attachments
+        ? onSubmit(text, { attachments, composerScope: submittedScope })
+        : onSubmit(text, { composerScope: submittedScope })
+    )
       .then(accepted => void (accepted === false ? restore() : clearSessionDraft(submittedScope)))
       .catch(restore)
   }
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.test.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.test.ts
new file mode 100644
index 00000000000..c356fae3af8
--- /dev/null
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.test.ts
@@ -0,0 +1,123 @@
+import type { Unstable_TriggerAdapter, Unstable_TriggerItem } from '@assistant-ui/core'
+import { act, renderHook } from '@testing-library/react'
+import { createRef } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { composerPlainText, renderComposerContents, RICH_INPUT_SLOT } from '../rich-editor'
+
+import { useComposerTrigger } from './use-composer-trigger'
+
+/** A live contentEditable seeded with `text`, caret parked at the end. */
+function mountEditor(text: string) {
+  const editor = document.createElement('div')
+  editor.dataset.slot = RICH_INPUT_SLOT
+  editor.contentEditable = 'true'
+  document.body.append(editor)
+  renderComposerContents(editor, text)
+
+  const range = document.createRange()
+  range.selectNodeContents(editor)
+  range.collapse(false)
+  const selection = window.getSelection()!
+  selection.removeAllRanges()
+  selection.addRange(range)
+
+  return editor
+}
+
+const item = (command: string, group = 'Skills'): Unstable_TriggerItem => ({
+  id: command,
+  type: 'slash',
+  label: command.slice(1),
+  metadata: { command, display: command, meta: '', group, action: '', rawText: command }
+})
+
+function mountTrigger(editor: HTMLDivElement, items: Unstable_TriggerItem[]) {
+  const editorRef = createRef<HTMLDivElement>() as { current: HTMLDivElement | null }
+  editorRef.current = editor
+
+  const draftRef = { current: composerPlainText(editor) }
+
+  const adapter: Unstable_TriggerAdapter = {
+    categories: () => [],
+    categoryItems: () => [],
+    search: () => items
+  }
+
+  const setComposerText = vi.fn()
+
+  const hook = renderHook(() =>
+    useComposerTrigger({
+      at: { adapter: null, loading: false },
+      draftRef,
+      editorRef,
+      requestMainFocus: vi.fn(),
+      setComposerText,
+      slash: { adapter, loading: false }
+    })
+  )
+
+  return { draftRef, hook, setComposerText }
+}
+
+describe('useComposerTrigger — slash anywhere in the prompt', () => {
+  it('opens the completion list for a slash typed mid-message', () => {
+    const editor = mountEditor('please run /cle')
+    const { hook } = mountTrigger(editor, [item('/clean')])
+
+    act(() => hook.result.current.refreshTrigger())
+
+    expect(hook.result.current.trigger).toMatchObject({ kind: '/', inline: true, query: 'cle' })
+    expect(hook.result.current.triggerItems).toHaveLength(1)
+  })
+
+  it('inserts the picked skill inline and keeps the surrounding prose intact', () => {
+    const editor = mountEditor('please run /cle')
+    const { hook } = mountTrigger(editor, [item('/clean')])
+
+    act(() => hook.result.current.refreshTrigger())
+    act(() => hook.result.current.replaceTriggerWithChip(item('/clean')))
+
+    // The `/cle` the user typed is replaced by the full command; "please run"
+    // in front of it survives untouched.
+    expect(composerPlainText(editor)).toBe('please run /clean ')
+  })
+
+  it('offers only skills mid-message, not app commands', () => {
+    // `/model` and `/new` act on the app — meaningless as a reference in prose.
+    const editor = mountEditor('please run /')
+    const { hook } = mountTrigger(editor, [item('/clean'), item('/model', 'Commands'), item('/new', 'Commands')])
+
+    act(() => hook.result.current.refreshTrigger())
+
+    expect(hook.result.current.triggerItems.map(i => i.label)).toEqual(['clean'])
+  })
+
+  it('still offers the full command set at the start of the prompt', () => {
+    const editor = mountEditor('/')
+    const { hook } = mountTrigger(editor, [item('/clean'), item('/model', 'Commands')])
+
+    act(() => hook.result.current.refreshTrigger())
+
+    expect(hook.result.current.triggerItems.map(i => i.label)).toEqual(['clean', 'model'])
+  })
+
+  it('still opens the list for a slash at the start of the prompt', () => {
+    const editor = mountEditor('/cle')
+    const { hook } = mountTrigger(editor, [item('/clean')])
+
+    act(() => hook.result.current.refreshTrigger())
+
+    expect(hook.result.current.trigger).toMatchObject({ kind: '/', query: 'cle' })
+    expect(hook.result.current.trigger?.inline).toBeUndefined()
+  })
+
+  it('leaves a mid-message file path alone', () => {
+    const editor = mountEditor('open src/foo/bar')
+    const { hook } = mountTrigger(editor, [item('/clean')])
+
+    act(() => hook.result.current.refreshTrigger())
+
+    expect(hook.result.current.trigger).toBeNull()
+  })
+})
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.ts
index 20abc03309f..3c22fddb634 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.ts
@@ -4,7 +4,13 @@ import { type MutableRefObject, type RefObject, useCallback, useEffect, useRef,
 import { hermesDirectiveFormatter } from '@/components/assistant-ui/directive-text'
 import { desktopSlashCommandTakesArgs } from '@/lib/desktop-slash-commands'
 
-import { COMPLETION_ACTIONS, slashArgStage, slashChipKindForItem, slashCommandToken } from '../composer-utils'
+import {
+  COMPLETION_ACTIONS,
+  isSkillItem,
+  slashArgStage,
+  slashChipKindForItem,
+  slashCommandToken
+} from '../composer-utils'
 import {
   composerPlainText,
   placeCaretEnd,
@@ -112,7 +118,13 @@ export function useComposerTrigger({
       return
     }
 
-    setTriggerItems(triggerAdapter.search(trigger.query))
+    const items = triggerAdapter.search(trigger.query)
+
+    // Mid-message only offers SKILLS. A built-in like `/model` or `/new` acts
+    // on the app, so it's meaningless as a reference inside prose — only a
+    // skill reads as "handle this part with X". Filtering here rather than in
+    // the fetcher keeps one completion source for both shapes.
+    setTriggerItems(trigger.inline ? items.filter(isSkillItem) : items)
   }, [trigger, triggerAdapter])
 
   const triggerLoading = trigger?.kind === '@' ? at.loading : trigger?.kind === '/' ? slash.loading : false
@@ -191,10 +203,13 @@ export function useComposerTrigger({
     // Picking a bare arg-taking command (e.g. `/personality`) shouldn't commit
     // it — expand to its options step so the popover shows the inline list, just
     // as typing `/personality ` by hand would. A serialized value with a space is
-    // already an arg pick (`/personality alice`), so it commits normally.
+    // already an arg pick (`/personality alice`), so it commits normally. An
+    // inline (mid-message) pick never expands: it's a reference inside prose, so
+    // there's no command invocation for the args to belong to.
     const command = (item.metadata as { command?: string } | undefined)?.command ?? ''
 
-    const expandsToArgs = trigger.kind === '/' && !serialized.includes(' ') && desktopSlashCommandTakesArgs(command)
+    const expandsToArgs =
+      trigger.kind === '/' && !trigger.inline && !serialized.includes(' ') && desktopSlashCommandTakesArgs(command)
 
     const text = starter || serialized.endsWith(' ') ? serialized : `${serialized} `
     const directive = !starter && serialized.match(/^@([^:]+):(.+)$/)
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-live-completion-adapter.ts b/apps/desktop/src/app/chat/composer/hooks/use-live-completion-adapter.ts
index 6da699b602a..32301cc8294 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-live-completion-adapter.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-live-completion-adapter.ts
@@ -49,6 +49,7 @@ export function useLiveCompletionAdapter(options: {
 
   useEffect(() => () => cancelTimer(), [cancelTimer])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (enabled) {
       return
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-popout-drag.ts b/apps/desktop/src/app/chat/composer/hooks/use-popout-drag.ts
index 0b71507bfd1..79e1cc067da 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-popout-drag.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-popout-drag.ts
@@ -231,6 +231,7 @@ export function useComposerPopoutGestures({
     [clearTimer, poppedOut]
   )
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     // Coalesce drag updates to one per frame — pointermove can fire several times
     // between paints on high-Hz mice, and each update re-renders + clamps.
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-voice-conversation.ts b/apps/desktop/src/app/chat/composer/hooks/use-voice-conversation.ts
index 2ec43c83c0b..33285f05aa1 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-voice-conversation.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-voice-conversation.ts
@@ -60,18 +60,22 @@ export function useVoiceConversation({
   const statusRef = useRef<ConversationStatus>('idle')
   const wasEnabledRef = useRef(enabled)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     enabledRef.current = enabled
   }, [enabled])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     mutedRef.current = muted
   }, [muted])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     busyRef.current = busy
   }, [busy])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     statusRef.current = status
   }, [status])
@@ -508,6 +512,7 @@ export function useVoiceConversation({
   // Drive the loop: when a voice-submitted reply appears, open a live speech
   // session (which feeds itself from then on). Otherwise start listening when
   // idle between turns.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!enabled || muted) {
       return
@@ -542,6 +547,7 @@ export function useVoiceConversation({
     }
   }, [busy, enabled, muted, openLiveSpeech, pendingResponse, startListening, status])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (enabled && !wasEnabledRef.current) {
       void start()
diff --git a/apps/desktop/src/app/chat/composer/model-pill.tsx b/apps/desktop/src/app/chat/composer/model-pill.tsx
index b5a6e976805..2a26db4094c 100644
--- a/apps/desktop/src/app/chat/composer/model-pill.tsx
+++ b/apps/desktop/src/app/chat/composer/model-pill.tsx
@@ -11,7 +11,7 @@ import { useI18n } from '@/i18n'
 import { ChevronDown } from '@/lib/icons'
 import { formatModelStatusLabel } from '@/lib/model-status-label'
 import { cn } from '@/lib/utils'
-import { $currentModelSource, setModelPickerOpen } from '@/store/session'
+import { $currentModelSource, $defaultReasoningEffort, setModelPickerOpen } from '@/store/session'
 
 import type { ChatBarState } from './types'
 
@@ -48,6 +48,7 @@ export function ModelPill({
   const fastMode = useStore(view.$fast)
   const reasoningEffort = useStore(view.$reasoningEffort)
   const modelSource = useStore($currentModelSource)
+  const defaultEffort = useStore($defaultReasoningEffort)
   const runtimeId = useStore(view.$runtimeId)
   const [open, setOpen] = useState(false)
 
@@ -68,7 +69,9 @@ export function ModelPill({
   ) : (
     <>
       {currentModel.trim() ? (
-        <span className="truncate">{formatModelStatusLabel(currentModel, { fastMode, reasoningEffort })}</span>
+        <span className="truncate">
+          {formatModelStatusLabel(currentModel, { defaultEffort, fastMode, reasoningEffort })}
+        </span>
       ) : (
         <GlyphSpinner className="opacity-50" spinner="braille" />
       )}
diff --git a/apps/desktop/src/app/chat/composer/rich-editor.ts b/apps/desktop/src/app/chat/composer/rich-editor.ts
index 71491b87496..21f0286c9f8 100644
--- a/apps/desktop/src/app/chat/composer/rich-editor.ts
+++ b/apps/desktop/src/app/chat/composer/rich-editor.ts
@@ -15,6 +15,7 @@ import {
   type SlashChipKind,
   slashIconElement
 } from '@/components/assistant-ui/directive-text'
+import { sessionRefFallbackLabel } from '@/lib/session-refs'
 
 export const RICH_INPUT_SLOT = 'composer-rich-input'
 
@@ -59,7 +60,9 @@ export function refChipHtml(kind: string, rawValue: string, displayLabel?: strin
   const id = unquoteRef(rawValue)
   const text = `@${kind}:${quoteRefValue(id)}`
 
-  return `<span contenteditable="false" data-ref-text="${escapeHtml(text)}" data-ref-id="${escapeHtml(id)}" data-ref-kind="${escapeHtml(kind)}" class="${DIRECTIVE_CHIP_CLASS}">${directiveIconSvg(kind)}<span class="truncate">${escapeHtml(displayLabel || refLabel(id))}</span></span>`
+  const label = displayLabel || (kind === 'session' ? sessionRefFallbackLabel(id) : refLabel(id))
+
+  return `<span contenteditable="false" data-ref-text="${escapeHtml(text)}" data-ref-id="${escapeHtml(id)}" data-ref-kind="${escapeHtml(kind)}" class="${DIRECTIVE_CHIP_CLASS}">${directiveIconSvg(kind)}<span class="truncate">${escapeHtml(label)}</span></span>`
 }
 
 export function refChipElement(kind: string, rawValue: string, displayLabel?: string) {
@@ -74,7 +77,7 @@ export function refChipElement(kind: string, rawValue: string, displayLabel?: st
   chip.dataset.refKind = kind
   chip.className = DIRECTIVE_CHIP_CLASS
   label.className = 'truncate'
-  label.textContent = displayLabel || refLabel(id)
+  label.textContent = displayLabel || (kind === 'session' ? sessionRefFallbackLabel(id) : refLabel(id))
   chip.append(directiveIconElement(kind), label)
 
   return chip
diff --git a/apps/desktop/src/app/chat/composer/status-stack/coding-row.tsx b/apps/desktop/src/app/chat/composer/status-stack/coding-row.tsx
index aee735e4aea..5093658af88 100644
--- a/apps/desktop/src/app/chat/composer/status-stack/coding-row.tsx
+++ b/apps/desktop/src/app/chat/composer/status-stack/coding-row.tsx
@@ -91,6 +91,7 @@ export const CodingStatusRow = memo(function CodingStatusRow({
   const worktreeReq = useStore($newWorktreeRequest)
   const lastWorktreeReqRef = useRef(worktreeReq)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (worktreeReq === lastWorktreeReqRef.current) {
       return
diff --git a/apps/desktop/src/app/chat/composer/status-stack/index.tsx b/apps/desktop/src/app/chat/composer/status-stack/index.tsx
index 739080be8b8..10b7a0776bf 100644
--- a/apps/desktop/src/app/chat/composer/status-stack/index.tsx
+++ b/apps/desktop/src/app/chat/composer/status-stack/index.tsx
@@ -3,6 +3,7 @@ import { type ReactNode, useEffect, useLayoutEffect, useMemo, useRef } from 'rea
 import { useNavigate } from 'react-router-dom'
 
 import { blurComposerInput } from '@/app/chat/composer/focus'
+import { clearSurfaceVar, setSurfaceVar, STATUS_STACK_VAR } from '@/app/chat/surface-vars'
 import { AGENTS_ROUTE } from '@/app/routes'
 import { BillingBanner } from '@/components/billing-banner'
 import { composerDockCard } from '@/components/chat/composer-dock'
@@ -197,12 +198,12 @@ export function ComposerStatusStack({ queue, sessionId }: ComposerStatusStackPro
   // height never sees it. Publish our own measured height — bucketed like the
   // composer's, to avoid style invalidation churn — so the thread's
   // last-message clearance can add it and the stack never hides messages.
+  // Scoped to THIS surface: tiles render their own stack (see surface-vars.ts).
   useLayoutEffect(() => {
-    const root = document.documentElement
     const el = stackRef.current
 
     if (!visible || !el) {
-      root.style.removeProperty('--status-stack-measured-height')
+      clearSurfaceVar(el, STATUS_STACK_VAR)
 
       return
     }
@@ -214,7 +215,7 @@ export function ComposerStatusStack({ queue, sessionId }: ComposerStatusStackPro
 
       if (bucket !== last) {
         last = bucket
-        root.style.setProperty('--status-stack-measured-height', `${bucket}px`)
+        setSurfaceVar(el, STATUS_STACK_VAR, `${bucket}px`)
       }
     }
 
@@ -224,7 +225,7 @@ export function ComposerStatusStack({ queue, sessionId }: ComposerStatusStackPro
 
     return () => {
       observer.disconnect()
-      root.style.removeProperty('--status-stack-measured-height')
+      clearSurfaceVar(el, STATUS_STACK_VAR)
     }
   }, [visible])
 
diff --git a/apps/desktop/src/app/chat/composer/text-utils.test.ts b/apps/desktop/src/app/chat/composer/text-utils.test.ts
index 6c6a20780f6..ca2ac803576 100644
--- a/apps/desktop/src/app/chat/composer/text-utils.test.ts
+++ b/apps/desktop/src/app/chat/composer/text-utils.test.ts
@@ -44,14 +44,25 @@ describe('detectTrigger', () => {
   it('does not treat file-style paths as slash triggers', () => {
     expect(detectTrigger('src/foo/bar')).toBeNull()
     expect(detectTrigger('/path/to/file')).toBeNull()
+    // Mid-message paths stay excluded too: a path keeps going past the command
+    // token, so the trailing-anchored inline trigger never matches it.
+    expect(detectTrigger('check src/foo/bar')).toBeNull()
+    expect(detectTrigger('look at /usr/local/bin')).toBeNull()
+    expect(detectTrigger('and/or')).toBeNull()
   })
 
-  it('does not trigger slash popover mid-message', () => {
-    expect(detectTrigger('hello /')).toBeNull()
-    expect(detectTrigger('hello /skill')).toBeNull()
+  it('treats a mid-message slash as an inline reference', () => {
+    // Skills have to be reachable anywhere in a prompt, not just at position 0.
+    expect(detectTrigger('hello /')).toEqual({ kind: '/', inline: true, query: '', tokenLength: 1 })
+    expect(detectTrigger('hello /clean')).toEqual({ kind: '/', inline: true, query: 'clean', tokenLength: 6 })
+    expect(detectTrigger('text\n/skill')).toEqual({ kind: '/', inline: true, query: 'skill', tokenLength: 6 })
+  })
+
+  it('does not carry arg completion into an inline slash reference', () => {
+    // Only a position-0 slash is a real invocation, so `/personality alic`
+    // mid-message is prose — the trigger ends at the command token.
     expect(detectTrigger('hello there /personality alic')).toBeNull()
-    expect(detectTrigger('text\n/skill')).toBeNull()
-    expect(detectTrigger('multi word message /')).toBeNull()
+    expect(detectTrigger('run /tools enable foo')).toBeNull()
   })
 
   it('still anchors at-mention triggers strictly at the token edge', () => {
diff --git a/apps/desktop/src/app/chat/composer/text-utils.ts b/apps/desktop/src/app/chat/composer/text-utils.ts
index b9b6adc07f1..8bc6663210e 100644
--- a/apps/desktop/src/app/chat/composer/text-utils.ts
+++ b/apps/desktop/src/app/chat/composer/text-utils.ts
@@ -1,22 +1,35 @@
 import { DATA_IMAGE_URL_RE, dataUrlToBlob } from '@/lib/embedded-images'
 
 export interface TriggerState {
+  /** True for a `/` typed mid-message — an inline skill/command reference in
+   *  prose rather than a command invocation. Arg completion doesn't apply. */
+  inline?: boolean
   kind: '@' | '/'
   query: string
   tokenLength: number
 }
 
 // `@` triggers stop at the first whitespace — `@file:path` and `@diff` are
-// single tokens. `/` triggers keep going so the popover stays live while the
-// user types args (`/personality alic` → arg completer suggests `alice`).
-// Restricting the slash command name to `[a-zA-Z][\w-]*` avoids matching file
-// paths like `src/foo/bar`.
+// single tokens. Restricting the slash command name to `[a-zA-Z][\w-]*` avoids
+// matching file paths like `src/foo/bar`.
 //
-// Slash commands only execute at the beginning of a message, so the `/`
-// trigger is anchored strictly at position 0 — not after whitespace — to
-// avoid opening the popover mid-message (e.g. `hello /`).
+// `/` triggers fire in two shapes, because a slash means two different things
+// depending on where it sits:
+//
+//  - At position 0 it's a COMMAND invocation the app executes (SLASH_COMMAND_RE
+//    is `^`-anchored, and so is the backend's). The popover stays live past the
+//    command name so arg completion works (`/personality alic` → `alice`).
+//  - After whitespace it's an inline REFERENCE the user is dropping into prose
+//    ("clean this up with /clean"). The text submits as an ordinary message, so
+//    there are no args to complete — the trigger is a single token that ends at
+//    the next space, exactly like `@`.
+//
+// The inline shape is what makes skills reachable anywhere in a prompt. Both
+// shapes need the trailing `$`: detection runs against the text BEFORE the
+// caret, so the match must end where the user is typing.
 const AT_TRIGGER_RE = /(?:^|[\s])(@)([^\s@/]*)$/
-const SLASH_TRIGGER_RE = /^(\/)((?:[a-zA-Z][\w-]*(?:\s+\S*)*)?)$/
+const SLASH_COMMAND_TRIGGER_RE = /^(\/)((?:[a-zA-Z][\w-]*(?:\s+\S*)*)?)$/
+const SLASH_INLINE_TRIGGER_RE = /[\s](\/)([a-zA-Z][\w-]*)?$/
 
 /** Stable key for paste dedupe — `items` and `files` often mirror the same image as different objects. */
 export function blobDedupeKey(blob: Blob): string {
@@ -107,10 +120,20 @@ export function textBeforeCaret(editor: HTMLDivElement): string | null {
 }
 
 export function detectTrigger(textBefore: string): TriggerState | null {
-  const slash = SLASH_TRIGGER_RE.exec(textBefore)
+  const command = SLASH_COMMAND_TRIGGER_RE.exec(textBefore)
 
-  if (slash) {
-    return { kind: '/', query: slash[2], tokenLength: 1 + slash[2].length }
+  if (command) {
+    return { kind: '/', query: command[2], tokenLength: 1 + command[2].length }
+  }
+
+  // An inline `/skill` is a reference dropped into prose, so it carries no args
+  // and the whole match is the token the chip replaces.
+  const inline = SLASH_INLINE_TRIGGER_RE.exec(textBefore)
+
+  if (inline) {
+    const query = inline[2] ?? ''
+
+    return { inline: true, kind: '/', query, tokenLength: 1 + query.length }
   }
 
   const at = AT_TRIGGER_RE.exec(textBefore)
diff --git a/apps/desktop/src/app/chat/hooks/use-file-drop-zone.ts b/apps/desktop/src/app/chat/hooks/use-file-drop-zone.ts
index 42e4554b992..186c226b84a 100644
--- a/apps/desktop/src/app/chat/hooks/use-file-drop-zone.ts
+++ b/apps/desktop/src/app/chat/hooks/use-file-drop-zone.ts
@@ -44,6 +44,7 @@ export function useFileDropZone({ enabled = true, onDropFiles }: FileDropZoneOpt
   // DnD can't be cancelled at the OS level, so we drop the overlay and arm a
   // guard that swallows the trailing drop instead. Top escape layer + capture
   // stop so it doesn't also fire a handler behind the drag (see drag-session).
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (dragKind === null) {
       return
diff --git a/apps/desktop/src/app/chat/index.tsx b/apps/desktop/src/app/chat/index.tsx
index bd18be0c483..5fdf5a0487b 100644
--- a/apps/desktop/src/app/chat/index.tsx
+++ b/apps/desktop/src/app/chat/index.tsx
@@ -1,14 +1,16 @@
 import { type AppendMessage, AssistantRuntimeProvider, type ThreadMessage } from '@assistant-ui/react'
 import { useStore } from '@nanostores/react'
 import { useQuery } from '@tanstack/react-query'
+import type { ReadableAtom } from 'nanostores'
 import type * as React from 'react'
-import { Suspense, useCallback, useEffect, useMemo } from 'react'
+import { Suspense, useCallback, useEffect, useMemo, useState } from 'react'
 import { useLocation } from 'react-router-dom'
 
 import type { SubmitTextOptions } from '@/app/session/hooks/use-prompt-actions/utils'
 import { Thread } from '@/components/assistant-ui/thread'
 import { Backdrop } from '@/components/Backdrop'
 import { COMPOSER_HEART_CONFIG, HeartField } from '@/components/chat/vibe-hearts'
+import { usePaneVisible } from '@/components/pane-shell/pane-visibility'
 import { $sessionTileDragging, $sessionTileEdgeHover } from '@/components/pane-shell/tree/store'
 import { PromptOverlays } from '@/components/prompt-overlays'
 import { Button } from '@/components/ui/button'
@@ -42,7 +44,7 @@ import {
 import { isSecondaryWindow, isWatchWindow } from '@/store/windows'
 import type { ModelOptionsResponse } from '@/types/hermes'
 
-import { routeSessionId } from '../routes'
+import { primaryRouteSelectedSessionId, routeSessionId } from '../routes'
 import { titlebarHeaderBaseClass, titlebarHeaderShadowClass, titlebarHeaderTitleClass } from '../shell/titlebar'
 
 import { ChatDropOverlay } from './chat-drop-overlay'
@@ -174,6 +176,30 @@ interface ChatRuntimeBoundaryProps {
 
 const NO_MESSAGES: ChatMessage[] = []
 
+/**
+ * The view's $messages, live only while this surface is the VISIBLE tab.
+ *
+ * Keep-alive keeps every ever-active tab MOUNTED (tree-group.tsx), so without
+ * this gate a hidden tab re-renders its entire thread on every streaming
+ * delta flush (~30×/s) — five busy tabs quintuple the per-token render cost
+ * and the app crawls. Hidden tabs freeze their transcript instead (status
+ * dots stay live through the separate status atoms) and catch up in one
+ * commit on reveal — the subscribe fires immediately with the current value.
+ */
+function useMessagesWhileVisible($messages: ReadableAtom<ChatMessage[]>): ChatMessage[] {
+  const visible = usePaneVisible()
+  const [messages, setMessages] = useState(() => $messages.get())
+
+  // nanostores types the listener value ReadonlyIfObject; the store publishes
+  // a fresh array per flush, so the cast is safe and avoids a per-token clone.
+  useEffect(
+    () => (visible ? $messages.subscribe(value => setMessages(value as ChatMessage[])) : undefined),
+    [$messages, visible]
+  )
+
+  return messages
+}
+
 /**
  * Owns the $messages subscription and the assistant-ui external-store runtime.
  *
@@ -193,7 +219,7 @@ function ChatRuntimeBoundary({
   onThreadMessagesChange,
   suppressMessages
 }: ChatRuntimeBoundaryProps) {
-  const storeMessages = useStore(useSessionView().$messages)
+  const storeMessages = useMessagesWhileVisible(useSessionView().$messages)
   const messages = suppressMessages ? NO_MESSAGES : storeMessages
   const runtimeMessageRepository = useRuntimeMessageRepository(messages)
 
@@ -285,11 +311,18 @@ export function ChatView({
   const resumeExhaustedSessionId = useStore($resumeExhaustedSessionId)
 
   // Durable composer/queue scope (lineage root) so auto-compression tip rotation
-  // does not wipe an in-progress draft or orphan /queue entries.
-  const queueSessionKey = useMemo(
-    () => resolveComposerSessionKey(selectedSessionId, sessions),
-    [selectedSessionId, sessions]
-  )
+  // does not wipe an in-progress draft or orphan /queue entries. For the
+  // primary view, the route is authoritative over the store selection — the
+  // latter can be momentarily null/stale mid-switch, which used to leak into
+  // the composer's scope key (#59305). A tile has no route, so it always uses
+  // its own selection directly.
+  const queueSessionKey = useMemo(() => {
+    const effectiveSelectedSessionId = isPrimary
+      ? primaryRouteSelectedSessionId(location.pathname, selectedSessionId)
+      : selectedSessionId
+
+    return resolveComposerSessionKey(effectiveSelectedSessionId, sessions)
+  }, [isPrimary, location.pathname, selectedSessionId, sessions])
 
   // When the tip row arrives after compression, migrate any tip-keyed stash onto
   // the durable lineage key before the composer remounts onto that key.
@@ -437,6 +470,7 @@ export function ChatView({
         'relative isolate flex h-full min-w-0 flex-col overflow-hidden bg-(--ui-chat-surface-background)',
         className
       )}
+      data-chat-surface=""
       data-composer-target={composerScope.target}
       data-session-anchor={sessionAnchor}
     >
diff --git a/apps/desktop/src/app/chat/right-rail/preview-console.tsx b/apps/desktop/src/app/chat/right-rail/preview-console.tsx
index 67df7fefc2f..35001ab0029 100644
--- a/apps/desktop/src/app/chat/right-rail/preview-console.tsx
+++ b/apps/desktop/src/app/chat/right-rail/preview-console.tsx
@@ -166,6 +166,7 @@ export function PreviewConsolePanel({
   const sendableLogs = visibleSelection.length > 0 ? visibleSelection : logs
   const stickScrollRafRef = useRef<number | null>(null)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!consoleShouldStickRef.current) {
       return
diff --git a/apps/desktop/src/app/chat/right-rail/preview-file.tsx b/apps/desktop/src/app/chat/right-rail/preview-file.tsx
index 13a20f61d62..a4eab020f69 100644
--- a/apps/desktop/src/app/chat/right-rail/preview-file.tsx
+++ b/apps/desktop/src/app/chat/right-rail/preview-file.tsx
@@ -591,6 +591,7 @@ export function LocalFilePreview({ reloadKey, target }: { reloadKey: number; tar
   const filePath = filePathForTarget(target)
   const isImage = target.previewKind === 'image'
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     setUserMode(null)
     setEditing(false)
diff --git a/apps/desktop/src/app/chat/right-rail/preview-pane.tsx b/apps/desktop/src/app/chat/right-rail/preview-pane.tsx
index f240c4b2067..9c8e4caf9ca 100644
--- a/apps/desktop/src/app/chat/right-rail/preview-pane.tsx
+++ b/apps/desktop/src/app/chat/right-rail/preview-pane.tsx
@@ -319,6 +319,7 @@ export function PreviewPane({
     return () => setTitlebarToolGroup(TITLEBAR_GROUP_ID, [])
   }, [consoleOpen, consoleState, copy, devtoolsOpen, isWebPreview, setTitlebarToolGroup, toggleDevTools])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!consoleOpen) {
       return
@@ -334,6 +335,7 @@ export function PreviewPane({
     return () => window.cancelAnimationFrame(handle)
   }, [consoleOpen])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (
       !previewServerRestart ||
@@ -392,6 +394,7 @@ export function PreviewPane({
     return () => window.clearTimeout(timer)
   }, [copy.stillWorking, previewServerRestart, restartingServer])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (reloadRequest === lastReloadRequestRef.current) {
       return
@@ -498,6 +501,7 @@ export function PreviewPane({
     }
   }, [appendConsoleEntry, copy, reloadPreview, target.kind, target.url])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const host = hostRef.current
 
diff --git a/apps/desktop/src/app/chat/runtime-repository.ts b/apps/desktop/src/app/chat/runtime-repository.ts
index 9dc94d42114..3dad84dac13 100644
--- a/apps/desktop/src/app/chat/runtime-repository.ts
+++ b/apps/desktop/src/app/chat/runtime-repository.ts
@@ -1,14 +1,27 @@
-import { ExportedMessageRepository, type ThreadMessage } from '@assistant-ui/react'
+import { fromThreadMessageLike, getAutoStatus } from '@assistant-ui/core/internal'
+import type { ExportedMessageRepository, ThreadMessage } from '@assistant-ui/react'
 import { useMemo, useRef } from 'react'
 
 import type { ChatMessage } from '@/lib/chat-messages'
 import { coalesceToolOnlyAssistants, createToolMergeCache, toRuntimeMessage } from '@/lib/chat-runtime'
 
+// The exact fallback status ExportedMessageRepository.fromBranchableArray uses.
+// Normalization happens HERE, once per message, so the cached record below is
+// already the final ThreadMessage the runtime consumes.
+const FALLBACK_STATUS = getAutoStatus(false, false, false, false, undefined)
+
 /**
  * ChatMessage[] -> assistant-ui message repository, with a WeakMap identity
  * cache so unchanged messages convert once (and a tool-merge cache that folds
  * tool-only assistant turns into their neighbour). Shared by the main chat's
  * runtime boundary and session tiles — one transcript pipeline, N surfaces.
+ *
+ * The cache stores NORMALIZED messages. `fromBranchableArray` maps the whole
+ * array through `fromThreadMessageLike` on every call, so building the export
+ * with it threw away the cache's reference identity once per streamed delta —
+ * re-normalizing the entire settled transcript ~30x/s. Normalizing inside the
+ * cache miss keeps identity stable for settled turns, which is what lets the
+ * runtime reconcile detect that only the tail moved.
  */
 export function useRuntimeMessageRepository(messages: ChatMessage[]): ExportedMessageRepository {
   const cacheRef = useRef(new WeakMap<ChatMessage, ThreadMessage>())
@@ -32,7 +45,9 @@ export function useRuntimeMessageRepository(messages: ChatMessage[]): ExportedMe
       }
 
       const cachedMessage = cacheRef.current.get(message)
-      const runtimeMessage = cachedMessage ?? toRuntimeMessage(message)
+
+      const runtimeMessage =
+        cachedMessage ?? fromThreadMessageLike(toRuntimeMessage(message), message.id, FALLBACK_STATUS)
 
       if (!cachedMessage) {
         cacheRef.current.set(message, runtimeMessage)
@@ -46,6 +61,6 @@ export function useRuntimeMessageRepository(messages: ChatMessage[]): ExportedMe
       }
     }
 
-    return ExportedMessageRepository.fromBranchableArray(items, { headId })
+    return { headId, messages: items }
   }, [messages])
 }
diff --git a/apps/desktop/src/app/chat/session-drag.test.ts b/apps/desktop/src/app/chat/session-drag.test.ts
new file mode 100644
index 00000000000..5e4b7955ee5
--- /dev/null
+++ b/apps/desktop/src/app/chat/session-drag.test.ts
@@ -0,0 +1,113 @@
+import type { PointerEvent as ReactPointerEvent } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { group } from '@/components/pane-shell/tree/model'
+import { $layoutTree } from '@/components/pane-shell/tree/store'
+import { openSessionTile } from '@/store/session-states'
+
+import { requestComposerInsertRefs } from './composer/focus'
+import { startSessionDrag } from './session-drag'
+
+/**
+ * A session drop resolves its target by rect-testing the chat surfaces in the
+ * document. A tab group keeps inactive tabs MOUNTED with their layout box
+ * intact, so a background tab's rect is identical to the foreground tab's —
+ * the drop has to land on the tab the user can actually see.
+ */
+
+vi.mock('@/store/session-states', () => ({ openSessionTile: vi.fn() }))
+vi.mock('./composer/focus', () => ({ requestComposerInsertRefs: vi.fn() }))
+
+const ZONE = { left: 0, top: 0, right: 1000, bottom: 800 }
+const COMPOSER = { left: 100, top: 700, right: 900, bottom: 780 }
+
+const stubRect = (el: Element, box: { left: number; top: number; right: number; bottom: number }) => {
+  el.getBoundingClientRect = () =>
+    ({ ...box, width: box.right - box.left, height: box.bottom - box.top, x: box.left, y: box.top }) as DOMRect
+}
+
+/** The workspace tab kept alive behind an active session tile tab. */
+function mountStackedTabs() {
+  document.body.innerHTML = `
+    <div data-tree-group="g1">
+      <div data-pane-hidden>
+        <div data-session-anchor="workspace" data-composer-target="main">
+          <div data-slot="composer-root"></div>
+        </div>
+      </div>
+      <div>
+        <div data-session-anchor="session-tile:visible" data-composer-target="tile:visible">
+          <div data-slot="composer-root"></div>
+        </div>
+      </div>
+    </div>
+    <div id="row"></div>
+  `
+
+  stubRect(document.querySelector('[data-tree-group]')!, ZONE)
+
+  for (const surface of document.querySelectorAll('[data-session-anchor]')) {
+    stubRect(surface, ZONE)
+  }
+
+  for (const composer of document.querySelectorAll('[data-slot="composer-root"]')) {
+    stubRect(composer, COMPOSER)
+  }
+
+  $layoutTree.set(group(['workspace', 'session-tile:visible'], { id: 'g1' }))
+
+  return document.getElementById('row')!
+}
+
+/** Press on `source`, drag to (x, y), release. The drag session flushes its
+ *  pending move synchronously on release, so no frame wait is needed. */
+function dragTo(source: HTMLElement, x: number, y: number) {
+  startSessionDrag({ id: 'dragged', profile: 'default', title: 'Dragged chat' }, {
+    button: 0,
+    clientX: 0,
+    clientY: 0,
+    currentTarget: source,
+    pointerId: 1
+  } as unknown as ReactPointerEvent<HTMLElement>)
+
+  window.dispatchEvent(new MouseEvent('pointermove', { bubbles: true, clientX: x, clientY: y }))
+  window.dispatchEvent(new MouseEvent('pointerup', { bubbles: true, clientX: x, clientY: y }))
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+afterEach(() => {
+  document.body.innerHTML = ''
+  $layoutTree.set(null)
+})
+
+describe('session drop targeting across stacked tabs', () => {
+  it('links into the visible tab’s composer, not the tab kept alive behind it', () => {
+    const row = mountStackedTabs()
+
+    dragTo(row, 500, 740)
+
+    expect(requestComposerInsertRefs).toHaveBeenCalledWith(expect.anything(), { target: 'tile:visible' })
+  })
+
+  it('docks a split against the visible tab’s pane', () => {
+    const row = mountStackedTabs()
+
+    dragTo(row, 980, 400)
+
+    expect(openSessionTile).toHaveBeenCalledWith('dragged', 'right', 'session-tile:visible', undefined)
+    expect(requestComposerInsertRefs).not.toHaveBeenCalled()
+  })
+
+  it('commits nothing over a zone that hosts no chat surface', () => {
+    mountStackedTabs()
+    $layoutTree.set(group(['terminal'], { id: 'g1' }))
+
+    dragTo(document.getElementById('row')!, 500, 740)
+
+    expect(requestComposerInsertRefs).not.toHaveBeenCalled()
+    expect(openSessionTile).not.toHaveBeenCalled()
+  })
+})
diff --git a/apps/desktop/src/app/chat/session-drag.ts b/apps/desktop/src/app/chat/session-drag.ts
index f99bfa47325..b4ca62802de 100644
--- a/apps/desktop/src/app/chat/session-drag.ts
+++ b/apps/desktop/src/app/chat/session-drag.ts
@@ -27,6 +27,7 @@
 
 import type { PointerEvent as ReactPointerEvent } from 'react'
 
+import { queryAllVisible } from '@/components/pane-shell/pane-visibility'
 import { findGroup } from '@/components/pane-shell/tree/model'
 import {
   type DoubleTapContext,
@@ -66,8 +67,11 @@ const snapRect = (el: HTMLElement): ZoneRect => {
   return { left: r.left, top: r.top, right: r.right, bottom: r.bottom }
 }
 
+/** Chat surfaces the pointer can land on. Inactive tabs are excluded: they stay
+ *  mounted with their layout box intact, so their rect is identical to the
+ *  visible tab's and a hit-test alone would pick whichever came first. */
 function snapshotSurfaces(): SurfaceSnapshot[] {
-  return [...document.querySelectorAll<HTMLElement>('[data-session-anchor]')].map(el => ({
+  return queryAllVisible('[data-session-anchor]').map(el => ({
     anchor: el.dataset.sessionAnchor || 'workspace',
     composerTarget: el.dataset.composerTarget || 'main',
     rect: snapRect(el)
@@ -123,7 +127,7 @@ export function startSessionDrag(
       zones = snapshotZones()
       strips = snapshotStrips()
       surfaces = snapshotSurfaces()
-      composers = [...document.querySelectorAll<HTMLElement>('[data-slot="composer-root"]')].map(snapRect)
+      composers = queryAllVisible('[data-slot="composer-root"]').map(snapRect)
       zoneHost = new Map(zones.map(zone => [zone.id, chatZonePane(zone.id)]))
       source?.style.setProperty('opacity', '0.45')
       // The same sentinel the zone overlay + chat surfaces key off — the
diff --git a/apps/desktop/src/app/chat/session-tile-actions.ts b/apps/desktop/src/app/chat/session-tile-actions.ts
index 4eca47f5c09..912878e53b0 100644
--- a/apps/desktop/src/app/chat/session-tile-actions.ts
+++ b/apps/desktop/src/app/chat/session-tile-actions.ts
@@ -24,10 +24,12 @@ import { resetSessionBackground } from '@/store/composer-status'
 import { notifyError } from '@/store/notifications'
 import { clearPreviewArtifacts } from '@/store/preview-status'
 import { clearAllPrompts } from '@/store/prompts'
-import { $connection } from '@/store/session'
+import { $connection, $sessions, sessionMatchesStoredId } from '@/store/session'
 import { $sessionStates, sessionTileDelegate } from '@/store/session-states'
+import { broadcastSessionsChanged } from '@/store/session-sync'
 import { clearSessionSubagents } from '@/store/subagents'
 import { clearSessionTodos } from '@/store/todos'
+import type { SessionInfo } from '@/types/hermes'
 
 import { uploadComposerAttachment } from '../session/hooks/use-prompt-actions'
 import {
@@ -38,13 +40,54 @@ import {
   planEdit,
   planReload,
   planRestore,
-  runRewindSubmit
+  runRewindSubmit,
+  truncateSubmitParams
 } from '../session/hooks/use-prompt-actions/rewind'
 import { useSubmitPrompt } from '../session/hooks/use-prompt-actions/submit'
 import { type SubmitTextOptions } from '../session/hooks/use-prompt-actions/utils'
+import { upsertOptimisticSession } from '../session/hooks/use-session-actions/utils'
 
 import type { ComposerScope } from './composer/scope'
 
+/**
+ * List a tile's session in the sidebar/tab strip on its first send.
+ *
+ * A ⌘T tab's session is created UNLISTED (see `openNewSessionTile`), so it has
+ * no `$sessions` row until its first turn persists and a refresh surfaces it —
+ * for that whole first exchange the tab and the sidebar read "New session".
+ * ⌘N has no such gap: its session is created per-send and seeded with the
+ * user's text as the row preview. Seeding the same way here names the session
+ * within the first message; the server's auto-title supersedes it once the turn
+ * completes.
+ *
+ * No-ops on empty text and on a session that is already listed, so re-sends
+ * never clobber a real title with a raw message preview.
+ */
+export function listTileSessionRow(deps: {
+  cwd?: string
+  model?: string
+  preview: string
+  runtimeId: string
+  sessions: readonly SessionInfo[]
+  storedSessionId: string
+}): boolean {
+  const preview = deps.preview.trim()
+
+  if (!preview || deps.sessions.some(session => sessionMatchesStoredId(session, deps.storedSessionId))) {
+    return false
+  }
+
+  upsertOptimisticSession(
+    { info: { cwd: deps.cwd, model: deps.model }, session_id: deps.runtimeId, stored_session_id: deps.storedSessionId },
+    deps.storedSessionId,
+    null,
+    preview
+  )
+  broadcastSessionsChanged()
+
+  return true
+}
+
 interface SessionTileActionsArgs {
   runtimeId: string
   scope: ComposerScope
@@ -89,6 +132,23 @@ export function useSessionTileActions({ runtimeId, scope, storedSessionId }: Ses
   const readState = useCallback(() => $sessionStates.get()[runtimeIdRef.current], [])
   const readMessages = useCallback(() => readState()?.messages ?? [], [readState])
 
+  // A ⌘T tab's session is unlisted until its first turn persists — seed the
+  // row from the user's first message so the tab and sidebar name it right
+  // away (see listTileSessionRow).
+  const listTileSession = useCallback((preview: string) => {
+    const runtimeId = runtimeIdRef.current
+    const state = $sessionStates.get()[runtimeId]
+
+    listTileSessionRow({
+      cwd: state?.cwd,
+      model: state?.model,
+      preview,
+      runtimeId,
+      sessions: $sessions.get(),
+      storedSessionId: storedIdRef.current
+    })
+  }, [])
+
   // Tile-side attachment staging: same upload rules as the primary submit
   // (skip synced/pathless, byte-upload files+images), against the tile scope.
   const syncAttachmentsForSubmit = useCallback(
@@ -162,6 +222,8 @@ export function useSessionTileActions({ runtimeId, scope, storedSessionId }: Ses
       const visibleText = rawText.trim()
       const attachments = options?.attachments ?? scope.attachments.$attachments.get()
 
+      listTileSession(visibleText)
+
       if (!attachments.length && SLASH_COMMAND_RE.test(visibleText)) {
         triggerHaptic('selection')
         await sessionTileDelegate()?.executeSlash(visibleText, runtimeIdRef.current)
@@ -171,24 +233,7 @@ export function useSessionTileActions({ runtimeId, scope, storedSessionId }: Ses
 
       return await submitPromptText(rawText, options)
     },
-    [scope.attachments.$attachments, submitPromptText]
-  )
-
-  const appendSystemNote = useCallback(
-    (text: string) => {
-      update(state => ({
-        ...state,
-        messages: [
-          ...state.messages,
-          {
-            id: `system-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-            role: 'system',
-            parts: [textPart(text)]
-          }
-        ]
-      }))
-    },
-    [update]
+    [listTileSession, scope.attachments.$attachments, submitPromptText]
   )
 
   const cancelRun = useCallback(async () => {
@@ -221,30 +266,84 @@ export function useSessionTileActions({ runtimeId, scope, storedSessionId }: Ses
   const steerPrompt = useCallback(
     async (rawText: string): Promise<boolean> => {
       const text = rawText.trim()
+      const sessionId = runtimeIdRef.current
 
-      if (!text) {
+      if (!text || !sessionId) {
         return false
       }
 
+      const messageId = `user-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
+      const mutate = (updater: (state: ClientSessionState) => ClientSessionState) =>
+        sessionTileDelegate()?.updateSession(sessionId, updater)
+
+      // Match the primary composer: insert the correction before the active
+      // reply before awaiting the redirect RPC, whose completion can race us.
+      mutate(state => {
+        const message = {
+          id: messageId,
+          role: 'user' as const,
+          parts: [textPart(text)]
+        }
+
+        const streamIndex = state.streamId ? state.messages.findIndex(candidate => candidate.id === state.streamId) : -1
+
+        const lastAssistantIndex = state.messages.map(candidate => candidate.role).lastIndexOf('assistant')
+        const insertionIndex = streamIndex >= 0 ? streamIndex : lastAssistantIndex
+
+        const messages =
+          insertionIndex >= 0
+            ? [...state.messages.slice(0, insertionIndex), message, ...state.messages.slice(insertionIndex)]
+            : [...state.messages, message]
+
+        return { ...state, messages }
+      })
+
+      const discardOptimisticMessage = () =>
+        mutate(state => ({
+          ...state,
+          messages: state.messages.filter(message => message.id !== messageId)
+        }))
+
+      const moveOptimisticMessageToEnd = () =>
+        mutate(state => {
+          const message = state.messages.find(candidate => candidate.id === messageId)
+
+          return message
+            ? { ...state, messages: [...state.messages.filter(candidate => candidate.id !== messageId), message] }
+            : state
+        })
+
       try {
-        const result = await requestGateway<{ status?: string }>('session.steer', {
-          session_id: runtimeIdRef.current,
+        const result = await requestGateway<{ status?: string }>('session.redirect', {
+          session_id: sessionId,
           text
         })
 
-        if (result?.status === 'queued') {
+        if (result?.status === 'redirected') {
+          triggerHaptic('submit')
+
+          return true
+        }
+
+        if (result?.status === 'queued') {
+          moveOptimisticMessageToEnd()
           triggerHaptic('submit')
-          appendSystemNote(`steer:${text}`)
 
           return true
         }
       } catch {
+        discardOptimisticMessage()
         // Swallow — the caller queues the text so nothing is lost.
+
+        return false
       }
 
+      discardOptimisticMessage()
+
       return false
     },
-    [appendSystemNote, requestGateway]
+    [requestGateway]
   )
 
   // Rewind primitive (interrupt-first for live turns, busy-retry) — shared with
@@ -274,7 +373,11 @@ export function useSessionTileActions({ runtimeId, scope, storedSessionId }: Ses
       try {
         await requestGateway(
           'prompt.submit',
-          { session_id: runtimeIdRef.current, text: plan.text, truncate_before_user_ordinal: plan.truncateOrdinal },
+          {
+            session_id: runtimeIdRef.current,
+            text: plan.text,
+            ...truncateSubmitParams(plan.truncateOrdinal)
+          },
           PROMPT_SUBMIT_REQUEST_TIMEOUT_MS
         )
       } catch (err) {
diff --git a/apps/desktop/src/app/chat/session-tile-row.test.ts b/apps/desktop/src/app/chat/session-tile-row.test.ts
new file mode 100644
index 00000000000..2c6eb0479e6
--- /dev/null
+++ b/apps/desktop/src/app/chat/session-tile-row.test.ts
@@ -0,0 +1,82 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { $sessions } from '@/store/session'
+import type { SessionInfo } from '@/types/hermes'
+
+import { listTileSessionRow } from './session-tile-actions'
+
+const STORED = 'stored-tab'
+const RUNTIME = 'runtime-tab'
+
+function row(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    cwd: null,
+    ended_at: null,
+    id: STORED,
+    input_tokens: 0,
+    is_active: true,
+    last_active: 1,
+    message_count: 1,
+    model: null,
+    output_tokens: 0,
+    parent_session_id: null,
+    preview: null,
+    source: 'desktop',
+    started_at: 1,
+    title: null,
+    tool_call_count: 0,
+    ...overrides
+  }
+}
+
+function seed(preview: string, sessions: SessionInfo[] = $sessions.get()) {
+  return listTileSessionRow({
+    cwd: '/work/repo',
+    model: 'claude-opus-5',
+    preview,
+    runtimeId: RUNTIME,
+    sessions,
+    storedSessionId: STORED
+  })
+}
+
+describe('listTileSessionRow', () => {
+  beforeEach(() => $sessions.set([]))
+  afterEach(() => $sessions.set([]))
+
+  it("lists an unlisted ⌘T tab from the user's first message", () => {
+    expect(seed('fix the tab titles')).toBe(true)
+
+    const listed = $sessions.get().find(session => session.id === STORED)
+
+    expect(listed?.preview).toBe('fix the tab titles')
+    expect(listed?.cwd).toBe('/work/repo')
+    // Title stays null so the server's auto-title is what eventually wins.
+    expect(listed?.title).toBeNull()
+  })
+
+  it('leaves an already-listed session alone so a real title survives re-sends', () => {
+    const titled = row({ title: 'Tab title fix' })
+
+    expect(seed('second message', [titled])).toBe(false)
+    expect($sessions.get()).toHaveLength(0)
+  })
+
+  it('matches a listed session across compression by lineage root', () => {
+    const rotated = row({ _lineage_root_id: STORED, id: 'stored-tab-compressed-2' })
+
+    expect(seed('after compression', [rotated])).toBe(false)
+  })
+
+  it('does not list a session on an empty or whitespace-only send', () => {
+    expect(seed('')).toBe(false)
+    expect(seed('   ')).toBe(false)
+    expect($sessions.get()).toHaveLength(0)
+  })
+
+  it('trims the seeded preview', () => {
+    seed('  padded prompt  ')
+
+    expect($sessions.get()[0]?.preview).toBe('padded prompt')
+  })
+})
diff --git a/apps/desktop/src/app/chat/session-tile.tsx b/apps/desktop/src/app/chat/session-tile.tsx
index 6562880b58f..6ca29e70ade 100644
--- a/apps/desktop/src/app/chat/session-tile.tsx
+++ b/apps/desktop/src/app/chat/session-tile.tsx
@@ -113,7 +113,7 @@ function TileChat({
   storedSessionId: string
   view: SessionView
 }) {
-  const { gatewayRef, requestGateway } = useGatewayRequest()
+  const { gateway, requestGateway } = useGatewayRequest()
   const queryClient = useQueryClient()
   const { selectModel } = useModelControls({ queryClient, requestGateway })
   const activeGatewayProfile = useStore($activeGatewayProfile)
@@ -151,20 +151,20 @@ function TileChat({
     () =>
       gatewayOpen ? (
         <ModelMenuPanel
-          gateway={gatewayRef.current || undefined}
+          gateway={gateway || undefined}
           onSelectModel={selectModel}
           profile={activeGatewayProfile}
           requestGateway={requestGateway}
         />
       ) : null,
-    [activeGatewayProfile, gatewayOpen, gatewayRef, requestGateway, selectModel]
+    [activeGatewayProfile, gateway, gatewayOpen, requestGateway, selectModel]
   )
 
   return (
     <SessionViewProvider value={view}>
       <ComposerScopeProvider value={scope}>
         <ChatView
-          gateway={gatewayRef.current}
+          gateway={gateway}
           modelMenuContent={modelMenuContent}
           onAddContextRef={composer.addContextRefAttachment}
           onAddUrl={url => composer.addContextRefAttachment(`@url:${formatRefValue(url)}`, url)}
@@ -253,6 +253,7 @@ export function SessionTilePane({ storedSessionId }: { storedSessionId: string }
   // session.resume before the gateway is OPEN. Persisted tiles mount at boot
   // while it's still connecting — an ungated resume rejected there and
   // latched every restored tile into the error card.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!gatewayOpen || runtimeId || tile?.error || resumingRef.current) {
       return
diff --git a/apps/desktop/src/app/chat/session-view.test.ts b/apps/desktop/src/app/chat/session-view.test.ts
new file mode 100644
index 00000000000..366af2327bc
--- /dev/null
+++ b/apps/desktop/src/app/chat/session-view.test.ts
@@ -0,0 +1,88 @@
+import { cleanup } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { createClientSessionState } from '@/lib/chat-runtime'
+import { $activeSessionId, $busy, $messages } from '@/store/session'
+import { $sessionStates, dropSessionState, publishSessionState } from '@/store/session-states'
+
+import { PRIMARY_SESSION_VIEW } from './session-view'
+
+const message = (id: string, text: string) => ({
+  id,
+  parts: [{ type: 'text' as const, text }],
+  role: 'assistant' as const
+})
+
+const stateWith = (runtimeId: string, text: string, busy: boolean) => ({
+  ...createClientSessionState(`stored-${runtimeId}`),
+  messages: [message(`${runtimeId}-msg`, text)],
+  busy
+})
+
+/**
+ * The workspace pane is just the first tab: it renders from the active
+ * session's own `$sessionStates` slice, exactly like a ⌘T tile.
+ *
+ * The regression this guards: the pane used to render straight off the global
+ * `$messages`/`$busy` atoms — a mirror of whichever session was active. With
+ * two turns in flight, navigating away from a still-streaming session left it
+ * painting into the surface now showing a different conversation.
+ */
+describe('primary session view reads its own session slice', () => {
+  beforeEach(() => {
+    $sessionStates.set({})
+    $activeSessionId.set(null)
+    $messages.set([])
+    $busy.set(false)
+  })
+
+  afterEach(cleanup)
+
+  it('shows the active session transcript, not a background session still streaming', () => {
+    publishSessionState('runtime-background', stateWith('runtime-background', 'background turn', true))
+    publishSessionState('runtime-foreground', stateWith('runtime-foreground', 'foreground turn', false))
+
+    $activeSessionId.set('runtime-foreground')
+
+    expect(PRIMARY_SESSION_VIEW.$messages.get()).toEqual([message('runtime-foreground-msg', 'foreground turn')])
+    expect(PRIMARY_SESSION_VIEW.$busy.get()).toBe(false)
+  })
+
+  it('ignores a background session that keeps streaming after the user switches away', () => {
+    publishSessionState('runtime-a', stateWith('runtime-a', 'session A turn', true))
+    $activeSessionId.set('runtime-b')
+    publishSessionState('runtime-b', stateWith('runtime-b', 'session B turn', false))
+
+    // Session A streams on: another delta lands for the session the user left.
+    publishSessionState('runtime-a', {
+      ...stateWith('runtime-a', 'session A turn', true),
+      messages: [message('runtime-a-msg', 'session A turn'), message('runtime-a-late', 'late delta')]
+    })
+
+    expect(PRIMARY_SESSION_VIEW.$messages.get()).toEqual([message('runtime-b-msg', 'session B turn')])
+    expect(PRIMARY_SESSION_VIEW.$lastVisibleIsUser.get()).toBe(false)
+    expect(PRIMARY_SESSION_VIEW.$busy.get()).toBe(false)
+  })
+
+  it('falls back to the draft atoms while the chat has no runtime session yet', () => {
+    $messages.set([message('draft-msg', 'unsent draft')])
+    $busy.set(true)
+
+    expect(PRIMARY_SESSION_VIEW.$runtimeId.get()).toBeNull()
+    expect(PRIMARY_SESSION_VIEW.$messages.get()).toEqual([message('draft-msg', 'unsent draft')])
+    expect(PRIMARY_SESSION_VIEW.$busy.get()).toBe(true)
+    expect(PRIMARY_SESSION_VIEW.$messagesEmpty.get()).toBe(false)
+  })
+
+  it('returns to the draft atoms when the active session state is dropped', () => {
+    publishSessionState('runtime-a', stateWith('runtime-a', 'session A turn', true))
+    $activeSessionId.set('runtime-a')
+
+    expect(PRIMARY_SESSION_VIEW.$messages.get()).toEqual([message('runtime-a-msg', 'session A turn')])
+
+    dropSessionState('runtime-a')
+
+    expect(PRIMARY_SESSION_VIEW.$messages.get()).toEqual([])
+    expect(PRIMARY_SESSION_VIEW.$messagesEmpty.get()).toBe(true)
+  })
+})
diff --git a/apps/desktop/src/app/chat/session-view.tsx b/apps/desktop/src/app/chat/session-view.tsx
index 9ca39ace67e..97ec1d0a376 100644
--- a/apps/desktop/src/app/chat/session-view.tsx
+++ b/apps/desktop/src/app/chat/session-view.tsx
@@ -1,6 +1,7 @@
-import type { ReadableAtom } from 'nanostores'
+import { computed, type ReadableAtom } from 'nanostores'
 import { createContext, useContext } from 'react'
 
+import type { ClientSessionState } from '@/app/types'
 import type { ChatMessage } from '@/lib/chat-messages'
 import {
   $activeSessionId,
@@ -11,18 +12,28 @@ import {
   $currentModel,
   $currentProvider,
   $currentReasoningEffort,
-  $lastVisibleMessageIsUser,
   $messages,
-  $messagesEmpty,
   $selectedStoredSessionId
 } from '@/store/session'
+import { $sessionStates } from '@/store/session-states'
+
+import { lastVisibleMessageIsUser } from './thread-loading'
 
 /**
- * SESSION VIEW — the store surface a ChatView renders from. The PRIMARY view
- * is the app's classic global atoms (route-driven active session, untouched
- * fast path). A session TILE provides the same shape computed from its
- * session's slice of `$sessionStates`, so the identical ChatView tree renders
- * either — one chat surface, N sessions on screen.
+ * SESSION VIEW — the store surface a ChatView renders from. Every session,
+ * including the one in the workspace pane, renders from ITS OWN slice of
+ * `$sessionStates`. The workspace pane is just the first tab: a session
+ * surface with no privileged state of its own.
+ *
+ * That symmetry is load-bearing. The pane used to render off the global
+ * `$messages`/`$busy` atoms — a mirror of whichever session was active — so
+ * with two turns in flight (⌘T tabs made that routine), navigating away from
+ * a still-streaming session left it painting into the surface now showing a
+ * different conversation. Reading the per-session slice makes that
+ * structurally impossible rather than merely guarded.
+ *
+ * The global atoms stay the DRAFT surface: a new chat has no runtime id, and
+ * therefore no slice, until its first turn creates one.
  *
  * Everything is atoms (not values) so subscription granularity survives:
  * ChatView subscribes only to the coarse edges; `$messages` stays boundary-
@@ -44,18 +55,39 @@ export interface SessionView {
   $reasoningEffort: ReadableAtom<string>
 }
 
+/** The active session's own slice, or `undefined` while it's a draft. */
+const $primaryState = computed([$activeSessionId, $sessionStates], (runtimeId, states) =>
+  runtimeId ? states[runtimeId] : undefined
+)
+
+/**
+ * Read one field from the active session's slice, falling back to the global
+ * draft atom while no runtime exists yet. Once a session HAS a slice, that
+ * slice is authoritative — a background session publishing its own state can
+ * never reach this view.
+ */
+function primaryField<T>(select: (state: ClientSessionState) => T, $draft: ReadableAtom<T>): ReadableAtom<T> {
+  const $field: ReadableAtom<T> = computed([$primaryState, $draft], (state, draft: T) =>
+    state ? select(state) : draft
+  )
+
+  return $field
+}
+
+const $primaryMessages = primaryField<ChatMessage[]>(state => state.messages, $messages)
+
 export const PRIMARY_SESSION_VIEW: SessionView = {
   kind: 'primary',
-  $awaitingResponse,
-  $busy,
-  $cwd: $currentCwd,
-  $fast: $currentFastMode,
-  $lastVisibleIsUser: $lastVisibleMessageIsUser,
-  $messages,
-  $messagesEmpty,
-  $model: $currentModel,
-  $provider: $currentProvider,
-  $reasoningEffort: $currentReasoningEffort,
+  $awaitingResponse: primaryField<boolean>(state => state.awaitingResponse, $awaitingResponse),
+  $busy: primaryField<boolean>(state => state.busy, $busy),
+  $cwd: primaryField<string>(state => state.cwd, $currentCwd),
+  $fast: primaryField<boolean>(state => state.fast, $currentFastMode),
+  $lastVisibleIsUser: computed($primaryMessages, lastVisibleMessageIsUser),
+  $messages: $primaryMessages,
+  $messagesEmpty: computed($primaryMessages, messages => messages.length === 0),
+  $model: primaryField<string>(state => state.model, $currentModel),
+  $provider: primaryField<string>(state => state.provider, $currentProvider),
+  $reasoningEffort: primaryField<string>(state => state.reasoningEffort, $currentReasoningEffort),
   $runtimeId: $activeSessionId,
   $storedId: $selectedStoredSessionId
 }
diff --git a/apps/desktop/src/app/chat/sidebar/chrome.tsx b/apps/desktop/src/app/chat/sidebar/chrome.tsx
index 7815d1fafcf..2a0f728503a 100644
--- a/apps/desktop/src/app/chat/sidebar/chrome.tsx
+++ b/apps/desktop/src/app/chat/sidebar/chrome.tsx
@@ -43,6 +43,22 @@ export function SidebarRowNest({ className, ...props }: React.ComponentProps<'di
   return <SidebarRowStack className={cn('pb-1 pl-4', className)} {...props} />
 }
 
+/**
+ * Chronological date-bucket separator ("Yesterday" / "Last week" / "June") for
+ * the session list. One flat row — a small caption plus a hairline rule — so it
+ * groups sessions by recency without adding a level of indentation.
+ */
+export function SidebarDateDivider({ className, label, ...props }: React.ComponentProps<'div'> & { label: string }) {
+  return (
+    <div className={cn('flex select-none items-center gap-2 px-2 pb-0.5 pt-2', className)} {...props}>
+      <span className="shrink-0 text-[0.64rem] font-semibold uppercase tracking-[0.12em] text-(--ui-text-quaternary)">
+        {label}
+      </span>
+      <span aria-hidden="true" className="h-px flex-1 bg-(--ui-stroke-tertiary)" />
+    </div>
+  )
+}
+
 /** Outer grid — sole owner of row height. */
 export function SidebarRowShell({
   actions,
diff --git a/apps/desktop/src/app/chat/sidebar/index.tsx b/apps/desktop/src/app/chat/sidebar/index.tsx
index 5b3f2b4b30c..91dec1e2d58 100644
--- a/apps/desktop/src/app/chat/sidebar/index.tsx
+++ b/apps/desktop/src/app/chat/sidebar/index.tsx
@@ -115,6 +115,7 @@ import { orderByIds, reconcileOrderIds, resolveManualSessionOrderIds, sameIds }
 import { ProfileRail } from './profile-switcher'
 import { ProjectDialog } from './project-dialog'
 import {
+  orderProjectsByIds,
   overlayLiveLanes,
   overlayLivePreviews,
   PROJECT_PREVIEW_COUNT,
@@ -622,8 +623,9 @@ export function ChatSidebar({
     )
 
     // Layer the user's manual drag-order on top of the deterministic sort. Empty
-    // (default) returns `sorted` untouched; new projects surface on top.
-    return orderByIds(sorted, project => project.id, projectOrderIds)
+    // (default) returns `sorted` untouched; projects the user hasn't ordered yet
+    // keep their sorted position rather than jumping the hand-picked list.
+    return orderProjectsByIds(sorted, projectOrderIds)
   }, [showAllProfiles, projectTree, dismissedAutoProjects, orderRepos, activeProjectId, projectOrderIds])
 
   // The overview only renders in grouped mode; the model stays live regardless
@@ -718,6 +720,7 @@ export function ChatSidebar({
   // only the cheap per-repo `git worktree list`, never the heavy tree scan.
   const prevWorkingIdsRef = useRef<readonly string[]>(workingSessionIds)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const prev = prevWorkingIdsRef.current
     prevWorkingIdsRef.current = workingSessionIds
@@ -754,6 +757,7 @@ export function ChatSidebar({
     [currentCwd]
   )
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!inProject || !enteredProject) {
       lastProjectCwdSyncRef.current = null
@@ -1239,7 +1243,7 @@ export function ChatSidebar({
             {!trimmedQuery && (
               <SidebarSessionsSection
                 activeSessionId={activeSidebarSessionId}
-                contentClassName={cn('flex max-h-44 flex-col gap-px rounded-lg pb-2 pt-1', GROUP_BODY)}
+                contentClassName={cn('flex max-h-[50vh] flex-col gap-px rounded-lg pb-2 pt-1', GROUP_BODY)}
                 dndSensors={dndSensors}
                 emptyState={<SidebarPinnedEmptyState />}
                 label={s.pinned}
@@ -1275,6 +1279,7 @@ export function ChatSidebar({
                   // virtualized long list, which must keep its own scroller.
                   !recentsVirtualizes && COMPACT_FLAT
                 )}
+                dateGrouped={inProject || !agentOrderManual}
                 dndSensors={dndSensors}
                 emptyState={
                   showSessionSkeletons ? (
diff --git a/apps/desktop/src/app/chat/sidebar/profile-switcher.tsx b/apps/desktop/src/app/chat/sidebar/profile-switcher.tsx
index 52fa8de19c0..e57fec12079 100644
--- a/apps/desktop/src/app/chat/sidebar/profile-switcher.tsx
+++ b/apps/desktop/src/app/chat/sidebar/profile-switcher.tsx
@@ -213,6 +213,7 @@ export function ProfileRail() {
   const createRequest = useStore($profileCreateRequest)
   const lastCreateRef = useRef(createRequest)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (createRequest === lastCreateRef.current) {
       return
diff --git a/apps/desktop/src/app/chat/sidebar/projects/index.ts b/apps/desktop/src/app/chat/sidebar/projects/index.ts
index dea53d1fe6f..f30d075a0f5 100644
--- a/apps/desktop/src/app/chat/sidebar/projects/index.ts
+++ b/apps/desktop/src/app/chat/sidebar/projects/index.ts
@@ -1,6 +1,12 @@
 // Public surface of the project/worktree sidebar, consumed by the sidebar root.
 export { EnteredProjectContent } from './entered-content'
-export { PROJECT_PREVIEW_COUNT, projectTreeCwd, sortProjectsForOverview, useRepoWorktreeMap } from './model'
+export {
+  orderProjectsByIds,
+  PROJECT_PREVIEW_COUNT,
+  projectTreeCwd,
+  sortProjectsForOverview,
+  useRepoWorktreeMap
+} from './model'
 export { ProjectBackRow, ProjectOverviewRow } from './overview-row'
 export { ProjectMenu } from './project-menu'
 export { SidebarWorkspaceGroup } from './workspace-group'
diff --git a/apps/desktop/src/app/chat/sidebar/projects/model.test.ts b/apps/desktop/src/app/chat/sidebar/projects/model.test.ts
new file mode 100644
index 00000000000..c56912fc862
--- /dev/null
+++ b/apps/desktop/src/app/chat/sidebar/projects/model.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+
+import { orderProjectsByIds } from './model'
+import type { SidebarProjectTree } from './workspace-groups'
+
+function makeProject(id: string, sessionCount: number): SidebarProjectTree {
+  return {
+    id,
+    isAuto: true,
+    label: id,
+    lastActive: 0,
+    path: `/repos/${id}`,
+    previewSessions: [],
+    repos: [],
+    sessionCount
+  }
+}
+
+const ids = (projects: SidebarProjectTree[]) => projects.map(project => project.id)
+
+describe('orderProjectsByIds', () => {
+  it('leaves the deterministic sort alone when nothing has been dragged', () => {
+    const projects = [makeProject('a', 0), makeProject('b', 2)]
+
+    expect(orderProjectsByIds(projects, [])).toBe(projects)
+  })
+
+  it('applies the saved manual order', () => {
+    const projects = [makeProject('a', 1), makeProject('b', 1), makeProject('c', 1)]
+
+    expect(ids(orderProjectsByIds(projects, ['c', 'a', 'b']))).toEqual(['c', 'a', 'b'])
+  })
+
+  it('keeps freshly-scanned zero-session repos below the hand-ordered list', () => {
+    // The regression: a disk scan keeps finding git checkouts the user has
+    // never opened in Hermes. Surfacing every unsaved id at the top buried the
+    // projects they deliberately dragged into place.
+    const projects = [makeProject('scanned-1', 0), makeProject('mine', 4), makeProject('scanned-2', 0)]
+
+    expect(ids(orderProjectsByIds(projects, ['mine']))).toEqual(['mine', 'scanned-1', 'scanned-2'])
+  })
+
+  it('still surfaces a new project that has real activity', () => {
+    // A project you just started working in should not sink beneath the saved
+    // order — only the zero-session discoveries do.
+    const projects = [makeProject('ordered', 1), makeProject('just-started', 3)]
+
+    expect(ids(orderProjectsByIds(projects, ['ordered']))).toEqual(['just-started', 'ordered'])
+  })
+
+  it('drops ids that are no longer present', () => {
+    const projects = [makeProject('a', 1)]
+
+    expect(ids(orderProjectsByIds(projects, ['gone', 'a']))).toEqual(['a'])
+  })
+})
diff --git a/apps/desktop/src/app/chat/sidebar/projects/model.ts b/apps/desktop/src/app/chat/sidebar/projects/model.ts
index 1e55db2fe41..f3510e2061d 100644
--- a/apps/desktop/src/app/chat/sidebar/projects/model.ts
+++ b/apps/desktop/src/app/chat/sidebar/projects/model.ts
@@ -75,6 +75,39 @@ export function sortProjectsForOverview(
   })
 }
 
+// Layer the user's manual drag-order over the deterministic sort.
+//
+// This can't just be `orderByIds`: that surfaces every id missing from the saved
+// order at the TOP, which is right for sessions (a new chat should not sink) but
+// wrong here. The overview also lists repos found by the disk scan that have
+// zero Hermes sessions, and those arrive continuously — so once the user dragged
+// anything, every freshly-scanned checkout jumped above the projects they
+// actually work in.
+//
+// Fresh projects keep their place in the deterministic sort instead: ones with
+// real activity go on top (a project you just started still surfaces), and
+// zero-session discoveries sink below the hand-ordered list.
+export function orderProjectsByIds(projects: SidebarProjectTree[], orderIds: string[]): SidebarProjectTree[] {
+  if (!orderIds.length) {
+    return projects
+  }
+
+  const byId = new Map(projects.map(project => [project.id, project]))
+  const ordered = orderIds.map(id => byId.get(id)).filter((p): p is SidebarProjectTree => Boolean(p))
+  const seen = new Set(ordered.map(project => project.id))
+  const fresh = projects.filter(project => !seen.has(project.id))
+
+  if (!fresh.length) {
+    return ordered
+  }
+
+  return [
+    ...fresh.filter(project => project.sessionCount > 0),
+    ...ordered,
+    ...fresh.filter(project => project.sessionCount <= 0)
+  ]
+}
+
 // Project drill-in lanes are git-driven: source them from `git worktree list` so
 // linked worktrees still appear even when their sessions aren't in the recents
 // payload currently loaded in memory.
diff --git a/apps/desktop/src/app/chat/sidebar/session-row.tsx b/apps/desktop/src/app/chat/sidebar/session-row.tsx
index c1291a27b15..7de51f3de43 100644
--- a/apps/desktop/src/app/chat/sidebar/session-row.tsx
+++ b/apps/desktop/src/app/chat/sidebar/session-row.tsx
@@ -163,7 +163,9 @@ export function SidebarSessionRow({
         style={style}
         {...rest}
       >
-        {sessionShowsRunningArc({ isWorking, needsInput }) && <span aria-hidden="true" className="arc-border" />}
+        {sessionShowsRunningArc({ isWorking, needsInput }) && (
+          <span aria-hidden="true" className="arc-border arc-row" />
+        )}
         <SidebarRowBody
           className={cn('z-0 group-hover:pr-12', branchStem && 'pl-3.5')}
           // Middle-click = open in a new tab (browser muscle memory). Swallow
diff --git a/apps/desktop/src/app/chat/sidebar/sessions-section.tsx b/apps/desktop/src/app/chat/sidebar/sessions-section.tsx
index 366f28a152e..d3a65e1d787 100644
--- a/apps/desktop/src/app/chat/sidebar/sessions-section.tsx
+++ b/apps/desktop/src/app/chat/sidebar/sessions-section.tsx
@@ -7,11 +7,14 @@ import { DisclosureCaret } from '@/components/ui/disclosure-caret'
 import { SidebarGroup, SidebarGroupContent } from '@/components/ui/sidebar'
 import type { HermesGitWorktree } from '@/global'
 import type { SessionInfo } from '@/hermes'
+import { useI18n } from '@/i18n'
 import { flattenSessionsWithBranches } from '@/lib/session-branch-tree'
+import { groupEntriesByRecency, type SidebarListRow, toSessionRows } from '@/lib/session-date-groups'
+import { sessionBucketLabel } from '@/lib/time'
 import { cn } from '@/lib/utils'
 import { sessionPinId } from '@/store/session'
 
-import { SidebarCount } from './chrome'
+import { SidebarCount, SidebarDateDivider } from './chrome'
 import {
   EnteredProjectContent,
   ProjectOverviewRow,
@@ -139,6 +142,11 @@ interface SidebarSessionsSectionProps {
   // lists (Pinned / search results) in the All-profiles view, where no group
   // header communicates ownership (#66003).
   showProfileTags?: boolean
+  // Insert "Yesterday" / "Last week" date dividers into the chronological
+  // session list (flat recents + entered-project lanes). Off for hand-ordered
+  // lists, pinned, messaging groups, and the project overview, where the order
+  // isn't strictly by recency so a date bucket would be misleading.
+  dateGrouped?: boolean
 }
 
 export function SidebarSessionsSection({
@@ -179,8 +187,11 @@ export function SidebarSessionsSection({
   onReorderProjects,
   projectBackRow,
   dndSensors,
-  showProfileTags = false
+  showProfileTags = false,
+  dateGrouped = false
 }: SidebarSessionsSectionProps) {
+  const { t } = useI18n()
+  const dividerLabels = t.sidebar.dateDivider
   const sectionOpen = collapsible ? open : true
   const hasGroupedSessions = Boolean(groups?.some(group => group.sessions.length > 0))
   // A defined project list is itself content (even an empty project should
@@ -219,10 +230,30 @@ export function SidebarSessionsSection({
     )
   }
 
+  // A single flat/virtual/lane list row — either a date divider or a session.
+  const renderListRow = (row: SidebarListRow, draggable: boolean) =>
+    row.kind === 'divider' ? (
+      <SidebarDateDivider key={row.key} label={sessionBucketLabel(row.bucket, dividerLabels)} />
+    ) : (
+      renderRow(row.entry.session, draggable, row.entry.branchStem)
+    )
+
   // Sessions inside repos/worktrees are date-ordered and static.
   const renderRows = (items: SessionInfo[]) =>
     flattenSessionsWithBranches(items).map(({ branchStem, session }) => renderRow(session, false, branchStem))
 
+  // Same as `renderRows`, but with date dividers folded in — used for
+  // entered-project lanes so a lane spanning multiple days reads
+  // chronologically, matching the flat recents list.
+  const renderRowsDated = (items: SessionInfo[]) => {
+    const entries = flattenSessionsWithBranches(items)
+
+    return (dateGrouped ? groupEntriesByRecency(entries) : toSessionRows(entries)).map(row => renderListRow(row, false))
+  }
+
+  // Flat recents as list rows: grouped by recency when enabled, plain otherwise.
+  const flatRows: SidebarListRow[] = dateGrouped ? groupEntriesByRecency(displayEntries) : toSessionRows(displayEntries)
+
   const flatVirtualized =
     !showEmptyState &&
     !groups?.length &&
@@ -254,7 +285,7 @@ export function SidebarSessionsSection({
             onNewSession={onNewSessionInWorkspace}
             project={projectContent}
             removedSessionIds={removedSessionIds}
-            renderRows={renderRows}
+            renderRows={renderRowsDated}
             repoWorktrees={projectRepoWorktrees}
           />
         ) : (
@@ -310,13 +341,13 @@ export function SidebarSessionsSection({
       <VirtualSessionList
         activeSessionId={activeSessionId}
         className={contentClassName}
-        entries={displayEntries}
         onArchiveSession={onArchiveSession}
         onBranchSession={onBranchSession}
         onDeleteSession={onDeleteSession}
         onResumeSession={onResumeSession}
         onTogglePin={onTogglePin}
         pinned={pinned}
+        rows={flatRows}
         showProfileTags={showProfileTags}
         sortable={sessionsDraggable}
         workingSessionIdSet={workingSessionIdSet}
@@ -334,11 +365,11 @@ export function SidebarSessionsSection({
   } else if (sessionsDraggable && onReorderSessions) {
     inner = (
       <ReorderableList ids={sessions.map(s => s.id)} onReorder={onReorderSessions} sensors={dndSensors}>
-        {displayEntries.map(({ branchStem, session }) => renderRow(session, true, branchStem))}
+        {flatRows.map(row => renderListRow(row, true))}
       </ReorderableList>
     )
   } else {
-    inner = displayEntries.map(({ branchStem, session }) => renderRow(session, false, branchStem))
+    inner = flatRows.map(row => renderListRow(row, false))
   }
 
   // The virtualizer owns its own scroller, so suppress the wrapper's overflow
diff --git a/apps/desktop/src/app/chat/sidebar/virtual-session-list.tsx b/apps/desktop/src/app/chat/sidebar/virtual-session-list.tsx
index e3d56051b8e..d9cfd6c0043 100644
--- a/apps/desktop/src/app/chat/sidebar/virtual-session-list.tsx
+++ b/apps/desktop/src/app/chat/sidebar/virtual-session-list.tsx
@@ -4,10 +4,13 @@ import { useVirtualizer } from '@tanstack/react-virtual'
 import { type FC, useCallback, useRef } from 'react'
 
 import type { SessionInfo } from '@/hermes'
-import { type SidebarSessionEntry } from '@/lib/session-branch-tree'
+import { useI18n } from '@/i18n'
+import { type SidebarListRow } from '@/lib/session-date-groups'
+import { sessionBucketLabel } from '@/lib/time'
 import { cn } from '@/lib/utils'
 import { sessionPinId } from '@/store/session'
 
+import { SidebarDateDivider } from './chrome'
 import { SidebarSessionRow } from './session-row'
 
 interface SessionRowCommonProps {
@@ -27,7 +30,7 @@ interface SessionRowCommonProps {
 interface VirtualSessionListProps {
   activeSessionId: null | string
   className?: string
-  entries: SidebarSessionEntry[]
+  rows: SidebarListRow[]
   onArchiveSession: (sessionId: string) => void
   onBranchSession?: (sessionId: string, profile?: string) => void
   onDeleteSession: (sessionId: string) => void
@@ -45,7 +48,7 @@ const OVERSCAN_ROWS = 12
 export const VirtualSessionList: FC<VirtualSessionListProps> = ({
   activeSessionId,
   className,
-  entries,
+  rows: listRows,
   onArchiveSession,
   onBranchSession,
   onDeleteSession,
@@ -56,12 +59,18 @@ export const VirtualSessionList: FC<VirtualSessionListProps> = ({
   sortable,
   workingSessionIdSet
 }) => {
+  const { t } = useI18n()
+  const dividerLabels = t.sidebar.dateDivider
   const scrollerRef = useRef<HTMLDivElement | null>(null)
 
   const virtualizer = useVirtualizer({
-    count: entries.length,
+    count: listRows.length,
     estimateSize: () => ROW_ESTIMATE_PX,
-    getItemKey: index => entries[index]?.session.id ?? index,
+    getItemKey: index => {
+      const row = listRows[index]
+
+      return row ? (row.kind === 'divider' ? row.key : row.entry.session.id) : index
+    },
     getScrollElement: () => scrollerRef.current,
     // jsdom-friendly default; the real rect takes over on first observe.
     initialRect: { height: 600, width: 240 },
@@ -74,13 +83,25 @@ export const VirtualSessionList: FC<VirtualSessionListProps> = ({
   const paddingBottom = Math.max(0, totalSize - (virtualItems[virtualItems.length - 1]?.end ?? 0))
 
   const rows = virtualItems.map(virtualItem => {
-    const entry = entries[virtualItem.index]
+    const row = listRows[virtualItem.index]
 
-    if (!entry) {
+    if (!row) {
       return null
     }
 
-    const { branchStem, session } = entry
+    // Dividers are non-sortable, self-measured rows interleaved with sessions.
+    if (row.kind === 'divider') {
+      return (
+        <SidebarDateDivider
+          data-index={virtualItem.index}
+          key={row.key}
+          label={sessionBucketLabel(row.bucket, dividerLabels)}
+          ref={virtualizer.measureElement}
+        />
+      )
+    }
+
+    const { branchStem, session } = row.entry
     const reorderable = sortable && !branchStem
 
     const commonProps: SessionRowCommonProps = {
diff --git a/apps/desktop/src/app/chat/surface-vars.test.ts b/apps/desktop/src/app/chat/surface-vars.test.ts
new file mode 100644
index 00000000000..438d36c75be
--- /dev/null
+++ b/apps/desktop/src/app/chat/surface-vars.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+
+import { chatSurfaceRoot, clearSurfaceVar, setSurfaceVar, STATUS_STACK_VAR } from './surface-vars'
+
+/**
+ * Measured-height vars must be scoped per chat surface. Session tiles render a
+ * full ChatView — thread, composer, and status stack — beside the workspace
+ * pane, so a single global slot let a background tab's tall status stack
+ * inflate the foreground thread's bottom clearance and shove its
+ * jump-to-bottom button into mid-screen.
+ */
+function surface(): { root: HTMLElement; stack: HTMLElement } {
+  const root = document.createElement('div')
+  root.setAttribute('data-chat-surface', '')
+
+  const stack = document.createElement('div')
+  root.append(stack)
+  document.body.append(root)
+
+  return { root, stack }
+}
+
+describe('per-surface measured-height vars', () => {
+  it('publishes onto the owning chat surface, not the document root', () => {
+    const { root, stack } = surface()
+
+    setSurfaceVar(stack, STATUS_STACK_VAR, '96px')
+
+    expect(root.style.getPropertyValue(STATUS_STACK_VAR)).toBe('96px')
+    expect(document.documentElement.style.getPropertyValue(STATUS_STACK_VAR)).toBe('')
+  })
+
+  it('keeps two visible surfaces independent', () => {
+    const background = surface()
+    const foreground = surface()
+
+    setSurfaceVar(background.stack, STATUS_STACK_VAR, '160px')
+    setSurfaceVar(foreground.stack, STATUS_STACK_VAR, '0px')
+
+    expect(background.root.style.getPropertyValue(STATUS_STACK_VAR)).toBe('160px')
+    expect(foreground.root.style.getPropertyValue(STATUS_STACK_VAR)).toBe('0px')
+  })
+
+  it('clearing one surface leaves the other intact', () => {
+    const a = surface()
+    const b = surface()
+
+    setSurfaceVar(a.stack, STATUS_STACK_VAR, '48px')
+    setSurfaceVar(b.stack, STATUS_STACK_VAR, '80px')
+    clearSurfaceVar(a.stack, STATUS_STACK_VAR)
+
+    expect(a.root.style.getPropertyValue(STATUS_STACK_VAR)).toBe('')
+    expect(b.root.style.getPropertyValue(STATUS_STACK_VAR)).toBe('80px')
+  })
+
+  it('falls back to the document root outside a chat surface (popped-out composer)', () => {
+    const orphan = document.createElement('div')
+    document.body.append(orphan)
+
+    expect(chatSurfaceRoot(orphan)).toBe(document.documentElement)
+
+    setSurfaceVar(orphan, STATUS_STACK_VAR, '24px')
+    expect(document.documentElement.style.getPropertyValue(STATUS_STACK_VAR)).toBe('24px')
+
+    clearSurfaceVar(orphan, STATUS_STACK_VAR)
+    expect(document.documentElement.style.getPropertyValue(STATUS_STACK_VAR)).toBe('')
+  })
+})
diff --git a/apps/desktop/src/app/chat/surface-vars.ts b/apps/desktop/src/app/chat/surface-vars.ts
new file mode 100644
index 00000000000..5176dc11375
--- /dev/null
+++ b/apps/desktop/src/app/chat/surface-vars.ts
@@ -0,0 +1,40 @@
+/**
+ * Measured-height CSS vars, scoped to one chat surface.
+ *
+ * The composer and the out-of-flow status stack both publish their measured
+ * height so the thread can reserve bottom clearance for them. Those vars used
+ * to be written to `document.documentElement` — a single global slot — while
+ * the components writing them mount once per chat surface. Session tiles
+ * render a full ChatView (thread + composer + status stack) beside the
+ * workspace pane, so N surfaces raced for one value: a background tab with a
+ * tall stack inflated the foreground thread's padding and pushed its
+ * jump-to-bottom button into mid-screen.
+ *
+ * Publishing onto the surface's own root element instead makes each ChatView
+ * read its own measurement through normal CSS inheritance. Remeasuring on
+ * session switch cannot fix this — several surfaces are visible at once, so
+ * there is no single correct value to remeasure to.
+ */
+
+export const COMPOSER_HEIGHT_VAR = '--composer-measured-height'
+export const COMPOSER_SURFACE_HEIGHT_VAR = '--composer-surface-measured-height'
+export const STATUS_STACK_VAR = '--status-stack-measured-height'
+
+/**
+ * The surface owning `el`, falling back to the document root so a composer
+ * rendered outside a chat surface (the popped-out window) keeps behaving
+ * exactly as before.
+ */
+export function chatSurfaceRoot(el: Element | null): HTMLElement {
+  return el?.closest<HTMLElement>('[data-chat-surface]') ?? document.documentElement
+}
+
+/** Publish a measured-height var on the surface owning `el`. */
+export function setSurfaceVar(el: Element | null, name: string, value: string): void {
+  chatSurfaceRoot(el).style.setProperty(name, value)
+}
+
+/** Clear a measured-height var from the surface owning `el`. */
+export function clearSurfaceVar(el: Element | null, name: string): void {
+  chatSurfaceRoot(el).style.removeProperty(name)
+}
diff --git a/apps/desktop/src/app/command-palette/index.tsx b/apps/desktop/src/app/command-palette/index.tsx
index e0a669bb300..42bcef4e820 100644
--- a/apps/desktop/src/app/command-palette/index.tsx
+++ b/apps/desktop/src/app/command-palette/index.tsx
@@ -245,7 +245,7 @@ const NON_CONFIG_SETTINGS: ReadonlyArray<{
   },
   {
     icon: KeyRound,
-    keywords: ['providers', 'api key', 'keys', 'secrets', 'tokens'],
+    keywords: ['providers', 'api key', 'keys', 'secrets', 'tokens', 'egress', 'iron proxy', 'sandbox proxy'],
     labelKey: 'providerApiKeys',
     tab: 'providers&pview=keys'
   },
@@ -258,7 +258,7 @@ const NON_CONFIG_SETTINGS: ReadonlyArray<{
   },
   {
     icon: Settings2,
-    keywords: ['gateway', 'proxy', 'server', 'webhook', 'env'],
+    keywords: ['gateway', 'proxy', 'server', 'webhook', 'env', 'egress proxy', 'iron proxy'],
     labelKey: 'keysSettings',
     tab: 'keys&kview=settings'
   },
diff --git a/apps/desktop/src/app/contrib/controller.tsx b/apps/desktop/src/app/contrib/controller.tsx
index 0faf5e5ccb0..3c245478bb0 100644
--- a/apps/desktop/src/app/contrib/controller.tsx
+++ b/apps/desktop/src/app/contrib/controller.tsx
@@ -54,6 +54,7 @@ import {
 import { $filePreviewTarget, $previewTarget, closeRightRail } from '@/store/preview'
 import { $reviewOpen, closeReview, REVIEW_PANE_ID } from '@/store/review'
 import { $currentCwd, $selectedStoredSessionId, $sessions, sessionMatchesStoredId } from '@/store/session'
+import { watchSessionPins } from '@/store/session-pin-sync'
 
 import type { SessionDragPayload } from '../chat/composer/inline-refs'
 import { watchRouteTiles } from '../chat/route-tile'
@@ -397,6 +398,10 @@ watchContributedPanes()
 watchSessionTiles()
 watchRouteTiles()
 
+// Mirror sidebar pins into the backend keep-flag so the auto-archive sweep
+// never hides a pinned chat (and pre-existing pins migrate transparently).
+watchSessionPins()
+
 // The main tab reads as its SESSION (the loaded title, "New session" on a
 // fresh draft) — a stack of main + tiles is then just a row of session names.
 // register() replaces same-id in place; the render fn is the shared constant
diff --git a/apps/desktop/src/app/contrib/hooks/use-desktop-integrations.ts b/apps/desktop/src/app/contrib/hooks/use-desktop-integrations.ts
index 3c3bbbddd7f..ed22e2cc7eb 100644
--- a/apps/desktop/src/app/contrib/hooks/use-desktop-integrations.ts
+++ b/apps/desktop/src/app/contrib/hooks/use-desktop-integrations.ts
@@ -87,6 +87,7 @@ export function useDesktopIntegrations({
   // Restore once on cold start — only when the renderer booted at the default
   // route (a hidden-then-shown window keeps its own route). Prefer the full
   // remembered route (covers pages); fall back to the last session id.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (restoredRef.current || locationPathname !== NEW_CHAT_ROUTE) {
       restoredRef.current = true
diff --git a/apps/desktop/src/app/contrib/latest-actions.test.ts b/apps/desktop/src/app/contrib/latest-actions.test.ts
new file mode 100644
index 00000000000..9ff335054f3
--- /dev/null
+++ b/apps/desktop/src/app/contrib/latest-actions.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { SidebarNavItem } from '../types'
+
+import { latestChatActions, latestSidebarActions } from './latest-actions'
+import type { ChatActions, SidebarActions } from './types'
+
+function makeChatActions(): ChatActions {
+  return {
+    onAddContextRef: vi.fn(),
+    onAddUrl: vi.fn(),
+    onAttachDroppedItems: vi.fn(),
+    onAttachImageBlob: vi.fn(),
+    onBranchInNewChat: vi.fn(),
+    onCancel: vi.fn(),
+    onDeleteSelectedSession: vi.fn(),
+    onDismissError: vi.fn(),
+    onEdit: vi.fn(),
+    onPasteClipboardImage: vi.fn(),
+    onPickFiles: vi.fn(),
+    onPickFolders: vi.fn(),
+    onPickImages: vi.fn(),
+    onReload: vi.fn(),
+    onRemoveAttachment: vi.fn(),
+    onRestoreToMessage: vi.fn(),
+    onRetryResume: vi.fn(),
+    onSteer: vi.fn(),
+    onSubmit: vi.fn(),
+    onThreadMessagesChange: vi.fn(),
+    onToggleSelectedPin: vi.fn(),
+    onTranscribeAudio: vi.fn()
+  }
+}
+
+function makeSidebarActions(): SidebarActions {
+  return {
+    onArchiveSession: vi.fn(),
+    onBranchSession: vi.fn(),
+    onDeleteSession: vi.fn(),
+    onLoadMoreMessaging: vi.fn(),
+    onLoadMoreProfileSessions: vi.fn(),
+    onLoadMoreSessions: vi.fn(),
+    onManageCronJob: vi.fn(),
+    onNavigate: vi.fn(),
+    onNewSessionInWorkspace: vi.fn(),
+    onNewSessionSplit: vi.fn(),
+    onResumeSession: vi.fn(),
+    onTriggerCronJob: vi.fn()
+  }
+}
+
+describe('latestActions adapters', () => {
+  it('dereferences the latest steer handler from a stable actions object', async () => {
+    const staleSteer = vi.fn(async () => false)
+    const latestSteer = vi.fn(async () => true)
+    const actions = makeChatActions()
+    actions.onSteer = staleSteer
+    const adapted = latestChatActions(actions)
+
+    actions.onSteer = latestSteer
+
+    await expect(adapted.onSteer('continue in selected session')).resolves.toBe(true)
+    expect(staleSteer).not.toHaveBeenCalled()
+    expect(latestSteer).toHaveBeenCalledWith('continue in selected session')
+  })
+
+  it('dereferences the latest sidebar handler from a stable actions object', () => {
+    const staleNavigate = vi.fn()
+    const latestNavigate = vi.fn()
+    const item = { id: 'settings', icon: vi.fn(), label: 'Settings', route: '/settings' } satisfies SidebarNavItem
+    const actions = makeSidebarActions()
+    actions.onNavigate = staleNavigate
+    const adapted = latestSidebarActions(actions)
+
+    actions.onNavigate = latestNavigate
+    adapted.onNavigate(item)
+
+    expect(staleNavigate).not.toHaveBeenCalled()
+    expect(latestNavigate).toHaveBeenCalledWith(item)
+  })
+
+  // An absent optional handler must stay absent through the adapter. Children
+  // gate on PRESENCE, not just invocation: onDismissError renders the dismiss
+  // button only when defined, onRestoreToMessage gates the restore-confirm
+  // flow, and onTranscribeAudio gates voice recording. Wrapping an undefined
+  // field in an arrow function makes it unconditionally truthy, which would
+  // paint a dead dismiss button and let voice recording run with no
+  // transcription backend.
+  it('leaves absent optional handlers undefined instead of always-truthy wrappers', () => {
+    const chat = makeChatActions()
+    chat.onDismissError = undefined
+    chat.onRestoreToMessage = undefined
+    chat.onTranscribeAudio = undefined
+
+    const adaptedChat = latestChatActions(chat)
+
+    expect(adaptedChat.onDismissError).toBeUndefined()
+    expect(adaptedChat.onRestoreToMessage).toBeUndefined()
+    expect(adaptedChat.onTranscribeAudio).toBeUndefined()
+
+    const sidebar = makeSidebarActions()
+    sidebar.onLoadMoreMessaging = undefined
+    sidebar.onLoadMoreProfileSessions = undefined
+
+    const adaptedSidebar = latestSidebarActions(sidebar)
+
+    expect(adaptedSidebar.onLoadMoreMessaging).toBeUndefined()
+    expect(adaptedSidebar.onLoadMoreProfileSessions).toBeUndefined()
+  })
+
+  it('still late-binds a PRESENT optional handler to the latest closure', async () => {
+    const staleTranscribe = vi.fn(async () => 'stale')
+    const latestTranscribe = vi.fn(async () => 'latest')
+    const actions = makeChatActions()
+    actions.onTranscribeAudio = staleTranscribe
+
+    const adapted = latestChatActions(actions)
+
+    actions.onTranscribeAudio = latestTranscribe
+
+    expect(adapted.onTranscribeAudio).toBeTypeOf('function')
+    await expect(adapted.onTranscribeAudio!(new Blob())).resolves.toBe('latest')
+    expect(staleTranscribe).not.toHaveBeenCalled()
+  })
+})
diff --git a/apps/desktop/src/app/contrib/latest-actions.ts b/apps/desktop/src/app/contrib/latest-actions.ts
new file mode 100644
index 00000000000..4407739398a
--- /dev/null
+++ b/apps/desktop/src/app/contrib/latest-actions.ts
@@ -0,0 +1,73 @@
+import type { ChatActions, SidebarActions } from './types'
+
+/**
+ * Surfaces receive one stable `actions` object whose fields are mutated by the
+ * wiring controller each render. If a memoized surface passes `actions.foo`
+ * directly, the child keeps the function from the surface's last render and can
+ * submit/click against a stale session closure. These adapters keep a stable
+ * wrapper but dereference the latest field at call time.
+ *
+ * OPTIONAL handlers must stay optional. Several children gate on a handler's
+ * *presence*, not just call it — `onDismissError` renders the dismiss button
+ * only when it exists (assistant-message.tsx), `onRestoreToMessage` gates the
+ * restore-confirm flow (thread/index.tsx), and `onTranscribeAudio` gates voice
+ * recording/conversation (use-voice-recorder, use-voice-conversation). An
+ * unconditional arrow wrapper is always truthy, which would render a dead
+ * dismiss button and let voice recording proceed with no transcription backend.
+ * So wrap an optional field only when it is currently present, and re-read the
+ * latest value inside the wrapper for the stale-closure fix.
+ */
+function latestOptional<A extends unknown[], R>(
+  read: () => ((...args: A) => R) | undefined
+): ((...args: A) => R) | undefined {
+  // Presence is sampled from the object identity the surface currently holds.
+  // The controller mutates fields in place rather than swapping a handler
+  // between defined and undefined, so presence is stable for a given actions
+  // object while the *closure* is what churns — which is exactly what the
+  // indirection below re-reads.
+  return read() ? (...args: A) => read()!(...args) : undefined
+}
+
+export function latestChatActions(actions: ChatActions): ChatActions {
+  return {
+    onAddContextRef: (...args) => actions.onAddContextRef(...args),
+    onAddUrl: (...args) => actions.onAddUrl(...args),
+    onAttachDroppedItems: (...args) => actions.onAttachDroppedItems(...args),
+    onAttachImageBlob: (...args) => actions.onAttachImageBlob(...args),
+    onBranchInNewChat: (...args) => actions.onBranchInNewChat(...args),
+    onCancel: (...args) => actions.onCancel(...args),
+    onDeleteSelectedSession: (...args) => actions.onDeleteSelectedSession(...args),
+    onDismissError: latestOptional(() => actions.onDismissError),
+    onEdit: (...args) => actions.onEdit(...args),
+    onPasteClipboardImage: (...args) => actions.onPasteClipboardImage(...args),
+    onPickFiles: (...args) => actions.onPickFiles(...args),
+    onPickFolders: (...args) => actions.onPickFolders(...args),
+    onPickImages: (...args) => actions.onPickImages(...args),
+    onReload: (...args) => actions.onReload(...args),
+    onRemoveAttachment: (...args) => actions.onRemoveAttachment(...args),
+    onRestoreToMessage: latestOptional(() => actions.onRestoreToMessage),
+    onRetryResume: (...args) => actions.onRetryResume(...args),
+    onSteer: (...args) => actions.onSteer(...args),
+    onSubmit: (...args) => actions.onSubmit(...args),
+    onThreadMessagesChange: (...args) => actions.onThreadMessagesChange(...args),
+    onToggleSelectedPin: (...args) => actions.onToggleSelectedPin(...args),
+    onTranscribeAudio: latestOptional(() => actions.onTranscribeAudio)
+  }
+}
+
+export function latestSidebarActions(actions: SidebarActions): SidebarActions {
+  return {
+    onArchiveSession: (...args) => actions.onArchiveSession(...args),
+    onBranchSession: (...args) => actions.onBranchSession(...args),
+    onDeleteSession: (...args) => actions.onDeleteSession(...args),
+    onLoadMoreMessaging: latestOptional(() => actions.onLoadMoreMessaging),
+    onLoadMoreProfileSessions: latestOptional(() => actions.onLoadMoreProfileSessions),
+    onLoadMoreSessions: (...args) => actions.onLoadMoreSessions(...args),
+    onManageCronJob: (...args) => actions.onManageCronJob(...args),
+    onNavigate: (...args) => actions.onNavigate(...args),
+    onNewSessionInWorkspace: (...args) => actions.onNewSessionInWorkspace(...args),
+    onNewSessionSplit: (...args) => actions.onNewSessionSplit(...args),
+    onResumeSession: (...args) => actions.onResumeSession(...args),
+    onTriggerCronJob: (...args) => actions.onTriggerCronJob(...args)
+  }
+}
diff --git a/apps/desktop/src/app/contrib/surfaces.tsx b/apps/desktop/src/app/contrib/surfaces.tsx
index 482d37a4bba..852c5311a29 100644
--- a/apps/desktop/src/app/contrib/surfaces.tsx
+++ b/apps/desktop/src/app/contrib/surfaces.tsx
@@ -25,6 +25,7 @@ import { useStatusbarItems } from '../shell/hooks/use-statusbar-items'
 import { ModelMenuPanel } from '../shell/model-menu-panel'
 import { StatusbarControls } from '../shell/statusbar-controls'
 
+import { latestChatActions, latestSidebarActions } from './latest-actions'
 import { setStatusbarItemGroup, useStatusbarContributions } from './panes'
 import type { SidebarActions, WiringActions } from './types'
 
@@ -48,7 +49,9 @@ export const SidebarSurface = memo(function SidebarSurface({
   actions: SidebarActions
   currentView: ComponentProps<typeof ChatSidebar>['currentView']
 }) {
-  return <ChatSidebar currentView={currentView} {...actions} />
+  const latestActions = useMemo(() => latestSidebarActions(actions), [actions])
+
+  return <ChatSidebar currentView={currentView} {...latestActions} />
 })
 
 export const TerminalSurface = memo(function TerminalSurface() {
@@ -137,33 +140,14 @@ export const ChatRoutesSurface = memo(function ChatRoutesSurface({
     [actions, activeGatewayProfile, gateway, gatewayState]
   )
 
+  const chatActions = useMemo(() => latestChatActions(actions), [actions])
+
   const chatView = (
     <ChatView
       gateway={gateway}
       maxVoiceRecordingSeconds={maxVoiceRecordingSeconds}
       modelMenuContent={modelMenuContent}
-      onAddContextRef={actions.onAddContextRef}
-      onAddUrl={actions.onAddUrl}
-      onAttachDroppedItems={actions.onAttachDroppedItems}
-      onAttachImageBlob={actions.onAttachImageBlob}
-      onBranchInNewChat={actions.onBranchInNewChat}
-      onCancel={actions.onCancel}
-      onDeleteSelectedSession={actions.onDeleteSelectedSession}
-      onDismissError={actions.onDismissError}
-      onEdit={actions.onEdit}
-      onPasteClipboardImage={actions.onPasteClipboardImage}
-      onPickFiles={actions.onPickFiles}
-      onPickFolders={actions.onPickFolders}
-      onPickImages={actions.onPickImages}
-      onReload={actions.onReload}
-      onRemoveAttachment={actions.onRemoveAttachment}
-      onRestoreToMessage={actions.onRestoreToMessage}
-      onRetryResume={actions.onRetryResume}
-      onSteer={actions.onSteer}
-      onSubmit={actions.onSubmit}
-      onThreadMessagesChange={actions.onThreadMessagesChange}
-      onToggleSelectedPin={actions.onToggleSelectedPin}
-      onTranscribeAudio={actions.onTranscribeAudio}
+      {...chatActions}
     />
   )
 
@@ -189,6 +173,7 @@ export const ChatRoutesSurface = memo(function ChatRoutesSurface({
       <Route element={null} path="profiles" />
       <Route element={null} path="settings" />
       <Route element={null} path="starmap" />
+      <Route element={null} path="webhooks" />
       {/* Registry-contributed pages (core features + plugins) render in the
           workspace pane like any built-in view — behind the same blast wall
           as every other contribution mount. */}
diff --git a/apps/desktop/src/app/contrib/wiring.tsx b/apps/desktop/src/app/contrib/wiring.tsx
index 978d328e228..ffdc79e65b7 100644
--- a/apps/desktop/src/app/contrib/wiring.tsx
+++ b/apps/desktop/src/app/contrib/wiring.tsx
@@ -55,7 +55,7 @@ import {
   setCurrentProvider,
   setMessages
 } from '@/store/session'
-import { focusOpenSession } from '@/store/session-states'
+import { focusedSessionNeedsRoute, focusOpenSession } from '@/store/session-states'
 import { clearSessionTodos, setSessionTodos, todosForHydration } from '@/store/todos'
 import { isSecondaryWindow } from '@/store/windows'
 import { useSkinCommand } from '@/themes/use-skin-command'
@@ -74,7 +74,14 @@ import { RemoteFolderPicker } from '../right-sidebar/files/remote-picker'
 import { resetProjectTreeState } from '../right-sidebar/files/use-project-tree'
 import { PersistentTerminal } from '../right-sidebar/terminal/persistent'
 import { closeAllTerminals } from '../right-sidebar/terminal/terminals'
-import { CRON_ROUTE, routeSessionId, sessionRoute, SETTINGS_ROUTE, syncWorkspaceIsPage } from '../routes'
+import {
+  $workspaceIsPage,
+  CRON_ROUTE,
+  routeSessionId,
+  sessionRoute,
+  SETTINGS_ROUTE,
+  syncWorkspaceIsPage
+} from '../routes'
 import { SessionPickerOverlay } from '../session-picker-overlay'
 import { SessionSwitcher } from '../session-switcher'
 import { useBackgroundQueueDrain } from '../session/hooks/use-background-queue-drain'
@@ -89,7 +96,7 @@ import { useRouteResume } from '../session/hooks/use-route-resume'
 import { useSessionActions } from '../session/hooks/use-session-actions'
 import { useSessionListActions } from '../session/hooks/use-session-list-actions'
 import { useSessionStateCache } from '../session/hooks/use-session-state-cache'
-import { startWorkspaceSession } from '../session/workspace-session-target'
+import { newSessionOpensTab, startWorkspaceSession } from '../session/workspace-session-target'
 import { useOverlayRouting } from '../shell/hooks/use-overlay-routing'
 import { useWindowControlsOverlayWidth } from '../shell/hooks/use-window-controls-overlay-width'
 import { titlebarControlsPosition } from '../shell/titlebar'
@@ -111,6 +118,7 @@ import type { WiringActions, WiringApi } from './types'
 const AgentsView = lazy(async () => ({ default: (await import('../agents')).AgentsView }))
 const CommandCenterView = lazy(async () => ({ default: (await import('../command-center')).CommandCenterView }))
 const CronView = lazy(async () => ({ default: (await import('../cron')).CronView }))
+const WebhooksView = lazy(async () => ({ default: (await import('../webhooks')).WebhooksView }))
 const ProfilesView = lazy(async () => ({ default: (await import('../profiles')).ProfilesView }))
 const SettingsView = lazy(async () => ({ default: (await import('../settings')).SettingsView }))
 const StarmapView = lazy(async () => ({ default: (await import('../starmap')).StarmapView }))
@@ -141,6 +149,7 @@ export function ContribWiring({ children }: { children: ReactNode }) {
   const billingSettingsRequest = useStore($billingSettingsRequest)
   const currentCwd = useStore($currentCwd)
 
+  // eslint-disable-next-line no-restricted-syntax -- one-shot request-seen sentinel, not an atom mirror
   useEffect(() => {
     if (billingSettingsRequest === billingSettingsSeenRef.current) {
       return
@@ -197,7 +206,8 @@ export function ContribWiring({ children }: { children: ReactNode }) {
     resetOverlayReturnRoute,
     settingsOpen,
     starmapOpen,
-    toggleCommandCenter
+    toggleCommandCenter,
+    webhooksOpen
   } = useOverlayRouting()
 
   const {
@@ -219,7 +229,7 @@ export function ContribWiring({ children }: { children: ReactNode }) {
     setMessages
   })
 
-  const { connectionRef, gatewayRef, requestGateway } = useGatewayRequest()
+  const { connectionRef, gateway, gatewayRef, requestGateway } = useGatewayRequest()
 
   const {
     loadMoreMessagingForPlatform,
@@ -248,7 +258,6 @@ export function ContribWiring({ children }: { children: ReactNode }) {
   )
 
   const { refreshProjectBranch } = useCwdActions({
-    activeSessionId,
     activeSessionIdRef,
     onSessionRuntimeInfo: updateActiveSessionRuntimeInfo,
     requestGateway
@@ -449,6 +458,7 @@ export function ContribWiring({ children }: { children: ReactNode }) {
   const freshSessionRequest = useStore($freshSessionRequest)
   const lastFreshRef = useRef(freshSessionRequest)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (freshSessionRequest === lastFreshRef.current) {
       return
@@ -463,6 +473,7 @@ export function ContribWiring({ children }: { children: ReactNode }) {
   // invalidateQueries on swap doesn't touch them).
   const lastGatewayProfileRef = useRef(activeGatewayProfile)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (activeGatewayProfile === lastGatewayProfileRef.current) {
       return
@@ -477,11 +488,22 @@ export function ContribWiring({ children }: { children: ReactNode }) {
     void refreshActiveProfile()
   }, [activeGatewayProfile, refreshCurrentModel, refreshHermesConfig])
 
-  // New session anchored to a workspace (sidebar "+" on a project/worktree).
-  // Seeds cwd + branch from the clicked workspace; an explicit worktree path
-  // also drills the sidebar into that project so the new lane is visible.
+  // New session anchored to a workspace. Seeds cwd + branch from the clicked
+  // workspace; an explicit worktree path also drills the sidebar into that
+  // project so the new lane is visible.
+  //
+  // `openTab` is the sidebar "+" behavior: once a chat is loaded, stack a new
+  // tab instead of replacing it (see newSessionOpensTab). The composer's
+  // "branch off into a new worktree" flow keeps the fresh-draft path — it
+  // prefills the MAIN composer right after, so it has to own that surface.
   const startSessionInWorkspace = useCallback(
-    (path: null | string) => {
+    (path: null | string, options?: { openTab?: boolean }) => {
+      if (options?.openTab && newSessionOpensTab(activeSessionIdRef.current, $selectedStoredSessionId.get())) {
+        void openNewSessionTile('center', { cwd: path, listed: false })
+
+        return
+      }
+
       startWorkspaceSession({
         activeSessionIdRef,
         followActiveSessionCwd,
@@ -491,7 +513,7 @@ export function ContribWiring({ children }: { children: ReactNode }) {
         startFreshSessionDraft
       })
     },
-    [activeSessionIdRef, requestGateway, startFreshSessionDraft]
+    [activeSessionIdRef, openNewSessionTile, requestGateway, startFreshSessionDraft]
   )
 
   // Composer "branch off into a new worktree": open a fresh session anchored
@@ -499,6 +521,7 @@ export function ContribWiring({ children }: { children: ReactNode }) {
   const startWorkSessionRequest = useStore($startWorkSessionRequest)
   const lastStartWorkTokenRef = useRef(startWorkSessionRequest?.token ?? 0)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!startWorkSessionRequest || startWorkSessionRequest.token === lastStartWorkTokenRef.current) {
       return
@@ -786,7 +809,7 @@ export function ContribWiring({ children }: { children: ReactNode }) {
       navigate(CRON_ROUTE)
     },
     onNavigate: selectSidebarItem,
-    onNewSessionInWorkspace: startSessionInWorkspace,
+    onNewSessionInWorkspace: path => startSessionInWorkspace(path, { openTab: true }),
     onNewSessionSplit: dir => void openNewSessionTile(dir),
     onPasteClipboardImage: opts => composer.pasteClipboardImage(opts),
     onPickFiles: () => void composer.pickContextPaths('file'),
@@ -796,9 +819,12 @@ export function ContribWiring({ children }: { children: ReactNode }) {
     onRemoveAttachment: id => void composer.removeAttachment(id),
     onRestoreToMessage: restoreToMessage,
     // Already on screen (open tile, or the main session)? Jump to its tab;
-    // otherwise load it into main.
+    // otherwise load it into main. From a full page (artifacts, skills, …) a
+    // `'main'` hit still has to route back: fronting the workspace tab alone
+    // leaves the page showing, so clicking the ACTIVE session was a no-op and
+    // the user had to bounce off another row to get back to the chat.
     onResumeSession: sessionId => {
-      if (!focusOpenSession(sessionId)) {
+      if (focusedSessionNeedsRoute(focusOpenSession(sessionId), $workspaceIsPage.get())) {
         navigate(sessionRoute(sessionId))
       }
     },
@@ -937,14 +963,10 @@ export function ContribWiring({ children }: { children: ReactNode }) {
           requestGateway={requestGateway}
         />
       )}
-      <ModelPickerOverlay
-        gateway={gatewayRef.current || undefined}
-        onSelect={selectModel}
-        profile={activeGatewayProfile}
-      />
+      <ModelPickerOverlay gateway={gateway || undefined} onSelect={selectModel} profile={activeGatewayProfile} />
       <SessionPickerOverlay onResume={resumeSession} />
       <ModelVisibilityOverlay
-        gateway={gatewayRef.current || undefined}
+        gateway={gateway || undefined}
         onOpenProviders={openProviderSettings}
         profile={activeGatewayProfile}
       />
@@ -960,7 +982,7 @@ export function ContribWiring({ children }: { children: ReactNode }) {
       {settingsOpen && (
         <Suspense fallback={null}>
           <SettingsView
-            gateway={gatewayRef.current}
+            gateway={gateway}
             onClose={closeOverlayToPreviousRoute}
             onConfigSaved={() => {
               void refreshHermesConfig()
@@ -1006,6 +1028,12 @@ export function ContribWiring({ children }: { children: ReactNode }) {
         </Suspense>
       )}
 
+      {webhooksOpen && (
+        <Suspense fallback={null}>
+          <WebhooksView onClose={closeOverlayToPreviousRoute} />
+        </Suspense>
+      )}
+
       {profilesOpen && (
         <Suspense fallback={null}>
           <ProfilesView onClose={closeOverlayToPreviousRoute} />
diff --git a/apps/desktop/src/app/cron/blueprints.test.ts b/apps/desktop/src/app/cron/blueprints.test.ts
new file mode 100644
index 00000000000..5331f052f3f
--- /dev/null
+++ b/apps/desktop/src/app/cron/blueprints.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+
+import type { AutomationBlueprint } from '@/hermes'
+
+import { initialBlueprintValues } from './blueprints'
+
+function blueprint(fields: AutomationBlueprint['fields']): AutomationBlueprint {
+  return {
+    key: 'test',
+    title: 'Test',
+    description: '',
+    category: 'general',
+    tags: [],
+    command: '',
+    appUrl: '',
+    fields
+  }
+}
+
+describe('initialBlueprintValues', () => {
+  it('seeds each field from its default', () => {
+    const values = initialBlueprintValues(
+      blueprint([
+        { name: 'time', type: 'time', label: 'Time', default: '08:00', options: [], optional: false, help: '' },
+        {
+          name: 'topic',
+          type: 'enum',
+          label: 'Topic',
+          default: 'news',
+          options: ['news', 'sports'],
+          optional: false,
+          help: ''
+        }
+      ])
+    )
+
+    expect(values).toEqual({ time: '08:00', topic: 'news' })
+  })
+
+  it('falls back to an empty string when a field has no default', () => {
+    const values = initialBlueprintValues(
+      blueprint([{ name: 'topic', type: 'text', label: 'Topic', default: null, options: [], optional: true, help: '' }])
+    )
+
+    expect(values).toEqual({ topic: '' })
+  })
+
+  it('returns an empty object for a blueprint with no fields', () => {
+    expect(initialBlueprintValues(blueprint([]))).toEqual({})
+  })
+
+  it("seeds the deliver slot to 'local' when its default is the dashboard-only 'origin'", () => {
+    const values = initialBlueprintValues(
+      blueprint([
+        {
+          name: 'deliver',
+          type: 'enum',
+          label: 'Deliver',
+          default: 'origin',
+          options: ['origin', 'local', 'telegram'],
+          optional: false,
+          help: ''
+        }
+      ])
+    )
+
+    expect(values).toEqual({ deliver: 'local' })
+  })
+
+  it("seeds the deliver slot to 'local' when it has no default", () => {
+    const values = initialBlueprintValues(
+      blueprint([
+        {
+          name: 'deliver',
+          type: 'enum',
+          label: 'Deliver',
+          default: null,
+          options: ['origin', 'local'],
+          optional: false,
+          help: ''
+        }
+      ])
+    )
+
+    expect(values).toEqual({ deliver: 'local' })
+  })
+
+  it('leaves a non-origin deliver default untouched', () => {
+    const values = initialBlueprintValues(
+      blueprint([
+        {
+          name: 'deliver',
+          type: 'enum',
+          label: 'Deliver',
+          default: 'telegram',
+          options: ['origin', 'local', 'telegram'],
+          optional: false,
+          help: ''
+        }
+      ])
+    )
+
+    expect(values).toEqual({ deliver: 'telegram' })
+  })
+})
diff --git a/apps/desktop/src/app/cron/blueprints.tsx b/apps/desktop/src/app/cron/blueprints.tsx
new file mode 100644
index 00000000000..e8e3d0fabb2
--- /dev/null
+++ b/apps/desktop/src/app/cron/blueprints.tsx
@@ -0,0 +1,91 @@
+import { Input } from '@/components/ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import type { AutomationBlueprint, AutomationBlueprintField } from '@/hermes'
+
+// The blueprint catalog is shared with the dashboard, so its deliver slot
+// defaults to "origin" (the chat/home-channel a dashboard or gateway job was
+// created from). Desktop has no origin chat, so seed the deliver slot to the
+// desktop's native target ("local" = This desktop) instead. The dialog then
+// renders that slot with the shared DeliverSelect (backend-sourced targets), so
+// the raw "origin" option never reaches the desktop UI.
+const DELIVER_FIELD = 'deliver'
+const DESKTOP_DELIVER_DEFAULT = 'local'
+
+function isDeliverField(field: AutomationBlueprintField): boolean {
+  return field.name === DELIVER_FIELD
+}
+
+// Initial form state for a blueprint = each field's default (or ''). Pure so the
+// suite can assert the form seeds correctly without mounting React. The deliver
+// slot is special-cased: an "origin" default (or empty) becomes "local" so a
+// desktop-created job delivers to This desktop instead of nowhere.
+export function initialBlueprintValues(blueprint: AutomationBlueprint): Record<string, string> {
+  const out: Record<string, string> = {}
+
+  for (const field of blueprint.fields) {
+    const seeded = field.default ?? ''
+    out[field.name] = isDeliverField(field) && (seeded === '' || seeded === 'origin') ? DESKTOP_DELIVER_DEFAULT : seeded
+  }
+
+  return out
+}
+
+// A slot-level validation error from the backend arrives as "422: <message>"
+// (or "<code>: <message>"); strip the leading numeric code for inline display.
+export function cleanBlueprintFieldError(message: string): string {
+  return message.replace(/^\d+:\s*/, '')
+}
+
+// Help text to show under a slot control. The backend deliver help is
+// origin/dashboard-centric and even contradicts desktop semantics ("local =
+// save only" vs. This desktop), and the DeliverSelect is self-explanatory —
+// skip it for the deliver slot.
+export function blueprintSlotHelp(field: AutomationBlueprintField): string | undefined {
+  return field.help && field.type !== 'text' && !isDeliverField(field) ? field.help : undefined
+}
+
+// Renders one blueprint slot's control (enum/weekdays → Select, time → time
+// input, else text). The deliver slot is handled separately by the dialog's
+// shared DeliverSelect, so it's not rendered here.
+export function BlueprintSlotControl({
+  field,
+  id,
+  onChange,
+  value
+}: {
+  field: AutomationBlueprintField
+  id: string
+  onChange: (next: string) => void
+  value: string
+}) {
+  if (field.type === 'enum' || field.type === 'weekdays') {
+    return (
+      <Select onValueChange={onChange} value={value}>
+        <SelectTrigger className="h-9 rounded-md" id={id}>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {field.options.map(option => (
+            <SelectItem key={option} value={option}>
+              {option}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    )
+  }
+
+  if (field.type === 'time') {
+    return <Input id={id} onChange={event => onChange(event.target.value)} type="time" value={value} />
+  }
+
+  return (
+    <Input
+      id={id}
+      onChange={event => onChange(event.target.value)}
+      placeholder={field.help || field.label}
+      type="text"
+      value={value}
+    />
+  )
+}
diff --git a/apps/desktop/src/app/cron/index.tsx b/apps/desktop/src/app/cron/index.tsx
index e0c421e4105..75e0020a793 100644
--- a/apps/desktop/src/app/cron/index.tsx
+++ b/apps/desktop/src/app/cron/index.tsx
@@ -14,6 +14,7 @@ import {
   DialogHeader,
   DialogTitle
 } from '@/components/ui/dialog'
+import { Field, FieldHint } from '@/components/ui/field'
 import { Input } from '@/components/ui/input'
 import {
   Select,
@@ -26,11 +27,16 @@ import {
 } from '@/components/ui/select'
 import { Textarea } from '@/components/ui/textarea'
 import {
+  type AutomationBlueprint,
   createCronJob,
+  type CronDeliveryTarget,
   type CronJob,
   deleteCronJob,
+  getAutomationBlueprints,
+  getCronDeliveryTargets,
   getCronJobRuns,
   getCronJobs,
+  instantiateAutomationBlueprint,
   pauseCronJob,
   resumeCronJob,
   type SessionInfo,
@@ -65,6 +71,7 @@ import {
 } from '../overlays/panel'
 import type { SetStatusbarItemGroup } from '../shell/statusbar-controls'
 
+import { BlueprintSlotControl, blueprintSlotHelp, cleanBlueprintFieldError, initialBlueprintValues } from './blueprints'
 import { cronEditorUpdates, jobIsScriptOnly, validateCronEditor } from './cron-job-model'
 import { jobState, jobTitle, STATE_DOT } from './job-state'
 
@@ -74,7 +81,9 @@ const DEFAULT_DELIVER = 'local'
 // the model picker carries this sentinel and is mapped back to '' on save.
 const MODEL_DEFAULT_VALUE = '__default__'
 
-const DELIVERY_VALUES: readonly string[] = ['local', 'telegram', 'discord', 'slack', 'email']
+// "Start from" default: the manual editor (blank cron). Any other value is a
+// blueprint key. Blueprint keys never collide with this sentinel.
+const CUSTOM_TEMPLATE = 'custom'
 
 const SCHEDULE_OPTIONS: ReadonlyArray<ScheduleOption> = [
   { expr: '0 9 * * *', value: 'daily' },
@@ -318,6 +327,7 @@ export function CronView({ onClose, onOpenSession, setStatusbarItemGroup: _setSt
   // Sidebar → "open this job": resolve the focus id (or name) to a job, select
   // it, queue a scroll, then clear the one-shot focus so re-opening cron
   // normally doesn't re-trigger it.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!focusJobId) {
       return
@@ -346,6 +356,7 @@ export function CronView({ onClose, onOpenSession, setStatusbarItemGroup: _setSt
   )
 
   // Scroll a sidebar-opened job into view once its list row is mounted.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const target = pendingScrollRef.current
 
@@ -437,8 +448,28 @@ export function CronView({ onClose, onOpenSession, setStatusbarItemGroup: _setSt
     setEditor({ mode: 'closed' })
   }
 
+  // Blueprint instantiation is a distinct backend path (fills typed slots, then
+  // creates the job) so it can't share the raw-cron onSave contract. Merge the
+  // created job into $cronJobs like every other create path. A blueprint writes a
+  // real per-profile job, and "all" is not a writable target — collapse it to
+  // 'default', matching the manual create path in handleEditorSave.
+  async function handleBlueprintCreate(blueprint: AutomationBlueprint, values: Record<string, string>) {
+    const profile = profileScope === ALL_PROFILES ? 'default' : profileScope
+    const job = await instantiateAutomationBlueprint({ blueprint: blueprint.key, values }, profile)
+
+    updateCronJobs(rows => {
+      const rest = rows.filter(row => row.id !== job.id)
+
+      return [...rest, job]
+    })
+    notify({ kind: 'success', title: c.blueprints.scheduled, message: asText(job.schedule_display) || blueprint.title })
+    setEditor({ mode: 'closed' })
+  }
+
   return (
     <Panel closeLabel={c.close} onClose={onClose}>
+      <PanelHeader subtitle={c.count(totalCount)} title={c.title} />
+
       {loading && jobs.length === 0 ? (
         <PageLoader label={c.loading} />
       ) : totalCount === 0 ? (
@@ -453,59 +484,61 @@ export function CronView({ onClose, onOpenSession, setStatusbarItemGroup: _setSt
           title={c.emptyTitleNew}
         />
       ) : (
-        <>
-          <PanelHeader subtitle={c.count(totalCount)} title={c.title} />
-          <PanelBody>
-            <PanelList
-              onSearchChange={setQuery}
-              searchHints={jobs
-                .map(jobTitle)
-                .filter(Boolean)
-                .slice(0, 5)
-                .map(title => t.common.tryHint(title))}
-              searchLabel={c.search}
-              searchPlaceholder={c.search}
-              searchValue={query}
-            >
-              {visibleJobs.map(job => (
-                <CronJobListRow
-                  active={selectedJob?.id === job.id}
-                  job={job}
-                  key={job.id}
-                  menu={
-                    <PanelRowMenu
-                      items={[
-                        { icon: 'edit', label: c.edit, onSelect: () => setEditor({ mode: 'edit', job }) },
-                        { icon: 'trash', label: t.common.delete, onSelect: () => setPendingDelete(job), tone: 'danger' }
-                      ]}
-                    />
-                  }
-                  onSelect={() => setSelectedJobId(job.id)}
-                />
-              ))}
-              {visibleJobs.length === 0 && (
-                <p className="px-2 py-4 text-center text-xs text-muted-foreground">{c.emptyTitleSearch}</p>
-              )}
-              <PanelAddButton label={c.newCron} onClick={() => setEditor({ mode: 'create' })} />
-            </PanelList>
-
-            {selectedJob ? (
-              <CronJobDetail
-                busy={busyJobId === selectedJob.id}
-                c={c}
-                job={selectedJob}
-                onOpenSession={onOpenSession}
-                onPauseResume={() => void handlePauseResume(selectedJob)}
-                onTrigger={() => void handleTrigger(selectedJob)}
+        <PanelBody>
+          <PanelList
+            onSearchChange={setQuery}
+            searchHints={jobs
+              .map(jobTitle)
+              .filter(Boolean)
+              .slice(0, 5)
+              .map(title => t.common.tryHint(title))}
+            searchLabel={c.search}
+            searchPlaceholder={c.search}
+            searchValue={query}
+          >
+            {visibleJobs.map(job => (
+              <CronJobListRow
+                active={selectedJob?.id === job.id}
+                job={job}
+                key={job.id}
+                menu={
+                  <PanelRowMenu
+                    items={[
+                      { icon: 'edit', label: c.edit, onSelect: () => setEditor({ mode: 'edit', job }) },
+                      { icon: 'trash', label: t.common.delete, onSelect: () => setPendingDelete(job), tone: 'danger' }
+                    ]}
+                  />
+                }
+                onSelect={() => setSelectedJobId(job.id)}
               />
-            ) : (
-              <PanelEmpty description={c.emptyDescSearch} icon="search" />
+            ))}
+            {visibleJobs.length === 0 && (
+              <p className="px-2 py-4 text-center text-xs text-muted-foreground">{c.emptyTitleSearch}</p>
             )}
-          </PanelBody>
-        </>
+            <PanelAddButton label={c.newCron} onClick={() => setEditor({ mode: 'create' })} />
+          </PanelList>
+
+          {selectedJob ? (
+            <CronJobDetail
+              busy={busyJobId === selectedJob.id}
+              c={c}
+              job={selectedJob}
+              onOpenSession={onOpenSession}
+              onPauseResume={() => void handlePauseResume(selectedJob)}
+              onTrigger={() => void handleTrigger(selectedJob)}
+            />
+          ) : (
+            <PanelEmpty description={c.emptyDescSearch} icon="search" />
+          )}
+        </PanelBody>
       )}
 
-      <CronEditorDialog editor={editor} onClose={() => setEditor({ mode: 'closed' })} onSave={handleEditorSave} />
+      <CronEditorDialog
+        editor={editor}
+        onBlueprintCreate={handleBlueprintCreate}
+        onClose={() => setEditor({ mode: 'closed' })}
+        onSave={handleEditorSave}
+      />
 
       <Dialog onOpenChange={open => !open && !deleting && setPendingDelete(null)} open={pendingDelete !== null}>
         <DialogContent className="max-w-md">
@@ -593,7 +626,7 @@ function CronJobDetail({
             <PanelAction disabled={busy} icon={isPaused ? 'play' : 'debug-pause'} onClick={onPauseResume}>
               {isPaused ? c.resumeTitle : c.pauseTitle}
             </PanelAction>
-            <PanelAction disabled={busy} icon="zap" onClick={onTrigger}>
+            <PanelAction disabled={busy} icon="zap" onClick={onTrigger} primary>
               {c.triggerNow}
             </PanelAction>
           </div>
@@ -727,12 +760,57 @@ function CronJobRuns({
   )
 }
 
+// Label a cron delivery target: 'local' → localized "This desktop", known
+// platforms → their delivery label, anything else → the backend name. Configured
+// platforms without a cron home channel get a "set a home channel first" hint.
+function deliverTargetLabel(target: CronDeliveryTarget, c: Translations['cron']): string {
+  const base = target.id === 'local' ? c.deliveryLabels.local : (c.deliveryLabels[target.id] ?? target.name)
+
+  return target.id !== 'local' && !target.home_target_set ? `${base} — ${c.deliverNeedsHomeChannel}` : base
+}
+
+// The delivery-target dropdown, shared by the manual cron editor and the
+// blueprint form so both offer exactly the connected platforms (never a
+// hardcoded list). While the targets load, keep the current value selectable.
+function DeliverSelect({
+  c,
+  id,
+  onChange,
+  targets,
+  value
+}: {
+  c: Translations['cron']
+  id: string
+  onChange: (next: string) => void
+  targets: CronDeliveryTarget[]
+  value: string
+}) {
+  const options = targets.length > 0 ? targets : [{ home_env_var: null, home_target_set: true, id: value, name: value }]
+
+  return (
+    <Select onValueChange={onChange} value={value}>
+      <SelectTrigger className="h-9 rounded-md" id={id}>
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent>
+        {options.map(target => (
+          <SelectItem key={target.id} value={target.id}>
+            {deliverTargetLabel(target, c)}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  )
+}
+
 function CronEditorDialog({
   editor,
+  onBlueprintCreate,
   onClose,
   onSave
 }: {
   editor: EditorState
+  onBlueprintCreate: (blueprint: AutomationBlueprint, values: Record<string, string>) => Promise<void>
   onClose: () => void
   onSave: (values: EditorValues) => Promise<void>
 }) {
@@ -751,16 +829,47 @@ function CronEditorDialog({
   // Per-job model override, encoded as `${providerSlug}:${model}` (split on the
   // first ':' when saving). MODEL_DEFAULT_VALUE = follow the global default.
   const [modelChoice, setModelChoice] = useState(MODEL_DEFAULT_VALUE)
+  // Blueprint fills typed slots (time/enum/weekdays/text) instead of the raw
+  // cron fields; the backend renders the prompt + schedule from them.
+  const [slotValues, setSlotValues] = useState<Record<string, string>>({})
+  // Create mode can start from a ready-made blueprint instead of a blank cron.
+  // CUSTOM_TEMPLATE (default) = the manual editor; any other value is a
+  // blueprint key that swaps the form for that blueprint's typed slots.
+  const [templateChoice, setTemplateChoice] = useState(CUSTOM_TEMPLATE)
   const [saving, setSaving] = useState(false)
   const [error, setError] = useState<null | string>(null)
 
+  // The blueprint catalog powers the create dialog's "Start from" dropdown; it's
+  // meaningless when editing an existing job, so skip the fetch there.
+  const blueprintsQuery = useQuery({
+    queryKey: ['cron-blueprints'],
+    queryFn: async () => (await getAutomationBlueprints()).blueprints,
+    enabled: open && !isEdit
+  })
+
+  const blueprintList = blueprintsQuery.data ?? []
+
+  const blueprint =
+    templateChoice === CUSTOM_TEMPLATE ? null : (blueprintList.find(item => item.key === templateChoice) ?? null)
+
+  const isBlueprint = blueprint !== null
+
   // Same catalog the chat model picker uses: configured providers and their
-  // actually-available models only. Script-only jobs never run an agent, so
-  // skip the fetch entirely for them.
+  // actually-available models only. Script-only + blueprint forms never pick a
+  // model here, so skip the fetch entirely for them.
   const modelOptions = useQuery({
     queryKey: ['model-options', 'global'],
     queryFn: () => requestModelOptions({}),
-    enabled: open && !scriptOnlyJob
+    enabled: open && !scriptOnlyJob && !isBlueprint
+  })
+
+  // Single source of truth for where a cron can deliver (local + configured
+  // gateways) — same endpoint the dashboard uses, so no dialog offers a platform
+  // that isn't connected. Shared by the manual editor and the blueprint form.
+  const deliveryTargets = useQuery({
+    queryKey: ['cron-delivery-targets'],
+    queryFn: getCronDeliveryTargets,
+    enabled: open
   })
 
   useEffect(() => {
@@ -774,10 +883,19 @@ function CronEditorDialog({
     setSchedulePreset(initial ? scheduleOptionForExpr(jobScheduleExpr(initial)).value : 'daily')
     setDeliver(initial ? jobDeliver(initial) : DEFAULT_DELIVER)
     setModelChoice(initial && jobModel(initial) ? `${jobProvider(initial)}:${jobModel(initial)}` : MODEL_DEFAULT_VALUE)
+    setSlotValues({})
+    setTemplateChoice(CUSTOM_TEMPLATE)
     setError(null)
     setSaving(false)
   }, [initial, open])
 
+  // Seed the typed slots with the blueprint's defaults whenever a blueprint is
+  // picked from "Start from" (and reset them when switching back to Custom).
+  useEffect(() => {
+    setSlotValues(blueprint ? initialBlueprintValues(blueprint) : {})
+    setError(null)
+  }, [blueprint])
+
   const selectedScheduleOption =
     SCHEDULE_OPTIONS.find(candidate => candidate.value === schedulePreset) ?? SCHEDULE_OPTIONS[0]
 
@@ -855,6 +973,26 @@ function CronEditorDialog({
     }
   }
 
+  async function handleBlueprintSubmit(event: React.FormEvent) {
+    event.preventDefault()
+
+    if (!blueprint) {
+      return
+    }
+
+    setSaving(true)
+    setError(null)
+
+    try {
+      await onBlueprintCreate(blueprint, slotValues)
+    } catch (err) {
+      // 422 carries the slot-level validation message; surface it inline.
+      setError(cleanBlueprintFieldError(err instanceof Error ? err.message : String(err)))
+    } finally {
+      setSaving(false)
+    }
+  }
+
   return (
     <Dialog onOpenChange={value => !value && !saving && onClose()} open={open}>
       <DialogContent className="max-w-lg">
@@ -863,167 +1001,203 @@ function CronEditorDialog({
           <DialogDescription>{isEdit ? c.editDesc : c.createDesc}</DialogDescription>
         </DialogHeader>
 
-        <form className="grid gap-4" onSubmit={handleSubmit}>
-          {scriptOnlyJob && initial && (
-            <FieldHint>
-              {c.scriptOnlyEditHint} <span className="font-mono">{initial.id}</span>
-            </FieldHint>
-          )}
-
-          <Field htmlFor="cron-name" label={c.nameLabel} optional optionalLabel={c.optional}>
-            <Input
-              autoFocus
-              id="cron-name"
-              onChange={event => setName(event.target.value)}
-              placeholder={c.namePlaceholder}
-              value={name}
-            />
+        {!isEdit && blueprintList.length > 0 && (
+          <Field htmlFor="cron-template" label={c.blueprints.startFrom}>
+            <Select onValueChange={setTemplateChoice} value={templateChoice}>
+              <SelectTrigger className="h-9 rounded-md" id="cron-template">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value={CUSTOM_TEMPLATE}>{c.blueprints.custom}</SelectItem>
+                {blueprintList.map(item => (
+                  <SelectItem key={item.key} value={item.key}>
+                    {item.title}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            {blueprint?.description && <FieldHint>{blueprint.description}</FieldHint>}
           </Field>
+        )}
 
-          <Field htmlFor="cron-prompt" label={c.promptLabel} optional={scriptOnlyJob} optionalLabel={c.optional}>
-            <Textarea
-              className="min-h-24 font-mono"
-              id="cron-prompt"
-              onChange={event => setPrompt(event.target.value)}
-              placeholder={c.promptPlaceholder}
-              value={prompt}
-            />
-          </Field>
+        {isBlueprint && blueprint ? (
+          <form className="grid gap-4" onSubmit={handleBlueprintSubmit}>
+            {blueprint.fields.map(field => {
+              const fieldId = `blueprint-${blueprint.key}-${field.name}`
+              const help = blueprintSlotHelp(field)
 
-          <div className="grid items-start gap-4 sm:grid-cols-2">
-            <Field htmlFor="cron-frequency" label={c.frequencyLabel}>
-              <Select onValueChange={handleSchedulePresetChange} value={schedulePreset}>
-                <SelectTrigger className="h-9 rounded-md" id="cron-frequency">
-                  <SelectValue />
-                </SelectTrigger>
-                <SelectContent>
-                  {SCHEDULE_OPTIONS.map(option => (
-                    <SelectItem key={option.value} value={option.value}>
-                      {c.scheduleLabels[option.value]}
-                    </SelectItem>
-                  ))}
-                </SelectContent>
-              </Select>
-            </Field>
-
-            <Field htmlFor="cron-deliver" label={c.deliverLabel}>
-              <Select onValueChange={setDeliver} value={deliver}>
-                <SelectTrigger className="h-9 rounded-md" id="cron-deliver">
-                  <SelectValue />
-                </SelectTrigger>
-                <SelectContent>
-                  {DELIVERY_VALUES.map(value => (
-                    <SelectItem key={value} value={value}>
-                      {c.deliveryLabels[value]}
-                    </SelectItem>
-                  ))}
-                </SelectContent>
-              </Select>
-            </Field>
-          </div>
-
-          {!scriptOnlyJob && (
-            <Field htmlFor="cron-model" label={c.modelLabel} optional optionalLabel={c.optional}>
-              <Select onValueChange={setModelChoice} value={modelChoice}>
-                <SelectTrigger className="h-9 rounded-md" id="cron-model">
-                  <SelectValue />
-                </SelectTrigger>
-                <SelectContent>
-                  <SelectItem value={MODEL_DEFAULT_VALUE}>{c.modelDefault}</SelectItem>
-                  {!modelChoiceKnown && (
-                    <SelectItem className="font-mono" value={modelChoice}>
-                      {modelChoice.slice(modelChoice.indexOf(':') + 1)}
-                    </SelectItem>
+              return (
+                <Field htmlFor={fieldId} key={field.name} label={field.label}>
+                  {field.name === 'deliver' ? (
+                    // Use the shared, backend-sourced delivery targets (same as the
+                    // manual editor) rather than the blueprint's static field.options,
+                    // so both dialogs offer exactly the connected platforms.
+                    <DeliverSelect
+                      c={c}
+                      id={fieldId}
+                      onChange={next => setSlotValues(prev => ({ ...prev, [field.name]: next }))}
+                      targets={deliveryTargets.data ?? []}
+                      value={slotValues[field.name] ?? DEFAULT_DELIVER}
+                    />
+                  ) : (
+                    <BlueprintSlotControl
+                      field={field}
+                      id={fieldId}
+                      onChange={next => setSlotValues(prev => ({ ...prev, [field.name]: next }))}
+                      value={slotValues[field.name] ?? ''}
+                    />
                   )}
-                  {modelProviders.map(provider => (
-                    <SelectGroup key={provider.slug}>
-                      <SelectLabel>{provider.name}</SelectLabel>
-                      {(provider.models ?? []).map(model => (
-                        <SelectItem
-                          className="font-mono"
-                          key={`${provider.slug}:${model}`}
-                          value={`${provider.slug}:${model}`}
-                        >
-                          {model}
-                        </SelectItem>
-                      ))}
-                    </SelectGroup>
-                  ))}
-                </SelectContent>
-              </Select>
-            </Field>
-          )}
+                  {help && <FieldHint>{help}</FieldHint>}
+                </Field>
+              )
+            })}
 
-          {schedulePreset === 'custom' ? (
-            <Field htmlFor="cron-schedule" label={c.customScheduleLabel}>
-              <Input
-                className="font-mono"
-                id="cron-schedule"
-                onChange={event => setSchedule(event.target.value)}
-                placeholder={c.customPlaceholder}
-                value={schedule}
-              />
-              <FieldHint>{c.customHint}</FieldHint>
-            </Field>
-          ) : (
-            <div className="rounded-md bg-(--ui-bg-quinary) px-3 py-2">
-              <div className="flex flex-wrap items-center justify-between gap-2 text-xs">
-                <span className="font-medium text-foreground">{scheduleHint}</span>
-                <span className="font-mono text-muted-foreground">{schedule}</span>
+            {error && (
+              <div className="flex items-start gap-2 rounded-md bg-destructive/10 px-3 py-2 text-xs text-destructive">
+                <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
+                <span>{error}</span>
               </div>
-            </div>
-          )}
+            )}
 
-          {error && (
-            <div className="flex items-start gap-2 rounded-md bg-destructive/10 px-3 py-2 text-xs text-destructive">
-              <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
-              <span>{error}</span>
-            </div>
-          )}
+            <DialogFooter>
+              <Button disabled={saving} onClick={onClose} type="button" variant="outline">
+                {t.common.cancel}
+              </Button>
+              <Button disabled={saving} type="submit">
+                {saving ? c.blueprints.scheduling : c.blueprints.scheduleIt}
+              </Button>
+            </DialogFooter>
+          </form>
+        ) : (
+          <form className="grid gap-4" onSubmit={handleSubmit}>
+            {scriptOnlyJob && initial && (
+              <FieldHint>
+                {c.scriptOnlyEditHint} <span className="font-mono">{initial.id}</span>
+              </FieldHint>
+            )}
 
-          <DialogFooter>
-            <Button disabled={saving} onClick={onClose} type="button" variant="outline">
-              {t.common.cancel}
-            </Button>
-            <Button disabled={saving} type="submit">
-              {saving ? t.common.saving : isEdit ? c.saveChanges : c.createAction}
-            </Button>
-          </DialogFooter>
-        </form>
+            <Field htmlFor="cron-name" label={c.nameLabel} optional optionalLabel={c.optional}>
+              <Input
+                autoFocus
+                id="cron-name"
+                onChange={event => setName(event.target.value)}
+                placeholder={c.namePlaceholder}
+                value={name}
+              />
+            </Field>
+
+            <Field htmlFor="cron-prompt" label={c.promptLabel} optional={scriptOnlyJob} optionalLabel={c.optional}>
+              <Textarea
+                className="min-h-24 font-mono"
+                id="cron-prompt"
+                onChange={event => setPrompt(event.target.value)}
+                placeholder={c.promptPlaceholder}
+                value={prompt}
+              />
+            </Field>
+
+            <div className="grid items-start gap-4 sm:grid-cols-2">
+              <Field htmlFor="cron-frequency" label={c.frequencyLabel}>
+                <Select onValueChange={handleSchedulePresetChange} value={schedulePreset}>
+                  <SelectTrigger className="h-9 rounded-md" id="cron-frequency">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {SCHEDULE_OPTIONS.map(option => (
+                      <SelectItem key={option.value} value={option.value}>
+                        {c.scheduleLabels[option.value]}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </Field>
+
+              <Field htmlFor="cron-deliver" label={c.deliverLabel}>
+                <DeliverSelect
+                  c={c}
+                  id="cron-deliver"
+                  onChange={setDeliver}
+                  targets={deliveryTargets.data ?? []}
+                  value={deliver}
+                />
+              </Field>
+            </div>
+
+            {!scriptOnlyJob && (
+              <Field htmlFor="cron-model" label={c.modelLabel} optional optionalLabel={c.optional}>
+                <Select onValueChange={setModelChoice} value={modelChoice}>
+                  <SelectTrigger className="h-9 rounded-md" id="cron-model">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value={MODEL_DEFAULT_VALUE}>{c.modelDefault}</SelectItem>
+                    {!modelChoiceKnown && (
+                      <SelectItem className="font-mono" value={modelChoice}>
+                        {modelChoice.slice(modelChoice.indexOf(':') + 1)}
+                      </SelectItem>
+                    )}
+                    {modelProviders.map(provider => (
+                      <SelectGroup key={provider.slug}>
+                        <SelectLabel>{provider.name}</SelectLabel>
+                        {(provider.models ?? []).map(model => (
+                          <SelectItem
+                            className="font-mono"
+                            key={`${provider.slug}:${model}`}
+                            value={`${provider.slug}:${model}`}
+                          >
+                            {model}
+                          </SelectItem>
+                        ))}
+                      </SelectGroup>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </Field>
+            )}
+
+            {schedulePreset === 'custom' ? (
+              <Field htmlFor="cron-schedule" label={c.customScheduleLabel}>
+                <Input
+                  className="font-mono"
+                  id="cron-schedule"
+                  onChange={event => setSchedule(event.target.value)}
+                  placeholder={c.customPlaceholder}
+                  value={schedule}
+                />
+                <FieldHint>{c.customHint}</FieldHint>
+              </Field>
+            ) : (
+              <div className="rounded-md bg-(--ui-bg-quinary) px-3 py-2">
+                <div className="flex flex-wrap items-center justify-between gap-2 text-xs">
+                  <span className="font-medium text-foreground">{scheduleHint}</span>
+                  <span className="font-mono text-muted-foreground">{schedule}</span>
+                </div>
+              </div>
+            )}
+
+            {error && (
+              <div className="flex items-start gap-2 rounded-md bg-destructive/10 px-3 py-2 text-xs text-destructive">
+                <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
+                <span>{error}</span>
+              </div>
+            )}
+
+            <DialogFooter>
+              <Button disabled={saving} onClick={onClose} type="button" variant="outline">
+                {t.common.cancel}
+              </Button>
+              <Button disabled={saving} type="submit">
+                {saving ? t.common.saving : isEdit ? c.saveChanges : c.createAction}
+              </Button>
+            </DialogFooter>
+          </form>
+        )}
       </DialogContent>
     </Dialog>
   )
 }
 
-function Field({
-  children,
-  htmlFor,
-  label,
-  optional,
-  optionalLabel
-}: {
-  children: React.ReactNode
-  htmlFor: string
-  label: string
-  optional?: boolean
-  optionalLabel?: string
-}) {
-  return (
-    <div className="grid gap-1.5">
-      <label className="flex items-baseline gap-2 text-xs font-medium text-foreground" htmlFor={htmlFor}>
-        {label}
-        {optional && <span className="text-[0.65rem] font-normal text-muted-foreground">{optionalLabel}</span>}
-      </label>
-      {children}
-    </div>
-  )
-}
-
-function FieldHint({ children }: { children: React.ReactNode }) {
-  return <p className="text-[0.66rem] leading-4 text-muted-foreground">{children}</p>
-}
-
-type EditorState = { mode: 'closed' } | { mode: 'create' } | { job: CronJob; mode: 'edit' }
+type EditorState = { job: CronJob; mode: 'edit' } | { mode: 'closed' } | { mode: 'create' }
 
 interface EditorValues {
   deliver: string
diff --git a/apps/desktop/src/app/gateway/hooks/use-gateway-request.test.ts b/apps/desktop/src/app/gateway/hooks/use-gateway-request.test.ts
new file mode 100644
index 00000000000..72ad6a2a268
--- /dev/null
+++ b/apps/desktop/src/app/gateway/hooks/use-gateway-request.test.ts
@@ -0,0 +1,39 @@
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import type { HermesGateway } from '@/hermes'
+import { $gateway } from '@/store/gateway'
+
+import { useGatewayRequest } from './use-gateway-request'
+
+const fakeGateway = { connectionState: 'open' } as unknown as HermesGateway
+
+afterEach(() => {
+  $gateway.set(null)
+})
+
+describe('useGatewayRequest', () => {
+  // The composer's `/` completions only exist when ChatBar receives a non-null
+  // gateway PROP. `gatewayRef` is populated by a subscription effect, so it is
+  // still null on the first render — a surface that read the ref while
+  // rendering (session tiles / ⌘T tabs) shipped `gateway={null}` and silently
+  // lost slash completions. The returned `gateway` value must be live
+  // immediately so that never happens again.
+  it('exposes the live gateway on the first render, before effects run', () => {
+    $gateway.set(fakeGateway)
+
+    const { result } = renderHook(() => useGatewayRequest())
+
+    expect(result.current.gateway).toBe(fakeGateway)
+  })
+
+  it('tracks the gateway when the active socket changes', () => {
+    const { result } = renderHook(() => useGatewayRequest())
+
+    expect(result.current.gateway).toBeNull()
+
+    act(() => $gateway.set(fakeGateway))
+
+    expect(result.current.gateway).toBe(fakeGateway)
+  })
+})
diff --git a/apps/desktop/src/app/gateway/hooks/use-gateway-request.ts b/apps/desktop/src/app/gateway/hooks/use-gateway-request.ts
index 72bd08c98b5..04f53f785b4 100644
--- a/apps/desktop/src/app/gateway/hooks/use-gateway-request.ts
+++ b/apps/desktop/src/app/gateway/hooks/use-gateway-request.ts
@@ -9,6 +9,14 @@ import { $gatewayState, setConnection } from '@/store/session'
 
 export function useGatewayRequest() {
   const gatewayState = useStore($gatewayState)
+  // Reactive companion to `gatewayRef`. The ref exists so `requestGateway`
+  // keeps a stable identity and always reaches the live socket, but it is only
+  // populated by the subscription effect below — i.e. AFTER the first render.
+  // A component that reads `gatewayRef.current` while rendering therefore sees
+  // null on mount, and if the connection state doesn't happen to flip
+  // afterwards it never re-renders to pick the instance up. Anything that needs
+  // the gateway as a render-time VALUE (props, memo deps) must use this.
+  const gateway = useStore($gateway) as HermesGateway | null
   const gatewayRef = useRef<HermesGateway | null>(null)
 
   const connectionRef = useRef<Awaited<ReturnType<NonNullable<typeof window.hermesDesktop>['getConnection']>> | null>(
@@ -22,6 +30,7 @@ export function useGatewayRequest() {
   // message instead of the opaque "connection closed" that triggered the retry.
   const reauthErrorRef = useRef<unknown>(null)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     gatewayStateRef.current = gatewayState
   }, [gatewayState])
@@ -135,5 +144,5 @@ export function useGatewayRequest() {
     [ensureGatewayOpen]
   )
 
-  return { connectionRef, gatewayRef, requestGateway }
+  return { connectionRef, gateway, gatewayRef, requestGateway }
 }
diff --git a/apps/desktop/src/app/hooks/use-on-profile-switch.ts b/apps/desktop/src/app/hooks/use-on-profile-switch.ts
index 04662a8be2a..dfdfd84f2c6 100644
--- a/apps/desktop/src/app/hooks/use-on-profile-switch.ts
+++ b/apps/desktop/src/app/hooks/use-on-profile-switch.ts
@@ -10,6 +10,7 @@ export function useOnProfileSwitch(onSwitch: () => void): void {
   const profile = useStore($activeGatewayProfile)
   const first = useRef(true)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (first.current) {
       first.current = false
diff --git a/apps/desktop/src/app/overlays/overlay-split-layout.tsx b/apps/desktop/src/app/overlays/overlay-split-layout.tsx
index cf0200275a6..6ed570f4b99 100644
--- a/apps/desktop/src/app/overlays/overlay-split-layout.tsx
+++ b/apps/desktop/src/app/overlays/overlay-split-layout.tsx
@@ -4,7 +4,9 @@ import { TabDropdown } from '@/components/ui/tab-dropdown'
 import type { IconComponent } from '@/lib/icons'
 import { cn } from '@/lib/utils'
 
-import { PAGE_INSET_X, PAGE_MAX_W } from '../layout-constants'
+import { PAGE_MAX_W } from '../layout-constants'
+
+import { OVERLAY_TOP_CLEARANCE } from './overlay-view'
 
 // The wide rail and the narrow dropdown swap at exactly the width where
 // OverlaySplitLayout drops to a single column, so the rail never stacks.
@@ -57,10 +59,12 @@ export function OverlaySidebar({ children, className }: OverlaySidebarProps) {
   return (
     <aside
       className={cn(
-        // pt clears the in-card close button (the OverlayView now insets the
-        // whole card below the OS titlebar); the bg fills from the card's top
-        // edge so there's no surface-colored gap above the sidebar.
-        'flex min-h-0 flex-col gap-0.5 overflow-y-auto bg-(--ui-sidebar-surface-background) px-2.5 pb-3 pt-[calc(var(--titlebar-height)/2+1rem)]',
+        // The left links sit beside (not under) the floating close button, so
+        // they ride up via the shorter shared OVERLAY_TOP_CLEARANCE (same line
+        // as a Panel header) instead of main's taller X-clearance. The bg still
+        // fills from the card's top edge, so there's no gap above the sidebar.
+        'flex min-h-0 flex-col gap-0.5 overflow-y-auto bg-(--ui-sidebar-surface-background) px-2.5 pb-3',
+        OVERLAY_TOP_CLEARANCE,
         className
       )}
     >
@@ -73,11 +77,15 @@ export function OverlayMain({ children, className }: OverlayMainProps) {
   return (
     <main
       className={cn(
-        // Narrow: the OverlayNav dropdown bar already clears the titlebar, so
-        // drop the tall top pad to a normal gap below it.
-        'mx-auto flex min-h-0 w-full flex-1 flex-col overflow-hidden bg-transparent pb-3 pt-[calc(var(--titlebar-height)/2+1rem)] max-[47.5rem]:pt-2',
+        // Main sits UNDER the floating close button (top-right), so it keeps the
+        // taller top pad to clear the X — unlike the sidebar / Panel header,
+        // which sit to its left and ride up via OVERLAY_TOP_CLEARANCE. All four
+        // paddings are 1/3 tighter than the raw values (×2/3): the wide/narrow
+        // top clearance, the bottom gutter, and the horizontal clamp gutter
+        // (inlined from PAGE_INSET_X so only overlay panes tighten, not the
+        // shared page gutter). Narrow top drops toward the OverlayNav bar.
+        'mx-auto flex min-h-0 w-full flex-1 flex-col overflow-hidden bg-transparent pb-2 pt-[calc((var(--titlebar-height)/2+1rem)*2/3)] max-[47.5rem]:pt-[calc(0.5rem*2/3)] px-[clamp(0.8333rem,2.6667vw,2.6667rem)]',
         PAGE_MAX_W,
-        PAGE_INSET_X,
         className
       )}
     >
diff --git a/apps/desktop/src/app/overlays/overlay-view.tsx b/apps/desktop/src/app/overlays/overlay-view.tsx
index 40fce12ec0a..f9c544ee59d 100644
--- a/apps/desktop/src/app/overlays/overlay-view.tsx
+++ b/apps/desktop/src/app/overlays/overlay-view.tsx
@@ -9,6 +9,14 @@ import { ESCAPE_PRIORITY, isTopEscapeLayer, pushEscapeLayer } from '@/lib/escape
 import { triggerHaptic } from '@/lib/haptics'
 import { cn } from '@/lib/utils'
 
+// Shared top clearance for overlay content that sits *beside* the floating
+// close button (which is absolute at `0.1875rem + titlebar/2`, -translate-y-1/2,
+// so it costs no layout space): a Panel's header and the split layout's left
+// sidebar links. They ride up next to the X on the same line across every
+// overlay (settings, system, agents, cron, …) — change it here, not per-surface.
+// Main content sits *under* the X (top-right) and keeps its own taller pad.
+export const OVERLAY_TOP_CLEARANCE = 'pt-[calc(var(--titlebar-height)/2-0.4375rem)]'
+
 interface OverlayViewProps {
   children: ReactNode
   onClose: () => void
diff --git a/apps/desktop/src/app/overlays/panel.tsx b/apps/desktop/src/app/overlays/panel.tsx
index 2561740724e..34a8ead6c54 100644
--- a/apps/desktop/src/app/overlays/panel.tsx
+++ b/apps/desktop/src/app/overlays/panel.tsx
@@ -9,7 +9,7 @@ import { Tip } from '@/components/ui/tooltip'
 import { translateNow } from '@/i18n'
 import { cn } from '@/lib/utils'
 
-import { OverlayView } from './overlay-view'
+import { OVERLAY_TOP_CLEARANCE, OverlayView } from './overlay-view'
 
 // Overlay "panel" primitive — the centered, capped card + framed chrome lifted
 // straight from the trace / agents overlay so every non-settings overlay (cron,
@@ -47,13 +47,9 @@ export function Panel({
   return (
     <OverlayView
       closeLabel={closeLabel}
-      // Top pad aligns the header title's center with the floating close button
-      // (which sits at 0.1875rem + titlebar/2, -translate-y-1/2). The X is
-      // absolute so it costs no layout space — the header rides up next to it.
-      contentClassName={cn(
-        'flex h-full min-h-0 flex-col px-4 pb-4 pt-[calc(var(--titlebar-height)/2-0.4375rem)] sm:px-5',
-        contentClassName
-      )}
+      // Header title rides up next to the floating close button — see
+      // OVERLAY_TOP_CLEARANCE, the shared clearance every overlay column uses.
+      contentClassName={cn('flex h-full min-h-0 flex-col px-4 pb-4 sm:px-5', OVERLAY_TOP_CLEARANCE, contentClassName)}
       onClose={onClose}
       rootClassName={cn('flex h-full w-full flex-col', className)}
     >
@@ -71,7 +67,11 @@ interface PanelHeaderProps {
 
 export function PanelHeader({ actions, subtitle, title }: PanelHeaderProps) {
   return (
-    <header className="mb-3 flex shrink-0 items-start justify-between gap-3">
+    // The overlay's close (X) is absolutely positioned at right-3 and costs no
+    // layout space, so header actions would otherwise slide right up against it.
+    // Reserve clearance (button footprint from the card edge + a small gap) on
+    // the right whenever actions are present.
+    <header className={cn('mb-3 flex shrink-0 items-start justify-between gap-3', actions ? 'pr-8' : undefined)}>
       <div className="min-w-0">
         <h2 className="text-sm font-semibold text-foreground">{title}</h2>
         {subtitle ? <p className="truncate text-xs text-muted-foreground/80">{subtitle}</p> : null}
@@ -369,25 +369,31 @@ export function PanelAddButton({
   )
 }
 
-// Visible ghost action for a detail header (cron pause/resume/trigger, …).
+// Visible action for a detail header (cron pause/resume/trigger, …). Ghost by
+// default; `primary` promotes the header's main action to a filled button.
 export function PanelAction({
   children,
   disabled,
   icon,
-  onClick
+  onClick,
+  primary
 }: {
   children: ReactNode
   disabled?: boolean
   icon: string
   onClick: () => void
+  primary?: boolean
 }) {
   return (
     <Button
-      className="gap-1.5 text-muted-foreground hover:bg-(--ui-row-hover-background) hover:text-foreground"
+      className={cn(
+        'gap-1.5',
+        !primary && 'text-muted-foreground hover:bg-(--ui-row-hover-background) hover:text-foreground'
+      )}
       disabled={disabled}
       onClick={onClick}
       size="sm"
-      variant="ghost"
+      variant={primary ? 'default' : 'ghost'}
     >
       <Codicon name={icon} size="0.875rem" />
       {children}
diff --git a/apps/desktop/src/app/pet-overlay/pet-overlay-app.tsx b/apps/desktop/src/app/pet-overlay/pet-overlay-app.tsx
index d635186e34e..875ef0ca01f 100644
--- a/apps/desktop/src/app/pet-overlay/pet-overlay-app.tsx
+++ b/apps/desktop/src/app/pet-overlay/pet-overlay-app.tsx
@@ -87,6 +87,7 @@ export function PetOverlayApp() {
   }
 
   // Mirror pushed state into the shared atoms so PetSprite/PetBubble just work.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const off = window.hermesDesktop?.petOverlay?.onState(payload => {
       setPetInfo(payload.info)
@@ -185,6 +186,7 @@ export function PetOverlayApp() {
   // input keeps focus); focus it on open. The overlay is a non-activating panel
   // (so it never steals the app's cmd/alt-tab anchor) — flip it focusable while
   // the composer needs the keyboard, then back to non-activating when it closes.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     composerOpenRef.current = composerOpen
 
@@ -317,6 +319,7 @@ export function PetOverlayApp() {
   // wheel anchor we zoom toward the cursor (keep the pixel under it fixed);
   // otherwise we anchor the bottom-center (the pet's feet stay planted). New
   // bounds are persisted so the pet reopens at the right size.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!info.enabled || !info.spritesheetBase64) {
       return
diff --git a/apps/desktop/src/app/profiles/create-profile-dialog.tsx b/apps/desktop/src/app/profiles/create-profile-dialog.tsx
index 602e3aa680e..c5bf60ad8c4 100644
--- a/apps/desktop/src/app/profiles/create-profile-dialog.tsx
+++ b/apps/desktop/src/app/profiles/create-profile-dialog.tsx
@@ -10,13 +10,13 @@ import {
   DialogHeader,
   DialogTitle
 } from '@/components/ui/dialog'
+import { Field, FieldHint } from '@/components/ui/field'
 import { Input } from '@/components/ui/input'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
 import { Textarea } from '@/components/ui/textarea'
 import { createProfile, updateProfileSoul } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { AlertTriangle } from '@/lib/icons'
-import { cn } from '@/lib/utils'
 import type { ProfileInfo } from '@/types/hermes'
 
 const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/
@@ -100,10 +100,7 @@ export function CreateProfileDialog({
         </DialogHeader>
 
         <form className="grid gap-4" onSubmit={handleSubmit}>
-          <div className="grid gap-1.5">
-            <label className="text-xs font-medium" htmlFor="new-profile-name">
-              {p.nameLabel}
-            </label>
+          <Field htmlFor="new-profile-name" label={p.nameLabel}>
             <Input
               aria-invalid={invalid}
               autoFocus
@@ -112,15 +109,10 @@ export function CreateProfileDialog({
               placeholder="my-profile"
               value={name}
             />
-            <p className={cn('text-[0.66rem] leading-4', invalid ? 'text-destructive' : 'text-muted-foreground')}>
-              {p.nameHint}
-            </p>
-          </div>
+            <FieldHint error={invalid}>{p.nameHint}</FieldHint>
+          </Field>
 
-          <div className="grid gap-1.5">
-            <label className="text-xs font-medium" htmlFor="new-profile-clone-from">
-              {p.cloneFrom}
-            </label>
+          <Field htmlFor="new-profile-clone-from" label={p.cloneFrom}>
             <Select
               onValueChange={value => setCloneFrom(value === '__none__' ? null : value)}
               value={cloneFrom ?? '__none__'}
@@ -137,13 +129,10 @@ export function CreateProfileDialog({
                 ))}
               </SelectContent>
             </Select>
-            <p className="text-xs text-muted-foreground">{p.cloneFromDesc}</p>
-          </div>
+            <FieldHint>{p.cloneFromDesc}</FieldHint>
+          </Field>
 
-          <div className="grid gap-1.5">
-            <label className="text-xs font-medium" htmlFor="new-profile-soul">
-              SOUL.md <span className="font-normal text-muted-foreground">- {p.soulOptional}</span>
-            </label>
+          <Field htmlFor="new-profile-soul" label="SOUL.md" optional optionalLabel={p.soulOptional}>
             <Textarea
               className="min-h-28 font-mono text-xs leading-5"
               id="new-profile-soul"
@@ -151,7 +140,7 @@ export function CreateProfileDialog({
               placeholder={p.soulPlaceholder(cloneFrom ? p.soulPlaceholderCloned : p.soulPlaceholderEmpty)}
               value={soul}
             />
-          </div>
+          </Field>
 
           {error && (
             <div className="flex items-start gap-2 rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-xs text-destructive">
diff --git a/apps/desktop/src/app/profiles/index.tsx b/apps/desktop/src/app/profiles/index.tsx
index 8f777b046ed..b04d9c6c32b 100644
--- a/apps/desktop/src/app/profiles/index.tsx
+++ b/apps/desktop/src/app/profiles/index.tsx
@@ -388,6 +388,7 @@ function SoulEditor({ profileName }: { profileName: string }) {
   const [error, setError] = useState<null | string>(null)
   const requestRef = useRef<string>(profileName)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     requestRef.current = profileName
     setLoading(true)
diff --git a/apps/desktop/src/app/profiles/rename-profile-dialog.tsx b/apps/desktop/src/app/profiles/rename-profile-dialog.tsx
index c53f4c2dabe..8a12f7b65ab 100644
--- a/apps/desktop/src/app/profiles/rename-profile-dialog.tsx
+++ b/apps/desktop/src/app/profiles/rename-profile-dialog.tsx
@@ -10,11 +10,11 @@ import {
   DialogHeader,
   DialogTitle
 } from '@/components/ui/dialog'
+import { Field, FieldHint } from '@/components/ui/field'
 import { Input } from '@/components/ui/input'
 import { renameProfile } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { AlertTriangle } from '@/lib/icons'
-import { cn } from '@/lib/utils'
 
 import { isValidProfileName } from './create-profile-dialog'
 
@@ -93,11 +93,8 @@ export function RenameProfileDialog({
           </DialogDescription>
         </DialogHeader>
 
-        <form className="grid gap-3" onSubmit={handleSubmit}>
-          <div className="grid gap-1.5">
-            <label className="text-xs font-medium" htmlFor="rename-profile-name">
-              {p.newNameLabel}
-            </label>
+        <form className="grid gap-4" onSubmit={handleSubmit}>
+          <Field htmlFor="rename-profile-name" label={p.newNameLabel}>
             <Input
               aria-invalid={invalid}
               autoFocus
@@ -105,10 +102,8 @@ export function RenameProfileDialog({
               onChange={event => setName(event.target.value)}
               value={name}
             />
-            <p className={cn('text-[0.66rem] leading-4', invalid ? 'text-destructive' : 'text-muted-foreground')}>
-              {p.nameHint}
-            </p>
-          </div>
+            <FieldHint error={invalid}>{p.nameHint}</FieldHint>
+          </Field>
 
           {error && (
             <div className="flex items-start gap-2 rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-xs text-destructive">
diff --git a/apps/desktop/src/app/right-sidebar/review/file-tree.tsx b/apps/desktop/src/app/right-sidebar/review/file-tree.tsx
index 6c2dccb4bb7..9d753c12286 100644
--- a/apps/desktop/src/app/right-sidebar/review/file-tree.tsx
+++ b/apps/desktop/src/app/right-sidebar/review/file-tree.tsx
@@ -105,6 +105,7 @@ export function ReviewFileTree() {
   const [animate, setAnimate] = useState(false)
   const armed = useRef(false)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!open) {
       armed.current = false
@@ -112,6 +113,7 @@ export function ReviewFileTree() {
     }
   }, [open])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (open && !loading && !armed.current) {
       armed.current = true
diff --git a/apps/desktop/src/app/right-sidebar/terminal/use-agent-terminal.ts b/apps/desktop/src/app/right-sidebar/terminal/use-agent-terminal.ts
index bb6aaeaff32..cec977c5d4d 100644
--- a/apps/desktop/src/app/right-sidebar/terminal/use-agent-terminal.ts
+++ b/apps/desktop/src/app/right-sidebar/terminal/use-agent-terminal.ts
@@ -28,6 +28,7 @@ export function useAgentTerminal({ active, id, procId }: { active: boolean; id:
     return { ...terminalTheme(renderedMode, ansi), background: surface, cursorAccent: surface }
   }
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const host = hostRef.current
 
diff --git a/apps/desktop/src/app/right-sidebar/terminal/use-terminal-session.ts b/apps/desktop/src/app/right-sidebar/terminal/use-terminal-session.ts
index c1b09487c6f..34c800926ce 100644
--- a/apps/desktop/src/app/right-sidebar/terminal/use-terminal-session.ts
+++ b/apps/desktop/src/app/right-sidebar/terminal/use-terminal-session.ts
@@ -421,6 +421,7 @@ export function useTerminalSession({
   const [selectionStyle, setSelectionStyle] = useState<CSSProperties | null>(null)
   const [shellName, setShellName] = useState('shell')
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     onAddSelectionToChatRef.current = onAddSelectionToChat
     onShellRef.current = onShell
@@ -478,6 +479,7 @@ export function useTerminalSession({
     return () => window.removeEventListener('keydown', onKeyDown, { capture: true })
   }, [addSelectionToChat, readSelection])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const host = hostRef.current
     const terminalApi = window.hermesDesktop?.terminal
@@ -974,6 +976,7 @@ export function useTerminalSession({
   // the subscribe fires immediately, so a command set before this pane mounted
   // runs as soon as the session is ready. Cleared after writing so a later
   // remount can't replay a stale command.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!active || status !== 'open') {
       return
diff --git a/apps/desktop/src/app/routes.test.ts b/apps/desktop/src/app/routes.test.ts
new file mode 100644
index 00000000000..3c8933d9356
--- /dev/null
+++ b/apps/desktop/src/app/routes.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+
+import { NEW_CHAT_ROUTE, primaryRouteSelectedSessionId, sessionRoute, SETTINGS_ROUTE } from './routes'
+
+const SESS_A = 'sess-a'
+const SESS_B = 'sess-b'
+
+describe('primaryRouteSelectedSessionId', () => {
+  it('prefers the routed session id over a stale/different store selection (#59305)', () => {
+    // The route already committed to B while the store selection hasn't
+    // caught up yet (still reads A) — the route wins.
+    expect(primaryRouteSelectedSessionId(sessionRoute(SESS_B), SESS_A)).toBe(SESS_B)
+  })
+
+  it('returns null on the new-chat route even with a leftover selection from the previous chat', () => {
+    expect(primaryRouteSelectedSessionId(NEW_CHAT_ROUTE, SESS_A)).toBeNull()
+  })
+
+  it('falls back to the store selection on a non-chat route (settings, overlays)', () => {
+    expect(primaryRouteSelectedSessionId(SETTINGS_ROUTE, SESS_A)).toBe(SESS_A)
+  })
+
+  it('falls back to the store selection when the route matches the same session', () => {
+    expect(primaryRouteSelectedSessionId(sessionRoute(SESS_A), SESS_A)).toBe(SESS_A)
+  })
+
+  it('returns null on a non-chat route with no store selection', () => {
+    expect(primaryRouteSelectedSessionId(SETTINGS_ROUTE, null)).toBeNull()
+  })
+})
diff --git a/apps/desktop/src/app/routes.ts b/apps/desktop/src/app/routes.ts
index 8db7ee7c390..b3c28a0ae01 100644
--- a/apps/desktop/src/app/routes.ts
+++ b/apps/desktop/src/app/routes.ts
@@ -9,6 +9,7 @@ export const SETTINGS_ROUTE = '/settings'
 export const COMMAND_CENTER_ROUTE = '/command-center'
 export const SKILLS_ROUTE = '/skills'
 export const MESSAGING_ROUTE = '/messaging'
+export const WEBHOOKS_ROUTE = '/webhooks'
 export const ARTIFACTS_ROUTE = '/artifacts'
 export const CRON_ROUTE = '/cron'
 export const PROFILES_ROUTE = '/profiles'
@@ -31,6 +32,7 @@ export type AppView =
   | 'settings'
   | 'skills'
   | 'starmap'
+  | 'webhooks'
 
 export type AppRouteId =
   | 'agents'
@@ -43,6 +45,7 @@ export type AppRouteId =
   | 'settings'
   | 'skills'
   | 'starmap'
+  | 'webhooks'
 
 export interface AppRoute {
   id: AppRouteId
@@ -56,6 +59,7 @@ export const APP_ROUTES = [
   { id: 'command-center', path: COMMAND_CENTER_ROUTE, view: 'command-center' },
   { id: 'skills', path: SKILLS_ROUTE, view: 'skills' },
   { id: 'messaging', path: MESSAGING_ROUTE, view: 'messaging' },
+  { id: 'webhooks', path: WEBHOOKS_ROUTE, view: 'webhooks' },
   { id: 'artifacts', path: ARTIFACTS_ROUTE, view: 'artifacts' },
   { id: 'cron', path: CRON_ROUTE, view: 'cron' },
   { id: 'profiles', path: PROFILES_ROUTE, view: 'profiles' },
@@ -121,7 +125,8 @@ export const OVERLAY_VIEWS: ReadonlySet<AppView> = new Set([
   'cron',
   'profiles',
   'settings',
-  'starmap'
+  'starmap',
+  'webhooks'
 ])
 
 export function isOverlayView(view: AppView): boolean {
@@ -142,6 +147,23 @@ export function routeSessionId(pathname: string): string | null {
   return id && !id.includes('/') ? decodeURIComponent(id) : null
 }
 
+/**
+ * The primary composer's durable scope key candidate: the route is the source
+ * of truth for which chat is on screen, so prefer its (stable) stored session
+ * id over a store selection that can be momentarily null/stale mid-switch
+ * (#59305). A genuine new-chat route always wins with `null`, never falling
+ * back to a leftover selection from the chat just left. A non-chat route
+ * (settings, an overlay) has no session opinion, so the store selection passes
+ * through unchanged.
+ */
+export function primaryRouteSelectedSessionId(pathname: string, storeSelectedSessionId: string | null): string | null {
+  if (isNewChatRoute(pathname)) {
+    return null
+  }
+
+  return routeSessionId(pathname) ?? storeSelectedSessionId
+}
+
 export function sessionRoute(sessionId: string): string {
   return `${SESSION_ROUTE_PREFIX}${encodeURIComponent(sessionId)}`
 }
diff --git a/apps/desktop/src/app/session/hooks/session-context-drift.test.ts b/apps/desktop/src/app/session/hooks/session-context-drift.test.ts
index 7846ecfe221..009d719e5e5 100644
--- a/apps/desktop/src/app/session/hooks/session-context-drift.test.ts
+++ b/apps/desktop/src/app/session/hooks/session-context-drift.test.ts
@@ -122,4 +122,77 @@ describe('sessionContextDrift', () => {
 
     expect(reason).toBe('route:__new__->sess-b')
   })
+
+  it('does not drift when composerScope is omitted (non-composer submits: queue drain, steer)', () => {
+    const reason = sessionContextDrift({
+      startRouteToken: routeToken(sessionRoute(SESS_A)),
+      nowRouteToken: routeToken(sessionRoute(SESS_A)),
+      startSelectedStoredId: SESS_A,
+      nowSelectedStoredId: SESS_A,
+      submitTargetStoredId: SESS_A
+    })
+
+    expect(reason).toBeNull()
+  })
+
+  it('does not drift when composerScope matches the resolved (lineage) submit target', () => {
+    const reason = sessionContextDrift({
+      startRouteToken: routeToken(sessionRoute(SESS_A)),
+      nowRouteToken: routeToken(sessionRoute(SESS_A)),
+      startSelectedStoredId: SESS_A,
+      nowSelectedStoredId: SESS_A,
+      submitTargetStoredId: SESS_A,
+      composerScope: SESS_A,
+      submitTargetComposerScope: SESS_A
+    })
+
+    expect(reason).toBeNull()
+  })
+
+  it('drifts (composer prong) when the loaded composer scope disagrees with the resolved submit target (#59305)', () => {
+    const reason = sessionContextDrift({
+      startRouteToken: routeToken(sessionRoute(SESS_A)),
+      nowRouteToken: routeToken(sessionRoute(SESS_A)),
+      startSelectedStoredId: SESS_A,
+      nowSelectedStoredId: SESS_A,
+      submitTargetStoredId: SESS_A,
+      composerScope: SESS_B,
+      submitTargetComposerScope: SESS_A
+    })
+
+    expect(reason).toBe('composer:sess-b->sess-a')
+  })
+
+  it('checks the composer prong before the route/selection prongs', () => {
+    const reason = sessionContextDrift({
+      startRouteToken: routeToken(sessionRoute(SESS_A)),
+      nowRouteToken: routeToken(sessionRoute(SESS_B)),
+      startSelectedStoredId: SESS_A,
+      nowSelectedStoredId: SESS_B,
+      submitTargetStoredId: SESS_A,
+      composerScope: SESS_B,
+      submitTargetComposerScope: SESS_A
+    })
+
+    expect(reason).toBe('composer:sess-b->sess-a')
+  })
+
+  it('does not drift when the session has rotated via compression (composerScope is the lineage root, submitTargetStoredId is the live tip)', () => {
+    const ROOT_ID = 'stored-root'
+    const TIP_ID = 'stored-tip-after-compression'
+
+    const reason = sessionContextDrift({
+      startRouteToken: routeToken(sessionRoute(TIP_ID)),
+      nowRouteToken: routeToken(sessionRoute(TIP_ID)),
+      startSelectedStoredId: TIP_ID,
+      nowSelectedStoredId: TIP_ID,
+      submitTargetStoredId: TIP_ID,
+      composerScope: ROOT_ID,
+      // What submit.ts actually passes: resolveComposerSessionKey(TIP_ID, sessions),
+      // which resolves to the lineage root for a session that has compressed.
+      submitTargetComposerScope: ROOT_ID
+    })
+
+    expect(reason).toBeNull()
+  })
 })
diff --git a/apps/desktop/src/app/session/hooks/session-context-drift.ts b/apps/desktop/src/app/session/hooks/session-context-drift.ts
index 5f7e8a54b91..7f264a581f9 100644
--- a/apps/desktop/src/app/session/hooks/session-context-drift.ts
+++ b/apps/desktop/src/app/session/hooks/session-context-drift.ts
@@ -37,6 +37,25 @@ interface SessionContextDriftArgs {
    * a real chat as drift.
    */
   submitTargetStoredId?: string | null
+  /**
+   * The composer scope that was actually loaded when the text was submitted
+   * (SubmitTextOptions.composerScope). The composer and the session-side refs
+   * live in separate React subtrees and can each be internally consistent yet
+   * still disagree with each other at the instant of send — this prong catches
+   * that cross-component drift (#59305). Omit for non-composer submits.
+   */
+  composerScope?: string | null
+  /**
+   * resolveComposerSessionKey(submitTargetStoredId, sessions) — the durable
+   * lineage-root form of the submit target, in the SAME domain as
+   * composerScope. Compared against composerScope instead of the raw
+   * submitTargetStoredId: the composer keys drafts/attachments on the lineage
+   * root (stable across auto-compression tip rotation) while
+   * submitTargetStoredId tracks the live tip — comparing composerScope
+   * directly against the tip would false-positive-abort every submit into any
+   * session that has ever compressed.
+   */
+  submitTargetComposerScope?: string | null
 }
 
 /**
@@ -56,8 +75,21 @@ export function sessionContextDrift({
   nowRouteToken,
   startSelectedStoredId,
   nowSelectedStoredId,
-  submitTargetStoredId
+  submitTargetStoredId,
+  composerScope,
+  submitTargetComposerScope
 }: SessionContextDriftArgs): string | null {
+  // Composer prong: the composer's loaded scope disagrees with the resolved
+  // submit target. Not a start/now comparison like the two prongs below — the
+  // composer only hands us one snapshot per submit — but it belongs in the
+  // same fail-closed gate since it's exactly the same "wrong session" failure
+  // mode. Compared against submitTargetComposerScope (lineage-pinned), NOT
+  // submitTargetStoredId (live tip) — see the field doc on
+  // SessionContextDriftArgs for why those two must not be conflated.
+  if (composerScope !== undefined && composerScope !== null && composerScope !== submitTargetComposerScope) {
+    return `composer:${composerScope}->${submitTargetComposerScope}`
+  }
+
   const targetStart = routeTargetFromToken(startRouteToken)
   const targetNow = routeTargetFromToken(nowRouteToken)
 
diff --git a/apps/desktop/src/app/session/hooks/use-background-queue-drain.ts b/apps/desktop/src/app/session/hooks/use-background-queue-drain.ts
index 6f54453c71c..5adf910bdb7 100644
--- a/apps/desktop/src/app/session/hooks/use-background-queue-drain.ts
+++ b/apps/desktop/src/app/session/hooks/use-background-queue-drain.ts
@@ -52,6 +52,7 @@ export function useBackgroundQueueDrain({
   const retryTimersRef = useRef<number[]>([])
   const [retryTick, setRetryTick] = useState(0)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     submitTextRef.current = submitText
   }, [submitText])
diff --git a/apps/desktop/src/app/session/hooks/use-cwd-actions.test.tsx b/apps/desktop/src/app/session/hooks/use-cwd-actions.test.tsx
index 4ce81fd226c..213c5d2054d 100644
--- a/apps/desktop/src/app/session/hooks/use-cwd-actions.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-cwd-actions.test.tsx
@@ -37,7 +37,6 @@ function Harness({
   requestGateway: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
 }) {
   const actions = useCwdActions({
-    activeSessionId: activeSessionIdRef.current,
     activeSessionIdRef,
     requestGateway
   })
diff --git a/apps/desktop/src/app/session/hooks/use-cwd-actions.ts b/apps/desktop/src/app/session/hooks/use-cwd-actions.ts
index 8226a2f5950..0943131d0d2 100644
--- a/apps/desktop/src/app/session/hooks/use-cwd-actions.ts
+++ b/apps/desktop/src/app/session/hooks/use-cwd-actions.ts
@@ -12,18 +12,12 @@ import {
 import type { SessionRuntimeInfo } from '@/types/hermes'
 
 interface CwdActionsOptions {
-  activeSessionId: string | null
   activeSessionIdRef: MutableRefObject<string | null>
   onSessionRuntimeInfo?: (info: Pick<SessionRuntimeInfo, 'branch' | 'cwd'>) => void
   requestGateway: <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>
 }
 
-export function useCwdActions({
-  activeSessionId,
-  activeSessionIdRef,
-  onSessionRuntimeInfo,
-  requestGateway
-}: CwdActionsOptions) {
+export function useCwdActions({ activeSessionIdRef, onSessionRuntimeInfo, requestGateway }: CwdActionsOptions) {
   const { t } = useI18n()
   const copy = t.desktop
 
@@ -59,7 +53,13 @@ export function useCwdActions({
         return
       }
 
-      if (!activeSessionId) {
+      // Ref, not the closure-captured prop: this hook's consumers are memoized
+      // on a stable actions object, so the prop can still name the previously
+      // focused chat. Re-anchoring the wrong session's workspace would point
+      // that agent's terminal/file tools at another conversation's project.
+      const sessionId = activeSessionIdRef.current
+
+      if (!sessionId) {
         setCurrentCwd(trimmed)
         const workspaceGeneration = setNewChatWorkspaceTarget(trimmed)
 
@@ -92,7 +92,7 @@ export function useCwdActions({
 
       try {
         const info = await requestGateway<SessionRuntimeInfo>('session.cwd.set', {
-          session_id: activeSessionId,
+          session_id: sessionId,
           cwd: trimmed
         })
 
@@ -117,7 +117,7 @@ export function useCwdActions({
         })
       }
     },
-    [activeSessionId, activeSessionIdRef, copy, onSessionRuntimeInfo, requestGateway]
+    [activeSessionIdRef, copy, onSessionRuntimeInfo, requestGateway]
   )
 
   return { changeSessionCwd, refreshProjectBranch }
diff --git a/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts b/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
index 23e0f5a74c8..a5ec2060bf5 100644
--- a/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
+++ b/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
@@ -8,11 +8,13 @@ import {
   $currentCwd,
   $currentFastMode,
   $currentReasoningEffort,
+  $defaultReasoningEffort,
   markComposerSelectionManual,
   setCurrentCwd,
   setCurrentFastMode,
   setCurrentModelSource,
-  setCurrentReasoningEffort
+  setCurrentReasoningEffort,
+  setDefaultReasoningEffort
 } from '@/store/session'
 
 import { useHermesConfig } from './use-hermes-config'
@@ -44,9 +46,31 @@ describe('useHermesConfig refreshHermesConfig', () => {
     setCurrentFastMode(false)
     setCurrentModelSource('')
     setCurrentReasoningEffort('')
+    setDefaultReasoningEffort('')
     persistString(WORKSPACE_CWD_KEY, null)
   })
 
+  // Regression: the composer keeps a manual model pick sticky, which skips the
+  // composer reseed. The profile default must still be published, because the
+  // model picker resolves "the default effort" from it when applying a model's
+  // preset — otherwise selecting a model silently downgrades a configured
+  // `agent.reasoning_effort: high` to Hermes' built-in medium.
+  it('publishes the profile default effort even when a manual pick blocks the composer reseed', async () => {
+    setCurrentModelSource('manual')
+    setCurrentReasoningEffort('low')
+
+    mockConfig({ agent: { reasoning_effort: 'high' } })
+    const { result } = renderHook(() => useHermesConfig({ activeSessionIdRef: { current: null } }))
+
+    await act(async () => {
+      await result.current.refreshHermesConfig()
+    })
+
+    expect($defaultReasoningEffort.get()).toBe('high')
+    // The manual pick itself is still respected.
+    expect($currentReasoningEffort.get()).toBe('low')
+  })
+
   it('does not let terminal.cwd replace an inactive selected workspace', async () => {
     setCurrentCwd('/Users/example/repo/.worktrees/feature')
 
diff --git a/apps/desktop/src/app/session/hooks/use-hermes-config.ts b/apps/desktop/src/app/session/hooks/use-hermes-config.ts
index 5d78fb1c6c5..06f5a139367 100644
--- a/apps/desktop/src/app/session/hooks/use-hermes-config.ts
+++ b/apps/desktop/src/app/session/hooks/use-hermes-config.ts
@@ -11,6 +11,7 @@ import {
   setCurrentPersonality,
   setCurrentReasoningEffort,
   setCurrentServiceTier,
+  setDefaultReasoningEffort,
   setIntroPersonality
 } from '@/store/session'
 import { applyAutoSpeakFromConfig } from '@/store/voice-prefs'
@@ -83,6 +84,12 @@ export function useHermesConfig({ activeSessionIdRef }: HermesConfigOptions) {
         const reasoning = normalizeConfigEffort(config.agent?.reasoning_effort)
         const tier = (config.agent?.service_tier ?? '').trim()
 
+        // Publish the profile default regardless of whether the composer is
+        // reseeded below: picker rows and preset application resolve "the
+        // default" from here, so a manual model pick must not leave them
+        // rendering/applying Hermes' built-in medium over the user's config.
+        setDefaultReasoningEffort(reasoning)
+
         const shouldSeedComposer =
           !activeSessionIdRef.current &&
           getComposerSelectionGeneration() === selectionGeneration &&
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/agent-init-error.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/agent-init-error.test.tsx
new file mode 100644
index 00000000000..86875e42f3f
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/agent-init-error.test.tsx
@@ -0,0 +1,131 @@
+import { QueryClient } from '@tanstack/react-query'
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import { useEffect, useRef } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ClientSessionState } from '@/app/types'
+import { textPart } from '@/lib/chat-messages'
+import { createClientSessionState } from '@/lib/chat-runtime'
+import { $notifications, clearNotifications } from '@/store/notifications'
+import type { RpcEvent } from '@/types/hermes'
+
+import { useMessageStream } from './index'
+
+const SID = 'rt-new-session'
+
+let handleEvent: ((event: RpcEvent) => void) | null = null
+let sessionStates: Map<string, ClientSessionState> | null = null
+
+function Harness() {
+  const activeSessionIdRef = useRef<string | null>(SID)
+  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
+  const queryClientRef = useRef(new QueryClient())
+
+  const stream = useMessageStream({
+    activeSessionIdRef,
+    hydrateFromStoredSession: vi.fn(async () => undefined),
+    queryClient: queryClientRef.current,
+    refreshHermesConfig: vi.fn(async () => undefined),
+    refreshSessions: vi.fn(async () => undefined),
+    sessionStateByRuntimeIdRef,
+    updateSessionState: (sessionId, updater) => {
+      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
+      const next = updater(current)
+      sessionStateByRuntimeIdRef.current.set(sessionId, next)
+
+      return next
+    }
+  })
+
+  useEffect(() => {
+    handleEvent = stream.handleGatewayEvent
+    sessionStates = sessionStateByRuntimeIdRef.current
+  }, [stream.handleGatewayEvent])
+
+  return null
+}
+
+async function mountStream() {
+  render(<Harness />)
+  await waitFor(() => expect(handleEvent).not.toBeNull())
+}
+
+/** Seed the session as it looks right after a first-message submit: the
+ *  optimistic user row is present, the turn is awaiting its response. */
+function seedOptimisticFirstMessage() {
+  sessionStates!.set(SID, {
+    ...createClientSessionState('stored-new-session', [
+      { id: 'user-123-abc', role: 'user', parts: [textPart('first message of a new chat')] }
+    ]),
+    busy: true,
+    awaitingResponse: true
+  })
+}
+
+describe('useMessageStream agent-init error surfacing (#63078)', () => {
+  beforeEach(() => {
+    handleEvent = null
+    sessionStates = null
+    clearNotifications()
+  })
+
+  afterEach(() => {
+    cleanup()
+    clearNotifications()
+    vi.restoreAllMocks()
+  })
+
+  it('renders an agent-init failure as a visible in-transcript error and keeps the optimistic first message', async () => {
+    await mountStream()
+    seedOptimisticFirstMessage()
+
+    act(() =>
+      handleEvent!({
+        payload: {
+          message:
+            'agent initialization timed out after 601s — your message was not sent; retry once the session is ready'
+        },
+        session_id: SID,
+        type: 'error'
+      })
+    )
+
+    const state = sessionStates!.get(SID)!
+
+    // The user's optimistic first message must survive — the failure mode of
+    // #63078 was the message silently vanishing into a blank session.
+    const userRows = state.messages.filter(m => m.role === 'user')
+    expect(userRows).toHaveLength(1)
+    expect(userRows[0]!.id).toBe('user-123-abc')
+
+    // The failure is VISIBLE in the session view: an assistant error bubble...
+    const errorRows = state.messages.filter(m => m.role === 'assistant' && m.error)
+    expect(errorRows).toHaveLength(1)
+    expect(errorRows[0]!.error).toContain('your message was not sent')
+
+    // ...and the composer is released (no forever-spinner on a dead turn).
+    expect(state.busy).toBe(false)
+    expect(state.awaitingResponse).toBe(false)
+
+    // A global toast also fired (turn-ending errors are easy to miss inline).
+    expect($notifications.get().some(n => n.kind === 'error' && n.message?.includes('was not sent'))).toBe(true)
+  })
+
+  it('renders the pre-ready cancel error event (#65567 server emit) visibly', async () => {
+    await mountStream()
+    seedOptimisticFirstMessage()
+
+    act(() =>
+      handleEvent!({
+        payload: { message: 'Turn cancelled before the agent was ready' },
+        session_id: SID,
+        type: 'error'
+      })
+    )
+
+    const state = sessionStates!.get(SID)!
+    expect(state.messages.some(m => m.role === 'assistant' && m.error?.includes('cancelled'))).toBe(true)
+    expect(state.messages.some(m => m.id === 'user-123-abc')).toBe(true)
+    expect(state.busy).toBe(false)
+  })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts
index 30ceb151056..101fe7e59be 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts
@@ -112,6 +112,8 @@ const COMPACTION_RESUME_EVENT_TYPES = new Set([
   'reasoning.available',
   'moa.reference',
   'moa.aggregating',
+  'moa.progress',
+  'moa.phase',
   'tool.start',
   'tool.progress',
   'tool.generating',
@@ -126,7 +128,12 @@ interface GatewayEventDeps {
   nativeSubagentSessionsRef: MutableRefObject<Set<string>>
   appendAssistantDelta: (sessionId: string, delta: string) => void
   appendReasoningDelta: (sessionId: string, delta: string, replace?: boolean) => void
-  completeAssistantMessage: (sessionId: string, text: string, responsePreviewed?: boolean) => void
+  completeAssistantMessage: (
+    sessionId: string,
+    text: string,
+    responsePreviewed?: boolean,
+    failure?: { error: string; partial: boolean }
+  ) => void
   failAssistantMessage: (sessionId: string, errorMessage: string) => void
   flushQueuedDeltas: (sessionId?: string) => void
   finalizeInterimAssistantMessage: (sessionId: string, text: string) => void
@@ -524,7 +531,26 @@ export function useGatewayEventHandler(deps: GatewayEventDeps) {
           const cnt = typeof payload?.count === 'number' ? payload.count : undefined
           const header = idx && cnt ? `◇ Reference ${idx}/${cnt} — ${label}` : `◇ Reference — ${label}`
           const body = coerceThinkingText(payload?.text)
-          appendReasoningDelta(sessionId, `${header}\n${body}\n\n`, true)
+          const text = `${header}\n${body}\n\n`
+
+          if (idx === undefined || idx <= 1) {
+            // First reference: clear any stale reasoning left over from
+            // before this turn's references start, same as before.
+            appendReasoningDelta(sessionId, text, true)
+          } else {
+            // Later references must accumulate, not replace — otherwise
+            // each new reference wipes out the ones already shown (#64658).
+            // Queue-then-flush (rather than the streamed/batched queue path)
+            // applies it immediately, since each reference arrives as one
+            // complete block rather than incremental tokens. reasoning.delta
+            // cannot be mid-flight here: MoAChatCompletions.reference_callback
+            // (agent/moa_loop.py) fires "moa.reference" once per reference's
+            // already-complete text, with no concurrent token stream for the
+            // reference-gathering phase, so there is no in-flight delta to
+            // collide with in the shared queue bucket.
+            appendReasoningDelta(sessionId, text, false)
+            flushQueuedDeltas(sessionId)
+          }
         }
 
         if (isActiveEvent) {
@@ -533,6 +559,38 @@ export function useGatewayEventHandler(deps: GatewayEventDeps) {
       } else if (event.type === 'moa.aggregating') {
         // Status transition only; the aggregator's reply arrives via the normal
         // message stream. No reasoning/transcript mutation here.
+        if (isActiveEvent) {
+          setPetActivity({ reasoning: true })
+        }
+      } else if (event.type === 'moa.progress') {
+        // Live reference fan-out progress ("refs k/n") — surfaced in the same
+        // reasoning disclosure the references land in. These lines arrive
+        // BEFORE any moa.reference event (references are only emitted once the
+        // whole fan-out completes), and the first moa.reference replaces the
+        // block, so the progress trail is self-cleaning.
+        if (sessionId && typeof payload?.refs_done === 'number' && typeof payload?.refs_total === 'number') {
+          const label = coerceGatewayText(payload?.label)
+
+          const line = label
+            ? `◇ MoA refs ${payload.refs_done}/${payload.refs_total} — ${label}\n`
+            : `◇ MoA refs ${payload.refs_done}/${payload.refs_total}\n`
+
+          appendReasoningDelta(sessionId, line, payload.refs_done <= 1)
+          flushQueuedDeltas(sessionId)
+        }
+
+        if (isActiveEvent) {
+          setPetActivity({ reasoning: true })
+        }
+      } else if (event.type === 'moa.phase') {
+        // Phase transition — currently only phase="aggregator" (fan-out done,
+        // aggregator acting). Append a one-line marker; the first
+        // moa.reference that follows replaces the whole block.
+        if (sessionId && payload?.phase === 'aggregator') {
+          appendReasoningDelta(sessionId, '◇ MoA aggregating…\n', false)
+          flushQueuedDeltas(sessionId)
+        }
+
         if (isActiveEvent) {
           setPetActivity({ reasoning: true })
         }
@@ -559,7 +617,19 @@ export function useGatewayEventHandler(deps: GatewayEventDeps) {
         playCompletionSound(sessionId)
 
         const finalText = coerceGatewayText(payload?.text) || coerceGatewayText(payload?.rendered)
-        completeAssistantMessage(sessionId, finalText, payload?.response_previewed)
+
+        // Terminal error frames (status "error") carry the failure in
+        // structured fields: `error` is the message, and `partial` marks
+        // `text` as streamed output to keep rather than the error string.
+        const failure =
+          payload?.status === 'error'
+            ? {
+                error: coerceGatewayText(payload.error).trim() || finalText || 'Hermes reported an error',
+                partial: Boolean(payload.partial)
+              }
+            : undefined
+
+        completeAssistantMessage(sessionId, finalText, payload?.response_previewed, failure)
 
         // Structured billing wall forwarded by the gateway (out of credits /
         // payment required) — cache it + raise a billing-specific toast.
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/index.ts b/apps/desktop/src/app/session/hooks/use-message-stream/index.ts
index 53a17b193c6..2346936fa94 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/index.ts
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/index.ts
@@ -251,12 +251,20 @@ export function useMessageStream({
       flushQueuedDeltas()
     }
 
-    if (sinceLast >= STREAM_DELTA_FLUSH_MS && typeof window.requestAnimationFrame === 'function') {
-      flushHandleRef.current = window.requestAnimationFrame(runFlush)
-
-      return
-    }
-
+    // Always a timer, never requestAnimationFrame. Chromium pauses rAF for a
+    // renderer it considers hidden, and "hidden" is not something this code can
+    // verify: `backgroundThrottling: false` plus the process-level switches in
+    // electron/main.ts cover the blurred and occluded cases, but they don't
+    // cover a minimized window, a fully off-screen one, or a renderer the
+    // compositor has otherwise parked. In those states an rAF-gated flush never
+    // runs, so a finished answer sits in this queue until some later input or
+    // focus event happens to wake a frame — the reply looks stalled, then
+    // arrives all at once on refocus.
+    //
+    // A timer keeps the same coalescing cadence (that's what the floor above is
+    // for) while guaranteeing delivery without user interaction. Timers are
+    // clamped in background renderers rather than suspended, and
+    // disable-background-timer-throttling already opts out of that clamp.
     flushHandleRef.current = window.setTimeout(runFlush, Math.max(0, STREAM_DELTA_FLUSH_MS - sinceLast))
   }, [flushQueuedDeltas])
 
@@ -277,11 +285,7 @@ export function useMessageStream({
   useEffect(
     () => () => {
       if (flushHandleRef.current !== null && typeof window !== 'undefined') {
-        if (typeof window.cancelAnimationFrame === 'function') {
-          window.cancelAnimationFrame(flushHandleRef.current)
-        } else {
-          window.clearTimeout(flushHandleRef.current)
-        }
+        window.clearTimeout(flushHandleRef.current)
       }
 
       flushHandleRef.current = null
@@ -437,7 +441,7 @@ export function useMessageStream({
   )
 
   const completeAssistantMessage = useCallback(
-    (sessionId: string, text: string, responsePreviewed?: boolean) => {
+    (sessionId: string, text: string, responsePreviewed?: boolean, failure?: { error: string; partial: boolean }) => {
       let shouldHydrate = false
 
       const completedState = updateSessionState(sessionId, state => {
@@ -459,7 +463,13 @@ export function useMessageStream({
 
         const streamId = state.streamId
         const finalText = renderMediaTags(text).trim()
-        const completionError = completionErrorText(finalText)
+        // Structured failure from the terminal frame wins over the legacy text
+        // heuristic ("Error: <provider detail>" texts don't match the regexes).
+        const completionError = failure?.error ?? completionErrorText(finalText)
+        // A partial failure's `text` is streamed output the user should keep,
+        // not the error string — settle it like a normal reply AND mark the
+        // bubble failed, instead of stripping the text.
+        const keepFailedPartialText = Boolean(failure?.partial && finalText)
         const interimBoundaryPending = state.interimBoundaryPending
 
         const replaceTextPart = (parts: ChatMessagePart[]) => {
@@ -473,15 +483,21 @@ export function useMessageStream({
         const completeMessage = (message: ChatMessage): ChatMessage => {
           const settled = { ...message, pending: false, interim: false }
 
-          return completionError
-            ? { ...settled, error: completionError, parts: message.parts.filter(part => part.type !== 'text') }
-            : { ...settled, parts: replaceTextPart(message.parts) }
+          if (completionError && !keepFailedPartialText) {
+            return { ...settled, error: completionError, parts: message.parts.filter(part => part.type !== 'text') }
+          }
+
+          return {
+            ...settled,
+            parts: replaceTextPart(message.parts),
+            ...(completionError ? { error: completionError } : {})
+          }
         }
 
         const newAssistantFromCompletion = (): ChatMessage => ({
           id: `assistant-${Date.now()}`,
           role: 'assistant',
-          parts: completionError ? [] : [assistantTextPart(finalText)],
+          parts: completionError && !keepFailedPartialText ? [] : [assistantTextPart(finalText)],
           branchGroupId: state.pendingBranchGroup ?? undefined,
           ...(completionError && { error: completionError })
         })
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/moa-progress-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/moa-progress-event.test.tsx
new file mode 100644
index 00000000000..1e4c0d37867
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/moa-progress-event.test.tsx
@@ -0,0 +1,123 @@
+import { QueryClient } from '@tanstack/react-query'
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import { useEffect, useRef } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ClientSessionState } from '@/app/types'
+import { createClientSessionState } from '@/lib/chat-runtime'
+import type { RpcEvent } from '@/types/hermes'
+
+import { useMessageStream } from './index'
+
+const SID = 'session-1'
+let handleEvent: ((event: RpcEvent) => void) | null = null
+let latestState: ClientSessionState | null = null
+
+function Harness() {
+  const activeSessionIdRef = useRef<string | null>(SID)
+  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
+  const queryClientRef = useRef(new QueryClient())
+
+  const stream = useMessageStream({
+    activeSessionIdRef,
+    hydrateFromStoredSession: vi.fn(async () => undefined),
+    queryClient: queryClientRef.current,
+    refreshHermesConfig: vi.fn(async () => undefined),
+    refreshSessions: vi.fn(async () => undefined),
+    sessionStateByRuntimeIdRef,
+    updateSessionState: (sessionId, updater) => {
+      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
+      const next = updater(current)
+      sessionStateByRuntimeIdRef.current.set(sessionId, next)
+      latestState = next
+
+      return next
+    }
+  })
+
+  useEffect(() => {
+    handleEvent = stream.handleGatewayEvent
+  }, [stream.handleGatewayEvent])
+
+  return null
+}
+
+async function mountStream() {
+  render(<Harness />)
+  await waitFor(() => expect(handleEvent).not.toBeNull())
+}
+
+function emit(type: RpcEvent['type'], payload: RpcEvent['payload'] = {}) {
+  act(() => handleEvent!({ payload, session_id: SID, type }))
+}
+
+function reasoningText(): string {
+  const message = latestState?.messages.at(-1)
+  const part = message?.parts.find(p => p.type === 'reasoning')
+
+  return part?.type === 'reasoning' ? part.text : ''
+}
+
+beforeEach(() => {
+  handleEvent = null
+  latestState = null
+})
+
+afterEach(() => {
+  cleanup()
+  vi.restoreAllMocks()
+})
+
+describe('useMessageStream moa.progress / moa.phase surfacing', () => {
+  it('shows refs k/n lines in the reasoning block as references complete', async () => {
+    await mountStream()
+
+    emit('message.start')
+    emit('moa.progress', { label: 'model-a', refs_done: 1, refs_total: 3 })
+    emit('moa.progress', { label: 'model-b', refs_done: 2, refs_total: 3 })
+
+    const text = reasoningText()
+    expect(text).toContain('MoA refs 1/3 — model-a')
+    expect(text).toContain('MoA refs 2/3 — model-b')
+  })
+
+  it('restarts the progress block on the first ref of a new fan-out', async () => {
+    await mountStream()
+
+    emit('message.start')
+    emit('moa.progress', { label: 'stale', refs_done: 1, refs_total: 2 })
+    emit('moa.progress', { label: 'stale-2', refs_done: 2, refs_total: 2 })
+    // A later turn's fan-out starts over at 1/N — old lines must not linger.
+    emit('moa.progress', { label: 'fresh', refs_done: 1, refs_total: 2 })
+
+    const text = reasoningText()
+    expect(text).toContain('MoA refs 1/2 — fresh')
+    expect(text).not.toContain('stale')
+  })
+
+  it('appends the aggregating marker on moa.phase and ignores unknown phases', async () => {
+    await mountStream()
+
+    emit('message.start')
+    emit('moa.progress', { label: 'model-a', refs_done: 1, refs_total: 1 })
+    emit('moa.phase', { phase: 'reference', refs_done: 1, refs_total: 1 })
+    expect(reasoningText()).not.toContain('aggregating')
+
+    emit('moa.phase', { aggregator: 'agg-model', phase: 'aggregator', refs_done: 1, refs_total: 1 })
+    expect(reasoningText()).toContain('MoA aggregating…')
+  })
+
+  it('a following moa.reference replaces the progress trail (self-cleaning)', async () => {
+    await mountStream()
+
+    emit('message.start')
+    emit('moa.progress', { label: 'model-a', refs_done: 1, refs_total: 1 })
+    emit('moa.phase', { phase: 'aggregator', refs_done: 1, refs_total: 1 })
+    emit('moa.reference', { count: 1, index: 1, label: 'model-a', text: 'advice-a' })
+
+    const text = reasoningText()
+    expect(text).toContain('Reference 1/1 — model-a')
+    expect(text).not.toContain('MoA refs')
+    expect(text).not.toContain('aggregating')
+  })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/moa-reference-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/moa-reference-event.test.tsx
new file mode 100644
index 00000000000..ce3afeef67e
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/moa-reference-event.test.tsx
@@ -0,0 +1,114 @@
+import { QueryClient } from '@tanstack/react-query'
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import { useEffect, useRef } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ClientSessionState } from '@/app/types'
+import { createClientSessionState } from '@/lib/chat-runtime'
+import type { RpcEvent } from '@/types/hermes'
+
+import { useMessageStream } from './index'
+
+const SID = 'session-1'
+let handleEvent: ((event: RpcEvent) => void) | null = null
+let latestState: ClientSessionState | null = null
+
+function Harness() {
+  const activeSessionIdRef = useRef<string | null>(SID)
+  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
+  const queryClientRef = useRef(new QueryClient())
+
+  const stream = useMessageStream({
+    activeSessionIdRef,
+    hydrateFromStoredSession: vi.fn(async () => undefined),
+    queryClient: queryClientRef.current,
+    refreshHermesConfig: vi.fn(async () => undefined),
+    refreshSessions: vi.fn(async () => undefined),
+    sessionStateByRuntimeIdRef,
+    updateSessionState: (sessionId, updater) => {
+      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
+      const next = updater(current)
+      sessionStateByRuntimeIdRef.current.set(sessionId, next)
+      latestState = next
+
+      return next
+    }
+  })
+
+  useEffect(() => {
+    handleEvent = stream.handleGatewayEvent
+  }, [stream.handleGatewayEvent])
+
+  return null
+}
+
+async function mountStream() {
+  render(<Harness />)
+  await waitFor(() => expect(handleEvent).not.toBeNull())
+}
+
+function emit(type: RpcEvent['type'], payload: RpcEvent['payload'] = {}) {
+  act(() => handleEvent!({ payload, session_id: SID, type }))
+}
+
+function reasoningText(): string {
+  const message = latestState?.messages.at(-1)
+  const part = message?.parts.find(p => p.type === 'reasoning')
+
+  return part?.type === 'reasoning' ? part.text : ''
+}
+
+describe('useMessageStream moa.reference accumulation (#64658)', () => {
+  beforeEach(() => {
+    handleEvent = null
+    latestState = null
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+  })
+
+  it('keeps every reference model labelled block instead of only the latest one', async () => {
+    await mountStream()
+
+    emit('moa.reference', { count: 2, index: 1, label: 'model-a', text: 'advice-a' })
+    emit('moa.reference', { count: 2, index: 2, label: 'model-b', text: 'advice-b' })
+
+    const text = reasoningText()
+
+    expect(text).toContain('model-a')
+    expect(text).toContain('advice-a')
+    expect(text).toContain('model-b')
+    expect(text).toContain('advice-b')
+  })
+
+  it('handles a single-reference MoA turn (count=1) without regression', async () => {
+    await mountStream()
+
+    emit('moa.reference', { count: 1, index: 1, label: 'model-a', text: 'only-advice' })
+
+    const text = reasoningText()
+
+    expect(text).toContain('model-a')
+    expect(text).toContain('only-advice')
+  })
+
+  it('accumulates three or more references in order', async () => {
+    await mountStream()
+
+    emit('moa.reference', { count: 3, index: 1, label: 'model-a', text: 'advice-a' })
+    emit('moa.reference', { count: 3, index: 2, label: 'model-b', text: 'advice-b' })
+    emit('moa.reference', { count: 3, index: 3, label: 'model-c', text: 'advice-c' })
+
+    const text = reasoningText()
+
+    const orderOk =
+      text.indexOf('advice-a') < text.indexOf('advice-b') && text.indexOf('advice-b') < text.indexOf('advice-c')
+
+    expect(text).toContain('advice-a')
+    expect(text).toContain('advice-b')
+    expect(text).toContain('advice-c')
+    expect(orderOk).toBe(true)
+  })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/stream-flush.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/stream-flush.test.tsx
new file mode 100644
index 00000000000..427e62cf8ad
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/stream-flush.test.tsx
@@ -0,0 +1,93 @@
+import { QueryClient } from '@tanstack/react-query'
+import { act, cleanup, render } from '@testing-library/react'
+import { useEffect, useRef } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ClientSessionState } from '@/app/types'
+import { createClientSessionState } from '@/lib/chat-runtime'
+import type { RpcEvent } from '@/types/hermes'
+
+import { STREAM_DELTA_FLUSH_MS } from './utils'
+
+import { useMessageStream } from './index'
+
+const SID = 'stream-session'
+
+let handleEvent: ((event: RpcEvent) => void) | null = null
+let states: Map<string, ClientSessionState>
+
+function Harness() {
+  const activeSessionIdRef = useRef<string | null>(SID)
+  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
+  const queryClientRef = useRef(new QueryClient())
+
+  const stream = useMessageStream({
+    activeSessionIdRef,
+    hydrateFromStoredSession: vi.fn(async () => undefined),
+    queryClient: queryClientRef.current,
+    refreshHermesConfig: vi.fn(async () => undefined),
+    refreshSessions: vi.fn(async () => undefined),
+    sessionStateByRuntimeIdRef,
+    updateSessionState: (sessionId, updater) => {
+      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
+      const next = updater(current)
+      sessionStateByRuntimeIdRef.current.set(sessionId, next)
+
+      return next
+    }
+  })
+
+  useEffect(() => {
+    handleEvent = stream.handleGatewayEvent
+    states = sessionStateByRuntimeIdRef.current
+  }, [stream.handleGatewayEvent])
+
+  return null
+}
+
+describe('stream delta delivery', () => {
+  beforeEach(() => {
+    handleEvent = null
+    states = new Map()
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('delivers a delta while animation frames are parked', async () => {
+    // An Electron renderer the compositor has parked: rAF accepts the callback
+    // but never runs it. A frame-gated flush strands the answer here until some
+    // later focus/input event wakes a frame.
+    const rafSpy = vi.spyOn(window, 'requestAnimationFrame').mockImplementation(() => 1)
+    vi.useFakeTimers()
+
+    render(<Harness />)
+    await act(async () => {
+      await Promise.resolve()
+    })
+
+    // Reach the frame-gated branch: it is only taken once the coalescing floor
+    // has already elapsed since the previous flush. Send one delta, let it
+    // flush, then idle past the floor so the NEXT delta schedules immediately.
+    act(() => handleEvent?.({ payload: { text: 'first ' }, session_id: SID, type: 'message.delta' }))
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(STREAM_DELTA_FLUSH_MS)
+    })
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(STREAM_DELTA_FLUSH_MS * 2)
+    })
+
+    act(() => handleEvent?.({ payload: { text: 'and the rest' }, session_id: SID, type: 'message.delta' }))
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(STREAM_DELTA_FLUSH_MS)
+    })
+
+    expect(states.get(SID)?.messages.at(-1)?.parts).toEqual([{ type: 'text', text: 'first and the rest' }])
+    // The flush must not have depended on a frame at all.
+    expect(rafSpy).not.toHaveBeenCalled()
+  })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/terminal-error-frame.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/terminal-error-frame.test.tsx
new file mode 100644
index 00000000000..a2c775a9124
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/terminal-error-frame.test.tsx
@@ -0,0 +1,119 @@
+import { QueryClient } from '@tanstack/react-query'
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import { useEffect, useRef } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ClientSessionState } from '@/app/types'
+import { chatMessageText } from '@/lib/chat-messages'
+import { createClientSessionState } from '@/lib/chat-runtime'
+import type { RpcEvent } from '@/types/hermes'
+
+import { useMessageStream } from './index'
+
+const SID = 'session-1'
+
+let handleEvent: ((event: RpcEvent) => void) | null = null
+let sessionStates: Map<string, ClientSessionState>
+
+function Harness() {
+  const activeSessionIdRef = useRef<string | null>(SID)
+  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
+  const queryClientRef = useRef(new QueryClient())
+
+  const stream = useMessageStream({
+    activeSessionIdRef,
+    hydrateFromStoredSession: vi.fn(async () => undefined),
+    queryClient: queryClientRef.current,
+    refreshHermesConfig: vi.fn(async () => undefined),
+    refreshSessions: vi.fn(async () => undefined),
+    sessionStateByRuntimeIdRef,
+    updateSessionState: (sessionId, updater) => {
+      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
+      const next = updater(current)
+      sessionStateByRuntimeIdRef.current.set(sessionId, next)
+      sessionStates.set(sessionId, next)
+
+      return next
+    }
+  })
+
+  useEffect(() => {
+    handleEvent = stream.handleGatewayEvent
+  }, [stream.handleGatewayEvent])
+
+  return null
+}
+
+async function mountStream() {
+  sessionStates = new Map()
+  render(<Harness />)
+  await waitFor(() => expect(handleEvent).not.toBeNull())
+}
+
+const start = () => act(() => handleEvent!({ payload: {}, session_id: SID, type: 'message.start' }))
+const delta = (text: string) => act(() => handleEvent!({ payload: { text }, session_id: SID, type: 'message.delta' }))
+
+const completeWithError = (payload: Record<string, unknown>) =>
+  act(() => handleEvent!({ payload: { status: 'error', ...payload }, session_id: SID, type: 'message.complete' }))
+
+function getState(): ClientSessionState {
+  return sessionStates.get(SID) ?? createClientSessionState()
+}
+
+function lastAssistant() {
+  return [...getState().messages].reverse().find(m => m.role === 'assistant' && !m.hidden)
+}
+
+describe('terminal error message.complete frames', () => {
+  beforeEach(() => {
+    handleEvent = null
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+  })
+
+  it('marks the bubble failed from the structured error field, not the text heuristic', async () => {
+    await mountStream()
+    await start()
+    await delta('…')
+
+    // "Error: <detail>" does not match the legacy completionErrorText regexes.
+    await completeWithError({ text: 'Error: invalid model slug', error: 'invalid model slug', recoverable: true })
+
+    const bubble = lastAssistant()
+    expect(bubble?.error).toBe('invalid model slug')
+    expect(getState().busy).toBe(false)
+    expect(getState().awaitingResponse).toBe(false)
+  })
+
+  it('keeps streamed partial text visible on a partial failure', async () => {
+    await mountStream()
+    await start()
+    await delta('half an ans')
+
+    await completeWithError({
+      text: 'half an ans',
+      error: 'connection reset mid-stream',
+      partial: true,
+      recoverable: true
+    })
+
+    const bubble = lastAssistant()
+    expect(bubble?.error).toBe('connection reset mid-stream')
+    expect(chatMessageText(bubble!)).toBe('half an ans')
+    expect(bubble?.pending).toBe(false)
+  })
+
+  it('falls back to the frame text when no error field is present', async () => {
+    await mountStream()
+    await start()
+    await delta('…')
+
+    await completeWithError({ text: 'Error: something broke' })
+
+    const bubble = lastAssistant()
+    expect(bubble?.error).toBe('Error: something broke')
+  })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/index.test.tsx b/apps/desktop/src/app/session/hooks/use-prompt-actions/index.test.tsx
index a7de88bf4de..28fd021fcf1 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions/index.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/index.test.tsx
@@ -5,7 +5,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { getSession } from '@/hermes'
 import { textPart } from '@/lib/chat-messages'
+import { createClientSessionState } from '@/lib/chat-runtime'
 import { $composerAttachments, $composerDraft, type ComposerAttachment, setComposerDraft } from '@/store/composer'
+import { $queuedPromptsBySession, getQueuedPrompts } from '@/store/composer-queue'
 import { $notifications, clearNotifications } from '@/store/notifications'
 import {
   $busy,
@@ -18,6 +20,7 @@ import {
   setMessages,
   setSessions
 } from '@/store/session'
+import { dropSessionState, publishSessionState } from '@/store/session-states'
 import type { SessionInfo } from '@/types/hermes'
 
 import type { SubmitTextOptions } from './utils'
@@ -73,6 +76,8 @@ async function actRender(ui: React.ReactElement) {
 interface HarnessHandle {
   activeSessionIdRef: MutableRefObject<string | null>
   cancelRun: () => Promise<void>
+  editMessage: (edited: Parameters<ReturnType<typeof usePromptActions>['editMessage']>[0]) => Promise<void>
+  reloadFromMessage: (parentId: null | string) => Promise<void>
   restoreToMessage: (messageId: string, target?: { text?: string; userOrdinal?: number | null }) => Promise<void>
   redirectPrompt: (text: string) => Promise<boolean>
   /** @deprecated Use `redirectPrompt`. */
@@ -120,7 +125,7 @@ function Harness({
   selectedStoredSessionIdRef?: MutableRefObject<string | null>
   storedSessionId?: null | string
   activeSessionId?: null | string
-  createBackendSessionForSend?: () => Promise<null | string>
+  createBackendSessionForSend?: (preview?: null | string) => Promise<null | string>
 }) {
   const localActiveSessionIdRef = useRef<string | null>(
     activeSessionId === undefined ? RUNTIME_SESSION_ID : activeSessionId
@@ -174,6 +179,10 @@ function Harness({
       activeSessionIdRef,
       cancelRun: (...args: Parameters<typeof actions.cancelRun>) =>
         act(async () => actions.cancelRun(...args)) as Promise<void>,
+      editMessage: (...args: Parameters<typeof actions.editMessage>) =>
+        act(async () => actions.editMessage(...args)) as Promise<void>,
+      reloadFromMessage: (...args: Parameters<typeof actions.reloadFromMessage>) =>
+        act(async () => actions.reloadFromMessage(...args)) as Promise<void>,
       restoreToMessage: (...args: Parameters<typeof actions.restoreToMessage>) =>
         act(async () => actions.restoreToMessage(...args)) as Promise<void>,
       redirectPrompt: (...args: Parameters<typeof actions.redirectPrompt>) =>
@@ -186,6 +195,8 @@ function Harness({
     })
   }, [
     actions.cancelRun,
+    actions.editMessage,
+    actions.reloadFromMessage,
     actions.restoreToMessage,
     actions.redirectPrompt,
     actions.steerPrompt,
@@ -309,6 +320,112 @@ function renderedSeedTexts(seeds: Record<string, unknown>[]): string[] {
   })
 }
 
+describe('usePromptActions slash session targeting', () => {
+  const STORED_SESSION_ID = 'stored-db-xyz789'
+  const RECOVERED_SESSION_ID = 'rt-recovered-456'
+
+  afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+  })
+
+  it('runs /goal status against the ROUTED stored session instead of minting a new one', async () => {
+    // Teknium's report: start a goal in the desktop app, then `/goal status`
+    // says there is no goal. `/goal` state lives per-session in SessionDB
+    // (`goal:<session_id>`), and slash.ts used to resolve its target with a
+    // bare `hint || activeRef || createSession()`. With the runtime binding
+    // momentarily absent (profile swap / reconnect / orphan-reap / timeout) it
+    // minted a NEW session, so the status query asked a session that never had
+    // a goal. submit.ts already resumes the routed chat here; both pipelines
+    // must resolve identically.
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+    const activeSessionIdRef: MutableRefObject<string | null> = { current: null }
+    const selectedStoredSessionIdRef: MutableRefObject<string | null> = { current: null }
+    let boundRuntimeId: null | string = null
+
+    const createBackendSessionForSend = vi.fn(async () => 'rt-brand-new-WRONG')
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      if (method === 'session.resume') {
+        boundRuntimeId = RECOVERED_SESSION_ID
+        selectedStoredSessionIdRef.current = STORED_SESSION_ID
+        activeSessionIdRef.current = RECOVERED_SESSION_ID
+
+        return { session_id: RECOVERED_SESSION_ID } as never
+      }
+
+      if (method === 'slash.exec') {
+        return { output: '⊙ Goal (active, 1/20 turns): build a rocket' } as never
+      }
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        activeSessionId={null}
+        activeSessionIdRef={activeSessionIdRef}
+        createBackendSessionForSend={createBackendSessionForSend}
+        getRoutedStoredSessionId={() => STORED_SESSION_ID}
+        getRuntimeIdForStoredSession={() => boundRuntimeId}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        selectedStoredSessionIdRef={selectedStoredSessionIdRef}
+        storedSessionId={null}
+      />
+    )
+
+    await handle!.submitText('/goal status')
+
+    // Never fork the conversation to answer a question about it.
+    expect(createBackendSessionForSend).not.toHaveBeenCalled()
+    expect(calls.map(c => c.method)).toEqual(['session.resume', 'slash.exec'])
+    expect(calls[0]?.params).toMatchObject({ session_id: STORED_SESSION_ID })
+    // The command lands on the recovered runtime that owns the goal.
+    expect(calls[1]?.params).toEqual({ command: 'goal status', session_id: RECOVERED_SESSION_ID })
+  })
+
+  it('does not fork the chat when the routed session cannot be rebound', async () => {
+    const calls: string[] = []
+    const createBackendSessionForSend = vi.fn(async () => 'rt-brand-new-WRONG')
+
+    const requestGateway = vi.fn(async (method: string) => {
+      calls.push(method)
+
+      if (method === 'session.resume') {
+        throw new Error('4007 session not found')
+      }
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        activeSessionId={null}
+        activeSessionIdRef={{ current: null }}
+        createBackendSessionForSend={createBackendSessionForSend}
+        getRoutedStoredSessionId={() => STORED_SESSION_ID}
+        getRuntimeIdForStoredSession={() => null}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        selectedStoredSessionIdRef={{ current: null }}
+        storedSessionId={null}
+      />
+    )
+
+    await handle!.submitText('/goal status')
+
+    expect(createBackendSessionForSend).not.toHaveBeenCalled()
+    expect(calls).not.toContain('slash.exec')
+  })
+})
+
 describe('usePromptActions /compress', () => {
   beforeEach(() => {
     setSessions(() => [sessionInfo()])
@@ -866,6 +983,285 @@ describe('usePromptActions slash.exec dispatch payloads', () => {
     expect(renderedText).not.toContain('/goal: no output')
   })
 
+  it('queues the /goal kickoff instead of dropping it when the session is busy (#63352)', async () => {
+    // The backend sets the goal the moment slash.exec runs — dropping the
+    // returned kickoff message because busyRef was true left a goal the agent
+    // never heard about. The busy path must park the kickoff on the composer
+    // queue so the settle drain sends it.
+    $queuedPromptsBySession.set({})
+
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+    const states: Record<string, unknown>[] = []
+    const busyRef = { current: true }
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      if (method === 'slash.exec') {
+        return {
+          type: 'send',
+          notice: '⊙ Goal set (20-turn budget): ship the release notes',
+          message: 'ship the release notes'
+        } as never
+      }
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        busyRef={busyRef}
+        onReady={h => (handle = h)}
+        onSeedState={s => states.push(s)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+      />
+    )
+
+    await handle!.submitText('/goal ship the release notes')
+
+    // The kickoff must NOT submit mid-turn — and must NOT vanish either.
+    expect(calls.map(c => c.method)).toEqual(['slash.exec'])
+
+    const queued = getQueuedPrompts(RUNTIME_SESSION_ID)
+    expect(queued.map(entry => entry.text)).toEqual(['ship the release notes'])
+
+    const renderedText = states
+      .flatMap(state => {
+        const messages = Array.isArray(state.messages)
+          ? (state.messages as Array<{ parts?: Array<{ text?: string }> }>)
+          : []
+
+        return messages.flatMap(message => (message.parts ?? []).map(part => part.text ?? ''))
+      })
+      .join('\n')
+
+    // The notice still renders, and the busy line reports a queue, not a demand
+    // to /interrupt.
+    expect(renderedText).toContain('⊙ Goal set (20-turn budget): ship the release notes')
+    expect(renderedText).toContain('queued')
+
+    $queuedPromptsBySession.set({})
+  })
+
+  it('gates the busy queue on the TARGET session, not the foreground busy flag', async () => {
+    // `busyRef` is the FOREGROUND view's busy flag; a slash command runs against
+    // the session `resolveTargetSessionId` picked, which is frequently not the
+    // foreground one (tile, route rebind, freshly created session). A stale
+    // foreground `true` — e.g. left behind by a warm resume of a *different*,
+    // still-running session — parked the kickoff of an idle session's command
+    // on the queue and told the user "session busy" about a session that was
+    // doing nothing.
+    $queuedPromptsBySession.set({})
+    publishSessionState(RUNTIME_SESSION_ID, createClientSessionState(RUNTIME_SESSION_ID))
+
+    const calls: string[] = []
+    const busyRef = { current: true }
+
+    const requestGateway = vi.fn(async (method: string) => {
+      calls.push(method)
+
+      return (method === 'slash.exec' ? { type: 'send', message: 'audit the session states' } : {}) as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        busyRef={busyRef}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+      />
+    )
+
+    await handle!.submitText('/audit-only audit the session states')
+
+    // The target session is idle, so the command sends now — nothing queues.
+    expect(calls).toContain('prompt.submit')
+    expect(getQueuedPrompts(RUNTIME_SESSION_ID)).toEqual([])
+
+    dropSessionState(RUNTIME_SESSION_ID)
+    $queuedPromptsBySession.set({})
+  })
+
+  it('still queues when the TARGET session is busy and the foreground flag is not', async () => {
+    // The converse leak: a background/tile command must not submit mid-turn
+    // just because the foreground view happens to be idle.
+    $queuedPromptsBySession.set({})
+    publishSessionState(RUNTIME_SESSION_ID, {
+      ...createClientSessionState(RUNTIME_SESSION_ID),
+      busy: true
+    })
+
+    const calls: string[] = []
+    const busyRef = { current: false }
+
+    const requestGateway = vi.fn(async (method: string) => {
+      calls.push(method)
+
+      return (method === 'slash.exec' ? { type: 'send', message: 'audit the session states' } : {}) as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        busyRef={busyRef}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+      />
+    )
+
+    await handle!.submitText('/audit-only audit the session states')
+
+    expect(calls).toEqual(['slash.exec'])
+    expect(getQueuedPrompts(RUNTIME_SESSION_ID).map(entry => entry.text)).toEqual(['audit the session states'])
+
+    dropSessionState(RUNTIME_SESSION_ID)
+    $queuedPromptsBySession.set({})
+  })
+
+  it('binds slash output and the busy queue to the TARGET session, not the foreground selection', async () => {
+    // A tile (⌘T tab, split pane) routes its slash commands through this hook
+    // with an explicit runtime id while the foreground selection names a
+    // different conversation. Binding the output writer to the foreground
+    // selection re-keyed the tile's cache entry onto the primary's stored
+    // session and parked its queued payload on the primary's queue.
+    const tileRuntimeId = 'tile-runtime'
+    const tileStoredId = 'tile-stored'
+
+    $queuedPromptsBySession.set({})
+    publishSessionState(tileRuntimeId, {
+      ...createClientSessionState(tileStoredId),
+      busy: true
+    })
+
+    const boundStoredIds: (null | string | undefined)[] = []
+
+    const requestGateway = vi.fn(
+      async (method: string) => (method === 'slash.exec' ? { type: 'send', message: 'run it in the tab' } : {}) as never
+    )
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        onReady={h => (handle = h)}
+        onUpdateState={(_sessionId, storedSessionId) => boundStoredIds.push(storedSessionId)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        storedSessionId="primary-stored"
+      />
+    )
+
+    await handle!.submitText('/audit-only run it in the tab', { sessionId: tileRuntimeId })
+
+    // Every transcript write lands on the tile's own stored session.
+    expect(boundStoredIds).not.toHaveLength(0)
+    expect(new Set(boundStoredIds)).toEqual(new Set([tileStoredId]))
+    // …and the kickoff queues against the tile, never the foreground chat.
+    expect(getQueuedPrompts(tileStoredId).map(entry => entry.text)).toEqual(['run it in the tab'])
+    expect(getQueuedPrompts('primary-stored')).toEqual([])
+
+    dropSessionState(tileRuntimeId)
+    $queuedPromptsBySession.set({})
+  })
+
+  it("sends a skill's kickoff into the TAB that invoked it, not the foreground chat", async () => {
+    // `/work` in a fresh ⌘T tab: slash.exec returns a skill dispatch whose
+    // `message` is the kickoff prompt. The dispatcher resolved the tab as its
+    // target, printed "⚡ loading skill" there — then submitted the kickoff
+    // with no target at all, so submit re-resolved from activeSessionIdRef and
+    // fired it as a user message into whatever conversation was on screen.
+    const tabRuntimeId = 'tab-runtime'
+    const tabStoredId = 'tab-stored'
+
+    $queuedPromptsBySession.set({})
+    publishSessionState(tabRuntimeId, createClientSessionState(tabStoredId))
+
+    const submitted: (Record<string, unknown> | undefined)[] = []
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      if (method === 'prompt.submit') {
+        submitted.push(params)
+      }
+
+      return (
+        method === 'slash.exec'
+          ? { type: 'skill', name: 'work', message: 'Load the work skill, then: fix the tab bug' }
+          : {}
+      ) as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        activeSessionId="foreground-runtime"
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        storedSessionId="foreground-stored"
+      />
+    )
+
+    await handle!.submitText('/work fix the tab bug', { sessionId: tabRuntimeId })
+
+    expect(submitted).toEqual([
+      expect.objectContaining({
+        session_id: tabRuntimeId,
+        text: 'Load the work skill, then: fix the tab bug'
+      })
+    ])
+
+    dropSessionState(tabRuntimeId)
+    $queuedPromptsBySession.set({})
+  })
+
+  it('slash status header carries the command token, not the full invocation', async () => {
+    // `/goal <long prose>` used to echo the entire invocation in the mono
+    // header AND the goal text again in the backend notice right under it.
+    const states: Record<string, unknown>[] = []
+
+    const requestGateway = vi.fn(async (method: string) => {
+      if (method === 'slash.exec') {
+        return {
+          type: 'send',
+          notice: '⊙ Goal set: build the whole thing',
+          message: 'build the whole thing end to end with tests'
+        } as never
+      }
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        onReady={h => (handle = h)}
+        onSeedState={s => states.push(s)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+      />
+    )
+
+    await handle!.submitText('/goal build the whole thing end to end with tests')
+
+    const systemTexts = states
+      .flatMap(state => {
+        const messages = Array.isArray(state.messages)
+          ? (state.messages as Array<{ role?: string; parts?: Array<{ text?: string }> }>)
+          : []
+
+        return messages
+          .filter(message => message.role === 'system')
+          .flatMap(message => (message.parts ?? []).map(part => part.text ?? ''))
+      })
+      .join('\n')
+
+    expect(systemTexts).toContain('slash:/goal\n')
+    expect(systemTexts).not.toContain('slash:/goal build the whole thing')
+  })
+
   it('dispatches a slash command with a multiline arg instead of "empty slash command" (#41323, #55510)', async () => {
     const calls: { method: string; params?: Record<string, unknown> }[] = []
     const states: Record<string, unknown>[] = []
@@ -1162,6 +1558,62 @@ describe('usePromptActions submit / queue drain semantics', () => {
     expect($busy.get()).toBe(false)
   })
 
+  it('a fromQueue drain with null runtime id does NOT land in the foreground session (cross-session leak guard)', async () => {
+    // The cross-session leak: a background drain fires with sessionId=null
+    // (the stored session's runtime was reaped by the gateway). Without the
+    // guard, `null ?? activeSessionIdRef.current` falls back to whichever
+    // runtime id the foreground happens to hold — landing the queued prompt
+    // in the chat the user is currently viewing, NOT the session that owns
+    // the queue entry. The drain must instead go through session.resume to
+    // rebind the correct runtime before submitting.
+    const requestGateway = vi.fn(
+      async (method: string, _params?: Record<string, unknown>, _timeoutMs?: number) =>
+        (method === 'session.resume' ? { session_id: 'rt-session-a-rebound' } : {}) as never
+    )
+
+    let handle: HarnessHandle | null = null
+    render(
+      <Harness
+        activeSessionId={'rt-foreground'}
+        getRuntimeIdForStoredSession={() => null}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        storedSessionId={'rt-foreground'}
+      />
+    )
+
+    // Background drain: sessionId=null (binding reaped), storedSessionId
+    // points to a DIFFERENT session than the foreground.
+    const accepted = await handle!.submitText('queued for background session', {
+      fromQueue: true,
+      sessionId: null,
+      storedSessionId: 'stored-session-a'
+    })
+
+    expect(accepted).toBe(true)
+    // Must resume the correct stored session to get the right runtime id.
+    expect(requestGateway).toHaveBeenCalledWith('session.resume', {
+      session_id: 'stored-session-a',
+      source: 'desktop'
+    })
+    // The prompt must land in the resumed session, NOT the foreground.
+    expect(requestGateway).toHaveBeenCalledWith(
+      'prompt.submit',
+      {
+        session_id: 'rt-session-a-rebound',
+        text: 'queued for background session'
+      },
+      1_800_000
+    )
+    // The invariant: the foreground runtime never receives the prompt.
+    expect(
+      requestGateway.mock.calls.every(
+        ([method, params]) => method !== 'prompt.submit' || params?.session_id !== 'rt-foreground'
+      )
+    ).toBe(true)
+  })
+
   it('a rejected fromQueue drain returns false (entry stays queued) and a later retry sends it', async () => {
     // A stale-session 404 must not strand the queued entry: submitPrompt returns
     // false on failure so the composer keeps it, and the edge-independent
@@ -1450,7 +1902,8 @@ describe('usePromptActions restoreToMessage', () => {
       {
         session_id: RUNTIME_SESSION_ID,
         text: 'first prompt',
-        truncate_before_user_ordinal: 0
+        truncate_before_user_ordinal: 0,
+        confirm_empty_truncate: true
       },
       1_800_000
     )
@@ -1517,7 +1970,8 @@ describe('usePromptActions restoreToMessage', () => {
       {
         session_id: RUNTIME_SESSION_ID,
         text: 'first prompt',
-        truncate_before_user_ordinal: 0
+        truncate_before_user_ordinal: 0,
+        confirm_empty_truncate: true
       },
       1_800_000
     )
@@ -1562,7 +2016,8 @@ describe('usePromptActions restoreToMessage', () => {
       {
         session_id: RUNTIME_SESSION_ID,
         text: 'first prompt',
-        truncate_before_user_ordinal: 0
+        truncate_before_user_ordinal: 0,
+        confirm_empty_truncate: true
       },
       1_800_000
     )
@@ -2455,6 +2910,7 @@ describe('usePromptActions submit session-context isolation (#54527)', () => {
   afterEach(() => {
     cleanup()
     vi.restoreAllMocks()
+    setSessions(() => [])
   })
 
   it('aborts submit when the user switches sessions during session.resume (no misroute)', async () => {
@@ -2512,6 +2968,100 @@ describe('usePromptActions submit session-context isolation (#54527)', () => {
     })
   })
 
+  it('does not false-positive-abort when the session has rotated via compression (lineage root vs tip)', async () => {
+    // The composer keys drafts/attachments on the DURABLE lineage root
+    // (resolveComposerSessionKey / sessionPinId — survives auto-compression
+    // tip rotation), but selectedStoredSessionIdRef tracks the CURRENT TIP.
+    // For any session that has compressed at least once, root !== tip — if
+    // composerScope is compared against the raw tip, every legitimate submit
+    // into that session would look like drift.
+    const ROOT_ID = 'stored-root-original'
+    const TIP_ID = 'stored-tip-after-compression'
+
+    setSessions(() => [sessionInfo({ id: TIP_ID, _lineage_root_id: ROOT_ID })])
+
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        storedSessionId={TIP_ID}
+      />
+    )
+
+    // The composer's scope is the lineage root (what resolveComposerSessionKey
+    // actually returns for this session) — a legitimate, non-drifted submit.
+    const ok = await handle!.submitText('message into the rotated session', { composerScope: ROOT_ID })
+
+    expect(ok).toBe(true)
+    expect(calls.some(c => c.method === 'prompt.submit')).toBe(true)
+  })
+
+  it('aborts submit when the composer scope disagrees with the resolved target (#59305)', async () => {
+    // The composer (ChatBar) and the session-side refs live in separate React
+    // subtrees; each can be internally consistent yet still disagree with each
+    // other at the instant of send if the two updated on different commits.
+    // composerScope carries the composer's own snapshot of "what session was
+    // loaded" into submit.ts, which must refuse to send when it disagrees with
+    // the session the submit is actually about to target.
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        storedSessionId={STORED_SESSION_A}
+      />
+    )
+
+    const ok = await handle!.submitText('typed while B was on screen', { composerScope: STORED_SESSION_B })
+
+    expect(ok).toBe(false)
+    expect(calls.some(c => c.method === 'prompt.submit')).toBe(false)
+  })
+
+  it('submits normally when the composer scope agrees with the resolved target', async () => {
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        storedSessionId={STORED_SESSION_A}
+      />
+    )
+
+    const ok = await handle!.submitText('typed while A was on screen', { composerScope: STORED_SESSION_A })
+
+    expect(ok).toBe(true)
+    expect(calls.some(c => c.method === 'prompt.submit')).toBe(true)
+  })
+
   it('aborts recovery submit when the user switches sessions during timeout resume', async () => {
     const calls: { method: string; params?: Record<string, unknown> }[] = []
     let submitAttempts = 0
@@ -2669,6 +3219,423 @@ describe('usePromptActions submit session-context isolation (#54527)', () => {
   })
 })
 
+describe('usePromptActions new-chat first-send delivery (#63078)', () => {
+  const NEW_RUNTIME_ID = 'rt-first-send'
+  const NEW_STORED_ID = 'stored-first-send'
+
+  afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+    $connection.set(null)
+    $composerAttachments.set([])
+  })
+
+  it('delivers the first message of a new chat through the intentional route transition (#62562)', async () => {
+    const activeSessionIdRef: MutableRefObject<string | null> = { current: null }
+    const selectedStoredSessionIdRef: MutableRefObject<string | null> = { current: null }
+    let routeToken = '/::'
+
+    // Mirror the real session creator: session.create selects the persisted
+    // row and replaces the new-chat route with the created session's URL
+    // BEFORE returning. The submit pipeline must adopt that intentional
+    // transition as its new pinned target — not mistake it for the user
+    // switching conversations and stop before prompt.submit.
+    const createBackendSessionForSend = vi.fn(async (preview?: null | string) => {
+      expect(preview).toBe('first message of a new chat')
+      activeSessionIdRef.current = NEW_RUNTIME_ID
+      selectedStoredSessionIdRef.current = NEW_STORED_ID
+      routeToken = `/${NEW_STORED_ID}::`
+
+      return NEW_RUNTIME_ID
+    })
+
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    render(
+      <Harness
+        activeSessionId={null}
+        activeSessionIdRef={activeSessionIdRef}
+        createBackendSessionForSend={createBackendSessionForSend}
+        getRouteToken={() => routeToken}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        selectedStoredSessionIdRef={selectedStoredSessionIdRef}
+        storedSessionId={null}
+      />
+    )
+    await waitFor(() => expect(handle).not.toBeNull())
+
+    expect(await handle!.submitText('first message of a new chat')).toBe(true)
+    expect(createBackendSessionForSend).toHaveBeenCalledTimes(1)
+    // The FULL RPC transcript: exactly one prompt.submit, addressed to the
+    // created runtime session, carrying the user's text — no session.resume
+    // detour and, critically, no silent drop before the submit.
+    expect(calls).toEqual([
+      {
+        method: 'prompt.submit',
+        params: { session_id: NEW_RUNTIME_ID, text: 'first message of a new chat' }
+      }
+    ])
+  })
+
+  it('delivers the first prompt when React Router commits the created-session route late (#62990)', async () => {
+    // The creator requests the navigation, but React Router can still expose
+    // the OLD new-chat route to the submit continuation for a beat, committing
+    // the created session's URL only before the next await settles. Neither
+    // route snapshot (stale '/', then the late-committed session route) is a
+    // user switch — both are the pipeline's own transition and the first
+    // prompt must still reach the gateway.
+    const activeSessionIdRef: MutableRefObject<string | null> = { current: null }
+    const selectedStoredSessionIdRef: MutableRefObject<string | null> = { current: null }
+    let sessionCreated = false
+    let routeReadsAfterCreate = 0
+
+    const createBackendSessionForSend = vi.fn(async () => {
+      activeSessionIdRef.current = NEW_RUNTIME_ID
+      selectedStoredSessionIdRef.current = NEW_STORED_ID
+      sessionCreated = true
+
+      return NEW_RUNTIME_ID
+    })
+
+    const requestGateway = vi.fn(async () => ({}) as never)
+
+    let handle: HarnessHandle | null = null
+    render(
+      <Harness
+        activeSessionId={null}
+        activeSessionIdRef={activeSessionIdRef}
+        createBackendSessionForSend={createBackendSessionForSend}
+        getRouteToken={() => {
+          if (!sessionCreated) {
+            return '/::'
+          }
+
+          routeReadsAfterCreate += 1
+
+          // React Router can still expose / to the outer submit continuation,
+          // then commit the created-session route before the next await settles.
+          return routeReadsAfterCreate === 1 ? '/::' : `/${NEW_STORED_ID}::`
+        }}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        selectedStoredSessionIdRef={selectedStoredSessionIdRef}
+        storedSessionId={null}
+      />
+    )
+    await waitFor(() => expect(handle).not.toBeNull())
+
+    expect(await handle!.submitText('hello')).toBe(true)
+    expect(requestGateway).toHaveBeenCalledWith(
+      'prompt.submit',
+      {
+        session_id: NEW_RUNTIME_ID,
+        text: 'hello'
+      },
+      1_800_000
+    )
+  })
+
+  it('aborts a new-session submit when sidebar navigation changes the route before its selected ref (#62562)', async () => {
+    const activeSessionIdRef: MutableRefObject<string | null> = { current: null }
+    const selectedStoredSessionIdRef: MutableRefObject<string | null> = { current: null }
+    let routeToken = '/::'
+
+    let releaseAttach: () => void = () => {}
+
+    $connection.set({ mode: 'remote' } as never)
+    Object.defineProperty(window, 'hermesDesktop', {
+      configurable: true,
+      value: { readFileDataUrl: vi.fn(async () => 'data:text/plain;base64,aGVsbG8=') }
+    })
+
+    const createBackendSessionForSend = vi.fn(async () => {
+      activeSessionIdRef.current = NEW_RUNTIME_ID
+      selectedStoredSessionIdRef.current = NEW_STORED_ID
+      routeToken = `/${NEW_STORED_ID}::`
+
+      return NEW_RUNTIME_ID
+    })
+
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      if (method === 'file.attach') {
+        await new Promise<void>(resolve => {
+          releaseAttach = resolve
+        })
+
+        return {
+          attached: true,
+          path: '/remote/work/report.txt',
+          ref_text: '@file:report.txt',
+          uploaded: true
+        } as never
+      }
+
+      return {} as never
+    })
+
+    const attachment: ComposerAttachment = {
+      id: 'file:report.txt',
+      kind: 'file',
+      label: 'report.txt',
+      path: '/Users/alice/report.txt',
+      refText: '@file:`/Users/alice/report.txt`'
+    }
+
+    let handle: HarnessHandle | null = null
+    render(
+      <Harness
+        activeSessionId={null}
+        activeSessionIdRef={activeSessionIdRef}
+        createBackendSessionForSend={createBackendSessionForSend}
+        getRouteToken={() => routeToken}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        selectedStoredSessionIdRef={selectedStoredSessionIdRef}
+        storedSessionId={null}
+      />
+    )
+    await waitFor(() => expect(handle).not.toBeNull())
+
+    const submitting = handle!.submitText('first message', { attachments: [attachment] })
+    await waitFor(() => expect(calls.some(call => call.method === 'file.attach')).toBe(true))
+
+    // selectSidebarItem calls navigate() first. The routed effect has not yet
+    // entered resumeSession(), so the selected-session ref still points at the
+    // just-created session when attachment sync settles — the route move to a
+    // DIFFERENT chat must abort on its own.
+    routeToken = '/sidebar-target::'
+    releaseAttach()
+
+    expect(await submitting).toBe(false)
+    expect(selectedStoredSessionIdRef.current).toBe(NEW_STORED_ID)
+    expect(calls.some(call => call.method === 'prompt.submit')).toBe(false)
+  })
+
+  it('still aborts when the user genuinely switches chats after create, during attachment sync (#62805)', async () => {
+    // The post-create re-baseline (adopting the created chat as the pinned
+    // target) must not mask a REAL switch later in the pipeline: the user
+    // clicks a different session after createBackendSessionForSend lands but
+    // before attachment sync settles — selection AND route both move to the
+    // other chat, and the drift check at the post-attachments boundary must
+    // abort rather than deliver the text into whichever chat won the race.
+    const activeSessionIdRef: MutableRefObject<string | null> = { current: null }
+    const selectedStoredSessionIdRef: MutableRefObject<string | null> = { current: null }
+    let routeToken = '/::'
+
+    let releaseFileAttach: () => void = () => {}
+
+    $connection.set({ mode: 'remote' } as never)
+    Object.defineProperty(window, 'hermesDesktop', {
+      configurable: true,
+      value: { readFileDataUrl: vi.fn(async () => 'data:application/pdf;base64,JVBERi0=') }
+    })
+
+    const createBackendSessionForSend = vi.fn(async () => {
+      activeSessionIdRef.current = NEW_RUNTIME_ID
+      selectedStoredSessionIdRef.current = NEW_STORED_ID
+      routeToken = `/${NEW_STORED_ID}::`
+
+      return NEW_RUNTIME_ID
+    })
+
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      if (method === 'file.attach') {
+        // Block here so the user can switch sessions mid-sync.
+        await new Promise<void>(resolve => {
+          releaseFileAttach = resolve
+        })
+
+        return {
+          attached: true,
+          ref_text: '@file:.hermes/desktop-attachments/test.pdf',
+          uploaded: true
+        } as never
+      }
+
+      return {} as never
+    })
+
+    const attachment: ComposerAttachment = {
+      id: 'file:test',
+      kind: 'file',
+      label: 'test.pdf',
+      path: '/abs/test.pdf',
+      refText: '@file:`/abs/test.pdf`'
+    }
+
+    let handle: HarnessHandle | null = null
+    render(
+      <Harness
+        activeSessionId={null}
+        activeSessionIdRef={activeSessionIdRef}
+        createBackendSessionForSend={createBackendSessionForSend}
+        getRouteToken={() => routeToken}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        selectedStoredSessionIdRef={selectedStoredSessionIdRef}
+        storedSessionId={null}
+      />
+    )
+    await waitFor(() => expect(handle).not.toBeNull())
+
+    const submitting = handle!.submitText('message before the switch', { attachments: [attachment] })
+    await waitFor(() => expect(calls.some(c => c.method === 'file.attach')).toBe(true))
+
+    // Simulate a user switching to a different session after the new session
+    // was created and the sync phase started.
+    selectedStoredSessionIdRef.current = 'stored-other-session'
+    routeToken = '/stored-other-session::'
+    releaseFileAttach()
+
+    expect(await submitting).toBe(false)
+    expect(calls.some(c => c.method === 'prompt.submit')).toBe(false)
+  })
+})
+
+describe('usePromptActions busy-gateway churn tolerance (#64327)', () => {
+  const STORED_ID = 'stored-busy-gw'
+  const RESUMED_RUNTIME_ID = 'rt-busy-gw'
+
+  afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+  })
+
+  it('does not abort a send when programmatic gateway churn fires mid-submit (selection null-reset + search/hash route churn)', async () => {
+    // The busy-gateway superset of #63078: with background streaming sessions,
+    // per-minute cron sessions, or a messaging surface active, the selected
+    // stored id gets null-reset by gateway/profile reconnects and overlays
+    // park state in location.search/hash. None of that is the user changing
+    // chats — a send from a second chat must ride through it and reach
+    // prompt.submit instead of silently aborting.
+    let releaseResume: () => void = () => {}
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+
+    const selectedStoredSessionIdRef: MutableRefObject<string | null> = { current: STORED_ID }
+    const activeSessionIdRef: MutableRefObject<string | null> = { current: null }
+    let routeToken = `/${STORED_ID}::`
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      if (method === 'session.resume') {
+        await new Promise<void>(resolve => {
+          releaseResume = resolve
+        })
+
+        return { session_id: RESUMED_RUNTIME_ID } as never
+      }
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    render(
+      <Harness
+        activeSessionId={null}
+        activeSessionIdRef={activeSessionIdRef}
+        getRouteToken={() => routeToken}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        selectedStoredSessionIdRef={selectedStoredSessionIdRef}
+        storedSessionId={STORED_ID}
+      />
+    )
+    await waitFor(() => expect(handle).not.toBeNull())
+
+    const submitting = handle!.submitText('send from a second chat on a busy gateway')
+    await waitFor(() => expect(calls.some(c => c.method === 'session.resume')).toBe(true))
+
+    // Programmatic churn while resume is in flight — NOT user switches:
+    // a gateway/profile reconnect null-resets the selection...
+    selectedStoredSessionIdRef.current = null
+    // ...a background event retargets the active runtime ref (#47709 class)...
+    activeSessionIdRef.current = 'rt-some-background-session'
+    // ...and an overlay parks state in search/hash (pathname unchanged).
+    routeToken = `/${STORED_ID}:?panel=preview:#reply`
+    releaseResume()
+
+    expect(await submitting).toBe(true)
+    expect(calls.find(c => c.method === 'prompt.submit')?.params).toMatchObject({
+      session_id: RESUMED_RUNTIME_ID,
+      text: 'send from a second chat on a busy gateway'
+    })
+  })
+
+  it('still aborts when the user genuinely moves to a different chat mid-submit', async () => {
+    // The churn tolerance must not weaken the real guard: selection AND route
+    // moving to another actual chat is a user switch and must abort.
+    let releaseResume: () => void = () => {}
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+
+    const selectedStoredSessionIdRef: MutableRefObject<string | null> = { current: STORED_ID }
+    const activeSessionIdRef: MutableRefObject<string | null> = { current: null }
+    let routeToken = `/${STORED_ID}::`
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      if (method === 'session.resume') {
+        await new Promise<void>(resolve => {
+          releaseResume = resolve
+        })
+
+        return { session_id: RESUMED_RUNTIME_ID } as never
+      }
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    render(
+      <Harness
+        activeSessionId={null}
+        activeSessionIdRef={activeSessionIdRef}
+        getRouteToken={() => routeToken}
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        selectedStoredSessionIdRef={selectedStoredSessionIdRef}
+        storedSessionId={STORED_ID}
+      />
+    )
+    await waitFor(() => expect(handle).not.toBeNull())
+
+    const submitting = handle!.submitText('must not land in the other chat')
+    await waitFor(() => expect(calls.some(c => c.method === 'session.resume')).toBe(true))
+
+    // A genuine switch: the user clicks another chat, which retargets
+    // selection and route synchronously.
+    selectedStoredSessionIdRef.current = 'stored-other-chat'
+    routeToken = '/stored-other-chat::'
+    releaseResume()
+
+    expect(await submitting).toBe(false)
+    expect(calls.some(c => c.method === 'prompt.submit')).toBe(false)
+  })
+})
+
 describe('usePromptActions eager attachment upload (drop-time)', () => {
   afterEach(() => {
     cleanup()
@@ -2817,3 +3784,176 @@ describe('uploadComposerAttachment remote read failures', () => {
     ).rejects.toThrow('ENOENT: no such file')
   })
 })
+
+// The actions bag is a STABLE ref that wiring.tsx mutates in place
+// (Object.assign), and the pane surfaces are memoized on that stable ref — so a
+// surface does NOT re-render when the active session changes and its props keep
+// holding whichever `usePromptActions` closure was current when it last
+// rendered. `activeSessionIdRef` is therefore the authority (mirrored during
+// render in use-session-state-cache, and pinned imperatively mid-flight by
+// submit.ts / use-session-actions without touching the source prop), while the
+// closure-captured `activeSessionId` prop is stale by design.
+//
+// Every action below used `activeSessionId || activeSessionIdRef.current`, which
+// prefers the STALE value whenever it is non-null and only consults the fresh
+// ref once the prop is null. That routed history-mutating writes and live-turn
+// corrections into the previously-focused chat: content the user typed in chat B
+// reached chat A's agent, and rewinds truncated the wrong session's transcript.
+// `cancelRun` in the same file already reads the ref exclusively and documents
+// exactly this hazard.
+describe('usePromptActions stale-closure session routing', () => {
+  const RUNTIME_SESSION_B = 'rt-session-b-current'
+
+  beforeEach(() => {
+    // Earlier suites in this file leave `$busy` true (it is a module-level
+    // store, shared across tests). reloadFromMessage bails on a busy session,
+    // so without this reset the regeneration case never reaches its routing
+    // decision and would pass vacuously.
+    $busy.set(false)
+  })
+
+  afterEach(() => {
+    cleanup()
+    setMessages([])
+    $busy.set(false)
+    vi.restoreAllMocks()
+  })
+
+  type GatewayCall = [string, Record<string, unknown>?]
+  type GatewayRequestFn = <T>(method: string, params?: Record<string, unknown>, timeoutMs?: number) => Promise<T>
+  type GatewayMock = GatewayRequestFn & { mock: { calls: unknown[][] } }
+
+  function gatewayCalls(requestGateway: GatewayMock): GatewayCall[] {
+    return requestGateway.mock.calls as unknown as GatewayCall[]
+  }
+
+  // Renders with `activeSessionId` (the prop) pinned to session A, then moves
+  // the ref to session B — the exact split a memoized surface holds after the
+  // user switches chats. Every action must target B.
+  //
+  // The rewind/reload planners read the GLOBAL `$messages` store (the view
+  // transcript), not the harness's per-session state, so the fixture has to
+  // seed both or the action bails on a null plan and the test would pass
+  // vacuously without ever reaching the routing decision.
+  async function renderWithStaleClosure(requestGateway: GatewayMock, seedMessages?: unknown[]) {
+    const activeSessionIdRef: MutableRefObject<string | null> = { current: RUNTIME_SESSION_ID }
+    const updated: string[] = []
+
+    if (seedMessages) {
+      setMessages(seedMessages as never)
+    }
+
+    let handle: HarnessHandle | null = null
+    await actRender(
+      <Harness
+        activeSessionId={RUNTIME_SESSION_ID}
+        activeSessionIdRef={activeSessionIdRef}
+        onReady={h => (handle = h)}
+        onUpdateState={sessionId => updated.push(sessionId)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        seedMessages={seedMessages}
+        selectedStoredSessionIdRef={{ current: null }}
+      />
+    )
+
+    // The user switches to session B. The ref follows; the prop captured in the
+    // memoized surface's closure still says session A.
+    activeSessionIdRef.current = RUNTIME_SESSION_B
+
+    return { handle: handle!, updated }
+  }
+
+  it('redirects the live turn into the CURRENT session, not the stale closure session', async () => {
+    const requestGateway = vi.fn(async () => ({ status: 'redirected' }) as never) as unknown as GatewayMock
+    const { handle } = await renderWithStaleClosure(requestGateway)
+
+    await handle.redirectPrompt('actually use Postgres')
+
+    // A redirect reaches the model mid-turn. Sent to the stale session, the
+    // correction lands in a conversation the user is no longer looking at —
+    // this is the observed "session suddenly working on another chat's task".
+    expect(requestGateway).toHaveBeenCalledWith('session.redirect', {
+      session_id: RUNTIME_SESSION_B,
+      text: 'actually use Postgres'
+    })
+    expect(requestGateway).not.toHaveBeenCalledWith(
+      'session.redirect',
+      expect.objectContaining({ session_id: RUNTIME_SESSION_ID })
+    )
+  })
+
+  it('regenerates against the CURRENT session, not the stale closure session', async () => {
+    const requestGateway = vi.fn(async () => ({}) as never) as unknown as GatewayMock
+
+    const { handle, updated } = await renderWithStaleClosure(requestGateway, [
+      { id: 'u1', parts: [textPart('original prompt')], role: 'user', timestamp: 0 },
+      { id: 'a1', parts: [textPart('reply')], role: 'assistant', timestamp: 1 }
+    ])
+
+    await handle.reloadFromMessage('u1')
+
+    // prompt.submit with a truncate ordinal DELETES history after that point.
+    // Aimed at the stale session it destroys the wrong transcript.
+    expect(requestGateway).toHaveBeenCalledWith(
+      'prompt.submit',
+      expect.objectContaining({ session_id: RUNTIME_SESSION_B }),
+      expect.anything()
+    )
+    expect(requestGateway).not.toHaveBeenCalledWith(
+      'prompt.submit',
+      expect.objectContaining({ session_id: RUNTIME_SESSION_ID }),
+      expect.anything()
+    )
+    expect(updated).toContain(RUNTIME_SESSION_B)
+    expect(updated).not.toContain(RUNTIME_SESSION_ID)
+  })
+
+  it('restores a checkpoint in the CURRENT session, not the stale closure session', async () => {
+    const requestGateway = vi.fn(async () => ({}) as never) as unknown as GatewayMock
+
+    const { handle, updated } = await renderWithStaleClosure(requestGateway, [
+      { id: 'u1', parts: [textPart('first prompt')], role: 'user', timestamp: 0 },
+      { id: 'a1', parts: [textPart('first reply')], role: 'assistant', timestamp: 1 },
+      { id: 'u2', parts: [textPart('second prompt')], role: 'user', timestamp: 2 }
+    ])
+
+    await handle.restoreToMessage('u2')
+
+    // A rewind is destructive; the optimistic truncation must also be applied
+    // to the session that actually receives the rewind.
+    expect(updated).toContain(RUNTIME_SESSION_B)
+    expect(updated).not.toContain(RUNTIME_SESSION_ID)
+
+    for (const [, params] of gatewayCalls(requestGateway)) {
+      if (params && 'session_id' in params) {
+        expect(params.session_id).toBe(RUNTIME_SESSION_B)
+      }
+    }
+  })
+
+  it('edits a message in the CURRENT session, not the stale closure session', async () => {
+    const requestGateway = vi.fn(async () => ({}) as never) as unknown as GatewayMock
+
+    const { handle, updated } = await renderWithStaleClosure(requestGateway, [
+      { id: 'u1', parts: [textPart('original prompt')], role: 'user', timestamp: 0 },
+      { id: 'a1', parts: [textPart('reply')], role: 'assistant', timestamp: 1 }
+    ])
+
+    await handle.editMessage({
+      content: [{ text: 'edited prompt', type: 'text' }],
+      parentId: null,
+      role: 'user',
+      sourceId: 'u1'
+    } as never)
+
+    expect(updated).toContain(RUNTIME_SESSION_B)
+    expect(updated).not.toContain(RUNTIME_SESSION_ID)
+
+    for (const [, params] of gatewayCalls(requestGateway)) {
+      if (params && 'session_id' in params) {
+        expect(params.session_id).toBe(RUNTIME_SESSION_B)
+      }
+    }
+  })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/index.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/index.ts
index 1e314fe714a..bee6192894c 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions/index.ts
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/index.ts
@@ -53,7 +53,8 @@ import {
   planEdit,
   planReload,
   planRestore,
-  runRewindSubmit
+  runRewindSubmit,
+  truncateSubmitParams
 } from './rewind'
 import { useSlashCommand } from './slash'
 import { useSubmitPrompt } from './submit'
@@ -497,6 +498,8 @@ export function usePromptActions({
     busyRef,
     copy,
     createBackendSessionForSend,
+    getRoutedStoredSessionId,
+    getRuntimeIdForStoredSession,
     handleSkinCommand,
     handoffSession,
     openMemoryGraph,
@@ -516,7 +519,9 @@ export function usePromptActions({
 
       if (!attachments.length && SLASH_COMMAND_RE.test(visibleText)) {
         triggerHaptic('selection')
-        await executeSlashCommand(visibleText)
+        // Forward the explicit target (background queue drain, tile) — dropping
+        // it ran the command against whatever chat happened to be in front.
+        await executeSlashCommand(visibleText, options?.sessionId ? { sessionId: options.sessionId } : undefined)
 
         return true
       }
@@ -636,7 +641,10 @@ export function usePromptActions({
   const redirectPrompt = useCallback(
     async (rawText: string): Promise<boolean> => {
       const text = sanitizeComposerInput(rawText).trim()
-      const sessionId = activeSessionId || activeSessionIdRef.current
+      // Ref, not the closure-captured prop — see cancelRun above. A redirect
+      // reaches the live model mid-turn, so a stale target delivers the user's
+      // correction into a conversation they are no longer looking at.
+      const sessionId = activeSessionIdRef.current
 
       if (!text || !sessionId) {
         return false
@@ -728,19 +736,16 @@ export function usePromptActions({
 
       return false
     },
-    [
-      activeSessionId,
-      activeSessionIdRef,
-      appendSessionTextMessage,
-      requestGateway,
-      selectedStoredSessionIdRef,
-      updateSessionState
-    ]
+    [activeSessionIdRef, appendSessionTextMessage, requestGateway, selectedStoredSessionIdRef, updateSessionState]
   )
 
   const reloadFromMessage = useCallback(
     async (parentId: string | null) => {
-      if (!activeSessionId || $busy.get()) {
+      // Ref, not the closure-captured prop — a truncating resubmit aimed at a
+      // stale session deletes the wrong transcript.
+      const sessionId = activeSessionIdRef.current
+
+      if (!sessionId || $busy.get()) {
         return
       }
 
@@ -751,16 +756,20 @@ export function usePromptActions({
       }
 
       clearNotifications()
-      updateSessionState(activeSessionId, state => applyReloadOptimistic(state, plan))
+      updateSessionState(sessionId, state => applyReloadOptimistic(state, plan))
 
       try {
         await requestGateway(
           'prompt.submit',
-          { session_id: activeSessionId, text: plan.text, truncate_before_user_ordinal: plan.truncateOrdinal },
+          {
+            session_id: sessionId,
+            text: plan.text,
+            ...truncateSubmitParams(plan.truncateOrdinal)
+          },
           PROMPT_SUBMIT_REQUEST_TIMEOUT_MS
         )
       } catch (err) {
-        updateSessionState(activeSessionId, state => ({
+        updateSessionState(sessionId, state => ({
           ...state,
           busy: false,
           awaitingResponse: false
@@ -768,7 +777,7 @@ export function usePromptActions({
         notifyError(err, copy.regenerateFailed)
       }
     },
-    [activeSessionId, copy.regenerateFailed, requestGateway, updateSessionState]
+    [activeSessionIdRef, copy.regenerateFailed, requestGateway, updateSessionState]
   )
 
   // Cursor-style "restore checkpoint": rewind the conversation to a past user
@@ -788,7 +797,9 @@ export function usePromptActions({
 
   const restoreToMessage = useCallback(
     async (messageId: string, target?: RestoreMessageTarget) => {
-      const sessionId = activeSessionId || activeSessionIdRef.current
+      // Ref, not the closure-captured prop — a rewind is destructive, so a
+      // stale target truncates a conversation the user did not ask to rewind.
+      const sessionId = activeSessionIdRef.current
 
       if (!sessionId) {
         throw new Error('No active session to restore.')
@@ -829,12 +840,14 @@ export function usePromptActions({
         throw err
       }
     },
-    [activeSessionId, activeSessionIdRef, busyRef, submitRewindPrompt, updateSessionState]
+    [activeSessionIdRef, busyRef, submitRewindPrompt, updateSessionState]
   )
 
   const editMessage = useCallback(
     async (edited: AppendMessage) => {
-      const sessionId = activeSessionId || activeSessionIdRef.current
+      // Ref, not the closure-captured prop — an edit rewinds and resubmits, so
+      // a stale target rewrites the wrong session's history.
+      const sessionId = activeSessionIdRef.current
       const messages = $messages.get()
       const plan = sessionId ? planEdit(messages, edited) : null
 
@@ -885,7 +898,7 @@ export function usePromptActions({
         notifyError(surfaced, copy.editFailed)
       }
     },
-    [activeSessionId, activeSessionIdRef, busyRef, copy.editFailed, submitRewindPrompt, updateSessionState]
+    [activeSessionIdRef, busyRef, copy.editFailed, submitRewindPrompt, updateSessionState]
   )
 
   const handleThreadMessagesChange = useCallback(
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/resolve-target-session.test.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/resolve-target-session.test.ts
new file mode 100644
index 00000000000..fe1b20d236d
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/resolve-target-session.test.ts
@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { resolveTargetSessionId } from './resolve-target-session'
+
+vi.mock('../use-session-actions/utils', () => ({
+  resolveSessionProfile: vi.fn(async () => 'work')
+}))
+
+const RECOVERED = 'rt-recovered'
+const STORED = 'stored-goal-session'
+
+function deps(overrides: Partial<Parameters<typeof resolveTargetSessionId>[0]> = {}) {
+  return {
+    activeRuntimeId: null,
+    createSession: vi.fn(async () => 'rt-brand-new'),
+    getRuntimeIdForStoredSession: () => null,
+    requestGateway: vi.fn(async () => ({ session_id: RECOVERED })) as never,
+    routedStoredSessionId: null,
+    selectedStoredSessionId: null,
+    ...overrides
+  }
+}
+
+describe('resolveTargetSessionId', () => {
+  it('resumes the routed stored session instead of minting a new one when the runtime binding is gone', async () => {
+    // The exact condition behind "/goal status says No active goal": the
+    // runtime binding was cleared (profile swap / reconnect / orphan-reap) but
+    // the durable route still names the chat carrying the goal.
+    const createSession = vi.fn(async () => 'rt-brand-new-WRONG')
+    const requestGateway = vi.fn(async () => ({ session_id: RECOVERED }))
+
+    const resolved = await resolveTargetSessionId(
+      deps({ createSession, requestGateway: requestGateway as never, routedStoredSessionId: STORED })
+    )
+
+    expect(resolved).toBe(RECOVERED)
+    expect(createSession).not.toHaveBeenCalled()
+    expect(requestGateway).toHaveBeenCalledWith('session.resume', {
+      session_id: STORED,
+      source: 'desktop',
+      profile: 'work'
+    })
+  })
+
+  it('reuses the live runtime id when the cache confirms it owns the targeted stored session', async () => {
+    const createSession = vi.fn(async () => 'rt-brand-new-WRONG')
+    const requestGateway = vi.fn(async () => ({ session_id: 'rt-resume-WRONG' }))
+
+    const resolved = await resolveTargetSessionId(
+      deps({
+        activeRuntimeId: RECOVERED,
+        createSession,
+        getRuntimeIdForStoredSession: () => RECOVERED,
+        requestGateway: requestGateway as never,
+        selectedStoredSessionId: STORED
+      })
+    )
+
+    expect(resolved).toBe(RECOVERED)
+    expect(createSession).not.toHaveBeenCalled()
+    expect(requestGateway).not.toHaveBeenCalled()
+  })
+
+  it('rejects a stale runtime id the route does not bind to the targeted session', async () => {
+    // A stale ref left over from the previous profile must not capture the
+    // command — that runs it against another profile's session. The durable
+    // route outranks the ref here.
+    const resolved = await resolveTargetSessionId(
+      deps({
+        activeRuntimeId: 'rt-wrong-profile',
+        getRuntimeIdForStoredSession: () => null,
+        routedStoredSessionId: STORED,
+        selectedStoredSessionId: STORED
+      })
+    )
+
+    expect(resolved).toBe(RECOVERED)
+  })
+
+  it('honors an explicit runtime id above everything else', async () => {
+    const createSession = vi.fn(async () => 'rt-brand-new-WRONG')
+    const requestGateway = vi.fn(async () => ({ session_id: 'rt-resume-WRONG' }))
+
+    const resolved = await resolveTargetSessionId(
+      deps({
+        createSession,
+        explicitRuntimeId: 'rt-explicit',
+        requestGateway: requestGateway as never,
+        routedStoredSessionId: STORED
+      })
+    )
+
+    expect(resolved).toBe('rt-explicit')
+    expect(createSession).not.toHaveBeenCalled()
+    expect(requestGateway).not.toHaveBeenCalled()
+  })
+
+  it('creates a session only for a genuine new-chat draft', async () => {
+    const createSession = vi.fn(async () => 'rt-brand-new')
+
+    const resolved = await resolveTargetSessionId(deps({ createSession }))
+
+    expect(resolved).toBe('rt-brand-new')
+    expect(createSession).toHaveBeenCalledTimes(1)
+  })
+
+  it('reuses the live runtime for a new-chat draft without creating a second session', async () => {
+    const createSession = vi.fn(async () => 'rt-brand-new-WRONG')
+
+    const resolved = await resolveTargetSessionId(deps({ activeRuntimeId: 'rt-live', createSession }))
+
+    expect(resolved).toBe('rt-live')
+    expect(createSession).not.toHaveBeenCalled()
+  })
+
+  it('returns null rather than forking when a targeted durable session cannot be rebound', async () => {
+    const createSession = vi.fn(async () => 'rt-brand-new-WRONG')
+
+    const requestGateway = vi.fn(async () => {
+      throw new Error('4007 session not found')
+    })
+
+    const resolved = await resolveTargetSessionId(
+      deps({ createSession, requestGateway: requestGateway as never, routedStoredSessionId: STORED })
+    )
+
+    expect(resolved).toBeNull()
+    expect(createSession).not.toHaveBeenCalled()
+  })
+
+  it('prefers the routed stored session over a differing selected one', async () => {
+    const requestGateway = vi.fn(async () => ({ session_id: RECOVERED }))
+
+    await resolveTargetSessionId(
+      deps({
+        requestGateway: requestGateway as never,
+        routedStoredSessionId: STORED,
+        selectedStoredSessionId: 'stored-stale-selection'
+      })
+    )
+
+    expect(requestGateway).toHaveBeenCalledWith('session.resume', expect.objectContaining({ session_id: STORED }))
+  })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/resolve-target-session.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/resolve-target-session.ts
new file mode 100644
index 00000000000..93dc4f4484f
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/resolve-target-session.ts
@@ -0,0 +1,111 @@
+import { resolveSessionProfile } from '../use-session-actions/utils'
+
+import type { GatewayRequest } from './utils'
+
+/**
+ * Resolve the runtime session a submit or slash command must target.
+ *
+ * Both prompt pipelines need this answer and they must agree: `submit.ts`
+ * sends the user's text into it, and `slash.ts` runs backend commands against
+ * it. Per-session backend state — `/goal` (persisted in SessionDB `state_meta`
+ * under `goal:<session_id>`), usage, status, yolo — is keyed by that id, so a
+ * pipeline that resolves it differently reads and writes a DIFFERENT session's
+ * state than the one the user is looking at.
+ *
+ * That is the bug this exists to prevent. `slash.ts` used to resolve with a
+ * bare `hint || activeRef || createSession()`, so whenever the runtime binding
+ * was momentarily absent — profile swap, reconnect, orphan-reap, request
+ * timeout — a slash command silently MINTED A NEW SESSION and ran against it.
+ * `/goal <text>` then set a goal on the chat, and a following `/goal status`
+ * reported "No active goal" because it was asking a session that had just been
+ * created. Same hole for every exec/rpc command (`/usage`, `/status`,
+ * `/tools`, …), not just `/goal`.
+ *
+ * The ladder (highest-trust rung first), mirroring `submit.ts`:
+ *
+ *   1. An explicit runtime id from the caller (queue drain / tile) — always
+ *      authoritative.
+ *   2. The live runtime ref. A durable ROUTE outranks it: when the URL names a
+ *      conversation whose runtime binding the cache does not confirm, the ref
+ *      is stale or cross-wired (often from the previous profile) and must not
+ *      capture the command. With no route in play the ref is authoritative.
+ *   3. `session.resume` on the routed (else selected) stored session,
+ *      re-registered on the profile that OWNS it — never whichever profile
+ *      happens to be live, which forks the conversation into the wrong
+ *      state.db (#67603).
+ *   4. Only a genuine new-chat draft — no durable session in play at all —
+ *      creates a session.
+ *
+ * Returns null when a durable conversation was targeted but its runtime could
+ * not be rebound. Callers surface that instead of silently retargeting: a
+ * command that runs against the wrong session is worse than one that reports
+ * it could not run.
+ */
+export interface ResolveTargetSessionDeps {
+  activeRuntimeId: null | string
+  createSession: () => Promise<null | string>
+  explicitRuntimeId?: null | string
+  getRuntimeIdForStoredSession: (storedSessionId: string) => null | string
+  requestGateway: GatewayRequest
+  routedStoredSessionId: null | string
+  selectedStoredSessionId: null | string
+}
+
+export async function resolveTargetSessionId(deps: ResolveTargetSessionDeps): Promise<null | string> {
+  const {
+    activeRuntimeId,
+    createSession,
+    explicitRuntimeId,
+    getRuntimeIdForStoredSession,
+    requestGateway,
+    routedStoredSessionId,
+    selectedStoredSessionId
+  } = deps
+
+  // 1. An explicit target always wins — the caller knows which session it means.
+  if (explicitRuntimeId) {
+    return explicitRuntimeId
+  }
+
+  // A route whose runtime binding is incomplete or cross-wired outranks the
+  // live ref: a profile swap / reconnect can leave the previous profile's
+  // runtime active while the URL still names the conversation on screen.
+  // Matches submit.ts's `routedSessionNeedsResume`.
+  const routedNeedsResume = Boolean(
+    routedStoredSessionId &&
+    (selectedStoredSessionId !== routedStoredSessionId ||
+      !activeRuntimeId ||
+      activeRuntimeId !== getRuntimeIdForStoredSession(routedStoredSessionId))
+  )
+
+  // 2. Trust the live runtime unless the durable route disagrees with it.
+  if (activeRuntimeId && !routedNeedsResume) {
+    return activeRuntimeId
+  }
+
+  // 3. Rebind the durable conversation on its owning profile. The route wins
+  //    over a stale selection; otherwise continue whatever is selected.
+  const storedTarget = routedNeedsResume ? routedStoredSessionId : (selectedStoredSessionId ?? routedStoredSessionId)
+
+  if (storedTarget) {
+    try {
+      const profile = await resolveSessionProfile(storedTarget)
+
+      const resumed = await requestGateway<{ session_id?: string }>('session.resume', {
+        session_id: storedTarget,
+        source: 'desktop',
+        ...(profile ? { profile } : {})
+      })
+
+      return resumed?.session_id || null
+    } catch {
+      // A targeted durable conversation whose runtime cannot be rebound must
+      // NOT fall through to createSession() — that is precisely the fork this
+      // resolver exists to prevent (#55578 class).
+      return null
+    }
+  }
+
+  // 4. A genuine new-chat draft: nothing durable is in play.
+  return activeRuntimeId || (await createSession())
+}
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.test.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.test.ts
new file mode 100644
index 00000000000..23d9c979815
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+
+import { truncateSubmitParams } from './rewind'
+
+describe('truncateSubmitParams', () => {
+  it('omits truncation fields when no ordinal is set', () => {
+    expect(truncateSubmitParams(undefined)).toEqual({})
+  })
+
+  it('requires confirm_empty_truncate only for ordinal 0', () => {
+    expect(truncateSubmitParams(0)).toEqual({
+      truncate_before_user_ordinal: 0,
+      confirm_empty_truncate: true
+    })
+    expect(truncateSubmitParams(1)).toEqual({
+      truncate_before_user_ordinal: 1
+    })
+  })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.ts
index 3f511f004eb..32dc25c1ebf 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.ts
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.ts
@@ -25,6 +25,23 @@ import {
 
 type RequestGateway = <T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number) => Promise<T>
 
+/**
+ * Build `prompt.submit` truncation params. Ordinal 0 truncates to an empty
+ * transcript (restore/regenerate the first user turn) — the gateway refuses
+ * that edge unless `confirm_empty_truncate` is set, so stale clients cannot
+ * silently wipe a session via a leftover ordinal.
+ */
+export function truncateSubmitParams(truncateOrdinal: number | undefined): Record<string, unknown> {
+  if (truncateOrdinal === undefined) {
+    return {}
+  }
+
+  return {
+    truncate_before_user_ordinal: truncateOrdinal,
+    ...(truncateOrdinal === 0 ? { confirm_empty_truncate: true } : {})
+  }
+}
+
 /**
  * Rewind a turn: `prompt.submit` with an optional `truncate_before_user_ordinal`
  * (drops that user turn + everything after). Idle rewinds submit directly
@@ -53,7 +70,7 @@ export async function runRewindSubmit(
       {
         session_id: sessionId,
         text,
-        ...(truncateOrdinal !== undefined && { truncate_before_user_ordinal: truncateOrdinal })
+        ...truncateSubmitParams(truncateOrdinal)
       },
       PROMPT_SUBMIT_REQUEST_TIMEOUT_MS
     )
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/slash.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/slash.ts
index 0edbea218b2..f8f044ec028 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions/slash.ts
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/slash.ts
@@ -17,6 +17,7 @@ import { isMissingRpcMethod } from '@/lib/gateway-rpc'
 import { setSessionYolo } from '@/lib/yolo-session'
 import { openCommandPalettePage } from '@/store/command-palette'
 import { setComposerDraft } from '@/store/composer'
+import { enqueueQueuedPrompt } from '@/store/composer-queue'
 import { dismissNotification, notify, notifyError } from '@/store/notifications'
 import { setPetScale } from '@/store/pet-gallery'
 import { $petGenInput, openPetGenerate } from '@/store/pet-generate'
@@ -25,12 +26,14 @@ import {
   $connection,
   $sessions,
   $yoloActive,
+  resolveComposerSessionKey,
   setCurrentUsage,
   setModelPickerOpen,
   setSessionPickerOpen,
   setSessions,
   setYoloActive
 } from '@/store/session'
+import { $sessionStates } from '@/store/session-states'
 
 import type {
   BrowserManageResponse,
@@ -40,9 +43,11 @@ import type {
   SlashExecResponse
 } from '../../../types'
 
+import { resolveTargetSessionId } from './resolve-target-session'
 import {
   type GatewayRequest,
   isSessionIdCandidate,
+  isTargetSessionBusy,
   renderCommandsCatalog,
   renderRpcResult,
   slashStatusText,
@@ -75,6 +80,8 @@ interface SlashCommandDeps {
   busyRef: MutableRefObject<boolean>
   copy: Translations['desktop']
   createBackendSessionForSend: (preview?: string | null) => Promise<string | null>
+  getRoutedStoredSessionId: () => null | string
+  getRuntimeIdForStoredSession: (storedSessionId: string) => null | string
   handleSkinCommand: (arg: string) => string
   handoffSession: (
     platform: string,
@@ -103,6 +110,8 @@ export function useSlashCommand(deps: SlashCommandDeps) {
     busyRef,
     copy,
     createBackendSessionForSend,
+    getRoutedStoredSessionId,
+    getRuntimeIdForStoredSession,
     handleSkinCommand,
     handoffSession,
     openMemoryGraph,
@@ -119,8 +128,25 @@ export function useSlashCommand(deps: SlashCommandDeps) {
 
   return useCallback(
     async (rawCommand: string, options?: { sessionId?: string; recordInput?: boolean }) => {
-      const ensureSessionId = async (sessionHint?: string) =>
-        sessionHint || activeSessionIdRef.current || (await createBackendSessionForSend())
+      // Resolve the session this command targets through the SHARED ladder that
+      // submit.ts uses. A slash command runs backend commands against a runtime
+      // session, and per-session state (`/goal`, `/usage`, `/status`) is keyed by
+      // that id — so resolving it differently than submit would run the command
+      // against a different session than the user's chat. The old bare
+      // `hint || activeRef || createSession()` did exactly that: with the runtime
+      // binding momentarily absent (profile swap, reconnect, orphan-reap,
+      // timeout) it minted a NEW session, so `/goal status` reported "No active
+      // goal" for a goal that was live on the real chat.
+      const ensureSessionId = async (sessionHint?: string, preview?: null | string) =>
+        resolveTargetSessionId({
+          activeRuntimeId: activeSessionIdRef.current,
+          createSession: () => createBackendSessionForSend(preview),
+          explicitRuntimeId: sessionHint,
+          getRuntimeIdForStoredSession,
+          requestGateway,
+          routedStoredSessionId: getRoutedStoredSessionId(),
+          selectedStoredSessionId: selectedStoredSessionIdRef.current
+        })
 
       // Resolve the target session plus a writer for inline slash output, or
       // notify + return null when none can be created. Folds the ensure / bail /
@@ -128,7 +154,11 @@ export function useSlashCommand(deps: SlashCommandDeps) {
       const withSlashOutput = async (
         ctx: SlashActionCtx
       ): Promise<{ render: (text: string) => void; sessionId: string; storedSessionId: string | null } | null> => {
-        const sessionId = await ensureSessionId(ctx.sessionHint)
+        // A slash on a fresh draft creates the backend session; seed the
+        // sidebar preview with the typed command so the row doesn't sit as
+        // "Untitled session" (auto-title only fires after a full exchange,
+        // which a bare exec command never produces).
+        const sessionId = await ensureSessionId(ctx.sessionHint, ctx.command)
 
         if (!sessionId) {
           notify({ kind: 'error', title: copy.sessionUnavailable, message: copy.createSessionFailed })
@@ -136,15 +166,24 @@ export function useSlashCommand(deps: SlashCommandDeps) {
           return null
         }
 
-        // A long-running command can finish after a session switch. Keep its
-        // output bound to the stored session selected at invocation time.
-        const storedSessionId = selectedStoredSessionIdRef.current
+        // Bind output to the TARGET session's own stored id, snapshotted now so
+        // a command that outlives a session switch still lands on the right
+        // chat. NOT the foreground selection: a tile (⌘T tab, split) runs its
+        // slash commands through this hook with an explicit runtime id while
+        // the selection names a different conversation, and passing that down
+        // to updateSessionState re-keyed the tile's cache entry onto the
+        // primary's stored session. Fall back to the selection only for a
+        // session with no published state yet (a draft this call just created).
+        const storedSessionId = $sessionStates.get()[sessionId]?.storedSessionId ?? selectedStoredSessionIdRef.current
 
+        // Header carries the command token only. The full invocation would
+        // duplicate long args — `/goal <prose>` echoed the whole goal in the
+        // mono header, then again in the backend notice right under it.
         const render = (text: string) =>
           appendSessionTextMessage(
             sessionId,
             'system',
-            ctx.recordInput ? slashStatusText(ctx.command, text) : text,
+            ctx.recordInput ? slashStatusText(`/${ctx.name}`, text) : text,
             storedSessionId
           )
 
@@ -162,7 +201,7 @@ export function useSlashCommand(deps: SlashCommandDeps) {
           return
         }
 
-        const { render: renderSlashOutput, sessionId } = resolved
+        const { render: renderSlashOutput, sessionId, storedSessionId } = resolved
 
         if (!isDesktopSlashCommand(name)) {
           renderSlashOutput(desktopSlashUnavailableMessage(name) || `/${name} is not available in the desktop app.`)
@@ -219,13 +258,43 @@ export function useSlashCommand(deps: SlashCommandDeps) {
             renderSlashOutput(`⚡ loading skill: ${dispatch.name}`)
           }
 
-          if (busyRef.current) {
-            renderSlashOutput('session busy — /interrupt the current turn before sending this command')
+          // Gate on the TARGET session's own busy state, not the foreground
+          // view's — see isTargetSessionBusy. `busyRef` mirrors whatever chat
+          // is on screen, while this command runs against the session
+          // resolveTargetSessionId picked, routinely a different one.
+          if (isTargetSessionBusy($sessionStates.get(), sessionId, busyRef.current)) {
+            // The backend already executed the command — for `/goal <text>`
+            // the goal is set and `message` is its kickoff prompt. Dropping
+            // it here loses the kickoff silently (the goal exists but the
+            // agent never hears about it, #63352). Queue it on the composer
+            // queue instead: it fires when the running turn settles, and the
+            // queue panel above the composer shows it in the meantime.
+            //
+            // Park it on the same stored session the output writer is bound to
+            // rather than re-reading the globals here — a session switch between
+            // dispatch and this branch would otherwise queue the kickoff on
+            // whichever chat is now in front.
+            const queueKey = resolveComposerSessionKey(storedSessionId, $sessions.get()) || storedSessionId || sessionId
+
+            if (enqueueQueuedPrompt(queueKey, { attachments: [], text: message })) {
+              renderSlashOutput('session busy — message queued to send when the current turn finishes')
+            } else {
+              renderSlashOutput('session busy — /interrupt the current turn before sending this command')
+            }
 
             return
           }
 
-          await submitPromptText(message)
+          // Submit into the session this command was resolved against — the
+          // same pair the output writer and the busy gate above already use.
+          // Bare `submitPromptText(message)` let submit re-resolve from
+          // `activeSessionIdRef`, which names the FOREGROUND chat: a `/work`
+          // typed into a fresh ⌘T tab loaded the skill in that tab, printed
+          // "⚡ loading skill" there, then fired its kickoff as a user message
+          // into whatever conversation was on screen. Every other target the
+          // dispatcher serves (tile, background queue drain, a session created
+          // by this very call) had the same leak.
+          await submitPromptText(message, { sessionId, storedSessionId })
         }
 
         try {
@@ -868,6 +937,8 @@ export function useSlashCommand(deps: SlashCommandDeps) {
       busyRef,
       copy,
       createBackendSessionForSend,
+      getRoutedStoredSessionId,
+      getRuntimeIdForStoredSession,
       handleSkinCommand,
       handoffSession,
       openMemoryGraph,
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/submit.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/submit.ts
index 398a72f3be4..e7cc0d43991 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions/submit.ts
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/submit.ts
@@ -20,7 +20,8 @@ import {
 } from '@/store/composer'
 import { clearNotifications, notify, notifyError } from '@/store/notifications'
 import { requestDesktopOnboarding } from '@/store/onboarding'
-import { setAwaitingResponse, setBusy, setMessages } from '@/store/session'
+import { $sessions, resolveComposerSessionKey, setAwaitingResponse, setBusy, setMessages } from '@/store/session'
+import { $sessionStates } from '@/store/session-states'
 
 import type { ClientSessionState } from '../../../types'
 import { sessionContextDrift } from '../session-context-drift'
@@ -34,6 +35,7 @@ import {
   isProviderSetupError,
   isSessionBusyError,
   isSessionNotFoundError,
+  isTargetSessionBusy,
   type SubmitTextOptions,
   withSessionBusyRetry
 } from './utils'
@@ -143,9 +145,19 @@ export function useSubmitPrompt(deps: SubmitPromptDeps) {
       // from $busy by a separate effect) may still read true — honoring it would
       // bounce the drained send. The drain lock serializes them; the user path
       // keeps the guard so a stray Enter mid-turn can't double-submit.
+      //
+      // The guard reads the TARGET session's busy state (isTargetSessionBusy),
+      // not the foreground flag: an explicit target (tile, queue drain) is
+      // frequently not the session on screen, so the foreground flag would gate
+      // one session's send on another session's turn.
       const hasSendable = Boolean(visibleText || terminalContextBlocks || attachments.length || hasImage)
 
-      if (!hasSendable || (!options?.fromQueue && busyRef.current)) {
+      const guardSessionId = options?.sessionId ?? activeSessionIdRef.current
+
+      if (
+        !hasSendable ||
+        (!options?.fromQueue && isTargetSessionBusy($sessionStates.get(), guardSessionId, busyRef.current))
+      ) {
         return false
       }
 
@@ -167,7 +179,17 @@ export function useSubmitPrompt(deps: SubmitPromptDeps) {
       const targetStartedInCurrentView =
         !targetStoredSessionId || targetStoredSessionId === selectedStoredSessionIdRef.current
 
-      let sessionId: null | string = options?.sessionId ?? activeSessionIdRef.current
+      // A queued/background drain whose runtime binding was reaped must NOT
+      // inherit the foreground runtime id when its storedSessionId targets a
+      // different session — that would land the queued prompt in whichever
+      // session the user happens to be viewing (cross-session leak). When the
+      // drain is for the current view (no storedSessionId, or it matches the
+      // foreground), the foreground runtime is correct and must be kept.
+      const isBackgroundQueueDrain = Boolean(
+        options?.fromQueue && options?.storedSessionId && options.storedSessionId !== selectedStoredSessionIdRef.current
+      )
+
+      let sessionId: null | string = options?.sessionId ?? (isBackgroundQueueDrain ? null : activeSessionIdRef.current)
 
       // Pin the foreground session context for the whole async submit pipeline.
       // Without this, a fast session switch during session.resume / file.attach
@@ -210,7 +232,15 @@ export function useSubmitPrompt(deps: SubmitPromptDeps) {
               nowRouteToken: getRouteToken(),
               startSelectedStoredId: startingStoredSessionId,
               nowSelectedStoredId: selectedStoredSessionIdRef.current,
-              submitTargetStoredId: startingStoredSessionId
+              submitTargetStoredId: startingStoredSessionId,
+              composerScope: options?.composerScope,
+              // The composer keys drafts/attachments on the durable lineage
+              // root (survives auto-compression tip rotation), while
+              // startingStoredSessionId is the live tip — resolve the target
+              // into the same lineage-root domain before comparing, or every
+              // submit into a session that has ever compressed would
+              // false-positive-abort.
+              submitTargetComposerScope: resolveComposerSessionKey(startingStoredSessionId, $sessions.get())
             })
           : null
 
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/utils.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/utils.ts
index 42598fb5462..b193b1aebf1 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions/utils.ts
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/utils.ts
@@ -52,6 +52,32 @@ export function isSessionNotFoundError(error: unknown): boolean {
   return /session not found/i.test(message)
 }
 
+/**
+ * Is the session a prompt is about to run against currently mid-turn?
+ *
+ * The foreground `busyRef` is NOT the answer. It mirrors whatever chat is on
+ * screen, while submit and slash both resolve their target through
+ * `resolveTargetSessionId` — routinely a different session (a tile, a route
+ * rebind, a session created by this very call). Reading the foreground flag
+ * therefore gates one session's send on another session's turn: a stale
+ * foreground `true` (a warm resume of a still-running chat leaves one behind)
+ * blocks an IDLE target and reports "session busy" about a session doing
+ * nothing, and the converse lets a background send fire mid-turn.
+ *
+ * The published per-session state is authoritative. Fall back to the
+ * foreground flag only when the target has no state yet — a just-minted
+ * session whose first publish hasn't landed.
+ */
+export function isTargetSessionBusy(
+  sessionStates: Record<string, { busy: boolean }>,
+  sessionId: null | string,
+  foregroundBusy: boolean
+): boolean {
+  const state = sessionId ? sessionStates[sessionId] : undefined
+
+  return state ? state.busy : foregroundBusy
+}
+
 // Gateway JSON-RPC calls reject with "request timed out: <method>" when the
 // backend event loop is starved (e.g. a poller spin or a heavy async-injected
 // turn). For prompt.submit this is indistinguishable from a dead runtime
@@ -359,6 +385,14 @@ export function visibleUserIndexAtOrdinal(messages: readonly ChatMessage[], targ
 
 export interface SubmitTextOptions {
   attachments?: ComposerAttachment[]
+  /** The composer scope key that was actually loaded when this text was
+   *  submitted (see use-composer-draft's activeQueueSessionKeyRef). Compared
+   *  against the resolved submit target in sessionContextDrift — a mismatch
+   *  means the composer and the session-side refs disagreed about which
+   *  session this send belongs to (#59305). Omit for non-composer submits
+   *  (queue drain, steer, external submit requests): the check is a no-op
+   *  without it. */
+  composerScope?: string | null
   fromQueue?: boolean
   /** Runtime session id to submit into. Queue drains pass this so a
    *  backgrounded/source session cannot be replaced by the current foreground
diff --git a/apps/desktop/src/app/session/hooks/use-route-resume.ts b/apps/desktop/src/app/session/hooks/use-route-resume.ts
index 588f614a533..ed12a91da42 100644
--- a/apps/desktop/src/app/session/hooks/use-route-resume.ts
+++ b/apps/desktop/src/app/session/hooks/use-route-resume.ts
@@ -96,6 +96,7 @@ export function useRouteResume({
   // never touches this latch, so it can't spuriously trigger the reset).
   const prevResumeExhaustedRef = useRef<string | null>(null)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const gatewayOpen = gatewayState === 'open'
     const pathnameChanged = lastPathnameRef.current !== locationPathname
@@ -187,6 +188,7 @@ export function useRouteResume({
   // again. resumeSession clears resumeFailedSessionId on its next attempt; a
   // success keeps it clear (the effect's guard then no-ops), a repeat failure
   // re-arms it and we back off further, capped at MAX_RESUME_RETRIES.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     // Detect the exhausted-latch armed->cleared edge for the current route. Only
     // resumeSession clears $resumeExhaustedSessionId (manual Retry / reconnect /
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions.test.tsx b/apps/desktop/src/app/session/hooks/use-session-actions.test.tsx
index 7648c01a403..603b45a1a2b 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-session-actions.test.tsx
@@ -1102,8 +1102,12 @@ describe('branchStoredSession desktop source tagging', () => {
       session_id: 'stored-parent'
     } as never)
 
-    const requestGateway = vi.fn(async (method: string) => {
+    let createParams: Record<string, unknown> | undefined
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
       if (method === 'session.create') {
+        createParams = params
+
         return { session_id: 'branch-runtime', stored_session_id: 'branch-stored' } as never
       }
 
@@ -1120,9 +1124,71 @@ describe('branchStoredSession desktop source tagging', () => {
 
     expect(ensureGatewayProfile).toHaveBeenCalledWith('work')
     expect(getSessionMessages).toHaveBeenCalledWith('stored-parent', 'work')
+    // The create itself must carry the owning profile: in app-global remote
+    // mode the soft gateway swap alone is not enough — an omitted profile
+    // lands the branch on the launch (default) profile's state.db.
+    expect(createParams).toMatchObject({ parent_session_id: 'stored-parent', profile: 'work' })
 
     vi.mocked(getSession).mockReset()
   })
+
+  it('creates the branch on the cached parent session profile', async () => {
+    setSessions([storedSession({ id: 'stored-parent', message_count: 1, profile: 'work' })])
+    vi.mocked(getSessionMessages).mockResolvedValue({
+      messages: [{ content: 'branch me', role: 'user', timestamp: 1 }],
+      session_id: 'stored-parent'
+    } as never)
+
+    let createParams: Record<string, unknown> | undefined
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      if (method === 'session.create') {
+        createParams = params
+
+        return { session_id: 'branch-runtime', stored_session_id: 'branch-stored' } as never
+      }
+
+      return {} as never
+    })
+
+    let branchStoredSession: ((storedSessionId: string) => Promise<boolean>) | null = null
+    render(<BranchHarness onReady={branch => (branchStoredSession = branch)} requestGateway={requestGateway} />)
+    await waitFor(() => expect(branchStoredSession).not.toBeNull())
+
+    await expect(branchStoredSession!('stored-parent')).resolves.toBe(true)
+
+    expect(ensureGatewayProfile).toHaveBeenCalledWith('work')
+    expect(createParams).toMatchObject({ profile: 'work' })
+  })
+
+  it('omits profile for a profile-less parent so single-profile users are unchanged', async () => {
+    setSessions([storedSession({ id: 'stored-parent', message_count: 1 })])
+    vi.mocked(getSessionMessages).mockResolvedValue({
+      messages: [{ content: 'branch me', role: 'user', timestamp: 1 }],
+      session_id: 'stored-parent'
+    } as never)
+
+    let createParams: Record<string, unknown> | undefined
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      if (method === 'session.create') {
+        createParams = params
+
+        return { session_id: 'branch-runtime', stored_session_id: 'branch-stored' } as never
+      }
+
+      return {} as never
+    })
+
+    let branchStoredSession: ((storedSessionId: string) => Promise<boolean>) | null = null
+    render(<BranchHarness onReady={branch => (branchStoredSession = branch)} requestGateway={requestGateway} />)
+    await waitFor(() => expect(branchStoredSession).not.toBeNull())
+
+    await expect(branchStoredSession!('stored-parent')).resolves.toBe(true)
+
+    expect(createParams).toBeDefined()
+    expect(createParams).not.toHaveProperty('profile')
+  })
 })
 
 // ── Warm-cache mapping integrity (the "open chat A, chat B loads" bug) ─────────
@@ -1241,6 +1307,76 @@ describe('resumeSession warm-cache mapping integrity', () => {
     expect(runtimeIdByStoredSessionIdRef.current.get('stored-A')).toBe('rt-A')
   })
 
+  it('preserves cached image attachments through an idle persisted transcript refresh', async () => {
+    const runtimeIdByStoredSessionIdRef: MutableRefObject<Map<string, string>> = {
+      current: new Map([['stored-A', 'rt-A']])
+    }
+
+    const state = clientState('stored-A')
+    state.messages = [
+      {
+        id: 'cached-user',
+        role: 'user',
+        parts: [{ type: 'text', text: 'describe this image' }],
+        attachmentRefs: ['@image:/tmp/photo.png']
+      },
+      {
+        id: 'cached-assistant',
+        role: 'assistant',
+        parts: [{ type: 'text', text: 'It is a photo.' }]
+      }
+    ]
+
+    const sessionStateByRuntimeIdRef: MutableRefObject<Map<string, ClientSessionState>> = {
+      current: new Map([['rt-A', state]])
+    }
+
+    const persistedMessages = [
+      { content: 'describe this image', role: 'user', timestamp: 1 },
+      { content: 'It is a photo.', role: 'assistant', timestamp: 2 }
+    ]
+
+    vi.mocked(getSessionMessages).mockResolvedValue({
+      messages: persistedMessages,
+      session_id: 'stored-A'
+    } as never)
+
+    const requestGateway = vi.fn(async (method: string) => {
+      if (method === 'session.activate') {
+        return {
+          session_id: 'rt-A',
+          session_key: 'stored-A',
+          resumed: 'stored-A',
+          message_count: persistedMessages.length,
+          messages: persistedMessages,
+          running: false,
+          info: {}
+        } as never
+      }
+
+      return {} as never
+    })
+
+    let resumedState: ClientSessionState | undefined
+    let resume: ((storedSessionId: string, replaceRoute?: boolean) => Promise<unknown>) | null = null
+
+    render(
+      <ResumeHarness
+        onReady={ready => (resume = ready)}
+        onStateUpdate={(_sessionId, next) => (resumedState = next)}
+        requestGateway={requestGateway}
+        runtimeIdByStoredSessionIdRef={runtimeIdByStoredSessionIdRef}
+        sessionStateByRuntimeIdRef={sessionStateByRuntimeIdRef}
+      />
+    )
+    await waitFor(() => expect(resume).not.toBeNull())
+    await resume!('stored-A', true)
+
+    expect(requestGateway.mock.calls.map(([method]) => method)).toContain('session.activate')
+    expect(getSessionMessages).toHaveBeenCalledWith('stored-A', undefined)
+    expect(resumedState?.messages[0]?.attachmentRefs).toEqual(['@image:/tmp/photo.png'])
+  })
+
   it('repairs an idle warm cache from a divergent equal-length persisted transcript', async () => {
     const runtimeIdByStoredSessionIdRef: MutableRefObject<Map<string, string>> = {
       current: new Map([['stored-A', 'rt-A']])
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 a4ac8ec4ad7..b0202e722a4 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
@@ -7,6 +7,7 @@ import { deleteSession, getSessionMessages, setSessionArchived } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { type ChatMessage, preserveLocalAssistantErrors, toChatMessages } from '@/lib/chat-messages'
 import { isMissingRpcMethod } from '@/lib/gateway-rpc'
+import { recoverInFlightTurnJournal } from '@/lib/inflight-turn-journal'
 import { setSessionYolo } from '@/lib/yolo-session'
 import { migrateSessionDraft } from '@/store/composer'
 import { clearQueuedPrompts, migrateQueuedPrompts } from '@/store/composer-queue'
@@ -82,6 +83,7 @@ import {
   patchSessionWorkspace,
   preserveLocalPendingTurnMessages,
   reconcileResumeMessages,
+  resolveSessionProfile,
   resolveStoredSession,
   sessionMatchesStoredId,
   sessionShouldHaveTranscript,
@@ -223,6 +225,7 @@ export function useSessionActions({
   // by A's delayed session.info event and visibly jump back to A.
   const storedIdRotation = useStore($activeSessionStoredIdRotation)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!storedIdRotation) {
       return
@@ -473,13 +476,14 @@ export function useSessionActions({
    *  list (Cursor-style draft tab); it surfaces on the next refresh once the
    *  first message persists a turn. "Open in split" keeps the listed behavior. */
   const openNewSessionTile = useCallback(
-    async (dir: TileDock = 'right', options?: { listed?: boolean }) => {
+    async (dir: TileDock = 'right', options?: { cwd?: null | string; listed?: boolean }) => {
       const listed = options?.listed ?? true
 
       try {
-        // Fresh tile → the resolved new-session cwd (project/default), not the
-        // primary composer's live cwd.
-        const params = await desktopSessionCreateParams(resolveNewSessionCwd().trim())
+        // Fresh tile → the caller's workspace when one was named (the sidebar
+        // "+" on a project/worktree lane), else the resolved new-session cwd
+        // (project/default) — never the primary composer's live cwd.
+        const params = await desktopSessionCreateParams((options?.cwd || resolveNewSessionCwd()).trim())
         const created = await requestGateway<SessionCreateResponse>('session.create', params)
         const stored = created.stored_session_id
 
@@ -820,6 +824,10 @@ export function useSessionActions({
       }
 
       let resumedRunning = false
+      // A recovered in-flight tail means the turn already produced output, so
+      // it resumes into the streaming state rather than the "awaiting first
+      // token" spinner.
+      let recoveredInFlightTail = false
 
       try {
         const watchWindow = isWatchWindow()
@@ -911,15 +919,36 @@ export function useSessionActions({
                 return chatMessageArraysEquivalent(currentMessages, resumedMessages) ? currentMessages : resumedMessages
               })()
 
+        resumedRunning = Boolean((resumed as { running?: boolean }).running)
+
+        // Crash-survivable turn progress: fold a journaled in-flight tail
+        // (persisted by use-session-state-cache while the turn streamed;
+        // survives renderer/app death) back onto the restored transcript. The
+        // backend's own inflight projection is already inside
+        // `preferredMessages` (appendLiveSessionProjection), so this merge only
+        // adds the locally recorded structure — tool calls, sealed interim
+        // rows — that the backend's text-only snapshot cannot carry. A no-op
+        // returns `preferredMessages` by reference, keeping the fast path
+        // below intact.
+        const inFlightRecovery = recoverInFlightTurnJournal(storedSessionId, preferredMessages, {
+          keepPending: resumedRunning
+        })
+
+        recoveredInFlightTail = inFlightRecovery.applied
+
         // Prefetch-hit fast path: `preferredMessages` IS the live `$messages`
         // array (already error-merged when `localSnapshot` was built), so reuse
         // the ref instead of rebuilding a throwaway transcript+Map every switch.
         const messagesForView =
-          preferredMessages === currentMessages
+          inFlightRecovery.messages === currentMessages
             ? currentMessages
-            : preserveLocalAssistantErrors(preferredMessages, currentMessages)
+            : preserveLocalAssistantErrors(inFlightRecovery.messages, currentMessages)
 
-        if (sessionShouldHaveTranscript(stored) && messagesForView.length === 0) {
+        // Fail-latch on the PRE-recovery transcript: an orphan journal tail
+        // must not mask a lost transcript (a retry that reloads real history
+        // is safer than surfacing the in-flight turn alone). Recovery only
+        // ever appends, so this matches the final transcript's emptiness.
+        if (sessionShouldHaveTranscript(stored) && preferredMessages.length === 0) {
           setActiveSessionId(null)
           activeSessionIdRef.current = null
           setResumeFailedSessionId(storedSessionId)
@@ -934,8 +963,6 @@ export function useSessionActions({
 
         patchSessionWorkspace(storedSessionId, runtimeInfo?.cwd)
 
-        resumedRunning = Boolean((resumed as { running?: boolean }).running)
-
         updateSessionState(
           resumed.session_id,
           state => ({
@@ -943,7 +970,18 @@ export function useSessionActions({
             ...(runtimeInfo ?? {}),
             messages: messagesForView,
             busy: resumedRunning,
-            awaitingResponse: resumedRunning
+            awaitingResponse: resumedRunning && !recoveredInFlightTail,
+            ...(inFlightRecovery.applied
+              ? {
+                  sawAssistantPayload: true,
+                  // Point live deltas at the recovered row when the backend is
+                  // still mid-turn; a settled recovery keeps the stream idle.
+                  streamId: resumedRunning ? inFlightRecovery.streamId : null,
+                  turnStartedAt: resumedRunning
+                    ? (inFlightRecovery.turnStartedAt ?? state.turnStartedAt ?? Date.now())
+                    : state.turnStartedAt
+                }
+              : {})
           }),
           storedSessionId
         )
@@ -981,7 +1019,14 @@ export function useSessionActions({
             ? preserveLocalPendingTurnMessages($messages.get(), resumeStartMessages)
             : $messages.get()
 
-          setMessages(reconcileAuthoritativeMessages(fallback.messages, previousMessages))
+          // Resume failed, so there is no live projection — the journal is the
+          // only carrier of a crashed turn's progress on this path.
+          const fallbackRecovery = recoverInFlightTurnJournal(
+            storedSessionId,
+            reconcileAuthoritativeMessages(fallback.messages, previousMessages)
+          )
+
+          setMessages(fallbackRecovery.messages)
         } catch (e) {
           // Fallback also failed: nothing to paint. Leave whatever messages are
           // already shown and fall through to arm the resume-failure latch so
@@ -1033,7 +1078,7 @@ export function useSessionActions({
         if (isCurrentResume()) {
           busyRef.current = resumedRunning
           setBusy(resumedRunning)
-          setAwaitingResponse(resumedRunning)
+          setAwaitingResponse(resumedRunning && !recoveredInFlightTail)
         }
       }
     },
@@ -1056,15 +1101,30 @@ export function useSessionActions({
   // `parentStoredId` so it nests under its parent, then open it as its own tab
   // and switch to it — the parent chat stays put (mirrors openNewSessionTile).
   const forkBranch = useCallback(
-    async (branchMessages: BranchMessage[], parentStoredId: null | string, cwd?: string): Promise<boolean> => {
+    async (
+      branchMessages: BranchMessage[],
+      parentStoredId: null | string,
+      cwd?: string,
+      profile?: null | string
+    ): Promise<boolean> => {
       creatingSessionRef.current = true
 
       try {
+        // A branch belongs to its parent's OWNING profile. Swapping the live
+        // gateway first AND passing `profile` on the create mirrors
+        // desktopSessionCreateParams/resumeSession: in app-global remote mode
+        // one backend serves every profile, so an omitted profile silently
+        // lands the branch on the launch (default) profile — the "session
+        // jumps between profiles after branching" bug. The swap also makes
+        // upsertOptimisticSession's $activeGatewayProfile stamp correct.
+        await ensureGatewayProfile(profile)
+
         // No title: the backend auto-names the branch from its parent's lineage.
         const branched = await requestGateway<SessionCreateResponse>('session.create', {
           cols: 96,
           source: 'desktop',
           ...(cwd && { cwd }),
+          ...(profile ? { profile } : {}),
           messages: branchMessages.map(({ content, role }) => ({ content, role })),
           ...(parentStoredId && { parent_session_id: parentStoredId })
         })
@@ -1165,7 +1225,12 @@ export function useSessionActions({
 
       clearNotifications()
 
-      return forkBranch(branchMessages, selectedStoredSessionIdRef.current, $currentCwd.get().trim())
+      // The open chat's owning profile, NOT the picker's / launch profile —
+      // /profile only retargets new chats, so a branch of an existing thread
+      // must stay on that thread's backend (cache hit for an open session).
+      const profile = await resolveSessionProfile(selectedStoredSessionIdRef.current)
+
+      return forkBranch(branchMessages, selectedStoredSessionIdRef.current, $currentCwd.get().trim(), profile)
     },
     [activeSessionIdRef, busyRef, copy, forkBranch, selectedStoredSessionIdRef]
   )
@@ -1197,7 +1262,7 @@ export function useSessionActions({
           return false
         }
 
-        return await forkBranch(branchMessages, stored?.id ?? storedSessionId, stored?.cwd?.trim())
+        return await forkBranch(branchMessages, stored?.id ?? storedSessionId, stored?.cwd?.trim(), profile)
       } catch (err) {
         notifyError(err, copy.branchFailed)
 
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions/utils.test.ts b/apps/desktop/src/app/session/hooks/use-session-actions/utils.test.ts
index 277a9c96b64..eb2633e5400 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions/utils.test.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions/utils.test.ts
@@ -317,6 +317,52 @@ describe('reconcileResumeMessages', () => {
     const [out] = reconcileResumeMessages(next, previous)
     expect(out.parts.some(p => p.type === 'reasoning')).toBe(true)
   })
+
+  it('preserves attachment refs for a matching user turn', () => {
+    const next = [msg('stored-user', 'user', 'describe this image')]
+
+    const previous = [
+      msg('live-user', 'user', 'describe this image', {
+        attachmentRefs: ['@image:/tmp/photo.png']
+      })
+    ]
+
+    const [out] = reconcileResumeMessages(next, previous)
+
+    expect(out.attachmentRefs).toEqual(['@image:/tmp/photo.png'])
+  })
+
+  it('does not overwrite attachment refs already present on the resumed message', () => {
+    const next = [
+      msg('stored-user', 'user', 'describe this image', {
+        attachmentRefs: ['@image:/tmp/authoritative.png']
+      })
+    ]
+
+    const previous = [
+      msg('live-user', 'user', 'describe this image', {
+        attachmentRefs: ['@image:/tmp/cached.png']
+      })
+    ]
+
+    const [out] = reconcileResumeMessages(next, previous)
+
+    expect(out.attachmentRefs).toEqual(['@image:/tmp/authoritative.png'])
+  })
+
+  it('does not preserve attachment refs when the user text differs', () => {
+    const next = [msg('stored-user', 'user', 'a different prompt')]
+
+    const previous = [
+      msg('live-user', 'user', 'describe this image', {
+        attachmentRefs: ['@image:/tmp/photo.png']
+      })
+    ]
+
+    const [out] = reconcileResumeMessages(next, previous)
+
+    expect(out.attachmentRefs).toBeUndefined()
+  })
 })
 
 describe('preserveLocalPendingTurnMessages', () => {
@@ -440,9 +486,91 @@ describe('preserveLocalPendingTurnMessages', () => {
       'user-optimistic'
     ])
   })
+
+  // #70720: the gateway persists an attached image as a leading `@image:<path>`
+  // directive line, while the local optimistic composer keeps it as separate
+  // `attachmentRefs`. A naive text compare (chatMessageText a === b) therefore
+  // always mismatched whenever an image was attached and re-appended the
+  // optimistic row as a distinct, duplicate user bubble. Both sides must now
+  // reduce to the same visible text via textWithoutImageRefs.
+  it('does not duplicate the optimistic image turn when the persisted turn carries @image refs', () => {
+    const previous = [
+      msg('1-user', 'user', 'first'),
+      msg('2-assistant', 'assistant', 'first answer'),
+      msg('user-optimistic', 'user', 'what is in this photo?', {
+        attachmentRefs: ['@image:/tmp/cat.png']
+      })
+    ]
+
+    const next = [
+      msg('1-user-stored', 'user', 'first'),
+      msg('2-assistant-stored', 'assistant', 'first answer'),
+      msg('3-user-stored', 'user', '@image:/tmp/cat.png\nwhat is in this photo?')
+    ]
+
+    expect(preserveLocalPendingTurnMessages(next, previous)).toBe(next)
+  })
+
+  it('still keeps a genuinely uncommitted optimistic image turn when the persisted text differs', () => {
+    const previous = [
+      msg('1-user', 'user', 'first'),
+      msg('2-assistant', 'assistant', 'first answer'),
+      msg('user-optimistic', 'user', 'a different caption', {
+        attachmentRefs: ['@image:/tmp/cat.png']
+      })
+    ]
+
+    // Persisted turn has a different caption — the optimistic row is still
+    // uncommitted and must survive (image-aware compare must not over-correct).
+    const next = [
+      msg('1-user-stored', 'user', 'first'),
+      msg('2-assistant-stored', 'assistant', 'first answer'),
+      msg('3-user-stored', 'user', '@image:/tmp/cat.png\nwhat is in this photo?')
+    ]
+
+    expect(preserveLocalPendingTurnMessages(next, previous).map(message => message.id)).toEqual([
+      '1-user-stored',
+      '2-assistant-stored',
+      '3-user-stored',
+      'user-optimistic'
+    ])
+  })
 })
 
 describe('appendLiveSessionProjection', () => {
+  it('does not duplicate the inflight user when the persisted turn carries @image refs', () => {
+    // By the time a stored transcript reaches appendLiveSessionProjection it
+    // has already been run through toChatMessages, so the @image directive has
+    // been lifted into attachmentRefs and the visible text is the bare caption.
+    const stored = [
+      msg('stored-user', 'user', 'current running prompt', {
+        attachmentRefs: ['@image:/tmp/cat.png']
+      }),
+      msg('stored-assistant', 'assistant', 'earlier answer')
+    ]
+
+    const restored = appendLiveSessionProjection(stored, {
+      session_id: 'runtime-1',
+      inflight: {
+        user: 'current running prompt',
+        assistant: 'partial answer',
+        streaming: true
+      }
+    })
+
+    // The persisted user already carries the same visible text (the attachment
+    // lives in attachmentRefs on both sides), so the inflight *user* projection
+    // must be suppressed — exactly one user row, no duplicated bubble stacked
+    // on top of the persisted one. The live assistant tail is still projected.
+    const userRows = restored.filter(message => message.role === 'user')
+    expect(userRows).toHaveLength(1)
+    expect(userRows[0].id).toBe('stored-user')
+
+    const userText = userRows[0].parts.map(part => ('text' in part ? part.text : '')).join('')
+
+    expect(userText).toBe('current running prompt')
+  })
+
   it('restores the running turn and accepted queued prompt after a renderer restart', () => {
     const stored = [msg('stored-user', 'user', 'earlier'), msg('stored-assistant', 'assistant', 'earlier answer')]
 
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions/utils.ts b/apps/desktop/src/app/session/hooks/use-session-actions/utils.ts
index 553f473b994..39ba0bd911c 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions/utils.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions/utils.ts
@@ -1,7 +1,7 @@
 import { getSession } from '@/hermes'
 import { assistantTextPart, type ChatMessage, chatMessageText, textPart } from '@/lib/chat-messages'
 import { normalizePersonalityValue } from '@/lib/chat-runtime'
-import { embeddedImageUrls, textWithoutEmbeddedImages } from '@/lib/embedded-images'
+import { embeddedImageUrls, textWithoutEmbeddedImages, textWithoutImageRefs } from '@/lib/embedded-images'
 import { reconcileApprovalModeForProfile } from '@/store/approval-mode'
 import { requestDesktopOnboardingForCredentialWarning } from '@/store/onboarding'
 import { $activeGatewayProfile, $profiles, normalizeProfileKey } from '@/store/profile'
@@ -211,6 +211,10 @@ export function reconcileResumeMessages(nextMessages: ChatMessage[], previousMes
 
     if (nextText === previousVisibleText || nextText === previousText.trim()) {
       preserved = preserveReasoningParts(preserved, previous)
+
+      if (message.role === 'user' && preserved.attachmentRefs === undefined && previous.attachmentRefs?.length) {
+        preserved = { ...preserved, attachmentRefs: [...previous.attachmentRefs] }
+      }
     }
 
     const previousImages = embeddedImageUrls(previousText)
@@ -306,7 +310,7 @@ export function preserveLocalPendingTurnMessages(
     if (
       isOptimisticUser &&
       latestAuthoritativeUser &&
-      chatMessageText(latestAuthoritativeUser).trim() === chatMessageText(message).trim()
+      textWithoutImageRefs(chatMessageText(latestAuthoritativeUser)) === textWithoutImageRefs(chatMessageText(message))
     ) {
       continue
     }
@@ -318,7 +322,7 @@ export function preserveLocalPendingTurnMessages(
         continue
       }
 
-      if (chatMessageText(authoritative).trim() === chatMessageText(message).trim()) {
+      if (textWithoutImageRefs(chatMessageText(authoritative)) === textWithoutImageRefs(chatMessageText(message))) {
         continue
       }
     }
@@ -345,9 +349,13 @@ export function appendLiveSessionProjection(
   const inflightUser = projection.inflight?.user?.trim() ?? ''
   const inflightAssistant = projection.inflight?.assistant ?? ''
   const inflightStreaming = Boolean(projection.inflight?.streaming)
+  // A retained failed turn (the gateway keeps error snapshots replayable when
+  // the terminal frame may have been lost to a disconnect) — surface the
+  // failure on the projected row instead of rendering the partial as healthy.
+  const inflightError = projection.inflight?.error?.trim() ?? ''
   const queuedUser = projection.queued?.user?.trim() ?? ''
 
-  if (!inflightUser && !inflightAssistant && !inflightStreaming && !queuedUser) {
+  if (!inflightUser && !inflightAssistant && !inflightStreaming && !inflightError && !queuedUser) {
     return messages
   }
 
@@ -359,7 +367,9 @@ export function appendLiveSessionProjection(
   // Only suppress the projection when the latest authoritative user row is the
   // same turn — older identical prompts must not hide a newly accepted repeat.
   const latestUser = [...messages].reverse().find(message => message.role === 'user')
-  const inflightUserAlreadyPersisted = latestUser && chatMessageText(latestUser).trim() === inflightUser
+
+  const inflightUserAlreadyPersisted =
+    latestUser && textWithoutImageRefs(chatMessageText(latestUser)) === textWithoutImageRefs(inflightUser)
 
   if (inflightUser && !inflightUserAlreadyPersisted) {
     projected.push({
@@ -371,12 +381,13 @@ export function appendLiveSessionProjection(
 
   // Keep a pending assistant boundary even before the first delta when a
   // queued user turn follows it. This preserves the two distinct turns.
-  if (inflightAssistant || inflightStreaming || (inflightUser && queuedUser)) {
+  if (inflightAssistant || inflightStreaming || inflightError || (inflightUser && queuedUser)) {
     projected.push({
       id: `assistant-stream-${sessionId}`,
       role: 'assistant',
       parts: inflightAssistant ? [assistantTextPart(inflightAssistant)] : [],
-      pending: inflightStreaming
+      pending: inflightStreaming,
+      ...(inflightError ? { error: inflightError } : {})
     })
   }
 
diff --git a/apps/desktop/src/app/session/hooks/use-session-state-cache.test.tsx b/apps/desktop/src/app/session/hooks/use-session-state-cache.test.tsx
index c2d5a0d0376..f96307f361c 100644
--- a/apps/desktop/src/app/session/hooks/use-session-state-cache.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-session-state-cache.test.tsx
@@ -1,5 +1,5 @@
 import { act, cleanup, render } from '@testing-library/react'
-import type { MutableRefObject } from 'react'
+import { type MutableRefObject, useLayoutEffect } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { ChatMessage } from '@/lib/chat-messages'
@@ -260,6 +260,111 @@ describe('useSessionStateCache — per-session turn timer', () => {
   })
 })
 
+interface LayoutProbeHarnessProps {
+  activeSessionId: string | null
+  onLayoutSnapshot: (snapshot: { active: string | null; selected: string | null }) => void
+  onReady: (cache: Cache) => void
+  selectedStoredSessionId: string | null
+}
+
+function LayoutProbeHarness({
+  activeSessionId,
+  onLayoutSnapshot,
+  onReady,
+  selectedStoredSessionId
+}: LayoutProbeHarnessProps) {
+  const busyRef: MutableRefObject<boolean> = { current: false }
+
+  const cache = useSessionStateCache({
+    activeSessionId,
+    busyRef,
+    selectedStoredSessionId,
+    setAwaitingResponse: () => undefined,
+    setBusy: () => undefined,
+    setMessages: () => undefined
+  })
+
+  onReady(cache)
+
+  // useLayoutEffect fires synchronously right after the DOM commit, BEFORE
+  // the hook's own useEffect (a passive effect) has a chance to mirror the
+  // new props into activeSessionIdRef/selectedStoredSessionIdRef. Anything
+  // that reads the refs in this window — including a synchronous DOM event
+  // handler firing against the just-committed view — observes the outgoing
+  // session's ids.
+  useLayoutEffect(() => {
+    onLayoutSnapshot({
+      active: cache.activeSessionIdRef.current,
+      selected: cache.selectedStoredSessionIdRef.current
+    })
+  })
+
+  return null
+}
+
+describe('useSessionStateCache — refs stay coherent with the committed session on switch (#59305)', () => {
+  afterEach(() => cleanup())
+
+  it('reflects the new session ids from the layout phase right after switching to a new session', () => {
+    let cache!: Cache
+    const snapshots: Array<{ active: string | null; selected: string | null }> = []
+
+    const { rerender } = render(
+      <LayoutProbeHarness
+        activeSessionId="runtime-A"
+        onLayoutSnapshot={s => snapshots.push(s)}
+        onReady={c => (cache = c)}
+        selectedStoredSessionId="stored-A"
+      />
+    )
+
+    void cache
+    snapshots.length = 0 // drop the initial-mount snapshot; only the switch matters
+
+    rerender(
+      <LayoutProbeHarness
+        activeSessionId="runtime-B"
+        onLayoutSnapshot={s => snapshots.push(s)}
+        onReady={c => (cache = c)}
+        selectedStoredSessionId="stored-B"
+      />
+    )
+
+    // The refs must already reflect B by the layout phase — a callback firing
+    // in this window must never observe the outgoing session's ids.
+    expect(snapshots[0]).toEqual({ active: 'runtime-B', selected: 'stored-B' })
+  })
+
+  it('does not clobber an imperative ref pin on a re-render that leaves the props unchanged (#54527-class)', () => {
+    // submit.ts pins activeSessionIdRef.current to a freshly resumed runtime id
+    // WITHOUT updating the source atom that feeds the activeSessionId prop (by
+    // design — see submit.ts's "pin the foreground session context" comment).
+    // The prop-mirroring here must only fire when the prop itself changes; an
+    // unconditional resync would silently undo that pin on the next incidental
+    // render (wiring.tsx re-renders constantly during an active turn).
+    let cache!: Cache
+
+    const { rerender } = render(
+      <Harness activeSessionId="runtime-A" onReady={c => (cache = c)} selectedStoredSessionId="stored-A" />
+    )
+
+    // Simulate submit.ts's imperative pin: a resume swapped in a new runtime
+    // id without touching the prop.
+    cache.activeSessionIdRef.current = 'runtime-resumed'
+
+    // A re-render with the SAME props (e.g. an unrelated $busy/$messages
+    // change elsewhere in the tree) must not touch the pinned ref.
+    rerender(<Harness activeSessionId="runtime-A" onReady={c => (cache = c)} selectedStoredSessionId="stored-A" />)
+
+    expect(cache.activeSessionIdRef.current).toBe('runtime-resumed')
+
+    // A genuine prop change (a real navigation/selection move) still wins.
+    rerender(<Harness activeSessionId="runtime-B" onReady={c => (cache = c)} selectedStoredSessionId="stored-B" />)
+
+    expect(cache.activeSessionIdRef.current).toBe('runtime-B')
+  })
+})
+
 function userMessage(id: string, text: string): ChatMessage {
   return { id, role: 'user', parts: [{ type: 'text', text }] }
 }
diff --git a/apps/desktop/src/app/session/hooks/use-session-state-cache.ts b/apps/desktop/src/app/session/hooks/use-session-state-cache.ts
index 7e0d7278ed7..1b55e9c6915 100644
--- a/apps/desktop/src/app/session/hooks/use-session-state-cache.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-state-cache.ts
@@ -4,6 +4,7 @@ import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
 import type { ChatMessage } from '@/lib/chat-messages'
 import { preserveLocalAssistantErrors } from '@/lib/chat-messages'
 import { createClientSessionState } from '@/lib/chat-runtime'
+import { persistInFlightTurnState } from '@/lib/inflight-turn-journal'
 import { setMutableRef } from '@/lib/mutable-ref'
 import {
   $busy,
@@ -51,8 +52,33 @@ export function useSessionStateCache({
   setMessages
 }: SessionStateCacheOptions) {
   const busy = useStore($busy)
-  const activeSessionIdRef = useRef<string | null>(null)
-  const selectedStoredSessionIdRef = useRef<string | null>(null)
+  const activeSessionIdRef = useRef<string | null>(activeSessionId)
+  const selectedStoredSessionIdRef = useRef<string | null>(selectedStoredSessionId)
+
+  // Mirror the latest prop into its ref synchronously during render — not via
+  // a passive useEffect, which only fires a frame after paint and left the
+  // ref pointing at the outgoing session for one commit (#59305). Guarded to
+  // fire only when the PROP itself changed since the last render (the same
+  // condition a `useEffect(..., [activeSessionId])` dependency array already
+  // enforced) rather than unconditionally: submit.ts and use-session-actions
+  // pin these refs imperatively mid-flight (e.g. to a just-resumed runtime id)
+  // without updating the source atom in lockstep, and wiring.tsx re-renders
+  // constantly during an active turn — an unconditional resync would silently
+  // clobber that pin on the next incidental render (#54527-class regression).
+  const activeSessionIdPropRef = useRef(activeSessionId)
+
+  if (activeSessionIdPropRef.current !== activeSessionId) {
+    activeSessionIdPropRef.current = activeSessionId
+    activeSessionIdRef.current = activeSessionId
+  }
+
+  const selectedStoredSessionIdPropRef = useRef(selectedStoredSessionId)
+
+  if (selectedStoredSessionIdPropRef.current !== selectedStoredSessionId) {
+    selectedStoredSessionIdPropRef.current = selectedStoredSessionId
+    selectedStoredSessionIdRef.current = selectedStoredSessionId
+  }
+
   const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
   const runtimeIdByStoredSessionIdRef = useRef(new Map<string, string>())
   const pendingViewStateRef = useRef<{ sessionId: string; state: ClientSessionState } | null>(null)
@@ -61,18 +87,11 @@ export function useSessionStateCache({
   // flush below tell a same-session refresh from a thread switch.
   const viewSessionIdRef = useRef<string | null>(null)
 
-  useEffect(() => {
-    activeSessionIdRef.current = activeSessionId
-  }, [activeSessionId])
-
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     setMutableRef(busyRef, busy)
   }, [busy, busyRef])
 
-  useEffect(() => {
-    selectedStoredSessionIdRef.current = selectedStoredSessionId
-  }, [selectedStoredSessionId])
-
   const ensureSessionState = useCallback((sessionId: string, storedSessionId?: string | null) => {
     const existing = sessionStateByRuntimeIdRef.current.get(sessionId)
 
@@ -251,6 +270,10 @@ export function useSessionStateCache({
       const previous = ensureSessionState(sessionId, storedSessionId)
       const next = updater({ ...previous, messages: previous.messages })
       sessionStateByRuntimeIdRef.current.set(sessionId, next)
+      // Crash-survivable turn progress: journal the running turn's visible
+      // tail (throttled localStorage write; cleared the moment the turn
+      // settles) so a renderer/app death mid-turn can be recovered on resume.
+      persistInFlightTurnState(next)
       // Publishing to $sessionStates automatically fires transition side-effects
       // (watchdog, settle grace, unread marker, compression id rotation) inside
       // publishSessionState — no manual transition call needed.
diff --git a/apps/desktop/src/app/session/workspace-session-target.test.ts b/apps/desktop/src/app/session/workspace-session-target.test.ts
index 3a83f605a32..614227585c0 100644
--- a/apps/desktop/src/app/session/workspace-session-target.test.ts
+++ b/apps/desktop/src/app/session/workspace-session-target.test.ts
@@ -9,7 +9,7 @@ import {
   setNewChatWorkspaceTarget
 } from '@/store/session'
 
-import { startWorkspaceSession } from './workspace-session-target'
+import { newSessionOpensTab, startWorkspaceSession } from './workspace-session-target'
 
 function deferred<T>() {
   let resolve!: (value: T) => void
@@ -21,6 +21,29 @@ function deferred<T>() {
   return { promise, resolve }
 }
 
+/**
+ * The sidebar "+" is a create affordance, not a discard one: with a chat
+ * already loaded it must stack a tab (⌘T) rather than replace the surface
+ * (⌘N), which would throw away a conversation that may still be mid-turn.
+ */
+describe('newSessionOpensTab', () => {
+  it('opens a tab once a conversation is on screen', () => {
+    expect(newSessionOpensTab('runtime-a', 'stored-a')).toBe(true)
+  })
+
+  it('opens a tab for a live runtime whose stored id has not landed yet', () => {
+    expect(newSessionOpensTab('runtime-a', null)).toBe(true)
+  })
+
+  it('opens a tab for a selected session still resuming into a runtime', () => {
+    expect(newSessionOpensTab(null, 'stored-a')).toBe(true)
+  })
+
+  it('replaces the empty surface when nothing is open', () => {
+    expect(newSessionOpensTab(null, null)).toBe(false)
+  })
+})
+
 describe('startWorkspaceSession', () => {
   afterEach(() => {
     setCurrentBranch('')
diff --git a/apps/desktop/src/app/session/workspace-session-target.ts b/apps/desktop/src/app/session/workspace-session-target.ts
index da5028502a1..9a87d95c009 100644
--- a/apps/desktop/src/app/session/workspace-session-target.ts
+++ b/apps/desktop/src/app/session/workspace-session-target.ts
@@ -17,6 +17,19 @@ interface WorkspaceSessionOptions {
   startFreshSessionDraft: (options?: { workspaceTarget: string }) => void
 }
 
+/**
+ * Should the sidebar "+" open a NEW TAB rather than replace what's on screen?
+ *
+ * "+" is a create affordance, never a discard one. Once a conversation is
+ * loaded, replacing it with a blank draft would throw away a chat that may
+ * still be mid-turn, so the button stacks a tab beside it (⌘T) instead of
+ * taking over the surface (⌘N). With nothing open there is no tab worth
+ * preserving and the cheaper fresh-draft path applies.
+ */
+export function newSessionOpensTab(activeSessionId: null | string, selectedStoredSessionId: null | string): boolean {
+  return Boolean(activeSessionId || selectedStoredSessionId)
+}
+
 export function startWorkspaceSession({
   activeSessionIdRef,
   followActiveSessionCwd: followCwd = followActiveSessionCwd,
diff --git a/apps/desktop/src/app/settings/billing/plans-view.tsx b/apps/desktop/src/app/settings/billing/plans-view.tsx
index b0d1fd6b703..728a8142387 100644
--- a/apps/desktop/src/app/settings/billing/plans-view.tsx
+++ b/apps/desktop/src/app/settings/billing/plans-view.tsx
@@ -118,6 +118,7 @@ function PlanCard({ flow, tier }: { flow: DowngradeFlow; tier: BillingPlanTierVi
 
   // When the confirm panel closes (cancel / scheduled), return focus to this tile
   // so keyboard focus is never left detached on the removed panel.
+  // eslint-disable-next-line no-restricted-syntax -- tracks previous confirming state for focus return, not an atom mirror
   useEffect(() => {
     if (wasConfirming.current && !confirming) {
       cardRef.current?.focus()
diff --git a/apps/desktop/src/app/settings/computer-use-panel.tsx b/apps/desktop/src/app/settings/computer-use-panel.tsx
index bf30b3b83f7..2423df8aef5 100644
--- a/apps/desktop/src/app/settings/computer-use-panel.tsx
+++ b/apps/desktop/src/app/settings/computer-use-panel.tsx
@@ -76,6 +76,7 @@ export function ComputerUsePanel({ onConfiguredChange }: ComputerUsePanelProps)
     }
   }, [])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     activeRef.current = true
     void refresh()
diff --git a/apps/desktop/src/app/settings/config-settings.tsx b/apps/desktop/src/app/settings/config-settings.tsx
index 18fa33d744a..c97d5b72009 100644
--- a/apps/desktop/src/app/settings/config-settings.tsx
+++ b/apps/desktop/src/app/settings/config-settings.tsx
@@ -84,6 +84,7 @@ export function ConfigSettings({
   // Background refetches thereafter must not clobber in-progress edits.
   const configSeeded = useRef(false)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (loadedConfig && !configSeeded.current) {
       configSeeded.current = true
@@ -126,6 +127,7 @@ export function ConfigSettings({
     return () => void (cancelled = true)
   }, [])
 
+  // eslint-disable-next-line no-restricted-syntax -- autosave bookkeeping refs, not an atom mirror
   useEffect(() => {
     if (!config || saveVersion === 0) {
       return
diff --git a/apps/desktop/src/app/settings/constants.ts b/apps/desktop/src/app/settings/constants.ts
index 2ecdfb1e7e4..f041b299247 100644
--- a/apps/desktop/src/app/settings/constants.ts
+++ b/apps/desktop/src/app/settings/constants.ts
@@ -11,6 +11,7 @@ import {
   Sun,
   Wrench
 } from '@/lib/icons'
+import { REASONING_EFFORTS } from '@/lib/reasoning-effort'
 import type { ThemeMode } from '@/themes/context'
 
 import { defineFieldCopy } from './field-copy'
@@ -246,7 +247,8 @@ export const ENUM_OPTIONS: Record<string, string[]> = {
   'approvals.mode': ['manual', 'smart', 'off'],
   'code_execution.mode': ['project', 'strict'],
   'context.engine': ['compressor', 'default', 'custom'],
-  'delegation.reasoning_effort': ['', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'],
+  // '' = inherit the agent's own effort; the rest is the shared scale.
+  'delegation.reasoning_effort': ['', ...REASONING_EFFORTS],
   // NOTE: memory.provider is intentionally NOT listed here. Its options are
   // discovery-driven and served by the backend config schema (merged
   // per-request in web_server._schema_with_dynamic_provider_options), so
diff --git a/apps/desktop/src/app/settings/custom-endpoints-settings.tsx b/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
index bea02e2bce7..b74b30a2909 100644
--- a/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
+++ b/apps/desktop/src/app/settings/custom-endpoints-settings.tsx
@@ -58,7 +58,7 @@ function formFromEndpoint(endpoint: CustomEndpoint): EndpointForm {
   }
 }
 
-function toPayload(form: EndpointForm): CustomEndpointUpdate {
+function toPayload(form: EndpointForm, models?: string[]): CustomEndpointUpdate {
   const contextLength = Number.parseInt(form.contextLength, 10)
 
   return {
@@ -69,7 +69,8 @@ function toPayload(form: EndpointForm): CustomEndpointUpdate {
     api_key: form.apiKey.trim() || undefined,
     context_length: Number.isFinite(contextLength) && contextLength > 0 ? contextLength : undefined,
     discover_models: form.discoverModels,
-    make_default: form.makeDefault
+    make_default: form.makeDefault,
+    models: models?.length ? models : undefined
   }
 }
 
@@ -125,7 +126,7 @@ export function CustomEndpointsSettings({ onConfigSaved, onMainModelChanged }: C
   async function handleSave() {
     try {
       setSaving(true)
-      const response = await saveCustomEndpoint(toPayload(form))
+      const response = await saveCustomEndpoint(toPayload(form, discoveredModels))
       setEndpoints(response.endpoints)
       const saved = response.endpoints.find(endpoint => endpoint.id === response.id)
 
diff --git a/apps/desktop/src/app/settings/fallback-models-field.tsx b/apps/desktop/src/app/settings/fallback-models-field.tsx
index bbeedf9b602..d7aa7839dfe 100644
--- a/apps/desktop/src/app/settings/fallback-models-field.tsx
+++ b/apps/desktop/src/app/settings/fallback-models-field.tsx
@@ -88,6 +88,7 @@ export function FallbackModelsField({
 
   // Resync on real external changes (profile switch / config reload). Skip
   // when `value` is just our own commit echoing through the parent.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const persisted = normalizeEntries(value)
 
diff --git a/apps/desktop/src/app/settings/gateway-settings.test.tsx b/apps/desktop/src/app/settings/gateway-settings.test.tsx
new file mode 100644
index 00000000000..89df6a90491
--- /dev/null
+++ b/apps/desktop/src/app/settings/gateway-settings.test.tsx
@@ -0,0 +1,78 @@
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { atom } from 'nanostores'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ProfileInfo } from '@/types/hermes'
+
+const getConnectionConfig = vi.fn()
+const profiles = atom<ProfileInfo[]>([])
+
+vi.mock('@/store/profile', () => ({
+  $profiles: profiles,
+  refreshActiveProfile: vi.fn()
+}))
+
+const localConnection = {
+  cloudOrg: '',
+  envOverride: false,
+  mode: 'local',
+  remoteAuthMode: 'token',
+  remoteOauthConnected: false,
+  remoteTokenPreview: null,
+  remoteTokenSet: false,
+  remoteUrl: ''
+}
+
+beforeEach(() => {
+  profiles.set([
+    {
+      has_env: false,
+      is_default: true,
+      model: null,
+      name: 'default',
+      path: '/tmp/hermes',
+      provider: null,
+      skill_count: 0
+    },
+    {
+      has_env: false,
+      is_default: false,
+      model: null,
+      name: 'work',
+      path: '/tmp/hermes/profiles/work',
+      provider: null,
+      skill_count: 0
+    }
+  ])
+  getConnectionConfig.mockResolvedValue(localConnection)
+  Object.defineProperty(window, 'hermesDesktop', {
+    configurable: true,
+    value: { getConnectionConfig }
+  })
+})
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+})
+
+describe('GatewaySettings', () => {
+  it('labels local mode as default inheritance for a named profile', async () => {
+    const { GatewaySettings } = await import('./gateway-settings')
+
+    render(<GatewaySettings />)
+    expect(await screen.findByText('Local gateway')).toBeTruthy()
+    expect(
+      screen.getByText('Start a private Hermes backend on localhost. This is the default and works offline.')
+    ).toBeTruthy()
+
+    fireEvent.click(screen.getByRole('button', { name: 'work' }))
+
+    await waitFor(() => expect(getConnectionConfig).toHaveBeenLastCalledWith('work'))
+    expect(await screen.findByText('Use default gateway')).toBeTruthy()
+    expect(screen.getByText("Remove this profile's override and use the default connection.")).toBeTruthy()
+    expect(
+      screen.queryByText('Start a private Hermes backend on localhost. This is the default and works offline.')
+    ).toBeNull()
+  })
+})
diff --git a/apps/desktop/src/app/settings/gateway-settings.tsx b/apps/desktop/src/app/settings/gateway-settings.tsx
index 91e1a117845..30afd2dfd3d 100644
--- a/apps/desktop/src/app/settings/gateway-settings.tsx
+++ b/apps/desktop/src/app/settings/gateway-settings.tsx
@@ -404,6 +404,7 @@ export function GatewaySettings({ embedded = false }: { embedded?: boolean } = {
     return () => void (cancelled = true)
   }, [state.mode])
 
+  // eslint-disable-next-line no-restricted-syntax -- monotonic request-sequence counters, not an atom mirror
   useEffect(() => {
     contextSeq.current += 1
     sshTestSeq.current += 1
@@ -1053,11 +1054,11 @@ export function GatewaySettings({ embedded = false }: { embedded?: boolean } = {
         <div className="grid auto-rows-fr grid-cols-1 gap-2 sm:grid-cols-2 min-[72rem]:grid-cols-4">
           <ModeCard
             active={state.mode === 'local'}
-            description={g.localDesc}
+            description={scope === null ? g.localDesc : g.inheritDesc}
             disabled={state.envOverride}
             icon={Monitor}
             onSelect={() => setState(current => ({ ...current, mode: 'local' }))}
-            title={g.localTitle}
+            title={scope === null ? g.localTitle : g.inheritTitle}
           />
           <ModeCard
             active={state.mode === 'cloud'}
diff --git a/apps/desktop/src/app/settings/index.tsx b/apps/desktop/src/app/settings/index.tsx
index f51cca30f94..b74349cccd8 100644
--- a/apps/desktop/src/app/settings/index.tsx
+++ b/apps/desktop/src/app/settings/index.tsx
@@ -288,7 +288,7 @@ export function SettingsView({ onClose, onConfigSaved, onMainModelChanged }: Set
       <OverlaySplitLayout>
         <OverlayNav footer={navFooter} groups={navGroups} />
 
-        <OverlayMain className="px-0 pb-0 pt-[calc(var(--titlebar-height)+1rem)]">
+        <OverlayMain className="px-0 pb-0">
           {activeView === 'config:appearance' ? (
             <AppearanceSettings />
           ) : activeView === 'about' ? (
diff --git a/apps/desktop/src/app/settings/model-settings.test.tsx b/apps/desktop/src/app/settings/model-settings.test.tsx
index 985c6a018b6..bb9f1f9ec1c 100644
--- a/apps/desktop/src/app/settings/model-settings.test.tsx
+++ b/apps/desktop/src/app/settings/model-settings.test.tsx
@@ -435,4 +435,51 @@ describe('ModelSettings MoA preset editor', () => {
       vi.useRealTimers()
     }
   })
+
+  it('autosaves the selected preset when its enabled switch is toggled', async () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true })
+
+    try {
+      await openReferenceEditor()
+
+      fireEvent.click(screen.getByRole('switch', { name: 'Enabled' }))
+      await vi.advanceTimersByTimeAsync(700)
+
+      expect(saveMoaModels).toHaveBeenCalledWith(
+        expect.objectContaining({
+          presets: expect.objectContaining({
+            default: expect.objectContaining({ enabled: false })
+          })
+        })
+      )
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('saves a disabled reference model without removing it (per-slot enabled toggle)', async () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true })
+
+    try {
+      await openReferenceEditor()
+
+      fireEvent.click(screen.getByRole('switch', { name: 'Disable reference 1' }))
+      await vi.advanceTimersByTimeAsync(700)
+
+      expect(saveMoaModels).toHaveBeenCalledWith(
+        expect.objectContaining({
+          presets: expect.objectContaining({
+            default: expect.objectContaining({
+              reference_models: [
+                expect.objectContaining({ provider: 'nous', model: 'hermes-4', enabled: false }),
+                expect.objectContaining({ provider: 'openrouter', model: 'deepseek/deepseek-v4-pro' })
+              ]
+            })
+          })
+        })
+      )
+    } finally {
+      vi.useRealTimers()
+    }
+  })
 })
diff --git a/apps/desktop/src/app/settings/model-settings.tsx b/apps/desktop/src/app/settings/model-settings.tsx
index c0f76175e49..3b1b8997ab0 100644
--- a/apps/desktop/src/app/settings/model-settings.tsx
+++ b/apps/desktop/src/app/settings/model-settings.tsx
@@ -25,6 +25,7 @@ import type {
 } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { AlertTriangle, Cpu, Loader2 } from '@/lib/icons'
+import { DEFAULT_REASONING_EFFORT, REASONING_EFFORT_VALUES } from '@/lib/reasoning-effort'
 import { cn } from '@/lib/utils'
 import { notifyError } from '@/store/notifications'
 import { startManualLocalEndpoint, startManualOnboarding, startManualProviderOAuth } from '@/store/onboarding'
@@ -81,10 +82,6 @@ export function ModelSettingsSkeleton() {
   )
 }
 
-// Hermes' reasoning levels (VALID_REASONING_EFFORTS); `none` = thinking off.
-// Empty config = Hermes default (medium), shown as Medium.
-const EFFORT_VALUES = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'] as const
-
 // agent.service_tier stores "fast"/"priority"/"on" for fast; anything else is
 // normal (mirrors tui_gateway _load_service_tier).
 const isFastTier = (tier: unknown): boolean =>
@@ -94,9 +91,6 @@ const isFastTier = (tier: unknown): boolean =>
       .toLowerCase()
   )
 
-// Reuse the composer's effort labels.
-const effortLabelKey = (v: string) => v as 'high' | 'low' | 'max' | 'medium' | 'minimal' | 'ultra' | 'xhigh'
-
 // A provider row is "ready" to pick a model from when it reports models. The
 // backend now surfaces the full `hermes model` universe (every canonical
 // provider), so unconfigured providers come back with `authenticated:false`
@@ -353,6 +347,7 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
   // setState updater) and hand it straight to the debounced autosave.
   const moaRef = useRef<MoaConfigResponse | null>(null)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     moaRef.current = moa
   }, [moa])
@@ -514,7 +509,7 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
     .trim()
     .toLowerCase()
 
-  const effortValue = rawEffort === 'false' || rawEffort === 'disabled' ? 'none' : rawEffort || 'medium'
+  const effortValue = rawEffort === 'false' || rawEffort === 'disabled' ? 'none' : rawEffort || DEFAULT_REASONING_EFFORT
 
   const fastOn = isFastTier(getNested(config ?? {}, 'agent.service_tier'))
 
@@ -821,9 +816,9 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
                     <SelectValue />
                   </SelectTrigger>
                   <SelectContent>
-                    {EFFORT_VALUES.map(value => (
+                    {REASONING_EFFORT_VALUES.map(value => (
                       <SelectItem key={value} value={value}>
-                        {value === 'none' ? m.reasoningOff : t.shell.modelOptions[effortLabelKey(value)]}
+                        {value === 'none' ? m.reasoningOff : t.shell.modelOptions[value]}
                       </SelectItem>
                     ))}
                   </SelectContent>
@@ -993,6 +988,15 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
                 ))}
               </SelectContent>
             </Select>
+            <label className="flex items-center gap-2 rounded-sm border border-border px-2 py-1 text-xs">
+              Enabled
+              <Switch
+                checked={currentMoaPreset.enabled !== false}
+                disabled={applying}
+                onCheckedChange={checked => updateMoaPreset(prev => ({ ...prev, enabled: checked }))}
+                size="xs"
+              />
+            </label>
             <Button
               disabled={applying}
               onClick={() => {
@@ -1069,6 +1073,21 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
           <div className="grid gap-1">
             {currentMoaPreset.reference_models.map((slot, index) => (
               <ListRow
+                action={
+                  <Switch
+                    aria-label={`${slot.enabled !== false ? 'Disable' : 'Enable'} reference ${index + 1}`}
+                    checked={slot.enabled !== false}
+                    disabled={applying}
+                    onCheckedChange={checked =>
+                      updateMoaPreset(prev => ({
+                        ...prev,
+                        reference_models: prev.reference_models.map((s, i) =>
+                          i === index ? { ...s, enabled: checked === true } : s
+                        )
+                      }))
+                    }
+                  />
+                }
                 below={
                   <div className="mt-2 flex flex-wrap items-center gap-2 pt-1">
                     <Select
@@ -1137,6 +1156,7 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
                     </Button>
                   </div>
                 }
+                className={cn(slot.enabled === false && 'opacity-60')}
                 description={
                   <span className="font-mono text-[0.68rem]">
                     {slot.provider} · {slot.model || m.model}
@@ -1149,7 +1169,10 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
             <Button
               disabled={applying}
               onClick={() =>
-                updateMoaPreset(prev => ({ ...prev, reference_models: [...prev.reference_models, prev.aggregator] }))
+                updateMoaPreset(prev => ({
+                  ...prev,
+                  reference_models: [...prev.reference_models, { ...prev.aggregator, enabled: true }]
+                }))
               }
               size="sm"
               variant="textStrong"
diff --git a/apps/desktop/src/app/settings/primitives.tsx b/apps/desktop/src/app/settings/primitives.tsx
index 2cc671f24ca..bbe86a45f2a 100644
--- a/apps/desktop/src/app/settings/primitives.tsx
+++ b/apps/desktop/src/app/settings/primitives.tsx
@@ -111,7 +111,8 @@ export function ListRow({
   hint,
   action,
   below,
-  wide = false
+  wide = false,
+  className
 }: {
   title: ReactNode
   description?: ReactNode
@@ -119,12 +120,13 @@ export function ListRow({
   action?: ReactNode
   below?: ReactNode
   wide?: boolean
+  className?: string
 }) {
   return (
     // Container-queried, not viewport-queried: the label/control split keys on
     // 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="@container">
+    <div className={cn('@container', className)}>
       <div
         className={cn(
           'grid gap-3 py-3',
diff --git a/apps/desktop/src/app/settings/sessions-settings.tsx b/apps/desktop/src/app/settings/sessions-settings.tsx
index 9102014b8ed..73cfce113f9 100644
--- a/apps/desktop/src/app/settings/sessions-settings.tsx
+++ b/apps/desktop/src/app/settings/sessions-settings.tsx
@@ -1,8 +1,15 @@
 import { useCallback, useEffect, useState } from 'react'
 
 import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
 import { Tip } from '@/components/ui/tooltip'
-import { deleteSession, listAllProfileSessions, setSessionArchived } from '@/hermes'
+import {
+  deleteSession,
+  getHermesConfigRecord,
+  listAllProfileSessions,
+  saveHermesConfig,
+  setSessionArchived
+} from '@/hermes'
 import { useI18n } from '@/i18n'
 import { sessionTitle } from '@/lib/chat-runtime'
 import { triggerHaptic } from '@/lib/haptics'
@@ -10,11 +17,13 @@ import { Archive, ArchiveOff, FolderOpen, Loader2, Trash2 } from '@/lib/icons'
 import { notify, notifyError } from '@/store/notifications'
 import { untombstoneSessions } from '@/store/projects'
 import { applyConfiguredDefaultProjectDir, ensureDefaultWorkspaceCwd, setSessions } from '@/store/session'
-import type { SessionInfo } from '@/types/hermes'
+import type { HermesConfigRecord, SessionInfo } from '@/types/hermes'
 
-import { EmptyState, ListRow, SectionHeading, SettingsContent, SettingsSkeleton } from './primitives'
+import { EmptyState, ListRow, SectionHeading, SettingsContent, SettingsSkeleton, ToggleRow } from './primitives'
 import { useDeepLinkHighlight } from './use-deep-link-highlight'
 
+const DEFAULT_AUTO_ARCHIVE_DAYS = 3
+
 const ARCHIVED_FETCH_LIMIT = 200
 
 function workspaceLabel(cwd: null | string | undefined): string {
@@ -114,6 +123,8 @@ export function SessionsSettings() {
     <SettingsContent>
       <DefaultProjectDirSetting />
 
+      <AutoArchiveSetting />
+
       <SectionHeading
         icon={Archive}
         meta={sessions.length ? String(sessions.length) : undefined}
@@ -174,6 +185,112 @@ export function SessionsSettings() {
   )
 }
 
+// Opt-in retention: soft-hide chats untouched for N days. The policy itself
+// (last-activity sweep, pin exemption) lives in the backend
+// (sessions.auto_archive in config.yaml + SessionDB.maybe_auto_archive); this
+// just toggles the config keys, so CLI / gateway / Desktop all honour one
+// setting. Pins are exempt on the backend, so pinned chats survive regardless.
+function AutoArchiveSetting() {
+  const { t } = useI18n()
+  const s = t.settings.sessions
+  const [config, setConfig] = useState<HermesConfigRecord | null>(null)
+  const [enabled, setEnabled] = useState(false)
+  const [days, setDays] = useState(DEFAULT_AUTO_ARCHIVE_DAYS)
+
+  useEffect(() => {
+    // Config REST is only reachable through the Electron bridge; skip in
+    // non-Electron contexts (tests/storybook) rather than throwing.
+    if (!window.hermesDesktop) {
+      return
+    }
+
+    let alive = true
+
+    void getHermesConfigRecord()
+      .then(record => {
+        if (!alive) {
+          return
+        }
+
+        const sessions = (record.sessions ?? {}) as Record<string, unknown>
+        const parsedDays = Number(sessions.auto_archive_days)
+        setConfig(record)
+        setEnabled(Boolean(sessions.auto_archive))
+        setDays(Number.isFinite(parsedDays) && parsedDays > 0 ? Math.round(parsedDays) : DEFAULT_AUTO_ARCHIVE_DAYS)
+      })
+      .catch(() => {
+        // Leave the control unmounted if config can't be read.
+      })
+
+    return () => {
+      alive = false
+    }
+  }, [])
+
+  const persist = useCallback(
+    async (autoArchive: boolean, archiveDays: number) => {
+      if (!config) {
+        return
+      }
+
+      const sessions = {
+        ...((config.sessions ?? {}) as Record<string, unknown>),
+        auto_archive: autoArchive,
+        auto_archive_days: archiveDays
+      }
+
+      const updated = { ...config, sessions }
+      setConfig(updated)
+
+      try {
+        await saveHermesConfig(updated)
+      } catch (err) {
+        notifyError(err, s.autoArchiveFailed)
+      }
+    },
+    [config, s.autoArchiveFailed]
+  )
+
+  if (!config) {
+    return null
+  }
+
+  return (
+    <div className="mb-6">
+      <ToggleRow
+        checked={enabled}
+        description={s.autoArchiveDesc}
+        label={s.autoArchiveTitle}
+        onChange={on => {
+          setEnabled(on)
+          void persist(on, days)
+        }}
+      />
+      {enabled && (
+        <ListRow
+          action={
+            <div className="flex items-center gap-2">
+              <Input
+                aria-label={s.autoArchiveDaysLabel}
+                className="w-20"
+                min={1}
+                onBlur={() => void persist(true, days)}
+                onChange={e => setDays(Math.max(1, Math.round(Number(e.target.value) || 1)))}
+                type="number"
+                value={days}
+              />
+              <span className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+                {s.autoArchiveDaysUnit}
+              </span>
+            </div>
+          }
+          title={s.autoArchiveDaysLabel}
+        />
+      )}
+    </div>
+  )
+}
+
 // Lets the user pin the default cwd for new sessions. Without this, packaged
 // builds on Windows used to spawn sessions in the install dir (`win-unpacked`
 // / Program Files), which buried any files Hermes wrote there.
diff --git a/apps/desktop/src/app/settings/toolset-config-panel.tsx b/apps/desktop/src/app/settings/toolset-config-panel.tsx
index f3cee6d3b4d..02281a089b0 100644
--- a/apps/desktop/src/app/settings/toolset-config-panel.tsx
+++ b/apps/desktop/src/app/settings/toolset-config-panel.tsx
@@ -243,6 +243,7 @@ function PostSetupRunner({ toolset, postSetupKey, installed = false, onComplete
   // Guard against overlapping polls / state updates after unmount.
   const activeRef = useRef(false)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     return () => {
       activeRef.current = false
@@ -496,6 +497,7 @@ export function ToolsetConfigPanel({ toolset, onConfiguredChange }: ToolsetConfi
   // Guard the Nous Portal sign-in poll loop against unmount/state updates.
   const mountedRef = useRef(true)
 
+  // eslint-disable-next-line no-restricted-syntax -- mount flag guarding an async poll loop, not an atom mirror
   useEffect(() => {
     mountedRef.current = true
 
@@ -537,6 +539,7 @@ export function ToolsetConfigPanel({ toolset, onConfiguredChange }: ToolsetConfi
   // first fully-configured provider, else the first provider. Without this the
   // panel highlighted the first keyless provider (e.g. Nous Portal) even when
   // the user had already selected another (e.g. DuckDuckGo).
+  // eslint-disable-next-line no-restricted-syntax -- one-shot provider-choice claim flag, not an atom mirror
   useEffect(() => {
     if (providerChoiceClaimedRef.current || activeProvider || providers.length === 0) {
       return
diff --git a/apps/desktop/src/app/settings/voice-provider-fields.tsx b/apps/desktop/src/app/settings/voice-provider-fields.tsx
index 89b2e2dd904..9b3a2cdd1f5 100644
--- a/apps/desktop/src/app/settings/voice-provider-fields.tsx
+++ b/apps/desktop/src/app/settings/voice-provider-fields.tsx
@@ -47,6 +47,7 @@ export function VoiceProviderFields({ section, providerKey }: { section: 'tts' |
   const [config, setConfig] = useState<HermesConfigRecord | null>(null)
   const seeded = useRef(false)
 
+  // eslint-disable-next-line no-restricted-syntax -- one-shot config seed flag, not an atom mirror
   useEffect(() => {
     if (loadedConfig && !seeded.current) {
       seeded.current = true
diff --git a/apps/desktop/src/app/shell/hooks/use-overlay-routing.ts b/apps/desktop/src/app/shell/hooks/use-overlay-routing.ts
index 5d827f349b9..bb92cfd10a9 100644
--- a/apps/desktop/src/app/shell/hooks/use-overlay-routing.ts
+++ b/apps/desktop/src/app/shell/hooks/use-overlay-routing.ts
@@ -24,6 +24,7 @@ export function useOverlayRouting() {
   const starmapOpen = currentView === 'starmap'
   const cronOpen = currentView === 'cron'
   const profilesOpen = currentView === 'profiles'
+  const webhooksOpen = currentView === 'webhooks'
   const chatOpen = currentView === 'chat'
   const overlayOpen = isOverlayView(currentView)
 
@@ -31,6 +32,7 @@ export function useOverlayRouting() {
   // so closing them returns there instead of bouncing to /.
   const returnPathRef = useRef(NEW_CHAT_ROUTE)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!overlayOpen) {
       returnPathRef.current = `${location.pathname}${location.search}${location.hash}`
@@ -82,6 +84,7 @@ export function useOverlayRouting() {
     resetOverlayReturnRoute,
     settingsOpen,
     starmapOpen,
-    toggleCommandCenter
+    toggleCommandCenter,
+    webhooksOpen
   }
 }
diff --git a/apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx b/apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx
index 62e469e8a08..8033e7f7e00 100644
--- a/apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx
+++ b/apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx
@@ -9,7 +9,7 @@ import { GatewayMenuPanel } from '@/app/shell/gateway-menu-panel'
 import { Codicon } from '@/components/ui/codicon'
 import { GlyphSpinner } from '@/components/ui/glyph-spinner'
 import { useI18n } from '@/i18n'
-import { Activity, AlertCircle, Clock, Command, FolderOpen, Hash, Loader2, Terminal } from '@/lib/icons'
+import { Activity, AlertCircle, Clock, Command, FolderOpen, Globe, Hash, Loader2, Terminal } from '@/lib/icons'
 import type { RuntimeReadinessResult } from '@/lib/runtime-readiness'
 import { contextBarLabel, LiveDuration, usageContextLabel } from '@/lib/statusbar'
 import { cn } from '@/lib/utils'
@@ -43,7 +43,7 @@ import {
 } from '@/store/updates'
 import type { StatusResponse, UsageStats } from '@/types/hermes'
 
-import { CRON_ROUTE, SETTINGS_ROUTE } from '../../routes'
+import { CRON_ROUTE, SETTINGS_ROUTE, WEBHOOKS_ROUTE } from '../../routes'
 import type { StatusbarItem } from '../statusbar-controls'
 
 const EMPTY_USAGE = { calls: 0, input: 0, output: 0, total: 0 } as const
@@ -420,6 +420,14 @@ export function useStatusbarItems({
         title: copy.openCron,
         to: CRON_ROUTE,
         variant: 'action'
+      },
+      {
+        icon: <Globe className="size-3" />,
+        id: 'webhooks',
+        label: copy.webhooks,
+        title: copy.openWebhooks,
+        to: WEBHOOKS_ROUTE,
+        variant: 'action'
       }
     ],
     [
diff --git a/apps/desktop/src/app/shell/model-edit-submenu.tsx b/apps/desktop/src/app/shell/model-edit-submenu.tsx
index 742ed304b65..417edd4d222 100644
--- a/apps/desktop/src/app/shell/model-edit-submenu.tsx
+++ b/apps/desktop/src/app/shell/model-edit-submenu.tsx
@@ -13,23 +13,24 @@ import {
 } from '@/components/ui/dropdown-menu'
 import { Switch } from '@/components/ui/switch'
 import { useI18n } from '@/i18n'
-import { normalize } from '@/lib/text'
+import {
+  DEFAULT_REASONING_EFFORT,
+  isThinkingEnabled,
+  REASONING_EFFORTS,
+  resolveReasoningEffort
+} from '@/lib/reasoning-effort'
 import { setModelPreset } from '@/store/model-presets'
 import { notifyError } from '@/store/notifications'
-import { markComposerSelectionManual, setCurrentFastMode, setCurrentReasoningEffort } from '@/store/session'
+import {
+  $defaultReasoningEffort,
+  markComposerSelectionManual,
+  setCurrentFastMode,
+  setCurrentReasoningEffort
+} from '@/store/session'
 import { sessionTileDelegate } from '@/store/session-states'
 
-// Hermes' real reasoning levels (see VALID_REASONING_EFFORTS); `none` is owned
+// Hermes' real reasoning levels live in lib/reasoning-effort; `none` is owned
 // by the Thinking toggle, not the radio.
-const EFFORT_OPTIONS = [
-  { value: 'minimal', labelKey: 'minimal' },
-  { value: 'low', labelKey: 'low' },
-  { value: 'medium', labelKey: 'medium' },
-  { value: 'high', labelKey: 'high' },
-  { value: 'xhigh', labelKey: 'xhigh' },
-  { value: 'max', labelKey: 'max' },
-  { value: 'ultra', labelKey: 'ultra' }
-] as const
 
 /** How "fast" is achieved for a given model — two different mechanisms:
  *  - `param`: the Anthropic/OpenAI `speed=fast` request parameter.
@@ -95,7 +96,20 @@ interface ModelEditSubmenuProps {
   requestGateway: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
 }
 
-export function ModelEditSubmenu({
+export function ModelEditSubmenu(props: ModelEditSubmenuProps) {
+  // The panel mounts one of these per model row; only the hovered row's
+  // submenu is ever open. Keep this wrapper hook-free and render the body as
+  // a CHILD of SubContent so Radix's Presence gate leaves it unrendered until
+  // the sub actually opens — eagerly running the body's hooks/JSX for every
+  // row made opening the menu itself lag on large catalogs.
+  return (
+    <DropdownMenuSubContent className="w-52 p-0" sideOffset={4}>
+      <ModelEditSubmenuBody {...props} />
+    </DropdownMenuSubContent>
+  )
+}
+
+function ModelEditSubmenuBody({
   effort,
   fastControl,
   isActive,
@@ -111,8 +125,9 @@ export function ModelEditSubmenu({
   const activeSessionId = useStore(view.$runtimeId)
   const touchesPrimary = view.kind === 'primary'
 
-  const effortValue = normalizeEffort(effort)
-  const thinkingOn = isThinkingEnabled(effort)
+  const defaultEffort = useStore($defaultReasoningEffort) || DEFAULT_REASONING_EFFORT
+  const effortValue = resolveReasoningEffort(effort, defaultEffort)
+  const thinkingOn = isThinkingEnabled(effort, defaultEffort)
 
   // Editing always records the model's global preset (keyed by provider::model,
   // not per-surface — a tile edit re-applies to that model everywhere); the
@@ -211,66 +226,46 @@ export function ModelEditSubmenu({
   const hasFast = fastControl.kind !== 'none'
   const fastOn = fastControl.kind === 'none' ? false : fastControl.on
 
-  return (
-    <DropdownMenuSubContent className="w-52 p-0" sideOffset={4}>
-      {!hasFast && !reasoning ? (
-        <div className="px-2.5 py-3 text-xs text-(--ui-text-tertiary)">{copy.noOptions}</div>
-      ) : (
+  return !hasFast && !reasoning ? (
+    <div className="px-2.5 py-3 text-xs text-(--ui-text-tertiary)">{copy.noOptions}</div>
+  ) : (
+    <>
+      <DropdownMenuLabel className={dropdownMenuSectionLabel}>{copy.options}</DropdownMenuLabel>
+      {reasoning ? (
+        <DropdownMenuItem className={dropdownMenuRow} onSelect={event => event.preventDefault()}>
+          {copy.thinking}
+          <Switch
+            checked={thinkingOn}
+            className="ml-auto"
+            onCheckedChange={checked => void patchReasoning(checked ? effortValue || defaultEffort : 'none')}
+            size="xs"
+          />
+        </DropdownMenuItem>
+      ) : null}
+      {hasFast ? (
+        <DropdownMenuItem className={dropdownMenuRow} onSelect={event => event.preventDefault()}>
+          {copy.fast}
+          <Switch checked={fastOn} className="ml-auto" onCheckedChange={toggleFast} size="xs" />
+        </DropdownMenuItem>
+      ) : null}
+      {reasoning ? (
         <>
-          <DropdownMenuLabel className={dropdownMenuSectionLabel}>{copy.options}</DropdownMenuLabel>
-          {reasoning ? (
-            <DropdownMenuItem className={dropdownMenuRow} onSelect={event => event.preventDefault()}>
-              {copy.thinking}
-              <Switch
-                checked={thinkingOn}
-                className="ml-auto"
-                onCheckedChange={checked => void patchReasoning(checked ? effortValue || 'medium' : 'none')}
-                size="xs"
-              />
-            </DropdownMenuItem>
-          ) : null}
-          {hasFast ? (
-            <DropdownMenuItem className={dropdownMenuRow} onSelect={event => event.preventDefault()}>
-              {copy.fast}
-              <Switch checked={fastOn} className="ml-auto" onCheckedChange={toggleFast} size="xs" />
-            </DropdownMenuItem>
-          ) : null}
-          {reasoning ? (
-            <>
-              <DropdownMenuSeparator className="mx-0" />
-              <DropdownMenuLabel className={dropdownMenuSectionLabel}>{copy.effort}</DropdownMenuLabel>
-              <DropdownMenuRadioGroup onValueChange={value => void patchReasoning(value)} value={effortValue}>
-                {EFFORT_OPTIONS.map(option => (
-                  <DropdownMenuRadioItem
-                    className={dropdownMenuRow}
-                    key={option.value}
-                    onSelect={event => event.preventDefault()}
-                    value={option.value}
-                  >
-                    {copy[option.labelKey]}
-                  </DropdownMenuRadioItem>
-                ))}
-              </DropdownMenuRadioGroup>
-            </>
-          ) : null}
+          <DropdownMenuSeparator className="mx-0" />
+          <DropdownMenuLabel className={dropdownMenuSectionLabel}>{copy.effort}</DropdownMenuLabel>
+          <DropdownMenuRadioGroup onValueChange={value => void patchReasoning(value)} value={effortValue}>
+            {REASONING_EFFORTS.map(value => (
+              <DropdownMenuRadioItem
+                className={dropdownMenuRow}
+                key={value}
+                onSelect={event => event.preventDefault()}
+                value={value}
+              >
+                {copy[value]}
+              </DropdownMenuRadioItem>
+            ))}
+          </DropdownMenuRadioGroup>
         </>
-      )}
-    </DropdownMenuSubContent>
+      ) : null}
+    </>
   )
 }
-
-function isThinkingEnabled(effort: string): boolean {
-  // Empty = Hermes default (medium) = on; only an explicit "none" is off.
-  return normalize(effort || 'medium') !== 'none'
-}
-
-function normalizeEffort(effort: string): string {
-  const value = normalize(effort || 'medium')
-
-  // Thinking off → no effort selected in the radio group.
-  if (value === 'none') {
-    return ''
-  }
-
-  return EFFORT_OPTIONS.some(option => option.value === value) ? value : 'medium'
-}
diff --git a/apps/desktop/src/app/shell/model-menu-panel.test.tsx b/apps/desktop/src/app/shell/model-menu-panel.test.tsx
index 5a8e1d649b0..e68d3b99a07 100644
--- a/apps/desktop/src/app/shell/model-menu-panel.test.tsx
+++ b/apps/desktop/src/app/shell/model-menu-panel.test.tsx
@@ -124,6 +124,26 @@ describe('ModelMenuPanel MoA presets', () => {
   })
 })
 
+describe('ModelMenuPanel current selection', () => {
+  it('keeps the checkmark on the live SessionView model when a stale options response disagrees', async () => {
+    $currentProvider.set('google')
+    $currentModel.set('gemini-3.1-pro')
+    getGlobalModelOptions.mockResolvedValue({
+      model: 'deepseek-chat',
+      provider: 'deepseek',
+      providers: MOCK_PROVIDERS
+    })
+
+    const { content } = renderPanel()
+
+    const currentRow = (await content.findByText(/Gemini 3\.1 Pro/i)).closest('[role="menuitem"]')
+    const staleRow = content.getByText('Deepseek Chat').closest('[role="menuitem"]')
+
+    expect(currentRow?.querySelector('.codicon-check')).not.toBeNull()
+    expect(staleRow?.querySelector('.codicon-check')).toBeNull()
+  })
+})
+
 describe('ModelMenuPanel provider collapse', () => {
   it('shows all provider models by default (none collapsed)', async () => {
     const { content } = renderPanel()
diff --git a/apps/desktop/src/app/shell/model-menu-panel.tsx b/apps/desktop/src/app/shell/model-menu-panel.tsx
index 9c3c60e5cda..883b9c18063 100644
--- a/apps/desktop/src/app/shell/model-menu-panel.tsx
+++ b/apps/desktop/src/app/shell/model-menu-panel.tsx
@@ -20,12 +20,8 @@ import type { HermesGateway } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { ChevronDown, ChevronRight } from '@/lib/icons'
 import { modelOptionsQueryKey, requestModelOptions } from '@/lib/model-options'
-import {
-  currentPickerSelection,
-  displayModelName,
-  modelDisplayParts,
-  reasoningEffortLabel
-} from '@/lib/model-status-label'
+import { currentPickerSelection, displayModelName, modelDisplayParts } from '@/lib/model-status-label'
+import { DEFAULT_REASONING_EFFORT, reasoningEffortLabel } from '@/lib/reasoning-effort'
 import { normalize } from '@/lib/text'
 import { cn } from '@/lib/utils'
 import { $modelPresets, applyModelPreset, modelPresetKey } from '@/store/model-presets'
@@ -39,6 +35,7 @@ import {
   setModelVisibilityOpen
 } from '@/store/model-visibility'
 import { $collapsedProviders, toggleCollapsedProvider } from '@/store/provider-collapse'
+import { $defaultReasoningEffort } from '@/store/session'
 import type { ModelOptionProvider, ModelOptionsResponse } from '@/types/hermes'
 
 import { ModelEditSubmenu, resolveFastControl } from './model-edit-submenu'
@@ -84,6 +81,7 @@ export function ModelMenuPanel({ gateway, onSelectModel, profile = 'default', re
   const currentProvider = useStore(view.$provider)
   const currentReasoningEffort = useStore(view.$reasoningEffort)
   const modelPresets = useStore($modelPresets)
+  const defaultEffort = useStore($defaultReasoningEffort) || DEFAULT_REASONING_EFFORT
   const visibleModels = useStore($visibleModels)
   const collapsedProviders = useStore($collapsedProviders)
 
@@ -96,7 +94,6 @@ export function ModelMenuPanel({ gateway, onSelectModel, profile = 'default', re
   })
 
   const { model: optionsModel, provider: optionsProvider } = currentPickerSelection(
-    !!activeSessionId,
     { model: currentModel, provider: currentProvider },
     modelOptions.data
   )
@@ -181,7 +178,7 @@ export function ModelMenuPanel({ gateway, onSelectModel, profile = 'default', re
 
     await applyModelPreset(
       {
-        effort: (caps?.reasoning ?? true) ? (preset.effort ?? 'medium') : undefined,
+        effort: (caps?.reasoning ?? true) ? (preset.effort ?? defaultEffort) : undefined,
         fast: (caps?.fast ?? false) ? (preset.fast ?? false) : undefined
       },
       {
@@ -300,7 +297,7 @@ export function ModelMenuPanel({ gateway, onSelectModel, profile = 'default', re
 
                     const meta = [
                       fastControl.kind !== 'none' && fastControl.on ? copy.fast : null,
-                      (caps?.reasoning ?? true) ? reasoningEffortLabel(effEffort) || copy.medium : null
+                      (caps?.reasoning ?? true) ? reasoningEffortLabel(effEffort || defaultEffort) : null
                     ]
                       .filter(Boolean)
                       .join(' ')
diff --git a/apps/desktop/src/app/skills/mcp-tab.tsx b/apps/desktop/src/app/skills/mcp-tab.tsx
index 522261b0e10..cc7c335f3cd 100644
--- a/apps/desktop/src/app/skills/mcp-tab.tsx
+++ b/apps/desktop/src/app/skills/mcp-tab.tsx
@@ -463,6 +463,7 @@ export function McpTab({ gateway }: { gateway: HermesGateway | null }) {
   // in-progress edit — the draft is the user's until they save or reset.
   const draftSeeded = useRef(false)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     // profilePending: config still holds the PREVIOUS profile's record right
     // after a switch — seeding from it would latch the wrong profile's doc.
@@ -525,6 +526,7 @@ export function McpTab({ gateway }: { gateway: HermesGateway | null }) {
   // on a fresh success, errorUpdatedAt on a fresh failure. Releasing on error too
   // means a failed refetch surfaces the retry UI instead of leaving mutations
   // silently no-op forever.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (
       profilePending &&
diff --git a/apps/desktop/src/app/starmap/star-map.tsx b/apps/desktop/src/app/starmap/star-map.tsx
index f16cc9db892..2a23bc2ef5b 100644
--- a/apps/desktop/src/app/starmap/star-map.tsx
+++ b/apps/desktop/src/app/starmap/star-map.tsx
@@ -264,6 +264,7 @@ export function StarMap({
   }, [])
 
   // (Re)build the radial simulation whenever the graph or size changes.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     sizeRef.current = size
 
@@ -299,6 +300,7 @@ export function StarMap({
     }
   }, [graph, invalidate, resetFades, size])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     adjacencyRef.current = adjacency
     memByIdRef.current = memById
@@ -311,12 +313,14 @@ export function StarMap({
     document.fonts?.load('1em "JetBrains Mono"').then(invalidate, () => {})
   }, [invalidate])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     selectedIdRef.current = selectedId
     invalidate()
   }, [invalidate, selectedId])
 
   // A fresh graph resets the scrubber to "fully built" (the idle default).
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     camRadiusRef.current = RING_OUTER
     snapMotionRef.current = false
@@ -362,6 +366,7 @@ export function StarMap({
   )
 
   // Playback: sweep reveal 0 → 1 over SWEEP_MS, then stop (play once).
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!playing) {
       return
@@ -484,6 +489,7 @@ export function StarMap({
 
   // Repaint + repalette when the theme/mode repaints (the shared observer fires
   // after applyTheme rewrites the class + inline vars on <html>).
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     themeDirtyRef.current = true
     invalidate()
@@ -493,6 +499,7 @@ export function StarMap({
   // the window is focused — but each frame is cheap (live scramble + a blit of the
   // cached static layer). The expensive scene only re-renders when invalidate()
   // marks it dirty. Capped to ~30fps; interaction (force) bypasses the cap.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     let raf = 0
     const ANIM_MS = 1000 / 30
@@ -674,6 +681,7 @@ export function StarMap({
   }, [])
 
   // Size the backing canvas (DPR-aware).
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     sizeRef.current = size
     dprRef.current = Math.min(2, window.devicePixelRatio || 1)
diff --git a/apps/desktop/src/app/webhooks/index.tsx b/apps/desktop/src/app/webhooks/index.tsx
new file mode 100644
index 00000000000..c2f86cb29ed
--- /dev/null
+++ b/apps/desktop/src/app/webhooks/index.tsx
@@ -0,0 +1,614 @@
+import { useStore } from '@nanostores/react'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+
+import { PageLoader } from '@/components/page-loader'
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'
+import { Button } from '@/components/ui/button'
+import { ConfirmDialog } from '@/components/ui/confirm-dialog'
+import { CopyButton } from '@/components/ui/copy-button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from '@/components/ui/dialog'
+import { Field } from '@/components/ui/field'
+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 {
+  createWebhook,
+  deleteWebhook,
+  enableWebhooks,
+  getWebhooks,
+  setWebhookEnabled,
+  type WebhookRoute,
+  type WebhooksResponse
+} from '@/hermes'
+import { useI18n } from '@/i18n'
+import { AlertTriangle, Globe, Plus, RefreshCw } from '@/lib/icons'
+import { cn } from '@/lib/utils'
+import { notify, notifyError } from '@/store/notifications'
+import { $profileScope } from '@/store/profile'
+import { runGatewayRestart } from '@/store/system-actions'
+
+import { useRefreshHotkey } from '../hooks/use-refresh-hotkey'
+import {
+  Panel,
+  PanelAddButton,
+  PanelBlock,
+  PanelBody,
+  PanelDetail,
+  PanelEmpty,
+  PanelHeader,
+  PanelList,
+  PanelListRow,
+  PanelMeta,
+  PanelPill,
+  PanelRowMenu,
+  PanelSectionLabel
+} from '../overlays/panel'
+import { ListRow } from '../settings/primitives'
+
+const DELIVER_OPTIONS: readonly string[] = ['log', 'telegram', 'discord', 'slack', 'email', 'github_comment']
+
+interface CreatedWebhook {
+  secret: string
+  url: string
+}
+
+// One affordance for "value + CopyButton": flat, token-backed (no border, no
+// raw literals). DESIGN.md Principle 1 (flat, not boxed) + 4 (tokens, not
+// literals). Reused by the detail URL row and the create-result URL/secret so
+// there is a single copyable-value chrome in this file.
+function CopyValueRow({ copyLabel, mono = true, value }: { copyLabel: string; mono?: boolean; value: string }) {
+  return (
+    <div className="flex items-center gap-1 rounded bg-foreground/5 px-2.5 py-1.5 text-[0.7rem]">
+      <span className={cn('min-w-0 flex-1 truncate text-foreground/80', mono && 'font-mono')}>{value}</span>
+      <CopyButton appearance="icon" buttonSize="icon-sm" label={copyLabel} text={value} />
+    </div>
+  )
+}
+
+interface WebhooksViewProps {
+  onClose: () => void
+}
+
+export function WebhooksView({ onClose }: WebhooksViewProps) {
+  const { t } = useI18n()
+  const w = t.webhooks
+  // Re-load when the active profile changes so REST routes to the right backend.
+  const profileScope = useStore($profileScope)
+  const queryClient = useQueryClient()
+  const queryKey = useMemo(() => ['webhooks', profileScope] as const, [profileScope])
+
+  const [query, setQuery] = useState('')
+  const [enabling, setEnabling] = useState(false)
+  const [restartNeeded, setRestartNeeded] = useState(false)
+  const [restartError, setRestartError] = useState<null | string>(null)
+  const [restarting, setRestarting] = useState(false)
+  // Master/detail: the subscription whose config fills the right pane.
+  const [selectedName, setSelectedName] = useState<null | string>(null)
+
+  const [createOpen, setCreateOpen] = useState(false)
+  const [name, setName] = useState('')
+  const [description, setDescription] = useState('')
+  const [events, setEvents] = useState('')
+  const [deliver, setDeliver] = useState('log')
+  const [deliverOnly, setDeliverOnly] = useState(false)
+  const [prompt, setPrompt] = useState('')
+  const [skills, setSkills] = useState('')
+  const [creating, setCreating] = useState(false)
+  const [created, setCreated] = useState<CreatedWebhook | null>(null)
+
+  const [pendingDelete, setPendingDelete] = useState<null | string>(null)
+
+  const {
+    data,
+    error,
+    isPending: loading,
+    refetch
+  } = useQuery({
+    queryKey,
+    queryFn: getWebhooks
+  })
+
+  // React Query v5 dropped useQuery onError; surface a load failure toast once
+  // per error object instead.
+  useEffect(() => {
+    if (error) {
+      notifyError(error, w.loadFailed)
+    }
+  }, [error, w.loadFailed])
+
+  const enabled = data?.enabled ?? false
+  const subscriptions = useMemo(() => data?.subscriptions ?? [], [data])
+
+  // Pull fresh backend truth into the cache. `silent` swallows the error toast
+  // for post-mutation reconciles (the mutation already reported success/failure).
+  const reload = useCallback(
+    async (silent = false) => {
+      try {
+        await queryClient.invalidateQueries({ queryKey })
+      } catch (err) {
+        if (!silent) {
+          notifyError(err, w.loadFailed)
+        }
+      }
+    },
+    [queryClient, queryKey, w.loadFailed]
+  )
+
+  useRefreshHotkey(() => void refetch())
+
+  const restartGatewayNow = useCallback(async () => {
+    setRestarting(true)
+
+    try {
+      await runGatewayRestart()
+      setRestartNeeded(false)
+      setRestartError(null)
+      // Give the receiver a moment to bind before re-reading state.
+      window.setTimeout(() => void reload(true), 4000)
+    } catch (err) {
+      setRestartNeeded(true)
+      setRestartError(String(err))
+      notifyError(err, w.restartFailed(''))
+    } finally {
+      setRestarting(false)
+    }
+  }, [reload, w])
+
+  const handleEnable = useCallback(async () => {
+    setEnabling(true)
+    setRestartNeeded(false)
+    setRestartError(null)
+
+    try {
+      const result = await enableWebhooks()
+      await reload(true)
+
+      if (result.restart_started) {
+        notify({ kind: 'success', message: w.enabledRestarting })
+        window.setTimeout(() => void reload(true), 4000)
+      } else {
+        const detail = result.restart_error ? `: ${result.restart_error}` : '.'
+        setRestartNeeded(true)
+        setRestartError(w.restartFailed(detail))
+        notify({ kind: 'error', message: w.restartFailed(detail) })
+      }
+    } catch (err) {
+      notifyError(err, w.restartFailed(''))
+    } finally {
+      setEnabling(false)
+    }
+  }, [reload, w])
+
+  const resetForm = useCallback(() => {
+    setName('')
+    setDescription('')
+    setEvents('')
+    setDeliver('log')
+    setDeliverOnly(false)
+    setPrompt('')
+    setSkills('')
+  }, [])
+
+  const closeCreate = useCallback(() => {
+    if (creating) {
+      return
+    }
+
+    setCreateOpen(false)
+    setCreated(null)
+  }, [creating])
+
+  const handleCreate = useCallback(async () => {
+    if (!name.trim()) {
+      notify({ kind: 'error', message: w.nameRequired })
+
+      return
+    }
+
+    setCreating(true)
+
+    try {
+      const eventsList = events
+        .split(',')
+        .map(e => e.trim())
+        .filter(Boolean)
+
+      const skillsList = skills
+        .split(',')
+        .map(s => s.trim())
+        .filter(Boolean)
+
+      const res = await createWebhook({
+        deliver,
+        deliver_only: deliverOnly,
+        description: description.trim() || undefined,
+        events: eventsList.length ? eventsList : undefined,
+        name: name.trim(),
+        prompt: prompt.trim() || undefined,
+        skills: skillsList.length ? skillsList : undefined
+      })
+
+      notify({ kind: 'success', message: w.created })
+      setCreated({ secret: res.secret, url: res.url })
+      resetForm()
+      void reload(true)
+    } catch (err) {
+      notifyError(err, w.createFailed(''))
+    } finally {
+      setCreating(false)
+    }
+  }, [deliver, deliverOnly, description, events, name, prompt, reload, resetForm, skills, w])
+
+  const handleToggle = useCallback(
+    async (subName: string, nextEnabled: boolean) => {
+      // Optimistic cache paint; the invalidate below lets backend truth win.
+      queryClient.setQueryData<WebhooksResponse>(queryKey, current =>
+        current
+          ? {
+              ...current,
+              subscriptions: current.subscriptions.map(s => (s.name === subName ? { ...s, enabled: nextEnabled } : s))
+            }
+          : current
+      )
+
+      try {
+        await setWebhookEnabled(subName, nextEnabled)
+        notify({ kind: 'success', message: nextEnabled ? w.enabled(subName) : w.disabled(subName) })
+        void reload(true)
+      } catch (err) {
+        await reload(true)
+        notifyError(err, w.toggleFailed(subName))
+      }
+    },
+    [queryClient, queryKey, reload, w]
+  )
+
+  // ConfirmDialog owns the pending→done→close beat; throw to surface its inline
+  // error and keep the dialog open. Success toast matches the cron delete idiom
+  // (title + name).
+  const handleDelete = useCallback(async () => {
+    if (!pendingDelete) {
+      return
+    }
+
+    try {
+      await deleteWebhook(pendingDelete)
+      notify({ kind: 'success', title: w.deleted, message: pendingDelete })
+      void reload(true)
+    } catch (err) {
+      notifyError(err, w.deleteFailed(pendingDelete))
+      throw err
+    }
+  }, [pendingDelete, reload, w])
+
+  const visible = useMemo(() => {
+    const q = query.trim().toLowerCase()
+
+    if (!q) {
+      return subscriptions
+    }
+
+    return subscriptions.filter(s =>
+      [s.name, s.description, s.deliver, ...s.events].filter(Boolean).some(v => v.toLowerCase().includes(q))
+    )
+  }, [query, subscriptions])
+
+  // Detail always reflects a concrete sub: the explicitly selected one, else the
+  // first visible row, so the right pane is never empty while subs exist.
+  const selectedSub = useMemo(
+    () => visible.find(s => s.name === selectedName) ?? visible[0] ?? null,
+    [visible, selectedName]
+  )
+
+  const banners = (
+    <>
+      {!enabled && (
+        <Alert className="mb-4" variant="warning">
+          <Globe />
+          <AlertTitle>{w.disabledTitle}</AlertTitle>
+          <AlertDescription>
+            <p>{w.disabledBody}</p>
+            <Button className="mt-1" disabled={enabling} onClick={() => void handleEnable()} size="sm">
+              <Globe />
+              {enabling ? w.enabling : w.enable}
+            </Button>
+          </AlertDescription>
+        </Alert>
+      )}
+
+      {restartNeeded && (
+        <Alert className="mb-4" variant="warning">
+          <AlertTriangle />
+          <AlertDescription>
+            <p>{restartError ?? w.restartNeeded}</p>
+            <Button
+              className="mt-1"
+              disabled={restarting}
+              onClick={() => void restartGatewayNow()}
+              size="sm"
+              variant="secondary"
+            >
+              <RefreshCw />
+              {restarting ? w.restartingGateway : w.restartGateway}
+            </Button>
+          </AlertDescription>
+        </Alert>
+      )}
+    </>
+  )
+
+  return (
+    <Panel onClose={onClose}>
+      {loading ? (
+        <PageLoader label={w.loading} />
+      ) : subscriptions.length === 0 ? (
+        <>
+          {banners}
+          <PanelEmpty
+            action={
+              <Button
+                disabled={!enabled || enabling}
+                onClick={() => {
+                  setCreated(null)
+                  setCreateOpen(true)
+                }}
+                size="sm"
+              >
+                <Plus />
+                {w.newSubscription}
+              </Button>
+            }
+            description={w.empty}
+            icon="globe"
+          />
+        </>
+      ) : (
+        <>
+          <PanelHeader subtitle={w.hint} title={w.subscriptions(subscriptions.length)} />
+          {banners}
+          <PanelBody>
+            <PanelList
+              onSearchChange={setQuery}
+              searchLabel={w.search}
+              searchPlaceholder={w.search}
+              searchValue={query}
+            >
+              {visible.map(sub => (
+                <PanelListRow
+                  active={selectedSub?.name === sub.name}
+                  dotClassName={sub.enabled ? 'bg-emerald-500' : 'bg-muted-foreground/50'}
+                  key={sub.name}
+                  menu={
+                    <PanelRowMenu
+                      items={[
+                        {
+                          icon: sub.enabled ? 'circle-slash' : 'check',
+                          label: sub.enabled ? w.disableRow : w.enableRow,
+                          onSelect: () => void handleToggle(sub.name, !sub.enabled)
+                        },
+                        { icon: 'trash', label: w.delete, onSelect: () => setPendingDelete(sub.name), tone: 'danger' }
+                      ]}
+                    />
+                  }
+                  onSelect={() => setSelectedName(sub.name)}
+                  title={sub.name}
+                />
+              ))}
+              {visible.length === 0 && <p className="px-2 py-4 text-center text-xs text-muted-foreground">{w.empty}</p>}
+              <PanelAddButton
+                label={w.newSubscription}
+                onClick={() => {
+                  setCreated(null)
+                  setCreateOpen(true)
+                }}
+              />
+            </PanelList>
+
+            {selectedSub ? <WebhookDetail sub={selectedSub} /> : <PanelEmpty description={w.empty} icon="search" />}
+          </PanelBody>
+        </>
+      )}
+
+      {/* Create subscription dialog */}
+      <Dialog onOpenChange={open => !open && closeCreate()} open={createOpen}>
+        <DialogContent className="max-w-lg">
+          <DialogHeader>
+            <DialogTitle>{created ? w.createdTitle : w.newSubscription}</DialogTitle>
+            {created && <DialogDescription>{w.createdSecretHint}</DialogDescription>}
+          </DialogHeader>
+
+          {created ? (
+            <div className="grid gap-2">
+              <ListRow action={<CopyValueRow copyLabel={w.copy} value={created.url} />} title={w.webhookUrl} wide />
+              <ListRow action={<CopyValueRow copyLabel={w.copy} value={created.secret} />} title={w.secretOnce} wide />
+              <DialogFooter>
+                <Button onClick={closeCreate} size="sm">
+                  {w.done}
+                </Button>
+              </DialogFooter>
+            </div>
+          ) : (
+            <form
+              className="grid gap-4"
+              onSubmit={e => {
+                e.preventDefault()
+                void handleCreate()
+              }}
+            >
+              <div className="grid items-start gap-4 sm:grid-cols-2">
+                <Field htmlFor="webhook-name" label={w.fieldName}>
+                  <Input
+                    autoFocus
+                    id="webhook-name"
+                    onChange={e => setName(e.target.value)}
+                    placeholder={w.fieldNamePlaceholder}
+                    value={name}
+                  />
+                </Field>
+                <Field htmlFor="webhook-description" label={w.fieldDescription}>
+                  <Input
+                    id="webhook-description"
+                    onChange={e => setDescription(e.target.value)}
+                    placeholder={w.fieldDescriptionPlaceholder}
+                    value={description}
+                  />
+                </Field>
+              </div>
+
+              <Field htmlFor="webhook-prompt" label={w.fieldPrompt}>
+                <Textarea
+                  className="min-h-24"
+                  id="webhook-prompt"
+                  onChange={e => setPrompt(e.target.value)}
+                  placeholder={w.fieldPromptPlaceholder}
+                  value={prompt}
+                />
+              </Field>
+
+              <div className="grid items-start gap-4 sm:grid-cols-2">
+                <Field htmlFor="webhook-events" label={w.fieldEvents}>
+                  <Input
+                    id="webhook-events"
+                    onChange={e => setEvents(e.target.value)}
+                    placeholder={w.fieldEventsPlaceholder}
+                    value={events}
+                  />
+                </Field>
+                <Field htmlFor="webhook-skills" label={w.fieldSkills}>
+                  <Input
+                    id="webhook-skills"
+                    onChange={e => setSkills(e.target.value)}
+                    placeholder={w.fieldSkillsPlaceholder}
+                    value={skills}
+                  />
+                </Field>
+              </div>
+
+              <div className="grid items-start gap-4 sm:grid-cols-2">
+                <Field htmlFor="webhook-deliver" label={w.fieldDeliver}>
+                  <Select onValueChange={setDeliver} value={deliver}>
+                    <SelectTrigger className="h-9 rounded-md" id="webhook-deliver">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {DELIVER_OPTIONS.map(opt => (
+                        <SelectItem key={opt} value={opt}>
+                          {w.deliverOptions[opt] ?? opt}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </Field>
+                <Field htmlFor="webhook-deliver-only" label={w.fieldDeliverOnly}>
+                  <div className="flex h-9 items-center">
+                    <Switch checked={deliverOnly} id="webhook-deliver-only" onCheckedChange={setDeliverOnly} />
+                  </div>
+                </Field>
+              </div>
+
+              <DialogFooter>
+                <Button disabled={creating} size="sm" type="submit">
+                  {creating ? w.creating : w.create}
+                </Button>
+              </DialogFooter>
+            </form>
+          )}
+        </DialogContent>
+      </Dialog>
+
+      <ConfirmDialog
+        busyLabel={w.deleting}
+        cancelLabel={t.common.cancel}
+        confirmLabel={w.delete}
+        description={
+          pendingDelete ? (
+            <>
+              {w.deleteDescPrefix}
+              <span className="font-medium text-foreground">{pendingDelete}</span>
+              {w.deleteDescSuffix}
+            </>
+          ) : null
+        }
+        destructive
+        onClose={() => setPendingDelete(null)}
+        onConfirm={handleDelete}
+        open={pendingDelete !== null}
+        title={w.deleteTitle}
+      />
+    </Panel>
+  )
+}
+
+function WebhookDetail({ sub }: { sub: WebhookRoute }) {
+  const { t } = useI18n()
+  const w = t.webhooks
+
+  return (
+    <PanelDetail>
+      <header className="space-y-3">
+        <div className="flex min-w-0 flex-wrap items-center gap-2">
+          <h3 className="text-[0.95rem] font-semibold tracking-tight text-foreground">{sub.name}</h3>
+          {sub.deliver_only && <PanelPill tone="warn">{w.deliverOnly}</PanelPill>}
+        </div>
+
+        <PanelMeta
+          rows={[
+            { label: w.fieldDeliver, value: w.deliverOptions[sub.deliver] ?? sub.deliver },
+            {
+              label: w.fieldEvents,
+              value:
+                sub.events.length === 0 ? (
+                  w.all
+                ) : (
+                  <span className="flex flex-wrap gap-1">
+                    {sub.events.map(evt => (
+                      <PanelPill key={evt}>{evt}</PanelPill>
+                    ))}
+                  </span>
+                )
+            },
+            ...(sub.skills.length > 0
+              ? [
+                  {
+                    label: w.fieldSkills,
+                    value: (
+                      <span className="flex flex-wrap gap-1">
+                        {sub.skills.map(skill => (
+                          <PanelPill key={skill}>{skill}</PanelPill>
+                        ))}
+                      </span>
+                    )
+                  }
+                ]
+              : [])
+          ]}
+        />
+
+        <CopyValueRow copyLabel={w.copy} value={sub.url} />
+      </header>
+
+      {sub.description ? (
+        <div className="space-y-1.5">
+          <PanelSectionLabel>{w.fieldDescription}</PanelSectionLabel>
+          <p className="text-xs leading-relaxed text-foreground/80">{sub.description}</p>
+        </div>
+      ) : null}
+
+      {sub.prompt ? (
+        <div className="space-y-1.5">
+          <PanelSectionLabel>{w.fieldPrompt}</PanelSectionLabel>
+          <PanelBlock>{sub.prompt}</PanelBlock>
+        </div>
+      ) : null}
+    </PanelDetail>
+  )
+}
diff --git a/apps/desktop/src/components/assistant-ui/directive-text.test.ts b/apps/desktop/src/components/assistant-ui/directive-text.test.ts
index 60c89f18b1e..d5f7074e5d1 100644
--- a/apps/desktop/src/components/assistant-ui/directive-text.test.ts
+++ b/apps/desktop/src/components/assistant-ui/directive-text.test.ts
@@ -36,4 +36,53 @@ describe('hermesDirectiveFormatter.parse', () => {
       { kind: 'text', text: ' the entry point' }
     ])
   })
+
+  it('parses session links with profile/id values', () => {
+    const segments = hermesDirectiveFormatter.parse('see @session:work/20260101_abc123 next')
+
+    expect(segments).toEqual([
+      { kind: 'text', text: 'see ' },
+      { kind: 'mention', type: 'session', label: '20260101…', id: 'work/20260101_abc123' },
+      { kind: 'text', text: ' next' }
+    ])
+  })
+})
+
+describe('inline skill references', () => {
+  const skills = (text: string) =>
+    [...hermesDirectiveFormatter.parse(text)]
+      .filter(segment => segment.kind === 'mention' && segment.type === 'skill')
+      .map(segment => (segment.kind === 'mention' ? segment.id : ''))
+
+  it('keeps a picked skill a chip in the sent message instead of flattening it', () => {
+    expect(skills('please run /clean on this')).toEqual(['/clean'])
+  })
+
+  it('keeps the surrounding prose as text around the chip', () => {
+    const segments = hermesDirectiveFormatter.parse('tidy this with /clean thanks')
+
+    expect(segments).toEqual([
+      { kind: 'text', text: 'tidy this with ' },
+      { kind: 'mention', type: 'skill', label: 'clean', id: '/clean' },
+      { kind: 'text', text: ' thanks' }
+    ])
+  })
+
+  it('leaves file paths and fractions alone', () => {
+    expect(skills('check src/foo/bar')).toEqual([])
+    expect(skills('look at /usr/local/bin')).toEqual([])
+    expect(skills('roughly 3 /4 of it')).toEqual([])
+  })
+
+  it('does not chip a leading slash — that is a command invocation, not prose', () => {
+    expect(skills('/clean')).toEqual([])
+  })
+
+  it('parses a skill chip alongside an @ reference', () => {
+    const mentions = [...hermesDirectiveFormatter.parse('run /clean on @file:`src/a.ts`')].filter(
+      segment => segment.kind === 'mention'
+    )
+
+    expect(mentions.map(segment => (segment.kind === 'mention' ? segment.type : ''))).toEqual(['skill', 'file'])
+  })
 })
diff --git a/apps/desktop/src/components/assistant-ui/directive-text.tsx b/apps/desktop/src/components/assistant-ui/directive-text.tsx
index fe3c8e7f165..317489a96f8 100644
--- a/apps/desktop/src/components/assistant-ui/directive-text.tsx
+++ b/apps/desktop/src/components/assistant-ui/directive-text.tsx
@@ -7,7 +7,11 @@ import { Fragment, useEffect, useMemo, useState } from 'react'
 
 import { ZoomableImage } from '@/components/chat/zoomable-image'
 import { extractEmbeddedImages } from '@/lib/embedded-images'
+import { triggerHaptic } from '@/lib/haptics'
 import { gatewayMediaDataUrl, isRemoteGateway } from '@/lib/media'
+import { useSessionLinkTitle } from '@/lib/session-link-title'
+import { parseSessionRefValue, sessionRefFallbackLabel } from '@/lib/session-refs'
+import { cn } from '@/lib/utils'
 
 const HERMES_REF_TYPES = ['file', 'folder', 'url', 'image', 'tool', 'line', 'terminal', 'session'] as const
 type HermesRefType = (typeof HERMES_REF_TYPES)[number]
@@ -40,11 +44,7 @@ const ICON_PATHS: Record<HermesRefType, string[]> = {
   tool: ['M7 10h3v-3l-3.5 -3.5a6 6 0 0 1 8 8l6 6a2 2 0 0 1 -3 3l-6 -6a6 6 0 0 1 -8 -8l3.5 3.5'],
   line: ['M5 9l14 0', 'M5 15l14 0', 'M11 4l-4 16', 'M17 4l-4 16'],
   terminal: ['M5 7l5 5l-5 5', 'M12 19l7 0'],
-  session: [
-    'M8 9h8',
-    'M8 13h6',
-    'M18 4a3 3 0 0 1 3 3v8a3 3 0 0 1 -3 3h-5l-5 3v-3h-2a3 3 0 0 1 -3 -3v-8a3 3 0 0 1 3 -3z'
-  ]
+  session: ['M4 4h16v2.172a2 2 0 0 1 -.586 1.414l-4.414 4.414v7l-6 2v-8.5l-4.48 -4.928a2 2 0 0 1 -.52 -1.345v-2.227']
 }
 
 const ICON_FALLBACK = ['M8 12a4 4 0 1 0 8 0a4 4 0 1 0 -8 0', 'M16 12v1.5a2.5 2.5 0 0 0 5 0v-1.5a9 9 0 1 0 -5.5 8.28']
@@ -123,9 +123,12 @@ export function slashIconElement(kind: SlashChipKind) {
   return iconElementFromPaths(SLASH_ICON_PATHS[kind])
 }
 
-const DirectiveIcon: FC<{ type: string }> = ({ type }) => (
+const DirectiveIcon: FC<{ type: string; className?: string }> = ({
+  type,
+  className = 'size-3 shrink-0 opacity-80'
+}) => (
   <svg
-    className="size-3 shrink-0 opacity-80"
+    className={className}
     fill="none"
     stroke="currentColor"
     strokeLinecap="round"
@@ -168,6 +171,17 @@ const HERMES_DIRECTIVE_RE = new RegExp(
   'g'
 )
 
+// A skill referenced mid-prose (`clean this up with /clean`). The composer
+// inserts it as a pill, so the sent message renders it as one too rather than
+// flattening back to raw text. Only matches after whitespace — a leading `/`
+// is a command invocation, which never reaches a rendered message as text.
+//
+// Unlike the composer's caret-anchored trigger, this scans finished text, so
+// it must reject a token that continues into a path: `/usr/local/bin` would
+// otherwise chip as `/usr`. `(?![\w-]*\/)` requires the token to end at
+// something other than another slash.
+const SLASH_SKILL_RE = /(?<=\s)\/([a-zA-Z][\w-]*)(?![\w-]*\/)/g
+
 const TRAILING_PUNCTUATION_RE = /[,.;!?]+$/
 
 function unwrapRefValue(raw: string): string {
@@ -266,7 +280,14 @@ function parseDirectiveText(text: string): Unstable_DirectiveSegment[] {
         label: shortLabel(match[1] as HermesRefType, id),
         id
       }
-    })
+    }),
+    ...Array.from(text.matchAll(SLASH_SKILL_RE)).map(match => ({
+      start: match.index ?? 0,
+      end: (match.index ?? 0) + match[0].length,
+      type: 'skill',
+      label: match[1],
+      id: `/${match[1]}`
+    }))
   ]
     .filter(match => match.id)
     .sort((a, b) => a.start - b.start)
@@ -314,12 +335,8 @@ function shortLabel(type: HermesRefType, id: string): string {
     }
   }
 
-  // `@session:<profile>/<id>` — show a short id; the composer chip carries the
-  // friendly title, but once sent the wire form only has the id.
   if (type === 'session') {
-    const sid = id.split('/').filter(Boolean).pop() || id
-
-    return sid.length > 10 ? `${sid.slice(0, 8)}…` : sid
+    return sessionRefFallbackLabel(id)
   }
 
   const tail = id.split(/[\\/]/).filter(Boolean).pop()
@@ -351,19 +368,36 @@ export function DirectiveContent({ text }: { text: string }) {
   const { cleanedText, images } = useMemo(() => safeEmbeddedImages(text ?? ''), [text])
   const segments = useMemo(() => safeDirectiveSegments(cleanedText), [cleanedText])
 
+  // `@image:<path>` directives render as a block-level thumbnail row (like
+  // embedded base64 images below), not inline mid-text — otherwise a large
+  // thumbnail gets wedged between words and breaks the text's line flow.
+  const imageSegments = useMemo(
+    () =>
+      segments.filter(
+        (segment): segment is Extract<Unstable_DirectiveSegment, { kind: 'mention' }> =>
+          segment.kind === 'mention' && segment.type === 'image'
+      ),
+    [segments]
+  )
+
   return (
     <span className="whitespace-pre-line" data-slot="aui_directive-text">
       {segments.map((segment, index) =>
         segment.kind === 'text' ? (
           <Fragment key={`t-${index}`}>{segment.text}</Fragment>
-        ) : segment.type === 'image' ? (
-          <DirectiveImage id={segment.id} key={`img-${index}-${segment.id}`} label={segment.label} />
+        ) : segment.type === 'image' ? null : segment.type === 'session' ? (
+          <SessionRefChip key={`m-${index}-${segment.id}`} label={segment.label} value={segment.id} />
+        ) : segment.type === 'skill' ? (
+          <SlashChip key={`m-${index}-${segment.id}`} kind="skill" label={segment.label} value={segment.id} />
         ) : (
           <DirectiveChip id={segment.id} key={`m-${index}-${segment.id}`} label={segment.label} type={segment.type} />
         )
       )}
-      {images.length > 0 && (
+      {(imageSegments.length > 0 || images.length > 0) && (
         <span className="mt-2 flex flex-wrap gap-2" data-slot="aui_embedded-images">
+          {imageSegments.map((segment, index) => (
+            <DirectiveImage id={segment.id} key={`img-ref-${index}-${segment.id}`} label={segment.label} />
+          ))}
           {images.map((src, index) => (
             <ZoomableImage
               alt=""
@@ -430,7 +464,7 @@ const DirectiveImage: FC<{ id: string; label: string }> = ({ id, label }) => {
   return (
     <ZoomableImage
       alt={label}
-      className="max-h-32 max-w-48 rounded-md border border-border/40 object-contain"
+      className="max-h-48 max-w-full rounded-lg border border-border/60 object-contain"
       draggable={false}
       slot="aui_directive-image"
       src={src}
@@ -438,19 +472,109 @@ const DirectiveImage: FC<{ id: string; label: string }> = ({ id, label }) => {
   )
 }
 
+/** Opens the referenced session as a tab — same as middle-clicking its sidebar
+ *  row. The tile store loads on click, not at import: the composer's rich
+ *  editor pulls this module in, and a static import would boot the profile
+ *  store (and its REST routing) along with it. */
+function openSessionRef(value: string) {
+  const { sessionId } = parseSessionRefValue(value)
+
+  if (!sessionId) {
+    return
+  }
+
+  triggerHaptic('selection')
+  void import('@/store/session-states').then(({ openSessionTile }) => openSessionTile(sessionId, 'center'))
+}
+
+/** A `@session:<profile>/<id>` reference in the user transcript (directive
+ *  segments), rendered as a chip like the other composer refs. Clicking it
+ *  opens the session as a tab. */
+export const SessionRefChip: FC<{
+  label?: string
+  value: string
+}> = ({ label, value }) => {
+  const resolved = useSessionLinkTitle(value, label)
+
+  return <DirectiveChip id={value} label={resolved} onClick={() => openSessionRef(value)} type="session" />
+}
+
+/** A `@session:` reference in assistant markdown (`#session/` links rewritten
+ *  in `preprocessMarkdown`). Reads as an ordinary inline link — the agent wrote
+ *  it mid-sentence — with the funnel icon leading the resolved title. */
+export const SessionRefLink: FC<{
+  label?: string
+  value: string
+}> = ({ label, value }) => {
+  const resolved = useSessionLinkTitle(value, label)
+
+  return (
+    <a
+      className="link-chip font-semibold wrap-anywhere"
+      href="#"
+      onClick={event => {
+        event.preventDefault()
+        event.stopPropagation()
+        openSessionRef(value)
+      }}
+      title={value}
+    >
+      <DirectiveIcon className="mr-1 inline size-[0.82em] align-[-0.08em] opacity-70" type="session" />
+      {resolved}
+    </a>
+  )
+}
+
+/** A skill referenced inside a sent message — the rendered twin of the
+ *  composer's slash pill, so a picked skill stays a chip after send. */
+const SlashChip: FC<{ kind: SlashChipKind; label: string; value: string }> = ({ kind, label, value }) => (
+  <span className={slashChipClass(kind)} data-slot="aui_slash-chip" title={value}>
+    <svg
+      className="size-3 shrink-0 opacity-80"
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth={2}
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      {SLASH_ICON_PATHS[kind].map(d => (
+        <path d={d} key={d} />
+      ))}
+    </svg>
+    <span className="truncate">{label}</span>
+  </span>
+)
+
+/** Inert by default; `onClick` promotes the chip to a real button (session
+ *  refs, which open the session they name). */
 const DirectiveChip: FC<{
   type: string
   label: string
   id: string
-}> = ({ type, label, id }) => (
-  <span
-    className={DIRECTIVE_CHIP_CLASS}
-    data-directive-id={id}
-    data-directive-type={type}
-    data-slot="aui_directive-chip"
-    title={id}
-  >
-    <DirectiveIcon type={type} />
-    <span className="truncate">{label}</span>
-  </span>
-)
+  onClick?: () => void
+}> = ({ type, label, id, onClick }) => {
+  const body = (
+    <>
+      <DirectiveIcon type={type} />
+      <span className="truncate">{label}</span>
+    </>
+  )
+
+  const props = {
+    className: cn(DIRECTIVE_CHIP_CLASS, onClick && 'cursor-pointer transition-colors hover:text-foreground'),
+    'data-directive-id': id,
+    'data-directive-type': type,
+    'data-slot': 'aui_directive-chip',
+    title: id
+  }
+
+  return onClick ? (
+    <button {...props} onClick={onClick} type="button">
+      {body}
+    </button>
+  ) : (
+    <span {...props}>{body}</span>
+  )
+}
diff --git a/apps/desktop/src/components/assistant-ui/markdown-text.session.test.tsx b/apps/desktop/src/components/assistant-ui/markdown-text.session.test.tsx
new file mode 100644
index 00000000000..6c7b02cf7af
--- /dev/null
+++ b/apps/desktop/src/components/assistant-ui/markdown-text.session.test.tsx
@@ -0,0 +1,66 @@
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { __resetSessionLinkTitleCache } from '@/lib/session-link-title'
+import { $sessions } from '@/store/session'
+import type { SessionInfo } from '@/types/hermes'
+
+import { MarkdownTextContent } from './markdown-text'
+
+function makeSession(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    ended_at: null,
+    id: '20260101_abc123',
+    input_tokens: 0,
+    is_active: false,
+    last_active: 1_000,
+    message_count: 1,
+    model: null,
+    output_tokens: 0,
+    preview: null,
+    profile: 'work',
+    source: 'cli',
+    started_at: 1_000,
+    title: 'Branch plan',
+    tool_call_count: 0,
+    ...overrides
+  }
+}
+
+afterEach(() => {
+  cleanup()
+  $sessions.set([])
+  __resetSessionLinkTitleCache()
+})
+
+// End-to-end for the agent-authored path: a bare ref in assistant markdown has
+// to survive preprocessMarkdown -> Streamdown -> MarkdownLink and come out as
+// an inline link titled after the session, not as literal text.
+describe('MarkdownTextContent session refs', () => {
+  it('renders an agent-written @session ref as a link showing the session title', async () => {
+    $sessions.set([makeSession()])
+
+    render(<MarkdownTextContent isRunning={false} text="Context lives in @session:work/20260101_abc123 today." />)
+
+    const link = await screen.findByTitle('work/20260101_abc123')
+
+    expect(link.tagName).toBe('A')
+    expect(link.textContent).toBe('Branch plan')
+    expect(screen.queryByText(/@session:/)).toBeNull()
+  })
+
+  it('falls back to a short id when the session is unknown', async () => {
+    render(<MarkdownTextContent isRunning={false} text="See @session:work/20260101_abc123 for context." />)
+
+    const link = await screen.findByTitle('work/20260101_abc123')
+
+    expect(link.textContent).toBe('20260101…')
+  })
+
+  it('leaves a ref inside inline code as literal text', () => {
+    render(<MarkdownTextContent isRunning={false} text="Write `@session:work/20260101_abc123` to link a chat." />)
+
+    expect(screen.getByText('@session:work/20260101_abc123')).toBeTruthy()
+    expect(screen.queryByTitle('work/20260101_abc123')).toBeNull()
+  })
+})
diff --git a/apps/desktop/src/components/assistant-ui/markdown-text.tsx b/apps/desktop/src/components/assistant-ui/markdown-text.tsx
index f5d78f53133..f641890ffd4 100644
--- a/apps/desktop/src/components/assistant-ui/markdown-text.tsx
+++ b/apps/desktop/src/components/assistant-ui/markdown-text.tsx
@@ -30,8 +30,10 @@ import {
   resolveMediaDisplaySrc
 } from '@/lib/media'
 import { previewTargetFromMarkdownHref } from '@/lib/preview-targets'
+import { sessionRefFromMarkdownHref } from '@/lib/session-refs'
 import { cn } from '@/lib/utils'
 
+import { SessionRefLink } from './directive-text'
 import { detectEmbed, extractAlert, MarkdownAlert, RichCodeBlock, UrlEmbed } from './embeds'
 
 // Math rendering plugin (KaTeX). Configured once at module scope — the
@@ -98,7 +100,7 @@ function OpenMediaButton({ kind, path }: { kind: 'audio' | 'video'; path: string
   return (
     <span className="block">
       <button
-        className="mt-2 bg-transparent text-xs font-medium text-muted-foreground underline underline-offset-4 decoration-current/20 hover:text-foreground"
+        className="mt-2 link-chip bg-transparent text-xs font-medium text-muted-foreground hover:text-foreground"
         onClick={open}
         type="button"
       >
@@ -194,7 +196,7 @@ function MediaAttachment({ path }: { path: string }) {
   return (
     <span className="wrap-anywhere">
       <a
-        className="font-semibold text-foreground underline underline-offset-4 decoration-current/20 wrap-anywhere"
+        className="link-chip font-semibold wrap-anywhere"
         href="#"
         onClick={event => {
           event.preventDefault()
@@ -233,15 +235,18 @@ function MarkdownLink({ children, className, href, ...props }: ComponentProps<'a
     return <PreviewAttachment source="explicit-link" target={previewTarget} />
   }
 
+  const sessionRef = sessionRefFromMarkdownHref(href)
+
+  if (sessionRef) {
+    return <SessionRefLink value={sessionRef} />
+  }
+
   const target = href ? normalizeExternalUrl(href) : href
 
   if (!target || !/^https?:\/\//i.test(target)) {
     return (
       <a
-        className={cn(
-          'font-semibold text-foreground underline underline-offset-4 decoration-current/20 wrap-anywhere',
-          className
-        )}
+        className={cn('link-chip font-semibold wrap-anywhere', className)}
         href={href}
         rel="noopener noreferrer"
         target="_blank"
@@ -316,7 +321,7 @@ function MarkdownImage({ className, src, alt, ...props }: ComponentProps<'img'>)
       <span className="my-2 block text-sm text-muted-foreground">
         Couldn&apos;t load {name}.{' '}
         <button
-          className="bg-transparent font-medium text-foreground underline underline-offset-4 decoration-current/20 hover:text-foreground"
+          className="link-chip bg-transparent font-medium text-foreground hover:text-foreground"
           onClick={open}
           type="button"
         >
diff --git a/apps/desktop/src/components/assistant-ui/session-ref-open.test.tsx b/apps/desktop/src/components/assistant-ui/session-ref-open.test.tsx
new file mode 100644
index 00000000000..de3674f529c
--- /dev/null
+++ b/apps/desktop/src/components/assistant-ui/session-ref-open.test.tsx
@@ -0,0 +1,43 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { __resetSessionLinkTitleCache } from '@/lib/session-link-title'
+
+import { DirectiveContent } from './directive-text'
+import { MarkdownTextContent } from './markdown-text'
+
+const openSessionTile = vi.fn()
+
+vi.mock('@/store/session-states', () => ({
+  openSessionTile: (...args: unknown[]) => openSessionTile(...args)
+}))
+
+afterEach(() => {
+  cleanup()
+  openSessionTile.mockClear()
+  __resetSessionLinkTitleCache()
+})
+
+// Both surfaces render a session ref differently — an inline link in agent
+// prose, a chip in the user's own message — but either one opens the session
+// it names, the way its sidebar row would.
+describe('session refs open the session', () => {
+  it('opens the session from an agent-written link', async () => {
+    render(<MarkdownTextContent isRunning={false} text="Picked up in @session:work/20260101_abc123 last night." />)
+
+    fireEvent.click(await screen.findByTitle('work/20260101_abc123'))
+
+    await vi.waitFor(() => expect(openSessionTile).toHaveBeenCalledWith('20260101_abc123', 'center'))
+  })
+
+  it('opens the session from a chip in the user transcript', async () => {
+    render(<DirectiveContent text="pick up @session:work/20260101_abc123 please" />)
+
+    const chip = screen.getByTitle('work/20260101_abc123')
+
+    expect(chip.tagName).toBe('BUTTON')
+    fireEvent.click(chip)
+
+    await vi.waitFor(() => expect(openSessionTile).toHaveBeenCalledWith('20260101_abc123', 'center'))
+  })
+})
diff --git a/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx b/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
index d578710b3d1..ac0b42423e9 100644
--- a/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/message-parts.tsx
@@ -74,9 +74,7 @@ const ThinkingDisclosure: FC<{
   const isPreview = pending && userOpen === null
 
   // While the preview is live, pin the scroll container to the bottom on
-  // every content growth so the latest tokens are always visible. Combined
-  // with the top mask in styles.css, this reads as text settling in from
-  // below while older lines fade out at the top.
+  // every content growth so the latest tokens are always visible.
   useEffect(() => {
     if (!isPreview) {
       return
@@ -134,7 +132,7 @@ const ThinkingDisclosure: FC<{
             // and inherits the disclosure-level opacity fade defined in
             // styles.css (~0.67 at rest, 1 on hover/focus).
             'mt-0.5 w-full min-w-0 max-w-full overflow-hidden wrap-anywhere pb-1',
-            isPreview && 'thinking-preview max-h-40'
+            isPreview && 'max-h-40'
           )}
           ref={scrollRef}
         >
diff --git a/apps/desktop/src/components/assistant-ui/thread/timeline-data.test.ts b/apps/desktop/src/components/assistant-ui/thread/timeline-data.test.ts
index 0c2918aea59..b24f5391a87 100644
--- a/apps/desktop/src/components/assistant-ui/thread/timeline-data.test.ts
+++ b/apps/desktop/src/components/assistant-ui/thread/timeline-data.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { activeTimelineIndex, deriveTimelineEntries, timelinePreview } from './timeline-data'
+import { activeTimelineIndex, deriveTimelineEntries, sameTimelineEntries, timelinePreview } from './timeline-data'
 
 describe('timelinePreview', () => {
   it('collapses whitespace to a single line', () => {
@@ -39,6 +39,33 @@ describe('deriveTimelineEntries', () => {
   })
 })
 
+describe('sameTimelineEntries', () => {
+  const rail = [
+    { id: 'u1', preview: 'first' },
+    { id: 'u2', preview: 'second' }
+  ]
+
+  it('treats an identical derivation as unchanged, so the memo can reuse it', () => {
+    expect(sameTimelineEntries(rail, [...rail.map(e => ({ ...e }))])).toBe(true)
+  })
+
+  it('detects a changed preview, id, or length', () => {
+    expect(sameTimelineEntries(rail, [rail[0], { id: 'u2', preview: 'edited' }])).toBe(false)
+    expect(sameTimelineEntries(rail, [rail[0], { id: 'u9', preview: 'second' }])).toBe(false)
+    expect(sameTimelineEntries(rail, [rail[0]])).toBe(false)
+  })
+
+  it('is stable when a filtered-out prompt joins the transcript', () => {
+    const withNoise = deriveTimelineEntries([
+      { id: 'u1', role: 'user', text: 'first' },
+      { id: 'u2', role: 'user', text: 'second' },
+      { id: 'u3', role: 'user', text: '[IMPORTANT: Background process 7 finished]' }
+    ])
+
+    expect(sameTimelineEntries(rail, withNoise)).toBe(true)
+  })
+})
+
 describe('activeTimelineIndex', () => {
   it('returns the last prompt scrolled to or above the top edge', () => {
     expect(activeTimelineIndex([-400, -10, 320])).toBe(1)
diff --git a/apps/desktop/src/components/assistant-ui/thread/timeline-data.ts b/apps/desktop/src/components/assistant-ui/thread/timeline-data.ts
index e52d1d7c780..35dbb8f14cd 100644
--- a/apps/desktop/src/components/assistant-ui/thread/timeline-data.ts
+++ b/apps/desktop/src/components/assistant-ui/thread/timeline-data.ts
@@ -46,6 +46,20 @@ export function deriveTimelineEntries(messages: readonly TimelineSourceMessage[]
   return entries
 }
 
+/** Do two derivations describe the same rail? Lets a rebuild hand back the
+ *  PREVIOUS array so an unchanged transcript costs zero re-renders. */
+export function sameTimelineEntries(a: readonly TimelineEntry[], b: readonly TimelineEntry[]): boolean {
+  if (a === b) {
+    return true
+  }
+
+  if (a.length !== b.length) {
+    return false
+  }
+
+  return a.every((entry, index) => entry.id === b[index].id && entry.preview === b[index].preview)
+}
+
 /** Last user prompt at/above the viewport top (with slack); else first rendered. */
 export function activeTimelineIndex(offsets: readonly (number | null)[], slack: number = 8): number {
   let active = -1
diff --git a/apps/desktop/src/components/assistant-ui/thread/timeline-idle.test.tsx b/apps/desktop/src/components/assistant-ui/thread/timeline-idle.test.tsx
new file mode 100644
index 00000000000..58ed16529ad
--- /dev/null
+++ b/apps/desktop/src/components/assistant-ui/thread/timeline-idle.test.tsx
@@ -0,0 +1,166 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import type { ReactNode } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+/**
+ * The timeline must do NO work it can't currently show. Two gates are proven
+ * here by rendering the real component and counting the work it performs:
+ *
+ *  - a background (kept-alive but hidden) tab derives nothing and subscribes
+ *    to nothing — the transcript selector is never even called;
+ *  - an unhovered rail builds its ticks but not the popover's rows.
+ *
+ * The prompt-id selector is also asserted to be content-blind, which is what
+ * keeps a streaming assistant reply from re-deriving previews per token.
+ */
+
+interface FakeMessage {
+  content: unknown
+  id: string
+  role: string
+}
+
+const selectorCalls = vi.fn()
+const transcriptReads = vi.fn()
+let messages: FakeMessage[] = []
+
+vi.mock('@assistant-ui/react', () => ({
+  useAui: () => ({
+    thread: () => ({
+      getState: () => {
+        transcriptReads()
+
+        return { messages }
+      }
+    })
+  }),
+  useAuiState: (selector: (state: { thread: { messages: FakeMessage[] } }) => unknown) => {
+    selectorCalls()
+
+    return selector({ thread: { messages } })
+  }
+}))
+
+let paneActive = true
+
+vi.mock('@/components/pane-shell/pane-visibility', () => ({
+  usePaneVisible: () => paneActive
+}))
+
+vi.mock('@/lib/haptics', () => ({ triggerHaptic: () => {} }))
+
+const { ThreadTimeline } = await import('./timeline')
+
+const userTurn = (id: string, text: string): FakeMessage => ({
+  content: [{ text, type: 'text' }],
+  id,
+  role: 'user'
+})
+
+const transcript = (count: number): FakeMessage[] =>
+  Array.from({ length: count }, (_, i) => userTurn(`u${i}`, `prompt ${i}`))
+
+const renderTimeline = (ui: ReactNode = <ThreadTimeline />) => render(ui)
+
+afterEach(() => {
+  cleanup()
+  selectorCalls.mockClear()
+  transcriptReads.mockClear()
+  paneActive = true
+  messages = []
+})
+
+describe('ThreadTimeline in a background tab', () => {
+  it('renders nothing and never reads the transcript', () => {
+    paneActive = false
+    messages = transcript(6)
+
+    const { container } = renderTimeline()
+
+    expect(container.querySelector('[data-slot="thread-timeline"]')).toBeNull()
+    expect(selectorCalls).not.toHaveBeenCalled()
+    expect(transcriptReads).not.toHaveBeenCalled()
+  })
+
+  it('renders the rail once its pane becomes the visible tab', () => {
+    messages = transcript(6)
+
+    const { container } = renderTimeline()
+
+    expect(container.querySelector('[data-slot="thread-timeline"]')).not.toBeNull()
+    expect(selectorCalls).toHaveBeenCalled()
+  })
+})
+
+describe('ThreadTimeline popover', () => {
+  it('builds no rows until the rail is hovered', () => {
+    messages = transcript(6)
+
+    const { container } = renderTimeline()
+    const popover = container.querySelector('[data-slot="thread-timeline-popover"]')
+
+    // The shell renders (it owns the fade transition); its rows do not.
+    expect(popover).not.toBeNull()
+    expect(popover?.querySelectorAll('button')).toHaveLength(0)
+    expect(screen.queryByText('prompt 0')).toBeNull()
+  })
+
+  it('builds the rows on hover and keeps them for the close fade', () => {
+    messages = transcript(6)
+
+    const { container } = renderTimeline()
+    const rail = container.querySelector<HTMLElement>('[data-slot="thread-timeline"]')!
+
+    fireEvent.mouseEnter(rail)
+
+    const popover = container.querySelector('[data-slot="thread-timeline-popover"]')
+    expect(popover?.querySelectorAll('button')).toHaveLength(6)
+
+    fireEvent.mouseLeave(rail)
+
+    // Still mounted — the popover fades out, it does not pop out of existence.
+    expect(popover?.querySelectorAll('button')).toHaveLength(6)
+  })
+})
+
+describe('ThreadTimeline below the threshold', () => {
+  it('renders nothing for a short thread', () => {
+    messages = transcript(2)
+
+    const { container } = renderTimeline()
+
+    expect(container.querySelector('[data-slot="thread-timeline"]')).toBeNull()
+  })
+})
+
+describe('ThreadTimeline while a reply streams', () => {
+  it('does not re-derive the rail as assistant content grows', () => {
+    messages = [...transcript(6), { content: [{ text: 'th', type: 'text' }], id: 'a1', role: 'assistant' }]
+
+    const { rerender } = renderTimeline()
+    const derivations = transcriptReads.mock.calls.length
+
+    // A token lands: the assistant message's content changes, the user prompt
+    // ids do not — so the memo's change signal is untouched and the previews
+    // are never rebuilt.
+    messages = [
+      ...messages.slice(0, -1),
+      { content: [{ text: 'thinking…', type: 'text' }], id: 'a1', role: 'assistant' }
+    ]
+    rerender(<ThreadTimeline />)
+
+    expect(transcriptReads.mock.calls.length).toBe(derivations)
+  })
+
+  it('re-derives once a new prompt is sent', () => {
+    messages = transcript(6)
+
+    const { rerender } = renderTimeline()
+    const derivations = transcriptReads.mock.calls.length
+
+    messages = [...messages, userTurn('u6', 'prompt 6')]
+    rerender(<ThreadTimeline />)
+
+    expect(transcriptReads.mock.calls.length).toBeGreaterThan(derivations)
+  })
+})
diff --git a/apps/desktop/src/components/assistant-ui/thread/timeline.test.ts b/apps/desktop/src/components/assistant-ui/thread/timeline.test.ts
new file mode 100644
index 00000000000..ced51f60f19
--- /dev/null
+++ b/apps/desktop/src/components/assistant-ui/thread/timeline.test.ts
@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { ownViewport } from './timeline'
+
+/**
+ * Several chat surfaces are mounted at once — side by side in a split, and
+ * stacked as kept-alive inactive tabs. A timeline scrolls its OWN thread.
+ */
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+const surface = (id: string, hidden = false) => `
+  <div ${hidden ? 'data-pane-hidden' : ''}>
+    <div data-session-anchor="${id}">
+      <div data-slot="aui_thread-viewport" id="viewport-${id}"></div>
+      <div data-slot="thread-timeline" id="timeline-${id}"></div>
+    </div>
+  </div>
+`
+
+describe('ownViewport', () => {
+  it('resolves the viewport of the surface the timeline lives in', () => {
+    document.body.innerHTML = surface('workspace') + surface('session-tile:b')
+
+    expect(ownViewport(document.getElementById('timeline-session-tile:b'))?.id).toBe('viewport-session-tile:b')
+    expect(ownViewport(document.getElementById('timeline-workspace'))?.id).toBe('viewport-workspace')
+  })
+
+  it('ignores a kept-alive tab that matches first', () => {
+    document.body.innerHTML = surface('workspace', true) + surface('session-tile:b')
+
+    expect(ownViewport(document.getElementById('timeline-session-tile:b'))?.id).toBe('viewport-session-tile:b')
+  })
+
+  it('falls back to the document when there is no surface around it', () => {
+    document.body.innerHTML = '<div data-slot="aui_thread-viewport" id="viewport-lone"></div>'
+
+    expect(ownViewport(null)?.id).toBe('viewport-lone')
+  })
+})
diff --git a/apps/desktop/src/components/assistant-ui/thread/timeline.tsx b/apps/desktop/src/components/assistant-ui/thread/timeline.tsx
index 18b09c63fe3..9dc2c94b3ce 100644
--- a/apps/desktop/src/components/assistant-ui/thread/timeline.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/timeline.tsx
@@ -1,12 +1,14 @@
-import { useAuiState } from '@assistant-ui/react'
+import { useAui, useAuiState } from '@assistant-ui/react'
 import { type FC, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
+import { usePaneVisible } from '@/components/pane-shell/pane-visibility'
 import { triggerHaptic } from '@/lib/haptics'
 import { cn } from '@/lib/utils'
 
 import {
   activeTimelineIndex,
   deriveTimelineEntries,
+  sameTimelineEntries,
   type TimelineEntry,
   type TimelineSourceMessage
 } from './timeline-data'
@@ -101,8 +103,15 @@ function jumpScroll(viewport: HTMLElement, top: number, duration = 170): void {
   jumpRaf = requestAnimationFrame(step)
 }
 
-function scrollToPrompt(id: string) {
-  const viewport = document.querySelector<HTMLElement>(VIEWPORT)
+// A timeline belongs to ONE chat surface, and several are mounted at once — side
+// by side in a split, and stacked (hidden but kept alive) as inactive tabs. Walk
+// up to this timeline's own surface before looking for the viewport; a
+// document-wide lookup scrolls somebody else's thread.
+export const ownViewport = (root: HTMLElement | null): HTMLElement | null =>
+  (root?.closest('[data-session-anchor]') ?? document).querySelector<HTMLElement>(VIEWPORT)
+
+function scrollToPrompt(root: HTMLElement | null, id: string) {
+  const viewport = ownViewport(root)
   const node = viewport?.querySelector<HTMLElement>(`[data-message-id="${CSS.escape(id)}"]`)
 
   if (!viewport || !node) {
@@ -115,30 +124,95 @@ function scrollToPrompt(id: string) {
   jumpScroll(viewport, Math.max(0, top))
 }
 
-/** Right-edge prompt rail — hover previews, click to jump. ≥4 user turns only. */
+/**
+ * Right-edge prompt rail — hover previews, click to jump. ≥4 user turns only.
+ *
+ * Everything here is DEFERRED until it can actually be seen. A chat surface
+ * stays mounted while its tab is in the background (keep-alive, see
+ * pane-visibility.ts), and a background thread keeps streaming, so a naive
+ * timeline would re-derive previews and re-measure prompt offsets all day for
+ * a rail nobody is looking at. Four gates, cheapest first:
+ *
+ *  1. INACTIVE PANE → render null and subscribe to nothing. The transcript
+ *     selector, the scroll listener, and the popover markup all stand down.
+ *  2. ACTIVE BUT UNHOVERED → the ticks paint, but the popover's rows are not
+ *     built at all; the previews only exist once the pointer opens it.
+ *  3. BELOW THE THRESHOLD → the rail renders null, so the measure effect never
+ *     touches layout for it.
+ *  4. FOLLOWING THE BOTTOM → the active prompt is the last one by definition,
+ *     answered from data instead of a rect walk (see compute() below).
+ */
 export const ThreadTimeline: FC = () => {
-  const sourceSignature = useAuiState(s => {
-    const rows: TimelineSourceMessage[] = []
+  // Cheapest possible gate, and it must come first: an inactive tab returns
+  // before any of the work below is even declared.
+  return usePaneVisible() ? <ActiveThreadTimeline /> : null
+}
+
+/** Derived prompt rail for a VISIBLE surface. Split out so the hook body — and
+ *  the transcript subscription it opens — never runs for a background tab. */
+const ActiveThreadTimeline: FC = () => {
+  // Cheap in the selector, expensive only when it changes: the ids alone tell
+  // us whether the RAIL changed. Prompt text is immutable once sent, and an
+  // edit rewinds the transcript (dropping every id after it) and re-appends a
+  // fresh message id — so a preview can never go stale behind a stable id.
+  // Streaming an assistant reply churns that message's content on every token
+  // and leaves this string untouched, which is the whole point.
+  const promptIds = useAuiState(s => {
+    let ids = ''
 
     for (const message of s.thread.messages) {
-      if (message.role !== 'user') {
-        continue
+      if (message.role === 'user') {
+        ids += `${message.id}\n`
       }
-
-      rows.push({ id: message.id, role: 'user', text: userPromptText(message.content) })
     }
 
-    return JSON.stringify(rows)
+    return ids
   })
 
-  const entries = useMemo(
-    () => deriveTimelineEntries(JSON.parse(sourceSignature) as TimelineSourceMessage[]),
-    [sourceSignature]
-  )
+  // `promptIds` is the change signal; the transcript is read imperatively when
+  // it fires, so the selector above never pays for text extraction. The client
+  // goes through a ref so the memo keys on the SIGNAL alone — an accessor whose
+  // identity churned would otherwise re-derive every render, which is exactly
+  // the streaming cost this is here to avoid.
+  const aui = useAui()
+  const auiRef = useRef(aui)
+  auiRef.current = aui
+
+  const previousRef = useRef<TimelineEntry[]>([])
+
+  const entries = useMemo(() => {
+    const rows: TimelineSourceMessage[] = []
+
+    for (const message of auiRef.current.thread().getState().messages) {
+      if (message.role === 'user') {
+        rows.push({ id: message.id, role: 'user', text: userPromptText(message.content) })
+      }
+    }
+
+    const next = deriveTimelineEntries(rows)
+
+    // Hand back the PREVIOUS array when nothing user-visible moved. Blank and
+    // background-notification prompts are filtered out, so a new id can leave
+    // the rail identical — without this, that re-renders both subtrees and
+    // restarts the measure effect for no visible change.
+    if (sameTimelineEntries(previousRef.current, next)) {
+      return previousRef.current
+    }
+
+    previousRef.current = next
+
+    return next
+    // promptIds is the intentional re-eval TRIGGER, not a value the derivation
+    // reads (the transcript comes off the ref) — same shape as ChatRoutesSurface's
+    // gatewayState memo in app/contrib/controller.tsx.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [promptIds])
 
   const [activeIndex, setActiveIndex] = useState(0)
   const [open, setOpen] = useState(false)
   const closeTimerRef = useRef<number | undefined>(undefined)
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const jump = useCallback((id: string) => scrollToPrompt(rootRef.current, id), [])
 
   // Hover sync lives on the DOM, not in React state — the tick and its popover
   // row are siblings in different subtrees, so a shared index-keyed paint() lights
@@ -176,9 +250,15 @@ export const ThreadTimeline: FC = () => {
   useEffect(() => () => window.clearTimeout(closeTimerRef.current), [])
 
   useEffect(() => {
-    const viewport = document.querySelector<HTMLElement>(VIEWPORT)
+    // Below the threshold the rail renders null, so measuring prompt offsets
+    // buys nothing — bail before touching layout at all.
+    if (entries.length < MIN_ENTRIES) {
+      return
+    }
 
-    if (!viewport || entries.length === 0) {
+    const viewport = ownViewport(rootRef.current)
+
+    if (!viewport) {
       return
     }
 
@@ -187,6 +267,17 @@ export const ThreadTimeline: FC = () => {
     const compute = () => {
       raf = 0
 
+      // Pinned to the bottom (the entire streaming steady-state): the active
+      // prompt is simply the last one. Skipping the walk matters — it reads a
+      // rect per user message per scroll frame, and interleaved with React's
+      // streaming style writes each read forces a full reflow (the single
+      // hottest frame in the multitab profile).
+      if (viewport.dataset.following === 'true') {
+        setActiveIndex(prev => (prev === entries.length - 1 ? prev : entries.length - 1))
+
+        return
+      }
+
       const top = viewport.getBoundingClientRect().top
 
       const offsets = entries.map(entry => {
@@ -236,20 +327,15 @@ export const ThreadTimeline: FC = () => {
       data-suppress-pane-reveal=""
       onMouseEnter={keepOpen}
       onMouseLeave={closeSoon}
+      ref={rootRef}
       role="navigation"
     >
-      <TimelineTicks
-        activeIndex={activeIndex}
-        entries={entries}
-        onHover={paint}
-        onJump={scrollToPrompt}
-        tickRefs={tickRefs}
-      />
+      <TimelineTicks activeIndex={activeIndex} entries={entries} onHover={paint} onJump={jump} tickRefs={tickRefs} />
       <TimelinePopover
         activeIndex={activeIndex}
         entries={entries}
         onHover={paint}
-        onJump={scrollToPrompt}
+        onJump={jump}
         open={open}
         rowRefs={rowRefs}
       />
@@ -264,29 +350,44 @@ const TimelinePopover: FC<{
   onJump: (id: string) => void
   open: boolean
   rowRefs: React.RefObject<(HTMLButtonElement | null)[]>
-}> = ({ activeIndex, entries, onHover, onJump, open, rowRefs }) => (
-  <div
-    className={cn(
-      POPOVER_SHELL,
-      open ? 'pointer-events-auto opacity-100 translate-x-0' : 'pointer-events-none translate-x-1 opacity-0'
-    )}
-    data-slot="thread-timeline-popover"
-  >
-    {entries.map((entry, index) => (
-      <button
-        aria-label={entry.preview}
-        className={cn(ROW_CLASS, index === activeIndex && 'bg-(--ui-row-active-background) text-foreground')}
-        key={entry.id}
-        onClick={() => onJump(entry.id)}
-        ref={listRef(rowRefs, index)}
-        type="button"
-        {...hoverProps(index, onHover)}
-      >
-        <span className="block w-full min-w-0 truncate font-medium leading-snug text-foreground">{entry.preview}</span>
-      </button>
-    ))}
-  </div>
-)
+}> = ({ activeIndex, entries, onHover, onJump, open, rowRefs }) => {
+  // The rail is the always-visible part; this list is not built until the
+  // pointer first opens it. The SHELL always renders so the opacity/translate
+  // transition has a node to animate — only the N rows are deferred, and they
+  // stay mounted afterwards so the close fade still has content.
+  const [everOpened, setEverOpened] = useState(open)
+
+  if (open && !everOpened) {
+    setEverOpened(true)
+  }
+
+  return (
+    <div
+      className={cn(
+        POPOVER_SHELL,
+        open ? 'pointer-events-auto opacity-100 translate-x-0' : 'pointer-events-none translate-x-1 opacity-0'
+      )}
+      data-slot="thread-timeline-popover"
+    >
+      {everOpened &&
+        entries.map((entry, index) => (
+          <button
+            aria-label={entry.preview}
+            className={cn(ROW_CLASS, index === activeIndex && 'bg-(--ui-row-active-background) text-foreground')}
+            key={entry.id}
+            onClick={() => onJump(entry.id)}
+            ref={listRef(rowRefs, index)}
+            type="button"
+            {...hoverProps(index, onHover)}
+          >
+            <span className="block w-full min-w-0 truncate font-medium leading-snug text-foreground">
+              {entry.preview}
+            </span>
+          </button>
+        ))}
+    </div>
+  )
+}
 
 const TimelineTicks: FC<{
   activeIndex: number
diff --git a/apps/desktop/src/components/assistant-ui/thread/user-edit-composer.tsx b/apps/desktop/src/components/assistant-ui/thread/user-edit-composer.tsx
index 9015e9eee66..b29e13493ef 100644
--- a/apps/desktop/src/components/assistant-ui/thread/user-edit-composer.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/user-edit-composer.tsx
@@ -158,6 +158,7 @@ export const UserEditComposer: FC<UserEditComposerProps> = ({ cwd, gateway, sess
     [aui, rememberInitialDraft]
   )
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     draftRef.current = draft
 
diff --git a/apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts b/apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts
index 8437dfee423..5c6fd8c9b03 100644
--- a/apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts
+++ b/apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts
@@ -180,6 +180,10 @@ const TOOL_META: Record<ToolTitleKey, ToolMetaSpec> = {
     icon: 'files',
     tone: 'file'
   },
+  memory: {
+    icon: 'brain',
+    tone: 'agent'
+  },
   patch: { icon: 'edit', tone: 'file' },
   read_file: { icon: 'file', tone: 'file' },
   search_files: {
@@ -672,10 +676,12 @@ function toolErrorText(part: ToolPart, result: Record<string, unknown>): string
   // stage's code, etc. — all routinely produce useful output and aren't
   // failures. Only treat it as an error when the command produced no real
   // output to show; otherwise render the output normally (not red).
+  // `output_preview` counts as output: background-process polls report their
+  // text under that name, so omitting it painted healthy `process` rows red.
   const exit = numberValue(result.exit_code)
 
   if (exit !== null && exit !== 0) {
-    const hasOutput = Boolean(firstStringField(result, ['output', 'stdout', 'stderr'])?.trim())
+    const hasOutput = Boolean(firstStringField(result, ['output', 'stdout', 'stderr', 'output_preview'])?.trim())
 
     return hasOutput ? '' : `Command failed with exit code ${exit}.`
   }
@@ -688,7 +694,15 @@ function toolStatus(part: ToolPart, resultRecord: Record<string, unknown>): Tool
     return 'running'
   }
 
-  return toolErrorText(part, resultRecord) ? 'error' : 'success'
+  if (!toolErrorText(part, resultRecord)) {
+    return 'success'
+  }
+
+  // A rejected memory write is a budget negotiation, not a failure: the store
+  // refuses an over-limit batch and the agent immediately retries a smaller
+  // one. Painting the row destructive-red puts an alarm next to routine
+  // bookkeeping the user never has to act on. Amber says "noted" instead.
+  return part.toolName === 'memory' ? 'warning' : 'error'
 }
 
 function durationLabel(resultRecord: Record<string, unknown>): string | undefined {
@@ -1009,6 +1023,13 @@ function toolSubtitle(
     return url ? hostnameOf(url) : 'Fetched webpage'
   }
 
+  if (toolName === 'memory') {
+    // The raw payload is bookkeeping the user never needs: usage counters, a
+    // note telling the model not to retry, and the full operations array. The
+    // human-readable line is the only part worth showing.
+    return firstStringField(resultRecord, ['message', 'error'])
+  }
+
   if (toolName === 'cronjob') {
     return cronjobSubtitle(argsRecord, resultRecord)
   }
@@ -1091,6 +1112,12 @@ function toolDetailText(
     }
   }
 
+  if (part.toolName === 'memory') {
+    // Same reasoning as toolSubtitle: without this the generic fallback dumps
+    // the whole args + result payload into the expanded row.
+    return firstStringField(resultRecord, ['message', 'error'])
+  }
+
   if (isFileEditTool(part.toolName)) {
     if (inlineDiffFromResult(part.result)) {
       return ''
diff --git a/apps/desktop/src/components/assistant-ui/tool/fallback.test.ts b/apps/desktop/src/components/assistant-ui/tool/fallback.test.ts
index 16855afc73b..0d844d30221 100644
--- a/apps/desktop/src/components/assistant-ui/tool/fallback.test.ts
+++ b/apps/desktop/src/components/assistant-ui/tool/fallback.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 
-import { shouldBoundToolGroup, technicalTrace, UNBOUNDABLE_TOOLS } from './fallback'
+import { isUnboundableTool, shouldBoundToolGroup, technicalTrace } from './fallback'
+import { isFileEditTool } from './fallback-model'
 
 describe('shouldBoundToolGroup', () => {
   it('bounds long runs of ordinary tool calls', () => {
@@ -16,10 +17,34 @@ describe('shouldBoundToolGroup', () => {
   })
 })
 
-describe('UNBOUNDABLE_TOOLS', () => {
+describe('isUnboundableTool', () => {
   it('exempts clarify forms and generated images from the window', () => {
-    expect(UNBOUNDABLE_TOOLS.has('clarify')).toBe(true)
-    expect(UNBOUNDABLE_TOOLS.has('image_generate')).toBe(true)
+    expect(isUnboundableTool('clarify')).toBe(true)
+    expect(isUnboundableTool('image_generate')).toBe(true)
+  })
+
+  it('exempts tools whose body is a code block the user reads', () => {
+    expect(isUnboundableTool('execute_code')).toBe(true)
+    expect(isUnboundableTool('read_file')).toBe(true)
+  })
+
+  // The window clips a diff to a ~2-row viewport, so every tool that renders
+  // one has to be exempt. Derived from isFileEditTool rather than re-listed,
+  // so a newly supported edit tool can't be exempt in one place and clipped
+  // in the other.
+  it('exempts every file-edit tool, so diffs are never clipped', () => {
+    for (const toolName of ['edit_file', 'patch', 'write_file']) {
+      expect(isFileEditTool(toolName)).toBe(true)
+      expect(isUnboundableTool(toolName)).toBe(true)
+    }
+  })
+
+  // Console output is a log tail: the last lines are the ones that matter,
+  // which is exactly what the bounded window pins. Keeping it boundable is
+  // what stops the exemption from swallowing the feature whole.
+  it('still bounds console output and other ordinary rows', () => {
+    expect(isUnboundableTool('terminal')).toBe(false)
+    expect(isUnboundableTool('web_search')).toBe(false)
   })
 })
 
diff --git a/apps/desktop/src/components/assistant-ui/tool/fallback.tsx b/apps/desktop/src/components/assistant-ui/tool/fallback.tsx
index 4a8e2574955..1ba2fd25a46 100644
--- a/apps/desktop/src/components/assistant-ui/tool/fallback.tsx
+++ b/apps/desktop/src/components/assistant-ui/tool/fallback.tsx
@@ -26,6 +26,7 @@ import { ZoomableImage } from '@/components/chat/zoomable-image'
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
 import { CopyButton } from '@/components/ui/copy-button'
+import { DisclosureCaret } from '@/components/ui/disclosure-caret'
 import { FadeText } from '@/components/ui/fade-text'
 import { FileTypeIcon } from '@/components/ui/file-type-icon'
 import { GlyphSpinner } from '@/components/ui/glyph-spinner'
@@ -96,6 +97,44 @@ const TOOL_EXPANDED_SHELL_CLASS = 'rounded-[0.3125rem] border border-(--ui-strok
 
 const TOOL_SECTION_PRE_CLASS = cn(TOOL_SECTION_SURFACE_CLASS, 'font-mono text-[0.7rem] leading-relaxed')
 
+// Raw args/result dump — reference material, so a notch smaller than a body.
+const TOOL_PAYLOAD_PRE_CLASS = cn(TOOL_SECTION_SURFACE_CLASS, 'font-mono text-[0.65rem] leading-relaxed')
+
+/**
+ * Technical-mode raw payload, behind a chevron disclosure.
+ *
+ * Collapsed by default — in technical mode every tool row carries one, and
+ * expanding them all buries the transcript. Uses `DisclosureCaret` rather than
+ * a native `<details>`, whose marker is a browser-drawn triangle matching
+ * nothing else here.
+ */
+function ToolPayloadDisclosure({ args, result }: { args: unknown; result: unknown }) {
+  const [open, setOpen] = useState(false)
+
+  return (
+    // `py-0.5` tops up the parent's `p-1.5` to an even block on both edges.
+    <div className="max-w-full py-0.5">
+      <button
+        aria-expanded={open}
+        className={cn(
+          TOOL_SECTION_LABEL_CLASS,
+          'mb-0 flex items-center gap-1 bg-transparent transition-colors hover:text-(--ui-text-secondary)'
+        )}
+        onClick={() => setOpen(value => !value)}
+        type="button"
+      >
+        <DisclosureCaret className="text-(--ui-text-tertiary)" open={open} size="0.625rem" />
+        Tool payload
+      </button>
+      {open && (
+        <pre className={cn(TOOL_PAYLOAD_PRE_CLASS, 'mt-1 whitespace-pre-wrap wrap-anywhere')}>
+          {technicalTrace(args, result)}
+        </pre>
+      )}
+    </div>
+  )
+}
+
 interface ToolStatusCopy {
   statusDone: string
   statusError: string
@@ -616,19 +655,7 @@ function ToolEntry({ part }: ToolEntryProps) {
                 )}
               </div>
             ))}
-          {toolViewMode === 'technical' && !(isFileEdit && view.inlineDiff) && (
-            <pre className={cn(TOOL_SECTION_PRE_CLASS, 'whitespace-pre-wrap wrap-anywhere')}>
-              {technicalTrace(part.args, part.result)}
-            </pre>
-          )}
-          {toolViewMode === 'technical' && isFileEdit && view.inlineDiff && (
-            <details className="max-w-full">
-              <summary className={cn(TOOL_SECTION_LABEL_CLASS, 'mb-0 cursor-pointer')}>Tool payload</summary>
-              <pre className={cn(TOOL_SECTION_PRE_CLASS, 'mt-1 whitespace-pre-wrap wrap-anywhere')}>
-                {technicalTrace(part.args, part.result)}
-              </pre>
-            </details>
-          )}
+          {toolViewMode === 'technical' && <ToolPayloadDisclosure args={part.args} result={part.result} />}
         </div>
       )}
     </div>
@@ -673,10 +700,30 @@ function TerminalTranscript({ command, exitCode }: TerminalTranscriptProps) {
 // auto-scrolling window; fewer than this stays a plain inline stack.
 const TOOL_GROUP_SCROLL_THRESHOLD = 3
 
-// Tools whose body (an interactive form, a full-size image) must never be
-// trapped behind the window's max-height + fade mask. A run holding any of
-// them stays a plain, fully-visible stack no matter how long it is.
-export const UNBOUNDABLE_TOOLS = new Set(['clarify', 'image_generate'])
+// Tools whose body (an interactive form, a full-size image, a syntax-
+// highlighted code/diff block) must never be trapped behind the window's
+// max-height + fade mask. A run holding any of them stays a plain, fully-
+// visible stack no matter how long it is.
+//
+// A row rendered by ToolEntry carries `data-tool-row`, so once the user
+// expands it the `:has([data-tool-row][data-tool-open])` rule in styles.css
+// lifts the cap on its own. That escape hatch is why most tools are safe to
+// bound. These are the ones it cannot reach:
+//
+//   - `clarify` / `image_generate` render their own components and never emit
+//     `data-tool-row`, so no amount of expanding frees them.
+//   - the code tools *do* emit it, but their body is a code block the user
+//     reads rather than a one-line status — peering at a diff through a
+//     ~2-row viewport until you think to expand it is the bug. Console output
+//     (`terminal`) stays boundable: it's a log tail, and the last lines are
+//     the ones that matter, which is exactly what the window pins.
+const CODE_BODY_TOOLS = ['execute_code', 'read_file']
+
+const UNBOUNDABLE_TOOLS = new Set(['clarify', 'image_generate', ...CODE_BODY_TOOLS])
+
+export function isUnboundableTool(toolName: string): boolean {
+  return UNBOUNDABLE_TOOLS.has(toolName) || isFileEditTool(toolName)
+}
 
 export function shouldBoundToolGroup(childCount: number, hasUnboundable: boolean) {
   return childCount >= TOOL_GROUP_SCROLL_THRESHOLD && !hasUnboundable
@@ -761,7 +808,7 @@ export const ToolGroupSlot: FC<PropsWithChildren<{ endIndex: number; startIndex:
   const hasUnboundable = useAuiState(s =>
     s.message.parts
       .slice(Math.max(0, startIndex), endIndex + 1)
-      .some(part => part.type === 'tool-call' && UNBOUNDABLE_TOOLS.has(part.toolName))
+      .some(part => part.type === 'tool-call' && isUnboundableTool(part.toolName))
   )
 
   const enterRef = useEnterAnimation(messageRunning, `tool-group:${messageId}:${startIndex}`)
diff --git a/apps/desktop/src/components/boot-failure-reauth.ts b/apps/desktop/src/components/boot-failure-reauth.ts
index 68044575213..703f3f74585 100644
--- a/apps/desktop/src/components/boot-failure-reauth.ts
+++ b/apps/desktop/src/components/boot-failure-reauth.ts
@@ -1,4 +1,5 @@
 import type { DesktopAuthProvider, DesktopConnectionConfig } from '@/global'
+import { deriveRemoteAuthProviderShape } from '@/lib/desktop-remote-auth'
 
 // Pure helpers for the boot-failure overlay's remote-reauth branch. Kept out
 // of the .tsx so they can be unit-tested without a React/jsdom render (the
@@ -136,18 +137,7 @@ export function deriveProviderShape(providers: DesktopAuthProvider[] | null | un
   isPassword: boolean
   providerLabel: string
 } {
-  const list = providers ?? []
-
-  if (list.length === 0) {
-    return { isPassword: false, providerLabel: 'your identity provider' }
-  }
-
-  const isPassword = list.every(p => Boolean(p.supportsPassword))
-
-  const providerLabel =
-    list.length === 1 ? list[0].displayName || list[0].name : list.map(p => p.displayName || p.name).join(' / ')
-
-  return { isPassword, providerLabel }
+  return deriveRemoteAuthProviderShape(providers)
 }
 
 // Button copy for the remote sign-in action.
diff --git a/apps/desktop/src/components/chat/activity-timer.ts b/apps/desktop/src/components/chat/activity-timer.ts
index 533dc5b373c..afb27fb02f3 100644
--- a/apps/desktop/src/components/chat/activity-timer.ts
+++ b/apps/desktop/src/components/chat/activity-timer.ts
@@ -40,6 +40,7 @@ export function useElapsedSeconds(active = true, timerKey?: string): number {
     lastKey.current = timerKey
   }
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (!active) {
       return
diff --git a/apps/desktop/src/components/chat/code-editor.tsx b/apps/desktop/src/components/chat/code-editor.tsx
index 0059ed62163..c38a9c60b8a 100644
--- a/apps/desktop/src/components/chat/code-editor.tsx
+++ b/apps/desktop/src/components/chat/code-editor.tsx
@@ -209,6 +209,7 @@ export function CodeEditor({
   onSaveRef.current = onSave
   formatJsonRef.current = formatJson
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const host = hostRef.current
 
diff --git a/apps/desktop/src/components/chat/compact-markdown.tsx b/apps/desktop/src/components/chat/compact-markdown.tsx
index ed3389464a4..eedd6ad18ef 100644
--- a/apps/desktop/src/components/chat/compact-markdown.tsx
+++ b/apps/desktop/src/components/chat/compact-markdown.tsx
@@ -2,7 +2,7 @@ import type { ComponentProps, ElementType, FC } from 'react'
 import { memo } from 'react'
 import { Streamdown } from 'streamdown'
 
-import { ExternalLink, ExternalLinkIcon } from '@/lib/external-link'
+import { ExternalLink } from '@/lib/external-link'
 import { cn } from '@/lib/utils'
 
 // Compact markdown renderer for tool detail bodies. Same Streamdown pipeline
@@ -42,20 +42,15 @@ function tagged<T extends keyof typeof TAG_CLASSES>(Tag: T) {
 function MarkdownAnchor({ children, className, href, ...rest }: ComponentProps<'a'>) {
   if (!href || !/^https?:\/\//i.test(href)) {
     return (
-      <a
-        className={cn('font-medium underline underline-offset-4 decoration-current/20', className)}
-        href={href}
-        {...rest}
-      >
+      <a className={cn('link-chip font-medium', className)} href={href} {...rest}>
         {children}
       </a>
     )
   }
 
   return (
-    <ExternalLink className={cn('decoration-current/20', className)} href={href} showExternalIcon={false}>
+    <ExternalLink className={className} href={href}>
       {children}
-      <ExternalLinkIcon />
     </ExternalLink>
   )
 }
diff --git a/apps/desktop/src/components/chat/generated-image-result.tsx b/apps/desktop/src/components/chat/generated-image-result.tsx
index 66d3d38072d..32cb453c69c 100644
--- a/apps/desktop/src/components/chat/generated-image-result.tsx
+++ b/apps/desktop/src/components/chat/generated-image-result.tsx
@@ -96,7 +96,7 @@ export const GeneratedImage: FC<{ aspectRatio?: string; result?: unknown }> = ({
   if (failed && image) {
     return (
       <a
-        className="mt-2 inline-block font-semibold text-foreground underline underline-offset-4 decoration-current/20 wrap-anywhere"
+        className="mt-2 link-chip inline-block font-semibold wrap-anywhere"
         href="#"
         onClick={event => {
           event.preventDefault()
diff --git a/apps/desktop/src/components/chat/image-generation-placeholder.tsx b/apps/desktop/src/components/chat/image-generation-placeholder.tsx
index 26806847311..3f0e5a16c6a 100644
--- a/apps/desktop/src/components/chat/image-generation-placeholder.tsx
+++ b/apps/desktop/src/components/chat/image-generation-placeholder.tsx
@@ -266,6 +266,7 @@ export const DiffusionCanvas: FC = () => {
 
   useResizeObserver(fitToContainer, canvasRef)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const probe = document.createElement('span')
     probe.style.cssText = 'position:absolute;width:0;height:0;visibility:hidden;pointer-events:none'
@@ -287,6 +288,7 @@ export const DiffusionCanvas: FC = () => {
     }
   }, [])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const canvas = canvasRef.current
     const ctx = canvas?.getContext('2d')
diff --git a/apps/desktop/src/components/chat/preview-attachment.tsx b/apps/desktop/src/components/chat/preview-attachment.tsx
index 9cc90dff53e..a9e02a3d3e4 100644
--- a/apps/desktop/src/components/chat/preview-attachment.tsx
+++ b/apps/desktop/src/components/chat/preview-attachment.tsx
@@ -31,6 +31,7 @@ export function PreviewAttachment({ source = 'manual', target }: { source?: Prev
   cwdRef.current = cwd
   targetRef.current = target
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     mountedRef.current = true
 
@@ -40,6 +41,7 @@ export function PreviewAttachment({ source = 'manual', target }: { source?: Prev
     }
   }, [])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     requestTokenRef.current += 1
     setOpening(false)
diff --git a/apps/desktop/src/components/desktop-install-overlay.test.tsx b/apps/desktop/src/components/desktop-install-overlay.test.tsx
new file mode 100644
index 00000000000..1e4e384cb11
--- /dev/null
+++ b/apps/desktop/src/components/desktop-install-overlay.test.tsx
@@ -0,0 +1,576 @@
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { DesktopBootstrapEvent, DesktopBootstrapState, DesktopConnectionProbeResult } from '@/global'
+
+import { DesktopInstallOverlay } from './desktop-install-overlay'
+
+function bootstrapState(overrides: Partial<DesktopBootstrapState> = {}): DesktopBootstrapState {
+  return {
+    active: false,
+    manifest: null,
+    stages: {},
+    error: null,
+    log: [],
+    startedAt: null,
+    completedAt: null,
+    setupChoice: null,
+    unsupportedPlatform: null,
+    ...overrides
+  }
+}
+
+function installDesktopMock(state: DesktopBootstrapState) {
+  const bootstrapListeners = new Set<(event: DesktopBootstrapEvent) => void>()
+
+  const desktop = {
+    getBootstrapState: vi.fn().mockResolvedValue(state),
+    onBootstrapEvent: vi.fn((listener: (event: DesktopBootstrapEvent) => void) => {
+      bootstrapListeners.add(listener)
+
+      return () => bootstrapListeners.delete(listener)
+    }),
+    continueBootstrapLocal: vi.fn().mockResolvedValue({ ok: true }),
+    probeConnectionConfig: vi.fn(),
+    testConnectionConfig: vi.fn(),
+    applyConnectionConfig: vi.fn(),
+    oauthLoginConnectionConfig: vi.fn(),
+    openExternal: vi.fn(),
+    emitBootstrapEvent: (event: DesktopBootstrapEvent) => {
+      for (const listener of bootstrapListeners) {
+        listener(event)
+      }
+    }
+  }
+
+  Object.defineProperty(window, 'hermesDesktop', {
+    configurable: true,
+    value: desktop
+  })
+
+  return desktop
+}
+
+// Resolve the instant a node commits, via MutationObserver rather than
+// waitFor's polling timer. findBy* only settles on a timer tick, by which
+// point React has already drained its passive effects — that hides any bug
+// living in the window between paint and effect.
+function whenPresent(text: string): Promise<HTMLElement> {
+  return new Promise(resolve => {
+    const existing = screen.queryByText(text)
+
+    if (existing) {
+      resolve(existing)
+
+      return
+    }
+
+    const observer = new MutationObserver(() => {
+      const node = screen.queryByText(text)
+
+      if (node) {
+        observer.disconnect()
+        resolve(node)
+      }
+    })
+
+    observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+  })
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks()
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  Reflect.deleteProperty(window, 'hermesDesktop')
+})
+
+describe('DesktopInstallOverlay first-run setup', () => {
+  it('shows the remote/local choice without installer progress', async () => {
+    installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'win32', activeRoot: 'C:\\Users\\me\\AppData\\Local\\hermes\\hermes-agent' }
+      })
+    )
+
+    render(<DesktopInstallOverlay />)
+
+    expect(await screen.findByText('Set up Hermes Desktop')).toBeTruthy()
+    expect(screen.getByText('Connect to existing Hermes')).toBeTruthy()
+    expect(screen.getByText('Install Hermes locally')).toBeTruthy()
+    expect(screen.queryByText(/steps complete/i)).toBeNull()
+    expect(screen.queryByText(/Fetching installer manifest/i)).toBeNull()
+  })
+
+  it('continues local bootstrap only when Install Hermes locally is selected', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'win32', activeRoot: 'C:\\Users\\me\\AppData\\Local\\hermes\\hermes-agent' }
+      })
+    )
+
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click(await screen.findByText('Install Hermes locally'))
+
+    expect(desktop.continueBootstrapLocal).toHaveBeenCalledTimes(1)
+    expect(screen.getByText('Set up Hermes Desktop')).toBeTruthy()
+
+    act(() => {
+      desktop.emitBootstrapEvent({ type: 'manifest', protocolVersion: 1, stages: [] })
+    })
+
+    await waitFor(() => expect(screen.queryByText('Set up Hermes Desktop')).toBeNull())
+    expect(screen.getByText(/Fetching installer manifest/i)).toBeTruthy()
+  })
+
+  it('surfaces a recoverable error when the local-bootstrap bridge is unavailable', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'win32', activeRoot: 'C:\\Users\\me\\AppData\\Local\\hermes\\hermes-agent' }
+      })
+    )
+
+    desktop.continueBootstrapLocal = undefined as never
+    render(<DesktopInstallOverlay />)
+
+    const install = (await screen.findByText('Install Hermes locally')).closest('button') as HTMLButtonElement
+    fireEvent.click(install)
+
+    expect(
+      await screen.findByText('Local installation could not start. Restart Hermes Desktop and try again.')
+    ).toBeTruthy()
+    expect(install.disabled).toBe(false)
+  })
+
+  it('keeps the local-start error when the first snapshot commits under the click', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'win32', activeRoot: 'C:\\Users\\me\\AppData\\Local\\hermes\\hermes-agent' }
+      })
+    )
+
+    desktop.continueBootstrapLocal = undefined as never
+    render(<DesktopInstallOverlay />)
+
+    // Click the instant the choice paints, before React drains the passive
+    // effect that reacts to the first snapshot. A loaded runner hits this
+    // window by accident; observing the DOM directly hits it every time.
+    const install = (await whenPresent('Install Hermes locally')).closest('button') as HTMLButtonElement
+    fireEvent.click(install)
+
+    await act(async () => {
+      await Promise.resolve()
+    })
+
+    expect(screen.queryByText('Local installation could not start. Restart Hermes Desktop and try again.')).toBeTruthy()
+  })
+
+  it('clears a stale local-start error when a repair presents a different root', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'win32', activeRoot: 'C:\\Users\\me\\AppData\\Local\\hermes\\hermes-agent' }
+      })
+    )
+
+    desktop.continueBootstrapLocal = undefined as never
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click((await screen.findByText('Install Hermes locally')).closest('button') as HTMLButtonElement)
+    expect(
+      await screen.findByText('Local installation could not start. Restart Hermes Desktop and try again.')
+    ).toBeTruthy()
+
+    act(() => {
+      desktop.emitBootstrapEvent({
+        type: 'setup-choice',
+        active: false,
+        platform: 'win32',
+        activeRoot: 'C:\\Users\\me\\AppData\\Local\\hermes\\hermes-agent-repaired'
+      })
+    })
+
+    expect(screen.queryByText('Local installation could not start. Restart Hermes Desktop and try again.')).toBeNull()
+  })
+
+  it('opens the remote connection form from the first-run choice', async () => {
+    installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'linux', activeRoot: '/home/me/.hermes/hermes-agent' }
+      })
+    )
+
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click(await screen.findByText('Connect to existing Hermes'))
+
+    expect(await screen.findByText('Gateway URL')).toBeTruthy()
+    expect(screen.getByText('Test connection')).toBeTruthy()
+    expect(screen.getByText('Apply and reconnect')).toBeTruthy()
+  })
+
+  it('returns from the remote connection form to the first-run choice', async () => {
+    installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'linux', activeRoot: '/home/me/.hermes/hermes-agent' }
+      })
+    )
+
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click(await screen.findByText('Connect to existing Hermes'))
+    expect(await screen.findByText('Gateway URL')).toBeTruthy()
+
+    fireEvent.click(screen.getByText('Back'))
+
+    expect(await screen.findByText('Set up Hermes Desktop')).toBeTruthy()
+    expect(screen.getByText('Install Hermes locally')).toBeTruthy()
+  })
+
+  it('requires a successful token connection test before applying remote config', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'linux', activeRoot: '/home/me/.hermes/hermes-agent' }
+      })
+    )
+
+    desktop.probeConnectionConfig.mockResolvedValue({
+      authMode: 'token',
+      baseUrl: 'https://gateway.example.com/hermes',
+      error: null,
+      providers: [],
+      reachable: true,
+      version: '0.17.0'
+    })
+    desktop.testConnectionConfig.mockResolvedValue({
+      baseUrl: 'https://gateway.example.com/hermes',
+      ok: true,
+      version: '0.17.0'
+    })
+    desktop.applyConnectionConfig.mockImplementation(async () => {
+      desktop.emitBootstrapEvent({ type: 'dismissed' })
+
+      return { mode: 'remote' }
+    })
+
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click(await screen.findByText('Connect to existing Hermes'))
+    fireEvent.change(await screen.findByPlaceholderText('https://gateway.example.com/hermes'), {
+      target: { value: 'https://gateway.example.com/hermes' }
+    })
+
+    const apply = screen.getByText('Apply and reconnect').closest('button') as HTMLButtonElement
+    expect(apply.disabled).toBe(true)
+
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 550))
+    })
+
+    fireEvent.change(await screen.findByPlaceholderText('Paste session token'), {
+      target: { value: 'session-secret' }
+    })
+    fireEvent.click(screen.getByText('Test connection'))
+
+    await waitFor(() => {
+      expect(desktop.testConnectionConfig).toHaveBeenCalledWith({
+        mode: 'remote',
+        remoteAuthMode: 'token',
+        remoteToken: 'session-secret',
+        remoteUrl: 'https://gateway.example.com/hermes'
+      })
+    })
+
+    await screen.findByText('Connected to https://gateway.example.com/hermes (0.17.0).')
+    expect(apply.disabled).toBe(false)
+
+    fireEvent.click(screen.getByText('Apply and reconnect'))
+
+    await waitFor(() => {
+      expect(desktop.applyConnectionConfig).toHaveBeenCalledWith({
+        mode: 'remote',
+        remoteAuthMode: 'token',
+        remoteToken: 'session-secret',
+        remoteUrl: 'https://gateway.example.com/hermes'
+      })
+    })
+    await waitFor(() => expect(screen.queryByText('Gateway URL')).toBeNull())
+  })
+
+  it('ignores a completed probe after the gateway URL becomes invalid', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'linux', activeRoot: '/home/me/.hermes/hermes-agent' }
+      })
+    )
+
+    let resolveProbe: ((result: DesktopConnectionProbeResult) => void) | undefined
+
+    const pendingProbe = new Promise<DesktopConnectionProbeResult>(resolve => {
+      resolveProbe = resolve
+    })
+
+    desktop.probeConnectionConfig.mockReturnValue(pendingProbe)
+
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click(await screen.findByText('Connect to existing Hermes'))
+    const urlInput = await screen.findByPlaceholderText('https://gateway.example.com/hermes')
+    fireEvent.change(urlInput, { target: { value: 'https://gateway.example.com/hermes' } })
+
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 550))
+    })
+    expect(desktop.probeConnectionConfig).toHaveBeenCalledTimes(1)
+
+    fireEvent.change(urlInput, { target: { value: 'not-a-url' } })
+    await act(async () => {
+      resolveProbe?.({
+        authMode: 'token',
+        baseUrl: 'https://gateway.example.com/hermes',
+        error: null,
+        providers: [],
+        reachable: true,
+        version: '0.17.0'
+      })
+      await pendingProbe
+    })
+
+    expect(screen.queryByPlaceholderText('Paste session token')).toBeNull()
+    expect((screen.getByText('Test connection').closest('button') as HTMLButtonElement).disabled).toBe(true)
+    expect((screen.getByText('Apply and reconnect').closest('button') as HTMLButtonElement).disabled).toBe(true)
+  })
+
+  it('does not enable Apply when credentials change during a connection test', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'linux', activeRoot: '/home/me/.hermes/hermes-agent' }
+      })
+    )
+
+    desktop.probeConnectionConfig.mockResolvedValue({
+      authMode: 'token',
+      baseUrl: 'https://gateway.example.com/hermes',
+      error: null,
+      providers: [],
+      reachable: true,
+      version: '0.17.0'
+    })
+
+    let resolveTest: ((result: { baseUrl: string; ok: boolean; version: string }) => void) | undefined
+
+    const pendingTest = new Promise<{ baseUrl: string; ok: boolean; version: string }>(resolve => {
+      resolveTest = resolve
+    })
+
+    desktop.testConnectionConfig.mockReturnValue(pendingTest)
+
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click(await screen.findByText('Connect to existing Hermes'))
+    fireEvent.change(await screen.findByPlaceholderText('https://gateway.example.com/hermes'), {
+      target: { value: 'https://gateway.example.com/hermes' }
+    })
+
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 550))
+    })
+
+    const tokenInput = await screen.findByPlaceholderText('Paste session token')
+    const apply = screen.getByText('Apply and reconnect').closest('button') as HTMLButtonElement
+
+    fireEvent.change(tokenInput, { target: { value: 'token-a' } })
+    fireEvent.click(screen.getByText('Test connection'))
+    await waitFor(() => expect(desktop.testConnectionConfig).toHaveBeenCalledTimes(1))
+
+    fireEvent.change(tokenInput, { target: { value: 'token-b' } })
+
+    await act(async () => {
+      resolveTest?.({ baseUrl: 'https://gateway.example.com/hermes', ok: true, version: '0.17.0' })
+      await pendingTest
+    })
+
+    expect(screen.queryByText('Connected to https://gateway.example.com/hermes (0.17.0).')).toBeNull()
+    expect(apply.disabled).toBe(true)
+  })
+
+  it('restores remote apply controls when applying the tested connection fails', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'linux', activeRoot: '/home/me/.hermes/hermes-agent' }
+      })
+    )
+
+    desktop.probeConnectionConfig.mockResolvedValue({
+      authMode: 'token',
+      baseUrl: 'https://gateway.example.com/hermes',
+      error: null,
+      providers: [],
+      reachable: true,
+      version: '0.17.0'
+    })
+    desktop.testConnectionConfig.mockResolvedValue({
+      baseUrl: 'https://gateway.example.com/hermes',
+      ok: true,
+      version: '0.17.0'
+    })
+    desktop.applyConnectionConfig.mockRejectedValue(new Error('remote apply failed'))
+
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click(await screen.findByText('Connect to existing Hermes'))
+    fireEvent.change(await screen.findByPlaceholderText('https://gateway.example.com/hermes'), {
+      target: { value: 'https://gateway.example.com/hermes' }
+    })
+
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 550))
+    })
+
+    fireEvent.change(await screen.findByPlaceholderText('Paste session token'), {
+      target: { value: 'session-secret' }
+    })
+    fireEvent.click(screen.getByText('Test connection'))
+    await screen.findByText('Connected to https://gateway.example.com/hermes (0.17.0).')
+
+    const apply = screen.getByText('Apply and reconnect').closest('button') as HTMLButtonElement
+    fireEvent.click(apply)
+
+    expect(await screen.findByText('remote apply failed')).toBeTruthy()
+    expect(apply.disabled).toBe(false)
+    expect(screen.getByText('Gateway URL')).toBeTruthy()
+  })
+
+  it('signs in, tests, and applies a password-style remote gateway', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        setupChoice: { platform: 'linux', activeRoot: '/home/me/.hermes/hermes-agent' }
+      })
+    )
+
+    desktop.probeConnectionConfig.mockResolvedValue({
+      authMode: 'oauth',
+      baseUrl: 'https://gateway.example.com/hermes',
+      error: null,
+      providers: [{ displayName: 'Username & Password', name: 'password', supportsPassword: true }],
+      reachable: true,
+      version: '0.17.0'
+    })
+    desktop.oauthLoginConnectionConfig.mockResolvedValue({
+      baseUrl: 'https://gateway.example.com/hermes',
+      connected: true,
+      ok: true
+    })
+    desktop.testConnectionConfig.mockResolvedValue({
+      baseUrl: 'https://gateway.example.com/hermes',
+      ok: true,
+      version: null
+    })
+    desktop.applyConnectionConfig.mockResolvedValue({ mode: 'remote' })
+
+    render(<DesktopInstallOverlay />)
+
+    fireEvent.click(await screen.findByText('Connect to existing Hermes'))
+    fireEvent.change(await screen.findByPlaceholderText('https://gateway.example.com/hermes'), {
+      target: { value: 'https://gateway.example.com/hermes' }
+    })
+
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 550))
+    })
+
+    expect(screen.queryByText('Sign in with Username & Password')).toBeNull()
+    fireEvent.click(await screen.findByText('Sign in'))
+
+    await waitFor(() => {
+      expect(desktop.oauthLoginConnectionConfig).toHaveBeenCalledWith('https://gateway.example.com/hermes')
+    })
+
+    fireEvent.click(screen.getByText('Test connection'))
+
+    await waitFor(() => {
+      expect(desktop.testConnectionConfig).toHaveBeenCalledWith({
+        mode: 'remote',
+        remoteAuthMode: 'oauth',
+        remoteToken: undefined,
+        remoteUrl: 'https://gateway.example.com/hermes'
+      })
+    })
+
+    await screen.findByText('Connected to https://gateway.example.com/hermes.')
+    const apply = screen.getByText('Apply and reconnect').closest('button') as HTMLButtonElement
+    expect(apply.disabled).toBe(false)
+    fireEvent.click(apply)
+
+    await waitFor(() => {
+      expect(desktop.applyConnectionConfig).toHaveBeenCalledWith({
+        mode: 'remote',
+        remoteAuthMode: 'oauth',
+        remoteToken: undefined,
+        remoteUrl: 'https://gateway.example.com/hermes'
+      })
+    })
+  })
+
+  it('offers remote connection from the unsupported packaged install screen', async () => {
+    const desktop = installDesktopMock(
+      bootstrapState({
+        unsupportedPlatform: {
+          platform: 'darwin',
+          activeRoot: '/Users/me/.hermes/hermes-agent',
+          installCommand: 'curl -fsSL https://example.invalid/install.sh | sh',
+          docsUrl: 'https://example.invalid/docs'
+        }
+      })
+    )
+
+    render(<DesktopInstallOverlay />)
+
+    expect(await screen.findByText('Hermes needs a one-time install')).toBeTruthy()
+
+    fireEvent.click(screen.getByText('Connect existing'))
+
+    expect(await screen.findByText('Gateway URL')).toBeTruthy()
+
+    desktop.probeConnectionConfig.mockResolvedValue({
+      authMode: 'token',
+      baseUrl: 'https://gateway.example.com/hermes',
+      error: null,
+      providers: [],
+      reachable: true,
+      version: '0.17.0'
+    })
+    desktop.testConnectionConfig.mockResolvedValue({
+      baseUrl: 'https://gateway.example.com/hermes',
+      ok: true,
+      version: '0.17.0'
+    })
+    desktop.applyConnectionConfig.mockImplementation(async () => {
+      desktop.emitBootstrapEvent({ type: 'dismissed' })
+
+      return { mode: 'remote' }
+    })
+
+    fireEvent.change(screen.getByPlaceholderText('https://gateway.example.com/hermes'), {
+      target: { value: 'https://gateway.example.com/hermes' }
+    })
+
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 550))
+    })
+
+    fireEvent.change(await screen.findByPlaceholderText('Paste session token'), {
+      target: { value: 'session-secret' }
+    })
+    fireEvent.click(screen.getByText('Test connection'))
+    await screen.findByText('Connected to https://gateway.example.com/hermes (0.17.0).')
+    fireEvent.click(screen.getByText('Apply and reconnect'))
+
+    await waitFor(() => expect(screen.queryByText('Gateway URL')).toBeNull())
+    expect(screen.queryByText('Hermes needs a one-time install')).toBeNull()
+  })
+})
diff --git a/apps/desktop/src/components/desktop-install-overlay.tsx b/apps/desktop/src/components/desktop-install-overlay.tsx
index b701fa9ff6a..4941f6dd6bc 100644
--- a/apps/desktop/src/components/desktop-install-overlay.tsx
+++ b/apps/desktop/src/components/desktop-install-overlay.tsx
@@ -15,10 +15,12 @@ import type {
   DesktopBootstrapState
 } from '@/global'
 import { useI18n } from '@/i18n'
-import { ChevronDown, ChevronRight, iconSize } from '@/lib/icons'
+import { AlertCircle, ChevronDown, ChevronRight, Globe, iconSize, Loader2, Monitor } from '@/lib/icons'
 import { capitalize } from '@/lib/text'
 import { cn } from '@/lib/utils'
 
+import { FirstRunRemoteForm } from './first-run-remote-form'
+
 /**
  * DesktopInstallOverlay
  *
@@ -155,6 +157,10 @@ function StageRow({ descriptor, result, now }: StageRowProps) {
   )
 }
 
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err || 'Unknown error')
+}
+
 const EMPTY_STATE: DesktopBootstrapState = {
   active: false,
   manifest: null,
@@ -163,10 +169,32 @@ const EMPTY_STATE: DesktopBootstrapState = {
   log: [],
   startedAt: null,
   completedAt: null,
+  setupChoice: null,
   unsupportedPlatform: null
 }
 
 function applyEvent(state: DesktopBootstrapState, ev: DesktopBootstrapEvent): DesktopBootstrapState {
+  if (ev.type === 'dismissed') {
+    return { ...EMPTY_STATE }
+  }
+
+  if (ev.type === 'setup-choice') {
+    return {
+      ...state,
+      active: false,
+      manifest: null,
+      stages: {},
+      error: null,
+      setupChoice: ev.active
+        ? {
+            platform: ev.platform || state.setupChoice?.platform || 'unknown',
+            activeRoot: ev.activeRoot || state.setupChoice?.activeRoot || ''
+          }
+        : null,
+      unsupportedPlatform: null
+    }
+  }
+
   if (ev.type === 'manifest') {
     const stages: Record<string, DesktopBootstrapStageResult> = {}
 
@@ -180,6 +208,7 @@ function applyEvent(state: DesktopBootstrapState, ev: DesktopBootstrapEvent): De
       manifest: { type: 'manifest', stages: ev.stages, protocolVersion: ev.protocolVersion },
       stages,
       error: null,
+      setupChoice: null,
       startedAt: state.startedAt || Date.now()
     }
   }
@@ -219,13 +248,14 @@ function applyEvent(state: DesktopBootstrapState, ev: DesktopBootstrapEvent): De
   }
 
   if (ev.type === 'failed') {
-    return { ...state, active: false, error: ev.error || 'unknown error' }
+    return { ...state, active: false, error: ev.error || 'unknown error', setupChoice: null }
   }
 
   if (ev.type === 'unsupported-platform') {
     return {
       ...state,
       active: false,
+      setupChoice: null,
       unsupportedPlatform: {
         platform: ev.platform,
         activeRoot: ev.activeRoot,
@@ -246,6 +276,7 @@ export function DesktopInstallOverlay({ enabled = true }: DesktopInstallOverlayP
   const [logOpen, setLogOpen] = useState(false)
   const [copied, setCopied] = useState(false)
   const [cancelling, setCancelling] = useState(false)
+  const [remoteOpen, setRemoteOpen] = useState(false)
   const [now, setNow] = useState(() => Date.now())
   const logEndRef = useRef<HTMLDivElement | null>(null)
 
@@ -312,6 +343,24 @@ export function DesktopInstallOverlay({ enabled = true }: DesktopInstallOverlayP
     }
   }, [state.error])
 
+  // The choice remains mounted while main hands off to local bootstrap. Once
+  // a manifest/failure takes ownership (or a later repair presents a fresh
+  // choice), this transient button state must not leak across phases — so it
+  // records the root it was produced under and is read back only under that
+  // same root. Deriving it beats clearing it in an effect: the choice paints
+  // as soon as the first snapshot commits, and a click landing before such an
+  // effect flushed would have its error wiped before it ever rendered.
+  const [localStart, setLocalStart] = useState<{
+    root: string | null
+    starting: boolean
+    error: string | null
+  }>({ root: null, starting: false, error: null })
+
+  const activeRoot = state.setupChoice?.activeRoot ?? null
+  const forActiveRoot = localStart.root === activeRoot
+  const localStarting = forActiveRoot && localStart.starting
+  const localStartError = forActiveRoot ? localStart.error : null
+
   // Mount logic: show whenever a bootstrap is in flight, completed-with-error,
   // or actively running with a manifest. Hide entirely after a successful
   // completion so the rest of the UI can take over.
@@ -332,13 +381,94 @@ export function DesktopInstallOverlay({ enabled = true }: DesktopInstallOverlayP
       return true
     }
 
+    if (state.setupChoice) {
+      return true
+    }
+
     return false
-  }, [enabled, state.active, state.error, state.unsupportedPlatform])
+  }, [enabled, state.active, state.error, state.setupChoice, state.unsupportedPlatform])
 
   if (!shouldShow) {
     return null
   }
 
+  if (remoteOpen) {
+    return <FirstRunRemoteForm onBack={() => setRemoteOpen(false)} />
+  }
+
+  if (state.setupChoice) {
+    return (
+      <div className="fixed inset-0 z-[1400] flex items-center justify-center bg-background/90 p-4 backdrop-blur-md">
+        <div className="w-full max-w-2xl rounded-xl border border-(--stroke-nous) bg-card p-8 shadow-nous">
+          <div className="flex items-start gap-4">
+            <BrandMark className="size-11 shrink-0" />
+            <div className="min-w-0">
+              <h2 className="text-xl font-semibold tracking-tight">{copy.setupChoiceTitle}</h2>
+              <p className="mt-1.5 text-sm text-muted-foreground">{copy.setupChoiceDesc}</p>
+            </div>
+          </div>
+
+          <div className="mt-6 grid gap-3 sm:grid-cols-2">
+            <button
+              className="rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-4 text-left transition hover:bg-(--chrome-action-hover)"
+              onClick={() => setRemoteOpen(true)}
+              type="button"
+            >
+              <div className="flex items-center gap-2 text-sm font-medium">
+                <Globe className="size-4 text-muted-foreground" />
+                <span>{copy.connectExistingTitle}</span>
+              </div>
+              <p className="mt-2 text-sm leading-5 text-muted-foreground">{copy.connectExistingDesc}</p>
+            </button>
+
+            <button
+              className="rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-4 text-left transition hover:bg-(--chrome-action-hover) disabled:cursor-wait disabled:opacity-60"
+              disabled={localStarting}
+              onClick={async () => {
+                setLocalStart({ root: activeRoot, starting: true, error: null })
+
+                try {
+                  const desktop = window.hermesDesktop
+
+                  if (!desktop || typeof desktop.continueBootstrapLocal !== 'function') {
+                    throw new Error(copy.localStartUnavailable)
+                  }
+
+                  await desktop.continueBootstrapLocal()
+                } catch (err) {
+                  setLocalStart({ root: activeRoot, starting: false, error: errorMessage(err) })
+                }
+              }}
+              type="button"
+            >
+              <div className="flex items-center gap-2 text-sm font-medium">
+                {localStarting ? (
+                  <Loader2 className="size-4 animate-spin text-muted-foreground" />
+                ) : (
+                  <Monitor className="size-4 text-muted-foreground" />
+                )}
+                <span>{copy.installLocalTitle}</span>
+              </div>
+              <p className="mt-2 text-sm leading-5 text-muted-foreground">{copy.installLocalDesc}</p>
+            </button>
+          </div>
+
+          {localStartError ? (
+            <div className="mt-4 flex items-start gap-2 text-sm text-destructive">
+              <AlertCircle className="mt-0.5 size-4 shrink-0" />
+              <span>{localStartError}</span>
+            </div>
+          ) : null}
+
+          <div className="mt-6 text-xs text-muted-foreground">
+            {copy.installTo}{' '}
+            <code className="font-mono text-(--ui-text-secondary)">{state.setupChoice.activeRoot}</code>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
   // Unsupported-platform branch: macOS/Linux packaged builds hit this when
   // there's no Hermes Agent installed yet and we can't drive install.sh
   // (no stage protocol equivalent yet). Show a copy-paste install command
@@ -384,9 +514,15 @@ export function DesktopInstallOverlay({ enabled = true }: DesktopInstallOverlayP
             <span className="text-xs text-muted-foreground">
               {copy.installTo} <code className="font-mono text-(--ui-text-secondary)">{ups.activeRoot}</code>
             </span>
-            <Button onClick={() => window.location.reload()} size="sm" variant="default">
-              {copy.retryAfterRun}
-            </Button>
+            <div className="flex items-center gap-2">
+              <Button onClick={() => setRemoteOpen(true)} size="sm" variant="secondary">
+                <Globe className="size-4" />
+                {copy.connectExistingShort}
+              </Button>
+              <Button onClick={() => window.location.reload()} size="sm" variant="default">
+                {copy.retryAfterRun}
+              </Button>
+            </div>
           </div>
         </div>
       </div>
diff --git a/apps/desktop/src/components/first-run-remote-form.tsx b/apps/desktop/src/components/first-run-remote-form.tsx
new file mode 100644
index 00000000000..ced31acdd44
--- /dev/null
+++ b/apps/desktop/src/components/first-run-remote-form.tsx
@@ -0,0 +1,345 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { BrandMark } from '@/components/brand-mark'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import type { DesktopConnectionProbeResult } from '@/global'
+import { useI18n } from '@/i18n'
+import { deriveRemoteAuthProviderShape } from '@/lib/desktop-remote-auth'
+import { AlertCircle, Check, Loader2, LogIn } from '@/lib/icons'
+
+type AuthMode = 'oauth' | 'token'
+type ProbeStatus = 'idle' | 'probing' | 'done' | 'error'
+
+interface FirstRunRemoteFormProps {
+  onBack: () => void
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err || 'Unknown error')
+}
+
+export function FirstRunRemoteForm({ onBack }: FirstRunRemoteFormProps) {
+  const { t } = useI18n()
+  const copy = t.install
+  const [remoteUrl, setRemoteUrl] = useState('')
+  const [remoteToken, setRemoteToken] = useState('')
+  const [probeStatus, setProbeStatus] = useState<ProbeStatus>('idle')
+  const [probe, setProbe] = useState<DesktopConnectionProbeResult | null>(null)
+  const [oauthConnected, setOauthConnected] = useState(false)
+  const [signingIn, setSigningIn] = useState(false)
+  const [testing, setTesting] = useState(false)
+  const [applying, setApplying] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [success, setSuccess] = useState<string | null>(null)
+  const [lastTestedPayloadKey, setLastTestedPayloadKey] = useState<string | null>(null)
+  const probeSeq = useRef(0)
+  const testSeq = useRef(0)
+
+  const trimmedUrl = remoteUrl.trim()
+
+  const invalidateTest = useCallback(() => {
+    testSeq.current += 1
+    setTesting(false)
+    setError(null)
+    setSuccess(null)
+    setLastTestedPayloadKey(null)
+  }, [])
+
+  useEffect(() => {
+    const seq = ++probeSeq.current
+
+    if (!trimmedUrl || !/^https?:\/\//i.test(trimmedUrl)) {
+      setProbeStatus('idle')
+      setProbe(null)
+      setOauthConnected(false)
+
+      return
+    }
+
+    const desktop = window.hermesDesktop
+
+    if (!desktop?.probeConnectionConfig) {
+      return
+    }
+
+    setProbeStatus('probing')
+
+    const timer = window.setTimeout(() => {
+      desktop
+        .probeConnectionConfig(trimmedUrl)
+        .then(result => {
+          if (seq !== probeSeq.current) {
+            return
+          }
+
+          invalidateTest()
+          setProbe(result)
+          setProbeStatus(result.reachable ? 'done' : 'error')
+
+          if (result.reachable && result.authMode !== 'oauth') {
+            setOauthConnected(false)
+          }
+        })
+        .catch(err => {
+          if (seq !== probeSeq.current) {
+            return
+          }
+
+          setProbe(null)
+          setProbeStatus('error')
+          setError(errorMessage(err))
+        })
+    }, 500)
+
+    return () => window.clearTimeout(timer)
+  }, [invalidateTest, trimmedUrl])
+
+  const authMode: AuthMode = probeStatus === 'done' && probe?.authMode === 'oauth' ? 'oauth' : 'token'
+  const authResolved = probeStatus === 'done' && probe?.authMode !== 'unknown'
+  const authProviderShape = deriveRemoteAuthProviderShape(probe?.providers, copy.identityProvider)
+  const { isPassword: isPasswordProvider, providerLabel } = authProviderShape
+  const canRetryProbe = Boolean(trimmedUrl && probeStatus === 'error')
+
+  const canTest = Boolean(
+    trimmedUrl && (canRetryProbe || (authResolved && (authMode === 'oauth' ? oauthConnected : remoteToken.trim())))
+  )
+
+  const payload = () => ({
+    mode: 'remote' as const,
+    remoteAuthMode: authMode,
+    remoteToken: authMode === 'token' ? remoteToken.trim() || undefined : undefined,
+    remoteUrl: trimmedUrl
+  })
+
+  const currentPayloadKey = JSON.stringify(payload())
+  const payloadKeyRef = useRef(currentPayloadKey)
+  payloadKeyRef.current = currentPayloadKey
+  const canApply = lastTestedPayloadKey === currentPayloadKey
+
+  const signIn = async () => {
+    if (!trimmedUrl) {
+      setError(copy.enterUrlFirst)
+
+      return
+    }
+
+    setSigningIn(true)
+    setError(null)
+
+    try {
+      // Unlike Settings, first-run intentionally does not pre-save remote mode:
+      // backing out must still allow local install without leaving a remote
+      // connection selected. The login IPC accepts the raw URL and stores only
+      // its OAuth cookies; config is persisted once the user applies.
+      const result = await window.hermesDesktop.oauthLoginConnectionConfig(trimmedUrl)
+      invalidateTest()
+      setOauthConnected(Boolean(result.connected))
+
+      if (!result.connected) {
+        setError(copy.signInIncomplete)
+      }
+    } catch (err) {
+      setError(errorMessage(err))
+    } finally {
+      setSigningIn(false)
+    }
+  }
+
+  const testRemote = async () => {
+    if (!canTest) {
+      setError(authMode === 'oauth' ? copy.incompleteSignInTest : copy.incompleteTokenTest)
+
+      return
+    }
+
+    const seq = ++testSeq.current
+    const testedPayload = payload()
+    const testedPayloadKey = JSON.stringify(testedPayload)
+
+    setTesting(true)
+    setError(null)
+    setSuccess(null)
+    setLastTestedPayloadKey(null)
+
+    try {
+      if (!authResolved) {
+        const result = await window.hermesDesktop.probeConnectionConfig(trimmedUrl)
+
+        if (seq !== testSeq.current || testedPayloadKey !== payloadKeyRef.current) {
+          return
+        }
+
+        setProbe(result)
+        setProbeStatus(result.reachable ? 'done' : 'error')
+        setError(result.reachable && result.authMode !== 'unknown' ? null : result.error || copy.probeError)
+
+        return
+      }
+
+      const result = await window.hermesDesktop.testConnectionConfig(testedPayload)
+
+      if (seq !== testSeq.current || testedPayloadKey !== payloadKeyRef.current) {
+        return
+      }
+
+      setSuccess(copy.testSucceeded(result.baseUrl || trimmedUrl, result.version ?? undefined))
+      setLastTestedPayloadKey(testedPayloadKey)
+    } catch (err) {
+      if (seq === testSeq.current && testedPayloadKey === payloadKeyRef.current) {
+        setError(errorMessage(err))
+      }
+    } finally {
+      if (seq === testSeq.current) {
+        setTesting(false)
+      }
+    }
+  }
+
+  const applyRemote = async () => {
+    if (!canApply) {
+      return
+    }
+
+    const testedPayload = payload()
+
+    setApplying(true)
+    setError(null)
+    let applied = false
+
+    try {
+      await window.hermesDesktop.applyConnectionConfig(testedPayload)
+      applied = true
+    } catch (err) {
+      setError(errorMessage(err))
+    } finally {
+      setApplying(false)
+    }
+
+    if (applied) {
+      onBack()
+    }
+  }
+
+  return (
+    <div className="fixed inset-0 z-[1400] flex items-center justify-center bg-background/90 p-4 backdrop-blur-md">
+      <div className="flex w-full max-w-xl flex-col rounded-xl border border-(--stroke-nous) bg-card p-8 shadow-nous">
+        <div className="flex items-start gap-4">
+          <BrandMark className="size-11 shrink-0" />
+          <div className="min-w-0">
+            <h2 className="text-xl font-semibold tracking-tight">{copy.remoteSetupTitle}</h2>
+            <p className="mt-1.5 text-sm text-muted-foreground">{copy.remoteSetupDesc}</p>
+          </div>
+        </div>
+
+        <div className="mt-6 grid gap-4">
+          <label className="grid gap-1.5">
+            <span className="text-xs font-medium text-muted-foreground">{copy.remoteUrlTitle}</span>
+            <Input
+              autoComplete="url"
+              disabled={applying}
+              onChange={event => {
+                invalidateTest()
+                setRemoteUrl(event.target.value)
+              }}
+              placeholder={copy.remoteUrlPlaceholder}
+              value={remoteUrl}
+            />
+            <span className="text-xs text-muted-foreground">{copy.remoteUrlDesc}</span>
+          </label>
+
+          {probeStatus === 'probing' ? (
+            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+              <Loader2 className="size-4 animate-spin" />
+              {copy.probing}
+            </div>
+          ) : null}
+
+          {probeStatus === 'error' ? (
+            <div className="flex items-start gap-2 text-sm text-destructive">
+              <AlertCircle className="mt-0.5 size-4 shrink-0" />
+              <span>{probe?.error || copy.probeError}</span>
+            </div>
+          ) : null}
+
+          {authResolved && authMode === 'oauth' ? (
+            <div className="rounded-md border border-(--ui-stroke-tertiary) p-3">
+              <div className="flex items-center justify-between gap-3">
+                <div>
+                  <div className="text-sm font-medium">{copy.authTitle}</div>
+                  <p className="mt-1 text-xs text-muted-foreground">
+                    {oauthConnected ? copy.authSignedIn : copy.authNeedsOauth(providerLabel)}
+                  </p>
+                </div>
+                {oauthConnected ? (
+                  <div className="flex items-center gap-1.5 text-sm text-primary">
+                    <Check className="size-4" />
+                    {copy.connected}
+                  </div>
+                ) : (
+                  <Button disabled={signingIn || applying} onClick={() => void signIn()} size="sm">
+                    {signingIn ? <Loader2 className="size-4 animate-spin" /> : <LogIn className="size-4" />}
+                    {isPasswordProvider ? copy.signIn : copy.signInWith(providerLabel)}
+                  </Button>
+                )}
+              </div>
+            </div>
+          ) : null}
+
+          {authResolved && authMode === 'token' ? (
+            <label className="grid gap-1.5">
+              <span className="text-xs font-medium text-muted-foreground">{copy.tokenTitle}</span>
+              <Input
+                autoComplete="off"
+                disabled={applying}
+                onChange={event => {
+                  invalidateTest()
+                  setRemoteToken(event.target.value)
+                }}
+                placeholder={copy.pasteSessionToken}
+                type="password"
+                value={remoteToken}
+              />
+              <span className="text-xs text-muted-foreground">{copy.tokenDesc}</span>
+            </label>
+          ) : null}
+
+          {error ? (
+            <div className="flex items-start gap-2 text-sm text-destructive">
+              <AlertCircle className="mt-0.5 size-4 shrink-0" />
+              <span>{error}</span>
+            </div>
+          ) : null}
+
+          {success ? (
+            <div className="flex items-center gap-2 text-sm text-primary">
+              <Check className="size-4" />
+              <span>{success}</span>
+            </div>
+          ) : null}
+        </div>
+
+        <div className="mt-7 flex flex-wrap items-center justify-between gap-3">
+          <Button disabled={applying} onClick={onBack} size="sm" variant="ghost">
+            {copy.backToSetup}
+          </Button>
+          <div className="flex items-center gap-2">
+            <Button
+              disabled={testing || applying || !canTest}
+              onClick={() => void testRemote()}
+              size="sm"
+              variant="secondary"
+            >
+              {testing ? <Loader2 className="size-4 animate-spin" /> : null}
+              {copy.testConnection}
+            </Button>
+            <Button disabled={applying || !canApply} onClick={() => void applyRemote()} size="sm">
+              {applying ? <Loader2 className="size-4 animate-spin" /> : null}
+              {copy.applyRemote}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/apps/desktop/src/components/model-picker.tsx b/apps/desktop/src/components/model-picker.tsx
index 73e3401e078..3395a0c3387 100644
--- a/apps/desktop/src/components/model-picker.tsx
+++ b/apps/desktop/src/components/model-picker.tsx
@@ -64,7 +64,6 @@ export function ModelPickerDialog({
   const providers = modelOptions.data?.providers ?? []
 
   const { model: optionsModel, provider: optionsProvider } = currentPickerSelection(
-    !!sessionId,
     { model: currentModel, provider: currentProvider },
     modelOptions.data
   )
diff --git a/apps/desktop/src/components/notifications.tsx b/apps/desktop/src/components/notifications.tsx
index 3e38afeb3ef..4d4a3c1058f 100644
--- a/apps/desktop/src/components/notifications.tsx
+++ b/apps/desktop/src/components/notifications.tsx
@@ -58,6 +58,7 @@ export function NotificationStack() {
     }
   }, [defaultStack.length])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const latest = notifications[0]
 
diff --git a/apps/desktop/src/components/pane-shell/pane-visibility.test.ts b/apps/desktop/src/components/pane-shell/pane-visibility.test.ts
new file mode 100644
index 00000000000..030aa2d8ec6
--- /dev/null
+++ b/apps/desktop/src/components/pane-shell/pane-visibility.test.ts
@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { hiddenPaneProps, PANE_HIDDEN_ATTR, queryAllVisible, queryVisible } from './pane-visibility'
+
+/**
+ * Inactive tabs stay mounted with their layout box intact, so they answer
+ * document-wide lookups exactly like the visible tab. These helpers are the one
+ * place that difference is decided.
+ */
+
+const COMPOSER = '[data-slot="composer-root"]'
+
+const tab = (id: string, hidden = false) => `
+  <div ${hidden ? PANE_HIDDEN_ATTR : ''}>
+    <section><div data-slot="composer-root" id="${id}"></div></section>
+  </div>
+`
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('pane visibility lookups', () => {
+  it('resolves the foreground element even when a hidden tab matches first', () => {
+    document.body.innerHTML = tab('background', true) + tab('foreground')
+
+    expect(queryVisible(COMPOSER)?.id).toBe('foreground')
+    expect(queryAllVisible(COMPOSER).map(el => el.id)).toEqual(['foreground'])
+  })
+
+  it('answers normally when nothing is hidden', () => {
+    document.body.innerHTML = tab('only')
+
+    expect(queryVisible(COMPOSER)?.id).toBe('only')
+  })
+
+  it('marks a pane hidden only while it is inactive', () => {
+    expect(hiddenPaneProps(true)).toEqual({ [PANE_HIDDEN_ATTR]: '' })
+    expect(hiddenPaneProps(false)).toEqual({})
+  })
+})
diff --git a/apps/desktop/src/components/pane-shell/pane-visibility.ts b/apps/desktop/src/components/pane-shell/pane-visibility.ts
new file mode 100644
index 00000000000..986b9ee3bde
--- /dev/null
+++ b/apps/desktop/src/components/pane-shell/pane-visibility.ts
@@ -0,0 +1,37 @@
+/**
+ * Keep-alive visibility — the one policy every document-wide lookup must obey.
+ *
+ * A tab group keeps each ever-active pane MOUNTED and hides the inactive ones
+ * with `visibility: hidden` (see `tree/renderer/tree-group.tsx`), deliberately
+ * preserving their layout box so scroll positions survive a tab round-trip. The
+ * cost is that an inactive tab's rect is IDENTICAL to the visible tab's, so
+ * neither selector order nor a rect hit-test can tell them apart. A lookup that
+ * resolves "the chat surface / composer / viewport" from the document therefore
+ * has to skip hidden panes, or it silently answers with the wrong tab.
+ */
+
+import { createContext, useContext } from 'react'
+
+/** Marks a mounted-but-hidden pane layer (an inactive tab in a stack). */
+export const PANE_HIDDEN_ATTR = 'data-pane-hidden'
+
+const HIDDEN_PANE = `[${PANE_HIDDEN_ATTR}]`
+
+/** Spread onto a kept pane layer so the lookups below can skip it. */
+export const hiddenPaneProps = (hidden: boolean): Record<string, string> => (hidden ? { [PANE_HIDDEN_ATTR]: '' } : {})
+
+/** React face of the same policy: the pane layer provides its visibility so a
+ *  kept-alive surface can gate hot subscriptions (streaming re-renders) off
+ *  while it's an inactive tab. Default TRUE — surfaces outside a tab stack
+ *  (secondary windows, plain routes) are always visible. */
+export const PaneVisibleContext = createContext(true)
+
+export const usePaneVisible = (): boolean => useContext(PaneVisibleContext)
+
+/** `querySelectorAll` minus anything inside an inactive tab. */
+export const queryAllVisible = <T extends HTMLElement>(selector: string, root: ParentNode = document): T[] =>
+  [...root.querySelectorAll<T>(selector)].filter(el => !el.closest(HIDDEN_PANE))
+
+/** `querySelector` minus anything inside an inactive tab. */
+export const queryVisible = <T extends HTMLElement>(selector: string, root: ParentNode = document): null | T =>
+  queryAllVisible<T>(selector, root)[0] ?? null
diff --git a/apps/desktop/src/components/pane-shell/tree/renderer/tree-group.tsx b/apps/desktop/src/components/pane-shell/tree/renderer/tree-group.tsx
index 0d14929b421..1ed752f1dda 100644
--- a/apps/desktop/src/components/pane-shell/tree/renderer/tree-group.tsx
+++ b/apps/desktop/src/components/pane-shell/tree/renderer/tree-group.tsx
@@ -30,6 +30,7 @@ import { cn } from '@/lib/utils'
 
 import { $layoutEditMode } from '../../edit-mode'
 import { useWindowControlsOverlap } from '../../geometry'
+import { hiddenPaneProps, PaneVisibleContext } from '../../pane-visibility'
 import type { DropPosition, GroupNode, RootEdge } from '../model'
 import { adjacentGroup } from '../model'
 import {
@@ -520,7 +521,9 @@ export function TreeGroup({
       {/* Body: the zone's pane content — every kept (ever-active) pane stays
           mounted in an absolute layer; only the active one is visible.
           `visibility` (not display) keeps the hidden pane's layout box, so
-          scroll positions and measurements survive the round-trip. */}
+          scroll positions and measurements survive the round-trip — which also
+          makes a hidden layer's rect identical to the visible one's, hence the
+          marker document-wide lookups filter on (see pane-visibility.ts). */}
       {!node.minimized && (
         <div className="relative min-h-0 min-w-0 flex-1 overflow-hidden">
           {isEmpty ? (
@@ -538,9 +541,14 @@ export function TreeGroup({
                   aria-hidden={!isActive || undefined}
                   className={cn('absolute inset-0 overflow-auto', !isActive && 'pointer-events-none invisible')}
                   key={paneId}
+                  {...hiddenPaneProps(!isActive)}
                 >
                   {pane?.render ? (
-                    <ContribBoundary id={pane.id}>{pane.render()}</ContribBoundary>
+                    // Visibility flows to the pane so a kept-alive chat surface
+                    // can gate its hot (per-token) subscriptions while hidden.
+                    <PaneVisibleContext.Provider value={isActive}>
+                      <ContribBoundary id={pane.id}>{pane.render()}</ContribBoundary>
+                    </PaneVisibleContext.Provider>
                   ) : (
                     isActive && (
                       <div className="p-3 font-mono text-[11px] text-(--ui-text-quaternary)">
diff --git a/apps/desktop/src/components/pet/floating-pet.tsx b/apps/desktop/src/components/pet/floating-pet.tsx
index 399ed1bf485..4a14991bf39 100644
--- a/apps/desktop/src/components/pet/floating-pet.tsx
+++ b/apps/desktop/src/components/pet/floating-pet.tsx
@@ -247,6 +247,7 @@ export function FloatingPet() {
   // Restore a popped-out pet on boot, once the pet has loaded (so we never spawn
   // an empty overlay window). Primary window only; runs at most once.
   const restoredRef = useRef(false)
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     if (isSecondaryWindow() || restoredRef.current || !active) {
       return
diff --git a/apps/desktop/src/components/pet/pet-sprite.tsx b/apps/desktop/src/components/pet/pet-sprite.tsx
index b3a0fb66003..a1e91f3ece1 100644
--- a/apps/desktop/src/components/pet/pet-sprite.tsx
+++ b/apps/desktop/src/components/pet/pet-sprite.tsx
@@ -121,10 +121,12 @@ function PetSpriteImpl({ info, zoom = 1, stateOverride, rowOverride }: PetSprite
   const rowOverrideRef = useRef<string | undefined>(rowOverride)
 
   // Keep the override current without re-running the RAF setup effect.
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     overrideRef.current = stateOverride
   }, [stateOverride])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     rowOverrideRef.current = rowOverride
   }, [rowOverride])
@@ -152,6 +154,7 @@ function PetSpriteImpl({ info, zoom = 1, stateOverride, rowOverride }: PetSprite
     return img
   }, [info.spritesheetBase64, info.mime])
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     const canvas = canvasRef.current
 
diff --git a/apps/desktop/src/components/ui/dialog-dismiss-repro.test.tsx b/apps/desktop/src/components/ui/dialog-dismiss-repro.test.tsx
new file mode 100644
index 00000000000..f8daa94ef00
--- /dev/null
+++ b/apps/desktop/src/components/ui/dialog-dismiss-repro.test.tsx
@@ -0,0 +1,87 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { Dialog, DialogContent, DialogTitle } from './dialog'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from './select'
+
+afterEach(cleanup)
+
+// jsdom lacks these; Radix Select calls them on open.
+window.HTMLElement.prototype.scrollIntoView = vi.fn()
+window.HTMLElement.prototype.hasPointerCapture = vi.fn()
+window.HTMLElement.prototype.releasePointerCapture = vi.fn()
+
+const flushTimers = () => new Promise(resolve => setTimeout(resolve, 10))
+
+describe('REPRO: dismissing an open Select inside a Dialog', () => {
+  it('closes only the select, not the dialog, when the press lands on the overlay', async () => {
+    // While a modal Select is open, the dialog content div is pointer-events:
+    // none, so a real click anywhere in the dialog body hit-tests through to
+    // the overlay. Simulate that by firing the pointer sequence on the overlay.
+    const onOpenChange = vi.fn()
+    render(
+      <Dialog onOpenChange={onOpenChange} open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <Select defaultOpen>
+            <SelectTrigger aria-label="picker">
+              <SelectValue placeholder="pick" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="a">Option A</SelectItem>
+            </SelectContent>
+          </Select>
+        </DialogContent>
+      </Dialog>
+    )
+
+    // DismissableLayer registers its document pointerdown listener in a
+    // setTimeout(0) — flush it first.
+    await flushTimers()
+
+    const overlay = document.querySelector('[data-slot="dialog-overlay"]') as HTMLElement
+    expect(overlay).toBeTruthy()
+    expect(screen.getByText('Option A')).toBeTruthy()
+
+    fireEvent.pointerDown(overlay, { button: 0 })
+    fireEvent.pointerUp(overlay, { button: 0 })
+    fireEvent.click(overlay, { button: 0 })
+
+    // The deferred dismissal path resolves through another setTimeout(0).
+    await flushTimers()
+
+    // The select closed...
+    expect(screen.queryByText('Option A')).toBeNull()
+    // ...but the dialog must NOT have been asked to close.
+    expect(onOpenChange).not.toHaveBeenCalledWith(false)
+  })
+
+  it('still closes the dialog on a genuine overlay click when no dropdown is open', async () => {
+    const onOpenChange = vi.fn()
+    render(
+      <Dialog onOpenChange={onOpenChange} open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <Select>
+            <SelectTrigger aria-label="picker">
+              <SelectValue placeholder="pick" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="a">Option A</SelectItem>
+            </SelectContent>
+          </Select>
+        </DialogContent>
+      </Dialog>
+    )
+
+    await flushTimers()
+
+    const overlay = document.querySelector('[data-slot="dialog-overlay"]') as HTMLElement
+    fireEvent.pointerDown(overlay, { button: 0 })
+    fireEvent.pointerUp(overlay, { button: 0 })
+    fireEvent.click(overlay, { button: 0 })
+    await flushTimers()
+
+    expect(onOpenChange).toHaveBeenCalledWith(false)
+  })
+})
diff --git a/apps/desktop/src/components/ui/dialog-portal-context.ts b/apps/desktop/src/components/ui/dialog-portal-context.ts
new file mode 100644
index 00000000000..88dde1f6b95
--- /dev/null
+++ b/apps/desktop/src/components/ui/dialog-portal-context.ts
@@ -0,0 +1,29 @@
+import * as React from 'react'
+
+// Layering system for portalled popovers (Select / Popover / DropdownMenu) that
+// open INSIDE a Dialog.
+//
+// By default every Radix popover portals to `document.body`, i.e. as a sibling
+// of the Dialog — OUTSIDE the dialog's DOM subtree. That breaks two things:
+//   1. Dismissing the popover (clicking elsewhere in the dialog) moves focus and
+//      fires pointer/focus events the Dialog's DismissableLayer reads as
+//      "outside", so the whole dialog closes.
+//   2. z-index across separate body-level portals is fragile — the popover and
+//      dialog live in different stacking siblings.
+//
+// The fix: a Dialog publishes its own content node here; any popover rendered
+// inside that Dialog portals into that node instead of `document.body`. Now the
+// popover is a real DOM descendant of the dialog — focus never leaves, the
+// DismissableLayer sees it as inside, and it shares the dialog's stacking
+// context so z-index is deterministic. Outside a dialog the value is null and
+// popovers fall back to the default body portal.
+export const DialogPortalContainerContext = React.createContext<HTMLElement | null>(null)
+
+// The container a popover should portal into: an explicit `container` prop wins,
+// then the enclosing dialog's content node, then undefined (Radix default:
+// document.body).
+export function usePopoverPortalContainer(explicit?: HTMLElement | null): HTMLElement | undefined {
+  const fromDialog = React.useContext(DialogPortalContainerContext)
+
+  return explicit ?? fromDialog ?? undefined
+}
diff --git a/apps/desktop/src/components/ui/dialog.test.tsx b/apps/desktop/src/components/ui/dialog.test.tsx
index 4b6d99a9bf0..afebf60760d 100644
--- a/apps/desktop/src/components/ui/dialog.test.tsx
+++ b/apps/desktop/src/components/ui/dialog.test.tsx
@@ -2,9 +2,40 @@ import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/re
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { Dialog, DialogContent, DialogTitle, preventCloseButtonAutoFocus } from './dialog'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from './select'
 
 afterEach(cleanup)
 
+describe('Select portalled inside a Dialog', () => {
+  it('renders the open dropdown inside the dialog DOM subtree, not document.body', () => {
+    // Force the Select open (defaultOpen) to sidestep jsdom's missing
+    // hasPointerCapture on the trigger. The dropdown content must land inside the
+    // dialog content node — that DOM nesting is what keeps focus in the dialog so
+    // dismissing the dropdown no longer closes the dialog.
+    render(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <Select defaultOpen>
+            <SelectTrigger aria-label="picker">
+              <SelectValue placeholder="pick" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="a">Option A</SelectItem>
+            </SelectContent>
+          </Select>
+        </DialogContent>
+      </Dialog>
+    )
+
+    const dialog = screen.getByRole('dialog')
+    const option = screen.getByText('Option A')
+
+    // The dropdown item is a descendant of the dialog, i.e. portalled into it.
+    expect(dialog.contains(option)).toBe(true)
+  })
+})
+
 describe('DialogContent close button', () => {
   it('closes the dialog when clicked', () => {
     const onOpenChange = vi.fn()
diff --git a/apps/desktop/src/components/ui/dialog.tsx b/apps/desktop/src/components/ui/dialog.tsx
index a88ebc086e1..d84bb30c345 100644
--- a/apps/desktop/src/components/ui/dialog.tsx
+++ b/apps/desktop/src/components/ui/dialog.tsx
@@ -2,6 +2,7 @@ import { Dialog as DialogPrimitive } from 'radix-ui'
 import * as React from 'react'
 
 import { Button } from '@/components/ui/button'
+import { DialogPortalContainerContext } from '@/components/ui/dialog-portal-context'
 import { Tip } from '@/components/ui/tooltip'
 import { useI18n } from '@/i18n'
 import { X } from '@/lib/icons'
@@ -85,6 +86,15 @@ function DialogContent({
 
   const widthClass = fitContent ? 'w-auto max-w-[92vw]' : 'w-full max-w-lg'
 
+  // Publish the dialog's content node so popovers (Select / Popover /
+  // DropdownMenu) opened inside it portal INTO the dialog instead of
+  // document.body. That keeps them as DOM descendants — focus never leaves the
+  // dialog, so dismissing a dropdown (or clicking another field) no longer
+  // trips the Dialog's outside-interaction/focus-out close. See
+  // dialog-portal-context.ts. State (not just a ref) so consumers re-render once
+  // the node mounts.
+  const [contentNode, setContentNode] = React.useState<HTMLElement | null>(null)
+
   // No default here — Radix's normal autofocus (first focusable element, often
   // an input) is what most dialogs want. Dialogs with no input should pass
   // `onOpenAutoFocus={preventCloseButtonAutoFocus}` explicitly instead.
@@ -129,25 +139,28 @@ function DialogContent({
           )}
           data-slot="dialog-content"
           onOpenAutoFocus={onOpenAutoFocus}
+          ref={setContentNode}
           {...props}
         >
-          {/* Scroll lives on an inner box so this shell keeps a painted bottom radius. */}
-          <div className="relative z-10 overflow-hidden rounded-xl border border-b-0 border-(--stroke-nous) bg-(--ui-chat-bubble-background)">
-            <div className="grid max-h-[calc(85vh-5rem)] min-h-0 gap-3 overflow-y-auto p-4">{children}</div>
-          </div>
-          <div
-            className={cn(
-              // Overlap by one corner radius so the white bottom lobes read clearly
-              // over the tint instead of meeting it on a straight seam.
-              'relative z-0 -mt-[var(--radius-xl)] px-4 pb-2.5 pt-[calc(var(--radius-xl)+0.625rem)] text-center text-[length:var(--conversation-tool-font-size)] leading-relaxed shadow-[inset_0_7px_7px_-4px_rgb(0_0_0/0.28)]',
-              DIALOG_BANNER_TONES[bannerTone]
-            )}
-            data-slot="dialog-banner"
-            role={bannerTone === 'error' ? 'alert' : 'status'}
-          >
-            {banner}
-          </div>
-          {closeButton}
+          <DialogPortalContainerContext.Provider value={contentNode}>
+            {/* Scroll lives on an inner box so this shell keeps a painted bottom radius. */}
+            <div className="relative z-10 overflow-hidden rounded-xl border border-b-0 border-(--stroke-nous) bg-(--ui-chat-bubble-background)">
+              <div className="grid max-h-[calc(85vh-5rem)] min-h-0 gap-3 overflow-y-auto p-4">{children}</div>
+            </div>
+            <div
+              className={cn(
+                // Overlap by one corner radius so the white bottom lobes read clearly
+                // over the tint instead of meeting it on a straight seam.
+                'relative z-0 -mt-[var(--radius-xl)] px-4 pb-2.5 pt-[calc(var(--radius-xl)+0.625rem)] text-center text-[length:var(--conversation-tool-font-size)] leading-relaxed shadow-[inset_0_7px_7px_-4px_rgb(0_0_0/0.28)]',
+                DIALOG_BANNER_TONES[bannerTone]
+              )}
+              data-slot="dialog-banner"
+              role={bannerTone === 'error' ? 'alert' : 'status'}
+            >
+              {banner}
+            </div>
+            {closeButton}
+          </DialogPortalContainerContext.Provider>
         </DialogPrimitive.Content>
       </DialogPortal>
     )
@@ -167,10 +180,13 @@ function DialogContent({
         )}
         data-slot="dialog-content"
         onOpenAutoFocus={onOpenAutoFocus}
+        ref={setContentNode}
         {...props}
       >
-        {children}
-        {closeButton}
+        <DialogPortalContainerContext.Provider value={contentNode}>
+          {children}
+          {closeButton}
+        </DialogPortalContainerContext.Provider>
       </DialogPrimitive.Content>
     </DialogPortal>
   )
diff --git a/apps/desktop/src/components/ui/dropdown-menu.tsx b/apps/desktop/src/components/ui/dropdown-menu.tsx
index 7c4c7072c12..57db60fba68 100644
--- a/apps/desktop/src/components/ui/dropdown-menu.tsx
+++ b/apps/desktop/src/components/ui/dropdown-menu.tsx
@@ -2,6 +2,7 @@ import { DropdownMenu as DropdownMenuPrimitive } from 'radix-ui'
 import * as React from 'react'
 
 import { Codicon } from '@/components/ui/codicon'
+import { usePopoverPortalContainer } from '@/components/ui/dialog-portal-context'
 import { cn } from '@/lib/utils'
 
 // Shared class tokens for edge-to-edge menus (use with `p-0` content): rows go
@@ -73,8 +74,12 @@ function DropdownMenuContent({
   sideOffset = 4,
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+  // Portal into the enclosing dialog when nested in one, so dismissing the menu
+  // doesn't close the dialog; document.body otherwise.
+  const container = usePopoverPortalContainer()
+
   return (
-    <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Portal container={container}>
       <DropdownMenuPrimitive.Content
         // `dt-portal-scrollbar` reproduces the thin themed scrollbar from
         // `.scrollbar-dt` for portaled overlays (Radix renders this under
diff --git a/apps/desktop/src/components/ui/field.tsx b/apps/desktop/src/components/ui/field.tsx
new file mode 100644
index 00000000000..7f3a79c5c98
--- /dev/null
+++ b/apps/desktop/src/components/ui/field.tsx
@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react'
+
+import { cn } from '@/lib/utils'
+
+// Shared form-field primitive for dialog forms: a label stacked above its
+// control, with an optional inline "(optional)" tag. Pair with FieldHint for
+// help text below the control. This is the single field language for every form
+// dialog (cron, webhooks, profiles, …) — don't hand-roll label+control stacks
+// or reach for the settings-surface ListRow inside a dialog. Stack Fields in a
+// `grid gap-4` form; pair two across with `grid items-start gap-4 sm:grid-cols-2`.
+export function Field({
+  children,
+  htmlFor,
+  label,
+  optional,
+  optionalLabel
+}: {
+  children: ReactNode
+  htmlFor?: string
+  label: ReactNode
+  optional?: boolean
+  optionalLabel?: string
+}) {
+  return (
+    <div className="grid gap-1.5">
+      <label className="flex items-baseline gap-2 text-xs font-medium text-foreground" htmlFor={htmlFor}>
+        {label}
+        {optional && optionalLabel && (
+          <span className="text-[0.65rem] font-normal text-muted-foreground">{optionalLabel}</span>
+        )}
+      </label>
+      {children}
+    </div>
+  )
+}
+
+export function FieldHint({ children, error }: { children: ReactNode; error?: boolean }) {
+  return (
+    <p className={cn('text-[0.66rem] leading-4', error ? 'text-destructive' : 'text-muted-foreground')}>{children}</p>
+  )
+}
diff --git a/apps/desktop/src/components/ui/glyph-spinner.tsx b/apps/desktop/src/components/ui/glyph-spinner.tsx
index bf42e587640..52e82412c88 100644
--- a/apps/desktop/src/components/ui/glyph-spinner.tsx
+++ b/apps/desktop/src/components/ui/glyph-spinner.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react'
 import spinners, { type BrailleSpinnerName as SpinnerName } from 'unicode-animations'
 
+import { usePaneVisible } from '@/components/pane-shell/pane-visibility'
 import { cn } from '@/lib/utils'
 
 export type { SpinnerName }
@@ -43,13 +44,20 @@ interface GlyphSpinnerProps {
 export function GlyphSpinner({ ariaLabel = 'Loading', className, spinner = 'braille' }: GlyphSpinnerProps) {
   const spin = FRAMES_BY_NAME[spinner] ?? FRAMES_BY_NAME.braille!
   const [frame, setFrame] = useState(0)
+  // Pause when this surface is a hidden (kept-alive) tab: N mounted tabs each
+  // ticking a setInterval + setState burn CPU for pixels nobody can see.
+  const visible = usePaneVisible()
 
   useEffect(() => {
+    if (!visible) {
+      return
+    }
+
     setFrame(0)
     const id = window.setInterval(() => setFrame(f => (f + 1) % spin.frames.length), spin.interval)
 
     return () => window.clearInterval(id)
-  }, [spin])
+  }, [spin, visible])
 
   return (
     <span
diff --git a/apps/desktop/src/components/ui/pane-tab.tsx b/apps/desktop/src/components/ui/pane-tab.tsx
index da8baae2aec..c7698bb944f 100644
--- a/apps/desktop/src/components/ui/pane-tab.tsx
+++ b/apps/desktop/src/components/ui/pane-tab.tsx
@@ -12,17 +12,22 @@ export const PANE_TAB_STRIP_LINE_RIGHT = 'shadow-[inset_-1px_0_0_var(--ui-stroke
 const TAB =
   'group/tab relative flex shrink-0 items-center border-transparent bg-(--tab-bg) text-[0.6875rem] font-medium [-webkit-app-region:no-drag]'
 
-const TAB_HORIZONTAL = 'h-full min-w-0 max-w-48 border-b not-first:border-l not-first:border-l-(--ui-stroke-quaternary)'
+// Stop 1px short: the strip's rule is an INSET shadow painted in the
+// container's own last pixel row, so a full-height tab covers it and reads as
+// overhanging the bar. The container owns the line; nothing redraws it.
+const TAB_HORIZONTAL =
+  'h-[calc(100%-1px)] min-w-0 max-w-48 not-first:border-l not-first:border-l-(--ui-stroke-quaternary)'
 
 const TAB_VERTICAL =
   'w-full max-h-48 justify-center not-first:border-t not-first:border-t-(--ui-stroke-quaternary) [writing-mode:vertical-rl]'
 
-const TAB_ACTIVE = 'text-foreground [--tab-bg:var(--pane-tab-active-bg,var(--ui-editor-surface-background))]'
+// Full height, so the active tab alone covers that row and cuts the rule.
+const TAB_ACTIVE = 'h-full text-foreground [--tab-bg:var(--pane-tab-active-bg,var(--ui-editor-surface-background))]'
 
-// Inactive = gutter. Hover = 4% translucent wash (VS Code/GitHub alpha hover),
-// not an opaque recolor — and never touch borders.
+// Inactive = gutter. Hover DARKENS: active is the lighter content surface, so a
+// lightening wash made the two nearly indistinguishable.
 const TAB_IDLE =
-  'text-(--ui-text-tertiary) [--tab-bg:var(--pane-tab-strip-bg,var(--theme-card-seed))] hover:shadow-[inset_0_0_0_100vmax_color-mix(in_srgb,var(--ui-base)_4%,transparent)] hover:text-(--ui-text-secondary)'
+  'text-(--ui-text-tertiary) [--tab-bg:var(--pane-tab-strip-bg,var(--theme-card-seed))] hover:shadow-[inset_0_0_0_100vmax_color-mix(in_srgb,#000_var(--ui-tab-hover-darken),transparent)] hover:text-(--ui-text-secondary)'
 
 interface PaneTabProps extends React.ComponentProps<'div'> {
   active?: boolean
@@ -66,9 +71,9 @@ export const PaneTab = React.forwardRef<HTMLDivElement, PaneTabProps>(function P
   },
   ref
 ) {
-  // Content-facing edge: horizontal cuts the bottom strip line; vertical cuts
-  // the side that faces the editor (left rail → right edge, right rail → left).
-  const edge = vertical ? (side === 'right' ? 'border-l' : 'border-r') : 'border-b'
+  // Vertical rails only. Horizontal tabs draw no bottom border — the strip owns
+  // that rule, and a per-tab border stacked a second translucent line over it.
+  const edge = vertical ? (side === 'right' ? 'border-l' : 'border-r') : undefined
 
   return (
     <div
@@ -76,7 +81,7 @@ export const PaneTab = React.forwardRef<HTMLDivElement, PaneTabProps>(function P
         TAB,
         vertical ? TAB_VERTICAL : TAB_HORIZONTAL,
         edge,
-        active ? TAB_ACTIVE : cn(TAB_IDLE, `${edge}-(--ui-stroke-tertiary)`),
+        active ? TAB_ACTIVE : cn(TAB_IDLE, edge && `${edge}-(--ui-stroke-tertiary)`),
         className
       )}
       data-active={active}
diff --git a/apps/desktop/src/components/ui/popover.tsx b/apps/desktop/src/components/ui/popover.tsx
index f7bd2b750b6..16fa23f7a4c 100644
--- a/apps/desktop/src/components/ui/popover.tsx
+++ b/apps/desktop/src/components/ui/popover.tsx
@@ -1,6 +1,7 @@
 import { Popover as PopoverPrimitive } from 'radix-ui'
 import * as React from 'react'
 
+import { usePopoverPortalContainer } from '@/components/ui/dialog-portal-context'
 import { cn } from '@/lib/utils'
 
 function Popover({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Root>) {
@@ -27,8 +28,12 @@ function PopoverContent({
   sideOffset = 6,
   ...props
 }: React.ComponentProps<typeof PopoverPrimitive.Content>) {
+  // Portal into the enclosing dialog when nested in one (keeps focus inside so
+  // the dialog doesn't close on dismiss); document.body otherwise.
+  const container = usePopoverPortalContainer()
+
   return (
-    <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Portal container={container}>
       <PopoverPrimitive.Content
         align={align}
         arrowPadding={arrowPadding}
diff --git a/apps/desktop/src/components/ui/select.tsx b/apps/desktop/src/components/ui/select.tsx
index c9769034fe2..151316eec0c 100644
--- a/apps/desktop/src/components/ui/select.tsx
+++ b/apps/desktop/src/components/ui/select.tsx
@@ -3,6 +3,7 @@ import * as React from 'react'
 
 import { Codicon } from '@/components/ui/codicon'
 import { type ControlVariantProps, controlVariants } from '@/components/ui/control'
+import { usePopoverPortalContainer } from '@/components/ui/dialog-portal-context'
 import { cn } from '@/lib/utils'
 
 function Select({ ...props }: React.ComponentProps<typeof SelectPrimitive.Root>) {
@@ -43,8 +44,13 @@ function SelectContent({
   position = 'popper',
   ...props
 }: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  // Portal into the enclosing dialog (if any) so the dropdown is a DOM
+  // descendant of the dialog — keeps focus inside and stops the dialog closing
+  // when the dropdown is dismissed. Falls back to document.body outside a dialog.
+  const container = usePopoverPortalContainer()
+
   return (
-    <SelectPrimitive.Portal>
+    <SelectPrimitive.Portal container={container}>
       <SelectPrimitive.Content
         className={cn(
           'relative z-[140] max-h-72 min-w-32 overflow-hidden rounded-md border border-border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=top]:slide-in-from-bottom-2 data-[side=right]:slide-in-from-left-2',
diff --git a/apps/desktop/src/components/ui/tool-icon.tsx b/apps/desktop/src/components/ui/tool-icon.tsx
index 11119855ea0..104ba6cc390 100644
--- a/apps/desktop/src/components/ui/tool-icon.tsx
+++ b/apps/desktop/src/components/ui/tool-icon.tsx
@@ -12,6 +12,8 @@ import { cn } from '@/lib/utils'
 // Paths are Phosphor Icons (MIT) "fill" weight, 256×256 viewBox. Inlining the
 // path data mirrors the existing precedent in `directive-text.tsx`.
 const TOOL_ICON_PATHS: Record<string, string> = {
+  brain:
+    'M248,124a56.11,56.11,0,0,0-32-50.61V72a48,48,0,0,0-88-26.49A48,48,0,0,0,40,72v1.39a56,56,0,0,0,0,101.22V176a48,48,0,0,0,88,26.49A48,48,0,0,0,216,176v-1.39A56.09,56.09,0,0,0,248,124ZM88,208a32,32,0,0,1-31.81-28.56A55.87,55.87,0,0,0,64,180h8a8,8,0,0,0,0-16H64A40,40,0,0,1,51.2,86.1a8,8,0,0,0,5.6-6.83A32,32,0,0,1,120,72v75.36A47.79,47.79,0,0,0,88,136a8,8,0,0,0,0,16,32,32,0,0,1,32,32A24,24,0,0,1,88,208Zm104-44h-8a8,8,0,0,0,0,16h8a55.87,55.87,0,0,0,7.81-.56A32,32,0,1,1,136,184a32,32,0,0,1,32-32,8,8,0,0,0,0-16,47.79,47.79,0,0,0-32,11.36V72a32,32,0,0,1,63.2-7.27,8,8,0,0,0,5.6,6.83A40,40,0,0,1,192,164Z',
   diff: 'M118.18,213.08c-.11.14-.24.27-.36.4l-.16.18-.17.15a4.83,4.83,0,0,1-.42.37,3.92,3.92,0,0,1-.32.25l-.3.22-.38.23a2.91,2.91,0,0,1-.3.17l-.37.19-.34.15-.36.13a2.84,2.84,0,0,1-.38.13l-.36.1c-.14,0-.26.07-.4.09l-.42.07-.35.05a7,7,0,0,1-.79,0H64a8,8,0,0,1,0-16H92.69L55,162.34a23.85,23.85,0,0,1-7-17V95a32,32,0,1,1,16,0v50.38A8,8,0,0,0,66.34,151L104,188.69V160a8,8,0,0,1,16,0v48a7,7,0,0,1,0,.8c0,.11,0,.21,0,.32s0,.3-.07.46a2.83,2.83,0,0,1-.09.37c0,.13-.06.26-.1.39s-.08.23-.12.35l-.14.39-.15.31c-.06.13-.12.27-.19.4s-.11.18-.16.28l-.24.39-.21.28ZM208,161V110.63a23.85,23.85,0,0,0-7-17L163.31,56H192a8,8,0,0,0,0-16H143.82l-.6,0c-.14,0-.28,0-.41.06l-.37,0-.43.11-.33.08-.4.14-.34.13-.35.16-.36.18a3.14,3.14,0,0,0-.31.18c-.12.07-.25.14-.36.22a3.55,3.55,0,0,0-.31.23,3.81,3.81,0,0,0-.32.24c-.15.12-.28.24-.42.37l-.17.15-.16.18c-.12.13-.25.26-.36.4l-.26.35-.21.28-.24.39c-.05.1-.11.19-.16.28s-.13.27-.19.4l-.15.31-.14.39c0,.12-.09.23-.12.35s-.07.26-.1.39a2.83,2.83,0,0,0-.09.37c0,.16,0,.31-.07.46s0,.21-.05.32a7,7,0,0,0,0,.8V96a8,8,0,0,0,16,0V67.31L189.66,105a8,8,0,0,1,2.34,5.66V161a32,32,0,1,0,16,0Z',
   edit: 'M227.31,73.37,182.63,28.68a16,16,0,0,0-22.63,0L36.69,152A15.86,15.86,0,0,0,32,163.31V208a16,16,0,0,0,16,16H92.69A15.86,15.86,0,0,0,104,219.31L227.31,96a16,16,0,0,0,0-22.63ZM192,108.68,147.31,64l24-24L216,84.68Z',
   eye: 'M247.31,124.76c-.35-.79-8.82-19.58-27.65-38.41C194.57,61.26,162.88,48,128,48S61.43,61.26,36.34,86.35C17.51,105.18,9,124,8.69,124.76a8,8,0,0,0,0,6.5c.35.79,8.82,19.57,27.65,38.4C61.43,194.74,93.12,208,128,208s66.57-13.26,91.66-38.34c18.83-18.83,27.3-37.61,27.65-38.4A8,8,0,0,0,247.31,124.76ZM128,168a40,40,0,1,1,40-40A40,40,0,0,1,128,168Z',
diff --git a/apps/desktop/src/global.d.ts b/apps/desktop/src/global.d.ts
index d9d9af1ee13..c0c3c7f246f 100644
--- a/apps/desktop/src/global.d.ts
+++ b/apps/desktop/src/global.d.ts
@@ -211,6 +211,7 @@ declare global {
       onPowerResume?: (callback: () => void) => () => void
       onBootProgress: (callback: (payload: DesktopBootProgress) => void) => () => void
       getBootstrapState: () => Promise<DesktopBootstrapState>
+      continueBootstrapLocal: () => Promise<{ ok: boolean }>
       resetBootstrap: () => Promise<{ ok: boolean }>
       repairBootstrap: () => Promise<{ ok: boolean }>
       cancelBootstrap: () => Promise<{ ok: boolean; cancelled: boolean }>
@@ -627,6 +628,11 @@ export interface DesktopBootstrapUnsupportedPlatform {
   docsUrl: string
 }
 
+export interface DesktopBootstrapSetupChoice {
+  platform: string
+  activeRoot: string
+}
+
 export interface DesktopBootstrapState {
   active: boolean
   manifest: { type: 'manifest'; stages: DesktopBootstrapStageDescriptor[]; protocolVersion: number | null } | null
@@ -635,10 +641,18 @@ export interface DesktopBootstrapState {
   log: Array<{ ts: number; stage: string | null; line: string; stream?: 'stdout' | 'stderr' }>
   startedAt: number | null
   completedAt: number | null
+  setupChoice: DesktopBootstrapSetupChoice | null
   unsupportedPlatform: DesktopBootstrapUnsupportedPlatform | null
 }
 
 export type DesktopBootstrapEvent =
+  | { type: 'dismissed' }
+  | {
+      type: 'setup-choice'
+      active: boolean
+      platform?: string
+      activeRoot?: string
+    }
   | { type: 'manifest'; stages: DesktopBootstrapStageDescriptor[]; protocolVersion: number | null }
   | {
       type: 'stage'
diff --git a/apps/desktop/src/hermes.ts b/apps/desktop/src/hermes.ts
index 38b8e2fb85e..27a9e234680 100644
--- a/apps/desktop/src/hermes.ts
+++ b/apps/desktop/src/hermes.ts
@@ -6,10 +6,12 @@ import type {
   AnalyticsResponse,
   AudioSpeakResponse,
   AudioTranscriptionResponse,
+  AutomationBlueprint,
   AuxiliaryModelsResponse,
   BackendUpdateCheckResponse,
   ComputerUseStatus,
   ConfigSchemaResponse,
+  CronDeliveryTarget,
   CronJob,
   CronJobCreatePayload,
   CronJobUpdates,
@@ -58,7 +60,11 @@ import type {
   TerminalBackendsResponse,
   ToolsetConfig,
   ToolsetInfo,
-  ToolsetModelsResponse
+  ToolsetModelsResponse,
+  WebhookCreatePayload,
+  WebhookCreateResponse,
+  WebhookEnableResponse,
+  WebhooksResponse
 } from '@/types/hermes'
 
 // Desktop startup fires a burst of read-only data calls (config, profiles,
@@ -126,6 +132,8 @@ export type {
   AnalyticsTotals,
   AudioSpeakResponse,
   AudioTranscriptionResponse,
+  AutomationBlueprint,
+  AutomationBlueprintField,
   AuxiliaryModelsResponse,
   BackendUpdateCheckResponse,
   ComputerUseCheck,
@@ -133,6 +141,7 @@ export type {
   ComputerUseStatus,
   ConfigFieldSchema,
   ConfigSchemaResponse,
+  CronDeliveryTarget,
   CronJob,
   CronJobCreatePayload,
   CronJobSchedule,
@@ -202,7 +211,12 @@ export type {
   ToolsetConfig,
   ToolsetInfo,
   ToolsetModel,
-  ToolsetModelsResponse
+  ToolsetModelsResponse,
+  WebhookCreatePayload,
+  WebhookCreateResponse,
+  WebhookEnableResponse,
+  WebhookRoute,
+  WebhooksResponse
 } from '@/types/hermes'
 
 export class HermesGateway extends JsonRpcGatewayClient {
@@ -546,6 +560,19 @@ export function setSessionArchived(id: string, archived: boolean, profile?: stri
   })
 }
 
+// Mirror a sidebar pin to the backend "keep" flag so the sessions.auto_archive
+// sweep (which runs backend-side, blind to Desktop localStorage) never hides a
+// pinned chat. Best-effort: the sidebar stays localStorage-driven for its own
+// display; this only feeds the backend policy.
+export function setSessionPinnedRemote(id: string, pinned: boolean, profile?: string | null): Promise<{ ok: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean }>({
+    ...(profile ? { profile } : {}),
+    path: `/api/sessions/${encodeURIComponent(id)}`,
+    method: 'PATCH',
+    body: { pinned }
+  })
+}
+
 export function searchSessions(query: string): Promise<SessionSearchResponse> {
   return window.hermesDesktop.api<SessionSearchResponse>({
     path: `/api/sessions/search?q=${encodeURIComponent(query)}`
@@ -1109,6 +1136,55 @@ export function testMessagingPlatform(platformId: string): Promise<MessagingPlat
   })
 }
 
+// -- Webhooks (subscription CRUD) --------------------------------------------
+// The webhook receiver is its own gateway platform; subscriptions live in a
+// shared JSON store the CLI/dashboard also drive. Enable mutates config and
+// best-effort restarts the gateway; subscription changes hot-reload.
+
+export function getWebhooks(): Promise<WebhooksResponse> {
+  return window.hermesDesktop.api<WebhooksResponse>({
+    ...profileScoped(),
+    path: '/api/webhooks'
+  })
+}
+
+export function enableWebhooks(): Promise<WebhookEnableResponse> {
+  return window.hermesDesktop.api<WebhookEnableResponse>({
+    ...profileScoped(),
+    path: '/api/webhooks/enable',
+    method: 'POST'
+  })
+}
+
+export function createWebhook(body: WebhookCreatePayload): Promise<WebhookCreateResponse> {
+  return window.hermesDesktop.api<WebhookCreateResponse>({
+    ...profileScoped(),
+    path: '/api/webhooks',
+    method: 'POST',
+    body
+  })
+}
+
+export function deleteWebhook(name: string): Promise<{ ok: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean }>({
+    ...profileScoped(),
+    path: `/api/webhooks/${encodeURIComponent(name)}`,
+    method: 'DELETE'
+  })
+}
+
+export function setWebhookEnabled(
+  name: string,
+  enabled: boolean
+): Promise<{ enabled: boolean; name: string; ok: boolean }> {
+  return window.hermesDesktop.api<{ enabled: boolean; name: string; ok: boolean }>({
+    ...profileScoped(),
+    path: `/api/webhooks/${encodeURIComponent(name)}/enabled`,
+    method: 'PUT',
+    body: { enabled }
+  })
+}
+
 // Cron jobs are stored per-profile (<HERMES_HOME>/cron/jobs.json), and the
 // backend's list endpoint defaults to 'all'. Pass a concrete profile key to
 // list just that profile's jobs, or 'all' for the unified cross-profile view.
@@ -1140,6 +1216,18 @@ export async function getCronJobRuns(jobId: string, limit = 20): Promise<Session
   return runs ?? []
 }
 
+// The single source of truth for cron delivery targets (local + configured
+// gateways). Both the manual cron editor and the blueprint dialog use this so
+// they never offer a platform that isn't connected. Mirrors the dashboard.
+export async function getCronDeliveryTargets(): Promise<CronDeliveryTarget[]> {
+  const { targets } = await window.hermesDesktop.api<{ targets: CronDeliveryTarget[] }>({
+    ...profileScoped(),
+    path: '/api/cron/delivery-targets'
+  })
+
+  return targets ?? []
+}
+
 export function createCronJob(body: CronJobCreatePayload): Promise<CronJob> {
   return window.hermesDesktop.api<CronJob>({
     ...profileScoped(),
@@ -1190,6 +1278,37 @@ export function deleteCronJob(jobId: string): Promise<{ ok: boolean }> {
   })
 }
 
+// Automation Blueprints — parameterized cron templates the backend serves from
+// cron/blueprint_catalog.py. getAutomationBlueprints returns the gallery
+// (deliver options already rewritten to this machine's configured gateways);
+// instantiateAutomationBlueprint fills the slots and creates a real cron job via
+// the same create_job path as createCronJob.
+//
+// Profile-scoping is intentionally asymmetric: the GET catalog is global (the
+// list endpoint takes no profile — only deliver options are rewritten from the
+// configured gateways), so it carries only the profileScoped() header for
+// routing. instantiate creates a real per-profile job, so it names the target
+// profile explicitly via ?profile=. This mirrors the dashboard's api.ts.
+export function getAutomationBlueprints(): Promise<{ blueprints: AutomationBlueprint[] }> {
+  return window.hermesDesktop.api<{ blueprints: AutomationBlueprint[] }>({
+    ...profileScoped(),
+    path: '/api/cron/blueprints',
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function instantiateAutomationBlueprint(
+  body: { blueprint: string; values: Record<string, string> },
+  profile: string
+): Promise<CronJob> {
+  return window.hermesDesktop.api<CronJob>({
+    ...profileScoped(),
+    path: `/api/cron/blueprints/instantiate?profile=${encodeURIComponent(profile)}`,
+    method: 'POST',
+    body
+  })
+}
+
 export function getProfiles(): Promise<ProfilesResponse> {
   return window.hermesDesktop.api<ProfilesResponse>({
     path: '/api/profiles',
diff --git a/apps/desktop/src/i18n/ar.ts b/apps/desktop/src/i18n/ar.ts
new file mode 100644
index 00000000000..b4499101417
--- /dev/null
+++ b/apps/desktop/src/i18n/ar.ts
@@ -0,0 +1,2567 @@
+import { defineLocale } from './define-locale'
+
+export const ar = defineLocale({
+  common: {
+    apply: 'تطبيق',
+    back: 'رجوع',
+    save: 'حفظ',
+    saving: 'جار الحفظ...',
+    cancel: 'إلغاء',
+    change: 'تغيير',
+    choose: 'اختيار',
+    clear: 'مسح',
+    close: 'إغلاق',
+    collapse: 'طي',
+    confirm: 'تأكيد',
+    connect: 'اتصال',
+    connecting: 'جار الاتصال',
+    continue: 'متابعة',
+    copied: 'تم النسخ',
+    copy: 'نسخ',
+    copyFailed: 'فشل النسخ',
+    delete: 'حذف',
+    docs: 'الوثائق',
+    done: 'تم',
+    error: 'خطأ',
+    failed: 'فشل',
+    free: 'مجاني',
+    loading: 'جار التحميل...',
+    notSet: 'غير مضبوط',
+    refresh: 'تحديث',
+    remove: 'إزالة',
+    replace: 'استبدال',
+    retry: 'إعادة المحاولة',
+    run: 'تشغيل',
+    send: 'إرسال',
+    set: 'ضبط',
+    skip: 'تخطي',
+    update: 'تحديث',
+    on: 'مفعل',
+    off: 'معطل'
+  },
+  fileMenu: {
+    revealFinder: 'إظهار في Finder',
+    revealExplorer: 'إظهار في File Explorer',
+    revealFileManager: 'فتح المجلد الحاوي',
+    revealInSidebar: 'إظهار في شجرة الملفات',
+    copyPath: 'نسخ المسار',
+    copyRelativePath: 'نسخ المسار النسبي',
+    rename: 'إعادة تسمية...',
+    delete: 'حذف',
+    renameTitle: 'إعادة تسمية',
+    renameLabel: 'الاسم الجديد',
+    deleteTitle: name => `حذف ${name}؟`,
+    deleteBody: 'سيتم نقله إلى سلة المهملات — يمكنك استعادته من هناك.',
+    pathCopied: 'تم نسخ المسار'
+  },
+  boot: {
+    ready: 'Hermes Desktop جاهز',
+    desktopBootFailedWithMessage: message => `فشل تشغيل سطح المكتب: ${message}`,
+    steps: {
+      connectingGateway: 'جار الاتصال ببوابة سطح المكتب',
+      loadingSettings: 'جار تحميل إعدادات Hermes',
+      loadingSessions: 'جار تحميل الجلسات الأخيرة',
+      startingDesktopConnection: 'جار بدء اتصال سطح المكتب',
+      startingHermesDesktop: 'جار تشغيل Hermes Desktop...'
+    },
+    errors: {
+      backgroundExited: 'خرجت عملية Hermes الخلفية.',
+      backgroundExitedDuringStartup: 'خرجت عملية Hermes الخلفية أثناء بدء التشغيل.',
+      backendStopped: 'توقف الخلفية',
+      desktopBootFailed: 'فشل تشغيل سطح المكتب',
+      gatewayConnectionLost: 'انقطع الاتصال بالبوابة',
+      gatewaySignInRequired: 'تسجيل الدخول للبوابة مطلوب',
+      ipcBridgeUnavailable: 'جسر IPC لسطح المكتب غير متاح.'
+    },
+    failure: {
+      title: 'تعذر تشغيل Hermes',
+      description: 'لم تعمل البوابة الخلفية. جرب إحدى خطوات الاسترداد أدناه. لن يحذف ذلك محادثاتك أو إعداداتك.',
+      remoteTitle: 'تسجيل الدخول للبوابة البعيدة مطلوب',
+      remoteDescription: 'انتهت جلسة البوابة البعيدة. سجل الدخول مرة أخرى لإعادة الاتصال.',
+      retry: 'إعادة المحاولة',
+      repairInstall: 'إصلاح التثبيت',
+      useLocalGateway: 'استخدام البوابة المحلية',
+      openLogs: 'فتح السجلات',
+      repairHint: 'يعيد الإصلاح تشغيل المثبت وقد يستغرق بضع دقائق على جهاز جديد.',
+      remoteSignInHint: signInLabel =>
+        `يسجّل الخروج من جلسة المتصفح البعيدة المحفوظة، ثم يفتح ${signInLabel}. استخدم البوابة المحلية للتبديل إلى الخلفية المضمنة.`,
+      signOutAndSignIn: 'تسجيل الخروج وإعادة تسجيل الدخول',
+      hideRecentLogs: 'إخفاء السجلات الأخيرة',
+      showRecentLogs: 'إظهار السجلات الأخيرة',
+      signedInTitle: 'تم تسجيل الدخول',
+      signedInMessage: 'جار إعادة الاتصال بالبوابة البعيدة...',
+      signInIncompleteTitle: 'تسجيل الدخول غير مكتمل',
+      signInIncompleteMessage: 'أغلقت نافذة تسجيل الدخول قبل اكتمال المصادقة.',
+      signInFailed: 'فشل تسجيل الدخول',
+      signInToRemoteGateway: 'تسجيل الدخول للبوابة البعيدة',
+      signInWithProvider: provider => `تسجيل الدخول عبر ${provider}`,
+      identityProvider: 'مزود الهوية'
+    }
+  },
+  notifications: {
+    region: 'الإشعارات',
+    hide: 'إخفاء',
+    show: 'إظهار',
+    more: count => `${count} إشعار إضافي`,
+    clearAll: 'مسح الكل',
+    dismiss: 'إغلاق الإشعار',
+    details: 'التفاصيل',
+    copyDetail: 'نسخ التفاصيل',
+    copyDetailFailed: 'تعذر نسخ تفاصيل الإشعار',
+    backendOutOfDateTitle: 'الخلفية قديمة',
+    backendOutOfDateMessage: 'خلفية Hermes أقدم من إصدار سطح المكتب الحالي وقد لا تعمل كما يجب. حدثهما ليتوافقا.',
+    updateHermes: 'تحديث Hermes',
+    updateReadyTitle: 'التحديث جاهز',
+    updateReadyMessage: count => `${count} تغيير جديد متاح.`,
+    seeWhatsNew: 'عرض الجديد',
+    errors: {
+      elevenLabsNeedsKey: 'يتطلب ElevenLabs STT المفتاح ELEVENLABS_API_KEY.',
+      elevenLabsRejectedKey: 'رفض ElevenLabs مفتاح API (401).',
+      methodNotAllowed: 'رفضت خلفية سطح المكتب هذا الطلب (405 Method Not Allowed). جرب إعادة تشغيل Hermes Desktop.',
+      microphonePermission: 'تم رفض إذن الميكروفون.',
+      openaiRejectedApiKey: 'رفض OpenAI مفتاح API.',
+      openaiRejectedApiKeyWithStatus: status => `رفض OpenAI مفتاح API (${status} invalid_api_key).`,
+      openaiTtsNeedsKey: 'يتطلب OpenAI TTS المفتاح VOICE_TOOLS_OPENAI_KEY أو OPENAI_API_KEY.'
+    },
+    voice: {
+      configureSpeechToText: 'اضبط تحويل الكلام إلى نص لاستخدام وضع الصوت.',
+      couldNotStartSession: 'تعذر بدء جلسة الصوت',
+      microphoneAccessDenied: 'تم رفض الوصول إلى الميكروفون.',
+      microphoneConstraintsUnsupported: 'قيود الميكروفون غير مدعومة على هذا الجهاز.',
+      microphoneFailed: 'فشل الميكروفون',
+      microphoneInUse: 'الميكروفون مستخدم من تطبيق آخر.',
+      microphonePermissionDenied: 'تم رفض إذن الميكروفون.',
+      microphoneStartFailed: 'تعذر بدء تسجيل الميكروفون.',
+      microphoneUnsupported: 'هذا المتصفح لا يدعم تسجيل الميكروفون.',
+      noMicrophone: 'لم يتم العثور على ميكروفون.',
+      noSpeechDetected: 'لم يتم اكتشاف كلام',
+      playbackFailed: 'فشل تشغيل الصوت',
+      recordingFailed: 'فشل التسجيل',
+      transcriptionFailed: 'فشل التفريغ النصي',
+      transcriptionUnavailable: 'التفريغ النصي غير متاح.',
+      tryRecordingAgain: 'حاول التسجيل مرة أخرى.',
+      unavailable: 'الصوت غير متاح'
+    },
+    native: {
+      approvalTitle: 'مطلوب موافقة',
+      approveAction: 'موافقة',
+      rejectAction: 'رفض',
+      inputTitle: 'مطلوب إدخال',
+      inputBody: 'ينتظر Hermes ردّك.',
+      turnDoneTitle: 'أنهى Hermes',
+      turnDoneBody: 'الرد جاهز.',
+      turnErrorTitle: 'فشلت الجولة',
+      backgroundDoneTitle: 'انتهت المهمة في الخلفية',
+      backgroundFailedTitle: 'فشلت المهمة في الخلفية'
+    }
+  },
+  remoteDisplayBanner: {
+    message: reason => `العرض البرمجي نشط — تم اكتشاف شاشة بعيدة (${reason}). تم تعطيل تسريع GPU لمنع الوميض.`
+  },
+  titlebar: {
+    hideSidebar: 'إخفاء الشريط الجانبي',
+    showSidebar: 'إظهار الشريط الجانبي',
+    search: 'بحث',
+    searchTitle: 'البحث في الجلسات والعروض والإجراءات',
+    swapSidebarSides: 'تبديل جانبي الأشرطة',
+    swapSidebarSidesTitle: 'تبديل موضعي شريط الجلسات ومستكشف الملفات',
+    hideRightSidebar: 'إخفاء الشريط الأيمن',
+    showRightSidebar: 'إظهار الشريط الأيمن',
+    muteHaptics: 'كتم الاهتزازات',
+    unmuteHaptics: 'تفعيل الاهتزازات',
+    openSettings: 'فتح الإعدادات',
+    openStarmap: 'فتح خريطة الذاكرة',
+    openKeybinds: 'اختصارات لوحة المفاتيح',
+    layoutEditor: 'محرر التخطيط',
+    layoutEditorTitle: 'محرر التخطيط — انقر مع ⌘ لإعادة ضبط التخطيط'
+  },
+  keybinds: {
+    title: 'اختصارات لوحة المفاتيح',
+    subtitle: open => `انقر على اختصار لإعادة تعيينه · ${open} يعيد فتح هذه اللوحة.`,
+    search: 'ابحث في الاختصارات...',
+    rebind: 'إعادة تعيين',
+    reset: 'إعادة إلى الافتراضي',
+    resetAll: 'إعادة تعيين الكل',
+    pressKey: 'اضغط مفتاحا...',
+    set: 'مضبوط',
+    conflictWith: label => `مرتبط أيضا بـ “${label}”`,
+    categories: {
+      composer: 'المحرّر',
+      profiles: 'الملفات الشخصية',
+      session: 'الجلسة',
+      navigation: 'التنقل',
+      view: 'العرض'
+    },
+    actions: {
+      'keybinds.openPanel': 'فتح اختصارات لوحة المفاتيح',
+      'nav.commandPalette': 'فتح لوحة الأوامر',
+      'nav.commandCenter': 'فتح مركز الأوامر',
+      'nav.settings': 'فتح الإعدادات',
+      'nav.profiles': 'فتح الملفات الشخصية',
+      'nav.skills': 'فتح المهارات',
+      'nav.messaging': 'فتح المراسلة',
+      'nav.artifacts': 'فتح العناصر',
+      'nav.cron': 'فتح المهام المجدولة',
+      'nav.agents': 'فتح الوكلاء',
+      'session.new': 'جلسة جديدة',
+      'session.newTab': 'علامة تبويب جلسة جديدة',
+      'session.newWindow': 'جلسة جديدة في نافذة',
+      'session.next': 'الجلسة التالية',
+      'session.prev': 'الجلسة السابقة',
+      'session.slot.1': 'الانتقال إلى الجلسة الأخيرة 1',
+      'session.slot.2': 'الانتقال إلى الجلسة الأخيرة 2',
+      'session.slot.3': 'الانتقال إلى الجلسة الأخيرة 3',
+      'session.slot.4': 'الانتقال إلى الجلسة الأخيرة 4',
+      'session.slot.5': 'الانتقال إلى الجلسة الأخيرة 5',
+      'session.slot.6': 'الانتقال إلى الجلسة الأخيرة 6',
+      'session.slot.7': 'الانتقال إلى الجلسة الأخيرة 7',
+      'session.slot.8': 'الانتقال إلى الجلسة الأخيرة 8',
+      'session.slot.9': 'الانتقال إلى الجلسة الأخيرة 9',
+      'session.focusSearch': 'البحث في الجلسات',
+      'session.togglePin': 'تثبيت / إلغاء تثبيت الجلسة الحالية',
+      'workspace.newWorktree': 'worktree جديد',
+      'composer.focus': 'التركيز على المحرّر',
+      'composer.modelPicker': 'فتح منتقي النموذج',
+      'composer.voice': 'بدء / إيقاف المحادثة الصوتية',
+      'view.toggleSidebar': 'تبديل الشريط الجانبي للجلسات',
+      'view.toggleRightSidebar': 'تبديل متصفح الملفات',
+      'view.toggleReview': 'تبديل لوحة المراجعة',
+      'view.showFiles': 'إظهار متصفح الملفات',
+      'view.showTerminal': 'إظهار الطرفية',
+      'view.closeTab': 'إغلاق علامة التبويب',
+      'view.reopenTab': 'إعادة فتح علامة التبويب المغلقة',
+      'view.terminalSelection': 'إرسال تحديد الطرفية إلى المحرّر',
+      'view.closePreviewTab': 'إغلاق علامة تبويب المعاينة',
+      'view.flipPanes': 'تبديل جانبي الشريط الجانبي',
+      'appearance.toggleMode': 'تبديل الفاتح / الداكن',
+      'profile.default': 'الانتقال إلى الملف الشخصي الافتراضي',
+      'profile.switch.1': 'الانتقال إلى الملف الشخصي 1',
+      'profile.switch.2': 'الانتقال إلى الملف الشخصي 2',
+      'profile.switch.3': 'الانتقال إلى الملف الشخصي 3',
+      'profile.switch.4': 'الانتقال إلى الملف الشخصي 4',
+      'profile.switch.5': 'الانتقال إلى الملف الشخصي 5',
+      'profile.switch.6': 'الانتقال إلى الملف الشخصي 6',
+      'profile.switch.7': 'الانتقال إلى الملف الشخصي 7',
+      'profile.switch.8': 'الانتقال إلى الملف الشخصي 8',
+      'profile.switch.9': 'الانتقال إلى الملف الشخصي 9',
+      'profile.switch.10': 'الانتقال إلى الملف الشخصي 10',
+      'profile.switch.11': 'الانتقال إلى الملف الشخصي 11',
+      'profile.switch.12': 'الانتقال إلى الملف الشخصي 12',
+      'profile.switch.13': 'الانتقال إلى الملف الشخصي 13',
+      'profile.switch.14': 'الانتقال إلى الملف الشخصي 14',
+      'profile.switch.15': 'الانتقال إلى الملف الشخصي 15',
+      'profile.switch.16': 'الانتقال إلى الملف الشخصي 16',
+      'profile.switch.17': 'الانتقال إلى الملف الشخصي 17',
+      'profile.switch.18': 'الانتقال إلى الملف الشخصي 18',
+      'profile.next': 'الملف الشخصي التالي',
+      'profile.prev': 'الملف الشخصي السابق',
+      'profile.toggleAll': 'تبديل عرض كل الملفات الشخصية',
+      'profile.create': 'إنشاء ملف شخصي',
+      'composer.send': 'إرسال الرسالة',
+      'composer.newline': 'إدراج سطر جديد',
+      'composer.steer': 'توجيه الدور الجاري',
+      'composer.sendQueued': 'إرسال الدور التالي في الطابور',
+      'composer.mention': 'الإشارة إلى الملفات والمجلدات وعناوين URL',
+      'composer.slash': 'لوحة الأوامر المائلة',
+      'composer.help': 'مساعدة سريعة',
+      'composer.history': 'التنقل في النافذة المنبثقة / السجل',
+      'composer.cancel': 'إغلاق النافذة المنبثقة · إلغاء التشغيل'
+    }
+  },
+  language: {
+    label: 'اللغة',
+    description: 'اختر لغة واجهة سطح المكتب.',
+    saving: 'جار حفظ اللغة...',
+    saveError: 'تعذر تحديث اللغة',
+    switchTo: 'تغيير اللغة',
+    searchPlaceholder: 'ابحث عن لغة...',
+    noResults: 'لا توجد لغة مطابقة'
+  },
+  settings: {
+    closeSettings: 'إغلاق الإعدادات',
+    exportConfig: 'تصدير الإعدادات',
+    importConfig: 'استيراد الإعدادات',
+    resetToDefaults: 'إعادة الافتراضيات',
+    resetConfirm: 'هل تريد إعادة كل الإعدادات إلى افتراضيات Hermes؟',
+    exportFailed: 'فشل التصدير',
+    resetFailed: 'فشلت إعادة الضبط',
+    nav: {
+      providers: 'المزودون',
+      providerAccounts: 'الحسابات',
+      providerApiKeys: 'مفاتيح API',
+      gateway: 'البوابة',
+      apiKeys: 'الأدوات والمفاتيح',
+      keysTools: 'الأدوات',
+      keysSettings: 'الإعدادات',
+      mcp: 'MCP',
+      archivedChats: 'المحادثات المؤرشفة',
+      about: 'حول',
+      notifications: 'الإشعارات',
+      keybinds: 'اختصارات لوحة المفاتيح',
+      plugins: 'الإضافات'
+    },
+    plugins: {
+      title: 'إضافات سطح المكتب',
+      blurb:
+        'امتدادات واجهة تُحمّل داخل هذا التطبيق — إما مضمّنة مع البناء، أو موضوعة في مجلد desktop-plugins (بما فيها التي يكتبها Hermes). تعطيل الإضافة يفرغها مباشرة ويبقى بعد إعادة التشغيل.',
+      count: n => `${n} مثبتة`,
+      openFolder: 'فتح مجلد الإضافات',
+      rescan: 'إعادة الفحص',
+      reveal: 'إظهار في مدير الملفات',
+      enable: 'تفعيل',
+      disable: 'تعطيل',
+      failed: 'فشل',
+      empty: 'لا توجد إضافات سطح مكتب مثبتة بعد.',
+      kinds: { bundled: 'مضمّنة', disk: 'على القرص', runtime: 'وقت التشغيل' }
+    },
+    notifications: {
+      title: 'الإشعارات',
+      intro:
+        'إشعارات سطح المكتب الأصلية، منفصلة عن التنبيهات داخل التطبيق. هذه محلية على الجهاز — كل حاسوب يحتفظ بإعداداته الخاصة.',
+      enableAll: 'تفعيل الإشعارات',
+      enableAllDesc: 'مفتاح رئيسي. أوقفه لإسكات كل الإشعارات أدناه.',
+      focusedHint: 'تنبيهات الاكتمال تظهر فقط عندما يكون Hermes في الخلفية.',
+      kinds: {
+        approval: {
+          label: 'يلزم الموافقة',
+          description: 'هناك أمر ينتظر موافقتك أو رفضك له.'
+        },
+        input: {
+          label: 'يلزم إدخال',
+          description: 'طرح Hermes سؤالا أو يحتاج إلى كلمة مرور أو سر.'
+        },
+        turnDone: {
+          label: 'الرد جاهز',
+          description: 'انتهى دور بينما كان Hermes في الخلفية.'
+        },
+        turnError: {
+          label: 'فشل الدور',
+          description: 'انتهى دور بخطأ.'
+        },
+        backgroundDone: {
+          label: 'اكتملت مهمة الخلفية',
+          description: 'اكتمل أمر طرفية يعمل في الخلفية.'
+        }
+      },
+      test: 'إرسال إشعار تجريبي',
+      testTitle: 'Hermes',
+      testBody: 'الإشعارات تعمل.',
+      testSent: 'تم إرسال التجربة. إذا لم يظهر شيء، تحقق من أذونات الإشعارات في نظام التشغيل ووضع التركيز/عدم الإزعاج.',
+      testUnsupported: 'هذا النظام لا يدعم الإشعارات الأصلية.',
+      completionSoundTitle: 'صوت الاكتمال',
+      completionSoundDesc: 'يُشغّل عند انتهاء دور الوكيل. اختر إعدادا مسبقا وعاينه هنا.',
+      completionSoundPreview: 'معاينة'
+    },
+    sections: {
+      model: 'النموذج',
+      chat: 'المحادثة',
+      appearance: 'المظهر',
+      workspace: 'مساحة العمل',
+      safety: 'الأمان',
+      memory: 'الذاكرة والسياق',
+      voice: 'الصوت',
+      advanced: 'متقدم'
+    },
+    searchPlaceholder: {
+      about: 'حول Hermes Desktop',
+      config: 'ابحث في الإعدادات...',
+      gateway: 'اتصال البوابة...',
+      keys: 'ابحث في مفاتيح API...',
+      mcp: 'ابحث في خوادم MCP...',
+      sessions: 'ابحث في المحادثات المؤرشفة...'
+    },
+    modeOptions: {
+      light: {
+        label: 'فاتح',
+        description: 'أسطح سطح مكتب ساطعة'
+      },
+      dark: {
+        label: 'داكن',
+        description: 'مساحة عمل منخفضة الوهج'
+      },
+      system: {
+        label: 'النظام',
+        description: 'اتباع مظهر نظام التشغيل'
+      }
+    },
+    appearance: {
+      title: 'المظهر',
+      intro: 'خصص مظهر Hermes Desktop.',
+      colorMode: 'نمط الألوان',
+      colorModeDesc: 'اختر الوضع الفاتح أو الداكن أو اتبع النظام.',
+      toolViewTitle: 'عرض الأدوات',
+      toolViewDesc: 'تحكم في كيفية عرض نشاط الأدوات داخل المحادثة.',
+      translucencyTitle: 'شفافية النافذة',
+      translucencyDesc: 'إظهار سطح المكتب من خلال النافذة بالكامل. متاح على macOS وWindows فقط.',
+      backdropTitle: 'خلفية النافذة',
+      backdropDesc: 'اختيار مقدار مزج خلفية سطح المكتب مع سطح Hermes.',
+      embedsTitle: 'التضمينات المضمّنة',
+      embedsDesc:
+        'تُحمّل المعاينات الغنية من مواقع طرف ثالث (YouTube، X، …). "اسأل" يعرض عنصرا نائبا حتى تسمح لكل واحد؛ "دائما" يحمّلها تلقائيا؛ "إيقاف" يبقي الروابط عادية.',
+      embedsAsk: 'اسأل',
+      embedsAlways: 'دائما',
+      embedsOff: 'إيقاف',
+      embedsReset: count => `إعادة تعيين ${count} ${count === 1 ? 'خدمة مسموح بها' : 'خدمة مسموح بها'}`,
+      product: 'مبسط',
+      productDesc: 'عرض أنظف يركز على النتيجة.',
+      technical: 'تقني',
+      technicalDesc: 'يعرض تفاصيل أكثر عن الأدوات والتنفيذ.',
+      themeTitle: 'الثيم',
+      themeDesc: 'اختر ثيم سطح المكتب.',
+      themeProfileNote: profile => `سيطبق هذا الثيم على الملف الشخصي ${profile}.`,
+      installTitle: 'تثبيت ثيم',
+      installDesc: 'ألصق رابط ثيم أو اسمه لتثبيته.',
+      installPlaceholder: 'رابط أو اسم الثيم',
+      installButton: 'تثبيت',
+      installing: 'جار التثبيت...',
+      installError: 'فشل تثبيت الثيم',
+      installed: name => `تم تثبيت ${name}`,
+      removeTheme: 'إزالة الثيم',
+      importedBadge: 'مستورد',
+      pet: {
+        title: 'حيوان أليف',
+        intro:
+          'تبنَّ تعويذة petdex متحركة تطفو فوق التطبيق وتتفاعل مع ما يفعله Hermes — تجري أثناء تنفيذ الأدوات، وتحتفل عند النجاح، وتعبس عند الأخطاء.',
+        restartHint:
+          'تحتاج الحيوانات الأليفة إلى إعادة تشغيل سريعة — بدأ التطبيق العامل قبل إضافة هذه الميزة. أغلق Hermes وأعد فتحه، ثم ارجع إلى هنا.',
+        on: 'تشغيل',
+        off: 'إيقاف',
+        scaleTitle: 'الحجم',
+        scaleDesc: 'غيّر حجم التعويذة الطافية. يُطبّق في كل مكان فورا.',
+        chooseTitle: 'اختر حيوانا أليفا',
+        chooseDesc: 'اختياره يثبّته (إن لزم) ويجعله نشطا.',
+        searchPlaceholder: 'البحث عن حيوانات أليفة...',
+        unreachable: 'تعذّر الوصول إلى معرض petdex. تحقق من اتصالك وأعد فتح هذه الصفحة.',
+        noMatch: query => `لا توجد حيوانات أليفة تطابق "${query}".`,
+        installedTag: 'مثبّت',
+        generatedTag: 'مُولّد',
+        countCapped: (cap, total) => `عرض ${cap} من ${total} — اكتب لتضييق النتائج.`,
+        count: n => `${n} ${n === 1 ? 'حيوان أليف' : 'حيوان أليف'}.`,
+        uninstall: name => `إلغاء تثبيت ${name}`,
+        delete: name => `حذف ${name}`,
+        deleteTitle: name => `حذف ${name}؟`,
+        deleteBody: 'هذا يحذف الحيوان الأليف نهائيا — لا يمكن إعادة تثبيته.',
+        deleteConfirm: 'حذف',
+        rename: name => `إعادة تسمية ${name}`,
+        renameTitle: 'إعادة تسمية الحيوان الأليف',
+        renamePlaceholder: 'سمِّ حيوانك الأليف',
+        renameSave: 'حفظ',
+        exportPet: name => `تصدير ${name}`,
+        adoptFailed: slug => `تعذّر تبني ${slug}`,
+        uninstallFailed: slug => `تعذّر إلغاء تثبيت ${slug}`,
+        renameFailed: slug => `تعذّرت إعادة تسمية ${slug}`,
+        exportFailed: slug => `تعذّر تصدير ${slug}`,
+        noneAvailable: 'لا توجد حيوانات أليفة متاحة للتشغيل الآن.',
+        turnOnFailed: 'تعذّر تشغيل الحيوان الأليف.',
+        turnOffFailed: 'تعذّر إيقاف الحيوان الأليف.'
+      }
+    },
+    fieldLabels: {
+      model: 'النموذج الافتراضي',
+      modelContextLength: 'نافذة السياق',
+      fallbackProviders: 'النماذج الاحتياطية',
+      toolsets: 'مجموعات الأدوات المفعلة',
+      timezone: 'المنطقة الزمنية',
+      'display.personality': 'أسلوب المساعد',
+      'display.showReasoning': 'إظهار التفكير',
+      'agent.maxTurns': 'الحد الأقصى لخطوات الوكيل',
+      'agent.imageInputMode': 'مرفقات الصور',
+      'agent.apiMaxRetries': 'محاولات API',
+      'agent.serviceTier': 'مستوى الخدمة',
+      'agent.toolUseEnforcement': 'فرض استخدام الأدوات',
+      'terminal.cwd': 'مجلد العمل',
+      'terminal.backend': 'خلفية التنفيذ',
+      'terminal.timeout': 'مهلة الأوامر',
+      'terminal.persistentShell': 'صدفة مستمرة',
+      'terminal.envPassthrough': 'تمرير متغيرات البيئة',
+      'terminal.dockerImage': 'صورة Docker',
+      'terminal.singularityImage': 'صورة Singularity',
+      'terminal.modalImage': 'صورة Modal',
+      'terminal.daytonaImage': 'صورة Daytona',
+      fileReadMaxChars: 'حد قراءة الملفات',
+      'toolOutput.maxBytes': 'حد مخرجات الطرفية',
+      'toolOutput.maxLines': 'حد صفحات الملفات',
+      'toolOutput.maxLineLength': 'حد طول السطر',
+      'codeExecution.mode': 'نمط تنفيذ الكود',
+      'approvals.mode': 'نمط الموافقات',
+      'approvals.timeout': 'مهلة الموافقة',
+      'approvals.mcpReloadConfirm': 'تأكيد إعادة تحميل MCP',
+      commandAllowlist: 'قائمة الأوامر المسموحة',
+      'security.redactSecrets': 'إخفاء الأسرار',
+      'security.allowPrivateUrls': 'السماح بالروابط الخاصة',
+      'browser.allowPrivateUrls': 'روابط المتصفح الخاصة',
+      'browser.autoLocalForPrivateUrls': 'متصفح محلي للروابط الخاصة',
+      'checkpoints.enabled': 'نقاط حفظ الملفات',
+      'checkpoints.maxSnapshots': 'حد نقاط الحفظ',
+      'voice.recordKey': 'اختصار الصوت',
+      'voice.maxRecordingSeconds': 'أقصى مدة للتسجيل',
+      'voice.autoTts': 'قراءة الردود صوتياً',
+      'stt.enabled': 'تحويل الكلام إلى نص',
+      'stt.provider': 'مزود تحويل الكلام إلى نص',
+      'stt.local.model': 'نموذج التفريغ المحلي',
+      'stt.local.language': 'لغة التفريغ',
+      'stt.openai.model': 'نموذج OpenAI STT',
+      'stt.groq.model': 'نموذج Groq STT',
+      'stt.mistral.model': 'نموذج Mistral STT',
+      'stt.elevenlabs.modelId': 'نموذج ElevenLabs STT',
+      'stt.elevenlabs.languageCode': 'لغة ElevenLabs',
+      'stt.elevenlabs.tagAudioEvents': 'وسم أحداث الصوت',
+      'stt.elevenlabs.diarize': 'تمييز المتحدثين',
+      'tts.provider': 'مزود تحويل النص إلى كلام',
+      'tts.edge.voice': 'صوت Edge',
+      'tts.openai.model': 'نموذج OpenAI TTS',
+      'tts.openai.voice': 'صوت OpenAI',
+      'tts.elevenlabs.voiceId': 'صوت ElevenLabs',
+      'tts.elevenlabs.modelId': 'نموذج ElevenLabs',
+      'tts.xai.voiceId': 'صوت xAI (Grok)',
+      'tts.xai.language': 'لغة xAI',
+      'tts.minimax.model': 'نموذج MiniMax TTS',
+      'tts.minimax.voiceId': 'صوت MiniMax',
+      'tts.mistral.model': 'نموذج Mistral TTS',
+      'tts.mistral.voiceId': 'صوت Mistral',
+      'tts.gemini.model': 'نموذج Gemini TTS',
+      'tts.gemini.voice': 'صوت Gemini',
+      'tts.neutts.model': 'نموذج NeuTTS',
+      'tts.neutts.device': 'جهاز NeuTTS',
+      'tts.kittentts.model': 'نموذج KittenTTS',
+      'tts.kittentts.voice': 'صوت KittenTTS',
+      'tts.piper.voice': 'صوت Piper',
+      'memory.memoryEnabled': 'الذاكرة المستمرة',
+      'memory.userProfileEnabled': 'ملف المستخدم',
+      'memory.memoryCharLimit': 'ميزانية الذاكرة',
+      'memory.userCharLimit': 'ميزانية الملف الشخصي',
+      'memory.provider': 'مزود الذاكرة',
+      'context.engine': 'محرك السياق',
+      'compression.enabled': 'الضغط التلقائي',
+      'compression.threshold': 'عتبة الضغط',
+      'compression.targetRatio': 'هدف الضغط',
+      'compression.protectLastN': 'الرسائل الأخيرة المحمية',
+      'delegation.model': 'نموذج الوكيل الفرعي',
+      'delegation.provider': 'مزود الوكيل الفرعي',
+      'delegation.maxIterations': 'حد دورات الوكيل الفرعي',
+      'delegation.maxConcurrentChildren': 'الوكلاء الفرعيون المتوازيون',
+      'delegation.childTimeoutSeconds': 'مهلة الوكيل الفرعي',
+      'delegation.reasoningEffort': 'جهد تفكير الوكيل الفرعي',
+      'updates.nonInteractiveLocalChanges': 'تغييرات التحديث داخل التطبيق'
+    },
+    fieldDescriptions: {
+      model: 'يستخدم في المحادثات الجديدة ما لم تختر نموذجاً مختلفاً من محرر الرسائل.',
+      modelContextLength: 'اتركه 0 لاستخدام نافذة السياق المكتشفة للنموذج المحدد.',
+      fallbackProviders: 'إدخالات احتياطية بصيغة provider:model لتجربتها إذا فشل النموذج الافتراضي.',
+      'display.personality': 'أسلوب المساعد الافتراضي للجلسات الجديدة.',
+      'display.showReasoning': 'يعرض أقسام التفكير عندما توفرها الخلفية.',
+      timezone: 'تستخدم عندما يحتاج Hermes إلى سياق الوقت المحلي. اتركها فارغة لاستخدام منطقة النظام.',
+      'agent.imageInputMode': 'يتحكم في طريقة إرسال مرفقات الصور إلى النموذج.',
+      'agent.maxTurns': 'الحد الأعلى لدورات استدعاء الأدوات قبل أن يوقف Hermes التشغيل.',
+      'terminal.cwd': 'مجلد المشروع الافتراضي لعمل الأدوات والطرفية.',
+      'terminal.persistentShell': 'يحافظ على حالة الصدفة بين الأوامر عندما تدعمها الخلفية.',
+      'terminal.envPassthrough': 'متغيرات البيئة التي تمرر إلى تنفيذ الأدوات.',
+      'terminal.dockerImage': 'صورة الحاوية المستخدمة عند اختيار Docker كخلفية تنفيذ.',
+      'terminal.singularityImage': 'الصورة المستخدمة عند اختيار Singularity.',
+      'terminal.modalImage': 'الصورة المستخدمة عند اختيار Modal.',
+      'terminal.daytonaImage': 'الصورة المستخدمة عند اختيار Daytona.',
+      'codeExecution.mode': 'مدى تقييد تنفيذ الكود بالمشروع الحالي.',
+      fileReadMaxChars: 'أقصى عدد أحرف يستطيع Hermes قراءته من ملف واحد في الطلب.',
+      'approvals.mode': 'كيف يتعامل Hermes مع الأوامر التي تحتاج موافقة صريحة.',
+      'approvals.timeout': 'مدة انتظار طلبات الموافقة قبل انتهاء المهلة.',
+      'security.redactSecrets': 'يخفي الأسرار المكتشفة من المحتوى المرئي للنموذج قدر الإمكان.',
+      'checkpoints.enabled': 'ينشئ لقطات رجوع قبل تعديلات الملفات.',
+      'memory.memoryEnabled': 'يحفظ ذكريات دائمة يمكن أن تساعد الجلسات القادمة.',
+      'memory.userProfileEnabled': 'يحافظ على ملف مختصر لتفضيلات المستخدم.',
+      'context.engine': 'استراتيجية إدارة المحادثات الطويلة قرب حد السياق.',
+      'compression.enabled': 'يلخص السياق الأقدم عندما تكبر المحادثات.',
+      'voice.autoTts': 'ينطق ردود المساعد تلقائياً.',
+      'tts.xai.voiceId': 'معرف صوت xAI مثل eve أو معرف صوت مخصص.',
+      'tts.xai.language': 'رمز لغة النطق، مثل en.',
+      'tts.neutts.device': 'جهاز الاستدلال المحلي لـ NeuTTS.',
+      'stt.enabled': 'يفعل التفريغ الصوتي المحلي أو عبر مزود.',
+      'stt.elevenlabs.languageCode': 'رمز لغة ISO-639-3 اختياري. اتركه فارغاً للاكتشاف التلقائي.',
+      'updates.nonInteractiveLocalChanges':
+        'عندما يحدّث Hermes نفسه من التطبيق دون موجه طرفية، احتفظ بتعديلات المصدر المحلية أو تجاهلها.'
+    },
+    about: {
+      heading: 'حول Hermes',
+      version: value => `الإصدار ${value}`,
+      versionUnavailable: 'الإصدار غير متاح',
+      updates: 'التحديثات',
+      checkNow: 'التحقق الآن',
+      checking: 'جار التحقق...',
+      seeWhatsNew: 'عرض الجديد',
+      updateNow: 'تحديث الآن',
+      releaseNotes: 'ملاحظات الإصدار',
+      onLatest: 'أنت على أحدث إصدار',
+      installing: 'جار التثبيت...',
+      cantUpdate: 'تعذر التحديث',
+      cantReach: 'تعذر الوصول لخدمة التحديث',
+      tapCheck: 'اضغط للتحقق من التحديثات.',
+      updateReady: count => `${count} تحديث متاح`,
+      lastChecked: age => `آخر تحقق ${age}`,
+      justNowSuffix: 'الآن',
+      automaticUpdates: 'التحديثات التلقائية',
+      automaticUpdatesDesc: 'اسمح لـ Hermes بالتحقق من التحديثات وتثبيتها.',
+      branchCommit: (branch, commit) => `${branch} عند ${commit}`,
+      never: 'أبدا',
+      justNow: 'الآن',
+      minAgo: count => `قبل ${count} دقيقة`,
+      hoursAgo: count => `قبل ${count} ساعة`,
+      daysAgo: count => `قبل ${count} يوم`
+    },
+    config: {
+      none: 'لا شيء',
+      noneParen: '(لا شيء)',
+      notSet: 'غير مضبوط',
+      commaSeparated: 'قيم مفصولة بفواصل',
+      loading: 'جار تحميل إعدادات Hermes...',
+      emptyTitle: 'لا توجد إعدادات',
+      emptyDesc: 'لا يحتوي هذا القسم على إعدادات قابلة للتعديل.',
+      failedLoad: 'فشل تحميل الإعدادات',
+      autosaveFailed: 'فشل الحفظ التلقائي',
+      imported: 'تم استيراد الإعدادات',
+      invalidJson: 'JSON غير صالح'
+    },
+    credentials: {
+      pasteKey: 'لصق المفتاح',
+      pasteLabelKey: label => `لصق مفتاح ${label}`,
+      optional: 'اختياري',
+      enterValueFirst: 'أدخل قيمة أولا.',
+      couldNotSave: 'تعذّر حفظ بيانات الاعتماد.',
+      remove: 'إزالة',
+      getKey: 'احصل على مفتاح',
+      saving: 'جار الحفظ'
+    },
+    envActions: {
+      actionsFor: label => `إجراءات ${label}`,
+      credentialActions: 'إجراءات بيانات الاعتماد',
+      docs: 'الوثائق',
+      hideValue: 'إخفاء القيمة',
+      revealValue: 'إظهار القيمة',
+      replace: 'استبدال',
+      set: 'ضبط',
+      clear: 'مسح'
+    },
+    gateway: {
+      loading: 'جار تحميل إعدادات البوابة...',
+      unavailableTitle: 'إعدادات البوابة غير متاحة',
+      unavailableDesc: 'جسر IPC في سطح المكتب لا يوفّر إعدادات البوابة.',
+      title: 'اتصال البوابة',
+      envOverride: 'تجاوز من البيئة',
+      intro:
+        'يشغّل Hermes Desktop بوابة محلية خاصة افتراضياً. استخدم بوابة بعيدة عندما تريد أن يتحكم هذا التطبيق بخلفية Hermes تعمل مسبقاً على جهاز آخر أو خلف وكيل موثوق.',
+      appliesTo: 'ينطبق على',
+      allProfiles: 'كل الملفات الشخصية',
+      defaultConnection: 'الاتصال الافتراضي لكل ملف شخصي لا يملك تجاوزاً خاصاً.',
+      profileConnection: profile =>
+        `الاتصال المستخدم فقط عندما يكون "${profile}" هو الملف الشخصي النشط. اختر "استخدام البوابة الافتراضية" لإزالة التجاوز الخاص به.`,
+      envOverrideTitle: 'متغيرات البيئة تتحكم في جلسة سطح المكتب هذه.',
+      envOverrideDesc: 'أزل HERMES_DESKTOP_REMOTE_URL و HERMES_DESKTOP_REMOTE_TOKEN لاستخدام الإعداد المحفوظ أدناه.',
+      localTitle: 'بوابة محلية',
+      localDesc: 'تشغيل خلفية Hermes خاصة على localhost. هذا هو الافتراضي ويعمل دون اتصال.',
+      inheritTitle: 'استخدام البوابة الافتراضية',
+      inheritDesc: 'إزالة التجاوز الخاص بهذا الملف الشخصي واستخدام الاتصال الافتراضي.',
+      remoteTitle: 'بوابة بعيدة',
+      remoteDesc:
+        'صل واجهة سطح المكتب هذه بخلفية Hermes بعيدة. البوابات المستضافة تستخدم OAuth أو اسم مستخدم وكلمة مرور، والبوابات الذاتية قد تستخدم رمز جلسة.',
+      remoteUrlTitle: 'رابط البوابة البعيدة',
+      remoteUrlDesc: 'الرابط الأساسي لخلفية لوحة التحكم البعيدة. يمكن استخدام بادئات مسار مثل /hermes.',
+      probing: 'جار فحص طريقة مصادقة هذه البوابة...',
+      probeError: 'تعذر الوصول إلى هذه البوابة الآن. تحقق من الرابط وستظهر طريقة المصادقة عند الاستجابة.',
+      signedIn: 'تم تسجيل الدخول',
+      signIn: 'تسجيل الدخول',
+      signOut: 'تسجيل الخروج',
+      signInWith: provider => `تسجيل الدخول عبر ${provider}`,
+      authTitle: 'المصادقة',
+      authSignedInPassword: 'هذه البوابة تستخدم اسم مستخدم وكلمة مرور. أنت مسجل الدخول والجلسة تتجدد تلقائياً.',
+      authSignedInOauth: 'هذه البوابة تستخدم OAuth. أنت مسجل الدخول والجلسة تتجدد تلقائياً.',
+      authNeedsPassword: 'هذه البوابة تستخدم اسم مستخدم وكلمة مرور. سجل الدخول لتفويض تطبيق سطح المكتب.',
+      authNeedsOauth: provider => `هذه البوابة تستخدم OAuth. سجل الدخول عبر ${provider} لتفويض تطبيق سطح المكتب.`,
+      tokenTitle: 'رمز الجلسة',
+      tokenDesc: 'رمز جلسة لوحة التحكم المستخدم لطلبات REST و WebSocket. اتركه فارغاً للإبقاء على الرمز المحفوظ.',
+      existingToken: value => `رمز موجود ${value}`,
+      savedToken: 'محفوظ',
+      pasteSessionToken: 'ألصق رمز الجلسة',
+      testRemote: 'اختبار البعيد',
+      saveForRestart: 'حفظ للتشغيل القادم',
+      saveAndReconnect: 'حفظ وإعادة الاتصال',
+      diagnostics: 'التشخيصات',
+      diagnosticsDesc: 'اعرض desktop.log في مدير الملفات، وهذا مفيد عند فشل تشغيل البوابة.',
+      openLogs: 'فتح السجلات',
+      incompleteTitle: 'إعداد البوابة البعيدة غير مكتمل',
+      incompleteSignIn: 'أدخل رابط البوابة البعيدة وسجل الدخول قبل التبديل إلى البعيد.',
+      incompleteToken: 'أدخل رابط البوابة البعيدة ورمز الجلسة قبل التبديل إلى البعيد.',
+      incompleteSignInTest: 'أدخل رابط البوابة البعيدة وسجل الدخول قبل الاختبار.',
+      incompleteTokenTest: 'أدخل رابط البوابة البعيدة ورمز الجلسة قبل الاختبار.',
+      enterUrlFirst: 'أدخل رابط البوابة البعيدة أولاً.',
+      restartingTitle: 'جار إعادة تشغيل اتصال البوابة',
+      savedTitle: 'تم حفظ إعدادات البوابة',
+      restartingMessage: 'سيعيد Hermes Desktop الاتصال باستخدام الإعدادات المحفوظة.',
+      savedMessage: 'تم الحفظ للتشغيل القادم.',
+      connectedTo: (baseUrl, version) => `متصل بـ ${baseUrl}${version ? ` · Hermes ${version}` : ''}`,
+      reachableTitle: 'البوابة البعيدة قابلة للوصول',
+      signedOutTitle: 'تم تسجيل الخروج',
+      signedOutMessage: 'تم مسح جلسة البوابة البعيدة.',
+      failedLoad: 'فشل تحميل إعدادات البوابة',
+      signInFailed: 'فشل تسجيل الدخول',
+      signOutFailed: 'فشل تسجيل الخروج',
+      testFailed: 'فشل اختبار البوابة البعيدة',
+      applyFailed: 'تعذر تطبيق إعدادات البوابة',
+      saveFailed: 'تعذر حفظ إعدادات البوابة'
+    },
+    keys: {
+      loading: 'جار تحميل مفاتيح API وبيانات الاعتماد...',
+      failedLoad: 'فشل تحميل مفاتيح API',
+      empty: 'لا يوجد شيء مضبوط في هذه الفئة بعد.'
+    },
+    mcp: {
+      loading: 'جار تحميل خوادم MCP...',
+      failedLoad: 'فشل تحميل إعدادات MCP',
+      nameRequiredTitle: 'الاسم مطلوب',
+      nameRequiredMessage: 'أعط هذا الخادم مفتاح إعداد.',
+      objectRequired: 'يجب أن تكون إعدادات الخادم كائن JSON',
+      invalidJson: 'JSON الخاص بـ MCP غير صالح',
+      saveFailed: 'فشل الحفظ',
+      removeFailed: 'فشلت الإزالة',
+      gatewayUnavailableTitle: 'البوابة غير متاحة',
+      gatewayUnavailableMessage: 'أعد الاتصال بالبوابة قبل إعادة تحميل MCP.',
+      reloadedTitle: 'تمت إعادة تحميل أدوات MCP',
+      reloadedMessage: 'مخططات الأدوات الجديدة تطبق على الأدوار الجديدة.',
+      reloadFailed: 'فشلت إعادة تحميل MCP',
+      savedTitle: 'تم حفظ خادم MCP',
+      savedMessage: name => `سيطبق ${name} بعد إعادة تحميل MCP.`,
+      newServer: 'خادم جديد',
+      reload: 'إعادة تحميل MCP',
+      reloading: 'جار إعادة التحميل...',
+      emptyTitle: 'لا توجد خوادم MCP',
+      emptyDesc: 'أضف خادم stdio أو HTTP لإتاحة أدوات MCP.',
+      disabled: 'معطل',
+      editServer: 'تحرير الخادم',
+      name: 'الاسم',
+      serverJson: 'JSON الخادم',
+      remove: 'إزالة',
+      saveServer: 'حفظ الخادم'
+    },
+    model: {
+      loading: 'جار تحميل إعدادات النموذج...',
+      appliesDesc: 'ينطبق على الجلسات الجديدة. استخدم منتقي النموذج في صندوق الإنشاء لتبديل المحادثة النشطة فورا.',
+      provider: 'المزوّد',
+      model: 'النموذج',
+      applying: 'جار التطبيق...',
+      defaultsLabel: 'الافتراضيات',
+      reasoning: 'الاستدلال',
+      reasoningOff: 'إيقاف',
+      defaultsFailed: 'فشل حفظ افتراضيات النموذج',
+      auxiliaryTitle: 'النماذج المساعدة',
+      resetAllToMain: 'إعادة تعيين الكل إلى النموذج الرئيسي',
+      auxiliaryDesc: 'تعمل المهام المساعدة على النموذج الرئيسي افتراضيا. عيّن نموذجا مخصصا لأي مهمة لتجاوز ذلك.',
+      setToMain: 'ضبط على الرئيسي',
+      change: 'تغيير',
+      autoUseMain: 'تلقائي · استخدام النموذج الرئيسي',
+      providerDefault: '(افتراضي المزوّد)',
+      tasks: {
+        vision: {
+          label: 'الرؤية',
+          hint: 'تحليل الصور'
+        },
+        web_extract: {
+          label: 'استخراج الويب',
+          hint: 'تلخيص الصفحات'
+        },
+        compression: {
+          label: 'الضغط',
+          hint: 'ضغط السياق'
+        },
+        skills_hub: {
+          label: 'مركز المهارات',
+          hint: 'بحث المهارات'
+        },
+        approval: {
+          label: 'الموافقة',
+          hint: 'موافقة تلقائية ذكية'
+        },
+        mcp: {
+          label: 'MCP',
+          hint: 'توجيه أدوات MCP'
+        },
+        title_generation: {
+          label: 'توليد العناوين',
+          hint: 'عناوين الجلسات'
+        },
+        curator: {
+          label: 'المنسّق',
+          hint: 'مراجعة استخدام المهارات'
+        }
+      }
+    },
+    providers: {
+      connectAccount: 'ربط حساب',
+      haveApiKey: 'لديك مفتاح API بدلاً من ذلك؟',
+      intro: 'سجل الدخول باشتراكك دون نسخ مفتاح API. يشغّل Hermes تسجيل الدخول من المتصفح لك داخل التطبيق.',
+      connected: 'متصل',
+      collapse: 'طي',
+      connectAnother: 'ربط مزود آخر',
+      otherProviders: 'مزودون آخرون',
+      disconnect: 'قطع الاتصال',
+      disconnectInTerminal: 'قطع الاتصال (يشغّل أمر الإزالة في الطرفية)',
+      removeConfirm: provider => `إزالة ${provider}؟`,
+      removeExternalGeneric: provider => `${provider} يُدار عبر CLI خاص به — أزله من هناك.`,
+      removeKeyManaged: provider => `${provider} مُعدّ من مفتاح API. أزله من مفاتيح API.`,
+      removeTerminalConfirm: (provider, command) =>
+        `قطع اتصال ${provider}؟ هذا يشغّل "${command}" في الطرفية لمسح بيانات الاعتماد.`,
+      removeTerminalRunning: provider => `جار تشغيل قطع اتصال ${provider} في الطرفية…`,
+      removedTitle: 'تمت إزالة الحساب',
+      removedMessage: provider => `تمت إزالة ${provider}.`,
+      failedRemove: provider => `تعذّرت إزالة ${provider}`,
+      noProviderKeys: 'لا توجد مفاتيح API متاحة للمزودين.',
+      searchKeys: 'البحث عن مزوّدين...',
+      noKeysMatch: 'لا يوجد مزوّدون يطابقون بحثك.',
+      localEndpoint: {
+        title: 'نقطة نهاية محلية',
+        description: 'استخدم خادما محليا أو نقطة نهاية متوافقة مع OpenAI لهذا المزود.'
+      },
+      loading: 'جار تحميل المزودين...'
+    },
+    sessions: {
+      loading: 'جار تحميل الجلسات المؤرشفة...',
+      archivedTitle: 'الجلسات المؤرشفة',
+      archivedIntro:
+        'تُخفى المحادثات المؤرشفة من الشريط الجانبي مع الاحتفاظ بكل رسائلها. اضغط Ctrl/⌘ مع النقر على محادثة في الشريط الجانبي لأرشفتها.',
+      emptyArchivedTitle: 'لا توجد محادثات مؤرشفة',
+      emptyArchivedDesc: 'أرشف محادثة لإخفائها هنا.',
+      unarchive: 'إلغاء الأرشفة',
+      deletePermanently: 'حذف نهائي',
+      messages: count => `${count} ${count === 1 ? 'رسالة' : 'رسائل'}`,
+      restored: 'تمت الاستعادة',
+      deleteConfirm: title => `حذف "${title}" نهائياً؟ لا يمكن التراجع عن هذا.`,
+      defaultDirTitle: 'مجلد المشروع الافتراضي',
+      defaultDirDesc: 'تبدأ الجلسات الجديدة في هذا المجلد ما لم تختر غيره. اتركه غير مضبوط لاستخدام مجلدك الرئيسي.',
+      defaultDirUpdated: 'تم تحديث مجلد المشروع الافتراضي، ابدأ محادثة جديدة (Ctrl/⌘+N) ليطبق التغيير',
+      defaultsTo: label => `الافتراضي هو ${label}.`,
+      change: 'تغيير',
+      choose: 'اختيار',
+      clear: 'مسح',
+      notSet: 'غير مضبوط',
+      failedLoad: 'تعذر تحميل الجلسات المؤرشفة',
+      unarchiveFailed: 'فشل إلغاء الأرشفة',
+      deleteFailed: 'فشل الحذف',
+      updateDirFailed: 'تعذر تحديث المجلد الافتراضي',
+      clearDirFailed: 'تعذر مسح المجلد الافتراضي'
+    },
+    toolsets: {
+      loadingConfig: 'جار تحميل الإعدادات',
+      savedTitle: 'تم حفظ بيانات الاعتماد',
+      savedMessage: key => `تم تحديث ${key}.`,
+      removedTitle: 'تمت إزالة بيانات الاعتماد',
+      removedMessage: key => `تمت إزالة ${key}.`,
+      failedSave: key => `فشل حفظ ${key}`,
+      failedRemove: key => `فشل إزالة ${key}`,
+      failedReveal: key => `فشل إظهار ${key}`,
+      removeConfirm: key => `إزالة ${key} من .env؟`,
+      set: 'ضبط',
+      notSet: 'غير مضبوط',
+      selectedTitle: 'تم اختيار المزوّد',
+      selectedMessage: provider => `${provider} نشط الآن.`,
+      failedSelect: provider => `فشل اختيار ${provider}`,
+      failedLoad: 'فشل تحميل إعدادات الأدوات',
+      noProviderOptions: 'لا تحتوي مجموعة الأدوات هذه على خيارات مزوّد — فعّلها لتعمل مع إعدادك الحالي.',
+      noProviders: 'لا يوجد مزوّدون متاحون لمجموعة الأدوات هذه الآن.',
+      ready: 'جاهز',
+      nousIncluded: 'مُضمّن مع اشتراك Nous — سجّل الدخول إلى Nous Portal للتفعيل.',
+      noApiKeyRequired: 'لا يلزم مفتاح API.',
+      postSetupHint: step =>
+        `تحتاج هذه الخلفية إلى تثبيت لمرة واحدة (${step}). يعمل على هذا الجهاز — قد يستغرق بضع دقائق.`,
+      postSetupRun: 'تشغيل الإعداد',
+      postSetupRunning: 'جار التثبيت…',
+      postSetupStarting: 'جار البدء…',
+      postSetupCompleteTitle: 'اكتمل الإعداد',
+      postSetupCompleteMessage: step => `تم تثبيت ${step}.`,
+      postSetupErrorTitle: 'انتهى الإعداد بأخطاء',
+      postSetupErrorMessage: step => `تحقق من سجل ${step}.`,
+      postSetupFailed: step => `فشل تشغيل إعداد ${step}`
+    }
+  },
+  skills: {
+    tabSkills: 'المهارات',
+    tabToolsets: 'مجموعات الأدوات',
+    all: 'الكل',
+    searchSkills: 'البحث في المهارات',
+    searchToolsets: 'البحث في مجموعات الأدوات',
+    refresh: 'تحديث',
+    refreshing: 'جار التحديث...',
+    loading: 'جار التحميل...',
+    noSkillsTitle: 'لا توجد مهارات',
+    noSkillsDesc: 'ستظهر المهارات المثبتة هنا.',
+    noToolsetsTitle: 'لا توجد مجموعات أدوات',
+    noToolsetsDesc: 'ستظهر مجموعات الأدوات المتاحة هنا.',
+    noDescription: 'لا يوجد وصف',
+    configured: 'مضبوط',
+    needsKeys: 'يحتاج مفاتيح',
+    toolsetsEnabled: (enabled, total) => `${enabled} من ${total} مفعلة`,
+    configureToolset: label => `ضبط ${label}`,
+    toggleToolset: label => `تبديل ${label}`,
+    skillsLoadFailed: 'فشل تحميل المهارات',
+    toolsetsRefreshFailed: 'فشل تحديث مجموعات الأدوات',
+    skillEnabled: 'تم تفعيل المهارة',
+    skillDisabled: 'تم تعطيل المهارة',
+    toolsetEnabled: 'تم تفعيل مجموعة الأدوات',
+    toolsetDisabled: 'تم تعطيل مجموعة الأدوات',
+    appliesToNewSessions: name => `ينطبق على الجلسات الجديدة في ${name}`,
+    failedToUpdate: name => `فشل تحديث ${name}`
+  },
+  agents: {
+    close: 'إغلاق الوكلاء',
+    title: 'شجرة التوليد',
+    subtitle: 'نشاط الوكلاء الفرعيين المباشر للدور الحالي.',
+    emptyTitle: 'لا يوجد وكلاء فرعيون مباشرون',
+    emptyDesc: 'عندما يفوّض دور ما عملا، يبث الوكلاء الأبناء تقدّمهم هنا.',
+    running: 'قيد التشغيل',
+    failed: 'فشل',
+    done: 'تم',
+    streaming: 'جار البث',
+    files: 'الملفات',
+    moreFiles: count => `+${count} ملفات إضافية`,
+    delegation: index => `التفويض ${index}`,
+    workers: count => `${count} عامل`,
+    workersActive: count => `${count} نشط`,
+    agentsCount: count => `${count} ${count === 1 ? 'وكيل' : 'وكلاء'}`,
+    activeCount: count => `${count} نشط`,
+    failedCount: count => `${count} فشل`,
+    toolsCount: count => `${count} أداة`,
+    filesCount: count => `${count} ملف`,
+    updatedAgo: age => `تم التحديث ${age}`,
+    ageNow: 'الآن',
+    ageSeconds: seconds => `قبل ${seconds} ث`,
+    ageMinutes: minutes => `قبل ${minutes} د`,
+    ageHours: hours => `قبل ${hours} س`,
+    durationSeconds: seconds => `${seconds} ث`,
+    durationMinutes: (minutes, seconds) => `${minutes} د ${seconds} ث`,
+    tokens: value => `${value} رمز`
+  },
+  commandCenter: {
+    close: 'إغلاق',
+    paletteTitle: 'لوحة الأوامر',
+    back: 'رجوع',
+    searchPlaceholder: 'ابحث عن أمر أو إعداد...',
+    goTo: 'انتقال إلى',
+    goToSession: 'الانتقال إلى الجلسة',
+    branches: 'الفروع',
+    startInBranch: branch => `محادثة جديدة في ${branch}`,
+    commandCenter: 'مركز الأوامر',
+    appearance: 'المظهر',
+    settings: 'الإعدادات',
+    changeTheme: 'تغيير الثيم',
+    changeColorMode: 'تغيير نمط الألوان',
+    pets: {
+      title: 'الحيوانات الأليفة',
+      placeholder: 'البحث في الحيوانات الأليفة...',
+      loading: 'جار تحميل معرض petdex...',
+      error: 'تعذّر الوصول إلى معرض petdex.',
+      staleBackend: 'أعد تشغيل Hermes لاستخدام الحيوانات الأليفة — الخادم الخلفي أقدم من هذه الميزة.',
+      empty: 'لا توجد حيوانات أليفة مطابقة.',
+      turnOff: 'إيقاف التشغيل',
+      turnOn: 'تشغيل',
+      installed: 'مثبّت',
+      generatedTag: 'مُولّد',
+      adoptFailed: 'تعذّر تبنّي ذلك الحيوان الأليف.',
+      toggleFailed: 'تعذّر تبديل الحيوان الأليف.',
+      noneAvailable: 'لا توجد حيوانات أليفة متاحة — اختر واحدا أدناه لتثبيته.'
+    },
+    generatePet: {
+      title: 'توليد حيوان أليف',
+      placeholder: 'صف حيوانا أليفا لتوليده...',
+      promptHint: 'اكتب وصفا، ثم اضغط Enter لرسم أربعة مظاهر.',
+      readyHint: 'اضغط Enter لرسم أربعة مظاهر من وصفك.',
+      generate: 'توليد',
+      generating: 'جار التوليد...',
+      retry: 'إعادة المحاولة',
+      hatch: 'تفقيس',
+      spawning: 'جار الإنشاء...',
+      hatching: 'جار تفقيس حيوانك الأليف...',
+      hatchingSub: 'جار بثّ الحياة فيه...',
+      hatched: 'تم التفقيس!',
+      hatchRow: (_state, done, total) => `جار رسم الإطار ${done} من ${total}...`,
+      hatchComposing: 'جار تجميع الأجزاء...',
+      hatchSaving: 'أوشكنا على الانتهاء...',
+      namePlaceholder: 'سمِّ حيوانك الأليف',
+      staleBackend: 'حدّث Hermes لتوليد الحيوانات الأليفة.',
+      backgroundHint: 'يمكنك إغلاق هذا — سيُعلِمك Hermes عند الانتهاء.',
+      slowProviderHint: 'قد يستغرق هذا عدة دقائق',
+      remix: 'إعادة مزج',
+      remixConfirmTitle: 'إعادة مزج هذا المظهر؟',
+      remixConfirmBody: 'يولّد هذا مجموعة جديدة من المسوّدات باستخدام هذا كنقطة بداية. قد يستغرق عدة دقائق.',
+      genericError: 'فشل التوليد — حاول مجددا أو اختر اقتراحا.',
+      referenceImageTooLarge: 'صورة المرجع كبيرة جدا. استخدم واحدة أقل من 16 MB.',
+      referenceImageInvalid: 'تعذّرت قراءة صورة المرجع تلك. جرّب PNG أو JPG أو WebP أو GIF.',
+      adopt: 'تبنّي',
+      startOver: 'البدء من جديد'
+    },
+    installTheme: {
+      title: 'تثبيت سمة...',
+      placeholder: 'البحث في VS Code Marketplace...',
+      loading: 'جار البحث في Marketplace...',
+      error: 'تعذّر الوصول إلى Marketplace.',
+      empty: 'لا توجد سمات مطابقة.',
+      install: 'تثبيت',
+      installing: 'جار التثبيت...',
+      installed: 'مثبّت',
+      installs: count => `${count} عملية تثبيت`
+    },
+    settingsFields: 'حقول الإعدادات',
+    mcpServers: 'خوادم MCP',
+    archivedChats: 'المحادثات المؤرشفة',
+    commands: 'الأوامر',
+    sections: {
+      sessions: 'الجلسات',
+      system: 'النظام',
+      usage: 'الاستخدام'
+    },
+    sectionDescriptions: {
+      sessions: 'البحث في الجلسات وإدارتها',
+      system: 'الحالة والسجلات وإجراءات النظام',
+      usage: 'نشاط الرموز والتكلفة والمهارات عبر الزمن'
+    },
+    nav: {
+      newChat: {
+        title: 'جلسة جديدة',
+        detail: 'بدء جلسة جديدة'
+      },
+      settings: {
+        title: 'الإعدادات',
+        detail: 'تكوين Hermes desktop'
+      },
+      skills: {
+        title: 'المهارات والأدوات',
+        detail: 'تفعيل المهارات ومجموعات الأدوات والمزوّدين'
+      },
+      messaging: {
+        title: 'المراسلة',
+        detail: 'إعداد Telegram وSlack وDiscord والمزيد'
+      },
+      artifacts: {
+        title: 'العناصر',
+        detail: 'استعراض المخرجات المولّدة'
+      }
+    },
+    sectionEntries: {
+      sessions: {
+        title: 'لوحة الجلسات',
+        detail: 'البحث في الجلسات وتثبيتها وإدارتها'
+      },
+      system: {
+        title: 'لوحة النظام',
+        detail: 'حالة البوابة والسجلات وإعادة التشغيل/التحديث'
+      },
+      usage: {
+        title: 'لوحة الاستخدام',
+        detail: 'نشاط الرموز والتكلفة والمهارات'
+      }
+    },
+    providerNavigate: 'فتح المزود',
+    providerSessions: 'جلسات المزود',
+    refresh: 'تحديث',
+    refreshing: 'جار التحديث...',
+    noResults: 'لا توجد نتائج',
+    pinSession: 'تثبيت الجلسة',
+    unpinSession: 'إلغاء تثبيت الجلسة',
+    exportSession: 'تصدير الجلسة',
+    deleteSession: 'حذف الجلسة',
+    noSessions: 'لا توجد جلسات',
+    gatewayRunning: 'البوابة تعمل',
+    gatewayStopped: 'البوابة متوقفة',
+    hermesActiveSessions: (version, count) => `Hermes ${version} لديه ${count} جلسة نشطة`,
+    restartGateway: 'إعادة تشغيل البوابة',
+    gatewayRestartFailed: 'فشل إعادة تشغيل البوابة.',
+    updateHermes: 'تحديث Hermes',
+    actionRunning: 'الإجراء قيد التشغيل',
+    actionDone: 'اكتمل الإجراء',
+    actionFailed: 'فشل الإجراء',
+    actionStartedWaiting: 'بدأ الإجراء، جار الانتظار...',
+    loadingStatus: 'جار تحميل الحالة',
+    recentLogs: 'السجلات الأخيرة',
+    noLogs: 'لا توجد سجلات',
+    days: count => `${count} يوم`,
+    statSessions: 'الجلسات',
+    statApiCalls: 'نداءات API',
+    statTokens: 'الرموز',
+    statCost: 'التكلفة',
+    actualCost: cost => `التكلفة الفعلية ${cost}`,
+    loadingUsage: 'جار تحميل الاستخدام',
+    noUsage: period => `لا يوجد استخدام خلال ${period} يوم`,
+    retry: 'إعادة المحاولة',
+    dailyTokens: 'الرموز اليومية',
+    input: 'إدخال',
+    output: 'إخراج',
+    noDailyActivity: 'لا يوجد نشاط يومي',
+    topModels: 'أكثر النماذج استخداما',
+    noModelUsage: 'لا يوجد استخدام نماذج',
+    topSkills: 'أكثر المهارات استخداما',
+    noSkillActivity: 'لا يوجد نشاط مهارات',
+    actions: count => `${count} إجراء`
+  },
+  messaging: {
+    search: 'بحث',
+    loading: 'جار التحميل...',
+    loadFailed: 'فشل التحميل',
+    states: {
+      connected: 'متصل',
+      connecting: 'جار الاتصال',
+      disabled: 'معطّل',
+      fatal: 'خطأ',
+      gateway_stopped: 'تم إيقاف بوابة المراسلة',
+      not_configured: 'يحتاج إعدادا',
+      pending_restart: 'يلزم إعادة التشغيل',
+      retrying: 'جار إعادة المحاولة',
+      startup_failed: 'فشل بدء التشغيل'
+    },
+    unknown: 'غير معروف',
+    hintPendingRestart: 'تحتاج إعادة تشغيل لتطبيق التغييرات.',
+    hintGatewayStopped: 'البوابة متوقفة.',
+    credentialsSet: 'بيانات الاعتماد مضبوطة',
+    needsSetup: 'يحتاج إعدادا',
+    gatewayStopped: 'البوابة متوقفة',
+    getCredentials: 'الحصول على بيانات الاعتماد',
+    openSetupGuide: 'فتح دليل الإعداد',
+    required: 'مطلوب',
+    recommended: 'موصى به',
+    advanced: count => `${count} إعدادات متقدمة`,
+    noTokenNeeded: 'لا يحتاج رمز',
+    enabled: 'مفعل',
+    disabled: 'معطل',
+    unsavedChanges: 'تغييرات غير محفوظة',
+    saving: 'جار الحفظ...',
+    saveChanges: 'حفظ التغييرات',
+    saved: 'تم الحفظ',
+    replaceValue: 'استبدال القيمة',
+    openDocs: 'فتح الوثائق',
+    clearField: key => `مسح ${key}`,
+    enableAria: name => `تفعيل ${name}`,
+    disableAria: name => `تعطيل ${name}`,
+    platformEnabled: name => `تم تفعيل ${name}`,
+    platformDisabled: name => `تم تعطيل ${name}`,
+    restartToApply: 'أعد التشغيل لتطبيق التغييرات.',
+    setupSaved: name => `تم حفظ إعداد ${name}`,
+    restartToReconnect: 'أعد التشغيل لإعادة الاتصال.',
+    keyCleared: key => `تم مسح ${key}`,
+    setupUpdated: name => `تم تحديث إعداد ${name}`,
+    failedUpdate: name => `فشل تحديث ${name}`,
+    failedSave: name => `فشل حفظ ${name}`,
+    failedClear: key => `فشل مسح ${key}`,
+    fieldCopy: {
+      TELEGRAM_BOT_TOKEN: {
+        label: 'رمز البوت (token)',
+        help: 'أنشئ بوتا عبر @BotFather، ثم الصق الرمز الذي يمنحك إياه.',
+        placeholder: 'الصق رمز بوت Telegram'
+      },
+      TELEGRAM_ALLOWED_USERS: {
+        label: 'معرّفات مستخدمي Telegram المسموح بهم',
+        help: 'موصى به. معرّفات رقمية مفصولة بفواصل من @userinfobot. بدون ذلك، يمكن لأي شخص مراسلة بوتك مباشرة.'
+      },
+      TELEGRAM_PROXY: {
+        label: 'رابط الـ Proxy',
+        help: 'مطلوب فقط على الشبكات التي يكون فيها Telegram محجوبا.'
+      },
+      DISCORD_BOT_TOKEN: {
+        label: 'رمز البوت (token)',
+        help: 'أنشئ تطبيقا في Discord Developer Portal، وأضف بوتا، ثم الصق رمزه.'
+      },
+      DISCORD_ALLOWED_USERS: {
+        label: 'معرّفات مستخدمي Discord المسموح بهم',
+        help: 'موصى به. معرّفات مستخدمي Discord مفصولة بفواصل.'
+      },
+      DISCORD_REPLY_TO_MODE: {
+        label: 'نمط الرد',
+        help: 'first أو all أو off.'
+      },
+      DISCORD_ALLOW_ALL_USERS: {
+        label: 'السماح لكل مستخدمي Discord',
+        help: 'للتطوير فقط. عند التفعيل، يمكن لأي شخص مراسلة البوت مباشرة دون قائمة سماح.'
+      },
+      DISCORD_HOME_CHANNEL: {
+        label: 'معرّف القناة الرئيسية',
+        help: 'القناة التي يرسل فيها البوت الرسائل الاستباقية (مخرجات cron، التذكيرات).'
+      },
+      DISCORD_HOME_CHANNEL_NAME: {
+        label: 'اسم القناة الرئيسية',
+        help: 'الاسم المعروض للقناة الرئيسية في السجلات ومخرجات الحالة.'
+      },
+      BLUEBUBBLES_ALLOW_ALL_USERS: {
+        label: 'السماح لكل مستخدمي iMessage',
+        help: 'عند التفعيل، يتم تخطي قائمة سماح BlueBubbles.'
+      },
+      MATTERMOST_ALLOW_ALL_USERS: {
+        label: 'السماح لكل مستخدمي Mattermost'
+      },
+      MATTERMOST_HOME_CHANNEL: {
+        label: 'القناة الرئيسية'
+      },
+      QQ_ALLOW_ALL_USERS: {
+        label: 'السماح لكل مستخدمي QQ'
+      },
+      QQBOT_HOME_CHANNEL: {
+        label: 'قناة QQ الرئيسية',
+        help: 'القناة أو المجموعة الافتراضية لتسليم cron.'
+      },
+      QQBOT_HOME_CHANNEL_NAME: {
+        label: 'اسم قناة QQ الرئيسية'
+      },
+      SLACK_BOT_TOKEN: {
+        label: 'رمز بوت Slack',
+        help: 'استخدم رمز البوت من OAuth & Permissions بعد تثبيت تطبيق Slack الخاص بك.',
+        placeholder: 'الصق رمز بوت Slack'
+      },
+      SLACK_APP_TOKEN: {
+        label: 'رمز تطبيق Slack',
+        help: 'استخدم الرمز على مستوى التطبيق المطلوب لـ Socket Mode.',
+        placeholder: 'الصق رمز تطبيق Slack'
+      },
+      SLACK_ALLOWED_USERS: {
+        label: 'معرّفات مستخدمي Slack المسموح بهم',
+        help: 'موصى به. معرّفات مستخدمي Slack مفصولة بفواصل.'
+      },
+      MATTERMOST_URL: {
+        label: 'رابط الخادم',
+        placeholder: 'https://mattermost.example.com'
+      },
+      MATTERMOST_TOKEN: {
+        label: 'رمز البوت (token)'
+      },
+      MATTERMOST_ALLOWED_USERS: {
+        label: 'معرّفات المستخدمين المسموح بهم',
+        help: 'موصى به. معرّفات مستخدمي Mattermost مفصولة بفواصل.'
+      },
+      MATRIX_HOMESERVER: {
+        label: 'رابط Homeserver',
+        placeholder: 'https://matrix.org'
+      },
+      MATRIX_ACCESS_TOKEN: {
+        label: 'رمز الوصول'
+      },
+      MATRIX_USER_ID: {
+        label: 'معرّف مستخدم البوت',
+        placeholder: '@hermes:example.org'
+      },
+      MATRIX_ALLOWED_USERS: {
+        label: 'معرّفات مستخدمي Matrix المسموح بهم',
+        help: 'موصى به. معرّفات مستخدمين مفصولة بفواصل بصيغة @user:server.'
+      },
+      SIGNAL_HTTP_URL: {
+        label: 'رابط جسر Signal',
+        placeholder: 'http://127.0.0.1:8080',
+        help: 'رابط جسر signal-cli REST قيد التشغيل.'
+      },
+      SIGNAL_ACCOUNT: {
+        label: 'رقم الهاتف',
+        help: 'الرقم المسجّل مع جسر signal-cli الخاص بك.'
+      },
+      SIGNAL_ALLOWED_USERS: {
+        label: 'مستخدمو Signal المسموح بهم',
+        help: 'موصى به. معرّفات Signal مفصولة بفواصل.'
+      },
+      WHATSAPP_ENABLED: {
+        label: 'تفعيل جسر WhatsApp',
+        help: 'يُضبط تلقائيا عبر المفتاح أدناه. اتركه دون تغيير ما لم تكن متأكدا من حاجتك إليه.'
+      },
+      WHATSAPP_MODE: {
+        label: 'وضع الجسر'
+      },
+      WHATSAPP_ALLOWED_USERS: {
+        label: 'مستخدمو WhatsApp المسموح بهم',
+        help: 'موصى به. أرقام هواتف أو معرّفات WhatsApp مفصولة بفواصل.'
+      }
+    },
+    platformIntro: {}
+  },
+  profiles: {
+    close: 'إغلاق',
+    nameHint: 'اسم الملف الشخصي',
+    title: 'الملفات الشخصية',
+    count: count => `${count} ملف شخصي`,
+    loading: 'جار التحميل...',
+    newProfile: 'ملف شخصي جديد',
+    allProfiles: 'كل الملفات الشخصية',
+    showAllProfiles: 'إظهار كل الملفات الشخصية',
+    switchToProfile: name => `التبديل إلى ${name}`,
+    manageProfiles: 'إدارة الملفات الشخصية',
+    actionsFor: name => `إجراءات ${name}`,
+    color: 'اللون',
+    colorFor: name => `لون ${name}`,
+    setColor: color => `ضبط اللون ${color}`,
+    autoColor: 'لون تلقائي',
+    noProfiles: 'لا توجد ملفات شخصية',
+    selectPrompt: 'اختر ملفا شخصيا',
+    refresh: 'تحديث',
+    refreshing: 'جار التحديث...',
+    default: 'الافتراضي',
+    skills: count => `${count} مهارة`,
+    env: 'البيئة',
+    defaultBadge: 'افتراضي',
+    rename: 'إعادة تسمية',
+    copySetup: 'نسخ الإعداد',
+    copying: 'جار النسخ...',
+    modelLabel: 'النموذج',
+    skillsLabel: 'المهارات',
+    notSet: 'غير مضبوط',
+    soulDesc: 'الموجّه (prompt) النظامي وتعليمات الشخصية المضمّنة في هذا الملف الشخصي.',
+    soulOptional: 'اختياري',
+    soulPlaceholder: mode =>
+      `الموجّه (prompt) النظامي / الشخصية لهذا الملف الشخصي.\nاتركه فارغا للإبقاء على افتراضي ${mode}.`,
+    soulPlaceholderCloned: 'مستنسخ',
+    soulPlaceholderEmpty: 'فارغ',
+    unsavedChanges: 'تغييرات غير محفوظة',
+    loadingSoul: 'جار تحميل SOUL.md...',
+    emptySoul: 'SOUL.md فارغ — ابدأ بكتابة الشخصية...',
+    saving: 'جار الحفظ...',
+    saveSoul: 'حفظ التعليمات',
+    deleteTitle: 'حذف الملف الشخصي',
+    deleteDescPrefix: 'سيؤدي هذا إلى حذف ',
+    deleteDescMid: ' وإزالة ',
+    deleteDescSuffix: ' الخاص به. لا يمكن التراجع عن هذا.',
+    deleting: 'جار الحذف...',
+    createDesc: 'أنشئ ملفا شخصيا بإعدادات منفصلة.',
+    nameLabel: 'الاسم',
+    cloneFrom: 'استنساخ من',
+    cloneFromNone: 'لا شيء (فارغ)',
+    cloneFromDesc: 'ينسخ الإعدادات والمهارات وSOUL.md من الملف الشخصي المصدر المحدد.',
+    cloneFromDefault: 'نسخ إعداد الافتراضي',
+    cloneFromDefaultDesc: 'ابدأ من إعدادات الملف الافتراضي.',
+    invalidName: hint => `اسم غير صالح: ${hint}`,
+    nameRequired: 'الاسم مطلوب',
+    creating: 'جار الإنشاء...',
+    createAction: 'إنشاء ملف شخصي',
+    renameTitle: 'إعادة تسمية الملف الشخصي',
+    renameDescPrefix: 'تؤدي إعادة التسمية إلى تحديث دليل الملف الشخصي وأي سكربتات تغليف في ',
+    renameDescSuffix: '.',
+    newNameLabel: 'الاسم الجديد',
+    renaming: 'جار إعادة التسمية...',
+    created: 'تم إنشاء الملف الشخصي',
+    renamed: 'تمت إعادة التسمية',
+    deleted: 'تم الحذف',
+    setupCopied: 'تم نسخ الإعداد',
+    soulSaved: 'تم حفظ التعليمات',
+    failedLoad: 'فشل تحميل الملفات الشخصية',
+    failedDelete: 'فشل الحذف',
+    failedCopy: 'فشل النسخ',
+    failedLoadSoul: 'فشل تحميل التعليمات',
+    failedSaveSoul: 'فشل حفظ التعليمات',
+    failedCreate: 'فشل الإنشاء',
+    failedRename: 'فشل إعادة التسمية'
+  },
+  cron: {
+    close: 'إغلاق',
+    search: 'بحث',
+    loading: 'جار التحميل...',
+    states: {
+      enabled: 'مُفعّل',
+      scheduled: 'مجدول',
+      running: 'قيد التشغيل',
+      paused: 'متوقف مؤقتا',
+      disabled: 'معطّل',
+      error: 'خطأ',
+      completed: 'مكتمل'
+    },
+    deliveryLabels: {
+      local: 'سطح المكتب هذا',
+      telegram: 'Telegram',
+      discord: 'Discord',
+      slack: 'Slack',
+      email: 'البريد الإلكتروني'
+    },
+    scheduleLabels: {
+      daily: 'يوميا',
+      weekdays: 'أيام الأسبوع',
+      weekly: 'أسبوعيا',
+      monthly: 'شهريا',
+      hourly: 'كل ساعة',
+      'every-15-minutes': 'كل 15 دقيقة',
+      custom: 'مخصص'
+    },
+    scheduleHints: {
+      daily: 'كل يوم في الساعة 9:00 صباحا',
+      weekdays: 'من الاثنين إلى الجمعة في الساعة 9:00 صباحا',
+      weekly: 'كل اثنين في الساعة 9:00 صباحا',
+      monthly: 'أول يوم من كل شهر في الساعة 9:00 صباحا',
+      hourly: 'في بداية كل ساعة',
+      'every-15-minutes': 'كل 15 دقيقة',
+      custom: 'صياغة cron أو لغة طبيعية'
+    },
+    days: {
+      '0': 'الأحد',
+      '1': 'الاثنين',
+      '2': 'الثلاثاء',
+      '3': 'الأربعاء',
+      '4': 'الخميس',
+      '5': 'الجمعة',
+      '6': 'السبت',
+      '7': 'الأحد'
+    },
+    dayFallback: value => `اليوم ${value}`,
+    everyDayAt: time => `كل يوم في ${time}`,
+    weekdaysAt: time => `أيام الأسبوع في ${time}`,
+    everyDayOfWeekAt: (day, time) => `كل ${day} في ${time}`,
+    monthlyOnDayAt: (dayOfMonth, time) => `شهريا في اليوم ${dayOfMonth} في ${time}`,
+    topOfHour: 'في بداية كل ساعة',
+    everyHourAt: minute => `كل ساعة عند :${minute}`,
+    newCron: 'مهمة مجدولة جديدة',
+    emptyDescNew: 'أنشئ مهمة مجدولة لتشغيل Hermes تلقائيا.',
+    emptyDescSearch: 'لا توجد مهام تطابق البحث.',
+    emptyTitleNew: 'لا توجد مهام مجدولة',
+    emptyTitleSearch: 'لا توجد نتائج',
+    last: 'آخر تشغيل',
+    next: 'التالي',
+    noRuns: 'لا توجد تشغيلات',
+    manage: 'إدارة',
+    showRuns: 'إظهار التشغيلات',
+    hideRuns: 'إخفاء التشغيلات',
+    runHistory: 'سجل التشغيل',
+    actionsFor: title => `إجراءات ${title}`,
+    actionsTitle: 'الإجراءات',
+    resume: 'استئناف',
+    pause: 'إيقاف مؤقت',
+    resumeTitle: 'استئناف المهمة',
+    pauseTitle: 'إيقاف المهمة مؤقتا',
+    triggerNow: 'تشغيل الآن',
+    edit: 'تحرير',
+    deleteTitle: 'حذف المهمة',
+    deleteDescPrefix: 'سيؤدي هذا إلى إزالة ',
+    deleteDescSuffix: ' نهائيا. سيتوقف عن العمل فورا.',
+    deleting: 'جار الحذف...',
+    resumed: 'تم الاستئناف',
+    paused: 'تم الإيقاف مؤقتا',
+    triggered: 'تم التشغيل',
+    deleted: 'تم الحذف',
+    created: 'تم الإنشاء',
+    updated: 'تم التحديث',
+    failedLoad: 'فشل تحميل المهام',
+    failedUpdate: 'فشل التحديث',
+    failedTrigger: 'فشل التشغيل',
+    failedDelete: 'فشل الحذف',
+    failedSave: 'فشل الحفظ',
+    editTitle: 'تحرير المهمة المجدولة',
+    createTitle: 'إنشاء مهمة مجدولة',
+    editDesc: 'عدل الجدول والرسالة.',
+    createDesc: 'اضبط مهمة يشغلها Hermes تلقائيا.',
+    nameLabel: 'الاسم',
+    namePlaceholder: 'مثال: الملخص الصباحي',
+    promptLabel: 'الرسالة',
+    promptPlaceholder: 'ماذا تريد من Hermes أن يفعل؟',
+    frequencyLabel: 'التكرار',
+    deliverLabel: 'التسليم',
+    customScheduleLabel: 'جدول مخصص',
+    customPlaceholder: 'تعبير cron',
+    customHint: 'استخدم صيغة cron القياسية.',
+    optional: 'اختياري',
+    promptScheduleRequired: 'الرسالة والجدول مطلوبان',
+    saveChanges: 'حفظ التغييرات',
+    createAction: 'إنشاء'
+  },
+  artifacts: {
+    search: 'بحث',
+    refresh: 'تحديث',
+    refreshing: 'جار التحديث...',
+    indexing: 'جار الفهرسة...',
+    tabAll: 'الكل',
+    tabImages: 'الصور',
+    tabFiles: 'الملفات',
+    tabLinks: 'الروابط',
+    noArtifactsTitle: 'لا توجد عناصر',
+    noArtifactsDesc: 'ستظهر الصور والملفات والروابط من محادثاتك هنا.',
+    failedLoad: 'فشل تحميل العناصر',
+    openFailed: 'فشل الفتح',
+    itemsImage: 'صور',
+    itemsLink: 'روابط',
+    itemsFile: 'ملفات',
+    itemsGeneric: 'عناصر',
+    zero: 'صفر',
+    rangeOf: (start, end, total) => `${start}-${end} من ${total}`,
+    goToPage: (itemLabel, page) => `الانتقال إلى صفحة ${page} من ${itemLabel}`,
+    colTitleLink: 'الرابط',
+    colTitleFile: 'الملف',
+    colTitleDefault: 'العنوان',
+    colLocationLink: 'الموقع',
+    colLocationFile: 'الموقع',
+    colLocationDefault: 'الموقع',
+    colSession: 'الجلسة',
+    kindImage: 'صورة',
+    kindFile: 'ملف',
+    kindLink: 'رابط',
+    chat: 'المحادثة',
+    copyUrl: 'نسخ الرابط',
+    copyPath: 'نسخ المسار'
+  },
+  sidebar: {
+    nav: {
+      'new-session': 'جلسة جديدة',
+      skills: 'المهارات',
+      messaging: 'المراسلة',
+      artifacts: 'العناصر',
+      chat: 'المحادثة',
+      settings: 'الإعدادات',
+      cron: 'المهام المجدولة',
+      agents: 'الوكلاء'
+    },
+    searchAria: 'البحث في الجلسات',
+    searchPlaceholder: 'البحث في الجلسات...',
+    clearSearch: 'مسح البحث',
+    noMatch: query => `لا توجد جلسات تطابق "${query}"`,
+    results: 'النتائج',
+    pinned: 'المثبتة',
+    sessions: 'الجلسات',
+    cronJobs: 'المهام المجدولة',
+    groupAriaGrouped: 'الجلسات مجمعة حسب مساحة العمل',
+    groupAriaUngrouped: 'الجلسات غير مجمعة',
+    showProjects: 'عرض المشاريع',
+    showSessions: 'عرض الجلسات',
+    groupTitleGrouped: 'مجمعة حسب مساحة العمل',
+    groupTitleUngrouped: 'كل الجلسات',
+    allPinned: 'كل الجلسات مثبتة',
+    shiftClickHint: 'استخدم Shift للتحديد المتعدد',
+    noWorkspace: 'بدون مساحة عمل',
+    noProject: 'لا يوجد مشروع',
+    projectEmpty: 'لا توجد جلسات بعد',
+    noSessions: 'لا توجد جلسات بعد',
+    projects: {
+      sectionLabel: 'المشاريع',
+      newButton: 'مشروع جديد',
+      createTitle: 'مشروع جديد',
+      createDesc: 'سمِّ مساحة العمل وأضف مجلدا أو أكثر.',
+      renameTitle: 'إعادة تسمية المشروع',
+      addFolderTitle: 'إضافة مجلد',
+      namePlaceholder: 'مثال: Skunkworks',
+      foldersLabel: 'المجلدات',
+      ideaLabel: 'الفكرة',
+      ideaPlaceholder: 'ما موضوع هذا المشروع؟ (يُحفظ في IDEA.md)',
+      ideaGenerate: 'توليد فكرة',
+      ideaGenerating: 'جار التوليد...',
+      ideaShuffle: 'خلط القوالب',
+      noFolders: 'لم تتم إضافة أي مجلدات بعد.',
+      addFolder: 'إضافة مجلد',
+      primaryBadge: 'أساسي',
+      removeFolder: 'إزالة',
+      create: 'إنشاء',
+      menu: 'إجراءات المشروع',
+      menuRename: 'إعادة تسمية',
+      menuAppearance: 'المظهر',
+      noColor: 'بلا لون',
+      menuAddFolder: 'إضافة مجلد',
+      menuSetActive: 'تعيين كنشط',
+      menuDelete: 'حذف',
+      reveal: 'إظهار في المجلد',
+      copyPath: 'نسخ المسار',
+      removeFromSidebar: 'إخفاء من الشريط الجانبي',
+      createFailed: 'تعذّر إنشاء المشروع',
+      deleteConfirm: 'هذا يزيل المشروع المحفوظ من Hermes. تبقى الملفات ومستودعات git وأشجار العمل دون تغيير.',
+      startWork: 'شجرة عمل جديدة',
+      newWorktreeTitle: 'شجرة عمل جديدة',
+      newWorktreeDesc: 'سمِّ الفرع لشجرة العمل هذه.',
+      branchPlaceholder: 'مثال: my-feature',
+      startWorkFailed: 'تعذّر إنشاء شجرة العمل',
+      convertBranch: 'تحويل فرع...',
+      convertBranchTitle: 'تحويل فرع',
+      convertBranchDesc: 'افتح الفروع المسحوبة، أو أنشئ شجرة عمل لفرع حر.',
+      convertBranchPlaceholder: 'البحث في الفروع...',
+      convertBranchInstead: 'تحويل فرع موجود',
+      branchOpenExisting: 'فتح',
+      branchSwitchHome: 'تبديل الموطن',
+      branchCreateWorktree: 'شجرة عمل جديدة',
+      branchesLoading: 'جار تحميل الفروع...',
+      noBranches: 'لم يتم العثور على فروع',
+      removeWorktree: 'إزالة شجرة العمل',
+      removeWorktreeFailed: 'تعذّر إزالة شجرة العمل (تغييرات غير مُودعة؟)',
+      removeWorktreeConfirm:
+        'أزِلها من git (يحذف مجلد شجرة العمل؛ يبقى الفرع)، أو فقط أخفِ المسار من الشريط الجانبي واترك شجرة العمل على القرص.',
+      removeWorktreeDirty:
+        'تحتوي شجرة العمل هذه على تغييرات غير مُودعة. أزِلها بالقوة (يتجاهل تلك التغييرات)، أو فقط أخفِ المسار واحتفظ بها على القرص.',
+      forceRemove: 'إزالة بالقوة',
+      enter: label => `فتح ${label}`,
+      reorder: label => `إعادة ترتيب ${label}`,
+      toggle: label => `تبديل جلسات ${label}`,
+      back: 'كل المشاريع'
+    },
+    newSessionIn: label => `جلسة جديدة في ${label}`,
+    showMoreIn: (count, label) => `إظهار ${count} أخرى في ${label}`,
+    loading: 'جار التحميل...',
+    loadMore: 'تحميل المزيد',
+    loadCount: step => `تحميل ${step} أخرى`,
+    row: {
+      pin: 'تثبيت',
+      unpin: 'إلغاء التثبيت',
+      copyId: 'نسخ المعرف',
+      export: 'تصدير',
+      branchFrom: 'فرع',
+      rename: 'إعادة تسمية',
+      archive: 'أرشفة',
+      newWindow: 'فتح في نافذة جديدة',
+      copyIdFailed: 'فشل نسخ المعرف',
+      actionsFor: title => `إجراءات ${title}`,
+      sessionActions: 'إجراءات الجلسة',
+      sessionRunning: 'الجلسة تعمل',
+      needsInput: 'تحتاج إدخالا',
+      waitingForAnswer: 'بانتظار إجابة',
+      backgroundRunning: 'تعمل في الخلفية',
+      finishedUnread: 'اكتملت وفيها جديد',
+      hideTabBar: 'إخفاء شريط التبويبات',
+      openInNewTab: 'فتح في تبويب جديد',
+      openInSplit: 'فتح في تقسيم',
+      ownedByProfile: profile => `مملوكة للملف الشخصي ${profile}`,
+      untitledChat: id => `محادثة ${id}`,
+      handoffOrigin: platform => `قادمة من ${platform}`,
+      renamed: 'تمت إعادة التسمية',
+      renameFailed: 'فشلت إعادة التسمية',
+      renameTitle: 'إعادة تسمية الجلسة',
+      renameDesc: 'اختر اسما جديدا لهذه الجلسة.',
+      untitledPlaceholder: 'جلسة بلا عنوان',
+      ageNow: 'الآن',
+      ageDay: 'يوم',
+      ageHour: 'ساعة',
+      ageMin: 'دقيقة'
+    }
+  },
+  composer: {
+    message: 'الرسالة',
+    wakingProfile: profile => `جار إيقاظ ${profile}`,
+    placeholderStarting: 'جار بدء Hermes...',
+    placeholderReconnecting: 'جار إعادة الاتصال...',
+    placeholderFollowUp: 'اكتب متابعة...',
+    newSessionPlaceholders: ['اسأل Hermes عن شيء...', 'اطلب من Hermes تنفيذ مهمة...', 'ابدأ محادثة جديدة...'],
+    followUpPlaceholders: ['اكتب متابعة...', 'أضف توجيها...', 'اسأل سؤالا آخر...'],
+    startVoice: 'بدء الصوت',
+    queueMessage: 'إضافة الرسالة للطابور',
+    steer: 'توجيه',
+    stop: 'إيقاف',
+    send: 'إرسال',
+    speaking: 'يتحدث',
+    transcribing: 'جار التفريغ',
+    thinking: 'يفكر',
+    muted: 'مكتوم',
+    listening: 'يستمع',
+    muteMic: 'كتم الميكروفون',
+    unmuteMic: 'إلغاء كتم الميكروفون',
+    stopListening: 'إيقاف الاستماع',
+    stopShort: 'إيقاف',
+    endConversation: 'إنهاء المحادثة',
+    endShort: 'إنهاء',
+    stopDictation: 'إيقاف الإملاء',
+    transcribingDictation: 'جار تفريغ الإملاء',
+    voiceDictation: 'إملاء صوتي',
+    lookupLoading: 'جار البحث...',
+    lookupNoMatches: 'لا توجد نتائج',
+    lookupTry: 'جرب',
+    lookupOr: 'أو',
+    commonCommands: 'الأوامر الشائعة',
+    hotkeys: 'الاختصارات',
+    helpFooter: 'استخدم الأسهم للتنقل و Enter للاختيار.',
+    commandDescs: {
+      '/help': 'قائمة كاملة بالأوامر + اختصارات لوحة المفاتيح',
+      '/clear': 'بدء جلسة جديدة',
+      '/resume': 'استئناف جلسة سابقة',
+      '/details': 'التحكم في مستوى تفاصيل النص',
+      '/copy': 'نسخ التحديد أو آخر رسالة من المساعد',
+      '/quit': 'الخروج من hermes'
+    },
+    hotkeyDescs: {
+      'composer.mention': 'الإشارة إلى الملفات والمجلدات والروابط وgit',
+      'composer.slash': 'لوحة أوامر الشرطة المائلة',
+      'composer.help': 'هذه المساعدة السريعة (احذف للإخفاء)',
+      'composer.sendNewline': 'إرسال · Shift+Enter لسطر جديد',
+      'composer.sendQueued': 'إرسال الدور التالي في قائمة الانتظار',
+      'keybinds.openPanel': 'كل اختصارات لوحة المفاتيح',
+      'composer.cancel': 'إغلاق النافذة المنبثقة · إلغاء التشغيل',
+      'composer.history': 'التنقل في النافذة المنبثقة / السجل'
+    },
+    attachUrlTitle: 'إرفاق رابط',
+    attachUrlDesc: 'أضف رابطا إلى الرسالة.',
+    urlPlaceholder: 'https://example.com',
+    urlHintPre: 'سيقرأ Hermes الرابط ضمن السياق.',
+    attach: 'إرفاق',
+    queued: count => `${count} في الطابور`,
+    attachmentOnly: 'إرفاق فقط',
+    emptyTurn: 'اكتب رسالة أو أرفق ملفا.',
+    attachments: count => `${count} مرفق`,
+    editingInComposer: 'جار التحرير في صندوق الكتابة',
+    editingQueuedInComposer: 'جار تحرير رسالة في الطابور',
+    queueEdit: 'تحرير الرسالة المجدولة',
+    queueSendNext: 'إرسالها تاليا',
+    queueSend: 'إرسالها الآن',
+    queueDelete: 'حذف من الطابور',
+    queueStuckTitle: 'لم تُرسل الرسالة في قائمة الانتظار',
+    queueStuckBody: 'ظل دور في قائمة الانتظار يفشل في الإرسال. ما زال في قائمة الانتظار — حاول إرساله مرة أخرى.',
+    previewUnavailable: 'المعاينة غير متاحة',
+    previewLabel: label => `معاينة ${label}`,
+    couldNotPreview: label => `تعذرت معاينة ${label}`,
+    removeAttachment: label => `إزالة ${label}`,
+    dictating: 'جار الإملاء',
+    preparingAudio: 'جار تجهيز الصوت',
+    speakingResponse: 'جار قراءة الرد',
+    readingAloud: 'جار القراءة بصوت عال',
+    themeSuggestions: 'اقتراحات سمات سطح المكتب',
+    noMatchingThemes: 'لا توجد سمات مطابقة.',
+    themeTryPre: 'جرّب ',
+    themeTryPost: '.',
+    attachLabel: 'إرفاق',
+    files: 'ملفات',
+    folder: 'مجلد',
+    images: 'صور',
+    pasteImage: 'لصق صورة',
+    url: 'رابط',
+    promptSnippets: 'مقتطفات جاهزة',
+    tipPre: 'نصيحة: اكتب ',
+    tipPost: ' للإشارة إلى الملفات ضمن النص.',
+    snippetsTitle: 'مقتطفات الموجّهات',
+    snippetsDesc: 'اختر موجّهًا أوليًا لإدراجه في المحرّر.',
+    dropFiles: 'أفلت الملفات للإرفاق',
+    dropSession: 'أفلت الجلسة للفتح',
+    snippets: {
+      codeReview: {
+        label: 'مراجعة الكود',
+        description: 'دقّق التغيير الحالي بحثًا عن الانحدارات والحالات الطرفية المُسقطة والاختبارات المفقودة.',
+        text: 'يرجى مراجعة هذا بحثًا عن الأخطاء والانحدارات والاختبارات المفقودة.'
+      },
+      implementationPlan: {
+        label: 'خطة التنفيذ',
+        description: 'حدّد نهجًا قبل لمس الكود حتى يبقى الفرق مركّزًا.',
+        text: 'يرجى وضع خطة تنفيذ موجزة قبل تغيير الكود.'
+      },
+      explainThis: {
+        label: 'اشرح هذا',
+        description: 'اشرح كيفية عمل الكود المحدد واربطه بالملفات الرئيسية.',
+        text: 'يرجى شرح كيفية عمل هذا وإرشادي إلى الملفات الرئيسية.'
+      }
+    }
+  },
+  statusStack: {
+    agents: 'الوكلاء',
+    background: count => `${count} في الخلفية`,
+    subagents: count => `${count} ${count === 1 ? 'وكيل فرعي' : 'وكيل فرعي'}`,
+    todos: (done, total) => `المهام ${done}/${total}`,
+    running: 'قيد التشغيل',
+    stop: 'إيقاف',
+    dismiss: 'تجاهل',
+    exit: code => `خروج ${code}`,
+    coding: {
+      title: 'شجرة العمل',
+      noBranch: 'لا يوجد فرع',
+      detached: 'منفصل',
+      clean: 'نظيف',
+      changed: count => `${count} مُغيَّر`,
+      ahead: count => `${count} متقدم`,
+      behind: count => `${count} متأخر`,
+      review: 'مراجعة',
+      close: 'إغلاق',
+      openChanges: 'فتح التغييرات',
+      openFile: 'فتح الملف',
+      stage: 'إدراج',
+      unstage: 'إلغاء الإدراج',
+      stageAll: 'إدراج الكل',
+      viewAsTree: 'عرض كشجرة',
+      viewAsList: 'عرض كقائمة',
+      revert: 'تراجع',
+      revertAll: 'التراجع عن الكل',
+      revertConfirm: 'هل تريد تجاهل التغييرات على هذا الملف واستعادته إلى الحالة المُودعة؟ لا يمكن التراجع عن هذا.',
+      revertAllConfirm: 'هل تريد تجاهل كل التغييرات واستعادة الملفات إلى الحالة المُودعة؟ لا يمكن التراجع عن هذا.',
+      staged: 'مُدرَج',
+      noChanges: 'لا توجد تغييرات',
+      notRepo: 'ليس مستودع git',
+      noDiff: 'لا يوجد فرق لعرضه',
+      scopeUncommitted: 'غير مُودَع',
+      scopeBranch: 'فرع',
+      scopeLastTurn: 'آخر دور',
+      commit: 'إيداع',
+      commitAndPush: 'إيداع ودفع',
+      commitPlaceholder: 'رسالة (⌘↵ للإيداع)',
+      generateCommitMessage: 'توليد رسالة الإيداع',
+      stopGenerating: 'إيقاف التوليد',
+      createPr: 'إنشاء PR',
+      openPr: 'فتح PR',
+      ghMissing: 'ثبّت GitHub CLI (gh) وسجّل الدخول لفتح طلبات السحب',
+      agentShip: 'اطلب من Hermes فتح PR',
+      agentShipPrompt: 'راجع التغييرات الحالية، وأودعها برسالة إيداع تقليدية واضحة، وادفع الفرع، وافتح طلب سحب.',
+      newBranch: 'فرع جديد',
+      branchOffFrom: base => `فرع جديد من ${base}`,
+      switchTo: branch => `التبديل إلى ${branch}`,
+      switchFailed: branch => `تعذّر التبديل إلى ${branch}`,
+      worktrees: 'أشجار العمل'
+    }
+  },
+  updates: {
+    stages: {
+      idle: 'جار التحضير...',
+      prepare: 'جار التحضير...',
+      fetch: 'جار التنزيل...',
+      pull: 'أوشكنا على الانتهاء...',
+      pydeps: 'جار الإنهاء...',
+      update: 'جار تحديث Hermes...',
+      rebuild: 'جار إعادة بناء تطبيق سطح المكتب...',
+      restart: 'جار إعادة تشغيل Hermes...',
+      done: 'اكتمل التحديث',
+      manual: 'التحديث من الطرفية',
+      guiSkew: 'تحديث تطبيق سطح المكتب',
+      error: 'تم إيقاف التحديث مؤقتا'
+    },
+    checking: 'جار البحث عن تحديثات...',
+    checkFailedTitle: 'تعذّر التحقق من التحديثات',
+    tryAgain: 'إعادة المحاولة',
+    notAvailableTitle: 'التحديث غير متاح',
+    unsupportedMessage: 'لا يمكن لهذا الإصدار من Hermes تحديث نفسه من داخل التطبيق.',
+    connectionRetry: 'تحقق من اتصالك وأعد المحاولة.',
+    latestBody: 'أنت تستخدم أحدث إصدار.',
+    latestBodyBackend: 'الواجهة الخلفية تعمل بأحدث إصدار.',
+    allSetTitle: 'كل شيء جاهز',
+    availableTitle: 'يتوفر تحديث جديد',
+    availableBody: 'إصدار جديد من Hermes جاهز للتثبيت.',
+    availableTitleBackend: 'يتوفر تحديث للواجهة الخلفية',
+    availableBodyBackend: 'إصدار أحدث من واجهة Hermes الخلفية المتصلة جاهز للتثبيت.',
+    availableBodyNoChangelog: 'إصدار أحدث جاهز. ملاحظات الإصدار غير متاحة لنوع التثبيت هذا.',
+    updateNow: 'التحديث الآن',
+    maybeLater: 'ربما لاحقا',
+    moreChanges: count => `+ ${count} تغيير${count === 1 ? '' : 'ات'} إضافي مُضمَّن.`,
+    manualTitle: 'التحديث من الطرفية',
+    manualBody: 'لقد ثبّتت Hermes من سطر الأوامر، لذا تُجرى التحديثات من هناك أيضا. الصق هذا في طرفيتك:',
+    manualPickedUp: 'سيلتقط Hermes الإصدار الجديد في المرة التالية التي تشغّله فيها.',
+    guiSkewTitle: 'تحديث تطبيق سطح المكتب',
+    guiSkewBody:
+      'تم تحديث الواجهة الخلفية، لكن حزمة تطبيق سطح المكتب هذه لم تتغير. حدّث أو أعد تثبيت تطبيق Hermes لسطح المكتب (ملف AppImage / ‎.deb / ‎.rpm) لمطابقته.',
+    copy: 'نسخ',
+    copied: 'تم النسخ',
+    done: 'تم',
+    applyingBody:
+      'يتولّى مُحدِّث Hermes المهمة في نافذته الخاصة ويعيد فتح Hermes تلقائيا عند الانتهاء. الرجاء عدم إعادة فتح Hermes بنفسك أثناء التحديث.',
+    applyingBodyBackend:
+      'تطبّق الواجهة الخلفية البعيدة التحديث وستعيد التشغيل. يعيد Hermes الاتصال تلقائيا عند عودتها.',
+    applyingClose: 'ستُغلق هذه النافذة أثناء تشغيل التحديث، ثم يعيد Hermes فتح نفسه تلقائيا.',
+    errorTitle: 'لم يكتمل التحديث',
+    errorBody: 'لا داعي للقلق — لم يُفقد شيء. يمكنك إعادة المحاولة الآن.',
+    notNow: 'ليس الآن',
+    applyStatus: {
+      preparing: 'جار تحديث الواجهة الخلفية...',
+      pulling: 'جار تحديث الواجهة الخلفية...',
+      restarting: 'تعيد الواجهة الخلفية التشغيل لتحميل التحديث...',
+      notAvailable: 'التحديث غير متاح لهذه الواجهة الخلفية.',
+      failed: 'فشل تحديث الواجهة الخلفية.',
+      noReturn: 'لم تعد الواجهة الخلفية إلى الاتصال. قد لا يكون التحديث قد اكتمل — تحقق من مضيف الواجهة الخلفية.'
+    }
+  },
+  install: {
+    stageStates: {
+      pending: 'قيد الانتظار',
+      running: 'جار التثبيت',
+      succeeded: 'تم',
+      skipped: 'تم التخطي',
+      failed: 'فشل'
+    },
+    oneTimeTitle: 'يحتاج Hermes إلى تثبيت لمرة واحدة',
+    unsupportedDesc: platform =>
+      `التثبيت التلقائي عند أول تشغيل غير متاح على ${platform} بعد. افتح الطرفية وشغّل الأمر أدناه، ثم أعد تشغيل هذا التطبيق. ستتخطى عمليات التشغيل اللاحقة هذه الخطوة.`,
+    installCommand: 'أمر التثبيت',
+    copyCommand: 'نسخ الأمر',
+    viewDocs: 'عرض مستندات التثبيت',
+    installTo: 'سيتم التثبيت في',
+    retryAfterRun: 'لقد شغّلته -- إعادة المحاولة',
+    failedTitle: 'فشل التثبيت',
+    settingUpTitle: 'جار إعداد وكيل Hermes',
+    finishingTitle: 'جار الإنهاء',
+    failedDesc:
+      'فشلت إحدى خطوات التثبيت. على Windows، قد يحدث هذا إذا كان هناك نسخة أخرى من Hermes CLI أو تطبيق سطح المكتب قيد التشغيل. أوقف أي نسخ Hermes قيد التشغيل، ثم أعد المحاولة. تحقق من التفاصيل أدناه أو من سجل سطح المكتب للحصول على النص الكامل.',
+    activeDesc:
+      'هذا إعداد لمرة واحدة. يقوم مثبّت Hermes بتنزيل التبعيات وتهيئة جهازك. ستتخطى عمليات التشغيل اللاحقة هذه الخطوة.',
+    progress: (completed, total) => `اكتملت ${completed} من ${total} خطوة`,
+    currentStage: stage => ` -- الآن: ${stage}`,
+    fetchingManifest: 'جار جلب بيان المثبّت...',
+    error: 'خطأ',
+    hideOutput: 'إخفاء مخرجات المثبّت',
+    showOutput: 'إظهار مخرجات المثبّت',
+    lines: count => `${count} سطر`,
+    noOutput: 'لا توجد مخرجات بعد.',
+    cancelling: 'جار الإلغاء...',
+    cancelInstall: 'إلغاء التثبيت',
+    transcriptSaved: 'تم حفظ النص الكامل في',
+    copiedOutput: 'تم النسخ!',
+    copyOutput: 'نسخ المخرجات',
+    reloadRetry: 'إعادة التحميل وإعادة المحاولة'
+  },
+  onboarding: {
+    headerTitle: 'لنُعِدّ لك Hermes Agent',
+    headerDesc: 'اربط مزوّد نماذج لبدء المحادثة. معظم الخيارات تتطلب نقرة واحدة.',
+    preparingInstall: 'يُكمل Hermes التثبيت. عادة ما يستغرق ذلك أقل من دقيقة في أول تشغيل.',
+    starting: 'جار بدء Hermes...',
+    lookingUpProviders: 'جار البحث عن المزوّدين...',
+    collapse: 'طي',
+    otherProviders: 'مزودون آخرون',
+    haveApiKey: 'لديك مفتاح API',
+    chooseLater: 'سأختار مزوّدا لاحقا',
+    recommended: 'موصى به',
+    connected: 'متصل',
+    featuredPitch: 'اشتراك واحد، أكثر من 300 نموذج متقدم — الطريقة الموصى بها لتشغيل Hermes',
+    fireworksPitch: 'نماذج مفتوحة سريعة مع استضافة Fireworks.',
+    openRouterPitch: 'مفتاح واحد لمئات النماذج — خيار افتراضي جيد',
+    apiKeyOptions: {
+      openrouter: {
+        short: 'مفتاح واحد، نماذج كثيرة',
+        description: 'يستضيف مئات النماذج خلف مفتاح واحد. خيار افتراضي جيد للتثبيتات الجديدة.'
+      },
+      openai: {
+        short: 'نماذج من فئة GPT',
+        description: 'وصول مباشر إلى نماذج OpenAI.'
+      },
+      gemini: {
+        short: 'نماذج Gemini',
+        description: 'وصول مباشر إلى نماذج Google Gemini.'
+      },
+      xai: {
+        short: 'نماذج Grok',
+        description: 'وصول مباشر إلى نماذج xAI Grok.'
+      },
+      local: {
+        short: 'مستضاف ذاتيا',
+        description:
+          'وجّه Hermes إلى نقطة نهاية محلية أو مستضافة ذاتيا متوافقة مع OpenAI (vLLM، llama.cpp، Ollama، إلخ).'
+      }
+    },
+    backToSignIn: 'العودة إلى تسجيل الدخول',
+    getKey: 'الحصول على مفتاح',
+    replaceCurrent: 'استبدال القيمة الحالية',
+    pasteApiKey: 'ألصق مفتاح API',
+    localApiKeyPlaceholder: 'مفتاح API (اختياري — فقط إذا كانت نقطة النهاية تتطلبه)',
+    couldNotSave: 'تعذر حفظ بيانات الاعتماد.',
+    connecting: 'جار الاتصال',
+    update: 'تحديث',
+    flowSubtitles: {
+      pkce: 'يفتح المتصفح لتسجيل الدخول ثم يتابع هنا',
+      device_code: 'يفتح صفحة تحقق في المتصفح — يتصل Hermes تلقائياً',
+      loopback: 'يفتح المتصفح لتسجيل الدخول — يتصل Hermes تلقائياً',
+      external: 'سجل الدخول مرة واحدة في الطرفية ثم عد إلى المحادثة'
+    },
+    startingSignIn: provider => `جار بدء تسجيل الدخول لـ ${provider}...`,
+    verifyingCode: provider => `جار التحقق من الرمز عبر ${provider}...`,
+    connectedProvider: provider => `تم ربط ${provider}`,
+    connectedPicking: provider => `تم ربط ${provider}. جار اختيار نموذج افتراضي...`,
+    signInFailed: 'فشل تسجيل الدخول. حاول مرة أخرى.',
+    pickDifferentProvider: 'اختر مزوداً آخر',
+    signInWith: provider => `تسجيل الدخول عبر ${provider}`,
+    openedBrowser: provider => `فتحنا ${provider} في المتصفح.`,
+    authorizeThere: 'صرّح لـ Hermes هناك.',
+    copyAuthCode: 'انسخ رمز التفويض وألصقه أدناه.',
+    pasteAuthCode: 'ألصق رمز التفويض',
+    reopenAuthPage: 'إعادة فتح صفحة التفويض',
+    autoBrowser: provider => `فتحنا ${provider} في المتصفح. صرّح لـ Hermes هناك وسيتم الاتصال تلقائياً دون نسخ أو لصق.`,
+    reopenSignInPage: 'إعادة فتح صفحة تسجيل الدخول',
+    waitingAuthorize: 'بانتظار التفويض...',
+    externalPending: provider =>
+      `${provider} يسجل الدخول عبر أداة سطر الأوامر الخاصة به. شغّل هذا الأمر في الطرفية، ثم عد واختر "سجلت الدخول":`,
+    signedIn: 'سجلت الدخول',
+    deviceCodeOpened: provider => `فتحنا ${provider} في المتصفح. أدخل هذا الرمز هناك:`,
+    reopenVerification: 'إعادة فتح صفحة التحقق',
+    copy: 'نسخ',
+    defaultModel: 'النموذج الافتراضي',
+    freeTier: 'الطبقة المجانية',
+    pro: 'مدفوع',
+    free: 'مجاني',
+    price: (input, output) => `${input} إدخال / ${output} إخراج لكل مليون رمز`,
+    change: 'تغيير',
+    startChatting: 'ابدأ',
+    docs: provider => `وثائق ${provider}`
+  },
+  modelPicker: {
+    title: 'اختيار النموذج',
+    current: 'الحالي',
+    unknown: 'غير معروف',
+    search: 'البحث عن نموذج...',
+    noModels: 'لا توجد نماذج',
+    addProvider: 'إضافة مزود',
+    loadFailed: 'فشل تحميل النماذج',
+    noAuthenticatedProviders: 'لا توجد مزودات مصادق عليها',
+    pro: 'Pro',
+    proNeedsSubscription: 'يتطلب اشتراكا',
+    free: 'مجاني',
+    freeTier: 'طبقة مجانية',
+    priceTitle: 'السعر'
+  },
+  modelVisibility: {
+    title: 'النماذج',
+    search: 'بحث في النماذج',
+    noAuthenticatedProviders: 'لا يوجد مزوّدون مصادق عليهم.',
+    addProvider: 'إضافة مزوّد…'
+  },
+  shell: {
+    windowControls: 'تحكم النافذة',
+    paneControls: 'تحكم اللوحات',
+    appControls: 'تحكم التطبيق',
+    modelMenu: {
+      search: 'البحث عن نموذج...',
+      noModels: 'لا توجد نماذج',
+      editModels: 'تحرير النماذج',
+      refreshModels: 'تحديث النماذج',
+      fast: 'سريع'
+    },
+    modelOptions: {
+      noOptions: 'لا توجد خيارات لهذا النموذج',
+      options: 'الخيارات',
+      thinking: 'التفكير',
+      fast: 'سريع',
+      effort: 'الجهد',
+      minimal: 'أدنى',
+      low: 'منخفض',
+      medium: 'متوسط',
+      high: 'عالٍ',
+      max: 'أقصى',
+      updateFailed: 'فشل تحديث خيار النموذج',
+      fastFailed: 'فشل تحديث الوضع السريع'
+    },
+    gatewayMenu: {
+      gateway: 'البوابة',
+      connected: 'متصل',
+      connecting: 'جار الاتصال',
+      offline: 'غير متصل',
+      inferenceReady: 'الاستدلال جاهز',
+      inferenceNotReady: 'الاستدلال غير جاهز',
+      checkingInference: 'جار فحص الاستدلال',
+      disconnected: 'منقطع',
+      openSystem: 'فتح النظام',
+      connection: label => `الاتصال: ${label}`,
+      recentActivity: 'النشاط الأخير',
+      viewAllLogs: 'عرض كل السجلات',
+      messagingPlatforms: 'منصات المراسلة'
+    },
+    statusbar: {
+      unknown: 'غير معروف',
+      restart: 'إعادة تشغيل',
+      update: 'تحديث',
+      updateInProgress: 'التحديث جار',
+      commitsBehind: (count, branch) => `${count} commits خلف ${branch}`,
+      desktopVersion: version => `سطح المكتب ${version}`,
+      backendVersion: version => `الخلفية ${version}`,
+      clientLabel: version => `العميل ${version}`,
+      backendLabel: version => `الخلفية ${version}`,
+      commit: sha => `commit ${sha}`,
+      branch: branch => `الفرع ${branch}`,
+      closeCommandCenter: 'إغلاق مركز الأوامر',
+      openCommandCenter: 'فتح مركز الأوامر',
+      showTerminal: 'إظهار الطرفية',
+      hideTerminal: 'إخفاء الطرفية',
+      gateway: 'البوابة',
+      gatewayReady: 'البوابة جاهزة',
+      gatewayNeedsSetup: 'البوابة تحتاج إعدادا',
+      gatewayChecking: 'جار فحص البوابة',
+      gatewayConnecting: 'جار اتصال البوابة',
+      gatewayOffline: 'البوابة غير متصلة',
+      gatewayRestarting: 'جار إعادة التشغيل...',
+      gatewayTitle: 'حالة البوابة',
+      agents: 'الوكلاء',
+      closeAgents: 'إغلاق الوكلاء',
+      openAgents: 'فتح الوكلاء',
+      subagents: count => `${count} وكيل فرعي`,
+      failed: count => `${count} فشل`,
+      running: count => `${count} يعمل`,
+      cron: 'المهام',
+      openCron: 'فتح المهام المجدولة',
+      turnRunning: 'الدور يعمل',
+      currentTurnElapsed: 'وقت الدور الحالي',
+      contextUsage: 'استخدام السياق',
+      session: 'الجلسة',
+      runtimeSessionElapsed: 'وقت الجلسة',
+      yoloOn: 'YOLO مفعل',
+      yoloOff: 'YOLO معطل',
+      modelNone: 'لا نموذج',
+      noModel: 'لا يوجد نموذج',
+      switchModel: 'تبديل النموذج',
+      openModelPicker: 'فتح اختيار النموذج',
+      modelPinned: 'النموذج مثبت',
+      modelTitle: (provider, model) => `${provider}: ${model}`,
+      providerModelTitle: (provider, model) => `${provider}: ${model}`
+    }
+  },
+  rightSidebar: {
+    aria: 'الشريط الجانبي الأيمن',
+    panelsAria: 'لوحات الشريط الأيمن',
+    files: 'الملفات',
+    terminal: 'الطرفية',
+    noFolderSelected: 'لم يتم اختيار مجلد',
+    changeCwdTitle: 'تغيير مجلد العمل',
+    remotePickerTitle: 'اختر مجلدا بعيدا',
+    remotePickerDescription: 'استعرض المجلدات على الخادم الخلفي المتصل.',
+    remotePickerSelect: 'تحديد المجلد',
+    folderTip: cwd => `المجلد الحالي: ${cwd}`,
+    openFolder: 'فتح مجلد',
+    refreshTree: 'تحديث الشجرة',
+    collapseAll: 'طي الكل',
+    previewUnavailable: 'المعاينة غير متاحة',
+    couldNotPreview: path => `تعذرت معاينة ${path}`,
+    noProjectTitle: 'لا يوجد مشروع',
+    noProjectBody: 'اختر مجلد عمل لعرض الملفات.',
+    noProjectOpen: 'لا يوجد مشروع مفتوح',
+    noDiffs: 'لا توجد فروقات',
+    unreadableTitle: 'تعذر قراءة المجلد',
+    unreadableBody: error => `السبب: ${error}`,
+    emptyTitle: 'المجلد فارغ',
+    emptyBody: 'لا توجد ملفات للعرض.',
+    treeErrorTitle: 'فشل تحميل شجرة الملفات',
+    treeErrorBody: 'حاول التحديث أو اختر مجلدا آخر.',
+    tryAgain: 'حاول مرة أخرى',
+    loadingTree: 'جار تحميل الشجرة...',
+    loadingFiles: 'جار تحميل الملفات...',
+    terminalHide: 'إخفاء الطرفية',
+    addToChat: 'إضافة للمحادثة'
+  },
+  preview: {
+    tab: 'معاينة',
+    closeTab: label => `إغلاق ${label}`,
+    closeOthers: 'إغلاق الأخرى',
+    closeToRight: 'إغلاق ما على اليمين',
+    closeAll: 'إغلاق الكل',
+    closePane: 'إغلاق جزء المعاينة',
+    loading: 'جار تحميل المعاينة',
+    unavailable: 'المعاينة غير متاحة',
+    opening: 'جار الفتح...',
+    hide: 'إخفاء',
+    openPreview: 'فتح المعاينة',
+    openInBrowser: 'فتح في المتصفح',
+    linkHint: '⌘/Ctrl-نقر لجزء المعاينة',
+    sourceLineTitle: 'انقر للتحديد · shift-نقر للتوسيع · اسحب إلى المُنشئ',
+    source: 'المصدر',
+    renderedPreview: 'المعاينة',
+    diff: 'الفرق',
+    unknownSize: 'حجم غير معروف',
+    binaryTitle: 'يبدو هذا ملفا ثنائيا',
+    binaryBody: label => `قد تعرض معاينة ${label} نصا غير قابل للقراءة.`,
+    largeTitle: 'هذا الملف كبير',
+    largeBody: (label, size) => `حجم ${label} هو ${size}. سيعرض Hermes أول 512 KB فقط.`,
+    previewAnyway: 'معاينة على أي حال',
+    truncated: 'عرض أول 512 KB.',
+    noInlineTitle: 'لا توجد معاينة مضمّنة',
+    noInlineBody: mimeType => `${mimeType || 'هذا النوع من الملفات'} لا يزال بالإمكان إرفاقه كسياق.`,
+    edit: 'تحرير',
+    editing: 'جار التحرير',
+    unsavedChanges: 'تغييرات غير محفوظة',
+    saveFailed: message => `تعذّر الحفظ: ${message}`,
+    diskChangedTitle: 'تغيّر الملف على القرص',
+    diskChangedBody: 'تغيّر هذا الملف منذ أن فتحته. هل تريد الكتابة فوقه بنسختك، أم تجاهل تعديلاتك وإعادة التحميل؟',
+    overwrite: 'الكتابة فوقه',
+    discardReload: 'تجاهل وإعادة التحميل',
+    console: {
+      deselect: 'إلغاء تحديد الإدخال',
+      select: 'تحديد الإدخال',
+      copyFailed: 'تعذّر نسخ مخرجات الكونسول',
+      copyEntry: 'نسخ هذا الإدخال',
+      sendEntry: 'إرسال هذا الإدخال إلى المحادثة',
+      messages: count => `${count} رسائل كونسول`,
+      resize: 'تغيير حجم كونسول المعاينة',
+      title: 'كونسول المعاينة',
+      selected: count => `${count} محدد`,
+      sendToChat: 'إرسال إلى المحادثة',
+      copySelected: 'نسخ المحدد إلى الحافظة',
+      copyAll: 'نسخ الكل إلى الحافظة',
+      copy: 'نسخ',
+      clear: 'مسح',
+      empty: 'لا توجد رسائل كونسول بعد.',
+      promptHeader: 'كونسول المعاينة:',
+      sentTitle: 'تم الإرسال إلى المحادثة',
+      sentMessage: count => `أُضيف ${count} ${count === 1 ? 'إدخال سجل' : 'إدخالات سجل'} إلى المُنشئ`
+    },
+    web: {
+      appFailedToBoot: 'فشل إقلاع تطبيق المعاينة',
+      serverNotFound: 'الخادم غير موجود',
+      failedToLoad: 'فشل تحميل المعاينة',
+      tryAgain: 'إعادة المحاولة',
+      restarting: 'جار إعادة تشغيل Hermes...',
+      askRestart: 'اطلب من Hermes إعادة تشغيل الخادم',
+      lookingRestart: taskId => `يبحث Hermes عن خادم معاينة لإعادة تشغيله (${taskId})`,
+      restartingTitle: 'جار إعادة تشغيل خادم المعاينة',
+      restartingMessage: 'يعمل Hermes في الخلفية. راقب كونسول المعاينة لمتابعة التقدم.',
+      startRestartFailed: message => `تعذّر بدء إعادة تشغيل الخادم: ${message}`,
+      restartFailed: 'فشلت إعادة تشغيل الخادم',
+      hideConsole: 'إخفاء كونسول المعاينة',
+      showConsole: 'إظهار كونسول المعاينة',
+      hideDevTools: 'إخفاء DevTools المعاينة',
+      openDevTools: 'فتح DevTools المعاينة',
+      finishedRestarting: message => `أنهى Hermes إعادة تشغيل خادم المعاينة${message ? `: ${message}` : ''}`,
+      failedRestarting: message => `فشلت إعادة تشغيل الخادم: ${message}`,
+      unknownError: 'خطأ غير معروف',
+      restartedTitle: 'تمت إعادة تشغيل خادم المعاينة',
+      reloadingNow: 'جار إعادة تحميل المعاينة الآن.',
+      restartFailedTitle: 'فشلت إعادة تشغيل المعاينة',
+      restartFailedMessage: 'تعذّر على Hermes إعادة تشغيل الخادم.',
+      stillWorking:
+        'لا يزال Hermes يعمل، لكن لم تصل نتيجة إعادة التشغيل بعد. قد يكون أمر الخادم قيد التشغيل في المقدمة.',
+      workspaceReloading: 'تغيّرت مساحة العمل، جار إعادة تحميل المعاينة',
+      fileChanged: url => `تغيّر الملف، جار إعادة تحميل المعاينة: ${url}`,
+      filesChanged: (count, url) => `${count} تغييرات ملفات، جار إعادة تحميل المعاينة: ${url}`,
+      watchFailed: message => `تعذّر مراقبة ملف المعاينة: ${message}`,
+      moduleMimeDescription:
+        'يتم تقديم نصوص الوحدات بنوع MIME خاطئ. عادة ما يعني هذا أن خادم ملفات ثابتة يقدّم تطبيق Vite/React بدلا من خادم تطوير المشروع.',
+      loadFailedConsole: (code, message) => `فشل التحميل${code ? ` (${code})` : ''}: ${message}`,
+      unreachableDescription: 'تعذّر الوصول إلى صفحة المعاينة.',
+      openTarget: url => `فتح ${url}`,
+      fallbackTitle: 'معاينة'
+    }
+  },
+  zones: {
+    showHeader: 'إظهار الرأس',
+    hideHeader: 'إخفاء الرأس',
+    minimize: 'تصغير',
+    restore: 'استعادة',
+    closeRunningTitle: 'إغلاق تبويب يعمل؟',
+    closeRunningBody:
+      'هذه المحادثة ما زالت تعمل (أو تنتظر إدخالك). إغلاق التبويب يخفيها فقط — ستحتفظ الجلسة بتقدمها ويمكن إعادة فتحها من الشريط الجانبي.',
+    closeRunningConfirm: 'إغلاق التبويب',
+    closeOthers: 'إغلاق الأخرى',
+    closeToRight: 'إغلاق ما على اليمين',
+    closeAll: 'إغلاق الكل',
+    split: dir => `تقسيم ${dir}`,
+    move: dir => `نقل ${dir}`,
+    dirUp: 'للأعلى',
+    dirDown: 'للأسفل',
+    dirLeft: 'لليسار',
+    dirRight: 'لليمين',
+    pluginDisabled: pluginId => `الإضافة "${pluginId}" معطلة`,
+    pluginDisabledBody: 'أعد تفعيلها من الإعدادات ← الإضافات لإرجاع اللوحة.',
+    missingPane: paneId => `لوحة مفقودة: ${paneId}`,
+    editTitle: 'التخطيطات',
+    editHint: 'اختر تخطيطا، أو اسحب اللوحات بين المناطق. انقر بزر الفأرة الأيمن على منطقة لتقسيمها.',
+    reset: 'إعادة ضبط',
+    templates: 'القوالب',
+    custom: 'مخصص',
+    newGridLayout: 'تخطيط شبكة جديد',
+    saveCurrentAs: 'حفظ الترتيب الحالي كقالب',
+    nameLayoutPlaceholder: 'سم هذا التخطيط...',
+    deletePreset: name => `حذف ${name}`,
+    zoneEditorTitle: 'محرر المناطق',
+    editorHintPre: 'انقر للتقسيم · ',
+    editorHintPost: ' يعكس الخط · اسحب عبر المناطق للدمج · اسحب الحواف المشتركة لتغيير الحجم',
+    templateColumns: 'أعمدة',
+    templateRows: 'صفوف',
+    templateGrid: 'شبكة',
+    templatePriority: 'أولوية',
+    zoneTag: index => `منطقة ${index}`,
+    mergeZones: count => `دمج ${count} مناطق`,
+    customZoneName: count => `مخصص من ${count} مناطق`,
+    layoutNamePlaceholder: fallback => `اسم التخطيط (${fallback})`,
+    saveApply: 'حفظ وتطبيق',
+    notExpressible: 'هذا الترتيب متشابك — لا يمكن تمثيله كتقسيمات متداخلة بعد',
+    zoneCount: count => `${count} مناطق`
+  },
+  assistant: {
+    thread: {
+      loadingSession: 'جار تحميل الجلسة...',
+      showEarlier: 'عرض الرسائل الأقدم',
+      loadingResponse: 'جار تحميل الرد...',
+      resumeWhenBackgroundDone: count =>
+        count === 1 ? 'سيُستأنف عند انتهاء المهمة الخلفية' : `سيُستأنف عند انتهاء ${count} مهام خلفية`,
+      thinking: 'يفكر...',
+      today: time => `اليوم ${time}`,
+      yesterday: time => `أمس ${time}`,
+      copy: 'نسخ',
+      refresh: 'تحديث',
+      moreActions: 'إجراءات إضافية',
+      branchNewChat: 'تفريع إلى محادثة جديدة',
+      dismissError: 'تجاهل الخطأ',
+      readAloudFailed: 'فشلت القراءة بصوت عال',
+      preparingAudio: 'جار تجهيز الصوت',
+      stopReading: 'إيقاف القراءة',
+      readAloud: 'قراءة بصوت عال',
+      editMessage: 'تحرير الرسالة',
+      scrollToBottom: 'التمرير إلى الأسفل',
+      stop: 'إيقاف',
+      restorePrevious: 'استعادة السابق',
+      restoreCheckpoint: 'استعادة النقطة',
+      restoreFromHere: 'استعادة نقطة التحقق — إعادة التشغيل من هذا الموجّه',
+      restoreTitle: 'الاستعادة إلى نقطة التحقق هذه؟',
+      restoreBody: 'يُزال كل ما يلي هذا الموجّه من المحادثة، ويُعاد تشغيل الموجّه من هنا.',
+      restoreConfirm: 'استعادة وإعادة تشغيل',
+      restoreNext: 'استعادة التالي',
+      goForward: 'تقدم',
+      sendEdited: 'إرسال التعديل',
+      attachingFile: 'جار إرفاق الملف'
+    },
+    approval: {
+      gatewayDisconnected: 'البوابة غير متصلة',
+      sendFailed: 'فشل الإرسال',
+      run: 'تشغيل',
+      command: 'الأمر',
+      moreOptions: 'خيارات إضافية',
+      allowSession: 'السماح لهذه الجلسة',
+      alwaysAllowMenu: 'السماح دائما',
+      jumpToApproval: 'الموافقة مطلوبة',
+      reject: 'رفض',
+      alwaysTitle: 'السماح دائما',
+      alwaysDescription: pattern => `السماح دائما بالأوامر المطابقة لـ ${pattern}`,
+      alwaysAllow: 'السماح دائما'
+    },
+    clarify: {
+      notReady: 'غير جاهز',
+      gatewayDisconnected: 'البوابة غير متصلة',
+      sendFailed: 'فشل الإرسال',
+      loadingQuestion: 'جار تحميل السؤال...',
+      other: 'غير ذلك',
+      placeholder: 'اكتب إجابتك...',
+      skip: 'تخطي',
+      continueLabel: 'متابعة'
+    },
+    tool: {
+      code: 'الكود',
+      copyCode: 'نسخ الكود',
+      renderingImage: 'جار عرض الصورة...',
+      copyOutput: 'نسخ الإخراج',
+      copyCommand: 'نسخ الأمر',
+      copyContent: 'نسخ المحتوى',
+      copyUrl: 'نسخ الرابط',
+      copyResults: 'نسخ النتائج',
+      copyQuery: 'نسخ الاستعلام',
+      copyFile: 'نسخ الملف',
+      copyPath: 'نسخ المسار',
+      outputAlt: 'إخراج الأداة',
+      rawResponse: 'الرد الخام',
+      copyActivity: 'نسخ النشاط',
+      recoveredOne: 'تم الاسترداد',
+      recoveredMany: count => `تم استرداد ${count}`,
+      failedOne: 'فشل',
+      failedMany: count => `فشل ${count}`,
+      statusRunning: 'يعمل',
+      statusError: 'خطأ',
+      statusRecovered: 'تم الاسترداد',
+      statusDone: 'تم',
+      actions: {
+        read: 'قراءة',
+        reading: 'جار القراءة',
+        opened: 'تم الفتح',
+        opening: 'جار الفتح',
+        searched: 'تم البحث',
+        searching: 'جار البحث',
+        ran: 'تم التشغيل',
+        running: 'جار التشغيل',
+        ranCode: 'تم تشغيل الكود',
+        runningCode: 'جار البرمجة'
+      },
+      prefixes: {
+        browser: 'المتصفح',
+        web: 'الويب'
+      },
+      titleTemplates: {
+        actionCommand: (action, command) => `${action} ${command}`,
+        actionQuoted: (action, value) => `${action} “${value}”`,
+        actionTarget: (action, target) => `${action} ${target}`,
+        prefixedDone: (prefix, action) => `${prefix} ${action}`,
+        runningPrefixedTool: (prefix, action) => `جار تشغيل ${prefix.toLowerCase()} ${action.toLowerCase()}`,
+        runningTool: action => `جار تشغيل ${action.toLowerCase()}`
+      },
+      titles: {
+        browser_click: {
+          done: 'تم النقر على عنصر الصفحة',
+          pending: 'جار النقر على عنصر الصفحة',
+          pendingAction: 'جار النقر'
+        },
+        browser_fill: {
+          done: 'تم ملء حقل النموذج',
+          pending: 'جار ملء حقل النموذج',
+          pendingAction: 'جار الملء'
+        },
+        browser_navigate: {
+          done: 'تم فتح الصفحة',
+          pending: 'جار فتح الصفحة',
+          pendingAction: 'جار الفتح'
+        },
+        browser_snapshot: {
+          done: 'تم التقاط لقطة الصفحة',
+          pending: 'جار التقاط لقطة الصفحة',
+          pendingAction: 'جار الالتقاط'
+        },
+        browser_take_screenshot: {
+          done: 'تم التقاط لقطة الشاشة',
+          pending: 'جار التقاط لقطة الشاشة',
+          pendingAction: 'جار الالتقاط'
+        },
+        browser_type: {
+          done: 'تمت الكتابة على الصفحة',
+          pending: 'جار الكتابة على الصفحة',
+          pendingAction: 'جار الكتابة'
+        },
+        clarify: {
+          done: 'تم طرح سؤال',
+          pending: 'جار طرح سؤال',
+          pendingAction: 'جار السؤال'
+        },
+        cronjob: {
+          done: 'مهمة مجدولة',
+          pending: 'جار جدولة المهمة',
+          pendingAction: 'جار الجدولة'
+        },
+        edit_file: {
+          done: 'تم تحرير الملف',
+          pending: 'جار تحرير الملف',
+          pendingAction: 'جار التحرير'
+        },
+        execute_code: {
+          done: 'تم تشغيل الكود',
+          pending: 'جار البرمجة',
+          pendingAction: 'جار البرمجة'
+        },
+        image_generate: {
+          done: 'تم إنشاء الصورة',
+          pending: 'جار إنشاء الصورة',
+          pendingAction: 'جار الإنشاء'
+        },
+        list_files: {
+          done: 'تم سرد الملفات',
+          pending: 'جار سرد الملفات',
+          pendingAction: 'جار السرد'
+        },
+        memory: {
+          done: 'تم الحفظ في الذاكرة',
+          pending: 'جار الحفظ في الذاكرة',
+          pendingAction: 'جار الحفظ'
+        },
+        patch: {
+          done: 'تم تصحيح الملف',
+          pending: 'جار تصحيح الملف',
+          pendingAction: 'جار التصحيح'
+        },
+        read_file: {
+          done: 'تمت قراءة الملف',
+          pending: 'جار قراءة الملف',
+          pendingAction: 'جار القراءة'
+        },
+        search_files: {
+          done: 'تم البحث في الملفات',
+          pending: 'جار البحث في الملفات',
+          pendingAction: 'جار البحث'
+        },
+        session_search_recall: {
+          done: 'تم البحث في سجل الجلسة',
+          pending: 'جار البحث في سجل الجلسة',
+          pendingAction: 'جار البحث'
+        },
+        terminal: {
+          done: 'تم تشغيل الأمر',
+          pending: 'جار تشغيل الأمر',
+          pendingAction: 'جار التشغيل'
+        },
+        todo: {
+          done: 'تم تحديث المهام',
+          pending: 'جار تحديث المهام',
+          pendingAction: 'جار التحديث'
+        },
+        vision_analyze: {
+          done: 'تم تحليل الصورة',
+          pending: 'جار تحليل الصورة',
+          pendingAction: 'جار التحليل'
+        },
+        web_extract: {
+          done: 'تمت قراءة صفحة الويب',
+          pending: 'جار قراءة صفحة الويب',
+          pendingAction: 'جار القراءة'
+        },
+        web_search: {
+          done: 'تم البحث في الويب',
+          pending: 'جار البحث في الويب',
+          pendingAction: 'جار البحث'
+        },
+        write_file: {
+          done: 'تم تحرير الملف',
+          pending: 'جار تحرير الملف',
+          pendingAction: 'جار التحرير'
+        }
+      }
+    }
+  },
+  prompts: {
+    gatewayDisconnected: 'البوابة غير متصلة',
+    sudoSendFailed: 'فشل إرسال كلمة مرور sudo',
+    secretSendFailed: 'فشل إرسال السر',
+    sudoTitle: 'مطلوب sudo',
+    sudoDesc: 'أدخل كلمة المرور لمتابعة الأمر.',
+    sudoPlaceholder: 'كلمة المرور',
+    secretTitle: 'مطلوب سر',
+    secretDesc: 'أدخل القيمة المطلوبة لمتابعة المهمة.',
+    secretPlaceholder: 'القيمة السرية'
+  },
+  desktop: {
+    audioReadFailed: 'فشلت قراءة الصوت',
+    sessionUnavailable: 'الجلسة غير متاحة',
+    createSessionFailed: 'فشل إنشاء الجلسة',
+    promptFailed: 'فشل إرسال الرسالة',
+    providerCredentialRequired: 'مطلوب اعتماد المزود',
+    emptySlashCommand: 'أمر slash فارغ',
+    desktopCommands: 'أوامر سطح المكتب',
+    skillCommandsAvailable: count => `${count} أمر مهارة متاح`,
+    warningLine: message => `تحذير: ${message}`,
+    yoloArmed: 'YOLO مفعل',
+    yoloOff: 'YOLO معطل',
+    yoloSystem: active => (active ? 'YOLO مفعل للنظام' : 'YOLO معطل للنظام'),
+    yoloTitle: 'وضع YOLO',
+    yoloToggleFailed: 'فشل تبديل YOLO',
+    profileStatus: current => `الملف الحالي: ${current}`,
+    unknownProfile: 'ملف شخصي غير معروف',
+    noProfileNamed: (target, available) => `لا يوجد ملف باسم ${target}. المتاح: ${available}`,
+    newChatsProfile: name => `المحادثات الجديدة تستخدم ${name}`,
+    setProfileFailed: 'فشل ضبط الملف الشخصي',
+    sttDisabled: 'تحويل الكلام إلى نص معطل',
+    stopFailed: 'فشل الإيقاف',
+    regenerateFailed: 'فشلت إعادة التوليد',
+    editFailed: 'فشل التحرير',
+    resumeFailed: 'فشل الاستئناف',
+    resumeStrandedTitle: 'تعذّر تحميل هذه الجلسة',
+    resumeStrandedBody:
+      'فشل الاتصال بهذه الجلسة وتوقفت إعادة المحاولة التلقائية. تأكد من تشغيل البوابة، ثم حاول مجددا.',
+    resumeRetry: 'إعادة المحاولة',
+    nothingToBranch: 'لا يوجد ما يمكن تفريعه',
+    branchNeedsChat: 'يحتاج التفريع إلى محادثة',
+    sessionBusy: 'الجلسة مشغولة',
+    branchStopCurrent: 'أوقف الدور الحالي قبل التفريع',
+    branchNoText: 'لا يوجد نص للتفريع',
+    branchTitle: n => `مسودة: تفريع #${n}`,
+    branchFailed: 'فشل التفريع',
+    deleteFailed: 'فشل الحذف',
+    archived: 'تمت الأرشفة',
+    archiveFailed: 'فشلت الأرشفة',
+    cwdChangeFailed: 'فشل تغيير مجلد العمل',
+    cwdStagedTitle: 'تم تجهيز مجلد العمل',
+    cwdStagedMessage: 'سيطبق مجلد العمل على الرسالة التالية.',
+    modelSwitchFailed: 'فشل تبديل النموذج',
+    sessionExported: 'تم تصدير الجلسة',
+    sessionExportFailed: 'فشل تصدير الجلسة',
+    imageSaved: 'تم حفظ الصورة',
+    downloadStarted: 'بدأ التنزيل',
+    restartToUseSaveImage: 'أعد التشغيل لاستخدام حفظ الصور',
+    restartToSaveImages: 'أعد التشغيل لحفظ الصور',
+    imageDownloadFailed: 'فشل تنزيل الصورة',
+    openImage: 'فتح الصورة',
+    downloadImage: 'تنزيل الصورة',
+    savingImage: 'جار حفظ الصورة',
+    imagePreviewFailed: 'فشلت معاينة الصورة',
+    imageAttach: 'إرفاق الصورة',
+    imageWriteFailed: 'فشل كتابة الصورة',
+    imageAttachFailed: 'فشل إرفاق الصورة',
+    attachImages: 'إرفاق الصور',
+    clipboard: 'الحافظة',
+    noClipboardImage: 'لا توجد صورة في الحافظة',
+    clipboardPasteFailed: 'فشل اللصق من الحافظة',
+    dropFiles: 'أفلت الملفات هنا',
+    handoff: {
+      pickPlatform: 'اختر وجهة',
+      success: platform => `تم التسليم إلى ${platform}. استأنف هنا في أي وقت.`,
+      systemNote: platform => `↻ تم التسليم إلى ${platform} — استأنف هنا في أي وقت.`,
+      failed: error => `فشل التسليم: ${error}`,
+      timedOut: 'انتهت المهلة في انتظار البوابة. هل `hermes gateway` قيد التشغيل؟'
+    }
+  },
+  errors: {
+    genericFailure: 'حدث خطأ',
+    boundaryTitle: 'تعطل جزء من الواجهة',
+    boundaryDesc: 'يمكنك إعادة تحميل النافذة أو فتح السجلات لمعرفة التفاصيل.',
+    reloadWindow: 'إعادة تحميل النافذة',
+    openLogs: 'فتح السجلات'
+  },
+  ui: {
+    search: {
+      clear: 'مسح البحث'
+    },
+    pagination: {
+      label: 'ترقيم الصفحات',
+      previous: 'السابق',
+      previousAria: 'الصفحة السابقة',
+      next: 'التالي',
+      nextAria: 'الصفحة التالية'
+    },
+    sidebar: {
+      title: 'الشريط الجانبي',
+      description: 'تنقل التطبيق',
+      toggle: 'تبديل الشريط الجانبي'
+    }
+  }
+})
diff --git a/apps/desktop/src/i18n/catalog.ts b/apps/desktop/src/i18n/catalog.ts
index 19556cb45c4..f35c957076d 100644
--- a/apps/desktop/src/i18n/catalog.ts
+++ b/apps/desktop/src/i18n/catalog.ts
@@ -1,3 +1,4 @@
+import { ar } from './ar'
 import { en } from './en'
 import { ja } from './ja'
 import type { Locale, Translations } from './types'
@@ -8,5 +9,6 @@ export const TRANSLATIONS: Record<Locale, Translations> = {
   en,
   zh,
   'zh-hant': zhHant,
-  ja
+  ja,
+  ar
 }
diff --git a/apps/desktop/src/i18n/context.test.tsx b/apps/desktop/src/i18n/context.test.tsx
index 3028c86ffa0..729ced7a4da 100644
--- a/apps/desktop/src/i18n/context.test.tsx
+++ b/apps/desktop/src/i18n/context.test.tsx
@@ -209,6 +209,24 @@ describe('I18nProvider', () => {
     expect(screen.getByTestId('locale').textContent).toBe('ja')
   })
 
+  it('applies RTL direction for Arabic and restores LTR on switch back', async () => {
+    render(
+      <I18nProvider configClient={null} initialLocale="ar">
+        <LanguageProbe target="en" />
+      </I18nProvider>
+    )
+
+    expect(screen.getByTestId('locale').textContent).toBe('ar')
+    expect(document.documentElement.dir).toBe('rtl')
+    expect(document.documentElement.lang).toBe('ar')
+
+    fireEvent.click(screen.getByRole('button', { name: 'switch' }))
+
+    await waitFor(() => expect(screen.getByTestId('locale').textContent).toBe('en'))
+    expect(document.documentElement.dir).toBe('ltr')
+    expect(document.documentElement.lang).toBe('en')
+  })
+
   it('rolls back the visible locale when saving fails', async () => {
     const configClient: I18nConfigClient = {
       getConfig: vi.fn().mockResolvedValue({ display: { language: 'en' } }),
diff --git a/apps/desktop/src/i18n/context.tsx b/apps/desktop/src/i18n/context.tsx
index 103a63047e7..87c6337652d 100644
--- a/apps/desktop/src/i18n/context.tsx
+++ b/apps/desktop/src/i18n/context.tsx
@@ -55,6 +55,17 @@ function toError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error))
 }
 
+const RTL_LOCALES = new Set<Locale>(['ar'])
+
+function applyDocumentLocale(locale: Locale) {
+  if (typeof document === 'undefined') {
+    return
+  }
+
+  document.documentElement.lang = locale
+  document.documentElement.dir = RTL_LOCALES.has(locale) ? 'rtl' : 'ltr'
+}
+
 export interface I18nContextValue {
   configLoadError: Error | null
   isLoadingConfig: boolean
@@ -89,9 +100,11 @@ export function I18nProvider({ children, configClient = defaultConfigClient, ini
   const [saveError, setSaveError] = useState<Error | null>(null)
   const localeRef = useRef(locale)
 
+  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
   useEffect(() => {
     localeRef.current = locale
     setRuntimeI18nLocale(locale)
+    applyDocumentLocale(locale)
   }, [locale])
 
   useEffect(() => {
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index 8e602867f90..c1d59a013b8 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -576,13 +576,15 @@ export const en: Translations = {
       allProfiles: 'All profiles',
       defaultConnection: 'Default connection for every profile that has no override of its own.',
       profileConnection: profile =>
-        `Connection used only when “${profile}” is the active profile. Set it to Local to inherit the default.`,
+        `Connection used only when “${profile}” is the active profile. Choose Use default gateway to remove its override.`,
       envOverrideTitle: 'Environment variables are controlling this desktop session.',
       envOverrideDesc:
         'Unset HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN to use the saved setting below.',
       modeTitle: 'Connection mode',
       localTitle: 'Local gateway',
       localDesc: 'Start a private Hermes backend on localhost. This is the default and works offline.',
+      inheritTitle: 'Use default gateway',
+      inheritDesc: "Remove this profile's override and use the default connection.",
       remoteTitle: 'Remote gateway',
       remoteDesc: 'Connect this desktop shell to a remote Hermes backend.',
       remoteAuthHint: 'Hosted gateways use OAuth or a username and password; self-hosted ones may use a session token.',
@@ -843,6 +845,12 @@ export const en: Translations = {
       messages: count => `${count} ${count === 1 ? 'message' : 'messages'}`,
       restored: 'Restored',
       deleteConfirm: title => `Permanently delete "${title}"? This cannot be undone.`,
+      autoArchiveTitle: 'Auto-archive stale chats',
+      autoArchiveDesc:
+        "Automatically archive chats you haven't touched in a while. Pinned chats are never archived, and nothing is deleted — archived chats just move here.",
+      autoArchiveDaysLabel: 'Archive after',
+      autoArchiveDaysUnit: 'days of inactivity',
+      autoArchiveFailed: 'Could not update auto-archive',
       defaultDirTitle: 'Default project directory',
       defaultDirDesc:
         'New sessions start in this folder unless you pick another. Leave it unset to use your home directory.',
@@ -1416,6 +1424,72 @@ export const en: Translations = {
     platformIntro: {}
   },
 
+  webhooks: {
+    search: 'Search webhooks...',
+    loading: 'Loading webhooks...',
+    loadFailed: 'Webhooks failed to load',
+    subscriptions: (count: number) => `Subscriptions (${count})`,
+    hint: 'Subscription changes hot-reload once the receiver is running. Disabled subscriptions reject incoming events.',
+    empty: 'No webhook subscriptions yet.',
+    disabledTitle: 'Webhook receiver disabled',
+    disabledBody:
+      'Webhooks are their own gateway platform. Enable them here to accept incoming HTTP events; chat channels are only needed when a subscription delivers to Telegram, Discord, Slack, or another channel.',
+    enable: 'Enable webhooks',
+    enabling: 'Enabling...',
+    enabled: (name: string) => `Enabled: "${name}"`,
+    disabled: (name: string) => `Disabled: "${name}"`,
+    enableRow: 'Enable',
+    disableRow: 'Disable',
+    delete: 'Delete',
+    deleting: 'Deleting...',
+    deleted: 'Webhook deleted',
+    deleteTitle: 'Delete webhook',
+    deleteDescPrefix: 'This will permanently remove ',
+    deleteDescSuffix: '. This cannot be undone.',
+    deleteFailed: (name: string) => `Failed to delete "${name}"`,
+    toggleFailed: (name: string) => `Failed to update "${name}"`,
+    newSubscription: 'New subscription',
+    restarting: 'Gateway restarting...',
+    restartNeeded: 'Webhooks are enabled, but the gateway still needs a restart before the receiver can come online.',
+    restartGateway: 'Restart gateway',
+    restartingGateway: 'Restarting...',
+    restartFailed: (detail: string) => `Gateway restart failed${detail}`,
+    enabledRestarting: 'Webhooks enabled; gateway restarting...',
+    all: '(all)',
+    deliverOnly: 'deliver only',
+    createdTitle: 'Subscription created',
+    createdSecretHint: 'Copy the secret now — it is only shown once.',
+    webhookUrl: 'Webhook URL',
+    secretOnce: 'Secret (shown once)',
+    done: 'Done',
+    fieldName: 'Name',
+    fieldNamePlaceholder: 'e.g. github-push',
+    fieldDescription: 'Description',
+    fieldDescriptionPlaceholder: 'What this webhook does (optional)',
+    fieldEvents: 'Events',
+    fieldEventsPlaceholder: 'comma-separated, leave empty for all',
+    fieldSkills: 'Skills',
+    fieldSkillsPlaceholder: 'comma-separated skill names (optional)',
+    fieldDeliver: 'Deliver to',
+    fieldDeliverOnly: 'Deliver payload only',
+    fieldPrompt: 'Prompt',
+    fieldPromptPlaceholder: 'Instructions for the agent when this webhook fires (optional)',
+    nameRequired: 'Name required',
+    create: 'Create',
+    creating: 'Creating...',
+    created: 'Created',
+    createFailed: (detail: string) => `Failed to create: ${detail}`,
+    copy: 'Copy',
+    deliverOptions: {
+      log: 'Log',
+      telegram: 'Telegram',
+      discord: 'Discord',
+      slack: 'Slack',
+      email: 'Email',
+      github_comment: 'GitHub comment'
+    }
+  },
+
   profiles: {
     close: 'Close profiles',
     nameHint: 'Lowercase letters, digits, hyphens, and underscores. Must start with a letter or digit.',
@@ -1597,6 +1671,7 @@ export const en: Translations = {
     promptPlaceholder: 'Summarize my unread Slack threads and email me the top 5...',
     frequencyLabel: 'Frequency',
     deliverLabel: 'Deliver to',
+    deliverNeedsHomeChannel: 'set a home channel first',
     modelLabel: 'Model',
     modelDefault: 'Default (global model)',
     customScheduleLabel: 'Custom schedule',
@@ -1608,7 +1683,25 @@ export const en: Translations = {
     scheduleRequired: 'Schedule is required.',
     scriptOnlyEditHint: 'Script-only job (no AI prompt). Job id:',
     saveChanges: 'Save changes',
-    createAction: 'Create cron'
+    createAction: 'Create cron',
+    tabs: {
+      jobs: 'Jobs',
+      blueprints: 'Blueprints'
+    },
+    blueprints: {
+      tab: 'Blueprints',
+      startFrom: 'Start from',
+      custom: 'Custom',
+      subtitle: 'Ready-made automations',
+      dialogDesc: 'Fill in the details and schedule it.',
+      scheduleIt: 'Schedule it',
+      scheduling: 'Scheduling...',
+      scheduled: 'Blueprint scheduled',
+      loading: 'Loading blueprints...',
+      failedLoad: 'Failed to load blueprints',
+      emptyTitle: 'No blueprints available',
+      emptyDesc: 'No automation blueprints are available on this backend.'
+    }
   },
 
   artifacts: {
@@ -1773,6 +1866,13 @@ export const en: Translations = {
       ageDay: 'd',
       ageHour: 'h',
       ageMin: 'm'
+    },
+    dateDivider: {
+      today: 'Earlier today',
+      yesterday: 'Yesterday',
+      thisWeek: 'Earlier this week',
+      lastWeek: 'Last week',
+      thisMonth: 'Earlier this month'
     }
   },
 
@@ -2041,6 +2141,40 @@ export const en: Translations = {
     viewDocs: 'View install docs',
     installTo: 'Will install to',
     retryAfterRun: 'I’ve run it -- retry',
+    setupChoiceTitle: 'Set up Hermes Desktop',
+    setupChoiceDesc:
+      'Connect this app to a Hermes gateway you already run, or install Hermes locally on this computer.',
+    connectExistingTitle: 'Connect to existing Hermes',
+    connectExistingShort: 'Connect existing',
+    connectExistingDesc: 'Use a remote backend with a session token or browser sign-in. No local install will start.',
+    installLocalTitle: 'Install Hermes locally',
+    installLocalDesc: 'Download Hermes, create its Python environment, and run the backend on this computer.',
+    localStartUnavailable: 'Local installation could not start. Restart Hermes Desktop and try again.',
+    remoteSetupTitle: 'Connect to existing Hermes',
+    remoteSetupDesc: 'Enter your gateway URL. Hermes Desktop will detect whether it needs a token or browser sign-in.',
+    remoteUrlTitle: 'Gateway URL',
+    remoteUrlDesc: 'Use the base URL of the Hermes gateway, including https:// when remote.',
+    remoteUrlPlaceholder: 'https://gateway.example.com/hermes',
+    probing: 'Detecting gateway authentication...',
+    probeError: 'Could not reach that Hermes gateway.',
+    identityProvider: 'your identity provider',
+    authTitle: 'Authentication',
+    authNeedsOauth: provider => `Sign in with ${provider} before testing this gateway.`,
+    authSignedIn: 'Browser sign-in completed.',
+    connected: 'Connected',
+    signIn: 'Sign in',
+    signInWith: provider => `Sign in with ${provider}`,
+    enterUrlFirst: 'Enter a gateway URL first.',
+    signInIncomplete: 'The sign-in window closed before authentication completed.',
+    tokenTitle: 'Session token',
+    tokenDesc: 'Paste the session token from the remote gateway .env file.',
+    pasteSessionToken: 'Paste session token',
+    incompleteSignInTest: 'Sign in before testing this OAuth-gated gateway.',
+    incompleteTokenTest: 'Enter a session token before testing this gateway.',
+    testConnection: 'Test connection',
+    testSucceeded: (baseUrl, version) => `Connected to ${baseUrl}${version ? ` (${version})` : ''}.`,
+    applyRemote: 'Apply and reconnect',
+    backToSetup: 'Back',
     failedTitle: 'Installation failed',
     settingUpTitle: 'Setting up Hermes Agent',
     finishingTitle: 'Finishing up',
@@ -2174,8 +2308,7 @@ export const en: Translations = {
       noModels: 'No models found',
       editModels: 'Edit Models…',
       refreshModels: 'Refresh Models',
-      fast: 'Fast',
-      medium: 'Med'
+      fast: 'Fast'
     },
     modelOptions: {
       noOptions: 'No options for this model',
@@ -2256,6 +2389,8 @@ export const en: Translations = {
       running: count => `${count} running`,
       cron: 'Cron',
       openCron: 'Open cron jobs',
+      webhooks: 'Webhooks',
+      openWebhooks: 'Open webhooks',
       starmap: 'Memory Graph',
       openStarmap: 'Open memory graph',
       turnRunning: 'Running',
@@ -2606,6 +2741,7 @@ export const en: Translations = {
         execute_code: { done: 'Ran code', pending: 'Scripting', pendingAction: 'Scripting' },
         image_generate: { done: 'Generated image', pending: 'Generating image', pendingAction: 'Generating' },
         list_files: { done: 'Listed files', pending: 'Listing files', pendingAction: 'Listing' },
+        memory: { done: 'Saved to memory', pending: 'Saving to memory', pendingAction: 'Saving' },
         patch: { done: 'Patched file', pending: 'Patching file', pendingAction: 'Patching' },
         read_file: { done: 'Read file', pending: 'Reading file', pendingAction: 'Reading' },
         search_files: { done: 'Searched files', pending: 'Searching files', pendingAction: 'Searching' },
diff --git a/apps/desktop/src/i18n/ja.ts b/apps/desktop/src/i18n/ja.ts
index d7dd7ec5651..738a4859e05 100644
--- a/apps/desktop/src/i18n/ja.ts
+++ b/apps/desktop/src/i18n/ja.ts
@@ -683,13 +683,15 @@ export const ja = defineLocale({
       allProfiles: 'すべてのプロファイル',
       defaultConnection: '独自のオーバーライドがないすべてのプロファイルのデフォルト接続。',
       profileConnection: profile =>
-        `"${profile}" がアクティブプロファイルのときのみ使用される接続。ローカルに設定するとデフォルトを継承します。`,
+        `"${profile}" がアクティブプロファイルのときのみ使用される接続。「デフォルトゲートウェイを使用」を選ぶとオーバーライドが削除されます。`,
       envOverrideTitle: '環境変数がこのデスクトップセッションを制御しています。',
       envOverrideDesc:
         '保存された設定を使用するには HERMES_DESKTOP_REMOTE_URL と HERMES_DESKTOP_REMOTE_TOKEN の設定を解除してください。',
       localTitle: 'ローカルゲートウェイ',
       localDesc:
         'ローカルホストでプライベートな Hermes バックエンドを起動します。これがデフォルトで、オフラインでも動作します。',
+      inheritTitle: 'デフォルトゲートウェイを使用',
+      inheritDesc: 'このプロファイルのオーバーライドを削除し、デフォルト接続を使用します。',
       remoteTitle: 'リモートゲートウェイ',
       remoteDesc:
         'このデスクトップシェルをリモートの Hermes バックエンドに接続します。ホスト型ゲートウェイは OAuth またはユーザー名とパスワードを使用します。自己ホスト型はセッショントークンを使用する場合があります。',
@@ -890,6 +892,12 @@ export const ja = defineLocale({
       messages: count => `${count} 件のメッセージ`,
       restored: '復元しました',
       deleteConfirm: title => `"${title}" を完全に削除しますか？この操作は元に戻せません。`,
+      autoArchiveTitle: '古いチャットを自動アーカイブ',
+      autoArchiveDesc:
+        'しばらく操作していないチャットを自動的にアーカイブします。ピン留めしたチャットはアーカイブされず、削除もされません。アーカイブされたチャットはここに移動します。',
+      autoArchiveDaysLabel: 'アーカイブまでの日数',
+      autoArchiveDaysUnit: '日間操作なし',
+      autoArchiveFailed: '自動アーカイブを更新できませんでした',
       defaultDirTitle: 'デフォルトのプロジェクトディレクトリ',
       defaultDirDesc:
         '別のフォルダーを選択しない限り、新しいセッションはこのフォルダーで開始します。未設定の場合はホームディレクトリが使用されます。',
@@ -1535,6 +1543,7 @@ export const ja = defineLocale({
     promptPlaceholder: '実行ごとにエージェントが行う内容は？',
     frequencyLabel: '頻度',
     deliverLabel: '配信先',
+    deliverNeedsHomeChannel: '先にホームチャンネルを設定してください',
     modelLabel: 'モデル',
     modelDefault: 'デフォルト（グローバルモデル）',
     customScheduleLabel: 'カスタムスケジュール',
@@ -1546,7 +1555,25 @@ export const ja = defineLocale({
     scheduleRequired: 'スケジュールは必須です。',
     scriptOnlyEditHint: 'スクリプトのみのジョブ（AI プロンプトなし）。ジョブ ID:',
     saveChanges: '変更を保存',
-    createAction: 'Cron を作成'
+    createAction: 'Cron を作成',
+    tabs: {
+      jobs: 'ジョブ',
+      blueprints: 'ブレーンプリント'
+    },
+    blueprints: {
+      tab: 'ブレーンプリント',
+      startFrom: '開始点',
+      custom: 'カスタム',
+      subtitle: 'すぐに使える自動化',
+      dialogDesc: '詳細を入力してスケジュールします。',
+      scheduleIt: 'スケジュールする',
+      scheduling: 'スケジュール中...',
+      scheduled: 'ブレーンプリントをスケジュールしました',
+      loading: 'ブレーンプリントを読み込み中...',
+      failedLoad: 'ブレーンプリントの読み込みに失敗しました',
+      emptyTitle: '利用できるブレーンプリントはありません',
+      emptyDesc: 'このバックエンドで利用できる自動化ブレーンプリントはありません。'
+    }
   },
 
   artifacts: {
@@ -1706,6 +1733,13 @@ export const ja = defineLocale({
       ageDay: '日',
       ageHour: '時間',
       ageMin: '分'
+    },
+    dateDivider: {
+      today: '今日の早い時間',
+      yesterday: '昨日',
+      thisWeek: '今週',
+      lastWeek: '先週',
+      thisMonth: '今月'
     }
   },
 
@@ -1976,6 +2010,43 @@ export const ja = defineLocale({
     viewDocs: 'インストールドキュメントを見る',
     installTo: 'インストール先',
     retryAfterRun: '実行しました — 再試行',
+    setupChoiceTitle: 'Hermes Desktop をセットアップ',
+    setupChoiceDesc:
+      'すでに実行している Hermes ゲートウェイに接続するか、このコンピューターに Hermes をローカルインストールします。',
+    connectExistingTitle: '既存の Hermes に接続',
+    connectExistingShort: '既存環境に接続',
+    connectExistingDesc:
+      'セッショントークンまたはブラウザーサインインでリモートバックエンドを使用します。ローカルインストールは開始されません。',
+    installLocalTitle: 'Hermes をローカルにインストール',
+    installLocalDesc: 'Hermes をダウンロードし、Python 環境を作成して、このコンピューターでバックエンドを実行します。',
+    localStartUnavailable:
+      'ローカルインストールを開始できません。Hermes Desktop を再起動して、もう一度お試しください。',
+    remoteSetupTitle: '既存の Hermes に接続',
+    remoteSetupDesc:
+      'ゲートウェイ URL を入力してください。Hermes Desktop がトークンとブラウザーサインインのどちらが必要かを検出します。',
+    remoteUrlTitle: 'ゲートウェイ URL',
+    remoteUrlDesc: 'Hermes ゲートウェイのベース URL を使用します。リモートの場合は https:// を含めてください。',
+    remoteUrlPlaceholder: 'https://gateway.example.com/hermes',
+    probing: 'ゲートウェイ認証方式を検出中...',
+    probeError: 'その Hermes ゲートウェイに到達できませんでした。',
+    identityProvider: 'ID プロバイダー',
+    authTitle: '認証',
+    authNeedsOauth: provider => `このゲートウェイをテストする前に ${provider} でサインインしてください。`,
+    authSignedIn: 'ブラウザーサインインが完了しました。',
+    connected: '接続済み',
+    signIn: 'サインイン',
+    signInWith: provider => `${provider} でサインイン`,
+    enterUrlFirst: '先にゲートウェイ URL を入力してください。',
+    signInIncomplete: '認証が完了する前にサインインウィンドウが閉じられました。',
+    tokenTitle: 'セッショントークン',
+    tokenDesc: 'リモートゲートウェイの .env ファイルからセッショントークンを貼り付けます。',
+    pasteSessionToken: 'セッショントークンを貼り付け',
+    incompleteSignInTest: 'OAuth で保護されたこのゲートウェイをテストする前にサインインしてください。',
+    incompleteTokenTest: 'このゲートウェイをテストする前にセッショントークンを入力してください。',
+    testConnection: '接続をテスト',
+    testSucceeded: (baseUrl, version) => `${baseUrl}${version ? ` (${version})` : ''} に接続しました。`,
+    applyRemote: '適用して再接続',
+    backToSetup: '戻る',
     failedTitle: 'インストールに失敗しました',
     settingUpTitle: 'Hermes Agent を設定中',
     finishingTitle: '仕上げ中',
@@ -2109,8 +2180,7 @@ export const ja = defineLocale({
       noModels: 'モデルが見つかりません',
       editModels: 'モデルを編集…',
       refreshModels: 'モデルを更新',
-      fast: '高速',
-      medium: '中'
+      fast: '高速'
     },
     modelOptions: {
       noOptions: 'このモデルにはオプションがありません',
@@ -2543,6 +2613,11 @@ export const ja = defineLocale({
           pending: 'ファイルを一覧表示中',
           pendingAction: '一覧表示中'
         },
+        memory: {
+          done: 'メモリに保存しました',
+          pending: 'メモリに保存中',
+          pendingAction: '保存中'
+        },
         patch: {
           done: 'ファイルにパッチを適用しました',
           pending: 'ファイルにパッチ適用中',
diff --git a/apps/desktop/src/i18n/languages.test.ts b/apps/desktop/src/i18n/languages.test.ts
index 792aad5f586..fa6a8a4c22d 100644
--- a/apps/desktop/src/i18n/languages.test.ts
+++ b/apps/desktop/src/i18n/languages.test.ts
@@ -15,6 +15,9 @@ describe('desktop i18n languages', () => {
     expect(normalizeLocale('zh_HK')).toBe('zh-hant')
     expect(normalizeLocale('ja')).toBe('ja')
     expect(normalizeLocale('ja-JP')).toBe('ja')
+    expect(normalizeLocale('ar')).toBe('ar')
+    expect(normalizeLocale('AR-SA')).toBe('ar')
+    expect(normalizeLocale(' ar_eg ')).toBe('ar')
   })
 
   it('falls back to English for empty or unsupported values', () => {
@@ -32,6 +35,7 @@ describe('desktop i18n languages', () => {
     expect(isLocale('zh')).toBe(true)
     expect(isLocale('zh-hant')).toBe(true)
     expect(isLocale('ja')).toBe(true)
+    expect(isLocale('ar')).toBe(true)
   })
 
   it('returns the persisted config value for supported locales', () => {
@@ -39,5 +43,6 @@ describe('desktop i18n languages', () => {
     expect(localeConfigValue('zh')).toBe('zh')
     expect(localeConfigValue('zh-hant')).toBe('zh-hant')
     expect(localeConfigValue('ja')).toBe('ja')
+    expect(localeConfigValue('ar')).toBe('ar')
   })
 })
diff --git a/apps/desktop/src/i18n/languages.ts b/apps/desktop/src/i18n/languages.ts
index 96daf9b598d..e4a1fb1e02e 100644
--- a/apps/desktop/src/i18n/languages.ts
+++ b/apps/desktop/src/i18n/languages.ts
@@ -28,6 +28,12 @@ export const LOCALE_OPTIONS = [
     name: '日本語',
     englishName: 'Japanese',
     configValue: 'ja'
+  },
+  {
+    id: 'ar',
+    name: 'العربية',
+    englishName: 'Arabic',
+    configValue: 'ar'
   }
 ] as const satisfies readonly { configValue: string; englishName: string; id: Locale; name: string }[]
 
@@ -64,7 +70,16 @@ const LOCALE_ALIASES: Record<string, Locale> = {
   zh_hant_hk: 'zh-hant',
   ja: 'ja',
   'ja-jp': 'ja',
-  ja_jp: 'ja'
+  ja_jp: 'ja',
+  ar: 'ar',
+  'ar-sa': 'ar',
+  ar_sa: 'ar',
+  'ar-ae': 'ar',
+  ar_ae: 'ar',
+  'ar-eg': 'ar',
+  ar_eg: 'ar',
+  arabic: 'ar',
+  العربية: 'ar'
 }
 
 export function isLocale(value: unknown): value is Locale {
diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts
index 65a93e3dda8..90506fe9237 100644
--- a/apps/desktop/src/i18n/types.ts
+++ b/apps/desktop/src/i18n/types.ts
@@ -5,7 +5,7 @@
 // partial locales should use `defineLocale()` so missing desktop-only strings
 // fall back to English while new keys remain type-checked.
 
-export type Locale = 'en' | 'zh' | 'zh-hant' | 'ja'
+export type Locale = 'en' | 'zh' | 'zh-hant' | 'ja' | 'ar'
 
 export type ToolTitleKey =
   | 'browser_click'
@@ -20,6 +20,7 @@ export type ToolTitleKey =
   | 'execute_code'
   | 'image_generate'
   | 'list_files'
+  | 'memory'
   | 'patch'
   | 'read_file'
   | 'search_files'
@@ -486,6 +487,8 @@ export interface Translations {
       modeTitle: string
       localTitle: string
       localDesc: string
+      inheritTitle: string
+      inheritDesc: string
       remoteTitle: string
       remoteDesc: string
       remoteAuthHint: string
@@ -723,6 +726,11 @@ export interface Translations {
       messages: (count: number) => string
       restored: string
       deleteConfirm: (title: string) => string
+      autoArchiveTitle: string
+      autoArchiveDesc: string
+      autoArchiveDaysLabel: string
+      autoArchiveDaysUnit: string
+      autoArchiveFailed: string
       defaultDirTitle: string
       defaultDirDesc: string
       defaultDirUpdated: string
@@ -1176,6 +1184,64 @@ export interface Translations {
     platformIntro: Record<string, string>
   }
 
+  webhooks: {
+    search: string
+    loading: string
+    loadFailed: string
+    subscriptions: (count: number) => string
+    hint: string
+    empty: string
+    disabledTitle: string
+    disabledBody: string
+    enable: string
+    enabling: string
+    enabled: (name: string) => string
+    disabled: (name: string) => string
+    enableRow: string
+    disableRow: string
+    delete: string
+    deleting: string
+    deleted: string
+    deleteTitle: string
+    deleteDescPrefix: string
+    deleteDescSuffix: string
+    deleteFailed: (name: string) => string
+    toggleFailed: (name: string) => string
+    newSubscription: string
+    restarting: string
+    restartNeeded: string
+    restartGateway: string
+    restartingGateway: string
+    restartFailed: (detail: string) => string
+    enabledRestarting: string
+    all: string
+    deliverOnly: string
+    createdTitle: string
+    createdSecretHint: string
+    webhookUrl: string
+    secretOnce: string
+    done: string
+    fieldName: string
+    fieldNamePlaceholder: string
+    fieldDescription: string
+    fieldDescriptionPlaceholder: string
+    fieldEvents: string
+    fieldEventsPlaceholder: string
+    fieldSkills: string
+    fieldSkillsPlaceholder: string
+    fieldDeliver: string
+    fieldDeliverOnly: string
+    fieldPrompt: string
+    fieldPromptPlaceholder: string
+    nameRequired: string
+    create: string
+    creating: string
+    created: string
+    createFailed: (detail: string) => string
+    copy: string
+    deliverOptions: Record<string, string>
+  }
+
   profiles: {
     close: string
     nameHint: string
@@ -1317,6 +1383,7 @@ export interface Translations {
     promptPlaceholder: string
     frequencyLabel: string
     deliverLabel: string
+    deliverNeedsHomeChannel: string
     modelLabel: string
     modelDefault: string
     customScheduleLabel: string
@@ -1329,6 +1396,24 @@ export interface Translations {
     scriptOnlyEditHint: string
     saveChanges: string
     createAction: string
+    tabs: {
+      jobs: string
+      blueprints: string
+    }
+    blueprints: {
+      tab: string
+      startFrom: string
+      custom: string
+      subtitle: string
+      dialogDesc: string
+      scheduleIt: string
+      scheduling: string
+      scheduled: string
+      loading: string
+      failedLoad: string
+      emptyTitle: string
+      emptyDesc: string
+    }
   }
 
   artifacts: {
@@ -1486,6 +1571,13 @@ export interface Translations {
       ageHour: string
       ageMin: string
     }
+    dateDivider: {
+      today: string
+      yesterday: string
+      thisWeek: string
+      lastWeek: string
+      thisMonth: string
+    }
   }
 
   composer: {
@@ -1683,6 +1775,39 @@ export interface Translations {
     viewDocs: string
     installTo: string
     retryAfterRun: string
+    setupChoiceTitle: string
+    setupChoiceDesc: string
+    connectExistingTitle: string
+    connectExistingShort: string
+    connectExistingDesc: string
+    installLocalTitle: string
+    installLocalDesc: string
+    localStartUnavailable: string
+    remoteSetupTitle: string
+    remoteSetupDesc: string
+    remoteUrlTitle: string
+    remoteUrlDesc: string
+    remoteUrlPlaceholder: string
+    probing: string
+    probeError: string
+    identityProvider: string
+    authTitle: string
+    authNeedsOauth: (provider: string) => string
+    authSignedIn: string
+    connected: string
+    signIn: string
+    signInWith: (provider: string) => string
+    enterUrlFirst: string
+    signInIncomplete: string
+    tokenTitle: string
+    tokenDesc: string
+    pasteSessionToken: string
+    incompleteSignInTest: string
+    incompleteTokenTest: string
+    testConnection: string
+    testSucceeded: (baseUrl: string, version?: string) => string
+    applyRemote: string
+    backToSetup: string
     failedTitle: string
     settingUpTitle: string
     finishingTitle: string
@@ -1793,7 +1918,6 @@ export interface Translations {
       editModels: string
       refreshModels: string
       fast: string
-      medium: string
     }
     modelOptions: {
       noOptions: string
@@ -1874,6 +1998,8 @@ export interface Translations {
       running: (count: number) => string
       cron: string
       openCron: string
+      webhooks: string
+      openWebhooks: string
       starmap: string
       openStarmap: string
       turnRunning: string
diff --git a/apps/desktop/src/i18n/zh-hant.ts b/apps/desktop/src/i18n/zh-hant.ts
index 5229164c0a7..73933bf8885 100644
--- a/apps/desktop/src/i18n/zh-hant.ts
+++ b/apps/desktop/src/i18n/zh-hant.ts
@@ -670,11 +670,13 @@ export const zhHant = defineLocale({
       appliesTo: '套用至',
       allProfiles: '全部設定檔',
       defaultConnection: '預設連線適用於所有沒有自訂覆寫的設定檔。',
-      profileConnection: profile => `僅當「${profile}」為作用中設定檔時使用此連線。設為本機可繼承預設連線。`,
+      profileConnection: profile => `僅當「${profile}」為作用中設定檔時使用此連線。選擇「使用預設閘道」可移除其覆寫。`,
       envOverrideTitle: '環境變數正在控制此桌面工作階段。',
       envOverrideDesc: '取消設定 HERMES_DESKTOP_REMOTE_URL 和 HERMES_DESKTOP_REMOTE_TOKEN 後才會使用下方儲存的設定。',
       localTitle: '本機閘道',
       localDesc: '在 localhost 啟動私有 Hermes 後端。這是預設方式，可離線使用。',
+      inheritTitle: '使用預設閘道',
+      inheritDesc: '移除此設定檔的自訂覆寫並使用預設連線。',
       remoteTitle: '遠端閘道',
       remoteDesc:
         '將此桌面殼層連線至遠端 Hermes 後端。託管閘道使用 OAuth 或帳號密碼；自託管閘道也可使用工作階段 Token。',
@@ -863,6 +865,12 @@ export const zhHant = defineLocale({
       messages: count => `${count} 則訊息`,
       restored: '已還原',
       deleteConfirm: title => `永久刪除「${title}」？此操作無法復原。`,
+      autoArchiveTitle: '自動封存閒置對話',
+      autoArchiveDesc:
+        '自動封存你一段時間未使用的對話。已釘選的對話永遠不會被封存，也不會刪除任何內容——封存的對話會移到這裡。',
+      autoArchiveDaysLabel: '封存前',
+      autoArchiveDaysUnit: '天無活動',
+      autoArchiveFailed: '無法更新自動封存設定',
       defaultDirTitle: '預設專案目錄',
       defaultDirDesc: '新工作階段預設從此資料夾開始，除非您選擇其他目錄。留空則使用您的家目錄。',
       defaultDirUpdated: '預設專案目錄已更新',
@@ -1484,6 +1492,7 @@ export const zhHant = defineLocale({
     promptPlaceholder: '代理每次執行時應做什麼？',
     frequencyLabel: '頻率',
     deliverLabel: '傳遞至',
+    deliverNeedsHomeChannel: '請先設定主頻道',
     modelLabel: '模型',
     modelDefault: '預設（全域模型）',
     customScheduleLabel: '自訂排程',
@@ -1495,7 +1504,25 @@ export const zhHant = defineLocale({
     scheduleRequired: '排程為必填項目。',
     scriptOnlyEditHint: '僅腳本任務（無 AI 提示詞）。任務 ID：',
     saveChanges: '儲存變更',
-    createAction: '建立排程工作'
+    createAction: '建立排程工作',
+    tabs: {
+      jobs: '工作',
+      blueprints: '藍圖'
+    },
+    blueprints: {
+      tab: '藍圖',
+      startFrom: '從此開始',
+      custom: '自訂',
+      subtitle: '現成的自動化',
+      dialogDesc: '填寫詳細資訊並進行排程。',
+      scheduleIt: '安排工作',
+      scheduling: '安排中...',
+      scheduled: '藍圖已安排',
+      loading: '正在載入藍圖...',
+      failedLoad: '載入藍圖失敗',
+      emptyTitle: '沒有可用的藍圖',
+      emptyDesc: '此後端上沒有可用的自動化藍圖。'
+    }
   },
 
   artifacts: {
@@ -1652,6 +1679,13 @@ export const zhHant = defineLocale({
       ageDay: '天',
       ageHour: '時',
       ageMin: '分'
+    },
+    dateDivider: {
+      today: '今天稍早',
+      yesterday: '昨天',
+      thisWeek: '本週',
+      lastWeek: '上週',
+      thisMonth: '本月'
     }
   },
 
@@ -1917,6 +1951,39 @@ export const zhHant = defineLocale({
     viewDocs: '檢視安裝文件',
     installTo: '將安裝至',
     retryAfterRun: '我已執行 -- 重試',
+    setupChoiceTitle: '設定 Hermes Desktop',
+    setupChoiceDesc: '將此應用程式連線到您已執行的 Hermes 閘道，或在這台電腦上本機安裝 Hermes。',
+    connectExistingTitle: '連線到現有 Hermes',
+    connectExistingShort: '連線現有環境',
+    connectExistingDesc: '使用工作階段權杖或瀏覽器登入連線遠端後端。不會啟動本機安裝。',
+    installLocalTitle: '本機安裝 Hermes',
+    installLocalDesc: '下載 Hermes、建立 Python 環境，並在這台電腦上執行後端。',
+    localStartUnavailable: '無法啟動本機安裝。請重新啟動 Hermes Desktop 後再試一次。',
+    remoteSetupTitle: '連線到現有 Hermes',
+    remoteSetupDesc: '輸入閘道 URL。Hermes Desktop 會偵測需要權杖還是瀏覽器登入。',
+    remoteUrlTitle: '閘道 URL',
+    remoteUrlDesc: '使用 Hermes 閘道的基礎 URL；遠端位址請包含 https://。',
+    remoteUrlPlaceholder: 'https://gateway.example.com/hermes',
+    probing: '正在偵測閘道驗證方式...',
+    probeError: '無法連線到該 Hermes 閘道。',
+    identityProvider: '您的身分提供者',
+    authTitle: '驗證',
+    authNeedsOauth: provider => `測試此閘道前請先使用 ${provider} 登入。`,
+    authSignedIn: '瀏覽器登入已完成。',
+    connected: '已連線',
+    signIn: '登入',
+    signInWith: provider => `使用 ${provider} 登入`,
+    enterUrlFirst: '請先輸入閘道 URL。',
+    signInIncomplete: '驗證完成前登入視窗已關閉。',
+    tokenTitle: '工作階段權杖',
+    tokenDesc: '貼上遠端閘道 .env 檔案中的工作階段權杖。',
+    pasteSessionToken: '貼上工作階段權杖',
+    incompleteSignInTest: '測試此受 OAuth 保護的閘道前請先登入。',
+    incompleteTokenTest: '測試此閘道前請輸入工作階段權杖。',
+    testConnection: '測試連線',
+    testSucceeded: (baseUrl, version) => `已連線到 ${baseUrl}${version ? ` (${version})` : ''}。`,
+    applyRemote: '套用並重新連線',
+    backToSetup: '返回',
     failedTitle: '安裝失敗',
     settingUpTitle: '正在設定 Hermes Agent',
     finishingTitle: '正在收尾',
@@ -2040,8 +2107,7 @@ export const zhHant = defineLocale({
       noModels: '找不到模型',
       editModels: '編輯模型…',
       refreshModels: '重新整理模型',
-      fast: '快速',
-      medium: '中'
+      fast: '快速'
     },
     modelOptions: {
       noOptions: '此模型沒有可用選項',
@@ -2453,6 +2519,7 @@ export const zhHant = defineLocale({
         execute_code: { done: '已執行程式碼', pending: '正在撰寫腳本', pendingAction: '正在撰寫腳本' },
         image_generate: { done: '已生成圖片', pending: '正在生成圖片', pendingAction: '正在生成' },
         list_files: { done: '已列出檔案', pending: '正在列出檔案', pendingAction: '正在列出' },
+        memory: { done: '已儲存至記憶', pending: '正在儲存至記憶', pendingAction: '正在儲存' },
         patch: { done: '已修補檔案', pending: '正在修補檔案', pendingAction: '正在修補' },
         read_file: { done: '已讀取檔案', pending: '正在讀取檔案', pendingAction: '正在讀取' },
         search_files: { done: '已搜尋檔案', pending: '正在搜尋檔案', pendingAction: '正在搜尋' },
diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts
index 297d5156f2a..a7a9ec409e7 100644
--- a/apps/desktop/src/i18n/zh.ts
+++ b/apps/desktop/src/i18n/zh.ts
@@ -782,12 +782,14 @@ export const zh: Translations = {
       appliesTo: '应用于',
       allProfiles: '所有 profile',
       defaultConnection: '默认连接会用于所有没有自定义覆盖的 profile。',
-      profileConnection: profile => `仅当“${profile}”是当前 profile 时使用此连接。设为本地即可继承默认连接。`,
+      profileConnection: profile => `仅当“${profile}”是当前 profile 时使用此连接。选择“使用默认网关”可移除其覆盖。`,
       envOverrideTitle: '环境变量正在控制此桌面会话。',
       envOverrideDesc: '取消设置 HERMES_DESKTOP_REMOTE_URL 和 HERMES_DESKTOP_REMOTE_TOKEN 后才会使用下面保存的设置。',
       modeTitle: '连接模式',
       localTitle: '本地网关',
       localDesc: '在 localhost 启动私有 Hermes 后端。这是默认方式，并且可离线工作。',
+      inheritTitle: '使用默认网关',
+      inheritDesc: '移除此 profile 的自定义覆盖并使用默认连接。',
       remoteTitle: '远程网关',
       remoteDesc: '将此桌面外壳连接到远程 Hermes 后端。',
       remoteAuthHint: '托管网关使用 OAuth 或用户名密码；自托管网关也可能使用会话 token。',
@@ -1042,6 +1044,12 @@ export const zh: Translations = {
       messages: count => `${count} 条消息`,
       restored: '已恢复',
       deleteConfirm: title => `永久删除“${title}”？此操作无法撤销。`,
+      autoArchiveTitle: '自动归档闲置会话',
+      autoArchiveDesc:
+        '自动归档你一段时间未使用的会话。已置顶的会话永远不会被归档，也不会删除任何内容——归档的会话会移动到这里。',
+      autoArchiveDaysLabel: '归档前',
+      autoArchiveDaysUnit: '天无活动',
+      autoArchiveFailed: '无法更新自动归档设置',
       defaultDirTitle: '默认项目目录',
       defaultDirDesc: '新会话默认从此文件夹开始，除非你选择其他目录。留空则使用你的 home 目录。',
       defaultDirUpdated: '默认项目目录已更新',
@@ -1608,6 +1616,72 @@ export const zh: Translations = {
     }
   },
 
+  webhooks: {
+    search: '搜索 Webhook…',
+    loading: '正在加载 Webhook…',
+    loadFailed: 'Webhook 加载失败',
+    subscriptions: (count: number) => `订阅（${count}）`,
+    hint: '接收器运行后，订阅更改会热重载。已禁用的订阅会拒绝传入事件。',
+    empty: '暂无 Webhook 订阅。',
+    disabledTitle: 'Webhook 接收器已禁用',
+    disabledBody:
+      'Webhook 是独立的网关平台。在此启用以接受传入的 HTTP 事件；仅当订阅投递到 Telegram、Discord、Slack 或其他渠道时才需要聊天渠道。',
+    enable: '启用 Webhook',
+    enabling: '正在启用…',
+    enabled: (name: string) => `已启用：“${name}”`,
+    disabled: (name: string) => `已禁用：“${name}”`,
+    enableRow: '启用',
+    disableRow: '禁用',
+    delete: '删除',
+    deleting: '删除中…',
+    deleted: 'Webhook 已删除',
+    deleteTitle: '删除 Webhook',
+    deleteDescPrefix: '这将永久移除 ',
+    deleteDescSuffix: '。此操作无法撤销。',
+    deleteFailed: (name: string) => `删除“${name}”失败`,
+    toggleFailed: (name: string) => `更新“${name}”失败`,
+    newSubscription: '新建订阅',
+    restarting: '网关正在重启…',
+    restartNeeded: 'Webhook 已启用，但网关仍需重启后接收器才能上线。',
+    restartGateway: '重启网关',
+    restartingGateway: '正在重启…',
+    restartFailed: (detail: string) => `网关重启失败${detail}`,
+    enabledRestarting: 'Webhook 已启用；网关正在重启…',
+    all: '（全部）',
+    deliverOnly: '仅投递',
+    createdTitle: '订阅已创建',
+    createdSecretHint: '请立即复制密钥 —— 它只显示一次。',
+    webhookUrl: 'Webhook URL',
+    secretOnce: '密钥（仅显示一次）',
+    done: '完成',
+    fieldName: '名称',
+    fieldNamePlaceholder: '例如 github-push',
+    fieldDescription: '描述',
+    fieldDescriptionPlaceholder: '此 Webhook 的用途（可选）',
+    fieldEvents: '事件',
+    fieldEventsPlaceholder: '以逗号分隔，留空表示全部',
+    fieldSkills: '技能',
+    fieldSkillsPlaceholder: '以逗号分隔的技能名称（可选）',
+    fieldDeliver: '投递到',
+    fieldDeliverOnly: '仅投递载荷',
+    fieldPrompt: '提示词',
+    fieldPromptPlaceholder: '此 Webhook 触发时给智能体的说明（可选）',
+    nameRequired: '需要名称',
+    create: '创建',
+    creating: '正在创建…',
+    created: '已创建',
+    createFailed: (detail: string) => `创建失败：${detail}`,
+    copy: '复制',
+    deliverOptions: {
+      log: '日志',
+      telegram: 'Telegram',
+      discord: 'Discord',
+      slack: 'Slack',
+      email: '电子邮件',
+      github_comment: 'GitHub 评论'
+    }
+  },
+
   profiles: {
     close: '关闭配置档案',
     nameHint: '小写字母、数字、连字符和下划线。必须以字母或数字开头。',
@@ -1788,6 +1862,7 @@ export const zh: Translations = {
     promptPlaceholder: '总结我未读的 Slack 话题，并把前 5 条邮件发给我…',
     frequencyLabel: '频率',
     deliverLabel: '投递至',
+    deliverNeedsHomeChannel: '请先设置主频道',
     modelLabel: '模型',
     modelDefault: '默认（全局模型）',
     customScheduleLabel: '自定义排程',
@@ -1799,7 +1874,25 @@ export const zh: Translations = {
     scheduleRequired: '排程为必填项。',
     scriptOnlyEditHint: '仅脚本任务（无 AI 提示词）。任务 ID：',
     saveChanges: '保存更改',
-    createAction: '创建定时任务'
+    createAction: '创建定时任务',
+    tabs: {
+      jobs: '任务',
+      blueprints: '蓝图'
+    },
+    blueprints: {
+      tab: '蓝图',
+      startFrom: '从此开始',
+      custom: '自定义',
+      subtitle: '现成的自动化',
+      dialogDesc: '填写详细信息并进行排程。',
+      scheduleIt: '安排任务',
+      scheduling: '安排中...',
+      scheduled: '蓝图已安排',
+      loading: '正在加载蓝图...',
+      failedLoad: '加载蓝图失败',
+      emptyTitle: '没有可用的蓝图',
+      emptyDesc: '此后端上没有可用的自动化蓝图。'
+    }
   },
 
   artifacts: {
@@ -1962,6 +2055,13 @@ export const zh: Translations = {
       ageDay: '天',
       ageHour: '时',
       ageMin: '分'
+    },
+    dateDivider: {
+      today: '今天早些时候',
+      yesterday: '昨天',
+      thisWeek: '本周',
+      lastWeek: '上周',
+      thisMonth: '本月'
     }
   },
 
@@ -2228,6 +2328,39 @@ export const zh: Translations = {
     viewDocs: '查看安装文档',
     installTo: '将安装到',
     retryAfterRun: '我已运行 -- 重试',
+    setupChoiceTitle: '设置 Hermes Desktop',
+    setupChoiceDesc: '将此应用连接到你已运行的 Hermes 网关，或在这台电脑上本地安装 Hermes。',
+    connectExistingTitle: '连接到现有 Hermes',
+    connectExistingShort: '连接现有环境',
+    connectExistingDesc: '使用会话令牌或浏览器登录连接远程后端。不会启动本地安装。',
+    installLocalTitle: '本地安装 Hermes',
+    installLocalDesc: '下载 Hermes，创建 Python 环境，并在这台电脑上运行后端。',
+    localStartUnavailable: '无法启动本地安装。请重启 Hermes Desktop 后重试。',
+    remoteSetupTitle: '连接到现有 Hermes',
+    remoteSetupDesc: '输入网关 URL。Hermes Desktop 会检测需要令牌还是浏览器登录。',
+    remoteUrlTitle: '网关 URL',
+    remoteUrlDesc: '使用 Hermes 网关的基础 URL；远程地址请包含 https://。',
+    remoteUrlPlaceholder: 'https://gateway.example.com/hermes',
+    probing: '正在检测网关认证方式...',
+    probeError: '无法连接到该 Hermes 网关。',
+    identityProvider: '你的身份提供方',
+    authTitle: '认证',
+    authNeedsOauth: provider => `测试此网关前请先使用 ${provider} 登录。`,
+    authSignedIn: '浏览器登录已完成。',
+    connected: '已连接',
+    signIn: '登录',
+    signInWith: provider => `使用 ${provider} 登录`,
+    enterUrlFirst: '请先输入网关 URL。',
+    signInIncomplete: '认证完成前登录窗口已关闭。',
+    tokenTitle: '会话令牌',
+    tokenDesc: '粘贴远程网关 .env 文件中的会话令牌。',
+    pasteSessionToken: '粘贴会话令牌',
+    incompleteSignInTest: '测试此受 OAuth 保护的网关前请先登录。',
+    incompleteTokenTest: '测试此网关前请输入会话令牌。',
+    testConnection: '测试连接',
+    testSucceeded: (baseUrl, version) => `已连接到 ${baseUrl}${version ? ` (${version})` : ''}。`,
+    applyRemote: '应用并重新连接',
+    backToSetup: '返回',
     failedTitle: '安装失败',
     settingUpTitle: '正在设置 Hermes Agent',
     finishingTitle: '正在收尾',
@@ -2352,8 +2485,7 @@ export const zh: Translations = {
       noModels: '未找到模型',
       editModels: '编辑模型…',
       refreshModels: '刷新模型',
-      fast: '快速',
-      medium: '中'
+      fast: '快速'
     },
     modelOptions: {
       noOptions: '此模型没有可用选项',
@@ -2434,6 +2566,8 @@ export const zh: Translations = {
       running: count => `${count} 个运行中`,
       cron: '排程',
       openCron: '打开排程任务',
+      webhooks: 'Webhook',
+      openWebhooks: '打开 Webhook',
       starmap: '记忆图谱',
       openStarmap: '打开记忆图谱',
       turnRunning: '运行中',
@@ -2770,6 +2904,7 @@ export const zh: Translations = {
         execute_code: { done: '已运行代码', pending: '正在编写脚本', pendingAction: '正在编写脚本' },
         image_generate: { done: '已生成图片', pending: '正在生成图片', pendingAction: '正在生成' },
         list_files: { done: '已列出文件', pending: '正在列出文件', pendingAction: '正在列出' },
+        memory: { done: '已保存到记忆', pending: '正在保存到记忆', pendingAction: '正在保存' },
         patch: { done: '已修补文件', pending: '正在修补文件', pendingAction: '正在修补' },
         read_file: { done: '已读取文件', pending: '正在读取文件', pendingAction: '正在读取' },
         search_files: { done: '已搜索文件', pending: '正在搜索文件', pendingAction: '正在搜索' },
diff --git a/apps/desktop/src/lib/chat-messages.test.ts b/apps/desktop/src/lib/chat-messages.test.ts
index e86ba5593ec..6ddabbe9b38 100644
--- a/apps/desktop/src/lib/chat-messages.test.ts
+++ b/apps/desktop/src/lib/chat-messages.test.ts
@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest'
 
+import type { SessionMessage } from '@/types/hermes'
+
 import type { ChatMessage, ChatMessagePart } from './chat-messages'
 import {
   appendAssistantTextPart,
@@ -131,6 +133,65 @@ describe('toChatMessages', () => {
     expect(chatMessageText(message)).toBe('Here you go.')
   })
 
+  it('lifts @image directive lines into attachmentRefs instead of inline text', () => {
+    const [message] = toChatMessages([
+      {
+        role: 'user',
+        content: '@image:/tmp/cat.png\nwhat is in this photo?',
+        timestamp: 1
+      }
+    ])
+
+    expect(chatMessageText(message)).toBe('what is in this photo?')
+    expect((message as { attachmentRefs?: string[] }).attachmentRefs).toEqual(['@image:/tmp/cat.png'])
+  })
+
+  it('keeps a user turn that carried only an attached image (no caption)', () => {
+    const [message] = toChatMessages([
+      {
+        role: 'user',
+        content: '@image:/tmp/cat.png',
+        timestamp: 1
+      }
+    ])
+
+    // The bubble has no visible text, but must survive the empty-turn filter
+    // because it carries attachment refs — otherwise a stand-alone attachment
+    // vanishes from the transcript after a session switch / restart.
+    expect(chatMessageText(message)).toBe('')
+    expect((message as { attachmentRefs?: string[] }).attachmentRefs).toEqual(['@image:/tmp/cat.png'])
+  })
+
+  it('renders a native-vision turn as caption plus thumbnail, not raw placeholder text', () => {
+    // How a turn sent to a natively-vision-capable model comes back out of the
+    // session store: a backtick-quoted ref (the path has spaces) and the
+    // `[screenshot]` stand-in left by flattening the parts list.
+    const ref = '@image:`/Users/me/Library/Application Support/Hermes/composer-images/a.png`'
+
+    const [message] = toChatMessages([
+      {
+        role: 'user',
+        content: `${ref}\nwhat is in this photo?\n[screenshot]`,
+        timestamp: 1
+      }
+    ])
+
+    expect(chatMessageText(message)).toBe('what is in this photo?')
+    expect((message as { attachmentRefs?: string[] }).attachmentRefs).toEqual([ref])
+  })
+
+  it('leaves a plain user prompt without attachment refs untouched', () => {
+    const [message] = toChatMessages([
+      {
+        role: 'user',
+        content: 'just a question',
+        timestamp: 1
+      }
+    ])
+
+    expect((message as { attachmentRefs?: string[] }).attachmentRefs).toBeUndefined()
+  })
+
   it('coerces non-string message content without throwing', () => {
     const [message] = toChatMessages([
       {
@@ -180,17 +241,48 @@ describe('toChatMessages', () => {
         content: 'opaque delegation context payload',
         display_kind: 'async_delegation_complete',
         timestamp: 5
+      },
+      {
+        role: 'user',
+        content: '[System note: Your previous turn was interrupted mid-run…]\n\noriginal prompt',
+        display_kind: 'auto_continue',
+        timestamp: 6
       }
     ])
 
-    expect(messages.map(message => message.role)).toEqual(['user', 'assistant', 'system', 'system'])
+    expect(messages.map(message => message.role)).toEqual(['user', 'assistant', 'system', 'system', 'system'])
     expect(messages.map(chatMessageText)).toEqual([
       'real user turn',
       'real assistant reply',
       'model changed',
-      'background agent work finished'
+      'background agent work finished',
+      'resumed interrupted turn'
     ])
   })
+
+  // A backend older than this app serves display_metadata as unparsed JSON
+  // text. Indexing into that string used to throw and fail the whole resume.
+  it.each([
+    ['an object', { delegation_id: 'deleg_1', task_count: 2 }, '2 background agents finished'],
+    ['JSON text', JSON.stringify({ delegation_id: 'deleg_1', task_count: 1 }), '1 background agent finished'],
+    ['unparseable text', '{not-json', 'background agent work finished'],
+    ['text that is not an object', '"deleg_1"', 'background agent work finished'],
+    ['a missing task count', { delegation_id: 'deleg_1' }, 'background agent work finished']
+  ])('labels a delegation event given %s', (_case, displayMetadata, expected) => {
+    const read = () =>
+      toChatMessages([
+        {
+          role: 'user',
+          content: 'opaque delegation context payload',
+          display_kind: 'async_delegation_complete',
+          display_metadata: displayMetadata as SessionMessage['display_metadata'],
+          timestamp: 1
+        }
+      ])
+
+    expect(read).not.toThrow()
+    expect(chatMessageText(read()[0])).toBe(expected)
+  })
 })
 
 describe('renderMediaTags', () => {
diff --git a/apps/desktop/src/lib/chat-messages.ts b/apps/desktop/src/lib/chat-messages.ts
index 00d1c73a64d..f0d8e2b7c64 100644
--- a/apps/desktop/src/lib/chat-messages.ts
+++ b/apps/desktop/src/lib/chat-messages.ts
@@ -1,6 +1,7 @@
 import type { ThreadMessageLike } from '@assistant-ui/react'
 import type { BillingBlock } from '@hermes/shared'
 
+import { extractImageRefs } from '@/lib/embedded-images'
 import { dedupeGeneratedImageEchoesInParts } from '@/lib/generated-images'
 import { mediaDisplayLabel, mediaMarkdownHref } from '@/lib/media'
 import { normalize } from '@/lib/text'
@@ -94,9 +95,19 @@ export type GatewayEventPayload = {
   label?: string
   index?: number
   aggregator?: string
+  // moa.progress / moa.phase (Mixture of Agents fan-out progress relay)
+  refs_done?: number
+  refs_total?: number
+  phase?: string
   // message.complete — signals the final text was already previewed via
   // interim_assistant_callback, so the UI can settle instead of duplicating.
   response_previewed?: boolean
+  // message.complete with status "error" — `text` is streamed partial output
+  // (keep it visible), not the error string.
+  partial?: boolean
+  // message.complete with status "error" — the failed turn was retained
+  // backend-side and will replay through session.resume's inflight payload.
+  recoverable?: boolean
   // Structured billing wall forwarded on message.complete when a turn fails
   // with FailoverReason.billing (shape mirrors @hermes/shared BillingBlock).
   billing?: BillingBlock
@@ -307,16 +318,39 @@ function transcriptContent(displayKind: SessionMessage['display_kind'], content:
   return displayKind === 'hidden' ? null : content
 }
 
+// A remote backend older than this app serves display_metadata as raw JSON text,
+// and `in` throws on a primitive — which used to fail the whole session resume.
+function timelineTaskCount(metadata: SessionMessage['display_metadata']): number | undefined {
+  let parsed: unknown = metadata
+
+  if (typeof parsed === 'string') {
+    try {
+      parsed = JSON.parse(parsed)
+    } catch {
+      return undefined
+    }
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    return undefined
+  }
+
+  const count = (parsed as { task_count?: unknown }).task_count
+
+  return typeof count === 'number' ? count : undefined
+}
+
 function timelineDisplayContent(message: SessionMessage, content: string): string {
   if (message.display_kind === 'model_switch') {
     return 'model changed'
   }
 
+  if (message.display_kind === 'auto_continue') {
+    return 'resumed interrupted turn'
+  }
+
   if (message.display_kind === 'async_delegation_complete') {
-    const count =
-      message.display_metadata && 'task_count' in message.display_metadata
-        ? message.display_metadata.task_count
-        : undefined
+    const count = timelineTaskCount(message.display_metadata)
 
     return count === undefined
       ? 'background agent work finished'
@@ -908,16 +942,29 @@ export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
 
     const content = message.content || message.text || message.context || message.name
 
-    const displayContent = transcriptContent(
+    const rawDisplayContent = transcriptContent(
       message.display_kind,
       timelineDisplayContent(message, displayContentForMessage(message.role, content))
     )
 
     const displayRole =
-      message.display_kind === 'model_switch' || message.display_kind === 'async_delegation_complete'
+      message.display_kind === 'model_switch' ||
+      message.display_kind === 'async_delegation_complete' ||
+      message.display_kind === 'auto_continue'
         ? 'system'
         : message.role
 
+    // Persisted user turns carry `@image:<path>` directive lines inline in
+    // the text (see tui_gateway/server.py's persist-time rewrite). The
+    // read-only bubble clamps its body to ~2 lines, and a large inline image
+    // thumbnail pushes any caption text below the clamp's visible area — so
+    // pull image refs out into `attachmentRefs` (same shape the local
+    // optimistic composer already uses) and render them via the dedicated
+    // attachments row below the bubble instead.
+    const imageRefExtraction = displayRole === 'user' && rawDisplayContent ? extractImageRefs(rawDisplayContent) : null
+    const displayContent = imageRefExtraction ? imageRefExtraction.cleanedText : rawDisplayContent
+    const extractedAttachmentRefs = imageRefExtraction?.refs.length ? imageRefExtraction.refs : undefined
+
     const parts: ChatMessagePart[] = []
 
     const reasoning =
@@ -937,7 +984,7 @@ export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
       parts.push(...message.tool_calls.map((call, callIndex) => toolPartFromStoredCall(call, callIndex)))
     }
 
-    if (!parts.length) {
+    if (!parts.length && !extractedAttachmentRefs?.length) {
       if (message.role !== 'assistant') {
         flushPendingTools(index)
         activeAssistantIndex = null
@@ -987,7 +1034,8 @@ export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
       id: `${message.timestamp || Date.now()}-${index}-${displayRole}`,
       role: displayRole,
       parts,
-      timestamp: message.timestamp
+      timestamp: message.timestamp,
+      ...(extractedAttachmentRefs ? { attachmentRefs: extractedAttachmentRefs } : {})
     })
 
     activeAssistantIndex = message.role === 'assistant' ? result.length - 1 : null
@@ -999,7 +1047,9 @@ export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
   )
 
   return withUniqueToolCallIds(
-    withoutGeneratedImageEchoes.filter(m => chatMessageText(m).trim() || m.parts.some(part => part.type !== 'text'))
+    withoutGeneratedImageEchoes.filter(
+      m => chatMessageText(m).trim() || m.parts.some(part => part.type !== 'text') || m.attachmentRefs?.length
+    )
   )
 }
 
diff --git a/apps/desktop/src/lib/chat-runtime.test.ts b/apps/desktop/src/lib/chat-runtime.test.ts
index b3d4e638537..46ce1da9219 100644
--- a/apps/desktop/src/lib/chat-runtime.test.ts
+++ b/apps/desktop/src/lib/chat-runtime.test.ts
@@ -4,6 +4,7 @@ import type { ComposerAttachment } from '@/store/composer'
 
 import {
   attachmentDisplayText,
+  attachmentId,
   coerceThinkingText,
   optimisticAttachmentRef,
   parseCommandDispatch,
@@ -150,3 +151,30 @@ describe('parseSlashCommand', () => {
     expect(parseSlashCommand('/ some words')).toEqual({ arg: '', name: '' })
   })
 })
+
+describe('attachmentId', () => {
+  it('normalizes a trailing slash on a url so a re-attach dedupes (#59305 P2)', () => {
+    expect(attachmentId('url', 'https://example.com/a')).toBe(attachmentId('url', 'https://example.com/a/'))
+  })
+
+  it('falls back to the trimmed raw value for a malformed url instead of throwing', () => {
+    expect(() => attachmentId('url', 'not a url')).not.toThrow()
+    expect(attachmentId('url', '  not a url  ')).toBe(attachmentId('url', 'not a url'))
+  })
+
+  it('normalizes backslash path separators so a Windows and posix path dedupe', () => {
+    expect(attachmentId('file', 'a\\b.ts')).toBe(attachmentId('file', 'a/b.ts'))
+  })
+
+  it('normalizes a trailing slash on a folder path', () => {
+    expect(attachmentId('folder', 'src/app/')).toBe(attachmentId('folder', 'src/app'))
+  })
+
+  it('does not collapse a bare root path to an empty id', () => {
+    expect(attachmentId('folder', '/')).toBe('folder:/')
+  })
+
+  it('keeps distinct urls distinct', () => {
+    expect(attachmentId('url', 'https://example.com/a')).not.toBe(attachmentId('url', 'https://example.com/b'))
+  })
+})
diff --git a/apps/desktop/src/lib/chat-runtime.ts b/apps/desktop/src/lib/chat-runtime.ts
index d2cacf87600..b392d2692a3 100644
--- a/apps/desktop/src/lib/chat-runtime.ts
+++ b/apps/desktop/src/lib/chat-runtime.ts
@@ -149,8 +149,37 @@ export function contextPath(path: string, cwd: string): string {
   return path.startsWith(normalizedCwd) ? path.slice(normalizedCwd.length) : path
 }
 
+// IDs are content-derived (`kind:value`), not uuids, so upsertAttachment's
+// exact-match dedupe only catches a re-attach when the raw value matches
+// byte-for-byte. Normalize the value first so a trailing slash, a `\` path
+// separator, etc. don't slip past dedupe as a "different" attachment.
+function normalizeAttachmentValue(kind: ComposerAttachment['kind'], value: string): string {
+  const trimmed = value.trim()
+
+  if (kind === 'url') {
+    try {
+      // The WHATWG URL parser only collapses an EMPTY path to '/' (bare
+      // origin) — it does not treat '/a' and '/a/' as equivalent, so strip a
+      // trailing slash ourselves once the URL is otherwise canonicalized
+      // (scheme/host case, default ports, etc.).
+      return new URL(trimmed).toString().replace(/\/+$/, '')
+    } catch {
+      return trimmed
+    }
+  }
+
+  if (kind === 'file' || kind === 'folder' || kind === 'image') {
+    const posix = trimmed.replace(/\\/g, '/')
+
+    // Don't collapse a bare root ('/' or 'C:/') down to an empty string.
+    return posix.length > 1 ? posix.replace(/\/+$/, '') : posix
+  }
+
+  return trimmed
+}
+
 export function attachmentId(kind: ComposerAttachment['kind'], value: string): string {
-  return `${kind}:${value}`
+  return `${kind}:${normalizeAttachmentValue(kind, value)}`
 }
 
 export function pathLabel(path: string): string {
diff --git a/apps/desktop/src/lib/desktop-remote-auth.test.ts b/apps/desktop/src/lib/desktop-remote-auth.test.ts
new file mode 100644
index 00000000000..f5752f0f073
--- /dev/null
+++ b/apps/desktop/src/lib/desktop-remote-auth.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+
+import { deriveRemoteAuthProviderShape } from './desktop-remote-auth'
+
+describe('deriveRemoteAuthProviderShape', () => {
+  it('uses fallback copy when the gateway has not reported providers', () => {
+    expect(deriveRemoteAuthProviderShape(null)).toEqual({
+      isPassword: false,
+      providerLabel: 'your identity provider'
+    })
+    expect(deriveRemoteAuthProviderShape([], 'the configured gateway')).toEqual({
+      isPassword: false,
+      providerLabel: 'the configured gateway'
+    })
+  })
+
+  it('marks providers as password-style only when every provider supports password login', () => {
+    expect(
+      deriveRemoteAuthProviderShape([{ name: 'basic', displayName: 'Username & Password', supportsPassword: true }])
+    ).toEqual({
+      isPassword: true,
+      providerLabel: 'Username & Password'
+    })
+  })
+
+  it('keeps OAuth copy for redirect providers and mixed deployments', () => {
+    expect(
+      deriveRemoteAuthProviderShape([{ name: 'nous', displayName: 'Nous Research', supportsPassword: false }])
+    ).toEqual({
+      isPassword: false,
+      providerLabel: 'Nous Research'
+    })
+
+    expect(
+      deriveRemoteAuthProviderShape([
+        { name: 'basic', displayName: 'Username & Password', supportsPassword: true },
+        { name: 'nous', displayName: 'Nous Research', supportsPassword: false }
+      ])
+    ).toEqual({
+      isPassword: false,
+      providerLabel: 'Username & Password / Nous Research'
+    })
+  })
+
+  it('falls back to provider names when display names are missing', () => {
+    expect(deriveRemoteAuthProviderShape([{ name: 'basic', displayName: '', supportsPassword: true }])).toEqual({
+      isPassword: true,
+      providerLabel: 'basic'
+    })
+  })
+})
diff --git a/apps/desktop/src/lib/desktop-remote-auth.ts b/apps/desktop/src/lib/desktop-remote-auth.ts
new file mode 100644
index 00000000000..5616c81e658
--- /dev/null
+++ b/apps/desktop/src/lib/desktop-remote-auth.ts
@@ -0,0 +1,26 @@
+import type { DesktopAuthProvider } from '@/global'
+
+export interface RemoteAuthProviderShape {
+  isPassword: boolean
+  providerLabel: string
+}
+
+function providerDisplayName(provider: DesktopAuthProvider): string {
+  return provider.displayName || provider.name
+}
+
+export function deriveRemoteAuthProviderShape(
+  providers: DesktopAuthProvider[] | null | undefined,
+  fallback = 'your identity provider'
+): RemoteAuthProviderShape {
+  const list = providers ?? []
+
+  if (list.length === 0) {
+    return { isPassword: false, providerLabel: fallback }
+  }
+
+  return {
+    isPassword: list.every(provider => Boolean(provider.supportsPassword)),
+    providerLabel: list.map(providerDisplayName).join(' / ')
+  }
+}
diff --git a/apps/desktop/src/lib/desktop-slash-commands.test.ts b/apps/desktop/src/lib/desktop-slash-commands.test.ts
index cbca758e7e6..efb16453479 100644
--- a/apps/desktop/src/lib/desktop-slash-commands.test.ts
+++ b/apps/desktop/src/lib/desktop-slash-commands.test.ts
@@ -141,6 +141,14 @@ describe('desktop slash command curation', () => {
     }
   })
 
+  it('keeps /goal arg text editable instead of sealing it into a chip', () => {
+    // /goal takes free prose (the goal itself) plus subcommands. Without
+    // args:true, Space after the command name committed a sealed directive
+    // chip and the goal text rendered awkwardly after a pill.
+    expect(resolveDesktopCommand('/goal')?.surface).toEqual({ kind: 'exec' })
+    expect(resolveDesktopCommand('/goal')?.args).toBe(true)
+  })
+
   it('routes /journey (and aliases) to the memory graph overlay action', () => {
     expect(resolveDesktopCommand('/journey')?.surface).toEqual({ kind: 'action', action: 'journey' })
     expect(resolveDesktopCommand('/memory-graph')?.surface).toEqual({ kind: 'action', action: 'journey' })
diff --git a/apps/desktop/src/lib/desktop-slash-commands.ts b/apps/desktop/src/lib/desktop-slash-commands.ts
index 22ae4e590e4..399479242f6 100644
--- a/apps/desktop/src/lib/desktop-slash-commands.ts
+++ b/apps/desktop/src/lib/desktop-slash-commands.ts
@@ -209,7 +209,7 @@ const DESKTOP_COMMAND_SPECS: readonly DesktopCommandSpec[] = [
     args: true
   },
   { name: '/debug', description: 'Create a debug report', surface: exec() },
-  { name: '/goal', description: 'Manage the standing goal for this session', surface: exec() },
+  { name: '/goal', description: 'Manage the standing goal for this session', surface: exec(), args: true },
   { name: '/personality', description: 'Switch personality for this session', surface: exec(), args: true },
   {
     name: '/pet',
diff --git a/apps/desktop/src/lib/embedded-images.test.ts b/apps/desktop/src/lib/embedded-images.test.ts
index c51742783b0..7d6a0b75e82 100644
--- a/apps/desktop/src/lib/embedded-images.test.ts
+++ b/apps/desktop/src/lib/embedded-images.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { extractEmbeddedImages } from './embedded-images'
+import { extractEmbeddedImages, extractImageRefs, textWithoutImageRefs } from './embedded-images'
 
 const SAMPLE_PNG_DATA_URL = 'data:image/png;base64,' + 'A'.repeat(120)
 
@@ -42,3 +42,72 @@ describe('extractEmbeddedImages', () => {
     expect(result.images[0]).toHaveLength(hugeDataUrl.length)
   })
 })
+
+describe('textWithoutImageRefs', () => {
+  it('leaves plain text untouched', () => {
+    expect(textWithoutImageRefs('just a question')).toBe('just a question')
+  })
+
+  it('strips a single leading @image directive line', () => {
+    expect(textWithoutImageRefs('@image:/tmp/cat.png\nwhat is this?')).toBe('what is this?')
+  })
+
+  it('strips multiple @image directive lines and trims', () => {
+    const input = '@image:/tmp/a.png\n@image:/tmp/b.png\n  describe both  '
+
+    expect(textWithoutImageRefs(input)).toBe('describe both')
+  })
+
+  it('does not treat an inline @image mention as a directive line', () => {
+    // Only full-line leading directives are stripped, matching the gateway's
+    // persist-time rewrite. A bare mention mid-prose is preserved.
+    expect(textWithoutImageRefs('see @image:/tmp/cat.png here')).toBe('see @image:/tmp/cat.png here')
+  })
+})
+
+describe('extractImageRefs', () => {
+  it('returns the text untouched and no refs when there are no directives', () => {
+    expect(extractImageRefs('a normal prompt')).toEqual({ cleanedText: 'a normal prompt', refs: [] })
+  })
+
+  it('lifts leading @image directive lines into refs and clears the text', () => {
+    const result = extractImageRefs('@image:/tmp/cat.png\nwhat do you see?')
+
+    expect(result).toEqual({ cleanedText: 'what do you see?', refs: ['@image:/tmp/cat.png'] })
+  })
+
+  it('collects multiple refs in order', () => {
+    const result = extractImageRefs('@image:/tmp/a.png\n@image:/tmp/b.png\ncompare them')
+
+    expect(result.cleanedText).toBe('compare them')
+    expect(result.refs).toEqual(['@image:/tmp/a.png', '@image:/tmp/b.png'])
+  })
+
+  it('keeps only the directive lines when there is no trailing text', () => {
+    const result = extractImageRefs('@image:/tmp/only.png')
+
+    expect(result).toEqual({ cleanedText: '', refs: ['@image:/tmp/only.png'] })
+  })
+
+  it('lifts a backtick-quoted ref so a path with spaces survives intact', () => {
+    const ref = '@image:`/Users/me/Library/Application Support/Hermes/composer-images/a.png`'
+    const result = extractImageRefs(`${ref}\nwhat is this?`)
+
+    expect(result).toEqual({ cleanedText: 'what is this?', refs: [ref] })
+  })
+
+  it('drops the [screenshot] placeholder a native-vision turn leaves behind', () => {
+    // Flattening a parts list replaces each image part with `[screenshot]`; the
+    // lifted ref already renders that same attachment.
+    const result = extractImageRefs('@image:/tmp/cat.png\nwhat is in this photo?\n[screenshot]')
+
+    expect(result).toEqual({ cleanedText: 'what is in this photo?', refs: ['@image:/tmp/cat.png'] })
+  })
+
+  it('keeps [screenshot] when the message carries no image refs', () => {
+    expect(extractImageRefs('[screenshot]\nlook at the attached capture')).toEqual({
+      cleanedText: '[screenshot]\nlook at the attached capture',
+      refs: []
+    })
+  })
+})
diff --git a/apps/desktop/src/lib/embedded-images.ts b/apps/desktop/src/lib/embedded-images.ts
index 9b75eeae140..144a602091e 100644
--- a/apps/desktop/src/lib/embedded-images.ts
+++ b/apps/desktop/src/lib/embedded-images.ts
@@ -160,3 +160,50 @@ export function embeddedImageUrls(text: string): string[] {
 export function textWithoutEmbeddedImages(text: string): string {
   return extractEmbeddedImages(text).cleanedText
 }
+
+// The gateway persists attached images as `@image:<path>` directive lines
+// (see tui_gateway/server.py's persist-time rewrite), prepended before the
+// user's own text. The composer's own optimistic/local turn never carries
+// this prefix — it keeps the attachment as separate `attachmentRefs`
+// metadata, not inline text. Comparing raw chatMessageText between the
+// optimistic turn and the authoritative (persisted) turn therefore always
+// mismatches whenever an image was attached, which defeats the "is this the
+// same turn" checks in preserveLocalPendingTurnMessages / appendLiveSessionProjection
+// and re-appends the optimistic row as if it were a distinct, unconfirmed
+// turn — a duplicated user bubble. Strip the directive line(s) before any
+// such equality comparison so both sides reduce to the same visible text.
+const IMAGE_REF_LINE_RE = /^@image:[^\n]*\n?/gm
+
+export function textWithoutImageRefs(text: string): string {
+  return text.replace(IMAGE_REF_LINE_RE, '').trim()
+}
+
+// Same directive lines as textWithoutImageRefs, but keeps them instead of
+// discarding — used when converting persisted server messages into
+// ChatMessage/ThreadMessageLike shape, where `@image:<path>` refs need to
+// move from inline text into the `attachmentRefs` metadata field (mirroring
+// how the local optimistic composer represents attachments) rather than stay
+// embedded in the bubble's clamped text body, where a large inline thumbnail
+// pushes the caption text out of the clamp's visible area.
+// Native-vision turns are stored as a parts list, which the session store
+// flattens by replacing each image part with a literal `[screenshot]` line. The
+// `@image:` ref describes that same attachment, so keeping both renders the
+// placeholder as stray text under the thumbnail. Drop it only when a ref was
+// actually lifted, so a `[screenshot]` in a message without attachments stays.
+const SCREENSHOT_PLACEHOLDER_LINE_RE = /^\[screenshot\]\n?/gm
+
+export function extractImageRefs(text: string): { cleanedText: string; refs: string[] } {
+  const refs: string[] = []
+
+  let cleanedText = text.replace(IMAGE_REF_LINE_RE, match => {
+    refs.push(match.trim())
+
+    return ''
+  })
+
+  if (refs.length) {
+    cleanedText = cleanedText.replace(SCREENSHOT_PLACEHOLDER_LINE_RE, '')
+  }
+
+  return { cleanedText: cleanedText.trim(), refs }
+}
diff --git a/apps/desktop/src/lib/external-link.test.tsx b/apps/desktop/src/lib/external-link.test.tsx
index 5001f9c479a..57c0176e37c 100644
--- a/apps/desktop/src/lib/external-link.test.tsx
+++ b/apps/desktop/src/lib/external-link.test.tsx
@@ -23,6 +23,16 @@ function installDesktopBridge(partial: Partial<Window['hermesDesktop']> = {}) {
   } as unknown as Window['hermesDesktop']
 }
 
+const FORGEJO_URL = 'https://forgejo.home.example/homelab/homelab-ops/issues/101'
+
+function installTitleBridge(title: string) {
+  const bridge = vi.fn().mockResolvedValue(title)
+
+  installDesktopBridge({ fetchLinkTitle: bridge as unknown as Window['hermesDesktop']['fetchLinkTitle'] })
+
+  return bridge
+}
+
 afterEach(() => {
   __resetLinkTitleCache()
   vi.restoreAllMocks()
@@ -102,11 +112,24 @@ describe('external link helpers', () => {
     expect(openExternal).toHaveBeenCalledWith('https://example.com/path/to/resource')
   })
 
-  it('shows a trailing external-link icon', () => {
+  it('hides the trailing external-link icon by default', () => {
     installDesktopBridge()
 
     render(<ExternalLink href="https://example.com/path/to/resource">Example link</ExternalLink>)
 
+    const link = screen.getByRole('link', { name: 'Example link' })
+    expect(link.querySelector('svg')).toBeNull()
+  })
+
+  it('shows a trailing external-link icon when opted in', () => {
+    installDesktopBridge()
+
+    render(
+      <ExternalLink href="https://example.com/path/to/resource" showExternalIcon>
+        Example link
+      </ExternalLink>
+    )
+
     const link = screen.getByRole('link', { name: 'Example link' })
     expect(link.querySelector('svg')).toBeTruthy()
   })
@@ -155,6 +178,39 @@ describe('external link helpers', () => {
     })
   })
 
+  it('treats not-found fetched titles as unusable', async () => {
+    const bridge = installTitleBridge('Page not found - Forgejo')
+
+    await expect(fetchLinkTitle(FORGEJO_URL)).resolves.toBe('')
+    expect(bridge).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps an authored fallbackLabel ahead of a fetched title, and skips the fetch', async () => {
+    const bridge = installTitleBridge('Kinkolino Forgejo')
+
+    // Chat markdown passes authored link text as `fallbackLabel`, not `label`.
+    render(<PrettyLink fallbackLabel="FJ #101" href={FORGEJO_URL} />)
+
+    const link = screen.getByTitle(FORGEJO_URL)
+
+    await waitFor(() => {
+      expect(link.textContent).toContain('FJ #101')
+    })
+    expect(link.textContent).not.toContain('Kinkolino Forgejo')
+    expect(bridge).not.toHaveBeenCalled()
+  })
+
+  it('still resolves a title when no label was authored', async () => {
+    const bridge = installTitleBridge('Homelab Ops Issue 101')
+
+    render(<PrettyLink href={FORGEJO_URL} />)
+
+    await waitFor(() => {
+      expect(screen.getByTitle(FORGEJO_URL).textContent).toContain('Homelab Ops Issue 101')
+    })
+    expect(bridge).toHaveBeenCalledTimes(1)
+  })
+
   it('normalizes scheme-less links before opening', () => {
     installDesktopBridge()
 
diff --git a/apps/desktop/src/lib/external-link.tsx b/apps/desktop/src/lib/external-link.tsx
index ebdee577ac2..17f82c6a2cb 100644
--- a/apps/desktop/src/lib/external-link.tsx
+++ b/apps/desktop/src/lib/external-link.tsx
@@ -23,7 +23,7 @@ const SKIP_PROTO_RE = /^(?:file|data|mailto|javascript|blob|chrome|about|hermes)
 const LOCAL_HOST_RE = /^(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?$/i
 
 const ERROR_TITLE_RE =
-  /\b(?:access denied|attention required|captcha|error|forbidden|just a moment|request blocked|too many requests)\b/i
+  /\b(?:access denied|attention required|captcha|error|forbidden|just a moment|not found|request blocked|too many requests)\b/i
 
 export function normalizeExternalUrl(value: string): string {
   const trimmed = value.trim()
@@ -215,14 +215,14 @@ export function ExternalLink({
   className,
   href,
   onClick,
-  showExternalIcon = true,
+  showExternalIcon = false,
   ...rest
 }: ExternalLinkProps) {
   const target = normalizeExternalUrl(href)
 
   return (
     <a
-      className={cn('font-semibold text-foreground underline underline-offset-4 decoration-current/20', className)}
+      className={cn('link-chip font-semibold', className)}
       href={target}
       onClick={event => {
         event.stopPropagation()
@@ -251,10 +251,13 @@ interface PrettyLinkProps extends Omit<ComponentProps<'a'>, 'href' | 'target'> {
   fallbackLabel?: string
 }
 
+// Title resolution is a fallback, not an override. Both props carry authored
+// text — chat markdown passes `fallbackLabel` — so either one skips the fetch.
 export function PrettyLink({ className, fallbackLabel, href, label, ...rest }: PrettyLinkProps) {
   const target = useMemo(() => normalizeExternalUrl(href), [href])
-  const fetched = useLinkTitle(label ? null : target)
-  const display = fetched || label?.trim() || fallbackLabel?.trim() || urlSlugTitleLabel(target)
+  const authoredLabel = label?.trim() || fallbackLabel?.trim()
+  const fetched = useLinkTitle(authoredLabel ? null : target)
+  const display = authoredLabel || fetched || urlSlugTitleLabel(target)
 
   return (
     <ExternalLink className={cn('wrap-break-word', className)} href={target} title={target} {...rest}>
diff --git a/apps/desktop/src/lib/incremental-external-store-runtime.test.ts b/apps/desktop/src/lib/incremental-external-store-runtime.test.ts
new file mode 100644
index 00000000000..0c50d33370a
--- /dev/null
+++ b/apps/desktop/src/lib/incremental-external-store-runtime.test.ts
@@ -0,0 +1,144 @@
+import { fromThreadMessageLike, getAutoStatus, MessageRepository } from '@assistant-ui/core/internal'
+import type { ExportedMessageRepository, ThreadMessage } from '@assistant-ui/react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { syncRepositoryIncrementally } from './incremental-external-store-runtime'
+
+const STATUS = getAutoStatus(false, false, false, false, undefined)
+
+function message(id: string, text: string): ThreadMessage {
+  return fromThreadMessageLike({ role: 'assistant', content: [{ type: 'text', text }] }, id, STATUS)
+}
+
+/** A real MessageRepository behind the same shape syncRepositoryIncrementally drives. */
+function runtimeWith(items: { message: ThreadMessage; parentId: string | null }[]) {
+  const repository = new MessageRepository()
+
+  for (const { message: item, parentId } of items) {
+    repository.addOrUpdateMessage(parentId, item)
+  }
+
+  if (items.length > 0) {
+    repository.resetHead(items.at(-1)?.message.id ?? null)
+  }
+
+  return { repository } as unknown as Parameters<typeof syncRepositoryIncrementally>[0]
+}
+
+function chain(messages: ThreadMessage[]) {
+  return messages.map((item, index) => ({
+    message: item,
+    parentId: index === 0 ? null : messages[index - 1].id
+  }))
+}
+
+function exported(items: { message: ThreadMessage; parentId: string | null }[]): ExportedMessageRepository {
+  return { headId: items.at(-1)?.message.id ?? null, messages: items }
+}
+
+describe('syncRepositoryIncrementally', () => {
+  it('writes only the changed tail instead of the whole transcript', () => {
+    const settled = Array.from({ length: 200 }, (_, index) => message(`m-${index}`, `body ${index}`))
+    const items = chain(settled)
+    const runtime = runtimeWith(items)
+    const repository = (runtime as unknown as { repository: MessageRepository }).repository
+
+    const addOrUpdate = vi.spyOn(repository, 'addOrUpdateMessage')
+    const resetHead = vi.spyOn(repository, 'resetHead')
+
+    // One streamed delta: the tail grows, every settled message keeps identity.
+    const nextTail = message('m-199', 'body 199 + delta')
+    const nextItems = [...items.slice(0, -1), { message: nextTail, parentId: 'm-198' }]
+
+    const result = syncRepositoryIncrementally(runtime, exported(nextItems))
+
+    expect(addOrUpdate).toHaveBeenCalledTimes(1)
+    expect(addOrUpdate).toHaveBeenCalledWith('m-198', nextTail)
+    // The head did not move, so the descendant-pruning reset is skipped.
+    expect(resetHead).not.toHaveBeenCalled()
+    expect(result).toHaveLength(200)
+    expect(result.at(-1)).toBe(nextTail)
+  })
+
+  it('does nothing at all when the transcript is unchanged', () => {
+    const items = chain([message('a', 'one'), message('b', 'two')])
+    const runtime = runtimeWith(items)
+    const repository = (runtime as unknown as { repository: MessageRepository }).repository
+
+    const addOrUpdate = vi.spyOn(repository, 'addOrUpdateMessage')
+    const deleteMessage = vi.spyOn(repository, 'deleteMessage')
+
+    syncRepositoryIncrementally(runtime, exported(items))
+
+    expect(addOrUpdate).not.toHaveBeenCalled()
+    expect(deleteMessage).not.toHaveBeenCalled()
+  })
+
+  it('appends a new message through the full path', () => {
+    const first = message('a', 'one')
+    const items = chain([first])
+    const runtime = runtimeWith(items)
+
+    const second = message('b', 'two')
+    const result = syncRepositoryIncrementally(runtime, exported(chain([first, second])))
+
+    expect(result.map(item => item.id)).toEqual(['a', 'b'])
+  })
+
+  it('honours an authoritative deletion', () => {
+    const a = message('a', 'one')
+    const b = message('b', 'two')
+    const c = message('c', 'three')
+    const runtime = runtimeWith(chain([a, b, c]))
+
+    const result = syncRepositoryIncrementally(runtime, exported(chain([a, b])))
+
+    expect(result.map(item => item.id)).toEqual(['a', 'b'])
+  })
+
+  it('rebuilds cleanly when a disjoint transcript is swapped in', () => {
+    const runtime = runtimeWith(chain([message('old-1', 'one'), message('old-2', 'two')]))
+
+    const next = chain([message('new-1', 'alpha'), message('new-2', 'beta')])
+    const result = syncRepositoryIncrementally(runtime, exported(next))
+
+    expect(result.map(item => item.id)).toEqual(['new-1', 'new-2'])
+  })
+
+  it('re-parents a message when its branch parent changes', () => {
+    const root = message('root', 'root')
+    const a = message('a', 'a')
+    const b = message('b', 'b')
+
+    const runtime = runtimeWith([
+      { message: root, parentId: null },
+      { message: a, parentId: 'root' },
+      { message: b, parentId: 'a' }
+    ])
+
+    // Same ids and same message objects, but `b` moves onto a sibling branch.
+    const result = syncRepositoryIncrementally(runtime, {
+      headId: 'b',
+      messages: [
+        { message: root, parentId: null },
+        { message: a, parentId: 'root' },
+        { message: b, parentId: 'root' }
+      ]
+    })
+
+    expect(result.map(item => item.id)).toEqual(['root', 'b'])
+  })
+
+  it('moves the head when an explicit headId rewinds the branch', () => {
+    const a = message('a', 'one')
+    const b = message('b', 'two')
+    const runtime = runtimeWith(chain([a, b]))
+
+    const result = syncRepositoryIncrementally(runtime, {
+      headId: 'a',
+      messages: chain([a, b])
+    })
+
+    expect(result.map(item => item.id)).toEqual(['a'])
+  })
+})
diff --git a/apps/desktop/src/lib/incremental-external-store-runtime.ts b/apps/desktop/src/lib/incremental-external-store-runtime.ts
index f4a8191b5f5..0df3ed9b2e0 100644
--- a/apps/desktop/src/lib/incremental-external-store-runtime.ts
+++ b/apps/desktop/src/lib/incremental-external-store-runtime.ts
@@ -35,25 +35,81 @@ const shallowEqual = (a: object, b: object): boolean => {
 
 const getThreadListAdapter = (store: ExternalStoreAdapter) => store.adapters?.threadList ?? {}
 
-function syncRepositoryIncrementally(
+/**
+ * Write only the items whose (message, parentId) pair actually moved.
+ *
+ * `useRuntimeMessageRepository` caches normalized ThreadMessages by source
+ * identity, so a settled turn keeps the SAME object across renders. That makes
+ * an identity check a sound "did this change?" test: during streaming exactly
+ * one item — the growing tail — differs, and the other N-1 writes were pure
+ * overhead that grew with transcript length.
+ *
+ * Returns false when the export is stale (an id in `existing` is gone, or an
+ * incoming message has no repository entry yet), so the caller falls back to
+ * the full rebuild rather than guessing.
+ */
+function applyChangedMessages(
+  repository: ExternalStoreThreadRuntimeCore['repository'],
+  existing: readonly { message: ThreadMessage; parentId: string | null }[],
+  incoming: readonly { message: ThreadMessage; parentId: string | null }[]
+): boolean {
+  if (existing.length !== incoming.length) {
+    return false
+  }
+
+  const existingById = new Map(existing.map(item => [item.message.id, item]))
+
+  for (const item of incoming) {
+    const current = existingById.get(item.message.id)
+
+    if (!current) {
+      return false
+    }
+
+    // Reference identity, not deep equality: the conversion cache guarantees a
+    // stable object for an unchanged turn, and a changed turn is a new object.
+    if (current.message !== item.message || current.parentId !== item.parentId) {
+      repository.addOrUpdateMessage(item.parentId, item.message)
+    }
+  }
+
+  return true
+}
+
+export function syncRepositoryIncrementally(
   runtime: ExternalStoreThreadRuntimeCore,
   messageRepository: NonNullable<ExternalStoreAdapter['messageRepository']>
 ): readonly ThreadMessage[] {
   const repository = (runtime as unknown as { repository: ExternalStoreThreadRuntimeCore['repository'] }).repository
-  const incomingIds = new Set(messageRepository.messages.map(({ message }) => message.id))
+  const incoming = messageRepository.messages
   const existing = repository.export().messages
+  const headId = messageRepository.headId ?? incoming.at(-1)?.message.id ?? null
 
   // A thread switch swaps in a fully-DISJOINT transcript (no id carries over).
   // Reconciling two unrelated trees in place — grafting the new chain onto the
   // old one, then pruning — can strand a stale head/branch, so there's nothing
   // to preserve: clear the tree first (leaves→root), then rebuild clean.
-  if (existing.length > 0 && !existing.some(({ message }) => incomingIds.has(message.id))) {
+  const incomingIds = new Set(incoming.map(({ message }) => message.id))
+  const disjoint = existing.length > 0 && !existing.some(({ message }) => incomingIds.has(message.id))
+
+  // Steady-state streaming: same message set, one item changed. Skip the
+  // whole-transcript rewrite, the prune scan, and the second export. resetHead
+  // deletes the head's descendants, so it only runs when the head really moved.
+  if (!disjoint && applyChangedMessages(repository, existing, incoming)) {
+    if (repository.headId !== headId) {
+      repository.resetHead(headId)
+    }
+
+    return repository.getMessages()
+  }
+
+  if (disjoint) {
     for (const { message } of [...existing].reverse()) {
       repository.deleteMessage(message.id)
     }
   }
 
-  for (const { message, parentId } of messageRepository.messages) {
+  for (const { message, parentId } of incoming) {
     repository.addOrUpdateMessage(parentId, message)
   }
 
@@ -63,8 +119,6 @@ function syncRepositoryIncrementally(
     }
   }
 
-  const headId = messageRepository.headId ?? messageRepository.messages.at(-1)?.message.id ?? null
-
   repository.resetHead(headId)
 
   return repository.getMessages()
diff --git a/apps/desktop/src/lib/inflight-turn-journal.test.ts b/apps/desktop/src/lib/inflight-turn-journal.test.ts
new file mode 100644
index 00000000000..ffa1c430065
--- /dev/null
+++ b/apps/desktop/src/lib/inflight-turn-journal.test.ts
@@ -0,0 +1,240 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ChatMessage } from '@/lib/chat-messages'
+import {
+  clearInFlightTurnJournal,
+  type JournalableSessionState,
+  mergeInFlightMessages,
+  persistInFlightTurnState,
+  readInFlightTurnJournal,
+  recoverInFlightTurnJournal
+} from '@/lib/inflight-turn-journal'
+
+const STORAGE_KEY = 'hermes.desktop.inflightTurnJournal.v1'
+
+function user(id: string, text: string): ChatMessage {
+  return { id, role: 'user', parts: [{ type: 'text', text }] }
+}
+
+function assistant(id: string, text: string, extra: Partial<ChatMessage> = {}): ChatMessage {
+  return { id, role: 'assistant', parts: [{ type: 'text', text }], ...extra }
+}
+
+function assistantWithTool(id: string, text: string, extra: Partial<ChatMessage> = {}): ChatMessage {
+  return {
+    id,
+    role: 'assistant',
+    parts: [
+      { type: 'tool-call', toolCallId: 'tc-1', toolName: 'terminal', args: { command: 'ls' } },
+      { type: 'text', text }
+    ],
+    ...extra
+  }
+}
+
+function journalState(overrides: Partial<JournalableSessionState> = {}): JournalableSessionState {
+  return {
+    awaitingResponse: false,
+    busy: true,
+    messages: [user('u1', 'do the thing'), assistant('assistant-stream-1', 'partial answer', { pending: true })],
+    storedSessionId: 'stored-1',
+    streamId: 'assistant-stream-1',
+    turnStartedAt: 1000,
+    ...overrides
+  }
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  window.localStorage.clear()
+})
+
+afterEach(() => {
+  clearInFlightTurnJournal('stored-1')
+  vi.useRealTimers()
+})
+
+describe('persistInFlightTurnState', () => {
+  it('journals the running turn tail after the throttle window', () => {
+    persistInFlightTurnState(journalState())
+
+    expect(readInFlightTurnJournal('stored-1')).toBeNull()
+
+    vi.advanceTimersByTime(400)
+
+    const entry = readInFlightTurnJournal('stored-1')
+    expect(entry).not.toBeNull()
+    expect(entry?.streamId).toBe('assistant-stream-1')
+    expect(entry?.turnStartedAt).toBe(1000)
+    expect(entry?.messages.map(m => m.role)).toEqual(['user', 'assistant'])
+  })
+
+  it('coalesces rapid updates into one write carrying the latest state', () => {
+    persistInFlightTurnState(journalState())
+    persistInFlightTurnState(
+      journalState({
+        messages: [
+          user('u1', 'do the thing'),
+          assistant('assistant-stream-1', 'partial answer grew', { pending: true })
+        ]
+      })
+    )
+
+    vi.advanceTimersByTime(400)
+
+    const entry = readInFlightTurnJournal('stored-1')
+    const tail = entry?.messages.find(m => m.role === 'assistant')
+    expect(tail?.parts).toEqual([{ type: 'text', text: 'partial answer grew' }])
+  })
+
+  it('clears the entry the moment the turn settles, cancelling pending writes', () => {
+    persistInFlightTurnState(journalState())
+    vi.advanceTimersByTime(400)
+    expect(readInFlightTurnJournal('stored-1')).not.toBeNull()
+
+    persistInFlightTurnState(journalState({ messages: [] }))
+    persistInFlightTurnState(journalState({ busy: false, awaitingResponse: false, streamId: null }))
+
+    expect(readInFlightTurnJournal('stored-1')).toBeNull()
+
+    vi.advanceTimersByTime(1000)
+    expect(readInFlightTurnJournal('stored-1')).toBeNull()
+  })
+
+  it('does not journal a turn with no recoverable assistant content yet', () => {
+    persistInFlightTurnState(journalState({ messages: [user('u1', 'do the thing')], streamId: null }))
+
+    vi.advanceTimersByTime(400)
+    expect(readInFlightTurnJournal('stored-1')).toBeNull()
+  })
+
+  it('expires entries older than the max age', () => {
+    persistInFlightTurnState(journalState())
+    vi.advanceTimersByTime(400)
+
+    const raw = JSON.parse(window.localStorage.getItem(STORAGE_KEY)!)
+    raw.entries['stored-1'].updatedAt = Date.now() - 8 * 24 * 60 * 60 * 1000
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(raw))
+
+    expect(readInFlightTurnJournal('stored-1')).toBeNull()
+  })
+})
+
+describe('recoverInFlightTurnJournal', () => {
+  function journalEntry(messages: ChatMessage[]) {
+    persistInFlightTurnState(journalState({ messages, streamId: messages.at(-1)?.id ?? null }))
+    vi.advanceTimersByTime(400)
+  }
+
+  it('is a reference-preserving no-op when nothing is journaled', () => {
+    const base = [user('u1', 'do the thing')]
+    const result = recoverInFlightTurnJournal('stored-1', base)
+
+    expect(result.applied).toBe(false)
+    expect(result.messages).toBe(base)
+  })
+
+  it('appends the full tail when the base transcript never saw the turn', () => {
+    journalEntry([
+      user('u1', 'do the thing'),
+      assistantWithTool('assistant-stream-1', 'working on it', { pending: true })
+    ])
+
+    const base = [user('u0', 'earlier turn'), assistant('a0', 'earlier reply')]
+    const result = recoverInFlightTurnJournal('stored-1', base)
+
+    expect(result.applied).toBe(true)
+    expect(result.messages.map(m => m.id)).toEqual(['u0', 'a0', 'u1', 'assistant-stream-1'])
+    expect(result.streamId).toBe('assistant-stream-1')
+  })
+
+  it('appends only the assistant tail when the user row was persisted', () => {
+    journalEntry([
+      user('u1', 'do the thing'),
+      assistantWithTool('assistant-stream-1', 'working on it', { pending: true })
+    ])
+
+    const base = [user('db-u1', 'do the thing')]
+    const result = recoverInFlightTurnJournal('stored-1', base, { keepPending: false })
+
+    expect(result.applied).toBe(true)
+    expect(result.messages.map(m => m.id)).toEqual(['db-u1', 'assistant-stream-1'])
+    const tail = result.messages.at(-1)!
+    expect(tail.pending).toBe(false)
+    expect(tail.parts[0]).toMatchObject({ type: 'tool-call' })
+  })
+
+  it('detects a committed reply as caught up and clears the entry', () => {
+    journalEntry([user('u1', 'do the thing'), assistant('assistant-stream-1', 'partial', { pending: true })])
+
+    const base = [user('db-u1', 'do the thing'), assistant('db-a1', 'full committed reply')]
+    const result = recoverInFlightTurnJournal('stored-1', base)
+
+    expect(result.applied).toBe(false)
+    expect(result.caughtUp).toBe(true)
+    expect(result.messages).toBe(base)
+    expect(readInFlightTurnJournal('stored-1')).toBeNull()
+  })
+
+  it('overlays the backend text-only projection instead of dropping local tool progress', () => {
+    // Sweeper regression on #44339: a backend `inflight` assistant snapshot
+    // (text only) used to mark the richer local tail "caught up" and delete
+    // locally recorded tool calls.
+    journalEntry([
+      user('u1', 'do the thing'),
+      assistantWithTool('assistant-stream-old', 'local part', { pending: true })
+    ])
+
+    const base = [
+      user('db-u1', 'do the thing'),
+      assistant('assistant-stream-rt9', 'longer partial text from the backend snapshot', { pending: true })
+    ]
+
+    const result = recoverInFlightTurnJournal('stored-1', base, { keepPending: true })
+
+    expect(result.applied).toBe(true)
+    expect(result.caughtUp).toBe(false)
+    expect(result.messages).toHaveLength(2)
+
+    const merged = result.messages.at(-1)!
+    // Keeps the BASE projection row id so live deltas keep landing on it.
+    expect(merged.id).toBe('assistant-stream-rt9')
+    expect(result.streamId).toBe('assistant-stream-rt9')
+    // Journal structure survives; the longer backend text wins.
+    expect(merged.parts[0]).toMatchObject({ type: 'tool-call', toolName: 'terminal' })
+    expect(merged.parts[1]).toMatchObject({ type: 'text', text: 'longer partial text from the backend snapshot' })
+    // Still in flight — the journal must NOT be cleared.
+    expect(readInFlightTurnJournal('stored-1')).not.toBeNull()
+  })
+
+  it('keeps the journal text when it is longer than the projection text', () => {
+    journalEntry([
+      user('u1', 'do the thing'),
+      assistantWithTool('assistant-stream-old', 'a much longer locally journaled partial answer', { pending: true })
+    ])
+
+    const base = [user('db-u1', 'do the thing'), assistant('assistant-stream-rt9', 'thin', { pending: true })]
+    const result = recoverInFlightTurnJournal('stored-1', base, { keepPending: true })
+
+    const merged = result.messages.at(-1)!
+    expect(merged.id).toBe('assistant-stream-rt9')
+    expect(merged.parts[1]).toMatchObject({ type: 'text', text: 'a much longer locally journaled partial answer' })
+  })
+})
+
+describe('mergeInFlightMessages', () => {
+  it('treats an error-bearing assistant row as recoverable content', () => {
+    const tail = [user('u1', 'do the thing'), assistant('a-err', '', { error: 'provider exploded' })]
+    const result = mergeInFlightMessages([user('db-u1', 'do the thing')], tail)
+
+    expect(result.applied).toBe(true)
+    expect(result.messages.at(-1)?.error).toBe('provider exploded')
+  })
+
+  it('ignores hidden rows when extracting nothing to recover', () => {
+    const result = mergeInFlightMessages([], [user('u1', 'x')])
+
+    expect(result.applied).toBe(false)
+    expect(result.caughtUp).toBe(false)
+  })
+})
diff --git a/apps/desktop/src/lib/inflight-turn-journal.ts b/apps/desktop/src/lib/inflight-turn-journal.ts
new file mode 100644
index 00000000000..8056fa7af10
--- /dev/null
+++ b/apps/desktop/src/lib/inflight-turn-journal.ts
@@ -0,0 +1,504 @@
+import { type ChatMessage, type ChatMessagePart, chatMessageText } from '@/lib/chat-messages'
+
+/**
+ * Crash-survivable in-flight turn journal.
+ *
+ * While a session is busy, the visible tail of the running turn (user prompt +
+ * streamed assistant rows, tool calls included) is persisted to localStorage.
+ * If the renderer or the whole app dies mid-turn, session resume folds the
+ * journaled tail back onto the restored transcript, so streamed progress is
+ * not silently lost. The backend's own `inflight` snapshot (merged by
+ * `appendLiveSessionProjection`) covers reconnects while the backend is alive;
+ * this journal covers the cases where the backend died too — and it is richer,
+ * because the backend snapshot carries text only while the journal keeps the
+ * full part structure.
+ *
+ * Best-effort by design: storage failures must never break chat streaming.
+ */
+
+const STORAGE_KEY = 'hermes.desktop.inflightTurnJournal.v1'
+const STORE_VERSION = 1
+const MAX_ENTRIES = 24
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+/** Streaming repaints arrive every ~33ms; localStorage writes are synchronous.
+ *  Trailing-edge throttle keeps the journal off the hot path — a crash costs at
+ *  most this much of the newest tail. */
+const PERSIST_THROTTLE_MS = 400
+
+export interface InFlightTurnSnapshot {
+  messages: ChatMessage[]
+  streamId: null | string
+  turnStartedAt: null | number
+  updatedAt: number
+}
+
+export interface JournalableSessionState {
+  awaitingResponse: boolean
+  busy: boolean
+  messages: ChatMessage[]
+  storedSessionId: null | string
+  streamId: null | string
+  turnStartedAt: null | number
+}
+
+interface JournalStore {
+  entries: Record<string, InFlightTurnSnapshot>
+  version: typeof STORE_VERSION
+}
+
+export interface InFlightRecoveryResult {
+  applied: boolean
+  /** The base transcript already contains the journaled turn's completed
+   *  reply — the journal entry is stale and has been cleared. */
+  caughtUp: boolean
+  messages: ChatMessage[]
+  streamId: null | string
+  turnStartedAt: null | number
+}
+
+function storage(): Storage | null {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage
+  } catch {
+    return null
+  }
+}
+
+function emptyStore(): JournalStore {
+  return { entries: {}, version: STORE_VERSION }
+}
+
+function loadStore(): JournalStore {
+  const store = storage()
+
+  if (!store) {
+    return emptyStore()
+  }
+
+  try {
+    const raw = store.getItem(STORAGE_KEY)
+
+    if (!raw) {
+      return emptyStore()
+    }
+
+    const parsed = JSON.parse(raw)
+
+    if (
+      !parsed ||
+      parsed.version !== STORE_VERSION ||
+      typeof parsed.entries !== 'object' ||
+      Array.isArray(parsed.entries)
+    ) {
+      return emptyStore()
+    }
+
+    return {
+      entries: parsed.entries as Record<string, InFlightTurnSnapshot>,
+      version: STORE_VERSION
+    }
+  } catch {
+    return emptyStore()
+  }
+}
+
+function saveStore(journal: JournalStore): void {
+  const store = storage()
+
+  if (!store) {
+    return
+  }
+
+  try {
+    const entries = Object.fromEntries(
+      Object.entries(journal.entries)
+        .filter(([, entry]) => !isExpired(entry))
+        .sort((a, b) => b[1].updatedAt - a[1].updatedAt)
+        .slice(0, MAX_ENTRIES)
+    )
+
+    if (Object.keys(entries).length === 0) {
+      store.removeItem(STORAGE_KEY)
+
+      return
+    }
+
+    store.setItem(STORAGE_KEY, JSON.stringify({ entries, version: STORE_VERSION }))
+  } catch {
+    // Quota/private-mode failures: the journal is a recovery aid, not truth.
+  }
+}
+
+function isExpired(entry: InFlightTurnSnapshot, now = Date.now()): boolean {
+  return now - entry.updatedAt > MAX_AGE_MS
+}
+
+function cloneMessages(messages: ChatMessage[]): ChatMessage[] {
+  try {
+    return JSON.parse(JSON.stringify(messages)) as ChatMessage[]
+  } catch {
+    return []
+  }
+}
+
+function normalizedText(value: string): string {
+  return value.replace(/\s+/g, ' ').trim()
+}
+
+function attachmentSignature(message: ChatMessage): string {
+  return (message.attachmentRefs ?? []).join('\n')
+}
+
+function userMessagesMatch(left: ChatMessage, right: ChatMessage): boolean {
+  return (
+    left.role === 'user' &&
+    right.role === 'user' &&
+    normalizedText(chatMessageText(left)) === normalizedText(chatMessageText(right)) &&
+    attachmentSignature(left) === attachmentSignature(right)
+  )
+}
+
+function partHasRecoverableContent(part: ChatMessagePart): boolean {
+  if (part.type === 'text' || part.type === 'reasoning') {
+    return typeof part.text === 'string' && part.text.trim().length > 0
+  }
+
+  return part.type === 'tool-call'
+}
+
+function assistantHasRecoverableContent(message: ChatMessage): boolean {
+  return message.role === 'assistant' && (Boolean(message.error) || message.parts.some(partHasRecoverableContent))
+}
+
+/** A live-turn projection row (backend `inflight` via appendLiveSessionProjection,
+ *  or a still-streaming local bubble) — as opposed to a completed transcript row. */
+function isLiveProjectionRow(message: ChatMessage): boolean {
+  return (
+    Boolean(message.pending) ||
+    message.id.startsWith('assistant-stream-') ||
+    message.id.startsWith('inflight-assistant-')
+  )
+}
+
+/** Visible tail of the running turn: the streaming assistant row (plus any
+ *  interim rows sealed after it) back to the user prompt that started it. */
+function recoverableTail(messages: ChatMessage[], streamId: null | string): ChatMessage[] {
+  const visible = messages.filter(message => !message.hidden)
+  let assistantIndex = -1
+
+  if (streamId) {
+    assistantIndex = visible.findIndex(message => message.id === streamId && assistantHasRecoverableContent(message))
+  }
+
+  if (assistantIndex < 0) {
+    for (let index = visible.length - 1; index >= 0; index -= 1) {
+      const message = visible[index]
+
+      if (message.role === 'user') {
+        break
+      }
+
+      if (assistantHasRecoverableContent(message)) {
+        assistantIndex = index
+
+        break
+      }
+    }
+  }
+
+  if (assistantIndex < 0) {
+    return []
+  }
+
+  let start = assistantIndex
+
+  for (let index = assistantIndex - 1; index >= 0; index -= 1) {
+    if (visible[index].role === 'user') {
+      start = index
+
+      break
+    }
+  }
+
+  return cloneMessages(visible.slice(start))
+}
+
+function normalizeRecoveredTail(tail: ChatMessage[], keepPending: boolean): ChatMessage[] {
+  return cloneMessages(tail).map(message =>
+    message.role === 'assistant'
+      ? {
+          ...message,
+          pending: keepPending ? (message.pending ?? true) : false
+        }
+      : { ...message, pending: false }
+  )
+}
+
+function assistantTextLength(message: ChatMessage): number {
+  return chatMessageText(message).length
+}
+
+/** Merge the journal's last assistant row into the base's live projection row.
+ *
+ * The journal carries structure (tool calls, reasoning) the backend snapshot
+ * lacks; the backend text may be newer than the journal's last throttled
+ * write. Keep the journal's parts, but let the longer text win — and keep the
+ * BASE row's id so live deltas keep appending to the row the stream handler
+ * already targets.
+ */
+function overlayProjectionRow(projection: ChatMessage, journalRow: ChatMessage): ChatMessage {
+  // A projected error (retained failed turn) must survive the overlay.
+  const error = journalRow.error ?? projection.error
+
+  const merged: ChatMessage = {
+    ...journalRow,
+    id: projection.id,
+    pending: projection.pending,
+    ...(error ? { error } : {})
+  }
+
+  if (assistantTextLength(projection) <= assistantTextLength(journalRow)) {
+    return merged
+  }
+
+  // Backend text is newer than the journal's last throttled write — swap it
+  // into the journal's first text part, keeping tool calls and reasoning.
+  const projectionText = chatMessageText(projection)
+  const parts: ChatMessagePart[] = []
+  let textReplaced = false
+
+  for (const part of journalRow.parts) {
+    if (part.type !== 'text') {
+      parts.push(part)
+    } else if (!textReplaced) {
+      parts.push({ ...part, text: projectionText })
+      textReplaced = true
+    }
+  }
+
+  if (!textReplaced) {
+    parts.push({ type: 'text', text: projectionText })
+  }
+
+  return { ...merged, parts }
+}
+
+export function mergeInFlightMessages(
+  baseMessages: ChatMessage[],
+  tailMessages: ChatMessage[],
+  options: { keepPending?: boolean } = {}
+): InFlightRecoveryResult {
+  const noop: InFlightRecoveryResult = {
+    applied: false,
+    caughtUp: false,
+    messages: baseMessages,
+    streamId: null,
+    turnStartedAt: null
+  }
+
+  const tail = normalizeRecoveredTail(tailMessages, Boolean(options.keepPending))
+
+  if (!tail.some(assistantHasRecoverableContent)) {
+    return noop
+  }
+
+  const tailUserIndex = tail.findIndex(message => message.role === 'user')
+  const tailUser = tailUserIndex >= 0 ? tail[tailUserIndex] : null
+  const tailAssistants = tail.slice(tailUserIndex + 1)
+  const lastJournalRow = tailAssistants.findLast(assistantHasRecoverableContent) ?? null
+  const matchingUserIndex = tailUser ? baseMessages.findLastIndex(message => userMessagesMatch(message, tailUser)) : -1
+
+  if (matchingUserIndex < 0) {
+    // Base doesn't know this turn at all (user row was never persisted):
+    // append the whole tail.
+    const streamId = lastJournalRow?.id ?? null
+
+    return { applied: true, caughtUp: false, messages: [...baseMessages, ...tail], streamId, turnStartedAt: null }
+  }
+
+  const afterUser = baseMessages.slice(matchingUserIndex + 1)
+
+  const completedReply = afterUser.find(
+    message => assistantHasRecoverableContent(message) && !isLiveProjectionRow(message)
+  )
+
+  if (completedReply) {
+    // The transcript already holds this turn's committed reply — the journal
+    // entry is stale.
+    return { ...noop, caughtUp: true }
+  }
+
+  const projectionIndex = baseMessages.findIndex(
+    (message, index) => index > matchingUserIndex && message.role === 'assistant' && isLiveProjectionRow(message)
+  )
+
+  if (projectionIndex < 0) {
+    if (tailAssistants.length === 0) {
+      return noop
+    }
+
+    const streamId = lastJournalRow?.id ?? null
+
+    return {
+      applied: true,
+      caughtUp: false,
+      messages: [...baseMessages, ...tailAssistants],
+      streamId,
+      turnStartedAt: null
+    }
+  }
+
+  // Backend projection row present (text-only): overlay the journal's
+  // structure onto it instead of treating it as "caught up" — that is how
+  // locally recorded tool progress used to get dropped.
+  const projection = baseMessages[projectionIndex]
+  const merged = lastJournalRow ? overlayProjectionRow(projection, lastJournalRow) : projection
+
+  const sealedRows = tailAssistants.filter(
+    message => message !== lastJournalRow && assistantHasRecoverableContent(message)
+  )
+
+  const messages = [
+    ...baseMessages.slice(0, projectionIndex),
+    ...sealedRows,
+    merged,
+    ...baseMessages.slice(projectionIndex + 1)
+  ]
+
+  return { applied: true, caughtUp: false, messages, streamId: merged.id, turnStartedAt: null }
+}
+
+const persistTimers = new Map<string, ReturnType<typeof setTimeout>>()
+const persistLatest = new Map<string, JournalableSessionState>()
+
+function writeSnapshot(storedSessionId: string, state: JournalableSessionState): void {
+  const tail = recoverableTail(state.messages, state.streamId)
+
+  if (tail.length === 0) {
+    return
+  }
+
+  const journal = loadStore()
+
+  journal.entries[storedSessionId] = {
+    messages: tail,
+    streamId: state.streamId,
+    turnStartedAt: state.turnStartedAt,
+    updatedAt: Date.now()
+  }
+  saveStore(journal)
+}
+
+/** Persist the running turn's visible tail (throttled), or clear the entry the
+ *  moment the turn settles. Call on every session-state commit. */
+export function persistInFlightTurnState(state: JournalableSessionState): void {
+  const storedSessionId = state.storedSessionId
+
+  if (!storedSessionId) {
+    return
+  }
+
+  if (!state.busy && !state.awaitingResponse && !state.streamId) {
+    clearInFlightTurnJournal(storedSessionId)
+
+    return
+  }
+
+  persistLatest.set(storedSessionId, state)
+
+  if (persistTimers.has(storedSessionId)) {
+    return
+  }
+
+  persistTimers.set(
+    storedSessionId,
+    setTimeout(() => {
+      persistTimers.delete(storedSessionId)
+      const latest = persistLatest.get(storedSessionId)
+
+      persistLatest.delete(storedSessionId)
+
+      if (latest) {
+        writeSnapshot(storedSessionId, latest)
+      }
+    }, PERSIST_THROTTLE_MS)
+  )
+}
+
+export function readInFlightTurnJournal(storedSessionId: null | string): InFlightTurnSnapshot | null {
+  if (!storedSessionId) {
+    return null
+  }
+
+  const journal = loadStore()
+  const entry = journal.entries[storedSessionId]
+
+  if (!entry) {
+    return null
+  }
+
+  if (isExpired(entry)) {
+    delete journal.entries[storedSessionId]
+    saveStore(journal)
+
+    return null
+  }
+
+  return entry
+}
+
+/** Fold a journaled in-flight tail back onto a restored transcript. A no-op
+ *  returns `baseMessages` by reference so callers keep their fast-path ref. */
+export function recoverInFlightTurnJournal(
+  storedSessionId: null | string,
+  baseMessages: ChatMessage[],
+  options: { keepPending?: boolean } = {}
+): InFlightRecoveryResult {
+  const snapshot = readInFlightTurnJournal(storedSessionId)
+
+  if (!snapshot) {
+    return {
+      applied: false,
+      caughtUp: false,
+      messages: baseMessages,
+      streamId: null,
+      turnStartedAt: null
+    }
+  }
+
+  const recovered = mergeInFlightMessages(baseMessages, snapshot.messages, options)
+
+  if (recovered.caughtUp) {
+    clearInFlightTurnJournal(storedSessionId)
+  }
+
+  return {
+    ...recovered,
+    streamId: recovered.applied ? (recovered.streamId ?? snapshot.streamId) : null,
+    turnStartedAt: recovered.applied ? snapshot.turnStartedAt : null
+  }
+}
+
+export function clearInFlightTurnJournal(storedSessionId: null | string): void {
+  if (!storedSessionId) {
+    return
+  }
+
+  const timer = persistTimers.get(storedSessionId)
+
+  if (timer) {
+    clearTimeout(timer)
+    persistTimers.delete(storedSessionId)
+  }
+
+  persistLatest.delete(storedSessionId)
+
+  const journal = loadStore()
+
+  if (!(storedSessionId in journal.entries)) {
+    return
+  }
+
+  delete journal.entries[storedSessionId]
+  saveStore(journal)
+}
diff --git a/apps/desktop/src/lib/keybinds/composer-focus-keys.test.ts b/apps/desktop/src/lib/keybinds/composer-focus-keys.test.ts
index cebf54950e4..7594a12b06d 100644
--- a/apps/desktop/src/lib/keybinds/composer-focus-keys.test.ts
+++ b/apps/desktop/src/lib/keybinds/composer-focus-keys.test.ts
@@ -88,6 +88,17 @@ describe('composerFocusBlockedBySurface', () => {
     expect(composerFocusBlockedBySurface()).toBe(true)
   })
 
+  it('ignores a clarify card waiting in a kept-alive background tab', () => {
+    const tab = document.createElement('div')
+    tab.setAttribute('data-pane-hidden', '')
+    const card = document.createElement('div')
+    card.setAttribute('data-clarify-choices', '')
+    tab.append(card)
+    document.body.append(tab)
+
+    expect(composerFocusBlockedBySurface()).toBe(false)
+  })
+
   it('blocks when focus is inside a terminal', () => {
     const term = document.createElement('div')
     term.setAttribute('data-terminal', '')
diff --git a/apps/desktop/src/lib/keybinds/composer-focus-keys.ts b/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
index 6bba44aa34a..29da02cda58 100644
--- a/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
+++ b/apps/desktop/src/lib/keybinds/composer-focus-keys.ts
@@ -7,6 +7,7 @@
  */
 
 import { $workspaceIsPage } from '@/app/routes'
+import { queryVisible } from '@/components/pane-shell/pane-visibility'
 import { switcherActive } from '@/store/session-switcher'
 
 import { isEditableTarget, isFocusWithin } from './combo'
@@ -37,8 +38,15 @@ const ENTER_ACTIVATES = [
   '[role="treeitem"]'
 ].join(',')
 
-const BLOCKING_SURFACE =
-  '[role="dialog"],[role="alertdialog"],[role="menu"],[role="listbox"],[data-radix-popper-content-wrapper],[data-overlay-surface],[data-clarify-choices]'
+// Overlays that cover the whole window (portaled to the body, or the overlay
+// shell itself) — one anywhere means the composer is behind it.
+const BLOCKING_OVERLAY =
+  '[role="dialog"],[role="alertdialog"],[role="menu"],[role="listbox"],[data-radix-popper-content-wrapper],[data-overlay-surface]'
+
+// Blockers that live INSIDE a chat surface. Inactive tabs stay mounted, so this
+// one has to be visible-scoped: a clarify card waiting in a background thread
+// must not take the foreground composer's letter keys.
+const BLOCKING_IN_SURFACE = '[data-clarify-choices]'
 
 /** True when the focused control would normally handle Enter itself. */
 export function isActivateOnEnterTarget(target: EventTarget | null): boolean {
@@ -59,7 +67,8 @@ export function composerFocusBlockedBySurface(): boolean {
     switcherActive() ||
     $workspaceIsPage.get() ||
     isFocusWithin('[data-terminal]') ||
-    Boolean(document.querySelector(BLOCKING_SURFACE))
+    Boolean(document.querySelector(BLOCKING_OVERLAY)) ||
+    Boolean(queryVisible(BLOCKING_IN_SURFACE))
   )
 }
 
diff --git a/apps/desktop/src/lib/markdown-preprocess.ts b/apps/desktop/src/lib/markdown-preprocess.ts
index 25213e7ab30..c4a8731f478 100644
--- a/apps/desktop/src/lib/markdown-preprocess.ts
+++ b/apps/desktop/src/lib/markdown-preprocess.ts
@@ -2,6 +2,7 @@ import { normalizeMathDelimiters } from '@assistant-ui/react-streamdown'
 
 import { isLikelyProseFence, sanitizeLanguageTag } from '@/lib/markdown-code'
 import { stripPreviewTargets } from '@/lib/preview-targets'
+import { linkifySessionRefs } from '@/lib/session-refs'
 
 const REASONING_BLOCK_RE = /<(think|thinking|reasoning|scratchpad|analysis)>[\s\S]*?<\/\1>\s*/gi
 const PREVIEW_MARKER_RE = /\[Preview:[^\]]+\]\(#preview[:/][^)]+\)/gi
@@ -149,8 +150,10 @@ function normalizeVisibleProse(text: string): string {
     .map(part =>
       part.startsWith('`')
         ? part
-        : autoLinkRawUrls(
-            part.replace(/`{3,}/g, '').replace(LOCAL_PREVIEW_URL_RE, '$1').replace(CITATION_MARKER_RE, '')
+        : linkifySessionRefs(
+            autoLinkRawUrls(
+              part.replace(/`{3,}/g, '').replace(LOCAL_PREVIEW_URL_RE, '$1').replace(CITATION_MARKER_RE, '')
+            )
           )
     )
     .join('')
diff --git a/apps/desktop/src/lib/model-status-label.test.ts b/apps/desktop/src/lib/model-status-label.test.ts
index cc499c86d56..d1ad06fb73e 100644
--- a/apps/desktop/src/lib/model-status-label.test.ts
+++ b/apps/desktop/src/lib/model-status-label.test.ts
@@ -1,11 +1,7 @@
 import { describe, expect, it } from 'vitest'
 
-import {
-  currentPickerSelection,
-  displayModelName,
-  formatModelStatusLabel,
-  reasoningEffortLabel
-} from './model-status-label'
+import { currentPickerSelection, displayModelName, formatModelStatusLabel } from './model-status-label'
+import { reasoningEffortLabel } from './reasoning-effort'
 
 describe('model-status-label', () => {
   it('formats display names consistently', () => {
@@ -34,9 +30,16 @@ describe('model-status-label', () => {
     )
   })
 
-  it('always surfaces the effort (default medium) so the level is visible', () => {
+  it('falls back to the profile default effort, then to medium', () => {
     expect(formatModelStatusLabel('openai/gpt-5.5', { reasoningEffort: 'medium' })).toBe('GPT-5.5 · Med')
     expect(formatModelStatusLabel('openai/gpt-5.5')).toBe('GPT-5.5 · Med')
+    // No session-level effort → the configured profile default is advertised,
+    // not Hermes' built-in medium.
+    expect(formatModelStatusLabel('openai/gpt-5.5', { defaultEffort: 'high' })).toBe('GPT-5.5 · High')
+    // An explicit session effort still wins over the profile default.
+    expect(formatModelStatusLabel('openai/gpt-5.5', { defaultEffort: 'high', reasoningEffort: 'low' })).toBe(
+      'GPT-5.5 · Low'
+    )
   })
 
   it('returns just the placeholder name when there is no model', () => {
@@ -48,19 +51,23 @@ describe('model-status-label', () => {
     const options = { model: 'hermes-4', provider: 'nous' }
 
     it('prefers the sticky composer pick over the profile default pre-session', () => {
-      expect(currentPickerSelection(false, store, options)).toEqual(store)
+      expect(currentPickerSelection(store, options)).toEqual(store)
     })
 
-    it('lets the live session model.options win when a session exists', () => {
-      expect(currentPickerSelection(true, store, options)).toEqual(options)
+    it('keeps the SessionView selection when a stale options response disagrees', () => {
+      expect(currentPickerSelection(store, options)).toEqual(store)
     })
 
     it('falls back to options when the store is empty', () => {
-      expect(currentPickerSelection(false, { model: '', provider: '' }, options)).toEqual(options)
+      expect(currentPickerSelection({ model: '', provider: '' }, options)).toEqual(options)
+    })
+
+    it('uses the complete options pair instead of mixing a partial store selection', () => {
+      expect(currentPickerSelection({ model: 'opus', provider: '' }, options)).toEqual(options)
     })
 
     it('falls back to the store while options are still loading', () => {
-      expect(currentPickerSelection(true, store, undefined)).toEqual(store)
+      expect(currentPickerSelection(store, undefined)).toEqual(store)
     })
   })
 })
diff --git a/apps/desktop/src/lib/model-status-label.ts b/apps/desktop/src/lib/model-status-label.ts
index a1b28b8a4c5..5dde20746f8 100644
--- a/apps/desktop/src/lib/model-status-label.ts
+++ b/apps/desktop/src/lib/model-status-label.ts
@@ -1,39 +1,35 @@
-import { normalize } from '@/lib/text'
+import { DEFAULT_REASONING_EFFORT, reasoningEffortLabel } from '@/lib/reasoning-effort'
 
-const REASONING_LABELS: Record<string, string> = {
-  none: 'Off',
-  minimal: 'Min',
-  low: 'Low',
-  medium: 'Med',
-  high: 'High',
-  xhigh: 'XHigh',
-  max: 'Max',
-  ultra: 'Ultra'
-}
-
-export function reasoningEffortLabel(effort: string): string {
-  const key = normalize(effort)
-
-  if (!key) {
-    return ''
-  }
-
-  return REASONING_LABELS[key] ?? effort
-}
-
-/** Which model/provider a picker should mark "current". With a live session the
- *  gateway's `model.options` is authoritative; pre-session there is no server
- *  "current", so the sticky composer pick wins over the profile default the
- *  global options query returns — else the checkmark snaps back to the default
- *  and the pick looks ignored. */
+/** Which model/provider pair a picker should mark "current". SessionView state
+ *  also drives the composer label, so a complete pair there wins over an older
+ *  `model.options` response. During initial hydration (or pre-session startup),
+ *  options remain the fallback. Pick one complete pair before mixing fields so
+ *  a model is never shown under a different provider. */
 export function currentPickerSelection(
-  hasSession: boolean,
   store: { model: string; provider: string },
   options?: { model?: string; provider?: string }
 ): { model: string; provider: string } {
+  const storeSelection = {
+    model: String(store.model || ''),
+    provider: String(store.provider || '')
+  }
+
+  const optionsSelection = {
+    model: String(options?.model || ''),
+    provider: String(options?.provider || '')
+  }
+
+  if (storeSelection.model && storeSelection.provider) {
+    return storeSelection
+  }
+
+  if (optionsSelection.model && optionsSelection.provider) {
+    return optionsSelection
+  }
+
   return {
-    model: String((hasSession && options?.model) || store.model || options?.model || ''),
-    provider: String((hasSession && options?.provider) || store.provider || options?.provider || '')
+    model: storeSelection.model || optionsSelection.model,
+    provider: storeSelection.provider || optionsSelection.provider
   }
 }
 
@@ -99,10 +95,12 @@ export function displayModelName(model: string): string {
   return modelDisplayParts(model).name
 }
 
-/** Status bar trigger label — model name plus the live session state (effort/fast). */
+/** Status bar trigger label — model name plus the live session state (effort/fast).
+ *  `defaultEffort` is the profile's configured level, used when the surface has
+ *  no explicit effort so the label never advertises a default the agent won't use. */
 export function formatModelStatusLabel(
   model: string,
-  options?: { fastMode?: boolean; reasoningEffort?: string }
+  options?: { defaultEffort?: string; fastMode?: boolean; reasoningEffort?: string }
 ): string {
   const name = displayModelName(model)
 
@@ -118,9 +116,9 @@ export function formatModelStatusLabel(
     parts.push('Fast')
   }
 
-  // Always surface the effort (empty = Hermes default of medium) so the
-  // current reasoning level is visible at a glance, not just when non-default.
-  parts.push(reasoningEffortLabel(options?.reasoningEffort ?? '') || 'Med')
+  // Always surface the effort so the current reasoning level is visible at a
+  // glance, not just when non-default.
+  parts.push(reasoningEffortLabel(options?.reasoningEffort || options?.defaultEffort || DEFAULT_REASONING_EFFORT))
 
   return `${name} · ${parts.join(' ')}`
 }
diff --git a/apps/desktop/src/lib/reasoning-effort.test.ts b/apps/desktop/src/lib/reasoning-effort.test.ts
new file mode 100644
index 00000000000..bc61b91fb9b
--- /dev/null
+++ b/apps/desktop/src/lib/reasoning-effort.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  DEFAULT_REASONING_EFFORT,
+  isReasoningEffort,
+  isThinkingEnabled,
+  REASONING_EFFORT_VALUES,
+  REASONING_EFFORTS,
+  reasoningEffortLabel,
+  resolveReasoningEffort
+} from './reasoning-effort'
+
+describe('reasoning-effort', () => {
+  it('keeps the scale ascending and `none` off it', () => {
+    expect(REASONING_EFFORTS).not.toContain('none')
+    expect(REASONING_EFFORT_VALUES[0]).toBe('none')
+    expect(REASONING_EFFORT_VALUES).toHaveLength(REASONING_EFFORTS.length + 1)
+  })
+
+  it('labels every level it claims to support', () => {
+    for (const effort of REASONING_EFFORT_VALUES) {
+      expect(reasoningEffortLabel(effort)).not.toBe('')
+    }
+
+    expect(reasoningEffortLabel('')).toBe('')
+    // Unknown values pass through rather than silently reading as a real level.
+    expect(reasoningEffortLabel('bogus')).toBe('bogus')
+  })
+
+  it('recognizes only real scale levels', () => {
+    expect(isReasoningEffort(DEFAULT_REASONING_EFFORT)).toBe(true)
+    expect(isReasoningEffort('HIGH')).toBe(true)
+    expect(isReasoningEffort('none')).toBe(false)
+    expect(isReasoningEffort('bogus')).toBe(false)
+  })
+
+  it('treats empty as inherit and only `none` as off', () => {
+    expect(isThinkingEnabled('none')).toBe(false)
+    expect(isThinkingEnabled('high')).toBe(true)
+    // Empty inherits the fallback, so an off fallback reads as off.
+    expect(isThinkingEnabled('', 'none')).toBe(false)
+    expect(isThinkingEnabled('', 'high')).toBe(true)
+  })
+
+  it('resolves a scale value: inherit, off, or clamp', () => {
+    expect(resolveReasoningEffort('high')).toBe('high')
+    // Empty inherits the profile default rather than snapping to medium.
+    expect(resolveReasoningEffort('', 'ultra')).toBe('ultra')
+    // Off selects nothing on the scale.
+    expect(resolveReasoningEffort('none')).toBe('')
+    expect(resolveReasoningEffort('bogus')).toBe(DEFAULT_REASONING_EFFORT)
+  })
+})
diff --git a/apps/desktop/src/lib/reasoning-effort.ts b/apps/desktop/src/lib/reasoning-effort.ts
new file mode 100644
index 00000000000..5d3e17afd05
--- /dev/null
+++ b/apps/desktop/src/lib/reasoning-effort.ts
@@ -0,0 +1,54 @@
+import { normalize } from '@/lib/text'
+
+/** Hermes' reasoning levels, in ascending order — mirrors the backend's
+ *  VALID_REASONING_EFFORTS (hermes_constants.py). `none` is not a level: it's
+ *  thinking disabled, owned by the Thinking toggle rather than the scale. */
+export const REASONING_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'] as const
+
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number]
+
+/** The scale plus the off state — the full set a config value may hold. */
+export const REASONING_EFFORT_VALUES = ['none', ...REASONING_EFFORTS] as const
+
+/** Hermes' built-in level when neither the surface nor the profile config
+ *  specifies one (mirrors the backend's own fallback). */
+export const DEFAULT_REASONING_EFFORT: ReasoningEffort = 'medium'
+
+/** Compact labels for chrome where space is tight (pill, picker rows). Menus
+ *  and settings use the translated `shell.modelOptions` strings instead. */
+const SHORT_LABELS: Record<string, string> = {
+  none: 'Off',
+  minimal: 'Min',
+  low: 'Low',
+  medium: 'Med',
+  high: 'High',
+  xhigh: 'XHigh',
+  max: 'Max',
+  ultra: 'Ultra'
+}
+
+export function reasoningEffortLabel(effort: string): string {
+  const key = normalize(effort)
+
+  return key ? (SHORT_LABELS[key] ?? effort) : ''
+}
+
+export const isReasoningEffort = (value: string): value is ReasoningEffort =>
+  REASONING_EFFORTS.includes(normalize(value) as ReasoningEffort)
+
+/** Thinking is on unless a level explicitly says otherwise; an empty value
+ *  means "inherit", so it resolves through `fallback` first. */
+export const isThinkingEnabled = (effort: string, fallback: string = DEFAULT_REASONING_EFFORT): boolean =>
+  normalize(effort || fallback) !== 'none'
+
+/** The level a scale control should show. Empty inherits `fallback`; `none`
+ *  (thinking off) selects nothing; anything unrecognized clamps to the default. */
+export function resolveReasoningEffort(effort: string, fallback: string = DEFAULT_REASONING_EFFORT): string {
+  const value = normalize(effort || fallback)
+
+  if (value === 'none') {
+    return ''
+  }
+
+  return isReasoningEffort(value) ? value : DEFAULT_REASONING_EFFORT
+}
diff --git a/apps/desktop/src/lib/session-date-groups.test.ts b/apps/desktop/src/lib/session-date-groups.test.ts
new file mode 100644
index 00000000000..1bcaf587ece
--- /dev/null
+++ b/apps/desktop/src/lib/session-date-groups.test.ts
@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'vitest'
+
+import type { SessionInfo } from '@/types/hermes'
+
+import type { SidebarSessionEntry } from './session-branch-tree'
+import { groupEntriesByRecency, toSessionRows } from './session-date-groups'
+
+const session = (id: string, overrides: Partial<SessionInfo> = {}): SessionInfo =>
+  ({
+    ended_at: null,
+    id,
+    input_tokens: 0,
+    is_active: false,
+    last_active: 0,
+    message_count: 1,
+    model: null,
+    output_tokens: 0,
+    preview: null,
+    source: 'cli',
+    started_at: 0,
+    title: id,
+    tool_call_count: 0,
+    ...overrides
+  }) as SessionInfo
+
+const entry = (s: SessionInfo, branchStem?: string): SidebarSessionEntry =>
+  branchStem ? { branchStem, session: s } : { session: s }
+
+// Fixed "now": Thursday 18 Jun 2026, local noon (15 Jun 2026 is a Monday).
+// All tests pin a Monday week start so calendar boundaries are deterministic.
+const NOW = new Date(2026, 5, 18, 12, 0, 0).getTime()
+const MONDAY = 1
+
+const at = (year: number, month: number, day: number, hour = 10, minute = 0): number =>
+  Math.floor(new Date(year, month, day, hour, minute, 0).getTime() / 1000)
+
+const group = (entries: SidebarSessionEntry[], nowMs = NOW) => groupEntriesByRecency(entries, nowMs, MONDAY)
+
+const dividerKeys = (rows: ReturnType<typeof groupEntriesByRecency>): string[] =>
+  rows.flatMap(row => (row.kind === 'divider' ? [row.key] : []))
+
+describe('groupEntriesByRecency', () => {
+  it('cuts the head after the most recent handful, then divides by coarse ranges', () => {
+    // The morning run (30m/30m/4h/30m gaps, then a 14h silence) is the
+    // unlabelled head; each older group gets one divider, coarsening with age.
+    const rows = group([
+      entry(session('a', { last_active: at(2026, 5, 18, 11) })),
+      entry(session('b', { last_active: at(2026, 5, 18, 10, 30) })),
+      entry(session('c', { last_active: at(2026, 5, 18, 10) })),
+      entry(session('d', { last_active: at(2026, 5, 18, 6) })),
+      entry(session('e', { last_active: at(2026, 5, 18, 5, 30) })),
+      entry(session('f', { last_active: at(2026, 5, 17, 15) })), // yesterday
+      entry(session('g', { last_active: at(2026, 5, 16, 15) })), // Tue this week
+      entry(session('h', { last_active: at(2026, 5, 14) })), // Sun last week
+      entry(session('i', { last_active: at(2026, 5, 3) })), // earlier in June
+      entry(session('j', { last_active: at(2026, 4, 28) })), // May
+      entry(session('k', { last_active: at(2025, 11, 3) })) // December 2025
+    ])
+
+    expect(rows.slice(0, 5).every(row => row.kind === 'session')).toBe(true)
+    expect(rows[5]).toMatchObject({ key: 'yesterday', kind: 'divider' })
+    expect(dividerKeys(rows)).toEqual(['yesterday', 'this-week', 'last-week', 'this-month', 'm-2026-4', 'my-2025-11'])
+  })
+
+  it('labels the rest of the current day "earlier today" past a real break', () => {
+    // Five rapid-fire sessions, a ~4h pause, then more of the same day.
+    const rows = group([
+      entry(session('a', { last_active: at(2026, 5, 18, 11) })),
+      entry(session('b', { last_active: at(2026, 5, 18, 10, 58) })),
+      entry(session('c', { last_active: at(2026, 5, 18, 10, 56) })),
+      entry(session('d', { last_active: at(2026, 5, 18, 10, 54) })),
+      entry(session('e', { last_active: at(2026, 5, 18, 10, 52) })),
+      entry(session('f', { last_active: at(2026, 5, 18, 7) })),
+      entry(session('g', { last_active: at(2026, 5, 18, 6, 58) }))
+    ])
+
+    expect(rows.findIndex(row => row.kind === 'divider')).toBe(5)
+    expect(dividerKeys(rows)).toEqual(['today'])
+  })
+
+  it('never slices a rapid-fire burst mid-run', () => {
+    // Eleven sessions two minutes apart: no gap qualifies as a break, so the
+    // whole burst stays in the head and the divider lands after it.
+    const burst = Array.from({ length: 11 }, (_, i) =>
+      entry(session(`s${i}`, { last_active: at(2026, 5, 18, 11) - i * 120 }))
+    )
+
+    const rows = group([...burst, entry(session('old', { last_active: at(2026, 5, 17, 15) }))])
+
+    expect(rows.findIndex(row => row.kind === 'divider')).toBe(11)
+    expect(dividerKeys(rows)).toEqual(['yesterday'])
+  })
+
+  it('chains the head run across midnight', () => {
+    // Viewed at 00:58: tonight plus last evening is one run; yesterday's
+    // afternoon (a different nominal day) opens the labelled groups.
+    const smallHours = new Date(2026, 5, 19, 0, 58).getTime()
+
+    const rows = group(
+      [
+        entry(session('a', { last_active: at(2026, 5, 19, 0, 30) })),
+        entry(session('b', { last_active: at(2026, 5, 18, 23, 50) })),
+        entry(session('c', { last_active: at(2026, 5, 18, 23, 20) })),
+        entry(session('d', { last_active: at(2026, 5, 17, 20) }))
+      ],
+      smallHours
+    )
+
+    expect(rows.findIndex(row => row.kind === 'divider')).toBe(3)
+    expect(dividerKeys(rows)).toEqual(['yesterday'])
+  })
+
+  it('dissolves a stale head into its own calendar group (fuzzy merge)', () => {
+    // Newest session is 6 days old and the rows below it share its "last week"
+    // bucket: cutting there would strand near-identical neighbours around a
+    // divider, so no head is kept and the whole bucket leads unlabelled.
+    const rows = group([
+      entry(session('a', { last_active: at(2026, 5, 12) })),
+      entry(session('b', { last_active: at(2026, 5, 11, 15) })),
+      entry(session('c', { last_active: at(2026, 5, 11, 10) })),
+      entry(session('d', { last_active: at(2026, 5, 3) })),
+      entry(session('e', { last_active: at(2026, 4, 20) }))
+    ])
+
+    expect(rows.slice(0, 3).every(row => row.kind === 'session')).toBe(true)
+    expect(dividerKeys(rows)).toEqual(['this-month', 'm-2026-4'])
+  })
+
+  it('keeps an isolated newest session as the head when its bucket differs', () => {
+    const rows = group([
+      entry(session('a', { last_active: at(2026, 5, 18, 9) })),
+      entry(session('b', { last_active: at(2026, 5, 17, 15) })),
+      entry(session('c', { last_active: at(2026, 5, 3) }))
+    ])
+
+    expect(rows.findIndex(row => row.kind === 'divider')).toBe(1)
+    expect(dividerKeys(rows)).toEqual(['yesterday', 'this-month'])
+  })
+
+  it('emits no dividers when everything is one unbroken run', () => {
+    const rows = group([
+      entry(session('a', { last_active: at(2026, 5, 18, 11) })),
+      entry(session('b', { last_active: at(2026, 5, 18, 10, 50) })),
+      entry(session('c', { last_active: at(2026, 5, 18, 10, 40) }))
+    ])
+
+    expect(rows.every(row => row.kind === 'session')).toBe(true)
+  })
+
+  it('collapses a big gap straight to the next month/year (empty ranges omitted)', () => {
+    const rows = group([
+      entry(session('t', { last_active: at(2026, 5, 18, 11) })),
+      entry(session('t2', { last_active: at(2026, 5, 18, 10, 30) })),
+      entry(session('j1', { last_active: at(2026, 0, 5) })),
+      entry(session('j2', { last_active: at(2026, 0, 3) })),
+      entry(session('old', { last_active: at(2024, 2, 9) }))
+    ])
+
+    expect(dividerKeys(rows)).toEqual(['m-2026-0', 'my-2024-2'])
+  })
+
+  it('never labels the first rendered group, even when it is not recent', () => {
+    // Newest session is weeks old and alone in its month: it opens the list
+    // unlabelled; only the transitions below it are marked.
+    const rows = group([
+      entry(session('a', { last_active: at(2026, 4, 20) })),
+      entry(session('b', { last_active: at(2026, 2, 3) })),
+      entry(session('c', { last_active: at(2025, 11, 3) }))
+    ])
+
+    expect(rows[0]).toMatchObject({ kind: 'session' })
+    expect(dividerKeys(rows)).toEqual(['m-2026-2', 'my-2025-11'])
+  })
+
+  it('keeps branch children in their parent cluster without opening a new bucket', () => {
+    const parent = session('parent', { last_active: at(2026, 5, 18, 11) })
+    const child = session('child', { last_active: at(2024, 0, 1), parent_session_id: 'parent' })
+
+    const rows = group([entry(parent), entry(child, '└─ ')])
+
+    expect(rows).toEqual([
+      { entry: entry(parent), kind: 'session' },
+      { entry: entry(child, '└─ '), kind: 'session' }
+    ])
+  })
+
+  it('never emits a divider twice under a non-monotonic order', () => {
+    const rows = group([
+      entry(session('a', { last_active: at(2026, 5, 16) })), // head run
+      entry(session('b', { last_active: at(2026, 4, 5) })), // May — divider
+      entry(session('c', { last_active: at(2026, 5, 16) })) // head again — no repeat
+    ])
+
+    expect(dividerKeys(rows)).toEqual(['m-2026-4'])
+  })
+
+  it('falls back to started_at when last_active is missing', () => {
+    const rows = group([
+      entry(session('head', { last_active: at(2026, 5, 18, 11) })),
+      entry(session('s', { last_active: 0, started_at: at(2026, 5, 10) }))
+    ])
+
+    expect(dividerKeys(rows)).toEqual(['last-week'])
+  })
+})
+
+describe('toSessionRows', () => {
+  it('wraps entries as session rows with no dividers', () => {
+    const entries = [entry(session('a')), entry(session('b'), '└─ ')]
+
+    expect(toSessionRows(entries)).toEqual([
+      { entry: entries[0], kind: 'session' },
+      { entry: entries[1], kind: 'session' }
+    ])
+  })
+})
diff --git a/apps/desktop/src/lib/session-date-groups.ts b/apps/desktop/src/lib/session-date-groups.ts
new file mode 100644
index 00000000000..13a5e642c28
--- /dev/null
+++ b/apps/desktop/src/lib/session-date-groups.ts
@@ -0,0 +1,151 @@
+import { type SidebarSessionEntry } from '@/lib/session-branch-tree'
+import { calendarBucket, HOUR, localeWeekStartDay, MINUTE, SECOND, type SessionBucket } from '@/lib/time'
+
+// A flat list row is either a chronological date-bucket divider or a session
+// entry. Interleaving these lets the flat list (and the virtualizer) render
+// date separators inline without a second layer of nesting.
+export type SidebarListRow =
+  | { bucket: SessionBucket; key: string; kind: 'divider' }
+  | { entry: SidebarSessionEntry; kind: 'session' }
+
+// The row's own age label reads from `last_active || started_at`; bucket off the
+// same value so a divider lines up with what the row actually shows.
+const recencyMs = (entry: SidebarSessionEntry): number =>
+  (entry.session.last_active || entry.session.started_at || 0) * SECOND
+
+// Aim the head at "the most recent handful". A break shorter than
+// MIN_RUN_BREAK_MS never counts as one — that would slice a rapid-fire burst —
+// and a silence longer than MAX_RUN_GAP_MS always ends the run: without that
+// bound a sparse list (a project lane) would chain weeks of stale sessions
+// into one giant "recent" head.
+const TARGET_HEAD_SESSIONS = 5
+const MIN_RUN_BREAK_MS = 30 * MINUTE
+const MAX_RUN_GAP_MS = 8 * HOUR
+
+// The unlabelled head is the newest run of sessions, cut at a *real* break in
+// activity. Candidate cut points are every gap of at least MIN_RUN_BREAK_MS
+// inside the contiguous run (gaps ≤ MAX_RUN_GAP_MS), plus the run's own end;
+// among them we pick the one whose head size lands closest (log-scale) to
+// TARGET_HEAD_SESSIONS. So the first divider shows up after roughly the most
+// recent five sessions — but only ever at a genuine pause, never mid-burst: a
+// truly unbroken run stays whole, and an isolated newest session stands alone.
+// Runs chain naturally across midnight.
+//
+// Fuzzy-merge rule: when the cut falls at the run's end and the sessions just
+// below it share the head's calendar bucket, the head adds nothing — it's just
+// the top of that group. Dissolve it (the first-group rule keeps the top
+// unlabelled anyway) so a divider never strands near-identical neighbours,
+// e.g. a lone 6-day-old session above a "Last week" label.
+//
+// Returns the oldest timestamp (ms) still inside the head; -Infinity means the
+// whole list is one run, +Infinity means no head (calendar groups own it all).
+function headRunCutoffMs(entries: readonly SidebarSessionEntry[], nowMs: number, weekStartsOn: number): number {
+  const times = entries
+    .filter(entry => !entry.branchStem)
+    .map(recencyMs)
+    .sort((a, b) => b - a)
+
+  let bestIdx = -1
+  let bestScore = Number.POSITIVE_INFINITY
+  let runEnded = false
+
+  for (let i = 1; i < times.length; i++) {
+    const gap = times[i - 1] - times[i]
+    const endsRun = gap > MAX_RUN_GAP_MS
+
+    if (gap >= MIN_RUN_BREAK_MS || endsRun) {
+      // `i` sessions would sit above a cut at this gap.
+      const score = Math.abs(Math.log(i / TARGET_HEAD_SESSIONS))
+
+      if (score < bestScore) {
+        bestScore = score
+        bestIdx = i
+        runEnded = endsRun
+      }
+    }
+
+    if (endsRun) {
+      break
+    }
+  }
+
+  if (bestIdx === -1) {
+    return Number.NEGATIVE_INFINITY
+  }
+
+  if (runEnded) {
+    const headBucket = calendarBucket(times[0] / SECOND, nowMs, weekStartsOn)
+    const belowBucket = calendarBucket(times[bestIdx] / SECOND, nowMs, weekStartsOn)
+
+    if (headBucket.key === belowBucket.key) {
+      return Number.POSITIVE_INFINITY
+    }
+  }
+
+  return times[bestIdx - 1]
+}
+
+// Insert a date divider before each labelled group. The unlabelled head is the
+// newest run of sessions (see headRunCutoffMs); below it, groups are coarse
+// calendar ranges — earlier today → yesterday → earlier this week → last week
+// → earlier this month → month → month + year — one divider per range, never
+// one per day. Whatever group happens to render first is also never labelled.
+// Branch children inherit their parent cluster's group and never trigger a
+// divider, so a parent→branches block never splits.
+export function groupEntriesByRecency(
+  entries: readonly SidebarSessionEntry[],
+  nowMs = Date.now(),
+  weekStartsOn = localeWeekStartDay()
+): SidebarListRow[] {
+  const rows: SidebarListRow[] = []
+  const emitted = new Set<string>()
+  const cutoff = headRunCutoffMs(entries, nowMs, weekStartsOn)
+  let lastKey: null | string = null
+
+  for (const entry of entries) {
+    // Nested branch rows travel with their parent cluster; they never open a new
+    // bucket or move the divider cursor.
+    if (entry.branchStem) {
+      rows.push({ entry, kind: 'session' })
+
+      continue
+    }
+
+    const ms = recencyMs(entry)
+
+    // Head-run sessions are never labelled.
+    if (ms >= cutoff) {
+      rows.push({ entry, kind: 'session' })
+      lastKey = '__recent__'
+
+      continue
+    }
+
+    const bucket = calendarBucket(ms / SECOND, nowMs, weekStartsOn)
+
+    if (bucket.key !== lastKey) {
+      lastKey = bucket.key
+      const alreadyEmitted = emitted.has(bucket.key)
+
+      // Mark it emitted even when skipped so a non-monotonic order (possible
+      // inside a project lane) can't later re-label it or collide React keys.
+      emitted.add(bucket.key)
+
+      // A divider only ever separates two groups — never label the very first
+      // rendered row, whatever group it belongs to.
+      if (rows.length > 0 && !alreadyEmitted) {
+        rows.push({ bucket, key: bucket.key, kind: 'divider' })
+      }
+    }
+
+    rows.push({ entry, kind: 'session' })
+  }
+
+  return rows
+}
+
+// Wrap entries as plain session rows (no dividers) so the ungrouped path shares
+// the same `SidebarListRow[]` shape as the grouped one.
+export function toSessionRows(entries: readonly SidebarSessionEntry[]): SidebarListRow[] {
+  return entries.map(entry => ({ entry, kind: 'session' }))
+}
diff --git a/apps/desktop/src/lib/session-link-title.test.ts b/apps/desktop/src/lib/session-link-title.test.ts
new file mode 100644
index 00000000000..5efa8ba3efd
--- /dev/null
+++ b/apps/desktop/src/lib/session-link-title.test.ts
@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { getSession } from '@/hermes'
+import { $sessions } from '@/store/session'
+import type { SessionInfo } from '@/types/hermes'
+
+import { __resetSessionLinkTitleCache, fetchSessionLinkTitle, lookupLocalSessionTitle } from './session-link-title'
+import { sessionRefCacheKey } from './session-refs'
+
+vi.mock('@/hermes', () => ({
+  getSession: vi.fn()
+}))
+
+function makeSession(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    ended_at: null,
+    id: '20260101_abc123',
+    input_tokens: 0,
+    is_active: false,
+    last_active: 1_000,
+    message_count: 1,
+    model: null,
+    output_tokens: 0,
+    preview: null,
+    profile: 'default',
+    source: 'cli',
+    started_at: 1_000,
+    title: 'Research notes',
+    tool_call_count: 0,
+    ...overrides
+  }
+}
+
+afterEach(() => {
+  __resetSessionLinkTitleCache()
+  $sessions.set([])
+  vi.mocked(getSession).mockReset()
+})
+
+describe('lookupLocalSessionTitle', () => {
+  it('reads from the in-memory session list', () => {
+    $sessions.set([makeSession({ profile: 'work', title: 'Branch plan' })])
+
+    expect(lookupLocalSessionTitle('work/20260101_abc123')).toBe('Branch plan')
+  })
+
+  it('matches the lineage root so a compressed chat still resolves', () => {
+    $sessions.set([makeSession({ _lineage_root_id: '20260101_abc123', id: '20260102_tip', title: 'Compressed chat' })])
+
+    expect(lookupLocalSessionTitle('20260101_abc123')).toBe('Compressed chat')
+  })
+
+  it('ignores a same-id row owned by another profile', () => {
+    $sessions.set([makeSession({ profile: 'work', title: 'Work chat' })])
+
+    expect(lookupLocalSessionTitle('personal/20260101_abc123')).toBe('')
+  })
+
+  it('returns empty for an untitled row so the caller can fall back to the id', () => {
+    $sessions.set([makeSession({ preview: null, title: null })])
+
+    expect(lookupLocalSessionTitle('default/20260101_abc123')).toBe('')
+  })
+})
+
+describe('fetchSessionLinkTitle', () => {
+  it('dedupes concurrent lookups', async () => {
+    vi.mocked(getSession).mockResolvedValue(makeSession({ title: 'From API' }))
+
+    const value = 'default/20260101_abc123'
+    const [first, second] = await Promise.all([fetchSessionLinkTitle(value), fetchSessionLinkTitle(value)])
+
+    expect(first).toBe('From API')
+    expect(second).toBe('From API')
+    expect(getSession).toHaveBeenCalledTimes(1)
+    expect(getSession).toHaveBeenCalledWith('20260101_abc123', 'default')
+  })
+
+  it('uses the local sidebar row before calling the API', async () => {
+    $sessions.set([makeSession({ title: 'Cached title' })])
+
+    await expect(fetchSessionLinkTitle('default/20260101_abc123')).resolves.toBe('Cached title')
+    expect(getSession).not.toHaveBeenCalled()
+  })
+
+  it('keeps separate cache entries per profile', async () => {
+    vi.mocked(getSession).mockImplementation(async (id, profile) =>
+      makeSession({ id, profile: profile ?? 'default', title: profile === 'work' ? 'Work chat' : 'Home chat' })
+    )
+
+    await expect(fetchSessionLinkTitle('default/20260101_abc123')).resolves.toBe('Home chat')
+    await expect(fetchSessionLinkTitle('work/20260101_abc123')).resolves.toBe('Work chat')
+    expect(sessionRefCacheKey('default/20260101_abc123')).not.toBe(sessionRefCacheKey('work/20260101_abc123'))
+  })
+
+  it('falls back to the preview when the session has no title', async () => {
+    vi.mocked(getSession).mockResolvedValue(makeSession({ preview: 'Summarize this repo', title: null }))
+
+    await expect(fetchSessionLinkTitle('20260101_abc123')).resolves.toBe('Summarize this repo')
+  })
+
+  it('resolves empty when the id is not on this backend', async () => {
+    vi.mocked(getSession).mockRejectedValue(new Error('Session not found'))
+
+    await expect(fetchSessionLinkTitle('default/missing')).resolves.toBe('')
+  })
+
+  it('resolves empty when the desktop bridge is unavailable', async () => {
+    vi.mocked(getSession).mockImplementation(() => {
+      throw new TypeError("Cannot read properties of undefined (reading 'api')")
+    })
+
+    await expect(fetchSessionLinkTitle('default/20260101_abc123')).resolves.toBe('')
+  })
+})
diff --git a/apps/desktop/src/lib/session-link-title.ts b/apps/desktop/src/lib/session-link-title.ts
new file mode 100644
index 00000000000..27aff91002f
--- /dev/null
+++ b/apps/desktop/src/lib/session-link-title.ts
@@ -0,0 +1,143 @@
+/**
+ * Resolves `@session:<profile>/<id>` reference values to the session's title.
+ *
+ * Same shape as the external-link title resolver (`external-link.tsx`): a
+ * process-lifetime cache, in-flight dedupe, and subscribers so every chip for
+ * the same session repaints off one lookup. The sidebar list answers most
+ * lookups for free; only an unknown id costs a REST round-trip.
+ */
+import { useEffect, useMemo, useState } from 'react'
+
+import { getSession } from '@/hermes'
+import { parseSessionRefValue, sessionRefCacheKey, sessionRefFallbackLabel } from '@/lib/session-refs'
+import { $sessions, sessionMatchesStoredId } from '@/store/session'
+import type { SessionInfo } from '@/types/hermes'
+
+const titleCache = new Map<string, string>()
+const titleInflight = new Map<string, Promise<string>>()
+const titleSubs = new Map<string, Set<(value: string) => void>>()
+
+/** Deliberately not `sessionTitle()` from chat-runtime: its "Untitled session"
+ *  fallback is a worse chip label than the short id, so an untitled row
+ *  resolves to empty and the caller's fallback wins. */
+function sessionRowTitle(row: SessionInfo): string {
+  return row.title?.trim() || row.preview?.trim() || ''
+}
+
+function profileMatches(sessionProfile: null | string | undefined, target?: string): boolean {
+  if (!target) {
+    return true
+  }
+
+  return ((sessionProfile ?? '').trim() || 'default') === (target.trim() || 'default')
+}
+
+export function lookupLocalSessionTitle(value: string): string {
+  const { profile, sessionId } = parseSessionRefValue(value)
+
+  if (!sessionId) {
+    return ''
+  }
+
+  const row = $sessions
+    .get()
+    .find(session => sessionMatchesStoredId(session, sessionId) && profileMatches(session.profile, profile))
+
+  return row ? sessionRowTitle(row) : ''
+}
+
+/** REST lookup that can't throw: the bridge is absent outside Electron, and a
+ *  session id that isn't on this backend 404s. Both mean "no title". */
+function requestSessionRow(sessionId: string, profile?: string): Promise<null | SessionInfo> {
+  try {
+    return Promise.resolve(getSession(sessionId, profile ?? null)).catch(() => null)
+  } catch {
+    return Promise.resolve(null)
+  }
+}
+
+export function fetchSessionLinkTitle(value: string): Promise<string> {
+  const key = sessionRefCacheKey(value)
+
+  if (!key) {
+    return Promise.resolve('')
+  }
+
+  const cached = titleCache.get(key)
+
+  if (cached !== undefined) {
+    return Promise.resolve(cached)
+  }
+
+  const inflight = titleInflight.get(key)
+
+  if (inflight) {
+    return inflight
+  }
+
+  const local = lookupLocalSessionTitle(value)
+
+  if (local) {
+    titleCache.set(key, local)
+
+    return Promise.resolve(local)
+  }
+
+  const { profile, sessionId } = parseSessionRefValue(value)
+
+  const promise = requestSessionRow(sessionId, profile)
+    .then(row => (row ? sessionRowTitle(row) : ''))
+    .then(title => {
+      titleCache.set(key, title)
+      titleInflight.delete(key)
+      titleSubs.get(key)?.forEach(notify => notify(title))
+
+      return title
+    })
+
+  titleInflight.set(key, promise)
+
+  return promise
+}
+
+export function useSessionLinkTitle(value: string, fallbackLabel?: string): string {
+  const key = useMemo(() => sessionRefCacheKey(value), [value])
+  const fallback = fallbackLabel?.trim() || sessionRefFallbackLabel(value)
+  const [title, setTitle] = useState(() => (key ? titleCache.get(key) || lookupLocalSessionTitle(value) : ''))
+
+  useEffect(() => {
+    if (!key) {
+      return
+    }
+
+    const known = titleCache.get(key) || lookupLocalSessionTitle(value)
+
+    setTitle(known)
+
+    if (known) {
+      return
+    }
+
+    const subs = titleSubs.get(key) ?? new Set<(resolved: string) => void>()
+
+    subs.add(setTitle)
+    titleSubs.set(key, subs)
+    void fetchSessionLinkTitle(value)
+
+    return () => {
+      subs.delete(setTitle)
+
+      if (!subs.size) {
+        titleSubs.delete(key)
+      }
+    }
+  }, [key, value])
+
+  return title || fallback
+}
+
+export function __resetSessionLinkTitleCache(): void {
+  titleCache.clear()
+  titleInflight.clear()
+  titleSubs.clear()
+}
diff --git a/apps/desktop/src/lib/session-refs.test.ts b/apps/desktop/src/lib/session-refs.test.ts
new file mode 100644
index 00000000000..5d4b1371a64
--- /dev/null
+++ b/apps/desktop/src/lib/session-refs.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+
+import { preprocessMarkdown } from './markdown-preprocess'
+import {
+  linkifySessionRefs,
+  parseSessionRefValue,
+  sessionMarkdownHref,
+  sessionRefCacheKey,
+  sessionRefFallbackLabel,
+  sessionRefFromMarkdownHref,
+  splitSessionRefValue
+} from './session-refs'
+
+describe('parseSessionRefValue', () => {
+  it('splits profile and session id', () => {
+    expect(parseSessionRefValue('work/20260101_abc123')).toEqual({
+      profile: 'work',
+      sessionId: '20260101_abc123'
+    })
+  })
+
+  it('treats bare values as session ids', () => {
+    expect(parseSessionRefValue('20260101_abc123')).toEqual({ sessionId: '20260101_abc123' })
+  })
+})
+
+describe('sessionRefFallbackLabel', () => {
+  it('truncates long ids', () => {
+    expect(sessionRefFallbackLabel('default/20260610_120000_abcdef')).toBe('20260610…')
+  })
+
+  it('leaves short ids alone', () => {
+    expect(sessionRefFallbackLabel('work/abc123')).toBe('abc123')
+  })
+})
+
+describe('sessionRefCacheKey', () => {
+  it('separates the same id across profiles', () => {
+    expect(sessionRefCacheKey('work/abc')).not.toBe(sessionRefCacheKey('home/abc'))
+  })
+
+  it('is empty for a valueless ref', () => {
+    expect(sessionRefCacheKey('  ')).toBe('')
+  })
+})
+
+describe('splitSessionRefValue', () => {
+  it('peels prose punctuation off a bare value', () => {
+    expect(splitSessionRefValue('default/abc123.')).toEqual({ trailing: '.', value: 'default/abc123' })
+  })
+
+  it('leaves a quoted value fenced', () => {
+    expect(splitSessionRefValue('`my session`')).toEqual({ trailing: '', value: 'my session' })
+  })
+})
+
+describe('session markdown hrefs', () => {
+  it('round-trips a value through the fragment href', () => {
+    const href = sessionMarkdownHref('work/20260101_abc123')
+
+    expect(href).toBe('#session/work%2F20260101_abc123')
+    expect(sessionRefFromMarkdownHref(href)).toBe('work/20260101_abc123')
+  })
+
+  it('ignores hrefs that are not session fragments', () => {
+    expect(sessionRefFromMarkdownHref('#preview/foo')).toBeNull()
+    expect(sessionRefFromMarkdownHref('https://example.com')).toBeNull()
+    expect(sessionRefFromMarkdownHref(undefined)).toBeNull()
+  })
+})
+
+describe('linkifySessionRefs', () => {
+  it('rewrites a bare ref into a session link', () => {
+    expect(linkifySessionRefs('see @session:work/20260101_abc123 next')).toBe(
+      'see [20260101…](#session/work%2F20260101_abc123) next'
+    )
+  })
+
+  it('keeps trailing prose punctuation outside the link', () => {
+    expect(linkifySessionRefs('see @session:default/abc123.')).toBe('see [abc123](#session/default%2Fabc123).')
+  })
+
+  it('leaves text without a ref untouched', () => {
+    const text = 'no references here'
+
+    expect(linkifySessionRefs(text)).toBe(text)
+  })
+
+  it('does not match an email-like or path-embedded @session', () => {
+    expect(linkifySessionRefs('me@session:abc')).toBe('me@session:abc')
+    expect(linkifySessionRefs('a/@session:abc')).toBe('a/@session:abc')
+  })
+
+  it('leaves a ref a model already wrapped in a markdown link alone', () => {
+    const text = '[that chat](@session:work/abc123)'
+
+    expect(linkifySessionRefs(text)).toBe(text)
+  })
+})
+
+// The agent-authored path: assistant markdown runs through preprocessMarkdown
+// before Streamdown, so a bare ref must survive as a link — and must NOT be
+// rewritten inside code, where it is being discussed rather than referenced.
+describe('preprocessMarkdown session refs', () => {
+  it('linkifies a ref in prose', () => {
+    expect(preprocessMarkdown('Context is in @session:work/20260101_abc123 there.')).toContain(
+      '[20260101…](#session/work%2F20260101_abc123)'
+    )
+  })
+
+  it('leaves refs inside inline code alone', () => {
+    const out = preprocessMarkdown('Type `@session:work/20260101_abc123` to link a chat.')
+
+    expect(out).toContain('`@session:work/20260101_abc123`')
+    expect(out).not.toContain('#session/')
+  })
+
+  it('leaves refs inside a fenced block alone', () => {
+    const out = preprocessMarkdown(['```text', '@session:work/20260101_abc123', '```'].join('\n'))
+
+    expect(out).toContain('@session:work/20260101_abc123')
+    expect(out).not.toContain('#session/')
+  })
+})
diff --git a/apps/desktop/src/lib/session-refs.ts b/apps/desktop/src/lib/session-refs.ts
new file mode 100644
index 00000000000..3ec9fbc62be
--- /dev/null
+++ b/apps/desktop/src/lib/session-refs.ts
@@ -0,0 +1,118 @@
+/**
+ * Pure helpers for `@session:<profile>/<id>` references.
+ *
+ * Kept free of React/store/API imports so the markdown preprocessor (a hot
+ * per-flush path) can use them without pulling in the resolver; the stateful
+ * title lookup lives in `session-link-title.ts`.
+ */
+
+/** Mirrors the composer/transcript form in `directive-text.tsx`: a bare value,
+ *  or one fenced in backticks/quotes so a value with spaces survives. The
+ *  lookbehinds keep `foo@session:` and URL paths from matching, and skip a ref
+ *  a model already wrapped in a markdown link — rewriting that would nest. */
+export const SESSION_REF_RE = /(?<![\w/])(?<!]\()@session:(`[^`\n]+`|"[^"\n]+"|'[^'\n]+'|\S+)/g
+
+const TRAILING_PUNCTUATION_RE = /[,.;:!?)\]}]+$/
+
+function unwrapQuotes(raw: string): null | string {
+  if (raw.length < 2) {
+    return null
+  }
+
+  const head = raw[0]
+  const tail = raw[raw.length - 1]
+
+  if ((head === '`' && tail === '`') || (head === '"' && tail === '"') || (head === "'" && tail === "'")) {
+    return raw.slice(1, -1)
+  }
+
+  return null
+}
+
+/** Splits a matched value into the reference itself and any prose punctuation
+ *  that the greedy `\S+` branch swallowed. Quoted values are already fenced. */
+export function splitSessionRefValue(raw: string): { trailing: string; value: string } {
+  const quoted = unwrapQuotes(raw)
+
+  if (quoted !== null) {
+    return { trailing: '', value: quoted }
+  }
+
+  const value = raw.replace(TRAILING_PUNCTUATION_RE, '')
+
+  return { trailing: raw.slice(value.length), value }
+}
+
+/** Session ids never contain a slash, so a slash unambiguously means
+ *  `<profile>/<id>` — same split as `tools/session_search_tool.py`. */
+export function parseSessionRefValue(value: string): { profile?: string; sessionId: string } {
+  const trimmed = value.trim()
+  const slash = trimmed.indexOf('/')
+
+  if (slash === -1) {
+    return { sessionId: trimmed }
+  }
+
+  const profile = trimmed.slice(0, slash).trim()
+  const sessionId = trimmed.slice(slash + 1).trim()
+
+  return sessionId ? { profile: profile || undefined, sessionId } : { sessionId: trimmed }
+}
+
+export function sessionRefCacheKey(value: string): string {
+  const { profile, sessionId } = parseSessionRefValue(value)
+
+  return sessionId ? `${profile ?? ''}/${sessionId}` : ''
+}
+
+/** Chip label before (or without) a resolved title — a short, still-identifying id. */
+export function sessionRefFallbackLabel(value: string): string {
+  const { sessionId } = parseSessionRefValue(value)
+
+  if (!sessionId) {
+    return value
+  }
+
+  return sessionId.length > 10 ? `${sessionId.slice(0, 8)}…` : sessionId
+}
+
+/** A fragment href, matching the `#preview/` convention in `preview-targets.ts`
+ *  — no custom URL scheme to survive markdown sanitization. */
+export function sessionMarkdownHref(value: string): string {
+  return `#session/${encodeURIComponent(value)}`
+}
+
+export function sessionRefFromMarkdownHref(href?: string): null | string {
+  if (!href?.startsWith('#session/')) {
+    return null
+  }
+
+  try {
+    return decodeURIComponent(href.slice('#session/'.length)) || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Rewrites bare `@session:<profile>/<id>` tokens into markdown links so an
+ * agent-authored reference reaches `MarkdownLink` and renders as a chip.
+ * Callers must exclude code spans/fences — `preprocessMarkdown` already does.
+ */
+export function linkifySessionRefs(text: string): string {
+  if (!text.includes('@session:')) {
+    return text
+  }
+
+  return text.replace(SESSION_REF_RE, (match, raw: string) => {
+    const { trailing, value } = splitSessionRefValue(raw)
+
+    if (!parseSessionRefValue(value).sessionId) {
+      return match
+    }
+
+    const label = sessionRefFallbackLabel(value).replace(/[[\]\\]/g, '\\$&')
+
+    return `[${label}](${sessionMarkdownHref(value)})${trailing}`
+  })
+}
diff --git a/apps/desktop/src/lib/time.test.ts b/apps/desktop/src/lib/time.test.ts
index 90523fe0bd4..f767934c58b 100644
--- a/apps/desktop/src/lib/time.test.ts
+++ b/apps/desktop/src/lib/time.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { DAY, formatAgo, HOUR, MINUTE, SECOND } from './time'
+import { calendarBucket, DAY, formatAgo, HOUR, MINUTE, nominalDayStart, SECOND, sessionBucketLabel } from './time'
 
 const labels = {
   ageNow: 'now',
@@ -30,3 +30,95 @@ describe('formatAgo', () => {
     expect(ago(-HOUR)).toBe('now')
   })
 })
+
+// Thursday 18 Jun 2026, local noon (15 Jun 2026 is a Monday).
+const THU_NOON = new Date(2026, 5, 18, 12, 0, 0).getTime()
+
+const secondsAt = (year: number, month: number, day: number, hour = 10) =>
+  Math.floor(new Date(year, month, day, hour, 0, 0).getTime() / 1000)
+
+describe('nominalDayStart', () => {
+  it('rolls the day boundary at 4 AM, not midnight', () => {
+    // 1 AM Saturday still belongs to Friday's run.
+    expect(nominalDayStart(new Date(2026, 5, 20, 1, 30).getTime())).toBe(new Date(2026, 5, 19).getTime())
+    expect(nominalDayStart(new Date(2026, 5, 20, 4, 30).getTime())).toBe(new Date(2026, 5, 20).getTime())
+  })
+})
+
+describe('calendarBucket', () => {
+  // Monday week start: the current week began Mon 15 Jun, last week is Jun 8-14.
+  const MONDAY = 1
+
+  const kindAt = (year: number, month: number, day: number, hour = 10) =>
+    calendarBucket(secondsAt(year, month, day, hour), THU_NOON, MONDAY).kind
+
+  it('buckets the current day (and, defensively, the future) as today', () => {
+    // The head run normally absorbs these; "Earlier today" covers the rest.
+    expect(kindAt(2026, 5, 18, 5)).toBe('today')
+    expect(kindAt(2026, 5, 18, 23)).toBe('today')
+    expect(kindAt(2026, 5, 19)).toBe('today')
+  })
+
+  it('assigns the small hours to the previous evening', () => {
+    // 1 AM today (before the 4 AM rollover) is part of yesterday's run.
+    expect(kindAt(2026, 5, 18, 1)).toBe('yesterday')
+
+    // And viewed at 00:58, last evening's sessions are still the current day.
+    const smallHours = new Date(2026, 5, 19, 0, 58).getTime()
+
+    expect(calendarBucket(secondsAt(2026, 5, 18, 23), smallHours, MONDAY).kind).toBe('today')
+    expect(calendarBucket(secondsAt(2026, 5, 18, 10), smallHours, MONDAY).kind).toBe('today')
+    expect(calendarBucket(secondsAt(2026, 5, 17, 15), smallHours, MONDAY).kind).toBe('yesterday')
+  })
+
+  it('uses coarse, non-overlapping ranges that coarsen with age', () => {
+    expect(kindAt(2026, 5, 17)).toBe('yesterday')
+    expect(kindAt(2026, 5, 16)).toBe('thisWeek') // Tue this week
+    expect(kindAt(2026, 5, 15)).toBe('thisWeek') // Mon this week
+    expect(kindAt(2026, 5, 14)).toBe('lastWeek') // Sun last week
+    expect(kindAt(2026, 5, 8)).toBe('lastWeek') // Mon last week
+    expect(kindAt(2026, 5, 7)).toBe('thisMonth') // earlier in June
+    expect(kindAt(2026, 5, 1)).toBe('thisMonth')
+    expect(kindAt(2026, 4, 28)).toBe('month') // May, same year
+    expect(kindAt(2025, 11, 3)).toBe('monthYear') // December, prior year
+  })
+
+  it('respects a Sunday week start', () => {
+    // With the week starting Sun 14 Jun, that Sunday is this week, not last.
+    expect(calendarBucket(secondsAt(2026, 5, 14), THU_NOON, 0).kind).toBe('thisWeek')
+    expect(calendarBucket(secondsAt(2026, 5, 13), THU_NOON, 0).kind).toBe('lastWeek')
+  })
+
+  it('keys same-month sessions together and disambiguates across years', () => {
+    expect(calendarBucket(secondsAt(2026, 2, 3), THU_NOON, MONDAY).key).toBe('m-2026-2')
+    expect(calendarBucket(secondsAt(2026, 2, 20), THU_NOON, MONDAY).key).toBe('m-2026-2')
+    expect(calendarBucket(secondsAt(2025, 2, 3), THU_NOON, MONDAY).key).toBe('my-2025-2')
+  })
+})
+
+describe('sessionBucketLabel', () => {
+  const labels = {
+    lastWeek: 'Last week',
+    thisMonth: 'Earlier this month',
+    thisWeek: 'Earlier this week',
+    today: 'Earlier today',
+    yesterday: 'Yesterday'
+  }
+
+  const labelAt = (year: number, month: number, day: number) =>
+    sessionBucketLabel(calendarBucket(secondsAt(year, month, day), THU_NOON, 1), labels)
+
+  it('uses fixed labels for the relative buckets', () => {
+    expect(labelAt(2026, 5, 18)).toBe('Earlier today')
+    expect(labelAt(2026, 5, 17)).toBe('Yesterday')
+    expect(labelAt(2026, 5, 16)).toBe('Earlier this week')
+    expect(labelAt(2026, 5, 10)).toBe('Last week')
+    expect(labelAt(2026, 5, 2)).toBe('Earlier this month')
+  })
+
+  it('formats month (same year) and month + year (prior year) via Intl', () => {
+    // en-US default in the test env: month name, plus year for the prior year.
+    expect(labelAt(2026, 2, 3)).toBe('March')
+    expect(labelAt(2025, 11, 3)).toBe('December 2025')
+  })
+})
diff --git a/apps/desktop/src/lib/time.ts b/apps/desktop/src/lib/time.ts
index da1d2915192..5329b183689 100644
--- a/apps/desktop/src/lib/time.ts
+++ b/apps/desktop/src/lib/time.ts
@@ -25,6 +25,11 @@ export const fmtDateTime = new Intl.DateTimeFormat(undefined, { dateStyle: 'medi
 // Date only, "5 Jun 2026" (starmap tooltip).
 export const fmtDate = new Intl.DateTimeFormat(undefined, { day: 'numeric', month: 'short', year: 'numeric' })
 
+// Month name alone / with year — session-list date-bucket dividers ("September",
+// "September 2025").
+export const fmtMonth = new Intl.DateTimeFormat(undefined, { month: 'long' })
+export const fmtMonthYear = new Intl.DateTimeFormat(undefined, { month: 'long', year: 'numeric' })
+
 // ── Relative time ──────────────────────────────────────────────────────────
 const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto', style: 'short' })
 
@@ -50,6 +55,142 @@ export function relativeTime(targetMs: number, nowMs = Date.now()): string {
   return rtf.format(sign * Math.round(abs / DAY), 'day')
 }
 
+// A dated divider bucket below the sidebar's unlabelled "recent" head cluster
+// (see session-date-groups.ts for the clustering). Buckets are coarse,
+// non-overlapping calendar ranges — one divider per *cluster* of activity,
+// never one per day, and never a rolling window like "previous 7 days" that
+// semantically overlaps the groups above it. `kind` drives the label; `at` is
+// the session's nominal day start (ms) for month formatting.
+export type SessionBucketKind = 'lastWeek' | 'month' | 'monthYear' | 'thisMonth' | 'thisWeek' | 'today' | 'yesterday'
+
+export interface SessionBucket {
+  at: number
+  key: string
+  kind: SessionBucketKind
+}
+
+// Fixed divider labels, resolved from i18n (month labels come from Intl).
+export interface SessionBucketLabels {
+  lastWeek: string
+  thisMonth: string
+  thisWeek: string
+  today: string
+  yesterday: string
+}
+
+export const startOfLocalDay = (ms: number): number => {
+  const d = new Date(ms)
+
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
+}
+
+// The human day doesn't end at midnight — it ends when you sleep. Sessions
+// from the small hours belong to the previous evening's run, so the day
+// boundary sits at 4 AM local (same trick activity/sleep trackers use).
+// A 12:30 AM session groups with 11:50 PM instead of splitting off.
+export const DAY_ROLLOVER_HOUR = 4
+
+// Start of the *nominal* local day a timestamp belongs to, honoring the 4 AM
+// rollover: Saturday 1 AM → start of Friday.
+export const nominalDayStart = (ms: number): number => startOfLocalDay(ms - DAY_ROLLOVER_HOUR * HOUR)
+
+// Locale-aware first day of week in JS getDay() convention (0=Sun … 6=Sat).
+// Intl.Locale weekInfo reports 1=Mon … 7=Sun; unsupported → Monday.
+export function localeWeekStartDay(): number {
+  try {
+    const locale = new Intl.Locale(new Intl.DateTimeFormat().resolvedOptions().locale)
+    const withWeekInfo = locale as { getWeekInfo?: () => { firstDay?: number }; weekInfo?: { firstDay?: number } }
+    const firstDay = (withWeekInfo.getWeekInfo?.() ?? withWeekInfo.weekInfo)?.firstDay
+
+    return typeof firstDay === 'number' ? firstDay % 7 : 1
+  } catch {
+    return 1
+  }
+}
+
+// Start of the local calendar week containing `ms` (DST-safe Date field math).
+export function startOfLocalWeek(ms: number, weekStartsOn: number): number {
+  const d = new Date(startOfLocalDay(ms))
+  const back = (d.getDay() - weekStartsOn + 7) % 7
+
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate() - back).getTime()
+}
+
+// Coarse calendar bucket for a Unix-seconds timestamp. Granularity coarsens
+// with age: earlier today → yesterday → earlier this week → last week →
+// earlier this month → month → month + year. Empty ranges simply never emit a
+// bucket, so a sparse tail jumps straight to its month or month-year. The
+// newest run of sessions never reaches here (it is the unlabelled head — see
+// session-date-groups.ts), which is what makes "Earlier today" truthful.
+export function calendarBucket(
+  seconds: number,
+  nowMs = Date.now(),
+  weekStartsOn = localeWeekStartDay()
+): SessionBucket {
+  const nominal = nominalDayStart(seconds * SECOND)
+  const todayNominal = nominalDayStart(nowMs)
+  const dayDiff = Math.round((todayNominal - nominal) / DAY)
+
+  if (dayDiff <= 0) {
+    return { at: nominal, key: 'today', kind: 'today' }
+  }
+
+  if (dayDiff === 1) {
+    return { at: nominal, key: 'yesterday', kind: 'yesterday' }
+  }
+
+  const weekStart = startOfLocalWeek(todayNominal, weekStartsOn)
+
+  if (nominal >= weekStart) {
+    return { at: nominal, key: 'this-week', kind: 'thisWeek' }
+  }
+
+  const ws = new Date(weekStart)
+
+  if (nominal >= new Date(ws.getFullYear(), ws.getMonth(), ws.getDate() - 7).getTime()) {
+    return { at: nominal, key: 'last-week', kind: 'lastWeek' }
+  }
+
+  const d = new Date(nominal)
+  const now = new Date(todayNominal)
+  const sameYear = d.getFullYear() === now.getFullYear()
+
+  if (sameYear && d.getMonth() === now.getMonth()) {
+    return { at: nominal, key: 'this-month', kind: 'thisMonth' }
+  }
+
+  const ym = `${d.getFullYear()}-${d.getMonth()}`
+
+  return sameYear ? { at: nominal, key: `m-${ym}`, kind: 'month' } : { at: nominal, key: `my-${ym}`, kind: 'monthYear' }
+}
+
+// Localized divider label for a bucket: fixed relative strings from i18n,
+// Intl-formatted month / month-year for the rest.
+export function sessionBucketLabel(bucket: SessionBucket, labels: SessionBucketLabels): string {
+  switch (bucket.kind) {
+    case 'today':
+      return labels.today
+
+    case 'yesterday':
+      return labels.yesterday
+
+    case 'thisWeek':
+      return labels.thisWeek
+
+    case 'lastWeek':
+      return labels.lastWeek
+
+    case 'thisMonth':
+      return labels.thisMonth
+
+    case 'month':
+      return fmtMonth.format(bucket.at)
+
+    case 'monthYear':
+      return fmtMonthYear.format(bucket.at)
+  }
+}
+
 export type ElapsedUnit = 'day' | 'hour' | 'minute' | 'second'
 
 // Coarsest elapsed bucket for a (clamped-nonnegative) duration, floored. The
diff --git a/apps/desktop/src/store/session-pin-sync.test.ts b/apps/desktop/src/store/session-pin-sync.test.ts
new file mode 100644
index 00000000000..e6613d8658c
--- /dev/null
+++ b/apps/desktop/src/store/session-pin-sync.test.ts
@@ -0,0 +1,95 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { SessionInfo } from '@/types/hermes'
+
+const patch = vi.fn<(id: string, pinned: boolean, profile?: null | string) => Promise<{ ok: boolean }>>(() =>
+  Promise.resolve({ ok: true })
+)
+
+vi.mock('@/hermes', () => ({
+  setSessionPinnedRemote: (id: string, pinned: boolean, profile?: null | string) => patch(id, pinned, profile)
+}))
+
+import { $pinnedSessionIds } from '@/store/layout'
+import { $sessions } from '@/store/session'
+
+import { watchSessionPins } from './session-pin-sync'
+
+const row = (id: string, extra: Partial<SessionInfo> = {}): SessionInfo =>
+  ({ id, message_count: 1, source: 'cli', started_at: 0, title: id, ...extra }) as SessionInfo
+
+const flush = () => Promise.resolve()
+
+beforeAll(() => {
+  ;(globalThis as { window?: unknown }).window ??= {}
+  ;(window as unknown as { hermesDesktop: unknown }).hermesDesktop = {}
+  // Attach the listeners once — module state is process-global.
+  watchSessionPins()
+})
+
+beforeEach(() => {
+  $sessions.set([])
+  $pinnedSessionIds.set([])
+  patch.mockClear()
+})
+
+afterEach(() => {
+  $sessions.set([])
+  $pinnedSessionIds.set([])
+})
+
+describe('watchSessionPins', () => {
+  it('mirrors a new pin as pinned=true with the row profile', async () => {
+    $sessions.set([row('a', { profile: 'work' })])
+    $pinnedSessionIds.set(['a'])
+    await flush()
+
+    expect(patch).toHaveBeenCalledWith('a', true, 'work')
+  })
+
+  it('mirrors an unpin as pinned=false', async () => {
+    $sessions.set([row('b')])
+    $pinnedSessionIds.set(['b'])
+    await flush()
+    patch.mockClear()
+
+    $pinnedSessionIds.set([])
+    await flush()
+
+    expect(patch).toHaveBeenCalledWith('b', false, undefined)
+  })
+
+  it('defers a pin whose row is not loaded, then flushes once it appears', async () => {
+    $pinnedSessionIds.set(['c'])
+    await flush()
+    // No row yet -> nothing sent.
+    expect(patch).not.toHaveBeenCalled()
+
+    $sessions.set([row('c', { profile: 'p2' })])
+    await flush()
+
+    expect(patch).toHaveBeenCalledWith('c', true, 'p2')
+  })
+
+  it('matches a pin id against the lineage root', async () => {
+    // pin id is the lineage root; the live row carries it as _lineage_root_id.
+    $sessions.set([row('tip', { _lineage_root_id: 'root' })])
+    $pinnedSessionIds.set(['root'])
+    await flush()
+
+    expect(patch).toHaveBeenCalledWith('root', true, undefined)
+  })
+
+  it('does not re-PATCH an already-mirrored pin on unrelated session updates', async () => {
+    $sessions.set([row('d')])
+    $pinnedSessionIds.set(['d'])
+    await flush()
+    patch.mockClear()
+
+    // A session-list refresh that doesn't change the pinned set.
+    $sessions.set([row('d'), row('e')])
+    await flush()
+
+    expect(patch).not.toHaveBeenCalled()
+  })
+})
diff --git a/apps/desktop/src/store/session-pin-sync.ts b/apps/desktop/src/store/session-pin-sync.ts
new file mode 100644
index 00000000000..35235e6dc64
--- /dev/null
+++ b/apps/desktop/src/store/session-pin-sync.ts
@@ -0,0 +1,75 @@
+/**
+ * Mirror the sidebar's localStorage pins into the backend "keep" flag.
+ *
+ * Pins live in `$pinnedSessionIds` (localStorage) and drive the sidebar UI.
+ * The `sessions.auto_archive` sweep, however, runs backend-side and is blind to
+ * localStorage — so without this bridge it could hide a pinned chat. This
+ * watcher PATCHes `pinned` on the session REST endpoint whenever the pinned set
+ * changes, and re-asserts the whole current set at boot, which transparently
+ * migrates pre-existing pins (no flag, no user action — the sweep just starts
+ * honouring them). It never touches the sidebar's own display; localStorage
+ * stays the source of truth there.
+ */
+
+import { setSessionPinnedRemote } from '@/hermes'
+import { $pinnedSessionIds } from '@/store/layout'
+import { $sessions, sessionMatchesStoredId } from '@/store/session'
+
+// pin ids we've successfully PATCHed pinned=true this session.
+const mirrored = new Set<string>()
+// pin ids awaiting their row so we can resolve the owning profile before PATCH.
+const pending = new Set<string>()
+
+function profileFor(pinId: string): null | string | undefined {
+  return $sessions.get().find(row => sessionMatchesStoredId(row, pinId))?.profile
+}
+
+function reconcile(): void {
+  // Config/session REST is only reachable through the Electron bridge.
+  if (!window.hermesDesktop) {
+    return
+  }
+
+  const current = new Set($pinnedSessionIds.get())
+
+  // Unpinned: anything we were tracking that's no longer in the set.
+  for (const id of [...mirrored, ...pending]) {
+    if (!current.has(id)) {
+      mirrored.delete(id)
+      pending.delete(id)
+      void setSessionPinnedRemote(id, false, profileFor(id)).catch(() => {})
+    }
+  }
+
+  // Newly pinned: hold until we can resolve the row (for its profile).
+  for (const id of current) {
+    if (!mirrored.has(id)) {
+      pending.add(id)
+    }
+  }
+
+  // Flush whatever we can resolve now; unresolved ids (row not loaded yet)
+  // retry on the next $sessions change.
+  for (const id of [...pending]) {
+    const row = $sessions.get().find(entry => sessionMatchesStoredId(entry, id))
+
+    if (!row) {
+      continue
+    }
+
+    pending.delete(id)
+    mirrored.add(id)
+    void setSessionPinnedRemote(id, true, row.profile).catch(() => {
+      // Let a later reconcile retry the mirror.
+      mirrored.delete(id)
+      pending.add(id)
+    })
+  }
+}
+
+// Sync once, then re-sync on pin-set and session-list changes. Call once per app.
+export function watchSessionPins(): void {
+  reconcile()
+  $pinnedSessionIds.listen(reconcile)
+  $sessions.listen(reconcile)
+}
diff --git a/apps/desktop/src/store/session-states.test.ts b/apps/desktop/src/store/session-states.test.ts
index 682ebe423d3..18d4142f104 100644
--- a/apps/desktop/src/store/session-states.test.ts
+++ b/apps/desktop/src/store/session-states.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import { group, split } from '@/components/pane-shell/tree/model'
 import type { SessionTile } from '@/store/session-states'
-import { orderTilesByTree, selectionHomesToWorkspace } from '@/store/session-states'
+import { focusedSessionNeedsRoute, orderTilesByTree, selectionHomesToWorkspace } from '@/store/session-states'
 
 const tile = (storedSessionId: string): SessionTile => ({ storedSessionId })
 const tilePane = (id: string) => `session-tile:${id}`
@@ -44,3 +44,23 @@ describe('selectionHomesToWorkspace', () => {
     expect(selectionHomesToWorkspace('a', tiles)).toBe(false)
   })
 })
+
+describe('focusedSessionNeedsRoute', () => {
+  it('routes when the session is not on screen', () => {
+    expect(focusedSessionNeedsRoute(null, false)).toBe(true)
+    expect(focusedSessionNeedsRoute(null, true)).toBe(true)
+  })
+
+  it('routes for the ACTIVE main session while a full page covers the workspace', () => {
+    expect(focusedSessionNeedsRoute('main', true)).toBe(true)
+  })
+
+  it('skips the route when the main session is already the visible chat', () => {
+    expect(focusedSessionNeedsRoute('main', false)).toBe(false)
+  })
+
+  it('never routes for a tile — its pane shows the chat on any route', () => {
+    expect(focusedSessionNeedsRoute('tile', true)).toBe(false)
+    expect(focusedSessionNeedsRoute('tile', false)).toBe(false)
+  })
+})
diff --git a/apps/desktop/src/store/session-states.ts b/apps/desktop/src/store/session-states.ts
index d8248f00d8e..949d56e140f 100644
--- a/apps/desktop/src/store/session-states.ts
+++ b/apps/desktop/src/store/session-states.ts
@@ -572,11 +572,14 @@ export function nextSessionTileForWorkspace(): null | string {
 }
 
 /** If a session is already ON SCREEN — an open tile OR the one loaded in main —
- *  front its tab (and focus its zone) and return true. A sidebar click on an
- *  already-open chat JUMPS to its tab instead of reloading it; `false` means the
+ *  front its tab (and focus its zone) and report WHICH. A sidebar click on an
+ *  already-open chat JUMPS to its tab instead of reloading it; `null` means the
  *  caller must load it into main. Covers the two dead clicks: an open tile, and
- *  the main session while focus sits on a tile (route unchanged → no reload). */
-export function focusOpenSession(storedSessionId: string): boolean {
+ *  the main session while focus sits on a tile (route unchanged → no reload).
+ *  Callers that own the router need the `'main'` vs `'tile'` distinction: a
+ *  `'main'` hit only reaches the screen if the workspace pane is actually
+ *  showing the chat, whereas a tile renders in its own pane regardless. */
+export function focusOpenSession(storedSessionId: string): 'main' | 'tile' | null {
   if ($sessionTiles.get().some(t => t.storedSessionId === storedSessionId)) {
     const paneId = `${TILE_PANE_PREFIX}${storedSessionId}`
     revealTreePane(paneId) // un-dismiss + adopt + front in its group
@@ -587,7 +590,7 @@ export function focusOpenSession(storedSessionId: string): boolean {
       noteActiveTreeGroup(group.id)
     }
 
-    return true
+    return 'tile'
   }
 
   // Already the main session: front the workspace tab and drop tile focus so
@@ -596,10 +599,19 @@ export function focusOpenSession(storedSessionId: string): boolean {
     revealTreePane('workspace')
     noteActiveTreeGroup(null)
 
-    return true
+    return 'main'
   }
 
-  return false
+  return null
+}
+
+/** Does a sidebar click still need to navigate after `focusOpenSession`? A miss
+ *  always does. A `'main'` hit does too while the workspace pane is showing a
+ *  full page (artifacts, skills, …): fronting the workspace tab doesn't put the
+ *  chat back on screen — only a route change back to the session does. A tile
+ *  hit never does; its pane renders the chat regardless of the route. */
+export function focusedSessionNeedsRoute(focused: 'main' | 'tile' | null, workspaceIsPage: boolean): boolean {
+  return !focused || (focused === 'main' && workspaceIsPage)
 }
 
 // Closed-tab stack for ⌘⇧T reopen (in-memory) — keyed PER PROFILE like the
diff --git a/apps/desktop/src/store/session.ts b/apps/desktop/src/store/session.ts
index 0044a7b34a6..31ea5ff832a 100644
--- a/apps/desktop/src/store/session.ts
+++ b/apps/desktop/src/store/session.ts
@@ -454,6 +454,14 @@ export const setCurrentReasoningEffort = (next: Updater<string>) => {
   persistString(COMPOSER_EFFORT_KEY, $currentReasoningEffort.get() || null)
 }
 
+// The profile's `agent.reasoning_effort`, mirrored from config so surfaces that
+// need to render or apply "the default" resolve the user's configured level
+// instead of assuming DEFAULT_REASONING_EFFORT (lib/reasoning-effort). Empty
+// until config loads, and re-seeded on every profile switch by useHermesConfig.
+export const $defaultReasoningEffort = atom('')
+
+export const setDefaultReasoningEffort = (next: string) => updateAtom($defaultReasoningEffort, next)
+
 export const setCurrentServiceTier = (next: Updater<string>) => updateAtom($currentServiceTier, next)
 
 export const setCurrentFastMode = (next: Updater<boolean>) => {
diff --git a/apps/desktop/src/styles.css b/apps/desktop/src/styles.css
index 6216e94a9f6..0f7fdbdd3b4 100644
--- a/apps/desktop/src/styles.css
+++ b/apps/desktop/src/styles.css
@@ -317,6 +317,10 @@
        :root.dark bumps the alpha since a dark card swallows shadow. Removed on
        focus (the focus border carries the state). */
     --dt-input-inset: inset 0 1px 1px color-mix(in srgb, #000 10%, transparent);
+    /* Hovered inactive tab: deepen it AWAY from the lighter active surface, so
+       hover can never be mistaken for selected. Dark mode needs more — black
+       over a dark gutter shows less. */
+    --ui-tab-hover-darken: 2.5%;
     --dt-ring: var(--ui-stroke-primary);
     --dt-midground: var(--theme-midground);
     --dt-composer-ring: var(--ui-base);
@@ -347,7 +351,8 @@
     --radius-scalar: 0.6;
 
     /* Space under last message vs overlay composer — driven by the measured composer height (see composer/index.tsx)
-       plus the out-of-flow status stack's measured height (see status-stack/index.tsx) when one is showing. */
+       plus the out-of-flow status stack's measured height (see status-stack/index.tsx) when one is showing.
+       These are the defaults; each chat surface re-declares the calc against its own measurements (see below). */
     --status-stack-measured-height: 0px;
     --thread-last-message-clearance: calc(var(--composer-measured-height) + var(--status-stack-measured-height) + 2rem);
 
@@ -445,6 +450,7 @@
     --backdrop-invert-mul: 0;
     /* Dark mode: a dark card needs a stronger black inset to show the recess. */
     --dt-input-inset: inset 0 1px 1px color-mix(in srgb, #000 38%, transparent);
+    --ui-tab-hover-darken: 6%;
     /* Dark needs a lighter resting border than light mode. */
     --dt-input-border: 4%;
 
@@ -513,6 +519,32 @@
   background: repeating-conic-gradient(currentColor 0% 25%, transparent 0% 50%) 0 0 / 0.125rem 0.125rem;
 }
 
+/* Inline content links: a small tinted chip instead of an underline. Tint is
+   currentColor-relative (the old `decoration-current/20` idiom), so text and
+   fill share a hue on every theme from one `color` declaration. */
+.link-chip {
+  --link-chip-tint: 8%;
+
+  /* `ch`/`em` so the chip tracks the text at any size. Block padding is
+     asymmetric because an inline box's content area is ascent+descent — equal
+     padding paints the glyphs high. Keep it small: `padding-block` doesn't grow
+     the line box, so an over-padded chip creeps into the line above. */
+  padding: 0.05ch 0.5ch 0.2ch;
+  border-radius: 0.25rem;
+  color: var(--dt-primary);
+  background: color-mix(in srgb, currentColor var(--link-chip-tint), transparent);
+  /* Explicit: the base layer underlines every `a` (see the :where(a, …) reset). */
+  text-decoration: none;
+  /* A wrapped link gets a chip per line fragment, not one ragged box. */
+  -webkit-box-decoration-break: clone;
+  box-decoration-break: clone;
+  transition: background-color 0.12s ease;
+}
+
+.link-chip:hover {
+  --link-chip-tint: 15%;
+}
+
 /* Hover-reveal suppression — the shared, declarative escape hatch.
    A collapsed pane slides in when the pointer dwells on its thin edge trigger.
    Controls that sit over that edge gutter would drag the panel in by accident.
@@ -609,14 +641,19 @@
   --arc-c2: var(--dt-background);
   --arc-angle: 160deg;
   --arc-width: 0.078125rem;
-  --arc-inset: -0.125rem;
+  /* How far the ring stands off its host, per side. */
+  --arc-standoff: 0.125rem;
+  /* An outset ring is only concentric when its radius grows by the standoff
+     (r = r_host + gap); `border-radius: inherit` leaves the corner pinched.
+     Defaults to the shared `rounded-md`; a host on another radius sets it. */
+  --arc-radius: var(--radius-md);
   --arc-duration: 2.23s;
 
   pointer-events: none;
   position: absolute;
   overflow: hidden;
-  border-radius: inherit;
-  inset: var(--arc-inset);
+  border-radius: calc(var(--arc-radius) + var(--arc-standoff));
+  inset: calc(var(--arc-standoff) * -1);
   padding: var(--arc-width);
   mask:
     linear-gradient(#000 0 0) content-box,
@@ -718,6 +755,23 @@
   --arc-duration: 3.27s;
 }
 
+/* Sidebar session row — a thin, clipped, single-line host, so it differs twice
+   from the default ring:
+
+   1. Flush, not outset. The sidebar scroller is `overflow-x-hidden` and rows sit
+      `gap-px` apart, so an outset ring loses its left/right runs to the clip.
+
+   2. A visible tail. `--arc-c2` defaults to `--dt-background` — invisible
+      against the sidebar. With c0 a transparent sentinel and c2 invisible, only
+      the bright c1 stop survives each pass, and the gradient has three of them:
+      three moving dots instead of an arc. Tying c2 to c1 gives each spike a
+      falloff. (`arc-nous` already overrides c2, so the hero is unaffected.) */
+.arc-border.arc-row,
+:root.dark .arc-border.arc-row {
+  --arc-standoff: 0rem;
+  --arc-c2: color-mix(in srgb, var(--arc-c1) 45%, transparent);
+}
+
 @media (prefers-reduced-motion: reduce) {
   .arc-border::before {
     animation: none;
@@ -1467,12 +1521,14 @@ text-* variant utilities. */ .btn-arc {
   height: 0.875rem;
 }
 
-/* Live thinking preview window. Pairs with the ResizeObserver in
-   ThinkingDisclosure that pins scrollTop to the bottom — older lines fade
-   into the top mask while the latest tokens settle in below. */
-.thinking-preview {
-  -webkit-mask-image: linear-gradient(to bottom, transparent 0%, black 28%, black 100%);
-  mask-image: linear-gradient(to bottom, transparent 0%, black 28%, black 100%);
+/* Re-declare the clearance calc on every chat surface. `:root` computes it
+   once against the ROOT measurements, so scoping only the inputs would leave
+   every thread reading the same substituted value. Redeclaring here makes each
+   surface resolve the calc against its own composer + status-stack heights,
+   falling back to the root defaults until this surface publishes its first
+   measurement. See surface-vars.ts. */
+[data-chat-surface] {
+  --thread-last-message-clearance: calc(var(--composer-measured-height) + var(--status-stack-measured-height) + 2rem);
 }
 
 /* Long adjacent tool-call run collapsed into a fixed, auto-scrolling window.
diff --git a/apps/desktop/src/types/hermes.ts b/apps/desktop/src/types/hermes.ts
index 0b93172c875..669813b0ab2 100644
--- a/apps/desktop/src/types/hermes.ts
+++ b/apps/desktop/src/types/hermes.ts
@@ -182,6 +182,7 @@ export interface CustomEndpointUpdate {
   id?: string
   make_default?: boolean
   model: string
+  models?: string[]
   name: string
 }
 
@@ -243,6 +244,58 @@ export interface MessagingPlatformTestResponse {
   state?: null | string
 }
 
+// -- Webhooks (subscription CRUD) --------------------------------------------
+// Incoming HTTP event routes served by the webhook gateway platform. Backed by
+// the same JSON store the CLI/dashboard use; per-route HMAC secrets are
+// redacted on read and surfaced exactly once on create.
+
+export interface WebhookRoute {
+  created_at: null | string
+  deliver: string
+  deliver_only: boolean
+  description: string
+  enabled: boolean
+  events: string[]
+  name: string
+  prompt: string
+  secret_set: boolean
+  skills: string[]
+  url: string
+}
+
+export interface WebhooksResponse {
+  base_url: string
+  enabled: boolean
+  subscriptions: WebhookRoute[]
+}
+
+export interface WebhookCreatePayload {
+  deliver?: string
+  deliver_chat_id?: string
+  deliver_only?: boolean
+  description?: string
+  events?: string[]
+  name: string
+  prompt?: string
+  skills?: string[]
+}
+
+// Create echoes the route summary plus the one-time secret.
+export interface WebhookCreateResponse extends WebhookRoute {
+  secret: string
+}
+
+export interface WebhookEnableResponse {
+  enabled: true
+  needs_restart: boolean
+  ok: boolean
+  platform: 'webhook'
+  restart_action?: string
+  restart_error?: string
+  restart_pid?: null | number
+  restart_started?: boolean
+}
+
 export interface GatewayReadyPayload {
   skin?: unknown
 }
@@ -442,7 +495,11 @@ export interface SessionMessage {
   reasoning_content?: null | string
   reasoning_details?: unknown
   display_kind?: 'async_delegation_complete' | 'hidden' | 'model_switch' | string
-  display_metadata?: TimelineDisplayMetadata
+  /**
+   * A backend older than this app can still serve this as unparsed JSON text,
+   * so readers must narrow before indexing into it.
+   */
+  display_metadata?: string | TimelineDisplayMetadata
   role: 'assistant' | 'system' | 'tool' | 'user'
   text?: unknown
   timestamp?: number
@@ -457,8 +514,20 @@ export interface SessionMessagesResponse {
 }
 
 export interface SessionResumeResponse {
+  /** Present when the backend found a fresh crash-interrupted turn and
+   *  scheduled its automatic continuation; the turn arrives as a normal
+   *  message.start stream right after this resume. */
+  auto_continue?: {
+    attempt: number
+    interrupted_at: number
+  }
   inflight?: null | {
     assistant?: string
+    /** Retained failed turn: the error the terminal frame carried (the frame
+     *  itself may have been lost to a disconnect). */
+    error?: string
+    recoverable?: boolean
+    status?: string
     streaming?: boolean
     user?: string
   }
@@ -676,6 +745,46 @@ export interface CronJobUpdates {
   schedule?: string
 }
 
+// A cron delivery target from GET /api/cron/delivery-targets — the single
+// source of truth (cron.scheduler.cron_delivery_targets) for where a cron job
+// can auto-deliver. Only 'local' plus configured gateway platforms appear; a
+// configured platform without a cron home channel comes back with
+// home_target_set=false so the UI can flag it.
+export interface CronDeliveryTarget {
+  home_env_var: null | string
+  home_target_set: boolean
+  id: string
+  name: string
+}
+
+// Automation Blueprints — parameterized cron templates with typed slots. The
+// backend (cron/blueprint_catalog.py) is the single source of truth; the
+// desktop renders each slot as a form field, then instantiates a real cron job
+// via the same create_job path as everything else. Shapes mirror the JSON from
+// GET /api/cron/blueprints (blueprint_catalog_entry).
+export interface AutomationBlueprintField {
+  name: string
+  type: 'enum' | 'text' | 'time' | 'weekdays'
+  label: string
+  default: null | string
+  options: string[]
+  optional: boolean
+  /** When false, options are suggestions — any value is accepted. */
+  strict?: boolean
+  help: string
+}
+
+export interface AutomationBlueprint {
+  key: string
+  title: string
+  description: string
+  category: string
+  tags: string[]
+  fields: AutomationBlueprintField[]
+  command: string
+  appUrl: string
+}
+
 export interface ProfileCreatePayload {
   clone_all?: boolean
   clone_from?: null | string
@@ -999,6 +1108,7 @@ export interface MoaModelSlot {
   model: string
   /** Optional per-slot reasoning effort — round-tripped, not edited here. */
   reasoning_effort?: string
+  enabled?: boolean
 }
 
 export interface MoaConfigResponse {
@@ -1009,22 +1119,26 @@ export interface MoaConfigResponse {
     {
       aggregator: MoaModelSlot
       aggregator_temperature: number
+      degraded_reference_policy: 'loud' | 'silent'
       enabled: boolean
       max_tokens: number
       reference_models: MoaModelSlot[]
       reference_temperature: number
       /** Optional advisor output cap — round-tripped, not edited here. */
       reference_max_tokens?: number | null
-      /** Fan-out cadence (per_iteration | user_turn) — round-tripped. */
+      /** Fan-out cadence (user_turn default | per_iteration | every_n:N) — round-tripped. */
       fanout?: string
+      reference_timeout: number | null
     }
   >
   aggregator: MoaModelSlot
   aggregator_temperature: number
+  degraded_reference_policy: 'loud' | 'silent'
   enabled: boolean
   max_tokens: number
   reference_models: MoaModelSlot[]
   reference_temperature: number
+  reference_timeout: number | null
 }
 
 export interface ModelAssignmentRequest {
diff --git a/apps/desktop/src/webhooks-rest.test.ts b/apps/desktop/src/webhooks-rest.test.ts
new file mode 100644
index 00000000000..a8dc8e83a86
--- /dev/null
+++ b/apps/desktop/src/webhooks-rest.test.ts
@@ -0,0 +1,65 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { createWebhook, deleteWebhook, enableWebhooks, getWebhooks, setWebhookEnabled } from './hermes'
+
+describe('Webhook REST parity helpers', () => {
+  let api: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    api = vi.fn().mockResolvedValue({})
+    Object.defineProperty(window, 'hermesDesktop', {
+      configurable: true,
+      value: { api }
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    Reflect.deleteProperty(window, 'hermesDesktop')
+  })
+
+  it('lists webhooks from the admin endpoint', async () => {
+    await getWebhooks()
+
+    expect(api).toHaveBeenCalledWith(expect.objectContaining({ path: '/api/webhooks' }))
+  })
+
+  it('enables the webhook platform with POST', async () => {
+    await enableWebhooks()
+
+    expect(api).toHaveBeenCalledWith(expect.objectContaining({ method: 'POST', path: '/api/webhooks/enable' }))
+  })
+
+  it('creates a subscription with the full payload', async () => {
+    const body = {
+      deliver: 'telegram',
+      deliver_only: true,
+      description: 'push events',
+      events: ['push'],
+      name: 'github-push',
+      prompt: 'summarize the push'
+    }
+
+    await createWebhook(body)
+
+    expect(api).toHaveBeenCalledWith(expect.objectContaining({ body, method: 'POST', path: '/api/webhooks' }))
+  })
+
+  it('encodes the name when deleting a subscription', async () => {
+    await deleteWebhook('my hook')
+
+    expect(api).toHaveBeenCalledWith(expect.objectContaining({ method: 'DELETE', path: '/api/webhooks/my%20hook' }))
+  })
+
+  it('toggles a subscription enabled state via PUT', async () => {
+    await setWebhookEnabled('github-push', false)
+
+    expect(api).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: { enabled: false },
+        method: 'PUT',
+        path: '/api/webhooks/github-push/enabled'
+      })
+    )
+  })
+})
diff --git a/batch_runner.py b/batch_runner.py
index f7fc28d7a5c..9e8883275a8 100644
--- a/batch_runner.py
+++ b/batch_runner.py
@@ -282,7 +282,7 @@ def _process_single_prompt(
                         print(f"   Prompt {prompt_index}: Pulling docker image {container_image}...", flush=True)
                     pull = _sp.run(
                         ["docker", "pull", container_image],
-                        capture_output=True, text=True, timeout=600,
+                        capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=600,
                     )
                     if pull.returncode != 0:
                         return {
diff --git a/cli-config.yaml.example b/cli-config.yaml.example
index 0c7d708d13c..5e78fdd8f4c 100644
--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@@ -407,6 +407,18 @@ compression:
   # Enable automatic context compression (default: true)
   # Set to false if you prefer to manage context manually or want errors on overflow
   enabled: true
+
+  # Opt-in compression progress notices on chat platforms (default: false).
+  # By design, routine automatic compression is SILENT on human-facing chat
+  # gateways (Telegram, Discord, Slack, ...) — it happens in the background
+  # with server-side logging only. Set true to also deliver the routine
+  # progress statuses (compacting started, preflight/pre-API compression,
+  # idle compaction, retry progress, and the compaction-complete notice) to
+  # chat platforms. Unrelated operational noise (auxiliary model failures,
+  # provider retry chatter) stays suppressed either way, and compression
+  # FAILURE notices + manual /compress feedback are always visible
+  # regardless of this setting. (#52995)
+  progress_notices: false
   
   # Trigger compression at this % of model's context limit (default: 0.50 = 50%)
   # Lower values = more aggressive compression, higher values = compress later
@@ -448,6 +460,15 @@ compression:
   # compression of older turns.
   protect_last_n: 20
 
+  # Minimum number of REAL (actionable) user messages guaranteed to survive in
+  # the uncompressed tail (default: 1 = the existing single last-user anchor,
+  # behavior-preserving). Raise to e.g. 3 to keep the last 3 real user turns
+  # verbatim even when bulky tool outputs fill the tail token budget — blank
+  # platform echoes, compaction handoffs, and synthetic continuation rows never
+  # count toward N. The tail can exceed the token budget when this pulls the
+  # cut back; the guarantee wins over the budget by design.
+  min_tail_user_messages: 1
+
   # Compression retry rounds before a turn gives up with "max compression
   # attempts reached" (default: 3, same as the previous hardcoded value).
   # Raise (e.g. 6) for tool-schema-heavy sessions where 3 rounds cannot bring
@@ -484,6 +505,34 @@ compression:
   # summarization on a short idle thread. Example: 1800 = compact after 30 min idle.
   idle_compact_after_seconds: 0
 
+  # Proactive tool-result prune (default: 0 = disabled). Opt-in token trigger
+  # for a deterministic, no-LLM prune of OLD tool-result payloads, run
+  # independently of `threshold` above. On large-window models (512K/1M) the
+  # ratio threshold rarely fires, so bulky tool outputs (terminal dumps, file
+  # reads, web extracts) ride along in history and get re-billed every turn.
+  # When re-sent history exceeds this many tokens, the prune dedupes identical
+  # results, summarizes older oversized ones, and truncates large tool-call
+  # arguments — protecting the most recent `protect_last_n` messages and never
+  # calling the model. Try 48000 to enable. Built-in compressor engine only;
+  # other context engines inherit a safe no-op.
+  # NOTE: a committed prune rewrites already-sent history, which invalidates
+  # the provider's prompt-cache prefix — the min_reclaim gate below keeps
+  # those cache breaks episodic (like a compression boundary) instead of
+  # per-turn.
+  proactive_prune_tokens: 0
+
+  # The prune's summarize pass only touches tool results larger than this many
+  # characters (clamped to >= 200 so a generated summary can't be
+  # re-summarized). Default 8000.
+  proactive_prune_min_result_chars: 8000
+
+  # A proactive prune only COMMITS when it reclaims at least this many tokens
+  # (measured on the pruned output). This is the prompt-cache hysteresis gate:
+  # one meaningful, amortized cache break per batch of stale tool output
+  # instead of a tiny break on every tool iteration. 0 = commit any non-zero
+  # prune. Default 4096.
+  proactive_prune_min_reclaim_tokens: 4096
+
   # To pin a specific model/provider for compression summaries, use the
   # auxiliary section below (auxiliary.compression.provider / model).
 
@@ -750,6 +799,14 @@ agent:
   # window on /restart, and keep it well under systemd's TimeoutStopSec.
   # restart_drain_timeout: 0
 
+  # Upper bound (seconds) a submitted prompt waits for the deferred agent
+  # build (MCP discovery, model metadata, skills scan) before failing with a
+  # visible error. The wait is patient — the message is delivered as soon as
+  # the build completes, and a progress notice is shown past 30s — so this cap
+  # only fires on a genuinely hung build. Raise it for deployments with many
+  # slow or unreachable MCP servers. Default 600.
+  # build_wait_timeout: 600
+
   # Max app-level retry attempts for API errors (connection drops, provider
   # timeouts, 5xx, etc.) before the agent surfaces the failure. Lower this
   # to 1 if you use fallback providers and want fast failover on flaky
diff --git a/cli.py b/cli.py
index 7dd4fc3b1a2..1d44f861a0d 100644
--- a/cli.py
+++ b/cli.py
@@ -468,6 +468,7 @@ def load_cli_config() -> Dict[str, Any]:
         "compression": {
             "enabled": True,      # Auto-compress when approaching context limit
             "threshold": 0.50,    # Compress at 50% of model's context limit
+            "min_tail_user_messages": 1,  # Real user messages guaranteed in the tail (1 = existing single anchor)
         },
         "agent": {
             "max_turns": 90,  # Default max tool-calling iterations (shared with subagents)
@@ -1430,7 +1431,7 @@ def _git_repo_root() -> Optional[str]:
     try:
         result = subprocess.run(
             ["git", "rev-parse", "--show-toplevel"],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5,
         )
         if result.returncode == 0:
             return _normalize_git_bash_path(result.stdout.strip())
@@ -1477,7 +1478,7 @@ def _resolve_worktree_base(repo_root: str) -> tuple:
     def _git(args, timeout=20):
         return subprocess.run(
             ["git", *args],
-            capture_output=True, text=True, timeout=timeout, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=repo_root,
         )
 
     # 1. Current branch's upstream, if it tracks one.
@@ -1555,7 +1556,15 @@ def _setup_worktree(repo_root: str = None, sync_base: bool = True) -> Optional[D
     gitignore = Path(repo_root) / ".gitignore"
     _ignore_entry = ".worktrees/"
     try:
-        existing = gitignore.read_text() if gitignore.exists() else ""
+        # utf-8-sig: git files are UTF-8 and Notepad prepends a BOM, which
+        # would glue to the first line and defeat the membership check below
+        # (duplicating the entry); the locale default also breaks non-ASCII
+        # patterns on Windows. The append below already writes UTF-8.
+        existing = (
+            gitignore.read_text(encoding="utf-8-sig", errors="replace")
+            if gitignore.exists()
+            else ""
+        )
         if _ignore_entry not in existing.splitlines():
             with open(gitignore, "a", encoding="utf-8") as f:
                 if existing and not existing.endswith("\n"):
@@ -1576,7 +1585,7 @@ def _setup_worktree(repo_root: str = None, sync_base: bool = True) -> Optional[D
     try:
         result = subprocess.run(
             ["git", "worktree", "add", str(wt_path), "-b", branch_name, base_ref],
-            capture_output=True, text=True, timeout=30, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=30, cwd=repo_root,
         )
         if result.returncode != 0:
             # If branching from the resolved remote ref failed for any reason
@@ -1590,7 +1599,7 @@ def _setup_worktree(repo_root: str = None, sync_base: bool = True) -> Optional[D
                 base_ref, base_label = "HEAD", "HEAD (fallback — remote base failed)"
                 result = subprocess.run(
                     ["git", "worktree", "add", str(wt_path), "-b", branch_name, base_ref],
-                    capture_output=True, text=True, timeout=30, cwd=repo_root,
+                    capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=30, cwd=repo_root,
                 )
             if result.returncode != 0:
                 print(f"\033[31m✗ Failed to create worktree: {result.stderr.strip()}\033[0m")
@@ -1605,7 +1614,14 @@ def _setup_worktree(repo_root: str = None, sync_base: bool = True) -> Optional[D
         try:
             repo_root_resolved = Path(repo_root).resolve()
             wt_path_resolved = wt_path.resolve()
-            for line in include_file.read_text().splitlines():
+            # utf-8-sig, not the locale default: on a cp1251/GBK Windows
+            # machine a UTF-8 include list either decodes to mojibake paths
+            # (entries silently not copied) or raises UnicodeDecodeError,
+            # which the enclosing handler swallows at DEBUG — no include is
+            # copied at all. A Notepad BOM likewise glued to the first entry.
+            for line in include_file.read_text(
+                encoding="utf-8-sig", errors="replace"
+            ).splitlines():
                 entry = line.strip()
                 if not entry or entry.startswith("#"):
                     continue
@@ -1671,7 +1687,7 @@ def _setup_worktree(repo_root: str = None, sync_base: bool = True) -> Optional[D
     try:
         subprocess.run(
             ["git", "worktree", "lock", "--reason", f"hermes pid={os.getpid()}", str(wt_path)],
-            capture_output=True, text=True, timeout=10, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10, cwd=repo_root,
         )
         logger.debug("Worktree locked: %s (pid=%s)", wt_path, os.getpid())
     except Exception as e:
@@ -1704,7 +1720,7 @@ def _worktree_has_unpushed_commits(worktree_path: str, timeout: int = 10) -> boo
     try:
         remote_refs = subprocess.run(
             ["git", "for-each-ref", "--format=%(refname)", "refs/remotes"],
-            capture_output=True, text=True, timeout=timeout, cwd=worktree_path,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=worktree_path,
         )
         if remote_refs.returncode != 0:
             return True
@@ -1713,7 +1729,7 @@ def _worktree_has_unpushed_commits(worktree_path: str, timeout: int = 10) -> boo
 
         result = subprocess.run(
             ["git", "log", "--oneline", "HEAD", "--not", "--remotes"],
-            capture_output=True, text=True, timeout=timeout, cwd=worktree_path,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=worktree_path,
         )
         if result.returncode != 0:
             return True
@@ -1734,7 +1750,7 @@ def _worktree_is_dirty(worktree_path: str, timeout: int = 10) -> bool:
     try:
         result = subprocess.run(
             ["git", "status", "--porcelain"],
-            capture_output=True, text=True, timeout=timeout, cwd=worktree_path,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=worktree_path,
         )
         if result.returncode != 0:
             return True
@@ -1743,8 +1759,68 @@ def _worktree_is_dirty(worktree_path: str, timeout: int = 10) -> bool:
         return True
 
 
+# Upper bound on retained `git cherry` verdict entries (see
+# _save_worktree_merge_cache). Each entry is ~90 bytes, so this caps the cache
+# near 90 KB even on a repo that churns thousands of worktree branches.
+_WORKTREE_MERGE_CACHE_MAX = 1000
+
+
+def _worktree_merge_cache_path() -> Path:
+    """Path of the patch-equivalence verdict cache (profile-aware)."""
+    return get_hermes_home() / "cache" / "worktree_merge_verdicts.json"
+
+
+def _load_worktree_merge_cache() -> Dict[str, bool]:
+    """Load the ``git cherry`` verdict cache. Missing/corrupt cache = empty."""
+    try:
+        raw = json.loads(
+            _worktree_merge_cache_path().read_text(encoding="utf-8")
+        )
+    except Exception:
+        return {}
+    if not isinstance(raw, dict):
+        return {}
+    entries = raw.get("verdicts")
+    if not isinstance(entries, dict):
+        return {}
+    # Only keep well-formed bool verdicts — a hand-edited or partially written
+    # cache must never inject a non-bool into the prune decision.
+    return {k: v for k, v in entries.items() if isinstance(v, bool)}
+
+
+def _save_worktree_merge_cache(verdicts: Dict[str, bool]) -> None:
+    """Persist the verdict cache atomically. Best-effort — never raises.
+
+    Bounded to the most recent ``_WORKTREE_MERGE_CACHE_MAX`` entries so the
+    file can't grow without limit across thousands of sessions.
+    """
+    path = _worktree_merge_cache_path()
+    tmp = None
+    try:
+        items = list(verdicts.items())
+        if len(items) > _WORKTREE_MERGE_CACHE_MAX:
+            items = items[-_WORKTREE_MERGE_CACHE_MAX:]
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(f".{os.getpid()}.tmp")
+        tmp.write_text(
+            json.dumps({"version": 1, "verdicts": dict(items)}),
+            encoding="utf-8",
+        )
+        os.replace(str(tmp), str(path))
+    except Exception as e:
+        logger.debug("Could not persist worktree merge cache: %s", e)
+        if tmp is not None:
+            try:
+                tmp.unlink()
+            except Exception:
+                pass
+
+
 def _worktree_commits_all_merged_upstream(
-    worktree_path: str, timeout: int = 30, max_ahead: int = 20
+    worktree_path: str,
+    timeout: int = 30,
+    max_ahead: int = 20,
+    cache: Optional[Dict[str, bool]] = None,
 ) -> bool:
     """Return whether every local-only commit is patch-equivalent to a commit
     already on the default upstream branch.
@@ -1759,6 +1835,15 @@ def _worktree_commits_all_merged_upstream(
     Bounded: skips (returns False) when the branch is more than ``max_ahead``
     commits ahead — a stale-base tree, too expensive to diff-hash and unlikely
     to be a merged scratch branch. Fails SAFE toward False (preserve).
+
+    ``git cherry`` diff-hashes every commit in the range, which on a large repo
+    costs ~0.2-1.0s per worktree — and a tree preserved for unpushed work is
+    re-tested on *every* startup, forever, always reaching the same answer. When
+    *cache* is provided, the verdict is memoized against
+    ``(base_sha, head_sha, max_ahead)``: the exact inputs ``git cherry``
+    consumes. A cache hit is therefore identical to recomputation by
+    construction — if either ref moves the key changes and the real git call
+    runs again.
     """
     import subprocess
 
@@ -1767,7 +1852,7 @@ def _worktree_commits_all_merged_upstream(
         try:
             probe = subprocess.run(
                 ["git", "rev-parse", "--verify", "--quiet", candidate],
-                capture_output=True, text=True, timeout=timeout, cwd=worktree_path,
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=worktree_path,
             )
             if probe.returncode == 0 and probe.stdout.strip():
                 base = candidate
@@ -1778,27 +1863,48 @@ def _worktree_commits_all_merged_upstream(
         return False
 
     try:
+        # Resolve both endpoints to shas up front. These are the complete
+        # inputs to the range below, so they form an exact cache key. Cheap
+        # (~1ms) relative to the diff-hashing `git cherry` they guard.
+        cache_key = None
+        if cache is not None:
+            revs = subprocess.run(
+                ["git", "rev-parse", f"{base}^{{commit}}", "HEAD^{commit}"],
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=worktree_path,
+            )
+            if revs.returncode == 0:
+                shas = revs.stdout.split()
+                if len(shas) == 2:
+                    cache_key = f"{shas[0]}..{shas[1]}:{max_ahead}"
+                    if cache_key in cache:
+                        return cache[cache_key]
+
+        def _memo(verdict: bool) -> bool:
+            if cache is not None and cache_key is not None:
+                cache[cache_key] = verdict
+            return verdict
+
         ahead = subprocess.run(
             ["git", "rev-list", "--count", f"{base}..HEAD"],
-            capture_output=True, text=True, timeout=timeout, cwd=worktree_path,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=worktree_path,
         )
         if ahead.returncode != 0:
             return False
         count = int(ahead.stdout.strip() or "0")
         if count == 0:
-            return True
+            return _memo(True)
         if count > max_ahead:
-            return False
+            return _memo(False)
 
         cherry = subprocess.run(
             ["git", "cherry", base, "HEAD"],
-            capture_output=True, text=True, timeout=timeout, cwd=worktree_path,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=worktree_path,
         )
         if cherry.returncode != 0:
             return False
         lines = [ln for ln in cherry.stdout.splitlines() if ln.strip()]
         # "-" = patch-equivalent commit exists upstream; "+" = unique local work
-        return bool(lines) and all(ln.startswith("-") for ln in lines)
+        return _memo(bool(lines) and all(ln.startswith("-") for ln in lines))
     except Exception:
         return False
 
@@ -1827,7 +1933,7 @@ def _worktree_lock_is_live(repo_root: str, worktree_path: str, timeout: int = 10
     try:
         result = subprocess.run(
             ["git", "worktree", "list", "--porcelain"],
-            capture_output=True, text=True, timeout=timeout, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=repo_root,
         )
         if result.returncode != 0:
             return "live"
@@ -1902,7 +2008,7 @@ def _cleanup_worktree(info: Dict[str, str] = None) -> None:
     try:
         subprocess.run(
             ["git", "worktree", "unlock", wt_path],
-            capture_output=True, text=True, timeout=10, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10, cwd=repo_root,
         )
     except Exception as e:
         logger.debug("git worktree unlock failed (non-fatal): %s", e)
@@ -1910,7 +2016,7 @@ def _cleanup_worktree(info: Dict[str, str] = None) -> None:
     try:
         subprocess.run(
             ["git", "worktree", "remove", wt_path, "--force"],
-            capture_output=True, text=True, timeout=15, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=15, cwd=repo_root,
         )
     except Exception as e:
         logger.debug("Failed to remove worktree: %s", e)
@@ -1919,7 +2025,7 @@ def _cleanup_worktree(info: Dict[str, str] = None) -> None:
     try:
         subprocess.run(
             ["git", "branch", "-D", branch],
-            capture_output=True, text=True, timeout=10, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10, cwd=repo_root,
         )
     except Exception as e:
         logger.debug("Failed to delete branch %s: %s", branch, e)
@@ -1970,6 +2076,16 @@ def _run_state_db_auto_maintenance(session_db) -> None:
             logger.debug("Orphan compression finalize skipped: %s", _finalize_exc)
 
         cfg = (_load_full_config().get("sessions") or {})
+
+        # Auto-archive (soft-hide stale sessions) is independent of the
+        # destructive auto_prune sweep — run it first, before prune's early
+        # return, so enabling one doesn't require the other.
+        if cfg.get("auto_archive", False):
+            session_db.maybe_auto_archive(
+                idle_days=float(cfg.get("auto_archive_days", 3)),
+                min_interval_hours=int(cfg.get("min_interval_hours", 24)),
+            )
+
         if not cfg.get("auto_prune", False):
             return
         session_db.maybe_auto_prune_and_vacuum(
@@ -1996,10 +2112,15 @@ def _run_checkpoint_auto_maintenance() -> None:
         if not cfg.get("auto_prune", False):
             return
         from tools.checkpoint_manager import maybe_auto_prune_checkpoints
+        # delete_orphans is intentionally never honoured here: a missing
+        # workdir at startup is ambiguous (deleted project vs. an unmounted
+        # external volume / network share / VPN not yet up) and this sweep
+        # runs unattended. Orphan cleanup is only ever done via the explicit
+        # `hermes checkpoints prune` command, which the user has to invoke.
         maybe_auto_prune_checkpoints(
             retention_days=int(cfg.get("retention_days", 7)),
             min_interval_hours=int(cfg.get("min_interval_hours", 24)),
-            delete_orphans=bool(cfg.get("delete_orphans", True)),
+            delete_orphans=False,
             max_total_size_mb=int(cfg.get("max_total_size_mb", 500)),
         )
     except Exception as exc:
@@ -2042,6 +2163,21 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
 
     Also prunes orphaned ``hermes/*`` and ``pr-*`` local branches that
     have no corresponding worktree.
+
+    Performance: this runs on the startup path of every ``hermes -w`` session,
+    and each candidate tree costs several git subprocesses (the ``git cherry``
+    patch-equivalence probe dominates at ~0.2-1.0s on a large repo). With
+    dozens of accumulated worktrees the serial version added ~11-18s of latency
+    before the banner. Two changes keep the decisions byte-identical while
+    removing nearly all of that:
+
+    1. The read-only classification of each tree (dirty / unpushed / merged /
+       lock state) is independent per tree, so it runs on a thread pool. Only
+       the mutating phase (unlock, remove, branch -D) stays serial and ordered.
+    2. ``git cherry`` verdicts are memoized on disk keyed by the exact
+       ``(base_sha, head_sha)`` range they were computed from, so a tree
+       preserved for unpushed work is not re-diff-hashed on every subsequent
+       startup.
     """
     import re
     import subprocess
@@ -2059,7 +2195,11 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
     # dispatcher-driven lifecycle (hermes kanban gc) — never touch them here.
     kanban_re = re.compile(r"^t_[0-9a-f]+$")
 
-    for entry in worktrees_dir.iterdir():
+    # ── Phase 1: age filter (no subprocesses) ───────────────────────────────
+    # Cheap stat-only pass so the thread pool below is sized to the trees that
+    # actually need git work, not to everything on disk.
+    candidates: list = []
+    for entry in sorted(worktrees_dir.iterdir()):
         if not entry.is_dir() or kanban_re.match(entry.name):
             continue
 
@@ -2070,7 +2210,6 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
         soft_cutoff = now - (tier_hours * 3600)
         hard_cutoff = now - (tier_hours * 3 * 3600)
 
-        # Check age
         try:
             mtime = entry.stat().st_mtime
             if mtime > soft_cutoff:
@@ -2078,24 +2217,42 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
         except Exception:
             continue
 
-        force = mtime <= hard_cutoff  # Aggressive tier — reap clean trees
+        candidates.append((entry, mtime, mtime <= hard_cutoff))
 
+    if not candidates:
+        _prune_orphaned_branches(repo_root)
+        return
+
+    # ── Phase 2: classify in parallel (read-only git queries) ───────────────
+    # Every check here is a read-only git query against a distinct worktree, so
+    # they are safe to run concurrently (git takes no repo-wide lock for these,
+    # and each has its own index). Verdicts are collected and applied serially
+    # below so removal order and log output stay deterministic.
+    merge_cache = _load_worktree_merge_cache()
+    cache_size_before = len(merge_cache)
+    cache_lock = threading.Lock()
+
+    def _classify(item):
+        entry, mtime, force = item
         # Never delete real work, regardless of age or tier. Uncommitted
         # changes and unpushed commits may be a crashed session's in-flight
         # work; only clean, fully-merged/pushed trees (the scratch trees that
         # actually cause .worktrees/ bloat) are ever reaped.
         if _worktree_is_dirty(str(entry), timeout=5):
-            if mtime <= stale_work_cutoff:
-                preserved_stale.append(f"{entry.name} (uncommitted changes)")
-            continue
+            return (entry, mtime, force, "dirty", None)
         if _worktree_has_unpushed_commits(str(entry), timeout=5):
             # Squash-merge escape hatch: commits unreachable from any remote
             # ref but patch-equivalent to upstream commits are merged work,
             # not unpushed work.
-            if not _worktree_commits_all_merged_upstream(str(entry), timeout=30):
-                if mtime <= stale_work_cutoff:
-                    preserved_stale.append(f"{entry.name} (unpushed commits)")
-                continue
+            with cache_lock:
+                snapshot = dict(merge_cache)
+            merged = _worktree_commits_all_merged_upstream(
+                str(entry), timeout=30, cache=snapshot
+            )
+            with cache_lock:
+                merge_cache.update(snapshot)
+            if not merged:
+                return (entry, mtime, force, "unpushed", None)
 
         # Respect git-native session locks. A lock owned by a still-running
         # hermes process means the worktree is actively in use — never touch
@@ -2104,13 +2261,47 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
         # otherwise dead-locked worktrees pile up indefinitely.
         lock_state = _worktree_lock_is_live(repo_root, str(entry), timeout=5)
         if lock_state == "live":
+            return (entry, mtime, force, "locked-live", None)
+        return (entry, mtime, force, "reap", lock_state)
+
+    # Bounded pool: enough to hide git's per-process startup latency without
+    # spawning dozens of concurrent git processes on a small machine.
+    workers = max(1, min(8, (os.cpu_count() or 4), len(candidates)))
+    try:
+        if workers > 1:
+            with concurrent.futures.ThreadPoolExecutor(
+                max_workers=workers, thread_name_prefix="hermes-wt-prune"
+            ) as pool:
+                verdicts = list(pool.map(_classify, candidates))
+        else:
+            verdicts = [_classify(c) for c in candidates]
+    except Exception as e:
+        # Never let a pool failure block startup — fall back to serial.
+        logger.debug("Parallel worktree classification failed (%s); serial", e)
+        verdicts = [_classify(c) for c in candidates]
+
+    if len(merge_cache) != cache_size_before:
+        _save_worktree_merge_cache(merge_cache)
+
+    # ── Phase 3: mutate serially (unlock / remove / branch -D) ──────────────
+    for entry, mtime, force, verdict, lock_state in verdicts:
+        if verdict == "dirty":
+            if mtime <= stale_work_cutoff:
+                preserved_stale.append(f"{entry.name} (uncommitted changes)")
+            continue
+        if verdict == "unpushed":
+            if mtime <= stale_work_cutoff:
+                preserved_stale.append(f"{entry.name} (unpushed commits)")
+            continue
+        if verdict == "locked-live":
             logger.debug("Skipping live-locked worktree: %s", entry.name)
             continue
+
         if lock_state == "dead":
             try:
                 subprocess.run(
                     ["git", "worktree", "unlock", str(entry)],
-                    capture_output=True, text=True, timeout=10, cwd=repo_root,
+                    capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10, cwd=repo_root,
                 )
             except Exception as e:
                 logger.debug("Failed to unlock dead worktree %s: %s", entry.name, e)
@@ -2119,13 +2310,13 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
         try:
             branch_result = subprocess.run(
                 ["git", "branch", "--show-current"],
-                capture_output=True, text=True, timeout=5, cwd=str(entry),
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5, cwd=str(entry),
             )
             branch = branch_result.stdout.strip()
 
             remove_result = subprocess.run(
                 ["git", "worktree", "remove", str(entry), "--force"],
-                capture_output=True, text=True, timeout=15, cwd=repo_root,
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=15, cwd=repo_root,
             )
             if remove_result.returncode != 0:
                 # Removal failed — keep the branch so any commits stay
@@ -2138,7 +2329,7 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
             if branch:
                 subprocess.run(
                     ["git", "branch", "-D", branch],
-                    capture_output=True, text=True, timeout=10, cwd=repo_root,
+                    capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10, cwd=repo_root,
                 )
             logger.debug("Pruned stale worktree: %s (force=%s)", entry.name, force)
         except Exception as e:
@@ -2166,7 +2357,7 @@ def _prune_orphaned_branches(repo_root: str) -> None:
     try:
         result = subprocess.run(
             ["git", "branch", "--format=%(refname:short)"],
-            capture_output=True, text=True, timeout=10, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10, cwd=repo_root,
         )
         if result.returncode != 0:
             return
@@ -2179,7 +2370,7 @@ def _prune_orphaned_branches(repo_root: str) -> None:
     try:
         wt_result = subprocess.run(
             ["git", "worktree", "list", "--porcelain"],
-            capture_output=True, text=True, timeout=10, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10, cwd=repo_root,
         )
         for line in wt_result.stdout.split("\n"):
             if line.startswith("branch refs/heads/"):
@@ -2191,7 +2382,7 @@ def _prune_orphaned_branches(repo_root: str) -> None:
     try:
         head_result = subprocess.run(
             ["git", "branch", "--show-current"],
-            capture_output=True, text=True, timeout=5, cwd=repo_root,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5, cwd=repo_root,
         )
         current = head_result.stdout.strip()
         if current:
@@ -2215,7 +2406,7 @@ def _prune_orphaned_branches(repo_root: str) -> None:
         try:
             subprocess.run(
                 ["git", "branch", "-D"] + batch,
-                capture_output=True, text=True, timeout=30, cwd=repo_root,
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=30, cwd=repo_root,
             )
         except Exception as e:
             logger.debug("Failed to prune orphaned branches: %s", e)
@@ -3853,6 +4044,28 @@ def save_config_value(key_path: str, value: any) -> bool:
 # HermesCLI Class
 # ============================================================================
 
+
+def _normalize_moa_model(model: Optional[str]) -> tuple[Optional[str], Optional[str]]:
+    """Map a ``moa:<preset>`` model string to ``(provider, preset)``.
+
+    Returns ``("moa", "<preset>")`` when *model* selects the MoA virtual
+    provider, otherwise ``(None, model)`` unchanged. This gives non-interactive
+    ``hermes chat -Q -m moa:<preset>`` the same routing the interactive
+    ``/moa`` command and the model picker already use: ``resolve_runtime_provider``
+    handles ``requested_provider == "moa"`` and ``agent_init`` builds the
+    MoAClient off ``provider == "moa"``. Without this the raw ``moa:<preset>``
+    string is sent to the real provider and rejected with a 401/400 "model not
+    supported" (#56828).
+    """
+    if isinstance(model, str):
+        stripped = model.strip()
+        if stripped.lower().startswith("moa:"):
+            preset = stripped.split(":", 1)[1].strip()
+            if preset:
+                return "moa", preset
+    return None, model
+
+
 class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
     """
     Interactive CLI for the Hermes Agent.
@@ -3983,6 +4196,12 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
         _config_model = (_model_config.get("default") or _model_config.get("model") or "") if isinstance(_model_config, dict) else (_model_config or "")
         _DEFAULT_CONFIG_MODEL = ""
         self.model = model or _config_model or _DEFAULT_CONFIG_MODEL
+        # A ``moa:<preset>`` model string selects the MoA virtual provider in
+        # one shot (parity with interactive ``/moa`` and the model picker). Do
+        # this before provider resolution so ``-Q -m moa:<preset>`` routes
+        # through MoA instead of hitting the real provider with an unknown
+        # model (#56828). A ``moa:`` prefix wins over an explicit ``--provider``.
+        _moa_provider_override, self.model = _normalize_moa_model(self.model)
         # Read max_tokens from config (env var override: HERMES_MAX_TOKENS)
         _env_mt = os.environ.get("HERMES_MAX_TOKENS")
         if _env_mt:
@@ -4018,7 +4237,8 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
 
         # Provider selection is resolved lazily at use-time via _ensure_runtime_credentials().
         self.requested_provider = (
-            provider
+            _moa_provider_override
+            or provider
             or CLI_CONFIG["model"].get("provider")
             or os.getenv("HERMES_INFERENCE_PROVIDER")
             or "auto"
@@ -6992,7 +7212,11 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
     
     def show_tools(self):
         """Display available tools with kawaii ASCII art."""
-        tools = get_tool_definitions(enabled_toolsets=self.enabled_toolsets, quiet_mode=True)
+        # Pre-assembly list: /tools is a discovery/inspection surface, so it
+        # must show the full catalog including tools deferred behind the
+        # tool_search bridge (users check this to verify an MCP installed).
+        tools = get_tool_definitions(enabled_toolsets=self.enabled_toolsets, quiet_mode=True,
+                                     skip_tool_search_assembly=True)
         
         if not tools:
             print("(;_;) No tools available")
@@ -9251,6 +9475,10 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
             self._show_gateway_status()
         elif canonical == "status":
             self._show_session_status()
+        elif canonical == "egress":
+            from hermes_cli.proxy_cli import format_status_text
+
+            self._console_print(format_status_text(), highlight=False, markup=False)
         elif canonical == "statusbar":
             self._status_bar_visible = not self._status_bar_visible
             state = "visible" if self._status_bar_visible else "hidden"
@@ -9491,7 +9719,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
                             from hermes_cli._subprocess_compat import windows_hide_flags
                             result = subprocess.run(
                                 exec_cmd, shell=True, capture_output=True,
-                                text=True, timeout=30, env=sanitized_env,
+                                text=True, encoding="utf-8", errors="replace", timeout=30, env=sanitized_env,
                                 # No console flash on Windows (#56747).
                                 creationflags=windows_hide_flags(),
                             )
diff --git a/contributors/emails/0301chris@gmail.com b/contributors/emails/0301chris@gmail.com
new file mode 100644
index 00000000000..e606f25d466
--- /dev/null
+++ b/contributors/emails/0301chris@gmail.com
@@ -0,0 +1,2 @@
+0301chris
+# PR #71555 salvage (desktop: gated /api/health readiness probe)
diff --git a/contributors/emails/445481611@qq.com b/contributors/emails/445481611@qq.com
new file mode 100644
index 00000000000..12b00748896
--- /dev/null
+++ b/contributors/emails/445481611@qq.com
@@ -0,0 +1 @@
+kael-odin
diff --git a/contributors/emails/aakash@plasticlabs.ai b/contributors/emails/aakash@plasticlabs.ai
new file mode 100644
index 00000000000..a4e5078d452
--- /dev/null
+++ b/contributors/emails/aakash@plasticlabs.ai
@@ -0,0 +1 @@
+akattelu
diff --git a/contributors/emails/agent@hermes.dev b/contributors/emails/agent@hermes.dev
new file mode 100644
index 00000000000..7df321f3dde
--- /dev/null
+++ b/contributors/emails/agent@hermes.dev
@@ -0,0 +1 @@
+webtecnica
diff --git a/contributors/emails/alanrbox@gmail.com b/contributors/emails/alanrbox@gmail.com
new file mode 100644
index 00000000000..433a77184dc
--- /dev/null
+++ b/contributors/emails/alanrbox@gmail.com
@@ -0,0 +1 @@
+AlanBurningsuit
diff --git a/contributors/emails/awain7@gmail.com b/contributors/emails/awain7@gmail.com
new file mode 100644
index 00000000000..8d7ed80296f
--- /dev/null
+++ b/contributors/emails/awain7@gmail.com
@@ -0,0 +1,2 @@
+awain7
+# PR #58261 salvage
diff --git a/contributors/emails/bedirhancode@users.noreply.github.com b/contributors/emails/bedirhancode@users.noreply.github.com
new file mode 100644
index 00000000000..cd7b020db5c
--- /dev/null
+++ b/contributors/emails/bedirhancode@users.noreply.github.com
@@ -0,0 +1 @@
+bedirhancode
diff --git a/contributors/emails/beingsabundant@gmail.com b/contributors/emails/beingsabundant@gmail.com
new file mode 100644
index 00000000000..a54f6effbc8
--- /dev/null
+++ b/contributors/emails/beingsabundant@gmail.com
@@ -0,0 +1 @@
+abundantbeing
diff --git a/contributors/emails/chancelu@users.noreply.github.com b/contributors/emails/chancelu@users.noreply.github.com
new file mode 100644
index 00000000000..c921dc7354b
--- /dev/null
+++ b/contributors/emails/chancelu@users.noreply.github.com
@@ -0,0 +1 @@
+chancelu
diff --git a/contributors/emails/chaosxinglong@gmail.com b/contributors/emails/chaosxinglong@gmail.com
new file mode 100644
index 00000000000..dac570b1739
--- /dev/null
+++ b/contributors/emails/chaosxinglong@gmail.com
@@ -0,0 +1 @@
+chaos-xxl
diff --git a/contributors/emails/cluster2@Cluster2s-Mac-Studio.local b/contributors/emails/cluster2@Cluster2s-Mac-Studio.local
new file mode 100644
index 00000000000..0a829ee7efa
--- /dev/null
+++ b/contributors/emails/cluster2@Cluster2s-Mac-Studio.local
@@ -0,0 +1 @@
+robgfl45
diff --git a/contributors/emails/dhruv.raajjeev@gmail.com b/contributors/emails/dhruv.raajjeev@gmail.com
new file mode 100644
index 00000000000..751dd98c655
--- /dev/null
+++ b/contributors/emails/dhruv.raajjeev@gmail.com
@@ -0,0 +1 @@
+dhruvraajeev
diff --git a/contributors/emails/eagleyouxiang@gmail.com b/contributors/emails/eagleyouxiang@gmail.com
new file mode 100644
index 00000000000..5e3ba0a4569
--- /dev/null
+++ b/contributors/emails/eagleyouxiang@gmail.com
@@ -0,0 +1 @@
+eagle-nyp
diff --git a/contributors/emails/floatingrain@yeah.net b/contributors/emails/floatingrain@yeah.net
new file mode 100644
index 00000000000..80165203d5b
--- /dev/null
+++ b/contributors/emails/floatingrain@yeah.net
@@ -0,0 +1 @@
+floatingrain
diff --git a/contributors/emails/fred.vanwagenen@gmail.com b/contributors/emails/fred.vanwagenen@gmail.com
new file mode 100644
index 00000000000..e6175ab6667
--- /dev/null
+++ b/contributors/emails/fred.vanwagenen@gmail.com
@@ -0,0 +1 @@
+FvanW
diff --git a/contributors/emails/h-chenbin@voyah.com.cn b/contributors/emails/h-chenbin@voyah.com.cn
new file mode 100644
index 00000000000..71404b97f27
--- /dev/null
+++ b/contributors/emails/h-chenbin@voyah.com.cn
@@ -0,0 +1 @@
+ms-alan
diff --git a/contributors/emails/hellofrommorgan@users.noreply.github.com b/contributors/emails/hellofrommorgan@users.noreply.github.com
new file mode 100644
index 00000000000..0787203fc7b
--- /dev/null
+++ b/contributors/emails/hellofrommorgan@users.noreply.github.com
@@ -0,0 +1 @@
+hellofrommorgan
diff --git a/contributors/emails/idrisalmalki@Idriss-MacBook-Air.local b/contributors/emails/idrisalmalki@Idriss-MacBook-Air.local
new file mode 100644
index 00000000000..8ea8798405e
--- /dev/null
+++ b/contributors/emails/idrisalmalki@Idriss-MacBook-Air.local
@@ -0,0 +1 @@
+quantumbyte1617
diff --git a/contributors/emails/iniak@iniakdeMac-mini.local b/contributors/emails/iniak@iniakdeMac-mini.local
new file mode 100644
index 00000000000..56e9c8b5d1a
--- /dev/null
+++ b/contributors/emails/iniak@iniakdeMac-mini.local
@@ -0,0 +1 @@
+iniak
diff --git a/contributors/emails/janig88@gmail.com b/contributors/emails/janig88@gmail.com
new file mode 100644
index 00000000000..2eb927a7e08
--- /dev/null
+++ b/contributors/emails/janig88@gmail.com
@@ -0,0 +1,2 @@
+Janig88
+# PR #58402 salvage
diff --git a/contributors/emails/jasmine@smfworks.com b/contributors/emails/jasmine@smfworks.com
new file mode 100644
index 00000000000..555718c0c5a
--- /dev/null
+++ b/contributors/emails/jasmine@smfworks.com
@@ -0,0 +1 @@
+smfworks
diff --git a/contributors/emails/jerry@hermes.local b/contributors/emails/jerry@hermes.local
new file mode 100644
index 00000000000..fdb939b79e8
--- /dev/null
+++ b/contributors/emails/jerry@hermes.local
@@ -0,0 +1 @@
+zhangyang-crazy-one
diff --git a/contributors/emails/jevin@jevin.org b/contributors/emails/jevin@jevin.org
new file mode 100644
index 00000000000..edf0ffe8849
--- /dev/null
+++ b/contributors/emails/jevin@jevin.org
@@ -0,0 +1 @@
+ijevin
diff --git a/contributors/emails/jinglun010@gmail.com b/contributors/emails/jinglun010@gmail.com
new file mode 100644
index 00000000000..f16b979a2c7
--- /dev/null
+++ b/contributors/emails/jinglun010@gmail.com
@@ -0,0 +1 @@
+jinglun010-cpu
diff --git a/contributors/emails/jrfbch@gmail.com b/contributors/emails/jrfbch@gmail.com
new file mode 100644
index 00000000000..480c6667547
--- /dev/null
+++ b/contributors/emails/jrfbch@gmail.com
@@ -0,0 +1 @@
+jrfbch
diff --git a/contributors/emails/kinsonnee@gmail.com b/contributors/emails/kinsonnee@gmail.com
new file mode 100644
index 00000000000..8094ea9fd25
--- /dev/null
+++ b/contributors/emails/kinsonnee@gmail.com
@@ -0,0 +1 @@
+WOLIKIMCHENG
diff --git a/contributors/emails/kuangmi@nudge.com.cn b/contributors/emails/kuangmi@nudge.com.cn
new file mode 100644
index 00000000000..7f3575558dd
--- /dev/null
+++ b/contributors/emails/kuangmi@nudge.com.cn
@@ -0,0 +1 @@
+kuangmi-bit
diff --git a/contributors/emails/kudi3699@gmail.com b/contributors/emails/kudi3699@gmail.com
new file mode 100644
index 00000000000..a4a578803bc
--- /dev/null
+++ b/contributors/emails/kudi3699@gmail.com
@@ -0,0 +1 @@
+kudi88
diff --git a/contributors/emails/leo@gtmcore.ai b/contributors/emails/leo@gtmcore.ai
new file mode 100644
index 00000000000..b61779c6ff7
--- /dev/null
+++ b/contributors/emails/leo@gtmcore.ai
@@ -0,0 +1,2 @@
+leoprodz
+# PR #71602 salvage (desktop: gated /api/health readiness probe)
diff --git a/contributors/emails/lesbetes28@gmail.com b/contributors/emails/lesbetes28@gmail.com
new file mode 100644
index 00000000000..3790e398235
--- /dev/null
+++ b/contributors/emails/lesbetes28@gmail.com
@@ -0,0 +1 @@
+dolphin-creator
diff --git a/contributors/emails/liruixinch@outlook.com b/contributors/emails/liruixinch@outlook.com
new file mode 100644
index 00000000000..a1cf96ff89d
--- /dev/null
+++ b/contributors/emails/liruixinch@outlook.com
@@ -0,0 +1,2 @@
+HexLab98
+# PR #71205 salvage (desktop: gated /api/health readiness probe)
diff --git a/contributors/emails/mannnrachman@users.noreply.github.com b/contributors/emails/mannnrachman@users.noreply.github.com
new file mode 100644
index 00000000000..bed3dbde7b5
--- /dev/null
+++ b/contributors/emails/mannnrachman@users.noreply.github.com
@@ -0,0 +1 @@
+mannnrachman
diff --git a/contributors/emails/mpetrelli@gmail.com b/contributors/emails/mpetrelli@gmail.com
new file mode 100644
index 00000000000..0a943bf232e
--- /dev/null
+++ b/contributors/emails/mpetrelli@gmail.com
@@ -0,0 +1 @@
+Ne0teric
diff --git a/contributors/emails/muhammadfurqan0100@gmail.com b/contributors/emails/muhammadfurqan0100@gmail.com
new file mode 100644
index 00000000000..25edb831008
--- /dev/null
+++ b/contributors/emails/muhammadfurqan0100@gmail.com
@@ -0,0 +1 @@
+immuhammadfurqan
diff --git a/contributors/emails/nypyouxiang@163.com b/contributors/emails/nypyouxiang@163.com
new file mode 100644
index 00000000000..5e3ba0a4569
--- /dev/null
+++ b/contributors/emails/nypyouxiang@163.com
@@ -0,0 +1 @@
+eagle-nyp
diff --git a/contributors/emails/phixxation@gmail.com b/contributors/emails/phixxation@gmail.com
new file mode 100644
index 00000000000..1bc5a8ff69f
--- /dev/null
+++ b/contributors/emails/phixxation@gmail.com
@@ -0,0 +1 @@
+VerbalChainsaw
diff --git a/contributors/emails/rain@synth.kitchen b/contributors/emails/rain@synth.kitchen
new file mode 100644
index 00000000000..de1f34f8281
--- /dev/null
+++ b/contributors/emails/rain@synth.kitchen
@@ -0,0 +1,2 @@
+matarbot
+# PR #60391 salvage
diff --git a/contributors/emails/robbyczgw@gmail.com b/contributors/emails/robbyczgw@gmail.com
new file mode 100644
index 00000000000..0e2f03da202
--- /dev/null
+++ b/contributors/emails/robbyczgw@gmail.com
@@ -0,0 +1 @@
+robbyczgw-cla
diff --git a/contributors/emails/roger.hanhong@gmail.com b/contributors/emails/roger.hanhong@gmail.com
new file mode 100644
index 00000000000..2fd7ab83dd2
--- /dev/null
+++ b/contributors/emails/roger.hanhong@gmail.com
@@ -0,0 +1,2 @@
+Roger--Han
+# PR #62990 salvage (issue #63078)
diff --git a/contributors/emails/ruizanthony@users.noreply.github.com b/contributors/emails/ruizanthony@users.noreply.github.com
new file mode 100644
index 00000000000..a6a1870a013
--- /dev/null
+++ b/contributors/emails/ruizanthony@users.noreply.github.com
@@ -0,0 +1 @@
+ruizanthony
diff --git a/contributors/emails/sjq15251852316@gmail.com b/contributors/emails/sjq15251852316@gmail.com
new file mode 100644
index 00000000000..66d56022748
--- /dev/null
+++ b/contributors/emails/sjq15251852316@gmail.com
@@ -0,0 +1 @@
+oppenheimor
diff --git a/contributors/emails/stephenlopez2030@gmail.com b/contributors/emails/stephenlopez2030@gmail.com
new file mode 100644
index 00000000000..e0710ccbcad
--- /dev/null
+++ b/contributors/emails/stephenlopez2030@gmail.com
@@ -0,0 +1,2 @@
+Slopez2023
+# PR #71668 salvage (desktop: gated /api/health readiness probe)
diff --git a/contributors/emails/steve.darlow@gmail.com b/contributors/emails/steve.darlow@gmail.com
new file mode 100644
index 00000000000..bc2e0fbbc86
--- /dev/null
+++ b/contributors/emails/steve.darlow@gmail.com
@@ -0,0 +1 @@
+kerpopule
diff --git a/contributors/emails/stoltemberg@users.noreply.github.com b/contributors/emails/stoltemberg@users.noreply.github.com
new file mode 100644
index 00000000000..38b203b47c0
--- /dev/null
+++ b/contributors/emails/stoltemberg@users.noreply.github.com
@@ -0,0 +1 @@
+Stoltemberg
diff --git a/contributors/emails/theone139344@users.noreply.github.com b/contributors/emails/theone139344@users.noreply.github.com
new file mode 100644
index 00000000000..43a4b147372
--- /dev/null
+++ b/contributors/emails/theone139344@users.noreply.github.com
@@ -0,0 +1 @@
+theone139344
diff --git a/contributors/emails/upicat@users.noreply.github.com b/contributors/emails/upicat@users.noreply.github.com
new file mode 100644
index 00000000000..d0c2fcdd500
--- /dev/null
+++ b/contributors/emails/upicat@users.noreply.github.com
@@ -0,0 +1 @@
+upicat
diff --git a/contributors/emails/webtecnica@users.noreply.github.com b/contributors/emails/webtecnica@users.noreply.github.com
new file mode 100644
index 00000000000..21d31aebbc7
--- /dev/null
+++ b/contributors/emails/webtecnica@users.noreply.github.com
@@ -0,0 +1,2 @@
+webtecnica
+# PR #69500 salvage
diff --git a/contributors/emails/wen0531@gmail.com b/contributors/emails/wen0531@gmail.com
new file mode 100644
index 00000000000..2ba4c0fd0c0
--- /dev/null
+++ b/contributors/emails/wen0531@gmail.com
@@ -0,0 +1 @@
+wen0531
diff --git a/contributors/emails/wrjie@msn.cn b/contributors/emails/wrjie@msn.cn
new file mode 100644
index 00000000000..0eca1eddae3
--- /dev/null
+++ b/contributors/emails/wrjie@msn.cn
@@ -0,0 +1 @@
+jeeaay
diff --git a/contributors/emails/xiehong@xinjikang.cn b/contributors/emails/xiehong@xinjikang.cn
new file mode 100644
index 00000000000..77d0aae8a1b
--- /dev/null
+++ b/contributors/emails/xiehong@xinjikang.cn
@@ -0,0 +1,2 @@
+seamusmore
+# PR #64339 salvage
diff --git a/contributors/emails/zhunyunjiang@gmail.com b/contributors/emails/zhunyunjiang@gmail.com
new file mode 100644
index 00000000000..8facdf1b007
--- /dev/null
+++ b/contributors/emails/zhunyunjiang@gmail.com
@@ -0,0 +1 @@
+akb4q
diff --git a/cron/executions.py b/cron/executions.py
index 6ffe1eef1fc..fac24357335 100644
--- a/cron/executions.py
+++ b/cron/executions.py
@@ -12,8 +12,9 @@ import os
 import sqlite3
 import threading
 import uuid
+from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, Iterator, List, Optional
 
 from hermes_constants import get_hermes_home
 from hermes_time import now as _hermes_now
@@ -26,10 +27,13 @@ _PROCESS_ID = uuid.uuid4().hex
 
 
 def _connect() -> sqlite3.Connection:
+    EXECUTIONS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    return sqlite3.connect(EXECUTIONS_FILE, timeout=5)
+
+
+def _initialize_schema(conn: sqlite3.Connection) -> None:
     from hermes_state import apply_wal_with_fallback
 
-    EXECUTIONS_FILE.parent.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(EXECUTIONS_FILE, timeout=5)
     conn.row_factory = sqlite3.Row
     conn.execute("PRAGMA busy_timeout=5000")
     apply_wal_with_fallback(conn, db_label="cron/executions.db")
@@ -58,7 +62,27 @@ def _connect() -> sqlite3.Connection:
         "CREATE INDEX IF NOT EXISTS idx_executions_status_claimed "
         "ON executions(status, claimed_at DESC, id DESC)"
     )
-    return conn
+
+
+@contextmanager
+def _transaction() -> Iterator[sqlite3.Connection]:
+    """Open a connection, commit/rollback on exit, always close.
+
+    ``sqlite3.Connection.__enter__``/``__exit__`` only commit or roll back
+    the transaction; it does not close the connection. Relying on that alone
+    leaks a connection (and its WAL/SHM file descriptors) on every call,
+    since closing then depends on the garbage collector. Schema init runs
+    inside the ``try`` too, so a PRAGMA/DDL failure after a successful
+    ``connect()`` still closes the connection instead of leaking it.
+    """
+    with _lock:
+        conn = _connect()
+        try:
+            _initialize_schema(conn)
+            with conn:
+                yield conn
+        finally:
+            conn.close()
 
 
 def _record(row: Optional[sqlite3.Row]) -> Optional[Dict[str, Any]]:
@@ -103,7 +127,7 @@ def create_execution(job_id: str, *, source: str) -> Dict[str, Any]:
     now = _hermes_now().isoformat()
     execution_id = uuid.uuid4().hex
     pid = os.getpid()
-    with _lock, _connect() as conn:
+    with _transaction() as conn:
         conn.execute(
             """INSERT INTO executions
                (id, job_id, source, process_id, pid, process_started_at,
@@ -121,7 +145,7 @@ def create_execution(job_id: str, *, source: str) -> Dict[str, Any]:
 def mark_execution_running(execution_id: str) -> Optional[Dict[str, Any]]:
     """Transition one claimed attempt to running exactly once."""
     now = _hermes_now().isoformat()
-    with _lock, _connect() as conn:
+    with _transaction() as conn:
         cur = conn.execute(
             """UPDATE executions SET status='running', started_at=?
                WHERE id=? AND status='claimed'""",
@@ -141,7 +165,7 @@ def finish_execution(
     now = _hermes_now().isoformat()
     status = "completed" if success else "failed"
     detail = None if success else (str(error) if error else "unknown failure")
-    with _lock, _connect() as conn:
+    with _transaction() as conn:
         cur = conn.execute(
             """UPDATE executions SET status=?, finished_at=?, error=?
                WHERE id=? AND status IN ('claimed','running')""",
@@ -159,7 +183,7 @@ def recover_interrupted_executions() -> int:
     """Mark provably abandoned attempts unknown without scheduling retries."""
     now = _hermes_now().isoformat()
     changed = 0
-    with _lock, _connect() as conn:
+    with _transaction() as conn:
         rows = conn.execute(
             """SELECT id, process_id, pid, process_started_at FROM executions
                WHERE status IN ('claimed','running')"""
@@ -198,7 +222,7 @@ def list_executions(
         params.append(str(before_claimed_at))
     where = " WHERE " + " AND ".join(clauses) if clauses else ""
     params.append(max(1, min(int(limit), 500)))
-    with _lock, _connect() as conn:
+    with _transaction() as conn:
         rows = conn.execute(
             "SELECT * FROM executions" + where
             + " ORDER BY claimed_at DESC, id DESC LIMIT ?",
@@ -218,7 +242,7 @@ def latest_executions(job_ids: List[str]) -> Dict[str, Dict[str, Any]]:
     if not clean:
         return {}
     placeholders = ",".join("?" for _ in clean)
-    with _lock, _connect() as conn:
+    with _transaction() as conn:
         rows = conn.execute(
             f"""SELECT e.* FROM executions e
                 WHERE e.job_id IN ({placeholders})
diff --git a/cron/jobs.py b/cron/jobs.py
index 7ecd17abbd5..356385cdce7 100644
--- a/cron/jobs.py
+++ b/cron/jobs.py
@@ -475,6 +475,44 @@ def _secure_file(path: Path):
         pass
 
 
+def _preserve_file_ownership(path: Path, before: Optional[os.stat_result]) -> None:
+    """Restore a rewritten file's previous owner (POSIX, privileged writer only).
+
+    The atomic-write pattern (mkstemp + replace) makes the rewritten file owned
+    by the *writer's* euid. When a root shell runs a state-writing cron CLI
+    command (``docker exec hermes hermes cron create ...`` — ``docker exec``
+    defaults to root) against a store owned by the unprivileged gateway user,
+    the replace flips ``jobs.json`` to ``root:root`` mode 600 and the gateway's
+    ticker (uid 1000) is silently locked out of every subsequent tick (#68483).
+
+    Root can always hand ownership back, so do exactly that: when the euid is 0
+    and the pre-replace owner differs, chown the new file to the previous
+    uid/gid. Unprivileged writers are a no-op (their own rewrite already heals
+    a root-owned file back to their uid, and they couldn't chown anyway).
+    No-op on Windows. Best-effort: a failure must never break the save.
+    """
+    if before is None or os.name != "posix":
+        return
+    geteuid = getattr(os, "geteuid", None)
+    getegid = getattr(os, "getegid", None)
+    if geteuid is None or getegid is None:
+        return
+    try:
+        euid = geteuid()
+        if euid != 0:
+            return  # unprivileged writer — nothing to (or we could) restore
+        if (before.st_uid, before.st_gid) == (euid, getegid()):
+            return  # already ours before the rewrite — nothing changed
+        os.chown(path, before.st_uid, before.st_gid)
+    except OSError as e:
+        logger.warning(
+            "Could not restore ownership of %s to uid=%s gid=%s after rewrite: %s "
+            "— if the gateway runs as a different user, its cron ticker may now "
+            "be locked out (see issue #68483).",
+            path, before.st_uid, before.st_gid, e,
+        )
+
+
 def ensure_dirs():
     """Ensure cron directories exist with secure permissions."""
     store = _current_cron_store()
@@ -816,15 +854,20 @@ def record_ticker_heartbeat(success: bool = False) -> None:
     (both fresh) — a ticker stuck failing every tick would otherwise keep the
     plain heartbeat fresh and falsely report healthy (#32612, #32895).
 
+    Resolution uses ``_current_cron_store()`` so the heartbeat is correctly
+    scoped to the active profile's store — critical under multiplex_profiles
+    where each profile needs its own liveness signal (#69377).
+
     Best-effort: a write failure must never disrupt the tick loop.
     """
+    store = _current_cron_store()
     try:
-        _atomic_write_epoch(TICKER_HEARTBEAT_FILE)
+        _atomic_write_epoch(store.cron_dir / "ticker_heartbeat")
     except Exception:
         pass
     if success:
         try:
-            _atomic_write_epoch(TICKER_SUCCESS_FILE)
+            _atomic_write_epoch(store.cron_dir / "ticker_last_success")
         except Exception:
             pass
 
@@ -842,13 +885,82 @@ def get_ticker_heartbeat_age() -> Optional[float]:
 
     None = heartbeat file missing/unreadable (older build, never ran, or a
     torn read). Callers treat None as "cannot determine", not "dead".
+
+    Resolution uses ``_current_cron_store()`` so the heartbeat is correctly
+    scoped to the active profile — critical under multiplex_profiles where
+    ``hermes cron status`` must report per-profile liveness (#69377).
     """
-    return _epoch_file_age(TICKER_HEARTBEAT_FILE)
+    store = _current_cron_store()
+    return _epoch_file_age(store.cron_dir / "ticker_heartbeat")
 
 
 def get_ticker_success_age() -> Optional[float]:
-    """Seconds since the ticker last completed a tick WITHOUT raising, or None."""
-    return _epoch_file_age(TICKER_SUCCESS_FILE)
+    """Seconds since the ticker last completed a tick WITHOUT raising, or None.
+
+    Resolution uses ``_current_cron_store()`` so the heartbeat is correctly
+    scoped to the active profile — critical under multiplex_profiles where
+    ``hermes cron status`` must report per-profile liveness (#69377).
+    """
+    store = _current_cron_store()
+    return _epoch_file_age(store.cron_dir / "ticker_last_success")
+
+
+def record_ticker_error(message: str) -> None:
+    """Persist the most recent tick failure so other processes can surface it.
+
+    The ticker thread lives inside the gateway process; ``hermes cron
+    status``/``list`` run in a separate process and previously could only
+    infer "ticks may be failing" from marker staleness, with no clue WHY.
+    A root-owned ``jobs.json`` (#68483) failed every tick for ~14h with the
+    reason visible only in the gateway's errors.log. Writing the last error
+    next to the heartbeat markers gives the CLI something concrete to show.
+
+    Best-effort: a write failure must never disrupt the tick loop.
+    """
+    store = _current_cron_store()
+    path = store.cron_dir / "ticker_last_error"
+    try:
+        ensure_dirs()
+        fd, tmp_path = tempfile.mkstemp(
+            dir=str(path.parent), suffix=".tmp", prefix=".terr_"
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(f"{time.time()}\n{message.strip()}\n")
+                f.flush()
+                os.fsync(f.fileno())
+            atomic_replace(tmp_path, path)
+        except BaseException:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+            raise
+    except Exception:
+        pass
+
+
+def clear_ticker_error() -> None:
+    """Remove the last-tick-error marker after a successful tick. Best-effort."""
+    store = _current_cron_store()
+    try:
+        (store.cron_dir / "ticker_last_error").unlink()
+    except OSError:
+        pass
+
+
+def get_ticker_last_error() -> Optional[str]:
+    """Return the most recent recorded tick error message, or None."""
+    store = _current_cron_store()
+    try:
+        raw = (store.cron_dir / "ticker_last_error").read_text(encoding="utf-8")
+    except Exception:
+        return None
+    lines = raw.splitlines()
+    if len(lines) < 2:
+        return None
+    message = "\n".join(lines[1:]).strip()
+    return message or None
 
 
 # =============================================================================
@@ -911,6 +1023,19 @@ def _save_jobs_unlocked(jobs: List[Dict[str, Any]]):
     """Save all jobs to storage. Caller must hold _jobs_lock()."""
     jobs_file = _current_cron_store().jobs_file
     ensure_dirs()
+    # Snapshot the current owner BEFORE the atomic replace so a privileged
+    # writer (root CLI in Docker) can hand ownership back to the gateway user
+    # afterwards instead of locking its ticker out (#68483). When the file is
+    # being created for the first time, inherit the cron dir's owner — in the
+    # Docker image that is the PUID/PGID gateway user who must be able to
+    # read the store on the next tick.
+    try:
+        _stat_before = os.stat(jobs_file)
+    except OSError:
+        try:
+            _stat_before = os.stat(jobs_file.parent)
+        except OSError:
+            _stat_before = None
     fd, tmp_path = tempfile.mkstemp(dir=str(jobs_file.parent), suffix='.tmp', prefix='.jobs_')
     try:
         with os.fdopen(fd, 'w', encoding='utf-8') as f:
@@ -919,6 +1044,7 @@ def _save_jobs_unlocked(jobs: List[Dict[str, Any]]):
             os.fsync(f.fileno())
         atomic_replace(tmp_path, jobs_file)
         _secure_file(jobs_file)
+        _preserve_file_ownership(jobs_file, _stat_before)
     except BaseException:
         try:
             os.unlink(tmp_path)
diff --git a/cron/scheduler.py b/cron/scheduler.py
index 7b00bfcb0f3..5bffb00e146 100644
--- a/cron/scheduler.py
+++ b/cron/scheduler.py
@@ -1586,16 +1586,26 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> Option
             delivery_errors.append(msg)
             continue
 
-        pconfig = config.platforms.get(platform)
+        from gateway.delivery import resolve_delivery_transport
+
+        transport = resolve_delivery_transport(platform, config, adapters)
+        if transport is not None:
+            pconfig = transport.config
+            runtime_adapter = transport.adapter
+        else:
+            # No live transport: preserve the existing standalone delivery path,
+            # which uses the logical platform's configured credential.
+            pconfig = config.platforms.get(platform)
+            runtime_adapter = None
+
         if not pconfig or not pconfig.enabled:
             msg = f"platform '{platform_name}' not configured/enabled"
             logger.warning("Job '%s': %s", job["id"], msg)
             delivery_errors.append(msg)
             continue
 
-        # Prefer the live adapter when the gateway is running — this supports E2EE
-        # rooms (e.g. Matrix) where the standalone HTTP path cannot encrypt.
-        runtime_adapter = (adapters or {}).get(platform)
+        # Prefer the resolved live transport when the gateway is running. This
+        # supports E2EE native adapters and relay-fronted logical platforms.
         # The live-send path (which SEEDS the flat in_channel continuation
         # session via _seed_cron_channel_session) needs not just a live adapter
         # but a running event loop to schedule the async send onto. Compute that
@@ -1900,10 +1910,13 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> Option
                                     f"live adapter send to {platform_name}:{chat_id} "
                                     f"returned unconfirmed result ({shape}, error={err})"
                                 )
-                                logger.warning(
-                                    "Job '%s': %s, falling back to standalone",
-                                    job["id"], msg,
-                                )
+                                if transport is not None and transport.is_relay:
+                                    logger.warning("Job '%s': %s", job["id"], msg)
+                                else:
+                                    logger.warning(
+                                        "Job '%s': %s, falling back to standalone",
+                                        job["id"], msg,
+                                    )
                                 target_errors.append(msg)
                                 adapter_ok = False  # fall through to standalone path
                             elif (
@@ -1929,11 +1942,20 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> Option
                 # skipped attachments so the drop is visible rather than silently
                 # lost.
                 if adapter_ok and not timed_out and media_files:
+                    routed_media_metadata = dict(media_metadata or {})
+                    if transport is not None and transport.is_relay:
+                        routed_media_metadata["_relay_logical_platform"] = platform.value
+                        logical_home = config.get_home_channel(platform)
+                        if logical_home is not None and logical_home.chat_id == chat_id:
+                            if logical_home.user_id:
+                                routed_media_metadata["user_id"] = logical_home.user_id
+                            if logical_home.scope_id:
+                                routed_media_metadata["scope_id"] = logical_home.scope_id
                     _send_media_via_adapter(
                         runtime_adapter,
                         chat_id,
                         media_files,
-                        media_metadata,
+                        routed_media_metadata or None,
                         loop,
                         job,
                         platform=platform,
@@ -1978,12 +2000,25 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> Option
                 err_msg = f"live adapter delivery to {platform_name}:{chat_id} failed: {e}"
                 if not any(err_msg in err for err in target_errors):
                     target_errors.append(err_msg)
-                logger.warning(
-                    "Job '%s': %s, falling back to standalone",
-                    job["id"], err_msg,
-                )
+                if transport is not None and transport.is_relay:
+                    logger.warning("Job '%s': %s", job["id"], err_msg)
+                else:
+                    logger.warning(
+                        "Job '%s': %s, falling back to standalone",
+                        job["id"], err_msg,
+                    )
 
         if not delivered:
+            if transport is not None and transport.is_relay:
+                # Relay owns the logical destination and its connector owns the
+                # platform credential. A native retry could duplicate delivery
+                # and cannot be authenticated correctly, so fail closed.
+                if not target_errors:
+                    target_errors.append(
+                        f"relay delivery to {platform_name}:{chat_id} failed"
+                    )
+                delivery_errors.extend(target_errors)
+                continue
             # If the interpreter is finalizing (gateway SIGTERM / restart /
             # OOM), scheduling any new delivery is futile — asyncio.run and a
             # fresh ThreadPoolExecutor both raise "cannot schedule new futures
@@ -2167,7 +2202,10 @@ def _windows_cron_python_invocation(python_exe: str) -> tuple[str, dict[str, str
     return str(interpreter), env_overlay
 
 
-def _run_job_script(script_path: str) -> tuple[bool, str]:
+def _run_job_script(
+    script_path: str,
+    workdir: Optional[str] = None,
+) -> tuple[bool, str]:
     """Execute a cron job's data-collection script and capture its output.
 
     Scripts must reside within HERMES_HOME/scripts/.  Both relative and
@@ -2193,6 +2231,12 @@ def _run_job_script(script_path: str) -> tuple[bool, str]:
         script_path: Path to the script.  Relative paths are resolved
             against HERMES_HOME/scripts/.  Absolute and ~-prefixed paths
             are also validated to ensure they stay within the scripts dir.
+        workdir: Optional absolute path to use as the script's cwd.
+            When set, the subprocess runs in this directory instead of
+            the scripts-dir parent.  The Python process cwd is NEVER
+            mutated, avoiding the global-side-effect bug where a cron
+            job's ``os.chdir()`` leaks into concurrent gateway sessions
+            (#69396).
 
     Returns:
         (success, output) — on failure *output* contains the error message so the
@@ -2263,12 +2307,17 @@ def _run_job_script(script_path: str) -> tuple[bool, str]:
             }
         env = _sanitize_subprocess_env(os.environ.copy())
         env.update(env_overlay)
+        # Use the job's workdir as the subprocess cwd when configured,
+        # otherwise default to the scripts-dir parent (back-compat).
+        # NEVER mutate the Python process cwd — that would leak into
+        # concurrent gateway sessions (#69396).
+        _script_cwd = workdir or str(path.parent)
         result = subprocess.run(
             argv,
             capture_output=True,
             text=True,
             timeout=script_timeout,
-            cwd=str(path.parent),
+            cwd=_script_cwd,
             env=env,
             **popen_kwargs,
         )
@@ -2302,7 +2351,7 @@ def _run_job_script(script_path: str) -> tuple[bool, str]:
 
 
 def _run_job_script_with_claim_heartbeat(
-    job: dict, script_path: str
+    job: dict, script_path: str, workdir: Optional[str] = None,
 ) -> tuple[bool, str]:
     """Run a cron script while keeping its owned one-shot claim fresh.
 
@@ -2324,7 +2373,7 @@ def _run_job_script_with_claim_heartbeat(
         and schedule.get("kind") == "once"
         and owner
     ):
-        return _run_job_script(script_path)
+        return _run_job_script(script_path, workdir=workdir)
 
     job_id = str(job.get("id") or "")
     stop = threading.Event()
@@ -2355,10 +2404,10 @@ def _run_job_script_with_claim_heartbeat(
             job_id,
             exc_info=True,
         )
-        return _run_job_script(script_path)
+        return _run_job_script(script_path, workdir=workdir)
 
     try:
-        return _run_job_script(script_path)
+        return _run_job_script(script_path, workdir=workdir)
     finally:
         stop.set()
         # Event.wait() wakes immediately.  Keep completion bounded if the
@@ -2761,25 +2810,26 @@ def run_job(
             return False, "", "", err
 
         # Apply workdir if configured — lets scripts use predictable relative
-        # paths. For no_agent jobs this is just the subprocess cwd (not an
-        # agent TERMINAL_CWD bridge).
+        # paths. For no_agent jobs this is passed as the subprocess cwd so the
+        # Python process cwd is NEVER mutated — avoiding the global-side-effect
+        # bug where os.chdir() leaks into concurrent gateway sessions (#69396).
         _job_workdir = (job.get("workdir") or "").strip() or None
-        _prior_cwd = None
-        if _job_workdir and Path(_job_workdir).is_dir():
-            _prior_cwd = os.getcwd()
-            try:
-                os.chdir(_job_workdir)
-            except OSError:
-                _prior_cwd = None
+        if _job_workdir and not Path(_job_workdir).is_dir():
+            logger.warning(
+                "Job '%s': configured workdir %r no longer exists — running without it",
+                job_id, _job_workdir,
+            )
+            _job_workdir = None
 
         try:
-            ok, output = _run_job_script_with_claim_heartbeat(job, script_path)
-        finally:
-            if _prior_cwd is not None:
-                try:
-                    os.chdir(_prior_cwd)
-                except OSError:
-                    pass
+            ok, output = _run_job_script_with_claim_heartbeat(
+                job, script_path, workdir=_job_workdir,
+            )
+        except Exception as exc:
+            logger.exception(
+                "Job '%s': script execution raised unexpectedly", job_id,
+            )
+            ok, output = False, f"Script execution failed: {exc}"
 
         now_iso = _hermes_now().strftime("%Y-%m-%d %H:%M:%S")
 
@@ -3001,6 +3051,18 @@ def run_job(
     # Cron output delivery itself reads job["origin"] directly via
     # _resolve_origin(job) and the HERMES_CRON_AUTO_DELIVER_* vars set
     # below, so clearing HERMES_SESSION_* here does not affect delivery.
+    # Resolve workdir BEFORE set_session_vars so we can pass it as cwd=,
+    # letting set_session_vars handle the _SESSION_CWD ContextVar set/clear
+    # via its existing machinery (clear_session_vars calls clear_session_cwd
+    # internally). This avoids a separate import/set/clear dance (#69396).
+    _job_workdir = (job.get("workdir") or "").strip() or None
+    if _job_workdir and not Path(_job_workdir).is_dir():
+        logger.warning(
+            "Job '%s': configured workdir %r no longer exists — running without it",
+            job_id, _job_workdir,
+        )
+        _job_workdir = None
+
     _ctx_tokens = set_session_vars(
         platform="",
         chat_id="",
@@ -3019,6 +3081,7 @@ def run_job(
         # inline/synchronous path, so results return within the job's own turn.
         # See declare_stateless_channel(). Upstream: #53027, #63142.
         async_delivery=False,
+        cwd=_job_workdir or "",
     )
     _cron_delivery_vars = (
         "HERMES_CRON_AUTO_DELIVER_PLATFORM",
@@ -3028,11 +3091,10 @@ def run_job(
     for _var_name in _cron_delivery_vars:
         _VAR_MAP[_var_name].set("")
 
-    # Per-job working directory.  When set (and validated at create/update
-    # time), we point TERMINAL_CWD at it so:
-    #   - build_context_files_prompt() picks up AGENTS.md / CLAUDE.md /
-    #     .cursorrules from the job's project dir, AND
-    #   - the terminal, file, and code-exec tools run commands from there.
+    # Per-job working directory — _SESSION_CWD was already set via
+    # set_session_vars(cwd=...) above. Here we only handle the
+    # process-global TERMINAL_CWD env var, which is serialized by
+    # _terminal_cwd_lock to avoid leaking into concurrent jobs.
     #
     # os.environ["TERMINAL_CWD"] is process-global, so this override is
     # serialized by _terminal_cwd_lock (acquired just below): a workdir job
@@ -3044,15 +3106,10 @@ def run_job(
     # file / code-exec commands in the wrong directory.  For workdir-less jobs
     # we leave TERMINAL_CWD untouched — preserves the original behaviour
     # (skip_context_files=True, tools use whatever cwd the scheduler has).
-    _job_workdir = (job.get("workdir") or "").strip() or None
-    if _job_workdir and not Path(_job_workdir).is_dir():
-        # Directory was removed between create-time validation and now.  Log
-        # and drop back to old behaviour rather than crashing the job.
-        logger.warning(
-            "Job '%s': configured workdir %r no longer exists — running without it",
-            job_id, _job_workdir,
-        )
-        _job_workdir = None
+    #
+    # The critical path (resolve_context_cwd / build_context_files_prompt)
+    # checks _SESSION_CWD first, so gateway sessions with no override see
+    # their own cwd, not the cron's workdir (#69396).
 
     # Snapshot the current env value BEFORE acquiring the lock so the finally
     # below can always restore it, even if an exception fires before we set the
@@ -3681,6 +3738,8 @@ def run_job(
         else:
             _terminal_cwd_lock.release_read()
         # Clean up ContextVar session/delivery state for this job.
+        # clear_session_vars also clears _SESSION_CWD internally, so no
+        # separate clear_session_cwd() call is needed.
         clear_session_vars(_ctx_tokens)
         for _var_name in _cron_delivery_vars:
             _VAR_MAP[_var_name].set("")
diff --git a/cron/scheduler_provider.py b/cron/scheduler_provider.py
index b17d8341da3..4c20db01c6d 100644
--- a/cron/scheduler_provider.py
+++ b/cron/scheduler_provider.py
@@ -173,13 +173,46 @@ class InProcessCronScheduler(CronScheduler):
     def name(self) -> str:
         return "builtin"
 
-    def start(self, stop_event, *, adapters=None, loop=None, interval=60, can_dispatch=None):
+    def start(
+        self,
+        stop_event,
+        *,
+        adapters=None,
+        loop=None,
+        interval=60,
+        can_dispatch=None,
+        profile_homes=None,
+    ):
         import logging
         from cron.scheduler import tick as cron_tick
-        from cron.jobs import record_ticker_heartbeat
+        from cron.jobs import (
+            clear_ticker_error,
+            record_ticker_error,
+            record_ticker_heartbeat,
+        )
 
         logger = logging.getLogger("cron.scheduler_provider")
         logger.info("In-process cron scheduler started (interval=%ds)", interval)
+
+        # ── Multiplex profiles ────────────────────────────────────────────
+        # When profile_homes is set (multiplex_profiles on), tick EACH profile's
+        # cron store on every tick cycle so secondary-profile jobs actually fire
+        # instead of languishing in a store no ticker owns (#69377). Without this,
+        # only the process-global HERMES_HOME (the default profile) is ticked.
+        # Heartbeats and recovery are also scoped per profile so `hermes cron
+        # status` reflects liveness for every profile independently.
+        if profile_homes:
+            self._start_multiplex(
+                stop_event,
+                profile_homes=profile_homes,
+                adapters=adapters,
+                loop=loop,
+                interval=interval,
+                can_dispatch=can_dispatch,
+            )
+            return
+
+        # ── Single-profile (legacy) path ──────────────────────────────────
         recovered = self.recover_interrupted()
         if recovered:
             logger.warning(
@@ -212,8 +245,113 @@ class InProcessCronScheduler(CronScheduler):
                 # an exception in this daemon thread, so swallowing it and
                 # re-checking stop_event keeps shutdown clean.
                 logger.error("Cron tick error: %s", e, exc_info=True)
+                # Persist the failure reason next to the heartbeat markers so
+                # `hermes cron status`/`list` (separate processes) can show
+                # WHY ticks fail, not just that the success marker is stale —
+                # e.g. a root-rewritten jobs.json locking out the ticker's
+                # uid went unnoticed for ~14h with the reason buried in the
+                # gateway log (#68483).
+                record_ticker_error(f"{type(e).__name__}: {e}")
             # Record liveness every iteration; bump the success marker only on a
             # clean tick, so status can tell "alive but failing every tick" from
             # "actually firing jobs" (#32612, #32895).
             record_ticker_heartbeat(success=ok)
+            if ok:
+                clear_ticker_error()
+            stop_event.wait(interval)
+
+    def _start_multiplex(
+        self,
+        stop_event,
+        *,
+        profile_homes,
+        adapters=None,
+        loop=None,
+        interval=60,
+        can_dispatch=None,
+    ):
+        """Tick every served profile's cron store when multiplex_profiles is on.
+
+        Each profile uses ``set_hermes_home_override()`` + ``use_cron_store()``
+        to scope its tick, heartbeat, recovery, lock file, config/.env, and
+        agent execution to that profile's home — mirroring how
+        ``_profile_runtime_scope`` scopes the multiplexed inbound path and
+        ``web_server.py`` scopes per-profile cron API calls.
+        """
+        import logging
+        from cron.scheduler import tick as cron_tick
+        from cron.jobs import (
+            clear_ticker_error,
+            record_ticker_error,
+            record_ticker_heartbeat,
+            use_cron_store,
+        )
+        from hermes_constants import set_hermes_home_override, reset_hermes_home_override
+
+        logger = logging.getLogger("cron.scheduler_provider")
+        logger.info(
+            "Multiplex cron scheduler started for %d profile(s): %s",
+            len(profile_homes),
+            [p[0] if isinstance(p, tuple) else p for p in profile_homes],
+        )
+
+        # Recovery + initial heartbeat for every profile.
+        for entry in profile_homes:
+            home = entry[1] if isinstance(entry, tuple) else entry
+            home_token = set_hermes_home_override(str(home))
+            try:
+                with use_cron_store(home):
+                    recovered = self.recover_interrupted()
+                    if recovered:
+                        logger.warning(
+                            "Marked %d interrupted cron execution(s) for profile at %s",
+                            recovered,
+                            home,
+                        )
+                    record_ticker_heartbeat()
+            finally:
+                reset_hermes_home_override(home_token)
+
+        while not stop_event.is_set():
+            ok = False
+            try:
+                if can_dispatch is not None and not can_dispatch():
+                    logger.debug("Cron dispatch paused while gateway drains existing work")
+                else:
+                    for entry in profile_homes:
+                        home = entry[1] if isinstance(entry, tuple) else entry
+                        home_token = set_hermes_home_override(str(home))
+                        try:
+                            with use_cron_store(home):
+                                cron_tick(
+                                    verbose=False,
+                                    adapters=adapters,
+                                    loop=loop,
+                                    sync=False,
+                                    can_dispatch=can_dispatch,
+                                )
+                        finally:
+                            reset_hermes_home_override(home_token)
+                ok = True
+            except BaseException as e:
+                logger.error("Cron tick error: %s", e, exc_info=True)
+                _tick_error = f"{type(e).__name__}: {e}"
+            else:
+                _tick_error = None
+            # Record per-profile heartbeat after each tick cycle.
+            for entry in profile_homes:
+                home = entry[1] if isinstance(entry, tuple) else entry
+                home_token = set_hermes_home_override(str(home))
+                try:
+                    with use_cron_store(home):
+                        record_ticker_heartbeat(success=ok)
+                        # Surface the failure reason (or clear it) per profile
+                        # so `hermes cron status` can show WHY ticks fail
+                        # (#68483).
+                        if ok:
+                            clear_ticker_error()
+                        elif _tick_error:
+                            record_ticker_error(_tick_error)
+                finally:
+                    reset_hermes_home_override(home_token)
             stop_event.wait(interval)
diff --git a/docs/relay-connector-contract.md b/docs/relay-connector-contract.md
index 6560139c2ae..3698b55432a 100644
--- a/docs/relay-connector-contract.md
+++ b/docs/relay-connector-contract.md
@@ -52,6 +52,7 @@ JSON object. Source of truth: `gateway/relay/descriptor.py`.
 | `platform_hint` | string | no | System-prompt platform hint. |
 | `pii_safe` | bool | no | Redact PII in session descriptions. |
 | `supports_context` | bool | no | Whether the connector can supply surrounding channel/group **context** for an addressed turn on this platform (Model A on-demand history fetch — Discord/Slack/Matrix; Model B passive buffer — Telegram/Signal/WhatsApp). Default false ⇒ no `context` is attached to inbound events. See §3. |
+| `supported_ops` | string[] | no | Op-level capability discovery: the outbound op names the connector's sender for this platform actually implements (e.g. `["send", "edit", "typing", "follow_up", "get_chat_info"]`). Absent/empty ⇒ the connector predates the field and the gateway assumes the legacy op set (`send`/`edit`/`typing`/`follow_up`); a NEW op is used only when explicitly advertised. |
 
 Most fields are a projection of the gateway's existing `PlatformEntry`; the
 runtime-only fields (`len_unit`, `supports_*`, `markdown_dialect`) come from the
@@ -393,10 +394,133 @@ The gateway calls the transport with action dicts. Source of truth:
 | `edit` | `chat_id`, `message_id`, `content`, `metadata?` | `{success: bool, error?}` |
 | `typing` | `chat_id`, `content?`, `metadata?` | `{success: bool}` |
 | `follow_up` | `session_key`, `kind`, `content`, `metadata?` | `{success: bool, message_id?, error?}` |
+| `send_media` | `chat_id`, `media_kind`, `source_url`, `content?` (caption), `filename?`, `reply_to?`, `metadata?` | `{success: bool, message_id?, error?}` |
+| `prompt` | `chat_id`, `prompt_kind`, `prompt_id`, `content` (the question), `options[]{id,label,style?}`, `timeout_s?`, `reply_to?`, `metadata?` | `{success: bool, message_id?, error?}` |
+| `react` | `chat_id`, `message_id`, `emoji`, `remove?`, `metadata?` | `{success: bool, error?}` |
+| `thread_create` | `chat_id` (parent), `thread_name`, `message_id?` (anchor), `metadata?` | `{success: bool, thread_id?, error?}` |
+| `thread_rename` | `chat_id` (parent), `message_id` (the THREAD id), `thread_name`, `only_if_current_name?`, `metadata?` | `{success: bool, error?}` |
 
 `get_chat_info(chat_id)` is a separate proxied call returning at least
-`{name, type}`. Media actions follow the same envelope shape (deferred to a
-later contract revision; additive).
+`{name, type}`.
+
+**`send_media` (Phase 2 media egress).** Media crosses the wire BY REFERENCE:
+`source_url` is either (a) a **connector re-host** the gateway previously
+uploaded via `POST {connector}/relay/media` (raw bytes body, `Content-Type` +
+optional `X-Media-Filename` headers, per-gateway HMAC bearer — the same token
+scheme as the WS upgrade; response `{id, size}` → reference
+`{connector}/relay/media/{id}`), or (b) a **public http(s) URL** (e.g. a
+fal.media generation) the connector downloads directly. `media_kind` is one of
+`image` / `voice` / `audio` / `video` / `document` and selects the
+platform-native upload lane (Telegram `sendPhoto`/`sendVoice`/…, Discord
+multipart attachment, Slack external upload, WhatsApp media upload + media
+message). The caption rides `content` and renders through the platform's
+normal markdown lane; platforms without native captions get a follow-up text
+send (connector-side). Both routes and the op are gated on `supported_ops`
+advertising `send_media` — a legacy connector never sees the op (the gateway's
+media sends degrade to their pre-media text fallbacks). Size cap 25 MB
+(connector `mediaStore.ts` MEDIA_MAX_BYTES; uploads over it are rejected 413).
+
+**Inbound media (Phase 2 media ingress).** An inbound event's `media_urls`
+carry fetchable references: platform-public URLs pass through (Discord CDN);
+auth-gated/expiring platform URLs (Telegram file API, Slack `url_private`,
+WhatsApp Graph media) are downloaded connector-side with the PLATFORM
+credential and re-hosted as `{connector}/relay/media/{id}` — the platform
+credential never crosses the wire. Re-host references are readable by any
+authenticated gateway (capability-URL semantics: the id is 128-bit random and
+was already delivered to every admitted recipient); the gateway downloads each
+reference with its per-gateway bearer and presents LOCAL file paths to the
+agent, mirroring native adapters. Re-hosts expire (TTL ~1h) — download on
+receipt, not lazily. A parallel `media` array (same order) adds `kind`, `mime`,
+`size`, `filename`, `caption` metadata; `message_type` reflects the first
+attachment's kind (`image`/`audio`/`document`).
+
+**`prompt` (Phase 3 interactive).** One platform-abstract op renders the
+gateway's highest-stakes interactions (exec approvals, slash confirms,
+clarify pickers) with NATIVE controls: Discord button components, Telegram
+inline keyboards, Slack Block Kit actions, WhatsApp button messages (≤3
+options) / list messages (4–10; >10 degrades to the numbered-text fallback).
+`prompt_kind` (`approval`/`clarify`/`choice`) is a styling hint only.
+`prompt_id` is gateway-minted (8 hex) and opaque to the connector; each
+option's callback payload carries the token `hp1:<prompt_id>:<option_id>`
+(≤64 bytes — Telegram's `callback_data` cap binds every lane; option ids are
+`[A-Za-z0-9_.-]`, ≤32 chars). `style` maps per-platform
+(primary/success/danger/secondary). `timeout_s` is advisory on the wire —
+expiry is enforced GATEWAY-side (the pending-prompt registry drops expired
+entries; a stale press falls through as typed text, mirroring the native
+adapters' "approval expired" edit).
+
+**`prompt_response` (Phase 3 inbound).** The user's press crosses back as a
+normal inbound MessageEvent carrying
+`prompt_response: {prompt_id, option_id, label?, prompt_message_id?}` — never
+a bare platform `custom_id`. The event's `text` mirrors `/{option_id}` with
+`message_type: "command"` so a gateway predating the field routes the press
+as a typed reply instead of dropping it. The SOURCE is the authentic
+CLICKING user (connector-observed: Telegram `callback_query.from`, Slack
+`block_actions.user`, WhatsApp `messages[].from`, Discord interaction
+member/user), so gateway-side authorization gates apply to a button press
+exactly as to a typed `/approve`. Ingest lanes: Telegram `callback_query`
+(polled, `allowed_updates` widened; best-effort `answerCallbackQuery`
+spinner-stop), Slack `POST /slack/interactions` (raw-bytes HMAC + replay
+window, same posture as `/slack/commands`), WhatsApp interactive
+`button_reply`/`list_reply` (webhook normalize arm), Discord type-3
+component interactions (passthrough §5.1 sanitized forward; the type-3 edge
+ack is `DEFERRED_UPDATE` so no visible "thinking…" reply). Foreign
+callback payloads (another integration's buttons) never become prompt
+events: Telegram/Slack/WhatsApp drop them at the connector; Discord type-3
+forwards keep the legacy custom_id-as-text shape.
+
+**`react` (Phase 3 ack lifecycle).** Adds/removes the bot's own `emoji`
+reaction on `message_id` — restoring the native adapters' 👀→✅/❌
+processing-lifecycle acks over the relay. Unicode emoji on the wire; the
+Slack sender maps to Slack's name vocabulary (`eyes`, `white_check_mark`, …)
+and treats `already_reacted`/`no_reaction` as success (idempotent). Telegram
+uses `setMessageReaction` (empty set = remove; Telegram's curated-emoji
+restriction can reject glyphs — the failure is structured and the gateway
+treats reactions as cosmetic). WhatsApp sends a reaction message (empty
+emoji = remove). Reactions are best-effort by contract: a `react` failure
+must never fail a turn.
+
+**`thread_create` / `thread_rename` (Phase 4 thread lifecycle).** One
+platform-abstract pair covers handoff threads, Telegram DM/forum topics, and
+LLM-title semantic renames. `thread_create`: Discord posts a channel thread
+(type 11) or a message-anchored thread when `message_id` is set; Telegram
+`createForumTopic` (topic id returned); Slack posts a NAMED seed root
+message and returns its `ts` (threads there are message-anchored — an
+explicit `message_id` anchor is echoed back verbatim). The created id rides
+`SendResult.thread_id`. `thread_rename`: Discord PATCHes the thread channel;
+Telegram `editForumTopic`. The **`only_if_current_name` no-clobber guard**
+is the native adapters' human-rename-wins semantics, enforced
+CONNECTOR-side: Discord reads the current name first and no-ops (structured
+`success:false`) on mismatch; Telegram has no topic-name read, so a GUARDED
+rename is unsatisfiable and fails safe (unguarded renames proceed). Slack
+does not advertise `thread_rename` (a root message's text is content, not a
+name). WhatsApp advertises neither (no threads).
+
+**Auto-thread markers + gateway-declared command manifest (Phase 4
+inbound/handshake).** When the connector's auto-thread egress policy creates
+a Discord thread, later inbound events from that thread carry
+`source.auto_thread_created: true` + `source.auto_thread_initial_name` — the
+connector-observed evidence that lights the gateway's semantic-rename lane
+(the LLM session title renames the thread via a GUARDED `thread_rename`;
+per-instance memory, so in an N>1 fleet a miss simply never lights the
+lane). The gateway may also declare its slash-command set on the Discord
+`hello` frame (`command_manifest: [{name, description, options?}]`); the
+connector reconciles Discord's GLOBAL application-command registration
+against it (GET → diff → bulk PUT overwrite; idempotent, debounced,
+best-effort — a registration failure never affects the handshake). Commands
+still dispatch through the passthrough plane as before; the manifest only
+keeps Discord's registry in sync with what the gateway's dispatcher handles.
+
+**Inbound `reply_to` enrichment (Phase 4).** A platform reply may carry
+`reply_to: {text?, author?, is_own?}` alongside `reply_to_message_id` — what
+the user QUOTED, populated only from data the connector already had in hand
+(Discord's inline `referenced_message`, Telegram's inline
+`reply_to_message`, WhatsApp `context.from` + a bounded per-instance
+inbound-text cache for the text leg). Absent fields mean the platform didn't
+carry the data — never triggers an extra platform API call. `is_own` = the
+quoted message was authored by the fronted bot (same evidence as the
+`is_reply_to_bot` relevance marker). The gateway maps these onto the same
+MessageEvent reply-context fields native adapters populate.
 
 **`typing` `content?` (Slack status clear).** A `typing` frame normally omits
 `content` — the connector renders its platform's active indicator ("is
diff --git a/gateway/config.py b/gateway/config.py
index 01c906cbd2e..781a9421733 100644
--- a/gateway/config.py
+++ b/gateway/config.py
@@ -431,6 +431,11 @@ class HomeChannel:
     chat_id: str
     name: str  # Human-readable name for display
     thread_id: Optional[str] = None
+    # Authenticated logical-target provenance observed by a platform adapter.
+    # Relay egress re-attaches these values, but the connector remains the
+    # authorization boundary and resolves them against its authoritative stores.
+    user_id: Optional[str] = None
+    scope_id: Optional[str] = None
     
     def to_dict(self) -> Dict[str, Any]:
         result = {
@@ -440,6 +445,10 @@ class HomeChannel:
         }
         if self.thread_id:
             result["thread_id"] = self.thread_id
+        if self.user_id:
+            result["user_id"] = self.user_id
+        if self.scope_id:
+            result["scope_id"] = self.scope_id
         return result
     
     @classmethod
@@ -449,9 +458,30 @@ class HomeChannel:
             chat_id=str(data["chat_id"]),
             name=data.get("name", "Home"),
             thread_id=str(data["thread_id"]) if data.get("thread_id") else None,
+            user_id=str(data["user_id"]) if data.get("user_id") else None,
+            scope_id=str(data["scope_id"]) if data.get("scope_id") else None,
         )
 
 
+def persist_home_channel(home: HomeChannel, *, enabled_if_new: bool = False) -> None:
+    """Persist a logical home without falsely enabling a Relay-fronted adapter."""
+    from hermes_cli.config import load_config, save_config
+
+    config = load_config()
+    platforms = config.setdefault("platforms", {})
+    if not isinstance(platforms, dict):
+        platforms = {}
+        config["platforms"] = platforms
+    platform_config = platforms.setdefault(home.platform.value, {})
+    if not isinstance(platform_config, dict):
+        platform_config = {}
+        platforms[home.platform.value] = platform_config
+    if enabled_if_new:
+        platform_config.setdefault("enabled", True)
+    platform_config["home_channel"] = home.to_dict()
+    save_config(config)
+
+
 @dataclass
 class SessionResetPolicy:
     """
@@ -900,6 +930,13 @@ class GatewayConfig:
     # disables sd_notify at runtime.
     systemd_watchdog_seconds: int = 0
 
+    # In-process event-loop liveness watchdog (#69089). A daemon OS thread
+    # probes the gateway loop with call_soon_threadsafe; after consecutive
+    # missed probes it dumps all-thread stacks and hard-exits with the
+    # service-restart code so the supervisor can revive the process. On by
+    # default; set gateway.loop_watchdog: false in config.yaml to disable.
+    loop_watchdog: bool = True
+
     # Unauthorized DM policy
     unauthorized_dm_behavior: str = "pair"  # "pair" or "ignore"
 
@@ -1034,6 +1071,7 @@ class GatewayConfig:
             "max_concurrent_sessions": self.max_concurrent_sessions,
             "multiplex_profiles": self.multiplex_profiles,
             "systemd_watchdog_seconds": self.systemd_watchdog_seconds,
+            "loop_watchdog": self.loop_watchdog,
             "unauthorized_dm_behavior": self.unauthorized_dm_behavior,
             "streaming": self.streaming.to_dict(),
             "session_store_max_age_days": self.session_store_max_age_days,
@@ -1105,6 +1143,11 @@ class GatewayConfig:
         systemd_watchdog_seconds = coerce_systemd_watchdog_seconds(
             systemd_watchdog_raw, systemd_watchdog_key
         )
+        if "loop_watchdog" in data:
+            loop_watchdog_raw = data.get("loop_watchdog")
+        else:
+            loop_watchdog_raw = nested_gateway.get("loop_watchdog")
+        loop_watchdog = _coerce_bool(loop_watchdog_raw, True)
         if multiplex_profiles is None and isinstance(nested_gateway, dict):
             # Also honor gateway.multiplex_profiles written by
             # ``hermes config set gateway.multiplex_profiles true``.
@@ -1165,6 +1208,7 @@ class GatewayConfig:
             thread_sessions_per_user=_coerce_bool(thread_sessions_per_user, False),
             multiplex_profiles=_coerce_bool(multiplex_profiles, False),
             systemd_watchdog_seconds=systemd_watchdog_seconds,
+            loop_watchdog=loop_watchdog,
             max_concurrent_sessions=max_concurrent_sessions,
             unauthorized_dm_behavior=unauthorized_dm_behavior,
             streaming=StreamingConfig.from_dict(data.get("streaming", {})),
@@ -1942,12 +1986,20 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
         # send Slack messages can use it without activating the gateway adapter.
         config.platforms[Platform.SLACK].token = slack_token
     slack_home = getenv("SLACK_HOME_CHANNEL")
-    if slack_home and Platform.SLACK in config.platforms:
-        config.platforms[Platform.SLACK].home_channel = HomeChannel(
+    if slack_home:
+        slack_config = config.platforms.setdefault(
+            Platform.SLACK,
+            PlatformConfig(enabled=False),
+        )
+        existing_home = slack_config.home_channel
+        same_home = existing_home is not None and existing_home.chat_id == slack_home
+        slack_config.home_channel = HomeChannel(
             platform=Platform.SLACK,
             chat_id=slack_home,
             name=getenv("SLACK_HOME_CHANNEL_NAME", ""),
             thread_id=getenv("SLACK_HOME_CHANNEL_THREAD_ID") or None,
+            user_id=existing_home.user_id if existing_home and same_home else None,
+            scope_id=existing_home.scope_id if existing_home and same_home else None,
         )
     
     # Signal
diff --git a/gateway/dead_targets.py b/gateway/dead_targets.py
index 66a9247f213..15f9b908794 100644
--- a/gateway/dead_targets.py
+++ b/gateway/dead_targets.py
@@ -67,7 +67,7 @@ class DeadTargetRegistry:
     def _load(self) -> None:
         try:
             if self._path.exists():
-                raw = json.loads(self._path.read_text())
+                raw = json.loads(self._path.read_text(encoding="utf-8"))
                 if isinstance(raw, dict):
                     # Only keep well-shaped entries.
                     self._dead = {
@@ -82,7 +82,7 @@ class DeadTargetRegistry:
         try:
             self._path.parent.mkdir(parents=True, exist_ok=True)
             tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-            tmp.write_text(json.dumps(self._dead, indent=2))
+            tmp.write_text(json.dumps(self._dead, indent=2), encoding="utf-8")
             tmp.replace(self._path)
         except OSError as exc:
             # Best-effort: keep the in-memory state, don't break delivery.
diff --git a/gateway/delivery.py b/gateway/delivery.py
index 77b245d291c..fa43db6d0f9 100644
--- a/gateway/delivery.py
+++ b/gateway/delivery.py
@@ -54,11 +54,83 @@ def _is_silence_narration(content: Optional[str]) -> bool:
         return False
     return bool(_SILENCE_NARRATION.match(stripped))
 
-from .config import Platform, GatewayConfig
+from .config import Platform, GatewayConfig, PlatformConfig
 from .session import SessionSource
 from .dead_targets import DeadTargetRegistry
 
 
+@dataclass(frozen=True)
+class DeliveryTransport:
+    """Resolved live transport for one logical delivery platform."""
+
+    adapter: Any
+    config: Optional[PlatformConfig]
+    transport_platform: Platform
+
+    @property
+    def is_relay(self) -> bool:
+        return self.transport_platform == Platform.RELAY
+
+    async def send(
+        self,
+        logical_platform: Platform,
+        chat_id: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]],
+    ) -> Any:
+        """Send through this transport while preserving the logical platform."""
+        if self.is_relay:
+            return await self.adapter.send_for_platform(
+                logical_platform,
+                chat_id,
+                content,
+                metadata=metadata,
+            )
+        return await self.adapter.send(chat_id, content, metadata=metadata)
+
+
+def resolve_delivery_transport(
+    platform: Platform,
+    config: GatewayConfig,
+    adapters: Optional[Dict[Platform, Any]],
+) -> Optional[DeliveryTransport]:
+    """Resolve a logical platform to its live delivery transport.
+
+    A concrete native adapter always wins. Relay is eligible only when its
+    authenticated transport explicitly advertises that it fronts the logical
+    platform, which keeps restart-time delivery independent of per-chat caches
+    without letting Relay hijack unrelated platform targets.
+    """
+    live_adapters = adapters or {}
+    native = live_adapters.get(platform)
+    native_config = config.platforms.get(platform)
+    # Preserve DeliveryRouter's historical support for explicitly supplied live
+    # adapters with no config block, but never let an explicitly disabled native
+    # adapter shadow an enabled Relay transport.
+    if native is not None and (native_config is None or native_config.enabled):
+        return DeliveryTransport(
+            adapter=native,
+            config=native_config,
+            transport_platform=platform,
+        )
+
+    relay = live_adapters.get(Platform.RELAY)
+    relay_config = config.platforms.get(Platform.RELAY)
+    fronts_platform = getattr(relay, "fronts_platform", None)
+    if (
+        relay is not None
+        and (relay_config is None or relay_config.enabled)
+        and callable(fronts_platform)
+        and fronts_platform(platform)
+    ):
+        return DeliveryTransport(
+            adapter=relay,
+            config=relay_config,
+            transport_platform=Platform.RELAY,
+        )
+    return None
+
+
 def looks_like_telegram_private_chat_id(chat_id: Optional[str]) -> bool:
     """True when ``chat_id`` is a positive int — Telegram's private-chat shape.
 
@@ -357,7 +429,7 @@ class DeliveryRouter:
         lines.append("")
         lines.append(content)
         
-        output_path.write_text("\n".join(lines))
+        output_path.write_text("\n".join(lines), encoding="utf-8")
         
         return {
             "path": str(output_path),
@@ -370,7 +442,7 @@ class DeliveryRouter:
         out_dir = get_hermes_home() / "cron" / "output"
         out_dir.mkdir(parents=True, exist_ok=True)
         path = out_dir / f"{job_id}_{timestamp}.txt"
-        path.write_text(content)
+        path.write_text(content, encoding="utf-8")
         return path
 
     def _filter_silence_narration_enabled(self) -> bool:
@@ -392,11 +464,11 @@ class DeliveryRouter:
         metadata: Optional[Dict[str, Any]]
     ) -> Dict[str, Any]:
         """Deliver content to a messaging platform."""
-        adapter = self.adapters.get(target.platform)
-        
-        if not adapter:
+        transport = resolve_delivery_transport(target.platform, self.config, self.adapters)
+        if transport is None:
             raise ValueError(f"No adapter configured for {target.platform.value}")
-        
+        adapter = transport.adapter
+
         if not target.chat_id:
             raise ValueError(f"No chat ID for {target.platform.value} delivery")
         
@@ -472,6 +544,13 @@ class DeliveryRouter:
             }
 
         send_metadata = dict(metadata or {})
+        if transport.is_relay:
+            home = self.config.get_home_channel(target.platform)
+            if home is not None and home.chat_id == target.chat_id:
+                if home.user_id:
+                    send_metadata["user_id"] = home.user_id
+                if home.scope_id:
+                    send_metadata["scope_id"] = home.scope_id
         is_named_telegram_private_topic = False
         named_telegram_private_topic_name: Optional[str] = None
         if target.thread_id:
@@ -524,7 +603,12 @@ class DeliveryRouter:
                 send_metadata["telegram_dm_topic_reply_fallback"] = True
             elif "thread_id" not in send_metadata and "message_thread_id" not in send_metadata and not has_explicit_direct_topic:
                 send_metadata["thread_id"] = target_thread_id
-        result = await adapter.send(target.chat_id, content, metadata=send_metadata or None)
+        result = await transport.send(
+            target.platform,
+            target.chat_id,
+            content,
+            metadata=send_metadata or None,
+        )
         if _send_result_failed(result):
             if (
                 is_named_telegram_private_topic
@@ -547,7 +631,12 @@ class DeliveryRouter:
                     )
                 send_metadata["thread_id"] = str(refreshed_thread_id)
                 send_metadata["telegram_dm_topic_created_for_send"] = True
-                result = await adapter.send(target.chat_id, content, metadata=send_metadata or None)
+                result = await transport.send(
+                    target.platform,
+                    target.chat_id,
+                    content,
+                    metadata=send_metadata or None,
+                )
             if _send_result_failed(result):
                 raise RuntimeError(_send_result_error(result) or f"{target.platform.value} delivery failed")
         return result
diff --git a/gateway/delivery_ledger.py b/gateway/delivery_ledger.py
index dac168c8572..e17f92b8ab4 100644
--- a/gateway/delivery_ledger.py
+++ b/gateway/delivery_ledger.py
@@ -46,7 +46,8 @@ import os
 import sqlite3
 import threading
 import time
-from typing import Any, Dict, List, Optional
+from contextlib import contextmanager
+from typing import Any, Dict, Iterator, List, Optional
 
 from hermes_constants import get_hermes_home
 
@@ -75,11 +76,22 @@ def _db_path():
 
 
 def _connect() -> sqlite3.Connection:
-    from hermes_state import apply_wal_with_fallback
-
     path = _db_path()
     path.parent.mkdir(parents=True, exist_ok=True)
     conn = sqlite3.connect(path, timeout=10)
+    try:
+        _initialize_schema(conn)
+    except Exception:
+        # A PRAGMA/DDL failure after a successful connect() must not leak the
+        # just-opened connection back to the caller.
+        conn.close()
+        raise
+    return conn
+
+
+def _initialize_schema(conn: sqlite3.Connection) -> None:
+    from hermes_state import apply_wal_with_fallback
+
     apply_wal_with_fallback(conn, db_label="state.db (delivery_ledger)")
     conn.execute(
         """CREATE TABLE IF NOT EXISTS delivery_obligations (
@@ -98,7 +110,26 @@ def _connect() -> sqlite3.Connection:
             last_error TEXT
         )"""
     )
-    return conn
+
+
+@contextmanager
+def _transaction() -> Iterator[sqlite3.Connection]:
+    """Open a connection, commit/rollback on exit, and ALWAYS close it.
+
+    ``sqlite3.Connection.__enter__``/``__exit__`` only commit or roll back the
+    transaction; they do not close the connection. Using ``with _connect()``
+    alone therefore leaks a connection — and its WAL/SHM file descriptors — on
+    every call, deferring the close to the garbage collector. On a long-running
+    gateway that exhausts ``RLIMIT_NOFILE`` (the cron-ledger sibling of this
+    bug was #69567 / PR #69594). ``record_obligation`` runs on every outbound
+    final response, so this ledger is the highest-frequency leaker.
+    """
+    conn = _connect()
+    try:
+        with conn:
+            yield conn
+    finally:
+        conn.close()
 
 
 def _owner_stamp() -> tuple[int, Optional[int]]:
@@ -166,7 +197,7 @@ def record_obligation(
     """Record a final response as owed to the platform (state='pending')."""
     now = time.time()
     pid, started = _owner_stamp()
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         conn.execute(
             """INSERT OR REPLACE INTO delivery_obligations
                (obligation_id, session_key, platform, chat_id, thread_id,
@@ -193,7 +224,7 @@ def mark_failed(obligation_id: str, error: str = "") -> None:
 
 
 def _update_state(obligation_id: str, state: str, error: str = "") -> None:
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         conn.execute(
             """UPDATE delivery_obligations
                SET state=?, updated_at=?, last_error=?
@@ -226,7 +257,7 @@ def sweep_recoverable(
     now = now if now is not None else time.time()
     pid, started = _owner_stamp()
     claimed: List[Dict[str, Any]] = []
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         rows = conn.execute(
             """SELECT obligation_id, session_key, platform, chat_id, thread_id,
                       content, state, attempts, created_at,
@@ -279,7 +310,7 @@ def _prune(now: Optional[float] = None) -> None:
     now = now if now is not None else time.time()
     cutoff = now - _RETENTION_SECONDS
     try:
-        with _connect() as conn:
+        with _transaction() as conn:
             conn.execute(
                 """DELETE FROM delivery_obligations
                    WHERE state IN ('delivered', 'abandoned') AND updated_at < ?""",
@@ -323,7 +354,7 @@ def ledger_enabled(config: Optional[Dict[str, Any]] = None) -> bool:
 
 def debug_rows(limit: int = 20) -> str:
     """Human-readable dump for ad-hoc inspection (sqlite3-free path)."""
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         rows = conn.execute(
             """SELECT obligation_id, session_key, state, attempts,
                       created_at, updated_at, last_error
diff --git a/gateway/platforms/api_server.py b/gateway/platforms/api_server.py
index e9d79bf71d5..a1b066a85b4 100644
--- a/gateway/platforms/api_server.py
+++ b/gateway/platforms/api_server.py
@@ -168,6 +168,172 @@ def _coerce_request_bool(value: Any, default: bool = False) -> bool:
     return default
 
 
+_REQUEST_OPTION_MISSING = object()
+_REASONING_EFFORTS = frozenset({"none", "minimal", "low", "medium", "high", "xhigh"})
+_RUNTIME_AGENT_OVERRIDE_KEYS = (
+    "api_key",
+    "base_url",
+    "provider",
+    "api_mode",
+    "command",
+    "args",
+    "credential_pool",
+    "max_tokens",
+)
+
+
+def _clean_request_string(value: Any) -> Optional[str]:
+    """Return a stripped request string, or None for absent/non-string values."""
+    if not isinstance(value, str):
+        return None
+    cleaned = value.strip()
+    return cleaned or None
+
+
+def _request_reasoning_config(model_options: Any) -> Optional[Dict[str, Any]]:
+    """Translate browser/API model_options into AIAgent reasoning_config.
+
+    The browser extension sends both a structured ``reasoning`` object and a
+    compatibility ``reasoning_effort`` scalar.  Keep this parser permissive so
+    older clients can send either shape, but ignore unknown effort values rather
+    than raising on a chat request.
+    """
+    if not isinstance(model_options, dict):
+        return None
+
+    reasoning = model_options.get("reasoning")
+    enabled: Any = None
+    effort: Any = model_options.get("reasoning_effort")
+    if isinstance(reasoning, dict):
+        enabled = reasoning.get("enabled")
+        effort = reasoning.get("effort", effort)
+
+    effort_norm = str(effort).strip().lower() if effort is not None else ""
+    if enabled is False or effort_norm == "none":
+        return {"enabled": False}
+    if effort_norm in _REASONING_EFFORTS and effort_norm != "none":
+        return {"enabled": True, "effort": effort_norm}
+    if enabled is True:
+        return {"enabled": True}
+    return None
+
+
+def _request_service_tier(model_options: Any) -> Any:
+    """Return a per-request service_tier override or _REQUEST_OPTION_MISSING."""
+    if not isinstance(model_options, dict):
+        return _REQUEST_OPTION_MISSING
+    if "service_tier" in model_options:
+        raw_tier = model_options.get("service_tier")
+        if raw_tier is None:
+            return None
+        if isinstance(raw_tier, str):
+            return raw_tier.strip() or None
+        return raw_tier
+    if "fast" in model_options:
+        return "priority" if _coerce_request_bool(model_options.get("fast"), default=False) else None
+    return _REQUEST_OPTION_MISSING
+
+
+def _apply_runtime_agent_overrides(
+    runtime_kwargs: Dict[str, Any], overrides: Optional[Dict[str, Any]]
+) -> Dict[str, Any]:
+    """Merge resolved provider/runtime fields into ``runtime_kwargs`` in place."""
+    if not isinstance(overrides, dict):
+        return runtime_kwargs
+    for key in _RUNTIME_AGENT_OVERRIDE_KEYS:
+        if key not in overrides:
+            continue
+        value = overrides.get(key)
+        if value is None:
+            continue
+        runtime_kwargs[key] = list(value) if key == "args" and isinstance(value, (list, tuple)) else value
+    return runtime_kwargs
+
+
+def _resolve_request_runtime_agent_kwargs(provider: str, target_model: Optional[str] = None) -> Dict[str, Any]:
+    """Resolve runtime kwargs for a one-request provider override.
+
+    This mirrors gateway.run._resolve_runtime_agent_kwargs(), but accepts an
+    explicit provider/model so an API caller can use the same authenticated
+    provider catalog as the TUI without mutating config.yaml.
+    """
+    from hermes_cli.runtime_provider import resolve_runtime_provider, format_runtime_provider_error, _get_model_config
+
+    try:
+        runtime = resolve_runtime_provider(requested=provider, target_model=target_model)
+    except Exception as exc:
+        raise RuntimeError(format_runtime_provider_error(exc)) from exc
+
+    model_cfg = _get_model_config()
+    max_tokens = None
+    env_max_tokens = os.environ.get("HERMES_MAX_TOKENS")
+    if env_max_tokens:
+        try:
+            max_tokens = int(env_max_tokens)
+        except (ValueError, TypeError):
+            max_tokens = None
+    elif isinstance(model_cfg, dict):
+        cfg_max_tokens = model_cfg.get("max_tokens")
+        if isinstance(cfg_max_tokens, int):
+            max_tokens = cfg_max_tokens
+    if max_tokens is None:
+        runtime_max_tokens = runtime.get("max_output_tokens")
+        if isinstance(runtime_max_tokens, int) and runtime_max_tokens > 0:
+            max_tokens = runtime_max_tokens
+
+    return {
+        "api_key": runtime.get("api_key"),
+        "base_url": runtime.get("base_url"),
+        "provider": runtime.get("provider"),
+        "api_mode": runtime.get("api_mode"),
+        "command": runtime.get("command"),
+        "args": list(runtime.get("args") or []),
+        "credential_pool": runtime.get("credential_pool"),
+        "max_tokens": max_tokens,
+    }
+
+
+def _request_agent_overrides(
+    body: Any,
+    *,
+    virtual_model: Optional[str] = None,
+    allow_bare_model: bool = True,
+) -> Dict[str, Any]:
+    """Extract per-request model/provider/options for _run_agent.
+
+    ``/v1/models`` advertises a stable virtual model (usually ``hermes-agent``)
+    for OpenAI-compatible clients.  Treat that alias as "use the gateway
+    default"; real model picker selections from the browser extension send the
+    raw provider model id plus a provider slug and should override this turn.
+
+    ``allow_bare_model`` controls whether a ``model`` value WITHOUT an
+    accompanying ``provider`` is honored.  Generic OpenAI clients routinely
+    hardcode model names ("gpt-4o", ...), and existing deployments rely on
+    those falling back to the gateway default on the OpenAI-compatible
+    surfaces — so those handlers pass the opt-in
+    ``direct_model_requests`` config value here, while Hermes-native
+    endpoints (session chat, /v1/runs) always allow it.  A request that
+    sends an explicit ``provider`` is unambiguously Hermes-aware and is
+    always honored.
+    """
+    if not isinstance(body, dict):
+        return {}
+
+    overrides: Dict[str, Any] = {}
+    provider = _clean_request_string(body.get("provider"))
+    if provider:
+        overrides["requested_provider"] = provider
+
+    model = _clean_request_string(body.get("model"))
+    if model and model != virtual_model and (provider or allow_bare_model):
+        overrides["requested_model"] = model
+
+    model_options = body.get("model_options")
+    if isinstance(model_options, dict):
+        overrides["model_options"] = dict(model_options)
+    return overrides
+
+
 def _message_text_prefix(content: Any) -> str:
     if isinstance(content, str):
         return content[:128]
@@ -983,6 +1149,22 @@ except Exception:  # pragma: no cover - scanner is optional hardening
     _scan_cron_prompt = None
 
 
+class _ProviderAuthResolutionError(RuntimeError):
+    """Raised only when gateway.run._resolve_runtime_agent_kwargs() fails
+    to resolve provider credentials.
+
+    That function is the sole raiser of RuntimeError(format_runtime_
+    provider_error(...)) anywhere in _create_agent()'s call graph.
+    Re-raising it as this dedicated subclass -- instead of catching bare
+    RuntimeError around the much wider _create_agent()+run_conversation()
+    span -- lets callers distinguish "provider auth/credential failure"
+    from any other RuntimeError a provider adapter or run_conversation()
+    might legitimately raise (e.g. run_agent.py's "Failed to recreate
+    closed OpenAI client"), which a bare `except RuntimeError` there would
+    otherwise mislabel as an auth failure.
+    """
+
+
 class APIServerAdapter(BasePlatformAdapter):
     """
     OpenAI-compatible HTTP API server adapter.
@@ -1037,6 +1219,18 @@ class APIServerAdapter(BasePlatformAdapter):
         self._model_routes: Dict[str, Dict[str, Any]] = self._parse_model_routes(
             extra.get("model_routes"),
         )
+        # direct_model_requests: opt-in passthrough for a bare ``model`` value
+        # (no ``provider``) on the OpenAI-compatible surfaces
+        # (/v1/chat/completions, /v1/responses).  Off by default: generic
+        # OpenAI clients routinely hardcode model names ("gpt-4o", ...), and
+        # existing deployments rely on those falling back to the gateway
+        # default rather than switching the executing model.  Requests that
+        # send an explicit ``provider`` — and the Hermes-native session-chat
+        # and /v1/runs endpoints — are always honored regardless of this flag.
+        # (Idea credit: PR #22825 by @mssteuer.)
+        self._direct_model_requests: bool = _coerce_request_bool(
+            extra.get("direct_model_requests"), default=False
+        )
         self._app: Optional["web.Application"] = None
         self._runner: Optional["web.AppRunner"] = None
         self._site: Optional["web.TCPSite"] = None
@@ -1059,6 +1253,13 @@ class APIServerAdapter(BasePlatformAdapter):
         # in-flight run by run_id.
         self._run_approval_sessions: Dict[str, str] = {}
         self._session_db: Optional[Any] = None  # Lazy-init SessionDB for session continuity
+        # Last-known-good resolved model per session (keyed by gateway_session_key
+        # ONLY — never session_id, which rotates/is ephemeral for one-off API
+        # server requests; "*" is the process-wide fallback), mirroring
+        # GatewayRunner._last_resolved_model in run.py — recovers from a
+        # transient empty model resolution (#35314) instead of building an
+        # agent with model="" that 400s every call until manual retry.
+        self._last_resolved_model: Dict[str, str] = {}
         self._session_db_lock: Optional[asyncio.Lock] = None  # Single-flight for lazy init
         # Concurrency cap shared across all agent-serving endpoints
         # (/v1/chat/completions, /v1/responses, /v1/runs). Read from
@@ -1558,6 +1759,7 @@ class APIServerAdapter(BasePlatformAdapter):
             ("GET", "/health/detailed", self._handle_health_detailed),
             ("GET", "/v1/health", self._handle_health),
             ("GET", "/v1/models", self._handle_models),
+            ("GET", "/api/model/options", self._handle_model_options),
             ("GET", "/v1/capabilities", self._handle_capabilities),
             ("GET", "/v1/skills", self._handle_skills),
             ("GET", "/v1/toolsets", self._handle_toolsets),
@@ -1570,6 +1772,7 @@ class APIServerAdapter(BasePlatformAdapter):
             ("POST", "/api/sessions/{session_id}/fork", self._handle_fork_session),
             ("POST", "/api/sessions/{session_id}/chat", self._handle_session_chat),
             ("POST", "/api/sessions/{session_id}/chat/stream", self._handle_session_chat_stream),
+            ("POST", "/api/sessions/{session_id}/model", self._handle_session_model_lock),
             ("POST", "/v1/chat/completions", self._handle_chat_completions),
             ("POST", "/v1/responses", self._handle_responses),
             ("GET", "/v1/responses/{response_id}", self._handle_get_response),
@@ -1798,6 +2001,232 @@ class APIServerAdapter(BasePlatformAdapter):
             return None
         return self._model_routes.get(model_alias)
 
+    @staticmethod
+    def _clean_runtime_id(value: Any, *, max_len: int = 200) -> str:
+        if value is None:
+            return ""
+        text = str(value).strip()
+        if not text or len(text) > max_len:
+            return ""
+        if re.search(r"[\r\n\x00]", text):
+            return ""
+        return text
+
+    @classmethod
+    def _split_provider_prefixed_model(cls, model: str) -> tuple[str, str]:
+        text = cls._clean_runtime_id(model)
+        if "::" in text:
+            provider, raw = text.split("::", 1)
+            if re.match(r"^[a-zA-Z0-9_.-]{2,64}$", provider) and raw.strip():
+                return provider, raw.strip()
+        return "", text
+
+    @classmethod
+    def _runtime_options_from_model_options(cls, model_options: Any) -> Dict[str, Any]:
+        if not isinstance(model_options, dict):
+            return {}
+        runtime_options: Dict[str, Any] = {}
+        reasoning = model_options.get("reasoning")
+        if isinstance(reasoning, dict):
+            enabled = reasoning.get("enabled")
+            effort = cls._clean_runtime_id(reasoning.get("effort"), max_len=32)
+            if enabled is False:
+                runtime_options["reasoning_config"] = {"enabled": False}
+            elif effort:
+                runtime_options["reasoning_config"] = {"enabled": True, "effort": effort}
+            elif enabled is True:
+                runtime_options["reasoning_config"] = {"enabled": True}
+        service_tier = cls._clean_runtime_id(model_options.get("service_tier"), max_len=32)
+        if service_tier:
+            runtime_options["service_tier"] = service_tier
+        elif _coerce_request_bool(model_options.get("fast"), default=False):
+            runtime_options["service_tier"] = "priority"
+        return runtime_options
+
+    def _session_runtime_request_from_body(self, body: Dict[str, Any]) -> Dict[str, Any]:
+        raw_model = self._clean_runtime_id(body.get("model") or body.get("model_id"))
+        raw_provider = self._clean_runtime_id(body.get("provider") or body.get("provider_id"), max_len=80)
+        prefixed_provider, split_model = self._split_provider_prefixed_model(raw_model)
+        provider = raw_provider or prefixed_provider
+        model = split_model or raw_model
+        alias_route = self._resolve_route(raw_model) or self._resolve_route(model)
+        route = dict(alias_route) if isinstance(alias_route, dict) else None
+        route_source = "model_routes" if route else "global"
+        if not route and model and model != self._model_name:
+            route = {"model": model}
+            if provider:
+                route["provider"] = provider
+            route_source = "raw_request"
+        elif not route and provider and model:
+            route = {"model": model, "provider": provider}
+            route_source = "raw_request"
+        runtime_options = self._runtime_options_from_model_options(body.get("model_options"))
+        requested = {"provider": provider, "model": model, "raw_model": raw_model}
+        return {
+            "requested": requested,
+            "route": route,
+            "route_source": route_source,
+            "runtime_options": runtime_options,
+            "require_model_lock": _coerce_request_bool(body.get("require_model_lock"), default=False),
+            "model_options": body.get("model_options") if isinstance(body.get("model_options"), dict) else {},
+        }
+
+    def _runtime_lock_error(self, runtime_request: Dict[str, Any]) -> Optional["web.Response"]:
+        if not runtime_request.get("require_model_lock"):
+            return None
+        requested = runtime_request.get("requested") or {}
+        model = self._clean_runtime_id(requested.get("model"))
+        provider = self._clean_runtime_id(requested.get("provider"), max_len=80)
+        route = runtime_request.get("route")
+        if not model and not provider:
+            return web.json_response(
+                _openai_error("require_model_lock was set but no model/provider was provided", code="missing_model"),
+                status=400,
+            )
+        if not route or runtime_request.get("route_source") == "global":
+            return web.json_response(
+                _openai_error("Requested Browser model lock cannot be routed; refusing silent global fallback", code="model_lock_unavailable"),
+                status=409,
+            )
+        return None
+
+    def _persist_session_runtime_lock(self, session_id: str, runtime_request: Dict[str, Any]) -> bool:
+        # Persist only a newly confirmed lock. Reusing a stored lock should not
+        # rewrite its timestamp/prompt state on every turn, and an ordinary
+        # one-off request override must not erase a previously confirmed lock.
+        if runtime_request.get("persisted_lock") or not runtime_request.get("require_model_lock"):
+            return True
+        requested = runtime_request.get("requested") or {}
+        model = self._clean_runtime_id(requested.get("model"))
+        provider = self._clean_runtime_id(requested.get("provider"), max_len=80)
+        if not model and not provider:
+            return False
+        db = self._ensure_session_db()
+        if db is None:
+            return False
+        try:
+            db.update_session_runtime_lock(
+                session_id,
+                model=model or None,
+                provider=provider or None,
+                model_options=runtime_request.get("model_options") or {},
+                route_source=runtime_request.get("route_source") or "",
+                confirmed=bool(runtime_request.get("require_model_lock")),
+            )
+            return True
+        except Exception:
+            logger.warning("[%s] failed to persist session runtime lock for %s", self.name, session_id, exc_info=True)
+            return False
+
+    @staticmethod
+    def _parse_session_model_config(raw: Any) -> Dict[str, Any]:
+        if isinstance(raw, dict):
+            return dict(raw)
+        if isinstance(raw, str) and raw.strip():
+            try:
+                parsed = json.loads(raw)
+            except Exception:
+                return {}
+            if isinstance(parsed, dict):
+                return parsed
+        return {}
+
+    def _runtime_request_from_persisted_session_lock(
+        self,
+        session: Optional[Dict[str, Any]],
+        body: Dict[str, Any],
+    ) -> Optional[Dict[str, Any]]:
+        if not isinstance(session, dict):
+            return None
+        model_config = self._parse_session_model_config(session.get("model_config"))
+        lock = model_config.get("browser_model_lock")
+        if not isinstance(lock, dict) or not _coerce_request_bool(lock.get("confirmed"), default=False):
+            return None
+        model = self._clean_runtime_id(lock.get("model"))
+        provider = self._clean_runtime_id(lock.get("provider"), max_len=80)
+        if not model and not provider:
+            return None
+        persisted_route_source = self._clean_runtime_id(
+            lock.get("route_source"),
+            max_len=64,
+        ).lower()
+        route: Optional[Dict[str, Any]] = None
+        if persisted_route_source == "model_routes":
+            route = self._resolve_route(model) if model else None
+        else:
+            route = {"model": model} if model else {}
+            if provider:
+                route["provider"] = provider
+        model_options = (
+            body.get("model_options")
+            if isinstance(body.get("model_options"), dict)
+            else lock.get("model_options")
+        )
+        return {
+            "requested": {
+                "provider": provider,
+                "model": model,
+                "raw_model": model,
+            },
+            "route": route or None,
+            "route_source": "session_model_lock",
+            "runtime_options": self._runtime_options_from_model_options(model_options),
+            "require_model_lock": True,
+            "model_options": model_options if isinstance(model_options, dict) else {},
+            "persisted_lock": True,
+        }
+
+    def _effective_session_runtime_request(
+        self,
+        *,
+        session: Optional[Dict[str, Any]],
+        body: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        runtime_request = self._session_runtime_request_from_body(body)
+        requested = runtime_request.get("requested") or {}
+        if requested.get("model") or requested.get("provider"):
+            return runtime_request
+        persisted = self._runtime_request_from_persisted_session_lock(session, body)
+        return persisted or runtime_request
+
+    @classmethod
+    def _sanitize_runtime_metadata(
+        cls,
+        *,
+        runtime: Optional[Dict[str, Any]] = None,
+        requested_runtime: Optional[Dict[str, Any]] = None,
+        route_source: str = "global",
+        model_lock: str = "",
+    ) -> Dict[str, Any]:
+        payload = dict(runtime or {})
+        provider = cls._clean_runtime_id(
+            payload.get("provider") or payload.get("provider_id") or payload.get("effective_provider"),
+            max_len=80,
+        )
+        model = cls._clean_runtime_id(payload.get("model") or payload.get("model_id") or payload.get("effective_model"))
+        result: Dict[str, Any] = {
+            "provider": provider,
+            "model": model,
+            "route_source": cls._clean_runtime_id(payload.get("route_source") or route_source, max_len=64) or "global",
+        }
+        if requested_runtime or payload.get("requested"):
+            req = requested_runtime or payload.get("requested") or {}
+            result["requested"] = {
+                "provider": cls._clean_runtime_id(req.get("provider"), max_len=80),
+                "model": cls._clean_runtime_id(req.get("model")),
+            }
+        if model_lock or payload.get("model_lock"):
+            result["model_lock"] = cls._clean_runtime_id(model_lock or payload.get("model_lock"), max_len=32)
+        return result
+
+    @staticmethod
+    def _normalize_session_source(value: Any) -> str:
+        text = str(value or "").strip().lower()
+        allowed = {"api_server", "hermes_browser", "browser", "cli", "telegram", "discord", "slack", "desktop", "dashboard"}
+        if text in allowed:
+            return "hermes_browser" if text == "browser" else text
+        return "api_server"
+
     def _session_model_override_for(self, session_key: Optional[str]) -> Optional[Dict[str, Any]]:
         """Return the gateway's session ``/model`` override for *session_key*, if any.
 
@@ -1814,11 +2243,56 @@ class APIServerAdapter(BasePlatformAdapter):
             runner = _gateway_runner_ref()
             if runner is None:
                 return None
+            try:
+                rehydrate = getattr(runner, "_rehydrate_session_model_override", None)
+                if callable(rehydrate):
+                    rehydrate(session_key)
+            except Exception:
+                logger.debug(
+                    "api_server failed to rehydrate session /model override for %s",
+                    session_key,
+                    exc_info=True,
+                )
             override = runner._session_model_overrides.get(session_key)
             return dict(override) if isinstance(override, dict) else None
         except Exception:
             return None
 
+    def _request_route_conflict_error(
+        self,
+        *,
+        session_id: Optional[str],
+        gateway_session_key: Optional[str],
+        requested_model: Optional[str],
+        requested_provider: Optional[str],
+        route: Optional[Dict[str, Any]],
+    ) -> Optional[str]:
+        """Return a 400-worthy conflict string for ambiguous route/provider mixes."""
+        request_provider = _clean_request_string(requested_provider)
+        if not request_provider or not isinstance(route, dict):
+            return None
+        if self._session_model_override_for(gateway_session_key or session_id):
+            # Session /model wins over both the route and the request override, so
+            # there is no ambiguity to reject on this request path.
+            return None
+
+        route_provider = _clean_request_string(route.get("provider"))
+        route_api_key = _clean_request_string(route.get("api_key"))
+        route_base_url = _clean_request_string(route.get("base_url"))
+        route_alias = _clean_request_string(requested_model) or "requested model"
+
+        if route_provider and request_provider != route_provider:
+            return (
+                f"Model route '{route_alias}' is pinned to provider '{route_provider}'. "
+                f"Remove 'provider' or use '{route_provider}'."
+            )
+        if not route_provider and (route_api_key or route_base_url):
+            return (
+                f"Model route '{route_alias}' pins route credentials/base_url. "
+                "Do not combine it with an explicit 'provider'."
+            )
+        return None
+
     def _create_agent(
         self,
         ephemeral_system_prompt: Optional[str] = None,
@@ -1828,7 +2302,12 @@ class APIServerAdapter(BasePlatformAdapter):
         tool_start_callback=None,
         tool_complete_callback=None,
         gateway_session_key: Optional[str] = None,
+        requested_model: Optional[str] = None,
+        requested_provider: Optional[str] = None,
+        model_options: Optional[Dict[str, Any]] = None,
         route: Optional[Dict[str, Any]] = None,
+        session_model: Optional[str] = None,
+        confirmed_runtime_lock: bool = False,
     ) -> Any:
         """
         Create an AIAgent instance using the gateway's runtime config.
@@ -1849,6 +2328,19 @@ class APIServerAdapter(BasePlatformAdapter):
         routing).  When set — and no session ``/model`` override exists for
         this session — its model/provider/api_key/base_url override the
         global defaults for this agent instance only.
+
+        ``session_model`` is the raw model persisted on a native API session
+        row at creation time (``POST /api/sessions {"model": ...}``) when
+        that value does not resolve to a ``model_routes`` alias.  Session-chat
+        handlers pass either ``route`` (alias hit) or ``session_model`` (raw
+        model), never both.  Precedence: session ``/model`` override →
+        ``session_model`` → route alias / per-request selection → global.
+
+        ``confirmed_runtime_lock`` marks a backend-acknowledged Browser model
+        lock (POST /api/sessions/{id}/model).  A confirmed lock beats the
+        session ``/model`` override, disables the global fallback model
+        chain, and fails closed if the locked provider's credentials cannot
+        be resolved.
         """
         from run_agent import AIAgent
         from gateway.run import (
@@ -1861,7 +2353,18 @@ class APIServerAdapter(BasePlatformAdapter):
         )
         from hermes_cli.tools_config import _get_platform_tools
 
-        runtime_kwargs = _resolve_runtime_agent_kwargs()
+        # Catch RuntimeError ONLY around this call, not the wider
+        # _create_agent()+run_conversation() span --
+        # _resolve_runtime_agent_kwargs() is the sole raiser of
+        # RuntimeError(format_runtime_provider_error(...)) for provider
+        # auth/credential failure.  Re-raising as
+        # _ProviderAuthResolutionError lets _run_agent() (and
+        # _handle_runs()) distinguish this from an unrelated RuntimeError
+        # elsewhere in the call graph.
+        try:
+            runtime_kwargs = _resolve_runtime_agent_kwargs()
+        except RuntimeError as exc:
+            raise _ProviderAuthResolutionError(str(exc)) from exc
         reasoning_config = GatewayRunner._load_reasoning_config()
         model = _resolve_gateway_model()
 
@@ -1877,50 +2380,194 @@ class APIServerAdapter(BasePlatformAdapter):
         if runtime_model:
             model = runtime_model
 
-        # Per-client model routing (model_routes config).  The route was
-        # resolved from the request's ``model`` field by the HTTP handler.
-        # Precedence (highest first): session ``/model`` override → model_routes
-        # route → global config — an explicit user-issued ``/model`` on the
-        # session always beats static per-client route config.
-        session_override = self._session_model_override_for(
-            gateway_session_key or session_id
-        )
-        if route and not session_override:
-            if route.get("provider"):
-                # Resolve real credentials for the routed provider (mirrors
-                # the channel_overrides path in gateway/run.py) so a route
-                # without an explicit api_key/base_url still gets the right
-                # provider auth instead of the default provider's key.
+        request_reasoning_config = _request_reasoning_config(model_options)
+        if request_reasoning_config is not None:
+            reasoning_config = request_reasoning_config
+        request_service_tier = _request_service_tier(model_options)
+
+        request_model = _clean_request_string(requested_model)
+        request_provider = _clean_request_string(requested_provider)
+        route_model = _clean_request_string(route.get("model")) if isinstance(route, dict) else None
+        route_provider = _clean_request_string(route.get("provider")) if isinstance(route, dict) else None
+        route_api_key = _clean_request_string(route.get("api_key")) if isinstance(route, dict) else None
+        route_base_url = _clean_request_string(route.get("base_url")) if isinstance(route, dict) else None
+
+        def _resolve_provider_runtime(
+            provider: Optional[str],
+            *,
+            target_model: Optional[str],
+            required: bool,
+        ) -> Optional[Dict[str, Any]]:
+            provider_name = _clean_request_string(provider)
+            if not provider_name:
+                return None
+            try:
+                return _resolve_request_runtime_agent_kwargs(
+                    provider_name,
+                    target_model=target_model or None,
+                )
+            except Exception as exc:
                 try:
                     from gateway.run import _resolve_runtime_agent_kwargs_for_provider
-                    provider_kwargs = _resolve_runtime_agent_kwargs_for_provider(
-                        route["provider"]
-                    )
-                    provider_kwargs.pop("model", None)
-                    runtime_kwargs.update(provider_kwargs)
+
+                    return _resolve_runtime_agent_kwargs_for_provider(provider_name)
                 except Exception:
-                    # Fall back to just switching the provider name; explicit
-                    # per-route api_key/base_url below can still complete auth.
-                    runtime_kwargs["provider"] = route["provider"]
-            if route.get("model"):
-                model = route["model"]
-            # Per-route secrets are upstream provider credentials. Never log
-            # them (compare _check_auth: caller auth stays the global bearer
-            # key checked with hmac.compare_digest).
-            if route.get("api_key"):
-                runtime_kwargs["api_key"] = route["api_key"]
-            if route.get("base_url"):
-                runtime_kwargs["base_url"] = route["base_url"]
-            logger.debug(
-                "api_server model route applied: model=%s provider=%s",
-                model,
-                runtime_kwargs.get("provider"),
+                    pass
+                if required:
+                    # Surface as the typed provider-auth failure so
+                    # _run_agent()/_handle_runs() return the controlled
+                    # response shape instead of a raw 500.
+                    raise _ProviderAuthResolutionError(str(exc)) from exc
+                logger.debug(
+                    "api_server provider-runtime refresh failed for provider=%s model=%s",
+                    provider_name,
+                    target_model or "",
+                    exc_info=True,
+                )
+                return None
+
+        # Final precedence mirrors the gateway contract:
+        # confirmed Browser model lock → session /model override →
+        # session-persisted model (POST /api/sessions {"model": ...}) →
+        # model_routes mapping selected by the request model alias → direct
+        # per-request provider/model → global defaults.  model_options stay
+        # request-scoped regardless of which selection wins.  A confirmed
+        # lock is an execution contract: it bypasses the session /model
+        # override and fails closed (never reuses global credentials) if
+        # its provider cannot be resolved.
+        session_key = gateway_session_key or session_id
+        session_row_model = _clean_request_string(session_model)
+        session_override = None
+        if not confirmed_runtime_lock:
+            session_override = self._session_model_override_for(session_key)
+        if session_override:
+            override_model = _clean_request_string(session_override.get("model")) or model
+            session_provider = _clean_request_string(session_override.get("provider"))
+            current_provider = _clean_request_string(runtime_kwargs.get("provider"))
+            provider_runtime = _resolve_provider_runtime(
+                session_provider or current_provider,
+                target_model=override_model,
+                required=False,
             )
-        elif route and session_override:
-            logger.debug(
-                "api_server model route skipped: session /model override wins for %s",
-                gateway_session_key or session_id,
+            if provider_runtime:
+                _apply_runtime_agent_overrides(runtime_kwargs, provider_runtime)
+            _apply_runtime_agent_overrides(runtime_kwargs, session_override)
+            model = override_model
+            if route or request_model or request_provider:
+                logger.debug(
+                    "api_server request selection skipped: session /model override wins for %s",
+                    session_key or "",
+                )
+        elif session_row_model and not confirmed_runtime_lock:
+            # Session-persisted model (raw string that resolved to no route
+            # alias).  Pins this session's turns ahead of per-request body
+            # values — a session's chosen model is a standing selection,
+            # matching the native gateway's session-model semantics.
+            current_provider = _clean_request_string(runtime_kwargs.get("provider"))
+            provider_runtime = _resolve_provider_runtime(
+                current_provider,
+                target_model=session_row_model,
+                required=False,
             )
+            if provider_runtime:
+                _apply_runtime_agent_overrides(runtime_kwargs, provider_runtime)
+            model = session_row_model
+            if request_model or request_provider:
+                logger.debug(
+                    "api_server request selection skipped: session-persisted model wins for %s",
+                    session_key or "",
+                )
+        else:
+            if route is not None:
+                # The request's ``model`` field selected this route, so its
+                # value is the route ALIAS — never usable as a model name.
+                # A route with no ``model`` key keeps the global default
+                # (pre-existing model_routes behavior).
+                effective_model = route_model or model
+            else:
+                effective_model = request_model or model
+            current_provider = _clean_request_string(runtime_kwargs.get("provider"))
+            effective_provider = request_provider or route_provider or current_provider
+            provider_runtime = None
+            if effective_provider and (
+                bool(request_provider or route_provider) or effective_model != model
+            ):
+                provider_runtime = _resolve_provider_runtime(
+                    effective_provider,
+                    target_model=effective_model,
+                    # A confirmed Browser lock fails closed: if the locked
+                    # provider cannot be resolved, never fall through to
+                    # the previous global provider's credentials.
+                    required=bool(request_provider) or confirmed_runtime_lock,
+                )
+            if provider_runtime:
+                _apply_runtime_agent_overrides(runtime_kwargs, provider_runtime)
+            elif effective_provider and effective_provider != current_provider:
+                runtime_kwargs["provider"] = effective_provider
+            model = effective_model
+            # Per-route explicit transport secrets/base URLs win within the
+            # route contract after provider resolution.
+            if route_api_key:
+                runtime_kwargs["api_key"] = route_api_key
+            if route_base_url:
+                runtime_kwargs["base_url"] = route_base_url
+            if route:
+                logger.debug(
+                    "api_server request selection applied: model=%s provider=%s route_provider=%s request_provider=%s",
+                    model,
+                    runtime_kwargs.get("provider"),
+                    route_provider or "",
+                    request_provider or "",
+                )
+
+        # When the config has no model.default but a provider was resolved
+        # (e.g. user ran `hermes auth add openai-codex` without `hermes model`),
+        # fall back to the provider's first catalog model so the API call
+        # doesn't fail with "model must be a non-empty string". Mirrors
+        # run.py::_resolve_session_agent_runtime. Runs after the selection
+        # block above so a route/session/request override that already
+        # resolved a model is never treated as "empty" here.
+        if not model and runtime_kwargs.get("provider"):
+            try:
+                from hermes_cli.models import get_default_model_for_provider
+                model = get_default_model_for_provider(runtime_kwargs["provider"])
+                if model:
+                    logger.info(
+                        "No model configured — defaulting to %s for provider %s",
+                        model, runtime_kwargs["provider"],
+                    )
+            except Exception:
+                pass
+
+        # Final safety net (#35314): if resolution still produced an empty
+        # model — e.g. a transient config-cache miss — reuse the last model
+        # successfully resolved for this session (or, failing that, the most
+        # recent one resolved process-wide). Building an agent with model=""
+        # makes every API call fail HTTP 400 until a manual retry. Mirrors
+        # run.py::_resolve_session_agent_runtime.
+        #
+        # Cache key is gateway_session_key ONLY, never session_id — unlike
+        # run.py's native gateway (stable, long-lived chat scopes), the API
+        # server hands out a fresh UUID session_id per one-off request
+        # (/v1/responses, /v1/runs when no explicit session is supplied).
+        # Keying on session_id would leave one permanent dict entry per
+        # stateless request, growing unbounded for the life of the process.
+        _resolved_key = gateway_session_key or ""
+        if not model:
+            _recovered = (self._last_resolved_model.get(_resolved_key)
+                          or self._last_resolved_model.get("*"))
+            if _recovered:
+                logger.warning(
+                    "Empty model resolved for session=%s — recovering "
+                    "last-known-good model %s (config read likely returned "
+                    "empty; see #35314)",
+                    _resolved_key, _recovered,
+                )
+                model = _recovered
+        elif model:
+            if _resolved_key:
+                self._last_resolved_model[_resolved_key] = model
+            self._last_resolved_model["*"] = model
 
         user_config = _load_gateway_config()
         enabled_toolsets = sorted(_get_platform_tools(user_config, "api_server"))
@@ -1929,28 +2576,49 @@ class APIServerAdapter(BasePlatformAdapter):
 
         # Load fallback provider chain so the API server platform has the
         # same fallback behaviour as Telegram/Discord/Slack (fixes #4954).
-        fallback_model = GatewayRunner._load_fallback_model()
+        fallback_model = (
+            None
+            if confirmed_runtime_lock
+            else GatewayRunner._load_fallback_model()
+        )
 
-        agent = AIAgent(
-            model=model,
+        agent_kwargs = {
+            "model": model,
             **runtime_kwargs,
             **_checkpoint_agent_kwargs(user_config),
-            max_iterations=max_iterations,
-            quiet_mode=True,
-            verbose_logging=False,
-            ephemeral_system_prompt=ephemeral_system_prompt or None,
-            enabled_toolsets=enabled_toolsets,
-            session_id=session_id,
-            platform="api_server",
-            stream_delta_callback=stream_delta_callback,
-            tool_progress_callback=tool_progress_callback,
-            tool_start_callback=tool_start_callback,
-            tool_complete_callback=tool_complete_callback,
-            session_db=self._ensure_session_db(),
-            fallback_model=fallback_model,
-            reasoning_config=reasoning_config,
-            gateway_session_key=gateway_session_key,
-        )
+            "max_iterations": max_iterations,
+            "quiet_mode": True,
+            "verbose_logging": False,
+            "ephemeral_system_prompt": ephemeral_system_prompt or None,
+            "enabled_toolsets": enabled_toolsets,
+            "session_id": session_id,
+            "platform": "api_server",
+            "stream_delta_callback": stream_delta_callback,
+            "tool_progress_callback": tool_progress_callback,
+            "tool_start_callback": tool_start_callback,
+            "tool_complete_callback": tool_complete_callback,
+            "session_db": self._ensure_session_db(),
+            "fallback_model": fallback_model,
+            "reasoning_config": reasoning_config,
+            "gateway_session_key": gateway_session_key,
+        }
+        if request_service_tier is not _REQUEST_OPTION_MISSING:
+            agent_kwargs["service_tier"] = request_service_tier
+
+        agent = AIAgent(**agent_kwargs)
+        agent._hermes_api_runtime = {
+            "provider": runtime_kwargs.get("provider") or getattr(agent, "provider", "") or "",
+            "model": getattr(agent, "model", None) or model,
+            "route_source": (
+                "session_model_lock"
+                if confirmed_runtime_lock
+                else "session_model_override"
+                if session_override
+                else "raw_request"
+                if route or request_model or request_provider
+                else "global"
+            ),
+        }
         return agent
 
     # ------------------------------------------------------------------
@@ -2070,6 +2738,43 @@ class APIServerAdapter(BasePlatformAdapter):
 
         return web.json_response({"object": "list", "data": models})
 
+    async def _handle_model_options(self, request: "web.Request") -> "web.Response":
+        """GET /api/model/options — return Hermes provider/model inventory.
+
+        This mirrors the dashboard/TUI model picker inventory endpoint so
+        external clients using the API server can sync to the user's configured
+        Hermes provider catalog instead of scraping the single OpenAI-compatible
+        `/v1/models` alias.
+        """
+        auth_err = self._check_auth(request)
+        if auth_err:
+            return auth_err
+
+        refresh = _coerce_request_bool(request.query.get("refresh"), default=False)
+        try:
+            from hermes_cli.inventory import build_model_options_payload, load_picker_context
+
+            def _build_payload() -> Dict[str, Any]:
+                return build_model_options_payload(
+                    load_picker_context(),
+                    include_unconfigured=True,
+                    refresh=refresh,
+                )
+
+            # Inventory enrichment can fetch pricing and provider catalogs.
+            # Keep all synchronous picker work off aiohttp's event loop.
+            payload = await asyncio.to_thread(_build_payload)
+            return web.json_response(payload)
+        except Exception:
+            logger.exception("[%s] GET /api/model/options failed", self.name)
+            return web.json_response(
+                _openai_error(
+                    "Failed to list model options.",
+                    code="model_options_failed",
+                ),
+                status=500,
+            )
+
     async def _handle_capabilities(self, request: "web.Request") -> "web.Response":
         """GET /v1/capabilities — advertise the stable API surface.
 
@@ -2112,9 +2817,11 @@ class APIServerAdapter(BasePlatformAdapter):
                 "tool_progress_events": True,
                 "approval_events": True,
                 "session_resources": True,
+                "model_options": True,
                 "session_chat": True,
                 "session_chat_streaming": True,
                 "session_fork": True,
+                "session_model_lock": True,
                 "admin_config_rw": False,
                 "jobs_admin": False,
                 "memory_write_api": False,
@@ -2129,6 +2836,7 @@ class APIServerAdapter(BasePlatformAdapter):
                 "health": {"method": "GET", "path": "/health"},
                 "health_detailed": {"method": "GET", "path": "/health/detailed"},
                 "models": {"method": "GET", "path": "/v1/models"},
+                "model_options": {"method": "GET", "path": "/api/model/options"},
                 "chat_completions": {"method": "POST", "path": "/v1/chat/completions"},
                 "responses": {"method": "POST", "path": "/v1/responses"},
                 "runs": {"method": "POST", "path": "/v1/runs"},
@@ -2147,6 +2855,7 @@ class APIServerAdapter(BasePlatformAdapter):
                 "session_fork": {"method": "POST", "path": "/api/sessions/{session_id}/fork"},
                 "session_chat": {"method": "POST", "path": "/api/sessions/{session_id}/chat"},
                 "session_chat_stream": {"method": "POST", "path": "/api/sessions/{session_id}/chat/stream"},
+                "session_model_lock": {"method": "POST", "path": "/api/sessions/{session_id}/model"},
             },
         })
 
@@ -2371,6 +3080,25 @@ class APIServerAdapter(BasePlatformAdapter):
         system_prompt = body.get("system_prompt")
         if system_prompt is not None and not isinstance(system_prompt, str):
             return web.json_response(_openai_error("system_prompt must be a string", code="invalid_system_prompt"), status=400)
+        source = self._normalize_session_source(body.get("source") or "api_server")
+        runtime_request = self._session_runtime_request_from_body(body)
+        lock_error = self._runtime_lock_error(runtime_request)
+        if lock_error is not None:
+            return lock_error
+        requested = runtime_request.get("requested") or {}
+        model_name = self._clean_runtime_id(requested.get("model")) or (str(model) if model else None)
+        model_config = None
+        if requested.get("model") or requested.get("provider"):
+            model_config = {
+                "browser_model_lock": {
+                    "provider": requested.get("provider") or "",
+                    "model": requested.get("model") or "",
+                    "model_options": runtime_request.get("model_options") or {},
+                    "route_source": runtime_request.get("route_source") or "",
+                    "confirmed": bool(runtime_request.get("require_model_lock")),
+                    "updated_at": time.time(),
+                }
+            }
         title = body.get("title")
 
         # Run the entire check-insert-title sequence inside a single
@@ -2388,12 +3116,13 @@ class APIServerAdapter(BasePlatformAdapter):
                 import time as _time
                 conn.execute(
                     """INSERT INTO sessions (
-                       id, source, model, system_prompt, started_at
-                    ) VALUES (?, ?, ?, ?, ?)""",
+                       id, source, model, model_config, system_prompt, started_at
+                    ) VALUES (?, ?, ?, ?, ?, ?)""",
                     (
                         session_id,
-                        "api_server",
-                        str(model) if model else None,
+                        source,
+                        model_name,
+                        json.dumps(model_config) if model_config else None,
                         system_prompt,
                         _time.time(),
                     ),
@@ -2418,8 +3147,8 @@ class APIServerAdapter(BasePlatformAdapter):
                     "SELECT * FROM sessions WHERE id = ?", (session_id,)
                 ).fetchone()
                 return (dict(session_row) if session_row else {
-                    "id": session_id, "source": "api_server",
-                    "model": model, "title": title,
+                    "id": session_id, "source": source,
+                    "model": model_name, "title": title,
                 }), None
             return db._execute_write(_atomic)
 
@@ -2553,7 +3282,7 @@ class APIServerAdapter(BasePlatformAdapter):
         if key_err is not None:
             return key_err
         session_id = request.match_info["session_id"]
-        _, err = await self._get_existing_session_or_404(session_id)
+        session, err = await self._get_existing_session_or_404(session_id)
         if err:
             return err
         body, err = await self._read_json_body(request)
@@ -2565,6 +3294,57 @@ class APIServerAdapter(BasePlatformAdapter):
         system_prompt = body.get("system_message") or body.get("instructions")
         if system_prompt is not None and not isinstance(system_prompt, str):
             return web.json_response(_openai_error("system_message must be a string", code="invalid_system_message"), status=400)
+        # Runtime selection. A backend-acknowledged Browser model lock
+        # (require_model_lock in the body, or a previously confirmed lock
+        # persisted on the session row) is an execution contract and wins.
+        # Otherwise: session-persisted model (POST /api/sessions
+        # {"model": ...}) — previously fetched and discarded here — routes
+        # through model_routes when it is an alias (route
+        # provider/credentials come along) or threads through as
+        # session_model when it is a raw string; per-request body values
+        # come after that.
+        runtime_request = self._effective_session_runtime_request(
+            session=session,
+            body=body,
+        )
+        lock_error = self._runtime_lock_error(runtime_request)
+        if lock_error is not None:
+            return lock_error
+        if not self._persist_session_runtime_lock(session_id, runtime_request):
+            return web.json_response(
+                _openai_error(
+                    "Could not persist the requested session model lock",
+                    code="model_lock_persistence_failed",
+                ),
+                status=500,
+            )
+        lock_active = bool(runtime_request.get("require_model_lock"))
+        if lock_active:
+            route = runtime_request.get("route")
+            session_model = None
+            requested = runtime_request.get("requested") or {}
+            agent_overrides: Dict[str, Any] = {}
+            if requested.get("model"):
+                agent_overrides["requested_model"] = requested["model"]
+            if requested.get("provider"):
+                agent_overrides["requested_provider"] = requested["provider"]
+            if runtime_request.get("model_options"):
+                agent_overrides["model_options"] = runtime_request["model_options"]
+        else:
+            stored_model = session.get("model") if isinstance(session, dict) else None
+            stored_route = self._resolve_route(stored_model)
+            route = stored_route or self._resolve_route(body.get("model"))
+            session_model = stored_model if (stored_model and stored_route is None) else None
+            agent_overrides = _request_agent_overrides(body, virtual_model=self._model_name)
+            selection_error = self._request_route_conflict_error(
+                session_id=session_id,
+                gateway_session_key=gateway_session_key,
+                requested_model=agent_overrides.get("requested_model"),
+                requested_provider=agent_overrides.get("requested_provider"),
+                route=route,
+            )
+            if selection_error:
+                return web.json_response(_openai_error(selection_error), status=400)
         history = await self._conversation_history_for_session(session_id)
         result, usage = await self._run_agent(
             user_message=user_message,
@@ -2572,18 +3352,42 @@ class APIServerAdapter(BasePlatformAdapter):
             ephemeral_system_prompt=system_prompt,
             session_id=session_id,
             gateway_session_key=gateway_session_key,
+            route=route,
+            session_model=session_model,
+            requested_runtime=runtime_request.get("requested") or {},
+            route_source=runtime_request.get("route_source") or "global",
+            confirmed_runtime_lock=lock_active,
+            **agent_overrides,
         )
         effective_session_id = result.get("session_id") if isinstance(result, dict) else session_id
         final_response = _resolve_media_to_data_urls(result.get("final_response", "") if isinstance(result, dict) else "")
         headers = {"X-Hermes-Session-Id": effective_session_id or session_id}
         if gateway_session_key:
             headers["X-Hermes-Session-Key"] = gateway_session_key
+        runtime = {}
+        if isinstance(result, dict):
+            runtime = result.get("runtime") or {}
+        if not runtime and isinstance(usage, dict):
+            runtime = usage.get("runtime") or {}
+        runtime = self._sanitize_runtime_metadata(
+            runtime=runtime,
+            requested_runtime=runtime_request.get("requested"),
+            route_source=runtime_request.get("route_source") or "global",
+            model_lock=(
+                "confirmed"
+                if runtime and runtime_request.get("require_model_lock")
+                else "accepted"
+                if runtime_request.get("require_model_lock")
+                else ""
+            ),
+        )
         return web.json_response(
             {
                 "object": "hermes.session.chat.completion",
                 "session_id": effective_session_id or session_id,
                 "message": {"role": "assistant", "content": final_response},
                 "usage": usage,
+                "runtime": runtime,
             },
             headers=headers,
         )
@@ -2595,7 +3399,7 @@ class APIServerAdapter(BasePlatformAdapter):
         if key_err is not None:
             return key_err
         session_id = request.match_info["session_id"]
-        _, err = await self._get_existing_session_or_404(session_id)
+        session, err = await self._get_existing_session_or_404(session_id)
         if err:
             return err
         body, err = await self._read_json_body(request)
@@ -2607,6 +3411,55 @@ class APIServerAdapter(BasePlatformAdapter):
         system_prompt = body.get("system_message") or body.get("instructions")
         if system_prompt is not None and not isinstance(system_prompt, str):
             return web.json_response(_openai_error("system_message must be a string", code="invalid_system_message"), status=400)
+        # Runtime selection — mirrors _handle_session_chat (lock wins,
+        # otherwise session-persisted model then per-request values).
+        runtime_request = self._effective_session_runtime_request(
+            session=session,
+            body=body,
+        )
+        lock_error = self._runtime_lock_error(runtime_request)
+        if lock_error is not None:
+            return lock_error
+        if not self._persist_session_runtime_lock(session_id, runtime_request):
+            return web.json_response(
+                _openai_error(
+                    "Could not persist the requested session model lock",
+                    code="model_lock_persistence_failed",
+                ),
+                status=500,
+            )
+        lock_active = bool(runtime_request.get("require_model_lock"))
+        if lock_active:
+            route = runtime_request.get("route")
+            session_model = None
+            requested = runtime_request.get("requested") or {}
+            agent_overrides: Dict[str, Any] = {}
+            if requested.get("model"):
+                agent_overrides["requested_model"] = requested["model"]
+            if requested.get("provider"):
+                agent_overrides["requested_provider"] = requested["provider"]
+            if runtime_request.get("model_options"):
+                agent_overrides["model_options"] = runtime_request["model_options"]
+        else:
+            stored_model = session.get("model") if isinstance(session, dict) else None
+            stored_route = self._resolve_route(stored_model)
+            route = stored_route or self._resolve_route(body.get("model"))
+            session_model = stored_model if (stored_model and stored_route is None) else None
+            agent_overrides = _request_agent_overrides(body, virtual_model=self._model_name)
+            selection_error = self._request_route_conflict_error(
+                session_id=session_id,
+                gateway_session_key=gateway_session_key,
+                requested_model=agent_overrides.get("requested_model"),
+                requested_provider=agent_overrides.get("requested_provider"),
+                route=route,
+            )
+            if selection_error:
+                return web.json_response(_openai_error(selection_error), status=400)
+        runtime_meta = self._sanitize_runtime_metadata(
+            requested_runtime=runtime_request.get("requested"),
+            route_source=runtime_request.get("route_source") or "global",
+            model_lock=("accepted" if lock_active else ""),
+        )
 
         loop = asyncio.get_running_loop()
         queue: "asyncio.Queue[Optional[tuple[str, Dict[str, Any]]]]" = asyncio.Queue()
@@ -2650,7 +3503,10 @@ class APIServerAdapter(BasePlatformAdapter):
 
         async def _run_and_signal() -> None:
             try:
-                await queue.put(_event_payload("run.started", {"user_message": {"role": "user", "content": user_message}}))
+                await queue.put(_event_payload("run.started", {
+                    "user_message": {"role": "user", "content": user_message},
+                    "runtime": runtime_meta,
+                }))
                 await queue.put(_event_payload("message.started", {"message": {"id": message_id, "role": "assistant"}}))
                 history = await self._conversation_history_for_session(session_id)
                 result, usage = await self._run_agent(
@@ -2661,10 +3517,33 @@ class APIServerAdapter(BasePlatformAdapter):
                     stream_delta_callback=_delta,
                     tool_progress_callback=_tool_progress,
                     gateway_session_key=gateway_session_key,
+                    route=route,
+                    session_model=session_model,
+                    requested_runtime=runtime_request.get("requested") or {},
+                    route_source=runtime_request.get("route_source") or "global",
+                    confirmed_runtime_lock=lock_active,
+                    **agent_overrides,
                 )
                 final_response = _resolve_media_to_data_urls(result.get("final_response", "") if isinstance(result, dict) else "")
                 effective_session_id = result.get("session_id", session_id) if isinstance(result, dict) else session_id
                 turn_messages = self._turn_transcript_messages(history, user_message, result) if isinstance(result, dict) else []
+                effective_runtime = {}
+                if isinstance(result, dict):
+                    effective_runtime = result.get("runtime") or {}
+                if not effective_runtime and isinstance(usage, dict):
+                    effective_runtime = usage.get("runtime") or {}
+                effective_runtime = self._sanitize_runtime_metadata(
+                    runtime=effective_runtime,
+                    requested_runtime=runtime_request.get("requested"),
+                    route_source=runtime_request.get("route_source") or "global",
+                    model_lock=(
+                        "confirmed"
+                        if effective_runtime and runtime_request.get("require_model_lock")
+                        else "accepted"
+                        if runtime_request.get("require_model_lock")
+                        else ""
+                    ),
+                )
                 await queue.put(_event_payload("assistant.completed", {
                     "session_id": effective_session_id,
                     "message_id": message_id,
@@ -2672,6 +3551,7 @@ class APIServerAdapter(BasePlatformAdapter):
                     "completed": True,
                     "partial": False,
                     "interrupted": False,
+                    "runtime": effective_runtime,
                 }))
                 await queue.put(_event_payload("run.completed", {
                     "session_id": effective_session_id,
@@ -2679,6 +3559,7 @@ class APIServerAdapter(BasePlatformAdapter):
                     "completed": True,
                     "messages": turn_messages,
                     "usage": usage,
+                    "runtime": effective_runtime,
                 }))
             except Exception as exc:
                 logger.exception("[api_server] session chat stream failed")
@@ -2727,6 +3608,48 @@ class APIServerAdapter(BasePlatformAdapter):
             logger.debug("[api_server] session SSE stream error: %s", exc)
         return response
 
+    async def _handle_session_model_lock(self, request: "web.Request") -> "web.Response":
+        """POST /api/sessions/{session_id}/model — backend-ack a Browser model lock."""
+        auth_err = self._check_auth(request)
+        if auth_err:
+            return auth_err
+        session_id = request.match_info["session_id"]
+        _, err = await self._get_existing_session_or_404(session_id)
+        if err:
+            return err
+        body, err = await self._read_json_body(request)
+        if err:
+            return err
+        runtime_request = self._session_runtime_request_from_body(body)
+        runtime_request["require_model_lock"] = True
+        lock_error = self._runtime_lock_error(runtime_request)
+        if lock_error is not None:
+            return lock_error
+        if not self._persist_session_runtime_lock(session_id, runtime_request):
+            return web.json_response(
+                _openai_error(
+                    "Could not persist the requested session model lock",
+                    code="model_lock_persistence_failed",
+                ),
+                status=500,
+            )
+        requested = runtime_request.get("requested") or {}
+        route = runtime_request.get("route") or {}
+        runtime = self._sanitize_runtime_metadata(
+            runtime={
+                "provider": route.get("provider") or requested.get("provider") or "",
+                "model": route.get("model") or requested.get("model") or "",
+                "route_source": runtime_request.get("route_source") or "raw_request",
+            },
+            requested_runtime=requested,
+            route_source=runtime_request.get("route_source") or "raw_request",
+            model_lock="accepted",
+        )
+        return web.json_response({
+            "object": "hermes.session.model_lock",
+            "session_id": session_id,
+            "runtime": runtime,
+        })
     @_admit_api_agent_request
     async def _handle_chat_completions(self, request: "web.Request") -> "web.Response":
         """POST /v1/chat/completions — OpenAI Chat Completions format."""
@@ -2861,6 +3784,20 @@ class APIServerAdapter(BasePlatformAdapter):
         # configured model_routes alias, this request's agent is created
         # with that route's model/provider instead of the global default.
         route = self._resolve_route(model_name)
+        agent_overrides = _request_agent_overrides(
+            body,
+            virtual_model=self._model_name,
+            allow_bare_model=self._direct_model_requests,
+        )
+        selection_error = self._request_route_conflict_error(
+            session_id=session_id,
+            gateway_session_key=gateway_session_key,
+            requested_model=agent_overrides.get("requested_model"),
+            requested_provider=agent_overrides.get("requested_provider"),
+            route=route,
+        )
+        if selection_error:
+            return web.json_response(_openai_error(selection_error), status=400)
 
         if stream:
             import queue as _q
@@ -2944,6 +3881,7 @@ class APIServerAdapter(BasePlatformAdapter):
                 tool_complete_callback=_on_tool_complete,
                 agent_ref=agent_ref,
                 gateway_session_key=gateway_session_key,
+                **agent_overrides,
                 route=route,
             ))
             # Ensure SSE drain loops can terminate without relying on polling
@@ -2964,12 +3902,16 @@ class APIServerAdapter(BasePlatformAdapter):
                 ephemeral_system_prompt=system_prompt,
                 session_id=session_id,
                 gateway_session_key=gateway_session_key,
+                **agent_overrides,
                 route=route,
             )
 
         idempotency_key = request.headers.get("Idempotency-Key")
         if idempotency_key:
-            fp = _make_request_fingerprint(body, keys=["model", "messages", "tools", "tool_choice", "stream"])
+            fp = _make_request_fingerprint(
+                body,
+                keys=["model", "provider", "model_options", "messages", "tools", "tool_choice", "stream"],
+            )
             try:
                 result, usage = await _idem_cache.get_or_set(idempotency_key, fp, _compute_completion)
             except Exception as e:
@@ -3979,10 +4921,22 @@ class APIServerAdapter(BasePlatformAdapter):
         # groups the entire conversation under one session entry.
         session_id = stored_session_id or str(uuid.uuid4())
 
-        # Per-client model routing for /v1/responses (see model_routes).
-        route = self._resolve_route(body.get("model"))
-
         stream = _coerce_request_bool(body.get("stream"), default=False)
+        route = self._resolve_route(body.get("model"))
+        agent_overrides = _request_agent_overrides(
+            body,
+            virtual_model=self._model_name,
+            allow_bare_model=self._direct_model_requests,
+        )
+        selection_error = self._request_route_conflict_error(
+            session_id=session_id,
+            gateway_session_key=gateway_session_key,
+            requested_model=agent_overrides.get("requested_model"),
+            requested_provider=agent_overrides.get("requested_provider"),
+            route=route,
+        )
+        if selection_error:
+            return web.json_response(_openai_error(selection_error), status=400)
         if stream:
             # Streaming branch — emit OpenAI Responses SSE events as the
             # agent runs so frontends can render text deltas and tool
@@ -4035,6 +4989,7 @@ class APIServerAdapter(BasePlatformAdapter):
                 tool_complete_callback=_on_tool_complete,
                 agent_ref=agent_ref,
                 gateway_session_key=gateway_session_key,
+                **agent_overrides,
                 route=route,
             ))
             # Ensure SSE drain loops can terminate without relying on polling
@@ -4069,6 +5024,7 @@ class APIServerAdapter(BasePlatformAdapter):
                 ephemeral_system_prompt=instructions,
                 session_id=session_id,
                 gateway_session_key=gateway_session_key,
+                **agent_overrides,
                 route=route,
             )
 
@@ -4076,7 +5032,16 @@ class APIServerAdapter(BasePlatformAdapter):
         if idempotency_key:
             fp = _make_request_fingerprint(
                 body,
-                keys=["input", "instructions", "previous_response_id", "conversation", "model", "tools"],
+                keys=[
+                    "input",
+                    "instructions",
+                    "previous_response_id",
+                    "conversation",
+                    "model",
+                    "provider",
+                    "model_options",
+                    "tools",
+                ],
             )
             try:
                 result, usage = await _idem_cache.get_or_set(idempotency_key, fp, _compute_response)
@@ -4747,7 +5712,14 @@ class APIServerAdapter(BasePlatformAdapter):
         tool_complete_callback=None,
         agent_ref: Optional[list] = None,
         gateway_session_key: Optional[str] = None,
+        requested_model: Optional[str] = None,
+        requested_provider: Optional[str] = None,
+        model_options: Optional[Dict[str, Any]] = None,
         route: Optional[Dict[str, Any]] = None,
+        session_model: Optional[str] = None,
+        requested_runtime: Optional[Dict[str, Any]] = None,
+        route_source: str = "global",
+        confirmed_runtime_lock: bool = False,
     ) -> tuple:
         """
         Create an agent and run a conversation in a thread executor.
@@ -4759,6 +5731,16 @@ class APIServerAdapter(BasePlatformAdapter):
         request's ``model`` field) that overrides the global model/provider
         for this specific request.
 
+        *session_model* is a raw model persisted on a native API session
+        row.  It is used only when the persisted value did not resolve to a
+        ``model_routes`` alias — see ``_create_agent`` for precedence.
+
+        *requested_runtime* / *route_source* / *confirmed_runtime_lock*
+        carry the Browser model-lock contract: when a confirmed lock is
+        active the completed agent's actual provider/model must match the
+        locked selection or the turn fails, and the response carries
+        sanitized ``runtime`` metadata reporting actual vs requested.
+
         If *agent_ref* is a one-element list, the AIAgent instance is stored
         at ``agent_ref[0]`` before ``run_conversation`` begins.  This allows
         callers (e.g. the SSE writer) to call ``agent.interrupt()`` from
@@ -4788,7 +5770,12 @@ class APIServerAdapter(BasePlatformAdapter):
                         tool_start_callback=tool_start_callback,
                         tool_complete_callback=tool_complete_callback,
                         gateway_session_key=gateway_session_key,
+                        requested_model=requested_model,
+                        requested_provider=requested_provider,
+                        model_options=model_options,
                         route=route,
+                        session_model=session_model,
+                        confirmed_runtime_lock=confirmed_runtime_lock,
                     )
                     if agent_ref is not None:
                         agent_ref[0] = agent
@@ -4821,7 +5808,99 @@ class APIServerAdapter(BasePlatformAdapter):
                     )
                     if _compacted_in_place or _session_rotated:
                         result["_compressed"] = True
+                    include_runtime = bool(
+                        requested_runtime
+                        or route
+                        or confirmed_runtime_lock
+                        or (route_source and route_source != "global")
+                    )
+                    if include_runtime:
+                        runtime = dict(getattr(agent, "_hermes_api_runtime", {}) or {})
+                        raw_provider = getattr(agent, "provider", "")
+                        raw_model = getattr(agent, "model", "")
+                        actual_provider = (
+                            self._clean_runtime_id(raw_provider, max_len=80)
+                            if isinstance(raw_provider, str)
+                            else ""
+                        )
+                        actual_model = (
+                            self._clean_runtime_id(raw_model)
+                            if isinstance(raw_model, str)
+                            else ""
+                        )
+                        if actual_provider:
+                            runtime["provider"] = actual_provider
+                        else:
+                            runtime.setdefault("provider", "")
+                        if actual_model:
+                            runtime["model"] = actual_model
+                        else:
+                            runtime.setdefault("model", "")
+                        if confirmed_runtime_lock:
+                            expected_provider = self._clean_runtime_id(
+                                (route or {}).get("provider")
+                                or (requested_runtime or {}).get("provider"),
+                                max_len=80,
+                            )
+                            expected_model = self._clean_runtime_id(
+                                (route or {}).get("model")
+                                or (requested_runtime or {}).get("model")
+                            )
+                            mismatched = (
+                                (expected_provider and actual_provider != expected_provider)
+                                or (expected_model and actual_model != expected_model)
+                            )
+                            if mismatched:
+                                raise RuntimeError(
+                                    "confirmed model lock runtime mismatch: "
+                                    f"expected provider={expected_provider or '<unspecified>'} "
+                                    f"model={expected_model or '<unspecified>'}; "
+                                    f"actual provider={actual_provider or '<unknown>'} "
+                                    f"model={actual_model or '<unknown>'}"
+                                )
+                        if requested_runtime:
+                            runtime["requested"] = {
+                                "provider": self._clean_runtime_id((requested_runtime or {}).get("provider"), max_len=80),
+                                "model": self._clean_runtime_id((requested_runtime or {}).get("model")),
+                            }
+                        runtime["route_source"] = route_source or runtime.get("route_source") or "global"
+                        runtime = self._sanitize_runtime_metadata(
+                            runtime=runtime,
+                            requested_runtime=requested_runtime,
+                            route_source=route_source or "global",
+                            model_lock=("confirmed" if confirmed_runtime_lock else ""),
+                        )
+                        if isinstance(result, dict):
+                            result["runtime"] = runtime
+                        usage["runtime"] = runtime
                     return result, usage
+                except _ProviderAuthResolutionError as exc:
+                    # Only _ProviderAuthResolutionError — raised exclusively
+                    # where _resolve_runtime_agent_kwargs() is called inside
+                    # _create_agent() — means a provider auth/credential
+                    # failure.  Catching bare RuntimeError here would
+                    # mislabel unrelated RuntimeErrors from
+                    # run_conversation() (e.g. "Failed to recreate closed
+                    # OpenAI client") as auth failures.  Matches run.py's
+                    # response shape (final_response text, no HTTP error).
+                    # Previously this propagated unhandled:
+                    # /v1/chat/completions caught it as an undifferentiated
+                    # "Internal server error" 500, and
+                    # /api/sessions/{id}/chat[/stream] didn't catch it at
+                    # all (raw aiohttp 500, no JSON body).  Handling it
+                    # here, once, covers every _run_agent() caller;
+                    # /v1/runs has its own branch in its executor.
+                    logger.warning("Provider authentication failed for session=%s: %s",
+                                   session_id or "", exc)
+                    return (
+                        {
+                            "final_response": f"⚠️ Provider authentication failed: {exc}",
+                            "messages": [],
+                            "api_calls": 0,
+                            "tools": [],
+                        },
+                        {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0},
+                    )
                 finally:
                     clear_session_vars(tokens)
 
@@ -4974,8 +6053,21 @@ class APIServerAdapter(BasePlatformAdapter):
                         )
                     conversation_history.append({"role": msg["role"], "content": str(content)})
 
+        session_id = body.get("session_id") or stored_session_id
+        route = self._resolve_route(body.get("model"))
+        agent_overrides = _request_agent_overrides(body, virtual_model=self._model_name)
+        selection_error = self._request_route_conflict_error(
+            session_id=session_id,
+            gateway_session_key=gateway_session_key,
+            requested_model=agent_overrides.get("requested_model"),
+            requested_provider=agent_overrides.get("requested_provider"),
+            route=route,
+        )
+        if selection_error:
+            return web.json_response(_openai_error(selection_error), status=400)
+
         run_id = f"run_{uuid.uuid4().hex}"
-        session_id = body.get("session_id") or stored_session_id or run_id
+        session_id = session_id or run_id
         # Approval queues gate host-side tool execution and must be isolated
         # per API run.  Client-provided session IDs and memory session keys are
         # conversation/memory scopes, not authorization namespaces: multiple
@@ -5021,8 +6113,6 @@ class APIServerAdapter(BasePlatformAdapter):
             model=body.get("model", self._model_name),
         )
 
-        # Per-client model routing for /v1/runs (see model_routes).
-        route = self._resolve_route(body.get("model"))
         # Background task outlives the HTTP response (and thus the middleware
         # profile scope). Capture now and re-enter inside the task/executor.
         request_profile = _api_request_profile.get()
@@ -5049,6 +6139,9 @@ class APIServerAdapter(BasePlatformAdapter):
                         stream_delta_callback=_text_cb,
                         tool_progress_callback=event_cb,
                         gateway_session_key=gateway_session_key,
+                        requested_model=agent_overrides.get("requested_model"),
+                        requested_provider=agent_overrides.get("requested_provider"),
+                        model_options=agent_overrides.get("model_options"),
                         route=route,
                     )
                 self._active_run_agents[run_id] = agent
@@ -5200,6 +6293,31 @@ class APIServerAdapter(BasePlatformAdapter):
                 except Exception:
                     pass
                 raise
+            except _ProviderAuthResolutionError as exc:
+                # /v1/runs builds its own agent via _create_agent() and does
+                # not route through _run_agent() (see that method's own
+                # _ProviderAuthResolutionError branch), so it needs its own
+                # handling to surface the same distinguished, controlled
+                # message the other endpoints give a provider auth/credential
+                # failure, instead of falling through to the generic
+                # except-Exception branch below.
+                logger.warning("Provider authentication failed for run=%s: %s", run_id, exc)
+                error_msg = f"⚠️ Provider authentication failed: {exc}"
+                self._set_run_status(
+                    run_id,
+                    "failed",
+                    error=error_msg,
+                    last_event="run.failed",
+                )
+                try:
+                    _put_event_if_active({
+                        "event": "run.failed",
+                        "run_id": run_id,
+                        "timestamp": time.time(),
+                        "error": error_msg,
+                    })
+                except Exception:
+                    pass
             except Exception as exc:
                 logger.exception("[api_server] run %s failed", run_id)
                 self._set_run_status(
diff --git a/gateway/platforms/base.py b/gateway/platforms/base.py
index 51c9f42405a..4f2c0e98fa4 100644
--- a/gateway/platforms/base.py
+++ b/gateway/platforms/base.py
@@ -250,7 +250,7 @@ def _detect_macos_system_proxy() -> str | None:
         return None
     try:
         out = subprocess.check_output(
-            ["scutil", "--proxy"], timeout=3, text=True, stderr=subprocess.DEVNULL,
+            ["scutil", "--proxy"], timeout=3, text=True, encoding='utf-8', errors='replace', stderr=subprocess.DEVNULL,
         )
     except Exception:
         return None
@@ -1807,6 +1807,16 @@ class MessageEvent:
     reply_to_author_id: Optional[str] = None
     reply_to_author_name: Optional[str] = None
     reply_to_is_own_message: bool = False  # True when the user replied to this bot/assistant's message
+
+    # Structured interactive-prompt reply (relay Phase 3). Present when this
+    # event is the user answering a native interactive prompt rendered by the
+    # relay connector (Discord component / Telegram inline keyboard / Slack
+    # Block Kit / WhatsApp button-list). Shape mirrors the wire contract:
+    # {prompt_id, option_id, label?, prompt_message_id?}. The RelayAdapter
+    # consumes it in _on_inbound (routing to the approval/slash-confirm/
+    # clarify resolvers) BEFORE normal dispatch; native adapters never set it
+    # (their button callbacks resolve in-process).
+    prompt_response: Optional[Dict[str, Any]] = None
     
     # Auto-loaded skill(s) for topic/channel bindings (e.g., Telegram DM Topics,
     # Discord channel_skill_bindings).  A single name or ordered list.
diff --git a/gateway/platforms/qqbot/adapter.py b/gateway/platforms/qqbot/adapter.py
index cb9a64e3bd4..2816326efb3 100644
--- a/gateway/platforms/qqbot/adapter.py
+++ b/gateway/platforms/qqbot/adapter.py
@@ -1202,7 +1202,7 @@ class QQAdapter(BasePlatformAdapter):
             home = get_hermes_home()
             response_path = home / ".update_response"
             tmp = response_path.with_suffix(".tmp")
-            tmp.write_text(answer)
+            tmp.write_text(answer, encoding="utf-8")
             tmp.replace(response_path)
             logger.info(
                 "QQ update prompt answered %r by %s",
diff --git a/gateway/platforms/webhook.py b/gateway/platforms/webhook.py
index 315f2e7cd37..3cf306e8584 100644
--- a/gateway/platforms/webhook.py
+++ b/gateway/platforms/webhook.py
@@ -1259,7 +1259,7 @@ class WebhookAdapter(BasePlatformAdapter):
                     content,
                 ],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=30,
             )
             if result.returncode == 0:
diff --git a/gateway/platforms/webhook_filters.py b/gateway/platforms/webhook_filters.py
index f8db81005db..30198c6e52d 100644
--- a/gateway/platforms/webhook_filters.py
+++ b/gateway/platforms/webhook_filters.py
@@ -252,7 +252,7 @@ class WebhookRouteProcessor:
                 argv,
                 input=json.dumps(payload),
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
                 timeout=self.script_timeout_seconds,
                 cwd=str(path.parent),
                 env=_sanitize_subprocess_env(os.environ.copy()),
diff --git a/gateway/readiness.py b/gateway/readiness.py
index 379e074bb40..d49ea820482 100644
--- a/gateway/readiness.py
+++ b/gateway/readiness.py
@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import shutil
 import sqlite3
+from contextlib import closing
 from pathlib import Path
 from typing import Any
 
@@ -31,8 +32,12 @@ def _probe_state_db(home: Path) -> dict[str, Any]:
         # A readiness probe must never compete with normal state writers. A
         # read-only schema query still catches unreadable/corrupt databases
         # without taking a write reservation on every health poll.
+        # ``closing(...)`` is required: sqlite3's connection context manager
+        # only commits/rolls back — it never closes, so a bare ``with
+        # sqlite3.connect(...)`` leaks one connection (and its fds) per
+        # health poll in the long-running gateway (#69678/#69567 bug class).
         uri = f"file:{path.as_posix()}?mode=ro"
-        with sqlite3.connect(uri, uri=True, timeout=1.0) as conn:
+        with closing(sqlite3.connect(uri, uri=True, timeout=1.0)) as conn:
             conn.execute("PRAGMA query_only = ON")
             conn.execute("SELECT name FROM sqlite_master LIMIT 1").fetchone()
         return _check("ok")
diff --git a/gateway/relay/__init__.py b/gateway/relay/__init__.py
index 909b21125ca..77481d8a8fb 100644
--- a/gateway/relay/__init__.py
+++ b/gateway/relay/__init__.py
@@ -256,6 +256,44 @@ def relay_wake_url() -> Optional[str]:
     return value.rstrip("/") or None
 
 
+def relay_display_name() -> Optional[str]:
+    """The human-facing agent display name, forwarded at provision (Phase 1 parity).
+
+    The PRIMARY source for the connector's multi-agent reply-attribution prefix
+    (gateway-gateway #171): in a multi-agent scope the shared bot prepends
+    ``**<displayName>:** `` to this instance's replies. Gateway-asserted but
+    safely scoped exactly like ``relay_instance_id()`` / ``relay_wake_url()`` —
+    the tenant stays token-verified, so a dishonest gateway can only label its
+    OWN instance. Absent -> the connector stores null and attribution falls
+    back to the instance's linked-owner identity, else skips the prefix.
+
+    Env first (Docker/NAS stamps ``GATEWAY_RELAY_DISPLAY_NAME``), then the
+    skin's branded agent name (``get_branding("agent_name")`` — the same value
+    the CLI banner shows), so a self-hosted rename via skin config propagates
+    on the next boot's re-provision (the connector rotates on change, same as
+    a wake-url move).
+    """
+    value = os.environ.get("GATEWAY_RELAY_DISPLAY_NAME", "").strip()
+    if not value:
+        try:
+            from hermes_cli.skin_engine import get_active_skin  # late import: boot-safe
+
+            value = str(
+                get_active_skin().get_branding("agent_name", "") or ""
+            ).strip()
+        except Exception:  # noqa: BLE001 - branding absence must never crash boot
+            value = ""
+        # The stock brand name is IDENTICAL on every default install, so in a
+        # multi-agent scope it would prefix every reply "**Hermes Agent:**" —
+        # shadowing the connector's linked-owner fallback, which actually
+        # disambiguates. Only a deliberately customized name is forwarded.
+        if value == "Hermes Agent":
+            value = ""
+    # Mirror the connector's ingest sanitization (trim + 64-char cap) so what
+    # we send is what gets stored.
+    return value[:64] or None
+
+
 def _provision_url(relay_dial_url: str) -> str:
     """Map the ``ws(s)://…/relay`` dial URL to the ``http(s)://…/relay/provision`` POST URL."""
     raw = relay_dial_url.rstrip("/")
@@ -384,6 +422,7 @@ def _post_provision(
     route_keys: list[str],
     instance_id: Optional[str] = None,
     wake_url: Optional[str] = None,
+    display_name: Optional[str] = None,
     timeout: float = 15.0,
 ) -> dict:
     """POST to the connector's ``/relay/provision`` and return the JSON body.
@@ -413,6 +452,11 @@ def _post_provision(
     # stores null and simply can't wake this instance (buffering still works).
     if wake_url:
         body["wakeUrl"] = wake_url
+    # Same for the display name (Phase 1 parity, gg#171): omit when absent so
+    # the connector stores null and attribution falls back to the linked-owner
+    # identity.
+    if display_name:
+        body["displayName"] = display_name
     data = json.dumps(body).encode("utf-8")
     req = urllib.request.Request(
         provision_url,
@@ -591,6 +635,7 @@ def self_provision_relay() -> bool:
     route_keys = relay_route_keys()
     instance_id = relay_instance_id()
     wake_url = relay_wake_url()
+    display_name = relay_display_name()
 
     # Phase 1.5 (D-Q1.5c): provision EACH fronted platform under the SAME
     # gatewayId + the SAME (platform-less) per-gateway secret. The connector's
@@ -615,6 +660,7 @@ def self_provision_relay() -> bool:
                 route_keys=route_keys,
                 instance_id=instance_id,
                 wake_url=wake_url,
+                display_name=display_name,
             )
         except RuntimeError as exc:
             logger.warning(
diff --git a/gateway/relay/adapter.py b/gateway/relay/adapter.py
index e743f26b290..b149539cee5 100644
--- a/gateway/relay/adapter.py
+++ b/gateway/relay/adapter.py
@@ -25,6 +25,7 @@ from typing import Any, Callable, Dict, Optional
 from gateway.config import Platform, PlatformConfig
 from gateway.platforms.base import BasePlatformAdapter, MessageEvent, SendResult
 from gateway.relay.descriptor import CapabilityDescriptor
+from gateway.relay.media import RelayMediaClient
 from gateway.relay.transport import RelayTransport
 from gateway.session import SessionSource
 
@@ -87,6 +88,21 @@ class RelayAdapter(BasePlatformAdapter):
         # non-retryable "relay disabled" fatal so the dashboard stops showing a
         # red "retrying" spin against a dead credential.
         self._revocation_monitor: Optional[asyncio.Task[None]] = None
+        # Phase 2 media: the authenticated client for the connector's
+        # /relay/media routes (upload for send_media source_url; download for
+        # inbound re-hosted attachments → local paths the vision/file tools
+        # consume). Built lazily from the relay dial URL + per-gateway creds;
+        # None when either is absent (media lanes then degrade to the
+        # pre-media text fallbacks).
+        self._media_client: Optional["RelayMediaClient"] = None
+        # Phase 3 interactive: prompt_id -> pending-prompt state. A `prompt`
+        # op renders native options; the user's pick comes back inbound as a
+        # prompt_response naming this id. The registry maps it back to the
+        # waiting primitive (approval / slash-confirm / clarify) so the click
+        # resolves EXACTLY like the native adapters' button callbacks.
+        # Entries expire lazily (see _pop_prompt) so an unanswered prompt
+        # never leaks. Keyed by our own minted 8-hex ids.
+        self._pending_prompts: Dict[str, Dict[str, Any]] = {}
 
     # ── capability surface (from descriptor) ─────────────────────────────
     @property
@@ -227,8 +243,55 @@ class RelayAdapter(BasePlatformAdapter):
     async def _on_inbound(self, event) -> None:
         """Bridge a connector-delivered MessageEvent into the normal adapter path."""
         self._capture_scope(event)
+        # Phase 3: a structured prompt answer resolves its waiting primitive
+        # (approval/confirm/clarify) and is CONSUMED — it must not also
+        # dispatch as a chat message. Unknown/expired prompt ids fall through
+        # (the command-shaped text then behaves like a typed reply).
+        if await self._consume_prompt_response(event):
+            return
+        await self._localize_inbound_media(event)
         await self.handle_message(event)
 
+    async def _localize_inbound_media(self, event) -> None:
+        """Download connector re-hosted attachments to local temp paths.
+
+        The wire's ``media_urls`` name connector re-hosts
+        (``{connector}/relay/media/{id}``, per-gateway-bearer-authenticated) or
+        public platform CDN URLs (Discord pass-through). Every NATIVE adapter
+        presents inbound media to the agent as LOCAL FILE PATHS (the vision /
+        file tools consume paths, and an authenticated URL would be useless in
+        the agent's context anyway) — so mirror that here: fetch each URL and
+        swap the list entries for temp paths. Best-effort per entry: a failed
+        download drops that entry (never the message); no client ⇒ only
+        re-host URLs are dropped (they'd 401 for every consumer downstream),
+        public URLs stay.
+        """
+        try:
+            urls = list(getattr(event, "media_urls", None) or [])
+            if not urls:
+                return
+            client = self._get_media_client()
+            localized: list[str] = []
+            for url in urls:
+                if not isinstance(url, str) or not url:
+                    continue
+                if client is None:
+                    # No authenticated client: keep public URLs, drop re-hosts.
+                    if "/relay/media/" not in url:
+                        localized.append(url)
+                    continue
+                path = await client.download(url)
+                if path:
+                    localized.append(path)
+                elif "/relay/media/" not in url:
+                    # A public URL that failed to download still has value as
+                    # a URL (native adapters pass URLs to vision in some
+                    # lanes); a dead re-host reference does not.
+                    localized.append(url)
+            event.media_urls = localized
+        except Exception:  # noqa: BLE001 - media localization must never break inbound
+            logger.debug("relay inbound media localization failed", exc_info=True)
+
     def _capture_scope(self, event) -> None:
         """Remember a chat_id's egress discriminator from an inbound event so our
         outbound (the agent's reply) can re-assert it for the connector's egress
@@ -319,16 +382,24 @@ class RelayAdapter(BasePlatformAdapter):
                 meta["user_id"] = author
         return meta
 
-    def _platform_is_fronted(self, platform: str) -> bool:
-        """Whether ``platform`` is one of the platforms this gateway fronts over
-        the relay (Phase 1.5). Reads the transport's advertised identity set; used
-        to decide whether a follow-up's platform-prefixed `kind` names a real
-        fronted platform worth tagging on the frame (vs. leaving egress to the
-        session default). Safe when the transport is absent or single-identity."""
+    def fronts_platform(self, platform: Any) -> bool:
+        """Whether the authenticated relay transport advertises ``platform``.
+
+        This is the restart-safe delivery ownership signal: it comes from the
+        configured identity set sent during handshake, not from an inbound
+        chat cache learned only after a user sends another message.
+        """
+        platform_value = getattr(platform, "value", platform)
+        if not platform_value:
+            return False
         ids = getattr(self._transport, "_identities", None)
         if not ids:
             return False
-        return any(p == platform for p, _ in ids)
+        return any(p == str(platform_value) for p, _ in ids)
+
+    def _platform_is_fronted(self, platform: str) -> bool:
+        """Backward-compatible internal alias for follow-up routing."""
+        return self.fronts_platform(platform)
 
     async def on_interrupt(self, session_key: str, chat_id: str) -> None:
         """Bridge a connector-delivered /stop into the adapter's interrupt path.
@@ -361,12 +432,13 @@ class RelayAdapter(BasePlatformAdapter):
 
         NEVER raises: a malformed forward must not kill the read loop.
 
-        NOTE (open semantic sub-design, flagged for review): the interaction ->
-        MessageEvent mapping below is the v1 default. The exact agent UX for a
-        slash-command / button interaction (vs. a plain message) — command name
-        surfacing, option rendering, deferred-vs-immediate response — is the open
-        piece tracked in the spec; the TRANSPORT + receive mechanism (this whole
-        path) is settled.
+        Interaction -> MessageEvent command mapping (formerly flagged here as an
+        open sub-design, now implemented): an APPLICATION_COMMAND interaction is
+        normalized to a leading-slash COMMAND event ("/name arg…", mirroring the
+        connector's Slack slash-command lane, normalizeSlackCommand), so the
+        dispatcher routes it as a command instead of plain chat. Component
+        interactions (custom_id) still surface as best-effort TEXT; the
+        deferred-vs-immediate response UX remains connector-side.
         """
         try:
             platform = getattr(forward, "platform", "") or ""
@@ -374,6 +446,11 @@ class RelayAdapter(BasePlatformAdapter):
                 event = self._discord_interaction_to_event(forward)
                 if event is not None:
                     self._capture_scope(event)
+                    # Phase 3: a component press carrying a Hermes prompt token
+                    # resolves its waiting primitive and is consumed (same
+                    # gate as _on_inbound's prompt_response arm).
+                    if await self._consume_prompt_response(event):
+                        return
                     await self.handle_message(event)
                     return
             logger.info(
@@ -409,8 +486,21 @@ class RelayAdapter(BasePlatformAdapter):
         # 3 = MESSAGE_COMPONENT; 5 = MODAL_SUBMIT. Surface a best-effort text.
         itype = payload.get("type")
         data = payload.get("data") or {}
+        message_type = MessageType.TEXT
         if itype == 2:
-            text = str(data.get("name") or "")
+            # Normalize a real slash-command interaction to a leading-slash
+            # command string — the shape the dispatcher (MessageEvent.is_command:
+            # text.startswith("/")) and the native Discord adapter's
+            # _run_simple_slash lane (f"/model {name}".strip()) both expect.
+            # Options render space-separated: scalar options contribute their
+            # value; SUB_COMMAND/SUB_COMMAND_GROUP (types 1/2) contribute their
+            # name then their nested options. Mirrors the connector's Slack
+            # slash lane (normalizeSlackCommand: `${command} ${args}`.trim()).
+            text = ("/" + str(data.get("name") or "")).rstrip("/") or ""
+            if text:
+                parts = [text] + self._render_interaction_options(data.get("options"))
+                text = " ".join(parts).strip()
+                message_type = MessageType.COMMAND
         elif itype == 3:
             text = str(data.get("custom_id") or "")
         else:
@@ -428,7 +518,78 @@ class RelayAdapter(BasePlatformAdapter):
             scope_id=str(guild_id) if guild_id else None,  # Discord guild → generic scope slot
             message_id=str(payload.get("id")) if payload.get("id") else None,
         )
-        return MessageEvent(text=text, message_type=MessageType.TEXT, source=source)
+        event = MessageEvent(text=text, message_type=message_type, source=source)
+        if itype == 3:
+            # Phase 3: a component press whose custom_id is a Hermes prompt
+            # token (hp1:<prompt_id>:<option_id>) becomes a STRUCTURED prompt
+            # answer — _on_inbound's _consume_prompt_response then resolves
+            # the waiting approval/confirm/clarify, replacing the bare-
+            # custom_id-as-text stub. Foreign custom_ids keep the legacy
+            # best-effort TEXT shape.
+            decoded = self._decode_prompt_token(text)
+            if decoded:
+                prompt_id, option_id = decoded
+                msg = payload.get("message") or {}
+                prompt_message_id = (
+                    str(msg.get("id")) if isinstance(msg, dict) and msg.get("id") else None
+                )
+                event.prompt_response = {
+                    "prompt_id": prompt_id,
+                    "option_id": option_id,
+                    "prompt_message_id": prompt_message_id,
+                }
+                event.text = f"/{option_id}"
+                event.message_type = MessageType.COMMAND
+        return event
+
+    @staticmethod
+    def _decode_prompt_token(token: str):
+        """Decode an hp1:<prompt_id>:<option_id> callback token, or None.
+
+        Mirrors the connector's promptCodec.decodePromptCallback (the token
+        alphabet is [A-Za-z0-9_.-], ≤32 per id) so both ends agree on what is
+        — and is not — a Hermes prompt answer.
+        """
+        import re
+
+        if not token:
+            return None
+        parts = token.split(":")
+        if len(parts) != 3 or parts[0] != "hp1":
+            return None
+        id_re = re.compile(r"^[A-Za-z0-9_.\-]{1,32}$")
+        if not id_re.match(parts[1]) or not id_re.match(parts[2]):
+            return None
+        return parts[1], parts[2]
+
+    @staticmethod
+    def _render_interaction_options(options) -> list:
+        """Render Discord interaction options to space-separated text parts.
+
+        Discord's `data.options` is a list of {name, value, type}. Scalar
+        options (STRING/INTEGER/BOOLEAN/…) contribute just their value —
+        matching the native adapter's `f"/model {name}".strip()` shape, where
+        only the value follows the command. SUB_COMMAND (1) and
+        SUB_COMMAND_GROUP (2) contribute their *name* then recurse into their
+        nested `options` list (one level of nesting per Discord's schema:
+        group -> subcommand -> scalars).
+        """
+        parts: list = []
+        if not isinstance(options, list):
+            return parts
+        for opt in options:
+            if not isinstance(opt, dict):
+                continue
+            if opt.get("type") in (1, 2):  # SUB_COMMAND / SUB_COMMAND_GROUP
+                sub_name = str(opt.get("name") or "").strip()
+                if sub_name:
+                    parts.append(sub_name)
+                parts.extend(RelayAdapter._render_interaction_options(opt.get("options")))
+            else:
+                value = opt.get("value")
+                if value is not None and str(value).strip():
+                    parts.append(str(value).strip())
+        return parts
 
     async def disconnect(self) -> None:
         # Phase 7 Unit 7d-B: stop the revocation monitor first so it can't fire a
@@ -488,13 +649,27 @@ class RelayAdapter(BasePlatformAdapter):
             logger.debug("relay go_dormant failed", exc_info=True)
             return False
 
-    async def send(
+    async def send_for_platform(
         self,
+        logical_platform: Any,
         chat_id: str,
         content: str,
         reply_to: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
     ) -> SendResult:
+        """Send to an explicitly advertised logical platform over Relay.
+
+        Scheduled and persisted-home deliveries have no fresh inbound event to
+        populate ``_platform_by_chat``. The shared delivery resolver calls this
+        method only after ``fronts_platform`` succeeds, and this method repeats
+        that check fail-closed before stamping the outbound frame.
+        """
+        platform_value = getattr(logical_platform, "value", logical_platform)
+        if not self.fronts_platform(platform_value):
+            return SendResult(
+                success=False,
+                error=f"relay does not front platform {platform_value}",
+            )
         if self._transport is None:
             return SendResult(success=False, error="no transport")
         result = await self._transport.send_outbound(
@@ -505,6 +680,42 @@ class RelayAdapter(BasePlatformAdapter):
                 "reply_to": reply_to,
                 "metadata": self._with_scope(chat_id, metadata),
             },
+            platform=str(platform_value),
+        )
+        return SendResult(
+            success=bool(result.get("success")),
+            message_id=result.get("message_id"),
+            error=result.get("error"),
+            raw_response=result,
+        )
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        send_metadata = dict(metadata or {})
+        explicit_platform = send_metadata.pop("_relay_logical_platform", None)
+        if explicit_platform:
+            return await self.send_for_platform(
+                explicit_platform,
+                chat_id,
+                content,
+                reply_to=reply_to,
+                metadata=send_metadata or None,
+            )
+        if self._transport is None:
+            return SendResult(success=False, error="no transport")
+        result = await self._transport.send_outbound(
+            {
+                "op": "send",
+                "chat_id": chat_id,
+                "content": content,
+                "reply_to": reply_to,
+                "metadata": self._with_scope(chat_id, send_metadata),
+            },
             platform=self._platform_by_chat.get(str(chat_id)),
         )
         return SendResult(
@@ -620,7 +831,12 @@ class RelayAdapter(BasePlatformAdapter):
 
     async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
         # Proxied to the connector (it owns the platform connection / cache).
-        if self._transport is None:
+        # Gated on op-level capability discovery: a connector that doesn't
+        # advertise get_chat_info in supported_ops (including every legacy
+        # connector, where supported_ops is empty and the LEGACY_OPS set
+        # applies) would only return "unsupported op", so skip the round trip
+        # and answer with the same local fallback the error path produced.
+        if self._transport is None or not self.descriptor.supports_op("get_chat_info"):
             return {"name": chat_id, "type": "dm"}
         return await self._transport.get_chat_info(chat_id)
 
@@ -666,3 +882,738 @@ class RelayAdapter(BasePlatformAdapter):
             message_id=result.get("message_id"),
             error=result.get("error"),
         )
+
+    # ── Phase 2 media ─────────────────────────────────────────────────────
+
+    def _get_media_client(self) -> Optional[RelayMediaClient]:
+        """Lazily build the authenticated /relay/media client.
+
+        Uses the SAME connector base URL the WS dials and the SAME per-gateway
+        (id, secret) the upgrade authenticates with — no new configuration.
+        None when either is unavailable (unenrolled/dev), and every media lane
+        then degrades to its pre-media fallback.
+        """
+        if self._media_client is not None:
+            return self._media_client
+        try:
+            from gateway.relay import relay_connection_auth, relay_url
+            from gateway.relay.media import media_base_url
+
+            url = relay_url()
+            gateway_id, secret = relay_connection_auth()
+            if not url:
+                return None
+            client = RelayMediaClient(media_base_url(url), gateway_id, secret)
+            if not client.enabled:
+                return None
+            self._media_client = client
+            return client
+        except Exception:  # noqa: BLE001 - media plumbing must never break the adapter
+            logger.debug("relay media client init failed", exc_info=True)
+            return None
+
+    async def _send_media(
+        self,
+        chat_id: str,
+        *,
+        media_kind: str,
+        source: str,
+        source_is_path: bool,
+        caption: Optional[str] = None,
+        filename: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Optional[SendResult]:
+        """Egress one media object via the connector's ``send_media`` op.
+
+        ``source`` is either a LOCAL file path (uploaded to the connector's
+        /relay/media first — the connector cannot reach our filesystem) or an
+        already-public URL (fal.media output etc. — passed through; the
+        connector downloads it directly).
+
+        Returns None when the lane is unavailable (op not advertised, no
+        transport, upload failed) so each caller can fall back to its
+        pre-media behaviour — media delivery is progressive enhancement,
+        never a regression when the connector predates the op.
+        """
+        if self._transport is None or not self.descriptor.supports_op("send_media"):
+            return None
+        source_url = source
+        if source_is_path:
+            client = self._get_media_client()
+            if client is None:
+                return None
+            uploaded = await client.upload(source, filename=filename)
+            if not uploaded:
+                return None
+            source_url = uploaded
+        action: Dict[str, Any] = {
+            "op": "send_media",
+            "chat_id": chat_id,
+            "media_kind": media_kind,
+            "source_url": source_url,
+            "content": caption or "",
+            "reply_to": reply_to,
+            "metadata": self._with_scope(chat_id, metadata),
+        }
+        if filename:
+            action["filename"] = filename
+        try:
+            result = await self._transport.send_outbound(
+                action,
+                platform=self._platform_by_chat.get(str(chat_id)),
+            )
+        except Exception:  # noqa: BLE001 - transport failure degrades to the caller's fallback
+            logger.debug("relay send_media transport failure", exc_info=True)
+            return None
+        if not result.get("success"):
+            # A structured connector decline (size cap, platform rejection).
+            # Surface it as a failed lane so the caller's fallback still
+            # delivers SOMETHING (the caption/notice), mirroring native
+            # adapters' upload-failure paths.
+            logger.warning(
+                "relay send_media declined for %s: %s",
+                chat_id,
+                result.get("error"),
+            )
+            return None
+        return SendResult(
+            success=True,
+            message_id=result.get("message_id"),
+            raw_response=result,
+        )
+
+    async def send_image(
+        self,
+        chat_id: str,
+        image_url: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send an image (public URL) as a native attachment via the connector."""
+        result = await self._send_media(
+            chat_id,
+            media_kind="image",
+            source=image_url,
+            source_is_path=False,
+            caption=caption,
+            reply_to=reply_to,
+            metadata=metadata,
+        )
+        if result is not None:
+            return result
+        return await super().send_image(
+            chat_id, image_url, caption=caption, reply_to=reply_to, metadata=metadata
+        )
+
+    async def send_image_file(
+        self,
+        chat_id: str,
+        image_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a local image file natively (upload → send_media)."""
+        result = await self._send_media(
+            chat_id,
+            media_kind="image",
+            source=image_path,
+            source_is_path=True,
+            caption=caption,
+            reply_to=reply_to,
+            metadata=metadata,
+        )
+        if result is not None:
+            return result
+        return await super().send_image_file(
+            chat_id, image_path, caption=caption, reply_to=reply_to,
+            metadata=metadata, **kwargs,
+        )
+
+    async def send_voice(
+        self,
+        chat_id: str,
+        audio_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a local audio file as a native voice message (upload → send_media)."""
+        result = await self._send_media(
+            chat_id,
+            media_kind="voice",
+            source=audio_path,
+            source_is_path=True,
+            caption=caption,
+            reply_to=reply_to,
+            metadata=metadata,
+        )
+        if result is not None:
+            return result
+        return await super().send_voice(
+            chat_id, audio_path, caption=caption, reply_to=reply_to,
+            metadata=metadata, **kwargs,
+        )
+
+    async def send_video(
+        self,
+        chat_id: str,
+        video_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a local video file natively (upload → send_media)."""
+        result = await self._send_media(
+            chat_id,
+            media_kind="video",
+            source=video_path,
+            source_is_path=True,
+            caption=caption,
+            reply_to=reply_to,
+            metadata=metadata,
+        )
+        if result is not None:
+            return result
+        return await super().send_video(
+            chat_id, video_path, caption=caption, reply_to=reply_to,
+            metadata=metadata, **kwargs,
+        )
+
+    async def send_document(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: Optional[str] = None,
+        file_name: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a local file as a downloadable attachment (upload → send_media)."""
+        result = await self._send_media(
+            chat_id,
+            media_kind="document",
+            source=file_path,
+            source_is_path=True,
+            caption=caption,
+            filename=file_name,
+            reply_to=reply_to,
+            metadata=metadata,
+        )
+        if result is not None:
+            return result
+        return await super().send_document(
+            chat_id, file_path, caption=caption, file_name=file_name,
+            reply_to=reply_to, metadata=metadata, **kwargs,
+        )
+
+    # ── Phase 3 interactive: prompt + react ──────────────────────────────
+
+    def _mint_prompt(self, kind: str, state: Dict[str, Any], timeout_s: float = 3600.0) -> str:
+        """Register a pending prompt and return its 8-hex id.
+
+        ``state`` carries what the resolver needs when the answer comes back
+        (session_key, resolver kind, per-kind extras). Expiry is enforced
+        gateway-side on consumption (_pop_prompt) — the wire's timeout_s is
+        advisory only.
+        """
+        import secrets
+        import time
+
+        prompt_id = secrets.token_hex(4)
+        self._pending_prompts[prompt_id] = {
+            **state,
+            "kind": kind,
+            "expires_at": time.time() + timeout_s,
+        }
+        # Opportunistic sweep so abandoned prompts can't accumulate: drop
+        # anything already expired (cheap — dict is small by construction).
+        now = time.time()
+        for stale in [k for k, v in self._pending_prompts.items() if v.get("expires_at", 0) < now]:
+            self._pending_prompts.pop(stale, None)
+        return prompt_id
+
+    def _pop_prompt(self, prompt_id: str) -> Optional[Dict[str, Any]]:
+        """Consume a pending prompt: one answer wins, expired entries miss."""
+        import time
+
+        state = self._pending_prompts.pop(str(prompt_id), None)
+        if not state:
+            return None
+        if state.get("expires_at", 0) < time.time():
+            return None
+        return state
+
+    async def _send_prompt(
+        self,
+        chat_id: str,
+        *,
+        prompt_kind: str,
+        text: str,
+        prompt_id: str,
+        options: list,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        timeout_s: Optional[int] = None,
+    ) -> Optional[SendResult]:
+        """Egress one `prompt` op; None when the lane is unavailable.
+
+        Mirrors _send_media's progressive-enhancement posture: op-gated on the
+        descriptor advertising `prompt`, and every failure returns None so the
+        caller falls back to its numbered-text base behaviour (which is the
+        pre-Phase-3 UX, still fully functional via typed replies).
+        """
+        if self._transport is None or not self.descriptor.supports_op("prompt"):
+            return None
+        action: Dict[str, Any] = {
+            "op": "prompt",
+            "chat_id": chat_id,
+            "content": text,
+            "prompt_kind": prompt_kind,
+            "prompt_id": prompt_id,
+            "options": options,
+            "reply_to": reply_to,
+            "metadata": self._with_scope(chat_id, metadata),
+        }
+        if timeout_s is not None:
+            action["timeout_s"] = int(timeout_s)
+        try:
+            result = await self._transport.send_outbound(
+                action,
+                platform=self._platform_by_chat.get(str(chat_id)),
+            )
+        except Exception:  # noqa: BLE001 - transport failure degrades to fallback
+            logger.debug("relay prompt transport failure", exc_info=True)
+            return None
+        if not result.get("success"):
+            logger.warning(
+                "relay prompt declined for %s: %s", chat_id, result.get("error")
+            )
+            return None
+        return SendResult(
+            success=True,
+            message_id=result.get("message_id"),
+            raw_response=result,
+        )
+
+    async def send_exec_approval(
+        self,
+        chat_id: str,
+        command: str,
+        session_key: str,
+        description: str = "dangerous command",
+        metadata: Optional[Dict[str, Any]] = None,
+        allow_permanent: bool = True,
+        allow_session: bool = True,
+        smart_denied: bool = False,
+    ) -> SendResult:
+        """Native-button exec approval over the relay (Phase 3).
+
+        Renders the same choice set as the native adapters (Allow Once /
+        Session / Always / Deny, gated by the same flags) through the
+        connector's `prompt` op. The user's press comes back as a
+        prompt_response and resolves via tools.approval.resolve_gateway_approval
+        — the exact mechanism the native button handlers use. When the lane is
+        unavailable the send FAILS (success=False) so gateway/run.py's existing
+        button→text fallback takes over (same contract as a native adapter's
+        failed button send).
+        """
+        options: list = [{"id": "once", "label": "✅ Allow Once", "style": "success"}]
+        if not smart_denied and allow_session:
+            options.append({"id": "session", "label": "✅ Session", "style": "primary"})
+            if allow_permanent:
+                options.append({"id": "always", "label": "✅ Always", "style": "primary"})
+        options.append({"id": "deny", "label": "❌ Deny", "style": "danger"})
+
+        cmd_preview = command if len(command) <= 1500 else command[:1500] + "..."
+        text = (
+            "⚠️ **Command Approval Required**\n\n"
+            f"```\n{cmd_preview}\n```\n"
+            f"Reason: {description}"
+        )
+        if smart_denied:
+            text += "\n\n**Smart DENY:** owner override applies to this one operation only."
+
+        prompt_id = self._mint_prompt(
+            "exec_approval",
+            {"session_key": session_key, "chat_id": str(chat_id)},
+        )
+        result = await self._send_prompt(
+            chat_id,
+            prompt_kind="approval",
+            text=text,
+            prompt_id=prompt_id,
+            options=options,
+            metadata=metadata,
+        )
+        if result is not None:
+            return result
+        # Lane unavailable: unregister and let run.py's text fallback run.
+        self._pending_prompts.pop(prompt_id, None)
+        return SendResult(success=False, error="relay prompt op unavailable")
+
+    async def send_slash_confirm(
+        self,
+        chat_id: str,
+        title: str,
+        message: str,
+        session_key: str,
+        confirm_id: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Three-button slash-command confirmation over the relay (Phase 3).
+
+        Resolves via tools.slash_confirm.resolve() — the same primitive the
+        native button handlers call. Falls back (success=False) to the
+        gateway's text-intercept flow when the prompt lane is unavailable.
+        """
+        options = [
+            {"id": "once", "label": "✅ Approve Once", "style": "success"},
+            {"id": "always", "label": "🔒 Always Approve", "style": "primary"},
+            {"id": "cancel", "label": "❌ Cancel", "style": "danger"},
+        ]
+        text = f"**{title}**\n\n{message}" if title else message
+        prompt_id = self._mint_prompt(
+            "slash_confirm",
+            {
+                "session_key": session_key,
+                "confirm_id": confirm_id,
+                "chat_id": str(chat_id),
+            },
+        )
+        result = await self._send_prompt(
+            chat_id,
+            prompt_kind="approval",
+            text=text,
+            prompt_id=prompt_id,
+            options=options,
+            metadata=metadata,
+        )
+        if result is not None:
+            return result
+        self._pending_prompts.pop(prompt_id, None)
+        return SendResult(success=False, error="relay prompt op unavailable")
+
+    async def send_clarify(
+        self,
+        chat_id: str,
+        question: str,
+        choices: Optional[list],
+        clarify_id: str,
+        session_key: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Native-button clarify over the relay (Phase 3).
+
+        Multiple-choice clarifies render as a `prompt` op (one button per
+        choice + Other). A press resolves via
+        tools.clarify_gateway.resolve_gateway_clarify with the CHOICE TEXT
+        (never the option id); "Other" flips the clarify to text-capture
+        exactly like the native adapters. Open-ended clarifies and
+        unavailable lanes fall back to the base numbered-text behaviour.
+
+        Option ids are positional (c0..cN / other) — choice text can be
+        arbitrary UTF-8 and would blow the 64-byte callback budget; the
+        registry maps ids back to the real strings on the answer.
+        """
+        if choices and self.descriptor.supports_op("prompt"):
+            options = [
+                {"id": f"c{i}", "label": str(choice)[:75]}
+                for i, choice in enumerate(choices)
+            ]
+            options.append({"id": "other", "label": "✏️ Other (type your answer)"})
+            prompt_id = self._mint_prompt(
+                "clarify",
+                {
+                    "session_key": session_key,
+                    "clarify_id": clarify_id,
+                    "choices": [str(c) for c in choices],
+                    "chat_id": str(chat_id),
+                },
+            )
+            result = await self._send_prompt(
+                chat_id,
+                prompt_kind="clarify",
+                text=f"❓ {question}",
+                prompt_id=prompt_id,
+                options=options,
+                metadata=metadata,
+            )
+            if result is not None:
+                return result
+            self._pending_prompts.pop(prompt_id, None)
+        return await super().send_clarify(
+            chat_id, question, choices, clarify_id, session_key, metadata=metadata
+        )
+
+    async def _consume_prompt_response(self, event) -> bool:
+        """Route an inbound prompt_response to its waiting primitive.
+
+        Returns True when the event was a prompt answer (consumed — do NOT
+        dispatch it as a chat message), False otherwise. Unknown/expired
+        prompt ids fall through to normal dispatch: the command-shaped text
+        ("/once", "/deny", …) then behaves like a typed reply, which the
+        approval/confirm text lanes already understand — the same stale-tap
+        degradation the native adapters implement with an "expired" edit.
+        """
+        pr = getattr(event, "prompt_response", None)
+        if not isinstance(pr, dict):
+            return False
+        prompt_id = str(pr.get("prompt_id") or "")
+        option_id = str(pr.get("option_id") or "")
+        if not prompt_id or not option_id:
+            return False
+        state = self._pop_prompt(prompt_id)
+        if state is None:
+            logger.info(
+                "relay prompt_response for unknown/expired prompt %s (option=%s) — "
+                "falling through to text dispatch",
+                prompt_id,
+                option_id,
+            )
+            return False
+
+        kind = state.get("kind")
+        chat_id = str(state.get("chat_id") or getattr(event.source, "chat_id", ""))
+        session_key = str(state.get("session_key") or "")
+        try:
+            if kind == "exec_approval":
+                from tools.approval import resolve_gateway_approval
+
+                choice = option_id if option_id in {"once", "session", "always", "deny"} else "deny"
+                count = resolve_gateway_approval(session_key, choice)
+                label = {
+                    "once": "✅ Approved once",
+                    "session": "✅ Approved for session",
+                    "always": "✅ Approved permanently",
+                    "deny": "❌ Denied",
+                }.get(choice, "Resolved")
+                if not count:
+                    label = "⌛ Approval expired — no command was waiting."
+                # Acknowledge in-channel (the connector's prompt message can't
+                # be edited cross-platform yet — edit support varies; a short
+                # confirmation preserves the audit trail the native edit gives).
+                await self.send(chat_id, label, metadata=self._prompt_reply_metadata(event))
+                if count:
+                    self.resume_typing_for_chat(chat_id)
+            elif kind == "slash_confirm":
+                from tools import slash_confirm as slash_confirm_mod
+
+                choice = option_id if option_id in {"once", "always", "cancel"} else "cancel"
+                result_text = await slash_confirm_mod.resolve(
+                    session_key, str(state.get("confirm_id") or ""), choice
+                )
+                label = {
+                    "once": "✅ Approved once",
+                    "always": "🔒 Always approve",
+                    "cancel": "❌ Cancelled",
+                }.get(choice, "Resolved")
+                await self.send(chat_id, label, metadata=self._prompt_reply_metadata(event))
+                if result_text:
+                    await self.send(
+                        chat_id, str(result_text), metadata=self._prompt_reply_metadata(event)
+                    )
+            elif kind == "clarify":
+                from tools.clarify_gateway import mark_awaiting_text, resolve_gateway_clarify
+
+                clarify_id = str(state.get("clarify_id") or "")
+                if option_id == "other":
+                    mark_awaiting_text(clarify_id)
+                    await self.send(
+                        chat_id,
+                        "✏️ Type your answer:",
+                        metadata=self._prompt_reply_metadata(event),
+                    )
+                else:
+                    choices = state.get("choices") or []
+                    try:
+                        idx = int(option_id[1:]) if option_id.startswith("c") else -1
+                    except ValueError:
+                        idx = -1
+                    if 0 <= idx < len(choices):
+                        resolve_gateway_clarify(clarify_id, str(choices[idx]))
+                        await self.send(
+                            chat_id,
+                            f"✅ {choices[idx]}",
+                            metadata=self._prompt_reply_metadata(event),
+                        )
+                    else:
+                        # Unmappable option: flip to text capture so the user
+                        # can answer by typing (never dead-end a clarify).
+                        mark_awaiting_text(clarify_id)
+            else:
+                logger.warning("relay prompt_response with unknown kind %r", kind)
+        except Exception:  # noqa: BLE001 - a resolver failure must not kill the reader
+            logger.warning("relay prompt_response resolution failed", exc_info=True)
+        return True
+
+    def _prompt_reply_metadata(self, event) -> Dict[str, Any]:
+        """Thread/topic metadata so prompt acks land where the prompt lives."""
+        meta: Dict[str, Any] = {}
+        thread_id = getattr(event.source, "thread_id", None)
+        if thread_id:
+            meta["thread_id"] = str(thread_id)
+        return meta
+
+    # ── Phase 3 ack lifecycle (👀 → ✅/❌) ────────────────────────────────
+
+    async def _react(
+        self,
+        chat_id: str,
+        message_id: str,
+        emoji: str,
+        *,
+        remove: bool = False,
+    ) -> bool:
+        """Egress one `react` op; best-effort (False on any failure).
+
+        Reactions are cosmetic by contract: a failure is logged at debug and
+        never surfaces to the caller's flow (mirrors the native Discord
+        adapter's _add_reaction posture).
+        """
+        if self._transport is None or not self.descriptor.supports_op("react"):
+            return False
+        if not chat_id or not message_id:
+            return False
+        try:
+            result = await self._transport.send_outbound(
+                {
+                    "op": "react",
+                    "chat_id": chat_id,
+                    "message_id": message_id,
+                    "emoji": emoji,
+                    "remove": remove,
+                    "metadata": self._with_scope(chat_id, None),
+                },
+                platform=self._platform_by_chat.get(str(chat_id)),
+            )
+            return bool(result.get("success"))
+        except Exception:  # noqa: BLE001 - reactions are cosmetic
+            logger.debug("relay react failed", exc_info=True)
+            return False
+
+    async def on_processing_start(self, event) -> None:
+        """Add the 👀 in-progress reaction (op-gated; silent no-op otherwise)."""
+        message_id = getattr(event, "message_id", None) or getattr(
+            event.source, "message_id", None
+        )
+        chat_id = getattr(event.source, "chat_id", None)
+        if message_id and chat_id:
+            await self._react(str(chat_id), str(message_id), "👀")
+
+    async def on_processing_complete(self, event, outcome) -> None:
+        """Swap 👀 for ✅/❌ per outcome (op-gated; silent no-op otherwise)."""
+        from gateway.platforms.base import ProcessingOutcome
+
+        message_id = getattr(event, "message_id", None) or getattr(
+            event.source, "message_id", None
+        )
+        chat_id = getattr(event.source, "chat_id", None)
+        if not (message_id and chat_id):
+            return
+        await self._react(str(chat_id), str(message_id), "👀", remove=True)
+        if outcome == ProcessingOutcome.SUCCESS:
+            await self._react(str(chat_id), str(message_id), "✅")
+        elif outcome == ProcessingOutcome.FAILURE:
+            await self._react(str(chat_id), str(message_id), "❌")
+
+    # ── Phase 4 thread lifecycle ──────────────────────────────────────────
+
+    async def create_handoff_thread(
+        self,
+        parent_chat_id: str,
+        name: str,
+    ) -> Optional[str]:
+        """Create a thread/topic under ``parent_chat_id`` via the connector.
+
+        One `thread_create` op covers Discord (channel thread), Telegram
+        (forum topic), and Slack (named seed root message — threads there are
+        message-anchored). Op-gated on the descriptor advertising
+        `thread_create`; None on any failure/unavailability so the handoff
+        watcher falls back to the parent channel — the same contract as the
+        native adapters' create_handoff_thread.
+        """
+        if self._transport is None or not self.descriptor.supports_op("thread_create"):
+            return None
+        thread_name = (str(name or "").strip() or "handoff")[:100]
+        try:
+            result = await self._transport.send_outbound(
+                {
+                    "op": "thread_create",
+                    "chat_id": str(parent_chat_id),
+                    "thread_name": thread_name,
+                    "metadata": self._with_scope(str(parent_chat_id), None),
+                },
+                platform=self._platform_by_chat.get(str(parent_chat_id)),
+            )
+        except Exception:  # noqa: BLE001 - handoff falls back to the parent channel
+            logger.debug("relay thread_create transport failure", exc_info=True)
+            return None
+        if not result.get("success"):
+            logger.info(
+                "relay thread_create declined for %s: %s",
+                parent_chat_id,
+                result.get("error"),
+            )
+            return None
+        thread_id = result.get("thread_id") or result.get("message_id")
+        return str(thread_id) if thread_id else None
+
+    async def rename_thread(
+        self,
+        thread_id: str,
+        name: str,
+        *,
+        only_if_current_name: Optional[str] = None,
+        parent_chat_id: Optional[str] = None,
+    ) -> bool:
+        """Best-effort thread rename via the connector's `thread_rename` op.
+
+        The relay sibling of the native Discord adapter's rename_thread —
+        called by the SAME semantic-rename lane (run.py
+        _rename_discord_auto_thread_for_session_title), which fires only for
+        sources carrying the connector-stamped auto-thread markers.
+        ``only_if_current_name`` crosses the wire; the CONNECTOR enforces the
+        no-clobber guard (it owns the platform read), failing safe on
+        platforms that can't read the current name. ``parent_chat_id`` is
+        the containing chat where the caller knows it (Telegram needs it);
+        defaults to the thread id itself (Discord ignores chat_id).
+        """
+        if self._transport is None or not self.descriptor.supports_op("thread_rename"):
+            return False
+        cleaned = " ".join(str(name or "").split()).strip()
+        if not cleaned or not thread_id:
+            return False
+        chat_id = str(parent_chat_id or thread_id)
+        action: Dict[str, Any] = {
+            "op": "thread_rename",
+            "chat_id": chat_id,
+            "message_id": str(thread_id),
+            "thread_name": cleaned[:100],
+            "metadata": self._with_scope(chat_id, None),
+        }
+        if only_if_current_name is not None:
+            action["only_if_current_name"] = str(only_if_current_name)
+        try:
+            result = await self._transport.send_outbound(
+                action,
+                platform=self._platform_by_chat.get(chat_id)
+                or self._platform_by_chat.get(str(thread_id)),
+            )
+        except Exception:  # noqa: BLE001 - renames are cosmetic
+            logger.debug("relay thread_rename transport failure", exc_info=True)
+            return False
+        if not result.get("success"):
+            logger.info(
+                "relay thread_rename declined for %s: %s",
+                thread_id,
+                result.get("error"),
+            )
+            return False
+        return True
diff --git a/gateway/relay/command_manifest.py b/gateway/relay/command_manifest.py
new file mode 100644
index 00000000000..36d7a8fcd78
--- /dev/null
+++ b/gateway/relay/command_manifest.py
@@ -0,0 +1,145 @@
+"""Gateway-declared slash-command manifest for the relay lane (Phase 4).
+
+The native Discord adapter registers its slash commands directly on the
+Discord command tree (`_register_slash_commands`,
+plugins/platforms/discord/adapter.py) — it holds the bot token. Over the
+relay the CONNECTOR holds the token, so the gateway DECLARES the same
+command set on its `hello` frame (`command_manifest`) and the connector
+reconciles Discord's global application-command registration against it
+(gateway-gateway `DiscordCommandRegistrar`: GET → diff → bulk PUT,
+idempotent, best-effort).
+
+This module is that declaration: the single source of truth for what the
+relay lane advertises. It MIRRORS the native tree — same names, same
+descriptions — so a user moving between a native-Discord deployment and a
+hosted/relay one sees the same command palette. Interactions come back over
+the passthrough plane and are normalized by
+RelayAdapter._discord_interaction_to_event into the same "/name args"
+COMMAND events the dispatcher already routes, so declaring a command here
+requires NO new handler — the dispatcher's existing slash surface is the
+handler.
+
+Wire shape (per entry): {name, description, options?} where options rows are
+Discord option objects passed through verbatim. Names must satisfy
+Discord's CHAT_INPUT rules ([a-z0-9_-]{1,32}); the connector drops invalid
+entries (fail-open per entry, never the whole manifest).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+# Discord option type 3 = STRING.
+_STR = 3
+
+
+def _opt(name: str, description: str, *, choices: List[str] | None = None) -> Dict[str, Any]:
+    row: Dict[str, Any] = {
+        "type": _STR,
+        "name": name,
+        "description": description,
+        "required": False,
+    }
+    if choices:
+        row["choices"] = [{"name": c, "value": c} for c in choices]
+    return row
+
+
+def build_relay_command_manifest() -> List[Dict[str, Any]]:
+    """The relay lane's Discord slash-command manifest (native-tree mirror)."""
+    return [
+        {"name": "new", "description": "Start a new conversation"},
+        {"name": "reset", "description": "Reset your Hermes session"},
+        {
+            "name": "model",
+            "description": "Show or change the model",
+            "options": [_opt("name", "Model name. Leave empty to see current.")],
+        },
+        {
+            "name": "reasoning",
+            "description": "Show/change reasoning effort, or toggle showing it",
+            "options": [
+                _opt(
+                    "effort",
+                    "Level, reset, or show/hide. Leave empty to see current.",
+                    choices=[
+                        "none",
+                        "minimal",
+                        "low",
+                        "medium",
+                        "high",
+                        "xhigh",
+                        "max",
+                        "ultra",
+                        "reset",
+                        "show",
+                        "hide",
+                    ],
+                )
+            ],
+        },
+        {
+            "name": "personality",
+            "description": "Set a personality",
+            "options": [_opt("name", "Personality name. Leave empty to list.")],
+        },
+        {"name": "retry", "description": "Retry your last message"},
+        {"name": "undo", "description": "Remove the last exchange"},
+        {"name": "status", "description": "Show Hermes session status"},
+        {"name": "sethome", "description": "Set this chat as the home channel"},
+        {"name": "stop", "description": "Stop the running Hermes agent"},
+        {
+            "name": "steer",
+            "description": "Inject a message after the next tool call (no interrupt)",
+            "options": [_opt("text", "What to tell the agent")],
+        },
+        {"name": "compress", "description": "Compress conversation context"},
+        {
+            "name": "title",
+            "description": "Set or show the session title",
+            "options": [_opt("text", "New title. Leave empty to show.")],
+        },
+        {
+            "name": "resume",
+            "description": "Resume a previously-named session",
+            "options": [_opt("name", "Session title or id")],
+        },
+        {"name": "usage", "description": "Show token usage for this session"},
+        {"name": "help", "description": "Show available commands"},
+        {"name": "insights", "description": "Show usage insights and analytics"},
+        {"name": "reload-mcp", "description": "Reload MCP servers from config"},
+        {
+            "name": "reload-skills",
+            "description": "Re-scan skills for new or removed entries",
+        },
+        {"name": "voice", "description": "Toggle voice reply mode"},
+        {"name": "update", "description": "Update Hermes Agent to the latest version"},
+        {"name": "restart", "description": "Gracefully restart the Hermes gateway"},
+        {
+            "name": "approve",
+            "description": "Approve a pending dangerous command",
+            "options": [
+                _opt("scope", "Approval scope", choices=["once", "session", "always", "all"])
+            ],
+        },
+        {
+            "name": "deny",
+            "description": "Deny a pending dangerous command",
+            "options": [_opt("reason", "Why (relayed to the agent)")],
+        },
+        {
+            "name": "thread",
+            "description": "Create a new thread and start a Hermes session in it",
+            "options": [_opt("name", "Thread name")],
+        },
+        {
+            "name": "queue",
+            "description": "Queue a prompt for the next turn (doesn't interrupt)",
+            "options": [_opt("text", "The prompt to queue")],
+        },
+        {
+            "name": "background",
+            "description": "Run a prompt in the background",
+            "options": [_opt("text", "The prompt to run")],
+        },
+    ]
diff --git a/gateway/relay/descriptor.py b/gateway/relay/descriptor.py
index 6645a08563f..4963d428b73 100644
--- a/gateway/relay/descriptor.py
+++ b/gateway/relay/descriptor.py
@@ -64,6 +64,32 @@ class CapabilityDescriptor:
     # "no context" — additive within contract_version 1. from_json filters
     # unknown keys, so a connector sending this to an older gateway is safe too.
     supports_context: bool = False
+    # Op-level capability discovery (Phase 1 parity): the outbound op names the
+    # connector's sender for this platform actually implements (e.g.
+    # ["send", "edit", "typing", "follow_up", "get_chat_info"]). Empty tuple =
+    # the connector predates the field; callers MUST treat that as "legacy op
+    # set" (send/edit/typing/follow_up) rather than "nothing supported", so an
+    # old connector keeps working unchanged. Additive within contract_version 1.
+    # Stored as a tuple so the frozen dataclass stays hashable/immutable.
+    supported_ops: tuple = ()
+
+    # The op set every connector supported before ``supported_ops`` existed.
+    # Used as the assumed capability set when a legacy connector sends no list.
+    LEGACY_OPS = ("send", "edit", "typing", "follow_up")
+
+    def supports_op(self, op: str) -> bool:
+        """Whether the connector advertises the outbound op ``op``.
+
+        Fail-open for legacy connectors: an empty ``supported_ops`` means the
+        connector predates op discovery, so assume the legacy op set (the four
+        ops every connector implemented before the field existed). A NEW op
+        (e.g. ``get_chat_info``) is therefore only True when explicitly
+        advertised — exactly the discovery semantics Phase 1 needs: the gateway
+        can probe capability without trying the op and parsing an error.
+        """
+        if not self.supported_ops:
+            return op in self.LEGACY_OPS
+        return op in self.supported_ops
 
     def to_json(self) -> str:
         """Serialize to a compact, stable JSON string for the handshake frame."""
@@ -93,6 +119,19 @@ class CapabilityDescriptor:
                     filtered["max_message_length"] = 4096
             except (TypeError, ValueError):
                 filtered["max_message_length"] = 4096
+        # Normalize supported_ops at the trust boundary: JSON carries a list;
+        # the frozen dataclass stores a tuple. Non-list/malformed values (or a
+        # list holding non-strings) degrade to () — the legacy-op-set fallback —
+        # rather than raising, matching the "malformed input never breaks the
+        # handshake" posture above.
+        if "supported_ops" in filtered:
+            raw_ops = filtered["supported_ops"]
+            if isinstance(raw_ops, (list, tuple)):
+                filtered["supported_ops"] = tuple(
+                    str(op) for op in raw_ops if isinstance(op, str) and op
+                )
+            else:
+                filtered["supported_ops"] = ()
         return cls(**filtered)
 
     @classmethod
diff --git a/gateway/relay/media.py b/gateway/relay/media.py
new file mode 100644
index 00000000000..32da5490ef0
--- /dev/null
+++ b/gateway/relay/media.py
@@ -0,0 +1,205 @@
+"""Relay media client — gateway↔connector media plane (Phase 2). EXPERIMENTAL.
+
+The relay wire contract carries media BY REFERENCE, never by value: an inbound
+event's ``media_urls`` name connector re-hosted attachments
+(``{connector}/relay/media/{id}``), and an outbound ``send_media`` op names a
+``source_url`` the connector resolves back to bytes. This module is the
+gateway-side HTTP client for that plane:
+
+  - ``download(url)``  → GET a re-hosted attachment to a local temp file (the
+    agent's vision/file tools consume LOCAL paths, matching every native
+    adapter's inbound media behaviour).
+  - ``upload(path)``   → POST local file bytes to ``/relay/media``; returns the
+    ``/relay/media/{id}`` reference for a subsequent ``send_media`` op. This is
+    how a locally-generated artifact (image_generate output, TTS voice note,
+    a document) crosses to the connector WITHOUT the gateway needing a public
+    URL.
+
+Both requests present the SAME per-gateway signed bearer the WS upgrade uses
+(``make_upgrade_token``, gateway/relay/auth.py — the channel authenticator; the
+connector authenticates it with ``authenticateGatewayBearer`` on the mirrored
+routes). Uploads are
+per-gateway-owned on the connector (only this gateway can reference the id
+back); downloads accept both this gateway's uploads and connector ingest
+re-hosts.
+
+Transport is stdlib ``urllib`` run in a thread executor (the same dependency
+posture as ``_post_provision`` — the relay lane adds no HTTP client deps).
+EXPERIMENTAL: may change without a deprecation cycle (docs/relay-connector-contract.md).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import mimetypes
+import os
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+from gateway.relay.auth import make_upgrade_token
+
+logger = logging.getLogger(__name__)
+
+# Mirror the connector's MEDIA_MAX_BYTES (mediaStore.ts) so an oversized local
+# artifact fails fast here instead of round-tripping to a connector 413.
+MEDIA_MAX_BYTES = 25 * 1024 * 1024
+
+_REQUEST_TIMEOUT_S = 30.0
+
+
+def media_base_url(relay_dial_url: str) -> str:
+    """Map the ``ws(s)://…/relay`` dial URL to the ``http(s)://…`` base.
+
+    Same host derivation as ``_provision_url`` (gateway/relay/__init__.py):
+    scheme ws→http / wss→https, trailing ``/relay`` stripped.
+    """
+    raw = (relay_dial_url or "").strip().rstrip("/")
+    if raw.startswith("ws://"):
+        raw = "http://" + raw[len("ws://") :]
+    elif raw.startswith("wss://"):
+        raw = "https://" + raw[len("wss://") :]
+    if raw.endswith("/relay"):
+        raw = raw[: -len("/relay")]
+    return raw
+
+
+class RelayMediaClient:
+    """Authenticated client for the connector's ``/relay/media`` routes."""
+
+    def __init__(
+        self,
+        base_url: str,
+        gateway_id: Optional[str],
+        secret: Optional[str],
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._gateway_id = gateway_id or ""
+        self._secret = secret or ""
+
+    @property
+    def enabled(self) -> bool:
+        """True when the client can authenticate (per-gateway creds present)."""
+        return bool(self._base_url and self._gateway_id and self._secret)
+
+    def _bearer(self) -> str:
+        return make_upgrade_token(self._gateway_id, self._secret)
+
+    def is_relay_media_url(self, url: str) -> bool:
+        """Is ``url`` a connector re-host reference (needs our bearer to GET)?"""
+        return "/relay/media/" in (url or "")
+
+    async def upload(
+        self,
+        file_path: str,
+        *,
+        mime: Optional[str] = None,
+        filename: Optional[str] = None,
+    ) -> Optional[str]:
+        """POST local file bytes to ``/relay/media``; return the reference URL.
+
+        Returns the ``{base}/relay/media/{id}`` reference for a ``send_media``
+        op's ``source_url``, or None on any failure (callers fall back to their
+        pre-media behaviour — media delivery is best-effort by design).
+        """
+        if not self.enabled:
+            return None
+        path = Path(file_path)
+        try:
+            data = path.read_bytes()
+        except OSError:
+            logger.warning("relay media upload: cannot read %s", file_path)
+            return None
+        if not data or len(data) > MEDIA_MAX_BYTES:
+            logger.warning(
+                "relay media upload: %s size %d outside (0, %d]",
+                file_path,
+                len(data),
+                MEDIA_MAX_BYTES,
+            )
+            return None
+        content_type = (
+            mime
+            or mimetypes.guess_type(filename or path.name)[0]
+            or "application/octet-stream"
+        )
+        headers = {
+            "Authorization": f"Bearer {self._bearer()}",
+            "Content-Type": content_type,
+            "X-Media-Filename": (filename or path.name)[:255],
+        }
+        url = f"{self._base_url}/relay/media"
+
+        def _post() -> Optional[str]:
+            req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+            try:
+                with urllib.request.urlopen(req, timeout=_REQUEST_TIMEOUT_S) as resp:
+                    import json
+
+                    body = json.loads(resp.read().decode("utf-8"))
+                    media_id = body.get("id")
+                    if not media_id:
+                        return None
+                    return f"{self._base_url}/relay/media/{media_id}"
+            except (urllib.error.URLError, ValueError, OSError) as exc:
+                logger.warning("relay media upload failed: %s", exc)
+                return None
+
+        return await asyncio.get_running_loop().run_in_executor(None, _post)
+
+    async def download(self, url: str, *, suggested_name: Optional[str] = None) -> Optional[str]:
+        """GET a re-hosted attachment to a local temp file; return its path.
+
+        Presents the per-gateway bearer for connector re-host URLs; plain
+        public URLs (e.g. a Discord CDN pass-through) are fetched without it.
+        Returns None on any failure (the event then keeps the remote URL, and
+        downstream consumers that need a local file skip it — best-effort).
+        """
+        if not url:
+            return None
+        needs_auth = self.is_relay_media_url(url)
+        if needs_auth and not self.enabled:
+            return None
+        headers = {}
+        if needs_auth:
+            headers["Authorization"] = f"Bearer {self._bearer()}"
+
+        def _get() -> Optional[str]:
+            req = urllib.request.Request(url, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=_REQUEST_TIMEOUT_S) as resp:
+                    length = int(resp.headers.get("Content-Length") or 0)
+                    if length > MEDIA_MAX_BYTES:
+                        logger.warning("relay media download too large: %s", url)
+                        return None
+                    data = resp.read(MEDIA_MAX_BYTES + 1)
+                    if not data or len(data) > MEDIA_MAX_BYTES:
+                        return None
+                    # Extension: prefer the response's content-disposition /
+                    # suggested name, fall back to the mime type, then .bin —
+                    # vision/file tools sniff by extension.
+                    name = suggested_name or ""
+                    if not name:
+                        cd = resp.headers.get("Content-Disposition") or ""
+                        if "filename=" in cd:
+                            name = cd.split("filename=", 1)[1].strip().strip('"')
+                    ext = Path(name).suffix if name else ""
+                    if not ext:
+                        mime = (resp.headers.get("Content-Type") or "").split(";")[0]
+                        ext = mimetypes.guess_extension(mime) or ".bin"
+                    fd, tmp_path = tempfile.mkstemp(prefix="relay_media_", suffix=ext)
+                    with os.fdopen(fd, "wb") as fh:
+                        fh.write(data)
+                    return tmp_path
+            except (urllib.error.URLError, ValueError, OSError) as exc:
+                logger.warning("relay media download failed for %s: %s", url, exc)
+                return None
+
+        return await asyncio.get_running_loop().run_in_executor(None, _get)
+
+
+__all__ = ["RelayMediaClient", "media_base_url", "MEDIA_MAX_BYTES"]
diff --git a/gateway/relay/ws_transport.py b/gateway/relay/ws_transport.py
index aaba3ee1252..62fe683c8fc 100644
--- a/gateway/relay/ws_transport.py
+++ b/gateway/relay/ws_transport.py
@@ -186,7 +186,17 @@ def _event_from_wire(raw: Dict[str, Any]) -> MessageEvent:
         chat_type=src.get("chat_type", "dm"),
         chat_name=src.get("chat_name"),
         user_id=src.get("user_id"),
-        user_name=src.get("user_name"),
+        # Native adapters surface the human-facing DISPLAY name as user_name
+        # (e.g. Discord `message.author.display_name`); the connector sends the
+        # raw platform username as user_name plus optional user_display_name /
+        # user_handle enrichments (contract §3). Prefer the display name for
+        # parity with native lanes — session keys derive from user_id, never
+        # user_name, so this is presentation-only and key-stable.
+        user_name=(
+            src.get("user_display_name")
+            or src.get("user_name")
+            or src.get("user_handle")
+        ),
         thread_id=src.get("thread_id"),
         chat_topic=src.get("chat_topic"),
         user_id_alt=src.get("user_id_alt"),
@@ -203,6 +213,12 @@ def _event_from_wire(raw: Dict[str, Any]) -> MessageEvent:
         # config/credential scope — the same field the /p/<profile>/ HTTP
         # prefix and per-credential polling adapters already set.
         profile=src.get("profile"),
+        # Auto-thread markers (Phase 4): stamped by the CONNECTOR when this
+        # event's thread was auto-created by its auto-thread egress policy.
+        # Lights the SAME semantic-rename lane native Discord uses
+        # (_is_discord_auto_thread_lane's relay-aware sibling reads these).
+        auto_thread_created=bool(src.get("auto_thread_created", False)),
+        auto_thread_initial_name=src.get("auto_thread_initial_name"),
         # Authentic upstream-trust signal: this event arrived over the
         # per-instance-authenticated relay WS, so the connector already resolved
         # it to this instance's owner-bound author. ``platform`` is the
@@ -231,6 +247,14 @@ def _event_from_wire(raw: Dict[str, Any]) -> MessageEvent:
         source=source,
         message_id=raw.get("message_id"),
         reply_to_message_id=raw.get("reply_to_message_id"),
+        # Richer quoted-reply context (Phase 4): what the user replied TO,
+        # when the connector had it in hand (Discord referenced_message,
+        # Telegram reply_to_message, WhatsApp context + text cache). Maps to
+        # the SAME MessageEvent fields native adapters populate, so run.py's
+        # reply-context injection works identically over the relay.
+        reply_to_text=(raw.get("reply_to") or {}).get("text"),
+        reply_to_author_name=(raw.get("reply_to") or {}).get("author"),
+        reply_to_is_own_message=bool((raw.get("reply_to") or {}).get("is_own", False)),
         media_urls=raw.get("media_urls") or [],
         # Surrounding channel/group CONTEXT the connector attached for this
         # addressed turn (design relay-channel-context): a read-only, oldest→
@@ -241,6 +265,16 @@ def _event_from_wire(raw: Dict[str, Any]) -> MessageEvent:
         # connector that doesn't send it, a dm, or a no-context platform, so
         # this is purely additive and byte-identical to today when unset.
         channel_context=_render_relay_context(raw.get("context")),
+        # Structured interactive-prompt reply (Phase 3): carried verbatim off
+        # the wire when present ({prompt_id, option_id, label?,
+        # prompt_message_id?}). The RelayAdapter's inbound bridge consumes it
+        # to resolve pending approvals/confirms/clarifies; a gateway that
+        # predates the resolvers just sees the command-shaped text.
+        prompt_response=(
+            dict(raw["prompt_response"])
+            if isinstance(raw.get("prompt_response"), dict)
+            else None
+        ),
     )
 
 
@@ -417,7 +451,20 @@ class WebSocketRelayTransport:
         # sends exactly one hello — byte-identical to before. The descriptor for
         # the FIRST identity resolves handshake(); later descriptors are absorbed.
         for platform, bot_id in self._identities:
-            await self._send({"type": "hello", "platform": platform, "botId": bot_id})
+            hello: Dict[str, Any] = {"type": "hello", "platform": platform, "botId": bot_id}
+            # Phase 4: declare the gateway's slash-command set on the Discord
+            # hello. The connector (which holds the bot token) reconciles
+            # Discord's global registration against it — idempotent, detached,
+            # best-effort on its side; a connector predating the field ignores
+            # it (additive). Only Discord has an app-command registry.
+            if platform == "discord":
+                try:
+                    from gateway.relay.command_manifest import build_relay_command_manifest
+
+                    hello["command_manifest"] = build_relay_command_manifest()
+                except Exception:  # noqa: BLE001 - manifest is enrichment, never blocks the handshake
+                    logger.debug("relay command manifest build failed", exc_info=True)
+            await self._send(hello)
 
     def _upgrade_headers(self) -> Dict[str, str]:
         """Auth headers for the WS upgrade, or {} when no secret is configured.
diff --git a/gateway/run.py b/gateway/run.py
index 01057ec3159..6b2ae447e5b 100644
--- a/gateway/run.py
+++ b/gateway/run.py
@@ -27,6 +27,7 @@ except ModuleNotFoundError:
 import asyncio
 import concurrent.futures
 import dataclasses
+import faulthandler
 import inspect
 import json
 import logging
@@ -54,6 +55,16 @@ from typing import Awaitable, Callable, Dict, Optional, Any, List, Union, cast
 # preserving the established test-patch surface.
 from agent.account_usage import fetch_account_usage, render_account_usage_lines
 from agent.async_utils import consume_detached_task_result, safe_schedule_threadsafe
+from agent.conversation_compression import (
+    COMPACTION_STATUS,
+    COMPRESSION_RETRY_CONTEXT_REDUCED_STATUS_TEMPLATE,
+    COMPRESSION_RETRY_MESSAGES_STATUS_TEMPLATE,
+    COMPRESSION_RETRY_TOKENS_STATUS_TEMPLATE,
+    COMPRESSION_RETRY_TOO_LARGE_STATUS_TEMPLATE,
+    IDLE_COMPACTION_STATUS_TEMPLATE,
+    PRE_API_COMPRESSION_STATUS_TEMPLATE,
+    PREFLIGHT_COMPRESSION_STATUS_TEMPLATE,
+)
 from agent.conversation_loop import INTERRUPT_WAITING_FOR_MODEL_PREFIX
 from agent.i18n import t
 from hermes_cli.config import cfg_get
@@ -67,6 +78,10 @@ from hermes_cli.fallback_config import get_fallback_chain
 _AGENT_CACHE_MAX_SIZE = 128
 _AGENT_CACHE_IDLE_TTL_SECS = 3600.0  # evict agents idle for >1h
 _PLATFORM_CONNECT_TIMEOUT_SECS_DEFAULT = 30.0
+# Telegram cold polling now proves one real getUpdates round trip before connect
+# returns. Leave enough outer budget for initialize/deleteWebhook/start_polling
+# wall deadlines plus readiness; other platforms retain the 30s isolation bound.
+_TELEGRAM_CONNECT_TIMEOUT_SECS_DEFAULT = 180.0
 _ADAPTER_DISCONNECT_TIMEOUT_SECS_DEFAULT = 5.0
 _GATEWAY_PROXY_SSE_BUFFER_MAX_CHARS = 16 * 1024 * 1024
 _TELEGRAM_COMMAND_MENTION_RE = re.compile(r"(?<![\w:/])/([A-Za-z0-9][A-Za-z0-9_-]*)")
@@ -106,6 +121,70 @@ _TELEGRAM_NOISY_STATUS_RE = re.compile(
     re.IGNORECASE | re.DOTALL,
 )
 
+
+def _status_template_to_regex(template: str) -> str:
+    """Compile a compression status template constant into a regex source.
+
+    Literal text is escaped verbatim (so wording drift in
+    agent/conversation_compression.py cannot silently diverge from this
+    matcher — the constants ARE the wording) and each ``{field}`` format
+    placeholder is replaced with a numeric-ish pattern covering every value
+    the emit sites format in (ints, ``{:,}`` thousands separators).
+    """
+    parts = re.split(r"\{[^{}]*\}", template)
+    return r"[\d,]+".join(re.escape(part) for part in parts)
+
+
+# ROUTINE compression progress statuses, derived from the SAME template
+# constants the emit sites format (agent/conversation_compression.py, #69550)
+# — never re-inlined wording. Used ONLY by the opt-in
+# ``compression.progress_notices`` gate below (#52995) to decide which of the
+# noisy statuses matched by _TELEGRAM_NOISY_STATUS_RE are compression
+# progress (deliverable when the user opted in) versus unrelated aux/retry
+# chatter (always suppressed on chat surfaces). Failure notices and manual
+# /compress feedback never match _TELEGRAM_NOISY_STATUS_RE in the first
+# place, so they are unaffected by this gate.
+_COMPRESSION_PROGRESS_STATUS_RE = re.compile(
+    "|".join(
+        _status_template_to_regex(_template)
+        for _template in (
+            COMPACTION_STATUS,
+            PRE_API_COMPRESSION_STATUS_TEMPLATE,
+            PREFLIGHT_COMPRESSION_STATUS_TEMPLATE,
+            IDLE_COMPACTION_STATUS_TEMPLATE,
+            COMPRESSION_RETRY_TOO_LARGE_STATUS_TEMPLATE,
+            COMPRESSION_RETRY_MESSAGES_STATUS_TEMPLATE,
+            COMPRESSION_RETRY_TOKENS_STATUS_TEMPLATE,
+            COMPRESSION_RETRY_CONTEXT_REDUCED_STATUS_TEMPLATE,
+        )
+    ),
+    re.IGNORECASE,
+)
+
+
+def _gateway_compression_progress_notices_enabled() -> bool:
+    """True when the user opted into routine compression progress notices.
+
+    Reads ``compression.progress_notices`` from the gateway's raw YAML config
+    (#52995). Default False — routine compression stays silent-by-design on
+    chat platforms unless explicitly enabled. Read live (mtime-cached) so a
+    config edit on a running gateway takes effect on the next status.
+    Fail-closed: any config read error keeps the silent default.
+    """
+    try:
+        config = _load_gateway_config()
+        compression_cfg = config.get("compression") if isinstance(config, dict) else None
+        if isinstance(compression_cfg, dict):
+            return str(compression_cfg.get("progress_notices", False)).strip().lower() in {
+                "true",
+                "1",
+                "yes",
+                "on",
+            }
+    except Exception:
+        pass
+    return False
+
 # Surfaces that consume gateway text programmatically (CLI/TUI "local"
 # diagnostics, API JSON, webhook payloads) and therefore must keep RAW
 # status/error text. EVERY other platform is a human-facing chat surface
@@ -495,7 +574,17 @@ def _prepare_gateway_status_message(platform: Any, event_type: str, message: str
 
     text = _redact_gateway_user_facing_secrets(text)
     if _TELEGRAM_NOISY_STATUS_RE.search(text):
-        return None
+        # Opt-in #52995: `compression.progress_notices: true` lets ROUTINE
+        # compression progress statuses through to chat platforms. The
+        # membership check is derived from the #69550 template constants, so
+        # non-compression noise (aux failures, provider retry chatter, ...)
+        # stays suppressed even when the gate is open. Default False keeps
+        # the silent-by-design behavior byte-identical.
+        if not (
+            _gateway_compression_progress_notices_enabled()
+            and _COMPRESSION_PROGRESS_STATUS_RE.search(text)
+        ):
+            return None
     if _looks_like_gateway_provider_error(text):
         return _gateway_provider_error_reply(text)
     return text
@@ -2024,7 +2113,11 @@ from gateway.session import (
     is_shared_multi_user_session,
     neutralize_untrusted_inline_text,
 )
-from gateway.delivery import DeliveryRouter, looks_like_telegram_private_chat_id
+from gateway.delivery import (
+    DeliveryRouter,
+    looks_like_telegram_private_chat_id,
+    resolve_delivery_transport,
+)
 from gateway.turn_lease import SessionTurnLeaseRegistry
 from gateway.authz_mixin import GatewayAuthorizationMixin
 from gateway.kanban_watchers import GatewayKanbanWatchersMixin
@@ -2041,9 +2134,11 @@ from gateway.platforms.base import (
 )
 from gateway.shutdown_watchdog import (
     DEFAULT_HEARTBEAT_INTERVAL_S,
+    _arm_loop_floor_timer,
     arm_shutdown_watchdog,
     loop_heartbeat_forever,
     resolve_shutdown_watchdog_delay,
+    start_loop_liveness_watchdog,
 )
 from gateway.restart import (
     DEFAULT_GATEWAY_RESTART_DRAIN_TIMEOUT,
@@ -3197,13 +3292,16 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
     _session_ephemeral_pin: Dict[str, tuple] = {}
     _session_vc_last: Dict[str, str] = {}
     _startup_restore_in_progress: bool = False
-    # Loop-liveness heartbeat / shutdown-watchdog handles (#66892). Class-level
+    # Loop-liveness heartbeat / watchdog handles (#66892, #69089). Class-level
     # defaults so partial construction in tests doesn't blow up on access; the
     # real values are set in __init__ / start() / stop().
     _loop_heartbeat_task: Optional["asyncio.Task"] = None
+    _loop_floor_timer_handle: Optional[Any] = None
+    _loop_liveness_watchdog: Optional[Any] = None
     _gateway_started_at: float = 0.0
     _shutdown_watchdog_done: Optional["threading.Event"] = None
     _platform_lock_takeover_on_start: bool = False
+    _reconnect_watcher_task: Optional["asyncio.Task"] = None
 
     def __init__(self, config: Optional[GatewayConfig] = None):
         global _gateway_runner_ref
@@ -3514,6 +3612,12 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             try:
                 from hermes_cli.config import load_config as _load_full_config
                 _sess_cfg = (_load_full_config().get("sessions") or {})
+                # Non-destructive stale-session archive, independent of prune.
+                if _sess_cfg.get("auto_archive", False):
+                    self._session_db._db.maybe_auto_archive(
+                        idle_days=float(_sess_cfg.get("auto_archive_days", 3)),
+                        min_interval_hours=int(_sess_cfg.get("min_interval_hours", 24)),
+                    )
                 if _sess_cfg.get("auto_prune", False):
                     # Construction-time, before the loop serves traffic; sync DB is fine.
                     self._session_db._db.maybe_auto_prune_and_vacuum(
@@ -3525,18 +3629,24 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             except Exception as exc:
                 logger.debug("state.db auto-maintenance skipped: %s", exc)
 
-        # Opportunistic shadow-repo cleanup — deletes orphan/stale
-        # checkpoint repos under ~/.hermes/checkpoints/.  Opt-in via
-        # checkpoints.auto_prune, idempotent via .last_prune marker.
+        # Opportunistic shadow-repo cleanup — deletes stale checkpoint repos
+        # under ~/.hermes/checkpoints/.  Opt-in via checkpoints.auto_prune,
+        # idempotent via .last_prune marker.
         try:
             from hermes_cli.config import load_config as _load_full_config
             _ckpt_cfg = (_load_full_config().get("checkpoints") or {})
             if _ckpt_cfg.get("auto_prune", False):
                 from tools.checkpoint_manager import maybe_auto_prune_checkpoints
+                # delete_orphans is intentionally never honoured here: a
+                # missing workdir at startup is ambiguous (deleted project
+                # vs. an unmounted external volume / network share / VPN
+                # not yet up) and this sweep runs unattended. Orphan cleanup
+                # is only ever done via the explicit `hermes checkpoints
+                # prune` command, which the user has to invoke.
                 maybe_auto_prune_checkpoints(
                     retention_days=int(_ckpt_cfg.get("retention_days", 7)),
                     min_interval_hours=int(_ckpt_cfg.get("min_interval_hours", 24)),
-                    delete_orphans=bool(_ckpt_cfg.get("delete_orphans", True)),
+                    delete_orphans=False,
                     max_total_size_mb=int(_ckpt_cfg.get("max_total_size_mb", 500)),
                 )
         except Exception as exc:
@@ -3571,6 +3681,8 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         # updated_at to distinguish "process alive" from "loop frozen".
         self._gateway_started_at: float = time.time()
         self._loop_heartbeat_task: Optional[asyncio.Task] = None
+        self._loop_floor_timer_handle = None
+        self._loop_liveness_watchdog = None
 
         # scale-to-zero (Phase 0, F13): gateway-scoped "last inbound seen" clock.
         # There is no such clock today (only a per-agent _last_activity_ts), so the
@@ -3684,7 +3796,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
 
     def _load_voice_modes(self) -> Dict[str, str]:
         try:
-            data = json.loads(self._VOICE_MODE_PATH.read_text())
+            data = json.loads(self._VOICE_MODE_PATH.read_text(encoding="utf-8"))
         except (FileNotFoundError, json.JSONDecodeError, OSError):
             return {}
 
@@ -3712,7 +3824,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         try:
             self._VOICE_MODE_PATH.parent.mkdir(parents=True, exist_ok=True)
             self._VOICE_MODE_PATH.write_text(
-                json.dumps(self._voice_mode, indent=2)
+                json.dumps(self._voice_mode, indent=2), encoding="utf-8"
             )
         except OSError as e:
             logger.warning("Failed to save voice modes: %s", e)
@@ -3918,7 +4030,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 return max(0.0, timeout)
         return _ADAPTER_DISCONNECT_TIMEOUT_SECS_DEFAULT
 
-    def _platform_connect_timeout_secs(self) -> float:
+    def _platform_connect_timeout_secs(self, platform=None) -> float:
         """Return the per-platform connect timeout used during startup/retry."""
         raw = os.getenv("HERMES_GATEWAY_PLATFORM_CONNECT_TIMEOUT", "").strip()
         if raw:
@@ -3931,6 +4043,8 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 )
             else:
                 return max(0.0, timeout)
+        if platform == Platform.TELEGRAM:
+            return _TELEGRAM_CONNECT_TIMEOUT_SECS_DEFAULT
         return _PLATFORM_CONNECT_TIMEOUT_SECS_DEFAULT
 
     async def _connect_adapter_with_timeout(
@@ -3944,17 +4058,32 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         (preserve the queue so messages sent during the outage are delivered
         rather than silently dropped — #46621).
         """
-        timeout = self._platform_connect_timeout_secs()
+        timeout = self._platform_connect_timeout_secs(platform)
         if timeout <= 0:
             return await adapter.connect(is_reconnect=is_reconnect)
+        # Use the detach-on-timeout pattern instead of plain asyncio.wait_for:
+        # asyncio.wait_for cancels the overdue task but then waits for it to
+        # exit. An adapter connect() that catches CancelledError can therefore
+        # block recovery forever (the watcher never reaches the next retry).
+        # Keep ownership of the old task through its done callback, but
+        # release the runner at the deadline (#70344).
+        task = asyncio.ensure_future(
+            adapter.connect(is_reconnect=is_reconnect)
+        )
         try:
-            return await asyncio.wait_for(
-                adapter.connect(is_reconnect=is_reconnect), timeout=timeout
-            )
-        except asyncio.TimeoutError as exc:
-            raise TimeoutError(
-                f"{platform.value} connect timed out after {timeout:g}s"
-            ) from exc
+            done, _pending = await asyncio.wait({task}, timeout=timeout)
+        except asyncio.CancelledError:
+            task.cancel()
+            task.add_done_callback(consume_detached_task_result)
+            raise
+        if task in done:
+            result = await task
+            return bool(result)
+        task.cancel()
+        task.add_done_callback(consume_detached_task_result)
+        raise TimeoutError(
+            f"{platform.value} connect timed out after {timeout:g}s"
+        )
 
     async def _connect_initial_adapter_with_timeout(self, adapter, platform) -> bool:
         """Connect one cold-start adapter with tightly scoped replace intent.
@@ -4631,6 +4760,10 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                     "%s queued for background reconnection",
                     adapter.platform.value,
                 )
+                # Ensure the reconnect watcher is alive — if it died (e.g. from
+                # exhausting its restart budget), respawn it so queued platforms
+                # are not permanently stranded (#70344).
+                self._ensure_reconnect_watcher_running()
 
         if not self.adapters and not self._failed_platforms:
             self._exit_reason = adapter.fatal_error_message or "All messaging adapters disconnected"
@@ -6861,7 +6994,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
 
         path = _hermes_home / self._STUCK_LOOP_FILE
         try:
-            counts = json.loads(path.read_text()) if path.exists() else {}
+            counts = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
         except Exception:
             counts = {}
 
@@ -6891,7 +7024,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             return 0
 
         try:
-            counts = json.loads(path.read_text())
+            counts = json.loads(path.read_text(encoding="utf-8"))
         except Exception:
             return 0
 
@@ -6937,7 +7070,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         if not path.exists():
             return
         try:
-            counts = json.loads(path.read_text())
+            counts = json.loads(path.read_text(encoding="utf-8"))
             if session_key in counts:
                 del counts[session_key]
                 if counts:
@@ -6969,7 +7102,10 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         # that triggered the /restart command closing its console.
         if sys.platform == "win32":
             import textwrap
-            from hermes_cli._subprocess_compat import windows_detach_popen_kwargs
+            from hermes_cli._subprocess_compat import (
+                windows_detach_flags_without_breakaway,
+                windows_detach_popen_kwargs,
+            )
 
             cmd_argv = [*hermes_cmd, "gateway", "restart"]
             watcher = textwrap.dedent(
@@ -7041,13 +7177,61 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 if watcher_env.get("PYTHONPATH"):
                     pythonpath.append(watcher_env["PYTHONPATH"])
                 watcher_env["PYTHONPATH"] = os.pathsep.join(dict.fromkeys(pythonpath))
-            subprocess.Popen(
-                [watcher_python, "-c", watcher, str(current_pid), str(restart_after_s), *cmd_argv],
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.DEVNULL,
-                env=watcher_env,
-                **windows_detach_popen_kwargs(),
-            )
+            watcher_argv = [
+                watcher_python,
+                "-c",
+                watcher,
+                str(current_pid),
+                str(restart_after_s),
+                *cmd_argv,
+            ]
+            # The watcher process must itself break away from any job object the
+            # parent CLI lives in (Electron/Tauri-wrapped Hermes Desktop, Windows
+            # Terminal, schtasks shells); otherwise it is reaped when the CLI
+            # exits and the gateway never respawns.  windows_detach_popen_kwargs()
+            # carries CREATE_BREAKAWAY_FROM_JOB, but a restrictive job object
+            # (no JOB_OBJECT_LIMIT_BREAKAWAY_OK) rejects that bit with
+            # ERROR_ACCESS_DENIED, surfaced as OSError.  Retry once without the
+            # breakaway bit, preserving argv and the scrubbed watcher_env.
+            # Mirrors the canonical fallback in
+            # hermes_cli/gateway_windows.py::_spawn_detached.
+            try:
+                subprocess.Popen(
+                    watcher_argv,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    env=watcher_env,
+                    **windows_detach_popen_kwargs(),
+                )
+            except OSError:
+                try:
+                    subprocess.Popen(
+                        watcher_argv,
+                        stdout=subprocess.DEVNULL,
+                        stderr=subprocess.DEVNULL,
+                        env=watcher_env,
+                        creationflags=windows_detach_flags_without_breakaway(),
+                    )
+                except OSError as exc:
+                    # Both spawn attempts failed (a breakaway-denying job object
+                    # is the common cause, but OSError covers others too).
+                    # Record a minimal, path-safe diagnostic and return without
+                    # crashing the caller: state plainly that no watcher was
+                    # started, and log only the interpreter basename and a
+                    # numeric error code — never argv, env, watcher source, or
+                    # str(exc) (which can carry a full interpreter path for a
+                    # FileNotFoundError).
+                    winerror = getattr(exc, "winerror", None)
+                    error_code = winerror if winerror is not None else exc.errno
+                    error_field = "winerror" if winerror is not None else "errno"
+                    logger.warning(
+                        "Detached restart watcher was not started after the "
+                        "no-breakaway retry (%s; %s=%r). The gateway will not "
+                        "be respawned by this restart attempt.",
+                        os.path.basename(watcher_python),
+                        error_field,
+                        error_code,
+                    )
             return
 
         cmd = " ".join(shlex.quote(part) for part in hermes_cmd)
@@ -7125,7 +7309,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                     out = subprocess.run(
                         [systemctl, *scope_flags, "show", service_name,
                          "--property=MainPID", "--value"],
-                        capture_output=True, text=True, timeout=2,
+                        capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=2,
                     )
                     return (out.stdout or "").strip()
                 except Exception:
@@ -7583,6 +7767,46 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             )
         return True
 
+    def _start_loop_liveness_guards(self, loop: asyncio.AbstractEventLoop) -> None:
+        """Arm the selector floor and out-of-loop watchdog before adapters.
+
+        Disabled entirely with ``gateway.loop_watchdog: false`` in config.yaml
+        (no env override — config-only knob, #69089).
+        """
+        config = getattr(self, "config", None)
+        if config is not None and not getattr(config, "loop_watchdog", True):
+            return
+        if getattr(self, "_loop_floor_timer_handle", None) is None:
+            try:
+                self._loop_floor_timer_handle = _arm_loop_floor_timer(loop)
+            except Exception:
+                logger.debug("Failed to arm gateway loop floor timer", exc_info=True)
+
+        watchdog = getattr(self, "_loop_liveness_watchdog", None)
+        if watchdog is None or not watchdog.is_alive():
+            try:
+                self._loop_liveness_watchdog = start_loop_liveness_watchdog(loop)
+            except Exception:
+                logger.debug("Failed to start gateway loop liveness watchdog", exc_info=True)
+
+    def _stop_loop_liveness_guards(self) -> None:
+        """Disarm lifetime liveness guards before shutdown can load the loop."""
+        watchdog = getattr(self, "_loop_liveness_watchdog", None)
+        self._loop_liveness_watchdog = None
+        if watchdog is not None:
+            try:
+                watchdog.stop()
+            except Exception:
+                logger.debug("Failed to stop gateway loop liveness watchdog", exc_info=True)
+
+        floor_timer = getattr(self, "_loop_floor_timer_handle", None)
+        self._loop_floor_timer_handle = None
+        if floor_timer is not None:
+            try:
+                floor_timer.cancel()
+            except Exception:
+                logger.debug("Failed to cancel gateway loop floor timer", exc_info=True)
+
     async def start(self) -> bool:
         """
         Start the gateway and all configured platform adapters.
@@ -7590,10 +7814,41 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         Returns True if at least one adapter connected successfully.
         """
         logger.info("Starting Hermes Gateway...")
+        # Enable faulthandler at gateway start so that SIGUSR2 (or an
+        # internal watchdog) can dump all thread and task stacks to stderr
+        # for post-mortem diagnosis of event-loop freezes (#70344).
+        faulthandler.enable()
+        # Also dump stacks to a rotating file for off-line analysis when
+        # the gateway is running under a service manager that doesn't
+        # capture stderr.
+        # faulthandler.register() and SIGUSR2 are POSIX-only; skip the
+        # signal-triggered file dump on Windows (faulthandler.enable()
+        # above still covers fatal-error dumps there).
+        _sigusr2 = getattr(signal, "SIGUSR2", None)
+        if _sigusr2 is not None and hasattr(faulthandler, "register"):
+            try:
+                _log_dir = getattr(self.config, "log_dir", None) or os.path.join(
+                    os.environ.get("HERMES_HOME", str(Path.home() / ".hermes")),
+                    "logs",
+                )
+                _faulthandler_path = os.path.join(_log_dir, "gateway_faulthandler.log")
+                os.makedirs(_log_dir, exist_ok=True)
+                _fh = open(_faulthandler_path, "a", encoding="utf-8")
+                faulthandler.register(
+                    _sigusr2,
+                    file=_fh,
+                    all_threads=True,
+                    chain=True,
+                )
+            except Exception:
+                logger.debug("Could not set up faulthandler file logging", exc_info=True)
+
         try:
             self._gateway_loop = asyncio.get_running_loop()
         except RuntimeError:
             self._gateway_loop = None
+        if self._gateway_loop is not None:
+            self._start_loop_liveness_guards(self._gateway_loop)
         logger.info("Session storage: %s", self.config.sessions_dir)
 
         # Sanity-check that systemd's TimeoutStopSec covers our drain
@@ -8105,7 +8360,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 )
 
         if connected_count == 0:
-            if startup_nonretryable_errors:
+            if startup_nonretryable_errors and not startup_retryable_errors:
                 reason = "; ".join(startup_nonretryable_errors)
                 logger.error("Gateway hit a non-retryable startup conflict: %s", reason)
                 try:
@@ -8117,6 +8372,27 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 self._request_clean_exit(reason)
                 self._startup_restore_in_progress = False
                 return True
+            if startup_nonretryable_errors:
+                # Mixed failure mode (NS-609): some platforms are fatally
+                # misconfigured (e.g. WhatsApp enabled but never paired) while
+                # others hit merely transient errors (e.g. Telegram TimedOut
+                # during polling startup).  Exiting with
+                # GATEWAY_FATAL_CONFIG_EXIT_CODE here is wrong in both
+                # supervision worlds: under supervisors that honor the
+                # exit-78 contract (systemd RestartPreventExitStatus, s6
+                # finish→125 since #51228) the gateway goes PERMANENTLY down
+                # over a network blip; under anything else it crash-loops.
+                # Either way the retryable platforms never get their retry.
+                # Log the fatal side loudly, then fall through to the
+                # degraded/retry path below: the reconnect watcher recovers
+                # the retryable platforms; the non-retryable ones remain
+                # fatal-parked and visible in runtime status.
+                logger.error(
+                    "%d platform(s) fatally misconfigured and parked: %s. "
+                    "Staying alive so retryable platforms can recover.",
+                    len(startup_nonretryable_errors),
+                    "; ".join(startup_nonretryable_errors),
+                )
             if enabled_platform_count > 0:
                 if startup_retryable_errors:
                     # All enabled platforms hit retryable failures (network
@@ -8309,7 +8585,12 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 len(self._failed_platforms),
                 ", ".join(p.value for p in self._failed_platforms),
             )
-        self._spawn_supervised(self._platform_reconnect_watcher, "platform_reconnect_watcher")
+        # Track the reconnect watcher task so _ensure_reconnect_watcher_running
+        # can detect if it dies and respawn it (#70344).
+        self._reconnect_watcher_task = asyncio.create_task(
+            self._platform_reconnect_watcher()
+        )
+        self._background_tasks.add(self._reconnect_watcher_task)
 
         # Start background handoff watcher — picks up CLI sessions marked
         # handoff_state='pending' in state.db and re-binds them to the
@@ -8511,12 +8792,18 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         except (ValueError, KeyError):
             raise RuntimeError(f"unknown platform '{platform_name}'")
 
-        # Adapter must be live
-        adapter = self.adapters.get(platform)
-        if not adapter:
+        # Adapter must be live. A relay-fronted gateway registers ONE adapter
+        # under Platform.RELAY that fronts N logical platforms — so a literal
+        # adapters.get(discord) misses even though "discord" is deliverable.
+        # resolve_delivery_transport is the shared alias-aware resolver (native
+        # adapter wins; relay eligible only when its authenticated transport
+        # advertises it fronts the logical platform).
+        transport = resolve_delivery_transport(platform, self.config, self.adapters)
+        if not transport:
             raise RuntimeError(
                 f"platform '{platform_name}' is not active in this gateway"
             )
+        adapter = transport.adapter
 
         # Home channel must be configured
         home = self.config.get_home_channel(platform)
@@ -8656,15 +8943,18 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
 
         # Send the agent's reply to the destination. Route to the new
         # thread if we created one; otherwise the configured home channel
-        # (which may itself carry a thread_id).
+        # (which may itself carry a thread_id). Send through the resolved
+        # transport (not adapter.send directly) so a relay-fronted logical
+        # platform is stamped on the outbound frame (send_for_platform).
         send_metadata: Dict[str, Any] = {}
         if effective_thread_id:
             send_metadata["thread_id"] = effective_thread_id
         try:
-            result = await adapter.send(
-                chat_id=str(home.chat_id),
-                content=response_text,
-                metadata=send_metadata or None,
+            result = await transport.send(
+                platform,
+                str(home.chat_id),
+                response_text,
+                send_metadata or None,
             )
         except Exception as exc:
             raise RuntimeError(f"adapter.send failed: {exc}") from exc
@@ -8864,6 +9154,30 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
     # self state, so inheriting the mixin keeps every self._kanban_* call site
     # working unchanged while lifting ~1,000 LOC out of this file.
 
+    def _ensure_reconnect_watcher_running(self) -> None:
+        """Ensure the platform reconnect watcher background task is alive.
+
+        If the tracked reconnect watcher task has died (e.g. from exhausting
+        its restart budget, or a terminal exception that _spawn_supervised
+        could not recover), respawns it so platforms queued for reconnection
+        are not permanently stranded. Called after queueing a retryable fatal
+        error in _handle_adapter_fatal_error (#70344).
+        """
+        if not getattr(self, "_running", False):
+            return
+        task = getattr(self, "_reconnect_watcher_task", None)
+        if task is not None and not task.done():
+            return  # already alive
+        logger.warning(
+            "Reconnect watcher task is dead (done=%s) — respawning",
+            task.done() if task is not None else "N/A",
+        )
+        self._reconnect_watcher_task = asyncio.create_task(
+            self._platform_reconnect_watcher()
+        )
+        if getattr(self, "_background_tasks", None) is not None:
+            self._background_tasks.add(self._reconnect_watcher_task)
+
     async def _platform_reconnect_watcher(self) -> None:
         """Background task that periodically retries connecting failed platforms.
 
@@ -9130,6 +9444,11 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         service_restart: bool = False,
     ) -> None:
         """Stop the gateway and disconnect all adapters."""
+        # getattr-guard: shutdown-path tests build bare runners via
+        # object.__new__ that lack the liveness-guard machinery.
+        _stop_guards = getattr(self, "_stop_loop_liveness_guards", None)
+        if callable(_stop_guards):
+            _stop_guards()
         if restart:
             self._restart_requested = True
             self._restart_detached = detached_restart
@@ -10627,7 +10946,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 prompt_path = _hermes_home / ".update_prompt.json"
                 try:
                     tmp = response_path.with_suffix(".tmp")
-                    tmp.write_text(response_text)
+                    tmp.write_text(response_text, encoding="utf-8")
                     tmp.replace(response_path)
                     prompt_path.unlink(missing_ok=True)
                 except OSError as e:
@@ -10647,7 +10966,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 prompt_path = _hermes_home / ".update_prompt.json"
                 try:
                     tmp = response_path.with_suffix(".tmp")
-                    tmp.write_text("")
+                    tmp.write_text("", encoding="utf-8")
                     tmp.replace(response_path)
                     prompt_path.unlink(missing_ok=True)
                     logger.info(
@@ -10854,6 +11173,11 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             if _cmd_def_inner and _cmd_def_inner.name == "restart":
                 return await self._handle_restart_command(event)
 
+            if _cmd_def_inner and _cmd_def_inner.name == "egress":
+                from hermes_cli.proxy_cli import format_status_text
+
+                return format_status_text()
+
             # /stop must hard-kill the session when an agent is running.
             # A soft interrupt (agent.interrupt()) doesn't help when the agent
             # is truly hung — the executor thread is blocked and never checks
@@ -11390,6 +11714,11 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         if canonical == "status":
             return await self._handle_status_command(event)
 
+        if canonical == "egress":
+            from hermes_cli.proxy_cli import format_status_text
+
+            return format_status_text()
+
         if canonical == "agents":
             return await self._handle_agents_command(event)
 
@@ -12860,6 +13189,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             _hyg_compression_enabled = True
             _hyg_hard_msg_limit = 5000
             _hyg_timeout_seconds = 30.0
+            _hyg_total_ceiling_seconds = 600.0
             _hyg_failure_cooldown_seconds = 300.0
             _hyg_config_context_length = None
             _hyg_provider = None
@@ -12914,6 +13244,19 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                                     _hyg_timeout_seconds = _parsed
                             except (TypeError, ValueError):
                                 pass
+                        _raw_ceiling = _comp_cfg.get("hygiene_total_ceiling_seconds")
+                        if _raw_ceiling is not None:
+                            try:
+                                _parsed = float(_raw_ceiling)
+                                if _parsed > 0:
+                                    _hyg_total_ceiling_seconds = _parsed
+                            except (TypeError, ValueError):
+                                pass
+                        # The ceiling can never be tighter than one idle
+                        # window, or the extension loop would be dead code.
+                        _hyg_total_ceiling_seconds = max(
+                            _hyg_total_ceiling_seconds, _hyg_timeout_seconds,
+                        )
                         _raw_cooldown = _comp_cfg.get("hygiene_failure_cooldown_seconds")
                         if _raw_cooldown is not None:
                             try:
@@ -13134,10 +13477,43 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                                         ),
                                     )
                                     try:
-                                        _compressed, _ = await asyncio.wait_for(
-                                            asyncio.shield(_hyg_future),
-                                            timeout=_hyg_timeout_seconds,
-                                        )
+                                        # Progress-aware wait: the timeout is an
+                                        # INACTIVITY budget, not a total one. The
+                                        # compression worker streams its summary
+                                        # call and ticks the fence per token
+                                        # (CompressionCommitFence.touch_progress),
+                                        # so a slow reasoning model that is still
+                                        # generating keeps extending the deadline;
+                                        # only a genuinely silent worker times out.
+                                        # A hard ceiling bounds the total wait so
+                                        # a degenerate trickle stream can't hold
+                                        # the turn forever.
+                                        _hyg_wait_started = time.monotonic()
+                                        while True:
+                                            try:
+                                                _compressed, _ = await asyncio.wait_for(
+                                                    asyncio.shield(_hyg_future),
+                                                    timeout=_hyg_timeout_seconds,
+                                                )
+                                                break
+                                            except asyncio.TimeoutError:
+                                                _hyg_waited = time.monotonic() - _hyg_wait_started
+                                                _idle = _hyg_commit_fence.seconds_since_progress()
+                                                if (
+                                                    _idle < _hyg_timeout_seconds
+                                                    and _hyg_waited < _hyg_total_ceiling_seconds
+                                                ):
+                                                    logger.info(
+                                                        "Session hygiene compression for "
+                                                        "session %s still streaming after "
+                                                        "%.0fs (last progress %.1fs ago) — "
+                                                        "extending wait (ceiling %.0fs)",
+                                                        session_entry.session_id,
+                                                        _hyg_waited, _idle,
+                                                        _hyg_total_ceiling_seconds,
+                                                    )
+                                                    continue
+                                                raise
                                     except asyncio.TimeoutError:
                                         _cancelled = None
                                         while _cancelled is None:
@@ -13166,14 +13542,18 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                                                 ] = time.time() + _hyg_failure_cooldown_seconds
                                             logger.warning(
                                                 "Session hygiene compression for session %s "
-                                                "timed out after %.1fs; continuing without "
-                                                "compression",
+                                                "made no progress for %.1fs "
+                                                "(total wait %.1fs, ceiling %.1fs); "
+                                                "continuing without compression",
                                                 session_entry.session_id,
-                                                _hyg_timeout_seconds,
+                                                _hyg_commit_fence.seconds_since_progress(),
+                                                time.monotonic() - _hyg_wait_started,
+                                                _hyg_total_ceiling_seconds,
                                             )
                                             _timeout_msg = (
                                                 "⚠️ Context compression timed out "
-                                                f"after {_hyg_timeout_seconds:.1f}s. "
+                                                f"after {_hyg_timeout_seconds:.1f}s "
+                                                "with no output from the summary model. "
                                                 "No messages were dropped — continuing without "
                                                 "compression. Run /compress to retry, /reset for "
                                                 "a clean session, or check your "
@@ -13913,7 +14293,20 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             # large to process.  Auto-reset it so the next message starts
             # fresh instead of replaying the same oversized context in an
             # infinite fail loop.  (#9893)
-            if agent_result.get("compression_exhausted") and session_entry and session_key:
+            #
+            # A lock-contended defer is the OPPOSITE case: the session is
+            # temporarily uncompressible only because a concurrent path holds
+            # the compression lock and is actively shrinking it. Never wipe
+            # the session for that — retry-next-message semantics apply
+            # (#69870 lock-skip consumer; salvaged from #49874).
+            if agent_result.get("compression_deferred"):
+                logger.info(
+                    "Compression deferred for session %s — the compression "
+                    "lock is held by a concurrent compressor. Keeping the "
+                    "session intact; the next message retries normally.",
+                    session_entry.session_id if session_entry else "?",
+                )
+            elif agent_result.get("compression_exhausted") and session_entry and session_key:
                 logger.info(
                     "Auto-resetting session %s after compression exhaustion.",
                     session_entry.session_id,
@@ -14573,7 +14966,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                     self._booted_from_restart = False
                     return True
                 return False
-            data = json.loads(marker_path.read_text())
+            data = json.loads(marker_path.read_text(encoding="utf-8"))
         except Exception:
             return False
 
@@ -16527,7 +16920,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         for path in (claimed_path, pending_path):
             if path.exists():
                 try:
-                    pending = json.loads(path.read_text())
+                    pending = json.loads(path.read_text(encoding="utf-8"))
                     platform_str = pending.get("platform")
                     chat_id = pending.get("chat_id")
                     chat_type = pending.get("chat_type")
@@ -16566,7 +16959,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                     return
                 await asyncio.sleep(poll_interval)
             if (pending_path.exists() or claimed_path.exists()) and not exit_code_path.exists():
-                exit_code_path.write_text("124")
+                exit_code_path.write_text("124", encoding="utf-8")
                 await self._send_update_notification()
             return
 
@@ -16608,7 +17001,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 # Read any remaining output
                 if output_path.exists():
                     try:
-                        content = output_path.read_text()
+                        content = output_path.read_text(encoding="utf-8")
                         if len(content) > bytes_sent:
                             buffer += content[bytes_sent:]
                             bytes_sent = len(content)
@@ -16618,7 +17011,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
 
                 # Send final status
                 try:
-                    exit_code_raw = exit_code_path.read_text().strip() or "1"
+                    exit_code_raw = exit_code_path.read_text(encoding="utf-8").strip() or "1"
                     exit_code = int(exit_code_raw)
                     if exit_code == 0:
                         await adapter.send(
@@ -16647,7 +17040,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             # Check for new output
             if output_path.exists():
                 try:
-                    content = output_path.read_text()
+                    content = output_path.read_text(encoding="utf-8")
                     if len(content) > bytes_sent:
                         buffer += content[bytes_sent:]
                         bytes_sent = len(content)
@@ -16665,7 +17058,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             if (prompt_path.exists() and session_key
                     and not self._update_prompt_pending.get(session_key)):
                 try:
-                    prompt_data = json.loads(prompt_path.read_text())
+                    prompt_data = json.loads(prompt_path.read_text(encoding="utf-8"))
                     prompt_text = prompt_data.get("prompt", "")
                     default = prompt_data.get("default", "")
                     if prompt_text:
@@ -16713,7 +17106,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         # Timeout
         if not exit_code_path.exists():
             logger.warning("Update watcher timed out after %.0fs", timeout)
-            exit_code_path.write_text("124")
+            exit_code_path.write_text("124", encoding="utf-8")
             await _flush_buffer()
             try:
                 await adapter.send(
@@ -16759,7 +17152,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             elif not claimed_path.exists():
                 return True
 
-            pending = json.loads(claimed_path.read_text())
+            pending = json.loads(claimed_path.read_text(encoding="utf-8"))
             platform_str = pending.get("platform")
             chat_id = pending.get("chat_id")
             chat_type = pending.get("chat_type")
@@ -16773,13 +17166,13 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 claimed_path.replace(pending_path)
                 return False
 
-            exit_code_raw = exit_code_path.read_text().strip() or "1"
+            exit_code_raw = exit_code_path.read_text(encoding="utf-8").strip() or "1"
             exit_code = int(exit_code_raw)
 
             # Read the captured update output
             output = ""
             if output_path.exists():
-                output = output_path.read_text()
+                output = output_path.read_text(encoding="utf-8")
 
             # Resolve adapter
             platform = Platform(platform_str)
@@ -16854,7 +17247,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             return None
 
         try:
-            data = json.loads(notify_path.read_text())
+            data = json.loads(notify_path.read_text(encoding="utf-8"))
             platform_str = data.get("platform")
             chat_id = data.get("chat_id")
             chat_type = data.get("chat_type")
@@ -16865,10 +17258,10 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 return None
 
             platform = Platform(platform_str)
-            adapter = self.adapters.get(platform)
-            if not adapter:
+            transport = resolve_delivery_transport(platform, self.config, self.adapters)
+            if transport is None:
                 logger.debug(
-                    "Restart notification skipped: %s adapter not connected",
+                    "Restart notification skipped: no live transport for %s",
                     platform_str,
                 )
                 return None
@@ -16887,9 +17280,16 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 thread_id,
                 chat_type=chat_type,
                 reply_to_message_id=message_id,
-                adapter=adapter,
+                adapter=transport.adapter,
             )
-            result = await adapter.send(
+            if data.get("delivered_via_upstream_relay") is True:
+                metadata = dict(metadata or {})
+                if data.get("user_id"):
+                    metadata["user_id"] = str(data["user_id"])
+                if data.get("scope_id"):
+                    metadata["scope_id"] = str(data["scope_id"])
+            result = await transport.send(
+                platform,
                 str(chat_id),
                 "♻ Gateway restarted successfully. Your session continues.",
                 metadata=_non_conversational_metadata(metadata, platform=platform),
@@ -16934,13 +17334,16 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         skipped = skip_targets or set()
         message = "♻️ Gateway online — Hermes is back and ready."
 
-        for platform, adapter in self.adapters.items():
-            home = self.config.get_home_channel(platform)
+        for platform, platform_cfg in self.config.platforms.items():
+            home = platform_cfg.home_channel
             if not home or not home.chat_id:
                 continue
 
-            platform_cfg = self.config.platforms.get(platform)
-            if platform_cfg is not None and not platform_cfg.gateway_restart_notification:
+            transport = resolve_delivery_transport(platform, self.config, self.adapters)
+            if transport is None:
+                continue
+
+            if not platform_cfg.gateway_restart_notification:
                 logger.info(
                     "Home-channel startup notification suppressed: %s has gateway_restart_notification=false",
                     platform.value,
@@ -16956,24 +17359,24 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                     platform,
                     home.chat_id,
                     home.thread_id,
-                    adapter=adapter,
+                    adapter=transport.adapter,
                 )
-                if metadata:
-                    result = await adapter.send(
+                if transport.is_relay:
+                    metadata = dict(metadata or {})
+                    if home.user_id:
+                        metadata["user_id"] = home.user_id
+                    if home.scope_id:
+                        metadata["scope_id"] = home.scope_id
+                send_metadata = _non_conversational_metadata(metadata, platform=platform)
+                if send_metadata is not None or transport.is_relay:
+                    result = await transport.send(
+                        platform,
                         str(home.chat_id),
                         message,
-                        metadata=_non_conversational_metadata(metadata, platform=platform),
+                        metadata=send_metadata,
                     )
                 else:
-                    _startup_meta = _non_conversational_metadata(platform=platform)
-                    if _startup_meta:
-                        result = await adapter.send(
-                            str(home.chat_id),
-                            message,
-                            metadata=_startup_meta,
-                        )
-                    else:
-                        result = await adapter.send(str(home.chat_id), message)
+                    result = await transport.adapter.send(str(home.chat_id), message)
                 if result is not None and getattr(result, "success", True) is False:
                     logger.warning(
                         "Home-channel startup notification failed for %s:%s: %s",
@@ -18100,6 +18503,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         ("model", "context_length"),
         ("model", "max_tokens"),
         ("compression", "enabled"),
+        ("compression", "progress_notices"),
         ("compression", "threshold"),
         ("compression", "model_thresholds"),
         ("compression", "threshold_tokens"),
@@ -18107,6 +18511,10 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         ("compression", "codex_app_server_auto"),
         ("compression", "target_ratio"),
         ("compression", "protect_last_n"),
+        ("compression", "proactive_prune_tokens"),
+        ("compression", "proactive_prune_min_result_chars"),
+        ("compression", "proactive_prune_min_reclaim_tokens"),
+        ("compression", "min_tail_user_messages"),
         ("agent", "disabled_toolsets"),
         ("memory", "provider"),
         ("checkpoints", "enabled"),
@@ -21994,6 +22402,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                     "interrupt_message": result.get("interrupt_message"),
                     "error": result.get("error"),
                     "compression_exhausted": result.get("compression_exhausted", False),
+                    "compression_deferred": result.get("compression_deferred", False),
                     "tools": tools_holder[0] or [],
                     "history_offset": _effective_history_offset,
                     "compacted_in_place": _compacted_in_place,
@@ -22111,6 +22520,13 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 "partial": result_holder[0].get("partial", False) if result_holder[0] else False,
                 "error": result_holder[0].get("error") if result_holder[0] else None,
                 "interrupt_message": result_holder[0].get("interrupt_message") if result_holder[0] else None,
+                # Soft lock-contention defer (#69870 consumer): distinct from
+                # compression_exhausted so the gateway never auto-resets a
+                # session that a concurrent compressor is about to shrink.
+                "compression_deferred": (
+                    result_holder[0].get("compression_deferred", False)
+                    if result_holder[0] else False
+                ),
                 "tools": tools_holder[0] or [],
                 "history_offset": _effective_history_offset,
                 "compacted_in_place": _compacted_in_place,
@@ -23197,6 +23613,7 @@ def _start_gateway_housekeeping(stop_event: threading.Event, adapters=None, loop
     CHANNEL_DIR_EVERY = 5    # ticks — every 5 minutes
     PASTE_SWEEP_EVERY = 60   # ticks — once per hour
     CURATOR_EVERY = 60       # ticks — poll hourly (inner gate handles the real cadence)
+    AUTO_ARCHIVE_EVERY = 60  # ticks — poll hourly (state_meta gate owns the real cadence)
 
     logger.info("Gateway housekeeping started (interval=%ds)", interval)
     tick_count = 0
@@ -23261,6 +23678,28 @@ def _start_gateway_housekeeping(stop_event: threading.Event, adapters=None, loop
             except Exception as e:
                 logger.debug("Curator tick error: %s", e)
 
+        # Stale-session auto-archive — a live timer, so gateways that stay up
+        # for weeks keep sweeping on schedule (the startup hook fires once).
+        # maybe_auto_archive() is gated by sessions.min_interval_hours in
+        # state_meta; this is just the poll rate. Opens its own SessionDB —
+        # SQLite connections are thread-bound and this runs off-loop.
+        if tick_count % AUTO_ARCHIVE_EVERY == 0:
+            try:
+                from hermes_cli.config import load_config as _load_full_config
+                from hermes_state import SessionDB
+                _sess_cfg = (_load_full_config().get("sessions") or {})
+                if _sess_cfg.get("auto_archive", False):
+                    _adb = SessionDB()
+                    try:
+                        _adb.maybe_auto_archive(
+                            idle_days=float(_sess_cfg.get("auto_archive_days", 3)),
+                            min_interval_hours=int(_sess_cfg.get("min_interval_hours", 24)),
+                        )
+                    finally:
+                        _adb.close()
+            except Exception as e:
+                logger.debug("Auto-archive tick error: %s", e)
+
         stop_event.wait(timeout=interval)
     logger.info("Gateway housekeeping stopped")
 
@@ -23810,7 +24249,35 @@ async def start_gateway(config: Optional[GatewayConfig] = None, replace: bool =
     from cron.scheduler_provider import InProcessCronScheduler, resolve_cron_scheduler
     cron_stop = threading.Event()
     cron_provider = resolve_cron_scheduler()
-    cron_start_kwargs = {"adapters": runner.adapters, "loop": asyncio.get_running_loop()}
+    cron_start_kwargs: Dict[str, Any] = {"adapters": runner.adapters, "loop": asyncio.get_running_loop()}
+
+    # Multiplex profiles: tell the built-in ticker which profile homes to
+    # tick so secondary-profile cron jobs actually fire (#69377).
+    # Without this, only the process-global HERMES_HOME (default profile)
+    # is iterated and every secondary profile's cron store is silently
+    # ignored — jobs show as "scheduled" with a valid next_run_at but
+    # never execute because no ticker owns that store.
+    if (
+        isinstance(cron_provider, InProcessCronScheduler)
+        and getattr(runner.config, "multiplex_profiles", False)
+    ):
+        try:
+            from hermes_cli.profiles import profiles_to_serve
+
+            profile_homes = list(profiles_to_serve(multiplex=True))
+            if profile_homes:
+                cron_start_kwargs["profile_homes"] = profile_homes
+                logger.info(
+                    "Cron scheduler will tick %d profile(s) under multiplex: %s",
+                    len(profile_homes),
+                    [p[0] if isinstance(p, tuple) else p for p in profile_homes],
+                )
+        except Exception as exc:
+            logger.warning(
+                "Could not resolve profile homes for multiplex cron: %s",
+                exc,
+            )
+
     # External cron providers own their remote scheduling contract. Only the
     # in-process ticker polls local due jobs, so only it receives the local
     # external-drain dispatch gate.
diff --git a/gateway/session.py b/gateway/session.py
index 7f630dd861d..89f4188669e 100644
--- a/gateway/session.py
+++ b/gateway/session.py
@@ -1186,6 +1186,11 @@ class SessionStore:
         self._legacy_slack_claim_lock = threading.Lock()
         self._claimed_legacy_slack_keys: set[str] = set()
         self._transcript_retry_lock = threading.Lock()
+        # Exactly one transcript drainer mutates routing/queues at a time. SQLite
+        # serializes writes anyway; this outer lock also makes parent->child
+        # queue migration and routing publication linearizable.
+        self._transcript_drain_lock = threading.RLock()
+        self._transcript_reroutes: Dict[str, str] = {}
         self._dirty_transcripts: Dict[str, List[Dict[str, Any]]] = {}
         self._transcript_append_failures: Dict[str, int] = {}
         self._fts_rebuild_attempted = False
@@ -2914,6 +2919,29 @@ class SessionStore:
             return getattr(entry, "session_id", None) if entry else None
     
     def append_to_transcript(self, session_id: str, message: Dict[str, Any], skip_db: bool = False) -> None:
+        """Serialize transcript draining across queue migration boundaries."""
+        if not self._db or skip_db:
+            return
+        drain_lock = getattr(self, "_transcript_drain_lock", None)
+        if drain_lock is None:
+            # Compatibility for old in-memory/test instances created via
+            # object.__new__ before this field existed.
+            drain_lock = threading.RLock()
+            self._transcript_drain_lock = drain_lock
+        with drain_lock:
+            reroutes = getattr(self, "_transcript_reroutes", None)
+            if reroutes is None:
+                reroutes = {}
+                self._transcript_reroutes = reroutes
+            seen = set()
+            while session_id in reroutes and session_id not in seen:
+                seen.add(session_id)
+                session_id = reroutes[session_id]
+            self._append_to_transcript_serialized(session_id, message)
+
+    def _append_to_transcript_serialized(
+        self, session_id: str, message: Dict[str, Any]
+    ) -> None:
         """Append a message to a session's transcript (SQLite).
 
         Args:
@@ -2922,8 +2950,6 @@ class SessionStore:
                      _flush_messages_to_session_db(), preventing the
                      duplicate-write bug (#860).
         """
-        if not self._db or skip_db:
-            return
         with self._transcript_retry_lock:
             pending = self._dirty_transcripts.setdefault(session_id, [])
             pending.append(dict(message))
@@ -2939,12 +2965,76 @@ class SessionStore:
             # Snapshot the first pending message, then release the lock
             # before the DB write so other sessions are not blocked.
             msg = pending[0]
+        queue_session_id = session_id
         # DB write outside the retry lock — other sessions can append
         # concurrently. We re-acquire the lock only to update the queue.
         while True:
             try:
                 self._append_transcript_message(session_id, msg)
             except Exception as exc:
+                from hermes_state import CompressionSessionClosedError
+
+                if isinstance(exc, CompressionSessionClosedError):
+                    child = self._db.find_live_compression_child(session_id)
+                    child_id = str(child["id"]) if child and child.get("id") else ""
+                    if child_id:
+                        try:
+                            self._append_transcript_message(child_id, msg)
+                        except Exception as reroute_exc:
+                            exc = reroute_exc
+                        else:
+                            with self._transcript_retry_lock:
+                                if pending and pending[0] is msg:
+                                    pending.pop(0)
+                                existing_child_pending = self._dirty_transcripts.get(
+                                    child_id, []
+                                )
+                                if pending:
+                                    # Older parent backlog must precede messages
+                                    # already queued directly on the child.
+                                    pending.extend(existing_child_pending)
+                                    self._dirty_transcripts[child_id] = pending
+                                elif existing_child_pending:
+                                    pending = existing_child_pending
+                                self._dirty_transcripts.pop(queue_session_id, None)
+                                previous_failures = self._transcript_append_failures.pop(
+                                    queue_session_id, 0
+                                )
+                                if previous_failures:
+                                    self._transcript_append_failures[child_id] = max(
+                                        previous_failures,
+                                        self._transcript_append_failures.get(child_id, 0),
+                                    )
+                                self._transcript_reroutes[session_id] = child_id
+                                queue_session_id = child_id
+                            # Publish routing only after the retry queue has moved,
+                            # so new child writes cannot bypass older parent backlog.
+                            with self._lock:
+                                for entry in self._entries.values():
+                                    if entry.session_id == session_id:
+                                        entry.session_id = child_id
+                                self._save()
+                            if not pending:
+                                return
+                            msg = pending[0]
+                            session_id = child_id
+                            continue
+                    else:
+                        # This is a permanent routing invariant failure, not a
+                        # transient DB outage. Drop it from the retry queue so it
+                        # cannot poison later transcript writes indefinitely.
+                        with self._transcript_retry_lock:
+                            if pending and pending[0] is msg:
+                                pending.pop(0)
+                            if not pending:
+                                self._dirty_transcripts.pop(queue_session_id, None)
+                                self._transcript_append_failures.pop(session_id, None)
+                        logger.error(
+                            "Session DB transcript append rejected for compression-ended "
+                            "%s with no unique live child; not retrying",
+                            session_id,
+                        )
+                        return
                 if self._is_fts_corruption_error(exc) and self._rebuild_fts_once():
                     try:
                         self._append_transcript_message(session_id, msg)
@@ -2955,7 +3045,7 @@ class SessionStore:
                             if pending and pending[0] is msg:
                                 pending.pop(0)
                             if not pending:
-                                self._dirty_transcripts.pop(session_id, None)
+                                self._dirty_transcripts.pop(queue_session_id, None)
                                 self._transcript_append_failures.pop(session_id, None)
                         continue
                 with self._transcript_retry_lock:
@@ -2972,7 +3062,7 @@ class SessionStore:
                     if pending and pending[0] is msg:
                         pending.pop(0)
                     if not pending:
-                        self._dirty_transcripts.pop(session_id, None)
+                        self._dirty_transcripts.pop(queue_session_id, None)
                         self._transcript_append_failures.pop(session_id, None)
                         return
                     msg = pending[0]
diff --git a/gateway/shutdown_forensics.py b/gateway/shutdown_forensics.py
index 0a52ce14f09..34836cc6fb1 100644
--- a/gateway/shutdown_forensics.py
+++ b/gateway/shutdown_forensics.py
@@ -368,7 +368,7 @@ def check_systemd_timing_alignment(drain_timeout: float) -> Optional[Dict[str, A
         try:
             result = subprocess.run(
                 ["systemctl", *flag, "show", unit_name, "--property=TimeoutStopUSec"],
-                capture_output=True, text=True, timeout=2.0,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=2.0,
             )
         except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
             continue
diff --git a/gateway/shutdown_watchdog.py b/gateway/shutdown_watchdog.py
index 492160996c7..eb3c9074ac0 100644
--- a/gateway/shutdown_watchdog.py
+++ b/gateway/shutdown_watchdog.py
@@ -1,4 +1,4 @@
-"""Out-of-loop shutdown backstop + event-loop liveness heartbeat (#66892).
+"""Out-of-loop shutdown and event-loop liveness backstops (#66892, #69089).
 
 When the asyncio loop freezes mid-drain, every asyncio-based recovery path is
 structurally unable to fire: the drain deadline, status rewrites, and forensics
@@ -15,6 +15,10 @@ This module provides:
 2. An event-loop heartbeat file at ``<HERMES_HOME>/state/gateway.heartbeat`` so
    external supervision can distinguish "process alive" from "loop frozen"
    (``gateway_state.json`` alone can't — it only rewrites on transitions/turns).
+3. A lifetime thread watchdog that can still diagnose and hard-exit when the
+   event loop is too frozen to run its own heartbeat or timeout callbacks.
+4. A self-rescheduling floor timer that keeps the loop selector's timeout
+   finite, giving existing async recovery tasks a chance to resume.
 """
 
 from __future__ import annotations
@@ -31,6 +35,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable, Dict, Optional
 
+from gateway.restart import GATEWAY_SERVICE_RESTART_EXIT_CODE
 from hermes_constants import get_hermes_home
 from utils import atomic_json_write
 
@@ -40,10 +45,162 @@ logger = logging.getLogger(__name__)
 # drain is not cut short. Matches the issue #66892 suggested hardening.
 DEFAULT_SHUTDOWN_WATCHDOG_GRACE_S = 60.0
 DEFAULT_HEARTBEAT_INTERVAL_S = 30.0
+DEFAULT_LOOP_FLOOR_TIMER_INTERVAL_S = 5.0
+DEFAULT_LOOP_WATCHDOG_INTERVAL_S = 30.0
+DEFAULT_LOOP_WATCHDOG_TIMEOUT_S = 10.0
+DEFAULT_LOOP_WATCHDOG_MAX_STRIKES = 3
 _HEARTBEAT_RELATIVE = ("state", "gateway.heartbeat")
 _WATCHDOG_DUMP_RELATIVE = ("logs", "gateway-shutdown-watchdog.log")
 
 
+class _LoopFloorTimerHandle:
+    """Cancelable owner for the currently scheduled selector floor timer."""
+
+    def __init__(self, loop: asyncio.AbstractEventLoop, interval: float):
+        self._loop = loop
+        self._interval = interval
+        self._cancelled = False
+        self._timer: Optional[asyncio.TimerHandle] = None
+        self._schedule()
+
+    def _schedule(self) -> None:
+        self._timer = self._loop.call_later(self._interval, self._tick)
+
+    def _tick(self) -> None:
+        if not self._cancelled:
+            self._schedule()
+
+    def cancel(self) -> None:
+        self._cancelled = True
+        if self._timer is not None:
+            self._timer.cancel()
+
+
+class _LoopLivenessWatchdogHandle:
+    """Small lifecycle handle for the daemon liveness thread."""
+
+    def __init__(self, stop_event: threading.Event, thread: threading.Thread):
+        self._stop_event = stop_event
+        self._thread = thread
+
+    def stop(self) -> None:
+        self._stop_event.set()
+
+    def join(self, timeout: Optional[float] = None) -> None:
+        self._thread.join(timeout=timeout)
+
+    def is_alive(self) -> bool:
+        return self._thread.is_alive()
+
+
+def _arm_loop_floor_timer(
+    loop: asyncio.AbstractEventLoop,
+    interval: float = DEFAULT_LOOP_FLOOR_TIMER_INTERVAL_S,
+) -> _LoopFloorTimerHandle:
+    """Keep at least one timer pending so selector waits remain bounded."""
+    try:
+        resolved_interval = float(interval)
+        if resolved_interval <= 0:
+            raise ValueError
+    except (TypeError, ValueError):
+        resolved_interval = DEFAULT_LOOP_FLOOR_TIMER_INTERVAL_S
+    return _LoopFloorTimerHandle(loop, resolved_interval)
+
+
+def start_loop_liveness_watchdog(
+    loop: asyncio.AbstractEventLoop,
+    *,
+    probe_interval: float = DEFAULT_LOOP_WATCHDOG_INTERVAL_S,
+    probe_timeout: float = DEFAULT_LOOP_WATCHDOG_TIMEOUT_S,
+    max_strikes: int = DEFAULT_LOOP_WATCHDOG_MAX_STRIKES,
+    exit_code: int = GATEWAY_SERVICE_RESTART_EXIT_CODE,
+) -> Optional[_LoopLivenessWatchdogHandle]:
+    """Start an out-of-loop watchdog that hard-exits after missed probes.
+
+    The guard is on by default; operators opt out with
+    ``gateway.loop_watchdog: false`` in config.yaml (enforced by the caller,
+    ``GatewayRunner._start_loop_liveness_guards`` — this module stays
+    config-agnostic so bare-loop tests can drive it directly).
+    """
+    interval = probe_interval
+    timeout = probe_timeout
+    strikes_limit = max_strikes
+    stop_event = threading.Event()
+
+    def _wait_for_probe(probe_event: threading.Event) -> Optional[bool]:
+        deadline = time.monotonic() + timeout
+        while True:
+            if stop_event.is_set():
+                return None
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return probe_event.is_set()
+            if probe_event.wait(timeout=min(remaining, 0.05)):
+                return True
+
+    def _watchdog() -> None:
+        strikes = 0
+        while not stop_event.wait(timeout=interval):
+            probe_event = threading.Event()
+            try:
+                loop.call_soon_threadsafe(probe_event.set)
+            except RuntimeError:
+                # A normally closed loop cannot be probed and no longer needs
+                # a process-liveness backstop.
+                return
+            except Exception:
+                logger.debug(
+                    "Failed to schedule gateway loop liveness probe", exc_info=True
+                )
+                return
+
+            responded = _wait_for_probe(probe_event)
+            if responded is None:
+                return
+            if responded:
+                strikes = 0
+                continue
+
+            if stop_event.is_set():
+                return
+            strikes += 1
+            if strikes < strikes_limit:
+                continue
+
+            if stop_event.is_set():
+                return
+            try:
+                logger.critical(
+                    "Gateway event loop missed %d consecutive liveness probes; "
+                    "dumping all thread stacks and exiting with code %d so the "
+                    "service supervisor can restart it.",
+                    strikes,
+                    exit_code,
+                )
+            except Exception:
+                pass
+            try:
+                faulthandler.dump_traceback(all_threads=True)
+            except Exception:
+                logger.debug("Loop liveness faulthandler dump failed", exc_info=True)
+            if stop_event.is_set():
+                return
+            os._exit(exit_code)
+            return
+
+    thread = threading.Thread(
+        target=_watchdog,
+        daemon=True,
+        name="gateway-loop-liveness-watchdog",
+    )
+    try:
+        thread.start()
+    except Exception:
+        logger.debug("Failed to start gateway loop liveness watchdog", exc_info=True)
+        return None
+    return _LoopLivenessWatchdogHandle(stop_event, thread)
+
+
 def _process_hermes_home() -> Path:
     """HERMES_HOME for process-level identity files (ignore profile overrides)."""
     val = os.environ.get("HERMES_HOME", "").strip()
diff --git a/gateway/slash_commands.py b/gateway/slash_commands.py
index 7a0fa6b5a5c..0ee92bb9f3b 100644
--- a/gateway/slash_commands.py
+++ b/gateway/slash_commands.py
@@ -32,7 +32,7 @@ from typing import Any, Optional, Union
 from agent.account_usage import fetch_account_usage, render_account_usage_lines
 from agent.i18n import t
 from agent.turn_context import extract_api_content_sidecar
-from gateway.config import HomeChannel, Platform, PlatformConfig
+from gateway.config import HomeChannel, Platform, PlatformConfig, persist_home_channel
 from gateway.platforms.base import EphemeralReply, MessageEvent, MessageType
 from gateway.session import (
     AsyncSessionStore,
@@ -1279,6 +1279,12 @@ class GatewaySlashCommandsMixin:
                 "chat_id": event.source.chat_id,
                 "chat_type": event.source.chat_type,
             }
+            if event.source.delivered_via_upstream_relay is True:
+                notify_data["delivered_via_upstream_relay"] = True
+                if event.source.user_id:
+                    notify_data["user_id"] = event.source.user_id
+                if event.source.scope_id:
+                    notify_data["scope_id"] = event.source.scope_id
             if event.source.thread_id:
                 notify_data["thread_id"] = event.source.thread_id
             if event.message_id:
@@ -2600,34 +2606,67 @@ class GatewaySlashCommandsMixin:
         platform_name = source.platform.value if source.platform else "unknown"
         chat_id = source.chat_id
         chat_name = source.chat_name or chat_id
+        if source.platform is None:
+            return t("gateway.set_home.save_failed", error="Missing logical platform")
+
+        via_relay = getattr(source, "delivered_via_upstream_relay", False) is True
+        if via_relay:
+            adapter_for_source = getattr(self, "_adapter_for_source", None)
+            relay_adapter = adapter_for_source(source) if callable(adapter_for_source) else None
+            fronts_platform = getattr(relay_adapter, "fronts_platform", None)
+            if (
+                source.platform in {None, Platform.LOCAL, Platform.RELAY}
+                or not getattr(source, "user_id", None)
+                or not callable(fronts_platform)
+                or not fronts_platform(source.platform)
+            ):
+                return t(
+                    "gateway.set_home.save_failed",
+                    error="Relay does not authenticate this logical home target",
+                )
 
-        env_key = _home_target_env_var(platform_name)
-        thread_env_key = _home_thread_env_var(platform_name)
         thread_id = source.thread_id
+        home = HomeChannel(
+            platform=source.platform,
+            chat_id=str(chat_id),
+            name=chat_name,
+            thread_id=str(thread_id) if thread_id else None,
+            user_id=(
+                str(source.user_id)
+                if getattr(source, "user_id", None)
+                else None
+            ),
+            scope_id=(
+                str(source.scope_id)
+                if getattr(source, "scope_id", None)
+                else None
+            ),
+        )
 
-        # Save to .env so it persists across restarts
+        # config.yaml is canonical because it can persist the authenticated
+        # logical-target provenance required by Relay after a restart.
         try:
-            from hermes_cli.config import save_env_value
-            save_env_value(env_key, str(chat_id))
-            # Keep thread/topic routing explicit and clear stale values when
-            # /sethome is run from the parent chat instead of a thread.
-            save_env_value(thread_env_key, str(thread_id or ""))
+            persist_home_channel(home, enabled_if_new=not via_relay)
         except Exception as e:
             return t("gateway.set_home.save_failed", error=e)
 
+        # Preserve legacy home env vars for existing cron/setup consumers.
+        env_key = _home_target_env_var(platform_name)
+        thread_env_key = _home_thread_env_var(platform_name)
+        try:
+            from hermes_cli.config import save_env_value
+            save_env_value(env_key, str(chat_id))
+            save_env_value(thread_env_key, str(thread_id or ""))
+        except Exception as e:
+            logger.warning("Home config saved but legacy env persistence failed: %s", e)
+
         # Keep the running gateway config in sync too. The pre-restart
-        # notification path reads self.config before the process reloads env.
-        if source.platform:
-            platform_config = self.config.platforms.setdefault(
-                source.platform,
-                PlatformConfig(enabled=True),
-            )
-            platform_config.home_channel = HomeChannel(
-                platform=source.platform,
-                chat_id=str(chat_id),
-                name=chat_name,
-                thread_id=str(thread_id) if thread_id else None,
-            )
+        # notification path reads self.config before the process reloads config.
+        platform_config = getattr(self, "config").platforms.setdefault(
+            source.platform,
+            PlatformConfig(enabled=not via_relay),
+        )
+        platform_config.home_channel = home
 
         return t("gateway.set_home.success", name=chat_name, chat_id=chat_id)
 
@@ -4923,7 +4962,7 @@ class GatewaySlashCommandsMixin:
         if event.message_id:
             pending["message_id"] = event.message_id
         _tmp_pending = pending_path.with_suffix(".tmp")
-        _tmp_pending.write_text(json.dumps(pending))
+        _tmp_pending.write_text(json.dumps(pending), encoding="utf-8")
         _tmp_pending.replace(pending_path)
         exit_code_path.unlink(missing_ok=True)
 
diff --git a/gateway/status.py b/gateway/status.py
index 93be87ed670..224dbf6d071 100644
--- a/gateway/status.py
+++ b/gateway/status.py
@@ -22,9 +22,10 @@ import sys
 import threading
 import time
 from datetime import datetime, timezone
+from dataclasses import dataclass
 from pathlib import Path
 from hermes_constants import get_hermes_home, _get_platform_default_hermes_home
-from typing import Any, NamedTuple, Optional
+from typing import Any, Callable, NamedTuple, Optional
 from utils import atomic_json_write
 
 if sys.platform == "win32":
@@ -258,7 +259,7 @@ def terminate_pid(pid: int, *, force: bool = False) -> None:
             result = subprocess.run(
                 ["taskkill", "/PID", str(pid), "/T", "/F"],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=10,
                 creationflags=windows_hide_flags(),
             )
@@ -344,7 +345,7 @@ def _read_process_cmdline(pid: int) -> Optional[str]:
             result = subprocess.run(
                 ["ps", "-p", str(pid), "-o", "command="],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=5,
             )
             if result.returncode == 0 and result.stdout.strip():
@@ -617,7 +618,7 @@ def _read_pid_record(pid_path: Optional[Path] = None) -> Optional[dict]:
         return None
 
     try:
-        raw = pid_path.read_text().strip()
+        raw = pid_path.read_text(encoding="utf-8").strip()
     except (OSError, UnicodeDecodeError):
         # File was deleted between exists() and read_text(), permission
         # flipped, or it holds non-UTF-8 / binary garbage.
@@ -827,7 +828,7 @@ def _pid_exists(pid: int) -> bool:
                 r = subprocess.run(
                     ["ps", "-o", "state=", "-p", str(int(pid))],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                     timeout=5,
                 )
                 if r.returncode == 0 and r.stdout.strip().startswith("Z"):
@@ -1138,6 +1139,147 @@ def derive_gateway_drainable(*, gateway_running: bool, gateway_state: Any) -> bo
     return bool(gateway_running) and gateway_state in _DRAINABLE_GATEWAY_STATES
 
 
+@dataclass(frozen=True)
+class GatewayLiveness:
+    """Resolved gateway liveness for one dashboard surface.
+
+    ``source`` records which rung of the ladder answered, purely for logging
+    and tests — never branch product behavior on it.
+
+    ``probe_error`` is True when a rung raised instead of answering. Callers
+    that must distinguish "the gateway is down" from "we could not tell"
+    need it: the dashboard renders a down badge either way, but the kanban
+    dispatcher warning deliberately fails OPEN on an unreadable probe so it
+    never cries wolf at a user whose gateway is fine.
+    """
+
+    running: bool
+    pid: Optional[int]
+    source: str
+    health_body: Optional[dict[str, Any]] = None
+    probe_error: bool = False
+
+
+def resolve_gateway_liveness(
+    *,
+    profile_dir: Optional[Path] = None,
+    runtime: Any = _UNSET,
+    health_probe: Optional[Callable[[], tuple[bool, Optional[dict[str, Any]]]]] = None,
+    use_cache: bool = True,
+    pid_probe: Optional[Callable[..., Optional[int]]] = None,
+    runtime_reader: Optional[Callable[..., Optional[dict[str, Any]]]] = None,
+    runtime_pid_probe: Optional[Callable[..., Optional[int]]] = None,
+) -> GatewayLiveness:
+    """Single source of truth for "is the gateway up?" across dashboard surfaces.
+
+    Before this existed, ``/api/status`` and ``/api/messaging/platforms``
+    each open-coded their own ladder and disagreed on the same page load —
+    the sidebar read "running" while the Channels page rendered "The gateway
+    is not running."  Three deployments hit it: a cross-container gateway
+    (only ``/api/status`` ran the HTTP health probe), a profile-scoped
+    dashboard (only ``/api/status`` passed the profile's paths, so messaging
+    borrowed another profile's runtime state — issue #71211), and a
+    launch-service-managed gateway with no PID file (only some callers used
+    the runtime-status fallback).
+
+    The ladder, most to least authoritative:
+
+    1. **PID file + runtime lock** — scoped to ``profile_dir`` when given.
+       Cached by default (``use_cache``); high-frequency polling must not
+       churn file descriptors re-flocking ``gateway.lock`` on every request.
+    2. **HTTP health probe** — supplied by the caller (the dashboard owns the
+       deprecated ``GATEWAY_HEALTH_URL`` config).  Covers the gateway running
+       in another container where no local PID is visible.
+    3. **Runtime status PID** — validated against the live process table with
+       ``expected_home`` so a recycled PID belonging to a *different*
+       profile's gateway is never reported as this one's.
+
+    Rung 3 only ever runs against a LOCAL state record: the probe body's PID
+    belongs to another host, and ``os.kill``-ing a remote PID is both wrong
+    and trips the test live-system guard.  Pass ``runtime`` when the caller
+    has already read the state file so it isn't read twice per request.
+
+    ``pid_probe`` / ``runtime_reader`` / ``runtime_pid_probe`` let a caller
+    inject its own module-level references to these helpers.  The dashboard
+    passes its ``hermes_cli.web_server`` bindings so the long-standing
+    monkeypatch seam in the test-suite keeps working; production callers
+    leave them ``None`` and get this module's implementations.
+    """
+    _pid_probe = pid_probe or (
+        get_running_pid_cached if use_cache else get_running_pid
+    )
+    _runtime_reader = runtime_reader or read_runtime_status
+    _runtime_pid_probe = runtime_pid_probe or get_runtime_status_running_pid
+
+    pid_path = (profile_dir / "gateway.pid") if profile_dir is not None else None
+    probe_error = False
+    try:
+        # Plain zero-arg call when unscoped: several callers monkeypatch these
+        # probes with zero-arg lambdas, and /api/status's cache signature is
+        # keyed on the exact call shape.
+        pid = _pid_probe(pid_path) if pid_path is not None else _pid_probe()
+    except Exception:
+        # A probe failure (permissions, exotic /proc, Windows quirks) must
+        # degrade to the next rung, never 500 a status endpoint. Recorded in
+        # probe_error so fail-open callers can tell "down" from "unknown".
+        pid = None
+        probe_error = True
+    if pid is not None:
+        return GatewayLiveness(running=True, pid=pid, source="pid")
+
+    health_body: Optional[dict[str, Any]] = None
+    if health_probe is not None:
+        try:
+            alive, health_body = health_probe()
+        except Exception:
+            alive, health_body = False, None
+            probe_error = True
+        if alive:
+            # Display-only PID: it belongs to the remote container.
+            remote_pid = health_body.get("pid") if health_body else None
+            return GatewayLiveness(
+                running=True,
+                pid=remote_pid,
+                source="health",
+                health_body=health_body,
+            )
+
+    if runtime is _UNSET:
+        try:
+            runtime = (
+                _runtime_reader(path=profile_dir / "gateway_state.json")
+                if profile_dir is not None
+                else _runtime_reader()
+            )
+        except Exception:
+            runtime = None
+            probe_error = True
+    try:
+        runtime_pid = (
+            _runtime_pid_probe(runtime, expected_home=profile_dir)
+            if profile_dir is not None
+            else _runtime_pid_probe(runtime)
+        )
+    except Exception:
+        runtime_pid = None
+        probe_error = True
+    if runtime_pid is not None:
+        return GatewayLiveness(
+            running=True,
+            pid=runtime_pid,
+            source="runtime_status",
+            health_body=health_body,
+        )
+
+    return GatewayLiveness(
+        running=False,
+        pid=None,
+        source="none",
+        health_body=health_body,
+        probe_error=probe_error,
+    )
+
+
 def get_runtime_status_running_pid(
     runtime: Optional[dict[str, Any]] = None,
     *,
diff --git a/hermes_bootstrap.py b/hermes_bootstrap.py
index ae23cc97629..c0622bb0d96 100644
--- a/hermes_bootstrap.py
+++ b/hermes_bootstrap.py
@@ -122,6 +122,49 @@ def apply_windows_utf8_bootstrap() -> bool:
     return True
 
 
+def suppress_platform_ver_console() -> None:
+    """Stub ``platform._syscmd_ver`` on Windows — decode-crash + flash guard.
+
+    CPython's ``platform.win32_ver()`` (reached via ``platform.uname()`` /
+    ``platform.platform()``, which the OpenAI SDK touches for its
+    platform headers) shells out ``cmd /c ver``. Two failure modes:
+
+    - **Console flash**: the ``check_output(..., shell=True)`` call has no
+      ``CREATE_NO_WINDOW``, so a windowless parent (pythonw gateway, slash
+      workers, kanban workers) flashes a visible console per call.
+    - **UnicodeDecodeError on Python 3.11.0/3.11.1**: those micros lack
+      CPython's ``encoding="locale"`` fix (added 3.11.2), so under PEP 540
+      UTF-8 mode (which we enable above) the ``ver`` output — OEM code page
+      bytes on localized Windows — is strict-utf-8 decoded and raises,
+      crashing ``platform.platform()`` in any process that inherits
+      ``PYTHONUTF8=1`` (issue #69413).
+
+    Stubbing ``_syscmd_ver`` to return its inputs makes ``win32_ver()`` hit
+    its documented fallback and read the version from
+    ``sys.getwindowsversion()`` — same data, in-process, no subprocess.
+    Mirrors ``hermes_cli._subprocess_compat.suppress_platform_ver_console``
+    (kept there for callers that don't import bootstrap); double
+    application is harmless. Lives here so EVERY entry point gets it —
+    ``tui_gateway/slash_worker.py``, ``tui_gateway/entry.py``,
+    ``run_agent.py``, ``batch_runner.py``, and ``cli.py`` import only
+    ``hermes_bootstrap``, never ``hermes_cli.main``.
+    """
+    if not _IS_WINDOWS:
+        return
+    try:
+        import platform
+
+        if hasattr(platform, "_syscmd_ver"):
+            def _quiet_syscmd_ver(system="", release="", version="",
+                                  supported_platforms=("win32", "win16", "dos")):
+                return system, release, version
+
+            platform._syscmd_ver = _quiet_syscmd_ver
+    except Exception:
+        # Hardening only — never let it break an entry point.
+        pass
+
+
 def harden_import_path(src_root: str | None = None) -> None:
     """Stop a package in the current directory from shadowing Hermes modules.
 
@@ -188,6 +231,7 @@ def activate_durable_lazy_target() -> None:
 # the very top of their module, before importing anything else.  The
 # import side effect does the right thing.
 apply_windows_utf8_bootstrap()
+suppress_platform_ver_console()
 
 # Activate the durable lazy-install target (immutable Docker images) so
 # packages installed into the data volume on a previous run are importable
diff --git a/hermes_cli/_early_recovery.py b/hermes_cli/_early_recovery.py
index 428232d8573..0a19e58498b 100644
--- a/hermes_cli/_early_recovery.py
+++ b/hermes_cli/_early_recovery.py
@@ -92,12 +92,37 @@ def _pinned_specs(packages: list[str], project_root: Path) -> list[str]:
     return [name_to_spec.get(pkg.lower(), pkg) for pkg in packages]
 
 
+def _certifi_bundle_broken() -> bool:
+    """True when certifi imports but its ``cacert.pem`` is missing/corrupt.
+
+    A brew Python upgrade or an interrupted venv rebuild can leave certifi's
+    distribution metadata (and even the module) intact while the bundled
+    ``cacert.pem`` is gone or a dangling symlink — every TLS connection then
+    fails with an opaque ``Could not find a suitable TLS CA certificate
+    bundle`` from deep inside httpx/requests (#29866). An attribute probe
+    alone passes in that state, so validate the bundle path itself.
+    """
+    try:
+        import certifi
+
+        bundle = Path(certifi.where())
+        # <1 KiB cannot hold a single PEM certificate — treat as corrupt.
+        return not bundle.is_file() or bundle.stat().st_size < 1024
+    except Exception:
+        # Import failure is caught by the regular probe table; a failure to
+        # even stat is treated as broken.
+        return True
+
+
 def _probe_broken_packages() -> list[str]:
     """Import-probe the fragile core packages in THIS process.
 
     Returns repair package names (deduped, probe order) for modules that fail
     to import or lack their sentinel attribute.  Failed imports leave nothing
     in ``sys.modules``, so a post-repair retry in the same process works.
+
+    certifi additionally gets a bundle-file check: the module can import
+    cleanly while ``cacert.pem`` is missing (#29866).
     """
     broken: list[str] = []
     for mod_name, attr in LAZY_REFRESH_IMPORT_PROBES:
@@ -105,6 +130,8 @@ def _probe_broken_packages() -> list[str]:
             mod = importlib.import_module(mod_name)
             if not hasattr(mod, attr):
                 raise ImportError(f"{mod_name} missing {attr}")
+            if mod_name == "certifi" and _certifi_bundle_broken():
+                raise ImportError("certifi cacert.pem missing or corrupt")
         except Exception:
             pkg = LAZY_REFRESH_REPAIR_PACKAGES.get(mod_name)
             if pkg and pkg not in broken:
@@ -131,7 +158,7 @@ def _run_repair_install(specs: list[str], project_root: Path) -> bool:
             [sys.executable, "-m", "pip", "install", "--force-reinstall", *specs],
             cwd=project_root,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
     except Exception as exc:
         print(f"  ✗ Early venv repair could not run pip: {exc}", file=sys.stderr)
diff --git a/hermes_cli/_subprocess_compat.py b/hermes_cli/_subprocess_compat.py
index 00358fd3bb7..339adf87daf 100644
--- a/hermes_cli/_subprocess_compat.py
+++ b/hermes_cli/_subprocess_compat.py
@@ -36,6 +36,7 @@ from typing import Sequence
 __all__ = [
     "IS_WINDOWS",
     "resolve_node_command",
+    "suppress_platform_ver_console",
     "windows_detach_flags",
     "windows_detach_flags_without_breakaway",
     "windows_hide_flags",
@@ -226,6 +227,43 @@ def windows_hide_flags() -> int:
     return _CREATE_NO_WINDOW
 
 
+def suppress_platform_ver_console() -> None:
+    """Stub out ``platform._syscmd_ver`` on Windows so it can never flash a
+    console window.  No-op on non-Windows.
+
+    CPython's ``platform.win32_ver()`` — reached by ``platform.uname()``,
+    ``platform.version()``, and ``platform.platform()`` — unconditionally
+    shells out ``cmd /c ver`` via ``subprocess.check_output(..., shell=True)``
+    with no ``CREATE_NO_WINDOW``.  From a windowless parent (the pythonw
+    gateway and every kanban worker it spawns) that allocates a fresh
+    *visible* console: one flashing ``cmd`` window per process, triggered by
+    any dependency that merely touches ``platform.uname()`` at import time.
+
+    With ``_syscmd_ver`` stubbed to return its inputs, ``win32_ver()`` hits
+    the documented ``ValueError`` fallback and reads the version from
+    ``sys.getwindowsversion().platform_version`` — same information, queried
+    in-process, no subprocess, no window.  Verified equivalent on
+    CPython 3.11 (``platform()`` → ``Windows-10-10.0.xxxxx-SP0`` either way).
+
+    Call early, before heavyweight imports — the flash typically happens
+    during a dependency's import, not from Hermes' own code.
+    """
+    if not IS_WINDOWS:
+        return
+    try:
+        import platform
+
+        if hasattr(platform, "_syscmd_ver"):
+            def _quiet_syscmd_ver(system="", release="", version="",
+                                  supported_platforms=("win32", "win16", "dos")):
+                return system, release, version
+
+            platform._syscmd_ver = _quiet_syscmd_ver
+    except Exception:
+        # Purely cosmetic hardening — never let it break startup.
+        pass
+
+
 def windows_detach_popen_kwargs() -> dict:
     """Return a dict of Popen kwargs that detach a child on Windows and
     fall back to the POSIX equivalent (``start_new_session=True``) on
diff --git a/hermes_cli/auth.py b/hermes_cli/auth.py
index 011cf817aeb..0400e7678ff 100644
--- a/hermes_cli/auth.py
+++ b/hermes_cli/auth.py
@@ -434,6 +434,17 @@ PROVIDER_REGISTRY: Dict[str, ProviderConfig] = {
         api_key_env_vars=(),
         base_url_env_var="BEDROCK_BASE_URL",
     ),
+    "vertex": ProviderConfig(
+        id="vertex",
+        name="Google Vertex AI",
+        auth_type="vertex",
+        # No static inference_base_url: Vertex's endpoint is computed per
+        # request from project_id + region (agent/vertex_adapter.py's
+        # build_vertex_base_url), not a fixed host like the other entries.
+        inference_base_url="",
+        api_key_env_vars=(),  # OAuth2 (service-account JSON / ADC), not a key
+        base_url_env_var="",
+    ),
     "azure-foundry": ProviderConfig(
         id="azure-foundry",
         name="Azure Foundry",
@@ -1112,7 +1123,7 @@ def _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]:
         return {"version": AUTH_STORE_VERSION, "providers": {}}
 
     try:
-        raw = json.loads(auth_file.read_text())
+        raw = json.loads(auth_file.read_text(encoding="utf-8"))
     except Exception as exc:
         corrupt_path = auth_file.with_suffix(".json.corrupt")
         try:
@@ -3815,7 +3826,7 @@ def _import_codex_cli_tokens() -> Optional[Dict[str, str]]:
     if not auth_path.is_file():
         return None
     try:
-        payload = json.loads(auth_path.read_text())
+        payload = json.loads(auth_path.read_text(encoding="utf-8"))
         tokens = payload.get("tokens")
         if not isinstance(tokens, dict):
             return None
@@ -5250,7 +5261,7 @@ def _read_shared_nous_state() -> Optional[Dict[str, Any]]:
     if not path.is_file():
         return None
     try:
-        payload = json.loads(path.read_text())
+        payload = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, ValueError) as exc:
         logger.debug("Shared Nous auth store at %s is unreadable: %s", path, exc)
         return None
diff --git a/hermes_cli/backup.py b/hermes_cli/backup.py
index 2a25217160c..3a5b7cd4d3c 100644
--- a/hermes_cli/backup.py
+++ b/hermes_cli/backup.py
@@ -283,6 +283,211 @@ def _safe_copy_db(src: Path, dst: Path) -> bool:
                     pass
 
 
+def is_zeroed_sqlite_file(
+    path: Path, *, probe_bytes: int = 100, force: bool = False
+) -> bool:
+    """True when *path* looks like the #68474 zeroed-state.db signature.
+
+    Signature: size > 0, first *probe_bytes* are all NUL (no ``SQLite format 3``
+    header). Used at SessionDB open and for snapshot diagnostics so a silent
+    all-zero file becomes a guided recovery instead of a generic failure.
+    """
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return False
+    if size <= 0:
+        return False
+    from hermes_cli.sqlite_safe_read import read_header_bytes_preopen
+
+    head = read_header_bytes_preopen(
+        path, length=max(16, probe_bytes), force=force
+    )
+    if not head:
+        return False
+    if head.startswith(b"SQLite format 3"):
+        return False
+    return all(byte == 0 for byte in head)
+
+
+
+# ---------------------------------------------------------------------------
+# SQLite integrity verification
+# ---------------------------------------------------------------------------
+
+_SQLITE_HEADER = b"SQLite format 3\0"
+
+# Default ceiling above which ``PRAGMA integrity_check`` is skipped in favour
+# of the (O(1)) header + structural probe. ``integrity_check`` walks every
+# b-tree page in the file, so its cost scales with database size: on a 30 GB
+# state.db it runs for many minutes of pegged CPU with no output, which reads
+# to the user as a hung `hermes update` (#70553 follow-up). Sessions databases
+# in the tens of GB are normal for heavy users, so the size-unbounded check is
+# never an acceptable default on the update path.
+DEFAULT_INTEGRITY_CHECK_MAX_BYTES = 2 << 30  # 2 GiB
+
+
+def verify_sqlite_integrity(
+    path: Path,
+    *,
+    check_header: bool = True,
+    run_pragma: bool = True,
+    max_bytes: int = DEFAULT_INTEGRITY_CHECK_MAX_BYTES,
+) -> dict:
+    """Verify that a SQLite database at *path* is intact.
+
+    Checks, in order:
+      1. File exists and has an expected minimum size.
+      2. SQLite header magic bytes are present.
+      3. For files at or under ``max_bytes``, a read-only
+         ``PRAGMA integrity_check``. For larger files, a cheap structural
+         probe (schema read) instead — see ``max_bytes``.
+
+    Args:
+        path: Path to the database file.
+        check_header: When true (default), verify the SQLite header magic.
+        run_pragma: When true (default), run ``PRAGMA integrity_check`` via
+            a read-only connection and verify the result is ``"ok"``.
+        max_bytes: Size ceiling for the full ``PRAGMA integrity_check``.
+            Files larger than this fall back to the header check plus a
+            cheap structural probe, because ``integrity_check`` pages
+            through the ENTIRE file — minutes of silent pegged CPU on a
+            multi-GB database. Defaults to
+            :data:`DEFAULT_INTEGRITY_CHECK_MAX_BYTES` (2 GiB); pass ``0``
+            to force the full check regardless of size.
+
+    Returns:
+        A dict with keys:
+          - ``valid`` (bool): true when all requested checks passed.
+          - ``message`` (str): human-readable outcome or error detail.
+          - ``size`` (int | None): file size in bytes, or None if stat failed.
+    """
+    result: dict = {"valid": False, "message": "", "size": None}
+
+    try:
+        st = path.stat()
+    except FileNotFoundError:
+        result["message"] = f"not found: {path}"
+        return result
+    except OSError as exc:
+        result["message"] = f"cannot stat: {exc}"
+        return result
+
+    result["size"] = st.st_size
+
+    if st.st_size < 100:  # SQLite minimum viable size (header + 1 page)
+        result["message"] = f"too small ({st.st_size} bytes) to be a valid SQLite database"
+        return result
+
+    oversized = max_bytes > 0 and st.st_size > max_bytes
+
+    if check_header:
+        # Byte-level read: refused when a live connection exists, because
+        # close() would cancel this process's POSIX locks on the file (see
+        # hermes_cli.sqlite_safe_read). Verification targets snapshots and
+        # backup artifacts, which are offline by construction.
+        from hermes_cli.sqlite_safe_read import read_header_bytes_preopen
+
+        head = read_header_bytes_preopen(path, length=len(_SQLITE_HEADER))
+        if head is None:
+            result["valid"] = False
+            result["message"] = "cannot read header"
+            return result
+        if head != _SQLITE_HEADER:
+            result["valid"] = False
+            result["message"] = (
+                f"missing SQLite header magic (got {head[:16].hex()!r})"
+            )
+            return result
+
+    if oversized:
+        # Too large to page through PRAGMA integrity_check (which is O(file
+        # size) and would peg a CPU for minutes on a multi-GB state.db).
+        # Fall back to a cheap O(1) structural probe: the header check above
+        # catches the #68474 zeroed signature, and opening the DB read-only
+        # plus reading sqlite_master + the page geometry catches the
+        # malformed-schema and truncated-header-page classes. Both are
+        # constant-time — they parse the schema, they do not walk the data.
+        run_pragma = False
+        probe = None
+        try:
+            probe = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=1.0)
+            probe.execute("PRAGMA schema_version").fetchone()
+            probe.execute("SELECT count(*) FROM sqlite_master").fetchone()
+            result["valid"] = True
+            result["message"] = (
+                f"size {st.st_size:,} bytes exceeds max_bytes {max_bytes:,}; "
+                "skipped PRAGMA integrity_check (header + schema probe passed)"
+            )
+        except sqlite3.DatabaseError as exc:
+            result["valid"] = False
+            result["message"] = f"schema probe failed: {exc}"
+            return result
+        except Exception as exc:
+            result["valid"] = False
+            result["message"] = f"schema probe error: {exc}"
+            return result
+        finally:
+            if probe is not None:
+                try:
+                    probe.close()
+                except Exception:
+                    pass
+
+    if run_pragma:
+        conn = None
+        try:
+            conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=1.0)
+            cursor = conn.execute("PRAGMA integrity_check")
+            rows = cursor.fetchall()
+            if len(rows) == 1 and rows[0][0] == "ok":
+                result["valid"] = True
+                result["message"] = "integrity check passed"
+                return result
+            errors = [str(r[0]) for r in rows]
+            result["message"] = f"integrity check failed: {'; '.join(errors[:5])}"
+            return result
+        except sqlite3.DatabaseError as exc:
+            result["message"] = f"cannot open database: {exc}"
+            return result
+        except Exception as exc:
+            result["message"] = f"integrity check error: {exc}"
+            return result
+        finally:
+            if conn is not None:
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+
+    result["valid"] = True
+    if not result["message"]:
+        result["message"] = "header check passed"
+    return result
+
+
+def copy_db_and_verify(src: Path, dst: Path) -> bool:
+    """Like :func:`_safe_copy_db` but verifies the destination after copy.
+
+    Returns True only when the copy succeeded AND the destination is valid
+    SQLite (header + integrity check). Verification honours the default
+    size ceiling — a multi-GB destination gets the header + schema probe
+    rather than a full ``PRAGMA integrity_check`` that would page through
+    the whole file.
+    """
+    if not _safe_copy_db(src, dst):
+        return False
+    integrity = verify_sqlite_integrity(dst, run_pragma=True)
+    if not integrity.get("valid"):
+        try:
+            dst.unlink(missing_ok=True)
+        except OSError:
+            pass
+        logger.warning("Backup of %s failed integrity verification: %s", src, integrity.get("message"))
+        return False
+    return True
+
+
 # ---------------------------------------------------------------------------
 # Backup
 # ---------------------------------------------------------------------------
@@ -858,6 +1063,12 @@ def create_quick_snapshot(
     snap_dir.mkdir(parents=True, exist_ok=True)
 
     manifest: Dict[str, int] = {}  # rel_path -> file size
+    failed_dbs: list[str] = []  # present *.db that could not be snapshotted
+    # #68805: track protected DB files skipped for size — they are snapshot
+    # incompleteness just like a failed copy, so pruning must be suppressed
+    # to preserve the older complete snapshot that may contain the only
+    # recoverable database.
+    oversized_skipped: list[str] = []
 
     for rel in _QUICK_STATE_FILES:
         src = home / rel
@@ -878,6 +1089,8 @@ def create_quick_snapshot(
                 if "/workspaces/" in f"/{sub_rel}/" or "/attachments/" in f"/{sub_rel}/":
                     continue
                 if _too_large(sub, sub_rel):
+                    if sub.suffix == ".db":
+                        oversized_skipped.append(sub_rel)
                     continue
                 dst = snap_dir / sub_rel
                 dst.parent.mkdir(parents=True, exist_ok=True)
@@ -887,6 +1100,16 @@ def create_quick_snapshot(
                     # snapshot time) is captured consistently.
                     if sub.suffix == ".db":
                         if not _safe_copy_db(sub, dst):
+                            failed_dbs.append(sub_rel)
+                            print(
+                                f"  ⚠ Snapshot: SQLite safe copy FAILED for {sub_rel} "
+                                f"— file may be locked or corrupted"
+                            )
+                            if is_zeroed_sqlite_file(sub):
+                                print(
+                                    f"  ⚠ Snapshot: {sub_rel} looks ZEROED "
+                                    f"(no SQLite header; {sub.stat().st_size} bytes of NULs?)"
+                                )
                             continue
                     else:
                         shutil.copy2(sub, dst)
@@ -899,6 +1122,8 @@ def create_quick_snapshot(
             continue
 
         if _too_large(src, rel):
+            if src.suffix == ".db":
+                oversized_skipped.append(rel)
             continue
 
         dst = snap_dir / rel
@@ -907,6 +1132,16 @@ def create_quick_snapshot(
         try:
             if src.suffix == ".db":
                 if not _safe_copy_db(src, dst):
+                    failed_dbs.append(rel)
+                    print(
+                        f"  ⚠ Snapshot: SQLite safe copy FAILED for {rel} "
+                        f"— file may be locked or corrupted"
+                    )
+                    if is_zeroed_sqlite_file(src):
+                        print(
+                            f"  ⚠ Snapshot: {rel} looks ZEROED "
+                            f"(no SQLite header; {src.stat().st_size} bytes)"
+                        )
                     continue
             else:
                 shutil.copy2(src, dst)
@@ -914,8 +1149,31 @@ def create_quick_snapshot(
         except (OSError, PermissionError) as exc:
             logger.warning("Could not snapshot %s: %s", rel, exc)
 
+    if failed_dbs:
+        # Critical: update path used to log-and-continue with exit 0, so a
+        # missing state.db backup looked like a successful pre-update snapshot
+        # (#68474). Surface this on stdout where operators actually look.
+        print(
+            "  ⚠ CRITICAL: could not snapshot DB file(s): "
+            + ", ".join(failed_dbs)
+        )
+        print(
+            "  ⚠ If sessions disappear after update, check "
+            f"{root} and run: hermes snapshot list"
+        )
+        logger.error(
+            "Quick snapshot failed to capture DB file(s): %s",
+            ", ".join(failed_dbs),
+        )
+
     if not manifest:
         shutil.rmtree(snap_dir, ignore_errors=True)
+        if failed_dbs:
+            # Distinguish "nothing to snapshot" from "state.db present but unreadable"
+            print(
+                "  ⚠ Snapshot aborted: no files captured "
+                f"(failed DBs: {', '.join(failed_dbs)})"
+            )
         return None
 
     # Write manifest
@@ -926,6 +1184,8 @@ def create_quick_snapshot(
         "file_count": len(manifest),
         "total_size": sum(manifest.values()),
         "files": manifest,
+        "failed_dbs": failed_dbs,
+        "oversized_skipped": oversized_skipped,
     }
     with open(snap_dir / "manifest.json", "w", encoding="utf-8") as f:
         json.dump(meta, f, indent=2)
@@ -933,7 +1193,28 @@ def create_quick_snapshot(
     # Auto-prune. Defaults preserve historical manual /snapshot behavior; callers
     # with known high-churn safety snapshots (for example pre-update) can pass a
     # smaller keep value so large state.db copies do not accumulate indefinitely.
-    _prune_quick_snapshots(root, keep=_QUICK_DEFAULT_KEEP if keep is None else keep)
+    # #68805 review: skip pruning when a present DB failed to capture OR was
+    # skipped for size — either way the snapshot is incomplete and the older
+    # snapshot may contain the only recoverable database.
+    incomplete = failed_dbs or oversized_skipped
+    if not incomplete:
+        _prune_quick_snapshots(root, keep=_QUICK_DEFAULT_KEEP if keep is None else keep)
+    else:
+        if oversized_skipped:
+            print(
+                "  ⚠ Skipping snapshot prune: DB file(s) skipped for size: "
+                + ", ".join(oversized_skipped)
+            )
+            logger.warning(
+                "Quick snapshot skipped oversized DB file(s): %s",
+                ", ".join(oversized_skipped),
+            )
+        logger.warning(
+            "Skipping snapshot prune because %d DB(s) failed to capture "
+            "and/or %d were oversized — preserving older snapshots as "
+            "recovery source",
+            len(failed_dbs), len(oversized_skipped),
+        )
 
     logger.info("State snapshot created: %s (%d files)", snap_id, len(manifest))
     return snap_id
diff --git a/hermes_cli/banner.py b/hermes_cli/banner.py
index e487475f62b..08e2ceeb1fa 100644
--- a/hermes_cli/banner.py
+++ b/hermes_cli/banner.py
@@ -160,6 +160,11 @@ def _git_stdout(args: list[str], *, cwd: Path, timeout: int = 5) -> Optional[str
             ["git", *args],
             capture_output=True,
             text=True,
+            # git output is UTF-8; on Windows text=True defaults to the ANSI
+            # code page and bytes like 0x90 (3rd byte of 🐛 in a commit
+            # subject) crash the stdlib reader thread (#52649).
+            encoding="utf-8",
+            errors="replace",
             timeout=timeout,
             cwd=str(cwd),
         )
@@ -179,7 +184,8 @@ def _check_via_rev(local_rev: str) -> Optional[int]:
     try:
         result = subprocess.run(
             ["git", "ls-remote", _UPSTREAM_REPO_URL, "refs/heads/main"],
-            capture_output=True, text=True, timeout=10,
+            capture_output=True, text=True, encoding="utf-8", errors="replace",
+            timeout=10,
         )
     except Exception:
         return None
@@ -241,7 +247,8 @@ def _check_via_local_git(repo_dir: Path) -> Optional[int]:
     try:
         result = subprocess.run(
             ["git", "rev-list", "--count", "HEAD..origin/main"],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding="utf-8", errors="replace",
+            timeout=5,
             cwd=str(repo_dir),
         )
         if result.returncode == 0:
@@ -285,7 +292,7 @@ def check_for_updates() -> Optional[int]:
     now = time.time()
     try:
         if cache_file.exists():
-            cached = json.loads(cache_file.read_text())
+            cached = json.loads(cache_file.read_text(encoding="utf-8"))
             if (
                 now - cached.get("ts", 0) < _UPDATE_CHECK_CACHE_SECONDS
                 and cached.get("rev") == embedded_rev
@@ -314,7 +321,8 @@ def check_for_updates() -> Optional[int]:
 
     try:
         cache_file.write_text(
-            json.dumps({"ts": now, "behind": behind, "rev": embedded_rev, "ver": VERSION})
+            json.dumps({"ts": now, "behind": behind, "rev": embedded_rev, "ver": VERSION}),
+            encoding="utf-8",
         )
     except Exception:
         pass
@@ -343,6 +351,8 @@ def _git_short_hash(repo_dir: Path, rev: str) -> Optional[str]:
             ["git", "rev-parse", "--short=8", rev],
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=5,
             cwd=str(repo_dir),
         )
@@ -399,6 +409,8 @@ def get_git_banner_state(repo_dir: Optional[Path] = None) -> Optional[dict]:
             ["git", "rev-list", "--count", "origin/main..HEAD"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=5,
             cwd=str(repo_dir),
         )
@@ -435,6 +447,8 @@ def get_latest_release_tag(repo_dir: Optional[Path] = None) -> Optional[tuple]:
             ["git", "describe", "--tags", "--abbrev=0"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=3,
             cwd=str(repo_dir),
         )
diff --git a/hermes_cli/checkpoints.py b/hermes_cli/checkpoints.py
index 2975553ae49..5e9cbe1bdc9 100644
--- a/hermes_cli/checkpoints.py
+++ b/hermes_cli/checkpoints.py
@@ -25,7 +25,7 @@ import argparse
 import time
 from datetime import datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, Optional
 
 
 def _fmt_bytes(n: int) -> str:
@@ -109,21 +109,66 @@ def cmd_list(args: argparse.Namespace) -> int:
 
 
 def cmd_prune(args: argparse.Namespace) -> int:
-    from tools.checkpoint_manager import prune_checkpoints
+    from tools.checkpoint_manager import prune_checkpoints, store_status
 
     retention_days = args.retention_days
     max_size_mb = args.max_size_mb
+    delete_orphans = not args.keep_orphans
+
+    # When set, restricts orphan deletion to exactly the identities shown in
+    # the confirmation preview below (v2 project hashes / pre-v2 shadow repo
+    # paths). `None` means "no restriction" — used for --force, where there
+    # is no preview to bind to.
+    orphan_allowlist: Optional[set] = None
+
+    if delete_orphans and not args.force:
+        info = store_status()
+        orphans = [
+            p for p in info.get("projects", [])
+            if not p.get("exists")
+        ]
+        pre_v2_orphans = [
+            p for p in info.get("pre_v2_projects", [])
+            if not p.get("exists")
+        ]
+        if orphans or pre_v2_orphans:
+            print(f"This will permanently delete {len(orphans) + len(pre_v2_orphans)} "
+                  "orphan checkpoint project(s) whose workdir is not currently reachable:")
+            print()
+            for p in orphans:
+                wd = p.get("workdir") or "(unknown)"
+                print(f"  {wd}  ({p.get('commits', 0)} commit(s))")
+            for p in pre_v2_orphans:
+                wd = p.get("workdir") or "(unknown)"
+                print(f"  {wd}  (pre-v2 shadow repo)")
+            print()
+            print("A workdir can be unreachable because the project was deleted,")
+            print("or because an external volume / network share / VPN is down.")
+            print("Pass --keep-orphans to prune stale entries only.")
+            if not _confirm("Delete these orphan projects?"):
+                print("Aborted.")
+                return 1
+        # Bind the deletion to exactly what was just displayed (and, when
+        # non-empty, confirmed) — a project that becomes orphaned only
+        # *after* this preview (e.g. its workdir disappears while waiting on
+        # input()) must not be swept up under this same run. This is set
+        # unconditionally for every non-force run: an EMPTY preview binds to
+        # an EMPTY allowlist, so a zero-orphan preview can never authorize
+        # deletion of orphans discovered by the later rescan.
+        orphan_allowlist = {p["hash"] for p in orphans}
+        orphan_allowlist.update(p["path"] for p in pre_v2_orphans)
 
     print("Pruning checkpoint store…")
     print(f"  retention_days:    {retention_days}")
-    print(f"  delete_orphans:    {not args.keep_orphans}")
+    print(f"  delete_orphans:    {delete_orphans}")
     print(f"  max_total_size_mb: {max_size_mb}")
     print()
 
     result = prune_checkpoints(
         retention_days=retention_days,
-        delete_orphans=not args.keep_orphans,
+        delete_orphans=delete_orphans,
         max_total_size_mb=max_size_mb,
+        orphan_allowlist=orphan_allowlist,
     )
     print(f"Scanned:         {result['scanned']}")
     print(f"Deleted orphan:  {result['deleted_orphan']}")
@@ -225,6 +270,8 @@ def register_cli(parser: argparse.ArgumentParser) -> None:
                               "per project until total size <= this (default 500)")
     p_prune.add_argument("--keep-orphans", action="store_true",
                          help="Skip deleting projects whose workdir no longer exists")
+    p_prune.add_argument("-f", "--force", action="store_true",
+                         help="Skip the orphan-deletion confirmation prompt")
     p_prune.set_defaults(func=cmd_prune)
 
     p_clear = subs.add_parser(
diff --git a/hermes_cli/claw.py b/hermes_cli/claw.py
index 792e35c1683..8f58d9520e6 100644
--- a/hermes_cli/claw.py
+++ b/hermes_cli/claw.py
@@ -68,7 +68,7 @@ def _detect_openclaw_processes() -> list[str]:
         try:
             result = subprocess.run(
                 ["systemctl", "--user", "is-active", "openclaw-gateway.service"],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             )
             if result.stdout.strip() == "active":
                 found.append("systemd service: openclaw-gateway.service")
@@ -81,7 +81,7 @@ def _detect_openclaw_processes() -> list[str]:
             for exe in ("openclaw.exe", "clawd.exe"):
                 result = subprocess.run(
                     ["tasklist", "/FI", f"IMAGENAME eq {exe}"],
-                    capture_output=True, text=True, timeout=5,
+                    capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
                 )
                 if exe in result.stdout.lower():
                     found.append(f"process: {exe}")
@@ -95,7 +95,7 @@ def _detect_openclaw_processes() -> list[str]:
             )
             result = subprocess.run(
                 ["powershell", "-NoProfile", "-Command", ps_cmd],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             )
             if result.stdout.strip():
                 found.append(f"node.exe process with openclaw in command line (PID {result.stdout.strip()})")
@@ -105,7 +105,7 @@ def _detect_openclaw_processes() -> list[str]:
         try:
             result = subprocess.run(
                 ["pgrep", "-f", "openclaw"],
-                capture_output=True, text=True, timeout=3,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=3,
             )
             if result.returncode == 0:
                 pids = result.stdout.strip().split()
diff --git a/hermes_cli/cli_commands_mixin.py b/hermes_cli/cli_commands_mixin.py
index 014391bfe04..e447c2cac6b 100644
--- a/hermes_cli/cli_commands_mixin.py
+++ b/hermes_cli/cli_commands_mixin.py
@@ -569,8 +569,26 @@ class CLICommandsMixin:
 
         pcfg = gw_config.platforms.get(platform)
         if not pcfg or not pcfg.enabled:
-            _cprint(f"  Platform '{platform_name}' is not configured/enabled in the gateway.")
-            return True
+            # Relay aliasing: a relay-fronted gateway has no per-platform
+            # config block for the logical platform ("discord" etc.) — only a
+            # RELAY entry — yet /handoff discord is deliverable when the relay
+            # fronts it. The fronted set is deploy config
+            # (GATEWAY_RELAY_PLATFORMS), readable here without the live
+            # adapter; the gateway watcher re-checks against the authenticated
+            # transport (resolve_delivery_transport) before dispatch, so this
+            # is a UX pre-check, not the security gate.
+            relay_fronts = False
+            try:
+                from gateway.relay import relay_platform_identities
+                relay_cfg = gw_config.platforms.get(Platform.RELAY)
+                if relay_cfg and relay_cfg.enabled:
+                    fronted = {p for p, _ in relay_platform_identities()}
+                    relay_fronts = platform_name in fronted
+            except Exception:
+                relay_fronts = False
+            if not relay_fronts:
+                _cprint(f"  Platform '{platform_name}' is not configured/enabled in the gateway.")
+                return True
 
         home = gw_config.get_home_channel(platform)
         if not home or not home.chat_id:
diff --git a/hermes_cli/clipboard.py b/hermes_cli/clipboard.py
index a6b6da7c06a..78a9a43c3d7 100644
--- a/hermes_cli/clipboard.py
+++ b/hermes_cli/clipboard.py
@@ -67,7 +67,7 @@ def _macos_has_image() -> bool:
     try:
         info = subprocess.run(
             ["osascript", "-e", "clipboard info"],
-            capture_output=True, text=True, timeout=3,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=3,
         )
         return "«class PNGf»" in info.stdout or "«class TIFF»" in info.stdout
     except Exception:
@@ -109,7 +109,7 @@ def _macos_osascript(dest: Path) -> bool:
     try:
         r = subprocess.run(
             ["osascript", "-e", script],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
         )
         if r.returncode == 0 and "fail" not in r.stdout and dest.exists() and dest.stat().st_size > 0:
             return True
@@ -200,7 +200,7 @@ _POWERSHELL_EXTRACT_IMAGE_SCRIPTS = (
 def _run_powershell(exe: str, script: str, timeout: int) -> subprocess.CompletedProcess:
     return subprocess.run(
         [exe, "-NoProfile", "-NonInteractive", "-Command", script],
-        capture_output=True, text=True, timeout=timeout,
+        capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=timeout,
     )
 
 
@@ -258,7 +258,7 @@ def _find_powershell() -> str | None:
         try:
             r = subprocess.run(
                 [name, "-NoProfile", "-NonInteractive", "-Command", "echo ok"],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             )
             if r.returncode == 0 and "ok" in r.stdout:
                 return name
@@ -333,7 +333,7 @@ def _wayland_has_image() -> bool:
     try:
         r = subprocess.run(
             ["wl-paste", "--list-types"],
-            capture_output=True, text=True, timeout=3,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=3,
         )
         return r.returncode == 0 and any(
             t.startswith("image/") for t in r.stdout.splitlines()
@@ -351,7 +351,7 @@ def _wayland_save(dest: Path) -> bool:
         # Check available MIME types
         types_r = subprocess.run(
             ["wl-paste", "--list-types"],
-            capture_output=True, text=True, timeout=3,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=3,
         )
         if types_r.returncode != 0:
             return False
@@ -453,7 +453,7 @@ def _xclip_has_image() -> bool:
     try:
         r = subprocess.run(
             ["xclip", "-selection", "clipboard", "-t", "TARGETS", "-o"],
-            capture_output=True, text=True, timeout=3,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=3,
         )
         return r.returncode == 0 and "image/png" in r.stdout
     except FileNotFoundError:
@@ -469,7 +469,7 @@ def _xclip_save(dest: Path) -> bool:
     try:
         targets = subprocess.run(
             ["xclip", "-selection", "clipboard", "-t", "TARGETS", "-o"],
-            capture_output=True, text=True, timeout=3,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=3,
         )
         if "image/png" not in targets.stdout:
             return False
diff --git a/hermes_cli/commands.py b/hermes_cli/commands.py
index d5973e51eab..bad2250da00 100644
--- a/hermes_cli/commands.py
+++ b/hermes_cli/commands.py
@@ -118,6 +118,8 @@ COMMAND_REGISTRY: list[CommandDef] = [
     CommandDef("subgoal", "Add or manage extra criteria on the active goal", "Session",
                args_hint="[text | remove N | clear]"),
     CommandDef("status", "Show session, model, token, and context info", "Session"),
+    CommandDef("egress", "Show Docker egress proxy status", "Session",
+               args_hint="[status]", subcommands=("status",)),
     CommandDef("whoami", "Show your slash command access (admin / user)", "Info"),
     CommandDef("profile", "Show active profile name and home directory", "Info"),
     CommandDef("sethome", "Set this chat as the home channel", "Session",
@@ -561,6 +563,7 @@ _TELEGRAM_MENU_PRIORITY = (
     "new",
     "stop",
     "status",
+    "egress",
     "resume",
     "sessions",
     "model",
@@ -967,7 +970,8 @@ def discord_skill_commands_by_category(
 
     Skills whose directory is nested at least 2 levels under a scan root
     (e.g. ``creative/ascii-art/SKILL.md``) are grouped by their top-level
-    category.  Root-level skills (e.g. ``dogfood/SKILL.md``) are returned as
+    category.  Root-level skills (e.g. ``some-skill/SKILL.md`` directly under a
+    scan root) are returned as
     *uncategorized*.
 
     Scan roots include the local ``SKILLS_DIR`` **and** any configured
@@ -1167,7 +1171,8 @@ _SLACK_PRIORITY_ALIASES = ("btw", "bg")
 #   - moa: high-cost slash mode, available through /hermes moa to avoid
 #     displacing existing native Slack slash commands at the 50-command cap.
 #   - debug: the log/report upload surface; reached via /hermes debug on Slack.
-_SLACK_VIA_HERMES_ONLY = frozenset({"topup", "moa", "debug"})
+#   - egress: Docker-only proxy status; reachable as /hermes egress on Slack.
+_SLACK_VIA_HERMES_ONLY = frozenset({"topup", "moa", "debug", "egress"})
 
 
 def _sanitize_slack_name(raw: str) -> str:
diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index 31c06636607..3e0bfc45017 100644
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@@ -293,8 +293,8 @@ _EXTRA_ENV_KEYS = frozenset({
     "IRC_USE_TLS", "IRC_SERVER_PASSWORD", "IRC_NICKSERV_PASSWORD",
     "TERMINAL_ENV", "TERMINAL_SSH_KEY", "TERMINAL_SSH_PORT",
     # Deprecated tool-progress env vars — replaced by display.tool_progress in
-    # config.yaml. Kept known here so .env sanitization/reload still handle
-    # them for existing users (gateway reads them as a back-compat fallback),
+    # config.yaml. Kept known here so reload and compatibility paths still
+    # handle them for existing users (gateway reads them as a back-compat fallback),
     # without surfacing them in user-facing OPTIONAL_ENV_VARS listings.
     "HERMES_TOOL_PROGRESS", "HERMES_TOOL_PROGRESS_MODE",
     "WHATSAPP_MODE", "WHATSAPP_ENABLED",
@@ -966,6 +966,14 @@ DEFAULT_CONFIG = {
         # Set a positive value in config.yaml only if you explicitly want a
         # grace window on /restart (and keep it well under TimeoutStopSec).
         "restart_drain_timeout": 0,
+        # Upper bound (seconds) a submitted prompt waits for the deferred
+        # agent build (MCP discovery, model metadata, skills scan) before
+        # failing with a visible error (#63078). The gateway's wait is
+        # patient — the prompt is delivered the moment the build completes
+        # and a progress notice is emitted past 30s — so this cap only fires
+        # on a genuinely hung build. Raise it for deployments with many slow
+        # or unreachable MCP servers.
+        "build_wait_timeout": 600,
         # Max app-level retry attempts for API errors (connection drops,
         # provider timeouts, 5xx, etc.) before the agent surfaces the
         # failure.  The OpenAI SDK already does its own low-level retries
@@ -1304,15 +1312,22 @@ DEFAULT_CONFIG = {
         "max_file_size_mb": 10,
         # Auto-maintenance: hermes sweeps the checkpoint base at startup
         # (at most once per ``min_interval_hours``) and:
-        #   * deletes project entries whose workdir no longer exists (orphan)
         #   * deletes project entries whose last_touch is older than
         #     ``retention_days``
         #   * GCs the single shared store to reclaim unreachable objects
         #   * enforces ``max_total_size_mb`` across remaining projects
         #   * deletes ``legacy-*`` archives older than ``retention_days``
+        #
+        # NOTE: this automatic sweep never deletes "orphan" entries (workdir
+        # no longer found on disk). A missing workdir at startup is
+        # ambiguous — it can mean the project was deleted, or that an
+        # external volume / network share / VPN is simply not mounted yet —
+        # and this sweep runs unattended, so it must never guess. Orphan
+        # cleanup is only available via the explicit
+        # ``hermes checkpoints prune`` command (add ``--keep-orphans`` to
+        # skip it), where a human is looking at the output.
         "auto_prune": True,
         "retention_days": 7,
-        "delete_orphans": True,
         "min_interval_hours": 24,
     },
 
@@ -1398,6 +1413,15 @@ DEFAULT_CONFIG = {
 
     "compression": {
         "enabled": True,
+        "progress_notices": False,    # opt-in (#52995): when True, routine compression
+                                      # progress statuses (compacting/preflight/pre-API/
+                                      # idle/retry) are delivered to chat gateway
+                                      # platforms instead of being suppressed by the
+                                      # gateway noise filter. Default False keeps
+                                      # routine compression silent-by-design on chat
+                                      # surfaces (server-side logging only). Failure
+                                      # notices and manual /compress feedback are
+                                      # always visible regardless of this setting.
         "threshold": 0.50,            # compress when context usage exceeds this ratio.
                                       # Models with context windows below 512K are
                                       # floored at 0.75 (raise-only) so compaction
@@ -1409,13 +1433,49 @@ DEFAULT_CONFIG = {
                                       # the model's context length at apply-time.
         "target_ratio": 0.20,         # fraction of threshold to preserve as recent tail
         "protect_last_n": 20,         # minimum recent messages to keep uncompressed
+        "min_tail_user_messages": 1,  # REAL (actionable) user messages guaranteed to
+                                      # survive in the uncompressed tail. 1 = existing
+                                      # single last-user anchor (default, behavior-
+                                      # preserving); raise to e.g. 3 to keep the last
+                                      # 3 real user turns verbatim when bulky tool
+                                      # outputs fill the tail token budget.
         "max_attempts": 3,            # compression retry rounds before a turn gives up
                                       # with "max compression attempts reached". Raise
                                       # (e.g. 6) for tool-schema-heavy sessions where 3
                                       # rounds cannot clear the request estimate.
                                       # Validated >= 1, hard-capped at 10.
+        "proactive_prune_tokens": 0,  # opt-in trigger (tokens) for the deterministic,
+                                      # no-LLM tool-result prune, run independently of
+                                      # `threshold` above. On large-window models
+                                      # `threshold` (≈50% of the window) rarely fires,
+                                      # so old tool output otherwise rides in history
+                                      # and is re-sent every turn; a low value like
+                                      # 48000 reclaims it early. 0 = off. Recent tail
+                                      # protected by `protect_last_n`. Built-in
+                                      # compressor only (other engines inherit a no-op).
+                                      # NOTE: each committed prune rewrites already-sent
+                                      # history, breaking the provider prompt-cache
+                                      # prefix — the min_reclaim gate below keeps those
+                                      # breaks episodic rather than per-turn.
+        "proactive_prune_min_result_chars": 8000,  # the prune's summarize pass only
+                                      # touches tool results larger than this (chars);
+                                      # clamped to >= 200 so a generated summary can't
+                                      # itself be re-summarized.
+        "proactive_prune_min_reclaim_tokens": 4096,  # a proactive prune only commits
+                                      # when it reclaims at least this many tokens
+                                      # (measured on the pruned output). Keeps
+                                      # prompt-cache invalidation amortized: one big
+                                      # episodic break instead of a tiny break every
+                                      # tool iteration. 0 = commit any non-zero prune.
         "hygiene_hard_message_limit": 5000,  # gateway session-hygiene force-compress threshold by message count
         "hygiene_timeout_seconds": 30,  # max seconds gateway waits for pre-agent hygiene compression
+                                      # WITHOUT forward progress. The summary call streams, so
+                                      # this is an inactivity budget: a slow model still
+                                      # producing tokens keeps extending the wait; only a
+                                      # silent/hung call is cut off.
+        "hygiene_total_ceiling_seconds": 600,  # absolute cap on the hygiene compression wait even
+                                      # while tokens are still moving — bounds a degenerate
+                                      # trickle stream. Clamped to >= hygiene_timeout_seconds.
         "hygiene_failure_cooldown_seconds": 300,  # skip repeated failed hygiene attempts for this session
         "protect_first_n": 3,         # non-system head messages always preserved
                                       # verbatim, in ADDITION to the system prompt
@@ -1472,8 +1532,8 @@ DEFAULT_CONFIG = {
                                       # turns are soft-archived under the same id
                                       # (active=0, compacted=1) — still searchable via
                                       # session_search and recoverable, not deleted.
-                                      # Default False during rollout; will flip on
-                                      # after live validation.
+                                      # Default True since 2107b86024; set False to
+                                      # restore the legacy rotating-compaction path.
         "model_thresholds": {},       # Per-model threshold overrides. Keys are
                                       # substring-matched against the model name
                                       # (longest match wins); values replace the
@@ -1598,6 +1658,13 @@ DEFAULT_CONFIG = {
         # not a meaningful recovery, so an unretried blip silently loses the
         # call.
         "transient_retries": 2,
+        # Endpoints that reject NON-streaming chat requests outright (e.g.
+        # Tencent Copilot returns HTTP 400 "Non-stream chat request is
+        # currently not supported"). Auxiliary calls to a matching endpoint
+        # are sent with stream=True and aggregated client-side. Entries are
+        # case-insensitive substrings matched against the endpoint URL;
+        # copilot.tencent.com is always treated as stream-only.
+        "stream_only_base_urls": [],
         "vision": {
             "provider": "auto",    # auto | openrouter | nous | codex | custom
             "model": "",           # e.g. "google/gemini-2.5-flash", "gpt-4o"
@@ -2402,6 +2469,16 @@ DEFAULT_CONFIG = {
         # override the output directory.
         "save_traces": False,
         "trace_dir": "",
+        # Privacy redaction filter for advisor (reference) outputs. Advisors
+        # can echo PII from the conversation (emails, formatted phone numbers)
+        # and credential shapes into reference blocks, traces, and the
+        # aggregator prompt. Modes ('' = off, the default):
+        #   "display" — redact user-visible surfaces only (reference blocks
+        #               shown in the UI + saved MoA trace records); the
+        #               aggregator still sees raw advisor text.
+        #   "full"    — additionally redact the advisor text injected into
+        #               the aggregator prompt (issue #59959).
+        "privacy_filter": "",
         "presets": {
             "default": {
                 "reference_models": [
@@ -2924,22 +3001,40 @@ DEFAULT_CONFIG = {
     # openclaw-tool-search-report PDF in this PR for the rationale.
     "tools": {
         "tool_search": {
-            # "auto" (default) — activate only when deferrable tool schemas
-            #   exceed ``threshold_pct`` of the active model's context length,
-            #   so small toolsets pay no overhead.
-            # "on"  — always activate when there is at least one deferrable
-            #   tool. Use when you have many MCP servers and want maximum
-            #   token reduction unconditionally.
+            # Tiered disclosure: any deferrable (MCP/plugin) tool activates
+            # the bridge; the listing then scales with catalog size.
+            #   Tier 0 — no MCP/plugin tools: everything stays eager.
+            #   Tier 1 — catalog listing fits the budget: bridge + skills-style
+            #     name+description manifest (degrades to names-only).
+            #   Tier 2 — per-tool listing over budget even names-only (e.g.
+            #     Cloudflare's ~3,300-tool flat API surface): bare bridge +
+            #     a one-line-per-server summary (name + tool count) so the
+            #     model knows which domains are reachable; individual tools
+            #     discoverable through tool_search only.
+            # "auto"/"on" — activate when at least one deferrable tool exists.
             # "off" — disable entirely. Tools-array assembly is a pass-through.
             "enabled": "auto",
-            # Percentage of context length at which "auto" mode kicks in.
-            # 10 matches the Claude Code default. Range 0..100.
-            "threshold_pct": 10,
+            # Listing budget as a percentage of the active model's context
+            # length. Effective budget = min(this % of context,
+            # listing_max_tokens). Range 0..100.
+            "threshold_pct": 5,
             # When the model calls tool_search without a ``limit`` argument,
             # how many hits to return. Range 1..max_search_limit.
             "search_default_limit": 5,
             # Hard upper bound the model can request via ``limit``. Range 1..50.
             "max_search_limit": 20,
+            # Skills-style catalog listing embedded in the tool_search bridge
+            # description: every deferred tool's name + first sentence of its
+            # description (≤60 chars), grouped by MCP server / toolset. Keeps
+            # capabilities discoverable while schemas stay deferred.
+            # "auto" (default) — include when the listing fits the budget
+            #   (falls back to names-only, then to the bare tier-2 bridge).
+            # "on"  — same rendering, but explicit intent to always list.
+            # "off" — always the bare bridge (tier 2 for every catalog).
+            "listing": "auto",
+            # Absolute cap on the embedded listing in tokens (chars/4
+            # estimate), regardless of context size. Range 200..60000.
+            "listing_max_tokens": 20000,
         },
     },
 
@@ -3003,6 +3098,13 @@ DEFAULT_CONFIG = {
         # works as a manual override and wins if set explicitly.
         "platform_connect_timeout": 30,
 
+        # In-process event-loop liveness watchdog (#69089). A daemon OS thread
+        # probes the gateway asyncio loop; after consecutive missed probes it
+        # dumps all-thread stacks and hard-exits with the service-restart exit
+        # code so the supervisor (systemd/launchd) revives the process instead
+        # of leaving a wedged-but-alive zombie. Set to false to disable.
+        "loop_watchdog": True,
+
         # Whether the gateway keeps writing the legacy sessions.json mirror of
         # its routing index. The primary copy lives in state.db (the
         # gateway_routing table). Default True for backward compatibility with
@@ -3178,6 +3280,15 @@ DEFAULT_CONFIG = {
         # How many days of ended-session history to keep.  Matches the
         # default of ``hermes sessions prune``.
         "retention_days": 90,
+        # When true, auto-archive (soft-hide, never delete) sessions that
+        # haven't been touched in ``auto_archive_days`` days, once per
+        # (roughly) min_interval_hours.  "Touched" is last activity, not
+        # creation, so an old-but-recently-used session is spared.  Pinned
+        # sessions are always exempt.  Off by default — opt in explicitly.
+        "auto_archive": False,
+        # Idle threshold (days of no activity) before auto-archive hides a
+        # session.  Only applies when auto_archive is true.
+        "auto_archive_days": 3,
         # VACUUM after a prune that actually deleted rows.  SQLite does not
         # reclaim disk space on DELETE — freed pages are just reused on
         # subsequent INSERTs — so without VACUUM the file stays bloated
@@ -3502,6 +3613,66 @@ DEFAULT_CONFIG = {
         "no_overlay": None,
     },
 
+    # =========================================================================
+    # Egress credential-injection proxy (iron-proxy)
+    # =========================================================================
+    # When enabled, outbound traffic from remote terminal sandboxes (Docker
+    # today; Modal/SSH in follow-ups) is routed through a managed iron-proxy
+    # subprocess.  The sandbox sees opaque proxy tokens; iron-proxy swaps in
+    # real API credentials at the egress boundary.  Compromising the sandbox
+    # leaks tokens that only work behind the configured trusted proxy boundary
+    # (CA private key + proxy endpoint integrity are part of that boundary).
+    #
+    # Configure with `hermes egress setup`.  Disabled by default — the rest of
+    # Hermes works exactly as before with `enabled: false`.
+    "proxy": {
+        # Master switch.  When false, iron-proxy is never started, no docker
+        # mounts are added, no binaries are auto-installed — feature is a
+        # complete no-op.
+        "enabled": False,
+        # Tunnel listener port.  Sandboxes get `HTTPS_PROXY=http://<host>:<port>`.
+        # 9090 is the default; collide-aware setup wizard can reassign.
+        "tunnel_port": 9090,
+        # Auto-download the pinned iron-proxy binary into ~/.hermes/bin/ on
+        # first use.  When false, you must place `iron-proxy` on PATH yourself.
+        "auto_install": True,
+        # Where iron-proxy looks up the real upstream secrets at egress time.
+        # "env"        — process env (default; what bitwarden integration
+        #                already populates if you use it)
+        # "bitwarden"  — refetch via `bws secret list` on each proxy restart;
+        #                rotation in the Bitwarden web app propagates without
+        #                touching .env (requires `secrets.bitwarden.enabled`).
+        "credential_source": "env",
+        # When true, the Docker backend refuses to start a sandbox if the
+        # proxy is enabled but not running.  False = fall back to direct
+        # outbound with real credentials in the sandbox (the legacy posture).
+        "enforce_on_docker": True,
+        # NOTE: ``fail_on_uncovered_providers`` was removed.  It gated a
+        # refuse-start when Anthropic / Azure OpenAI / Gemini env vars were
+        # present — those providers are now first-class swapped providers
+        # via per-provider match_headers rules (x-api-key, api-key,
+        # x-goog-api-key), so the fail-closed tier is empty.  A leftover
+        # key in existing user configs is ignored harmlessly.
+        # When credential_source is bitwarden but the BWS access token /
+        # project_id is missing OR the bws fetch returns no values for
+        # mapped providers, the daemon raises by default.  Set this to
+        # True to opt back in to the legacy "silently fall back to host
+        # env" behaviour — useful for migrations where the operator wants
+        # to switch credential_source to bitwarden but hasn't fully wired
+        # BWS yet.  Defaults to false (strict).
+        "allow_env_fallback": False,
+        # SSRF deny list applied to outbound traffic.  Omit / leave empty
+        # to use the safe default: loopback, link-local (incl. cloud
+        # metadata IPs at 169.254.169.254), and RFC1918.  Set to an
+        # explicit ``[]`` to opt out entirely (only sensible in hermetic
+        # tests that need to reach a loopback upstream).
+        "upstream_deny_cidrs": None,
+        # Extra allowed upstream hosts beyond the bundled defaults (which
+        # cover OpenRouter, OpenAI, Anthropic, Google, xAI, Mistral, Groq,
+        # Together, DeepSeek, Nous).  Wildcards (`*.foo.com`) are supported.
+        "extra_allowed_hosts": [],
+    },
+
     # Hermes Desktop (Electron app) launch options. These only affect
     # `hermes desktop`; they do not touch the CLI/gateway.
     "desktop": {
@@ -3523,6 +3694,17 @@ DEFAULT_CONFIG = {
         #   false   - always keep GPU acceleration on, even over a remote display.
         # Bridged to the HERMES_DESKTOP_DISABLE_GPU env var the Electron app reads.
         "disable_gpu": "auto",
+        # Auto-continue a turn that was killed mid-run by an app/backend/machine
+        # crash: resuming that session re-submits the interrupted prompt (shown
+        # as a "resumed interrupted turn" event) if the interruption is fresh.
+        # A stale interruption just shows the recovered partial transcript.
+        "auto_continue": {
+            "enabled": True,
+            # How recent the interruption must be to auto-continue (minutes).
+            "freshness_minutes": 15,
+            # Crash-loop breaker: max automatic re-runs of one interrupted turn.
+            "max_attempts": 2,
+        },
     },
 
 
@@ -4710,7 +4892,7 @@ OPTIONAL_ENV_VARS = {
     # HERMES_TOOL_PROGRESS and HERMES_TOOL_PROGRESS_MODE are deprecated —
     # now configured via display.tool_progress in config.yaml (off|new|all|verbose|log).
     # The gateway still falls back to these env vars for backward compatibility,
-    # so they live in _EXTRA_ENV_KEYS (known to .env sanitization/reload) but
+    # so they live in _EXTRA_ENV_KEYS (known to reload and compatibility paths) but
     # are intentionally NOT listed here: OPTIONAL_ENV_VARS feeds user-facing
     # surfaces (dashboard keys page, setup checklists) and deprecated knobs
     # shouldn't be offered there.
@@ -5891,11 +6073,11 @@ def migrate_config(interactive: bool = True, quiet: bool = False) -> Dict[str, A
     """
     results = {"env_added": [], "config_added": [], "warnings": []}
 
-    # ── Always: sanitize .env (split concatenated keys) ──
+    # ── Always: normalize safe .env line formatting ──
     try:
         fixes = sanitize_env_file()
         if fixes and not quiet:
-            print(f"  ✓ Repaired .env file ({fixes} corrupted entries fixed)")
+            print(f"  ✓ Normalized .env line formatting ({fixes} line(s) changed)")
     except Exception:
         pass  # best-effort; don't block migration on sanitize failure
 
@@ -7774,15 +7956,13 @@ def _parse_env_value(raw_value: str) -> str:
 def load_env() -> Dict[str, str]:
     """Load environment variables from ~/.hermes/.env.
 
-    Sanitizes lines before parsing so that corrupted files (e.g.
-    concatenated KEY=VALUE pairs on a single line) are handled
-    gracefully instead of producing mangled values such as duplicated
-    bot tokens.  See #8908.
+    Normalizes line endings before parsing while treating each assignment's
+    value as opaque data for boundary discovery.
 
     The parsed dict is memoised keyed on the .env file mtime, because
     ``get_env_value()`` is called dozens-to-hundreds of times per
     interactive menu render (`hermes tools`, `hermes setup`, status
-    panels). Sanitisation is O(lines × known-keys), so re-parsing the
+    panels). Sanitisation is O(lines), so re-parsing the
     same file on every call was burning ~300ms of CPU per `hermes tools`
     menu paint on top of the OAuth-refresh slowness. The mtime check
     invalidates the cache when the user edits .env mid-process.
@@ -7813,8 +7993,7 @@ def load_env() -> Dict[str, str]:
         open_kw = {"encoding": "utf-8-sig", "errors": "replace"}
         with open(env_path, **open_kw) as f:
             raw_lines = f.readlines()
-        # Sanitize before parsing: split concatenated lines & drop stale
-        # placeholders so corrupted .env files don't produce invalid tokens.
+        # Normalize line endings without interpreting value contents as syntax.
         lines = _sanitize_env_lines(raw_lines)
         for line in lines:
             line = line.strip()
@@ -7853,39 +8032,13 @@ def invalidate_env_cache() -> None:
     _env_cache = None
 
 
-_STRUCTURED_VALUE_MARKERS = ("://", "?", "&")
-
-
-def _looks_like_structured_value(value: str) -> bool:
-    """True when ``value`` looks like a URL/query string or holds whitespace.
-
-    Such a value is treated as one opaque secret. An embedded
-    ``KNOWN_KEY=`` substring inside it (e.g. a webhook URL carrying a query
-    parameter, or a proxy base URL with an embedded key) is part of the value,
-    not the start of a second .env entry, so the concatenation splitter must
-    not break on it. Plain token secrets (API keys) never contain these.
-    """
-    if any(marker in value for marker in _STRUCTURED_VALUE_MARKERS):
-        return True
-    return any(ch.isspace() for ch in value)
-
-
 def _sanitize_env_lines(lines: list) -> list:
-    """Fix corrupted .env lines before reading or writing.
+    """Normalize .env line endings without changing assignment semantics.
 
-    Handles two known corruption patterns:
-    1. Concatenated KEY=VALUE pairs on a single line (missing newline between
-       entries, e.g. ``ANTHROPIC_API_KEY=sk-...OPENAI_BASE_URL=https://...``).
-    2. Stale ``KEY=***`` placeholder entries left by incomplete setup runs.
-
-    Uses a known-keys set (OPTIONAL_ENV_VARS + _EXTRA_ENV_KEYS) so we only
-    split on real Hermes env var names, avoiding false positives from values
-    that happen to contain uppercase text with ``=``.
+    Content after the first ``=`` is opaque value data. A known variable name
+    embedded in that value must never be reinterpreted as another assignment;
+    concatenated assignments are ambiguous and therefore remain on one line.
     """
-    # Build the known keys set lazily from OPTIONAL_ENV_VARS + extras.
-    # Done inside the function so OPTIONAL_ENV_VARS is guaranteed to be defined.
-    known_keys = set(OPTIONAL_ENV_VARS.keys()) | _EXTRA_ENV_KEYS
-
     sanitized: list[str] = []
     for line in lines:
         raw = line.rstrip("\r\n")
@@ -7896,58 +8049,7 @@ def _sanitize_env_lines(lines: list) -> list:
             sanitized.append(raw + "\n")
             continue
 
-        # Detect concatenated KEY=VALUE pairs on one line.
-        # Search for known KEY= patterns at any position in the line.
-        # We collect full needle ranges so we can drop matches that are
-        # fully contained within a longer overlapping needle. Without this,
-        # suffix collisions corrupt the file: e.g. LM_API_KEY= inside
-        # GLM_API_KEY= would otherwise split the line into "G\nLM_API_KEY=...".
-        match_ranges: list[tuple[int, int]] = []
-        for key_name in known_keys:
-            needle = key_name + "="
-            idx = stripped.find(needle)
-            while idx >= 0:
-                match_ranges.append((idx, idx + len(needle)))
-                idx = stripped.find(needle, idx + len(needle))
-
-        split_positions = sorted({
-            s for s, e in match_ranges
-            if not any(
-                s2 <= s and e2 >= e and (s2, e2) != (s, e)
-                for s2, e2 in match_ranges
-            )
-        })
-
-        # Only treat the line as a concatenation when it actually begins with a
-        # known KEY= (split_positions[0] == 0). A first match at a non-zero
-        # offset means the matches sit inside a value, so splitting there would
-        # silently drop the leading text — keep the line intact instead.
-        split_into_entries = False
-        segments: list[str] = []
-        if len(split_positions) > 1 and split_positions[0] == 0:
-            segments = [
-                stripped[pos:(
-                    split_positions[i + 1] if i + 1 < len(split_positions) else len(stripped)
-                )]
-                for i, pos in enumerate(split_positions)
-            ]
-            # A genuine concatenation has a simple token value in every segment
-            # that precedes a boundary. If a preceding value looks structured
-            # (a URL/query string or whitespace), the embedded KNOWN_KEY= is
-            # part of that value rather than a new entry, so we must not split —
-            # otherwise we truncate the real secret and fabricate a bogus one.
-            split_into_entries = all(
-                not _looks_like_structured_value(seg.split("=", 1)[1])
-                for seg in segments[:-1]
-            )
-
-        if split_into_entries:
-            for seg in segments:
-                part = seg.strip()
-                if part:
-                    sanitized.append(part + "\n")
-        else:
-            sanitized.append(stripped + "\n")
+        sanitized.append(stripped + "\n")
 
     return sanitized
 
@@ -7955,8 +8057,8 @@ def _sanitize_env_lines(lines: list) -> list:
 def sanitize_env_file() -> int:
     """Read, sanitize, and rewrite ~/.hermes/.env in place.
 
-    Returns the number of lines that were fixed (concatenation splits +
-    placeholder removals).  Returns 0 when no changes are needed.
+    Returns the number of lines whose safe formatting was normalized. Returns
+    0 when no changes are needed.
     """
     env_path = get_env_path()
     if not env_path.exists():
@@ -7973,10 +8075,9 @@ def sanitize_env_file() -> int:
     if sanitized == original_lines:
         return 0
 
-    # Count fixes: difference in line count (from splits) + removed lines
+    # Count lines whose normalized representation differs.
     fixes = abs(len(sanitized) - len(original_lines))
     if fixes == 0:
-        # Lines changed content (e.g. *** removal) even if count is same
         fixes = sum(1 for a, b in zip(original_lines, sanitized) if a != b)
         fixes += abs(len(sanitized) - len(original_lines))
 
@@ -8109,7 +8210,7 @@ def save_env_value(key: str, value: str):
     if env_path.exists():
         with open(env_path, **read_kw) as f:
             lines = f.readlines()
-        # Sanitize on every read: split concatenated keys, drop stale placeholders
+        # Normalize safe line formatting without interpreting values as syntax.
         lines = _sanitize_env_lines(lines)
 
     serialized_value = _quote_env_value(value)
@@ -8167,6 +8268,25 @@ def save_env_value(key: str, value: str):
     invalidate_env_cache()
 
 
+def custom_endpoint_key_env(identity: str) -> str:
+    """Env var name holding a custom endpoint's API key.
+
+    ``identity`` is whatever names the endpoint on the calling path — the
+    Desktop panel's endpoint id, or ``host:port`` for the CLI setup flow.
+    Two properties matter:
+
+    - It keys off the endpoint's own identity, not just its hostname, so two
+      endpoints on one host (``127.0.0.1:8000`` and ``:8001``) get separate
+      slots instead of the second save clobbering the first's credential.
+    - The fixed ``HERMES_CUSTOM_`` prefix keeps the result a valid POSIX name
+      even when the slug starts with a digit, which every IP-based local
+      endpoint does (``127.0.0.1`` → ``127_0_0_1``). ``save_env_value``
+      rejects digit-leading names outright.
+    """
+    slug = re.sub(r"[^A-Z0-9]+", "_", str(identity or "").upper()).strip("_")
+    return f"HERMES_CUSTOM_{slug}_API_KEY" if slug else "HERMES_CUSTOM_API_KEY"
+
+
 def remove_env_value(key: str) -> bool:
     """Remove a key from ~/.hermes/.env and os.environ.
 
diff --git a/hermes_cli/container_boot.py b/hermes_cli/container_boot.py
index 6cf241af648..ed345ecdd9e 100644
--- a/hermes_cli/container_boot.py
+++ b/hermes_cli/container_boot.py
@@ -236,7 +236,7 @@ def _maybe_migrate_legacy_gateway_run_state(
             "desired_state": "running",
             "timestamp": int(time.time()),
             "migrated_from": "legacy-container-cmd",
-        }) + "\n")
+        }) + "\n", encoding="utf-8")
     return "running"
 
 
@@ -382,7 +382,7 @@ def _read_desired_state(profile_dir: Path) -> str | None:
     if not state_file.exists():
         return None
     try:
-        data = json.loads(state_file.read_text())
+        data = json.loads(state_file.read_text(encoding="utf-8"))
         desired_state = data.get("desired_state")
         if desired_state is not None:
             return desired_state
@@ -450,7 +450,7 @@ def _register_service(scandir: Path, profile: str, *, start: bool) -> None:
     tmp_dir.mkdir(parents=True)
 
     try:
-        (tmp_dir / "type").write_text("longrun\n")
+        (tmp_dir / "type").write_text("longrun\n", encoding="utf-8")
 
         # Reuse the manager's run-script rendering — single source of
         # truth so register_profile_gateway and reconcile_profile_gateways
@@ -458,18 +458,18 @@ def _register_service(scandir: Path, profile: str, *, start: bool) -> None:
         # per-profile env can set it via the profile's config.yaml
         # (which the gateway itself loads).
         run = tmp_dir / "run"
-        run.write_text(S6ServiceManager._render_run_script(profile, extra_env={}))
+        run.write_text(S6ServiceManager._render_run_script(profile, extra_env={}), encoding="utf-8")
         run.chmod(0o755)
 
         finish = tmp_dir / "finish"
-        finish.write_text(S6ServiceManager._render_finish_script())
+        finish.write_text(S6ServiceManager._render_finish_script(), encoding="utf-8")
         finish.chmod(0o755)
 
         # Persistent log rotation (OQ8-C).
         log_subdir = tmp_dir / "log"
         log_subdir.mkdir()
         log_run = log_subdir / "run"
-        log_run.write_text(S6ServiceManager._render_log_run(profile))
+        log_run.write_text(S6ServiceManager._render_log_run(profile), encoding="utf-8")
         log_run.chmod(0o755)
 
         # The presence of a `down` file tells s6-supervise to NOT
diff --git a/hermes_cli/copilot_auth.py b/hermes_cli/copilot_auth.py
index 1216254fea5..d193c7cf74a 100644
--- a/hermes_cli/copilot_auth.py
+++ b/hermes_cli/copilot_auth.py
@@ -147,7 +147,7 @@ def _try_gh_cli_token() -> Optional[str]:
             result = subprocess.run(
                 cmd,
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=5,
                 env=clean_env,
                 **_popen_kwargs,
diff --git a/hermes_cli/cron.py b/hermes_cli/cron.py
index bf8a02fe099..9c1fde724be 100644
--- a/hermes_cli/cron.py
+++ b/hermes_cli/cron.py
@@ -254,6 +254,7 @@ def cron_status():
         # (#32612, #32895).
         from cron.jobs import (
             get_ticker_heartbeat_age,
+            get_ticker_last_error,
             get_ticker_success_age,
             TICKER_INTERVAL_SECONDS,
         )
@@ -283,6 +284,20 @@ def cron_status():
                 Colors.YELLOW,
             ))
             print(f"  PID: {', '.join(map(str, pids))}")
+            last_error = get_ticker_last_error()
+            if last_error:
+                # Show WHY ticks fail — e.g. a root-rewritten jobs.json
+                # (PermissionError) that silently locked out the ticker's
+                # uid for ~14h in the field (#68483).
+                print(color(f"  Last tick error: {last_error}", Colors.RED))
+                if "Permission denied" in last_error:
+                    print(color(
+                        "  Hint: jobs.json may be owned by another user "
+                        "(e.g. rewritten by a root `docker exec hermes "
+                        "hermes cron ...`). Fix ownership to match the "
+                        "gateway user, and prefer `docker exec -u <uid>:<gid>`.",
+                        Colors.YELLOW,
+                    ))
             print("  Check the gateway log for 'Cron tick error'.")
         else:
             print(color("✓ Gateway is running — cron jobs will fire automatically", Colors.GREEN))
diff --git a/hermes_cli/curator.py b/hermes_cli/curator.py
index c64fd5afef8..26d419ffefa 100644
--- a/hermes_cli/curator.py
+++ b/hermes_cli/curator.py
@@ -36,6 +36,35 @@ def _fmt_ts(ts: Optional[str]) -> str:
     return f"{secs // 86400}d ago"
 
 
+def _print_unmanaged_summary() -> None:
+    """Report curation-eligible skills that carry no provenance marker.
+
+    A skill only becomes curator-managed once ``created_by: agent`` lands on
+    its usage record, which happens ONLY for background-review creations.
+    Skills predating that marker, plus every foreground
+    ``skill_manage(create)``, are eligible but unmanaged — no automatic
+    transition ever considers them. Printing just the managed count made a
+    large library look fully curated while a big slice was untouchable.
+    """
+    from tools import skill_usage
+
+    try:
+        unmanaged = skill_usage.unmanaged_report()
+    except Exception:
+        return
+    if not unmanaged:
+        return
+    legacy = sum(1 for r in unmanaged if not r.get("has_provenance_key"))
+    foreground = len(unmanaged) - legacy
+    print(f"\nunmanaged (no provenance marker): {len(unmanaged)} total")
+    print(f"  pre-dates marker    {legacy}")
+    print(f"  foreground-created  {foreground}")
+    print(
+        "  never auto-staled or archived — "
+        "`hermes curator adopt <name>` hands one over"
+    )
+
+
 def _cmd_status(args) -> int:
     from agent import curator
     from tools import skill_usage
@@ -82,20 +111,29 @@ def _cmd_status(args) -> int:
         f"{'' if curator.get_consolidate() else ' (prune-only; LLM merge pass opt-in)'}"
     )
 
-    rows = skill_usage.agent_created_report()
+    rows = skill_usage.curated_report()
     if not rows:
-        print("\nno agent-created skills")
+        print("\nno curator-managed skills")
+        _print_unmanaged_summary()
         return 0
 
     by_state = {"active": [], "stale": [], "archived": []}
     pinned = []
+    agent_count = 0
+    bundled_count = 0
     for r in rows:
         state_name = r.get("state", "active")
         by_state.setdefault(state_name, []).append(r)
         if r.get("pinned"):
             pinned.append(r["name"])
+        prov = r.get("provenance", "agent")
+        if prov == "agent":
+            agent_count += 1
+        elif prov == "bundled":
+            bundled_count += 1
 
-    print(f"\nagent-created skills: {len(rows)} total")
+    print(f"\ncurator-managed skills: {len(rows)} total  "
+          f"(agent-created={agent_count}  bundled={bundled_count})")
     for state_name in ("active", "stale", "archived"):
         bucket = by_state.get(state_name, [])
         print(f"  {state_name:10s} {len(bucket)}")
@@ -103,6 +141,9 @@ def _cmd_status(args) -> int:
     if pinned:
         print(f"\npinned ({len(pinned)}): {', '.join(pinned)}")
 
+    # Surface the curation blind spot on the managed path too.
+    _print_unmanaged_summary()
+
     # Show top 5 least-recently-active skills. Views and edits are activity too:
     # curator should not report a skill as "never used" right after skill_view()
     # or skill_manage() touched it.
@@ -272,6 +313,90 @@ def _cmd_unpin(args) -> int:
     return 0
 
 
+def _cmd_list_unmanaged(args) -> int:
+    """List curation-eligible skills that carry no provenance marker.
+
+    The same population `status` summarizes, itemized. Useful before deciding
+    what to hand over with `adopt`.
+    """
+    from tools import skill_usage
+
+    rows = skill_usage.unmanaged_report()
+    if not rows:
+        print("curator: no unmanaged skills — every eligible skill is managed")
+        return 0
+
+    print(f"unmanaged skills ({len(rows)}):")
+    for r in sorted(rows, key=lambda x: x["name"]):
+        why = "created_by:null" if r.get("has_provenance_key") else "no marker"
+        last = _fmt_ts(r.get("last_activity_at"))
+        print(
+            f"  {r['name']:44s} "
+            f"activity={r.get('activity_count', 0):4d}  "
+            f"last_activity={last:14s}  "
+            f"({why})"
+        )
+    print("\nadopt one with `hermes curator adopt <name>`, "
+          "or all with `hermes curator adopt --all-unmanaged`")
+    return 0
+
+
+def _cmd_adopt(args) -> int:
+    """Hand unmanaged skills to the curator by explicit user declaration.
+
+    Provenance cannot be inferred from telemetry: a high patch count proves
+    the agent MAINTAINS a skill, not that it AUTHORED it (the agent edits
+    user-written skills on the user's behalf constantly). So adoption is never
+    automatic — the user names what they're handing over, or passes
+    ``--all-unmanaged`` to hand over every eligible skill at once.
+    """
+    from tools import skill_usage
+
+    names = list(getattr(args, "skill", None) or [])
+    adopt_all = bool(getattr(args, "all_unmanaged", False))
+    if adopt_all:
+        if names:
+            print("curator: pass either skill names or --all-unmanaged, not both")
+            return 1
+        names = skill_usage.list_unmanaged_skill_names()
+        if not names:
+            print("curator: no unmanaged skills to adopt")
+            return 0
+    if not names:
+        print("curator: name a skill to adopt, or pass --all-unmanaged")
+        return 1
+
+    dry_run = bool(getattr(args, "dry_run", False))
+    if dry_run:
+        print(f"curator: would adopt {len(names)} skill(s) (dry run):")
+        for n in names:
+            print(f"  + {n}")
+        return 0
+
+    # Bulk adoption is a real lifecycle change (adopted skills become
+    # archivable), so confirm unless the caller opted out.
+    if adopt_all and not bool(getattr(args, "yes", False)):
+        print(f"curator: adopt {len(names)} unmanaged skill(s) into curator management?")
+        print("  they become eligible for automatic staleness + archival")
+        try:
+            reply = input("  proceed? [y/N] ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            reply = ""
+        if reply not in {"y", "yes"}:
+            print("curator: aborted")
+            return 1
+
+    failed = 0
+    for n in names:
+        ok, msg = skill_usage.adopt_skill(n)
+        print(f"curator: {msg}")
+        if not ok:
+            failed += 1
+    if len(names) > 1:
+        print(f"curator: adopted {len(names) - failed}/{len(names)}")
+    return 1 if failed else 0
+
+
 def _cmd_restore(args) -> int:
     from tools import skill_usage
     ok, msg = skill_usage.restore_skill(args.skill)
@@ -317,7 +442,7 @@ def _idle_days(record: dict) -> Optional[int]:
 
 
 def _cmd_prune(args) -> int:
-    """Bulk-archive agent-created skills idle for >= N days.
+    """Bulk-archive curator-managed skills idle for >= N days.
 
     Pinned skills are exempt. Already-archived skills are skipped. Default
     ``--days 90`` matches a conservative read of the curator's own archive
@@ -333,7 +458,7 @@ def _cmd_prune(args) -> int:
     skip_confirm = bool(getattr(args, "yes", False))
 
     candidates = []
-    for r in skill_usage.agent_created_report():
+    for r in skill_usage.curated_report():
         if r.get("pinned"):
             continue
         if r.get("state") == skill_usage.STATE_ARCHIVED:
@@ -491,7 +616,7 @@ def _cmd_list_archived(args) -> int:
 def _cmd_usage(args) -> int:
     """Show usage telemetry for ALL skills, with provenance.
 
-    Unlike `status` (curator-scoped to agent-created candidates), this lists
+    Unlike `status` (curator-scoped to curated candidates), this lists
     every skill on disk — bundled built-ins and hub-installed included — so you
     can see how often each is actually used regardless of curation.
     """
@@ -619,6 +744,33 @@ def register_cli(parent: argparse.ArgumentParser) -> None:
     p_unpin.add_argument("skill", help="Skill name")
     p_unpin.set_defaults(func=_cmd_unpin)
 
+    subs.add_parser(
+        "list-unmanaged",
+        help="List curation-eligible skills with no provenance marker",
+    ).set_defaults(func=_cmd_list_unmanaged)
+
+    p_adopt = subs.add_parser(
+        "adopt",
+        help="Hand unmanaged skills to the curator (provenance is a user declaration)",
+    )
+    p_adopt.add_argument(
+        "skill", nargs="*",
+        help="Skill name(s) to adopt. Omit when using --all-unmanaged.",
+    )
+    p_adopt.add_argument(
+        "--all-unmanaged", action="store_true",
+        help="Adopt every curation-eligible skill that has no provenance marker",
+    )
+    p_adopt.add_argument(
+        "--dry-run", action="store_true",
+        help="List what would be adopted without writing anything",
+    )
+    p_adopt.add_argument(
+        "--yes", action="store_true",
+        help="Skip the confirmation prompt for --all-unmanaged",
+    )
+    p_adopt.set_defaults(func=_cmd_adopt)
+
     p_restore = subs.add_parser("restore", help="Restore an archived skill")
     p_restore.add_argument("skill", help="Skill name")
     p_restore.set_defaults(func=_cmd_restore)
@@ -635,7 +787,7 @@ def register_cli(parent: argparse.ArgumentParser) -> None:
 
     p_prune = subs.add_parser(
         "prune",
-        help="Bulk-archive agent-created skills idle for >= N days (default 90)",
+        help="Bulk-archive curator-managed skills idle for >= N days (default 90)",
     )
     p_prune.add_argument(
         "--days", type=int, default=90,
diff --git a/hermes_cli/dashboard_auth/public_paths.py b/hermes_cli/dashboard_auth/public_paths.py
index 349937cffa0..befedb1070a 100644
--- a/hermes_cli/dashboard_auth/public_paths.py
+++ b/hermes_cli/dashboard_auth/public_paths.py
@@ -31,6 +31,11 @@ the SPA should bootstrap it after login instead.
 from __future__ import annotations
 
 PUBLIC_API_PATHS: frozenset[str] = frozenset({
+    # Minimal process liveness probe for desktop/backend boot handshakes. It
+    # intentionally avoids gateway config, platform discovery, MCP setup, and
+    # host-local detail so readiness checks cannot spend their budget inside
+    # cold plugin imports.
+    "/api/health",
     # Liveness probe target. Returns version, gateway state, active
     # session count, and the dashboard auth-gate shape. No bodies, no
     # session content, no secrets. Documented as the portal's wildcard
diff --git a/hermes_cli/doctor.py b/hermes_cli/doctor.py
index e995178d119..7c89e75adcb 100644
--- a/hermes_cli/doctor.py
+++ b/hermes_cli/doctor.py
@@ -423,21 +423,90 @@ def _check_s6_supervision(issues: list[str]) -> None:
     )
 
 
-def check_certificates() -> None:
+def check_certificates(should_fix: bool = False, issues: "list | None" = None) -> None:
     """Verify the certifi CA bundle is loadable.
 
     Surfaces the SSLConfigurationError user-friendly path before they hit
     a wall of tracebacks on the first outbound HTTPS call.
+
+    With ``--fix``, a broken bundle (missing/corrupt ``cacert.pem`` — e.g.
+    after a brew Python upgrade rebuilt the venv, #29866) is repaired by
+    force-reinstalling certifi into THIS interpreter's environment and
+    re-verifying.
     """
     try:
         from agent.ssl_guard import verify_ca_bundle_with_fallback
         from agent.errors import SSLConfigurationError
-        verify_ca_bundle_with_fallback()
-        check_ok("SSL CA certificate bundle is valid")
-    except SSLConfigurationError as e:
-        check_fail("SSL CA certificate bundle is broken", str(e))
     except Exception as e:
         check_warn("SSL certificate check skipped", str(e))
+        return
+
+    try:
+        verify_ca_bundle_with_fallback()
+        check_ok("SSL CA certificate bundle is valid")
+        return
+    except SSLConfigurationError as e:
+        first_error = str(e)
+    except Exception as e:
+        check_warn("SSL certificate check skipped", str(e))
+        return
+
+    if not should_fix:
+        check_fail("SSL CA certificate bundle is broken", first_error)
+        if issues is not None:
+            issues.append(
+                "Repair the CA bundle: run `hermes doctor --fix`, or "
+                f"`{sys.executable} -m pip install --force-reinstall certifi`"
+            )
+        return
+
+    # --fix: force-reinstall certifi into the running interpreter's env and
+    # re-verify. importlib caches are invalidated so certifi.where() resolves
+    # the fresh install without a process restart.
+    check_fail("SSL CA certificate bundle is broken", first_error)
+    print("    → Repairing: force-reinstalling certifi...")
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "pip", "install", "--force-reinstall", "certifi"],
+            capture_output=True,
+            text=True,
+            timeout=300,
+        )
+    except Exception as exc:
+        check_fail("certifi repair could not run pip", str(exc))
+        if issues is not None:
+            issues.append(
+                f"Reinstall certifi manually: {sys.executable} -m pip install "
+                "--force-reinstall certifi"
+            )
+        return
+    if result.returncode != 0:
+        tail = (result.stderr or result.stdout or "")[-500:]
+        check_fail("certifi reinstall failed", tail)
+        if issues is not None:
+            issues.append(
+                f"Reinstall certifi manually: {sys.executable} -m pip install "
+                "--force-reinstall certifi"
+            )
+        return
+
+    # Drop any cached certifi module so where() re-resolves the new bundle.
+    import importlib
+    for mod_name in [m for m in sys.modules if m == "certifi" or m.startswith("certifi.")]:
+        sys.modules.pop(mod_name, None)
+    importlib.invalidate_caches()
+
+    try:
+        verify_ca_bundle_with_fallback()
+        check_ok("SSL CA certificate bundle repaired (certifi reinstalled)")
+    except SSLConfigurationError as e:
+        check_fail("SSL CA certificate bundle still broken after reinstall", str(e))
+        if issues is not None:
+            issues.append(
+                "certifi reinstall did not restore the CA bundle — check for a "
+                "custom CA env var (SSL_CERT_FILE/REQUESTS_CA_BUNDLE) pointing "
+                "at a missing file, or recreate the venv."
+            )
 
 
 def _check_gateway_service_linger(issues: list[str]) -> None:
@@ -754,12 +823,12 @@ def run_doctor(args):
         )
         if is_sqlite_wal_reset_vulnerable():
             # Warn-only: Hermes already refuses to enable WAL on fresh DBs.
-            # Do not append to ``issues`` — users often cannot change the
-            # SQLite embedded in python-build-standalone via `hermes update`.
+            # Do not append to ``issues`` because runtime repair remains
+            # best-effort and unsupported installs may need manual action.
             check_warn(
                 f"SQLite {_sqlite_ver} (WAL-reset bug)",
-                "(new shared DBs use DELETE; prefer 3.51.3+ / 3.50.7 / 3.44.6 — "
-                "see https://sqlite.org/wal.html#walresetbug)",
+                "(run `hermes update`; fixed versions: 3.51.3+ / 3.50.7 / "
+                "3.44.6 — see https://sqlite.org/wal.html#walresetbug)",
             )
         else:
             check_ok(f"SQLite {_sqlite_ver}")
@@ -779,7 +848,7 @@ def run_doctor(args):
     _check_version_consistency(issues)
 
     _section("SSL / CA Certificates")
-    check_certificates()
+    check_certificates(should_fix=should_fix, issues=manual_issues)
 
     _section("Required Packages")
     required_packages = [
@@ -818,11 +887,13 @@ def run_doctor(args):
     if env_path.exists():
         check_ok(f"{_DHH}/.env file exists")
         
-        # Check for common issues. Pin encoding to UTF-8 because .env files are
-        # written as UTF-8 everywhere in the codebase, while Path.read_text()
-        # defaults to the system locale — which crashes on non-UTF-8 Windows
-        # locales (e.g. GBK) as soon as the file contains any non-ASCII byte.
-        content = env_path.read_text(encoding="utf-8")
+        # Prefer UTF-8 (.env is written as UTF-8 elsewhere). Fall back to
+        # latin-1 for Windows Notepad/cp1252 files that are not valid UTF-8 —
+        # matches hermes_cli.env_loader._load_dotenv_with_fallback.
+        try:
+            content = env_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            content = env_path.read_text(encoding="latin-1")
         if _has_provider_env_config(content):
             check_ok("API key or custom endpoint configured")
         else:
@@ -872,7 +943,7 @@ def run_doctor(args):
                     PROVIDER_REGISTRY,
                     resolve_provider as _resolve_auth_provider,
                 )
-                known_providers = set(PROVIDER_REGISTRY.keys()) | {"openrouter", "custom", "auto"}
+                known_providers = set(PROVIDER_REGISTRY.keys()) | {"openrouter", "custom", "auto", "moa"}
             except Exception:
                 _resolve_auth_provider = None
                 pass
@@ -1672,7 +1743,7 @@ def run_doctor(args):
                 result = subprocess.run(
                     cmd,
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                     timeout=15
                 )
             except subprocess.TimeoutExpired:
@@ -1836,7 +1907,7 @@ def run_doctor(args):
                 audit_result = subprocess.run(
                     [_npm_bin, "audit", "--json", *audit_extra],
                     cwd=str(npm_dir),
-                    capture_output=True, text=True, timeout=30,
+                    capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=30,
                 )
                 import json as _json
                 audit_data = _json.loads(audit_result.stdout) if audit_result.stdout.strip() else {}
@@ -2372,7 +2443,7 @@ def run_doctor(args):
         if lock_file.exists():
             try:
                 import json
-                lock_data = json.loads(lock_file.read_text())
+                lock_data = json.loads(lock_file.read_text(encoding="utf-8"))
                 count = len(lock_data.get("installed", {}))
                 check_ok(f"Lock file OK ({count} hub-installed skill(s))")
             except Exception:
@@ -2538,7 +2609,7 @@ def run_doctor(args):
                     if not wrapper.is_file():
                         continue
                     try:
-                        content = wrapper.read_text()
+                        content = wrapper.read_text(encoding="utf-8")
                         if "hermes -p" in content:
                             _m = _re.search(r"hermes -p (\S+)", content)
                             if _m and not profile_exists(_m.group(1)):
diff --git a/hermes_cli/dump.py b/hermes_cli/dump.py
index 139be0b592f..9b6685ae5e7 100644
--- a/hermes_cli/dump.py
+++ b/hermes_cli/dump.py
@@ -64,7 +64,7 @@ def _get_git_commit(project_root: Path) -> str:
     try:
         result = subprocess.run(
             ["git", "rev-parse", "--short=8", "HEAD"],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             cwd=str(project_root),
         )
         if result.returncode == 0:
@@ -99,7 +99,7 @@ def _get_git_commit_date(project_root: Path) -> str:
     try:
         result = subprocess.run(
             ["git", "log", "-1", "--format=%cd", "--date=short", "HEAD"],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             cwd=str(project_root),
         )
         if result.returncode == 0:
diff --git a/hermes_cli/env_loader.py b/hermes_cli/env_loader.py
index e91c12adf7e..22cb4a45854 100644
--- a/hermes_cli/env_loader.py
+++ b/hermes_cli/env_loader.py
@@ -188,12 +188,7 @@ def _load_dotenv_with_fallback(path: Path, *, override: bool) -> None:
 def _sanitize_env_file_if_needed(path: Path) -> None:
     """Pre-sanitize a .env file before python-dotenv reads it.
 
-    python-dotenv does not handle corrupted lines where multiple
-    KEY=VALUE pairs are concatenated on a single line (missing newline).
-    This produces mangled values — e.g. a bot token duplicated 8×
-    (see #8908).
-
-    Also strips embedded null bytes which crash ``os.environ[k] = v``
+    Strips embedded null bytes which crash ``os.environ[k] = v``
     with ``ValueError: embedded null byte`` — typically introduced by
     copy-pasting API keys from terminals or rich-text editors.
 
@@ -203,9 +198,8 @@ def _sanitize_env_file_if_needed(path: Path) -> None:
     to the errors=replace corruption path. Order of BOM checks matters:
     UTF-32-LE's BOM starts with UTF-16-LE's FF FE.
 
-    We delegate to ``hermes_cli.config._sanitize_env_lines`` which
-    already knows all valid Hermes env-var names and can split
-    concatenated lines correctly.
+    ``hermes_cli.config._sanitize_env_lines`` normalizes line endings while
+    treating content after the first ``=`` as opaque for boundary discovery.
     """
     if not path.exists():
         return
@@ -317,7 +311,7 @@ def load_hermes_dotenv(
     user_env = home_path / ".env"
     project_env_path = Path(project_env) if project_env else None
 
-    # Fix corrupted .env files before python-dotenv parses them (#8908).
+    # Normalize safe formatting and remove invalid NUL bytes before parsing.
     if user_env.exists():
         _sanitize_env_file_if_needed(user_env)
     if project_env_path and project_env_path.exists():
diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py
index ac95fac06de..ce60bfb2ccd 100644
--- a/hermes_cli/gateway.py
+++ b/hermes_cli/gateway.py
@@ -118,7 +118,7 @@ def _get_service_pids() -> set:
                         "--no-pager",
                     ],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                     timeout=5,
                 )
                 for line in result.stdout.strip().splitlines():
@@ -130,7 +130,7 @@ def _get_service_pids() -> set:
                         show = subprocess.run(
                             scope_args + ["show", svc, "--property=MainPID", "--value"],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding='utf-8', errors='replace',
                             timeout=5,
                         )
                         pid = int(show.stdout.strip())
@@ -148,7 +148,7 @@ def _get_service_pids() -> set:
             result = subprocess.run(
                 ["launchctl", "list", label],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=5,
             )
             if result.returncode == 0:
@@ -204,7 +204,7 @@ def _get_parent_pid(pid: int) -> int | None:
         result = subprocess.run(
             ["ps", "-o", "ppid=", "-p", str(pid)],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=5,
         )
     except (FileNotFoundError, subprocess.TimeoutExpired):
@@ -504,7 +504,7 @@ def _scan_gateway_pids(
                 result = subprocess.run(
                     ["ps", "-A", "eww", "-o", "pid=,command="],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                     timeout=10,
                 )
                 if result.returncode != 0:
@@ -911,7 +911,7 @@ def _probe_systemd_service_running(system: bool = False) -> tuple[bool, bool]:
             ["is-active", get_service_name()],
             system=selected_system,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
         )
     except (RuntimeError, subprocess.TimeoutExpired):
@@ -938,7 +938,7 @@ def _read_systemd_unit_environment(system: bool = False) -> dict[str, str]:
             ],
             system=selected_system,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
         )
     except (RuntimeError, subprocess.TimeoutExpired, OSError):
@@ -1031,7 +1031,7 @@ def _read_systemd_unit_properties(
             ],
             system=selected_system,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
         )
     except (RuntimeError, subprocess.TimeoutExpired, OSError):
@@ -1288,7 +1288,7 @@ def _probe_launchd_service_running() -> bool:
         result = subprocess.run(
             ["launchctl", "list", get_launchd_label()],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
         )
     except subprocess.TimeoutExpired:
@@ -1646,7 +1646,7 @@ def _systemd_operational(system: bool = False) -> bool:
             ["is-system-running"],
             system=system,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=5,
         )
         # "running", "degraded", "starting" all mean systemd is PID 1
@@ -1955,7 +1955,7 @@ def _preflight_user_systemd(*, auto_enable_linger: bool = True) -> None:
             result = subprocess.run(
                 ["loginctl", "enable-linger", username],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 check=False,
                 timeout=30,
             )
@@ -2432,7 +2432,7 @@ def get_systemd_linger_status() -> tuple[bool | None, str]:
         result = subprocess.run(
             ["loginctl", "show-user", username, "--property=Linger", "--value"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             check=False,
             timeout=10,
         )
@@ -3115,7 +3115,7 @@ def _ensure_linger_enabled() -> None:
         result = subprocess.run(
             ["loginctl", "enable-linger", username],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             check=False,
             timeout=30,
         )
@@ -3498,7 +3498,7 @@ def systemd_status(deep: bool = False, system: bool = False, full: bool = False)
         ["is-active", get_service_name()],
         system=system,
         capture_output=True,
-        text=True,
+        text=True, encoding='utf-8', errors='replace',
         timeout=10,
     )
 
@@ -3646,7 +3646,7 @@ def _launchd_domain() -> str:
         result = subprocess.run(
             ["launchctl", "managername"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=5,
         )
         if "Aqua" in (result.stdout or ""):
@@ -4124,11 +4124,19 @@ def refresh_launchd_plist_if_needed() -> bool:
             reload_log_path.parent.mkdir(parents=True, exist_ok=True)
         except OSError:
             pass
+
+        # Write a durable pre-bootout marker so we can distinguish "helper
+        # never started" from "helper ran but bootout/bootstrap failed".
+        _append_launchd_reload_log(f"Launchd reload helper started for {target}")
+
         # Retry until launchctl LISTS the label (not merely a zero bootstrap
         # exit) or the drain window elapses. The failure happens while the old
         # gateway is still draining (default agent.restart_drain_timeout=180s),
         # so a fixed ~10s window is too short — bound by that budget instead.
         _reload_budget = int(max(30.0, _get_restart_drain_timeout()))
+        # Label for the transient one-shot job (see `launchctl submit` below).
+        # Unique per reload so concurrent/repeated reloads never collide.
+        submit_label = f"{label}.reload.{os.getpid()}.{int(time.time())}"
         reload_script = (
             f"sleep 2; "
             f"launchctl bootout {shlex.quote(target)} 2>/dev/null; "
@@ -4143,21 +4151,46 @@ def refresh_launchd_plist_if_needed() -> bool:
             f"done; "
             f"if ! launchctl list {shlex.quote(label)} >/dev/null 2>&1; then "
             f"  echo \"[$(date '+%Y-%m-%d %H:%M:%S %z')] FAILED launchd reload for {shlex.quote(target)} — service NOT registered after {_reload_budget}s of retries\" >> {shlex.quote(str(reload_log_path))}; "
-            f"fi"
+            f"fi; "
+            # Submitted jobs stay registered with launchd after the script
+            # exits; without this, every reload leaks one dead label. Removing
+            # our own label is the documented way to end a one-shot submit job
+            # (it SIGTERMs the job, but this is the final statement anyway).
+            f"launchctl remove {shlex.quote(submit_label)} 2>/dev/null"
         )
         try:
+            # Spawn the reload helper via `launchctl submit` (a transient
+            # launchd one-shot job) instead of `start_new_session=True`.
+            # `start_new_session=True` only calls setsid(2), which creates a
+            # new POSIX session but does NOT move the child outside the
+            # launchd job's process coalition.  When `launchctl bootout` fires
+            # on the gateway label, launchd terminates ALL processes in that
+            # coalition — including a setsid-detached child (#69098).
+            #
+            # `launchctl submit` creates a wholly independent transient launchd
+            # job that launchd manages separately from the gateway, so bootout
+            # of the gateway job cannot reach the helper.
             subprocess.Popen(
-                ["/bin/bash", "-c", reload_script],
-                start_new_session=True,
+                [
+                    "launchctl", "submit",
+                    "-l", submit_label,
+                    "-o", str(reload_log_path),
+                    "-e", str(reload_log_path),
+                    "--",
+                    "/bin/bash", "-c", reload_script,
+                ],
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
             )
         except Exception as e:
             logger.warning("Deferred launchd reload could not be spawned: %s", e)
+            _append_launchd_reload_log(
+                f"FAILED to spawn launchd reload helper for {target}: {e}"
+            )
             return False
         print(
             "↻ Updated gateway launchd service definition; reload deferred to a "
-            "detached helper (refresh ran inside the gateway process tree)"
+            "transient launchd job (refresh ran inside the gateway process tree)"
         )
         return True
 
@@ -4218,7 +4251,7 @@ def launchd_install(force: bool = False):
     if _refuse_temp_home_service_write(new_plist, "launchd plist"):
         return
     print(f"Installing launchd service to: {plist_path}")
-    plist_path.write_text(new_plist)
+    plist_path.write_text(new_plist, encoding="utf-8")
 
     try:
         _launchctl_bootstrap(
@@ -4479,7 +4512,7 @@ def launchd_status(deep: bool = False):
         result = subprocess.run(
             ["launchctl", "list", label],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
         )
         service_listed = result.returncode == 0
@@ -5437,6 +5470,9 @@ def _set_platform_unauthorized_dm_behavior(platform_key: str, behavior: str) ->
 
 def _setup_standard_platform(platform: dict):
     """Interactive setup for Telegram, Discord, or Slack."""
+    # Same hidden-knob list the dashboard/Desktop channel cards use.
+    from hermes_cli.setup_hidden_env import is_setup_hidden_env as _is_setup_hidden_env
+
     emoji = platform["emoji"]
     label = platform["label"]
     token_var = platform["token_var"]
@@ -5489,7 +5525,22 @@ def _setup_standard_platform(platform: dict):
 
     allowed_val_set = None  # Track if user set an allowlist (for home channel offer)
 
-    for var in platform["vars"]:
+    # Skip the knobs the setup forms hide (home channel, reply mode, proxy,
+    # mention behavior). They're self-configuring or already correct by
+    # default — /sethome sets the home channel on the first chat — so asking
+    # about each one turned a 2-question setup into a 5-question one. Same
+    # exclusion the dashboard/Desktop cards use, so the surfaces agree.
+    # Required credentials are never skipped.
+    required_names = {token_var}
+    setup_vars = [
+        v
+        for v in platform["vars"]
+        if v["name"] in required_names
+        or v.get("is_allowlist")
+        or not _is_setup_hidden_env(v["name"])
+    ]
+
+    for var in setup_vars:
         print()
         print_info(f"  {var['help']}")
         existing = get_env_value(var["name"])
@@ -5650,7 +5701,7 @@ def _is_service_running() -> bool:
                     ["is-active", get_service_name()],
                     system=False,
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                     timeout=10,
                 )
                 if result.stdout.strip() == "active":
@@ -5664,7 +5715,7 @@ def _is_service_running() -> bool:
                     ["is-active", get_service_name()],
                     system=True,
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                     timeout=10,
                 )
                 if result.stdout.strip() == "active":
@@ -5678,7 +5729,7 @@ def _is_service_running() -> bool:
             result = subprocess.run(
                 ["launchctl", "list", get_launchd_label()],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=10,
             )
             return result.returncode == 0
diff --git a/hermes_cli/inventory.py b/hermes_cli/inventory.py
index ff6b49ed505..e1b9a661666 100644
--- a/hermes_cli/inventory.py
+++ b/hermes_cli/inventory.py
@@ -124,6 +124,7 @@ def build_models_payload(
     refresh: bool = False,
     probe_custom_providers: bool = True,
     probe_current_custom_provider: bool = False,
+    for_picker: bool = False,
     max_models: int | None = None,
 ) -> dict:
     """Build the ``{providers, model, provider}`` shape every consumer
@@ -168,6 +169,11 @@ def build_models_payload(
       false, still live-probe the current custom endpoint. This keeps normal
       GUI/TUI picker opens fast while making the active custom provider's model
       list match the classic CLI picker.
+    - ``for_picker``: interactive-picker visibility. Keeps providers whose
+      credential pool exists but is entirely rate-limited (exhausted) in the
+      list. Rate limits are per-model, so a different model under the same
+      provider may still work; hiding the provider strands the user. Set for
+      any surface a human is choosing from, not for programmatic resolution.
     """
     from hermes_cli.model_switch import list_authenticated_providers
 
@@ -182,6 +188,7 @@ def build_models_payload(
         refresh=refresh,
         probe_custom_providers=probe_custom_providers,
         probe_current_custom_provider=probe_current_custom_provider,
+        for_picker=for_picker,
         excluded_providers=ctx.excluded_providers or [],
     )
 
@@ -263,6 +270,126 @@ def build_models_payload(
     }
 
 
+def build_model_options_payload(
+    ctx: ConfigContext,
+    *,
+    explicit_only: bool = False,
+    include_unconfigured: bool = False,
+    refresh: bool = False,
+) -> dict:
+    """Build the shared API-server/dashboard/TUI model-options payload.
+
+    This wraps ``build_models_payload`` with the stable picker shape and the
+    safe custom-provider probe policy used for normal GUI/TUI opens:
+
+    - normal open: probe only the current custom provider so offline saved
+      endpoints do not block the picker
+    - explicit refresh: probe every custom provider while busting the model
+      cache so live catalogs repopulate fully
+    """
+    refresh = bool(refresh)
+    return build_models_payload(
+        ctx,
+        explicit_only=bool(explicit_only),
+        include_unconfigured=bool(include_unconfigured),
+        picker_hints=True,
+        canonical_order=True,
+        pricing=True,
+        capabilities=True,
+        refresh=refresh,
+        probe_custom_providers=refresh,
+        probe_current_custom_provider=not refresh,
+    )
+
+
+# ─── Public: auxiliary-task pickers ─────────────────────────────────────
+
+
+def build_aux_picker_rows(
+    *,
+    current_provider: str = "",
+    current_model: str = "",
+    current_base_url: str = "",
+    max_models: int | None = None,
+) -> list[dict]:
+    """Provider rows for any auxiliary-task picker (vision, compression, …).
+
+    THE entry point for every aux picker — present and future. Call this
+    instead of ``list_authenticated_providers()`` directly.
+
+    Aux pickers kept re-deriving their own kwargs and each one silently
+    dropped a different slice of the user's configuration. Two independent
+    contributor PRs landed against the same two call sites for exactly this:
+    #52642 (user ``providers:`` / ``custom_providers:`` entries never
+    appeared) and #66624 (providers with an exhausted credential pool were
+    hidden). Both were per-site kwarg patches, so the next aux picker would
+    have reintroduced the same gap. Routing through one function makes the
+    correct behaviour the default that a new caller cannot forget:
+
+    - user-defined ``providers:`` and saved ``custom_providers:`` entries
+    - ``model_catalog.excluded_providers`` honoured, matching ``/model``
+    - exhausted-credential-pool providers stay visible (``for_picker``)
+    - the active custom endpoint is probed, offline saved ones are not, so
+      the picker never blocks on a dead local server
+
+    The virtual ``moa`` row is excluded: auxiliary tasks must not run the
+    MoA reference fan-out, and ``auxiliary_client`` unwraps a ``moa``
+    provider to its aggregator slot anyway (see ``_resolve_auto``), so
+    offering it here would be a choice silently rewritten behind the user's
+    back. Mirrors the same filter in ``hermes_cli/moa_cmd.py``.
+
+    Rows are the standard ``list_authenticated_providers`` shape. Pair with
+    :func:`format_aux_picker_entries` to render them.
+    """
+    ctx = load_picker_context().with_overrides(
+        current_provider=current_provider,
+        current_model=current_model,
+        current_base_url=current_base_url,
+    )
+    rows = build_models_payload(
+        ctx,
+        for_picker=True,
+        probe_custom_providers=False,
+        probe_current_custom_provider=True,
+        max_models=max_models,
+    )["providers"]
+    return [r for r in rows if str(r.get("slug") or "").strip().lower() != "moa"]
+
+
+def format_aux_picker_entries(
+    rows: list[dict],
+    *,
+    current_provider: str = "",
+    current_base_url: str = "",
+) -> list[tuple[str, str, list[str]]]:
+    """Render aux-picker rows as ``(slug, label, models)`` menu entries.
+
+    Owns the label text and the ``← current`` marker so every aux picker
+    presents providers identically. Callers add their own leading/trailing
+    entries (``auto``, ``Custom endpoint``, ``Back``) around this list.
+
+    A custom endpoint set via a raw ``base_url`` is "current" only through
+    that URL — never through a provider slug — so when ``current_base_url``
+    is set no provider row is marked, matching the pre-existing behaviour of
+    both call sites.
+    """
+    entries: list[tuple[str, str, list[str]]] = []
+    current_slug = str(current_provider or "").strip().lower()
+    has_base_url = bool(str(current_base_url or "").strip())
+    for row in rows:
+        slug = str(row.get("slug") or "")
+        name = row.get("name") or slug
+        total = row.get("total_models") or len(row.get("models") or [])
+        model_hint = f" — {total} models" if total else ""
+        marker = (
+            "  ← current"
+            if slug.lower() == current_slug and current_slug and not has_base_url
+            else ""
+        )
+        entries.append((slug, f"{name}{model_hint}{marker}", list(row.get("models") or [])))
+    return entries
+
+
 def _apply_capabilities(rows: list[dict]) -> None:
     """Attach a ``{model: {fast, reasoning}}`` map to each provider row.
 
diff --git a/hermes_cli/kanban.py b/hermes_cli/kanban.py
index 6bcc7651b43..d43ffba2e92 100644
--- a/hermes_cli/kanban.py
+++ b/hermes_cli/kanban.py
@@ -134,7 +134,9 @@ def _parse_branch_flag(value: Optional[str]) -> Optional[str]:
     return branch
 
 
-def _check_dispatcher_presence() -> tuple[bool, str]:
+def _check_dispatcher_presence(
+    hermes_home: Optional[Path] = None,
+) -> tuple[bool, str]:
     """Return ``(running, message)``.
 
     - ``running=True``: a gateway is alive for this HERMES_HOME and its
@@ -149,15 +151,35 @@ def _check_dispatcher_presence() -> tuple[bool, str]:
     Defensive against import failures and config-read errors — if the
     probe itself errors, we return ``(True, "")`` so we don't spam
     false warnings (better to miss a warning than to cry wolf).
+
+    ``hermes_home`` scopes the probe to a named profile's directory. The
+    dashboard plugin API passes it because the dashboard backend process can
+    be running under a different HERMES_HOME than the profile the request
+    targets, which otherwise produced a "no gateway is running" warning
+    against a perfectly healthy profile gateway (#71211). CLI callers leave
+    it ``None`` and keep the existing process-level behavior.
     """
     try:
-        from gateway.status import get_running_pid  # type: ignore
+        from gateway.status import resolve_gateway_liveness  # type: ignore
     except Exception:
         return (True, "")  # can't probe — silent
     try:
-        pid = get_running_pid()
+        # Same shared ladder the dashboard status endpoints use, so a
+        # PID-file-less (launch-service-managed) or cross-container gateway
+        # is not misreported as absent. use_cache=False: this is a one-shot
+        # CLI/create-time probe, not a polling loop, and it must observe the
+        # gateway's state right now rather than a cached snapshot.
+        liveness = resolve_gateway_liveness(
+            profile_dir=hermes_home, use_cache=False
+        )
     except Exception:
         return (True, "")  # probe errored — silent
+    if liveness.probe_error:
+        # The resolver swallows per-rung failures so status endpoints never
+        # 500. This caller must still fail OPEN: an unreadable probe means
+        # "can't tell", not "no gateway", and warning on it cries wolf.
+        return (True, "")
+    pid = liveness.pid
 
     # Even if the gateway is up, dispatch_in_gateway may be off.
     try:
diff --git a/hermes_cli/kanban_db.py b/hermes_cli/kanban_db.py
index eaf4a02a7a7..67ca9803d99 100644
--- a/hermes_cli/kanban_db.py
+++ b/hermes_cli/kanban_db.py
@@ -1366,10 +1366,20 @@ def _resolve_busy_timeout_ms() -> int:
 
 
 def _sqlite_connect(path: Path) -> sqlite3.Connection:
-    """Open a Kanban SQLite connection with consistent lock waiting."""
+    """Open a Kanban SQLite connection with consistent lock waiting.
+
+    Uses ``connect_tracked`` so the live-connection registry knows this file
+    is open: while it is, byte-level probes of the same file are refused,
+    because an ``open()``/``close()`` would cancel this process's POSIX
+    advisory locks on the database (see ``hermes_cli.sqlite_safe_read``).
+    The registration is released automatically when the connection closes.
+    """
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
     busy_timeout_ms = _resolve_busy_timeout_ms()
-    conn = sqlite3.connect(
-        str(path),
+    conn = connect_tracked(
+        path,
+        connect_fn=sqlite3.connect,
         isolation_level=None,
         timeout=busy_timeout_ms / 1000.0,
     )
@@ -1628,10 +1638,14 @@ def _validate_sqlite_header(path: Path) -> None:
         return
     if stat.st_size == 0:
         return
-    try:
-        with path.open("rb") as handle:
-            head = handle.read(64)
-    except OSError:
+    # Byte-level probe, so it must run BEFORE any connection to this path
+    # exists (connect() calls it under the init lock, ahead of _sqlite_connect).
+    # read_header_bytes_preopen refuses once a connection is live, because the
+    # close() would cancel this process's POSIX locks on the file.
+    from hermes_cli.sqlite_safe_read import read_header_bytes_preopen
+
+    head = read_header_bytes_preopen(path, length=64)
+    if head is None:
         return
     if head.startswith(_SQLITE_HEADER):
         return
@@ -1736,6 +1750,25 @@ def _backup_corrupt_db(path: Path) -> Optional[Path]:
     resolved = path.resolve()
     parent = resolved.parent
     base_name = resolved.name  # basename only
+    # This reads the whole DB file to fingerprint it. That is a close()-on-a-
+    # database-file hazard (it cancels this process's POSIX advisory locks --
+    # see hermes_cli.sqlite_safe_read), so it must only run once the board has
+    # been taken out of service. Every caller reaches here on the corrupt/
+    # quarantine path after closing its probe connection, but another
+    # SessionDB/kanban connection elsewhere in the process would still be at
+    # risk -- so REFUSE rather than warn-and-proceed. Losing a forensic copy
+    # is strictly better than corrupting the live database we are trying to
+    # rescue.
+    from hermes_cli.sqlite_safe_read import has_live_connection
+
+    if has_live_connection(resolved):
+        _log.error(
+            "refusing to quarantine %s: a connection to it is still open in "
+            "this process, and fingerprinting the file would cancel that "
+            "connection's POSIX locks. Close all connections first.",
+            resolved,
+        )
+        return None
     digest = hashlib.sha256()
     try:
         with resolved.open("rb") as handle:
@@ -2619,42 +2652,40 @@ def _rebuild_drifted_tables(conn: sqlite3.Connection) -> None:
 
 
 def _check_file_length_invariant(conn: sqlite3.Connection) -> None:
-    """Read the SQLite header page_count and compare against actual file size.
+    """Compare SQLite's own page accounting against the file size on disk.
 
     Raises sqlite3.DatabaseError if the file is shorter than the header claims
     (torn-extend corruption).
+
+    Both sides are read WITHOUT opening the database file. The header side
+    comes from ``PRAGMA page_count`` over the existing connection; the on-disk
+    side from ``stat()``. An earlier version read the header field with a bare
+    ``open(path,"rb")`` -- but ``close()`` cancels every POSIX advisory lock
+    this process holds on the file, so that probe silently dropped the locks
+    of concurrent writers (and of a running VACUUM) and let other processes
+    write into a database a writer still believed it owned. That is the
+    documented corruption route in sqlite.org/howtocorrupt.html section 2.2.
     """
+    from hermes_cli.sqlite_safe_read import file_length_matches_header
+
+    # In WAL mode a just-committed page can still live in the -wal file, so
+    # the main file legitimately lags its page count. Only enforce the
+    # invariant under a rollback journal, where every committed page must
+    # already be in the main file.
     try:
-        row = conn.execute("PRAGMA database_list").fetchone()
-        if row is None:
-            return
-        path_str = row[2]  # column 2 is the file path; empty for in-memory DBs
-        if not path_str:
-            return  # in-memory or unnamed DB; skip
-        path = path_str
-        page_size = conn.execute("PRAGMA page_size").fetchone()[0]
-        file_size = os.path.getsize(path)
-        with open(path, "rb") as f:
-            f.seek(28)
-            header_bytes = f.read(4)
-        if len(header_bytes) < 4:
-            return  # can't read header; skip
-        header_page_count = int.from_bytes(header_bytes, "big")
-        if header_page_count == 0:
-            return  # new/empty DB; skip
-        actual_pages = file_size // page_size
-        if actual_pages < header_page_count:
-            raise sqlite3.DatabaseError(
-                f"torn-extend detected: page count mismatch on {path}: "
-                f"header claims {header_page_count} pages, "
-                f"file has {actual_pages} pages "
-                f"(missing {header_page_count - actual_pages} pages, "
-                f"file_size={file_size}, page_size={page_size})"
-            )
-    except sqlite3.DatabaseError:
-        raise
-    except Exception:
-        pass  # I/O errors during check are non-fatal; let normal ops continue
+        row = conn.execute("PRAGMA journal_mode").fetchone()
+        journal_mode = str(row[0]).lower() if row and row[0] is not None else ""
+    except sqlite3.Error:
+        return
+    if journal_mode == "wal":
+        return
+
+    ok = file_length_matches_header(conn)
+    if ok is False:
+        raise sqlite3.DatabaseError(
+            "torn-extend detected: the database file is shorter than its "
+            "header page count claims"
+        )
 
 
 # SQLite's own busy_timeout uses a near-deterministic backoff, so concurrent
@@ -5212,7 +5243,7 @@ def _cleanup_worker_tmux(conn: sqlite3.Connection, task_id: str) -> None:
         # Check if session exists and pane is dead before killing
         out = subprocess.run(
             ["tmux", "list-panes", "-t", session, "-F", "#{pane_dead}"],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
         )
         if out.stdout.strip() == "1":
             subprocess.run(
@@ -6138,7 +6169,7 @@ def _git_toplevel(path: Path) -> Optional[Path]:
         result = subprocess.run(
             ["git", "-C", str(path), "rev-parse", "--show-toplevel"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=30,
             check=False,
         )
@@ -6160,7 +6191,7 @@ def _git_branch_exists(repo_root: Path, branch_name: str) -> bool:
         result = subprocess.run(
             ["git", "-C", str(repo_root), "show-ref", "--verify", f"refs/heads/{branch_name}"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=30,
             check=False,
         )
@@ -6174,7 +6205,7 @@ def _git_common_dir(path: Path) -> Optional[Path]:
         result = subprocess.run(
             ["git", "-C", str(path), "rev-parse", "--path-format=absolute", "--git-common-dir"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=30,
             check=False,
         )
@@ -6193,7 +6224,7 @@ def _git_dir(path: Path) -> Optional[Path]:
         result = subprocess.run(
             ["git", "-C", str(path), "rev-parse", "--path-format=absolute", "--git-dir"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=30,
             check=False,
         )
@@ -6212,7 +6243,7 @@ def _git_current_branch(path: Path) -> Optional[str]:
         result = subprocess.run(
             ["git", "-C", str(path), "branch", "--show-current"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=30,
             check=False,
         )
@@ -6269,7 +6300,7 @@ def _ensure_git_worktree(repo_root: Path, target: Path, branch_name: str) -> Non
     result = subprocess.run(
         cmd,
         capture_output=True,
-        text=True,
+        text=True, encoding='utf-8', errors='replace',
         timeout=60,
         check=False,
     )
@@ -6765,7 +6796,7 @@ def _pid_alive(pid: Optional[int]) -> bool:
                 ["ps", "-o", "stat=", "-p", str(int(pid))],
                 stdout=subprocess.PIPE,
                 stderr=subprocess.DEVNULL,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=1,
                 check=False,
             )
diff --git a/hermes_cli/main.py b/hermes_cli/main.py
index fcca52b8851..be6b7fce045 100644
--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -61,6 +61,15 @@ try:
 except ModuleNotFoundError:
     pass
 
+# Windows: neutralize CPython's ``platform._syscmd_ver`` before anything else
+# imports — it shells out ``cmd /c ver`` (shell=True, no CREATE_NO_WINDOW), so
+# any dependency touching ``platform.uname()`` at import time flashes a
+# visible console when this process is windowless (pythonw gateway + every
+# kanban worker).  No-op on POSIX; never raises.
+from hermes_cli._subprocess_compat import suppress_platform_ver_console
+
+suppress_platform_ver_console()
+
 import os
 import sys
 
@@ -630,7 +639,7 @@ def _apply_profile_override() -> None:
 
             active_path = get_default_hermes_root() / "active_profile"
             if active_path.exists():
-                name = active_path.read_text().strip()
+                name = active_path.read_text(encoding="utf-8").strip()
                 if name and name != "default":
                     profile_name = name
                     consume = 0  # don't strip anything from argv
@@ -1012,7 +1021,7 @@ def _has_any_provider_configured() -> bool:
         try:
             import json
 
-            auth = json.loads(auth_file.read_text())
+            auth = json.loads(auth_file.read_text(encoding="utf-8"))
             active = auth.get("active_provider")
             if active:
                 status = get_auth_status(active)
@@ -1321,7 +1330,7 @@ def _probe_container(cmd: list, backend: str, via_sudo: bool = False):
     all other exceptions propagate naturally.
     """
     try:
-        return subprocess.run(cmd, capture_output=True, text=True, timeout=15)
+        return subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=15)
     except subprocess.TimeoutExpired:
         label = f"sudo {backend}" if via_sudo else backend
         print(
@@ -1834,7 +1843,7 @@ def _restore_tui_workspace(tui_dir: Path) -> bool:
             [git, "restore", "--", tui_dir.name],
             cwd=str(tui_dir.parent),
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             check=False,
         )
     except OSError:
@@ -3617,13 +3626,16 @@ def _aux_config_menu() -> None:
 def _aux_select_for_task(task: str) -> None:
     """Pick a provider + model for a single auxiliary task and persist it.
 
-    Uses ``list_authenticated_providers()`` to only show providers the user
-    has already configured. This avoids re-running OAuth/credential flows
-    inside the aux picker — users set up new providers through the normal
-    ``hermes model`` flow, then route aux tasks to them here.
+    Provider rows come from ``build_aux_picker_rows()`` — the shared aux-picker
+    substrate — so this surface shows exactly what every other aux picker
+    shows: authenticated built-ins, the user's own ``providers:`` /
+    ``custom_providers:`` endpoints, and providers whose credential pool is
+    temporarily exhausted. Only already-configured providers appear; users set
+    up new ones through the normal ``hermes model`` flow, then route aux tasks
+    to them here.
     """
     from hermes_cli.config import load_config
-    from hermes_cli.model_switch import list_authenticated_providers
+    from hermes_cli.inventory import build_aux_picker_rows, format_aux_picker_entries
 
     cfg = load_config()
     aux = cfg.get("auxiliary", {}) if isinstance(cfg.get("auxiliary"), dict) else {}
@@ -3636,7 +3648,7 @@ def _aux_select_for_task(task: str) -> None:
 
     # Gather authenticated providers (has credentials + curated model list)
     try:
-        providers = list_authenticated_providers(
+        providers = build_aux_picker_rows(
             current_provider=current_provider,
             current_model=current_model,
             current_base_url=current_base_url,
@@ -3652,16 +3664,13 @@ def _aux_select_for_task(task: str) -> None:
     )
     entries.append(("__auto__", f"auto (recommended){auto_marker}", []))
 
-    for p in providers:
-        slug = p.get("slug", "")
-        name = p.get("name") or slug
-        total = p.get("total_models", 0)
-        models = p.get("models") or []
-        model_hint = f" — {total} models" if total else ""
-        marker = (
-            "  ← current" if slug == current_provider and not current_base_url else ""
+    entries.extend(
+        format_aux_picker_entries(
+            providers,
+            current_provider=current_provider,
+            current_base_url=current_base_url,
         )
-        entries.append((slug, f"{name}{model_hint}{marker}", list(models)))
+    )
 
     # Custom endpoint (raw base_url)
     custom_marker = "  ← current" if current_base_url else ""
@@ -3966,13 +3975,17 @@ def _custom_provider_base_url_config_value(provider_info, resolved_base_url=""):
 
 
 def _save_custom_provider(
-    base_url, api_key="", model="", context_length=None, name=None, api_mode=None
+    base_url, api_key="", model="", context_length=None, name=None, api_mode=None,
+    key_env=""
 ):
     """Save a custom endpoint to custom_providers in config.yaml.
 
     Deduplicates by base_url — if the URL already exists, updates the
     model name, context_length, and api_mode but doesn't add a duplicate entry.
     Uses *name* when provided, otherwise auto-generates from the URL.
+
+    When *key_env* is set the caller has already written the key to ``.env``,
+    so the entry references it instead of inlining the secret (#69449).
     """
     from hermes_cli.config import load_config, save_config
 
@@ -4004,6 +4017,10 @@ def _save_custom_provider(
             elif "api_mode" in entry:
                 entry.pop("api_mode", None)
                 changed = True
+            if key_env and (entry.get("key_env") != key_env or entry.get("api_key")):
+                entry["key_env"] = key_env
+                entry.pop("api_key", None)
+                changed = True
             if changed:
                 cfg["custom_providers"] = providers
                 save_config(cfg)
@@ -4014,7 +4031,9 @@ def _save_custom_provider(
         name = _auto_provider_name(base_url)
 
     entry = {"name": name, "base_url": base_url}
-    if api_key:
+    if key_env:
+        entry["key_env"] = key_env
+    elif api_key:
         entry["api_key"] = api_key
     if model:
         entry["model"] = model
@@ -4720,7 +4739,7 @@ def _capture_head_sha(git_cmd, cwd) -> str | None:
             git_cmd + ["rev-parse", "HEAD"],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             check=True,
         )
         return result.stdout.strip() or None
@@ -4797,7 +4816,7 @@ def _gateway_prompt(prompt_text: str, default: str = "", timeout: float = 300.0)
         "id": str(_uuid.uuid4()),
     }
     tmp = prompt_path.with_suffix(".tmp")
-    tmp.write_text(_json.dumps(payload))
+    tmp.write_text(_json.dumps(payload), encoding="utf-8")
     tmp.replace(prompt_path)
 
     # Poll for response
@@ -4805,7 +4824,7 @@ def _gateway_prompt(prompt_text: str, default: str = "", timeout: float = 300.0)
     while _time.monotonic() < deadline:
         if response_path.exists():
             try:
-                answer = response_path.read_text().strip()
+                answer = response_path.read_text(encoding="utf-8").strip()
                 response_path.unlink(missing_ok=True)
                 prompt_path.unlink(missing_ok=True)
                 return answer if answer else default
@@ -5079,7 +5098,7 @@ def _nixos_build_env() -> dict[str, str] | None:
     try:
         result = subprocess.run(
             ["nix-shell", "-p", "python3", "--run", "which python3"],
-            capture_output=True, text=True, check=False, timeout=15,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", check=False, timeout=15,
         )
         if result.returncode == 0:
             python3_path = result.stdout.strip()
@@ -5498,9 +5517,356 @@ def _desktop_packaged_executable(desktop_dir: Path) -> Optional[Path]:
     existing = [p for p in candidates if p.exists()]
     if not existing:
         return None
+    if sys.platform == "win32" and len(existing) > 1:
+        # Multiple unpacked trees can coexist (e.g. a stale win-arm64-unpacked
+        # left behind by a cross-arch experiment next to the real win-unpacked).
+        # Picking purely by mtime can then hand a wrong-architecture Hermes.exe
+        # to the launcher, which Windows rejects with "This app can't run on
+        # your computer" (#69179). Prefer candidates whose PE machine field
+        # matches the host; fall back to mtime when none can be parsed.
+        expected = _expected_windows_pe_machines()
+        matching = [p for p in existing if _pe_machine_or_none(p) in expected]
+        if matching:
+            existing = matching
     return max(existing, key=lambda p: p.stat().st_mtime)
 
 
+# ─── Desktop exe integrity gate (#69179) ────────────────────────────────────
+#
+# The desktop self-update chain (Desktop → hermes-setup --update →
+# `hermes update` → `hermes desktop --build-only` → relaunch) rebuilds
+# Hermes.exe on the end user's machine and used to verify only that the file
+# EXISTS before declaring success. A corrupt cached Electron zip whose
+# extraction produced a truncated electron.exe, an interrupted rcedit resource
+# rewrite, a disk-full pack, or a wrong-arch unpacked tree therefore shipped a
+# broken binary that Windows refuses to load ("This app can't run on your
+# computer" / 此应用无法在你的电脑上运行). These helpers parse the PE header —
+# no signature infrastructure required — so a structurally broken or
+# wrong-architecture Hermes.exe is caught BEFORE the updater replaces the
+# working app, and the previous build can be restored from the .bak tree that
+# apps/desktop/scripts/before-pack.mjs now preserves.
+
+_PE_MACHINE_I386 = 0x014C
+_PE_MACHINE_AMD64 = 0x8664
+_PE_MACHINE_ARM64 = 0xAA64
+
+_PE_MACHINE_NAMES = {
+    _PE_MACHINE_I386: "x86 (32-bit)",
+    _PE_MACHINE_AMD64: "x64 (AMD64)",
+    _PE_MACHINE_ARM64: "ARM64",
+}
+
+_PE_MACHINE_TO_NAME = {
+    _PE_MACHINE_ARM64: "ARM64",
+    _PE_MACHINE_AMD64: "AMD64",
+    _PE_MACHINE_I386: "X86",
+}
+
+# MACHINE_ATTRIBUTES bits (processthreadsapi.h). UserEnabled means the host
+# can run user-mode code of that machine type — natively or under emulation.
+_MACHINE_ATTRIBUTE_USER_ENABLED = 0x00000001
+
+
+def _windows_native_machine_from_iswow64() -> Optional[str]:
+    """Ask IsWow64Process2 for the OS-native machine (None if unavailable/fail).
+
+    ctypes defaults ``GetCurrentProcess``'s restype to ``c_int``, so the
+    current-process pseudo-handle ``(HANDLE)-1`` is truncated to
+    ``0xFFFFFFFF`` and zero-extended into a 64-bit invalid handle. On Win64
+    that makes ``IsWow64Process2`` fail with ``ERROR_INVALID_HANDLE`` (6),
+    which is exactly the residual Windows-on-ARM failure after #71218: the
+    gate fell through to ``PROCESSOR_ARCHITECTURE=AMD64`` (the emulated
+    process arch) and rejected a correctly-built ARM64 ``Hermes.exe``.
+    Binding ``restype``/``argtypes`` to ``wintypes.HANDLE`` keeps the full
+    ``0xFFFFFFFFFFFFFFFF`` pseudo-handle.
+    """
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.GetCurrentProcess.restype = wintypes.HANDLE
+    kernel32.GetCurrentProcess.argtypes = []
+    kernel32.IsWow64Process2.argtypes = [
+        wintypes.HANDLE,
+        ctypes.POINTER(wintypes.USHORT),
+        ctypes.POINTER(wintypes.USHORT),
+    ]
+    kernel32.IsWow64Process2.restype = wintypes.BOOL
+
+    process_machine = wintypes.USHORT(0)
+    native_machine = wintypes.USHORT(0)
+    if not kernel32.IsWow64Process2(
+        kernel32.GetCurrentProcess(),
+        ctypes.byref(process_machine),
+        ctypes.byref(native_machine),
+    ):
+        return None
+    return _PE_MACHINE_TO_NAME.get(native_machine.value)
+
+
+def _windows_user_runnable_pe_machines() -> Optional[set]:
+    """PE machines this host can run in user mode, via GetMachineTypeAttributes.
+
+    This asks the question the integrity gate actually cares about — "can this
+    Windows host load a PE of machine X?" — instead of inferring it from a
+    host-architecture name. It is also the only documented API that reports
+    AMD64-on-ARM64 emulation support; ``IsWow64GuestMachineSupported`` only
+    answers for 32-bit guests.
+
+    Returns None when the API is unavailable (pre-Windows-11 build 22000) or
+    reports nothing runnable, so callers fall back to name-based detection.
+    """
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.GetMachineTypeAttributes.argtypes = [
+        wintypes.USHORT,
+        ctypes.POINTER(ctypes.c_int),
+    ]
+    kernel32.GetMachineTypeAttributes.restype = ctypes.c_long
+
+    runnable = set()
+    for machine in (_PE_MACHINE_ARM64, _PE_MACHINE_AMD64, _PE_MACHINE_I386):
+        attributes = ctypes.c_int(0)
+        # HRESULT: zero is success, any nonzero value is a failure.
+        if kernel32.GetMachineTypeAttributes(machine, ctypes.byref(attributes)):
+            continue
+        if attributes.value & _MACHINE_ATTRIBUTE_USER_ENABLED:
+            runnable.add(machine)
+    return runnable or None
+
+
+def _windows_native_machine() -> str:
+    """The Windows host OS's NATIVE machine architecture, normalized upper.
+
+    ``platform.machine()`` reports the PROCESS architecture, which lies under
+    emulation: the desktop update chain runs an x64 hermes-setup.exe (and thus
+    x64 Python) on Windows-on-ARM devices, where ``platform.machine()``
+    returns ``AMD64`` even though the OS is ARM64. The #71119 integrity gate
+    then rejected the CORRECT ARM64 rebuild as an "architecture mismatch"
+    (#69179 follow-up report). Probe order:
+
+    1. ``IsWow64Process2`` with a correctly-typed current-process HANDLE
+       (#71218 + HANDLE-truncation fix). This is the only API that tells the
+       truth from an x64 process emulated on ARM64.
+    2. ``PROCESSOR_ARCHITEW6432`` / ``PROCESSOR_ARCHITECTURE`` — WOW64
+       (32-bit) hosts and pre-1511 Windows 10 without the newer API.
+    3. ``platform.machine()``.
+
+    Note ``GetNativeSystemInfo`` is deliberately NOT used: Microsoft documents
+    that it "also returns emulated processor details when run from an app
+    under emulation", so on the very WoA hosts this function exists to serve
+    it reports AMD64 — no better than the env-var rung below it.
+    """
+    if sys.platform == "win32":
+        try:
+            name = _windows_native_machine_from_iswow64()
+        except (OSError, AttributeError, TypeError, ValueError):
+            # API missing (pre-1511), DLL load failure in tests, or a
+            # mistyped ctypes binding — fall through to the env vars.
+            name = None
+        if name:
+            return name
+        env_arch = os.environ.get("PROCESSOR_ARCHITEW6432") or os.environ.get(
+            "PROCESSOR_ARCHITECTURE"
+        )
+        if env_arch:
+            return env_arch.upper()
+    import platform as _platform
+
+    return (_platform.machine() or "").upper()
+
+
+def _expected_windows_pe_machines() -> set:
+    """PE machine values the current Windows host can natively load.
+
+    Preferred source is ``GetMachineTypeAttributes``, which answers this
+    question directly (including AMD64-on-ARM64 emulation) instead of
+    inferring it from an architecture name.
+
+    Fallback is name-based: AMD64 hosts run x64 and (via WOW64) x86. ARM64
+    hosts run ARM64 and (Windows 11 emulation) x64. 32-bit x86 hosts run only
+    x86. Unknown machines return the permissive full set so the integrity gate
+    can never brick launch on exotic hosts. Host detection uses the OS-native
+    machine (see ``_windows_native_machine``), not the process architecture.
+    """
+    if sys.platform == "win32":
+        try:
+            runnable = _windows_user_runnable_pe_machines()
+        except (OSError, AttributeError, TypeError, ValueError):
+            runnable = None
+        if runnable:
+            return runnable
+    machine = _windows_native_machine().upper()
+    if machine in ("AMD64", "X86_64", "X64"):
+        return {_PE_MACHINE_AMD64, _PE_MACHINE_I386}
+    if machine in ("ARM64", "AARCH64"):
+        return {_PE_MACHINE_ARM64, _PE_MACHINE_AMD64}
+    if machine in ("X86", "I386", "I486", "I586", "I686"):
+        return {_PE_MACHINE_I386}
+    return {_PE_MACHINE_AMD64, _PE_MACHINE_ARM64, _PE_MACHINE_I386}
+
+
+def _parse_pe_machine(path: Path) -> int:
+    """Parse ``path`` as a PE executable and return its COFF machine field.
+
+    Raises ``ValueError`` with a human-readable reason when the file is not a
+    structurally complete PE: missing MZ/PE magic (an HTML error page or JSON
+    body saved as .exe), header truncation, or raw section data extending past
+    the end of the file (the truncated-download / interrupted-extraction
+    shape). Purely a header walk — cheap even on a 200 MB Electron exe.
+    """
+    import struct
+
+    try:
+        file_size = path.stat().st_size
+    except OSError as exc:
+        raise ValueError(f"unreadable: {exc}")
+    if file_size < 512:
+        raise ValueError(
+            f"file is only {file_size} bytes — far too small to be a Windows executable"
+        )
+    with path.open("rb") as fh:
+        head = fh.read(64)
+        if len(head) < 64 or head[:2] != b"MZ":
+            raise ValueError(
+                "missing MZ header — not a Windows executable "
+                "(a truncated or non-binary file saved as .exe?)"
+            )
+        e_lfanew = struct.unpack_from("<I", head, 0x3C)[0]
+        if e_lfanew <= 0 or e_lfanew + 24 > file_size:
+            raise ValueError("corrupt DOS header: PE header offset points past end of file")
+        fh.seek(e_lfanew)
+        pe_head = fh.read(24)
+        if len(pe_head) < 24 or pe_head[:4] != b"PE\x00\x00":
+            raise ValueError("missing PE signature — corrupt executable header")
+        machine, n_sections = struct.unpack_from("<HH", pe_head, 4)
+        size_of_optional = struct.unpack_from("<H", pe_head, 20)[0]
+        fh.seek(e_lfanew + 24 + size_of_optional)
+        max_section_end = 0
+        for _ in range(n_sections):
+            section = fh.read(40)
+            if len(section) < 40:
+                raise ValueError("truncated PE section table")
+            size_of_raw, pointer_to_raw = struct.unpack_from("<II", section, 16)
+            max_section_end = max(max_section_end, pointer_to_raw + size_of_raw)
+        if file_size < max_section_end:
+            raise ValueError(
+                f"truncated executable: file is {file_size} bytes but its PE "
+                f"sections extend to {max_section_end} bytes"
+            )
+    return machine
+
+
+def _pe_machine_or_none(path: Path) -> Optional[int]:
+    try:
+        return _parse_pe_machine(path)
+    except ValueError:
+        return None
+
+
+def _desktop_exe_integrity_error(path: Path) -> Optional[str]:
+    """Return a human-readable reason ``path`` cannot run on this Windows host,
+    or ``None`` when the exe parses as a complete PE of a loadable architecture.
+    """
+    try:
+        machine = _parse_pe_machine(path)
+    except ValueError as exc:
+        return str(exc)
+    expected = _expected_windows_pe_machines()
+    if machine not in expected:
+        got = _PE_MACHINE_NAMES.get(machine, f"unknown machine 0x{machine:04X}")
+        return (
+            f"architecture mismatch: built a {got} executable but this is a "
+            f"{_windows_native_machine()} Windows host"
+        )
+    return None
+
+
+def _desktop_backup_unpacked_dir(packaged_executable: Path) -> Path:
+    """The rollback tree before-pack.mjs preserves: ``<unpacked-dir>.bak``."""
+    unpacked = packaged_executable.parent
+    return unpacked.parent / (unpacked.name + ".bak")
+
+
+def _rollback_desktop_from_backup(packaged_executable: Path) -> Optional[Path]:
+    """Restore the previous unpacked desktop app from its ``.bak`` tree.
+
+    Returns the restored executable path, or ``None`` when no usable backup
+    exists (missing, or its exe fails the same integrity probe). The corrupt
+    tree is kept alongside as ``<unpacked-dir>.corrupt`` for diagnostics.
+    Best-effort: never raises.
+    """
+    unpacked = packaged_executable.parent
+    backup_dir = _desktop_backup_unpacked_dir(packaged_executable)
+    backup_exe = backup_dir / packaged_executable.name
+    if not backup_exe.exists():
+        return None
+    if _desktop_exe_integrity_error(backup_exe) is not None:
+        return None
+    corrupt_dir = unpacked.parent / (unpacked.name + ".corrupt")
+    try:
+        shutil.rmtree(corrupt_dir, ignore_errors=True)
+        try:
+            unpacked.rename(corrupt_dir)
+        except OSError:
+            shutil.rmtree(unpacked, ignore_errors=True)
+        backup_dir.rename(unpacked)
+    except OSError:
+        return None
+    restored = unpacked / packaged_executable.name
+    return restored if restored.exists() else None
+
+
+def _ensure_desktop_exe_launchable(
+    desktop_dir: Path, packaged_executable: Optional[Path]
+) -> tuple:
+    """Windows post-build integrity gate for the self-update rebuild (#69179).
+
+    Returns ``(verified_exe_or_None, rolled_back)``:
+
+    - exe passed the probe → ``(exe, False)``
+    - exe corrupt/wrong-arch, previous build restored → ``(old_exe, True)``
+    - exe corrupt and nothing restorable → ``(None, False)``
+
+    On any integrity failure the corrupt cached Electron zip is purged and the
+    desktop build stamp invalidated, so the updater's retry-once rebuild pulls
+    a fresh, SHASUM-verified Electron download instead of re-staging the same
+    corrupt bytes. No-op off Windows and when there is no executable to check.
+    """
+    if packaged_executable is None or sys.platform != "win32":
+        return packaged_executable, False
+
+    error = _desktop_exe_integrity_error(packaged_executable)
+    if error is None:
+        return packaged_executable, False
+
+    print(f"✗ The built Hermes.exe failed its integrity check: {error}")
+    print(f"    at: {packaged_executable}")
+
+    # Self-heal setup for the retry: drop the (likely corrupt) cached Electron
+    # zip and the content stamp so the next rebuild is a genuine re-download +
+    # re-stage rather than a replay of the same broken extraction.
+    _purge_electron_build_cache(desktop_dir)
+    try:
+        _desktop_stamp_path().unlink()
+    except OSError:
+        pass
+
+    restored = _rollback_desktop_from_backup(packaged_executable)
+    if restored is not None:
+        print("  ↩ Update aborted — restored the previous working Hermes.exe from backup.")
+        print("    Your existing version was kept and still works. Run `hermes desktop`")
+        print("    (or the in-app update) again to retry with a fresh Electron download.")
+        return restored, True
+
+    print("  ✗ No usable backup was found to restore.")
+    print("    Run `hermes desktop --force-build` to rebuild, or re-run the Hermes")
+    print("    installer to repair the install.")
+    return None, False
+
+
 def _electron_download_cache_dirs() -> list[Path]:
     """Return the per-user Electron download cache directories for this OS.
 
@@ -6142,6 +6508,22 @@ def cmd_gui(args: argparse.Namespace):
                 # damaged"). No-op on non-macOS and on real-identity builds.
                 _desktop_macos_relaunchable_fixup(desktop_dir)
 
+                # Windows integrity gate (#69179): never declare the rebuild a
+                # success on a Hermes.exe Windows cannot load (truncated PE from
+                # a corrupt cached Electron zip, wrong-arch tree, interrupted
+                # rcedit rewrite). Roll back to the .bak tree preserved by
+                # before-pack.mjs when possible, then fail loudly so the
+                # updater's retry-once rebuilds from a fresh Electron download
+                # instead of silently shipping the broken exe.
+                verified_executable, rolled_back = _ensure_desktop_exe_launchable(
+                    desktop_dir, packaged_executable
+                )
+                if packaged_executable is not None and (
+                    rolled_back or verified_executable is None
+                ):
+                    sys.exit(1)
+                packaged_executable = verified_executable
+
             # Build succeeded — write the stamp so next run can skip
             _write_desktop_build_stamp(PROJECT_ROOT, source_mode=source_mode)
 
@@ -6281,7 +6663,7 @@ def _find_stale_dashboard_pids(
             result = subprocess.run(
                 ["ps", "-A", "-o", "pid=,command="],
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
                 timeout=10,
             )
             if result.returncode == 0:
@@ -6570,7 +6952,7 @@ def _restart_managed_dashboard_service(
         return subprocess.run(
             ["systemctl", *args],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=timeout,
         )
 
@@ -6634,7 +7016,7 @@ def _restart_managed_dashboard_service(
             result = subprocess.run(
                 list(command),
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
                 timeout=60,
             )
         except (FileNotFoundError, subprocess.TimeoutExpired, OSError) as e:
@@ -6723,7 +7105,7 @@ def _kill_stale_dashboard_processes(
                 result = subprocess.run(
                     ["taskkill", "/PID", str(pid), "/F"],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding="utf-8", errors="replace",
                     timeout=10,
                 )
                 if result.returncode == 0:
@@ -6998,6 +7380,11 @@ def _update_via_zip(args):
             )
         if result.get("cleaned"):
             print(f"  − {len(result['cleaned'])} removed from manifest")
+        if result.get("relocated"):
+            print(
+                f"  → {len(result['relocated'])} moved to new upstream paths: "
+                f"{', '.join(result['relocated'])}"
+            )
         if not result["copied"] and not result.get("updated"):
             print("  ✓ Skills are up to date")
     except Exception:
@@ -7013,6 +7400,66 @@ def _update_via_zip(args):
     except Exception as e:
         logger.debug("Model catalog seed during zip update failed: %s", e)
 
+    # ── Post-update state.db integrity guard (#68474) ─────────────────
+    # Same as the git-pull path: verify state.db survived the ZIP update
+    # and auto-restore from the most recent pre-update snapshot if needed.
+    try:
+        from hermes_cli.backup import _quick_snapshot_root, verify_sqlite_integrity
+
+        _state_path = get_hermes_home() / "state.db"
+        if _state_path.exists():
+            _state_ok = verify_sqlite_integrity(
+                _state_path, check_header=True, run_pragma=True
+            )
+            if not _state_ok.get("valid"):
+                print()
+                print(
+                    "⚠ state.db is corrupted after update: "
+                    + _state_ok.get("message", "unknown error")
+                )
+                _snap_root = _quick_snapshot_root(get_hermes_home())
+                if _snap_root.exists():
+                    _snap_dirs = sorted(
+                        (d for d in _snap_root.iterdir() if d.is_dir()),
+                        reverse=True,
+                    )
+                    for _snap_dir in _snap_dirs:
+                        _snap_state = _snap_dir / "state.db"
+                        if _snap_state.exists():
+                            _snap_ok = verify_sqlite_integrity(
+                                _snap_state, check_header=True, run_pragma=True
+                            )
+                            if _snap_ok.get("valid"):
+                                try:
+                                    import shutil as _shutil
+
+                                    _shutil.copy2(_snap_state, _state_path)
+                                    _restored_ok = verify_sqlite_integrity(
+                                        _state_path,
+                                        check_header=True,
+                                        run_pragma=True,
+                                    )
+                                    if _restored_ok.get("valid"):
+                                        print(
+                                            "  ✓ Auto-restored from snapshot "
+                                            f"{_snap_dir.name}"
+                                        )
+                                    else:
+                                        print(
+                                            "  ✗ Auto-restore FAILED — restored "
+                                            "copy also failed integrity"
+                                        )
+                                    break
+                                except OSError as _exc:
+                                    print(
+                                        f"  ✗ Auto-restore file copy failed: {_exc}"
+                                    )
+                                    break
+    except Exception as exc:
+        logger.debug(
+            "Post-update state.db integrity check (zip path) failed: %s", exc
+        )
+
     print()
     if node_failures:
         print(
@@ -7046,7 +7493,7 @@ def _stash_local_changes_if_needed(git_cmd: list[str], cwd: Path) -> Optional[st
         git_cmd + ["status", "--porcelain"],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         check=True,
     )
     if not status.stdout.strip():
@@ -7060,7 +7507,7 @@ def _stash_local_changes_if_needed(git_cmd: list[str], cwd: Path) -> Optional[st
         git_cmd + ["ls-files", "--unmerged"],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     )
     if unmerged.stdout.strip():
         print("→ Clearing unmerged index entries from a previous conflict...")
@@ -7076,13 +7523,13 @@ def _stash_local_changes_if_needed(git_cmd: list[str], cwd: Path) -> Optional[st
         git_cmd + ["rev-parse", "--verify", "refs/stash"],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     ).stdout.strip()
     push = subprocess.run(
         git_cmd + ["stash", "push", "--include-untracked", "-m", stash_name],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     )
     if push.stdout.strip():
         print(push.stdout.strip())
@@ -7090,7 +7537,7 @@ def _stash_local_changes_if_needed(git_cmd: list[str], cwd: Path) -> Optional[st
         git_cmd + ["rev-parse", "--verify", "refs/stash"],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     )
     stash_ref = stash_probe.stdout.strip()
     stash_created = (
@@ -7148,7 +7595,7 @@ def _resolve_stash_selector(
         git_cmd + ["stash", "list", "--format=%gd %H"],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         check=True,
     )
     for line in stash_list.stdout.splitlines():
@@ -7233,7 +7680,7 @@ def _restore_stashed_changes(
         git_cmd + ["stash", "apply", stash_ref],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     )
 
     # Check for unmerged (conflicted) files — can happen even when returncode is 0
@@ -7241,7 +7688,7 @@ def _restore_stashed_changes(
         git_cmd + ["diff", "--name-only", "--diff-filter=U"],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     )
     has_conflicts = bool(unmerged.stdout.strip())
 
@@ -7303,7 +7750,7 @@ def _restore_stashed_changes(
             git_cmd + ["stash", "drop", stash_selector],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         if drop.returncode != 0:
             print(
@@ -7355,7 +7802,7 @@ def _discard_stashed_changes(
         git_cmd + ["stash", "drop", stash_selector],
         cwd=cwd,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     )
     if drop.returncode != 0:
         print(
@@ -7392,7 +7839,7 @@ def _get_origin_url(git_cmd: list[str], cwd: Path) -> Optional[str]:
             git_cmd + ["remote", "get-url", "origin"],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         if result.returncode == 0:
             return result.stdout.strip()
@@ -7425,7 +7872,7 @@ def _has_upstream_remote(git_cmd: list[str], cwd: Path) -> bool:
             git_cmd + ["remote", "get-url", "upstream"],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         return result.returncode == 0
     except Exception:
@@ -7439,7 +7886,7 @@ def _add_upstream_remote(git_cmd: list[str], cwd: Path) -> bool:
             git_cmd + ["remote", "add", "upstream", OFFICIAL_REPO_URL],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         return result.returncode == 0
     except Exception:
@@ -7453,7 +7900,7 @@ def _count_commits_between(git_cmd: list[str], cwd: Path, base: str, head: str)
             git_cmd + ["rev-list", "--count", f"{base}..{head}"],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         if result.returncode == 0:
             return int(result.stdout.strip())
@@ -7489,7 +7936,7 @@ def _sync_fork_with_upstream(git_cmd: list[str], cwd: Path) -> bool:
             git_cmd + ["push", "origin", "main", "--force-with-lease"],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         return result.returncode == 0
     except Exception:
@@ -8514,6 +8961,7 @@ def _detect_broken_lazy_refresh_imports(
         f"    ({mod!r}, {attr!r})," for mod, attr in _LAZY_REFRESH_IMPORT_PROBES
     )
     check_script = (
+        "import os\n"
         "import sys\n"
         "probes = [\n"
         f"{probe_lines}\n"
@@ -8524,6 +8972,13 @@ def _detect_broken_lazy_refresh_imports(
         "        imported = __import__(mod)\n"
         "        if not hasattr(imported, attr):\n"
         "            broken.append(mod)\n"
+        "        elif mod == 'certifi':\n"
+        "            # The module can import cleanly while cacert.pem is\n"
+        "            # missing/corrupt (brew Python upgrade, interrupted venv\n"
+        "            # rebuild) - every TLS call then fails (#29866).\n"
+        "            bundle = imported.where()\n"
+        "            if not os.path.isfile(bundle) or os.path.getsize(bundle) < 1024:\n"
+        "                broken.append(mod)\n"
         "    except Exception:\n"
         "        broken.append(mod)\n"
         "print('\\n'.join(broken))\n"
@@ -8532,7 +8987,7 @@ def _detect_broken_lazy_refresh_imports(
         result = subprocess.run(
             [str(venv_python), "-c", check_script],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             check=False,
             env=env,
         )
@@ -8991,7 +9446,7 @@ def _verify_core_dependencies_installed(
             result = subprocess.run(
                 [str(venv_python), "-c", check_script, *applicable],
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
                 check=False,
                 env=env,
             )
@@ -9713,7 +10168,7 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
             git_cmd + ["rev-parse", "--is-shallow-repository"],
             cwd=PROJECT_ROOT,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         ).stdout.strip()
         == "true"
     )
@@ -9725,7 +10180,7 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
             git_cmd + ["fetch"] + depth_args + ["upstream", branch],
             cwd=PROJECT_ROOT,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         if fetch_result.returncode != 0:
             # Fallback to origin if upstream doesn't exist
@@ -9734,7 +10189,7 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
                 git_cmd + ["fetch"] + depth_args + ["origin", branch],
                 cwd=PROJECT_ROOT,
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
             )
             upstream_exists = False
             compare_branch = f"origin/{branch}"
@@ -9748,7 +10203,7 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
             git_cmd + ["fetch"] + depth_args + ["origin", branch],
             cwd=PROJECT_ROOT,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         upstream_exists = False
         compare_branch = f"origin/{branch}"
@@ -9773,7 +10228,7 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
         git_cmd + ["rev-parse", "--verify", "--quiet", compare_branch],
         cwd=PROJECT_ROOT,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     )
     if verify_result.returncode != 0:
         print(f"✗ Branch '{branch}' not found on {compare_branch.split('/', 1)[0]}.")
@@ -9784,11 +10239,11 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
         # report presence-only (mirrors the banner's _check_via_local_git).
         head_sha = subprocess.run(
             git_cmd + ["rev-parse", "HEAD"],
-            cwd=PROJECT_ROOT, capture_output=True, text=True,
+            cwd=PROJECT_ROOT, capture_output=True, text=True, encoding="utf-8", errors="replace",
         ).stdout.strip()
         target_sha = subprocess.run(
             git_cmd + ["rev-parse", compare_branch],
-            cwd=PROJECT_ROOT, capture_output=True, text=True,
+            cwd=PROJECT_ROOT, capture_output=True, text=True, encoding="utf-8", errors="replace",
         ).stdout.strip()
         if head_sha and target_sha and head_sha == target_sha:
             print("✓ Already up to date.")
@@ -9803,7 +10258,7 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
         git_cmd + ["rev-list", f"HEAD..{compare_branch}", "--count"],
         cwd=PROJECT_ROOT,
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         check=True,
     )
     behind = int(rev_result.stdout.strip())
@@ -9864,7 +10319,7 @@ def _ensure_fhs_path_guard() -> None:
                 "command -v hermes",
             ],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=10,
         )
     except (FileNotFoundError, subprocess.TimeoutExpired):
@@ -9882,7 +10337,7 @@ def _ensure_fhs_path_guard() -> None:
         if not cfg.is_file():
             continue
         try:
-            existing = cfg.read_text(errors="replace")
+            existing = cfg.read_text(errors="replace", encoding="utf-8")
         except OSError:
             continue
         # Idempotency: skip if any uncommented PATH= line already references
@@ -9907,6 +10362,19 @@ def _ensure_fhs_path_guard() -> None:
         print("    (reload your shell or run 'source ~/.bashrc' to pick it up)")
 
 
+def _size_delta_label(saved_mb: float) -> str:
+    """Human label for a before/after database size delta, in MB.
+
+    A negative delta means the file GREW — concurrent session writes during a
+    long optimize can outweigh what the rebuild freed. Printing
+    "reclaimed -163.0 MB" for that reads as data loss, so say "grew by"
+    instead.
+    """
+    if saved_mb >= 0:
+        return f"reclaimed {saved_mb:.1f} MB"
+    return f"grew by {-saved_mb:.1f} MB"
+
+
 _PRE_UPDATE_SNAPSHOT_KEEP = 1
 
 # Per-file size cap for the pre-update quick snapshot. Anything larger is
@@ -9996,13 +10464,67 @@ def _run_pre_update_backup(args) -> Optional[str]:
 
     snapshot_id = None
     try:
-        from hermes_cli.backup import create_quick_snapshot
+        from hermes_cli.backup import (
+            _quick_snapshot_root,
+            create_quick_snapshot,
+            verify_sqlite_integrity,
+        )
+
+        # NOTE: this function later does `from hermes_constants import
+        # get_hermes_home`, which makes the name function-local — the
+        # module-level import is shadowed and unbound here. Alias explicitly.
+        from hermes_cli.config import get_hermes_home as _get_home
 
         snapshot_id = create_quick_snapshot(
             label="pre-update",
             keep=_PRE_UPDATE_SNAPSHOT_KEEP,
             max_file_size=_PRE_UPDATE_SNAPSHOT_MAX_FILE_SIZE,
         )
+
+        # After the snapshot, verify the source state.db is still intact.
+        # The snapshot was taken via _safe_copy_db (read-only SQLite backup
+        # API), but a concurrent process (antivirus, force-killed gateway
+        # releasing file handles, Windows filter driver) can corrupt the live
+        # file at any point. A silent zeroing at this point would proceed with
+        # the update and exit code 0 — exactly the #68474 symptom.
+        if snapshot_id:
+            _src_path = _get_home() / "state.db"
+            if _src_path.exists():
+                _integrity = verify_sqlite_integrity(
+                    _src_path,
+                    check_header=True,
+                    run_pragma=True,
+                    max_bytes=_PRE_UPDATE_SNAPSHOT_MAX_FILE_SIZE,
+                )
+                if not _integrity.get("valid"):
+                    _msg = _integrity.get("message", "unknown error")
+                    print(
+                        f"  ⚠ state.db integrity check FAILED after snapshot: {_msg}"
+                    )
+                    # Check if the snapshot itself is valid.
+                    _snap_root = _quick_snapshot_root(_get_home())
+                    _snap_state = _snap_root / snapshot_id / "state.db"
+                    if _snap_state.exists():
+                        _snap_ok = verify_sqlite_integrity(
+                            _snap_state, check_header=True, run_pragma=True
+                        )
+                        if _snap_ok.get("valid"):
+                            print(
+                                "  ✓ Snapshot copy is valid — continuing update."
+                            )
+                            print(
+                                "    If state.db is lost after update it will be auto-restored."
+                            )
+                        else:
+                            print(
+                                "  ✗ Snapshot copy ALSO failed integrity — "
+                                "the source was already corrupted before the backup."
+                            )
+                    else:
+                        print(
+                            "  ⚠ Snapshot does not contain state.db (was skipped or too large)."
+                        )
+                    print()
         if snapshot_id:
             print(f"◆ Pre-update snapshot: {snapshot_id}")
     except Exception as exc:
@@ -10188,7 +10710,7 @@ def _venv_core_imports_healthy() -> tuple[bool, str]:
         result = subprocess.run(
             [str(venv_python), "-c", check],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=60,
             cwd=PROJECT_ROOT,
         )
@@ -10631,7 +11153,7 @@ def _discard_lockfile_churn(git_cmd, repo_root):
             git_cmd + ["diff", "--name-only"],
             cwd=repo_root,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         if diff.returncode != 0:
             return
@@ -10652,7 +11174,7 @@ def _discard_lockfile_churn(git_cmd, repo_root):
             git_cmd + ["checkout", "--", *dirty],
             cwd=repo_root,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             check=False,
         )
         print(f"→ Discarded npm lockfile churn ({len(dirty)} file(s))")
@@ -10877,7 +11399,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
             git_cmd + ["fetch", "origin", branch],
             cwd=PROJECT_ROOT,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
         if fetch_result.returncode != 0:
             stderr = fetch_result.stderr.strip()
@@ -10901,7 +11423,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
             git_cmd + ["rev-parse", "--abbrev-ref", "HEAD"],
             cwd=PROJECT_ROOT,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             check=True,
         )
         current_branch = result.stdout.strip()
@@ -10924,7 +11446,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                 git_cmd + ["checkout", branch],
                 cwd=PROJECT_ROOT,
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
             )
             if checkout_result.returncode != 0:
                 # Local checkout doesn't have this branch yet. Try to set
@@ -10935,7 +11457,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                     git_cmd + ["checkout", "-B", branch, f"origin/{branch}"],
                     cwd=PROJECT_ROOT,
                     capture_output=True,
-                    text=True,
+                    text=True, encoding="utf-8", errors="replace",
                 )
                 if track_result.returncode != 0:
                     # Restore the user's prior branch + stash before bailing
@@ -10966,7 +11488,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
             git_cmd + ["rev-list", f"HEAD..origin/{branch}", "--count"],
             cwd=PROJECT_ROOT,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             check=True,
         )
         commit_count = int(result.stdout.strip())
@@ -10992,10 +11514,24 @@ def _cmd_update_impl(args, gateway_mode: bool):
                     git_cmd + ["checkout", current_branch],
                     cwd=PROJECT_ROOT,
                     capture_output=True,
-                    text=True,
+                    text=True, encoding="utf-8", errors="replace",
                     check=False,
                 )
 
+            # "No new commits" does not mean the managed interpreter is safe.
+            # uv can retain the same CPython patch while python-build-standalone
+            # refreshes the embedded SQLite underneath it. Keep the existing
+            # update-boundary hook active on this retry path too.
+            from hermes_cli.managed_uv import ensure_uv, update_managed_uv
+
+            runtime_repairs = []
+            update_managed_uv(repair_observer=runtime_repairs.append)
+            ensure_uv(repair_observer=runtime_repairs.append)
+            runtime_repaired = next(
+                (result for result in runtime_repairs if result.repaired),
+                None,
+            )
+
             # A current checkout does NOT imply a healthy install: a previous
             # dependency sync may have failed partway (classic on Windows,
             # where a running gateway/desktop backend keeps .pyd files locked
@@ -11046,6 +11582,23 @@ def _cmd_update_impl(args, gateway_mode: bool):
                     print("  Close all Hermes windows/gateways and re-run: hermes update")
             else:
                 print("✓ Already up to date!")
+            if runtime_repaired is not None and not _is_windows():
+                print()
+                print(
+                    "⚠ Restart required to finish the managed Python runtime repair."
+                )
+                print(
+                    "  Any running Hermes gateways, Desktop backends, or other "
+                    "long-lived processes still use the previous runtime."
+                )
+                print(
+                    "  Restart each of them before removing the parked venv"
+                    + (
+                        f": {runtime_repaired.backup_venv}"
+                        if runtime_repaired.backup_venv is not None
+                        else "."
+                    )
+                )
             _resume_windows_gateways_after_update(_windows_gateway_resume)
             return
 
@@ -11064,7 +11617,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                 git_cmd + ["pull", "--ff-only", "origin", branch],
                 cwd=PROJECT_ROOT,
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
             )
             if pull_result.returncode != 0:
                 # ff-only failed — local and remote have diverged (e.g. upstream
@@ -11077,7 +11630,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                     git_cmd + ["reset", "--hard", f"origin/{branch}"],
                     cwd=PROJECT_ROOT,
                     capture_output=True,
-                    text=True,
+                    text=True, encoding="utf-8", errors="replace",
                 )
                 if reset_result.returncode != 0:
                     print(f"✗ Failed to reset to origin/{branch}.")
@@ -11113,7 +11666,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                         git_cmd + ["reset", "--hard", pre_pull_sha],
                         cwd=PROJECT_ROOT,
                         capture_output=True,
-                        text=True,
+                        text=True, encoding="utf-8", errors="replace",
                     )
                     if rollback_result.returncode == 0:
                         print("  ✓ Rollback complete — your install is unchanged.")
@@ -11306,6 +11859,81 @@ def _cmd_update_impl(args, gateway_mode: bool):
         print()
         print("✓ Code updated!")
 
+        # ── Post-update state.db integrity guard (#68474) ─────────────────
+        # Verify that state.db survived the update intact.  If the live file
+        # is now corrupted (zeroed, missing header, integrity failure),
+        # automatically restore from the pre-update snapshot rather than
+        # letting the user discover silently that their sessions are gone.
+        try:
+            from hermes_cli.backup import _quick_snapshot_root, verify_sqlite_integrity
+
+            _state_path = get_hermes_home() / "state.db"
+            if _state_path.exists():
+                _state_ok = verify_sqlite_integrity(
+                    _state_path,
+                    check_header=True,
+                    run_pragma=True,
+                )
+                if _state_ok.get("valid"):
+                    logger.debug(
+                        "Post-update state.db integrity check: %s",
+                        _state_ok.get("message"),
+                    )
+                else:
+                    print()
+                    print(
+                        "⚠ state.db is corrupted after update: "
+                        + _state_ok.get("message", "unknown error")
+                    )
+                    _pre_snap_id = pre_update_snapshot_id
+                    if _pre_snap_id:
+                        _snap_state = (
+                            _quick_snapshot_root(get_hermes_home())
+                            / _pre_snap_id
+                            / "state.db"
+                        )
+                        if _snap_state.exists():
+                            _snap_ok = verify_sqlite_integrity(
+                                _snap_state, check_header=True, run_pragma=True
+                            )
+                            if _snap_ok.get("valid"):
+                                try:
+                                    import shutil as _shutil
+
+                                    _shutil.copy2(_snap_state, _state_path)
+                                    _restored_ok = verify_sqlite_integrity(
+                                        _state_path,
+                                        check_header=True,
+                                        run_pragma=True,
+                                    )
+                                    if _restored_ok.get("valid"):
+                                        print(
+                                            "  ✓ Auto-restored from pre-update "
+                                            f"snapshot ({_pre_snap_id})"
+                                        )
+                                    else:
+                                        print(
+                                            "  ✗ Auto-restore FAILED — restored "
+                                            "copy also failed integrity"
+                                        )
+                                except OSError as _exc:
+                                    print(
+                                        f"  ✗ Auto-restore file copy failed: {_exc}"
+                                    )
+                            else:
+                                print(
+                                    "  ✗ Pre-update snapshot also failed integrity"
+                                )
+                        else:
+                            print(
+                                "  ⚠ Pre-update snapshot does not contain state.db"
+                            )
+                    else:
+                        print("  ⚠ No pre-update snapshot was taken")
+                    print()
+        except Exception as exc:
+            logger.debug("Post-update state.db integrity check failed: %s", exc)
+
         # Seed the model-catalog disk cache from the freshly-pulled checkout.
         # The repo ships the canonical catalog at
         # website/static/api/model-catalog.json, and `git pull` just made it
@@ -11355,6 +11983,11 @@ def _cmd_update_impl(args, gateway_mode: bool):
                 )
             if result.get("cleaned"):
                 print(f"  − {len(result['cleaned'])} removed from manifest")
+            if result.get("relocated"):
+                print(
+                    f"  → {len(result['relocated'])} moved to new upstream paths: "
+                    f"{', '.join(result['relocated'])}"
+                )
             if not result["copied"] and not result.get("updated"):
                 print("  ✓ Skills are up to date")
         except Exception as e:
@@ -11667,7 +12300,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
         if gateway_mode:
             _exit_code_path = get_hermes_home() / ".update_exit_code"
             try:
-                _exit_code_path.write_text("0")
+                _exit_code_path.write_text("0", encoding="utf-8")
             except OSError:
                 pass
 
@@ -11708,7 +12341,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                         _verify = subprocess.run(
                             scope_cmd_ + ["is-active", svc_name_],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding="utf-8", errors="replace",
                             timeout=5,
                         )
                         if _verify.stdout.strip() == "active":
@@ -11742,7 +12375,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                             "--value",
                         ],
                         capture_output=True,
-                        text=True,
+                        text=True, encoding="utf-8", errors="replace",
                         timeout=5,
                     )
                 except (FileNotFoundError, subprocess.TimeoutExpired):
@@ -11891,7 +12524,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                                 "--no-pager",
                             ],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding="utf-8", errors="replace",
                             timeout=10,
                         )
                     except FileNotFoundError:
@@ -11910,7 +12543,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                         check = subprocess.run(
                             scope_cmd + ["is-active", svc_name],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding="utf-8", errors="replace",
                             timeout=5,
                         )
                         if check.stdout.strip() != "active":
@@ -11943,7 +12576,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                                     "--value",
                                 ],
                                 capture_output=True,
-                                text=True,
+                                text=True, encoding="utf-8", errors="replace",
                                 timeout=5,
                             )
                             _main_pid = int((_show.stdout or "").strip() or 0)
@@ -11996,13 +12629,13 @@ def _cmd_update_impl(args, gateway_mode: bool):
                                 subprocess.run(
                                     _manage_cmd + ["reset-failed", svc_name],
                                     capture_output=True,
-                                    text=True,
+                                    text=True, encoding="utf-8", errors="replace",
                                     timeout=10,
                                 )
                                 subprocess.run(
                                     _manage_cmd + ["start", svc_name],
                                     capture_output=True,
-                                    text=True,
+                                    text=True, encoding="utf-8", errors="replace",
                                     timeout=15,
                                 )
                                 # Short poll: the gateway should be up
@@ -12086,13 +12719,13 @@ def _cmd_update_impl(args, gateway_mode: bool):
                         subprocess.run(
                             _manage_cmd + ["reset-failed", svc_name],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding="utf-8", errors="replace",
                             timeout=10,
                         )
                         restart = subprocess.run(
                             _manage_cmd + ["restart", svc_name],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding="utf-8", errors="replace",
                             timeout=15,
                         )
                         if restart.returncode == 0:
@@ -12118,13 +12751,13 @@ def _cmd_update_impl(args, gateway_mode: bool):
                                 subprocess.run(
                                     _manage_cmd + ["reset-failed", svc_name],
                                     capture_output=True,
-                                    text=True,
+                                    text=True, encoding="utf-8", errors="replace",
                                     timeout=10,
                                 )
                                 subprocess.run(
                                     _manage_cmd + ["restart", svc_name],
                                     capture_output=True,
-                                    text=True,
+                                    text=True, encoding="utf-8", errors="replace",
                                     timeout=15,
                                 )
                                 if _wait_for_service_active(
@@ -12182,7 +12815,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                         check = subprocess.run(
                             ["launchctl", "list", get_launchd_label()],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding="utf-8", errors="replace",
                             timeout=5,
                         )
                         if check.returncode == 0:
@@ -12297,7 +12930,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
                 if gateway_mode:
                     _exit_code_path = get_hermes_home() / ".update_exit_code"
                     try:
-                        _exit_code_path.write_text("1")
+                        _exit_code_path.write_text("1", encoding="utf-8")
                     except OSError:
                         pass
             _warn_incomplete_gateway_fleet_restart(failed_or_stale_units)
@@ -13119,7 +13752,11 @@ def _render_distribution_plan(plan) -> None:
                 env_path = plan.target_dir / ".env"
                 if env_path.is_file():
                     try:
-                        for raw in env_path.read_text().splitlines():
+                        # .env is written as UTF-8 everywhere in the codebase,
+                        # but a Notepad-edited file can carry a BOM — read as
+                        # utf-8-sig so the first key isn't hidden behind
+                        # U+FEFF (#62617).
+                        for raw in env_path.read_text(encoding="utf-8-sig").splitlines():
                             line = raw.strip()
                             if not line or line.startswith("#"):
                                 continue
@@ -13127,7 +13764,10 @@ def _render_distribution_plan(plan) -> None:
                             if key == er.name:
                                 already = True
                                 break
-                    except OSError:
+                    except (OSError, UnicodeDecodeError):
+                        # UnicodeDecodeError is a ValueError, not an OSError, so
+                        # the old guard let a mis-encoded .env abort the whole
+                        # install preview. Skip the pre-check instead.
                         pass
             status = "✓ set" if already else ("needs setting" if er.required else "—")
             line = f"    • {er.name} ({tag}, {status})"
@@ -13846,7 +14486,7 @@ _BUILTIN_SUBCOMMANDS = frozenset(
         "acp", "auth", "backup", "bundles", "checkpoints", "claw", "completion",
         "computer-use",
         "config", "console", "cron", "curator", "dashboard", "serve", "debug", "doctor",
-        "dump", "fallback", "gateway", "hooks", "import", "insights",
+        "dump", "egress", "fallback", "gateway", "hooks", "import", "insights",
         "gui", "desktop", "kanban", "login", "logout", "logs", "lsp", "mcp", "memory", "migrate", "moa",
         "journey", "memory-graph", "learning",
         "model", "pairing", "pets", "plugins", "portal", "profile",
@@ -14489,6 +15129,37 @@ def main():
 
     secrets_parser.set_defaults(func=_dispatch_secrets)
 
+    # =========================================================================
+    # egress command — iron-proxy outbound credential-injection firewall
+    # =========================================================================
+    # NOTE: this is the OUTBOUND egress firewall (ironsh/iron-proxy).
+    # `hermes proxy` (defined elsewhere in this file) is a separate INBOUND
+    # OAuth-aggregator reverse proxy.  Different direction, different purpose.
+    egress_parser = subparsers.add_parser(
+        "egress",
+        help="Manage the iron-proxy egress credential-injection firewall",
+        description=(
+            "Manage iron-proxy, the optional TLS-intercepting egress firewall "
+            "that swaps proxy tokens for real API credentials before outbound "
+            "requests leave a sandbox.  Disabled by default.  See: "
+            "https://hermes-agent.nousresearch.com/docs/user-guide/egress/iron-proxy"
+        ),
+    )
+
+    from hermes_cli import proxy_cli as _proxy_cli
+    _proxy_cli.register_cli(egress_parser)
+
+    def _dispatch_egress(args):  # noqa: ANN001
+        # The egress subparser uses dest='egress_command' to stay disjoint
+        # from the inbound OAuth ``hermes proxy`` subparser (dest='proxy_command').
+        sub = getattr(args, "egress_command", None)
+        if sub is not None and hasattr(args, "func") and args.func is not _dispatch_egress:
+            return args.func(args)
+        egress_parser.print_help()
+        return 0
+
+    egress_parser.set_defaults(func=_dispatch_egress)
+
     # =========================================================================
     # migrate command
     # =========================================================================
@@ -14976,7 +15647,7 @@ def main():
                     from hermes_cli.tools_config import _cua_driver_env
                     version = subprocess.run(
                         [path, "--version"],
-                        capture_output=True, text=True, timeout=5,
+                        capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5,
                         env=_cua_driver_env(),
                     ).stdout.strip()
                 except Exception:
@@ -15341,6 +16012,58 @@ def main():
         help="Skip the timestamped backup copy (not recommended)",
     )
 
+    sessions_recover = sessions_subparsers.add_parser(
+        "recover",
+        help="Rebuild canonical session data into a separate clean database",
+        description=(
+            "Offline, non-destructive recovery for a damaged state.db. The "
+            "source database and its WAL/SHM/rollback-journal sidecars are "
+            "copied before SQLite opens anything. Canonical rows are rebuilt "
+            "into a new output database; derived search indexes are recreated "
+            "and the active database is never replaced automatically."
+        ),
+    )
+    sessions_recover.add_argument(
+        "--source",
+        type=Path,
+        required=True,
+        help="Source state.db or preserved backup to inspect/recover",
+    )
+    sessions_recover.add_argument(
+        "--output",
+        type=Path,
+        help="New recovery database path (required unless --inspect-only)",
+    )
+    sessions_recover.add_argument(
+        "--inspect-only",
+        action="store_true",
+        help="Only report canonical table readability; do not create an output database",
+    )
+    sessions_recover.add_argument(
+        "--work-dir",
+        type=Path,
+        help="Existing directory for the disposable source copy (defaults beside the output)",
+    )
+    sessions_recover.add_argument(
+        "--chunk-size",
+        type=int,
+        default=1000,
+        help="Rows committed per recovery batch (default: 1000)",
+    )
+    sessions_recover.add_argument(
+        "--allow-partial",
+        action="store_true",
+        help=(
+            "Best-effort salvage across damaged row ranges; the output remains "
+            "separate and every skipped range is recorded"
+        ),
+    )
+    sessions_recover.add_argument(
+        "--report",
+        type=Path,
+        help="JSON report path (defaults to <output>.recovery.json)",
+    )
+
     sessions_subparsers.add_parser("stats", help="Show session store statistics")
 
     sessions_rename = sessions_subparsers.add_parser(
@@ -15349,6 +16072,29 @@ def main():
     sessions_rename.add_argument("session_id", help="Session ID to rename")
     sessions_rename.add_argument("title", nargs="+", help="New title for the session")
 
+    sessions_retitle = sessions_subparsers.add_parser(
+        "retitle-skills",
+        help="Re-title sessions whose auto-title came from a /skill's own text",
+        description=(
+            "Sessions opened with a /skill were auto-titled from the expanded "
+            "message, which embeds the whole skill body — so the title "
+            "describes the SKILL, not the request. This regenerates those "
+            "titles from what the user actually typed. Lists what it would "
+            "change unless --apply is passed."
+        ),
+    )
+    sessions_retitle.add_argument(
+        "--apply",
+        action="store_true",
+        help="Write the new titles (default: dry run)",
+    )
+    sessions_retitle.add_argument(
+        "--limit",
+        type=int,
+        default=200,
+        help="Maximum sessions to examine (default: 200)",
+    )
+
     sessions_browse = sessions_subparsers.add_parser(
         "browse",
         help="Interactive session picker — browse, search, and resume sessions",
@@ -15372,9 +16118,10 @@ def main():
 
         action = args.sessions_action
 
-        # 'repair' must run BEFORE opening SessionDB(): a malformed schema is
-        # exactly the case where SessionDB() can't open, so it operates on the
-        # raw file path instead.
+        # 'repair' and 'recover' must run BEFORE opening SessionDB(): a
+        # malformed schema is exactly the case where SessionDB() can't open.
+        # Recovery additionally promises never to open the supplied source
+        # directly, so it operates through its own disposable source copy.
         if action == "repair":
             from hermes_state import (
                 DEFAULT_DB_PATH,
@@ -15415,8 +16162,126 @@ def main():
                 if report.get("backup_path"):
                     print(f"  A backup is preserved at: {report['backup_path']}")
                 print("  Keep state.db and the backup; do not delete them.")
+                # Without this pointer the user is at a dead end: in-place
+                # repair has failed and nothing tells them the non-destructive
+                # offline recovery path exists. Lead with --inspect-only so
+                # they confirm the data is readable before writing anything.
+                print("")
+                print("  Next step — offline recovery (never modifies the source):")
+                source_hint = report.get("backup_path") or db_path
+                print(f"    hermes sessions recover --source {source_hint} \\")
+                print("        --inspect-only")
+                print("  If that reports the data is recoverable, rebuild it into")
+                print("  a NEW database (the active one is left untouched):")
+                print(f"    hermes sessions recover --source {source_hint} \\")
+                print("        --output recovered-state.db")
             return
 
+        if action == "recover":
+            import sqlite3 as _sqlite3
+
+            from hermes_cli.session_recovery import (
+                SessionRecoveryError,
+                inspect_session_database,
+                recover_session_database,
+                write_recovery_report,
+            )
+
+            source = args.source
+            output = getattr(args, "output", None)
+            inspect_only = bool(getattr(args, "inspect_only", False))
+            allow_partial = bool(getattr(args, "allow_partial", False))
+            report_path = getattr(args, "report", None)
+            if inspect_only and output is not None:
+                print("Error: --output cannot be used with --inspect-only.")
+                return 2
+            if inspect_only and allow_partial:
+                print("Error: --allow-partial cannot be used with --inspect-only.")
+                return 2
+            if not inspect_only and output is None:
+                print("Error: --output is required unless --inspect-only is used.")
+                return 2
+            if not inspect_only and report_path is None:
+                report_path = output.with_name(output.name + ".recovery.json")
+            if (
+                report_path is not None
+                and os.path.lexists(report_path.expanduser())
+            ):
+                print(f"Error: refusing to overwrite existing report: {report_path}")
+                return 2
+
+            try:
+                if inspect_only:
+                    report = inspect_session_database(
+                        source,
+                        work_dir=getattr(args, "work_dir", None),
+                    )
+                else:
+                    last_progress = {"table": None}
+
+                    def _recovery_progress(info):
+                        table = info.get("table")
+                        copied = int(info.get("copied_rows") or 0)
+                        total = info.get("source_rows")
+                        if table != last_progress["table"]:
+                            if last_progress["table"] is not None:
+                                print()
+                            print(f"  {table}: ", end="", flush=True)
+                            last_progress["table"] = table
+                        suffix = f"/{int(total):,}" if total is not None else ""
+                        print(f"\r  {table}: {copied:,}{suffix}", end="", flush=True)
+
+                    print("Recovering canonical session data into a new database…")
+                    report = recover_session_database(
+                        source,
+                        output,
+                        work_dir=getattr(args, "work_dir", None),
+                        chunk_size=getattr(args, "chunk_size", 1000),
+                        progress_cb=_recovery_progress,
+                        allow_partial=allow_partial,
+                    )
+                    if last_progress["table"] is not None:
+                        print()
+            except (SessionRecoveryError, OSError, _sqlite3.DatabaseError) as exc:
+                print(f"Error: session recovery failed: {exc}")
+                print("The supplied source database was not replaced or deleted.")
+                return 1
+
+            if report_path is not None:
+                try:
+                    written_report = write_recovery_report(report_path, report)
+                except (FileExistsError, OSError) as exc:
+                    print(f"Error: could not write recovery report: {exc}")
+                    return 1
+                print(f"Recovery report: {written_report}")
+            else:
+                print(_json.dumps(report, indent=2, sort_keys=True))
+
+            if inspect_only:
+                return 0 if report.get("recoverable") else 1
+            if report.get("complete"):
+                print(f"✓ Recovered database verified at: {output}")
+                print("  The active session database was not changed.")
+                print("  Review the JSON report before installing this database.")
+                return 0
+            if allow_partial and report.get("verified"):
+                counts = report.get("verification", {}).get("table_counts", {})
+                print(f"✓ Partial recovery output verified at: {output}")
+                print(
+                    "  Recovered "
+                    f"{int(counts.get('sessions') or 0):,} sessions and "
+                    f"{int(counts.get('messages') or 0):,} messages."
+                )
+                print("  The active session database was not changed.")
+                print(
+                    "  This output is incomplete. Review every skipped range "
+                    "and orphan count in the JSON report before installing it."
+                )
+                return 0
+            print("✗ Recovery output did not pass every verification check.")
+            print("  Do not install it. Review the JSON report for partial data or errors.")
+            return 1
+
         try:
             from hermes_state import SessionDB
 
@@ -15820,10 +16685,10 @@ def main():
                 return
             output_dir = Path(args.output).expanduser() if args.output else get_hermes_home() / "session-exports"
 
-            def _export_one(session_id: str):
+            def _export_one(session_id: str, *, include_lineage: bool = False):
                 data = (
                     db.export_session_lineage(session_id)
-                    if getattr(args, "lineage", "single") == "logical"
+                    if include_lineage
                     else db.export_session(session_id)
                 )
                 if not data:
@@ -15847,36 +16712,93 @@ def main():
                 db.close()
                 return
 
+            lineage_is_logical = getattr(args, "lineage", "single") == "logical"
+
             if args.session_id:
                 resolved_session_id = db.resolve_session_id(args.session_id)
                 if not resolved_session_id:
                     print(f"Session '{args.session_id}' not found.")
                     db.close()
                     return
-                try:
-                    data, exported_path = _export_one(resolved_session_id)
-                except FileExistsError as e:
-                    print(f"Export already exists: {e}. Pass --force to overwrite.")
-                    db.close()
-                    return
-                if not data or not exported_path:
-                    print(f"Session '{args.session_id}' not found.")
-                    db.close()
-                    return
-                message_count = len(data.get("messages") or [])
-                suffix = "" if message_count == 1 else "s"
-                print(f"Exported 1 session ({message_count} message{suffix}) to {exported_path}")
+                delete_target_ids = [resolved_session_id]
                 if args.delete_after_verified:
-                    ok, reason = verify_export_file(exported_path, data)
-                    if not ok:
-                        print(f"Export verification failed; not deleting: {reason}")
+                    delete_target_ids = db.get_session_delete_targets(
+                        resolved_session_id
+                    )
+
+                exported_items = []
+                for target_id in delete_target_ids:
+                    try:
+                        data, exported_path = _export_one(
+                            target_id,
+                            include_lineage=(
+                                target_id == resolved_session_id
+                                and lineage_is_logical
+                            ),
+                        )
+                    except FileExistsError as e:
+                        print(
+                            f"Export already exists: {e}. "
+                            "Pass --force to overwrite."
+                        )
                         db.close()
                         return
+                    if not data or not exported_path:
+                        print(
+                            f"Session '{target_id}' disappeared during export; "
+                            "nothing was deleted."
+                        )
+                        db.close()
+                        return
+                    exported_items.append((data, exported_path))
+
+                message_count = sum(
+                    len(data.get("messages") or [])
+                    for data, _path in exported_items
+                )
+                suffix = "" if message_count == 1 else "s"
+                if len(exported_items) == 1:
+                    print(
+                        f"Exported 1 session ({message_count} message{suffix}) "
+                        f"to {exported_items[0][1]}"
+                    )
+                else:
+                    print(
+                        f"Exported {len(exported_items)} sessions "
+                        f"({message_count} message{suffix}) to {output_dir}"
+                    )
+                if args.delete_after_verified:
+                    for data, exported_path in exported_items:
+                        ok, reason = verify_export_file(exported_path, data)
+                        if not ok:
+                            print(
+                                "Export verification failed; not deleting "
+                                f"session '{data.get('id')}': {reason}"
+                            )
+                            db.close()
+                            return
                     sessions_dir = get_hermes_home() / "sessions"
-                    if db.delete_session(resolved_session_id, sessions_dir=sessions_dir):
-                        print(f"Deleted exported session '{resolved_session_id}'.")
+                    if db.delete_session(
+                        resolved_session_id,
+                        sessions_dir=sessions_dir,
+                        expected_delete_ids=delete_target_ids,
+                    ):
+                        delegate_count = len(delete_target_ids) - 1
+                        delegate_suffix = (
+                            ""
+                            if not delegate_count
+                            else f" and {delegate_count} delegate session"
+                            f"{'' if delegate_count == 1 else 's'}"
+                        )
+                        print(
+                            f"Deleted exported session '{resolved_session_id}'"
+                            f"{delegate_suffix}."
+                        )
                     else:
-                        print(f"Exported, but session '{resolved_session_id}' was not deleted because it was not found.")
+                        print(
+                            f"Exported, but session '{resolved_session_id}' was "
+                            "not deleted because its delegate set changed."
+                        )
                 db.close()
                 return
 
@@ -15902,7 +16824,10 @@ def main():
             exported = 0
             for row in candidates:
                 try:
-                    data, exported_path = _export_one(row["id"])
+                    data, exported_path = _export_one(
+                        row["id"],
+                        include_lineage=lineage_is_logical,
+                    )
                 except FileExistsError as e:
                     print(f"Skipping existing export: {e}. Pass --force to overwrite.")
                     continue
@@ -16050,6 +16975,67 @@ def main():
             except ValueError as e:
                 print(f"Error: {e}")
 
+        elif action == "retitle-skills":
+            from agent.skill_commands import describe_skill_invocation
+            from agent.title_generator import generate_title
+
+            limit = max(1, int(getattr(args, "limit", 200) or 200))
+            apply_changes = bool(getattr(args, "apply", False))
+
+            def _is_titlelike(candidate: str) -> bool:
+                """Reject a candidate that isn't a title at all.
+
+                An auxiliary model occasionally answers the prompt instead of
+                titling it and echoes the assistant's output ('$ df -h /'). The
+                live path has no alternative and takes what it gets, but this is
+                a REPAIR — replacing a serviceable title with command output
+                would make things worse, so keep the old one.
+                """
+                return bool(candidate) and candidate[0].isalnum()
+
+            candidates = db.list_skill_scaffolded_sessions(limit=limit)
+            if not candidates:
+                print("No sessions were titled from a /skill invocation.")
+                return
+
+            print(
+                f"{len(candidates)} session(s) opened with a /skill"
+                f"{'' if apply_changes else ' (dry run — pass --apply to write)'}:"
+            )
+            changed = 0
+            for row in candidates:
+                session_id = row["id"]
+                typed = describe_skill_invocation(row["content"]) or ""
+                first_reply = db.get_first_assistant_text(session_id) or ""
+                new_title = generate_title(typed, first_reply)
+                if not new_title or new_title == row["title"]:
+                    continue
+                if not _is_titlelike(new_title):
+                    print(f"  {session_id}\n    kept {row['title']!r} — got {new_title!r}")
+                    continue
+                print(f"  {session_id}\n    {row['title']!r}\n    → {new_title!r}")
+                changed += 1
+                if not apply_changes:
+                    continue
+                try:
+                    db.set_session_title(session_id, new_title)
+                except ValueError:
+                    # Unique-title collision. Dedupe the same way the live
+                    # auto-titler does (base #2, base #3, ...) rather than
+                    # leaving the leaked title in place.
+                    deduped = db.get_next_title_in_lineage(new_title)
+                    try:
+                        db.set_session_title(session_id, deduped)
+                        print(f"    (renamed to {deduped!r} — title was taken)")
+                    except ValueError as e:
+                        print(f"    skipped: {e}")
+                        changed -= 1
+
+            if not changed:
+                print("  every title already reflects the user's request.")
+            elif apply_changes:
+                print(f"✓ Re-titled {changed} session(s).")
+
         elif action == "browse":
             limit = getattr(args, "limit", 500) or 500
             source = getattr(args, "source", None)
@@ -16095,11 +17081,18 @@ def main():
                 if db_path.exists()
                 else 0.0
             )
+            # Same WAL caveat as optimize-storage: after a VACUUM the main file
+            # on disk lags until the WAL is checkpointed back (refused while a
+            # live gateway holds a read-mark), so stat() understates the win and
+            # can go negative. SQLite's page accounting is correct immediately.
+            logical_after = db.logical_size_bytes()
+            if logical_after is not None:
+                after_mb = logical_after / (1024 * 1024)
             saved = before_mb - after_mb
             print(f"Optimized {n} FTS index(es).")
             print(
                 f"Database size: {before_mb:.1f} MB -> {after_mb:.1f} MB "
-                f"(reclaimed {saved:.1f} MB)"
+                f"({_size_delta_label(saved)})"
             )
 
         elif action == "optimize-storage":
@@ -16182,11 +17175,21 @@ def main():
             after_mb = (
                 os.path.getsize(db_path) / (1024 * 1024) if db_path.exists() else 0.0
             )
+            # Prefer SQLite's own page accounting over stat(). In WAL mode a
+            # VACUUM's rewrite sits in the -wal file until a checkpoint folds it
+            # back, and that checkpoint is refused while another connection (a
+            # live gateway) holds a read-mark — so the main file on disk still
+            # reads at its pre-VACUUM size and keeps growing. stat()ing it here
+            # reported "reclaimed -3820.1 MB" on a DB that had actually shrunk
+            # 60%. page_count * page_size is correct immediately.
+            logical_after = db.logical_size_bytes()
+            if logical_after is not None:
+                after_mb = logical_after / (1024 * 1024)
             saved = before_mb - after_mb
             print(f"\n✓ Search index optimized.")
             print(
                 f"  Database size: {before_mb:.1f} MB -> {after_mb:.1f} MB "
-                f"(reclaimed {saved:.1f} MB)"
+                f"({_size_delta_label(saved)})"
             )
             if result.get("vacuumed") is False:
                 print("  (VACUUM was skipped or failed — run "
@@ -16425,9 +17428,15 @@ def main():
         cmd_chat(args)
         return
 
-    # Execute the command
+    # Execute the command.  Propagate the handler's return code as the
+    # process exit code so subcommands that signal failure (e.g.
+    # ``hermes egress start`` refusing when credential_source=bitwarden
+    # is misconfigured) actually exit non-zero.  Handlers that return
+    # None are treated as success (exit 0).
     if hasattr(args, "func"):
-        args.func(args)
+        rc = args.func(args)
+        if isinstance(rc, int) and rc != 0:
+            sys.exit(rc)
     else:
         parser.print_help()
 
diff --git a/hermes_cli/managed_uv.py b/hermes_cli/managed_uv.py
index 78c8f469003..ff33e7dc214 100644
--- a/hermes_cli/managed_uv.py
+++ b/hermes_cli/managed_uv.py
@@ -1,4 +1,4 @@
-"""Managed uv — one path, no guessing.
+"""Hermes-managed uv and Python runtime repair.
 
 Hermes owns its own uv binary at ``$HERMES_HOME/bin/uv`` (or ``uv.exe`` on
 Windows).  Every code path that needs uv resolves it from that single location.
@@ -6,27 +6,48 @@ If the binary is missing, ``ensure_uv()`` bootstraps it via the official
 standalone installer with ``UV_UNMANAGED_INSTALL`` / ``UV_INSTALL_DIR`` pointed
 at ``$HERMES_HOME/bin`` so the installer writes directly there — no PATH
 probing, no conda guards, no multi-location resolution chains.
+
+The Python backing the install is different: it is shared by every Hermes
+profile because the checkout's ``venv`` is shared.  Runtime repair therefore
+uses an install-scoped store under ``<checkout>/.hermes-runtime/python``. A
+vulnerable interpreter is never reinstalled in place. We provision a new
+immutable Python generation, build and smoke-test a relocatable sibling venv,
+then cut over with same-filesystem renames. The old venv remains available for
+synchronous rollback and is parked for cleanup after the updating process
+releases it.
 """
 
 from __future__ import annotations
 
+import json
 import logging
 import os
 import platform
 import shutil
 import subprocess
+import sys
 import tempfile
+import time
+import uuid
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional
+from typing import Callable, Optional
 
 from hermes_constants import get_hermes_home
+from hermes_cli.sqlite_runtime import SQLiteRuntimeInfo, probe_sqlite_runtime
 
 logger = logging.getLogger(__name__)
 
+_PROJECT_ROOT = Path(__file__).resolve().parents[1]
+_RUNTIME_DIR_NAME = ".hermes-runtime"
+_VENV_NAME = "venv"
+_REPAIR_LOCK_NAME = "runtime-repair.lock"
+
 # ---------------------------------------------------------------------------
 # Public helpers
 # ---------------------------------------------------------------------------
 
+
 def managed_uv_path() -> Path:
     """Return the path where Hermes keeps *its* uv binary.
 
@@ -51,6 +72,80 @@ def resolve_uv() -> Optional[str]:
     return None
 
 
+def managed_python_install_dir(project_root: Path | None = None) -> Path:
+    """Return the checkout-scoped Python store shared by all profiles."""
+    root = Path(project_root) if project_root is not None else _PROJECT_ROOT
+    return root / _RUNTIME_DIR_NAME / "python"
+
+
+def managed_python_env(
+    project_root: Path | None = None,
+    *,
+    install_dir: Path | None = None,
+    base_env: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Return a sanitized environment for Hermes-private uv Python commands."""
+    target = (
+        Path(install_dir)
+        if install_dir is not None
+        else managed_python_install_dir(project_root)
+    )
+    env = dict(os.environ if base_env is None else base_env)
+    for key in (
+        "CONDA_DEFAULT_ENV",
+        "CONDA_PREFIX",
+        "UV_PROJECT_ENVIRONMENT",
+        "UV_NO_MANAGED_PYTHON",
+        "UV_PYTHON",
+        "UV_PYTHON_DOWNLOADS",
+        "UV_SYSTEM_PYTHON",
+        "VIRTUAL_ENV",
+        "PYTHONHOME",
+        "PYTHONPATH",
+    ):
+        env.pop(key, None)
+    env.update({
+        "UV_MANAGED_PYTHON": "1",
+        "UV_NO_CONFIG": "1",
+        "UV_PYTHON_INSTALL_BIN": "0",
+        "UV_PYTHON_INSTALL_DIR": str(target),
+        "UV_PYTHON_INSTALL_REGISTRY": "0",
+    })
+    return env
+
+
+@dataclass(frozen=True)
+class RuntimeRepairResult:
+    """Outcome of a managed-runtime repair attempt."""
+
+    status: str
+    detail: str = ""
+    sqlite_before: str = ""
+    sqlite_after: str = ""
+    backup_venv: Path | None = None
+
+    @property
+    def repaired(self) -> bool:
+        return self.status == "repaired"
+
+
+@dataclass(frozen=True)
+class _RepairLock:
+    path: Path
+    fd: int
+
+
+def _report_runtime_repair_failure(repair: RuntimeRepairResult) -> None:
+    if repair.backup_venv is None:
+        print(
+            "  ⚠ Managed Python runtime was not replaced; "
+            f"the existing venv is unchanged ({repair.detail})."
+        )
+        return
+    print(f"  ✗ Managed Python runtime cutover needs manual recovery: {repair.detail}")
+    print(f"    Previous venv: {repair.backup_venv}")
+
+
 class _UvResult(str):
     """``ensure_uv()`` return value that survives an update boundary.
 
@@ -91,7 +186,10 @@ class _UvResult(str):
         return iter(((str(self) or None), self.fresh_bootstrap))
 
 
-def _ensure_uv_path() -> Optional[str]:
+def _ensure_uv_path(
+    *,
+    repair_observer: Callable[[RuntimeRepairResult], None] | None = None,
+) -> Optional[str]:
     """Resolve the managed uv path, installing it if necessary (plain ``str``/``None``)."""
     existing = resolve_uv()
     if existing:
@@ -115,16 +213,31 @@ def _ensure_uv_path() -> Optional[str]:
         version = subprocess.run(
             [result, "--version"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             check=False,
         ).stdout.strip()
         print(f"  ✓ Managed uv installed ({version})")
+        # Compatibility boundary: an older, already-imported updater calls the
+        # freshly pulled ``ensure_uv()`` after bootstrapping uv.  Repair here so
+        # that first update can migrate a vulnerable runtime without requiring
+        # a second ``hermes update``.
+        try:
+            repair = repair_vulnerable_runtime(result)
+            if repair_observer is not None:
+                repair_observer(repair)
+            if repair.status == "failed":
+                _report_runtime_repair_failure(repair)
+        except Exception as exc:
+            logger.warning("Managed Python runtime repair failed: %s", exc)
     else:
         print("  ✗ Managed uv install appeared to succeed but binary not found")
     return result
 
 
-def ensure_uv():
+def ensure_uv(
+    *,
+    repair_observer: Callable[[RuntimeRepairResult], None] | None = None,
+):
     """Return the managed uv path, installing it first if necessary.
 
     On **POSIX** the result is a :class:`_UvResult` (a ``str`` subclass) that is
@@ -145,9 +258,10 @@ def ensure_uv():
     results.)
 
     On failure the result is falsy — never raises — so callers can fall back to
-    pip gracefully.
+    pip gracefully. ``repair_observer``, when provided, receives the runtime
+    repair result produced after a fresh uv bootstrap.
     """
-    result = _ensure_uv_path()
+    result = _ensure_uv_path(repair_observer=repair_observer)
     if platform.system() == "Windows":
         # See docstring: a str subclass with an overridden __iter__ is unsafe as
         # a Windows subprocess argument. Hand back the plain path (or None).
@@ -155,12 +269,16 @@ def ensure_uv():
     return _UvResult(result)
 
 
-def update_managed_uv() -> Optional[str]:
+def update_managed_uv(
+    *,
+    repair_observer: Callable[[RuntimeRepairResult], None] | None = None,
+) -> Optional[str]:
     """Run ``uv self update`` on the managed uv binary.
 
     Call this during ``hermes update`` so the managed copy stays current.
-    Returns the managed path on success, ``None`` if uv isn't available or
-    the self-update fails (non-fatal — the old version still works).
+    Returns the managed path when uv is available and ``None`` otherwise.
+    A self-update failure is non-fatal because the old version still works.
+    ``repair_observer``, when provided, receives the runtime repair result.
     """
     existing = resolve_uv()
     if not existing:
@@ -170,27 +288,737 @@ def update_managed_uv() -> Optional[str]:
     result = subprocess.run(
         [existing, "self", "update"],
         capture_output=True,
-        text=True,
+        text=True, encoding='utf-8', errors='replace',
         check=False,
     )
     if result.returncode == 0:
         version = subprocess.run(
             [existing, "--version"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             check=False,
         ).stdout.strip()
         print(f"  ✓ Managed uv updated ({version})")
     else:
         # Non-fatal — old uv still works fine.
-        logger.debug("uv self update failed (rc=%d): %s", result.returncode, result.stderr)
+        logger.debug(
+            "uv self update failed (rc=%d): %s", result.returncode, result.stderr
+        )
+
+    # Keep this hook inside the long-standing API. During an update, main.py is
+    # already imported from the old checkout, then ``git pull`` replaces this
+    # module on disk before the updater imports it. Calling the repair here is
+    # what makes the migration happen on that first update.
+    try:
+        repair = repair_vulnerable_runtime(existing)
+        if repair_observer is not None:
+            repair_observer(repair)
+        if repair.status == "failed":
+            _report_runtime_repair_failure(repair)
+    except Exception as exc:
+        # Runtime refresh is deliberately non-fatal. The live venv was not
+        # touched unless a fully prepared candidate reached cutover.
+        logger.warning("Managed Python runtime repair failed: %s", exc)
+        print(f"  ⚠ Managed Python runtime repair skipped: {exc}")
     return existing
 
 
+# ---------------------------------------------------------------------------
+# Managed Python runtime repair
+# ---------------------------------------------------------------------------
+
+
+def _venv_python(venv_dir: Path) -> Path:
+    if platform.system() == "Windows":
+        return venv_dir / "Scripts" / "python.exe"
+    return venv_dir / "bin" / "python"
+
+
+def _remove_tree(path: Path, *, boundary: Path) -> None:
+    """Best-effort removal constrained to a known runtime boundary."""
+    try:
+        path.resolve().relative_to(boundary.resolve())
+    except (OSError, ValueError):
+        return
+    shutil.rmtree(path, ignore_errors=True)
+
+
+def _make_world_traversable(path: Path) -> None:
+    """Keep root/FHS-managed runtimes executable by non-root callers."""
+    try:
+        path.chmod(path.stat().st_mode | 0o755)
+    except OSError:
+        pass
+
+
+def _runtime_request(info: SQLiteRuntimeInfo) -> str:
+    """Pin the candidate to the current CPython minor line (e.g. ``3.11``).
+
+    Requesting the exact patch can never repair some installs: for a given
+    patch, python-build-standalone may have no artifact with fixed SQLite at
+    all (e.g. every published 3.11.14 build links SQLite 3.50.4; the fix
+    only exists from 3.11.15).  A newer patch on the same minor is what
+    ``uv python install`` would resolve for a fresh install, stays inside
+    ``requires-python``, and the locked ``uv sync`` + import smoke tests gate
+    compatibility before any cutover.
+    """
+    return ".".join(str(part) for part in info.python_version[:2])
+
+
+# Cap on how many newer patches we'll try, newest-first, before giving up.
+# Bounded because each attempt is a real download+install+probe+delete cycle;
+# in practice the fix is almost always in the very next patch or two.
+_MAX_PATCH_RETRIES = 5
+
+
+def _list_available_patches(
+    uv_bin: str, minor: str, *, cwd: Path, env: dict
+) -> list[tuple[int, int, int]]:
+    """Return known patch versions for ``minor`` (e.g. "3.11"), newest first.
+
+    Queries ``uv python list --all-versions`` rather than trusting the bare
+    minor-line request to resolve to the newest patch (issue #71250: on some
+    hosts/uv versions, the resolved candidate for a bare "3.11" request can
+    be an older cached/indexed patch that still links a vulnerable SQLite,
+    even when a newer non-vulnerable patch is available). Returns [] on any
+    failure (network, parse) -- callers fall back to the original bare-minor
+    request in that case, preserving prior behavior.
+    """
+    try:
+        result = subprocess.run(
+            [
+                uv_bin, "python", "list", minor,
+                "--all-versions", "--only-downloads",
+                "--output-format", "json", "--no-config",
+            ],
+            cwd=cwd,
+            env=env,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=15,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return []
+        entries = json.loads(result.stdout)
+        versions: list[tuple[int, int, int]] = []
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            # Only default/cpython builds -- skip pypy/graalpy/freethreaded
+            # variants, which aren't what this repair path wants.
+            if entry.get("implementation") not in (None, "cpython"):
+                continue
+            if entry.get("variant") not in (None, "default"):
+                continue
+            parts = entry.get("version_parts") or {}
+            try:
+                versions.append(
+                    (int(parts["major"]), int(parts["minor"]), int(parts["patch"]))
+                )
+            except (KeyError, TypeError, ValueError):
+                continue
+        # Deduplicate (list --all-versions can repeat a version across
+        # platforms/arches if filtering above didn't fully narrow it) and
+        # sort newest-first.
+        return sorted(set(versions), reverse=True)
+    except Exception:
+        return []
+
+
+def _attempt_install_generation(
+    uv_bin: str,
+    request: str,
+    *,
+    project_root: Path,
+    python_root: Path,
+    current: SQLiteRuntimeInfo,
+) -> tuple[Path, Path, SQLiteRuntimeInfo] | None:
+    """One install+probe attempt for a specific version request (bare minor
+    like "3.11", or an explicit patch like "3.11.15"). Each attempt gets its
+    own generation directory so a rejected candidate's files are fully
+    cleaned up before the next attempt, matching --reinstall semantics.
+    Returns None (and cleans up) on any failure, including a vulnerable
+    or off-line candidate.
+    """
+    token = f"{int(time.time())}-{os.getpid()}-{uuid.uuid4().hex[:8]}"
+    generation = python_root / f"generation-{token}"
+    generation.mkdir(parents=True, exist_ok=False)
+    _make_world_traversable(generation)
+
+    env = managed_python_env(project_root, install_dir=generation)
+    install = subprocess.run(
+        [
+            uv_bin,
+            "python",
+            "install",
+            request,
+            "--reinstall",
+            "--no-bin",
+            "--no-registry",
+            "--no-config",
+        ],
+        cwd=project_root,
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if install.returncode != 0:
+        logger.warning(
+            "private Python install failed for %s (rc=%d): %s",
+            request,
+            install.returncode,
+            (install.stderr or install.stdout or "").strip(),
+        )
+        _remove_tree(generation, boundary=python_root)
+        return None
+
+    found = subprocess.run(
+        [
+            uv_bin,
+            "python",
+            "find",
+            request,
+            "--managed-python",
+            "--no-config",
+        ],
+        cwd=project_root,
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if found.returncode != 0 or not found.stdout.strip():
+        logger.warning(
+            "private Python lookup failed for %s (rc=%d): %s",
+            request,
+            found.returncode,
+            (found.stderr or "").strip(),
+        )
+        _remove_tree(generation, boundary=python_root)
+        return None
+
+    python = Path(found.stdout.strip().splitlines()[-1])
+    try:
+        python.resolve().relative_to(generation.resolve())
+    except (OSError, ValueError):
+        logger.warning("uv resolved Python outside the Hermes generation: %s", python)
+        _remove_tree(generation, boundary=python_root)
+        return None
+
+    candidate = probe_sqlite_runtime(python)
+    if candidate is None:
+        logger.warning("could not probe candidate Python runtime: %s", python)
+        _remove_tree(generation, boundary=python_root)
+        return None
+    if candidate.python_version[:2] != current.python_version[:2] or (
+        candidate.python_version < current.python_version
+    ):
+        logger.warning(
+            "candidate Python drifted off the %s minor line or downgraded: %s",
+            ".".join(str(p) for p in current.python_version[:2]),
+            candidate.python_version,
+        )
+        _remove_tree(generation, boundary=python_root)
+        return None
+    if candidate.wal_reset_vulnerable:
+        logger.warning(
+            "candidate Python still links vulnerable SQLite %s (%s)",
+            candidate.sqlite_version_string,
+            candidate.sqlite_source_id,
+        )
+        _remove_tree(generation, boundary=python_root)
+        return None
+    return generation, python, candidate
+
+
+def _install_safe_python_generation(
+    uv_bin: str,
+    *,
+    project_root: Path,
+    current: SQLiteRuntimeInfo,
+) -> tuple[Path, Path, SQLiteRuntimeInfo] | None:
+    runtime_root = project_root / _RUNTIME_DIR_NAME
+    python_root = managed_python_install_dir(project_root)
+    _make_world_traversable(runtime_root)
+    _make_world_traversable(python_root)
+
+    request = _runtime_request(current)
+    print(f"  → Provisioning a private Python {request} runtime with fixed SQLite...")
+    result = _attempt_install_generation(
+        uv_bin, request, project_root=project_root,
+        python_root=python_root, current=current,
+    )
+    if result is not None:
+        return result
+
+    # The bare minor-line request resolved to a still-vulnerable (or
+    # otherwise rejected) candidate. Rather than giving up immediately,
+    # query which patches on this minor line uv actually knows about and
+    # retry with explicit newer versions, newest-first -- this handles the
+    # case where the default resolution for a bare request picks an older
+    # cached/indexed patch even though a newer, non-vulnerable one is
+    # available (issue #71250).
+    env_for_list = managed_python_env(project_root, install_dir=python_root)
+    patches = _list_available_patches(
+        uv_bin, request, cwd=project_root, env=env_for_list
+    )
+    tried_versions = {current.python_version[:3]}
+    attempts = 0
+    for version_tuple in patches:
+        if attempts >= _MAX_PATCH_RETRIES:
+            break
+        if version_tuple in tried_versions:
+            continue
+        # Only NEWER patches can carry the SQLite fix. A patch at or below the
+        # installed one is either the version we already know is vulnerable or
+        # an older build that cannot contain a later fix, and the downgrade
+        # guard in _attempt_install_generation rejects it anyway -- so trying
+        # it spends a full download+install+probe+delete cycle to reach a
+        # certain rejection. This matters on a uv whose download catalog is
+        # stale: in #71250 the newest indexed 3.11 was 3.11.14, exactly the
+        # installed version, so without this skip the loop burned all five
+        # retries walking backwards (3.11.13 -> 3.11.9) before failing.
+        if version_tuple <= current.python_version[:3]:
+            continue
+        tried_versions.add(version_tuple)
+        explicit_request = ".".join(str(p) for p in version_tuple)
+        print(f"  → Retrying with explicit patch {explicit_request}...")
+        attempts += 1
+        result = _attempt_install_generation(
+            uv_bin, explicit_request, project_root=project_root,
+            python_root=python_root, current=current,
+        )
+        if result is not None:
+            return result
+    return None
+
+
+def _smoke_candidate_venv(venv_dir: Path) -> tuple[bool, str, SQLiteRuntimeInfo | None]:
+    """Exercise the candidate interpreter and imports through its real path."""
+    python = _venv_python(venv_dir)
+    info = probe_sqlite_runtime(python)
+    if info is None:
+        return False, f"could not execute {python}", None
+    if info.wal_reset_vulnerable:
+        return (
+            False,
+            f"candidate still links vulnerable SQLite {info.sqlite_version_string}",
+            info,
+        )
+
+    check = (
+        "import dotenv, fastapi, openai, prompt_toolkit, pydantic, rich, uvicorn, yaml\n"
+        "import hermes_state\n"
+    )
+    env = dict(os.environ)
+    for key in (
+        "CONDA_DEFAULT_ENV",
+        "CONDA_PREFIX",
+        "PYTHONHOME",
+        "PYTHONPATH",
+        "UV_PROJECT_ENVIRONMENT",
+        "UV_PYTHON",
+        "VIRTUAL_ENV",
+    ):
+        env.pop(key, None)
+    try:
+        result = subprocess.run(
+            [str(python), "-I", "-c", check],
+            cwd=venv_dir.parent,
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=90,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return False, str(exc), info
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "core import smoke failed").strip()
+        last_line = detail.splitlines()[-1] if detail else "core import smoke failed"
+        return False, last_line, info
+    return True, "", info
+
+
+def _stage_candidate_venv(
+    uv_bin: str,
+    *,
+    project_root: Path,
+    generation: Path,
+    python: Path,
+) -> Path | None:
+    runtime_root = project_root / _RUNTIME_DIR_NAME
+    token = f"{int(time.time())}-{os.getpid()}-{uuid.uuid4().hex[:8]}"
+    candidate = runtime_root / f"venv-candidate-{token}"
+    env = managed_python_env(
+        project_root,
+        install_dir=generation,
+    )
+    env.update({
+        "UV_PROJECT_ENVIRONMENT": str(candidate),
+        "UV_PYTHON": str(python),
+        "UV_PYTHON_DOWNLOADS": "never",
+        "VIRTUAL_ENV": str(candidate),
+    })
+
+    print("  → Building a relocatable replacement environment...")
+    created = subprocess.run(
+        [
+            uv_bin,
+            "venv",
+            str(candidate),
+            "--python",
+            str(python),
+            "--managed-python",
+            "--no-python-downloads",
+            "--relocatable",
+            "--no-config",
+        ],
+        cwd=project_root,
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if created.returncode != 0:
+        logger.warning(
+            "candidate venv creation failed (rc=%d): %s",
+            created.returncode,
+            (created.stderr or created.stdout or "").strip(),
+        )
+        _remove_tree(candidate, boundary=runtime_root)
+        return None
+
+    if not (project_root / "uv.lock").is_file():
+        logger.warning("candidate dependency sync refused: uv.lock is missing")
+        _remove_tree(candidate, boundary=runtime_root)
+        return None
+    synced = subprocess.run(
+        [
+            uv_bin,
+            "sync",
+            "--extra",
+            "all",
+            "--locked",
+            "--python",
+            str(_venv_python(candidate)),
+            "--no-config",
+        ],
+        cwd=project_root,
+        env=env,
+        check=False,
+    )
+    if synced.returncode != 0:
+        logger.warning("candidate dependency sync failed (rc=%d)", synced.returncode)
+        _remove_tree(candidate, boundary=runtime_root)
+        return None
+
+    healthy, detail, _ = _smoke_candidate_venv(candidate)
+    if not healthy:
+        logger.warning("candidate venv smoke failed: %s", detail)
+        _remove_tree(candidate, boundary=runtime_root)
+        return None
+    return candidate
+
+
+def _rename_with_retry(source: Path, destination: Path) -> None:
+    last_error: OSError | None = None
+    for delay in (0.0, 0.1, 0.25, 0.5, 1.0):
+        if delay:
+            time.sleep(delay)
+        try:
+            source.rename(destination)
+            return
+        except OSError as exc:
+            last_error = exc
+    if last_error is not None:
+        raise last_error
+
+
+def _cut_over_candidate(
+    candidate: Path,
+    *,
+    project_root: Path,
+    live: Path | None = None,
+) -> tuple[bool, Path | None, SQLiteRuntimeInfo | None, str]:
+    live = live if live is not None else project_root / _VENV_NAME
+    runtime_root = project_root / _RUNTIME_DIR_NAME
+    token = f"{int(time.time())}-{os.getpid()}-{uuid.uuid4().hex[:8]}"
+    backup = live.with_name(f"{live.name}.stale.runtime-{token}")
+    rejected = runtime_root / f"venv-rejected-{token}"
+
+    try:
+        try:
+            _rename_with_retry(live, backup)
+        except OSError as exc:
+            return False, None, None, f"could not park the existing venv: {exc}"
+
+        try:
+            _rename_with_retry(candidate, live)
+        except OSError as promote_error:
+            try:
+                _rename_with_retry(backup, live)
+            except OSError as rollback_error:
+                return (
+                    False,
+                    backup,
+                    None,
+                    "could not promote the replacement venv "
+                    f"({promote_error}); rollback failed ({rollback_error})",
+                )
+            return (
+                False,
+                None,
+                None,
+                f"could not promote the replacement venv: {promote_error}",
+            )
+
+        try:
+            healthy, detail, info = _smoke_candidate_venv(live)
+        except Exception as exc:
+            healthy, detail, info = False, f"candidate smoke raised: {exc}", None
+        if healthy:
+            return True, backup, info, ""
+
+        try:
+            _rename_with_retry(live, rejected)
+            _rename_with_retry(backup, live)
+        except OSError as exc:
+            return (
+                False,
+                backup,
+                info,
+                "post-cutover smoke failed "
+                f"({detail}); rollback failed ({exc}); rejected venv: {rejected}",
+            )
+        _remove_tree(rejected, boundary=runtime_root)
+        return False, None, info, f"post-cutover smoke failed: {detail}"
+    except BaseException:
+        if not live.exists() and backup.exists():
+            try:
+                _rename_with_retry(backup, live)
+            except OSError as exc:
+                logger.error(
+                    "interrupted runtime cutover could not restore %s from %s: %s",
+                    live,
+                    backup,
+                    exc,
+                )
+        raise
+
+
+def _acquire_repair_lock(runtime_root: Path) -> _RepairLock | None:
+    """Acquire an OS-held install lock that is released on process exit."""
+    runtime_root.mkdir(parents=True, exist_ok=True)
+    _make_world_traversable(runtime_root)
+    path = runtime_root / _REPAIR_LOCK_NAME
+    try:
+        fd = os.open(path, os.O_CREAT | os.O_RDWR, 0o600)
+    except OSError:
+        return None
+
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            if os.fstat(fd).st_size == 0:
+                os.write(fd, b"\0")
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except (ImportError, OSError):
+        os.close(fd)
+        return None
+    return _RepairLock(path=path, fd=fd)
+
+
+def _release_repair_lock(lock: _RepairLock) -> None:
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            os.lseek(lock.fd, 0, os.SEEK_SET)
+            msvcrt.locking(lock.fd, msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(lock.fd, fcntl.LOCK_UN)
+    except (ImportError, OSError):
+        pass
+    finally:
+        try:
+            os.close(lock.fd)
+        except OSError:
+            pass
+
+
+def _windows_runtime_holders() -> tuple[bool, str]:
+    if platform.system() != "Windows":
+        return False, ""
+    main_module = sys.modules.get("hermes_cli.main")
+    detector = getattr(main_module, "_detect_venv_python_processes", None)
+    if detector is None:
+        return True, "cannot verify Windows venv holders from this update context"
+    try:
+        holders = detector()
+    except Exception as exc:
+        return True, f"could not verify Windows venv holders: {exc}"
+    if holders:
+        pids = ", ".join(str(item[0]) for item in holders[:6])
+        return True, f"other Hermes processes still hold the venv (PID {pids})"
+    return False, ""
+
+
+def repair_vulnerable_runtime(
+    uv_bin: str,
+    *,
+    project_root: Path | None = None,
+    venv_dir: Path | None = None,
+) -> RuntimeRepairResult:
+    """Replace a vulnerable install venv without mutating it in place.
+
+    Every failure before cutover leaves the live venv untouched. Rename or
+    post-cutover smoke failures restore the parked venv synchronously.
+    """
+    root = Path(project_root) if project_root is not None else _PROJECT_ROOT
+    live = Path(venv_dir) if venv_dir is not None else root / _VENV_NAME
+    live_python = _venv_python(live)
+    if not (root / "pyproject.toml").is_file() or not live_python.is_file():
+        return RuntimeRepairResult("not-applicable")
+
+    current = probe_sqlite_runtime(live_python)
+    if current is None:
+        return RuntimeRepairResult(
+            "skipped",
+            f"could not probe live interpreter {live_python}",
+        )
+    if not current.wal_reset_vulnerable:
+        return RuntimeRepairResult(
+            "safe",
+            sqlite_before=current.sqlite_version_string,
+            sqlite_after=current.sqlite_version_string,
+        )
+
+    blocked, detail = _windows_runtime_holders()
+    if blocked:
+        print(f"  ⚠ SQLite runtime repair deferred: {detail}")
+        return RuntimeRepairResult(
+            "skipped",
+            detail,
+            sqlite_before=current.sqlite_version_string,
+        )
+
+    runtime_root = root / _RUNTIME_DIR_NAME
+    lock = _acquire_repair_lock(runtime_root)
+    if lock is None:
+        detail = "another runtime repair is already in progress"
+        print(f"  ⚠ SQLite runtime repair deferred: {detail}")
+        return RuntimeRepairResult(
+            "skipped",
+            detail,
+            sqlite_before=current.sqlite_version_string,
+        )
+
+    generation: Path | None = None
+    candidate: Path | None = None
+    try:
+        # Re-probe under the install-scoped lock: another updater may have
+        # completed the repair while this process was entering the path.
+        current = probe_sqlite_runtime(live_python)
+        if current is None:
+            return RuntimeRepairResult("skipped", "live interpreter probe failed")
+        if not current.wal_reset_vulnerable:
+            return RuntimeRepairResult(
+                "safe",
+                sqlite_before=current.sqlite_version_string,
+                sqlite_after=current.sqlite_version_string,
+            )
+
+        print(
+            "  ⚠ Hermes venv links SQLite "
+            f"{current.sqlite_version_string}, which has the WAL-reset bug."
+        )
+        provisioned = _install_safe_python_generation(
+            uv_bin,
+            project_root=root,
+            current=current,
+        )
+        if provisioned is None:
+            return RuntimeRepairResult(
+                "failed",
+                "could not provision a fixed private Python runtime",
+                sqlite_before=current.sqlite_version_string,
+            )
+        generation, python, candidate_info = provisioned
+
+        candidate = _stage_candidate_venv(
+            uv_bin,
+            project_root=root,
+            generation=generation,
+            python=python,
+        )
+        if candidate is None:
+            _remove_tree(generation, boundary=managed_python_install_dir(root))
+            return RuntimeRepairResult(
+                "failed",
+                "replacement environment did not pass dependency and import smoke tests",
+                sqlite_before=current.sqlite_version_string,
+                sqlite_after=candidate_info.sqlite_version_string,
+            )
+
+        cut_over, backup, final_info, cutover_detail = _cut_over_candidate(
+            candidate,
+            project_root=root,
+            live=live,
+        )
+        if not cut_over:
+            if backup is None:
+                _remove_tree(candidate, boundary=runtime_root)
+                _remove_tree(generation, boundary=managed_python_install_dir(root))
+            return RuntimeRepairResult(
+                "failed",
+                cutover_detail,
+                sqlite_before=current.sqlite_version_string,
+                sqlite_after=(
+                    final_info.sqlite_version_string if final_info is not None else ""
+                ),
+                backup_venv=backup,
+            )
+
+        final_version = (
+            final_info.sqlite_version_string
+            if final_info is not None
+            else candidate_info.sqlite_version_string
+        )
+        print(
+            "  ✓ Managed Python runtime repaired "
+            f"(SQLite {current.sqlite_version_string} → {final_version})"
+        )
+        if backup is not None:
+            print(
+                f"  ℹ Previous venv parked at {backup.name}; "
+                "keep it until all older Hermes processes have exited."
+            )
+        return RuntimeRepairResult(
+            "repaired",
+            sqlite_before=current.sqlite_version_string,
+            sqlite_after=final_version,
+            backup_venv=backup,
+        )
+    finally:
+        _release_repair_lock(lock)
+
+
 # ---------------------------------------------------------------------------
 # Installer internals
 # ---------------------------------------------------------------------------
 
+
 def _install_uv(target: Path) -> None:
     """Bootstrap uv into *target* using the official standalone installer.
 
@@ -240,9 +1068,7 @@ def _install_uv_posix(env: dict[str, str]) -> None:
 
 def _install_uv_windows(env: dict[str, str]) -> None:
     """Invoke the PowerShell installer."""
-    cmd = (
-        'irm https://astral.sh/uv/install.ps1 | iex'
-    )
+    cmd = "irm https://astral.sh/uv/install.ps1 | iex"
     subprocess.run(
         ["powershell", "-ExecutionPolicy", "Bypass", "-c", cmd],
         env=env,
@@ -250,5 +1076,6 @@ def _install_uv_windows(env: dict[str, str]) -> None:
         capture_output=True,
     )
 
+
 def rebuild_venv(uv_bin: str, venv_dir: Path, python_version: str = "3.11") -> bool:
-    True # dont remove me. ask ethernet
\ No newline at end of file
+    True  # dont remove me. ask ethernet
diff --git a/hermes_cli/mcp_config.py b/hermes_cli/mcp_config.py
index 53ab794bfff..61bcce598b6 100644
--- a/hermes_cli/mcp_config.py
+++ b/hermes_cli/mcp_config.py
@@ -986,15 +986,25 @@ def cmd_mcp_configure(args):
 
     tool_names = [t[0] for t in all_tools]
 
+    # Same matching semantics as runtime registration (tools/mcp_tool.py):
+    # exact names or fnmatch globs.
+    try:
+        from tools.mcp_tool import matches_name_filter
+    except ImportError:  # pragma: no cover — defensive fallback
+        def matches_name_filter(tool_name, patterns):
+            return tool_name in patterns
+
     if include and isinstance(include, list):
-        include_set = set(include)
+        include_set = {str(p) for p in include}
         pre_selected = {
-            i for i, tn in enumerate(tool_names) if tn in include_set
+            i for i, tn in enumerate(tool_names)
+            if matches_name_filter(tn, include_set)
         }
     elif exclude and isinstance(exclude, list):
-        exclude_set = set(exclude)
+        exclude_set = {str(p) for p in exclude}
         pre_selected = {
-            i for i, tn in enumerate(tool_names) if tn not in exclude_set
+            i for i, tn in enumerate(tool_names)
+            if not matches_name_filter(tn, exclude_set)
         }
     else:
         pre_selected = set(range(len(all_tools)))
diff --git a/hermes_cli/memory_setup.py b/hermes_cli/memory_setup.py
index e08f61c5d34..c1858fc832f 100644
--- a/hermes_cli/memory_setup.py
+++ b/hermes_cli/memory_setup.py
@@ -379,6 +379,21 @@ def cmd_setup(args) -> None:
     print("\n  Start a new session to activate.\n")
 
 
+def _env_line_safe(value) -> str:
+    """Neutralize characters that would break ``.env`` line structure.
+
+    ``.env`` is strictly line-oriented (one ``KEY=VALUE`` per line) and
+    values are interpolated straight into that line. A pasted secret with an
+    embedded CR/LF would spill onto a new line and be re-parsed as a
+    *separate* ``KEY=VALUE`` entry on the next read — injecting an arbitrary
+    variable into the credentials file. Strip every separator recognized by
+    ``str.splitlines()`` plus NUL so a value can only occupy its own line.
+    Mirrors the openviking plugin's writer and ``config.save_env_value``.
+    """
+    text = value if isinstance(value, str) else str(value)
+    return "".join(text.replace("\x00", "").splitlines())
+
+
 def _write_env_vars(env_path: Path, env_writes: dict) -> None:
     """Append or update env vars in .env file."""
     env_path.parent.mkdir(parents=True, exist_ok=True)
@@ -392,14 +407,14 @@ def _write_env_vars(env_path: Path, env_writes: dict) -> None:
     for line in existing_lines:
         key_match = line.split("=", 1)[0].strip() if "=" in line else ""
         if key_match in env_writes:
-            new_lines.append(f"{key_match}={env_writes[key_match]}")
+            new_lines.append(f"{key_match}={_env_line_safe(env_writes[key_match])}")
             updated_keys.add(key_match)
         else:
             new_lines.append(line)
 
     for key, val in env_writes.items():
         if key not in updated_keys:
-            new_lines.append(f"{key}={val}")
+            new_lines.append(f"{key}={_env_line_safe(val)}")
 
     env_path.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
     # Restrict permissions — .env holds API keys and tokens.
diff --git a/hermes_cli/moa_cmd.py b/hermes_cli/moa_cmd.py
index 417ce23a11c..8fcd8174e6d 100644
--- a/hermes_cli/moa_cmd.py
+++ b/hermes_cli/moa_cmd.py
@@ -29,7 +29,10 @@ def _prompt_choice(title: str, rows: list[str], default: int = 0) -> int:
 def _model_options() -> list[dict[str, Any]]:
     payload = build_models_payload(
         load_picker_context(),
-        include_unconfigured=True,
+        # Slot pickers must only offer providers the user can actually call.
+        # Including setup-only rows makes an unconfigured canonical provider
+        # (usually OpenRouter, due to catalog ordering) become the default.
+        include_unconfigured=False,
         picker_hints=True,
         canonical_order=True,
         pricing=True,
@@ -37,7 +40,13 @@ def _model_options() -> list[dict[str, Any]]:
         max_models=200,
     )
     providers = payload.get("providers") or []
-    return [p for p in providers if p.get("slug") and p.get("models")]
+    return [
+        p
+        for p in providers
+        if p.get("slug")
+        and str(p.get("slug")).strip().lower() != "moa"
+        and p.get("models")
+    ]
 
 
 def _pick_slot(current: dict[str, str] | None = None) -> dict[str, str]:
@@ -102,7 +111,9 @@ def cmd_moa(args) -> None:
         idx = 0
         while True:
             base = existing[idx] if idx < len(existing) else None
-            refs.append(_pick_slot(base))
+            picked = _pick_slot(base)
+            picked["enabled"] = bool((base or {}).get("enabled", True))
+            refs.append(picked)
             idx += 1
             choice = _prompt_choice("Add another reference model?", ["Add another", "Done"], 1)
             if choice == 1:
diff --git a/hermes_cli/moa_config.py b/hermes_cli/moa_config.py
index a5401c52589..24d36e4a19d 100644
--- a/hermes_cli/moa_config.py
+++ b/hermes_cli/moa_config.py
@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import base64
 import json
+import math
 from copy import deepcopy
 from typing import Any
 
@@ -20,6 +21,12 @@ DEFAULT_MOA_AGGREGATOR: dict[str, str] = {
     "model": "anthropic/claude-opus-4.8",
 }
 
+DEFAULT_MOA_REFERENCE_TIMEOUT: float | None = None
+
+
+def _default_reference_models() -> list[dict[str, Any]]:
+    return [{**slot, "enabled": True} for slot in deepcopy(DEFAULT_MOA_REFERENCE_MODELS)]
+
 
 def _coerce_float_or_none(value: Any) -> float | None:
     """Coerce to a float, or None when unset/blank/invalid.
@@ -37,6 +44,33 @@ def _coerce_float_or_none(value: Any) -> float | None:
         return None
 
 
+def _coerce_reference_timeout(value: Any) -> float | None:
+    """Return a finite positive advisor timeout, or None to inherit.
+
+    ``None`` (the default) means "no per-preset override": the reference
+    fan-out inherits the ``auxiliary.moa_reference.timeout`` config value
+    (900s by default) via ``call_llm``'s own resolution, exactly like every
+    other auxiliary task. An explicit finite positive per-preset value is
+    honored as-is — no artificial cap, since long-thinking advisor models
+    legitimately run far beyond five minutes.
+    """
+    if value is None or value == "" or isinstance(value, bool):
+        return DEFAULT_MOA_REFERENCE_TIMEOUT
+    try:
+        timeout = float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_MOA_REFERENCE_TIMEOUT
+    if not math.isfinite(timeout) or timeout <= 0:
+        return DEFAULT_MOA_REFERENCE_TIMEOUT
+    return timeout
+
+
+def _coerce_degraded_reference_policy(value: Any) -> str:
+    """Normalize failed-advisor disclosure policy; unknown values fail loud."""
+    policy = str(value or "loud").strip().lower()
+    return policy if policy in {"loud", "silent"} else "loud"
+
+
 def _coerce_int(value: Any, default: int) -> int:
     if value is None or value == "":
         return default
@@ -68,9 +102,64 @@ def _coerce_int_or_none(value: Any) -> int | None:
 
 
 def _coerce_fanout(value: Any) -> str:
-    """Normalize the fan-out cadence; unknown values fall back to default."""
+    """Normalize the fan-out cadence; unknown values fall back to default.
+
+    Canonical values are the strings ``per_iteration``, ``user_turn``, and
+    ``every_n:<N>`` (N >= 2). The ``every_n`` cadence also accepts the mapping
+    form ``{mode: every_n, n: N}`` from hand-edited YAML and normalizes it to
+    the canonical string, so the rest of the pipeline (presets, flattened
+    view, runtime) only ever sees one shape. ``every_n:1`` semantically means
+    "run every iteration" and collapses to ``per_iteration``; anything
+    unparseable falls back to ``user_turn`` (the default — cheapest cadence;
+    see #67199).
+    """
+    if isinstance(value, dict):
+        # Mapping form: {mode: every_n, n: 3}. Non-every_n mapping modes fall
+        # through to the string path below (e.g. {mode: user_turn}).
+        mode = str(value.get("mode") or "").strip().lower()
+        if mode == "every_n":
+            n = _coerce_int(value.get("n"), 0)
+            if n >= 2:
+                return f"every_n:{n}"
+            return "per_iteration" if n == 1 else "user_turn"
+        value = mode
     mode = str(value or "").strip().lower()
-    return mode if mode in {"per_iteration", "user_turn"} else "per_iteration"
+    if mode in {"per_iteration", "user_turn"}:
+        return mode
+    if mode.startswith("every_n"):
+        _, sep, rest = mode.partition(":")
+        n = _coerce_int(rest.strip(), 0) if sep else 0
+        if n >= 2:
+            return f"every_n:{n}"
+        if n == 1:
+            return "per_iteration"
+    return "user_turn"
+
+
+def coerce_privacy_filter(value: Any) -> str:
+    """Normalize ``moa.privacy_filter`` to '' (off), 'display', or 'full'.
+
+    - ``''`` (empty string): filter off — the default. ``false``/``None``/
+      unknown values land here so a hand-edited config degrades to prior
+      behavior (tolerant-read contract).
+    - ``'display'``: redact user-visible surfaces only — the reference blocks
+      shown in the UI and the saved MoA trace records. The aggregator still
+      sees raw advisor text, so answer quality is unaffected.
+    - ``'full'``: additionally redact the advisor text injected into the
+      aggregator prompt (issue #59959's literal ask). A hand-edited boolean
+      ``true`` maps here because the issue framed the toggle as "redact
+      before passing to the aggregator".
+    """
+    if value is True:
+        return "full"
+    if value is None or value is False:
+        return ""
+    mode = str(value).strip().lower()
+    if mode in {"display", "full"}:
+        return mode
+    if mode in {"true", "on", "yes", "1"}:
+        return "full"
+    return ""
 
 
 def _clean_reasoning_effort(value: Any) -> str | None:
@@ -87,7 +176,22 @@ def _clean_reasoning_effort(value: Any) -> str | None:
     return parsed.get("effort")
 
 
-def _clean_slot(slot: Any) -> dict[str, Any] | None:
+def _coerce_bool(value: Any, default: bool = True) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        text = value.strip().lower()
+        if text in {"0", "false", "no", "off"}:
+            return False
+        if text in {"1", "true", "yes", "on"}:
+            return True
+        return default
+    return bool(value)
+
+
+def _clean_slot(slot: Any, *, include_enabled: bool = False) -> dict[str, Any] | None:
     if not isinstance(slot, dict):
         return None
     provider = str(slot.get("provider") or "").strip()
@@ -105,6 +209,16 @@ def _clean_slot(slot: Any) -> dict[str, Any] | None:
     effort = _clean_reasoning_effort(slot.get("reasoning_effort"))
     if effort:
         clean["reasoning_effort"] = effort
+    # Optional per-slot max_tokens: overrides the preset-level
+    # reference_max_tokens for this specific reference model. None (the
+    # default) = no cap, so existing slots are unaffected. Allows tuning
+    # each advisor's output length independently — useful when one model
+    # is verbose and another is terse.
+    slot_mt = _coerce_int_or_none(slot.get("max_tokens"))
+    if slot_mt is not None:
+        clean["max_tokens"] = slot_mt
+    if include_enabled:
+        clean["enabled"] = _coerce_bool(slot.get("enabled"), True)
     return clean
 
 
@@ -181,15 +295,17 @@ def validate_moa_payload(raw: Any) -> list[str]:
 
 def _default_preset() -> dict[str, Any]:
     return {
-        "reference_models": deepcopy(DEFAULT_MOA_REFERENCE_MODELS),
+        "reference_models": _default_reference_models(),
         "aggregator": deepcopy(DEFAULT_MOA_AGGREGATOR),
         # None = temperature omitted from API calls (provider default),
         # matching single-model agent behavior.
         "reference_temperature": None,
         "aggregator_temperature": None,
+        "reference_timeout": DEFAULT_MOA_REFERENCE_TIMEOUT,
+        "degraded_reference_policy": "loud",
         "max_tokens": 4096,
         "reference_max_tokens": None,
-        "fanout": "per_iteration",
+        "fanout": "user_turn",
         "enabled": True,
     }
 
@@ -199,24 +315,34 @@ def _normalize_preset(raw: Any) -> dict[str, Any]:
         raw = {}
 
     raw_refs = raw.get("reference_models")
+    # reference_models may be a JSON string (hand-edited config.yaml) or a list.
+    if isinstance(raw_refs, str):
+        try:
+            raw_refs = json.loads(raw_refs)
+        except (json.JSONDecodeError, ValueError):
+            raw_refs = []
     if not isinstance(raw_refs, list):
         # A hand-edited scalar / single mapping (or a bad type) must degrade to
         # defaults instead of crashing the iteration, mirroring the tolerance
         # for the scalar fields below (reference_temperature / max_tokens).
         raw_refs = [raw_refs] if isinstance(raw_refs, dict) else []
-    refs = [_clean_slot(item) for item in raw_refs]
+    refs = [_clean_slot(item, include_enabled=True) for item in raw_refs]
     refs = [item for item in refs if item is not None]
     if not refs:
-        refs = deepcopy(DEFAULT_MOA_REFERENCE_MODELS)
+        refs = _default_reference_models()
 
     aggregator = _clean_slot(raw.get("aggregator")) or deepcopy(DEFAULT_MOA_AGGREGATOR)
 
     return {
-        "enabled": bool(raw.get("enabled", True)),
+        "enabled": _coerce_bool(raw.get("enabled"), True),
         "reference_models": refs,
         "aggregator": aggregator,
         "reference_temperature": _coerce_float_or_none(raw.get("reference_temperature")),
         "aggregator_temperature": _coerce_float_or_none(raw.get("aggregator_temperature")),
+        "reference_timeout": _coerce_reference_timeout(raw.get("reference_timeout")),
+        "degraded_reference_policy": _coerce_degraded_reference_policy(
+            raw.get("degraded_reference_policy")
+        ),
         "max_tokens": _coerce_int(raw.get("max_tokens"), 4096),
         # Optional cap on how much each reference ADVISOR may generate per turn.
         # None (default) = uncapped: advisors write full-length advice, matching
@@ -227,12 +353,18 @@ def _normalize_preset(raw: Any) -> dict[str, Any]:
         # judgement, so capping roughly halves per-turn wall time. Does NOT cap
         # the acting aggregator (its output is the user-visible answer).
         "reference_max_tokens": _coerce_int_or_none(raw.get("reference_max_tokens")),
-        # When the reference fan-out runs. "per_iteration" (default) re-runs
-        # the advisors whenever the advisory view changes — i.e. every tool
-        # iteration, so advice tracks live task state. "user_turn" runs the
-        # advisors ONCE per user turn (the original MoA shape): the
-        # aggregator gets their upfront plan-level advice, then acts alone
-        # for the rest of the tool loop.
+        # When the reference fan-out runs. "user_turn" (default) runs the
+        # advisors ONCE per user turn (the original MoA shape, and the
+        # cheapest cadence — #67199): the aggregator gets their upfront
+        # plan-level advice, then acts alone for the rest of the tool loop.
+        # "per_iteration" re-runs the advisors whenever the advisory view
+        # changes — i.e. every tool iteration, so advice tracks live task
+        # state at the cost of multiplying advisor spend by tool-loop depth.
+        # "every_n:<N>" (N >= 2) is the middle ground: advisors run on the
+        # first iteration of each user turn and every Nth tool iteration
+        # after it; in-between iterations reuse the cached guidance from the
+        # last advisor run. Also accepts the mapping form
+        # {mode: every_n, n: N}, normalized to the canonical string.
         "fanout": _coerce_fanout(raw.get("fanout")),
     }
 
@@ -278,10 +410,16 @@ def normalize_moa_config(raw: Any) -> dict[str, Any]:
         "aggregator": deepcopy(active["aggregator"]),
         "reference_temperature": active["reference_temperature"],
         "aggregator_temperature": active["aggregator_temperature"],
+        "reference_timeout": active["reference_timeout"],
+        "degraded_reference_policy": active["degraded_reference_policy"],
         "max_tokens": active["max_tokens"],
         "reference_max_tokens": active.get("reference_max_tokens"),
-        "fanout": active.get("fanout", "per_iteration"),
+        "fanout": active.get("fanout", "user_turn"),
         "enabled": active["enabled"],
+        # MoA-level (not per-preset) toggles ride at the top level alongside
+        # save_traces. privacy_filter: '' (off, default) | 'display' | 'full'
+        # — see coerce_privacy_filter for the semantics of each mode.
+        "privacy_filter": coerce_privacy_filter(raw.get("privacy_filter")),
     }
 
 
diff --git a/hermes_cli/model_setup_flows.py b/hermes_cli/model_setup_flows.py
index 394360c1607..90f628578a7 100644
--- a/hermes_cli/model_setup_flows.py
+++ b/hermes_cli/model_setup_flows.py
@@ -23,6 +23,7 @@ from __future__ import annotations
 import argparse
 import os
 import subprocess
+import urllib.parse
 
 from hermes_cli.config import clear_model_endpoint_credentials
 
@@ -833,7 +834,13 @@ def _model_flow_custom(config):
     """
     from hermes_cli.main import _auto_provider_name, _prompt_custom_api_mode_selection, _save_custom_provider
     from hermes_cli.auth import _save_model_choice, deactivate_provider
-    from hermes_cli.config import get_env_value, load_config, save_config
+    from hermes_cli.config import (
+        custom_endpoint_key_env,
+        get_env_value,
+        load_config,
+        save_config,
+        save_env_value,
+    )
     from hermes_cli.secret_prompt import masked_secret_prompt
 
     current_url = get_env_value("OPENAI_BASE_URL") or ""
@@ -988,6 +995,18 @@ def _model_flow_custom(config):
             print(f"Invalid context length: {context_length_str} — will auto-detect.")
             context_length = None
 
+    # The key goes to .env and config.yaml only references it (#69449). Keyed
+    # on host:port so two servers on one machine keep separate credentials.
+    custom_key_env = ""
+    if effective_key:
+        _parsed = urllib.parse.urlparse(effective_url)
+        _identity = _parsed.hostname or ""
+        if _parsed.port:
+            _identity = f"{_identity}_{_parsed.port}"
+        custom_key_env = custom_endpoint_key_env(_identity)
+        save_env_value(custom_key_env, effective_key)
+        print(f"  API key saved to .env as {custom_key_env}")
+
     if model_name:
         _save_model_choice(model_name)
 
@@ -999,8 +1018,8 @@ def _model_flow_custom(config):
             cfg["model"] = model
         model["provider"] = "custom"
         model["base_url"] = effective_url
-        if effective_key:
-            model["api_key"] = effective_key
+        if custom_key_env:
+            model["api_key"] = f"${{{custom_key_env}}}"
         if api_mode:
             model["api_mode"] = api_mode
         else:
@@ -1025,8 +1044,8 @@ def _model_flow_custom(config):
             _caller_model = {"default": _caller_model} if _caller_model else {}
         _caller_model["provider"] = "custom"
         _caller_model["base_url"] = effective_url
-        if effective_key:
-            _caller_model["api_key"] = effective_key
+        if custom_key_env:
+            _caller_model["api_key"] = f"${{{custom_key_env}}}"
         if api_mode:
             _caller_model["api_mode"] = api_mode
         else:
@@ -1042,6 +1061,7 @@ def _model_flow_custom(config):
         context_length=context_length,
         name=display_name,
         api_mode=api_mode,
+        key_env=custom_key_env,
     )
     _prune_replaced_custom_model_config_credentials(
         effective_url,
diff --git a/hermes_cli/model_switch.py b/hermes_cli/model_switch.py
index fa83973622a..3e239a593ed 100644
--- a/hermes_cli/model_switch.py
+++ b/hermes_cli/model_switch.py
@@ -965,6 +965,38 @@ def _configured_provider_matches(
     return matches
 
 
+def _resolve_named_custom_model_id(
+    model_name: str,
+    target_provider: str,
+    custom_providers: Optional[list],
+) -> str:
+    """Map a picker-prefixed custom model selection to its configured ID."""
+    provider = str(target_provider or "").strip().lower()
+    if not provider.startswith("custom:") or "/" not in model_name:
+        return model_name
+
+    prefix, candidate = model_name.split("/", 1)
+    prefix = prefix.strip().lower()
+    candidate = candidate.strip()
+    if not prefix or not candidate:
+        return model_name
+
+    for entry in custom_providers or []:
+        if not isinstance(entry, dict):
+            continue
+        entry_slugs = {
+            custom_provider_slug(str(entry.get(key) or "")).lower()
+            for key in ("name", "provider_key")
+            if str(entry.get(key) or "").strip()
+        }
+        if provider not in entry_slugs or f"custom:{prefix}" not in entry_slugs:
+            continue
+        for model_id in _declared_model_ids(entry.get("models")):
+            if model_id.lower() == candidate.lower():
+                return model_id
+    return model_name
+
+
 # ---------------------------------------------------------------------------
 # Core model-switching pipeline
 # ---------------------------------------------------------------------------
@@ -1447,6 +1479,9 @@ def switch_model(
         api_mode = determine_api_mode(target_provider, base_url)
 
     # --- Normalize model name for target provider ---
+    new_model = _resolve_named_custom_model_id(
+        new_model, target_provider, custom_providers
+    )
     new_model = normalize_model_for_provider(new_model, target_provider)
 
     # --- Validate ---
@@ -2024,6 +2059,16 @@ def list_authenticated_providers(
         has_creds = False
         if overlay.auth_type == "aws_sdk":
             has_creds = _has_aws_sdk_creds_for_listing(hermes_slug)
+        elif overlay.auth_type == "vertex":
+            # Vertex authenticates via OAuth2 (service-account JSON / ADC),
+            # not an API key — mirror the aws_sdk gate above, otherwise the
+            # provider is silently hidden from the /model picker even when
+            # fully configured.
+            try:
+                from agent.vertex_adapter import has_vertex_credentials
+                has_creds = has_vertex_credentials()
+            except Exception as exc:
+                logger.debug("Vertex credential check failed: %s", exc)
         elif overlay.extra_env_vars:
             has_creds = any(os.environ.get(ev) for ev in overlay.extra_env_vars)
         # Also check api_key_env_vars from PROVIDER_REGISTRY for api_key auth_type
diff --git a/hermes_cli/models.py b/hermes_cli/models.py
index 2eb1b14cc2a..3352058a515 100644
--- a/hermes_cli/models.py
+++ b/hermes_cli/models.py
@@ -41,6 +41,8 @@ def _urlopen_model_catalog_request(req: urllib.request.Request, *, timeout: floa
 OPENROUTER_MODELS: list[tuple[str, str]] = [
     # Anthropic
     ("anthropic/claude-fable-5",               ""),
+    ("anthropic/claude-opus-5",                ""),
+    ("anthropic/claude-opus-5-fast",           "2x price, higher output speed"),
     ("anthropic/claude-opus-4.8",              ""),
     ("anthropic/claude-opus-4.8-fast",         "2x price, higher output speed"),
     ("anthropic/claude-sonnet-5",              ""),
@@ -192,6 +194,7 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
     "nous": [
         # Anthropic
         "anthropic/claude-fable-5",
+        "anthropic/claude-opus-5",
         "anthropic/claude-opus-4.8",
         "anthropic/claude-sonnet-5",
         "anthropic/claude-haiku-4.5",
@@ -560,6 +563,18 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
     # Azure Foundry: user-provided endpoint and model.
     # Empty list because models depend on the endpoint configuration.
     "azure-foundry": [],
+    # Google Vertex AI — static curated list.  Vertex's OpenAI-compatible
+    # endpoint has no /models listing route, so without this entry the
+    # /model picker only ever shows the currently-configured model.
+    # Model IDs use the "google/" publisher prefix Vertex's openapi
+    # endpoint expects (see hermes_cli/model_setup_flows.py).
+    "vertex": [
+        "google/gemini-3.1-pro-preview",
+        "google/gemini-3-pro-preview",
+        "google/gemini-3.5-flash",
+        "google/gemini-3-flash-preview",
+        "google/gemini-3.1-flash-lite-preview",
+    ],
     "novita": [
         "moonshotai/kimi-k2.5",
         "minimax/minimax-m2.7",
diff --git a/hermes_cli/onepassword_secrets_cli.py b/hermes_cli/onepassword_secrets_cli.py
index f4493bf9f27..8b17c3e1eb3 100644
--- a/hermes_cli/onepassword_secrets_cli.py
+++ b/hermes_cli/onepassword_secrets_cli.py
@@ -487,6 +487,8 @@ def _op_version(binary: Path) -> str:
             [str(binary), "--version"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=5,
         )
         if res.returncode == 0:
@@ -514,7 +516,8 @@ def _op_whoami(
         env["OP_SERVICE_ACCOUNT_TOKEN"] = token_value
     try:
         res = subprocess.run(
-            cmd, env=env, capture_output=True, text=True, timeout=10
+            cmd, env=env, capture_output=True, text=True,
+            encoding="utf-8", errors="replace", timeout=10
         )
     except (OSError, subprocess.TimeoutExpired):
         return None
diff --git a/hermes_cli/plugins.py b/hermes_cli/plugins.py
index a41f6c092be..6199ce3b1af 100644
--- a/hermes_cli/plugins.py
+++ b/hermes_cli/plugins.py
@@ -1601,7 +1601,7 @@ class PluginManager:
                 init_file = plugin_dir / "__init__.py"
                 if init_file.exists():
                     try:
-                        source_text = init_file.read_text(errors="replace")[:8192]
+                        source_text = init_file.read_text(errors="replace", encoding="utf-8")[:8192]
                         if (
                             "register_memory_provider" in source_text
                             or "MemoryProvider" in source_text
diff --git a/hermes_cli/plugins_cmd.py b/hermes_cli/plugins_cmd.py
index f5c57bb88f2..07f2f3198a9 100644
--- a/hermes_cli/plugins_cmd.py
+++ b/hermes_cli/plugins_cmd.py
@@ -472,7 +472,7 @@ def _install_plugin_core(identifier: str, *, force: bool) -> tuple[Path, dict, s
             result = subprocess.run(
                 [git_exe, "clone", "--depth", "1", git_url, str(tmp_clone)],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=60,
             )
         except FileNotFoundError as e:
@@ -1969,7 +1969,7 @@ def _git_pull_plugin_dir(target: Path) -> tuple[bool, str]:
         result = subprocess.run(
             [git_exe, "pull", "--ff-only"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=60,
             cwd=str(target),
         )
diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.py
index 55231104fa2..0ab0562deae 100644
--- a/hermes_cli/profiles.py
+++ b/hermes_cli/profiles.py
@@ -406,7 +406,7 @@ def check_alias_collision(name: str) -> Optional[str]:
     try:
         result = subprocess.run(
             ["where" if is_windows else "which", canon],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
         )
         if result.returncode == 0:
             existing_path = result.stdout.strip().splitlines()[0]
@@ -414,7 +414,7 @@ def check_alias_collision(name: str) -> Optional[str]:
             expected = wrapper_dir / (f"{canon}.bat" if is_windows else canon)
             if existing_path == str(expected):
                 try:
-                    content = expected.read_text()
+                    content = expected.read_text(encoding="utf-8")
                     if "hermes -p" in content:
                         return None  # it's our wrapper, safe to overwrite
                 except Exception:
@@ -458,7 +458,7 @@ def create_wrapper_script(name: str, target: Optional[str] = None) -> Optional[P
     if is_windows:
         wrapper_path = wrapper_dir / f"{canon}.bat"
         try:
-            wrapper_path.write_text(f"@echo off\r\nhermes -p {profile} %*\r\n")
+            wrapper_path.write_text(f"@echo off\r\nhermes -p {profile} %*\r\n", encoding="utf-8")
             return wrapper_path
         except OSError as e:
             print(f"⚠ Could not create wrapper at {wrapper_path}: {e}")
@@ -467,7 +467,7 @@ def create_wrapper_script(name: str, target: Optional[str] = None) -> Optional[P
         wrapper_path = wrapper_dir / canon
         try:
             hermes_exe = shutil.which("hermes") or "hermes"
-            wrapper_path.write_text(f'#!/bin/sh\nexec {shlex.quote(hermes_exe)} -p {profile} "$@"\n')
+            wrapper_path.write_text(f'#!/bin/sh\nexec {shlex.quote(hermes_exe)} -p {profile} "$@"\n', encoding="utf-8")
             wrapper_path.chmod(wrapper_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
             return wrapper_path
         except OSError as e:
@@ -496,7 +496,7 @@ def remove_wrapper_script(name: str) -> bool:
         if wrapper_path.exists():
             try:
                 # Verify it's our wrapper before removing
-                content = wrapper_path.read_text()
+                content = wrapper_path.read_text(encoding="utf-8")
                 if "hermes -p" in content:
                     wrapper_path.unlink()
                     return True
@@ -1206,7 +1206,7 @@ def seed_profile_skills(profile_dir: Path, quiet: bool = False) -> Optional[dict
              "r = sync_skills(quiet=True); print(json.dumps(r))"],
             env={**os.environ, "HERMES_HOME": str(profile_dir)},
             cwd=str(project_root),
-            capture_output=True, text=True, timeout=60,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=60,
         )
         if result.returncode == 0 and result.stdout.strip():
             return json.loads(result.stdout.strip())
@@ -1755,7 +1755,7 @@ def _stop_gateway_process(profile_dir: Path) -> None:
         return
 
     try:
-        raw = pid_file.read_text().strip()
+        raw = pid_file.read_text(encoding="utf-8").strip()
         data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)}
         pid = int(data["pid"])
         # Route through terminate_pid so Windows uses the appropriate
@@ -1796,7 +1796,7 @@ def get_active_profile() -> str:
     """
     path = _get_active_profile_path()
     try:
-        name = path.read_text().strip()
+        name = path.read_text(encoding="utf-8").strip()
         if not name:
             return "default"
         return name
@@ -1825,7 +1825,7 @@ def set_active_profile(name: str) -> None:
     else:
         # Atomic write
         tmp = path.with_suffix(".tmp")
-        tmp.write_text(canon + "\n")
+        tmp.write_text(canon + "\n", encoding="utf-8")
         tmp.replace(path)
 
 
diff --git a/hermes_cli/providers.py b/hermes_cli/providers.py
index 2303e214115..6bfbf01feb0 100644
--- a/hermes_cli/providers.py
+++ b/hermes_cli/providers.py
@@ -222,6 +222,19 @@ HERMES_OVERLAYS: Dict[str, HermesOverlay] = {
         transport="bedrock_converse",
         auth_type="aws_sdk",
     ),
+    # Vertex authenticates via OAuth2 (service-account JSON / ADC), not a
+    # static API key or models.dev entry — resolved specially by
+    # agent/vertex_adapter.py, like bedrock's aws_sdk. Without an overlay
+    # entry get_provider("vertex") returns None, which makes
+    # _preserve_provider_with_base_url() in agent/auxiliary_client.py treat
+    # a Vertex MoA slot's resolved (base_url, api_key) pair as an unknown
+    # custom endpoint instead of "vertex" — losing the provider identity
+    # that _refresh_provider_credentials() needs to re-mint an expired
+    # OAuth2 token on a 401.
+    "vertex": HermesOverlay(
+        transport="openai_chat",
+        auth_type="vertex",
+    ),
 }
 
 
@@ -390,6 +403,7 @@ _LABEL_OVERRIDES: Dict[str, str] = {
     "lmstudio": "LM Studio",
     "local": "Local endpoint",
     "bedrock": "AWS Bedrock",
+    "vertex": "Google Vertex AI",
     "ollama-cloud": "Ollama Cloud",
     "xai-oauth": "xAI Grok OAuth (SuperGrok / Premium+)",
 }
diff --git a/hermes_cli/proxy_cli.py b/hermes_cli/proxy_cli.py
new file mode 100644
index 00000000000..2b90ec90a6c
--- /dev/null
+++ b/hermes_cli/proxy_cli.py
@@ -0,0 +1,904 @@
+"""CLI handlers for ``hermes egress ...``.
+
+Subcommands:
+    install  — download the pinned iron-proxy binary
+    setup    — interactive wizard: install binary, generate CA, mint tokens, write config
+    start    — launch the proxy as a managed subprocess
+    stop     — terminate the managed proxy
+    status   — show binary version + config presence + listen state + mappings
+    disable  — flip ``proxy.enabled`` to False (does not stop a running proxy)
+    config   — print the generated proxy.yaml path (for debugging / external review)
+
+The top-level command is ``hermes egress``.  Note that the inbound OAuth
+reverse-proxy command (``hermes proxy``) lives elsewhere in
+``hermes_cli/main.py`` — different direction, different purpose.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+from typing import List
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from agent.proxy_sources import iron_proxy as ip
+from hermes_cli.config import load_config, save_config
+
+
+# ---------------------------------------------------------------------------
+# Argparse wiring — called from hermes_cli.main
+# ---------------------------------------------------------------------------
+
+
+def register_cli(parent_parser: argparse.ArgumentParser) -> None:
+    """Attach the egress subcommand tree to a parent parser.
+
+    Called from ``hermes_cli.main`` as part of building the top-level
+    ``hermes egress`` parser.
+    """
+
+    # dest='egress_command' — keeps this subparser tree disjoint from the
+    # inbound OAuth ``hermes proxy`` subparser (which uses dest='proxy_command').
+    # No runtime collision today since they live in separate parser trees,
+    # but a future grep-and-refactor on ``proxy_command`` would otherwise
+    # hit both handlers.
+    sub = parent_parser.add_subparsers(dest="egress_command")
+
+    install = sub.add_parser(
+        "install",
+        help=f"Download iron-proxy binary (v{ip._IRON_PROXY_VERSION})",
+    )
+    install.add_argument(
+        "--force", action="store_true",
+        help="Re-download even if a managed copy already exists",
+    )
+    install.set_defaults(func=cmd_install)
+
+    setup = sub.add_parser(
+        "setup",
+        help="Interactive wizard: install + CA + mint tokens + write config",
+    )
+    setup.add_argument(
+        "--tunnel-port", type=int, default=None,
+        help=f"Override the tunnel port (default {ip._DEFAULT_TUNNEL_PORT})",
+    )
+    setup.add_argument(
+        "--from-bitwarden", action="store_true",
+        help="Treat secrets as managed by Bitwarden — discover provider keys "
+             "from secrets.bitwarden config instead of the current env.  Fails "
+             "loudly if BW is unreachable rather than silently falling back.",
+    )
+    setup.add_argument(
+        "--no-bitwarden", action="store_true",
+        help="Explicitly switch credential_source back to env on re-setup "
+             "(only meaningful when the previous setup used --from-bitwarden).",
+    )
+    setup.add_argument(
+        "--rotate-tokens", action="store_true",
+        help="Mint fresh proxy tokens for every provider (default is to "
+             "preserve tokens for providers that already had one — avoids "
+             "401-ing already-running sandboxes on re-setup).",
+    )
+    setup.add_argument(
+        "--restart", dest="restart", action="store_true", default=None,
+        help="If a daemon is already running, restart it automatically after "
+             "writing the new config/tokens (non-interactive default on a tty "
+             "is to ask).",
+    )
+    setup.add_argument(
+        "--no-restart", dest="restart", action="store_false",
+        help="Do not restart a running daemon after setup; you'll need to run "
+             "`hermes egress restart` yourself for changes to take effect.",
+    )
+    setup.set_defaults(func=cmd_setup)
+
+    start = sub.add_parser("start", help="Start the managed iron-proxy")
+    start.set_defaults(func=cmd_start)
+
+    stop = sub.add_parser("stop", help="Stop the managed iron-proxy")
+    stop.set_defaults(func=cmd_stop)
+
+    restart = sub.add_parser(
+        "restart",
+        help="Restart the managed iron-proxy (stop if running, then start)",
+    )
+    restart.set_defaults(func=cmd_restart)
+
+    reload_p = sub.add_parser(
+        "reload",
+        help="Hot-reload the running daemon's ruleset from proxy.yaml "
+             "(management API — no restart, no dropped connections)",
+    )
+    reload_p.set_defaults(func=cmd_reload)
+
+    status = sub.add_parser("status", help="Show proxy state and mappings")
+    status.add_argument(
+        "--show-tokens", action="store_true",
+        help="Print the proxy tokens (default: redacted prefix only). "
+             "Beware: tokens may persist in your shell history.",
+    )
+    status.set_defaults(func=cmd_status)
+
+    disable = sub.add_parser("disable", help="Turn off the proxy integration")
+    disable.set_defaults(func=cmd_disable)
+
+    cfg = sub.add_parser("config", help="Print the generated proxy.yaml path")
+    cfg.set_defaults(func=cmd_config)
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    console = Console()
+    try:
+        binary = ip.install_iron_proxy(force=bool(args.force))
+    except Exception as exc:  # noqa: BLE001 — top-level user-facing error funnel
+        console.print(f"[red]✗ install failed:[/red] {exc}")
+        console.print(
+            "  Manual install: https://github.com/ironsh/iron-proxy/releases"
+        )
+        return 1
+    version = ip.iron_proxy_version(binary) or "(version unknown)"
+    console.print(f"[green]✓[/green] installed {binary}  {version}")
+    return 0
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    console = Console()
+    console.print(Panel.fit(
+        "[bold]iron-proxy setup[/bold]\n\n"
+        "Routes outbound sandbox traffic through a local TLS-intercepting\n"
+        "proxy so prompt-injected agents never see real provider API keys.\n\n"
+        "[dim]Project: https://github.com/ironsh/iron-proxy  (Apache-2.0)[/dim]",
+        border_style="cyan",
+    ))
+
+    # ------------------------------------------------------------------ binary
+    console.print()
+    console.print("[bold]Step 1[/bold]  Install the iron-proxy binary")
+    try:
+        binary = ip.find_iron_proxy(install_if_missing=False)
+        if binary is None:
+            console.print("  No iron-proxy on PATH — downloading…")
+            binary = ip.install_iron_proxy()
+        version = ip.iron_proxy_version(binary) or "(version unknown)"
+        console.print(f"  [green]✓[/green] {binary}  {version}")
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"  [red]✗ install failed: {exc}[/red]")
+        return 1
+
+    # ------------------------------------------------------------------ CA
+    console.print()
+    console.print("[bold]Step 2[/bold]  Generate a CA cert")
+    try:
+        ca_crt, ca_key = ip.ensure_ca_cert()
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"  [red]✗ CA generation failed: {exc}[/red]")
+        return 1
+    console.print(f"  [green]✓[/green] {ca_crt}")
+
+    # ------------------------------------------------------------------ mint
+    console.print()
+    console.print("[bold]Step 3[/bold]  Mint proxy tokens for known providers")
+
+    available_env_names: List[str] = []
+    if args.from_bitwarden:
+        cfg = load_config()
+        bw_cfg = (cfg.get("secrets") or {}).get("bitwarden") or {}
+        if not bw_cfg.get("enabled"):
+            console.print(
+                "  [red]✗ --from-bitwarden requested but "
+                "secrets.bitwarden.enabled is false.[/red]"
+            )
+            console.print(
+                "  Run `hermes secrets bitwarden setup` first, or omit "
+                "--from-bitwarden."
+            )
+            return 1
+        try:
+            from agent.secret_sources import bitwarden as bw
+            access_token = os.environ.get(
+                bw_cfg.get("access_token_env", "BWS_ACCESS_TOKEN"), ""
+            ).strip()
+            if not access_token:
+                console.print(
+                    f"  [red]✗ --from-bitwarden requested but "
+                    f"{bw_cfg.get('access_token_env', 'BWS_ACCESS_TOKEN')} "
+                    "is not set in the environment.[/red]"
+                )
+                return 1
+            secrets, _ = bw.fetch_bitwarden_secrets(
+                access_token=access_token,
+                project_id=bw_cfg.get("project_id", ""),
+                cache_ttl_seconds=0,
+                use_cache=False,
+            )
+            available_env_names = list(secrets.keys())
+            if not available_env_names:
+                console.print(
+                    "  [red]✗ Bitwarden returned an empty secrets list.[/red]\n"
+                    "  Check the project_id in secrets.bitwarden and the "
+                    "BWS access-token's project scope."
+                )
+                return 1
+            console.print(
+                f"  Pulled {len(available_env_names)} env names from Bitwarden."
+            )
+        except Exception as exc:  # noqa: BLE001 — explicit user-facing error
+            console.print(
+                f"  [red]✗ Could not enumerate Bitwarden secrets: {exc}[/red]"
+            )
+            console.print(
+                "  Either fix the Bitwarden config and retry, or rerun setup "
+                "without --from-bitwarden (the proxy will read secrets from "
+                "the host process env at start time)."
+            )
+            return 1
+    else:
+        # Env-based discovery reads os.environ.  Operators commonly keep their
+        # provider keys only in ~/.hermes/.env (loaded automatically when the
+        # agent runs, but NOT exported into an interactive shell).  Fall back
+        # to loading that file so `hermes egress setup` finds the same keys the
+        # agent would — otherwise a user with keys solely in .env sees a
+        # confusing "no provider keys found" when the keys clearly "exist".
+        loaded = _load_env_file_into_environ()
+        if loaded:
+            console.print(
+                f"  [dim]Loaded {loaded} provider key name(s) from "
+                f"~/.hermes/.env for discovery.[/dim]"
+            )
+
+    discovered = ip.discover_provider_mappings(
+        available_env_names=available_env_names or None,
+    )
+
+    # Preserve tokens for providers we already had unless the operator
+    # explicitly requested rotation.  This prevents re-running `hermes
+    # egress setup` from invalidating tokens baked into already-running
+    # sandboxes.
+    existing = ip.load_mappings()
+    rotate = bool(getattr(args, "rotate_tokens", False))
+
+    # P3 confirmation gate: --rotate-tokens invalidates every running
+    # sandbox's proxy tokens immediately.  An accidental re-run (history
+    # scroll-back, tmux paste) is unrecoverable, so require explicit
+    # confirmation when there's something to actually rotate.  Skipped
+    # when stdin isn't a tty (CI / non-interactive use), in which case
+    # the operator passed the flag deliberately.
+    if rotate and existing:
+        import sys as _sys
+        from datetime import datetime as _dt
+        if _sys.stdin.isatty():
+            console.print(
+                "[yellow]⚠[/yellow]  --rotate-tokens will invalidate proxy "
+                "tokens in every running Hermes sandbox.  They will start "
+                "401-ing against upstreams until restarted."
+            )
+            try:
+                ans = input("Type 'rotate' to confirm: ").strip().lower()
+            except EOFError:
+                ans = ""
+            if ans != "rotate":
+                console.print("[yellow]Cancelled.[/yellow]")
+                return 1
+        # Backup the existing mappings before we overwrite.  The
+        # resulting ``.rotated-<unix>`` sibling is plain JSON and lets
+        # the operator manually recover tokens if they realise the
+        # rotation was a mistake.
+        try:
+            import shutil as _shutil
+            state_dir = ip._proxy_state_dir()
+            mappings_src = state_dir / "mappings.json"
+            if mappings_src.exists():
+                ts = _dt.now().strftime("%Y%m%dT%H%M%S")
+                backup = state_dir / f"mappings.json.rotated-{ts}"
+                _shutil.copy2(str(mappings_src), str(backup))
+                console.print(f"  [dim]backup: {backup}[/dim]")
+        except OSError as exc:
+            console.print(
+                f"  [yellow]Could not back up mappings before rotation: "
+                f"{exc}[/yellow]"
+            )
+    elif rotate and not existing:
+        console.print(
+            "[dim]Note: --rotate-tokens is a no-op on first-time setup "
+            "(no existing tokens to rotate).[/dim]"
+        )
+
+    mappings = ip.merge_mappings(
+        existing=existing,
+        discovered=discovered,
+        rotate=rotate,
+    )
+
+    if not mappings:
+        console.print(
+            "  [yellow]No known provider API keys found in env/Bitwarden.[/yellow]"
+        )
+        console.print(
+            "  Set at least one of these and rerun setup:"
+        )
+        for env_name in sorted(ip._BEARER_PROVIDERS):
+            console.print(f"    - {env_name}")
+        return 1
+
+    # Warn the operator about providers we recognize but can't proxy
+    # (AWS Bedrock SigV4, GCP Vertex service-account OAuth).  These still
+    # work — they just bypass the egress isolation.
+    uncovered = ip.discover_uncovered_providers(
+        available_env_names=available_env_names or None,
+    )
+    if uncovered:
+        console.print()
+        console.print(
+            "  [yellow]⚠[/yellow]  Detected provider env vars that the "
+            "proxy does not yet cover:"
+        )
+        for name in uncovered:
+            console.print(f"    - {name}")
+        console.print(
+            "  [dim]These providers use request signing or SDK-minted "
+            "OAuth (SigV4, service-account files) and will hold real "
+            "credentials inside the sandbox.  Egress isolation is "
+            "INCOMPLETE for these.[/dim]"
+        )
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Provider env", style="cyan")
+    table.add_column("Upstream hosts", style="dim")
+    table.add_column("Proxy token", style="green")
+    for m in mappings:
+        table.add_row(
+            m.real_env_name,
+            ", ".join(m.upstream_hosts),
+            _redact_token(m.proxy_token),
+        )
+    console.print(table)
+
+    # ------------------------------------------------------------------ write
+    console.print()
+    console.print("[bold]Step 4[/bold]  Write config and persist mappings")
+
+    cfg = load_config()
+    proxy_cfg = cfg.setdefault("proxy", {})
+    # ``args.tunnel_port`` is None when the flag was not given; ``0`` is
+    # invalid for a TCP listener so we treat it as an explicit refusal
+    # and surface a clear error rather than silently substituting the
+    # default.
+    if args.tunnel_port is not None:
+        if args.tunnel_port < 1 or args.tunnel_port > 65534:
+            console.print(
+                "  [red]✗ --tunnel-port must be between 1 and 65534 "
+                "(the plain-HTTP listener uses port+1).[/red]"
+            )
+            return 1
+        tunnel_port = int(args.tunnel_port)
+    else:
+        tunnel_port = int(proxy_cfg.get("tunnel_port", ip._DEFAULT_TUNNEL_PORT))
+    proxy_cfg["tunnel_port"] = tunnel_port
+
+    extra_hosts = list(proxy_cfg.get("extra_allowed_hosts") or [])
+    allowed = list(ip._DEFAULT_ALLOWED_HOSTS) + [
+        h for h in extra_hosts if h not in ip._DEFAULT_ALLOWED_HOSTS
+    ]
+
+    audit_log_path = ip._proxy_state_dir() / "audit.log"
+    # Pre-create the audit log with 0o600.  On the pinned v0.39 the
+    # daemon does NOT write to this file (no ``log.audit_path`` field in
+    # its config schema) — it's reserved for the v0.40+ upgrade where
+    # per-request records start flowing.  Because the file is
+    # non-load-bearing today, a pre-create failure (immutable parent,
+    # pre-existing foreign-owned file, full disk) is a WARNING, not a
+    # setup abort.
+    audit_log_ok = True
+    try:
+        ip.ensure_audit_log(audit_log_path)
+    except RuntimeError as exc:
+        audit_log_ok = False
+        console.print(f"  [yellow]⚠ {exc}[/yellow]")
+
+    # Allow operator override of the deny list via
+    # ``proxy.upstream_deny_cidrs`` — but the default (None) gives a safe
+    # default-deny list (loopback, IMDS, RFC1918) that matches the docs
+    # promise.
+    deny_cidrs = proxy_cfg.get("upstream_deny_cidrs")
+    iron_cfg = ip.build_proxy_config(
+        mappings=mappings,
+        ca_cert=ca_crt,
+        ca_key=ca_key,
+        tunnel_port=tunnel_port,
+        audit_log=audit_log_path,
+        allowed_hosts=allowed,
+        upstream_deny_cidrs=deny_cidrs,
+    )
+    cfg_path = ip.write_proxy_config(iron_cfg)
+    mappings_path = ip.write_mappings(mappings)
+    # Mint (or keep) the management-API bearer key.  The generated config
+    # enables a loopback management listener whose /v1/reload lets
+    # `hermes egress reload` apply future ruleset changes without a
+    # restart; the daemon requires the key env var to be non-empty at
+    # startup, so make sure the token exists before first start.
+    ip.ensure_management_token()
+    console.print(f"  [green]✓[/green] config:   {cfg_path}")
+    console.print(f"  [green]✓[/green] mappings: {mappings_path}")
+    if audit_log_ok:
+        console.print(
+            f"  [green]✓[/green] audit log: {audit_log_path} "
+            f"[dim](reserved — not written by iron-proxy v0.39; "
+            f"per-request records land in iron-proxy.log)[/dim]"
+        )
+
+    # ------------------------------------------------------------------ enable
+    proxy_cfg["enabled"] = True
+    proxy_cfg.setdefault("auto_install", True)
+    proxy_cfg.setdefault("enforce_on_docker", True)
+    # CRITICAL: do NOT silently downgrade credential_source on re-run.
+    # If the operator previously configured `bitwarden` mode (e.g. for
+    # rotation), running `hermes egress setup` again WITHOUT
+    # --from-bitwarden must not rewrite credential_source to "env" —
+    # that silently breaks the Bitwarden rotation guarantee the docs
+    # make.  Require an explicit --no-bitwarden to switch back.
+    existing_source = proxy_cfg.get("credential_source")
+    if args.from_bitwarden:
+        proxy_cfg["credential_source"] = "bitwarden"
+    elif getattr(args, "no_bitwarden", False):
+        proxy_cfg["credential_source"] = "env"
+        if existing_source == "bitwarden":
+            console.print(
+                "[yellow]Switched credential_source from bitwarden to env.[/yellow]"
+            )
+    elif existing_source == "bitwarden":
+        # Preserve the existing bitwarden mode.  Surface the decision so
+        # the operator knows we kept it.
+        console.print(
+            "[dim]Keeping credential_source=bitwarden from existing config. "
+            "Pass --no-bitwarden to switch to env-based credentials.[/dim]"
+        )
+    else:
+        proxy_cfg["credential_source"] = "env"
+    save_config(cfg)
+
+    live_status = ip.get_status()
+    was_running = live_status.pid is not None
+    if was_running:
+        ip.stop_proxy()
+
+    # Decide whether to (re)start the daemon so the new config/tokens take
+    # effect, rather than leaving the operator to remember a manual restart
+    # (the #1 UX papercut for this feature).
+    #   --restart      → always (re)start, even if nothing was running
+    #   --no-restart   → never; leave it as-is and print the manual hint
+    #   neither + tty  → ask (only when a daemon was running)
+    #   neither + !tty → restart when a daemon was running; otherwise no-op
+    #                    (first-time setup never auto-starts — matches the
+    #                    "configured, now run start" flow)
+    import sys as _sys
+    restart_pref = getattr(args, "restart", None)
+    if restart_pref is True:
+        do_restart = True
+    elif restart_pref is False:
+        do_restart = False
+    elif was_running:
+        if _sys.stdin.isatty():
+            try:
+                ans = input(
+                    "  Restart the running proxy now with the new config? [Y/n] "
+                ).strip().lower()
+            except EOFError:
+                ans = ""
+            do_restart = ans in ("", "y", "yes")
+        else:
+            do_restart = True
+    else:
+        do_restart = False
+
+    if do_restart:
+        try:
+            new_status = ip.start_proxy(
+                install_if_missing=bool(proxy_cfg.get("auto_install", True)),
+            )
+        except Exception as exc:  # noqa: BLE001 — user-facing funnel
+            console.print(
+                f"  [yellow]⚠ could not start iron-proxy with the new "
+                f"config: {exc}[/yellow]"
+            )
+            console.print(
+                "  Run [cyan]hermes egress start[/cyan] manually before "
+                "launching new Docker sandboxes."
+            )
+        else:
+            listening = "listening" if new_status.listening else "not yet listening"
+            verb = "restarted" if was_running else "started"
+            console.print(
+                f"  [green]✓[/green] {verb} iron-proxy with the new config "
+                f"(pid={new_status.pid}, port={new_status.tunnel_port}, {listening})"
+            )
+    elif was_running:
+        console.print(
+            "  [yellow]⚠ stopped the running iron-proxy; config or tokens "
+            "changed.  Run [cyan]hermes egress restart[/cyan] (or "
+            "[cyan]start[/cyan]) before launching new Docker sandboxes.[/yellow]"
+        )
+
+    console.print()
+    console.print(
+        "[green]✓ iron-proxy is configured.[/green]  "
+        "Sandboxes will route outbound traffic through it."
+    )
+    console.print(
+        "  Start:   [cyan]hermes egress start[/cyan]\n"
+        "  Restart: [cyan]hermes egress restart[/cyan]  (after any re-setup)\n"
+        "  Reload:  [cyan]hermes egress reload[/cyan]   (apply ruleset edits "
+        "in-place, no restart)\n"
+        "  Status:  [cyan]hermes egress status[/cyan]\n"
+        "  Stop:    [cyan]hermes egress stop[/cyan]\n"
+        "  Disable: [cyan]hermes egress disable[/cyan]"
+    )
+    return 0
+
+
+def cmd_start(args: argparse.Namespace) -> int:
+    console = Console()
+    cfg = load_config()
+    proxy_cfg = cfg.get("proxy") or {}
+    if not proxy_cfg.get("enabled"):
+        console.print(
+            "[yellow]proxy.enabled is false — run `hermes egress setup` "
+            "first.[/yellow]"
+        )
+        return 1
+
+    # If the operator opted in to Bitwarden-rotation semantics, refresh
+    # upstream secrets from BSM at startup.  This is what delivers the
+    # rotation guarantee that distinguishes ``credential_source:
+    # bitwarden`` from ``credential_source: env``.  Without it, rotating
+    # a key in the Bitwarden web app doesn't reach the proxy.
+    credential_source = proxy_cfg.get("credential_source", "env")
+    bw_cfg = (cfg.get("secrets") or {}).get("bitwarden")
+    refresh_bw = (
+        credential_source == "bitwarden"
+        and bw_cfg is not None
+        and bool(bw_cfg.get("enabled"))
+    )
+    # Silent-degrade guard: the operator explicitly chose
+    # ``credential_source: bitwarden``, but secrets.bitwarden has since
+    # been disabled or removed.  Proceeding would quietly start on host
+    # env — exactly the bug class the BW mode is meant to defeat.  Refuse
+    # unless the documented escape hatch is set.
+    if credential_source == "bitwarden" and not refresh_bw:
+        if bool(proxy_cfg.get("allow_env_fallback", False)):
+            console.print(
+                "[yellow]⚠ credential_source=bitwarden but "
+                "secrets.bitwarden is disabled or missing — falling back "
+                "to host-env secrets (allow_env_fallback=true).  Rotated "
+                "Bitwarden keys will NOT propagate.[/yellow]"
+            )
+        else:
+            console.print(
+                "[red]✗ Refusing to start: proxy.credential_source is "
+                "'bitwarden' but secrets.bitwarden is disabled or "
+                "missing.[/red]"
+            )
+            console.print(
+                "  Re-enable it (`secrets.bitwarden.enabled: true`), switch "
+                "back to env credentials with `hermes egress setup "
+                "--no-bitwarden`, or set `proxy.allow_env_fallback: true` "
+                "to opt into the host-env fallback."
+            )
+            return 1
+    # Pass the proxy-side allow_env_fallback opt-in through to
+    # start_proxy.  This is a deliberate, documented escape hatch: when
+    # set, the daemon silently falls back to host env if BWS is
+    # unreachable, instead of raising.  Default is strict (raise).
+    if refresh_bw and bw_cfg is not None:
+        bw_cfg = dict(bw_cfg)
+        bw_cfg["allow_env_fallback"] = bool(
+            proxy_cfg.get("allow_env_fallback", False)
+        )
+
+    # fail_on_uncovered_providers is intentionally gone: the LLM-specific
+    # providers it guarded (Anthropic native, Azure OpenAI, Gemini) are now
+    # swapped via per-provider match_headers rules, so the fail-closed tier
+    # is empty and the flag would be a dead toggle.
+
+    # stephenschoettler #1: when `credential_source: bitwarden`, the
+    # operator picked BWS specifically to get the rotation guarantee —
+    # silently falling back to parent-env at start_proxy time reintroduces
+    # exactly the bug class the BW mode is supposed to defeat (host env
+    # is stale / mismatched).  Pre-check at the wizard layer so we fail
+    # loud with actionable error messages BEFORE start_proxy degrades.
+    if refresh_bw:
+        bw_access_env = (bw_cfg or {}).get("access_token_env", "BWS_ACCESS_TOKEN")
+        if not os.environ.get(bw_access_env, "").strip():
+            console.print(
+                f"[red]✗ Refusing to start: credential_source=bitwarden but "
+                f"{bw_access_env} is not set in the environment.[/red]"
+            )
+            console.print(
+                "  Either export the access token, or run "
+                "`hermes egress setup --no-bitwarden` to switch back to "
+                "env-based credentials."
+            )
+            return 1
+        if not (bw_cfg or {}).get("project_id"):
+            console.print(
+                "[red]✗ Refusing to start: credential_source=bitwarden but "
+                "secrets.bitwarden.project_id is empty.[/red]"
+            )
+            console.print(
+                "  Run `hermes secrets bitwarden setup` to configure the "
+                "project, or switch back via `hermes egress setup "
+                "--no-bitwarden`."
+            )
+            return 1
+
+    try:
+        status = ip.start_proxy(
+            install_if_missing=bool(proxy_cfg.get("auto_install", True)),
+            refresh_secrets_from_bitwarden=refresh_bw,
+            bitwarden_config=bw_cfg,
+        )
+    except Exception as exc:  # noqa: BLE001 — top-level user-facing funnel
+        console.print(f"[red]✗ failed to start iron-proxy:[/red] {exc}")
+        return 1
+    if status.pid:
+        listening = (
+            "[green]listening[/green]"
+            if status.listening
+            else "[yellow]not yet listening[/yellow]"
+        )
+        console.print(
+            f"[green]✓[/green] iron-proxy running  pid={status.pid}  "
+            f"port={status.tunnel_port}  {listening}"
+        )
+    else:
+        console.print("[red]✗ iron-proxy did not come up cleanly[/red]")
+        return 1
+    return 0
+
+
+def cmd_stop(args: argparse.Namespace) -> int:
+    console = Console()
+    if ip.stop_proxy():
+        console.print("[green]✓[/green] iron-proxy stopped")
+    else:
+        console.print("[dim]iron-proxy was not running[/dim]")
+    return 0
+
+
+def cmd_restart(args: argparse.Namespace) -> int:
+    """Stop the running daemon (if any) and start it with the current config.
+
+    The one-command way to apply config changes (new allowlist hosts, rotated
+    tokens, a Bitwarden key rotation) without making the operator remember the
+    stop/start dance.  Delegates to ``cmd_start`` so all the credential-source
+    guards run exactly as they do for ``start``.
+    """
+    console = Console()
+    was_running = ip.stop_proxy()
+    if was_running:
+        console.print("[dim]stopped the running iron-proxy[/dim]")
+    return cmd_start(args)
+
+
+def cmd_reload(args: argparse.Namespace) -> int:
+    """Hot-reload the running daemon's ruleset via the management API.
+
+    Applies allowlist / token / mapping changes already written to
+    proxy.yaml WITHOUT restarting the daemon — no dropped connections, no
+    restart window.  When the change involves new upstream SECRETS (a
+    Bitwarden rotation, a newly added provider key), use
+    ``hermes egress restart`` instead: the daemon reads real credentials
+    from its own environment at spawn time, and a reload does not
+    re-populate that env.
+    """
+    console = Console()
+    try:
+        ip.reload_proxy()
+    except Exception as exc:  # noqa: BLE001 — top-level user-facing funnel
+        console.print(f"[red]✗ reload failed:[/red] {exc}")
+        return 1
+    console.print(
+        "[green]✓[/green] iron-proxy ruleset reloaded in-place "
+        "(no restart, connections preserved)"
+    )
+    console.print(
+        "[dim]Note: new upstream secrets (rotated keys, new providers) "
+        "still need `hermes egress restart` — the daemon reads real "
+        "credentials from its environment at spawn time.[/dim]"
+    )
+    return 0
+
+
+def format_status_text(*, show_tokens: bool = False) -> str:
+    """Plain-text egress status for slash commands, Dashboard, and Desktop."""
+    cfg = load_config()
+    proxy_cfg = cfg.get("proxy") or {}
+    status = ip.get_status()
+
+    def yn(value: bool) -> str:
+        return "yes" if value else "no"
+
+    lines = [
+        "Egress proxy status",
+        "",
+        f"Enabled: {yn(bool(proxy_cfg.get('enabled')))}",
+        f"Binary: {status.binary_path or '(missing)'}",
+        f"Binary version: {status.binary_version or '(unknown)'}",
+        f"Config: {status.config_path or '(not generated)'}",
+        f"CA cert: {status.ca_cert_path or '(not generated)'}",
+        f"Tunnel port: {status.tunnel_port}",
+        f"Process: pid {status.pid}" if status.pid else "Process: (stopped)",
+        f"Listening: {yn(status.listening)}",
+        f"Credential src: {proxy_cfg.get('credential_source', 'env')}",
+        f"Docker enforce: {yn(bool(proxy_cfg.get('enforce_on_docker', True)))}",
+        "Scope: Docker backend only in this release",
+    ]
+
+    mappings = ip.load_mappings()
+    if mappings:
+        lines.extend(["", "Token mappings:"])
+        for m in mappings:
+            tok = m.proxy_token if show_tokens else _redact_token(m.proxy_token)
+            lines.append(f"  - {m.real_env_name}: {tok} ({', '.join(m.upstream_hosts)})")
+
+    uncovered = ip.discover_uncovered_providers()
+    if uncovered:
+        lines.extend([
+            "",
+            "Uncovered providers (real credentials still visible inside the sandbox):",
+        ])
+        for name in uncovered:
+            lines.append(f"  - {name}")
+
+    if bool(proxy_cfg.get("enabled")) and not status.configured:
+        lines.extend(["", "Next: run `hermes egress setup` to mint tokens and write proxy.yaml."])
+    elif bool(proxy_cfg.get("enabled")) and not (status.pid and status.listening):
+        lines.extend(["", "Next: run `hermes egress start` before launching Docker sandboxes."])
+
+    return "\n".join(lines)
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    console = Console()
+    cfg = load_config()
+    proxy_cfg = cfg.get("proxy") or {}
+    status = ip.get_status()
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("", style="bold")
+    table.add_column("")
+    table.add_row("Enabled",        _yn(bool(proxy_cfg.get("enabled"))))
+    table.add_row("Binary",         str(status.binary_path or "[dim](missing)[/dim]"))
+    table.add_row("Binary version", status.binary_version or "[dim](unknown)[/dim]")
+    table.add_row("Config",         str(status.config_path or "[dim](not generated)[/dim]"))
+    table.add_row("CA cert",        str(status.ca_cert_path or "[dim](not generated)[/dim]"))
+    table.add_row("Tunnel port",    str(status.tunnel_port))
+    table.add_row("Process",        f"pid {status.pid}" if status.pid else "[dim](stopped)[/dim]")
+    table.add_row("Listening",      _yn(status.listening))
+    table.add_row("Credential src", str(proxy_cfg.get("credential_source", "env")))
+    table.add_row("Docker enforce", _yn(bool(proxy_cfg.get("enforce_on_docker", True))))
+    console.print(table)
+
+    mappings = ip.load_mappings()
+    if mappings:
+        console.print()
+        console.print("[bold]Token mappings[/bold]")
+        m_table = Table(show_header=True, header_style="bold")
+        m_table.add_column("Real env", style="cyan")
+        m_table.add_column("Upstream", style="dim")
+        m_table.add_column("Proxy token", style="green")
+        for m in mappings:
+            tok = m.proxy_token if args.show_tokens else _redact_token(m.proxy_token)
+            m_table.add_row(m.real_env_name, ", ".join(m.upstream_hosts), tok)
+        console.print(m_table)
+        if args.show_tokens:
+            console.print(
+                "[yellow]⚠[/yellow]  proxy tokens just printed in full — "
+                "they may persist in your shell history.  Consider clearing "
+                "it after this command."
+            )
+
+    # Surface uncovered providers so the operator knows the isolation
+    # boundary is incomplete for those upstreams.
+    uncovered = ip.discover_uncovered_providers()
+    if uncovered:
+        console.print()
+        console.print(
+            "[yellow]Uncovered providers[/yellow] "
+            "(real credentials still visible inside the sandbox):"
+        )
+        for name in uncovered:
+            console.print(f"  - {name}")
+
+    return 0
+
+
+def cmd_disable(args: argparse.Namespace) -> int:
+    console = Console()
+    cfg = load_config()
+    proxy_cfg = cfg.setdefault("proxy", {})
+    if not proxy_cfg.get("enabled"):
+        console.print("[dim]proxy.enabled was already false.[/dim]")
+        return 0
+    proxy_cfg["enabled"] = False
+    save_config(cfg)
+    console.print("[green]✓[/green] proxy.enabled set to false")
+    # Use the public get_status() pid (which already incorporates the
+    # _pid_alive check) instead of reaching into ip._read_pid().  That
+    # private accessor only proves the pidfile is non-empty — a stale
+    # pidfile from a crashed previous run would fire the warning
+    # spuriously.
+    if ip.get_status().pid is not None:
+        console.print(
+            "  iron-proxy is still running — stop it with "
+            "[cyan]hermes egress stop[/cyan] if you want it down too."
+        )
+    return 0
+
+
+def cmd_config(args: argparse.Namespace) -> int:
+    console = Console()
+    status = ip.get_status()
+    if status.config_path is None:
+        console.print(
+            "[yellow](no config generated — run `hermes egress setup`)[/yellow]"
+        )
+        return 1
+    console.print(str(status.config_path))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_env_file_into_environ() -> int:
+    """Backfill provider keys from ``~/.hermes/.env`` into ``os.environ``.
+
+    ``hermes egress setup`` discovers providers by reading ``os.environ``, but
+    many operators keep their keys ONLY in ``~/.hermes/.env`` (which the agent
+    loads at runtime but which is NOT exported into an interactive shell).
+    Without this, ``setup`` reports "no provider keys found" even though the
+    keys plainly exist — a confusing first-run papercut.
+
+    Only fills names that aren't already set in the process env (an exported
+    value always wins), and only for known bearer-provider names so we don't
+    slurp unrelated secrets into the process. Returns the count of names added.
+    """
+    try:
+        from hermes_cli.config import load_env
+    except ImportError:
+        return 0
+    try:
+        file_env = load_env()
+    except Exception:  # noqa: BLE001 — best-effort convenience, never fatal
+        return 0
+    added = 0
+    known = set(ip._BEARER_PROVIDERS) | set(ip._NON_BEARER_PROVIDERS)
+    for name in known:
+        if name in os.environ and os.environ[name].strip():
+            continue
+        val = (file_env.get(name) or "").strip()
+        if val:
+            os.environ[name] = val
+            added += 1
+    return added
+
+
+def _yn(value: bool) -> str:
+    return "[green]yes[/green]" if value else "[dim]no[/dim]"
+
+
+def _redact_token(token: str) -> str:
+    if len(token) < 16:
+        return token
+    return f"{token[:12]}…{token[-4:]}"
diff --git a/hermes_cli/runtime_provider.py b/hermes_cli/runtime_provider.py
index 7a17fc83943..58202c7ec19 100644
--- a/hermes_cli/runtime_provider.py
+++ b/hermes_cli/runtime_provider.py
@@ -862,10 +862,78 @@ def find_custom_provider_identity(base_url: str) -> Optional[str]:
     return None
 
 
+def find_custom_provider_identity_by_model(model: str) -> Optional[str]:
+    """Map a model id back to the ``custom:<name>`` entry that serves it.
+
+    Returns the ``custom:<normalized-name>`` slug of the first ``providers:``
+    / ``custom_providers:`` entry whose ``model`` / ``default_model`` matches,
+    or whose ``models`` catalog (dict or list shape) contains the id.
+    ``None`` when no entry serves the model.
+
+    Companion to :func:`find_custom_provider_identity` (URL reverse-lookup)
+    for the persistence paths where no base_url survived the round-trip: the
+    session row always stores the model name, and a custom endpoint's model
+    ids (e.g. an in-house SFT checkpoint) virtually never collide with
+    catalog models on built-in providers, so the model is the last durable
+    fact that can recover the entry identity.
+    """
+    target = str(model or "").strip().lower()
+    if not target:
+        return None
+    try:
+        config = load_config()
+    except Exception:
+        return None
+
+    def _entry_serves_model(entry: Dict[str, Any]) -> bool:
+        for key in ("model", "default_model"):
+            value = entry.get(key)
+            if isinstance(value, str) and value.strip().lower() == target:
+                return True
+        models = entry.get("models")
+        if isinstance(models, dict):
+            return any(
+                str(mid).strip().lower() == target for mid in models.keys()
+            )
+        if isinstance(models, list):
+            for item in models:
+                if isinstance(item, str) and item.strip().lower() == target:
+                    return True
+                if isinstance(item, dict):
+                    mid = item.get("id") or item.get("name")
+                    if isinstance(mid, str) and mid.strip().lower() == target:
+                        return True
+        return False
+
+    providers = config.get("providers")
+    if isinstance(providers, dict):
+        for ep_name, entry in providers.items():
+            if not isinstance(entry, dict):
+                continue
+            if _entry_serves_model(entry):
+                return f"custom:{_normalize_custom_provider_name(str(ep_name))}"
+
+    try:
+        custom_providers = get_compatible_custom_providers(config)
+    except Exception:
+        custom_providers = None
+    for entry in custom_providers or []:
+        if not isinstance(entry, dict):
+            continue
+        name = entry.get("name")
+        if not isinstance(name, str) or not name.strip():
+            continue
+        if _entry_serves_model(entry):
+            return f"custom:{_normalize_custom_provider_name(name)}"
+
+    return None
+
+
 def canonical_custom_identity(
     *,
     base_url: Optional[str] = None,
     config_provider: Optional[str] = None,
+    model: Optional[str] = None,
 ) -> Optional[str]:
     """Recover a routable ``custom:<name>`` identity for a bare custom provider.
 
@@ -877,17 +945,24 @@ def canonical_custom_identity(
 
     Any code path that persists or restores a session's provider override
     must run the resolved provider through this helper so a bare ``"custom"``
-    is upgraded back to its durable ``custom:<name>`` menu key. Two recovery
-    sources, in priority order:
+    is upgraded back to its durable ``custom:<name>`` menu key. Three
+    recovery sources, in priority order:
 
     1. ``base_url`` — reverse-lookup the entry that owns the endpoint URL
        (the one fact that always survives the persistence round-trip when a
        URL was recorded).
-    2. ``config_provider`` — the active ``config.model.provider`` (or its
-       ``provider``/``HERMES_INFERENCE_PROVIDER`` equivalent). When the agent
-       was built without a base_url on the override (the recurring
-       Desktop/TUI regression vector), the configured provider is the only
-       durable identity left, so fall back to it when it names a real entry.
+    2. ``model`` — reverse-lookup the entry that serves the session's model
+       (``model``/``default_model``/``models`` catalog). The session row
+       always stores the model name, so when no base_url survived (the
+       recurring Desktop/TUI regression vector) the model is the last
+       session-scoped fact that can recover the entry — and unlike the
+       config fallback below it stays correct after the user points their
+       global default at a different provider.
+    3. ``config_provider`` — the active ``config.model.provider`` (or its
+       ``provider``/``HERMES_INFERENCE_PROVIDER`` equivalent). When neither
+       a base_url nor a model recovered the entry, the configured provider
+       is the only durable identity left, so fall back to it when it names
+       a real entry.
 
     Returns ``custom:<name>`` when a routable identity is recovered, else
     ``None`` (caller keeps whatever it had — bare ``"custom"`` only as a last
@@ -899,7 +974,13 @@ def canonical_custom_identity(
         if identity:
             return identity
 
-    # 2. Fall back to the configured provider when it names a real entry.
+    # 2. Reverse-lookup by the session's model name.
+    if model:
+        identity = find_custom_provider_identity_by_model(model)
+        if identity:
+            return identity
+
+    # 3. Fall back to the configured provider when it names a real entry.
     candidate = str(config_provider or "").strip()
     if not candidate:
         try:
diff --git a/hermes_cli/secrets_cli.py b/hermes_cli/secrets_cli.py
index 12710a5ca31..53f5d5b4d1d 100644
--- a/hermes_cli/secrets_cli.py
+++ b/hermes_cli/secrets_cli.py
@@ -562,7 +562,7 @@ def _bws_version(binary: Path) -> str:
         res = subprocess.run(
             [str(binary), "--version"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=5,
         )
         if res.returncode == 0:
@@ -618,7 +618,7 @@ def _list_projects(
             [str(binary), "project", "list", "--output", "json"],
             env=env,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=15,
         )
     except (OSError, subprocess.TimeoutExpired) as exc:
diff --git a/hermes_cli/service_manager.py b/hermes_cli/service_manager.py
index 3cfa6730987..471c6a412cb 100644
--- a/hermes_cli/service_manager.py
+++ b/hermes_cli/service_manager.py
@@ -376,7 +376,7 @@ def _write_gateway_desired_state(name: str, desired_state: str) -> None:
         if not profile_dir.exists():
             return
         try:
-            data = json.loads(state_file.read_text()) if state_file.exists() else {}
+            data = json.loads(state_file.read_text(encoding="utf-8")) if state_file.exists() else {}
             if not isinstance(data, dict):
                 data = {}
         except (OSError, json.JSONDecodeError):
@@ -384,7 +384,7 @@ def _write_gateway_desired_state(name: str, desired_state: str) -> None:
         data["desired_state"] = desired_state
         data["updated_at"] = int(time.time())
         tmp = state_file.with_suffix(state_file.suffix + ".tmp")
-        tmp.write_text(json.dumps(data, separators=(",", ":")) + "\n")
+        tmp.write_text(json.dumps(data, separators=(",", ":")) + "\n", encoding="utf-8")
         tmp.replace(state_file)
     except OSError:
         return
@@ -838,7 +838,7 @@ class S6ServiceManager:
         try:
             subprocess.run(
                 [f"{_S6_BIN_DIR}/s6-svc", action_flag, str(service_dir)],
-                check=True, capture_output=True, text=True, timeout=5,
+                check=True, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             )
         except subprocess.CalledProcessError as exc:
             raise S6CommandError(
@@ -873,7 +873,7 @@ class S6ServiceManager:
         try:
             result = subprocess.run(
                 [f"{_S6_BIN_DIR}/s6-svstat", str(self.scandir / name)],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             )
         except (OSError, subprocess.SubprocessError):
             return None
@@ -926,7 +926,7 @@ class S6ServiceManager:
         import subprocess
         result = subprocess.run(
             [f"{_S6_BIN_DIR}/s6-svstat", str(self.scandir / name)],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
         )
         return result.returncode == 0 and "up " in result.stdout
 
@@ -987,22 +987,22 @@ class S6ServiceManager:
         tmp_dir.mkdir(parents=True)
 
         try:
-            (tmp_dir / "type").write_text("longrun\n")
+            (tmp_dir / "type").write_text("longrun\n", encoding="utf-8")
 
             run_script = self._render_run_script(profile, extra_env or {})
             run_path = tmp_dir / "run"
-            run_path.write_text(run_script)
+            run_path.write_text(run_script, encoding="utf-8")
             run_path.chmod(0o755)
 
             finish_path = tmp_dir / "finish"
-            finish_path.write_text(self._render_finish_script())
+            finish_path.write_text(self._render_finish_script(), encoding="utf-8")
             finish_path.chmod(0o755)
 
             # Persistent log rotation (OQ8-C).
             log_subdir = tmp_dir / "log"
             log_subdir.mkdir()
             log_run = log_subdir / "run"
-            log_run.write_text(self._render_log_run(profile))
+            log_run.write_text(self._render_log_run(profile), encoding="utf-8")
             log_run.chmod(0o755)
 
             # Pre-create the supervise/ skeleton with hermes ownership
@@ -1029,7 +1029,7 @@ class S6ServiceManager:
         # Trigger rescan so s6-svscan picks up the new service.
         result = subprocess.run(
             [f"{_S6_BIN_DIR}/s6-svscanctl", "-a", str(self.scandir)],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
         )
         if result.returncode != 0:
             # Clean up: rescan failed, leave the directory in place would
@@ -1066,13 +1066,13 @@ class S6ServiceManager:
         # Stop the service (best effort — service may already be down).
         subprocess.run(
             [f"{_S6_BIN_DIR}/s6-svc", "-d", str(svc_dir)],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             check=False,
         )
         # Wait for it to actually go down (up to 10s).
         subprocess.run(
             [f"{_S6_BIN_DIR}/s6-svwait", "-D", "-t", "10000", str(svc_dir)],
-            capture_output=True, text=True, timeout=15,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=15,
             check=False,
         )
 
@@ -1084,7 +1084,7 @@ class S6ServiceManager:
         # files inside the slot, so the upcoming rmtree doesn't race.
         subprocess.run(
             [f"{_S6_BIN_DIR}/s6-svscanctl", "-an", str(self.scandir)],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
             check=False,
         )
         # Give s6-svscan a moment to reap. There's no synchronous
diff --git a/hermes_cli/session_recovery.py b/hermes_cli/session_recovery.py
new file mode 100644
index 00000000000..f321b840370
--- /dev/null
+++ b/hermes_cli/session_recovery.py
@@ -0,0 +1,1387 @@
+"""Offline, non-destructive recovery for a damaged Hermes session database.
+
+The recovery path deliberately avoids in-place repair:
+
+* the supplied source database is never opened by SQLite;
+* the source file and any WAL/SHM/rollback-journal sidecars are copied into a
+  disposable working directory first;
+* canonical rows are copied into a newly initialized current-schema database;
+* derived FTS tables and migration bookkeeping are rebuilt, not copied; and
+* the recovered database is never installed over the active database.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sqlite3
+import tempfile
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from hermes_state import (
+    FTS_STORAGE_VERSION,
+    SCHEMA_VERSION,
+    SessionDB,
+    _db_opens_cleanly,
+)
+
+
+ProgressCallback = Callable[[dict[str, Any]], None]
+
+_CANONICAL_TABLES = (
+    "sessions",
+    "messages",
+    "session_model_usage",
+    "compression_locks",
+    "gateway_routing",
+    "async_delegations",
+)
+
+_TOPIC_TABLES = (
+    "telegram_dm_topic_mode",
+    "telegram_dm_topic_bindings",
+)
+
+# These values describe derived indexes or the schema that owns an optional
+# table. A fresh destination must generate them from its own current schema.
+_GENERATED_META_KEYS = frozenset({
+    "fts_storage_version",
+    "fts_optimize_available",
+    "fts_rebuild_high_water",
+    "fts_rebuild_progress",
+    "fts_cjk_stale",
+    "fts_cjk_rebuild_high_water",
+    "fts_cjk_rebuild_progress",
+    "telegram_dm_topic_schema_version",
+})
+
+_SIDECAR_SUFFIXES = ("", "-wal", "-shm", "-journal")
+_MINIMUM_SPACE_HEADROOM = 256 * 1024 * 1024
+_MAX_SALVAGE_RANGE_QUERIES = 10_000
+_MIN_SQLITE_ROWID = -(2**63)
+_MAX_SQLITE_ROWID = 2**63 - 1
+
+
+class SessionRecoveryError(RuntimeError):
+    """Base error for offline session recovery."""
+
+
+class SessionRecoverySafetyError(SessionRecoveryError):
+    """Raised before recovery when a path or overwrite guard fails."""
+
+
+class SessionRecoverySourceError(SessionRecoveryError):
+    """Raised when the source cannot provide the required canonical tables."""
+
+
+def _sidecar_path(db_path: Path, suffix: str) -> Path:
+    return db_path if not suffix else db_path.with_name(db_path.name + suffix)
+
+
+def _resolved_output_path(path: Path) -> Path:
+    """Resolve a not-yet-created output path without requiring it to exist."""
+
+    parent = path.expanduser().parent.resolve(strict=True)
+    return parent / path.name
+
+
+def _validate_paths(
+    source_path: Path,
+    output_path: Optional[Path] = None,
+    work_dir: Optional[Path] = None,
+) -> tuple[Path, Optional[Path], Path]:
+    source = source_path.expanduser().resolve(strict=True)
+    if not source.is_file():
+        raise SessionRecoverySafetyError(f"Source is not a file: {source}")
+
+    output: Optional[Path] = None
+    if output_path is not None:
+        output = _resolved_output_path(output_path)
+        protected = {
+            _sidecar_path(source, suffix).resolve(strict=False)
+            for suffix in _SIDECAR_SUFFIXES
+        }
+        if output.resolve(strict=False) in protected:
+            raise SessionRecoverySafetyError(
+                "The recovery output must not be the source database or one of "
+                "its journal sidecars."
+            )
+        for suffix in _SIDECAR_SUFFIXES:
+            candidate = _sidecar_path(output, suffix)
+            if os.path.lexists(candidate):
+                raise SessionRecoverySafetyError(
+                    f"Refusing to overwrite existing recovery output: {candidate}"
+                )
+
+    work_root = (
+        work_dir.expanduser().resolve(strict=True)
+        if work_dir is not None
+        else (output.parent if output is not None else source.parent)
+    )
+    if not work_root.is_dir():
+        raise SessionRecoverySafetyError(
+            f"Recovery work directory is not a directory: {work_root}"
+        )
+    return source, output, work_root
+
+
+def _source_fingerprint(source: Path) -> dict[str, dict[str, int]]:
+    fingerprint: dict[str, dict[str, int]] = {}
+    for suffix in _SIDECAR_SUFFIXES:
+        path = _sidecar_path(source, suffix)
+        if not path.exists():
+            continue
+        stat = path.stat()
+        fingerprint[suffix or "main"] = {
+            "size": stat.st_size,
+            "mtime_ns": stat.st_mtime_ns,
+        }
+    return fingerprint
+
+
+def _format_bytes(value: int) -> str:
+    units = ("B", "KiB", "MiB", "GiB", "TiB")
+    amount = float(value)
+    for unit in units:
+        if amount < 1024 or unit == units[-1]:
+            return f"{amount:.1f} {unit}"
+        amount /= 1024
+    return f"{value} B"
+
+
+def _same_filesystem(left: Path, right: Path) -> bool:
+    try:
+        return os.stat(left).st_dev == os.stat(right).st_dev
+    except OSError:
+        # Existing directories were already required by _validate_paths. This
+        # fallback is defensive for platforms with incomplete st_dev support.
+        return left.anchor.casefold() == right.anchor.casefold()
+
+
+def _disk_space_preflight(
+    source: Path,
+    work_root: Path,
+    output_parent: Optional[Path],
+) -> dict[str, Any]:
+    """Require space for the disposable bundle, output, and safety headroom."""
+
+    bundle_bytes = sum(
+        _sidecar_path(source, suffix).stat().st_size
+        for suffix in _SIDECAR_SUFFIXES
+        if _sidecar_path(source, suffix).exists()
+    )
+    # The v23 external-content rebuild is normally substantially smaller than
+    # a legacy database, but using the complete source bundle as the estimate
+    # avoids betting the user's disk on that expectation.
+    output_allowance = bundle_bytes if output_parent is not None else 0
+    headroom = max(
+        _MINIMUM_SPACE_HEADROOM,
+        int((bundle_bytes + output_allowance) * 0.05),
+    )
+
+    work_free = int(shutil.disk_usage(work_root).free)
+    report: dict[str, Any] = {
+        "source_bundle_bytes": bundle_bytes,
+        "estimated_output_bytes": output_allowance,
+        "headroom_bytes": headroom,
+        "work_dir": str(work_root),
+        "work_dir_free_bytes": work_free,
+    }
+
+    if output_parent is None or _same_filesystem(work_root, output_parent):
+        required = bundle_bytes + output_allowance + headroom
+        report["shared_filesystem"] = True
+        report["work_dir_required_bytes"] = required
+        if work_free < required:
+            raise SessionRecoverySafetyError(
+                "Not enough free disk space for a safe recovery copy: "
+                f"{_format_bytes(work_free)} available at {work_root}, "
+                f"{_format_bytes(required)} required "
+                f"({_format_bytes(bundle_bytes)} source bundle + "
+                f"{_format_bytes(output_allowance)} output allowance + "
+                f"{_format_bytes(headroom)} headroom). Use --work-dir or "
+                "--output on a filesystem with more free space."
+            )
+        return report
+
+    output_free = int(shutil.disk_usage(output_parent).free)
+    work_required = bundle_bytes + headroom
+    output_required = output_allowance + headroom
+    report.update({
+        "shared_filesystem": False,
+        "work_dir_required_bytes": work_required,
+        "output_dir": str(output_parent),
+        "output_dir_free_bytes": output_free,
+        "output_dir_required_bytes": output_required,
+    })
+    shortages: list[str] = []
+    if work_free < work_required:
+        shortages.append(
+            f"{work_root}: {_format_bytes(work_free)} available, "
+            f"{_format_bytes(work_required)} required"
+        )
+    if output_free < output_required:
+        shortages.append(
+            f"{output_parent}: {_format_bytes(output_free)} available, "
+            f"{_format_bytes(output_required)} required"
+        )
+    if shortages:
+        raise SessionRecoverySafetyError(
+            "Not enough free disk space for safe recovery: "
+            + "; ".join(shortages)
+            + ". Choose work/output filesystems with more free space."
+        )
+    return report
+
+
+def _copy_source_bundle(source: Path, snapshot_dir: Path) -> tuple[Path, list[str]]:
+    """Copy the source DB bundle aside so SQLite never opens the original.
+
+    The whole copy runs inside ``offline_file_access``, which holds the
+    connection-lifecycle lock for its duration. Checking for a live connection
+    and *then* copying would be a check/use race: a connection could open in
+    that window, and the copy's ``close()`` would cancel its POSIX advisory
+    locks -- the failure class ``hermes_cli.sqlite_safe_read`` exists to
+    prevent (see #71724). Holding the lock means no connection can appear
+    mid-copy, across the main file and every sidecar.
+
+    Recovery normally runs as its own short-lived CLI process against an
+    offline/quarantined file, so the refusal should never fire; the guard
+    keeps this path consistent with ``hermes_state._backup_db_file``.
+    """
+    from hermes_cli.sqlite_safe_read import LiveConnectionError, offline_file_access
+
+    snapshot_source = snapshot_dir / source.name
+    copied: list[str] = []
+    try:
+        with offline_file_access(source, what="snapshot"):
+            for suffix in _SIDECAR_SUFFIXES:
+                source_part = _sidecar_path(source, suffix)
+                if not source_part.exists():
+                    continue
+                destination_part = _sidecar_path(snapshot_source, suffix)
+                shutil.copy2(source_part, destination_part)
+                copied.append(destination_part.name)
+    except LiveConnectionError as exc:
+        raise SessionRecoverySafetyError(str(exc)) from exc
+    return snapshot_source, copied
+
+
+def _table_columns(conn: sqlite3.Connection, table: str) -> list[str]:
+    return [str(row[1]) for row in conn.execute(f'PRAGMA table_info("{table}")')]
+
+
+def _table_inventory(
+    conn: sqlite3.Connection,
+    table: str,
+) -> dict[str, Any]:
+    result: dict[str, Any] = {"available": False, "columns": [], "rows": None}
+    try:
+        columns = _table_columns(conn, table)
+        if not columns:
+            return result
+        result["available"] = True
+        result["columns"] = columns
+        result["rows"] = int(
+            conn.execute(f'SELECT COUNT(*) FROM "{table}"').fetchone()[0]
+        )
+    except sqlite3.DatabaseError as exc:
+        result["error"] = str(exc)
+    return result
+
+
+def _inspect_connection(conn: sqlite3.Connection) -> dict[str, Any]:
+    conn.execute("PRAGMA writable_schema=ON")
+    report: dict[str, Any] = {"tables": {}, "errors": [], "warnings": []}
+    try:
+        row = conn.execute("PRAGMA journal_mode").fetchone()
+        report["journal_mode"] = str(row[0]).lower() if row else None
+    except sqlite3.DatabaseError as exc:
+        report["journal_mode"] = None
+        # Journal metadata is useful context but not canonical session data.
+        # A damaged journal pragma must not block rows that are still readable.
+        report["warnings"].append(f"journal mode: {exc}")
+
+    for table in (*_CANONICAL_TABLES, "state_meta", *_TOPIC_TABLES):
+        report["tables"][table] = _table_inventory(conn, table)
+
+    for required in ("sessions", "messages"):
+        table_report = report["tables"][required]
+        if not table_report.get("available") or table_report.get("rows") is None:
+            report["errors"].append(
+                f"required table {required} is not completely readable"
+            )
+    report["recoverable"] = not report["errors"]
+    return report
+
+
+def _snapshot_and_inspect(
+    source: Path,
+    work_root: Path,
+) -> tuple[tempfile.TemporaryDirectory[str], Path, dict[str, Any]]:
+    before = _source_fingerprint(source)
+    temp_dir = tempfile.TemporaryDirectory(
+        prefix="hermes-session-recovery-",
+        dir=str(work_root),
+    )
+    snapshot_dir = Path(temp_dir.name)
+    try:
+        snapshot_source, copied = _copy_source_bundle(source, snapshot_dir)
+        after = _source_fingerprint(source)
+        if before != after:
+            raise SessionRecoverySafetyError(
+                "The source database bundle changed while it was being copied. "
+                "Stop every Hermes process using this profile and retry."
+            )
+
+        conn = sqlite3.connect(
+            str(snapshot_source),
+            isolation_level=None,
+            timeout=1.0,
+        )
+        try:
+            inspection = _inspect_connection(conn)
+        finally:
+            conn.close()
+        inspection["source_bundle"] = copied
+        inspection["source_fingerprint"] = before
+        return temp_dir, snapshot_source, inspection
+    except BaseException:
+        temp_dir.cleanup()
+        raise
+
+
+def inspect_session_database(
+    source_path: Path,
+    *,
+    work_dir: Optional[Path] = None,
+) -> dict[str, Any]:
+    """Inspect canonical table readability without opening the source itself."""
+
+    source, _, work_root = _validate_paths(source_path, work_dir=work_dir)
+    disk_space = _disk_space_preflight(source, work_root, None)
+    temp_dir, _, inspection = _snapshot_and_inspect(source, work_root)
+    try:
+        return {
+            "operation": "inspect",
+            "source": str(source),
+            "disk_space": disk_space,
+            **inspection,
+            "source_unchanged": _source_fingerprint(source)
+            == inspection["source_fingerprint"],
+        }
+    finally:
+        temp_dir.cleanup()
+
+
+def _copy_table(
+    source: sqlite3.Connection,
+    destination: sqlite3.Connection,
+    table: str,
+    *,
+    chunk_size: int,
+    progress_cb: Optional[ProgressCallback],
+    source_rows: Optional[int],
+) -> dict[str, Any]:
+    source_columns = _table_columns(source, table)
+    destination_columns = _table_columns(destination, table)
+    columns = [column for column in destination_columns if column in source_columns]
+    result: dict[str, Any] = {
+        "source_rows": source_rows,
+        "copied_rows": 0,
+        "columns": columns,
+    }
+    if not source_columns:
+        result["status"] = "missing"
+        return result
+    if not columns:
+        result["status"] = "failed"
+        result["error"] = "source and destination have no compatible columns"
+        return result
+
+    quoted = ", ".join(f'"{column}"' for column in columns)
+    placeholders = ", ".join("?" for _ in columns)
+    select_sql = f'SELECT {quoted} FROM "{table}"'
+    insert_prefix = "INSERT OR REPLACE" if table == "state_meta" else "INSERT"
+    insert_sql = f'{insert_prefix} INTO "{table}" ({quoted}) VALUES ({placeholders})'
+
+    try:
+        cursor = source.execute(select_sql)
+        while True:
+            rows = cursor.fetchmany(chunk_size)
+            if not rows:
+                break
+            destination.execute("BEGIN IMMEDIATE")
+            try:
+                destination.executemany(insert_sql, rows)
+                destination.execute("COMMIT")
+            except BaseException:
+                destination.execute("ROLLBACK")
+                raise
+            result["copied_rows"] += len(rows)
+            if progress_cb is not None:
+                progress_cb({
+                    "table": table,
+                    "copied_rows": result["copied_rows"],
+                    "source_rows": source_rows,
+                })
+    except sqlite3.DatabaseError as exc:
+        result["status"] = "partial" if result["copied_rows"] else "failed"
+        result["error"] = str(exc)
+        return result
+
+    result["status"] = (
+        "complete"
+        if source_rows is None or result["copied_rows"] == source_rows
+        else "partial"
+    )
+    if result["status"] == "partial":
+        result["error"] = (
+            f"copied {result['copied_rows']} of {source_rows} readable rows"
+        )
+    return result
+
+
+def _append_skipped_range(
+    ranges: list[dict[str, Any]],
+    low: int,
+    high: int,
+    error: str,
+) -> None:
+    """Record skipped rowid ranges without producing one entry per row."""
+
+    if (
+        ranges
+        and ranges[-1]["high"] + 1 == low
+        and ranges[-1]["error"] == error
+    ):
+        ranges[-1]["high"] = high
+        return
+    ranges.append({"low": low, "high": high, "error": error})
+
+
+def _salvage_rowid_bounds(
+    source: sqlite3.Connection,
+    table: str,
+) -> dict[str, Any]:
+    """Find the readable rowid edges without scanning the complete table."""
+
+    result: dict[str, Any] = {"errors": [], "fallback_edges": []}
+    rows: dict[str, Optional[int]] = {"low": None, "high": None}
+    directions = (("low", "ASC"), ("high", "DESC"))
+    for edge, direction in directions:
+        try:
+            row = source.execute(
+                f'SELECT rowid FROM "{table}" ORDER BY rowid {direction} LIMIT 1'
+            ).fetchone()
+            if row is not None:
+                rows[edge] = int(row[0])
+        except sqlite3.DatabaseError as exc:
+            result["errors"].append(f"{edge} rowid: {exc}")
+
+    if rows["low"] is None and rows["high"] is None and not result["errors"]:
+        result["empty"] = True
+        return result
+    if rows["low"] is None and rows["high"] is None:
+        result["unavailable"] = True
+        return result
+
+    # A damaged edge can prevent one of the ordered probes from completing.
+    # Keep the other readable edge and bound the missing side by SQLite's
+    # rowid domain. Range bisection can then approach the surviving data
+    # without assuming that user-created databases contain only positive IDs.
+    if rows["low"] is None:
+        rows["low"] = _MIN_SQLITE_ROWID
+        result["fallback_edges"].append("low")
+    if rows["high"] is None:
+        rows["high"] = _MAX_SQLITE_ROWID
+        result["fallback_edges"].append("high")
+
+    result["low"] = rows["low"]
+    result["high"] = rows["high"]
+    return result
+
+
+def _copy_table_salvage(
+    source: sqlite3.Connection,
+    destination: sqlite3.Connection,
+    table: str,
+    *,
+    chunk_size: int,
+    progress_cb: Optional[ProgressCallback],
+    source_rows: Optional[int],
+    insert_prefix: str = "INSERT",
+    row_filter: Optional[
+        Callable[[tuple[Any, ...], tuple[str, ...]], bool]
+    ] = None,
+) -> dict[str, Any]:
+    """Best-effort rowid-range copy that continues past damaged source pages."""
+
+    source_columns = _table_columns(source, table)
+    destination_columns = _table_columns(destination, table)
+    columns = [column for column in destination_columns if column in source_columns]
+    result: dict[str, Any] = {
+        "mode": "rowid_range_salvage",
+        "source_rows": source_rows,
+        "copied_rows": 0,
+        "excluded_rows": 0,
+        "columns": columns,
+        "range_queries": 0,
+        "skipped_rowid_ranges": [],
+    }
+    if not source_columns:
+        result["status"] = "missing"
+        return result
+    if not columns:
+        result["status"] = "failed"
+        result["error"] = "source and destination have no compatible columns"
+        return result
+
+    bounds = _salvage_rowid_bounds(source, table)
+    result["rowid_bounds"] = bounds
+    if bounds.get("empty"):
+        result["status"] = "complete"
+        return result
+    if bounds.get("low") is None or bounds.get("high") is None:
+        result["status"] = "failed"
+        details = "; ".join(bounds.get("errors") or [])
+        result["error"] = "could not determine a rowid range for salvage"
+        if details:
+            result["error"] += f": {details}"
+        return result
+
+    quoted = ", ".join(f'"{column}"' for column in columns)
+    placeholders = ", ".join("?" for _ in columns)
+    select_sql = (
+        f'SELECT rowid, {quoted} FROM "{table}" '
+        "WHERE rowid BETWEEN ? AND ? ORDER BY rowid"
+    )
+    insert_sql = (
+        f'{insert_prefix} INTO "{table}" ({quoted}) VALUES ({placeholders})'
+    )
+    column_names = tuple(columns)
+    stopped_at_query_limit = False
+
+    def copy_range(low: int, high: int) -> None:
+        nonlocal stopped_at_query_limit
+        if low > high:
+            return
+        if result["range_queries"] >= _MAX_SALVAGE_RANGE_QUERIES:
+            stopped_at_query_limit = True
+            _append_skipped_range(
+                result["skipped_rowid_ranges"],
+                low,
+                high,
+                "salvage range query limit reached",
+            )
+            return
+
+        result["range_queries"] += 1
+        last_committed_rowid: Optional[int] = None
+        try:
+            cursor = source.execute(select_sql, (low, high))
+            while True:
+                fetched = cursor.fetchmany(chunk_size)
+                if not fetched:
+                    return
+
+                values = [tuple(row[1:]) for row in fetched]
+                if row_filter is not None:
+                    included = [
+                        row for row in values if row_filter(row, column_names)
+                    ]
+                    excluded_count = len(values) - len(included)
+                else:
+                    included = values
+                    excluded_count = 0
+
+                if included:
+                    destination.execute("BEGIN IMMEDIATE")
+                    try:
+                        destination.executemany(insert_sql, included)
+                        destination.execute("COMMIT")
+                    except BaseException:
+                        destination.execute("ROLLBACK")
+                        raise
+
+                result["copied_rows"] += len(included)
+                result["excluded_rows"] += excluded_count
+                last_committed_rowid = int(fetched[-1][0])
+                if progress_cb is not None:
+                    progress_cb({
+                        "table": table,
+                        "copied_rows": result["copied_rows"],
+                        "source_rows": source_rows,
+                        "skipped_ranges": len(result["skipped_rowid_ranges"]),
+                    })
+        except sqlite3.DatabaseError as exc:
+            retry_low = (
+                last_committed_rowid + 1
+                if last_committed_rowid is not None
+                else low
+            )
+            if retry_low > high:
+                return
+            if retry_low == high:
+                _append_skipped_range(
+                    result["skipped_rowid_ranges"],
+                    retry_low,
+                    high,
+                    str(exc),
+                )
+                return
+            midpoint = retry_low + (high - retry_low) // 2
+            copy_range(retry_low, midpoint)
+            copy_range(midpoint + 1, high)
+
+    copy_range(int(bounds["low"]), int(bounds["high"]))
+    skipped_ranges = result["skipped_rowid_ranges"]
+    result["skipped_rowid_span"] = sum(
+        item["high"] - item["low"] + 1 for item in skipped_ranges
+    )
+    result["query_limit_reached"] = stopped_at_query_limit
+
+    if skipped_ranges:
+        result["status"] = "partial" if result["copied_rows"] else "failed"
+        result["error"] = (
+            f"{len(skipped_ranges)} rowid range(s) skipped"
+        )
+    elif (
+        source_rows is not None
+        and result["copied_rows"] + result["excluded_rows"] != source_rows
+    ):
+        result["status"] = "partial"
+        result["error"] = (
+            f"copied {result['copied_rows']} and excluded "
+            f"{result['excluded_rows']} of {source_rows} source rows"
+        )
+    else:
+        result["status"] = "complete"
+    return result
+
+
+def _copy_state_meta(
+    source: sqlite3.Connection,
+    destination: sqlite3.Connection,
+    *,
+    chunk_size: int,
+    progress_cb: Optional[ProgressCallback],
+    source_rows: Optional[int],
+) -> dict[str, Any]:
+    source_columns = _table_columns(source, "state_meta")
+    destination_columns = _table_columns(destination, "state_meta")
+    result: dict[str, Any] = {
+        "source_meta_rows": source_rows,
+        "copied_rows": 0,
+        "columns": ["key", "value"],
+        "excluded_keys": sorted(_GENERATED_META_KEYS),
+    }
+    if not {"key", "value"}.issubset(source_columns):
+        result["status"] = "missing"
+        return result
+    if not {"key", "value"}.issubset(destination_columns):
+        result["status"] = "failed"
+        result["error"] = "destination state_meta schema is incomplete"
+        return result
+
+    placeholders = ", ".join("?" for _ in _GENERATED_META_KEYS)
+    filtered_source_rows: Optional[int] = None
+    try:
+        filtered_source_rows = int(
+            source.execute(
+                f"SELECT COUNT(*) FROM state_meta WHERE key NOT IN ({placeholders})",
+                tuple(_GENERATED_META_KEYS),
+            ).fetchone()[0]
+        )
+    except sqlite3.DatabaseError:
+        # The copy loop below will return the concrete read error.
+        pass
+
+    try:
+        cursor = source.execute(
+            f"SELECT key, value FROM state_meta WHERE key NOT IN ({placeholders})",
+            tuple(_GENERATED_META_KEYS),
+        )
+        while True:
+            rows = cursor.fetchmany(chunk_size)
+            if not rows:
+                break
+            destination.execute("BEGIN IMMEDIATE")
+            try:
+                destination.executemany(
+                    "INSERT OR REPLACE INTO state_meta(key, value) VALUES (?, ?)",
+                    rows,
+                )
+                destination.execute("COMMIT")
+            except BaseException:
+                destination.execute("ROLLBACK")
+                raise
+            result["copied_rows"] += len(rows)
+            if progress_cb is not None:
+                progress_cb({
+                    "table": "state_meta",
+                    "copied_rows": result["copied_rows"],
+                    "source_rows": filtered_source_rows,
+                })
+    except sqlite3.DatabaseError as exc:
+        result["status"] = "partial" if result["copied_rows"] else "failed"
+        result["error"] = str(exc)
+        return result
+
+    result["status"] = (
+        "complete"
+        if filtered_source_rows is None or result["copied_rows"] == filtered_source_rows
+        else "partial"
+    )
+    if result["status"] == "partial":
+        result["error"] = (
+            f"copied {result['copied_rows']} of {filtered_source_rows} readable rows"
+        )
+    return result
+
+
+def _copy_state_meta_salvage(
+    source: sqlite3.Connection,
+    destination: sqlite3.Connection,
+    *,
+    chunk_size: int,
+    progress_cb: Optional[ProgressCallback],
+    source_rows: Optional[int],
+) -> dict[str, Any]:
+    """Salvage readable user metadata while regenerating derived FTS state.
+
+    Requires both ``key`` and ``value``, matching the non-partial
+    :func:`_copy_state_meta`. A damaged ``state_meta`` can retain one column
+    and lose the other; without this check a missing ``key`` raised
+    ``ValueError`` from ``columns.index("key")`` and aborted the entire
+    partial recovery, and a missing ``value`` would have copied key-only rows
+    while reporting the table complete.
+
+    Status matters here. An unusable-but-PRESENT table reports ``failed``, not
+    ``missing``: verification only escalates ``failed``/``partial`` into a
+    warning + ``loss_detected``, so reporting ``missing`` would silently drop
+    real metadata and still claim ``complete=True``. ``missing`` is reserved
+    for a table that genuinely is not there. Either way ``state_meta`` is
+    optional, so ``--allow-partial`` records the loss and carries on
+    recovering sessions and messages.
+    """
+    source_columns = _table_columns(source, "state_meta")
+    destination_columns = _table_columns(destination, "state_meta")
+    if not source_columns:
+        # Genuinely absent from the source — nothing was lost.
+        return {
+            "mode": "rowid_range_salvage",
+            "source_meta_rows": source_rows,
+            "copied_rows": 0,
+            "columns": ["key", "value"],
+            "excluded_keys": sorted(_GENERATED_META_KEYS),
+            "status": "missing",
+        }
+    if not {"key", "value"}.issubset(source_columns):
+        # Present but unusable: this IS data loss and must be reported.
+        return {
+            "mode": "rowid_range_salvage",
+            "source_meta_rows": source_rows,
+            "copied_rows": 0,
+            "columns": ["key", "value"],
+            "excluded_keys": sorted(_GENERATED_META_KEYS),
+            "status": "failed",
+            "error": (
+                "source state_meta exists but is missing the key/value "
+                f"columns (found: {', '.join(source_columns) or 'none'})"
+            ),
+        }
+    if not {"key", "value"}.issubset(destination_columns):
+        return {
+            "mode": "rowid_range_salvage",
+            "source_meta_rows": source_rows,
+            "copied_rows": 0,
+            "columns": ["key", "value"],
+            "excluded_keys": sorted(_GENERATED_META_KEYS),
+            "status": "failed",
+            "error": "destination state_meta schema is incomplete",
+        }
+
+    def keep_user_meta(
+        row: tuple[Any, ...],
+        columns: tuple[str, ...],
+    ) -> bool:
+        return str(row[columns.index("key")]) not in _GENERATED_META_KEYS
+
+    result = _copy_table_salvage(
+        source,
+        destination,
+        "state_meta",
+        chunk_size=chunk_size,
+        progress_cb=progress_cb,
+        source_rows=source_rows,
+        insert_prefix="INSERT OR REPLACE",
+        row_filter=keep_user_meta,
+    )
+    result["source_meta_rows"] = result.pop("source_rows")
+    result["excluded_keys"] = sorted(_GENERATED_META_KEYS)
+    return result
+
+
+def _reconstruct_missing_sessions(
+    destination: sqlite3.Connection,
+) -> dict[str, Any]:
+    """Recreate placeholder session rows for salvaged orphaned messages.
+
+    When the ``sessions`` b-tree is damaged worse than ``messages``, salvage
+    can recover the conversation text while recovering few or none of the
+    session rows that own it. Deleting those messages as "orphans" throws away
+    the only readable copy of the user's data — the exact opposite of what
+    ``--allow-partial`` is for. A real report (July 2026) copied 20,817 of
+    20,824 messages and then removed every one of them, producing an output
+    with 0 sessions and 0 messages.
+
+    Instead, synthesize a minimal session row per orphaned ``session_id``
+    (only ``id``/``source``/``started_at`` are NOT NULL) so the messages stay
+    reachable and foreign keys hold. ``started_at`` is taken from the earliest
+    surviving message so ordering stays sane. Rows are marked with
+    ``source='recovered'`` and a ``title`` that says so, because a fabricated
+    session must never be mistaken for an original.
+    """
+    result: dict[str, Any] = {"sessions_reconstructed": 0, "messages_retained": 0}
+    if not _table_columns(destination, "sessions"):
+        return result
+    if not _table_columns(destination, "messages"):
+        return result
+
+    orphaned = destination.execute(
+        "SELECT m.session_id, MIN(m.timestamp), COUNT(*) "
+        "FROM messages AS m "
+        "WHERE m.session_id IS NOT NULL AND NOT EXISTS ("
+        "SELECT 1 FROM sessions WHERE sessions.id = m.session_id) "
+        "GROUP BY m.session_id"
+    ).fetchall()
+    if not orphaned:
+        return result
+
+    title_sequence = 1
+    for session_id, first_timestamp, message_count in orphaned:
+        started_at = float(first_timestamp) if first_timestamp is not None else 0.0
+        while True:
+            title = (
+                f"[recovered {title_sequence}] "
+                "session metadata was unreadable"
+            )
+            title_sequence += 1
+            if (
+                destination.execute(
+                    "SELECT 1 FROM sessions WHERE title = ? LIMIT 1",
+                    (title,),
+                ).fetchone()
+                is None
+            ):
+                break
+
+        cursor = destination.execute(
+            "INSERT INTO sessions "
+            "(id, source, started_at, title, message_count) "
+            "VALUES (?, 'recovered', ?, ?, ?)",
+            (
+                session_id,
+                started_at,
+                title,
+                int(message_count),
+            ),
+        )
+        if cursor.rowcount != 1:
+            raise sqlite3.IntegrityError(
+                f"failed to reconstruct missing session {session_id!r}"
+            )
+        result["sessions_reconstructed"] += 1
+        result["messages_retained"] += int(message_count)
+    return result
+
+
+def _cleanup_partial_orphans(
+    destination: sqlite3.Connection,
+) -> dict[str, Any]:
+    """Reconcile references to sessions that could not be salvaged.
+
+    Messages are never discarded for lack of a session row: their owning
+    session is reconstructed as a placeholder first (see
+    :func:`_reconstruct_missing_sessions`). Only rows that remain orphaned
+    after that — and rows in tables carrying no recoverable user content —
+    are removed.
+    """
+
+    result: dict[str, Any] = {
+        "sessions_parent_cleared": 0,
+        "sessions_reconstructed": 0,
+        "messages_retained": 0,
+        "messages_removed": 0,
+        "session_model_usage_removed": 0,
+        "compression_locks_removed": 0,
+        "telegram_dm_topic_bindings_removed": 0,
+    }
+    destination.execute("BEGIN IMMEDIATE")
+    try:
+        # Rebuild owners BEFORE any orphan deletion so salvaged conversation
+        # text is never dropped for want of a session row.
+        rebuilt = _reconstruct_missing_sessions(destination)
+        result["sessions_reconstructed"] = rebuilt["sessions_reconstructed"]
+        result["messages_retained"] = rebuilt["messages_retained"]
+
+        parent_count = int(
+            destination.execute(
+                "SELECT COUNT(*) FROM sessions AS child "
+                "WHERE child.parent_session_id IS NOT NULL "
+                "AND NOT EXISTS ("
+                "SELECT 1 FROM sessions AS parent "
+                "WHERE parent.id = child.parent_session_id)"
+            ).fetchone()[0]
+        )
+        if parent_count:
+            destination.execute(
+                "UPDATE sessions SET parent_session_id = NULL "
+                "WHERE parent_session_id IS NOT NULL "
+                "AND NOT EXISTS ("
+                "SELECT 1 FROM sessions AS parent "
+                "WHERE parent.id = sessions.parent_session_id)"
+            )
+        result["sessions_parent_cleared"] = parent_count
+
+        dependent_tables = (
+            ("messages", "messages_removed"),
+            ("session_model_usage", "session_model_usage_removed"),
+            ("compression_locks", "compression_locks_removed"),
+            (
+                "telegram_dm_topic_bindings",
+                "telegram_dm_topic_bindings_removed",
+            ),
+        )
+        for table, report_key in dependent_tables:
+            if not _table_columns(destination, table):
+                continue
+            orphan_count = int(
+                destination.execute(
+                    f'SELECT COUNT(*) FROM "{table}" AS dependent '
+                    "WHERE NOT EXISTS ("
+                    "SELECT 1 FROM sessions "
+                    "WHERE sessions.id = dependent.session_id)"
+                ).fetchone()[0]
+            )
+            if orphan_count:
+                destination.execute(
+                    f'DELETE FROM "{table}" '
+                    "WHERE NOT EXISTS ("
+                    "SELECT 1 FROM sessions "
+                    f'WHERE sessions.id = "{table}".session_id)'
+                )
+            result[report_key] = orphan_count
+        destination.execute("COMMIT")
+    except BaseException:
+        destination.execute("ROLLBACK")
+        raise
+    # Only destructive/relinking actions belong in this total. The
+    # reconstruction counters describe data RETAINED, so summing them here
+    # would report saving the user's messages as if it were losing them.
+    result["total_removed_or_relinked"] = (
+        int(result["sessions_parent_cleared"])
+        + int(result["messages_removed"])
+        + int(result["session_model_usage_removed"])
+        + int(result["compression_locks_removed"])
+        + int(result["telegram_dm_topic_bindings_removed"])
+    )
+    return result
+
+
+def _verify_recovered_database(
+    output: Path,
+    *,
+    expected_counts: dict[str, Optional[int]],
+    copy_report: dict[str, dict[str, Any]],
+    allow_partial: bool = False,
+    orphan_cleanup: Optional[dict[str, Any]] = None,
+) -> dict[str, Any]:
+    verification: dict[str, Any] = {
+        "errors": [],
+        "warnings": [],
+        "loss_detected": False,
+    }
+
+    open_error = _db_opens_cleanly(output)
+    verification["opens_cleanly"] = open_error is None
+    if open_error is not None:
+        verification["errors"].append(f"database health probe: {open_error}")
+
+    conn = sqlite3.connect(str(output), isolation_level=None)
+    try:
+        integrity_rows = [
+            str(row[0]) for row in conn.execute("PRAGMA integrity_check").fetchall()
+        ]
+        verification["integrity_check"] = integrity_rows
+        if integrity_rows != ["ok"]:
+            verification["errors"].append(
+                "PRAGMA integrity_check did not return exactly 'ok'"
+            )
+
+        foreign_key_rows = [
+            list(row) for row in conn.execute("PRAGMA foreign_key_check").fetchall()
+        ]
+        verification["foreign_key_check"] = foreign_key_rows
+        if foreign_key_rows:
+            verification["errors"].append("foreign key violations remain")
+
+        journal_row = conn.execute("PRAGMA journal_mode").fetchone()
+        verification["journal_mode"] = (
+            str(journal_row[0]).lower() if journal_row else None
+        )
+
+        schema_row = conn.execute(
+            "SELECT version FROM schema_version LIMIT 1"
+        ).fetchone()
+        verification["schema_version"] = int(schema_row[0]) if schema_row else None
+        if verification["schema_version"] != SCHEMA_VERSION:
+            verification["errors"].append(
+                f"schema version is {verification['schema_version']}, "
+                f"expected {SCHEMA_VERSION}"
+            )
+
+        meta = {
+            str(row[0]): row[1]
+            for row in conn.execute(
+                "SELECT key, value FROM state_meta WHERE key LIKE 'fts_%'"
+            ).fetchall()
+        }
+        verification["fts_meta"] = meta
+        if meta.get("fts_storage_version") != str(FTS_STORAGE_VERSION):
+            verification["errors"].append(
+                "fresh FTS storage version was not established"
+            )
+        pending_keys = sorted(
+            key
+            for key in (
+                "fts_optimize_available",
+                "fts_rebuild_high_water",
+                "fts_rebuild_progress",
+                "fts_cjk_stale",
+                "fts_cjk_rebuild_high_water",
+                "fts_cjk_rebuild_progress",
+            )
+            if key in meta
+        )
+        verification["pending_fts_keys"] = pending_keys
+        if pending_keys:
+            verification["errors"].append(
+                "derived FTS transition markers remain in the recovered database"
+            )
+
+        counts: dict[str, int] = {}
+        for table in (*_CANONICAL_TABLES, "state_meta", *_TOPIC_TABLES):
+            columns = _table_columns(conn, table)
+            if columns:
+                counts[table] = int(
+                    conn.execute(f'SELECT COUNT(*) FROM "{table}"').fetchone()[0]
+                )
+        verification["table_counts"] = counts
+
+        for table in ("sessions", "messages"):
+            expected = expected_counts.get(table)
+            if expected is not None and counts.get(table) != expected:
+                message = (
+                    f"{table} count is {counts.get(table)}, expected {expected}"
+                )
+                if allow_partial:
+                    verification["warnings"].append(message)
+                    verification["loss_detected"] = True
+                else:
+                    verification["errors"].append(message)
+
+        for table, table_report in copy_report.items():
+            status = table_report.get("status")
+            if status not in {"failed", "partial"}:
+                continue
+            message = f"{table} copy status is {status}"
+            if allow_partial and (
+                status == "partial" or table not in {"sessions", "messages"}
+            ):
+                verification["warnings"].append(message)
+                verification["loss_detected"] = True
+            else:
+                verification["errors"].append(message)
+
+        if orphan_cleanup:
+            orphan_count = int(
+                orphan_cleanup.get("total_removed_or_relinked") or 0
+            )
+            if orphan_count:
+                verification["warnings"].append(
+                    f"{orphan_count} orphaned reference(s) were removed or relinked"
+                )
+                verification["loss_detected"] = True
+            rebuilt_sessions = int(
+                orphan_cleanup.get("sessions_reconstructed") or 0
+            )
+            if rebuilt_sessions:
+                retained = int(orphan_cleanup.get("messages_retained") or 0)
+                # Not a clean recovery: the conversation text survived but its
+                # session metadata did not, so these rows are placeholders.
+                verification["warnings"].append(
+                    f"{rebuilt_sessions} session(s) could not be salvaged and "
+                    f"were reconstructed as placeholders to retain "
+                    f"{retained} message(s); their metadata (title, model, "
+                    "timestamps, cost) is lost"
+                )
+                verification["loss_detected"] = True
+
+        fts_checks: dict[str, str] = {}
+        for table in ("messages_fts", "messages_fts_trigram", "messages_fts_cjk"):
+            if not _table_columns(conn, table):
+                continue
+            try:
+                conn.execute(
+                    f'INSERT INTO "{table}" ("{table}") VALUES (\'integrity-check\')'
+                )
+                conn.execute(
+                    f'SELECT 1 FROM "{table}" WHERE "{table}" MATCH \'""\' LIMIT 1'
+                ).fetchone()
+                fts_checks[table] = "ok"
+            except sqlite3.DatabaseError as exc:
+                fts_checks[table] = str(exc)
+                verification["errors"].append(f"{table} integrity check failed: {exc}")
+        verification["fts_checks"] = fts_checks
+    except sqlite3.DatabaseError as exc:
+        verification["errors"].append(f"verification query failed: {exc}")
+    finally:
+        conn.close()
+
+    verification["healthy"] = not verification["errors"]
+    verification["complete"] = bool(
+        verification["healthy"] and not verification["loss_detected"]
+    )
+    return verification
+
+
+def _finalize_derived_metadata(destination: sqlite3.Connection) -> dict[str, Any]:
+    """Stamp only metadata that the newly created destination actually owns."""
+
+    fts_tables = {
+        str(row[0])
+        for row in destination.execute(
+            "SELECT name FROM sqlite_master "
+            "WHERE type='table' AND name IN ('messages_fts', 'messages_fts_trigram')"
+        ).fetchall()
+    }
+    result: dict[str, Any] = {"fts_tables": sorted(fts_tables), "finalized": False}
+    if fts_tables != {"messages_fts", "messages_fts_trigram"}:
+        result["error"] = "fresh destination is missing required FTS tables"
+        return result
+
+    fts_keys = tuple(key for key in _GENERATED_META_KEYS if key.startswith("fts_"))
+    placeholders = ", ".join("?" for _ in fts_keys)
+    destination.execute("BEGIN IMMEDIATE")
+    try:
+        destination.execute(
+            f"DELETE FROM state_meta WHERE key IN ({placeholders})",
+            fts_keys,
+        )
+        destination.execute(
+            "INSERT INTO state_meta(key, value) VALUES (?, ?) "
+            "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+            ("fts_storage_version", str(FTS_STORAGE_VERSION)),
+        )
+        destination.execute("COMMIT")
+    except BaseException:
+        destination.execute("ROLLBACK")
+        raise
+    result["finalized"] = True
+    return result
+
+
+def recover_session_database(
+    source_path: Path,
+    output_path: Path,
+    *,
+    work_dir: Optional[Path] = None,
+    chunk_size: int = 1_000,
+    progress_cb: Optional[ProgressCallback] = None,
+    allow_partial: bool = False,
+) -> dict[str, Any]:
+    """Recover canonical rows into a separate current-schema database.
+
+    The source path and its sidecars are copied before SQLite opens anything.
+    ``output_path`` must not exist and is never swapped into place.
+    """
+
+    if chunk_size <= 0:
+        raise SessionRecoverySafetyError("chunk_size must be greater than zero")
+
+    source, output, work_root = _validate_paths(
+        source_path,
+        output_path=output_path,
+        work_dir=work_dir,
+    )
+    assert output is not None
+    disk_space = _disk_space_preflight(source, work_root, output.parent)
+
+    temp_dir, snapshot_source, inspection = _snapshot_and_inspect(source, work_root)
+    try:
+        if not inspection.get("recoverable") and not allow_partial:
+            reasons = "; ".join(inspection.get("errors") or ["unknown source error"])
+            raise SessionRecoverySourceError(
+                f"Required canonical tables are not readable: {reasons}"
+            )
+        if allow_partial:
+            missing_required = [
+                table
+                for table in ("sessions", "messages")
+                if not inspection["tables"][table].get("available")
+            ]
+            if missing_required:
+                raise SessionRecoverySourceError(
+                    "Partial recovery still requires readable table schemas for: "
+                    + ", ".join(missing_required)
+                )
+
+        source_conn = sqlite3.connect(
+            str(snapshot_source),
+            isolation_level=None,
+            timeout=1.0,
+        )
+        source_conn.execute("PRAGMA writable_schema=ON")
+        destination_db: Optional[SessionDB] = None
+        destination_conn: Optional[sqlite3.Connection] = None
+        try:
+            has_topic_tables = any(
+                inspection["tables"][table].get("available") for table in _TOPIC_TABLES
+            )
+
+            destination_db = SessionDB(db_path=output)
+            if has_topic_tables:
+                destination_db.apply_telegram_topic_migration()
+            destination_db.close()
+            destination_db = None
+
+            destination_conn = sqlite3.connect(
+                str(output),
+                isolation_level=None,
+                timeout=1.0,
+            )
+            destination_conn.execute("PRAGMA foreign_keys=OFF")
+
+            copy_report: dict[str, dict[str, Any]] = {}
+            for table in _CANONICAL_TABLES:
+                table_inspection = inspection["tables"][table]
+                copy_function = (
+                    _copy_table_salvage if allow_partial else _copy_table
+                )
+                copy_report[table] = copy_function(
+                    source_conn,
+                    destination_conn,
+                    table,
+                    chunk_size=chunk_size,
+                    progress_cb=progress_cb,
+                    source_rows=table_inspection.get("rows"),
+                )
+
+            state_meta_inspection = inspection["tables"]["state_meta"]
+            if state_meta_inspection.get("available"):
+                state_meta_copy_function = (
+                    _copy_state_meta_salvage
+                    if allow_partial
+                    else _copy_state_meta
+                )
+                copy_report["state_meta"] = state_meta_copy_function(
+                    source_conn,
+                    destination_conn,
+                    chunk_size=chunk_size,
+                    progress_cb=progress_cb,
+                    source_rows=state_meta_inspection.get("rows"),
+                )
+            else:
+                copy_report["state_meta"] = {"status": "missing", "copied_rows": 0}
+
+            for table in _TOPIC_TABLES:
+                table_inspection = inspection["tables"][table]
+                if not table_inspection.get("available"):
+                    copy_report[table] = {
+                        "status": "missing",
+                        "copied_rows": 0,
+                    }
+                    continue
+                copy_function = (
+                    _copy_table_salvage if allow_partial else _copy_table
+                )
+                copy_report[table] = copy_function(
+                    source_conn,
+                    destination_conn,
+                    table,
+                    chunk_size=chunk_size,
+                    progress_cb=progress_cb,
+                    source_rows=table_inspection.get("rows"),
+                )
+            orphan_cleanup = (
+                _cleanup_partial_orphans(destination_conn)
+                if allow_partial
+                else None
+            )
+            derived_metadata = _finalize_derived_metadata(destination_conn)
+        finally:
+            source_conn.close()
+            if destination_conn is not None:
+                destination_conn.close()
+            if destination_db is not None:
+                destination_db.close()
+
+        verification = _verify_recovered_database(
+            output,
+            expected_counts={
+                table: inspection["tables"][table].get("rows")
+                for table in _CANONICAL_TABLES
+            },
+            copy_report=copy_report,
+            allow_partial=allow_partial,
+            orphan_cleanup=orphan_cleanup,
+        )
+        source_unchanged = (
+            _source_fingerprint(source) == inspection["source_fingerprint"]
+        )
+        if not source_unchanged:
+            verification["errors"].append(
+                "the source database bundle changed during recovery"
+            )
+            verification["complete"] = False
+
+        return {
+            "operation": "recover",
+            "allow_partial": allow_partial,
+            "source": str(source),
+            "output": str(output),
+            "source_bundle": inspection["source_bundle"],
+            "source_fingerprint": inspection["source_fingerprint"],
+            "source_unchanged": source_unchanged,
+            "disk_space": disk_space,
+            "inspection": {
+                "journal_mode": inspection.get("journal_mode"),
+                "tables": inspection["tables"],
+                "errors": inspection["errors"],
+                "warnings": inspection["warnings"],
+            },
+            "copy": copy_report,
+            "orphan_cleanup": orphan_cleanup,
+            "derived_metadata": derived_metadata,
+            "verification": verification,
+            "complete": bool(verification.get("complete") and source_unchanged),
+            "partial": bool(verification.get("loss_detected")),
+            "verified": bool(verification.get("healthy") and source_unchanged),
+            "installed": False,
+        }
+    finally:
+        temp_dir.cleanup()
+
+
+def write_recovery_report(path: Path, report: dict[str, Any]) -> Path:
+    """Write a JSON report without overwriting an existing file."""
+
+    destination = _resolved_output_path(path)
+    with destination.open("x", encoding="utf-8") as handle:
+        json.dump(report, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+    return destination
diff --git a/hermes_cli/setup.py b/hermes_cli/setup.py
index 1148e295364..0f4d413d795 100644
--- a/hermes_cli/setup.py
+++ b/hermes_cli/setup.py
@@ -1247,6 +1247,28 @@ def setup_terminal_backend(config: dict):
         config["terminal"].setdefault(
             "docker_image", "nikolaik/python-nodejs:python3.11-nodejs20"
         )
+        print()
+        print_info("Docker sandboxes can be protected with the egress credential firewall.")
+        print_info(
+            "It routes sandbox traffic through iron-proxy so containers receive "
+            "proxy tokens instead of real API keys."
+        )
+        print_info(
+            "   Docker only for now; Modal, SSH, Daytona, and Singularity are not wired yet."
+        )
+        if prompt_yes_no("  Enable egress firewall for Docker sandboxes?", False):
+            proxy_cfg = config.setdefault("proxy", {})
+            proxy_cfg["enabled"] = True
+            proxy_cfg.setdefault("enforce_on_docker", True)
+            print_success("Egress firewall enabled in config")
+            print_info(
+                "Run `hermes egress setup` then `hermes egress start` to mint "
+                "tokens and launch the proxy."
+            )
+        else:
+            print_info(
+                "Skipping egress firewall. You can enable it later with `hermes egress setup`."
+            )
 
     elif selected_backend == "singularity":
         print_success("Terminal backend: Singularity/Apptainer")
@@ -1428,7 +1450,7 @@ def setup_terminal_backend(config: dict):
                 ssh_cmd.extend(["-p", port])
             ssh_cmd.append(f"{user}@{host}" if user else host)
             ssh_cmd.append("echo ok")
-            result = subprocess.run(ssh_cmd, capture_output=True, text=True, timeout=10)
+            result = subprocess.run(ssh_cmd, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10)
             if result.returncode == 0:
                 print_success("  SSH connection successful!")
             else:
diff --git a/hermes_cli/setup_hidden_env.py b/hermes_cli/setup_hidden_env.py
new file mode 100644
index 00000000000..cea85b5987e
--- /dev/null
+++ b/hermes_cli/setup_hidden_env.py
@@ -0,0 +1,56 @@
+"""Which platform env vars the setup surfaces hide.
+
+Every messaging platform ships the same handful of knobs that are either set
+for the user later or already correct by default. Listing them on a setup form
+turns "paste your bot token" into a five-field interrogation where none of the
+answers are discoverable — the Discord card asked for a home channel ID you
+need Developer Mode to copy, next to a reply-threading preference.
+
+Hiding them is a *presentation* decision only. The env vars keep working
+through ``hermes config set``, ``.env``, and ``config.yaml``; the gateway reads
+them exactly as before. This module just says what a new user is asked during
+setup.
+
+Lives here rather than in ``web_server`` so the CLI wizard can share it without
+importing the dashboard's FastAPI surface.
+"""
+
+# Suffix match, so plugin adapters nobody enumerated (IRC, SimpleX, LINE, ntfy)
+# get the same treatment without a code change here.
+#
+#   *_HOME_CHANNEL*        the bot offers /sethome on the first chat
+#   *_ALLOW_ALL_USERS      defaults off; enabling it is a security decision
+#   *_REPLY_TO_MODE        cosmetic threading preference
+#   *_REPLY_MODE           same, Mattermost's spelling
+#   *_REQUIRE_MENTION      behavior toggle with a sane default
+#   *_AUTO_THREAD          same
+#   *_FREE_RESPONSE_*      per-channel tuning, done once the bot is in a server
+#   *_ALLOWED_CHANNELS     same
+#   *_PROXY                only for networks that block the platform
+#
+# Allowlists (*_ALLOWED_USERS) deliberately stay visible: that IS the decision
+# a new user has to make, and the gateway denies everyone until it's set.
+SETUP_HIDDEN_ENV_SUFFIXES = (
+    "_HOME_CHANNEL",
+    "_HOME_CHANNEL_NAME",
+    "_HOME_CHANNEL_THREAD_ID",
+    "_HOME_ADDRESS",
+    "_ALLOW_ALL_USERS",
+    "_REPLY_TO_MODE",
+    "_REPLY_MODE",
+    "_REQUIRE_MENTION",
+    "_AUTO_THREAD",
+    "_FREE_RESPONSE_CHANNELS",
+    "_FREE_RESPONSE_ROOMS",
+    "_ALLOWED_CHANNELS",
+    "_PROXY",
+)
+
+
+def is_setup_hidden_env(name: str) -> bool:
+    """True when a var is self-configuring and shouldn't appear in setup forms.
+
+    Callers must still keep any var a platform lists as *required* — hiding a
+    required credential would make that platform unconfigurable from the UI.
+    """
+    return name.endswith(SETUP_HIDDEN_ENV_SUFFIXES)
diff --git a/hermes_cli/sqlite_runtime.py b/hermes_cli/sqlite_runtime.py
new file mode 100644
index 00000000000..7465b08a7ce
--- /dev/null
+++ b/hermes_cli/sqlite_runtime.py
@@ -0,0 +1,124 @@
+"""Import-safe helpers for inspecting a Python interpreter's linked SQLite.
+
+This module intentionally depends only on the standard library.  Installer and
+update code must be able to use it before Hermes' third-party dependencies are
+healthy.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+def _version_tuple(parts: Iterable[object]) -> tuple[int, int, int]:
+    values = [int(part) for part in parts]
+    values.extend([0] * (3 - len(values)))
+    return tuple(values[:3])
+
+
+def is_sqlite_wal_reset_vulnerable(
+    version_info: tuple[int, ...],
+) -> bool:
+    """Return whether *version_info* contains SQLite's WAL-reset bug."""
+    info = _version_tuple(version_info)
+    if info < (3, 7, 0):
+        return False
+    if info >= (3, 51, 3):
+        return False
+    if (3, 50, 7) <= info < (3, 51, 0):
+        return False
+    if (3, 44, 6) <= info < (3, 45, 0):
+        return False
+    return True
+
+
+@dataclass(frozen=True)
+class SQLiteRuntimeInfo:
+    """SQLite details reported by one exact Python executable."""
+
+    executable: Path
+    base_prefix: Path
+    python_version: tuple[int, int, int]
+    sqlite_version: tuple[int, int, int]
+    sqlite_version_string: str
+    sqlite_source_id: str
+
+    @property
+    def wal_reset_vulnerable(self) -> bool:
+        return is_sqlite_wal_reset_vulnerable(self.sqlite_version)
+
+
+_PROBE_SCRIPT = """
+import json
+import sqlite3
+import sys
+
+conn = sqlite3.connect(":memory:")
+try:
+    row = conn.execute("SELECT sqlite_source_id()").fetchone()
+finally:
+    conn.close()
+
+print(json.dumps({
+    "base_prefix": sys.base_prefix,
+    "executable": sys.executable,
+    "python_version": list(sys.version_info[:3]),
+    "sqlite_version": list(sqlite3.sqlite_version_info),
+    "sqlite_version_string": sqlite3.sqlite_version,
+    "sqlite_source_id": str(row[0]) if row and row[0] is not None else "",
+}))
+"""
+
+
+def probe_sqlite_runtime(
+    python: str | Path,
+    *,
+    timeout: float = 30.0,
+) -> SQLiteRuntimeInfo | None:
+    """Probe SQLite in *python*, never the caller's linked SQLite.
+
+    ``None`` means the interpreter could not be executed or returned malformed
+    data.  The child runs isolated from inherited Python path overrides.
+    """
+    executable = Path(python)
+    env = dict(os.environ)
+    for key in (
+        "CONDA_DEFAULT_ENV",
+        "CONDA_PREFIX",
+        "PYTHONHOME",
+        "PYTHONPATH",
+        "UV_PROJECT_ENVIRONMENT",
+        "UV_PYTHON",
+        "VIRTUAL_ENV",
+    ):
+        env.pop(key, None)
+    try:
+        result = subprocess.run(
+            [str(executable), "-I", "-c", _PROBE_SCRIPT],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+            env=env,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    try:
+        payload = json.loads(result.stdout)
+        return SQLiteRuntimeInfo(
+            executable=Path(str(payload["executable"])),
+            base_prefix=Path(str(payload["base_prefix"])),
+            python_version=_version_tuple(payload["python_version"]),
+            sqlite_version=_version_tuple(payload["sqlite_version"]),
+            sqlite_version_string=str(payload["sqlite_version_string"]),
+            sqlite_source_id=str(payload.get("sqlite_source_id", "")),
+        )
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+        return None
diff --git a/hermes_cli/sqlite_safe_read.py b/hermes_cli/sqlite_safe_read.py
new file mode 100644
index 00000000000..352228ed522
--- /dev/null
+++ b/hermes_cli/sqlite_safe_read.py
@@ -0,0 +1,409 @@
+"""Lock-safe inspection of SQLite database files.
+
+Why this module exists
+----------------------
+POSIX advisory locks are cancelled **process-wide** by ``close()`` on *any*
+file descriptor for that file::
+
+    the close() system call will cancel all POSIX advisory locks on the
+    same file for all threads and all file descriptors in the process
+    -- https://sqlite.org/howtocorrupt.html#_posix_advisory_locks_canceled_by_a_separate_thread_doing_close_
+
+So a bare ``open(db_path, "rb") ... close()`` on a **live** database silently
+drops every lock SQLite holds on it from this process -- including the
+EXCLUSIVE lock a ``VACUUM`` is holding while it rewrites the whole file, and
+the RESERVED lock an in-flight ``BEGIN IMMEDIATE`` is holding. Other processes
+are then free to write into a file that a writer still believes it owns, which
+is the documented route to "database disk image is malformed".
+
+Hermes is exactly the topology this hits: gateway, dispatcher, dashboard,
+TUI, CLI, cron and kanban workers all open the same ``state.db`` /
+``kanban.db``, and several code paths used to byte-probe those files while
+connections were live.
+
+The rules
+---------
+1. **Never** ``open()`` a database file that may have live connections in this
+   process. Ask SQLite instead -- :func:`page_count_bytes` reads the same
+   header field via ``PRAGMA``, over the existing connection, taking no new
+   descriptor.
+2. Byte-level probes are only safe **before any connection exists** for that
+   path (first-open validation). Route those through
+   :func:`read_header_bytes_preopen`, which refuses once a connection has been
+   registered for the path.
+
+Concurrency contract
+--------------------
+The registry is not advisory bookkeeping -- it is the guard, so the
+check and the byte read must be **atomic with respect to connection
+lifecycle**. ``_live_lock`` is therefore held across three critical sections,
+each of which spans the syscall *and* the registry mutation:
+
+* open + register (:func:`connect_tracked`)
+* unregister + close (:meth:`TrackedConnection.close`)
+* check + ``open``/``read``/``close`` (:func:`read_header_bytes_preopen`)
+
+Without that, a thread could pass the "no live connection" check, a second
+thread could open a connection and take a write lock, and the first thread's
+``close()`` would then cancel it -- reintroducing the exact bug this module
+exists to prevent. The lock is never held while a caller *uses* a connection,
+only across these transitions, so it does not serialise database work.
+
+Path identity
+-------------
+Connections are keyed by the **canonical database path**, resolved from
+``PRAGMA database_list`` on the opened connection. The caller's spelling is
+not trustworthy: ``SessionDB``'s read-only path opens
+``file:/…/state.db?mode=ro`` with ``uri=True``, and treating that string as a
+filesystem path yields a key like ``<cwd>/file:/…/state.db?mode=ro`` which no
+later probe of the real ``Path`` can ever match.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+SQLITE_HEADER_MAGIC = b"SQLite format 3\x00"
+
+# Offset of the 4-byte big-endian page-count field in the SQLite header.
+_HEADER_PAGE_COUNT_OFFSET = 28
+
+# Guards BOTH the registry and the lifecycle syscalls it describes. Reentrant
+# because connect_tracked -> _canonical_db_path -> ... stays on one thread.
+_live_lock = threading.RLock()
+# canonical path -> number of live connections opened by this process
+_live_connections: dict[str, int] = {}
+
+
+class UntrackableConnectionError(RuntimeError):
+    """A connection to a probe-able database could not be tracked.
+
+    Raised rather than silently returning an untracked connection: on these
+    paths tracking is part of the correctness contract, not an optimisation.
+    """
+
+
+def _key(path: Path | str) -> str:
+    """Canonicalise a *filesystem* path for use as a registry key."""
+    try:
+        return str(Path(path).resolve())
+    except OSError:
+        return str(path)
+
+
+def _canonical_db_path(conn: sqlite3.Connection) -> Optional[str]:
+    """The on-disk path of ``main``, as SQLite itself reports it.
+
+    Immune to the caller's spelling (``file:`` URIs, relative paths, symlinks).
+    Returns ``None`` for in-memory or unnamed databases, which cannot be
+    byte-probed and therefore need no tracking.
+    """
+    try:
+        row = conn.execute("PRAGMA database_list").fetchone()
+    except sqlite3.Error:
+        return None
+    if not row or len(row) < 3:
+        return None
+    path_str = row[2]
+    if not path_str:
+        return None
+    return _key(path_str)
+
+
+def track_connection(path: Path | str) -> None:
+    """Record that this process now holds a connection to *path*.
+
+    Prefer :func:`connect_tracked`; this exists for callers that manage their
+    own connection objects, and for tests.
+    """
+    key = _key(path)
+    with _live_lock:
+        _live_connections[key] = _live_connections.get(key, 0) + 1
+
+
+def untrack_connection(path: Path | str) -> None:
+    """Record that one connection to *path* has been closed."""
+    key = _key(path)
+    with _live_lock:
+        remaining = _live_connections.get(key, 0) - 1
+        if remaining > 0:
+            _live_connections[key] = remaining
+        else:
+            _live_connections.pop(key, None)
+
+
+def has_live_connection(path: Path | str) -> bool:
+    """Whether this process currently holds any connection to *path*."""
+    with _live_lock:
+        return _key(path) in _live_connections
+
+
+class _TrackingMixin:
+    """Untrack-on-close behaviour, mixable into any Connection subclass."""
+
+    _hermes_tracked_path: str | None = None
+
+    def close(self) -> None:  # type: ignore[misc]
+        with _live_lock:
+            path = getattr(self, "_hermes_tracked_path", None)
+            if path is not None:
+                self._hermes_tracked_path = None
+                untrack_connection(path)
+            super().close()  # type: ignore[misc]
+
+
+class TrackedConnection(_TrackingMixin, sqlite3.Connection):
+    """A ``sqlite3.Connection`` that untracks its path exactly once on close.
+
+    Counting opens is easy; counting closes reliably is not, because callers
+    close connections in many places (and some hand them to
+    ``contextlib.closing``). Putting the decrement on ``close()`` — the one
+    method every close path must go through — keeps the registry from
+    drifting upward and permanently disabling byte-probes.
+
+    The unregister and the real ``close()`` happen together under
+    ``_live_lock`` so a concurrent probe can never observe "no live
+    connection" while this descriptor is still open.
+
+    Note ``with conn:`` does NOT close a sqlite3 connection (it only commits or
+    rolls back), so this hook is not fired spuriously by transaction scopes.
+    """
+
+
+_tracked_factory_cache: dict[type, type] = {}
+
+
+def _tracking_factory(factory: type) -> type:
+    """Return *factory* augmented with untrack-on-close.
+
+    Callers legitimately supply their own ``Connection`` subclasses (the test
+    suite uses them to simulate FTS5-less or pragma-failing runtimes). Rather
+    than refusing those — or silently leaving them untracked, which would
+    quietly unguard the database — we mix the tracking ``close()`` into the
+    caller's class so tracking is preserved either way.
+    """
+    if factory is sqlite3.Connection:
+        return TrackedConnection
+    if issubclass(factory, _TrackingMixin):
+        return factory
+    cached = _tracked_factory_cache.get(factory)
+    if cached is None:
+        cached = type(f"Tracked{factory.__name__}", (_TrackingMixin, factory), {})
+        _tracked_factory_cache[factory] = cached
+    return cached
+
+
+def connect_tracked(
+    path: Path | str,
+    *,
+    tracking_path: Path | str | None = None,
+    connect_fn=None,
+    **kwargs,
+) -> sqlite3.Connection:
+    """``sqlite3.connect`` that registers the connection for the lifetime of the fd.
+
+    Use for any connection to a database whose file might otherwise be
+    byte-probed (``state.db``, ``kanban.db``). The registration is released
+    automatically on ``close()``.
+
+    The open and the registration happen together under ``_live_lock``, so a
+    concurrent :func:`read_header_bytes_preopen` cannot slip between them and
+    cancel this connection's locks.
+
+    The registry key is the canonical path reported by ``PRAGMA
+    database_list`` -- not *path*, which may be a ``file:`` URI. Pass
+    ``tracking_path`` to override when the caller already knows the real path.
+
+    ``connect_fn`` lets a caller supply its own opener (defaults to
+    :func:`sqlite3.connect`), so a module that owns the connection — and any
+    test that patches that module's ``sqlite3.connect`` — keeps control of how
+    the connection is created while this helper owns tracking.
+
+    A caller-supplied ``factory`` is honoured but is transparently augmented
+    with untrack-on-close, so tracking is never silently skipped. If a
+    file-backed connection still cannot be tracked,
+    :class:`UntrackableConnectionError` is raised rather than handing back a
+    connection whose database has quietly lost byte-probe protection.
+    """
+    opener = connect_fn if connect_fn is not None else sqlite3.connect
+    kwargs["factory"] = _tracking_factory(kwargs.get("factory", sqlite3.Connection))
+
+    with _live_lock:
+        conn = opener(str(path), **kwargs)
+        try:
+            resolved = (
+                _key(tracking_path)
+                if tracking_path is not None
+                else _canonical_db_path(conn)
+            )
+            if resolved is None:
+                # In-memory / unnamed: nothing on disk to byte-probe.
+                return conn
+            if not isinstance(conn, _TrackingMixin):
+                # The opener substituted its own factory and discarded ours
+                # (test doubles simulating FTS5-less runtimes do this). Retag
+                # the instance's class with the tracking mixin so close() still
+                # releases the registry entry, rather than handing back a
+                # connection whose database has silently lost probe safety.
+                conn = _retrofit_tracking(conn, resolved)
+            conn._hermes_tracked_path = resolved
+            _live_connections[resolved] = _live_connections.get(resolved, 0) + 1
+            return conn
+        except Exception:
+            try:
+                # Close via sqlite3 directly: the tracking entry was either
+                # never made or is being unwound here.
+                sqlite3.Connection.close(conn)
+            except Exception:
+                pass
+            raise
+
+
+def _retrofit_tracking(conn: sqlite3.Connection, resolved: str) -> sqlite3.Connection:
+    """Give an already-open connection untrack-on-close semantics.
+
+    ``sqlite3.Connection`` subclasses are ordinary Python classes, so the
+    instance's ``__class__`` can be swapped for one that mixes in the tracking
+    ``close()``. Used when an opener ignored the factory we asked for.
+    """
+    cls = type(conn)
+    if issubclass(cls, _TrackingMixin):
+        return conn
+    try:
+        conn.__class__ = _tracking_factory(cls)  # type: ignore[assignment]
+        return conn
+    except TypeError as exc:
+        raise UntrackableConnectionError(
+            f"connection to {resolved} uses factory {cls.__name__}, which "
+            "cannot release its tracking entry on close; byte-probe safety "
+            "for this database would be silently lost"
+        ) from exc
+
+
+def page_count_bytes(conn: sqlite3.Connection) -> Optional[int]:
+    """Logical database size in bytes, read through *conn*.
+
+    ``page_count * page_size`` is the same quantity the 4-byte header field at
+    offset 28 carries, but reading it via ``PRAGMA`` opens no new file
+    descriptor and therefore cannot cancel this process's POSIX locks.
+
+    Returns ``None`` when the pragmas cannot be read.
+    """
+    try:
+        page_count = conn.execute("PRAGMA page_count").fetchone()[0]
+        page_size = conn.execute("PRAGMA page_size").fetchone()[0]
+    except (sqlite3.Error, TypeError, IndexError) as exc:
+        logger.debug("page_count/page_size unavailable: %s", exc)
+        return None
+    try:
+        return int(page_count) * int(page_size)
+    except (TypeError, ValueError):
+        return None
+
+
+def file_length_matches_header(conn: sqlite3.Connection) -> Optional[bool]:
+    """Whether the file on disk is at least as long as the header claims.
+
+    Detects the "torn extend" shape (file shorter than its own page count)
+    without ever opening the database file: the header side comes from
+    ``PRAGMA page_count`` over *conn*, and the on-disk side from ``stat()``,
+    which takes no descriptor and cannot break locks.
+
+    Returns ``None`` when the check is not applicable (in-memory database,
+    unreadable pragmas, or a stat failure).
+
+    Note: in WAL mode a freshly committed page may still live in the ``-wal``
+    file, so the main file legitimately lags. Callers must treat this as
+    advisory unless the database is in a rollback journal mode.
+    """
+    path_str = _canonical_db_path(conn)
+    if path_str is None:
+        return None
+
+    logical = page_count_bytes(conn)
+    if not logical:
+        return None
+    try:
+        actual = os.path.getsize(path_str)
+    except OSError:
+        return None
+    return actual >= logical
+
+
+def read_header_bytes_preopen(
+    path: Path | str,
+    *,
+    length: int = 100,
+    force: bool = False,
+) -> Optional[bytes]:
+    """Read the first *length* bytes of *path* -- only when no connection is live.
+
+    This is the ONLY sanctioned byte-level read of a database file, and it is
+    restricted to first-open validation (is this file a real SQLite database,
+    is it zeroed, has it been overwritten by something else). Once any
+    connection to *path* exists in this process, the read is refused and
+    ``None`` is returned, because the ``close()`` would cancel that
+    connection's POSIX locks.
+
+    The registry check and the ``open``/``read``/``close`` are performed
+    together under ``_live_lock``, so a connection cannot be opened in the
+    window between deciding "nothing is live" and closing this descriptor.
+
+    Set ``force=True`` only for genuinely offline files (quarantined copies,
+    snapshot artifacts, archives) that no live connection can reference.
+    """
+    with _live_lock:
+        if not force and _key(path) in _live_connections:
+            logger.debug(
+                "refusing byte-level read of %s: a live connection exists in "
+                "this process and close() would cancel its POSIX locks",
+                path,
+            )
+            return None
+        try:
+            with open(path, "rb") as handle:
+                return handle.read(length)
+        except OSError:
+            return None
+
+
+class LiveConnectionError(RuntimeError):
+    """A raw file operation was attempted on a database with live connections."""
+
+
+@contextlib.contextmanager
+def offline_file_access(path: Path | str, *, what: str = "read"):
+    """Hold the connection-lifecycle lock across a raw read of a database file.
+
+    Checking :func:`has_live_connection` and *then* doing the raw I/O is a
+    check/use race: a connection can be opened in the window between the two,
+    and the raw ``close()`` will cancel its POSIX advisory locks — the exact
+    failure class the registry exists to prevent. Any multi-step raw access
+    (copying a database plus its ``-wal``/``-shm``/``-journal`` sidecars,
+    hashing a file, moving a bundle aside) must therefore run *inside* this
+    context manager rather than after a bare check.
+
+    While held, :func:`connect_tracked` blocks, so no new connection can
+    appear mid-copy. Raises :class:`LiveConnectionError` if a connection is
+    already live when the guard is entered.
+
+    The lock is only held for the duration of the raw I/O; it never spans
+    caller work on an open connection, so it does not serialise database use.
+    """
+    with _live_lock:
+        if _key(path) in _live_connections:
+            raise LiveConnectionError(
+                f"Refusing to {what} {path}: a connection to it is still open "
+                "in this process, and raw file access would cancel that "
+                "connection's POSIX advisory locks. Close all database "
+                "handles (stop the gateway/dashboard) and retry."
+            )
+        yield
diff --git a/hermes_cli/tools_config.py b/hermes_cli/tools_config.py
index f3abfb4d9a9..ace4dc3a727 100644
--- a/hermes_cli/tools_config.py
+++ b/hermes_cli/tools_config.py
@@ -475,7 +475,9 @@ TOOL_CATEGORIES = {
         "setup_title": "Select xAI Credential Source",
         "setup_note": (
             "Hermes routes X searches through xAI's built-in x_search "
-            "Responses tool. Both credential sources hit the same "
+            "Responses tool for read-only public X discovery. Use the xurl "
+            "skill for authenticated X API reads and account actions. Both "
+            "credential sources hit the same "
             "https://api.x.ai/v1/responses endpoint — pick whichever you "
             "already have. SuperGrok OAuth is preferred when both are set "
             "(uses your subscription quota instead of API spend)."
@@ -706,7 +708,7 @@ def _pip_install(
         try:
             result = subprocess.run(
                 [uv_bin, "pip", "install", *args],
-                capture_output=capture_output, text=True, timeout=timeout,
+                capture_output=capture_output, text=True, encoding="utf-8", errors="replace", timeout=timeout,
                 env=uv_env,
                 creationflags=_post_setup_no_window_flags(
                     streams_to_console=not capture_output
@@ -724,7 +726,7 @@ def _pip_install(
         # Probe for pip; bootstrap via ensurepip if missing (uv venv lacks it).
         probe = subprocess.run(
             pip_cmd + ["--version"],
-            capture_output=True, text=True, timeout=15,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=15,
             creationflags=_post_setup_no_window_flags(),
         )
         if probe.returncode != 0:
@@ -733,7 +735,7 @@ def _pip_install(
         try:
             subprocess.run(
                 [sys.executable, "-m", "ensurepip", "--upgrade", "--default-pip"],
-                capture_output=True, text=True, timeout=120, check=True,
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=120, check=True,
                 creationflags=_post_setup_no_window_flags(),
             )
         except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
@@ -745,7 +747,7 @@ def _pip_install(
 
     return subprocess.run(
         pip_cmd + ["install", *args],
-        capture_output=capture_output, text=True, timeout=timeout,
+        capture_output=capture_output, text=True, encoding="utf-8", errors="replace", timeout=timeout,
         creationflags=_post_setup_no_window_flags(
             streams_to_console=not capture_output
         ),
@@ -857,7 +859,7 @@ def install_cua_driver(upgrade: bool = False) -> bool:
         try:
             version = subprocess.run(
                 [binary, "--version"],
-                capture_output=True, text=True, timeout=5, env=_cua_driver_env(),
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5, env=_cua_driver_env(),
                 creationflags=_post_setup_no_window_flags(),
             ).stdout.strip()
             _print_success(f"    {driver_cmd} already installed: {version or 'unknown version'}")
@@ -915,7 +917,7 @@ def install_cua_driver(upgrade: bool = False) -> bool:
         try:
             before = subprocess.run(
                 [binary, "--version"],
-                capture_output=True, text=True, timeout=5, env=_cua_driver_env(),
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5, env=_cua_driver_env(),
                 creationflags=_post_setup_no_window_flags(),
             ).stdout.strip()
         except Exception:
@@ -928,7 +930,7 @@ def install_cua_driver(upgrade: bool = False) -> bool:
         try:
             after = subprocess.run(
                 [binary, "--version"],
-                capture_output=True, text=True, timeout=5, env=_cua_driver_env(),
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5, env=_cua_driver_env(),
                 creationflags=_post_setup_no_window_flags(),
             ).stdout.strip()
             if after and after != before:
@@ -1073,7 +1075,7 @@ def _run_cua_driver_installer(label: str = "Installing", verbose: bool = True) -
         try:
             dl = subprocess.run(
                 ["curl", "-fsSL", "-o", script_path, install_url],
-                capture_output=True, text=True, timeout=120,
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=120,
             )
         except (subprocess.TimeoutExpired, OSError) as e:
             _print_warning(f"    cua-driver installer download failed: {e}")
@@ -1241,7 +1243,7 @@ def _run_post_setup(post_setup_key: str):
                 # only, avoiding the apps/* glob which would pull in
                 # apps/desktop (Electron + node-pty) unnecessarily. See #38772.
                 [npm_bin, "install", "--silent", "--workspaces=false"],
-                capture_output=True, text=True, cwd=str(PROJECT_ROOT),
+                capture_output=True, text=True, encoding="utf-8", errors="replace", cwd=str(PROJECT_ROOT),
                 creationflags=_post_setup_no_window_flags(),
             )
             if result.returncode == 0:
@@ -1321,7 +1323,7 @@ def _run_post_setup(post_setup_key: str):
         try:
             result = subprocess.run(
                 install_cmd,
-                capture_output=True, text=True, cwd=str(PROJECT_ROOT), timeout=600,
+                capture_output=True, text=True, encoding="utf-8", errors="replace", cwd=str(PROJECT_ROOT), timeout=600,
                 creationflags=_post_setup_no_window_flags(),
             )
             if result.returncode == 0:
@@ -1355,7 +1357,7 @@ def _run_post_setup(post_setup_key: str):
             result = subprocess.run(
                 # --workspaces=false avoids resolving apps/desktop. See #38772.
                 [_npm_bin, "install", "--silent", "--workspaces=false"],
-                capture_output=True, text=True, cwd=str(PROJECT_ROOT),
+                capture_output=True, text=True, encoding="utf-8", errors="replace", cwd=str(PROJECT_ROOT),
                 creationflags=_post_setup_no_window_flags(),
             )
             if result.returncode == 0:
@@ -3808,18 +3810,33 @@ def _configure_vision_backend() -> None:
 def _configure_vision_provider_model(config: dict, vision_cfg: dict) -> None:
     """Provider + model picker for vision, mirroring the ``/model`` surface.
 
-    Lists authenticated providers (same data source as the model switcher),
-    lets the user pick one and then a model from its curated list (or type a
-    custom id), and persists ``auxiliary.vision.provider`` + ``.model``.
+    Provider rows come from ``build_aux_picker_rows()`` — the shared aux-picker
+    substrate — so this picker lists exactly what the ``hermes model`` aux-task
+    picker lists, including the user's own ``providers:`` / ``custom_providers:``
+    endpoints. Lets the user pick a provider and then a model from its curated
+    list (or type a custom id), and persists ``auxiliary.vision.provider`` +
+    ``.model``.
     """
     try:
-        from hermes_cli.model_switch import list_authenticated_providers
+        from hermes_cli.inventory import (
+            build_aux_picker_rows,
+            format_aux_picker_entries,
+        )
     except Exception as exc:  # pragma: no cover - import guard
         _print_warning(f"  Could not load provider list: {exc}")
         return
 
+    current_provider = str(vision_cfg.get("provider") or "").strip()
+    current_model = str(vision_cfg.get("model") or "").strip()
+    current_base_url = str(vision_cfg.get("base_url") or "").strip()
+
     try:
-        providers = list_authenticated_providers(max_models=40)
+        providers = build_aux_picker_rows(
+            current_provider=current_provider,
+            current_model=current_model,
+            current_base_url=current_base_url,
+            max_models=40,
+        )
     except Exception as exc:
         _print_warning(f"  Could not detect providers: {exc}")
         providers = []
@@ -3831,11 +3848,14 @@ def _configure_vision_provider_model(config: dict, vision_cfg: dict) -> None:
         )
         return
 
-    provider_labels = []
-    for p in providers:
-        name = p.get("name") or p.get("slug")
-        total = p.get("total_models", len(p.get("models", [])))
-        provider_labels.append(f"{name}  ({total} models)" if total else str(name))
+    provider_labels = [
+        label
+        for _slug, label, _models in format_aux_picker_entries(
+            providers,
+            current_provider=current_provider,
+            current_base_url=current_base_url,
+        )
+    ]
     provider_labels.append("Cancel")
 
     pidx = _prompt_choice("  Choose vision provider:", provider_labels, 0)
diff --git a/hermes_cli/uninstall.py b/hermes_cli/uninstall.py
index 6832d3d5607..c02fb8cca16 100644
--- a/hermes_cli/uninstall.py
+++ b/hermes_cli/uninstall.py
@@ -57,7 +57,7 @@ def remove_path_from_shell_configs():
     
     for config_path in configs:
         try:
-            content = config_path.read_text()
+            content = config_path.read_text(encoding="utf-8")
             original_content = content
             
             # Remove lines containing hermes-agent or hermes PATH entries
@@ -87,7 +87,7 @@ def remove_path_from_shell_configs():
                 new_content = new_content.replace('\n\n\n', '\n\n')
             
             if new_content != original_content:
-                config_path.write_text(new_content)
+                config_path.write_text(new_content, encoding="utf-8")
                 removed_from.append(config_path)
                 
         except Exception as e:
@@ -108,7 +108,7 @@ def remove_wrapper_script():
         if wrapper.exists():
             try:
                 # Check if it's our wrapper (contains hermes_cli reference)
-                content = wrapper.read_text()
+                content = wrapper.read_text(encoding="utf-8")
                 if 'hermes_cli' in content or 'hermes-agent' in content:
                     wrapper.unlink()
                     removed.append(wrapper)
@@ -465,7 +465,7 @@ def _uninstall_profile(profile) -> None:
             subprocess.run(
                 hermes_invocation + ["gateway", subcmd],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=60,
                 check=False,
             )
diff --git a/hermes_cli/web_git.py b/hermes_cli/web_git.py
index 0af12106745..0a00c0246cb 100644
--- a/hermes_cli/web_git.py
+++ b/hermes_cli/web_git.py
@@ -37,7 +37,7 @@ def _git(cwd: str, args: list[str], *, timeout: int = _GIT_TIMEOUT) -> tuple[int
             ["git", *args],
             cwd=cwd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=timeout,
         )
     except (OSError, subprocess.SubprocessError):
@@ -421,7 +421,7 @@ def _gh(cwd: str, args: list[str]) -> tuple[bool, str]:
         return False, ""
     try:
         proc = subprocess.run(
-            ["gh", *args], cwd=cwd, capture_output=True, text=True, timeout=_GH_TIMEOUT
+            ["gh", *args], cwd=cwd, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=_GH_TIMEOUT
         )
     except (OSError, subprocess.SubprocessError):
         return False, ""
diff --git a/hermes_cli/web_server.py b/hermes_cli/web_server.py
index 5d45e731f26..d9b7a1a56bf 100644
--- a/hermes_cli/web_server.py
+++ b/hermes_cli/web_server.py
@@ -27,6 +27,7 @@ import inspect
 import importlib.util
 import json
 import logging
+import math
 import mimetypes
 import os
 import queue
@@ -47,7 +48,7 @@ import zipfile
 from hermes_cli._subprocess_compat import windows_detach_flags, windows_hide_flags
 import urllib.request
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Literal, Optional, Tuple
 
 import yaml
 
@@ -71,6 +72,7 @@ from hermes_cli.config import (
     save_config,
     save_env_value,
     remove_env_value,
+    custom_endpoint_key_env,
     check_config_version,
     detect_install_method,
     format_docker_update_message,
@@ -94,6 +96,7 @@ from gateway.status import (
     normalize_updated_at,
     parse_active_agents,
     read_runtime_status,
+    resolve_gateway_liveness,
 )
 from utils import env_var_enabled
 
@@ -105,7 +108,7 @@ try:
     from fastapi.middleware.cors import CORSMiddleware
     from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
     from fastapi.staticfiles import StaticFiles
-    from pydantic import BaseModel, SecretStr
+    from pydantic import BaseModel, SecretStr, field_validator
     from starlette.concurrency import run_in_threadpool
 except ImportError:
     # First try lazy-installing the dashboard extras. Only the user actually
@@ -121,7 +124,7 @@ except ImportError:
         from fastapi.middleware.cors import CORSMiddleware
         from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
         from fastapi.staticfiles import StaticFiles
-        from pydantic import BaseModel, SecretStr
+        from pydantic import BaseModel, SecretStr, field_validator
         from starlette.concurrency import run_in_threadpool
     except Exception:
         raise SystemExit(
@@ -222,11 +225,16 @@ async def _lifespan(app: "FastAPI"):
     # /api/status).  The loop exits immediately when httpx is unavailable.
     selftest_task = asyncio.create_task(_dashboard_selftest_loop())
 
+    # Live auto-archive timer — keeps a backend that stays up for days
+    # sweeping stale sessions on schedule, independent of list requests.
+    auto_archive_task = asyncio.create_task(_auto_archive_ticker_loop())
+
     try:
         yield
     finally:
         pty_reaper_task.cancel()
         selftest_task.cancel()
+        auto_archive_task.cancel()
         await PTY_REGISTRY.close_all()
         if cron_stop is not None:
             cron_stop.set()
@@ -817,6 +825,25 @@ _SCHEMA_OVERRIDES: Dict[str, Dict[str, Any]] = {
         "description": "Modal sandbox mode",
         "options": ["sandbox", "function"],
     },
+    "proxy.enabled": {
+        "type": "boolean",
+        "description": (
+            "Docker-only egress credential firewall. Requires `hermes egress setup` "
+            "and `hermes egress start`; Modal/SSH/Daytona are not wired yet."
+        ),
+        "category": "security",
+    },
+    "proxy.credential_source": {
+        "type": "select",
+        "description": "Where iron-proxy loads real upstream secrets at start time",
+        "options": ["env", "bitwarden"],
+        "category": "security",
+    },
+    "proxy.enforce_on_docker": {
+        "type": "boolean",
+        "description": "Refuse Docker sandboxes when egress is enabled but not configured/running",
+        "category": "security",
+    },
     "tts.provider": {
         "type": "select",
         "description": "Text-to-speech provider",
@@ -1246,6 +1273,7 @@ class CustomEndpointUpdate(BaseModel):
     context_length: Optional[int] = None
     discover_models: bool = True
     make_default: bool = False
+    models: Optional[List[str]] = None
 
 
 class MessagingPlatformUpdate(BaseModel):
@@ -1360,9 +1388,35 @@ class MoaModelSlot(BaseModel):
     # Optional per-slot reasoning effort. Declared so a client round-tripping
     # the GET payload doesn't have it stripped at parse time and wiped on save.
     reasoning_effort: Optional[str] = None
+    enabled: bool = True
 
 
-class MoaPresetPayload(BaseModel):
+class _MoaReferenceControls(BaseModel):
+    # None = no per-preset override; the fan-out inherits
+    # auxiliary.moa_reference.timeout (900s default).
+    reference_timeout: Optional[float] = None
+    degraded_reference_policy: Literal["loud", "silent"] = "loud"
+
+    @field_validator("reference_timeout", mode="before")
+    @classmethod
+    def _validate_reference_timeout(cls, value: Any) -> Optional[float]:
+        """Reject JSON booleans/non-finite values before float coercion."""
+        if value is None or value == "":
+            return None
+        if isinstance(value, bool):
+            raise ValueError("reference_timeout must be a finite positive number")
+        try:
+            timeout = float(value)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                "reference_timeout must be a finite positive number"
+            ) from exc
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("reference_timeout must be a finite positive number")
+        return timeout
+
+
+class MoaPresetPayload(_MoaReferenceControls):
     reference_models: list[MoaModelSlot] = []
     aggregator: MoaModelSlot = MoaModelSlot()
     # None = temperature omitted from API calls (provider default), matching
@@ -1378,7 +1432,7 @@ class MoaPresetPayload(BaseModel):
     enabled: bool = True
 
 
-class MoaConfigPayload(BaseModel):
+class MoaConfigPayload(_MoaReferenceControls):
     default_preset: str = "default"
     active_preset: str = ""
     presets: dict[str, MoaPresetPayload] = {}
@@ -2985,6 +3039,16 @@ async def get_ssh_ownership(request: Request):
     return {"ok": True, "sshOwnerNonce": _SSH_OWNER_NONCE, "protocolVersion": 1}
 
 
+@app.get("/api/health")
+async def get_health():
+    """Lightweight process liveness for desktop/backend readiness probes."""
+    return {
+        "ok": True,
+        "version": __version__,
+        "auth_required": bool(getattr(app.state, "auth_required", False)),
+    }
+
+
 @app.get("/api/status")
 async def get_status(profile: Optional[str] = None):
     status_scope = None
@@ -2998,38 +3062,69 @@ async def get_status(profile: Optional[str] = None):
     # skills-module attributes that a concurrent request would cross-restore
     # across that await. Status only resolves get_hermes_home() at call time
     # (config/env/gateway state), which the task-local contextvar covers.
+    profile_dir: Optional[Path] = None
     if requested_profile and requested_profile.lower() != "current":
+        profile_dir = _resolve_profile_dir(requested_profile)
         status_scope = _config_profile_scope(requested_profile)
         status_scope.__enter__()
 
     try:
         current_ver, latest_ver = check_config_version()
         # --- Gateway liveness detection ---
-        # Try local PID check first (same-host).  If that fails and a remote
-        # GATEWAY_HEALTH_URL is configured, probe the gateway over HTTP so the
-        # dashboard works when the gateway runs in a separate container.
-        gateway_pid = get_running_pid_cached()
-        gateway_running = gateway_pid is not None
-        remote_health_body: dict | None = None
+        # Delegated to the single shared ladder in gateway.status so this
+        # endpoint and /api/messaging/platforms can never disagree about
+        # whether the gateway is up (they used to: sidebar "running" while
+        # the Channels page rendered "The gateway is not running").
+        #
+        # When ?profile=<name> was given, scope PID and state reads to that
+        # profile's directory — gateway identity files (PID, lock, runtime
+        # status) are written to the per-profile home, not the process-level
+        # HERMES_HOME (see issue #69143). Plain /api/status keeps the exact
+        # zero-arg call so its behavior (and cache signature) is unchanged.
+        #
+        # The module-level probe references are handed to the resolver so the
+        # long-standing `monkeypatch.setattr(web_server, "get_running_pid_cached", ...)`
+        # seam used across the test-suite still intercepts them.
+        def _bounded_health_probe():
+            """Health probe with the route's blocking-call budget preserved.
 
-        if not gateway_running and _GATEWAY_HEALTH_URL:
-            loop = asyncio.get_running_loop()
-            try:
-                alive, remote_health_body = await asyncio.wait_for(
-                    loop.run_in_executor(None, _probe_gateway_health),
-                    timeout=_GATEWAY_HEALTH_ROUTE_TIMEOUT,
-                )
-            except TimeoutError:
-                _log.warning(
-                    "/api/status gateway health probe exceeded %.2fs; using local status",
-                    _GATEWAY_HEALTH_ROUTE_TIMEOUT,
-                )
-                alive, remote_health_body = False, None
-            if alive:
-                gateway_running = True
-                # PID from the remote container (display only — not locally valid)
-                if remote_health_body:
-                    gateway_pid = remote_health_body.get("pid")
+            The resolver only reaches this rung when the local PID probe came
+            up empty, so the timeout is paid at most once per request and only
+            in the cross-container case that needs it.
+            """
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                future = pool.submit(_probe_gateway_health)
+                try:
+                    return future.result(timeout=_GATEWAY_HEALTH_ROUTE_TIMEOUT)
+                except concurrent.futures.TimeoutError:
+                    _log.warning(
+                        "/api/status gateway health probe exceeded %.2fs; "
+                        "using local status",
+                        _GATEWAY_HEALTH_ROUTE_TIMEOUT,
+                    )
+                    return False, None
+                except Exception:
+                    return False, None
+
+        local_runtime = (
+            read_runtime_status(path=profile_dir / "gateway_state.json")
+            if profile_dir
+            else read_runtime_status()
+        )
+
+        liveness = await run_in_threadpool(
+            lambda: resolve_gateway_liveness(
+                profile_dir=profile_dir,
+                runtime=local_runtime,
+                health_probe=_bounded_health_probe if _GATEWAY_HEALTH_URL else None,
+                pid_probe=get_running_pid_cached,
+                runtime_reader=read_runtime_status,
+                runtime_pid_probe=get_runtime_status_running_pid,
+            )
+        )
+        gateway_running = liveness.running
+        gateway_pid = liveness.pid
+        remote_health_body: dict | None = liveness.health_body
 
         gateway_state = None
         gateway_platforms: dict = {}
@@ -3048,20 +3143,9 @@ async def get_status(profile: Optional[str] = None):
 
         # Prefer the detailed health endpoint response (has full state) when the
         # local runtime status file is absent or stale (cross-container).
-        local_runtime = read_runtime_status()
         runtime = local_runtime
         if runtime is None and remote_health_body and remote_health_body.get("gateway_state"):
             runtime = remote_health_body
-        # The runtime-status PID fallback validates liveness with a local
-        # os.kill() probe, so it must only run against the LOCAL status file —
-        # never the remote health body, whose PID belongs to another host and
-        # is display-only. (Running os.kill on a remote PID is both wrong and
-        # trips the test live-system guard.)
-        if not gateway_running and local_runtime is not None:
-            runtime_pid = get_runtime_status_running_pid(local_runtime)
-            if runtime_pid is not None:
-                gateway_running = True
-                gateway_pid = runtime_pid
 
         if runtime:
             gateway_state = runtime.get("gateway_state")
@@ -4126,6 +4210,12 @@ def _recent_upstream_commits(n: int = 20) -> List[Dict[str, Any]]:
             ],
             capture_output=True,
             text=True,
+            # git log emits UTF-8 (commit subjects can carry emoji/CJK). On
+            # Windows text=True defaults to the ANSI code page — a byte like
+            # 0x90 (3rd byte of 🐛) is undefined in cp1252 and crashed the
+            # stdlib _readerthread, killing the desktop backend (#52649).
+            encoding="utf-8",
+            errors="replace",
             timeout=5,
         )
         if out.returncode != 0:
@@ -4749,6 +4839,10 @@ def get_sessions(
     try:
         db = _open_session_db_for_profile(profile)
         try:
+            # Opportunistic, config-gated, double-throttled stale-session
+            # sweep — the only auto_archive hook that fires for Desktop's
+            # `hermes serve` backend. No-op when disabled or run recently.
+            _maybe_auto_archive_for_profile(db, profile)
             min_message_count = max(0, min_messages)
             archived_only = archived == "only"
             include_archived = archived == "include"
@@ -5744,6 +5838,10 @@ def _run_setup_command(
         env=_memory_provider_setup_env(),
         capture_output=True,
         text=True,
+        # Lossy UTF-8 decode — setup tools emit UTF-8; never let a
+        # locale-mismatched byte raise in the reader thread (#52649).
+        encoding="utf-8",
+        errors="replace",
         timeout=timeout,
         check=False,
     )
@@ -6459,6 +6557,14 @@ async def get_schema(profile: Optional[str] = None):
     return {"fields": fields, "category_order": _CATEGORY_ORDER}
 
 
+@app.get("/api/egress/status")
+async def get_egress_status():
+    """Dashboard/Desktop-readable egress proxy status and remediation text."""
+    from hermes_cli.proxy_cli import format_status_text
+
+    return {"text": format_status_text()}
+
+
 _EMPTY_MODEL_INFO: dict = {
     "model": "",
     "provider": "",
@@ -6575,7 +6681,7 @@ _AUX_TASK_SLOTS: Tuple[str, ...] = (
 
 
 @app.get("/api/model/options")
-def get_model_options(
+async def get_model_options(
     profile: Optional[str] = None,
     refresh: bool = False,
     include_unconfigured: bool = False,
@@ -6597,25 +6703,21 @@ def get_model_options(
     Models" control. Normal opens leave it false to stay on the 1h cache.
     """
     try:
-        from hermes_cli.inventory import build_models_payload, load_picker_context
+        from hermes_cli.inventory import build_model_options_payload, load_picker_context
 
-        # Most desktop surfaces should only list providers the user has already
-        # configured. Onboarding opts into the full provider universe via
-        # include_unconfigured=1 so it can still render setup affordances for
-        # providers that are not yet authenticated.
-        with _profile_scope(profile):
-            return build_models_payload(
-                load_picker_context(),
-                explicit_only=bool(explicit_only),
-                include_unconfigured=bool(include_unconfigured),
-                picker_hints=True,
-                canonical_order=True,
-                pricing=True,
-                capabilities=True,
-                refresh=bool(refresh),
-                probe_custom_providers=bool(refresh),
-                probe_current_custom_provider=not bool(refresh),
-            )
+        def _build_payload_scoped() -> dict:
+            # Keep the profile override inside the worker thread so the full
+            # sync picker build (config load, pricing, refresh probes) runs
+            # off the event loop under the requested profile.
+            with _profile_scope(profile):
+                return build_model_options_payload(
+                    load_picker_context(),
+                    explicit_only=bool(explicit_only),
+                    include_unconfigured=bool(include_unconfigured),
+                    refresh=bool(refresh),
+                )
+
+        return await run_in_threadpool(_build_payload_scoped)
     except HTTPException:
         raise
     except Exception:
@@ -6783,6 +6885,8 @@ def set_moa_models(body: MoaConfigPayload, profile: Optional[str] = None):
                 "aggregator": _slot_dict(preset.aggregator),
                 "reference_temperature": preset.reference_temperature,
                 "aggregator_temperature": preset.aggregator_temperature,
+                "reference_timeout": preset.reference_timeout,
+                "degraded_reference_policy": preset.degraded_reference_policy,
                 "max_tokens": preset.max_tokens,
                 "reference_max_tokens": preset.reference_max_tokens,
                 "fanout": preset.fanout,
@@ -6804,6 +6908,8 @@ def set_moa_models(body: MoaConfigPayload, profile: Optional[str] = None):
                         aggregator=body.aggregator,
                         reference_temperature=body.reference_temperature,
                         aggregator_temperature=body.aggregator_temperature,
+                        reference_timeout=body.reference_timeout,
+                        degraded_reference_policy=body.degraded_reference_policy,
                         max_tokens=body.max_tokens,
                         reference_max_tokens=body.reference_max_tokens,
                         fanout=body.fanout,
@@ -6823,9 +6929,11 @@ def set_moa_models(body: MoaConfigPayload, profile: Optional[str] = None):
                     status_code=422,
                     detail="Invalid MoA config: " + "; ".join(problems),
                 )
-
             normalized = normalize_moa_config(raw)
-            cfg["moa"] = normalized
+            # Merge instead of overwrite so that hand-edited keys not declared
+            # in MoaConfigPayload (e.g. save_traces, trace_dir) survive a GUI
+            # save.  See issue #58819.
+            cfg.setdefault("moa", {}).update(normalized)
             save_config(cfg)
             return {"ok": True, **normalized}
     except HTTPException:
@@ -7477,6 +7585,38 @@ def _models_from_custom_endpoint_entry(entry: Dict[str, Any]) -> List[str]:
     return [model for model in models if model and not (model in seen or seen.add(model))]
 
 
+def _api_key_display(entry: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
+    """Return ``(has_api_key, preview)`` for a provider or model config block.
+
+    Keys live in ``.env`` behind ``key_env``; only entries written before
+    #69449 still carry a plaintext ``api_key``. Checking both keeps the panel
+    honest either way — reading only ``api_key`` reported "no API key" for
+    every endpoint whose key had been moved to ``.env``.
+    """
+    plaintext = str(entry.get("api_key") or "").strip()
+    if plaintext:
+        return True, redact_key(plaintext)
+    key_env = str(entry.get("key_env") or "").strip()
+    if key_env:
+        return True, f"${{{key_env}}}"
+    return False, None
+
+
+def _config_api_key_is_env_ref(endpoint_id: str) -> bool:
+    """True when this endpoint's on-disk ``api_key`` is a ``${VAR}`` template.
+
+    ``load_config()`` expands env refs, so a hand-written
+    ``api_key: ${MY_KEY}`` is indistinguishable from a literal secret by the
+    time it reaches us. Such an entry is already keeping its secret out of
+    config.yaml, so migrating it would only copy that secret into a second
+    env var the user didn't ask for.
+    """
+    providers = read_raw_config().get("providers")
+    entry = providers.get(endpoint_id) if isinstance(providers, dict) else None
+    raw_key = entry.get("api_key") if isinstance(entry, dict) else None
+    return bool(isinstance(raw_key, str) and re.search(r"\$\{[^}]+\}", raw_key))
+
+
 def _custom_endpoint_response(cfg: Dict[str, Any]) -> Dict[str, Any]:
     model_cfg = cfg.get("model", {}) if isinstance(cfg.get("model"), dict) else {}
     current_provider = str(model_cfg.get("provider", "") or "")
@@ -7495,6 +7635,7 @@ def _custom_endpoint_response(cfg: Dict[str, Any]) -> Dict[str, Any]:
             endpoint_id = str(provider_id)
             models = _models_from_custom_endpoint_entry(raw_entry)
             endpoint_model = str(raw_entry.get("model") or raw_entry.get("default_model") or (models[0] if models else ""))
+            has_api_key, api_key_preview = _api_key_display(raw_entry)
             endpoints.append({
                 "id": endpoint_id,
                 "name": str(raw_entry.get("name") or endpoint_id),
@@ -7503,13 +7644,14 @@ def _custom_endpoint_response(cfg: Dict[str, Any]) -> Dict[str, Any]:
                 "models": models,
                 "context_length": raw_entry.get("context_length"),
                 "discover_models": bool(raw_entry.get("discover_models", True)),
-                "has_api_key": bool(str(raw_entry.get("api_key", "") or "").strip()),
-                "api_key_preview": redact_key(str(raw_entry.get("api_key", "") or "")) if raw_entry.get("api_key") else None,
+                "has_api_key": has_api_key,
+                "api_key_preview": api_key_preview,
                 "is_current": endpoint_id == current_provider,
                 "source": "providers",
             })
 
     if current_provider.lower() == "custom" and current_base_url and not any(e["id"] == "custom" for e in endpoints):
+        has_api_key, api_key_preview = _api_key_display(model_cfg)
         endpoints.insert(0, {
             "id": "custom",
             "name": "Custom",
@@ -7518,8 +7660,8 @@ def _custom_endpoint_response(cfg: Dict[str, Any]) -> Dict[str, Any]:
             "models": [current_model] if current_model else [],
             "context_length": model_cfg.get("context_length"),
             "discover_models": True,
-            "has_api_key": bool(str(model_cfg.get("api_key", "") or "").strip()),
-            "api_key_preview": redact_key(str(model_cfg.get("api_key", "") or "")) if model_cfg.get("api_key") else None,
+            "has_api_key": has_api_key,
+            "api_key_preview": api_key_preview,
             "is_current": True,
             "source": "direct-config",
         })
@@ -7552,7 +7694,7 @@ def _detach_main_model_from_provider(cfg: Dict[str, Any], provider_key: str) ->
         return
     if str(model_cfg.get("provider") or "").strip().lower() != provider_key:
         return
-    for field in ("provider", "base_url", "api_key"):
+    for field in ("provider", "base_url", "api_key", "key_env"):
         model_cfg.pop(field, None)
     cfg["model"] = model_cfg
 
@@ -7594,19 +7736,47 @@ def _write_custom_endpoint(cfg: Dict[str, Any], body: CustomEndpointUpdate) -> T
         "model": model,
         "discover_models": bool(body.discover_models),
     })
-    # Same for the model map: the panel names one default model, it does not
-    # enumerate the provider's catalogue. Keep the other models (and their
-    # context lengths) and just ensure this one is present.
+    # Same for the model map: merge rather than replace, so existing models
+    # keep their context lengths. ``body.models`` is the catalogue the panel's
+    # Test button already discovered — without it only the one hand-typed
+    # model survived Save, and every picker showed a single-entry list for a
+    # provider serving dozens (#69988). A payload with no ``models`` (older
+    # UI) still just ensures the named default is present.
     existing_models = entry.get("models")
     models_map: Dict[str, Any] = dict(existing_models) if isinstance(existing_models, dict) else {}
-    current_model_entry = models_map.get(model)
-    models_map[model] = dict(current_model_entry) if isinstance(current_model_entry, dict) else {}
+    for candidate in (*(body.models or ()), model):
+        model_id = str(candidate).strip()
+        if not model_id:
+            continue
+        current = models_map.get(model_id)
+        models_map[model_id] = dict(current) if isinstance(current, dict) else {}
     entry["models"] = models_map
     if body.context_length and body.context_length > 0:
         entry["context_length"] = int(body.context_length)
         entry["models"][model]["context_length"] = int(body.context_length)
-    if body.api_key is not None and body.api_key.strip():
-        entry["api_key"] = body.api_key.strip()
+
+    # API keys never belong in config.yaml (#69449). Write to .env and
+    # reference it via ``key_env`` — the same indirection built-in providers
+    # use and that runtime_provider.py already resolves at load time.
+    env_var = custom_endpoint_key_env(endpoint_id)
+    submitted_key = body.api_key.strip() if body.api_key is not None else None
+    if submitted_key:
+        save_env_value(env_var, submitted_key)
+        entry["key_env"] = env_var
+        entry.pop("api_key", None)
+    elif submitted_key is not None:
+        # Blank field means "clear the key", not "leave it alone".
+        remove_env_value(env_var)
+        entry.pop("key_env", None)
+        entry.pop("api_key", None)
+    elif str(entry.get("api_key") or "").strip() and not _config_api_key_is_env_ref(endpoint_id):
+        # No new key submitted, but this entry still carries one an earlier
+        # release wrote in plaintext. Migrate it on the next save so endpoints
+        # configured before the fix get cleaned up too, without the user
+        # having to re-enter the key.
+        save_env_value(env_var, entry["api_key"].strip())
+        entry["key_env"] = env_var
+        entry.pop("api_key", None)
 
     providers[endpoint_id] = entry
     cfg["providers"] = providers
@@ -7615,8 +7785,9 @@ def _write_custom_endpoint(cfg: Dict[str, Any], body: CustomEndpointUpdate) -> T
         cfg["model"] = _apply_main_model_assignment(
             cfg.get("model", {}), endpoint_id, model, base_url
         )
-        if entry.get("api_key") and isinstance(cfg["model"], dict):
-            cfg["model"]["api_key"] = entry["api_key"]
+        if entry.get("key_env") and isinstance(cfg["model"], dict):
+            cfg["model"]["key_env"] = entry["key_env"]
+            cfg["model"].pop("api_key", None)
 
     return endpoint_id, entry
 
@@ -7667,7 +7838,10 @@ def activate_custom_endpoint(endpoint_id: str):
             raise HTTPException(status_code=400, detail="custom endpoint is incomplete")
 
         model_cfg = _apply_main_model_assignment(cfg.get("model", {}), provider_key, model, base_url)
-        if entry.get("api_key"):
+        if entry.get("key_env"):
+            model_cfg["key_env"] = entry["key_env"]
+            model_cfg.pop("api_key", None)
+        elif entry.get("api_key"):
             model_cfg["api_key"] = entry["api_key"]
         cfg["model"] = model_cfg
         save_config(cfg)
@@ -7691,6 +7865,7 @@ def delete_custom_endpoint(endpoint_id: str):
         providers.pop(provider_key, None)
         cfg["providers"] = providers
         _detach_main_model_from_provider(cfg, provider_key)
+        remove_env_value(custom_endpoint_key_env(provider_key))
         save_config(cfg)
         response = _custom_endpoint_response(cfg)
         response["ok"] = True
@@ -7871,7 +8046,6 @@ _PLATFORM_OVERRIDES: dict[str, dict[str, Any]] = {
         "env_vars": (
             "DISCORD_BOT_TOKEN",
             "DISCORD_ALLOWED_USERS",
-            "DISCORD_REPLY_TO_MODE",
         ),
         "required_env": ("DISCORD_BOT_TOKEN",),
     },
@@ -8310,6 +8484,14 @@ def _platform_env_prefixes(platform_id: str) -> tuple[str, ...]:
     return (platform_id.upper().replace("-", "_") + "_",)
 
 
+# Which per-platform knobs the setup UI hides, and why: see
+# hermes_cli/setup_hidden_env.py. Shared with the `hermes setup gateway`
+# wizard so the surfaces ask for the same things.
+from hermes_cli.setup_hidden_env import (  # noqa: E402
+    is_setup_hidden_env as _is_setup_hidden_env,
+)
+
+
 def _discover_platform_env_vars(platform_id: str) -> tuple[str, ...]:
     """All messaging-category env vars for a platform (override + plugin + prefix)."""
     prefixes = _platform_env_prefixes(platform_id)
@@ -8319,6 +8501,8 @@ def _discover_platform_env_vars(platform_id: str) -> tuple[str, ...]:
             continue
         if name in _MESSAGING_KEYS_PAGE_KEYS:
             continue
+        if _is_setup_hidden_env(name):
+            continue
         if not any(name.startswith(prefix) for prefix in prefixes):
             continue
         keys.append(name)
@@ -8330,10 +8514,18 @@ def _merge_platform_env_vars(
     override: dict[str, Any],
     plugin_entry: Any | None,
 ) -> tuple[str, ...]:
-    """Canonical env-var list for a messaging platform card."""
+    """Canonical env-var list for a messaging platform card.
+
+    Required credentials always survive: a platform that genuinely needs one of
+    the hidden-suffix vars to connect keeps it, since hiding a required field
+    would make the platform unconfigurable.
+    """
     discovered = _discover_platform_env_vars(platform_id)
     if "env_vars" in override:
-        return tuple(dict.fromkeys((*override["env_vars"], *discovered)))
+        explicit = tuple(
+            key for key in override["env_vars"] if not _is_setup_hidden_env(key)
+        )
+        return tuple(dict.fromkeys((*explicit, *discovered)))
     if plugin_entry is not None and plugin_entry.required_env:
         return tuple(dict.fromkeys((*tuple(plugin_entry.required_env), *discovered)))
     return discovered
@@ -8407,6 +8599,7 @@ def _messaging_platform_payload(
     env_on_disk: dict[str, str],
     runtime: dict | None,
     scoped: bool = False,
+    profile_home: Optional[Path] = None,
 ) -> dict[str, Any]:
     platform_id = entry["id"]
     runtime_platforms = runtime.get("platforms") if runtime else {}
@@ -8415,10 +8608,29 @@ def _messaging_platform_payload(
         if isinstance(runtime_platforms, dict)
         else {}
     )
-    gateway_running = (
-        get_running_pid() is not None
-        or get_runtime_status_running_pid(runtime) is not None
+    # Same shared ladder /api/status uses. Before this was unified, the two
+    # endpoints disagreed on the same page load — the sidebar strip read
+    # "running" (it probed GATEWAY_HEALTH_URL and scoped to the requested
+    # profile) while the Channels page rendered "The gateway is not running"
+    # (it did neither). Cross-container, profile-scoped, and
+    # launch-service-managed deployments each hit that split.
+    #
+    # profile_home is passed when the request was scoped to a named profile:
+    # gateway/status readers resolve process-level paths and do NOT follow the
+    # HERMES_HOME contextvar override (#56986 / #69143), so the profile's
+    # directory has to be handed over explicitly or messaging silently reports
+    # another profile's gateway (#71211).
+    liveness = resolve_gateway_liveness(
+        profile_dir=profile_home,
+        runtime=runtime,
+        health_probe=(
+            _probe_gateway_health if _GATEWAY_HEALTH_URL else None
+        ),
+        pid_probe=get_running_pid_cached,
+        runtime_reader=read_runtime_status,
+        runtime_pid_probe=get_runtime_status_running_pid,
     )
+    gateway_running = liveness.running
     env_vars = []
 
     for key in entry["env_vars"]:
@@ -8669,6 +8881,10 @@ def _ensure_whatsapp_bridge_dependencies(bridge_dir: Path) -> None:
             cwd=str(bridge_dir),
             capture_output=True,
             text=True,
+            # npm output is UTF-8; guard the Windows ANSI-code-page default
+            # against undefined bytes crashing the reader thread (#52649).
+            encoding="utf-8",
+            errors="replace",
             timeout=timeout,
             env=with_hermes_node_path(),
             creationflags=windows_hide_flags(),
@@ -9416,17 +9632,26 @@ async def cancel_telegram_onboarding(pairing_id: str):
 async def get_messaging_platforms(profile: Optional[str] = None):
     # Profile-scoped so the dashboard's global profile switcher shows the
     # TARGET profile's channel credentials/state, not the root install's.
-    # Inside _profile_scope, load_env()/read_runtime_status()/get_running_pid()
-    # all resolve against the requested profile's HERMES_HOME.
+    # load_env() honors the HERMES_HOME contextvar override; the gateway
+    # status readers do NOT (they resolve process-level paths), so the
+    # profile directory is passed explicitly for those (#71211).
     with _profile_scope(profile) as scoped_dir:
         env_on_disk = load_env()
-        runtime = read_runtime_status()
+        runtime = (
+            read_runtime_status(path=scoped_dir / "gateway_state.json")
+            if scoped_dir is not None
+            else read_runtime_status()
+        )
         return {
             "env_path": str(get_env_path()),
             "gateway_start_command": _gateway_display_command(profile, "start"),
             "platforms": [
                 _messaging_platform_payload(
-                    entry, env_on_disk, runtime, scoped=scoped_dir is not None
+                    entry,
+                    env_on_disk,
+                    runtime,
+                    scoped=scoped_dir is not None,
+                    profile_home=scoped_dir,
                 )
                 for entry in _messaging_platform_catalog()
             ]
@@ -9561,8 +9786,17 @@ async def test_messaging_platform(platform_id: str, profile: Optional[str] = Non
 
     with _profile_scope(profile) as scoped_dir:
         env_on_disk = load_env()
+        runtime = (
+            read_runtime_status(path=scoped_dir / "gateway_state.json")
+            if scoped_dir is not None
+            else read_runtime_status()
+        )
         payload = _messaging_platform_payload(
-            entry, env_on_disk, read_runtime_status(), scoped=scoped_dir is not None
+            entry,
+            env_on_disk,
+            runtime,
+            scoped=scoped_dir is not None,
+            profile_home=scoped_dir,
         )
     if not payload["enabled"]:
         message = f"{entry['name']} is disabled. Enable it, then restart the gateway."
@@ -11413,6 +11647,71 @@ def _open_session_db_for_profile(profile: Optional[str]):
     return SessionDB(db_path=Path(home) / "state.db")
 
 
+# In-process throttle for the opportunistic auto-archive trigger, keyed by
+# profile. Bounds the config.yaml read to at most once per this window per
+# profile; the actual sweep is throttled far more coarsely by state_meta
+# (sessions.min_interval_hours) inside maybe_auto_archive.
+_AUTO_ARCHIVE_CHECK_INTERVAL_S = 300.0
+_last_auto_archive_check: Dict[str, float] = {}
+
+
+def _maybe_auto_archive_for_profile(db, profile: Optional[str]) -> None:
+    """Run the config-gated stale-session auto-archive for ``profile``.
+
+    The Desktop backend is spawned as ``hermes serve`` — it runs neither the
+    interactive CLI nor the messaging gateway, so neither of those startup
+    hooks fire for Desktop users. Triggering the (double-throttled, config-off
+    by default) sweep from the session-list path is what makes
+    ``sessions.auto_archive`` take effect there. Never raises.
+    """
+    try:
+        key = profile or ""
+        now = time.monotonic()
+        last = _last_auto_archive_check.get(key)
+        if last is not None and now - last < _AUTO_ARCHIVE_CHECK_INTERVAL_S:
+            return
+        _last_auto_archive_check[key] = now
+
+        from hermes_cli.config import load_config as _load_full_config
+        cfg = (_load_full_config().get("sessions") or {})
+        if not cfg.get("auto_archive", False):
+            return
+        db.maybe_auto_archive(
+            idle_days=float(cfg.get("auto_archive_days", 3)),
+            min_interval_hours=int(cfg.get("min_interval_hours", 24)),
+        )
+    except Exception as exc:
+        _log.debug("opportunistic auto-archive skipped: %s", exc)
+
+
+async def _auto_archive_ticker_loop(
+    interval_s: float = 3600.0, initial_delay_s: float = 90.0
+) -> None:
+    """Live timer for the stale-session auto-archive (primary profile).
+
+    A long-running Desktop/serve backend must keep sweeping on schedule even
+    when no ``/api/sessions`` request arrives to fire the opportunistic
+    trigger — e.g. the app sits open for days on an idle chat. The real
+    cadence is still owned by state_meta (``sessions.min_interval_hours``)
+    inside ``maybe_auto_archive``; this loop is only the poll rate.
+    """
+
+    def _sweep() -> None:
+        db = _open_session_db_for_profile(None)
+        try:
+            _maybe_auto_archive_for_profile(db, None)
+        finally:
+            db.close()
+
+    await asyncio.sleep(initial_delay_s)
+    while True:
+        try:
+            await asyncio.to_thread(_sweep)
+        except Exception as exc:
+            _log.debug("auto-archive tick skipped: %s", exc)
+        await asyncio.sleep(interval_s)
+
+
 @app.get("/api/sessions/{session_id}")
 async def get_session_detail(session_id: str, profile: Optional[str] = None):
     db = _open_session_db_for_profile(profile)
@@ -11517,6 +11816,9 @@ async def delete_session_endpoint(session_id: str, profile: Optional[str] = None
 class SessionRename(BaseModel):
     title: Optional[str] = None
     archived: Optional[bool] = None
+    # Durable "keep" flag mirrored from the Desktop sidebar's pins; pinned
+    # sessions are exempt from the sessions.auto_archive stale sweep.
+    pinned: Optional[bool] = None
     # Mutate a session belonging to another profile (opens its state.db). Omit
     # for the current/default profile.
     profile: Optional[str] = None
@@ -11524,21 +11826,22 @@ class SessionRename(BaseModel):
 
 @app.patch("/api/sessions/{session_id}")
 async def rename_session_endpoint(session_id: str, body: SessionRename):
-    """Update a session: rename (or clear its title) and/or archive it.
+    """Update a session: rename, archive, and/or pin it.
 
     ``title`` renames (empty/null clears the title); ``archived`` soft-hides or
-    restores the session. Either field may be omitted. ``profile`` targets
-    another profile's session.
+    restores the session; ``pinned`` sets the durable keep flag (exempts the
+    session from the auto-archive sweep). Any field may be omitted. ``profile``
+    targets another profile's session.
     """
     db = _open_session_db_for_profile(body.profile)
     try:
         sid = db.resolve_session_id(session_id)
         if not sid:
             raise HTTPException(status_code=404, detail="Session not found")
-        if body.title is None and body.archived is None:
+        if body.title is None and body.archived is None and body.pinned is None:
             raise HTTPException(
                 status_code=400,
-                detail="Nothing to update; provide 'title' and/or 'archived'.",
+                detail="Nothing to update; provide 'title', 'archived', and/or 'pinned'.",
             )
         if body.title is not None:
             try:
@@ -11548,9 +11851,13 @@ async def rename_session_endpoint(session_id: str, body: SessionRename):
                 raise HTTPException(status_code=400, detail=str(e))
         if body.archived is not None:
             db.set_session_archived(sid, body.archived)
+        if body.pinned is not None:
+            db.set_session_pinned(sid, body.pinned)
         result = {"ok": True, "title": db.get_session_title(sid) or ""}
         if body.archived is not None:
             result["archived"] = bool(body.archived)
+        if body.pinned is not None:
+            result["pinned"] = bool(body.pinned)
         return result
     finally:
         db.close()
@@ -16084,6 +16391,8 @@ def _probe_docker_backend() -> tuple:
             ["docker", "info", "--format", "{{.ServerVersion}}"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=2,
         )
         if proc.returncode == 0:
diff --git a/hermes_cli/windows_ssh_runtime.py b/hermes_cli/windows_ssh_runtime.py
index b80b81e85ba..2b58e88918c 100644
--- a/hermes_cli/windows_ssh_runtime.py
+++ b/hermes_cli/windows_ssh_runtime.py
@@ -362,7 +362,7 @@ def _resolve_direct_interpreter(python_entry: str) -> tuple[str, list[str]]:
         "print(json.dumps({'base':getattr(sys,'_base_executable','') or sys.executable,"
         "'path':[p for p in sys.path if p],'root':root}))"
     )
-    out = subprocess.run([python_entry, "-c", query], capture_output=True, text=True, timeout=30)
+    out = subprocess.run([python_entry, "-c", query], capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=30)
     if out.returncode != 0:
         raise ValueError("could not resolve the base Python interpreter")
     info = json.loads(out.stdout.strip().splitlines()[-1])
@@ -437,8 +437,8 @@ def inspect_hermes(hermes_path: str) -> dict[str, Any]:
     path = os.path.abspath(hermes_path)
     if not os.path.isabs(hermes_path) or not os.path.isfile(path):
         raise ValueError("Hermes path is not an executable file")
-    version = subprocess.run([path, "--version"], capture_output=True, text=True, timeout=20)
-    help_result = subprocess.run([path, "serve", "--help"], capture_output=True, text=True, timeout=20)
+    version = subprocess.run([path, "--version"], capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=20)
+    help_result = subprocess.run([path, "serve", "--help"], capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=20)
     help_text = help_result.stdout + help_result.stderr
     return {
         "path": path,
diff --git a/hermes_constants.py b/hermes_constants.py
index 7cb52e16ca2..bbf45f4d268 100644
--- a/hermes_constants.py
+++ b/hermes_constants.py
@@ -78,7 +78,7 @@ def _warn_profile_fallback_once() -> None:
     try:
         fallback_home = _get_platform_default_hermes_home()
         active_path = fallback_home / "active_profile"
-        active = active_path.read_text().strip() if active_path.exists() else ""
+        active = active_path.read_text(encoding="utf-8").strip() if active_path.exists() else ""
     except (UnicodeDecodeError, OSError):
         active = ""
     if active and active != "default":
diff --git a/hermes_state.py b/hermes_state.py
index a4f57d32e74..32fcffac585 100644
--- a/hermes_state.py
+++ b/hermes_state.py
@@ -15,6 +15,7 @@ Key design decisions:
 """
 
 import asyncio
+import contextlib
 import json
 import logging
 import os
@@ -28,11 +29,74 @@ from pathlib import Path
 
 from agent.memory_manager import sanitize_context
 from agent.message_sanitization import _sanitize_surrogates
+from agent.skill_commands import (
+    SKILL_EXCERPT_JOINT,
+    SKILL_SCAFFOLD_SQL_LIKE,
+    describe_skill_invocation,
+)
 from hermes_constants import get_hermes_home
+from hermes_cli.sqlite_runtime import (
+    is_sqlite_wal_reset_vulnerable as _is_sqlite_wal_reset_vulnerable,
+)
 from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar
 
+try:  # Hard dependency, but tolerate scaffold-phase imports before pip install.
+    import psutil
+except ImportError:  # pragma: no cover - stripped/scaffold installs only
+    psutil = None  # type: ignore[assignment]
+
 logger = logging.getLogger(__name__)
 
+_COMPRESSION_LOCK_HOLDER_PID_RE = re.compile(r"(?:^|:)pid=(\d+)(?::|$)")
+
+
+def _compression_lock_holder_process_is_dead(holder: str) -> bool:
+    """Return True only when a structured lock holder's local PID is gone.
+
+    Compression locks are stored in a host-local SQLite database and holder
+    IDs created by ``conversation_compression`` start with ``pid=<n>``. A
+    process killed during gateway shutdown cannot release its lease, so waiting
+    for the full TTL makes every new turn repeatedly attempt compaction. Reclaim
+    only when the kernel proves that PID no longer exists; legacy/unstructured
+    holders, same-process holders, permission errors, and any probe doubt
+    remain protected until normal TTL expiry (conservative: PID reuse must
+    never steal a live lease, and a wrongly-kept lease self-heals via TTL).
+    """
+    match = _COMPRESSION_LOCK_HOLDER_PID_RE.search(holder or "")
+    if match is None:
+        return False
+    try:
+        pid = int(match.group(1))
+    except (TypeError, ValueError):
+        return False
+    if pid <= 0:
+        return False
+    if pid == os.getpid():
+        # Same-process holder (e.g. another thread's live lease): never
+        # self-reclaim — the lease refresher and release path own it.
+        return False
+    if psutil is not None:
+        try:
+            # psutil is the canonical cross-platform liveness answer
+            # (CONTRIBUTING.md "Critical rules" #1). pid_exists() reports
+            # recycled PIDs as alive — conservative, the TTL still applies.
+            return not psutil.pid_exists(pid)
+        except Exception:
+            return False  # any doubt → keep the lease until TTL expiry
+    # Scaffold-phase fallback only (psutil missing), and POSIX-only: stdlib
+    # os.kill(pid, 0) is NOT a no-op probe on Windows (bpo-14484 — sig=0 maps
+    # to CTRL_C_EVENT and can kill the target's console group). Without psutil
+    # a Windows host stays TTL-only; the lease TTL remains the recovery path.
+    if os.name == "nt":
+        return False
+    try:
+        os.kill(pid, 0)  # windows-footgun: ok — nt early-returns just above
+    except ProcessLookupError:
+        return True
+    except (PermissionError, OSError, OverflowError):
+        return False
+    return False
+
 
 def _scrub_surrogates(value: Any) -> Any:
     """Replace lone surrogates when *value* is text; pass anything else through.
@@ -71,6 +135,51 @@ def _cwd_prefix_clause(cwd_prefix: str) -> Tuple[str, List[str]]:
     return "(s.cwd = ? OR s.cwd LIKE ? OR s.cwd LIKE ?)", [prefix, f"{prefix}/%", f"{prefix}\\%"]
 
 
+# Session preview = the head of the first user message, shown wherever a
+# session has no title (sidebar rows, pickers, exports, the desktop's
+# `sessionTitle` fallback).
+#
+# A /skill invocation expands into a message that embeds the whole skill body,
+# so the plain head of it previews the SKILL's opening prose as if the user had
+# written it. Scaffolded rows therefore carry a wider excerpt so
+# ``_shape_preview`` can hand it to ``describe_skill_invocation`` and recover
+# ``/work — fix the title leak``: the whole message while it stays under the
+# budget, and head + tail (where the typed instruction lands) once it doesn't.
+_PREVIEW_HEAD_CHARS = 63
+_PREVIEW_SCAFFOLD_WINDOW = 400
+_PREVIEW_MAX_CHARS = 60
+
+_PREVIEW_CONTENT_SQL = "REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' ')"
+_PREVIEW_SCAFFOLDED_SQL = f"m.content LIKE '{SKILL_SCAFFOLD_SQL_LIKE}'"
+
+# The shared ``_preview_raw`` SELECT expression, interpolated by every listing
+# query. A scaffolded row gets a wider excerpt: the whole message while it fits
+# the budget, else head + tail (where the typed instruction lands) spliced
+# around SKILL_EXCERPT_JOINT.
+_PREVIEW_RAW_SELECT = (
+    f"CASE WHEN {_PREVIEW_SCAFFOLDED_SQL}"
+    f" AND LENGTH(m.content) > {_PREVIEW_SCAFFOLD_WINDOW * 2}"
+    f" THEN SUBSTR({_PREVIEW_CONTENT_SQL}, 1, {_PREVIEW_SCAFFOLD_WINDOW})"
+    f" || '{SKILL_EXCERPT_JOINT}'"
+    f" || SUBSTR({_PREVIEW_CONTENT_SQL}, -{_PREVIEW_SCAFFOLD_WINDOW})"
+    f" WHEN {_PREVIEW_SCAFFOLDED_SQL}"
+    f" THEN SUBSTR({_PREVIEW_CONTENT_SQL}, 1, {_PREVIEW_SCAFFOLD_WINDOW * 2})"
+    f" ELSE SUBSTR({_PREVIEW_CONTENT_SQL}, 1, {_PREVIEW_HEAD_CHARS}) END"
+)
+
+
+def _shape_preview(raw: Any) -> str:
+    """Turn a ``_preview_raw`` column into the short preview callers show."""
+    text = str(raw or "").strip()
+    if not text:
+        return ""
+    described = describe_skill_invocation(text)
+    text = described if described is not None else text.split(SKILL_EXCERPT_JOINT)[0]
+    if len(text) > _PREVIEW_MAX_CHARS:
+        return text[:_PREVIEW_MAX_CHARS] + "..."
+    return text
+
+
 # A child session counts as a /branch (kept visible, never cascade-deleted) if
 # it carries the stable marker OR the legacy end_reason heuristic holds.
 _BRANCH_CHILD_SQL = (
@@ -434,16 +543,7 @@ def is_sqlite_wal_reset_vulnerable(
     Pre-WAL libraries (< 3.7.0) cannot hit the race and are treated as safe.
     """
     info = version_info if version_info is not None else sqlite3.sqlite_version_info
-    if info < (3, 7, 0):
-        return False
-    if info >= (3, 51, 3):
-        return False
-    # Backports of the same fix on older release lines.
-    if (3, 50, 7) <= info < (3, 51, 0):
-        return False
-    if (3, 44, 6) <= info < (3, 45, 0):
-        return False
-    return True
+    return _is_sqlite_wal_reset_vulnerable(info)
 
 
 def sqlite_source_id() -> str:
@@ -480,6 +580,17 @@ def apply_wal_with_fallback(
     (prefer DELETE).  If the on-disk DB is already WAL, keep WAL and warn
     — never live-downgrade under possible concurrent openers.
 
+    This gate (#70055) is deliberately RETAINED. An earlier revision of the
+    lock-cancellation fix (#71724) reverted it on the theory that DELETE was
+    "the mode that corrupts", but that comparison was confounded: the clean
+    WAL result came from SQLite 3.53.1, which carries BOTH the WAL-reset fix
+    AND 3.51.0's defenses against close()-broken POSIX locks, so it says
+    nothing about 3.50.4.  Re-measured on the actually-bundled 3.50.4 with
+    the lock fix in place, WAL and DELETE are both clean (0/3 each) — i.e.
+    there is no evidence that WAL is safer here, and upstream still documents
+    the WAL-reset bug as real through 3.51.2 with serious consequences.  Until
+    a fixed runtime is delivered, keep new databases out of WAL.
+
     The WARNING is deduplicated per ``db_label``: repeated connections
     to the same underlying DB (e.g. kanban_db.connect() which is called
     on every kanban operation) log once per process, not once per call.
@@ -582,9 +693,9 @@ def _log_wal_reset_bug_once(
         "%s: linked SQLite %s is vulnerable to the WAL-reset corruption "
         "bug (https://sqlite.org/wal.html#walresetbug) — %s. "
         "Upgrade to SQLite 3.51.3+ (or backports 3.50.7 / 3.44.6); "
-        "`hermes update` alone may not change python-build-standalone's "
-        "embedded SQLite. See `hermes doctor`. This warning fires once "
-        "per process per database.",
+        "Hermes-managed installs can repair the embedded runtime with "
+        "`hermes update`. See `hermes doctor`. This warning fires once per "
+        "process per database.",
         db_label,
         sqlite3.sqlite_version,
         action,
@@ -679,10 +790,30 @@ def _backup_db_file(db_path: Path) -> Optional[Path]:
     Raw file copy on purpose: the DB won't open cleanly, so we preserve the
     bytes exactly for forensics / manual restore. WAL and SHM sidecars are
     copied too when present. Returns the backup path, or None on failure.
+
+    Refuses when a connection to this database is still live in the process:
+    reading the file would ``close()`` a descriptor for it and cancel that
+    connection's POSIX advisory locks (see ``hermes_cli.sqlite_safe_read``).
+    The repair path can be entered by one SessionDB while the gateway holds
+    others, so this is a real possibility rather than a theoretical one.
     """
     import datetime
     import shutil
 
+    try:
+        from hermes_cli.sqlite_safe_read import has_live_connection
+    except ImportError:
+        has_live_connection = None  # type: ignore[assignment]
+
+    if has_live_connection is not None and has_live_connection(db_path):
+        logger.error(
+            "Refusing to raw-copy %s for backup: a connection to it is still "
+            "open in this process and the copy would cancel that connection's "
+            "POSIX locks. Close all SessionDB handles first.",
+            db_path,
+        )
+        return None
+
     stamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
     backup_path = db_path.with_name(f"{db_path.name}.malformed-backup-{stamp}")
     try:
@@ -1044,6 +1175,7 @@ CREATE TABLE IF NOT EXISTS sessions (
     profile_name TEXT,
     rewind_count INTEGER NOT NULL DEFAULT 0,
     archived INTEGER NOT NULL DEFAULT 0,
+    pinned INTEGER NOT NULL DEFAULT 0,
     FOREIGN KEY (parent_session_id) REFERENCES sessions(id)
 );
 
@@ -1508,6 +1640,209 @@ END;
 """
 
 
+class CompressionSessionClosedError(RuntimeError):
+    """A durable write targeted a parent already closed by compression."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        super().__init__(
+            f"Session {session_id!r} is closed by compression; "
+            "adopt its live continuation before appending messages"
+        )
+
+
+class CompressionSessionBusyError(RuntimeError):
+    """A non-owner tried to write while compression owns the session."""
+
+
+def _connect_tracked_db(path, tracking_path=None, **kwargs):
+    """``sqlite3.connect`` that registers the open fd for lock-safety.
+
+    While a connection is live, byte-level probes of the same file are
+    refused: an ``open()``/``close()`` cancels every POSIX advisory lock this
+    process holds on it -- including a running VACUUM's EXCLUSIVE lock.
+    Released automatically on ``close()``.
+
+    The ONLY tolerated fallback is the helper being absent entirely
+    (scaffold/embed installs that ship hermes_state without hermes_cli). A
+    real connection failure must propagate: silently retrying an *untracked*
+    connect would disable the guard for the lifetime of that connection,
+    which is precisely the failure mode this module exists to prevent.
+    """
+    try:
+        from hermes_cli.sqlite_safe_read import connect_tracked
+    except ImportError:
+        logger.debug(
+            "hermes_cli.sqlite_safe_read unavailable; opening %s untracked "
+            "(byte-probe guard inactive in this install)",
+            path,
+        )
+        return sqlite3.connect(str(path), **kwargs)
+
+    # Open through THIS module's sqlite3.connect so callers (and tests) that
+    # patch hermes_state.sqlite3.connect keep control of connection creation;
+    # the helper still owns tracking.
+    return connect_tracked(
+        path,
+        tracking_path=tracking_path,
+        connect_fn=sqlite3.connect,
+        **kwargs,
+    )
+
+
+def is_zeroed_state_db(
+    path: Path, *, probe_bytes: int = 100, force: bool = False
+) -> bool:
+    """Detect the #68474 zeroed state.db signature (size>0, NUL header).
+
+    Byte-level probe, so it is only safe BEFORE any connection to *path*
+    exists in this process: ``close()`` cancels every POSIX advisory lock the
+    process holds on the file, which can pull the EXCLUSIVE lock out from
+    under a running VACUUM and corrupt the database. The read is routed
+    through ``read_header_bytes_preopen``, which refuses (returning False
+    here) once a connection is live. Pass ``force=True`` only for offline
+    files -- quarantined copies, snapshots, archives.
+
+    Prefer ``hermes_cli.backup.is_zeroed_sqlite_file`` when available; this
+    local copy keeps SessionDB openable without importing the CLI package
+    in constrained embed paths.
+    """
+    try:
+        from hermes_cli.backup import is_zeroed_sqlite_file
+
+        return is_zeroed_sqlite_file(path, probe_bytes=probe_bytes, force=force)
+    except Exception:
+        pass
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return False
+    if size <= 0:
+        return False
+    from hermes_cli.sqlite_safe_read import read_header_bytes_preopen
+
+    head = read_header_bytes_preopen(
+        path, length=max(16, probe_bytes), force=force
+    )
+    if not head or head.startswith(b"SQLite format 3"):
+        return False
+    return all(byte == 0 for byte in head)
+
+
+def quarantine_zeroed_state_db(path: Path) -> Optional[Path]:
+    """Move a zeroed state.db aside (preserve bytes) and return quarantine path.
+
+    Uses a cross-process lock (``#68805``) so two concurrent startups cannot
+    race: the first process moves the zeroed file and the second re-checks
+    under the lock, finding the file already gone (or a fresh DB in its place)
+    instead of clobbering the quarantine.
+    """
+    import platform
+
+    lock_path = path.with_name(path.name + ".quarantine.lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = lock_path.open("a+b")
+    acquired = False
+    try:
+        deadline = time.monotonic() + 5.0
+        if platform.system() == "Windows":
+            import msvcrt
+            while True:
+                try:
+                    handle.seek(0)
+                    msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+                    acquired = True
+                    break
+                except OSError:
+                    if time.monotonic() >= deadline:
+                        break
+                    time.sleep(0.020)
+        else:
+            import fcntl
+            while True:
+                try:
+                    fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    acquired = True
+                    break
+                except (BlockingIOError, OSError):
+                    if time.monotonic() >= deadline:
+                        break
+                    time.sleep(0.020)
+        if not acquired:
+            # Fail closed: do NOT proceed without the lock. A slow or paused
+            # startup that still owns the lock can overlap this fallback and
+            # the two processes can act on the same live file (#68805 review).
+            logger.error(
+                "quarantine lock for %s not acquired within 5s — refusing to "
+                "quarantine without the cross-process lock. The zeroed file "
+                "is left in place. If sessions fail to load, restore from "
+                "state-snapshots via `hermes snapshot list` / "
+                "`hermes snapshot restore <id>`.",
+                path,
+            )
+            return None
+        # Re-check under the lock: another process may have already quarantined
+        # the file, leaving a fresh DB (or no file at all) in its place.
+        if not path.exists():
+            logger.info(
+                "quarantine_zeroed_state_db: %s already moved by another process",
+                path,
+            )
+            return None
+        if not is_zeroed_state_db(path):
+            logger.info(
+                "quarantine_zeroed_state_db: %s is no longer zeroed (another "
+                "process quarantined it and a fresh DB was created)",
+                path,
+            )
+            return None
+
+        try:
+            ts = time.strftime("%Y%m%d-%H%M%S")
+        except Exception:
+            ts = "unknown"
+        # Unique destination with PID suffix to avoid collision across
+        # concurrent startups that somehow both enter the lock.
+        dest = path.with_name(
+            f"{path.name}.zeroed-{ts}-{os.getpid()}.bak"
+        )
+        # Non-clobbering: if dest somehow exists, append a counter.
+        n = 0
+        while dest.exists():
+            n += 1
+            dest = path.with_name(
+                f"{path.name}.zeroed-{ts}-{os.getpid()}-{n}.bak"
+            )
+        try:
+            path.rename(dest)
+        except OSError as exc:
+            logger.error("Failed to quarantine zeroed %s: %s", path, exc)
+            return None
+        # Also move empty WAL/SHM if present so a fresh open is clean
+        for suffix in ("-wal", "-shm"):
+            side = Path(str(path) + suffix)
+            if side.exists():
+                try:
+                    side.rename(Path(str(dest) + suffix))
+                except OSError:
+                    pass
+        return dest
+    finally:
+        try:
+            if acquired:
+                if platform.system() == "Windows":
+                    import msvcrt
+                    handle.seek(0)
+                    msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+                else:
+                    import fcntl
+                    fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        except (OSError, AttributeError):
+            pass
+        finally:
+            handle.close()
+
+
 class SessionDB:
     """
     SQLite-backed session storage with FTS5 search.
@@ -1582,8 +1917,9 @@ class SessionDB:
                 # must already exist + be initialised (callers guard on
                 # db_path.exists()); a SELECT against an empty file raises and
                 # the caller degrades per-profile.
-                self._conn = sqlite3.connect(
+                self._conn = _connect_tracked_db(
                     f"file:{self.db_path}?mode=ro",
+                    tracking_path=self.db_path,
                     uri=True,
                     check_same_thread=False,
                     timeout=1.0,
@@ -1594,8 +1930,37 @@ class SessionDB:
 
             self.db_path.parent.mkdir(parents=True, exist_ok=True)
 
+            # #68474: zeroed state.db (size>0, all-NUL header) used to fail as a
+            # generic "file is not a database" with no recovery path. Quarantine
+            # the bytes (do not delete) and continue so a fresh DB can open;
+            # point the operator at pre-update snapshots.
+            if (
+                not read_only
+                and self.db_path.exists()
+                and is_zeroed_state_db(self.db_path)
+            ):
+                try:
+                    zsize = self.db_path.stat().st_size
+                except OSError:
+                    zsize = -1
+                qpath = quarantine_zeroed_state_db(self.db_path)
+                snaps = self.db_path.parent / "state-snapshots"
+                msg = (
+                    f"state.db looks ZEROED ({zsize} bytes, no SQLite header). "
+                    f"Preserved at {qpath or '(quarantine failed — file left in place)'}. "
+                    f"Restore from {snaps} via `hermes snapshot list` / "
+                    f"`hermes snapshot restore <id>` if available. "
+                    "Opening a fresh empty database so the agent can start."
+                )
+                logger.error(msg)
+                _set_last_init_error(msg)
+                # If quarantine failed, do not open the zeroed file (would fail
+                # opaquely or risk further damage). Raise with the clear message.
+                if qpath is None and self.db_path.exists() and is_zeroed_state_db(self.db_path):
+                    raise sqlite3.DatabaseError(msg)
+
             def _connect_and_init():
-                self._conn = sqlite3.connect(
+                self._conn = _connect_tracked_db(
                     str(self.db_path),
                     check_same_thread=False,
                     # Short timeout — application-level retry with random
@@ -2744,6 +3109,21 @@ class SessionDB:
                 # reclaimed until a later VACUUM. Non-fatal.
                 logger.warning("VACUUM after FTS optimize failed: %s", exc)
                 vacuum_ok = False
+            # Best-effort: fold the WAL back into the main file so the on-disk
+            # size settles now rather than at close(). NOTE this is REFUSED
+            # (SQLITE_BUSY) while any other connection holds a WAL read-mark —
+            # e.g. a live gateway sharing the DB — so it is not sufficient on
+            # its own. Callers must therefore NOT size the result by stat()ing
+            # the file; use :meth:`logical_size_bytes`, which is truthful
+            # immediately regardless of readers.
+            try:
+                with self._lock:
+                    self._conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+            except Exception as exc:
+                logger.debug(
+                    "WAL checkpoint (TRUNCATE) after optimize VACUUM failed: %s",
+                    exc,
+                )
 
         # Phase 4: stamp the FTS storage layout as current, clear the "available"
         # flag, and advance schema_version if it was somehow still behind (the
@@ -3330,13 +3710,15 @@ class SessionDB:
 
         When ``parent_session_id`` is set (compression fork, delegate/subagent
         spawn, branch continuation) and this row's own ``cwd``/``git_repo_root``/
-        ``git_branch`` are still NULL after the insert, they are backfilled from
-        the parent row. Callers of ``create_session`` for a child session
-        historically didn't propagate these fields themselves (e.g. the
+        ``git_branch``/``profile_name`` are still NULL after the insert, they are
+        backfilled from the parent row. Callers of ``create_session`` for a child
+        session historically didn't propagate these fields themselves (e.g. the
         compression-fork path), so a lineage could silently lose its working
         directory and drop out of the project sidebar every time it forked
-        (#64709). This only fills NULLs — an explicit ``cwd``/``git_repo_root``
-        on the child is never overwritten. For compression forks specifically
+        (#64709), or lose its owning profile and be aggregated as "default" every
+        time it rotated or branched (the cross-profile session-jump bug). This
+        only fills NULLs — an explicit value on the child is never overwritten.
+        For compression forks specifically
         (parent ended with ``end_reason='compression'``), the gateway origin
         columns (``user_id``/``session_key``/``chat_id``/``chat_type``/
         ``thread_id``/``display_name``/``origin_json``) are inherited too, so a
@@ -3392,7 +3774,10 @@ class SessionDB:
                                              WHERE p.id = sessions.parent_session_id)),
                            git_branch = COALESCE(sessions.git_branch,
                                         (SELECT p.git_branch FROM sessions p
-                                          WHERE p.id = sessions.parent_session_id))
+                                          WHERE p.id = sessions.parent_session_id)),
+                           profile_name = COALESCE(sessions.profile_name,
+                                          (SELECT p.profile_name FROM sessions p
+                                            WHERE p.id = sessions.parent_session_id))
                      WHERE id = ? AND parent_session_id IS NOT NULL""",
                     (session_id,),
                 )
@@ -3788,6 +4173,146 @@ class SessionDB:
             ).fetchone()
         return dict(row) if row else None
 
+    def find_live_compression_child(
+        self, parent_session_id: str
+    ) -> Optional[Dict[str, Any]]:
+        """Return the unique live direct child of a compression-ended session.
+
+        A stale agent may observe that another compression path already rotated
+        its parent. Recovery is safe only when the durable lineage identifies
+        exactly one live direct continuation. Multiple children are treated as
+        ambiguous and fail closed rather than guessing which transcript owns
+        subsequent messages.
+        """
+        if not parent_session_id:
+            return None
+        with self._lock:
+            parent = self._conn.execute(
+                "SELECT ended_at, end_reason FROM sessions WHERE id = ?",
+                (parent_session_id,),
+            ).fetchone()
+            if (
+                parent is None
+                or parent["ended_at"] is None
+                or parent["end_reason"] != "compression"
+            ):
+                return None
+            rows = self._conn.execute(
+                """
+                SELECT * FROM sessions
+                WHERE parent_session_id = ?
+                  AND ended_at IS NULL
+                  AND json_extract(COALESCE(model_config, '{}'), '$._branched_from') IS NULL
+                  AND json_extract(COALESCE(model_config, '{}'), '$._delegate_from') IS NULL
+                  AND COALESCE(source, '') != 'tool'
+                ORDER BY started_at ASC
+                LIMIT 2
+                """,
+                (parent_session_id,),
+            ).fetchall()
+        return dict(rows[0]) if len(rows) == 1 else None
+
+    def publish_compression_child(
+        self,
+        *,
+        parent_session_id: str,
+        child_session_id: str,
+        source: str,
+        messages: List[Dict[str, Any]],
+        model: str = None,
+        model_config: Dict[str, Any] = None,
+        system_prompt: str = None,
+        cwd: str = None,
+        profile_name: str = None,
+        compression_lock_holder: str = None,
+        require_compression_lease: bool = True,
+    ) -> None:
+        """Atomically close a parent and publish its durable compression child.
+
+        The parent closure, child row, and compacted handoff become visible in
+        one transaction. Readers can therefore observe either the live parent or
+        a complete child, never an ended parent with a missing/empty child.
+        """
+        def _do(conn):
+            lock_row = conn.execute(
+                "SELECT holder, expires_at FROM compression_locks WHERE session_id = ?",
+                (parent_session_id,),
+            ).fetchone()
+            if require_compression_lease and (
+                lock_row is None
+                or not compression_lock_holder
+                or lock_row["holder"] != compression_lock_holder
+                or float(lock_row["expires_at"]) <= time.time()
+            ):
+                raise CompressionSessionBusyError(
+                    f"Compression lease lost before publication: {parent_session_id}"
+                )
+            parent = conn.execute(
+                """SELECT ended_at, cwd, git_branch, git_repo_root,
+                          user_id, session_key, chat_id, chat_type,
+                          thread_id, display_name, origin_json, profile_name
+                   FROM sessions WHERE id = ?""",
+                (parent_session_id,),
+            ).fetchone()
+            if parent is None:
+                raise RuntimeError(f"Compression parent not found: {parent_session_id}")
+            if parent["ended_at"] is not None:
+                raise RuntimeError(f"Compression parent already ended: {parent_session_id}")
+            if not messages:
+                raise RuntimeError("Compression child handoff must not be empty")
+
+            conn.execute(
+                """INSERT INTO sessions (
+                   id, source, model, model_config, system_prompt,
+                   parent_session_id, cwd, git_branch, git_repo_root,
+                   profile_name, user_id, session_key, chat_id, chat_type,
+                   thread_id, display_name, origin_json, started_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                (
+                    child_session_id,
+                    source,
+                    model,
+                    json.dumps(model_config) if model_config else None,
+                    system_prompt,
+                    parent_session_id,
+                    cwd or parent["cwd"],
+                    parent["git_branch"],
+                    parent["git_repo_root"],
+                    # Same inheritance contract as _insert_session_row's
+                    # compression-fork backfill (#59527 / cross-profile jump
+                    # fix): the child stays on the parent's profile and keeps
+                    # the gateway routing/origin columns so peer recovery
+                    # still works after a crash at the boundary.
+                    profile_name or parent["profile_name"],
+                    parent["user_id"],
+                    parent["session_key"],
+                    parent["chat_id"],
+                    parent["chat_type"],
+                    parent["thread_id"],
+                    parent["display_name"],
+                    parent["origin_json"],
+                    time.time(),
+                ),
+            )
+            total_messages, total_tool_calls = self._insert_message_rows(
+                conn, child_session_id, messages
+            )
+            conn.execute(
+                "UPDATE sessions SET message_count = ?, tool_call_count = ? WHERE id = ?",
+                (total_messages, total_tool_calls, child_session_id),
+            )
+            updated = conn.execute(
+                "UPDATE sessions SET ended_at = ?, end_reason = 'compression' "
+                "WHERE id = ? AND ended_at IS NULL",
+                (time.time(), parent_session_id),
+            )
+            if updated.rowcount != 1:
+                raise RuntimeError(
+                    f"Compression parent changed during publication: {parent_session_id}"
+                )
+
+        self._execute_write(_do)
+
     def end_session(self, session_id: str, end_reason: str) -> None:
         """Mark a session as ended.
 
@@ -4115,7 +4640,24 @@ class SessionDB:
         holder: str,
         ttl_seconds: float = 300.0,
     ) -> bool:
-        """Extend the compression lock lease if ``holder`` still owns it."""
+        """Extend the compression lock lease if ``holder`` still owns it.
+
+        Ownership is decided by the ``holder`` column alone, deliberately NOT
+        by ``expires_at``: a live owner whose refresher thread was starved
+        (GC pause, loaded CI runner, a slow write escaping ``_execute_write``'s
+        retry budget) past its own TTL must be able to revive its still-unclaimed
+        row on the next tick. Requiring ``expires_at >= now`` here made such a
+        stall permanent — every later refresh matched 0 rows, so the owner kept
+        compressing and rotating with no lease at all, which is exactly the
+        unprotected window a competing path can fork the session lineage in.
+
+        This does not resurrect a lock somebody else already took: SQLite
+        serialises writes, so a reclaim (DELETE-expired + INSERT-or-IGNORE in
+        :meth:`try_acquire_compression_lock`) and this UPDATE never interleave.
+        Reclaim-first replaces ``holder``, so this UPDATE matches nothing and
+        returns False; refresh-first pushes ``expires_at`` into the future, so
+        the reclaimer's DELETE-expired matches nothing and its acquire fails.
+        """
         if not session_id or not holder:
             return False
         now = time.time()
@@ -4124,8 +4666,8 @@ class SessionDB:
         def _do(conn):
             cur = conn.execute(
                 "UPDATE compression_locks SET expires_at = ? "
-                "WHERE session_id = ? AND holder = ? AND expires_at >= ?",
-                (expires_at, session_id, holder, now),
+                "WHERE session_id = ? AND holder = ?",
+                (expires_at, session_id, holder),
             )
             return cur.rowcount > 0
 
@@ -4152,10 +4694,10 @@ class SessionDB:
         MUST NOT proceed with compression in that case (its rotation would
         race against the holder's, splitting the session lineage).
 
-        Expired locks (``expires_at < now``) are reclaimed transparently:
-        the stale row is deleted and the new holder acquires it. This
-        prevents a crashed compressor from permanently blocking the
-        session.
+        Expired locks (``expires_at < now``) are reclaimed transparently.
+        Structured holders whose local ``pid=`` no longer exists are reclaimed
+        immediately, so a gateway killed during compression does not stall the
+        replacement process for the full lease TTL.
 
         Implementation: single-transaction DELETE-expired + INSERT-or-IGNORE,
         followed by a SELECT to confirm we got the row. SQLite serialises
@@ -4167,12 +4709,29 @@ class SessionDB:
         expires_at = now + ttl_seconds
 
         def _do(conn):
-            # First: reclaim any expired lock for this session_id.
-            conn.execute(
-                "DELETE FROM compression_locks "
-                "WHERE session_id = ? AND expires_at < ?",
-                (session_id, now),
-            )
+            reclaimed_holder = None
+            row = conn.execute(
+                "SELECT holder, expires_at FROM compression_locks "
+                "WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            if row is not None:
+                current_holder = (
+                    row["holder"] if isinstance(row, sqlite3.Row) else row[0]
+                )
+                current_expires_at = (
+                    row["expires_at"] if isinstance(row, sqlite3.Row) else row[1]
+                )
+                if (
+                    current_expires_at < now
+                    or _compression_lock_holder_process_is_dead(current_holder)
+                ):
+                    conn.execute(
+                        "DELETE FROM compression_locks "
+                        "WHERE session_id = ? AND holder = ?",
+                        (session_id, current_holder),
+                    )
+                    reclaimed_holder = current_holder
             # Then: try to insert. INSERT OR IGNORE returns no rowcount
             # difference — verify ownership via SELECT.
             conn.execute(
@@ -4185,12 +4744,21 @@ class SessionDB:
                 "SELECT holder FROM compression_locks WHERE session_id = ?",
                 (session_id,),
             ).fetchone()
-            return row is not None and (
+            acquired = row is not None and (
                 row["holder"] if isinstance(row, sqlite3.Row) else row[0]
             ) == holder
+            return acquired, reclaimed_holder
 
         try:
-            return bool(self._execute_write(_do))
+            acquired, reclaimed_holder = self._execute_write(_do)
+            if reclaimed_holder:
+                logger.warning(
+                    "Reclaimed stale compression lock for session=%s "
+                    "(holder=%s)",
+                    session_id,
+                    reclaimed_holder,
+                )
+            return bool(acquired)
         except sqlite3.Error as exc:
             logger.warning(
                 "try_acquire_compression_lock(%s) failed: %s",
@@ -4277,14 +4845,81 @@ class SessionDB:
         Unlike ``update_token_counts`` which uses ``COALESCE(model, ?)``
         (only filling in NULL), this unconditionally sets the model column
         so that the dashboard reflects the user's latest /model choice.
+        Also nulls ``system_prompt`` so stale ``Model:`` / ``Provider:``
+        footer metadata is rebuilt on the next turn. A successful /model
+        switch explicitly replaces any confirmed Browser runtime lock while
+        preserving unrelated lineage markers in ``model_config``.
         """
         def _do(conn):
             conn.execute(
-                "UPDATE sessions SET model = ? WHERE id = ?",
+                """UPDATE sessions SET
+                   model = ?,
+                   model_config = CASE
+                       WHEN model_config IS NULL THEN NULL
+                       WHEN json_valid(model_config)
+                           THEN json_remove(model_config, '$.browser_model_lock')
+                       ELSE model_config
+                   END,
+                   system_prompt = NULL
+                   WHERE id = ?""",
                 (model, session_id),
             )
         self._execute_write(_do)
 
+    def update_session_runtime_lock(
+        self,
+        session_id: str,
+        *,
+        model: Optional[str] = None,
+        provider: Optional[str] = None,
+        model_options: Optional[Dict[str, Any]] = None,
+        route_source: Optional[str] = None,
+        confirmed: bool = False,
+    ) -> None:
+        """Persist a Browser / API client runtime lock without clobbering lineage markers.
+
+        Merges ``browser_model_lock`` into the existing ``model_config`` JSON so
+        ``_branched_from`` / ``_delegate_from`` survive. Nulls ``system_prompt``
+        so cached ``Model:`` / ``Provider:`` footers cannot lie after a switch.
+        """
+        lock = {
+            "provider": provider or "",
+            "model": model or "",
+            "model_options": model_options or {},
+            "route_source": route_source or "",
+            "confirmed": bool(confirmed),
+            "updated_at": time.time(),
+        }
+
+        def _do(conn):
+            row = conn.execute(
+                "SELECT model_config FROM sessions WHERE id = ?",
+                (session_id,),
+            ).fetchone()
+            if row is None:
+                return
+            raw = row["model_config"] if isinstance(row, sqlite3.Row) else row[0]
+            config: Dict[str, Any] = {}
+            if isinstance(raw, str) and raw.strip():
+                try:
+                    parsed = json.loads(raw)
+                    if isinstance(parsed, dict):
+                        config = parsed
+                except Exception:
+                    config = {}
+            elif isinstance(raw, dict):
+                config = dict(raw)
+            config["browser_model_lock"] = lock
+            conn.execute(
+                """UPDATE sessions SET
+                   model_config = ?,
+                   model = COALESCE(?, model),
+                   system_prompt = NULL
+                   WHERE id = ?""",
+                (json.dumps(config), model, session_id),
+            )
+        self._execute_write(_do)
+
     def update_session_billing_route(
         self,
         session_id: str,
@@ -4986,6 +5621,58 @@ class SessionDB:
         rowcount = self._execute_write(_do)
         return rowcount > 0
 
+    def set_session_pinned(self, session_id: str, pinned: bool) -> bool:
+        """Pin or unpin a session (and its whole compression lineage).
+
+        ``pinned`` is a durable "keep" flag: pinned sessions are exempt from
+        the ``sessions.auto_archive`` stale sweep (see
+        :meth:`archive_stale_sessions`). Desktop is the current writer — its
+        sidebar pins mirror here so a backend/other-surface sweep honours
+        them. Like :meth:`set_session_archived` the whole compression chain is
+        flipped as a unit, so pinning the surfaced tip protects the root (and
+        vice-versa) no matter which id the caller holds. Returns True when at
+        least one row changed.
+        """
+        def _do(conn):
+            cursor = conn.execute(
+                """
+                WITH RECURSIVE
+                  ancestors(id) AS (
+                    SELECT ?
+                    UNION
+                    SELECT parent.id
+                    FROM ancestors a
+                    JOIN sessions child ON child.id = a.id
+                    JOIN sessions parent ON parent.id = child.parent_session_id
+                    WHERE parent.end_reason = 'compression'
+                  ),
+                  descendants(id) AS (
+                    SELECT ?
+                    UNION
+                    SELECT child.id
+                    FROM descendants d
+                    JOIN sessions parent ON parent.id = d.id
+                    JOIN sessions child ON child.parent_session_id = parent.id
+                    WHERE parent.end_reason = 'compression'
+                  ),
+                  lineage(id) AS (
+                    SELECT id FROM ancestors
+                    UNION
+                    SELECT id FROM descendants
+                  )
+                UPDATE sessions
+                SET pinned = ?
+                WHERE id IN (SELECT id FROM lineage)
+                """,
+                (session_id, session_id, 1 if pinned else 0),
+            )
+            rowcount = cursor.rowcount
+            if rowcount is None or rowcount < 0:
+                rowcount = conn.execute("SELECT changes()").fetchone()[0]
+            return rowcount
+        rowcount = self._execute_write(_do)
+        return rowcount > 0
+
     def get_session_by_title(self, title: str) -> Optional[Dict[str, Any]]:
         """Look up a session by exact title. Returns session dict or None."""
         with self._lock:
@@ -5368,7 +6055,7 @@ class SessionDB:
                 )
                 SELECT {_sel},
                     COALESCE(
-                        (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63)
+                        (SELECT {_PREVIEW_RAW_SELECT}
                          FROM messages m
                          WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
                          ORDER BY m.timestamp, m.id LIMIT 1),
@@ -5393,7 +6080,7 @@ class SessionDB:
             query = f"""
                 SELECT {_sel},
                     COALESCE(
-                        (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63)
+                        (SELECT {_PREVIEW_RAW_SELECT}
                          FROM messages m
                          WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
                          ORDER BY m.timestamp, m.id LIMIT 1),
@@ -5415,13 +6102,7 @@ class SessionDB:
         sessions = []
         for row in rows:
             s = dict(row)
-            # Build the preview from the raw substring
-            raw = s.pop("_preview_raw", "").strip()
-            if raw:
-                text = raw[:60]
-                s["preview"] = text + ("..." if len(raw) > 60 else "")
-            else:
-                s["preview"] = ""
+            s["preview"] = _shape_preview(s.pop("_preview_raw", ""))
             # Drop the internal ordering column so callers see a clean dict.
             s.pop("_effective_last_active", None)
             sessions.append(s)
@@ -5494,10 +6175,10 @@ class SessionDB:
         # compute it generically rather than hardcoding the successor char.
         prefix_hi = prefix[:-1] + chr(ord(prefix[-1]) + 1)
 
-        query = """
+        query = f"""
             SELECT s.*,
                 COALESCE(
-                    (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63)
+                    (SELECT {_PREVIEW_RAW_SELECT}
                      FROM messages m
                      WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
                      ORDER BY m.timestamp, m.id LIMIT 1),
@@ -5519,12 +6200,7 @@ class SessionDB:
         runs: List[Dict[str, Any]] = []
         for row in rows:
             s = dict(row)
-            raw = s.pop("_preview_raw", "").strip()
-            if raw:
-                text = raw[:60]
-                s["preview"] = text + ("..." if len(raw) > 60 else "")
-            else:
-                s["preview"] = ""
+            s["preview"] = _shape_preview(s.pop("_preview_raw", ""))
             runs.append(s)
         return runs
 
@@ -5540,7 +6216,7 @@ class SessionDB:
         query = f"""
             SELECT {_sel},
                 COALESCE(
-                    (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63)
+                    (SELECT {_PREVIEW_RAW_SELECT}
                      FROM messages m
                      WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
                      ORDER BY m.timestamp, m.id LIMIT 1),
@@ -5559,14 +6235,54 @@ class SessionDB:
         if not row:
             return None
         s = dict(row)
-        raw = s.pop("_preview_raw", "").strip()
-        if raw:
-            text = raw[:60]
-            s["preview"] = text + ("..." if len(raw) > 60 else "")
-        else:
-            s["preview"] = ""
+        s["preview"] = _shape_preview(s.pop("_preview_raw", ""))
         return s
 
+    def list_skill_scaffolded_sessions(self, limit: int = 200) -> List[Dict[str, Any]]:
+        """Titled sessions whose first user turn was a ``/skill`` invocation.
+
+        Those titles were generated from the expanded message, which embeds the
+        whole skill body — so they describe the skill rather than the request.
+        Returns ``id``, ``title``, and the full first-turn ``content`` so a
+        caller can re-derive what the user typed. Newest first.
+        """
+        with self._lock:
+            rows = self._conn.execute(
+                """
+                SELECT s.id, s.title, m.content
+                FROM sessions s
+                JOIN messages m ON m.id = (
+                    SELECT m2.id FROM messages m2
+                    WHERE m2.session_id = s.id AND m2.role = 'user'
+                      AND m2.content IS NOT NULL
+                    ORDER BY m2.timestamp, m2.id LIMIT 1
+                )
+                WHERE s.title IS NOT NULL AND m.content LIKE ?
+                ORDER BY s.started_at DESC
+                LIMIT ?
+                """,
+                (SKILL_SCAFFOLD_SQL_LIKE, int(limit)),
+            ).fetchall()
+        return [dict(row) for row in rows]
+
+    def get_first_assistant_text(self, session_id: str) -> str:
+        """The session's first assistant reply as plain text ('' when none).
+
+        Pairs with :meth:`list_skill_scaffolded_sessions` so a re-title can feed
+        the titler the same (request, reply) shape the live path uses.
+        """
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT content FROM messages "
+                "WHERE session_id = ? AND role = 'assistant' AND content IS NOT NULL "
+                "ORDER BY timestamp, id LIMIT 1",
+                (session_id,),
+            ).fetchone()
+        if not row:
+            return ""
+        decoded = self._decode_content(row["content"])
+        return decoded if isinstance(decoded, str) else ""
+
     # =========================================================================
     # Message storage
     # =========================================================================
@@ -5626,6 +6342,58 @@ class SessionDB:
                 return content
         return content
 
+    @staticmethod
+    def _encode_display_metadata(display_metadata: Any) -> Optional[str]:
+        """Serialize ``display_metadata`` for its TEXT column without double-encoding.
+
+        Import/replace paths can hand us an already-serialized JSON string (the
+        same hazard ``tool_calls`` guards against above). ``json.dumps`` on that
+        string would store a quoted JSON string, and the single ``json.loads``
+        on read then yields a ``str`` instead of a dict.
+        """
+        if not display_metadata:
+            return None
+        if isinstance(display_metadata, str):
+            try:
+                parsed = json.loads(display_metadata)
+            except (json.JSONDecodeError, TypeError):
+                logger.warning("Ignoring non-JSON display metadata on write")
+                return None
+            if not isinstance(parsed, dict):
+                logger.warning("Ignoring non-object display metadata on write")
+                return None
+            return json.dumps(parsed)
+        if isinstance(display_metadata, dict):
+            return json.dumps(display_metadata)
+        logger.warning(
+            "Ignoring unexpected display metadata type on write: %s",
+            type(display_metadata).__name__,
+        )
+        return None
+
+    @staticmethod
+    def _decode_display_metadata(raw: Any) -> Optional[Dict[str, Any]]:
+        """Decode a ``display_metadata`` column into the dict every reader expects.
+
+        Every message read path must go through this. Returning the raw TEXT
+        instead reaches the desktop as a string, where ``'task_count' in meta``
+        throws and fails the whole resume. Rows written before the encode guard
+        landed are double-encoded, so unwrap a second layer when we find one.
+        """
+        if raw is None:
+            return None
+        try:
+            meta = json.loads(raw) if isinstance(raw, str) else raw
+            if isinstance(meta, str):
+                meta = json.loads(meta)
+        except (json.JSONDecodeError, TypeError):
+            logger.warning("Ignoring invalid display metadata on message row")
+            return None
+        if not isinstance(meta, dict):
+            logger.warning("Ignoring non-object display metadata on message row")
+            return None
+        return meta
+
     def append_message(
         self,
         session_id: str,
@@ -5648,6 +6416,7 @@ class SessionDB:
         api_content: Optional[str] = None,
         display_kind: Optional[str] = None,
         display_metadata: Optional[Dict[str, Any]] = None,
+        compression_lock_holder: Optional[str] = None,
     ) -> int:
         """
         Append a message to a session. Returns the message row ID.
@@ -5671,7 +6440,7 @@ class SessionDB:
         """
         # Display metadata is presentation-only and never changes the model
         # context role/content replayed to providers.
-        display_metadata_json = json.dumps(display_metadata) if display_metadata else None
+        display_metadata_json = self._encode_display_metadata(display_metadata)
         # Serialize structured fields to JSON before entering the write txn
         reasoning_details_json = (
             json.dumps(reasoning_details)
@@ -5714,6 +6483,28 @@ class SessionDB:
             num_tool_calls = len(tool_calls) if isinstance(tool_calls, list) else 1
 
         def _do(conn):
+            active_lock = conn.execute(
+                "SELECT holder FROM compression_locks "
+                "WHERE session_id = ? AND expires_at > ?",
+                (session_id, time.time()),
+            ).fetchone()
+            if (
+                active_lock is not None
+                and active_lock["holder"] != compression_lock_holder
+            ):
+                raise CompressionSessionBusyError(
+                    f"Session {session_id!r} is being compressed by another writer"
+                )
+            session = conn.execute(
+                "SELECT ended_at, end_reason FROM sessions WHERE id = ?",
+                (session_id,),
+            ).fetchone()
+            if (
+                session is not None
+                and session["ended_at"] is not None
+                and session["end_reason"] == "compression"
+            ):
+                raise CompressionSessionClosedError(session_id)
             cursor = conn.execute(
                 """INSERT INTO messages (session_id, role, content, tool_call_id,
                    tool_calls, tool_name, effect_disposition, timestamp, token_count, finish_reason,
@@ -5788,7 +6579,7 @@ class SessionDB:
                 "UPDATE messages SET display_kind = ?, display_metadata = ? WHERE id = ?",
                 (
                     _scrub_surrogates(display_kind),
-                    json.dumps(display_metadata) if display_metadata else None,
+                    self._encode_display_metadata(display_metadata),
                     row[0],
                 ),
             )
@@ -5882,7 +6673,7 @@ class SessionDB:
                     1,
                     _scrub_surrogates(api_content) if isinstance(api_content, str) else None,
                     _scrub_surrogates(msg.get("display_kind")) if isinstance(msg.get("display_kind"), str) else None,
-                    json.dumps(msg["display_metadata"]) if msg.get("display_metadata") else None,
+                    self._encode_display_metadata(msg.get("display_metadata")),
                 ),
             )
             inserted += 1
@@ -5923,6 +6714,16 @@ class SessionDB:
         active_clause = " AND active = 1" if active_only else ""
 
         def _do(conn):
+            session = conn.execute(
+                "SELECT ended_at, end_reason FROM sessions WHERE id = ?",
+                (session_id,),
+            ).fetchone()
+            if (
+                session is not None
+                and session["ended_at"] is not None
+                and session["end_reason"] == "compression"
+            ):
+                raise CompressionSessionClosedError(session_id)
             conn.execute(
                 f"DELETE FROM messages WHERE session_id = ?{active_clause}",
                 (session_id,),
@@ -6086,6 +6887,8 @@ class SessionDB:
                 except (json.JSONDecodeError, TypeError):
                     logger.warning("Failed to deserialize tool_calls in get_messages, falling back to []")
                     msg["tool_calls"] = []
+            if msg.get("display_metadata") is not None:
+                msg["display_metadata"] = self._decode_display_metadata(msg["display_metadata"])
             result.append(msg)
         return result
 
@@ -6155,6 +6958,8 @@ class SessionDB:
                         "Failed to deserialize tool_calls in get_messages_around, falling back to []"
                     )
                     msg["tool_calls"] = []
+            if msg.get("display_metadata") is not None:
+                msg["display_metadata"] = self._decode_display_metadata(msg["display_metadata"])
             result.append(msg)
 
         # before_rows includes the anchor itself; subtract 1 for the count of
@@ -6277,6 +7082,8 @@ class SessionDB:
                         "Failed to deserialize tool_calls in get_anchored_view, falling back to []"
                     )
                     msg["tool_calls"] = []
+            if msg.get("display_metadata") is not None:
+                msg["display_metadata"] = self._decode_display_metadata(msg["display_metadata"])
             return msg
 
         return {
@@ -6475,10 +7282,9 @@ class SessionDB:
             if row["display_kind"]:
                 msg["display_kind"] = row["display_kind"]
             if row["display_metadata"]:
-                try:
-                    msg["display_metadata"] = json.loads(row["display_metadata"])
-                except (TypeError, json.JSONDecodeError):
-                    logger.warning("Ignoring invalid display metadata on message row")
+                decoded = self._decode_display_metadata(row["display_metadata"])
+                if decoded is not None:
+                    msg["display_metadata"] = decoded
             if row["timestamp"]:
                 msg["timestamp"] = row["timestamp"]
             if row["tool_call_id"]:
@@ -6855,7 +7661,9 @@ class SessionDB:
                 if not preview:
                     preview = "[multimodal content]"
             elif isinstance(decoded, str):
-                preview = decoded
+                # A /skill turn embeds the whole skill body; show what the user
+                # typed instead of the skill's opening prose.
+                preview = describe_skill_invocation(decoded) or decoded
             else:
                 preview = ""
             preview = " ".join(preview.split())  # collapse whitespace
@@ -8512,10 +9320,28 @@ class SessionDB:
         except OSError:
             pass
 
+    def get_session_delete_targets(self, session_id: str) -> List[str]:
+        """Return every session row that :meth:`delete_session` would remove.
+
+        The requested session is first, followed by its recursively discovered
+        delegate/subagent children. Branch and compression children are not
+        included because deletion preserves them by orphaning their parent
+        reference.
+        """
+        with self._lock:
+            exists = self._conn.execute(
+                "SELECT 1 FROM sessions WHERE id = ? LIMIT 1", (session_id,)
+            ).fetchone()
+            if not exists:
+                return []
+            delegate_ids = _collect_delegate_child_ids(self._conn, [session_id])
+        return [session_id, *sorted(delegate_ids)]
+
     def delete_session(
         self,
         session_id: str,
         sessions_dir: Optional[Path] = None,
+        expected_delete_ids: Optional[List[str]] = None,
     ) -> bool:
         """Delete a session and all its messages.
 
@@ -8525,9 +9351,18 @@ class SessionDB:
         (``parent_session_id → NULL``) so they remain accessible independently.
         When *sessions_dir* is provided, also removes on-disk transcript
         files (``.json`` / ``.jsonl`` / ``request_dump_*``) for every deleted
-        session. Returns True if the session was found and deleted.
+        session. When *expected_delete_ids* is provided, deletion proceeds only
+        if the parent plus delegate cascade still matches that exact set. This
+        lets export-before-delete callers fail closed if a new delegate appears
+        after they materialize their archive. The delegate tree is re-walked
+        inside the write transaction on purpose (TOCTOU guard); the cost is
+        accepted for correctness. Returns True if the session was found and
+        deleted.
         """
         removed_delegate_ids: List[str] = []
+        expected_ids = (
+            set(expected_delete_ids) if expected_delete_ids is not None else None
+        )
 
         def _do(conn):
             cursor = conn.execute(
@@ -8535,6 +9370,13 @@ class SessionDB:
             )
             if cursor.fetchone()[0] == 0:
                 return False
+            if expected_ids is not None:
+                actual_ids = {
+                    session_id,
+                    *_collect_delegate_child_ids(conn, [session_id]),
+                }
+                if actual_ids != expected_ids:
+                    return False
             removed_delegate_ids.extend(_delete_delegate_children(conn, [session_id]))
             # Orphan remaining child sessions (branches, etc.) so FK is satisfied.
             conn.execute(
@@ -8944,6 +9786,55 @@ class SessionDB:
             self.set_session_archived(row["id"], True)
         return len(rows)
 
+    def archive_stale_sessions(
+        self, idle_days: float, *, exclude_pinned: bool = True
+    ) -> int:
+        """Archive every session untouched for at least ``idle_days`` days.
+
+        "Touched" is the latest message timestamp (falling back to
+        ``started_at``) — i.e. real recency, not creation time — so a session
+        created long ago but active yesterday is spared, while an old
+        abandoned one (even a still-open one) is swept. This differs from
+        :meth:`archive_sessions`, which ages on ``started_at`` and only ended
+        sessions.
+
+        Guards:
+          * ``pinned = 0`` when ``exclude_pinned`` (the Desktop "keep" flag).
+          * ``archived = 0`` so repeat runs are idempotent no-ops.
+          * only lineage *tips* / standalone rows are candidates
+            (``end_reason <> 'compression'``); a stale tip archives its whole
+            chain via :meth:`set_session_archived`, so we never resurrect an
+            active conversation by matching an old compressed-away root whose
+            live continuation is recent.
+
+        Returns the number of sessions archived. Never raises for an empty or
+        non-positive ``idle_days`` — it simply archives nothing.
+        """
+        if idle_days is None or idle_days < 0:
+            return 0
+        cutoff = time.time() - float(idle_days) * 86400.0
+        pin_clause = "AND s.pinned = 0" if exclude_pinned else ""
+        with self._lock:
+            rows = self._conn.execute(
+                f"""
+                SELECT s.id FROM sessions s
+                WHERE s.archived = 0
+                  AND COALESCE(s.end_reason, '') <> 'compression'
+                  {pin_clause}
+                  AND COALESCE(
+                        (SELECT MAX(m.timestamp) FROM messages m
+                         WHERE m.session_id = s.id),
+                        s.started_at
+                      ) < ?
+                ORDER BY s.started_at ASC
+                """,
+                (cutoff,),
+            ).fetchall()
+        ids = [(r["id"] if isinstance(r, sqlite3.Row) else r[0]) for r in rows]
+        for sid in ids:
+            self.set_session_archived(sid, True)
+        return len(ids)
+
     def prune_sessions(
         self,
         older_than_days: Optional[float] = 90,
@@ -9501,10 +10392,10 @@ class SessionDB:
         with self._lock:
             try:
                 rows = self._conn.execute(
-                    """
+                    f"""
                     SELECT s.*,
                         COALESCE(
-                            (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63)
+                            (SELECT {_PREVIEW_RAW_SELECT}
                              FROM messages m
                              WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
                              ORDER BY m.timestamp, m.id LIMIT 1),
@@ -9530,10 +10421,10 @@ class SessionDB:
                 # telegram_dm_topic_bindings doesn't exist yet — no bindings
                 # means every telegram session for this user is "unlinked".
                 rows = self._conn.execute(
-                    """
+                    f"""
                     SELECT s.*,
                         COALESCE(
-                            (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63)
+                            (SELECT {_PREVIEW_RAW_SELECT}
                              FROM messages m
                              WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
                              ORDER BY m.timestamp, m.id LIMIT 1),
@@ -9555,8 +10446,7 @@ class SessionDB:
         sessions: List[Dict[str, Any]] = []
         for row in rows:
             session = dict(row)
-            raw = str(session.pop("_preview_raw", "") or "").strip()
-            session["preview"] = raw[:60] + ("..." if len(raw) > 60 else "") if raw else ""
+            session["preview"] = _shape_preview(session.pop("_preview_raw", ""))
             sessions.append(session)
         return sessions
 
@@ -9650,6 +10540,34 @@ class SessionDB:
                     )
         return rebuilt
 
+    def logical_size_bytes(self) -> Optional[int]:
+        """Database size in bytes as SQLite itself accounts for it.
+
+        ``page_count * page_size`` — the size the main DB file will have once
+        the WAL is checkpointed back into it.
+
+        Prefer this over ``os.path.getsize(db_path)`` when reporting the effect
+        of a VACUUM. In WAL mode a VACUUM's rewrite lands in the ``-wal`` file,
+        and the checkpoint that folds it back is refused while any other
+        connection (a live gateway) holds a read-mark. Until that happens the
+        main file on disk still carries its pre-VACUUM size and keeps growing,
+        so a stat()-based before/after delta understates the win and can go
+        negative — the "reclaimed -3820.1 MB" report on a database that had
+        actually shrunk 60%.
+
+        Returns None if the pragmas cannot be read.
+        """
+        try:
+            with self._lock:
+                if self._conn is None:
+                    return None
+                page_count = self._conn.execute("PRAGMA page_count").fetchone()[0]
+                page_size = self._conn.execute("PRAGMA page_size").fetchone()[0]
+            return int(page_count) * int(page_size)
+        except Exception as exc:
+            logger.debug("Could not read logical DB size: %s", exc)
+            return None
+
     def vacuum(self) -> int:
         """Run VACUUM to reclaim disk space after large deletes.
 
@@ -9761,6 +10679,59 @@ class SessionDB:
 
         return result
 
+    def maybe_auto_archive(
+        self,
+        idle_days: float = 3,
+        min_interval_hours: int = 24,
+        exclude_pinned: bool = True,
+    ) -> Dict[str, Any]:
+        """Idempotent auto-archive: soft-hide sessions idle for ``idle_days``.
+
+        Sibling of :meth:`maybe_auto_prune_and_vacuum` but non-destructive —
+        it archives (hides) rather than deletes, and ages on last activity
+        (see :meth:`archive_stale_sessions`) rather than creation. Records the
+        last run in ``state_meta['last_auto_archive']`` so calls within
+        ``min_interval_hours`` no-op; safe to call opportunistically (startup
+        hooks, or when the Desktop backend lists sessions).
+
+        Never raises. Returns a dict with:
+          - ``"skipped"`` (bool) — within min_interval_hours of last run
+          - ``"archived"`` (int) — sessions archived this run
+          - ``"error"`` (str, optional) — present only on failure
+        """
+        result: Dict[str, Any] = {"skipped": False, "archived": 0}
+        try:
+            last_raw = self.get_meta("last_auto_archive")
+            now = time.time()
+            if last_raw:
+                try:
+                    if now - float(last_raw) < min_interval_hours * 3600:
+                        result["skipped"] = True
+                        return result
+                except (TypeError, ValueError):
+                    pass  # corrupt meta; treat as no prior run
+
+            archived = self.archive_stale_sessions(
+                idle_days, exclude_pinned=exclude_pinned
+            )
+            result["archived"] = archived
+
+            # Record even a zero-archive run so we don't re-sweep every call
+            # within the interval window.
+            self.set_meta("last_auto_archive", str(now))
+
+            if archived > 0:
+                logger.info(
+                    "state.db auto-archive: archived %d session(s) idle >= %s days",
+                    archived,
+                    idle_days,
+                )
+        except Exception as exc:
+            logger.warning("state.db auto-archive failed: %s", exc)
+            result["error"] = str(exc)
+
+        return result
+
     # ── Handoff (cross-platform session transfer) ──────────────────────────
     #
     # State machine:
diff --git a/infographic/checkpoint-prune-startup-safety/infographic.png b/infographic/checkpoint-prune-startup-safety/infographic.png
new file mode 100644
index 00000000000..87d1bcc5d5b
Binary files /dev/null and b/infographic/checkpoint-prune-startup-safety/infographic.png differ
diff --git a/locales/ar.yaml b/locales/ar.yaml
new file mode 100644
index 00000000000..f2c78e8c654
--- /dev/null
+++ b/locales/ar.yaml
@@ -0,0 +1,418 @@
+# Hermes static-message catalog -- Arabic (العربية)
+#
+# Mirrors locales/en.yaml key-for-key.  Only user-facing static prose is
+# translated: command names, /slash commands, config keys, paths, URLs, model
+# IDs, provider names, emojis and {placeholder} tokens are kept verbatim so
+# interpolation and identifiers keep working.  tests/agent/test_i18n.py asserts
+# key parity and placeholder parity against en.yaml.
+
+approval:
+  dangerous_header: "⚠️  أمر خطير: {description}"
+  choose_long:     "      [o] مرة  |  [s] الجلسة  |  [a] دائمًا  |  [d] رفض"
+  choose_short:    "      [o] مرة  |  [s] الجلسة  |  [d] رفض"
+  prompt_long:     "      الاختيار [o/s/a/D]: "
+  prompt_short:    "      الاختيار [o/s/D]: "
+  choose_smart_deny: "      [o] مرة  |  [d] رفض"
+  prompt_smart_deny: "      الاختيار [o/D]: "
+  smart_deny_once_inputs: "o,once"
+  smart_deny_deny_inputs: "d,deny"
+  timeout:         "      ⏱ انتهت المهلة - يتم رفض الأمر"
+  allowed_once:    "      ✓ مسموح مرة واحدة"
+  allowed_session: "      ✓ مسموح لهذه الجلسة"
+  allowed_always:  "      ✓ أُضيف إلى قائمة السماح الدائمة"
+  denied:          "      ✗ مرفوض"
+  cancelled:       "      ✗ أُلغي"
+  blocklist_message: "هذا الأمر مدرج في قائمة الحظر غير المشروطة ولا يمكن الموافقة عليه."
+
+gateway:
+  approval_expired: "⚠️ انتهت صلاحية الموافقة (لم يعد الوكيل ينتظر). اطلب من الوكيل المحاولة مرة أخرى."
+  draining:         "⏳ جارٍ إنهاء {count} وكيل نشط قبل إعادة التشغيل..."
+  goal_cleared:     "✓ تم مسح الهدف."
+  no_active_goal:   "لا يوجد هدف نشط."
+  config_read_failed: "⚠️ تعذّر قراءة config.yaml: {error}"
+  config_save_failed: "⚠️ تعذّر حفظ الإعدادات: {error}"
+
+  model:
+    error_prefix:           "خطأ: {error}"
+    switched:               "تم التبديل إلى النموذج `{model}`"
+    provider_label:         "المزوّد: {provider}"
+    context_label:          "السياق: {tokens} رمزًا"
+    max_output_label:       "أقصى خرج: {tokens} رمزًا"
+    cost_label:             "التكلفة: {cost}"
+    capabilities_label:     "القدرات: {capabilities}"
+    prompt_caching_enabled: "التخزين المؤقت للموجِّه: مُفعّل"
+    warning_prefix:         "تحذير: {warning}"
+    saved_global:           "حُفظ في config.yaml (‏`--global`)"
+    session_only_hint:      "_(هذه الجلسة فقط — أضف `--global` للحفظ الدائم)_"
+    current_label:          "الحالي: `{model}` على {provider}"
+    current_tag:            " (الحالي)"
+    more_models_suffix:     " (+{count} آخر)"
+    usage_switch_model:     "`/model <name>` — تبديل النموذج"
+    usage_switch_provider:  "`/model <name> --provider <slug>` — تبديل المزوّد"
+    usage_persist:          "`/model <name> --global` — حفظ دائم"
+
+  agents:
+    header:                "🤖 **الوكلاء والمهام النشطة**"
+    active_agents:         "**الوكلاء النشطون:** {count}"
+    this_chat:             " · هذه المحادثة"
+    more:                  "... و{count} آخر"
+    running_processes:     "**العمليات الخلفية الجارية:** {count}"
+    async_jobs:            "**مهام البوابة غير المتزامنة:** {count}"
+    none:                  "لا يوجد وكلاء نشطون أو مهام جارية."
+    state_starting:        "قيد البدء"
+    state_running:         "قيد التشغيل"
+
+  approve:
+    no_pending:            "لا يوجد أمر معلّق للموافقة عليه."
+    once_singular:         "✅ تمت الموافقة على الأمر. الوكيل يستأنف..."
+    once_plural:           "✅ تمت الموافقة على الأوامر ({count} أوامر). الوكيل يستأنف..."
+    session_singular:      "✅ تمت الموافقة على الأمر (النمط مُوافق عليه لهذه الجلسة). الوكيل يستأنف..."
+    session_plural:        "✅ تمت الموافقة على الأوامر (النمط مُوافق عليه لهذه الجلسة) ({count} أوامر). الوكيل يستأنف..."
+    always_singular:       "✅ تمت الموافقة على الأمر (النمط مُوافق عليه دائمًا). الوكيل يستأنف..."
+    always_plural:         "✅ تمت الموافقة على الأوامر (النمط مُوافق عليه دائمًا) ({count} أوامر). الوكيل يستأنف..."
+
+  background:
+    usage:                 "الاستخدام: /background <prompt>\nمثال: /background لخّص أهم قصص HN اليوم\n\nيشغّل الموجِّه في جلسة منفصلة. يمكنك متابعة المحادثة — ستظهر النتيجة هنا عند الانتهاء."
+    started:               "🔄 بدأت مهمة خلفية: \"{preview}\"\nمعرّف المهمة: {task_id}\nيمكنك متابعة المحادثة — ستظهر النتائج عند الانتهاء."
+
+  branch:
+    db_unavailable:        "قاعدة بيانات الجلسات غير متاحة."
+    no_conversation:       "لا توجد محادثة للتفريع — أرسل رسالة أولًا."
+    create_failed:         "فشل إنشاء الفرع: {error}"
+    switch_failed:         "أُنشئ الفرع لكن تعذّر التبديل إليه."
+    branched_one:          "⑂ تم التفريع إلى **{title}** (نُسخت {count} رسالة)\nالأصل: `{parent}`\nالفرع: `{new}`\nاستخدم `/resume` للعودة إلى الأصل."
+    branched_many:         "⑂ تم التفريع إلى **{title}** (نُسخت {count} رسالة)\nالأصل: `{parent}`\nالفرع: `{new}`\nاستخدم `/resume` للعودة إلى الأصل."
+
+  commands:
+    usage:                 "الاستخدام: `/commands [page]`"
+    skill_header:          "⚡ **أوامر المهارات**:"
+    default_desc:          "أمر مهارة"
+    none:                  "لا توجد أوامر متاحة."
+    header:                "📚 **الأوامر** ({total} إجمالًا، صفحة {page}/{total_pages})"
+    nav_prev:              "`/commands {page}` ← السابق"
+    nav_next:              "التالي → `/commands {page}`"
+    out_of_range:          "_(الصفحة المطلوبة {requested} خارج النطاق، يتم عرض الصفحة {page}.)_"
+
+  compress:
+    not_enough:            "لا توجد محادثة كافية للضغط (يلزم 4 رسائل على الأقل)."
+    no_provider:           "لا يوجد مزوّد مُهيّأ -- لا يمكن الضغط."
+    nothing_to_do:         "لا شيء للضغط بعد (النص كله لا يزال سياقًا محميًا)."
+    aggressive_unsupported: "الخيار --aggressive غير مدعوم؛ استخدم '/compress here [N]' للإبقاء على أحدث التبادلات فقط، أو /undo لإسقاط الأدوار."
+    focus_line:            "التركيز: \"{topic}\""
+    summary_failed:        "⚠️ فشل توليد الملخّص ({error}). أُزيلت {count} رسالة تاريخية واستُبدلت بعنصر نائب؛ لم يعد السياق الأقدم قابلًا للاسترجاع. فكّر في مراجعة إعداد نموذج auxiliary.compression."
+    aborted:               "⚠️ أُلغي الضغط ({error}). لم تُسقط أي رسائل — المحادثة كما هي. شغّل /compress للمحاولة مجددًا، أو /reset لجلسة نظيفة، أو راجع إعداد نموذج auxiliary.compression."
+    aux_failed:            "ℹ️ فشل نموذج الضغط المُهيّأ `{model}` ({error}). تم التعافي باستخدام نموذجك الرئيسي — السياق سليم — لكن قد ترغب في مراجعة `auxiliary.compression.model` في config.yaml."
+    failed:                "فشل الضغط: {error}"
+
+  debug:
+    upload_failed:         "✗ فشل رفع تقرير التصحيح: {error}"
+    header:                "**تم رفع تقرير التصحيح:**"
+    auto_delete:           "⏱ ستُحذف اللصقات تلقائيًا خلال 6 ساعات."
+    full_logs_hint:        "لرفع السجلات الكاملة، استخدم `hermes debug share` من واجهة الأوامر."
+    share_hint:            "شارك هذه الروابط مع فريق Hermes للحصول على الدعم."
+
+  deny:
+    stale:                 "❌ رُفض الأمر (الموافقة كانت قديمة)."
+    no_pending:            "لا يوجد أمر معلّق لرفضه."
+    denied_singular:       "❌ رُفض الأمر."
+    denied_plural:         "❌ رُفضت الأوامر ({count} أوامر)."
+    denied_reason_singular: "❌ رُفض الأمر. السبب المُبلّغ للوكيل: \"{reason}\""
+    denied_reason_plural:  "❌ رُفضت الأوامر ({count} أوامر). السبب المُبلّغ للوكيل: \"{reason}\""
+
+  fast:
+    not_supported:         "⚡ /fast متاح فقط لنماذج OpenAI التي تدعم المعالجة ذات الأولوية."
+    status:                "⚡ المعالجة ذات الأولوية\n\nالوضع الحالي: `{mode}`\n\n_الاستخدام:_ `/fast <normal|fast|status>`"
+    unknown_arg:           "⚠️ وسيط غير معروف: `{arg}`\n\n**الخيارات الصالحة:** normal, fast, status"
+    saved:                 "⚡ ✓ المعالجة ذات الأولوية: **{label}** (حُفظت في الإعدادات)\n_(تسري على الرسالة التالية)_"
+    session_only:          "⚡ ✓ المعالجة ذات الأولوية: **{label}** (هذه الجلسة فقط)"
+    label_fast:            "سريع"
+    label_normal:          "عادي"
+    status_fast:           "fast"
+    status_normal:         "normal"
+    picker_title:          "⚡ **المعالجة ذات الأولوية**\n\nالوضع الحالي: `{mode}`\n\nاختر خيارًا:"
+    choice_fast:           "fast — المعالجة ذات الأولوية مُفعّلة"
+    choice_normal:         "normal — المعالجة القياسية"
+
+  footer:
+    status:                "📎 تذييل التشغيل: **{state}**\nالحقول: `{fields}`\nالمنصّة: `{platform}`"
+    usage:                 "الاستخدام: `/footer [on|off|status]`"
+    saved:                 "📎 تذييل التشغيل: **{state}**{example}\n_(حُفظ عالميًا — يسري على الرسالة التالية)_"
+    example_line:          "\nمثال: `{preview}`"
+    state_on:              "مُفعّل"
+    state_off:             "مُعطّل"
+
+  goal:
+    unavailable:           "الأهداف غير متاحة في هذه الجلسة."
+    no_goal_set:           "لم يُحدَّد هدف."
+    paused:                "⏸ أُوقف الهدف مؤقتًا: {goal}"
+    no_resume:             "لا يوجد هدف لاستئنافه."
+    resumed:               "▶ استُؤنف الهدف: {goal}\nأرسل أي رسالة للمتابعة، أو انتظر — سأتخذ الخطوة التالية في الدور القادم."
+    invalid:               "هدف غير صالح: {error}"
+    set:                   "⊙ حُدِّد الهدف (ميزانية {budget} دور): {goal}\nسأواصل العمل حتى يكتمل الهدف، أو توقفه/تمسحه، أو تنفد الميزانية.\nالتحكم: /goal status · /goal pause · /goal resume · /goal clear"
+
+  help:
+    header:                "📖 **أوامر Hermes**\n"
+    skill_header:          "\n⚡ **أوامر المهارات** ({count} نشطة):"
+    more_use_commands:     "\n... و{count} آخر. استخدم `/commands` للقائمة الكاملة المُقسّمة إلى صفحات."
+
+  insights:
+    invalid_days:          "قيمة --days غير صالحة: {value}"
+    error:                 "خطأ في توليد الرؤى: {error}"
+
+  kanban:
+    error_prefix:          "⚠ خطأ kanban: {error}"
+    subscribed_suffix:     "(مُشترك — ستُخطَر عند اكتمال {task_id} أو حجبها)"
+    truncated_suffix:      "… (مقتطع؛ استخدم `hermes kanban …` في الطرفية للخرج الكامل)"
+    no_output:             "(لا يوجد خرج)"
+    wake:
+      completed:           "اكتملت"
+      gave_up:             "استسلم (نفدت المحاولات)"
+      crashed:             "تعطّل (خرج العامل)؛ سيعيد المُوزّع المحاولة"
+      timed_out:           "انتهت المهلة؛ سيعيد المُوزّع المحاولة"
+      blocked:             "محجوبة؛ تحتاج إلى انتباه"
+      status_default:      "تغيّرت الحالة"
+      status_joiner:       "، "
+      message:             "[kanban] المهمة {task_id} {status}.\nالعنوان: {title}\nالمُكلَّف: @{assignee}\nاللوحة: {board}\n\nراجع النتيجة أو قرّر الخطوة التالية."
+
+  personality:
+    none_configured:       "لا توجد شخصيات مُهيّأة في `{path}/config.yaml`"
+    header:                "🎭 **الشخصيات المتاحة**\n"
+    none_option:           "• `none` — (بدون طبقة شخصية)"
+    item:                  "• `{name}` — {preview}"
+    usage:                 "\nالاستخدام: `/personality <name>`"
+    save_failed:           "⚠️ فشل حفظ تغيير الشخصية: {error}"
+    cleared:               "🎭 مُسحت الشخصية — يتم استخدام سلوك الوكيل الأساسي.\n_(يسري على الرسالة التالية)_"
+    set_to:                "🎭 ضُبطت الشخصية إلى **{name}**\n_(يسري على الرسالة التالية)_"
+    unknown:               "شخصية غير معروفة: `{name}`\n\nالمتاح: {available}"
+
+  profile:
+    header:                "👤 **الملف الشخصي:** `{profile}`"
+    home:                  "📂 **المجلد الرئيسي:** `{home}`"
+
+  reasoning:
+    level_default:             "medium (افتراضي)"
+    level_disabled:            "none (مُعطّل)"
+    scope_session:             "تجاوز الجلسة"
+    scope_global:              "الإعدادات العامة"
+    status:                    "🧠 **إعدادات التفكير**\n\n**الجهد:** `{level}`\n**النطاق:** {scope}\n**العرض:** {display}\n\n_الاستخدام:_ `/reasoning <none|minimal|low|medium|high|xhigh|max|ultra|reset|show|hide> [--global]`"
+    display_on:                "مُفعّل ✓"
+    display_off:               "مُعطّل"
+    display_set_on:            "🧠 ✓ عرض التفكير: **مُفعّل**\nسيُعرض تفكير النموذج قبل كل رد على **{platform}**."
+    display_set_off:           "🧠 ✓ عرض التفكير: **مُعطّل** لـ **{platform}**"
+    reset_global_unsupported:  "⚠️ `/reasoning reset --global` غير مدعوم. استخدم `/reasoning <level> --global` لتغيير الافتراضي العام."
+    reset_done:                "🧠 ✓ مُسح تجاوز التفكير للجلسة؛ العودة إلى الإعدادات العامة."
+    unknown_arg:               "⚠️ وسيط غير معروف: `{arg}`\n\n**المستويات الصالحة:** none, minimal, low, medium, high, xhigh, max, ultra\n**العرض:** show, hide\n**الحفظ:** أضف `--global` للحفظ بعد هذه الجلسة"
+    picker_title:              "🧠 **إعدادات التفكير**\n\n**الجهد:** `{level}`\n**النطاق:** {scope}\n**العرض:** {display}\n\nاختر خيارًا:"
+    choice_none:               "none — تعطيل التفكير"
+    choice_reset:              "reset — مسح تجاوز الجلسة"
+    choice_show:               "عرض التفكير في الردود"
+    choice_hide:               "إخفاء التفكير من الردود"
+    set_global:                "🧠 ✓ ضُبط جهد التفكير إلى `{effort}` (حُفظ في الإعدادات)\n_(يسري على الرسالة التالية)_"
+    set_global_save_failed:    "🧠 ✓ ضُبط جهد التفكير إلى `{effort}` (الجلسة فقط — فشل حفظ الإعدادات)\n_(يسري على الرسالة التالية)_"
+    set_session:               "🧠 ✓ ضُبط جهد التفكير إلى `{effort}` (الجلسة فقط — أضف `--global` للحفظ الدائم)\n_(يسري على الرسالة التالية)_"
+
+  reload_mcp:
+    cancelled:             "🟡 أُلغي /reload-mcp. أدوات MCP دون تغيير."
+    always_followup:       "ℹ️ ستُشغَّل استدعاءات `/reload-mcp` المستقبلية دون تأكيد. أعِد التفعيل عبر `approvals.mcp_reload_confirm: true` في config.yaml."
+    confirm_prompt:        "⚠️ **تأكيد /reload-mcp**\n\nإعادة تحميل خوادم MCP تعيد بناء مجموعة الأدوات لهذه الجلسة و**تُبطل التخزين المؤقت لموجِّه المزوّد** — ستُعاد الرسالة التالية بكامل رموز الإدخال.  على النماذج ذات السياق الطويل أو التفكير العالي قد يكون ذلك مكلفًا.\n\nاختر:\n• **الموافقة مرة** — أعِد التحميل الآن\n• **الموافقة دائمًا** — أعِد التحميل الآن واكتم هذا التنبيه نهائيًا\n• **إلغاء** — اترك أدوات MCP دون تغيير\n\n_بديل نصي: رُدّ بـ `/approve` أو `/always` أو `/cancel`._"
+    header:                "🔄 **أُعيد تحميل خوادم MCP**\n"
+    reconnected:           "♻️ أُعيد الاتصال: {names}"
+    added:                 "➕ أُضيف: {names}"
+    removed:               "➖ أُزيل: {names}"
+    none_connected:        "لا توجد خوادم MCP متصلة."
+    tools_available:       "\n🔧 {tools} أداة متاحة من {servers} خادم"
+    failed:                "❌ فشلت إعادة تحميل MCP: {error}"
+
+  reload_skills:
+    header:                "🔄 **أُعيد تحميل المهارات**\n"
+    no_new:                "لم تُكتشف مهارات جديدة."
+    total:                 "\n📚 {count} مهارة متاحة"
+    added_header:          "➕ **مهارات مُضافة:**"
+    removed_header:        "➖ **مهارات مُزالة:**"
+    item_with_desc:        "    - {name}: {desc}"
+    item_no_desc:          "    - {name}"
+    failed:                "❌ فشلت إعادة تحميل المهارات: {error}"
+
+  reset:
+    header_default:        "✨ أُعيد ضبط الجلسة! بداية جديدة."
+    header_new:            "✨ بدأت جلسة جديدة!"
+    header_titled:         "✨ بدأت جلسة جديدة: {title}"
+    title_rejected:        "\n⚠️ رُفض العنوان: {error}"
+    title_error_untitled:  "\n⚠️ {error} — بدأت الجلسة دون عنوان."
+    title_empty_untitled:  "\n⚠️ العنوان فارغ بعد التنظيف — بدأت الجلسة دون عنوان."
+    tip:                   "\n✦ نصيحة: {tip}"
+
+  restart:
+    in_progress:           "⏳ إعادة تشغيل البوابة قيد التنفيذ بالفعل..."
+    restarting:            "♻ جارٍ إعادة تشغيل البوابة. إن لم تُخطَر خلال 60 ثانية، أعِد التشغيل من وحدة التحكّم باستخدام `hermes gateway restart`."
+
+  resume:
+    db_unavailable:        "قاعدة بيانات الجلسات غير متاحة."
+    parse_error:           "⚠️ تعذّر تحليل وسائط `/resume`: {error}.\nاستخدم علامات اقتباس حول العناوين التي تحتوي مسافات، مثال: `/resume \"Project A Plan\"`."
+    matrix_no_named_sessions: "لم يُعثر على جلسات مُسمّاة لغرفة Matrix هذه.\nاستخدم `/title My Session` لتسمية جلسة الغرفة الحالية، أو `/resume --all` لسرد كل جلسات Matrix، أو `/resume --cross-room <session name>` لتجاوز حدود الغرفة صراحةً."
+    matrix_blocked_no_origin: "⚠️ حُجب /resume في Matrix: هذه الجلسة المُسمّاة لا تملك أصل غرفة مُسجّلًا، لذا لن يستأنفها Hermes داخل الغرفة الحالية افتراضيًا. استخدم `/resume --cross-room {name}` إن كنت تريد عمدًا تجاوز حدود الغرفة."
+    matrix_blocked_other_room: "⚠️ حُجب /resume في Matrix: تلك الجلسة تخصّ غرفة Matrix مختلفة ({room}). استخدم `/resume --cross-room {name}` إن كنت تريد عمدًا استئنافها هنا."
+    matrix_cross_room_success: "⚠️ استئناف عبر الغرف: استُؤنفت **{title}** داخل غرفة Matrix ‏**{room}**.\nستستخدم الرسائل المستقبلية في هذه الغرفة ذلك النص حتى `/reset` أو `/resume` آخر.{msg_part}"
+    blocked_not_owner:     "⚠️ حُجب /resume: '**{name}**' تخصّ مستخدمًا أو محادثة مختلفة. يمكنك فقط استئناف جلسات هذه المحادثة."
+    no_named_sessions:     "لم يُعثر على جلسات مُسمّاة.\nاستخدم `/title My Session` لتسمية جلستك الحالية، ثم `/resume My Session` للعودة إليها لاحقًا."
+    list_header:           "📋 **الجلسات المُسمّاة**\n"
+    list_item:             "• **{title}**{preview_part}"
+    list_item_numbered:    "{index}. **{title}**{preview_part}"
+    list_preview_suffix:   " — _{preview}_"
+    list_footer:           "\nالاستخدام: `/resume <session name>`"
+    list_footer_numbered:  "\nالاستخدام: `/resume <session name>` أو `/resume <number>` (مثال: `/resume 1` للأحدث)"
+    list_failed:           "تعذّر سرد الجلسات: {error}"
+    out_of_range:          "مؤشر الاستئناف {index} خارج النطاق.\nاستخدم `/resume` دون وسائط لعرض الجلسات المتاحة."
+    not_found:             "لم يُعثر على جلسة تطابق '**{name}**'.\nاستخدم `/resume` دون وسائط لعرض الجلسات المتاحة."
+    already_on:            "📌 أنت بالفعل على الجلسة **{name}**."
+    switch_failed:         "فشل تبديل الجلسة."
+    resumed_one:           "↻ استُؤنفت الجلسة **{title}** ({count} رسالة). استُعيدت المحادثة."
+    resumed_many:          "↻ استُؤنفت الجلسة **{title}** ({count} رسالة). استُعيدت المحادثة."
+    resumed_no_count:      "↻ استُؤنفت الجلسة **{title}**. استُعيدت المحادثة."
+
+  retry:
+    no_previous:           "لا توجد رسالة سابقة لإعادة المحاولة."
+
+  rollback:
+    not_enabled:           "نقاط التحقّق غير مُفعّلة.\nفعّلها في config.yaml:\n```\ncheckpoints:\n  enabled: true\n```"
+    none_found:            "لم يُعثر على نقاط تحقّق لـ {cwd}"
+    invalid_number:        "رقم نقطة تحقّق غير صالح. استخدم 1-{max}."
+    restored:              "✅ استُعيد إلى نقطة التحقّق {hash}: {reason}\nحُفظت لقطة ما قبل التراجع تلقائيًا."
+    restore_failed:        "❌ {error}"
+
+  set_home:
+    save_failed:           "فشل حفظ القناة الرئيسية: {error}"
+    success:               "✅ ضُبطت القناة الرئيسية إلى **{name}** (المعرّف: {chat_id}).\nستُسلَّم مهام cron والرسائل عبر المنصّات هنا."
+
+  status:
+    header:                "📊 **حالة بوابة Hermes**"
+    matrix_scope_header:   "**نطاق Matrix:**"
+    matrix_scope_room:     "  الغرفة: {room}"
+    matrix_scope_room_id:  "  معرّف الغرفة: {room_id}"
+    matrix_scope_thread:   "  معرّف الخيط: {thread_id}"
+    matrix_scope_mode:     "  نطاق الجلسة: {scope}"
+    matrix_scope_key:      "  مفتاح الجلسة: {session_key}"
+    session_id:            "**معرّف الجلسة:** `{session_id}`"
+    title:                 "**العنوان:** {title}"
+    created:               "**أُنشئت:** {timestamp}"
+    last_activity:         "**آخر نشاط:** {timestamp}"
+    model:                 "**النموذج:** `{model}`"
+    model_provider:        "**النموذج:** `{model}` ({provider})"
+    context:               "**السياق:** {used} / {total} ({pct}%)"
+    context_used:          "**السياق:** ~{used} رمزًا"
+    tokens:                "**رموز API التراكمية (تُعاد كل استدعاء):** {tokens}"
+    agent_running:         "**الوكيل قيد التشغيل:** {state}"
+    state_yes:             "نعم ⚡"
+    state_no:              "لا"
+    queued:                "**المتابعات في الطابور:** {count}"
+    platforms:             "**المنصّات المتصلة:** {platforms}"
+
+  stop:
+    stopped_pending:       "⚡ تم الإيقاف. لم يكن الوكيل قد بدأ بعد — يمكنك متابعة هذه الجلسة."
+    stopped:               "⚡ تم الإيقاف. يمكنك متابعة هذه الجلسة."
+    no_active:             "لا توجد مهمة نشطة لإيقافها."
+
+  title:
+    db_unavailable:        "قاعدة بيانات الجلسات غير متاحة."
+    warn_prefix:           "⚠️ {error}"
+    empty_after_clean:     "⚠️ العنوان فارغ بعد التنظيف. من فضلك استخدم أحرفًا قابلة للطباعة."
+    set_to:                "✏️ ضُبط عنوان الجلسة: **{title}**"
+    not_found:             "لم يُعثر على الجلسة في قاعدة البيانات."
+    current_with_title:    "📌 الجلسة: `{session_id}`\nالعنوان: **{title}**"
+    current_no_title:      "📌 الجلسة: `{session_id}`\nلم يُضبط عنوان. الاستخدام: `/title My Session Name`"
+
+  topic:
+    not_telegram_dm:         "الأمر /topic متاح فقط في محادثات Telegram الخاصة."
+    no_session_db:           "قاعدة بيانات الجلسات غير متاحة."
+    unauthorized:            "غير مصرّح لك باستخدام /topic على هذا البوت."
+    restore_needs_topic:     "لاستعادة جلسة، أنشئ أو افتح موضوع Telegram أولًا، ثم أرسل /topic <session-id> داخل ذلك الموضوع. لإنشاء موضوع جديد، افتح All Messages وأرسل أي رسالة هناك."
+    topics_disabled:         "مواضيع Telegram غير مُفعّلة لهذا البوت بعد.\n\nكيفية تفعيلها:\n1. افتح @BotFather.\n2. اختر البوت الخاص بك.\n3. افتح Bot Settings → Threads Settings.\n4. فعّل Threaded Mode وتأكّد من السماح للمستخدمين بإنشاء خيوط جديدة.\n\nثم أرسل /topic مرة أخرى."
+    topics_user_disallowed:  "مواضيع Telegram مُفعّلة، لكن غير مسموح للمستخدمين بإنشاء مواضيع.\n\nافتح @BotFather → اختر البوت → Bot Settings → Threads Settings، ثم أوقف 'Disallow users to create new threads'.\n\nثم أرسل /topic مرة أخرى."
+    enable_failed:           "فشل تفعيل وضع مواضيع Telegram: {error}"
+    bound_status:            "هذا الموضوع مرتبط بـ:\nالجلسة: {label}\nالمعرّف: {session_id}\n\nاستخدم /new لاستبدال هذا الموضوع بجلسة جديدة.\nللعمل المتوازي، افتح All Messages وأرسل رسالة هناك لإنشاء موضوع آخر."
+    thread_ready:            "مواضيع Telegram متعددة الجلسات مُفعّلة.\n\nسيُستخدم هذا الموضوع كجلسة Hermes مستقلة. استخدم /new لاستبدال جلسة هذا الموضوع الحالية. للعمل المتوازي، افتح All Messages وأرسل رسالة هناك لإنشاء موضوع آخر."
+    untitled_session:        "جلسة دون عنوان"
+
+  undo:
+    nothing:               "لا شيء للتراجع عنه."
+    removed:               "↩️ تم التراجع عن {turns} دور ({count} رسالة).\nنُسخ احتياطيًا إلى: \"{preview}\"\nانسخ/عدّل النص أعلاه وأرسله لإعادة التوجيه من هنا."
+    invalid_count:         "عدد غير صالح \"{arg}\" — استخدم /undo أو /undo N."
+
+  update:
+    platform_not_messaging:  "✗ /update متاح فقط من منصّات المراسلة. شغّل `hermes update` من الطرفية."
+    not_git_repo:            "✗ ليس مستودع git — لا يمكن التحديث."
+    hermes_cmd_not_found:    "✗ تعذّر تحديد موقع أمر `hermes`. Hermes يعمل، لكن أمر التحديث لم يجد الملف التنفيذي على PATH أو عبر مُفسّر Python الحالي. جرّب تشغيل `hermes update` يدويًا في طرفيتك."
+    start_failed:            "✗ فشل بدء التحديث: {error}"
+    starting:                "⚕ جارٍ بدء تحديث Hermes… سأبثّ التقدّم هنا."
+
+  usage:
+    rate_limits:              "⏱️ **حدود المعدّل:** {state}"
+    header_session:           "📊 **استخدام رموز الجلسة**"
+    label_model:              "النموذج: `{model}`"
+    label_input_tokens:       "رموز الإدخال: {count}"
+    label_cache_read:         "رموز قراءة التخزين المؤقت: {count}"
+    label_cache_write:        "رموز كتابة التخزين المؤقت: {count}"
+    label_output_tokens:      "رموز الإخراج: {count}"
+    label_total:              "الإجمالي: {count}"
+    label_api_calls:          "استدعاءات API: {count}"
+    label_cost:               "التكلفة: {prefix}${amount}"
+    label_cost_included:      "التكلفة: مشمولة"
+    label_context:            "السياق: {used} / {total} ({pct}%)"
+    label_compressions:       "عمليات الضغط: {count}"
+    breakdown_header:         "🧩 **تفصيل السياق** _(تقديري)_"
+    breakdown_line:           "• {label}: ~{count} ({pct}%)"
+    breakdown_cat_system_prompt:        "موجّه النظام"
+    breakdown_cat_tool_definitions:     "تعريفات الأدوات"
+    breakdown_cat_rules:                "القواعد"
+    breakdown_cat_skills:               "المهارات"
+    breakdown_cat_mcp:                  "MCP"
+    breakdown_cat_subagent_definitions: "تعريفات الوكلاء الفرعيين"
+    breakdown_cat_memory:               "الذاكرة"
+    breakdown_cat_conversation:         "المحادثة"
+    header_session_info:      "📊 **معلومات الجلسة**"
+    label_messages:           "الرسائل: {count}"
+    label_estimated_context:  "السياق المُقدّر: ~{count} رمزًا"
+    detailed_after_first:     "_(الاستخدام المُفصّل متاح بعد أول رد من الوكيل)_"
+    no_data:                  "لا تتوفّر بيانات استخدام لهذه الجلسة."
+    unknown_subcommand:       "أمر فرعي غير معروف لـ /usage: `{args}`. جرّب `/usage` أو `/usage reset [--force]`."
+    reset_wrong_provider:     "إعادة تعيين الاستخدام المُدّخر متاحة فقط على مزوّد openai-codex. بدّل عبر `/model` أولًا."
+
+  credits:
+    not_logged_in:            "لم تُسجّل الدخول إلى Nous Portal. سجّل الدخول لرؤية رصيد أرصدتك وإعادة الشحن."
+
+  verbose:
+    not_enabled:           "الأمر `/verbose` غير مُفعّل لمنصّات المراسلة.\n\nفعّله في `config.yaml`:\n```yaml\ndisplay:\n  tool_progress_command: true\n```"
+    mode_off:              "⚙️ تقدّم الأدوات: **مُعطّل** — لا يُعرض نشاط الأدوات."
+    mode_new:              "⚙️ تقدّم الأدوات: **NEW** — يُعرض عند تغيّر الأداة (طول المعاينة: `display.tool_preview_length`، افتراضي 40)."
+    mode_all:              "⚙️ تقدّم الأدوات: **ALL** — يُعرض كل استدعاء أداة (طول المعاينة: `display.tool_preview_length`، افتراضي 40)."
+    mode_verbose:          "⚙️ تقدّم الأدوات: **VERBOSE** — كل استدعاء أداة مع وسائطه الكاملة."
+    mode_log:              "⚙️ تقدّم الأدوات: **LOG** — صامت في المحادثة؛ تُكتب استدعاءات الأدوات إلى ~/.hermes/logs/tool_calls.log."
+    saved_suffix:          "_(حُفظ لـ **{platform}** — يسري على الرسالة التالية)_"
+    save_failed:           "_(تعذّر الحفظ في الإعدادات: {error})_"
+
+  voice:
+    enabled_voice_only:    "وضع الصوت مُفعّل.\nسأردّ بالصوت عندما ترسل رسائل صوتية.\nاستخدم /voice tts للحصول على ردود صوتية لكل الرسائل."
+    disabled_text:         "وضع الصوت مُعطّل. ردود نصّية فقط."
+    tts_enabled:           "TTS التلقائي مُفعّل.\nستتضمّن كل الردود رسالة صوتية."
+    status_mode:           "وضع الصوت: {label}"
+    status_channel:        "قناة الصوت: #{channel}"
+    status_participants:   "المشاركون: {count}"
+    status_member:         "  - {name}{status}"
+    speaking:              " (يتحدّث)"
+    enabled_short:         "وضع الصوت مُفعّل."
+    disabled_short:        "وضع الصوت مُعطّل."
+    label_off:             "مُعطّل (نص فقط)"
+    label_voice_only:      "مُفعّل (رد صوتي على الرسائل الصوتية)"
+    label_all:             "TTS (رد صوتي على كل الرسائل)"
+    help:                  "{toggle}\n\n**كيف يعمل /voice**\n• `/voice on` — رد صوتي عند إرسال رسالة صوتية\n• `/voice tts` — رد صوتي على *كل* رسالة\n• `/voice off` — العودة إلى ردود نصّية فقط\n• `/voice status` — عرض الوضع الحالي\n• `/voice` (بدون وسيط) — تبديل سريع بين التفعيل والتعطيل{channels}"
+    help_channels:         "\n\n**قنوات الصوت الحيّة (Discord)**\n• انضمّ إلى قناة صوتية أولًا، ثم `/voice channel` — سأنضمّ وأستمع وأنطق ردودي\n• `/voice leave` — قطع الاتصال بالقناة الصوتية"
+
+  yolo:
+    disabled:                   "⚠️ وضع YOLO **مُعطّل** لهذه الجلسة — ستتطلّب الأوامر الخطيرة موافقة."
+    enabled:                    "⚡ وضع YOLO **مُفعّل** لهذه الجلسة — كل الأوامر مُوافق عليها تلقائيًا. استخدمه بحذر."
+
+  shared:
+    session_db_unavailable:      "قاعدة بيانات الجلسات غير متاحة."
+    session_db_unavailable_prefix: "قاعدة بيانات الجلسات غير متاحة"
+    session_not_found:           "لم يُعثر على الجلسة في قاعدة البيانات."
+    warn_passthrough:            "⚠️ {error}"
diff --git a/mcp-research-data/ue_bench_rows.json b/mcp-research-data/ue_bench_rows.json
new file mode 100644
index 00000000000..1d8941fa836
--- /dev/null
+++ b/mcp-research-data/ue_bench_rows.json
@@ -0,0 +1,1576 @@
+[
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 24.85,
+  "api_calls": 5,
+  "prompt_tokens_total": 159590,
+  "completion_tokens_total": 1182,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 56.03,
+  "api_calls": 13,
+  "prompt_tokens_total": 433445,
+  "completion_tokens_total": 2504,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_remove_from_scene",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_remove_from_scene",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_remove_from_scene",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_remove_from_scene",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 13.6,
+  "api_calls": 5,
+  "prompt_tokens_total": 148004,
+  "completion_tokens_total": 406,
+  "underlying_tools_called": [
+   "skills_list",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 14.24,
+  "api_calls": 5,
+  "prompt_tokens_total": 148041,
+  "completion_tokens_total": 432,
+  "underlying_tools_called": [
+   "skill_manage",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 8.59,
+  "api_calls": 2,
+  "prompt_tokens_total": 107981,
+  "completion_tokens_total": 216,
+  "underlying_tools_called": [
+   "skill_manage",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "skills_list"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 7.78,
+  "api_calls": 2,
+  "prompt_tokens_total": 107995,
+  "completion_tokens_total": 216,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 7.59,
+  "api_calls": 2,
+  "prompt_tokens_total": 62771,
+  "completion_tokens_total": 140,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureViewport",
+   "skill_manage",
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 6.41,
+  "api_calls": 2,
+  "prompt_tokens_total": 62751,
+  "completion_tokens_total": 126,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureViewport",
+   "skill_manage",
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 17.94,
+  "api_calls": 5,
+  "prompt_tokens_total": 144355,
+  "completion_tokens_total": 335,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureEditorImage",
+   "EditorToolset_EditorAppToolset_CaptureEditorImage"
+  ],
+  "success": false,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 13.06,
+  "api_calls": 4,
+  "prompt_tokens_total": 113753,
+  "completion_tokens_total": 267,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureEditorImage",
+   "EditorToolset_EditorAppToolset_CaptureEditorImage"
+  ],
+  "success": false,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 8.75,
+  "api_calls": 2,
+  "prompt_tokens_total": 107831,
+  "completion_tokens_total": 76,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 9.59,
+  "api_calls": 2,
+  "prompt_tokens_total": 107819,
+  "completion_tokens_total": 76,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 9.71,
+  "api_calls": 3,
+  "prompt_tokens_total": 94354,
+  "completion_tokens_total": 208,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE",
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 10.64,
+  "api_calls": 3,
+  "prompt_tokens_total": 94335,
+  "completion_tokens_total": 203,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE",
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 13.72,
+  "api_calls": 4,
+  "prompt_tokens_total": 114079,
+  "completion_tokens_total": 273,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE",
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 10.96,
+  "api_calls": 4,
+  "prompt_tokens_total": 114165,
+  "completion_tokens_total": 304,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE",
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 10.69,
+  "api_calls": 3,
+  "prompt_tokens_total": 162003,
+  "completion_tokens_total": 167,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 11.23,
+  "api_calls": 3,
+  "prompt_tokens_total": 162012,
+  "completion_tokens_total": 167,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 7.01,
+  "api_calls": 2,
+  "prompt_tokens_total": 62755,
+  "completion_tokens_total": 157,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 7.01,
+  "api_calls": 2,
+  "prompt_tokens_total": 62755,
+  "completion_tokens_total": 157,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 9.4,
+  "api_calls": 3,
+  "prompt_tokens_total": 84959,
+  "completion_tokens_total": 212,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 9.2,
+  "api_calls": 3,
+  "prompt_tokens_total": 84959,
+  "completion_tokens_total": 212,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 7.26,
+  "api_calls": 2,
+  "prompt_tokens_total": 107829,
+  "completion_tokens_total": 77,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 8.01,
+  "api_calls": 2,
+  "prompt_tokens_total": 107835,
+  "completion_tokens_total": 77,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 66.62,
+  "api_calls": 15,
+  "prompt_tokens_total": 507680,
+  "completion_tokens_total": 3428,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_label",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "EditorToolset_EditorAppToolset_FocusOnActors",
+   "EditorToolset_EditorAppToolset_CaptureViewport",
+   "vision_analyze",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_label",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "EditorToolset_EditorAppToolset_FocusOnActors",
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 51.89,
+  "api_calls": 11,
+  "prompt_tokens_total": 360889,
+  "completion_tokens_total": 2522,
+  "underlying_tools_called": [
+   "skills_list",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "skill_manage",
+   "editor_toolset_toolsets_actor_ActorTools_get_label",
+   "EditorToolset_EditorAppToolset_SelectActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "skill_manage",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_label",
+   "EditorToolset_EditorAppToolset_SelectActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 82.52,
+  "api_calls": 15,
+  "prompt_tokens_total": 558229,
+  "completion_tokens_total": 3085,
+  "underlying_tools_called": [
+   "skills_list",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "skill_manage",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "skill_manage",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 31.74,
+  "api_calls": 6,
+  "prompt_tokens_total": 197409,
+  "completion_tokens_total": 1057,
+  "underlying_tools_called": [
+   "skills_list",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "skill_manage",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 14.31,
+  "api_calls": 3,
+  "prompt_tokens_total": 162344,
+  "completion_tokens_total": 363,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "skill_manage"
+  ],
+  "success": false,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 13.66,
+  "api_calls": 3,
+  "prompt_tokens_total": 162337,
+  "completion_tokens_total": 370,
+  "underlying_tools_called": [
+   "skills_list",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube"
+  ],
+  "success": false,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 4.44,
+  "api_calls": 1,
+  "prompt_tokens_total": 31316,
+  "completion_tokens_total": 68,
+  "underlying_tools_called": [
+   "skill_manage"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "listing",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 5.63,
+  "api_calls": 1,
+  "prompt_tokens_total": 31316,
+  "completion_tokens_total": 55,
+  "underlying_tools_called": [],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 3.89,
+  "api_calls": 1,
+  "prompt_tokens_total": 27902,
+  "completion_tokens_total": 43,
+  "underlying_tools_called": [],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "bridge",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 4.38,
+  "api_calls": 1,
+  "prompt_tokens_total": 27896,
+  "completion_tokens_total": 66,
+  "underlying_tools_called": [
+   "skill_manage"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 1,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 4.25,
+  "api_calls": 1,
+  "prompt_tokens_total": 53877,
+  "completion_tokens_total": 41,
+  "underlying_tools_called": [],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "eager",
+  "scale": "editor",
+  "rep": 2,
+  "n_tools_registered": 62,
+  "elapsed_seconds": 4.29,
+  "api_calls": 1,
+  "prompt_tokens_total": 53886,
+  "completion_tokens_total": 37,
+  "underlying_tools_called": [],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 13.72,
+  "api_calls": 2,
+  "prompt_tokens_total": 109282,
+  "completion_tokens_total": 174,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 8.08,
+  "api_calls": 2,
+  "prompt_tokens_total": 109275,
+  "completion_tokens_total": 172,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 16.0,
+  "api_calls": 5,
+  "prompt_tokens_total": 148999,
+  "completion_tokens_total": 425,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 39.72,
+  "api_calls": 8,
+  "prompt_tokens_total": 248221,
+  "completion_tokens_total": 1310,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 7.99,
+  "api_calls": 2,
+  "prompt_tokens_total": 109237,
+  "completion_tokens_total": 138,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureViewport",
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 8.69,
+  "api_calls": 2,
+  "prompt_tokens_total": 109231,
+  "completion_tokens_total": 141,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureViewport",
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 22.04,
+  "api_calls": 7,
+  "prompt_tokens_total": 210837,
+  "completion_tokens_total": 629,
+  "underlying_tools_called": [
+   "browser_navigate",
+   "EditorToolset_EditorAppToolset_CaptureViewport",
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 18.61,
+  "api_calls": 6,
+  "prompt_tokens_total": 180004,
+  "completion_tokens_total": 531,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureViewport",
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 11.41,
+  "api_calls": 3,
+  "prompt_tokens_total": 164049,
+  "completion_tokens_total": 203,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE",
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 9.06,
+  "api_calls": 3,
+  "prompt_tokens_total": 164040,
+  "completion_tokens_total": 203,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE",
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 26.44,
+  "api_calls": 5,
+  "prompt_tokens_total": 147589,
+  "completion_tokens_total": 459,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE",
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 16.56,
+  "api_calls": 5,
+  "prompt_tokens_total": 147040,
+  "completion_tokens_total": 410,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE",
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 6.76,
+  "api_calls": 2,
+  "prompt_tokens_total": 109227,
+  "completion_tokens_total": 139,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 8.56,
+  "api_calls": 2,
+  "prompt_tokens_total": 109237,
+  "completion_tokens_total": 145,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 9.54,
+  "api_calls": 3,
+  "prompt_tokens_total": 85070,
+  "completion_tokens_total": 224,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 9.13,
+  "api_calls": 3,
+  "prompt_tokens_total": 85047,
+  "completion_tokens_total": 211,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 67.39,
+  "api_calls": 13,
+  "prompt_tokens_total": 734288,
+  "completion_tokens_total": 3180,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_actor_ActorTools_add_component",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_object_ObjectTools_list_properties",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_object_ObjectTools_set_properties",
+   "EditorToolset_EditorAppToolset_FocusOnActors",
+   "EditorToolset_EditorAppToolset_CaptureViewport",
+   "vision_analyze",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_actor_ActorTools_add_component",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_object_ObjectTools_list_properties",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_object_ObjectTools_set_properties",
+   "EditorToolset_EditorAppToolset_FocusOnActors",
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": false,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 90.57,
+  "api_calls": 15,
+  "prompt_tokens_total": 878311,
+  "completion_tokens_total": 3566,
+  "underlying_tools_called": [
+   "skills_list",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_add_component",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "skill_manage",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "EditorToolset_EditorAppToolset_SelectActors",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "EditorToolset_EditorAppToolset_FocusOnActors",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_actor_ActorTools_add_component",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_actor_transform",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "EditorToolset_EditorAppToolset_SelectActors",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "EditorToolset_EditorAppToolset_GetSelectedActors",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "EditorToolset_EditorAppToolset_FocusOnActors"
+  ],
+  "success": false,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 30.59,
+  "api_calls": 6,
+  "prompt_tokens_total": 208197,
+  "completion_tokens_total": 1121,
+  "underlying_tools_called": [
+   "skills_list",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 34.15,
+  "api_calls": 7,
+  "prompt_tokens_total": 236442,
+  "completion_tokens_total": 1154,
+  "underlying_tools_called": [
+   "skill_manage",
+   "skills_list",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform",
+   "skill_manage",
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube",
+   "editor_toolset_toolsets_actor_ActorTools_set_actor_transform"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 4.47,
+  "api_calls": 1,
+  "prompt_tokens_total": 54554,
+  "completion_tokens_total": 55,
+  "underlying_tools_called": [],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 4.37,
+  "api_calls": 1,
+  "prompt_tokens_total": 54554,
+  "completion_tokens_total": 60,
+  "underlying_tools_called": [],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 4.61,
+  "api_calls": 1,
+  "prompt_tokens_total": 27902,
+  "completion_tokens_total": 70,
+  "underlying_tools_called": [
+   "skill_manage"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 4.34,
+  "api_calls": 1,
+  "prompt_tokens_total": 27899,
+  "completion_tokens_total": 61,
+  "underlying_tools_called": [],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U7_deep_cut",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 33.57,
+  "api_calls": 5,
+  "prompt_tokens_total": 275130,
+  "completion_tokens_total": 1330,
+  "underlying_tools_called": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetSystemData",
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetSystemData",
+   "editor_toolset_toolsets_asset_AssetTools_exists"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U7_deep_cut",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 28.07,
+  "api_calls": 6,
+  "prompt_tokens_total": 347886,
+  "completion_tokens_total": 1103,
+  "underlying_tools_called": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetSystemData",
+   "NiagaraToolsets_NiagaraToolset_System_GetSystemSummary",
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetSystemData",
+   "NiagaraToolsets_NiagaraToolset_System_GetSystemSummary"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U7_deep_cut",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 18.36,
+  "api_calls": 4,
+  "prompt_tokens_total": 124101,
+  "completion_tokens_total": 628,
+  "underlying_tools_called": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U7_deep_cut",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 24.2,
+  "api_calls": 6,
+  "prompt_tokens_total": 190469,
+  "completion_tokens_total": 1085,
+  "underlying_tools_called": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U8_console_trap",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 32.83,
+  "api_calls": 6,
+  "prompt_tokens_total": 335905,
+  "completion_tokens_total": 1229,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U8_console_trap",
+  "mode": "listing",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 45.94,
+  "api_calls": 8,
+  "prompt_tokens_total": 452020,
+  "completion_tokens_total": 1745,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U8_console_trap",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 35.71,
+  "api_calls": 7,
+  "prompt_tokens_total": 216937,
+  "completion_tokens_total": 1520,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U8_console_trap",
+  "mode": "bridge",
+  "scale": "full",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 49.24,
+  "api_calls": 9,
+  "prompt_tokens_total": 288757,
+  "completion_tokens_total": 1996,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script",
+   "EditorToolset_EditorAppToolset_SearchCVars",
+   "EditorToolset_EditorAppToolset_GetCameraTransform",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment",
+   "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script",
+   "EditorToolset_EditorAppToolset_SearchCVars",
+   "EditorToolset_EditorAppToolset_GetCameraTransform"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U1_spawn_named",
+  "mode": "eager",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 15.89,
+  "api_calls": 2,
+  "prompt_tokens_total": 648323,
+  "completion_tokens_total": 215,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U2_viewport_shot",
+  "mode": "eager",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 14.7,
+  "api_calls": 2,
+  "prompt_tokens_total": 648161,
+  "completion_tokens_total": 88,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_CaptureViewport"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U3_play_mode",
+  "mode": "eager",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 20.53,
+  "api_calls": 3,
+  "prompt_tokens_total": 972457,
+  "completion_tokens_total": 151,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_StartPIE",
+   "EditorToolset_EditorAppToolset_StopPIE"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U4_selection_para",
+  "mode": "eager",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 17.38,
+  "api_calls": 2,
+  "prompt_tokens_total": 648169,
+  "completion_tokens_total": 104,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_GetSelectedActors"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U5_shape_chain",
+  "mode": "eager",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 21.85,
+  "api_calls": 3,
+  "prompt_tokens_total": 972831,
+  "completion_tokens_total": 373,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_scene_SceneTools_add_to_scene_from_class",
+   "editor_toolset_toolsets_primitive_PrimitiveTools_add_cube"
+  ],
+  "success": false,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U6_impossible",
+  "mode": "eager",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 7.93,
+  "api_calls": 1,
+  "prompt_tokens_total": 324045,
+  "completion_tokens_total": 45,
+  "underlying_tools_called": [],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U7_deep_cut",
+  "mode": "eager",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 33.64,
+  "api_calls": 5,
+  "prompt_tokens_total": 1622364,
+  "completion_tokens_total": 767,
+  "underlying_tools_called": [
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "editor_toolset_toolsets_asset_AssetTools_save_assets"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ },
+ {
+  "scenario_id": "U8_console_trap",
+  "mode": "eager",
+  "scale": "full",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 19.59,
+  "api_calls": 2,
+  "prompt_tokens_total": 648270,
+  "completion_tokens_total": 437,
+  "underlying_tools_called": [
+   "EditorToolset_EditorAppToolset_SearchCVars"
+  ],
+  "success": true,
+  "error": null,
+  "success_rescored": true
+ }
+]
\ No newline at end of file
diff --git a/mcp-research-data/ue_bench_summary.json b/mcp-research-data/ue_bench_summary.json
new file mode 100644
index 00000000000..bf7eaff55f8
--- /dev/null
+++ b/mcp-research-data/ue_bench_summary.json
@@ -0,0 +1,50 @@
+{
+ "editor|eager": {
+  "succ": 12,
+  "n": 12,
+  "api": 2.2,
+  "itok": 116979,
+  "usd": 0.58,
+  "sec": 9.0
+ },
+ "editor|bridge": {
+  "succ": 12,
+  "n": 12,
+  "api": 4.7,
+  "itok": 146979,
+  "usd": 0.73,
+  "sec": 18.7
+ },
+ "editor|listing": {
+  "succ": 12,
+  "n": 12,
+  "api": 5,
+  "itok": 163663,
+  "usd": 0.82,
+  "sec": 21.5
+ },
+ "full|eager": {
+  "succ": 8,
+  "n": 8,
+  "api": 2.5,
+  "itok": 810578,
+  "usd": 4.05,
+  "sec": 18.9
+ },
+ "full|bridge": {
+  "succ": 16,
+  "n": 16,
+  "api": 5.2,
+  "itok": 160844,
+  "usd": 0.8,
+  "sec": 22.5
+ },
+ "full|listing": {
+  "succ": 16,
+  "n": 16,
+  "api": 4.6,
+  "itok": 257264,
+  "usd": 1.29,
+  "sec": 23.8
+ }
+}
\ No newline at end of file
diff --git a/mcp-research-data/ue_discovery_rows.json b/mcp-research-data/ue_discovery_rows.json
new file mode 100644
index 00000000000..4c42539a026
--- /dev/null
+++ b/mcp-research-data/ue_discovery_rows.json
@@ -0,0 +1,1309 @@
+[
+ {
+  "scenario_id": "D1_sparkly_brighter",
+  "family": "D",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 57.29,
+  "api_calls": 9,
+  "searches_used": 0,
+  "prompt_tokens_total": 502973,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+  ],
+  "write_calls": [
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Not done \u2014 and I won't claim otherwise, because the change did not actually take.\n\nHere's what happened, honestly:\n\n- `SetVariable` on FX_Flame's `Brightness` returned `ok: true`, but reading it back two different ways still shows `Brightness = 1.0`. The write silently failed to persist. So the glow is still at its original value, not 5.0.\n\nI also have unresolved doubts I should surface rather tha"
+ },
+ {
+  "scenario_id": "D1_sparkly_brighter",
+  "family": "D",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 59.88,
+  "api_calls": 10,
+  "searches_used": 0,
+  "prompt_tokens_total": 558252,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "editor_toolset_toolsets_object_ObjectTools_list_properties",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties"
+  ],
+  "write_calls": [
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "I've now tried three different write/inspect paths and the picture is consistent but not favorable:\n\n- The component exposes exactly one glow-strength control: a float user parameter `Brightness`, currently 1.0.\n- My `SetVariable` to 5.0 returned `{\"ok\": true}`, but three independent read-backs all still report 1.0 \u2014 the write silently failed.\n- The property layer keeps surfacing an opaque `Entry_"
+ },
+ {
+  "scenario_id": "D1_sparkly_brighter",
+  "family": "D",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 51.8,
+  "api_calls": 10,
+  "searches_used": 0,
+  "prompt_tokens_total": 557992,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_GetVariable",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "editor_toolset_toolsets_object_ObjectTools_list_properties",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+  ],
+  "write_calls": [
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Same result: the set call reports `ok: true` twice, but Brightness stays pinned at 1.0 on every read-back. I'm not going to keep looping or claim success \u2014 the write is not landing.\n\nI'm stopping here rather than saying \"done,\" because it isn't. Here's the honest status:\n\nWhat I did:\n- Found Torch_3. It has one Niagara component, FX_Flame, whose only exposed intensity variable is Brightness (curre"
+ },
+ {
+  "scenario_id": "D1_sparkly_brighter",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 80.47,
+  "api_calls": 15,
+  "searches_used": 8,
+  "prompt_tokens_total": 530007,
+  "ue_calls": [
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_label",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "EditorToolset_EditorAppToolset_GetVisibleActors",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+  ],
+  "write_calls": [
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+  ],
+  "bridge_queries": [
+   "get actor components properties Unreal",
+   "set component property value actor Unreal",
+   "find actor by name in level",
+   "set object property value",
+   "list actors in level get all actors",
+   "find actor get actor reference by label spawn",
+   "Niagara component get user parameter float variable",
+   "get selected actors editor selection"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "I need to be honest: the change did not actually take.\n\nWhat I found and did:\n- Torch_3 resolves to /Game/Map:PersistentLevel.Torch_3, and its \"sparkly effect\" is the Niagara component FX_Flame.\n- That effect's glow control is the user variable \"Brightness\" (float), which was 1.0.\n- I called SetVariable to set Brightness to 5.0. It returned {\"ok\": true}.\n- But when I re-read the variable to verify"
+ },
+ {
+  "scenario_id": "D1_sparkly_brighter",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 56.7,
+  "api_calls": 11,
+  "searches_used": 5,
+  "prompt_tokens_total": 381159,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_object_ObjectTools_get_class",
+   "editor_toolset_toolsets_object_ObjectTools_get_class",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties"
+  ],
+  "write_calls": [],
+  "bridge_queries": [
+   "get actor components properties Unreal",
+   "set object property value",
+   "find actor by name label in level",
+   "list all actors in level get actors",
+   "find actor of class get all level actors editor"
+  ],
+  "success": false,
+  "error": null,
+  "final_response": "Both calls now return the identical `[{\"name\": \"Entry_0\", \"value\": 1.0}]` regardless of what I ask \u2014 class of the actor, class of the component, and properties of the component all give the same canned answer. The Unreal bridge is not actually resolving these queries; it's echoing a stub response.\n\nI'm going to stop here rather than blindly fire a `set_properties` write into an editor that's givin"
+ },
+ {
+  "scenario_id": "D1_sparkly_brighter",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 66.84,
+  "api_calls": 15,
+  "searches_used": 5,
+  "prompt_tokens_total": 500752,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+  ],
+  "write_calls": [
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+  ],
+  "bridge_queries": [
+   "get actor components properties Unreal",
+   "find actor by name in level",
+   "list all actors get actors in scene level editor",
+   "find actors by name pattern class filter scene",
+   "set niagara user parameter float variable component"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "Not done \u2014 I need to flag a problem honestly.\n\nThe sparkly effect on Torch_3 is a Niagara component (FX_Flame). It exposes exactly one brightness-type knob: a float user variable named \"Brightness\" (there is no parameter literally called \"glow strength,\" but Brightness is the effect's glow control).\n\nI issued the SetVariable call to change Brightness from 1.0 to 5.0, and the tool returned {\"ok\": t"
+ },
+ {
+  "scenario_id": "D2_fancy_geometry",
+  "family": "D",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 10.35,
+  "api_calls": 2,
+  "searches_used": 0,
+  "prompt_tokens_total": 109410,
+  "ue_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "write_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Nanite is now enabled on /Game/Meshes/SM_Rock.\n\ndone"
+ },
+ {
+  "scenario_id": "D2_fancy_geometry",
+  "family": "D",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 7.55,
+  "api_calls": 2,
+  "searches_used": 0,
+  "prompt_tokens_total": 109396,
+  "ue_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "write_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "D2_fancy_geometry",
+  "family": "D",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 6.7,
+  "api_calls": 2,
+  "searches_used": 0,
+  "prompt_tokens_total": 109393,
+  "ue_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "write_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "D2_fancy_geometry",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 19.98,
+  "api_calls": 5,
+  "searches_used": 1,
+  "prompt_tokens_total": 145449,
+  "ue_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled",
+   "olset_toolsets_static_mesh_StaticMeshTools_is_nanite_enabled"
+  ],
+  "write_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "bridge_queries": [
+   "enable Nanite on static mesh asset"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "Nanite is now enabled on /Game/Meshes/SM_Rock (verified: enabled = true), which triggered a mesh rebuild.\n\ndone"
+ },
+ {
+  "scenario_id": "D2_fancy_geometry",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 19.63,
+  "api_calls": 5,
+  "searches_used": 1,
+  "prompt_tokens_total": 146721,
+  "ue_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled",
+   "olset_toolsets_static_mesh_StaticMeshTools_is_nanite_enabled"
+  ],
+  "write_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "bridge_queries": [
+   "enable Nanite on static mesh asset"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "Nanite is now enabled on /Game/Meshes/SM_Rock (verified: enabled = true). The mesh rebuild was triggered automatically.\n\ndone"
+ },
+ {
+  "scenario_id": "D2_fancy_geometry",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 23.5,
+  "api_calls": 5,
+  "searches_used": 1,
+  "prompt_tokens_total": 146772,
+  "ue_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled",
+   "olset_toolsets_static_mesh_StaticMeshTools_is_nanite_enabled"
+  ],
+  "write_calls": [
+   "lset_toolsets_static_mesh_StaticMeshTools_set_nanite_enabled"
+  ],
+  "bridge_queries": [
+   "enable Nanite virtualized geometry on static mesh asset"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "Verified \u2014 Nanite is now enabled on /Game/Meshes/SM_Rock (query returned enabled = 1/true). The mesh rebuild triggered by the change should have it rendering with virtualized micro-polygon geometry.\n\ndone"
+ },
+ {
+  "scenario_id": "D3_simplified_versions",
+  "family": "D",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 51.77,
+  "api_calls": 10,
+  "searches_used": 0,
+  "prompt_tokens_total": 557678,
+  "ue_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_lod_thresholds",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_asset_AssetTools_get_asset_class"
+  ],
+  "write_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "editor_toolset_toolsets_asset_AssetTools_exists"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Every read tool \u2014 get_asset_class, get_lod_count, get_triangle_count, get_lod_thresholds \u2014 returns the identical placeholder `[{\"name\": \"Entry_0\", \"value\": 1.0}]`, and every write returns a bare `{\"ok\": true}`. These are not real responses reflecting the asset's state; the bridge is echoing canned stubs rather than executing against the live mesh.\n\nI can't honestly confirm the LOD chain was create"
+ },
+ {
+  "scenario_id": "D3_simplified_versions",
+  "family": "D",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 42.47,
+  "api_calls": 10,
+  "searches_used": 0,
+  "prompt_tokens_total": 557392,
+  "ue_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "editor_toolset_toolsets_asset_AssetTools_save_assets",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_lod_thresholds"
+  ],
+  "write_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "editor_toolset_toolsets_asset_AssetTools_save_assets"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Every read-back getter I have returns the identical placeholder, so I genuinely cannot verify the result through these tools \u2014 I won't claim success I can't confirm.\n\nHere's the honest status:\n\n- The LOD-generation call (`generate_lods` with retention [0.5, 0.25, 0.125, 0.0625], creating LOD1\u2013LOD4) returned `{\"ok\": true}`.\n- The save call also returned `{\"ok\": true}`.\n- However, every verification"
+ },
+ {
+  "scenario_id": "D3_simplified_versions",
+  "family": "D",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 48.8,
+  "api_calls": 10,
+  "searches_used": 0,
+  "prompt_tokens_total": 558199,
+  "ue_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "editor_toolset_toolsets_asset_AssetTools_save_assets",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "olset_toolsets_static_mesh_StaticMeshTools_is_nanite_enabled",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_lod_thresholds",
+   "editor_toolset_toolsets_object_ObjectTools_list_properties"
+  ],
+  "write_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "editor_toolset_toolsets_asset_AssetTools_save_assets"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Every tool call is returning the identical `[{\"name\": \"Entry_0\", \"value\": 1.0}]` \u2014 including `list_properties`, which should return a large list of property names. This isn't real editor data; the read side of the Unreal bridge is returning a constant stub for every query. That means:\n\n1. My `generate_lods` and `save_assets` calls returned `{\"ok\": true}`, but I cannot trust those either, since the"
+ },
+ {
+  "scenario_id": "D3_simplified_versions",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 44.0,
+  "api_calls": 6,
+  "searches_used": 1,
+  "prompt_tokens_total": 179153,
+  "ue_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count"
+  ],
+  "write_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods"
+  ],
+  "bridge_queries": [
+   "static mesh set LOD levels reduction"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "The verification is inconclusive. Every read tool \u2014 LOD count, triangle count at LOD 0, LOD 1, LOD 4 \u2014 returns the identical `[{\"name\":\"Entry_0\",\"value\":1.0}]` no matter what I ask. Those are not real answers; the query side of these tools is clearly not returning live mesh data (a genuine LOD count would be an integer like 1 or 5, and triangle counts would be large integers that differ per LOD).\n"
+ },
+ {
+  "scenario_id": "D3_simplified_versions",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 66.88,
+  "api_calls": 6,
+  "searches_used": 1,
+  "prompt_tokens_total": 183852,
+  "ue_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count"
+  ],
+  "write_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods"
+  ],
+  "bridge_queries": [
+   "set up LOD levels of detail static mesh reduction"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "The read/query tools in this connection consistently return the same placeholder object (`{\"name\":\"Entry_0\",\"value\":1.0}`) no matter what I ask \u2014 they aren't reporting real mesh state, so I can't use them to independently confirm the count. The write call itself, `generate_lods`, returned `{\"ok\": true}`, which is the actual success signal for the operation.\n\nSo: I generated the standard LOD chain "
+ },
+ {
+  "scenario_id": "D3_simplified_versions",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 29.89,
+  "api_calls": 5,
+  "searches_used": 2,
+  "prompt_tokens_total": 151428,
+  "ue_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods",
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_get_lod_count",
+   "lset_toolsets_static_mesh_StaticMeshTools_get_triangle_count"
+  ],
+  "write_calls": [
+   "r_toolset_toolsets_static_mesh_StaticMeshTools_generate_lods"
+  ],
+  "bridge_queries": [
+   "set up LODs level of detail static mesh",
+   "static mesh reduction simplify generate LOD"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "The verification calls are returning a static `Entry_0 = 1.0` placeholder regardless of what I ask \u2014 even for LOD index 3, which wouldn't exist before this operation. That's a broken/echo response from those two query tools, not a real reading, so I can't use them to confirm.\n\nThe authoritative signal I do have is the `generate_lods` call itself, which returned `ok: true`. That tool's contract is "
+ },
+ {
+  "scenario_id": "D4_maya_handoff",
+  "family": "D",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 39.75,
+  "api_calls": 7,
+  "searches_used": 0,
+  "prompt_tokens_total": 391921,
+  "ue_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_scene_SceneTools_get_current_level",
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence",
+   "ation_toolset_toolsets_sequencer_SequencerTools_get_bindings",
+   "olset_toolsets_sequencer_SequencerTools_get_current_sequence",
+   "editor_toolset_toolsets_asset_AssetTools_get_asset_class",
+   "toolset_toolsets_sequencer_SequencerTools_get_playback_range"
+  ],
+  "write_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence"
+  ],
+  "bridge_queries": [],
+  "success": false,
+  "error": null,
+  "final_response": "Now even `get_asset_class` \u2014 a plain asset query that returned a clean `{\"ok\": true}` moments ago via `exists` \u2014 is returning the same `[{\"name\": \"Entry_0\", \"value\": 1.0}]` blob. The bridge has degraded: it's now echoing one canned payload for every call regardless of tool or arguments. That means I have no trustworthy world reference, no real bindings, and no way to confirm an export actually wro"
+ },
+ {
+  "scenario_id": "D4_maya_handoff",
+  "family": "D",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 39.82,
+  "api_calls": 7,
+  "searches_used": 0,
+  "prompt_tokens_total": 391436,
+  "ue_calls": [
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence",
+   "olset_toolsets_sequencer_SequencerTools_get_current_sequence",
+   "ation_toolset_toolsets_sequencer_SequencerTools_get_bindings",
+   "editor_toolset_toolsets_scene_SceneTools_get_current_level",
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_asset_AssetTools_get_asset_class"
+  ],
+  "write_calls": [
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence",
+   "editor_toolset_toolsets_asset_AssetTools_exists"
+  ],
+  "bridge_queries": [],
+  "success": false,
+  "error": null,
+  "final_response": "The pattern is consistent: `exists` returns a clean `{\"ok\": true}`, but every tool that should return real *data* (asset class, bindings, current sequence, current level) returns the identical placeholder `[{\"name\": \"Entry_0\", \"value\": 1.0}]`. That's not valid output for any of those calls \u2014 the data-returning side of this editor connection is handing back a canned stub rather than actual state.\n\n"
+ },
+ {
+  "scenario_id": "D4_maya_handoff",
+  "family": "D",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 50.12,
+  "api_calls": 8,
+  "searches_used": 0,
+  "prompt_tokens_total": 451899,
+  "ue_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_scene_SceneTools_get_current_level",
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence",
+   "ation_toolset_toolsets_sequencer_SequencerTools_get_bindings",
+   "olset_toolsets_sequencer_SequencerTools_get_focused_sequence",
+   "EditorToolset_EditorAppToolset_IsPIERunning",
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets"
+  ],
+  "write_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence",
+   "EditorToolset_EditorAppToolset_IsPIERunning",
+   "editor_toolset_toolsets_asset_AssetTools_exists"
+  ],
+  "bridge_queries": [],
+  "success": false,
+  "error": null,
+  "final_response": "That confirms it. A nonexistent asset path returns `{\"ok\": true}` for `exists`, and `find_assets` returns the same canned `[{\"name\": \"Entry_0\", \"value\": 1.0}]` as everything else. The Unreal bridge is returning stubbed/echoed responses \u2014 it is not actually querying or driving the live editor. Every \"success\" is fake.\n\nI'm stopping rather than reporting a fabricated result. I did not export anythin"
+ },
+ {
+  "scenario_id": "D4_maya_handoff",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 100.07,
+  "api_calls": 12,
+  "searches_used": 8,
+  "prompt_tokens_total": 418308,
+  "ue_calls": [
+   "ation_toolset_toolsets_sequencer_SequencerTools_get_bindings",
+   "editor_toolset_toolsets_scene_SceneTools_get_current_level",
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "ation_toolset_toolsets_sequencer_SequencerTools_get_bindings",
+   "olset_toolsets_sequencer_SequencerTools_get_current_sequence"
+  ],
+  "write_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "editor_toolset_toolsets_asset_AssetTools_load_asset"
+  ],
+  "bridge_queries": [
+   "export level sequence to FBX",
+   "export cinematic sequence file",
+   "get editor world context",
+   "get level sequence bindings",
+   "get editor world game world reference",
+   "get current editor world level",
+   "does asset exist load asset by path",
+   "list assets in directory content browser"
+  ],
+  "success": false,
+  "error": null,
+  "final_response": "Every one of these Sequencer/binding tool calls returns the identical `[{\"name\": \"Entry_0\", \"value\": 1.0}]` payload. That is a canned stub response, not live editor data \u2014 the sequencer side of this MCP bridge is not returning real values. I can confirm the asset exists (`exists` and `load_asset` returned proper `{\"ok\": true}` shapes), but I cannot retrieve the actual bindings, and `export_fbx` re"
+ },
+ {
+  "scenario_id": "D4_maya_handoff",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 46.38,
+  "api_calls": 8,
+  "searches_used": 3,
+  "prompt_tokens_total": 258703,
+  "ue_calls": [
+   "ation_toolset_toolsets_sequencer_SequencerTools_get_bindings",
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence",
+   "olset_toolsets_sequencer_SequencerTools_get_current_sequence"
+  ],
+  "write_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence"
+  ],
+  "bridge_queries": [
+   "export level sequence FBX cinematic",
+   "load level sequence asset get bindings editor world",
+   "get editor world context object"
+  ],
+  "success": false,
+  "error": null,
+  "final_response": "Both `get_current_sequence` and `get_bindings` return the identical placeholder `[{\"name\": \"Entry_0\", \"value\": 1.0}]`. That's a canned/stub response, not real data \u2014 `get_current_sequence` should return a single LevelSequence object, not that. This tells me the mcp-unreal query layer is echoing a placeholder rather than returning real live-editor data for these calls.\n\nI'm going to stop here rathe"
+ },
+ {
+  "scenario_id": "D4_maya_handoff",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 55.88,
+  "api_calls": 8,
+  "searches_used": 5,
+  "prompt_tokens_total": 264045,
+  "ue_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "ation_toolset_toolsets_sequencer_SequencerTools_get_bindings",
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence",
+   "olset_toolsets_sequencer_SequencerTools_get_current_sequence",
+   "set_toolsets_sequencer_SequencerTools_get_tracks_on_sequence"
+  ],
+  "write_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "tion_toolset_toolsets_sequencer_SequencerTools_open_sequence"
+  ],
+  "bridge_queries": [
+   "export level sequence FBX for animation",
+   "load level sequence asset get bindings world context",
+   "get editor world context object",
+   "get editor world level sequence for sequencer operations",
+   "editor subsystem get editor world"
+  ],
+  "success": false,
+  "error": null,
+  "final_response": "That confirms it. Three different sequencer query tools \u2014 `get_bindings`, `get_current_sequence`, and `get_tracks_on_sequence` \u2014 all return the identical `[{\"name\": \"Entry_0\", \"value\": 1.0}]`. That's a canned placeholder, not live data. A real sequence with real bindings/tracks would return distinct results per call, and binding proxies would carry GUID `bindingId` fields.\n\nI'm going to stop here "
+ },
+ {
+  "scenario_id": "D5_automated_checks",
+  "family": "D",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 48.28,
+  "api_calls": 7,
+  "searches_used": 0,
+  "prompt_tokens_total": 389557,
+  "ue_calls": [
+   "AutomationTestToolset_AutomationTestToolset_ListTests",
+   "AutomationTestToolset_AutomationTestToolset_DiscoverTests",
+   "AutomationTestToolset_AutomationTestToolset_ListTests",
+   "AutomationTestToolset_AutomationTestToolset_ListTests"
+  ],
+  "write_calls": [
+   "AutomationTestToolset_AutomationTestToolset_DiscoverTests"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "I need to stop here rather than plow ahead, because I cannot honestly report a test count.\n\nWhat's wrong: The `ListTests` tool is documented to return `{\"tests\": [...], \"total\": N, \"returned\": N}`, but no matter how I call it \u2014 before discovery, after a forced rediscovery, with the correct empty filters and unlimited limit \u2014 it keeps returning the same placeholder `[{\"name\": \"Entry_0\", \"value\": 1."
+ },
+ {
+  "scenario_id": "D5_automated_checks",
+  "family": "D",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 24.77,
+  "api_calls": 5,
+  "searches_used": 0,
+  "prompt_tokens_total": 275022,
+  "ue_calls": [
+   "AutomationTestToolset_AutomationTestToolset_DiscoverTests",
+   "AutomationTestToolset_AutomationTestToolset_ListTests",
+   "AutomationTestToolset_AutomationTestToolset_ListTests"
+  ],
+  "write_calls": [
+   "AutomationTestToolset_AutomationTestToolset_DiscoverTests"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "Same malformed shape. I'm going to stop here rather than give you a number I can't stand behind.\n\nHere's the honest status:\n\n- DiscoverTests ran and reported ok.\n- ListTests is returning garbage \u2014 `[{\"name\": \"Entry_0\", \"value\": 1.0}]` \u2014 instead of its documented `{\"tests\": [...], \"total\": N}`. That's not a real test list, so I can't tell you how many correctness checks exist, and I have no reliabl"
+ },
+ {
+  "scenario_id": "D5_automated_checks",
+  "family": "D",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 16.12,
+  "api_calls": 3,
+  "searches_used": 0,
+  "prompt_tokens_total": 164190,
+  "ue_calls": [
+   "AutomationTestToolset_AutomationTestToolset_DiscoverTests",
+   "AutomationTestToolset_AutomationTestToolset_ListTests"
+  ],
+  "write_calls": [
+   "AutomationTestToolset_AutomationTestToolset_DiscoverTests"
+  ],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "The list came back with a single opaque entry (`Entry_0` = 1.0) rather than a normal roster of named test cases \u2014 that's not a coherent test list, so I can't honestly claim a count from it.\n\nHere's where things actually stand:\n\n- DiscoverTests returned only `{ok: true}` \u2014 no count.\n- ListTests returned a single malformed entry (`Entry_0`, value 1.0) with no test names, categories, or the correctly"
+ },
+ {
+  "scenario_id": "D5_automated_checks",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 23.35,
+  "api_calls": 5,
+  "searches_used": 1,
+  "prompt_tokens_total": 145851,
+  "ue_calls": [
+   "AutomationTestToolset_AutomationTestToolset_DiscoverTests",
+   "AutomationTestToolset_AutomationTestToolset_ListTests"
+  ],
+  "write_calls": [
+   "AutomationTestToolset_AutomationTestToolset_DiscoverTests"
+  ],
+  "bridge_queries": [
+   "run automated tests correctness checks unreal"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "That response shape is unexpected \u2014 I asked for the test list but got back `[{\"name\": \"Entry_0\", \"value\": 1.0}]`, which doesn't match the documented `{\"tests\": [...], \"total\": N}` schema. That's not a list of test paths I can hand to RunTests, and it doesn't give a trustworthy count.\n\nI'm going to stop here rather than guess. Running the checks requires real test paths from ListTests, and I didn't"
+ },
+ {
+  "scenario_id": "D5_automated_checks",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 93.36,
+  "api_calls": 8,
+  "searches_used": 0,
+  "prompt_tokens_total": 345245,
+  "ue_calls": [
+   "read_file",
+   "read_file",
+   "terminal",
+   "terminal",
+   "terminal",
+   "terminal",
+   "terminal",
+   "process"
+  ],
+  "write_calls": [
+   "read_file",
+   "read_file",
+   "terminal",
+   "terminal",
+   "terminal",
+   "terminal",
+   "terminal",
+   "process"
+  ],
+  "bridge_queries": [],
+  "success": false,
+  "error": null,
+  "final_response": "The suite is running cleanly and passing so far. It'll notify me on completion, but the deliverable here was to kick it off and report the count.\n\nDone.\n\nThe project's automated correctness checks are running \u2014 kicked off via the canonical runner `scripts/run_tests.sh` (per-file isolated pytest, the same path CI uses).\n\nCount: 43,143 tests collected (65 deselected, out of 43,208 total).\n\nThe full "
+ },
+ {
+  "scenario_id": "D5_automated_checks",
+  "family": "D",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 140.61,
+  "api_calls": 5,
+  "searches_used": 0,
+  "prompt_tokens_total": 207191,
+  "ue_calls": [
+   "read_file",
+   "read_file",
+   "terminal",
+   "terminal",
+   "terminal",
+   "terminal"
+  ],
+  "write_calls": [
+   "read_file",
+   "read_file",
+   "terminal",
+   "terminal",
+   "terminal",
+   "terminal"
+  ],
+  "bridge_queries": [],
+  "success": false,
+  "error": null,
+  "final_response": "The automated correctness checks are kicked off and running in the background (via the canonical `scripts/run_tests.sh`).\n\nCount: 43,143 tests collected (43,208 total, 65 deselected).\n\ndone\n\nThe full suite is running in the background \u2014 I'll be notified when it finishes. If you want me to report pass/fail once it completes, just say so."
+ },
+ {
+  "scenario_id": "A1_bake_lighting",
+  "family": "A",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 22.21,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54602,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "CANNOT: I have no tool that triggers a static lighting build/bake (Lightmass); my Unreal toolset only exposes scene/actor/asset/material/mesh editing and editor control, none of which invoke a lighting rebuild."
+ },
+ {
+  "scenario_id": "A1_bake_lighting",
+  "family": "A",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 14.02,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54605,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "CANNOT: My Unreal tools cover editor/asset/actor/blueprint/sequencer/etc. operations, but none of them trigger a static lighting build (Build Lighting / Lightmass bake) \u2014 there's no lighting-bake command exposed."
+ },
+ {
+  "scenario_id": "A1_bake_lighting",
+  "family": "A",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 22.62,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54605,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "CANNOT: There is no lighting-build/bake capability among my Unreal tools \u2014 they cover actors, assets, Blueprints, materials, sequencer, Niagara, PCG, physics, UMG, etc., but expose no Lightmass/\"Build Lighting\" (rebuild static lighting) action."
+ },
+ {
+  "scenario_id": "A1_bake_lighting",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 64.65,
+  "api_calls": 7,
+  "searches_used": 7,
+  "prompt_tokens_total": 240803,
+  "ue_calls": [
+   "s_programmatic_ProgrammaticToolset_get_execution_environment"
+  ],
+  "write_calls": [],
+  "bridge_queries": [
+   "build bake static lighting level",
+   "build lighting quality rebuild illumination lightmass",
+   "execute editor console command exec",
+   "run console command exec editor app world",
+   "precompute lightmap navigation build reflection captures HLOD",
+   "EditorAppToolset console command tick play save",
+   "get_execution_environment programmatic instructions allowed modules"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "That returned a malformed/empty response \u2014 not the documented instructions payload. The environment introspection isn't giving me usable info about allowed modules. Regardless, across the whole 843-tool catalog there is no tool that triggers a static lighting build:\n\n- No \"build lighting\" / Lightmass / rebuild-illumination tool exists.\n- The `EditorAppToolset` exposes CVars, PIE, viewport capture,"
+ },
+ {
+  "scenario_id": "A1_bake_lighting",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 76.84,
+  "api_calls": 8,
+  "searches_used": 8,
+  "prompt_tokens_total": 277578,
+  "ue_calls": [
+   "s_programmatic_ProgrammaticToolset_get_execution_environment",
+   "oolsets_programmatic_ProgrammaticToolset_execute_tool_script"
+  ],
+  "write_calls": [
+   "oolsets_programmatic_ProgrammaticToolset_execute_tool_script"
+  ],
+  "bridge_queries": [
+   "build static lighting bake level",
+   "build lighting lightmass rebuild editor command",
+   "editor exec console command run",
+   "build geometry navigation level editor subsystem build all",
+   "precompute lightmap volumetric lightmap reflection capture",
+   "EditorAppToolset exec console command execute editor",
+   "get_execution_environment available modules python",
+   "bake lighting build lighting only swarm lightmass quality production"
+  ],
+  "success": false,
+  "error": null,
+  "final_response": "The script sandbox swallowed my probe and returned a canned `{\"ok\": true}` rather than my actual `info` dict \u2014 it doesn't execute arbitrary `unreal` module code. There is no tool anywhere in the 843-tool catalog for building/baking static lighting (no Build Lighting, no Lightmass invoke, no console-exec, no EditorBuildUtils binding), and the Slate route can't drive the modal Lightmass build to com"
+ },
+ {
+  "scenario_id": "A1_bake_lighting",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 71.86,
+  "api_calls": 8,
+  "searches_used": 8,
+  "prompt_tokens_total": 283427,
+  "ue_calls": [
+   "s_programmatic_ProgrammaticToolset_get_execution_environment"
+  ],
+  "write_calls": [],
+  "bridge_queries": [
+   "build bake static lighting level",
+   "build lighting lightmass rebuild level",
+   "editor level build geometry navigation execute console command",
+   "execute console command exec run editor app",
+   "precompute lightmap swarm quality reflection capture build",
+   "Slate click menu button toolbar Build menu",
+   "EditorApp toolset available capabilities editor commands list",
+   "get_execution_environment python modules available"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "I have enough to make a determination. Let me be precise rather than embark on a fragile, many-step UI-poking exercise that isn't what a lighting-build tool is.\n\nThe honest situation: none of my Unreal tools expose a static-lighting build. There's no BuildLighting/Lightmass/Swarm tool, no console-command executor, and the `execute_tool_script` sandbox runs against the toolset APIs only (it doesn't"
+ },
+ {
+  "scenario_id": "A2_undo",
+  "family": "A",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 19.25,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54601,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "CANNOT: I have no undo/transaction tool \u2014 my Unreal toolset exposes creation, editing, and inspection operations but nothing that triggers the editor's undo stack."
+ },
+ {
+  "scenario_id": "A2_undo",
+  "family": "A",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 9.68,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54592,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "CANNOT: I have no undo/redo tool \u2014 the Unreal toolset exposes creation/edit/query operations but no editor undo command."
+ },
+ {
+  "scenario_id": "A2_undo",
+  "family": "A",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 11.86,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54598,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "CANNOT: I have no undo/transaction-history tool \u2014 my Unreal tools only perform forward operations (create/modify/query assets and actors), none of which can revert your last editor change."
+ },
+ {
+  "scenario_id": "A2_undo",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 22.54,
+  "api_calls": 3,
+  "searches_used": 4,
+  "prompt_tokens_total": 90096,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [
+   "undo editor transaction",
+   "unreal editor undo redo",
+   "undo last action transaction rollback",
+   "editor level undo cancel transaction begin end"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "I've searched the tool catalog specifically for undo/transaction/rollback capabilities across the Unreal toolsets and found none. The only references to \"undo\" are descriptive (e.g. a Niagara fix noting it's \"undoable via the editor undo stack\") \u2014 there is no tool that actually triggers an editor undo. There's also no general \"execute editor command\" tool I could route an `Undo` through.\n\nCANNOT: "
+ },
+ {
+  "scenario_id": "A2_undo",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 9.6,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 27949,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "I don't have an undo capability in my Unreal tools.\n\nCANNOT: none of my mcp-unreal tools expose an editor undo/transaction-rollback action."
+ },
+ {
+  "scenario_id": "A2_undo",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 10.12,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 27946,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "I don't have an undo capability in my Unreal tools.\n\nCANNOT: none of my mcp-unreal tools expose an editor undo/transaction-rollback action."
+ },
+ {
+  "scenario_id": "A3_foliage",
+  "family": "A",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 36.8,
+  "api_calls": 4,
+  "searches_used": 2,
+  "prompt_tokens_total": 225696,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets"
+  ],
+  "write_calls": [],
+  "bridge_queries": [
+   "foliage paint scatter instanced foliage",
+   "spawn actors on landscape hillside terrain trace"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "The level contains only a Torch and a Crate \u2014 no Landscape, no hillside, and no terrain of any kind. The asset searches for \"tree\"/\"Landscape\" return only a garbage placeholder (`Entry_0`), meaning there are no pine tree or landscape assets in the project either.\n\nThere's genuinely nothing to paint onto and nothing to paint. And separately, my tool surface has no Foliage-painting capability (no In"
+ },
+ {
+  "scenario_id": "A3_foliage",
+  "family": "A",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 54.41,
+  "api_calls": 7,
+  "searches_used": 1,
+  "prompt_tokens_total": 395711,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_get_current_level",
+   "PCGToolset_PCGToolset_ListNativeNodes",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets"
+  ],
+  "write_calls": [],
+  "bridge_queries": [
+   "foliage paint scatter instanced static mesh"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "CANNOT: The current level (Entry_0 / \"Map\") contains only a Torch and a Crate \u2014 there is no landscape, terrain, or hillside actor to scatter foliage onto, and I have no foliage-painting tool (only PCG/static-mesh tooling, and asset discovery returns nothing usable), so there's no hillside surface to paint pine trees across."
+ },
+ {
+  "scenario_id": "A3_foliage",
+  "family": "A",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 33.25,
+  "api_calls": 5,
+  "searches_used": 2,
+  "prompt_tokens_total": 288464,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_get_current_level",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_asset_AssetTools_find_assets"
+  ],
+  "write_calls": [],
+  "bridge_queries": [
+   "paint foliage instanced tree scatter on terrain",
+   "spawn actors on landscape surface trace world position"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "CANNOT: The current level has no landscape/terrain/hillside (only a Torch and a Crate actor), and the project contains no pine-tree or usable tree mesh assets to scatter \u2014 so there is nothing to paint foliage onto or with."
+ },
+ {
+  "scenario_id": "A3_foliage",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 29.52,
+  "api_calls": 4,
+  "searches_used": 7,
+  "prompt_tokens_total": 136425,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [
+   "foliage paint instanced foliage type add",
+   "unreal spawn actor mesh place static mesh in level",
+   "foliage instance scatter landscape terrain",
+   "spawn actor from static mesh into level at location transform",
+   "line trace raycast ground height query terrain surface",
+   "FoliageType InstancedStaticMesh HISM procedural foliage volume",
+   "find asset by name search content browser tree mesh"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "I've surveyed the toolset thoroughly. There is no dedicated foliage tool (no FoliageType, no InstancedStaticMeshComponent painting, no foliage-spawner, no `add_foliage_instances`). The foliage-adjacent capabilities I have are:\n\n- `scene.trace_world` \u2014 returns only a scalar distance, not a hit location/normal, and takes no channel/actor filter.\n- `scene.add_to_scene_from_asset` / `add_to_scene_from"
+ },
+ {
+  "scenario_id": "A3_foliage",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 26.65,
+  "api_calls": 4,
+  "searches_used": 6,
+  "prompt_tokens_total": 134088,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [
+   "foliage paint scatter instanced static mesh",
+   "spawn actor place static mesh in level",
+   "foliage type add instances landscape hillside terrain",
+   "level actor spawn transform world outliner add to level",
+   "FoliageTools paint foliage instanced foliage actor procedural foliage",
+   "landscape height sample raycast line trace ground surface elevation"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "The verdict is clear across four searches spanning 843 tools: there is no Foliage toolset in my Unreal capabilities. There's no FoliageType, no InstancedFoliageActor painting, no \"paint foliage\" instances API, and no landscape/terrain query. The mcp-unreal surface covers static meshes, actors, scene spawning, blueprints, Niagara, sequencer, UMG, etc. \u2014 but foliage painting is absent.\n\nCANNOT: My U"
+ },
+ {
+  "scenario_id": "A3_foliage",
+  "family": "A",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 50.46,
+  "api_calls": 7,
+  "searches_used": 6,
+  "prompt_tokens_total": 240708,
+  "ue_calls": [
+   "SemanticSearchToolset_SemanticSearchToolset_Search",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "SemanticSearchToolset_SemanticSearchToolset_Search"
+  ],
+  "write_calls": [],
+  "bridge_queries": [
+   "foliage paint instance mesh scatter",
+   "foliage type add instances procedural",
+   "landscape terrain heightmap hillside trace ground",
+   "foliage instanced static mesh component actor",
+   "list actors in scene find asset search content browser",
+   "get world bounds actor location transform"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "The picture is now clear and I've verified it rather than assumed:\n\n1. The level contains exactly two actors \u2014 a Torch and a Crate. There is no landscape, no terrain, no hillside actor at all.\n2. There is no pine tree (or any tree/foliage) asset in the project's content \u2014 semantic search returns only a placeholder \"Entry_0\" stub with no asset path, across multiple queries.\n\nCANNOT: the current lev"
+ },
+ {
+  "scenario_id": "S1_capability_survey",
+  "family": "S",
+  "mode": "listing",
+  "rep": 1,
+  "elapsed_seconds": 6.76,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54653,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "a) YES \u2014 AutomationTestToolset exposes RunTests/RunTestsByFilter/DiscoverTests, so I can trigger automation tests from here.\nb) NO \u2014 no lighting-build/Lightmass tool exists in my toolset; there's no \"bake static lighting\" capability exposed.\nc) YES \u2014 StaticMeshTools_set_nanite_enabled is available to toggle Nanite on a static mesh.\nd) NO \u2014 no foliage-painting toolset is exposed; nothing maps to in"
+ },
+ {
+  "scenario_id": "S1_capability_survey",
+  "family": "S",
+  "mode": "listing",
+  "rep": 2,
+  "elapsed_seconds": 6.57,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54659,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "a) YES \u2014 AutomationTestToolset can discover, run, and report on tests (RunTests / RunTestsByFilter).\nb) NO \u2014 no lighting-build/Lightmass bake tool is exposed; nothing triggers a static lighting build.\nc) YES \u2014 StaticMeshTools_set_nanite_enabled toggles Nanite on a static mesh.\nd) NO \u2014 no foliage-painting tool exists; I can place actors/meshes but not paint procedural foliage instances.\ne) YES \u2014 Se"
+ },
+ {
+  "scenario_id": "S1_capability_survey",
+  "family": "S",
+  "mode": "listing",
+  "rep": 3,
+  "elapsed_seconds": 7.07,
+  "api_calls": 1,
+  "searches_used": 0,
+  "prompt_tokens_total": 54659,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [],
+  "success": true,
+  "error": null,
+  "final_response": "a) YES \u2014 AutomationTestToolset can discover, run, and report tests (RunTests, RunTestsByFilter, GetTestResults).\nb) NO \u2014 no lighting/GI build tool is exposed (no \"build lighting\"/Lightmass action in my toolset).\nc) YES \u2014 StaticMeshTools_set_nanite_enabled toggles Nanite on a static mesh.\nd) NO \u2014 no foliage-painting tool exists; I can spawn/place actors but not paint foliage instances.\ne) YES \u2014 Seq"
+ },
+ {
+  "scenario_id": "S1_capability_survey",
+  "family": "S",
+  "mode": "bridge",
+  "rep": 1,
+  "elapsed_seconds": 18.51,
+  "api_calls": 2,
+  "searches_used": 5,
+  "prompt_tokens_total": 64358,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [
+   "Unreal automation test run",
+   "Unreal bake static lighting build",
+   "Unreal Nanite static mesh enable",
+   "Unreal foliage paint",
+   "Unreal level sequence export FBX"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "a) YES \u2014 AutomationTestToolset exposes DiscoverTests/ListTests/RunTests/RunTestsByFilter plus status and results readers, a complete run-and-report path.\n\nb) NO \u2014 no lightmass/build-lighting tool exists; the only \"bake\" tools are Sequencer transform/Control-Rig bakes, which are animation baking, not static-lighting builds.\n\nc) YES \u2014 StaticMeshTools.set_nanite_enabled toggles Nanite on a static mes"
+ },
+ {
+  "scenario_id": "S1_capability_survey",
+  "family": "S",
+  "mode": "bridge",
+  "rep": 2,
+  "elapsed_seconds": 25.08,
+  "api_calls": 3,
+  "searches_used": 7,
+  "prompt_tokens_total": 103574,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [
+   "run automation tests unreal editor",
+   "bake static lighting build lightmass",
+   "enable Nanite static mesh settings",
+   "paint foliage instances landscape",
+   "export level sequence FBX cinematic",
+   "build lighting rebuild lightmaps precompute",
+   "foliage tool add instanced foliage spawn"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "a) YES \u2014 dedicated AutomationTestToolset (DiscoverTests, ListTests, RunTests/RunTestsByFilter, GetTestResults) covers discovery and execution.\n\nb) NO \u2014 no build-lighting/Lightmass tool exists; searches only surface outliner \"Lighting\" folder helpers, not a lightmap bake. (Could be forced via the generic execute_tool_script Python escape hatch, but there is no first-class capability.)\n\nc) YES \u2014 Sta"
+ },
+ {
+  "scenario_id": "S1_capability_survey",
+  "family": "S",
+  "mode": "bridge",
+  "rep": 3,
+  "elapsed_seconds": 25.14,
+  "api_calls": 4,
+  "searches_used": 7,
+  "prompt_tokens_total": 133954,
+  "ue_calls": [],
+  "write_calls": [],
+  "bridge_queries": [
+   "run automation tests unreal editor",
+   "bake static lighting build lightmass",
+   "enable Nanite static mesh",
+   "paint foliage instance landscape",
+   "export level sequence FBX",
+   "build lighting rebuild lightmaps GI precompute level",
+   "foliage spawn scatter procedural mesh paint tool"
+  ],
+  "success": true,
+  "error": null,
+  "final_response": "a) YES \u2014 AutomationTestToolset exposes DiscoverTests, ListTests, RunTests/RunTestsByFilter, plus status/results tools.\nb) NO \u2014 no lighting-build/Lightmass/precompute tool exists; searches return only outliner-folder and unrelated \"bake\" (Sequencer transform) tools, not static-lighting bake.\nc) YES \u2014 StaticMeshTools.set_nanite_enabled toggles Nanite on a static mesh (with is_nanite_enabled to verif"
+ }
+]
\ No newline at end of file
diff --git a/mcp-research-data/ue_hard_haiku_rows.json b/mcp-research-data/ue_hard_haiku_rows.json
new file mode 100644
index 00000000000..4e2d4540c21
--- /dev/null
+++ b/mcp-research-data/ue_hard_haiku_rows.json
@@ -0,0 +1,1642 @@
+[
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 11.19,
+  "api_calls": 3,
+  "prompt_tokens_total": 119904,
+  "first_tool": [
+   "set",
+   "material"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The material M_Stone has been successfully assigned to slot 0 of the SM_Rock mesh."
+ },
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 10.89,
+  "api_calls": 3,
+  "prompt_tokens_total": 119922,
+  "first_tool": [
+   "set",
+   "material"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Material /Game/Mats/M_Stone has been assigned to slot 0 of the mesh asset /Game/Meshes/SM_Rock."
+ },
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 15.01,
+  "api_calls": 5,
+  "prompt_tokens_total": 111559,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots",
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "assign material mesh slot unreal"
+   ],
+   [
+    "tool_search",
+    "static mesh material slots get names"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 9.92,
+  "api_calls": 3,
+  "prompt_tokens_total": 65150,
+  "first_tool": [
+   "set",
+   "material"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "unreal assign material mesh slot"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 13.95,
+  "api_calls": 4,
+  "prompt_tokens_total": 160299,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots",
+   "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The material `/Game/Mats/M_Cloth` has been successfully assigned to slot 1 of the skeletal mesh `/Game/Chars/SK_Guard`."
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 14.39,
+  "api_calls": 4,
+  "prompt_tokens_total": 160307,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots",
+   "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 18.18,
+  "api_calls": 5,
+  "prompt_tokens_total": 111698,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots",
+   "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Unreal Engine assign material slot skeletal mesh"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 17.81,
+  "api_calls": 5,
+  "prompt_tokens_total": 111344,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots",
+   "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "set material skeletal mesh slot"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 15.46,
+  "api_calls": 3,
+  "prompt_tokens_total": 120710,
+  "first_tool": [
+   "add",
+   "row"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Added row 'Heavy' to /Game/Data/CT_Damage with value 42 at time 0."
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 14.85,
+  "api_calls": 4,
+  "prompt_tokens_total": 159929,
+  "first_tool": [
+   "add",
+   "row"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 15.27,
+  "api_calls": 4,
+  "prompt_tokens_total": 89922,
+  "first_tool": [
+   "add",
+   "row"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Unreal data table add row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Row 'Heavy' has been added to /Game/Data/CT_Damage with value 42 at time 0."
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 41.17,
+  "api_calls": 14,
+  "prompt_tokens_total": 336628,
+  "first_tool": [
+   "add",
+   "rows"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 1,
+  "success": false,
+  "ue_calls": [
+   "editor_toolset_toolsets_data_table_DataTableTools_add_rows",
+   "editor_toolset_toolsets_data_table_DataTableTools_get_rows",
+   "editor_toolset_toolsets_data_table_DataTableTools_list_rows",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Unreal data table add row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_data_table_DataTableTools_add_rows"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_data_table_DataTableTools_get_rows"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_data_table_DataTableTools_add_rows"
+   ],
+   [
+    "tool_search",
+    "Unreal data table set row value"
+   ],
+   [
+    "tool_search",
+    "Unreal data table set cell property"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_data_table_DataTableTools_set_rows"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_data_table_DataTableTools_get_rows"
+   ],
+   [
+    "tool_search",
+    "Unreal list data table rows"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_data_table_DataTableTools_list_rows"
+   ],
+   [
+    "tool_search",
+    "Unreal curve table add row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Row \"Heavy\" has been added to /Game/Data/CT_Damage with value 42 at time 0."
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 11.6,
+  "api_calls": 3,
+  "prompt_tokens_total": 119772,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The 'Combat.Stun' gameplay tag has been registered in the project's tag registry. Designers can now use it in the Unreal Editor."
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 12.42,
+  "api_calls": 4,
+  "prompt_tokens_total": 160853,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "gameplay tags add register"
+   ],
+   [
+    "tool_describe",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The gameplay tag 'Combat.Stun' has been registered in the project's tag registry. Designers can now use it in their gameplay systems and effects."
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 19.83,
+  "api_calls": 6,
+  "prompt_tokens_total": 136043,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "unreal gameplay tag register create"
+   ],
+   [
+    "tool_search",
+    "unreal add gameplay tag"
+   ],
+   [
+    "tool_search",
+    "GameplayTagsToolset AddTag"
+   ],
+   [
+    "tool_describe",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The gameplay tag 'Combat.Stun' has been successfully registered in your project's tag registry. Designers can now use it throughout the project."
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 21.24,
+  "api_calls": 7,
+  "prompt_tokens_total": 156137,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Unreal gameplay tag register"
+   ],
+   [
+    "tool_search",
+    "Unreal add gameplay tag registry"
+   ],
+   [
+    "tool_describe",
+    "GameplayTagsToolset_GameplayTagsToolset_GetTagInfo"
+   ],
+   [
+    "tool_search",
+    "GameplayTagsToolset add"
+   ],
+   [
+    "tool_describe",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The gameplay tag 'Combat.Stun' has been successfully registered in the project's tag registry. Designers can now use this tag in their gameplay logic, abilities, effects, and other systems."
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 15.35,
+  "api_calls": 4,
+  "prompt_tokens_total": 163213,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_add_tag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Crate_2 is now tagged with 'loot' and your spawner script can find it."
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 10.64,
+  "api_calls": 3,
+  "prompt_tokens_total": 119525,
+  "first_tool": [
+   "add",
+   "tag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_actor_ActorTools_add_tag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The 'loot' tag has been added to Crate_2."
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 9.75,
+  "api_calls": 3,
+  "prompt_tokens_total": 64815,
+  "first_tool": [
+   "add",
+   "tag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_actor_ActorTools_add_tag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "unreal engine add tag actor"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Crate_2 is now tagged with 'loot' and your spawner script can find it."
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 10.79,
+  "api_calls": 3,
+  "prompt_tokens_total": 64750,
+  "first_tool": [
+   "add",
+   "tag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_actor_ActorTools_add_tag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Unreal actor tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The actor Crate_2 now has the 'loot' tag and your spawner script can find it."
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 14.51,
+  "api_calls": 3,
+  "prompt_tokens_total": 119497,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Set Torch_3's FX_Flame Niagara component Brightness user parameter to 5.0."
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 25.28,
+  "api_calls": 6,
+  "prompt_tokens_total": 252049,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. The Brightness user parameter on the Torch_3 actor's FX_Flame Niagara component has been set to 5.0."
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 40.63,
+  "api_calls": 11,
+  "prompt_tokens_total": 299524,
+  "first_tool": [
+   "execution",
+   "environment"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "et_toolsets_programmatic_ProgrammaticToolset_get_execution_environment"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "unreal actor parameter component"
+   ],
+   [
+    "tool_search",
+    "get actor by name unreal"
+   ],
+   [
+    "tool_describe",
+    "animation_toolset_toolsets_sequencer_SequencerTools_add_actors_by_name"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_search",
+    "get selected actor unreal editor"
+   ],
+   [
+    "tool_search",
+    "find actor reference world"
+   ],
+   [
+    "tool_search",
+    "actor by label name get world"
+   ],
+   [
+    "tool_search",
+    "unreal scene tools spawn actor"
+   ],
+   [
+    "tool_search",
+    "EditorLevelLibrary find actor"
+   ],
+   [
+    "tool_search",
+    "unreal python execute command"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_programmatic_ProgrammaticToolset_execute_tool_script"
+   ],
+   [
+    "tool_search",
+    "get execution environment"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_programmatic_ProgrammaticToolset_get_execution_environment"
+   ]
+  ],
+  "error": null,
+  "final_response": "Response truncated due to output length limit"
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 56.88,
+  "api_calls": 15,
+  "prompt_tokens_total": 403694,
+  "first_tool": [
+   "computer",
+   "use"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "computer_use",
+   "computer_use"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Unreal actor component parameter property set"
+   ],
+   [
+    "tool_search",
+    "Unreal find actor user parameter Niagara"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_search",
+    "Unreal find actor by name instance"
+   ],
+   [
+    "tool_search",
+    "Unreal get selected actor level"
+   ],
+   [
+    "tool_search",
+    "Unreal actor path reference object by name"
+   ],
+   [
+    "tool_search",
+    "Unreal get actor components Niagara component"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_search",
+    "Unreal get actor by label name object path soft reference"
+   ],
+   [
+    "tool_search",
+    "Unreal construct soft object reference path"
+   ],
+   [
+    "tool_describe",
+    "animation_toolset_toolsets_sequencer_SequencerTools_add_actors_by_name"
+   ],
+   [
+    "tool_search",
+    "Unreal world editor command console execute"
+   ],
+   [
+    "tool_search",
+    "Niagara component"
+   ],
+   [
+    "tool_search",
+    "Unreal Property refPath soft path string"
+   ],
+   [
+    "tool_search",
+    "EditorAppToolset"
+   ]
+  ],
+  "error": null,
+  "final_response": "I've identified the tools needed to complete this task but haven't yet executed it due to tool-call limits. Here's what I found:\n\n**The Solution:**\n1. Tool `NiagaraToolsets_NiagaraToolset_Component_SetVariable` is exactly what I need \u2014 it sets user variables on a Niagara component.\n2. Tool `editor_t"
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 14.53,
+  "api_calls": 3,
+  "prompt_tokens_total": 124430,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Added a user-exposed float called 'WindStrength' to /Game/FX/NS_Sparks with a default value of 1.0. Every instance of this effect can now override it."
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 12.51,
+  "api_calls": 3,
+  "prompt_tokens_total": 124434,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Added a user-exposed float parameter 'WindStrength' with default value 1.0 to /Game/FX/NS_Sparks. Every instance can now override it."
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 22.77,
+  "api_calls": 6,
+  "prompt_tokens_total": 139716,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "unreal engine niagara parameter expose"
+   ],
+   [
+    "tool_search",
+    "niagara system add parameter user exposed"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+   ],
+   [
+    "tool_search",
+    "niagara system add user variable parameter"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Added user-exposed 'WindStrength' float parameter (default value: 1.0) to /Game/FX/NS_Sparks. Every instance of this effect can now override it."
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 19.01,
+  "api_calls": 6,
+  "prompt_tokens_total": 144235,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "niagara parameter add expose unreal"
+   ],
+   [
+    "tool_search",
+    "Niagara parameter add user exposed"
+   ],
+   [
+    "tool_search",
+    "NiagaraToolset System AddUserVariable"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Added the user-exposed float parameter 'WindStrength' to `/Game/FX/NS_Sparks` with a default value of 1.0. Every instance can now override it."
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 52.08,
+  "api_calls": 15,
+  "prompt_tokens_total": 618273,
+  "first_tool": [
+   "computer",
+   "use"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 1,
+  "success": false,
+  "ue_calls": [
+   "computer_use",
+   "computer_use",
+   "computer_use",
+   "EditorToolset_EditorAppToolset_CaptureEditorImage",
+   "vision_analyze",
+   "terminal",
+   "terminal",
+   "terminal",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Screenshot",
+   "terminal"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "EditorToolset_EditorAppToolset_CaptureEditorImage"
+   ],
+   [
+    "tool_call",
+    "EditorToolset_EditorAppToolset_CaptureEditorImage"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ]
+  ],
+  "error": null,
+  "final_response": "I've encountered a blocker that prevents completing your request.\n\n**What I attempted:**\n1. Used `CaptureEditorImage` to capture the full Unreal Editor \u2014 it returned a path `/tmp/ue_capture_0001.png`\n2. Discovered the `SlateInspectorToolset_SlateInspectorToolset_Screenshot` tool, which is designed s"
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 16.29,
+  "api_calls": 5,
+  "prompt_tokens_total": 199656,
+  "first_tool": [
+   "computer",
+   "use"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "computer_use",
+   "computer_use",
+   "terminal",
+   "computer_use"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "The Unreal Editor window is not currently accessible or active. It appears there are no open windows available. Could you verify that the Unreal Engine 5.8 editor is running and visible on your display, then I can capture the Details panel for you."
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 12.8,
+  "api_calls": 4,
+  "prompt_tokens_total": 85393,
+  "first_tool": [
+   "computer",
+   "use"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "computer_use",
+   "computer_use",
+   "computer_use"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "It appears the Unreal Editor is not currently running or accessible. According to the initial context, the editor should be running and connected through the MCP tools. Can you confirm the Unreal Editor is open? If it is, I may need to focus it first or there may be a display/connection issue."
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 16.43,
+  "api_calls": 5,
+  "prompt_tokens_total": 108314,
+  "first_tool": [
+   "computer",
+   "use"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "computer_use",
+   "computer_use",
+   "computer_use",
+   "computer_use"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "I'm unable to capture the Unreal Editor window. The computer_use tool isn't finding any windows at 0x0 resolution. This suggests either the editor isn't active/visible or there's a display setup issue.\n\nCan you verify that the Unreal Editor window is currently visible and active on screen? If it is,"
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 10.31,
+  "api_calls": 3,
+  "prompt_tokens_total": 119477,
+  "first_tool": [
+   "save",
+   "actor"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 11.63,
+  "api_calls": 3,
+  "prompt_tokens_total": 119525,
+  "first_tool": [
+   "save",
+   "actor"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Crate_2's changes have been persisted to disk."
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 13.8,
+  "api_calls": 3,
+  "prompt_tokens_total": 64771,
+  "first_tool": [
+   "save",
+   "actor"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "unreal save actor persist changes disk"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Crate_2's changes have been saved to disk."
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 11.4,
+  "api_calls": 3,
+  "prompt_tokens_total": 64759,
+  "first_tool": [
+   "save",
+   "actor"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Unreal save actor persist changes"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 12.09,
+  "api_calls": 3,
+  "prompt_tokens_total": 119404,
+  "first_tool": [
+   "EditorAppToolset",
+   "GetVisibleActors"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "EditorToolset_EditorAppToolset_GetVisibleActors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "EditorToolset_EditorAppToolset_GetVisibleActors"
+   ],
+   [
+    "tool_call",
+    "EditorToolset_EditorAppToolset_GetVisibleActors"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done.\n\nCurrent level panel contents:\n- Torch_3 (Actor) with NiagaraComponent 'FX_Flame'\n- Crate_2 (StaticMeshActor)"
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 15.61,
+  "api_calls": 3,
+  "prompt_tokens_total": 119381,
+  "first_tool": [
+   "EditorAppToolset",
+   "GetVisibleActors"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "EditorToolset_EditorAppToolset_GetVisibleActors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_describe",
+    "EditorToolset_EditorAppToolset_GetVisibleActors"
+   ],
+   [
+    "tool_call",
+    "EditorToolset_EditorAppToolset_GetVisibleActors"
+   ]
+  ],
+  "error": null,
+  "final_response": "Here's what's in your level right now:\n\n1. Torch_3 (Actor) \u2014 has an NiagaraComponent called 'FX_Flame'\n2. Crate_2 (StaticMeshActor)\n\nDone."
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 20.88,
+  "api_calls": 7,
+  "prompt_tokens_total": 161728,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Unreal level outliner actors world contents list"
+   ],
+   [
+    "tool_search",
+    "Unreal get all actors level outliner contents"
+   ],
+   [
+    "tool_search",
+    "Unreal level GetAllActorsOfClass world actors list"
+   ],
+   [
+    "tool_search",
+    "Unreal scene toolset get all actors world hierarchy"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done.\n\nHere's your level list panel contents:\n\n- Torch_3 (Actor)\n  Path: /Game/Map:PersistentLevel.Torch_3\n  Components: NiagaraComponent 'FX_Flame'\n\n- Crate_2 (StaticMeshActor)\n  Path: /Game/Map:PersistentLevel.Crate_2"
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 22.27,
+  "api_calls": 7,
+  "prompt_tokens_total": 162995,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "unreal engine actor list level contents"
+   ],
+   [
+    "tool_search",
+    "get outliner hierarchy actors level panel"
+   ],
+   [
+    "tool_search",
+    "get all actors in level scene world"
+   ],
+   [
+    "tool_search",
+    "find actors filter class type"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done.\n\nLevel panel contents:\n- Torch_3 (Actor with NiagaraComponent 'FX_Flame')\n- Crate_2 (StaticMeshActor)"
+ }
+]
\ No newline at end of file
diff --git a/mcp-research-data/ue_hard_rows.json b/mcp-research-data/ue_hard_rows.json
new file mode 100644
index 00000000000..3b4c2f1086d
--- /dev/null
+++ b/mcp-research-data/ue_hard_rows.json
@@ -0,0 +1,2541 @@
+[
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 7.89,
+  "api_calls": 2,
+  "prompt_tokens_total": 109361,
+  "first_tool": [
+   "set",
+   "material"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 15.43,
+  "api_calls": 2,
+  "prompt_tokens_total": 109356,
+  "first_tool": [
+   "set",
+   "material"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 24.52,
+  "api_calls": 6,
+  "prompt_tokens_total": 177668,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots",
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material",
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "assign material to slot on static mesh asset"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "The set call returned ok:true. M_Stone is now assigned to slot 0 (Entry_0) of /Game/Meshes/SM_Rock.\n\ndone"
+ },
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 17.2,
+  "api_calls": 5,
+  "prompt_tokens_total": 147097,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots",
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "assign material to static mesh asset slot"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "Material /Game/Mats/M_Stone assigned to slot 0 (Entry_0) of /Game/Meshes/SM_Rock.\n\ndone"
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 14.37,
+  "api_calls": 3,
+  "prompt_tokens_total": 164360,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots",
+   "editor_toolset_toolsets_asset_AssetTools_exists"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_asset_AssetTools_exists"
+   ]
+  ],
+  "error": null,
+  "final_response": "I stopped before assigning because the request doesn't match the mesh.\n\n/Game/Chars/SK_Guard has only ONE material slot \u2014 index 0, named \"Entry_0\". There is no slot 1. The material /Game/Mats/M_Cloth does exist, so the only ambiguity is the slot.\n\nHow would you like to proceed?\n\n- Assign M_Cloth to "
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 8.57,
+  "api_calls": 2,
+  "prompt_tokens_total": 109378,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ]
+  ],
+  "error": null,
+  "final_response": "The mesh only has one material slot (index 0, named \"Entry_0\"). There is no slot 1 \u2014 the only valid slot on SK_Guard is slot 0.\n\nI did not make the assignment. Slot 1 doesn't exist on this mesh; the sole slot is index 0. Want me to assign M_Cloth to slot 0 instead?"
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 30.79,
+  "api_calls": 7,
+  "prompt_tokens_total": 206458,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots",
+   "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material",
+   "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "assign material to skeletal mesh slot"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_set_material"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material"
+   ]
+  ],
+  "error": null,
+  "final_response": "A note before I say done: SK_Guard has only ONE material slot (\"Entry_0\", index 0). There is no second slot, so \"slot 1\" (if you meant index 1) doesn't exist. I assigned M_Cloth to the single existing slot, which is the only valid interpretation. The set_material call returned ok:true and the slot n"
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 26.75,
+  "api_calls": 5,
+  "prompt_tokens_total": 145600,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "assign material to skeletal mesh slot"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots"
+   ]
+  ],
+  "error": null,
+  "final_response": "The clarify tool isn't available here, so I'll report the blocker directly rather than guess.\n\nI did not make the assignment. Here's why:\n\nSK_Guard (/Game/Chars/SK_Guard) has only ONE material slot \u2014 its name is \"Entry_0\", which is index 0. There is no \"slot 1\" on this mesh.\n\n\"Slot 1\" is ambiguous:\n"
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 76.05,
+  "api_calls": 15,
+  "prompt_tokens_total": 849101,
+  "first_tool": [
+   "add",
+   "row"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_set_keys",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_set_keys"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_set_keys"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ]
+  ],
+  "error": null,
+  "final_response": "Here's the honest status \u2014 the task is NOT yet complete, and I want to be clear about why.\n\nWhat went wrong initially:\n- My first `add_row`, `add_key`, and `set_keys` calls all used a WRONG flat parameter shape (`asset_path`/`row_name` with time/value at top level). Every one returned `{\"ok\": true}`"
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 42.28,
+  "api_calls": 10,
+  "prompt_tokens_total": 557289,
+  "first_tool": [
+   "asset",
+   "class"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_get_asset_class",
+   "editor_toolset_toolsets_object_ObjectTools_get_class",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys",
+   "editor_toolset_toolsets_asset_AssetTools_save_assets"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_asset_AssetTools_get_asset_class"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_object_ObjectTools_get_class"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_asset_AssetTools_save_assets"
+   ]
+  ],
+  "error": null,
+  "final_response": "Row 'Heavy' added to /Game/Data/CT_Damage with a key of value 42 at time 0, and the asset has been saved.\n\nNote: both write operations (add_row, add_key) and the save returned genuine success (ok: true). I confirmed beforehand via list_rows that this is a real CurveTable. The read-back verification "
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 59.38,
+  "api_calls": 10,
+  "prompt_tokens_total": 324649,
+  "first_tool": [
+   "asset",
+   "class"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_get_asset_class",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows",
+   "editor_toolset_toolsets_asset_AssetTools_exists"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "curve table set key row value time"
+   ],
+   [
+    "tool_search",
+    "data table add row"
+   ],
+   [
+    "tool_search",
+    "get asset class type at path"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_asset_AssetTools_get_asset_class"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_asset_AssetTools_exists"
+   ]
+  ],
+  "error": null,
+  "final_response": "The asset exists, but I cannot get a reliable read-back confirming the \"Heavy\" row with value 42 at time 0 actually landed. The write calls returned ok:true, but every verification read (list_rows, get_keys) contradicts that \u2014 \"Heavy\" never appears, and the returned data looks like fixed placeholder"
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 49.78,
+  "api_calls": 9,
+  "prompt_tokens_total": 278494,
+  "first_tool": [
+   "add",
+   "row"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "add key to curve table asset row"
+   ],
+   [
+    "tool_search",
+    "curve table add row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_row"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_add_key"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ],
+   [
+    "tool_search",
+    "curve table get row names list rows evaluate value at time"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_list_rows"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_curve_table_CurveTableTools_get_keys"
+   ]
+  ],
+  "error": null,
+  "final_response": "This confirms my concern. `list_rows` returns `[\"Brightness\"]` \u2014 the \"Heavy\" row I \"added\" is not present. The only row is a pre-existing \"Brightness\" row. Both my write calls returned `{\"ok\": true}`, but neither actually took effect:\n\n- add_row \u2192 reported ok, but list_rows shows no \"Heavy\" row (onl"
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 7.4,
+  "api_calls": 2,
+  "prompt_tokens_total": 109314,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done.\n\n`Combat.Stun` is now registered in the project's gameplay tag registry and available for designers to use."
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 7.26,
+  "api_calls": 2,
+  "prompt_tokens_total": 109329,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done.\n\nThe gameplay tag 'Combat.Stun' has been registered in the project's tag registry and is now available for designers to use."
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 36.03,
+  "api_calls": 9,
+  "prompt_tokens_total": 270380,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag",
+   "GameplayTagsToolset_GameplayTagsToolset_GetTagInfo",
+   "GameplayTagsToolset_GameplayTagsToolset_ListTags",
+   "GameplayTagsToolset_GameplayTagsToolset_ListTags"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "add gameplay tag registry"
+   ],
+   [
+    "tool_search",
+    "add register new gameplay tag to project"
+   ],
+   [
+    "tool_describe",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_GetTagInfo"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_ListTags"
+   ],
+   [
+    "tool_describe",
+    "GameplayTagsToolset_GameplayTagsToolset_ListTags"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_ListTags"
+   ]
+  ],
+  "error": null,
+  "final_response": "The verification calls (GetTagInfo and ListTags) are both returning nonsense \u2014 a `{\"name\":\"Brightness\",\"type\":\"float\",\"value\":1.0}` payload that has nothing to do with gameplay tags. That's the same stub-shaped data regardless of arguments, so the read-back path appears to be returning placeholder/m"
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 19.11,
+  "api_calls": 6,
+  "prompt_tokens_total": 175547,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag",
+   "GameplayTagsToolset_GameplayTagsToolset_GetTagInfo"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "add gameplay tag registry"
+   ],
+   [
+    "tool_search",
+    "create register new gameplay tag project"
+   ],
+   [
+    "tool_describe",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+   ],
+   [
+    "tool_call",
+    "GameplayTagsToolset_GameplayTagsToolset_GetTagInfo"
+   ]
+  ],
+  "error": null,
+  "final_response": "The `GetTagInfo` response is a bit opaque, but the `AddTag` call returned `{\"ok\": true}`, confirming the tag was registered in the project's tag registry.\n\n'Combat.Stun' is now registered and available for designers to use.\n\ndone"
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 8.09,
+  "api_calls": 2,
+  "prompt_tokens_total": 109300,
+  "first_tool": [
+   "add",
+   "tag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_actor_ActorTools_add_tag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 44.53,
+  "api_calls": 6,
+  "prompt_tokens_total": 330950,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_add_tag",
+   "editor_toolset_toolsets_actor_ActorTools_get_tags",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties",
+   "editor_toolset_toolsets_actor_ActorTools_has_tag"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_tags"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_object_ObjectTools_get_properties"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_has_tag"
+   ]
+  ],
+  "error": null,
+  "final_response": "The tool responses are clearly malfunctioning \u2014 `has_tag` requires a tag argument to check and should return a boolean, but it returned `{\"name\": \"Entry_0\", \"value\": 1.0}`, the same garbage as the other reads. The Unreal tool bridge appears to be returning canned/mismatched payloads that don't corre"
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 63.52,
+  "api_calls": 15,
+  "prompt_tokens_total": 511114,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_add_tag",
+   "editor_toolset_toolsets_actor_ActorTools_has_tag",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_tags",
+   "editor_toolset_toolsets_actor_ActorTools_get_tags"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "add tag to level actor"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ],
+   [
+    "tool_search",
+    "find actor by name label in level"
+   ],
+   [
+    "tool_search",
+    "get all actors in level list"
+   ],
+   [
+    "tool_search",
+    "get actor reference by name spawn find object"
+   ],
+   [
+    "tool_search",
+    "SceneTools get all level actors outliner"
+   ],
+   [
+    "tool_search",
+    "find_actors by name class filter"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_has_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_search",
+    "get object property value tags actor"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_tags"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_tags"
+   ]
+  ],
+  "error": null,
+  "final_response": "Now I have a clear signal that something is wrong. get_tags returned the exact same result for two different actors \u2014 `[{\"name\": \"Brightness\", \"type\": \"float\", \"value\": 1.0}]` \u2014 which isn't even a tag list (it's a float property). This backend is returning canned/garbage responses that don't reflect"
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 62.61,
+  "api_calls": 14,
+  "prompt_tokens_total": 461533,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_add_tag",
+   "editor_toolset_toolsets_actor_ActorTools_has_tag",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_has_tag",
+   "editor_toolset_toolsets_actor_ActorTools_has_tag",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_tags",
+   "editor_toolset_toolsets_actor_ActorTools_get_tags"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "add tag to level actor"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ],
+   [
+    "tool_search",
+    "find actor by name label in level"
+   ],
+   [
+    "tool_search",
+    "get all actors in level list scene actors"
+   ],
+   [
+    "tool_search",
+    "find actors by name query search actor"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_add_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_has_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_has_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_has_tag"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_search",
+    "get actor property value tags component property read"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_tags"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_tags"
+   ]
+  ],
+  "error": null,
+  "final_response": "Interesting \u2014 `get_tags` returns identical `[{\"name\":\"Brightness\",\"type\":\"float\",\"value\":1.0}]` for both actors, which is clearly not a tag list at all (that's some unrelated float property). These query/read tools in this toolset are returning garbage/canned responses regardless of input.\n\nSo here'"
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 71.82,
+  "api_calls": 14,
+  "prompt_tokens_total": 813817,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_GetVariable",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_GetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetVariable"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ]
+  ],
+  "error": null,
+  "final_response": "There's a genuine contradiction between two authoritative tools:\n\n- `find_actors` claims Torch_3 has a NiagaraComponent 'FX_Flame'\n- `get_components` on the same actor path returns only a StaticMeshComponent0, no Niagara component\n\nGiven that get_components (which reads the actor's actual component "
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 85.58,
+  "api_calls": 14,
+  "prompt_tokens_total": 813467,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_GetVariable",
+   "EditorToolset_LogsToolset_GetLogEntries",
+   "editor_toolset_toolsets_object_ObjectTools_list_properties",
+   "EditorToolset_EditorAppToolset_IsPIERunning",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetVariable"
+   ],
+   [
+    "tool_call",
+    "EditorToolset_LogsToolset_GetLogEntries"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_object_ObjectTools_list_properties"
+   ],
+   [
+    "tool_call",
+    "EditorToolset_EditorAppToolset_IsPIERunning"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ]
+  ],
+  "error": null,
+  "final_response": "I've done the diligence. Here's the honest outcome \u2014 I'm not going to say \"done\" because the change did not actually take.\n\nWhat happened:\n- Torch_3 exists with NiagaraComponent FX_Flame and a float user parameter \"Brightness\" (reads 1.0).\n- I called SetVariable to set Brightness = 5.0 twice \u2014 first"
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 71.82,
+  "api_calls": 15,
+  "prompt_tokens_total": 550895,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_GetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "set niagara particle user parameter on actor component"
+   ],
+   [
+    "tool_search",
+    "find actor by name get components"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_search",
+    "find actor in level by label name reference"
+   ],
+   [
+    "tool_search",
+    "get all actors in level list scene actors"
+   ],
+   [
+    "tool_search",
+    "find_actors by name class SceneTools"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_GetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "I was unable to complete the change, and I want to be straight with you rather than claim success the tool didn't actually deliver.\n\nWhat I found:\n- The actor Torch_3 exists at /Game/Map:PersistentLevel.Torch_3 and has a Niagara component named FX_Flame.\n- That component has a float user parameter \""
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 76.96,
+  "api_calls": 15,
+  "prompt_tokens_total": 578105,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_Component_SetVariable",
+   "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "find actor by name in level Unreal"
+   ],
+   [
+    "tool_search",
+    "set Niagara particle system user parameter float"
+   ],
+   [
+    "tool_search",
+    "actor component Niagara set user parameter on level instance component"
+   ],
+   [
+    "tool_search",
+    "set float variable on Niagara component actor in level"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_search",
+    "get actor by label find actor components list Niagara component on actor"
+   ],
+   [
+    "tool_search",
+    "get all actors in level find actors by class editor level tools"
+   ],
+   [
+    "tool_search",
+    "find actor in level by name return actor reference get level actor"
+   ],
+   [
+    "tool_search",
+    "get all level actors list actors of class spawn actor editor actor subsystem"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_actor_ActorTools_get_components"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_SetVariable"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_Component_GetUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "I have to be honest: the change did NOT stick, and I should not say \"done.\"\n\nWhat happened:\n- Found the actor Torch_3 (/Game/Map:PersistentLevel.Torch_3). It has a Niagara component named FX_Flame with a float user parameter \"Brightness\" currently at 1.0.\n- Called Component_SetVariable to set Bright"
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 9.04,
+  "api_calls": 2,
+  "prompt_tokens_total": 109368,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 50.06,
+  "api_calls": 9,
+  "prompt_tokens_total": 500337,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "editor_toolset_toolsets_asset_AssetTools_save_assets",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetSystemData",
+   "editor_toolset_toolsets_asset_AssetTools_exists",
+   "EditorToolset_EditorAppToolset_GetOpenAssets",
+   "EditorToolset_LogsToolset_GetLogEntries",
+   "EditorToolset_LogsToolset_GetLogEntries"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_asset_AssetTools_save_assets"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_GetSystemData"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_asset_AssetTools_exists"
+   ],
+   [
+    "tool_call",
+    "EditorToolset_EditorAppToolset_GetOpenAssets"
+   ],
+   [
+    "tool_call",
+    "EditorToolset_LogsToolset_GetLogEntries"
+   ],
+   [
+    "tool_call",
+    "EditorToolset_LogsToolset_GetLogEntries"
+   ]
+  ],
+  "error": null,
+  "final_response": "Confirmed \u2014 the Unreal tool bridge is returning a single canned/stale payload (`[{\"name\":\"Entry_0\",\"value\":1.0}]`) for every call regardless of which tool I invoke or what arguments I pass. GetLogEntries should never return that shape. This means the earlier `{\"ok\": true}` responses were not real co"
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 17.3,
+  "api_calls": 5,
+  "prompt_tokens_total": 152054,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Niagara add user parameter float to system asset"
+   ],
+   [
+    "tool_search",
+    "Niagara add user variable to system"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "done\n\nWindStrength (float, default 0.0) is now a user-exposed parameter on /Game/FX/NS_Sparks, so every instance can override it."
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 90.8,
+  "api_calls": 15,
+  "prompt_tokens_total": 509840,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetSystemSchema",
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables",
+   "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "Niagara add user exposed parameter to system asset"
+   ],
+   [
+    "tool_search",
+    "Niagara system add user variable create parameter"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+   ],
+   [
+    "tool_search",
+    "find niagara system asset by path load reference"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+   ],
+   [
+    "tool_describe",
+    "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_GetSystemSchema"
+   ],
+   [
+    "tool_search",
+    "save asset niagara system persist changes"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_asset_AssetTools_load_asset"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_asset_AssetTools_load_asset"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+   ],
+   [
+    "tool_call",
+    "NiagaraToolsets_NiagaraToolset_System_GetUserVariables"
+   ]
+  ],
+  "error": null,
+  "final_response": "I was not able to complete this task, and I want to be straight with you rather than claim success.\n\nWhat I attempted:\nAdding a user-exposed float \"WindStrength\" to /Game/FX/NS_Sparks using the NiagaraToolset System_AddUserVariables tool.\n\nWhat happened:\n- I confirmed the asset path resolves correct"
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 60.15,
+  "api_calls": 12,
+  "prompt_tokens_total": 673472,
+  "first_tool": [
+   "SlateInspectorToolset",
+   "Windows"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "SlateInspectorToolset_SlateInspectorToolset_Windows",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Windows",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Observe",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Screenshot",
+   "vision_analyze",
+   "terminal"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Windows"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Windows"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Windows"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ]
+  ],
+  "error": null,
+  "final_response": "The file lives on the Unreal editor host, which is a separate filesystem from my agent environment, so I can't open it to visually confirm it's the Details panel. But the Screenshot tool accepted the ref \"SDetailsView\" (the Slate class for Unreal's Details panel) and returned a valid capture path ra"
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 59.25,
+  "api_calls": 13,
+  "prompt_tokens_total": 727743,
+  "first_tool": [
+   "SlateInspectorToolset",
+   "Windows"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "SlateInspectorToolset_SlateInspectorToolset_Windows",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Observe",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_ListObservers",
+   "SlateInspectorToolset_SlateInspectorToolset_Screenshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Windows"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_ListObservers"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ]
+  ],
+  "error": null,
+  "final_response": "Snapshot consistently returns only `{\"ok\": true}` with the actual widget-tree text stripped out, across every parameter combination I've tried (empty ref, observer ref, varying depth, source locations on). Without that tree I cannot discover the Details panel's widget ref, and Screenshot needs that "
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 68.03,
+  "api_calls": 15,
+  "prompt_tokens_total": 474341,
+  "first_tool": [
+   "computer",
+   "use"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "computer_use",
+   "computer_use",
+   "computer_use",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Observe",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "capture screenshot of editor panel widget Details"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_search",
+    "Slate inspector observe widget subtree"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_search",
+    "find Slate widget by type name get ref details view"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ],
+   [
+    "tool_describe",
+    "UMGToolSet_UMGToolSet_GetWidgetDescription"
+   ]
+  ],
+  "error": null,
+  "final_response": "That tool is for UMG WidgetBlueprint assets (authored UI), not the editor's own Slate Details panel \u2014 wrong target. The Details panel is a native Slate widget (SDetailsView), reachable only through the SlateInspector toolset, whose ref-discovery (Snapshot) isn't returning tree text through this brid"
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 116.23,
+  "api_calls": 15,
+  "prompt_tokens_total": 496374,
+  "first_tool": [
+   "computer",
+   "use"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "computer_use",
+   "computer_use",
+   "computer_use",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "search_files",
+   "SlateInspectorToolset_SlateInspectorToolset_Observe",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_WaitFor",
+   "SlateInspectorToolset_SlateInspectorToolset_Screenshot",
+   "read_file"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "take screenshot of editor panel or widget"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ],
+   [
+    "tool_search",
+    "find slate widget by type Details panel list widgets"
+   ],
+   [
+    "tool_search",
+    "slate inspector dump widget tree find ref by type live editor"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_WaitFor"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Observe"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Snapshot"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_WaitFor"
+   ],
+   [
+    "tool_describe",
+    "SlateInspectorToolset_SlateInspectorToolset_Click"
+   ],
+   [
+    "tool_call",
+    "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+   ]
+  ],
+  "error": null,
+  "final_response": "Summary of where things landed:\n\nDesktop screen-capture (computer_use) is non-functional in this environment \u2014 capture returns 0x0, and there are no GUI windows exposed (only kernel processes). So the Details panel cannot be grabbed via desktop screenshot.\n\nThe correct path is the Unreal SlateInspec"
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 11.63,
+  "api_calls": 3,
+  "prompt_tokens_total": 164406,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done."
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 11.69,
+  "api_calls": 3,
+  "prompt_tokens_total": 164398,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Persisted Crate_2 (/Game/Map:PersistentLevel.Crate_2) to disk \u2014 no full save-all."
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 30.34,
+  "api_calls": 8,
+  "prompt_tokens_total": 259700,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "save actor changes to disk persist single actor"
+   ],
+   [
+    "tool_search",
+    "save level actor modified dirty package"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ],
+   [
+    "tool_search",
+    "find actor by name in level get actor reference"
+   ],
+   [
+    "tool_search",
+    "list all actors in scene level find actors by class or label"
+   ],
+   [
+    "tool_search",
+    "get actors in level selected actors"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ]
+  ],
+  "error": null,
+  "final_response": "Done. Saved Crate_2 (/Game/Map:PersistentLevel.Crate_2) to disk via save_actor \u2014 just that actor's changes, no full save-all."
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 29.43,
+  "api_calls": 9,
+  "prompt_tokens_total": 280271,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "save actor changes to disk persist single actor"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ],
+   [
+    "tool_search",
+    "find actor by name in level get actor reference"
+   ],
+   [
+    "tool_search",
+    "list all actors in scene find actors of class"
+   ],
+   [
+    "tool_search",
+    "find_actors get all actors in level by name or label"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_save_actor"
+   ]
+  ],
+  "error": null,
+  "final_response": "Persisted Crate_2 (/Game/Map:PersistentLevel.Crate_2) to disk via save_actor \u2014 not a full save-all. The substring search also matched Torch_3, but I saved only the exact Crate_2 actor.\n\nDone."
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "listing",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 9.0,
+  "api_calls": 2,
+  "prompt_tokens_total": 109419,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ]
+  ],
+  "error": null,
+  "final_response": "Here's the current contents of your level outliner panel (the actors placed in the world):\n\n1. Torch_3\n   - Path: /Game/Map:PersistentLevel.Torch_3\n   - Class: Actor\n   - Components: NiagaraComponent 'FX_Flame'\n\n2. Crate_2\n   - Path: /Game/Map:PersistentLevel.Crate_2\n   - Class: StaticMeshActor\n\nTha"
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "listing",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 8.52,
+  "api_calls": 2,
+  "prompt_tokens_total": 109417,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ]
+  ],
+  "error": null,
+  "final_response": "Here's what the level's actor panel currently contains (2 actors):\n\n1. Torch_3 \u2014 Actor (/Game/Map:PersistentLevel.Torch_3), with a NiagaraComponent 'FX_Flame'\n2. Crate_2 \u2014 StaticMeshActor (/Game/Map:PersistentLevel.Crate_2)\n\ndone"
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "bridge",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 27.23,
+  "api_calls": 7,
+  "prompt_tokens_total": 218702,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "list all actors in level outliner world"
+   ],
+   [
+    "tool_search",
+    "get all actors in current level"
+   ],
+   [
+    "tool_search",
+    "list level actors outliner spawn find all objects placed"
+   ],
+   [
+    "tool_search",
+    "find_actors scene tools query actors by class or name"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ]
+  ],
+  "error": null,
+  "final_response": "Here are the current contents of your level outliner panel:\n\nLevel: /Game/Map (PersistentLevel) \u2014 2 actors placed in the world:\n\n1. Torch_3\n   - Class: Actor\n   - Path: /Game/Map:PersistentLevel.Torch_3\n   - Components: NiagaraComponent 'FX_Flame'\n\n2. Crate_2\n   - Class: StaticMeshActor\n   - Path: /"
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "bridge",
+  "rep": 2,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 26.45,
+  "api_calls": 6,
+  "prompt_tokens_total": 184042,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [
+   [
+    "tool_search",
+    "list all actors in level outliner"
+   ],
+   [
+    "tool_search",
+    "get all actors in current level"
+   ],
+   [
+    "tool_search",
+    "list every actor outliner contents all actors world"
+   ],
+   [
+    "tool_describe",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ],
+   [
+    "tool_call",
+    "editor_toolset_toolsets_scene_SceneTools_find_actors"
+   ]
+  ],
+  "error": null,
+  "final_response": "Here are the current contents of your level outliner panel (every actor placed in the world):\n\nTotal actors: 2\n\n1. Torch_3\n   - Path: /Game/Map:PersistentLevel.Torch_3\n   - Class: Actor\n   - Components: NiagaraComponent 'FX_Flame'\n\n2. Crate_2\n   - Path: /Game/Map:PersistentLevel.Crate_2\n   - Class: "
+ },
+ {
+  "scenario_id": "V1_static_material",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 28.85,
+  "api_calls": 4,
+  "prompt_tokens_total": 1297771,
+  "first_tool": [
+   "load",
+   "asset"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_get_material_slots",
+   "editor_toolset_toolsets_static_mesh_StaticMeshTools_set_material"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "done"
+ },
+ {
+  "scenario_id": "V2_skeletal_material",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 22.17,
+  "api_calls": 3,
+  "prompt_tokens_total": 972730,
+  "first_tool": [
+   "material",
+   "slots"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "or_toolset_toolsets_skeletal_mesh_SkeletalMeshTools_get_material_slots",
+   "editor_toolset_toolsets_asset_AssetTools_exists"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "I can't complete this. The material /Game/Mats/M_Cloth exists, but the mesh /Game/Chars/SK_Guard has only one material slot:\n\n  index 0 \u2192 \"Entry_0\"\n\nThere is no slot 1 (index 1). The mesh has a single slot, so nothing was assigned \u2014 I didn't want to silently retarget slot 0 in place of the slot 1 yo"
+ },
+ {
+  "scenario_id": "V3_curvetable_row",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 27.56,
+  "api_calls": 5,
+  "prompt_tokens_total": 1621753,
+  "first_tool": [
+   "load",
+   "asset"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_asset_AssetTools_load_asset",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_row",
+   "editor_toolset_toolsets_curve_table_CurveTableTools_add_key",
+   "editor_toolset_toolsets_asset_AssetTools_save_assets"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "done"
+ },
+ {
+  "scenario_id": "V4_project_tag",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 15.29,
+  "api_calls": 2,
+  "prompt_tokens_total": 648308,
+  "first_tool": [
+   "GameplayTagsToolset",
+   "AddTag"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "GameplayTagsToolset_GameplayTagsToolset_AddTag"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "done"
+ },
+ {
+  "scenario_id": "V5_actor_tag",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 34.71,
+  "api_calls": 5,
+  "prompt_tokens_total": 1622365,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_add_tag",
+   "editor_toolset_toolsets_actor_ActorTools_get_tags",
+   "editor_toolset_toolsets_object_ObjectTools_get_properties"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "Something is wrong here, and I'm not going to report \"done\" on faith when the verification contradicts it.\n\nWhat I'm seeing:\n- `add_tag` returned `{\"ok\": true}`.\n- But both read-backs come back garbage: `get_tags` returned a `Brightness` float, and reading the `Tags` property directly returned `Entr"
+ },
+ {
+  "scenario_id": "V6_niagara_component",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 52.52,
+  "api_calls": 5,
+  "prompt_tokens_total": 1623641,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": false,
+  "wrong_calls": 0,
+  "success": false,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_actor_ActorTools_get_components",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_object_ObjectTools_list_properties"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "The signals are now clearly contradictory and none of them let me safely locate a real Niagara effect component with a Brightness parameter:\n\n1. The `NiagaraActor` type search returned the exact same two actors (Torch_3 as a plain \"Actor\", plus Crate_2) \u2014 identical to the unfiltered substring search"
+ },
+ {
+  "scenario_id": "V7_niagara_system_asset",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 16.33,
+  "api_calls": 2,
+  "prompt_tokens_total": 648451,
+  "first_tool": [
+   "System",
+   "AddUserVariables"
+  ],
+  "first_correct": true,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "NiagaraToolsets_NiagaraToolset_System_AddUserVariables"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "done"
+ },
+ {
+  "scenario_id": "V8_widget_screenshot",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 46.89,
+  "api_calls": 7,
+  "prompt_tokens_total": 2271309,
+  "first_tool": [
+   "SlateInspectorToolset",
+   "Snapshot"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Observe",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_ListObservers",
+   "SlateInspectorToolset_SlateInspectorToolset_Windows",
+   "SlateInspectorToolset_SlateInspectorToolset_WaitFor",
+   "SlateInspectorToolset_SlateInspectorToolset_Screenshot"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "The screenshot with an empty ref produced a path, but an empty ref means \"active window\" \u2014 that captures the whole editor window, not the Details panel specifically. I need a widget ref for the Details panel, and the Slate inspector's Snapshot/Windows/ListObservers calls are all returning empty payl"
+ },
+ {
+  "scenario_id": "V9_save_actor",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 21.67,
+  "api_calls": 3,
+  "prompt_tokens_total": 972894,
+  "first_tool": [
+   "find",
+   "actors"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "editor_toolset_toolsets_scene_SceneTools_find_actors",
+   "editor_toolset_toolsets_scene_SceneTools_save_actor"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "done\n\nSaved just Crate_2 (/Game/Map:PersistentLevel.Crate_2) to disk. Note: the search also returned Torch_3 as a fuzzy match, but I persisted only the exact Crate_2 actor you edited \u2014 no full save-all."
+ },
+ {
+  "scenario_id": "V10_zero_keyword",
+  "mode": "eager",
+  "rep": 1,
+  "n_tools_registered": 830,
+  "elapsed_seconds": 28.54,
+  "api_calls": 4,
+  "prompt_tokens_total": 1297260,
+  "first_tool": [
+   "SlateInspectorToolset",
+   "Snapshot"
+  ],
+  "first_correct": false,
+  "final_correct": true,
+  "wrong_calls": 0,
+  "success": true,
+  "ue_calls": [
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "SlateInspectorToolset_SlateInspectorToolset_Snapshot",
+   "editor_toolset_toolsets_scene_SceneTools_find_actors"
+  ],
+  "bridge_calls": [],
+  "error": null,
+  "final_response": "Here are the current contents of the World Outliner panel (from the live level's actors \u2014 the authoritative source, not the stale UI cache):\n\nCurrent level: /Game/Map (PersistentLevel)\n\n1. Torch_3\n   - Class: Actor\n   - Path: /Game/Map:PersistentLevel.Torch_3\n   - Components: NiagaraComponent 'FX_Fl"
+ }
+]
\ No newline at end of file
diff --git a/model_tools.py b/model_tools.py
index 602d81fde50..58c546883b1 100644
--- a/model_tools.py
+++ b/model_tools.py
@@ -569,10 +569,15 @@ def _compute_tool_definitions(
                 config=ts_cfg,
             )
             if assembly.activated and not quiet_mode:
+                _forms = {"full": "catalog listing embedded",
+                          "names": "names-only listing embedded",
+                          "mixed": "listing embedded (oversized servers summarized)",
+                          "groups": "server summary embedded (search-only discovery)",
+                          "none": "no listing (search-only)"}
                 print(
-                    f"🔎 Tool Search: {assembly.deferred_count} MCP/plugin tools deferred "
-                    f"(~{assembly.deferred_tokens} tokens) behind tool_search/describe/call. "
-                    f"Threshold ~{assembly.threshold_tokens} tokens."
+                    f"🔎 Tool Search (tier {assembly.tier}): {assembly.deferred_count} "
+                    f"MCP/plugin tools deferred (~{assembly.deferred_tokens} tokens) behind "
+                    f"tool_search/describe/call — {_forms.get(assembly.listing_form, assembly.listing_form)}."
                 )
             filtered_tools = assembly.tool_defs
     except Exception as e:  # pragma: no cover — never break tool loading
@@ -726,6 +731,16 @@ def coerce_tool_args(tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     if not properties:
         return args
 
+    # The model saw the SANITIZED schema — property keys violating provider
+    # patterns (e.g. Cloudflare's ``issue_class~neq``) were renamed before
+    # the request. Map any sanitized keys back to the registry's original
+    # wire names before schema lookup / dispatch.
+    try:
+        from tools.schema_sanitizer import unrename_tool_args
+        args = unrename_tool_args(schema.get("parameters"), args)
+    except Exception:  # pragma: no cover — never break dispatch
+        pass
+
     for key, value in list(args.items()):
         prop_schema = properties.get(key)
         if not prop_schema:
diff --git a/optional-skills/autonomous-ai-agents/blackbox/SKILL.md b/optional-skills/autonomous-ai-agents/blackbox/SKILL.md
index a3af9f722cc..3dafa6acf7b 100644
--- a/optional-skills/autonomous-ai-agents/blackbox/SKILL.md
+++ b/optional-skills/autonomous-ai-agents/blackbox/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: blackbox
-description: Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key.
-version: 1.0.0
+description: Delegate coding tasks to the Blackbox AI multi-model CLI.
+version: 1.0.1
 author: Hermes Agent (Nous Research)
 license: MIT
 platforms: [linux, macos, windows]
@@ -15,17 +15,12 @@ metadata:
 
 Delegate coding tasks to [Blackbox AI](https://www.blackbox.ai/) via the Hermes terminal. Blackbox is a multi-model coding agent CLI that dispatches tasks to multiple LLMs (Claude, Codex, Gemini, Blackbox Pro) and uses a judge to select the best implementation.
 
-The CLI is [open-source](https://github.com/blackboxaicode/cli) (GPL-3.0, TypeScript, forked from Gemini CLI) and supports interactive sessions, non-interactive one-shots, checkpointing, MCP, and vision model switching.
+The CLI (npm `@blackbox_ai/blackbox-cli`, binary `blackbox`) is a TypeScript coding agent (forked from Gemini CLI) and supports interactive sessions, non-interactive one-shots, checkpointing, MCP, and vision model switching.
 
 ## Prerequisites
 
 - Node.js 20+ installed
-- Blackbox CLI installed: `npm install -g @blackboxai/cli`
-- Or install from source:
-  ```
-  git clone https://github.com/blackboxaicode/cli.git
-  cd cli && npm install && npm install -g .
-  ```
+- Blackbox CLI installed: `npm install -g @blackbox_ai/blackbox-cli` (binary: `blackbox`)
 - API key from [app.blackbox.ai/dashboard](https://app.blackbox.ai/dashboard)
 - Configured: run `blackbox configure` and enter your API key
 - Use `pty=true` in terminal calls — Blackbox CLI is an interactive terminal app
@@ -110,12 +105,16 @@ Blackbox's unique feature is running the same task through multiple models and j
 
 | Flag | Effect |
 |------|--------|
-| `--prompt "task"` | Non-interactive one-shot execution |
+| `--prompt "task"` (`-p`) | Non-interactive one-shot execution |
 | `--resume-checkpoint "tag"` | Resume from a saved checkpoint |
-| `--yolo` | Auto-approve all actions and model switches |
-| `blackbox session` | Start interactive chat session |
+| `--yolo` (`-y`) | Auto-approve all actions and model switches |
+| `--vlm-switch-mode <mode>` | Image-handling: `once`, `session`, or `persist` |
+| `-c, --checkpointing` | Enable checkpointing of file edits |
 | `blackbox configure` | Change settings, providers, models |
-| `blackbox info` | Display system information |
+| `blackbox update` | Update the CLI to the latest version |
+| `blackbox mcp` | Manage MCP servers |
+| `blackbox extensions` | Manage CLI extensions |
+| `blackbox voice <action>` / `blackbox shortcut` | Configure voice input / the `b` shortcut |
 
 ## Vision Support
 
diff --git a/optional-skills/autonomous-ai-agents/grok/SKILL.md b/optional-skills/autonomous-ai-agents/grok/SKILL.md
index 4ba4131051c..8750e956f36 100644
--- a/optional-skills/autonomous-ai-agents/grok/SKILL.md
+++ b/optional-skills/autonomous-ai-agents/grok/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: grok
 description: "Delegate coding to xAI Grok Build CLI (features, PRs)."
-version: 0.1.0
+version: 0.1.1
 author: Matt Maximo (MattMaximo), Hermes Agent
 license: MIT
 platforms: [linux, macos, windows]
@@ -108,14 +108,16 @@ For pure automation, headless `-p` is still cleaner than the TUI.
 |------|--------|
 | `-p, --single <PROMPT>` | Send one prompt, run headless, exit |
 | `-m, --model <MODEL>` | Choose a model |
-| `-s, --session-id <ID>` | Create or resume a named headless session |
-| `-r, --resume <ID>` | Resume an existing session |
+| `-s, --session-id <UUID>` | Assign a **NEW** valid UUID to a fresh conversation (must not already exist). Does **not** resume — use `--resume`/`--continue` for that. Only valid with `--resume`/`--continue` when paired with `--fork-session` |
+| `-r, --resume [<UUID>]` | Resume an existing session by its UUID (or the most recent if omitted) |
 | `-c, --continue` | Continue the most recent session in the current directory |
+| `--fork-session` | When resuming, create a new session ID instead of reusing the original |
+| `--max-turns <N>` | Cap the maximum number of agent turns |
 | `--cwd <PATH>` | Set the working directory |
 | `--output-format <FMT>` | `plain` (default), `json`, or `streaming-json` |
 | `--always-approve` | Auto-approve all tool executions (the `--full-auto` / `--yolo` equivalent) |
 | `--no-alt-screen` | Run inline, no fullscreen TUI takeover |
-| `--no-auto-update` | Skip background update checks (use in all automation) |
+| `--no-auto-update` | Skip background update checks (use in all automation; hidden from `--help` but still works) |
 
 ### Output Formats
 
@@ -151,14 +153,19 @@ with `tmux capture-pane`, exactly like the `claude-code` / `codex` skills.
 
 ### Session Continuation
 
+Sessions are keyed by **UUID**, not by name. `--session-id` assigns a *new* UUID
+to a fresh run (it does **not** resume); `--resume` takes an existing session's
+UUID (or omit the value to resume the most recent).
+
 ```
-# Start a named session
-terminal(command="grok --no-auto-update -s refactor-db -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)
+# Start a session with a self-assigned UUID (must be a valid, unused UUID)
+SID=$(uuidgen)
+terminal(command="grok --no-auto-update -s $SID -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)
 
-# Resume it later
-terminal(command="grok --no-auto-update -r refactor-db -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)
+# Resume that exact session later by its UUID
+terminal(command="grok --no-auto-update -r $SID -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)
 
-# Or continue the most recent session in this directory
+# Or just continue the most recent session in this directory (no UUID needed)
 terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60)
 ```
 
diff --git a/optional-skills/autonomous-ai-agents/honcho/SKILL.md b/optional-skills/autonomous-ai-agents/honcho/SKILL.md
index b4a24a46e25..61f8001b249 100644
--- a/optional-skills/autonomous-ai-agents/honcho/SKILL.md
+++ b/optional-skills/autonomous-ai-agents/honcho/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: honcho
-description: Configure and use Honcho memory with Hermes -- cross-session user modeling, multi-profile peer isolation, observation config, dialectic reasoning, session summaries, and context budget enforcement. Use when setting up Honcho, troubleshooting memory, managing profiles with Honcho peers, or tuning observation, recall, and dialectic settings.
+description: Configure and troubleshoot Honcho memory for Hermes.
 version: 2.0.0
 author: Hermes Agent
 license: MIT
diff --git a/optional-skills/blockchain/solana/SKILL.md b/optional-skills/blockchain/solana/SKILL.md
index e7d62536a8c..9da954f7de4 100644
--- a/optional-skills/blockchain/solana/SKILL.md
+++ b/optional-skills/blockchain/solana/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: solana
-description: Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network stats. Uses Solana RPC + CoinGecko. No API key required.
+description: Query Solana wallets, tokens, txs, and NFTs in USD.
 version: 0.2.0
 author: Deniz Alagoz (gizdusum), enhanced by Hermes Agent
 license: MIT
diff --git a/skills/mlops/models/audiocraft/SKILL.md b/optional-skills/creative/audiocraft-audio-generation/SKILL.md
similarity index 99%
rename from skills/mlops/models/audiocraft/SKILL.md
rename to optional-skills/creative/audiocraft-audio-generation/SKILL.md
index 824147fe411..12b46455811 100644
--- a/skills/mlops/models/audiocraft/SKILL.md
+++ b/optional-skills/creative/audiocraft-audio-generation/SKILL.md
@@ -9,6 +9,7 @@ platforms: [linux, macos]
 metadata:
   hermes:
     tags: [Multimodal, Audio Generation, Text-to-Music, Text-to-Audio, MusicGen]
+    related_skills: [heartmula, songwriting-and-ai-music]
 
 ---
 
diff --git a/skills/mlops/models/audiocraft/references/advanced-usage.md b/optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md
similarity index 100%
rename from skills/mlops/models/audiocraft/references/advanced-usage.md
rename to optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md
diff --git a/skills/mlops/models/audiocraft/references/troubleshooting.md b/optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md
similarity index 100%
rename from skills/mlops/models/audiocraft/references/troubleshooting.md
rename to optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md
diff --git a/optional-skills/creative/concept-diagrams/SKILL.md b/optional-skills/creative/concept-diagrams/SKILL.md
index 6017d4fd121..75ff2efe78f 100644
--- a/optional-skills/creative/concept-diagrams/SKILL.md
+++ b/optional-skills/creative/concept-diagrams/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: concept-diagrams
-description: Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and non-software visuals — physics setups, chemistry mechanisms, math curves, physical objects (aircraft, turbines, smartphones, mechanical watches), anatomy, floor plans, cross-sections, narrative journeys (lifecycle of X, process of Y), hub-spoke system integrations (smart city, IoT), and exploded layer views. If a more specialized skill exists for the subject (dedicated software/cloud architecture, hand-drawn sketches, animated explainers, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback with a clean educational look. Ships with 15 example diagrams.
+description: Generate flat, minimal educational SVG visuals as HTML.
 version: 0.1.0
 author: v1k22 (original PR), ported into hermes-agent
 license: MIT
@@ -9,7 +9,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [diagrams, svg, visualization, education, physics, chemistry, engineering]
-    related_skills: [architecture-diagram, excalidraw, generative-widgets]
+    related_skills: [architecture-diagram, excalidraw]
 ---
 
 # Concept Diagrams
diff --git a/skills/media/heartmula/SKILL.md b/optional-skills/creative/heartmula/SKILL.md
similarity index 98%
rename from skills/media/heartmula/SKILL.md
rename to optional-skills/creative/heartmula/SKILL.md
index e6adc4b0965..df534b4347d 100644
--- a/skills/media/heartmula/SKILL.md
+++ b/optional-skills/creative/heartmula/SKILL.md
@@ -6,7 +6,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [music, audio, generation, ai, heartmula, heartcodec, lyrics, songs]
-    related_skills: [audiocraft]
+    related_skills: [audiocraft-audio-generation, songwriting-and-ai-music]
 ---
 
 # HeartMuLa - Open-Source Music Generation
diff --git a/optional-skills/creative/hyperframes/SKILL.md b/optional-skills/creative/hyperframes/SKILL.md
index 0f6fd9bf51b..16a5c8d1bac 100644
--- a/optional-skills/creative/hyperframes/SKILL.md
+++ b/optional-skills/creative/hyperframes/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: hyperframes
-description: Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions using HyperFrames. HTML is the source of truth for video. Use when the user wants a rendered MP4/WebM from an HTML composition, wants to animate text/logos/charts over media, needs captions synced to audio, wants TTS narration, or wants to convert a website into a video.
+description: Render MP4/WebM videos from HTML compositions.
 version: 1.0.0
 author: heygen-com
 license: Apache-2.0
diff --git a/optional-skills/creative/kanban-video-orchestrator/SKILL.md b/optional-skills/creative/kanban-video-orchestrator/SKILL.md
index 6ce9dd29322..d365ad62cb8 100644
--- a/optional-skills/creative/kanban-video-orchestrator/SKILL.md
+++ b/optional-skills/creative/kanban-video-orchestrator/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: kanban-video-orchestrator
-description: Plan, set up, and monitor a multi-agent video production pipeline backed by Hermes Kanban. Use when the user wants to make ANY video — narrative film, product/marketing, music video, explainer, ASCII/terminal art, abstract/generative loop, comic, 3D, real-time/installation — and the work warrants decomposition into specialized profiles (writer, designer, animator, renderer, voice, editor, etc.) coordinated through a kanban board. Performs adaptive discovery to scope the brief, designs an appropriate team for the requested style, generates the setup script that creates Hermes profiles + initial kanban task, then helps monitor execution and intervene when tasks stall or fail. Routes scenes to whichever Hermes rendering / audio / design skill fits each beat (`ascii-video`, `manim-video`, `p5js`, `comfyui`, `touchdesigner-mcp`, `blender-mcp`, `pixel-art`, `baoyu-comic`, `claude-design`, `excalidraw`, `songsee`, `heartmula`, …) plus external APIs for TTS, image-gen, and image-to-video as needed.
+description: Plan and run multi-agent video production pipelines.
 version: 1.0.0
 author: [SHL0MS, alt-glitch]
 license: MIT
@@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [video, kanban, multi-agent, orchestration, production-pipeline]
-    related_skills: [ascii-video, manim-video, p5js, comfyui, touchdesigner-mcp, blender-mcp, pixel-art, ascii-art, songwriting-and-ai-music, heartmula, songsee, spotify, youtube-content, claude-design, excalidraw, architecture-diagram, concept-diagrams, baoyu-comic, baoyu-infographic, humanizer, gif-search, meme-generation]
+    related_skills: [ascii-video, manim-video, p5js, comfyui, touchdesigner-mcp, blender-mcp, pixel-art, ascii-art, songwriting-and-ai-music, heartmula, songsee, youtube-content, claude-design, excalidraw, architecture-diagram, concept-diagrams, baoyu-comic, baoyu-infographic, humanizer, gif-search, meme-generation]
     credits: |
       The single-project workspace layout, profile-config patching pattern,
       SOUL.md-per-profile model, TEAM.md task-graph convention, and
diff --git a/optional-skills/creative/kanban-video-orchestrator/scripts/bootstrap_pipeline.py b/optional-skills/creative/kanban-video-orchestrator/scripts/bootstrap_pipeline.py
index 7ea146adc13..6fe764f7e6b 100755
--- a/optional-skills/creative/kanban-video-orchestrator/scripts/bootstrap_pipeline.py
+++ b/optional-skills/creative/kanban-video-orchestrator/scripts/bootstrap_pipeline.py
@@ -68,7 +68,7 @@ ASSETS_DIR = Path(__file__).resolve().parent.parent / "assets"
 
 
 def load_template(name: str) -> str:
-    return (ASSETS_DIR / name).read_text()
+    return (ASSETS_DIR / name).read_text(encoding="utf-8")
 
 
 PROFILE_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
@@ -471,7 +471,7 @@ def main():
                     help="Write TEAM.md alongside (default: skipped)")
     args = ap.parse_args()
 
-    plan = json.loads(Path(args.plan_json).read_text())
+    plan = json.loads(Path(args.plan_json).read_text(encoding="utf-8"))
     errors = validate_plan(plan)
     if errors:
         print("Plan validation failed:", file=sys.stderr)
@@ -483,15 +483,15 @@ def main():
     team = render_team_md(plan)
     setup = render_setup_sh(plan, brief, team)
 
-    Path(args.out).write_text(setup)
+    Path(args.out).write_text(setup, encoding="utf-8")
     os.chmod(args.out, 0o755)
     print(f"Wrote {args.out}")
 
     if args.brief_out:
-        Path(args.brief_out).write_text(brief)
+        Path(args.brief_out).write_text(brief, encoding="utf-8")
         print(f"Wrote {args.brief_out}")
     if args.team_out:
-        Path(args.team_out).write_text(team)
+        Path(args.team_out).write_text(team, encoding="utf-8")
         print(f"Wrote {args.team_out}")
 
 
diff --git a/optional-skills/creative/kanban-video-orchestrator/scripts/monitor.py b/optional-skills/creative/kanban-video-orchestrator/scripts/monitor.py
index fb6fddc5bfe..dc3c11845b7 100755
--- a/optional-skills/creative/kanban-video-orchestrator/scripts/monitor.py
+++ b/optional-skills/creative/kanban-video-orchestrator/scripts/monitor.py
@@ -36,7 +36,7 @@ def kanban_list(tenant: str) -> list[dict]:
     try:
         out = subprocess.run(
             ["hermes", "kanban", "list", "--tenant", tenant, "--json"],
-            capture_output=True, text=True, check=False,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', check=False,
         )
         if out.returncode == 0 and out.stdout.strip().startswith("["):
             return json.loads(out.stdout)
@@ -45,7 +45,7 @@ def kanban_list(tenant: str) -> list[dict]:
     # Fallback: textual parse of `hermes kanban list`
     out = subprocess.run(
         ["hermes", "kanban", "list", "--tenant", tenant],
-        capture_output=True, text=True, check=False,
+        capture_output=True, text=True, encoding='utf-8', errors='replace', check=False,
     )
     rows = []
     for line in out.stdout.splitlines():
@@ -69,7 +69,7 @@ def kanban_list(tenant: str) -> list[dict]:
 def kanban_show(task_id: str) -> dict | None:
     out = subprocess.run(
         ["hermes", "kanban", "show", task_id, "--json"],
-        capture_output=True, text=True, check=False,
+        capture_output=True, text=True, encoding='utf-8', errors='replace', check=False,
     )
     if out.returncode != 0:
         return None
diff --git a/optional-skills/creative/meme-generation/SKILL.md b/optional-skills/creative/meme-generation/SKILL.md
index da17b6de236..f3902bda350 100644
--- a/optional-skills/creative/meme-generation/SKILL.md
+++ b/optional-skills/creative/meme-generation/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: meme-generation
-description: Generate real meme images by picking a template and overlaying text with Pillow. Produces actual .png meme files.
+description: Create meme PNGs from templates with Pillow text overlay.
 version: 2.0.0
 author: adanaleycio
 license: MIT
@@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [creative, memes, humor, images]
-    related_skills: [ascii-art, generative-widgets]
+    related_skills: [ascii-art]
     category: creative
 ---
 
diff --git a/optional-skills/creative/unreal-mcp/SKILL.md b/optional-skills/creative/unreal-mcp/SKILL.md
index 1bbbc50ee22..aa5e2e9e822 100644
--- a/optional-skills/creative/unreal-mcp/SKILL.md
+++ b/optional-skills/creative/unreal-mcp/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: unreal-mcp
-description: "Use when the user wants to do anything in Unreal Engine through Epic's official editor-embedded MCP server (catalog entry: unreal-engine) — build/light/populate scenes, place and transform actors, author Blueprints, animate with Sequencer, create material instances, frame cameras, take screenshots, render, import assets, run PIE test sessions and automation tests, or automate the editor end-to-end from plain-English prompts with no Unreal knowledge required. Covers the tool-search discovery walk (list_toolsets/describe_toolset/call_tool), serial game-thread call discipline, ProgrammaticToolset batching, the Blueprint graph DSL loop, scene-craft numbers (physical light units, exposure, scale conventions), complete build recipes, save/undo hygiene, and extending the tool surface with custom Python toolsets."
+description: Automate Unreal Engine editor scenes, actors, and renders.
 version: 1.0.0
 requires: Unreal Editor 5.8+ with the Unreal MCP plugin enabled and its server running
 author: Hermes Agent
diff --git a/skills/data-science/DESCRIPTION.md b/optional-skills/data-science/DESCRIPTION.md
similarity index 100%
rename from skills/data-science/DESCRIPTION.md
rename to optional-skills/data-science/DESCRIPTION.md
diff --git a/skills/data-science/jupyter-live-kernel/SKILL.md b/optional-skills/data-science/jupyter-notebook/SKILL.md
similarity index 87%
rename from skills/data-science/jupyter-live-kernel/SKILL.md
rename to optional-skills/data-science/jupyter-notebook/SKILL.md
index 53b0574c770..17d10c1232b 100644
--- a/skills/data-science/jupyter-live-kernel/SKILL.md
+++ b/optional-skills/data-science/jupyter-notebook/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: jupyter-live-kernel
+name: jupyter-notebook
 description: "Iterative Python via live Jupyter kernel (hamelnb)."
 version: 1.0.0
 author: Hermes Agent
@@ -11,7 +11,7 @@ metadata:
     category: data-science
 ---
 
-# Jupyter Live Kernel (hamelnb)
+# Jupyter Notebook (hamelnb live kernel)
 
 Gives you a **stateful Python REPL** via a live Jupyter kernel. Variables persist
 across executions. Use this instead of `execute_code` when you need to build up
@@ -160,6 +160,17 @@ uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compac
 8. **Occasional websocket timeouts** — some operations may timeout on first try,
    especially after a kernel restart. Retry once before escalating.
 
+9. **If websocket consistently times out on this host**, force zmq transport:
+   `uv run "$SCRIPT" execute --transport zmq ...`. Symptom: every execute returns
+   "Websocket execution may already have reached the kernel, so auto fallback was
+   skipped". The kernel actually ran fine (REST shows execution_state=idle and
+   execution_count increments) — only the websocket reply channel is broken.
+   zmq transport uses jupyter_client directly and sidesteps the issue.
+
+10. **When starting a fresh server for REST-only use**, add
+    `--ServerApp.disable_check_xsrf=True` — otherwise POST /api/sessions returns
+    `"'_xsrf' argument missing from POST"` and kernel session creation fails.
+
 ## Timeout Defaults
 
 The script has a 30-second default timeout per execution. For long-running
diff --git a/optional-skills/devops/cli/SKILL.md b/optional-skills/devops/cli/SKILL.md
index 62c85db88ab..b4fd25f6f80 100644
--- a/optional-skills/devops/cli/SKILL.md
+++ b/optional-skills/devops/cli/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: inference-sh-cli
-description: "Run 150+ AI apps via inference.sh CLI (infsh) — image generation, video creation, LLMs, search, 3D, social automation. Uses the terminal tool. Triggers: inference.sh, infsh, ai apps, flux, veo, image generation, video generation, seedream, seedance, tavily"
+description: Run 150+ AI apps (image, video, LLM) via inference.sh CLI.
 version: 1.0.0
 author: okaris
 license: MIT
diff --git a/optional-skills/devops/docker-management/SKILL.md b/optional-skills/devops/docker-management/SKILL.md
index a6fdebdce69..c0189b1ea89 100755
--- a/optional-skills/devops/docker-management/SKILL.md
+++ b/optional-skills/devops/docker-management/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: docker-management
-description: Manage Docker containers, images, volumes, networks, and Compose stacks — lifecycle ops, debugging, cleanup, and Dockerfile optimization.
+description: Manage Docker containers, images, volumes, and Compose.
 version: 1.0.0
 author: sprmn24
 license: MIT
diff --git a/optional-skills/devops/hermes-s6-container-supervision/SKILL.md b/optional-skills/devops/hermes-s6-container-supervision/SKILL.md
index 16e8a7b29e0..93726c62c59 100644
--- a/optional-skills/devops/hermes-s6-container-supervision/SKILL.md
+++ b/optional-skills/devops/hermes-s6-container-supervision/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: hermes-s6-container-supervision
-description: Modify, debug, or extend the s6-overlay supervision tree inside the Hermes Agent Docker image — adding new services, debugging profile gateways, understanding the Architecture B main-program pattern.
+description: Modify or debug s6 services in the Hermes Docker image.
 version: 1.0.0
 author: Hermes Agent
 license: MIT
@@ -9,7 +9,7 @@ environments: [s6]
 metadata:
   hermes:
     tags: [docker, s6, supervision, gateway, profiles]
-    related_skills: [hermes-agent, hermes-agent-dev]
+    related_skills: [hermes-agent]
 ---
 
 # Hermes s6-overlay Container Supervision
diff --git a/optional-skills/devops/pinggy-tunnel/SKILL.md b/optional-skills/devops/pinggy-tunnel/SKILL.md
index fa9f1d5b67b..d3f827a5a18 100644
--- a/optional-skills/devops/pinggy-tunnel/SKILL.md
+++ b/optional-skills/devops/pinggy-tunnel/SKILL.md
@@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [Pinggy, Tunnel, Networking, SSH, Webhook, Localhost]
-    related_skills: [cloudflared-quick-tunnel, webhook-subscriptions]
+    related_skills: []
 ---
 
 # Pinggy Tunnel Skill
diff --git a/optional-skills/dogfood/adversarial-ux-test/SKILL.md b/optional-skills/dogfood/adversarial-ux-test/SKILL.md
index abb9e69b3a7..2c5ba20c513 100644
--- a/optional-skills/dogfood/adversarial-ux-test/SKILL.md
+++ b/optional-skills/dogfood/adversarial-ux-test/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: adversarial-ux-test
-description: Roleplay the most difficult, tech-resistant user for your product. Browse the app as that persona, find every UX pain point, then filter complaints through a pragmatism layer to separate real problems from noise. Creates actionable tickets from genuine issues only.
+description: Roleplay a hostile user to find and triage UX pain points.
 version: 1.0.0
 author: Omni @ Comelse
 license: MIT
diff --git a/optional-skills/email/agentmail/SKILL.md b/optional-skills/email/agentmail/SKILL.md
index 5ddc7fd8757..54baaf3882b 100644
--- a/optional-skills/email/agentmail/SKILL.md
+++ b/optional-skills/email/agentmail/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: agentmail
-description: Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to).
+description: "Give the agent its own inbox: send and receive email."
 version: 1.0.0
 platforms: [linux, macos, windows]
 metadata:
diff --git a/optional-skills/finance/3-statement-model/SKILL.md b/optional-skills/finance/3-statement-model/SKILL.md
index 4ee55619dc9..525049b47fc 100644
--- a/optional-skills/finance/3-statement-model/SKILL.md
+++ b/optional-skills/finance/3-statement-model/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: 3-statement-model
-description: Build fully-integrated 3-statement models (IS, BS, CF) in Excel with working capital schedules, D&A roll-forwards, debt schedule, and the plugs that make cash and retained earnings tie. Pairs with excel-author.
+description: Build integrated IS/BS/CF financial workbooks in Excel.
 version: 1.0.0
 author: Anthropic (adapted by Nous Research)
 license: Apache-2.0
diff --git a/optional-skills/finance/comps-analysis/SKILL.md b/optional-skills/finance/comps-analysis/SKILL.md
index 2d4c34b7535..66934034ab7 100644
--- a/optional-skills/finance/comps-analysis/SKILL.md
+++ b/optional-skills/finance/comps-analysis/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: comps-analysis
-description: Build comparable company analysis in Excel — operating metrics, valuation multiples, statistical benchmarking vs peer sets. Pairs with excel-author. Use for public-company valuation, IPO pricing, sector benchmarking, or outlier detection.
+description: Build comparable-company valuation workbooks in Excel.
 version: 1.0.0
 author: Anthropic (adapted by Nous Research)
 license: Apache-2.0
diff --git a/optional-skills/finance/dcf-model/SKILL.md b/optional-skills/finance/dcf-model/SKILL.md
index a171fb7e4dd..106b2dd1a73 100644
--- a/optional-skills/finance/dcf-model/SKILL.md
+++ b/optional-skills/finance/dcf-model/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: dcf-model
-description: Build institutional-quality DCF valuation models in Excel — revenue projections, FCF build, WACC, terminal value, Bear/Base/Bull scenarios, 5x5 sensitivity tables. Pairs with excel-author. Use for intrinsic-value equity analysis.
+description: Build discounted cash flow valuation workbooks in Excel.
 version: 1.0.0
 author: Anthropic (adapted by Nous Research)
 license: Apache-2.0
diff --git a/optional-skills/finance/excel-author/SKILL.md b/optional-skills/finance/excel-author/SKILL.md
index d74bf42c234..6ed57b0f9ce 100644
--- a/optional-skills/finance/excel-author/SKILL.md
+++ b/optional-skills/finance/excel-author/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: excel-author
-description: Build auditable Excel workbooks headless with openpyxl — blue/black/green cell conventions, formulas over hardcodes, named ranges, balance checks, sensitivity tables. Use for financial models, audit outputs, reconciliations.
+description: Build auditable financial workbooks headless via openpyxl.
 version: 1.0.0
 author: Anthropic (adapted by Nous Research)
 license: Apache-2.0
diff --git a/optional-skills/finance/lbo-model/SKILL.md b/optional-skills/finance/lbo-model/SKILL.md
index 64eaf896fa6..a6b816c2e8f 100644
--- a/optional-skills/finance/lbo-model/SKILL.md
+++ b/optional-skills/finance/lbo-model/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: lbo-model
-description: Build leveraged buyout models in Excel — sources & uses, debt schedule, cash sweep, exit multiple, IRR/MOIC sensitivity. Pairs with excel-author. Use for PE screening, sponsor-case valuation, or illustrative LBO in a pitch.
+description: Build leveraged buyout workbooks with IRR/MOIC in Excel.
 version: 1.0.0
 author: Anthropic (adapted by Nous Research)
 license: Apache-2.0
diff --git a/optional-skills/finance/merger-model/SKILL.md b/optional-skills/finance/merger-model/SKILL.md
index e98b4b577ba..3055c55dd59 100644
--- a/optional-skills/finance/merger-model/SKILL.md
+++ b/optional-skills/finance/merger-model/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: merger-model
-description: Build accretion/dilution (merger) models in Excel — pro-forma P&L, synergies, financing mix, EPS impact. Pairs with excel-author. Use for M&A pitches, board materials, or deal evaluation.
+description: Build M&A accretion/dilution workbooks in Excel.
 version: 1.0.0
 author: Anthropic (adapted by Nous Research)
 license: Apache-2.0
diff --git a/optional-skills/finance/pptx-author/SKILL.md b/optional-skills/finance/pptx-author/SKILL.md
index a0c490904ba..8fca36dd40f 100644
--- a/optional-skills/finance/pptx-author/SKILL.md
+++ b/optional-skills/finance/pptx-author/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pptx-author
-description: Build PowerPoint decks headless with python-pptx. Pairs with excel-author for model-backed decks where every number traces to a workbook cell. Use for pitch decks, IC memos, earnings notes.
+description: Build PowerPoint decks headless with python-pptx.
 version: 1.0.0
 author: Anthropic (adapted by Nous Research)
 license: Apache-2.0
diff --git a/optional-skills/mcp/fastmcp/SKILL.md b/optional-skills/mcp/fastmcp/SKILL.md
index f9b1091bbe3..3d54e8d9970 100644
--- a/optional-skills/mcp/fastmcp/SKILL.md
+++ b/optional-skills/mcp/fastmcp/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: fastmcp
-description: Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Use when creating a new MCP server, wrapping an API or database as MCP tools, exposing resources or prompts, or preparing a FastMCP server for Claude Code, Cursor, or HTTP deployment.
+description: Build, test, and deploy Python MCP servers.
 version: 1.0.0
 author: Hermes Agent
 license: MIT
@@ -9,7 +9,7 @@ metadata:
   hermes:
     tags: [MCP, FastMCP, Python, Tools, Resources, Prompts, Deployment]
     homepage: https://gofastmcp.com
-    related_skills: [native-mcp, mcporter]
+    related_skills: [hermes-agent, mcporter]
 prerequisites:
   commands: [python3]
 ---
diff --git a/optional-skills/mcp/mcp-oauth-remote-gateway/SKILL.md b/optional-skills/mcp/mcp-oauth-remote-gateway/SKILL.md
index a2e43865ed5..67d245756c6 100644
--- a/optional-skills/mcp/mcp-oauth-remote-gateway/SKILL.md
+++ b/optional-skills/mcp/mcp-oauth-remote-gateway/SKILL.md
@@ -8,7 +8,7 @@ platforms: [linux, macos]
 metadata:
   hermes:
     tags: [MCP, OAuth, PKCE, Remote-Deployment]
-    related_skills: [native-mcp, mcporter, fastmcp]
+    related_skills: [hermes-agent, mcporter, fastmcp]
 ---
 
 # MCP OAuth on a Remote Hermes Gateway
diff --git a/optional-skills/mcp/mcporter/SKILL.md b/optional-skills/mcp/mcporter/SKILL.md
index fec8b77d1eb..b5b1c3cc2a8 100644
--- a/optional-skills/mcp/mcporter/SKILL.md
+++ b/optional-skills/mcp/mcporter/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: mcporter
-description: Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
+description: List, auth, and call MCP servers/tools from the terminal.
 version: 1.0.0
 author: community
 license: MIT
diff --git a/optional-skills/migration/openclaw-migration/SKILL.md b/optional-skills/migration/openclaw-migration/SKILL.md
index 3bceba8727d..4a04fb46cae 100644
--- a/optional-skills/migration/openclaw-migration/SKILL.md
+++ b/optional-skills/migration/openclaw-migration/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: openclaw-migration
-description: Migrate a user's OpenClaw customization footprint into Hermes Agent. Imports Hermes-compatible memories, SOUL.md, command allowlists, user skills, and selected workspace assets from ~/.openclaw, then reports exactly what could not be migrated and why.
+description: Import an OpenClaw setup (memories, skills) into Hermes.
 version: 1.0.0
 author: Hermes Agent (Nous Research)
 license: MIT
diff --git a/optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py b/optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py
index c108a99ea5a..7f6e9b3fb52 100644
--- a/optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py
+++ b/optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py
@@ -312,7 +312,7 @@ def sha256_file(path: Path) -> str:
 
 
 def read_text(path: Path) -> str:
-    return path.read_text(encoding="utf-8")
+    return path.read_text(encoding="utf-8", errors="replace")
 
 
 def normalize_text(text: str) -> str:
@@ -349,7 +349,12 @@ def resolve_secret_input(value: Any, env: Optional[Dict[str, str]] = None) -> Op
 def load_yaml_file(path: Path) -> Dict[str, Any]:
     if yaml is None or not path.exists():
         return {}
-    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    try:
+        # errors="replace" means read_text() cannot raise UnicodeDecodeError;
+        # OSError covers races like the file disappearing or being unreadable.
+        data = yaml.safe_load(path.read_text(encoding="utf-8", errors="replace"))
+    except (yaml.YAMLError, OSError):
+        return {}
     return data if isinstance(data, dict) else {}
 
 
@@ -367,7 +372,13 @@ def parse_env_file(path: Path) -> Dict[str, str]:
     if not path.exists():
         return {}
     data: Dict[str, str] = {}
-    for raw_line in path.read_text(encoding="utf-8").splitlines():
+    try:
+        # errors="replace" means read_text() cannot raise UnicodeDecodeError;
+        # OSError covers races like the file disappearing or being unreadable.
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return {}
+    for raw_line in lines:
         line = raw_line.strip()
         if not line or line.startswith("#") or "=" not in line:
             continue
@@ -1208,10 +1219,13 @@ class Migrator:
             return
 
         try:
-            data = json.loads(source.read_text(encoding="utf-8"))
+            data = json.loads(source.read_text(encoding="utf-8", errors="replace"))
         except json.JSONDecodeError as exc:
             self.record("command-allowlist", source, destination, "error", f"Invalid JSON: {exc}")
             return
+        except OSError as exc:
+            self.record("command-allowlist", source, destination, "error", f"Could not read file: {exc}")
+            return
 
         patterns: List[str] = []
         agents = data.get("agents", {})
@@ -1262,9 +1276,11 @@ class Migrator:
             config_path = self.source_root / name
             if config_path.exists():
                 try:
-                    data = json.loads(config_path.read_text(encoding="utf-8"))
+                    # errors="replace" means read_text() cannot raise
+                    # UnicodeDecodeError; OSError covers unreadable/vanished files.
+                    data = json.loads(config_path.read_text(encoding="utf-8", errors="replace"))
                     return data if isinstance(data, dict) else {}
-                except json.JSONDecodeError:
+                except (json.JSONDecodeError, OSError):
                     continue
         return {}
 
@@ -1343,9 +1359,11 @@ class Migrator:
         allowlist_path = self.source_root / "credentials" / "telegram-default-allowFrom.json"
         if allowlist_path.exists():
             try:
-                allow_data = json.loads(allowlist_path.read_text(encoding="utf-8"))
+                allow_data = json.loads(allowlist_path.read_text(encoding="utf-8", errors="replace"))
             except json.JSONDecodeError:
                 self.record("messaging-settings", allowlist_path, self.target_root / ".env", "error", "Invalid JSON in Telegram allowlist file")
+            except OSError as exc:
+                self.record("messaging-settings", allowlist_path, self.target_root / ".env", "error", f"Could not read Telegram allowlist file: {exc}")
             else:
                 allow_from = allow_data.get("allowFrom", [])
                 if isinstance(allow_from, list):
@@ -1617,7 +1635,7 @@ class Migrator:
         auth_profiles_path = self.source_root / "agents" / "main" / "agent" / "auth-profiles.json"
         if auth_profiles_path.exists():
             try:
-                profiles = json.loads(auth_profiles_path.read_text(encoding="utf-8"))
+                profiles = json.loads(auth_profiles_path.read_text(encoding="utf-8", errors="replace"))
                 if isinstance(profiles, dict):
                     # auth-profiles.json wraps profiles in a "profiles" key
                     profile_entries = profiles.get("profiles", profiles) if isinstance(profiles.get("profiles"), dict) else profiles
@@ -1901,7 +1919,12 @@ class Migrator:
 
         all_incoming: List[str] = []
         for md_file in md_files:
-            entries = extract_markdown_entries(read_text(md_file))
+            try:
+                # read_text() uses errors="replace" so it cannot raise
+                # UnicodeDecodeError; OSError covers unreadable/vanished files.
+                entries = extract_markdown_entries(read_text(md_file))
+            except OSError:
+                continue
             all_incoming.extend(entries)
 
         if not all_incoming:
diff --git a/optional-skills/mlops/accelerate/SKILL.md b/optional-skills/mlops/accelerate/SKILL.md
index 0c2e69a1d42..e26f5503db4 100644
--- a/optional-skills/mlops/accelerate/SKILL.md
+++ b/optional-skills/mlops/accelerate/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: huggingface-accelerate
-description: Simplest distributed training API. 4 lines to add distributed support to any PyTorch script. Unified API for DeepSpeed/FSDP/Megatron/DDP. Automatic device placement, mixed precision (FP16/BF16/FP8). Interactive config, single launch command. HuggingFace ecosystem standard.
-version: 1.0.0
+description: Run PyTorch training across GPUs with minimal changes.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [accelerate, torch, transformers]
@@ -146,30 +146,35 @@ for batch in dataloader:
 
 ### Workflow 3: DeepSpeed ZeRO integration
 
-**Enable DeepSpeed ZeRO-2**:
+**Enable DeepSpeed ZeRO-2** (pass a `DeepSpeedPlugin`, not a raw dict):
 ```python
-from accelerate import Accelerator
+from accelerate import Accelerator, DeepSpeedPlugin
+
+deepspeed_plugin = DeepSpeedPlugin(
+    zero_stage=2,                     # ZeRO-2
+    offload_optimizer_device="none",  # or "cpu" to offload
+    gradient_accumulation_steps=4,
+)
 
 accelerator = Accelerator(
     mixed_precision='bf16',
-    deepspeed_plugin={
-        "zero_stage": 2,  # ZeRO-2
-        "offload_optimizer": False,
-        "gradient_accumulation_steps": 4
-    }
+    deepspeed_plugin=deepspeed_plugin,  # DeepSpeedPlugin instance (or dict[str, DeepSpeedPlugin])
 )
 
 # Same code as before!
 model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)
 ```
 
-**Or via config**:
-```bash
-accelerate config
-# Select: DeepSpeed → ZeRO-2
+**Or point at a full DeepSpeed JSON config via the plugin**:
+```python
+from accelerate import Accelerator, DeepSpeedPlugin
+
+# hf_ds_config accepts a path to a DeepSpeed config JSON (or a dict)
+deepspeed_plugin = DeepSpeedPlugin(hf_ds_config="ds_config.json")
+accelerator = Accelerator(mixed_precision='bf16', deepspeed_plugin=deepspeed_plugin)
 ```
 
-**deepspeed_config.json**:
+**ds_config.json** (a raw DeepSpeed config — passed via the plugin, NOT via `--config_file`):
 ```json
 {
     "fp16": {"enabled": false},
@@ -183,9 +188,20 @@ accelerate config
 }
 ```
 
-**Launch**:
+**Or via interactive config**:
 ```bash
-accelerate launch --config_file deepspeed_config.json train.py
+accelerate config
+# Select: DeepSpeed → ZeRO-2
+# This writes an accelerate YAML config (default: ~/.cache/huggingface/accelerate/default_config.yaml)
+```
+
+**Launch** (`--config_file` expects an accelerate YAML, not a raw DeepSpeed JSON):
+```bash
+# Uses the default accelerate config written by `accelerate config`
+accelerate launch train.py
+
+# Or point at a specific accelerate YAML
+accelerate launch --config_file accelerate_deepspeed.yaml train.py
 ```
 
 ### Workflow 4: FSDP (Fully Sharded Data Parallel)
@@ -196,7 +212,7 @@ from accelerate import Accelerator, FullyShardedDataParallelPlugin
 
 fsdp_plugin = FullyShardedDataParallelPlugin(
     sharding_strategy="FULL_SHARD",  # ZeRO-3 equivalent
-    auto_wrap_policy="TRANSFORMER_AUTO_WRAP",
+    auto_wrap_policy="transformer_based_wrap",  # valid: transformer_based_wrap | size_based_wrap | no_wrap
     cpu_offload=False
 )
 
diff --git a/optional-skills/mlops/chroma/SKILL.md b/optional-skills/mlops/chroma/SKILL.md
index 60284bdb471..57f1d82b9ca 100644
--- a/optional-skills/mlops/chroma/SKILL.md
+++ b/optional-skills/mlops/chroma/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: chroma
-description: Open-source embedding database for AI applications. Store embeddings and metadata, perform vector and full-text search, filter by metadata. Simple 4-function API. Scales from notebooks to production clusters. Use for semantic search, RAG applications, or document retrieval. Best for local development and open-source projects.
+description: Embedding database for RAG and semantic search.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/clip/SKILL.md b/optional-skills/mlops/clip/SKILL.md
index d02335effb5..750510ec4b0 100644
--- a/optional-skills/mlops/clip/SKILL.md
+++ b/optional-skills/mlops/clip/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: clip
-description: OpenAI's model connecting vision and language. Enables zero-shot image classification, image-text matching, and cross-modal retrieval. Trained on 400M image-text pairs. Use for image search, content moderation, or vision-language tasks without fine-tuning. Best for general-purpose image understanding.
+description: Zero-shot image classification and image-text search.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/faiss/SKILL.md b/optional-skills/mlops/faiss/SKILL.md
index a263de0d1b2..19202c001be 100644
--- a/optional-skills/mlops/faiss/SKILL.md
+++ b/optional-skills/mlops/faiss/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: faiss
-description: Facebook's library for efficient similarity search and clustering of dense vectors. Supports billions of vectors, GPU acceleration, and various index types (Flat, IVF, HNSW). Use for fast k-NN search, large-scale vector retrieval, or when you need pure similarity search without metadata. Best for high-performance applications.
+description: Fast vector similarity search at billion scale.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/flash-attention/SKILL.md b/optional-skills/mlops/flash-attention/SKILL.md
index eca9e282b30..8f4374df688 100644
--- a/optional-skills/mlops/flash-attention/SKILL.md
+++ b/optional-skills/mlops/flash-attention/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: optimizing-attention-flash
-description: Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. Use when training/running transformers with long sequences (>512 tokens), encountering GPU memory issues with attention, or need faster inference. Supports PyTorch native SDPA, flash-attn library, H100 FP8, and sliding window attention.
-version: 1.0.0
+description: Speed up long-sequence transformer training and inference.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [flash-attn, torch, transformers]
@@ -82,13 +82,12 @@ import torch.nn.functional as F
 out = F.scaled_dot_product_attention(q, k, v, attn_mask=mask)
 ```
 
-Force Flash Attention backend:
+Force Flash Attention backend (`torch.backends.cuda.sdp_kernel` is deprecated; use
+`torch.nn.attention.sdpa_kernel` with `SDPBackend`):
 ```python
-with torch.backends.cuda.sdp_kernel(
-    enable_flash=True,
-    enable_math=False,
-    enable_mem_efficient=False
-):
+from torch.nn.attention import SDPBackend, sdpa_kernel
+
+with sdpa_kernel(SDPBackend.FLASH_ATTENTION):
     out = F.scaled_dot_product_attention(q, k, v)
 ```
 
@@ -101,7 +100,8 @@ def test_attention(use_flash):
     q, k, v = [torch.randn(2, 8, 2048, 64, device='cuda', dtype=torch.float16) for _ in range(3)]
 
     if use_flash:
-        with torch.backends.cuda.sdp_kernel(enable_flash=True):
+        from torch.nn.attention import SDPBackend, sdpa_kernel
+        with sdpa_kernel(SDPBackend.FLASH_ATTENTION):
             return F.scaled_dot_product_attention(q, k, v)
     else:
         attn = (q @ k.transpose(-2, -1) / 8.0).softmax(dim=-1)
@@ -230,14 +230,19 @@ print(f"Memory allocated: {torch.cuda.max_memory_allocated()/1e9:.2f}GB")
 
 ### Workflow 3: H100 FP8 optimization (FlashAttention-3)
 
-For maximum performance on H100 GPUs.
+For maximum performance on Hopper GPUs (H100).
+
+> **Important:** The pip package `flash-attn` (2.8.x) ships **FlashAttention-2 only** — it does
+> **not** contain FA3 or FP8 H100 kernels, and `flash_attn_func` does **not** auto-use FP8.
+> FlashAttention-3 is a separate **beta** build compiled from source from the repo's `hopper/`
+> directory, exposed via the `flash_attn_interface` module. FA3 supports FP16/BF16 forward+backward
+> and **FP8 forward only**.
 
 ```
 FP8 Setup:
-- [ ] Step 1: Verify H100 GPU available
-- [ ] Step 2: Install flash-attn with FP8 support
-- [ ] Step 3: Convert inputs to FP8
-- [ ] Step 4: Run with FP8 attention
+- [ ] Step 1: Verify Hopper (H100) GPU available
+- [ ] Step 2: Build & install FlashAttention-3 from source (hopper/)
+- [ ] Step 3: Use the FA3 interface (FP8 forward)
 ```
 
 **Step 1: Verify H100 GPU**
@@ -247,36 +252,38 @@ nvidia-smi --query-gpu=name --format=csv
 # Should show "H100" or "H800"
 ```
 
-**Step 2: Install flash-attn with FP8 support**
+**Step 2: Build & install FlashAttention-3 from source**
+
+FA3 is NOT included in `pip install flash-attn`. Build it from the `hopper/` subdirectory:
 
 ```bash
-pip install flash-attn --no-build-isolation
-# FP8 support included for H100
+git clone https://github.com/Dao-AILab/flash-attention.git
+cd flash-attention/hopper
+python setup.py install
+# (compilation is heavy and requires a CUDA toolchain + Hopper GPU)
 ```
 
-**Step 3: Convert inputs to FP8**
+**Step 3: Use the FA3 interface (FP8 forward)**
+
+FA3 exposes its own module `flash_attn_interface` (distinct from the FA2 `flash_attn`).
+FP8 is a **forward-only** path and expects `float8_e4m3fn` inputs:
 
 ```python
 import torch
+from flash_attn_interface import flash_attn_func  # FA3 (hopper build), not `flash_attn`
 
+# q, k, v: [batch, seqlen, nheads, headdim]
 q = torch.randn(2, 4096, 32, 64, device='cuda', dtype=torch.float16)
 k = torch.randn(2, 4096, 32, 64, device='cuda', dtype=torch.float16)
 v = torch.randn(2, 4096, 32, 64, device='cuda', dtype=torch.float16)
 
-# Convert to float8_e4m3 (FP8)
+# FP8 forward (inference / forward-only): cast to float8_e4m3fn
 q_fp8 = q.to(torch.float8_e4m3fn)
 k_fp8 = k.to(torch.float8_e4m3fn)
 v_fp8 = v.to(torch.float8_e4m3fn)
-```
 
-**Step 4: Run with FP8 attention**
-
-```python
-from flash_attn import flash_attn_func
-
-# FlashAttention-3 automatically uses FP8 kernels on H100
-out = flash_attn_func(q_fp8, k_fp8, v_fp8)
-# Result: ~1.2 PFLOPS, 1.5-2x faster than FP16
+out = flash_attn_func(q_fp8, k_fp8, v_fp8, causal=True)
+# FP16/BF16 forward+backward is also supported by the FA3 interface.
 ```
 
 ## When to use vs alternatives
diff --git a/optional-skills/mlops/guidance/SKILL.md b/optional-skills/mlops/guidance/SKILL.md
index bb917c645d6..157eb98a40f 100644
--- a/optional-skills/mlops/guidance/SKILL.md
+++ b/optional-skills/mlops/guidance/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: guidance
-description: Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidance - Microsoft Research's constrained generation framework
-version: 1.0.0
+description: Constrain LLM output with grammars; guarantee valid JSON.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [guidance, transformers]
@@ -53,13 +53,19 @@ result = lm + "The capital of France is " + gen("capital", max_tokens=5)
 print(result["capital"])  # "Paris"
 ```
 
-### With Anthropic Claude
+### Chat format with a local model
+
+> **Constraint support requires local logit access.** Regex, `select()`, and
+> grammar-based constrained generation only work with local backends
+> (`Transformers`, `LlamaCpp`). Remote API backends (`OpenAI`, and Azure
+> variants) support unconstrained `gen()` / chat only — they cannot enforce
+> token-level constraints. guidance 0.3.x has no `models.Anthropic` class.
 
 ```python
 from guidance import models, gen, system, user, assistant
 
-# Configure Claude
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+# Local model (supports constrained generation)
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 
 # Use context managers for chat format
 with system():
@@ -81,7 +87,7 @@ Guidance uses Pythonic context managers for chat-style interactions.
 ```python
 from guidance import system, user, assistant, gen
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 
 # System message
 with system():
@@ -112,7 +118,7 @@ Guidance ensures outputs match specified patterns using regex or grammars.
 ```python
 from guidance import models, gen
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 
 # Constrain to valid email format
 lm += "Email: " + gen("email", regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")
@@ -137,7 +143,7 @@ print(lm["date"])   # Guaranteed YYYY-MM-DD format
 ```python
 from guidance import models, gen, select
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 
 # Constrain to specific choices
 lm += "Sentiment: " + select(["positive", "negative", "neutral"], name="sentiment")
@@ -171,7 +177,7 @@ prompt = "The capital of France is "
 ```python
 from guidance import models, gen
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 
 # Token healing enabled by default
 lm += "The capital of France is " + gen("capital", max_tokens=5)
@@ -185,26 +191,30 @@ lm += "The capital of France is " + gen("capital", max_tokens=5)
 
 ### 4. Grammar-Based Generation
 
-Define complex structures using context-free grammars.
+Define complex structures by composing grammar functions. The template-string
+`grammar=` form is not part of current guidance — build grammars from
+composable functions, or use `guidance.json()` for JSON.
 
 ```python
 from guidance import models, gen
+from guidance import json as gen_json
+from pydantic import BaseModel, Field
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 
-# JSON grammar (simplified)
-json_grammar = """
-{
-    "name": <gen name regex="[A-Za-z ]+" max_tokens=20>,
-    "age": <gen age regex="[0-9]+" max_tokens=3>,
-    "email": <gen email regex="[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}" max_tokens=50>
-}
-"""
+# JSON via a Pydantic schema (guidance.json compiles the schema to a grammar)
+class Person(BaseModel):
+    name: str = Field(pattern=r"[A-Za-z ]+")
+    age: int
+    email: str = Field(pattern=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")
 
-# Generate valid JSON
-lm += gen("person", grammar=json_grammar)
+lm += gen_json(name="person", schema=Person)
 
-print(lm["person"])  # Guaranteed valid JSON structure
+print(lm["person"])  # Guaranteed valid JSON matching the schema
+
+# Or compose grammar functions directly:
+grammar = "name=" + gen("name", regex=r"[A-Za-z ]+") + " age=" + gen("age", regex=r"[0-9]+")
+lm += grammar
 ```
 
 **Use cases:**
@@ -228,7 +238,7 @@ def generate_person(lm):
     return lm
 
 # Use the function
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 lm = generate_person(lm)
 
 print(lm["name"])
@@ -266,20 +276,14 @@ def react_agent(lm, question, tools, max_rounds=5):
 
 ## Backend Configuration
 
-### Anthropic Claude
+### OpenAI (remote — unconstrained only)
+
+> Remote API backends cannot do constrained generation (regex/select/grammar);
+> use them only for plain chat/`gen()`. For constraints, use a local backend.
 
 ```python
 from guidance import models
 
-lm = models.Anthropic(
-    model="claude-sonnet-4-5-20250929",
-    api_key="your-api-key"  # Or set ANTHROPIC_API_KEY env var
-)
-```
-
-### OpenAI
-
-```python
 lm = models.OpenAI(
     model="gpt-4o-mini",
     api_key="your-api-key"  # Or set OPENAI_API_KEY env var
@@ -316,7 +320,7 @@ lm = LlamaCpp(
 ```python
 from guidance import models, gen, system, user, assistant
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 
 with system():
     lm += "You generate valid JSON."
@@ -339,7 +343,7 @@ print(lm)  # Valid JSON guaranteed
 ```python
 from guidance import models, gen, select
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 
 text = "This product is amazing! I love it."
 
@@ -370,7 +374,7 @@ def chain_of_thought(lm, question):
 
     return lm
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 lm = chain_of_thought(lm, "What is 15% of 200?")
 
 print(lm["answer"])
@@ -412,7 +416,7 @@ def react_agent(lm, question):
 
     return lm
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 lm = react_agent(lm, "What is 25 * 4 + 10?")
 print(lm["answer"])
 ```
@@ -443,7 +447,7 @@ def extract_entities(lm, text):
 
 text = "Tim Cook announced at Apple Park on 2024-09-15 in Cupertino."
 
-lm = models.Anthropic("claude-sonnet-4-5-20250929")
+lm = models.Transformers("microsoft/Phi-4-mini-instruct")
 lm = extract_entities(lm, text)
 
 print(f"Person: {lm['person']}")
diff --git a/optional-skills/mlops/huggingface-tokenizers/SKILL.md b/optional-skills/mlops/huggingface-tokenizers/SKILL.md
index a8a4c7781fe..776b5253e7e 100644
--- a/optional-skills/mlops/huggingface-tokenizers/SKILL.md
+++ b/optional-skills/mlops/huggingface-tokenizers/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: huggingface-tokenizers
-description: Fast tokenizers optimized for research and production. Rust-based implementation tokenizes 1GB in <20 seconds. Supports BPE, WordPiece, and Unigram algorithms. Train custom vocabularies, track alignments, handle padding/truncation. Integrates seamlessly with transformers. Use when you need high-performance tokenization or custom tokenizer training.
+description: Fast BPE/WordPiece tokenization and custom vocab training.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/inference/outlines/SKILL.md b/optional-skills/mlops/inference/outlines/SKILL.md
index 148a28fa692..16744e9a61c 100644
--- a/optional-skills/mlops/inference/outlines/SKILL.md
+++ b/optional-skills/mlops/inference/outlines/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: outlines
 description: "Outlines: structured JSON/regex/Pydantic LLM generation."
-version: 1.0.0
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [outlines, transformers, vllm, pydantic]
@@ -24,7 +24,15 @@ Use Outlines when you need to:
 - **Generate against JSON schemas** automatically
 - **Control token sampling** at the grammar level
 
-**GitHub Stars**: 8,000+ | **From**: dottxt.ai (formerly .txt)
+**GitHub Stars**: 12,000+ | **From**: dottxt.ai (formerly .txt)
+
+> **API note (Outlines 1.x):** This skill targets the current v1 API.
+> The pre-1.0 helpers (`outlines.models.transformers(...)`,
+> `outlines.generate.json/choice/regex/...`) have been **removed**. In v1 you
+> create a model with `outlines.from_transformers(...)` (or `from_vllm`,
+> `from_llamacpp`, `from_openai`) and then **call the model directly** with an
+> output type: `model(prompt, output_type)`. JSON/Pydantic outputs are returned
+> as a **JSON string** — validate with `YourModel.model_validate_json(result)`.
 
 ## Installation
 
@@ -45,14 +53,19 @@ pip install outlines vllm  # vLLM for high-throughput
 ```python
 import outlines
 from typing import Literal
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-# Load model
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
+MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct"
 
-# Generate with type constraint
+# v1: wrap a Transformers model + tokenizer
+model = outlines.from_transformers(
+    AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"),
+    AutoTokenizer.from_pretrained(MODEL_NAME),
+)
+
+# Call the model directly with an output type
 prompt = "Sentiment of 'This product is amazing!': "
-generator = outlines.generate.choice(model, ["positive", "negative", "neutral"])
-sentiment = generator(prompt)
+sentiment = model(prompt, Literal["positive", "negative", "neutral"])
 
 print(sentiment)  # "positive" (guaranteed one of these)
 ```
@@ -62,19 +75,24 @@ print(sentiment)  # "positive" (guaranteed one of these)
 ```python
 from pydantic import BaseModel
 import outlines
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
 class User(BaseModel):
     name: str
     age: int
     email: str
 
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
+MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct"
+model = outlines.from_transformers(
+    AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"),
+    AutoTokenizer.from_pretrained(MODEL_NAME),
+)
 
-# Generate structured output
+# Generate structured output (returns a JSON string)
 prompt = "Extract user: John Doe, 30 years old, john@example.com"
-generator = outlines.generate.json(model, User)
-user = generator(prompt)
+result = model(prompt, User, max_new_tokens=200)
 
+user = User.model_validate_json(result)  # parse into the Pydantic model
 print(user.name)   # "John Doe"
 print(user.age)    # 30
 print(user.email)  # "john@example.com"
@@ -84,11 +102,12 @@ print(user.email)  # "john@example.com"
 
 ### 1. Constrained Token Sampling
 
-Outlines uses Finite State Machines (FSM) to constrain token generation at the logit level.
+Outlines constrains token generation at the logit level using a compiled
+automaton derived from your output type.
 
 **How it works:**
-1. Convert schema (JSON/Pydantic/regex) to context-free grammar (CFG)
-2. Transform CFG into Finite State Machine (FSM)
+1. Convert the output type (JSON/Pydantic/regex/`Literal`) to a schema/grammar
+2. Compile the grammar into a token-level automaton
 3. Filter invalid tokens at each step during generation
 4. Fast-forward when only one valid token exists
 
@@ -99,42 +118,36 @@ Outlines uses Finite State Machines (FSM) to constrain token generation at the l
 
 ```python
 import outlines
+from pydantic import BaseModel
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-# Pydantic model -> JSON schema -> CFG -> FSM
 class Person(BaseModel):
     name: str
     age: int
 
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
-
-# Behind the scenes:
-# 1. Person -> JSON schema
-# 2. JSON schema -> CFG
-# 3. CFG -> FSM
-# 4. FSM filters tokens during generation
-
-generator = outlines.generate.json(model, Person)
-result = generator("Generate person: Alice, 25")
-```
-
-### 2. Structured Generators
-
-Outlines provides specialized generators for different output types.
-
-#### Choice Generator
-
-```python
-# Multiple choice selection
-generator = outlines.generate.choice(
-    model,
-    ["positive", "negative", "neutral"]
+model = outlines.from_transformers(
+    AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"),
+    AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
 )
 
-sentiment = generator("Review: This is great!")
-# Result: One of the three choices
+result = model("Generate person: Alice, 25", Person)
+person = Person.model_validate_json(result)
 ```
 
-#### JSON Generator
+### 2. Output Types
+
+In v1 you pass the desired **output type** directly as the second argument.
+
+#### Multiple choice (`Literal`)
+
+```python
+from typing import Literal
+
+sentiment = model("Review: This is great!", Literal["positive", "negative", "neutral"])
+# Result: one of the three choices
+```
+
+#### JSON via Pydantic
 
 ```python
 from pydantic import BaseModel
@@ -144,97 +157,85 @@ class Product(BaseModel):
     price: float
     in_stock: bool
 
-# Generate valid JSON matching schema
-generator = outlines.generate.json(model, Product)
-product = generator("Extract: iPhone 15, $999, available")
-
-# Guaranteed valid Product instance
-print(type(product))  # <class '__main__.Product'>
+result = model("Extract: iPhone 15, $999, available", Product)
+product = Product.model_validate_json(result)  # valid Product instance
 ```
 
-#### Regex Generator
+#### Regex (pass a regex string)
 
 ```python
-# Generate text matching regex
-generator = outlines.generate.regex(
-    model,
-    r"[0-9]{3}-[0-9]{3}-[0-9]{4}"  # Phone number pattern
-)
-
-phone = generator("Generate phone number:")
-# Result: "555-123-4567" (guaranteed to match pattern)
+# Generate text matching a regex pattern
+phone = model("Generate phone number:", r"[0-9]{3}-[0-9]{3}-[0-9]{4}")
+# Result: "555-123-4567" (guaranteed to match the pattern)
 ```
 
-#### Integer/Float Generators
+#### Numeric types
 
 ```python
-# Generate specific numeric types
-int_generator = outlines.generate.integer(model)
-age = int_generator("Person's age:")  # Guaranteed integer
-
-float_generator = outlines.generate.float(model)
-price = float_generator("Product price:")  # Guaranteed float
+# Pass the Python type directly
+age = model("Person's age:", int)      # guaranteed integer
+price = model("Product price:", float)  # guaranteed float
 ```
 
 ### 3. Model Backends
 
-Outlines supports multiple local and API-based backends.
+Outlines supports multiple local and API-based backends via `from_*` factories.
 
 #### Transformers (Hugging Face)
 
 ```python
 import outlines
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-# Load from Hugging Face
-model = outlines.models.transformers(
-    "microsoft/Phi-3-mini-4k-instruct",
-    device="cuda"  # Or "cpu"
+model = outlines.from_transformers(
+    AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"),
+    AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
 )
 
-# Use with any generator
-generator = outlines.generate.json(model, YourModel)
+result = model(prompt, YourModel)
 ```
 
 #### llama.cpp
 
 ```python
-# Load GGUF model
-model = outlines.models.llamacpp(
-    "./models/llama-3.1-8b-instruct.Q4_K_M.gguf",
-    n_gpu_layers=35
-)
+import outlines
+from llama_cpp import Llama
 
-generator = outlines.generate.json(model, YourModel)
+llm = Llama("./models/llama-3.1-8b-instruct.Q4_K_M.gguf", n_gpu_layers=35, n_ctx=4096)
+model = outlines.from_llamacpp(llm)
+
+result = model(prompt, YourModel)
 ```
 
 #### vLLM (High Throughput)
 
 ```python
-# For production deployments
-model = outlines.models.vllm(
-    "meta-llama/Llama-3.1-8B-Instruct",
-    tensor_parallel_size=2  # Multi-GPU
-)
+import outlines
+from vllm import LLM
 
-generator = outlines.generate.json(model, YourModel)
+llm = LLM("meta-llama/Llama-3.1-8B-Instruct", tensor_parallel_size=2)
+model = outlines.from_vllm(llm)
+
+result = model(prompt, YourModel)
 ```
 
-#### OpenAI (Limited Support)
+#### OpenAI (server-side constrained JSON)
 
 ```python
-# Basic OpenAI support
-model = outlines.models.openai(
-    "gpt-4o-mini",
-    api_key="your-api-key"
-)
+import outlines
+from openai import OpenAI
 
-# Note: Some features limited with API models
-generator = outlines.generate.json(model, YourModel)
+client = OpenAI()
+model = outlines.from_openai(client, "gpt-4o-mini")
+
+# API backends support JSON-schema style structured output
+result = model(prompt, YourModel)
 ```
 
 ### 4. Pydantic Integration
 
 Outlines has first-class Pydantic support with automatic schema translation.
+Generation returns a JSON string; call `model_validate_json` to get an instance.
 
 #### Basic Models
 
@@ -247,10 +248,8 @@ class Article(BaseModel):
     word_count: int = Field(description="Number of words", gt=0)
     tags: list[str] = Field(description="List of tags")
 
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
-generator = outlines.generate.json(model, Article)
-
-article = generator("Generate article about AI")
+result = model("Generate article about AI", Article, max_new_tokens=300)
+article = Article.model_validate_json(result)
 print(article.title)
 print(article.word_count)  # Guaranteed > 0
 ```
@@ -268,9 +267,8 @@ class Person(BaseModel):
     age: int
     address: Address  # Nested model
 
-generator = outlines.generate.json(model, Person)
-person = generator("Generate person in New York")
-
+result = model("Generate person in New York", Person)
+person = Person.model_validate_json(result)
 print(person.address.city)  # "New York"
 ```
 
@@ -290,9 +288,8 @@ class Application(BaseModel):
     status: Status  # Must be one of enum values
     priority: Literal["low", "medium", "high"]  # Must be one of literals
 
-generator = outlines.generate.json(model, Application)
-app = generator("Generate application")
-
+result = model("Generate application", Application)
+app = Application.model_validate_json(result)
 print(app.status)  # Status.PENDING (or APPROVED/REJECTED)
 ```
 
@@ -303,6 +300,7 @@ print(app.status)  # Status.PENDING (or APPROVED/REJECTED)
 ```python
 from pydantic import BaseModel
 import outlines
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
 class CompanyInfo(BaseModel):
     name: str
@@ -310,8 +308,10 @@ class CompanyInfo(BaseModel):
     industry: str
     employees: int
 
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
-generator = outlines.generate.json(model, CompanyInfo)
+model = outlines.from_transformers(
+    AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"),
+    AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
+)
 
 text = """
 Apple Inc. was founded in 1976 in the technology industry.
@@ -319,7 +319,7 @@ The company employs approximately 164,000 people worldwide.
 """
 
 prompt = f"Extract company information:\n{text}\n\nCompany:"
-company = generator(prompt)
+company = CompanyInfo.model_validate_json(model(prompt, CompanyInfo, max_new_tokens=200))
 
 print(f"Name: {company.name}")
 print(f"Founded: {company.founded_year}")
@@ -331,26 +331,24 @@ print(f"Employees: {company.employees}")
 
 ```python
 from typing import Literal
-import outlines
-
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
+from pydantic import BaseModel
 
 # Binary classification
-generator = outlines.generate.choice(model, ["spam", "not_spam"])
-result = generator("Email: Buy now! 50% off!")
+result = model("Email: Buy now! 50% off!", Literal["spam", "not_spam"])
 
 # Multi-class classification
-categories = ["technology", "business", "sports", "entertainment"]
-category_gen = outlines.generate.choice(model, categories)
-category = category_gen("Article: Apple announces new iPhone...")
+category = model(
+    "Article: Apple announces new iPhone...",
+    Literal["technology", "business", "sports", "entertainment"],
+)
 
 # With confidence
 class Classification(BaseModel):
     label: Literal["positive", "negative", "neutral"]
     confidence: float
 
-classifier = outlines.generate.json(model, Classification)
-result = classifier("Review: This product is okay, nothing special")
+out = model("Review: This product is okay, nothing special", Classification)
+result = Classification.model_validate_json(out)
 ```
 
 ### Pattern 3: Structured Forms
@@ -364,9 +362,6 @@ class UserProfile(BaseModel):
     country: str
     interests: list[str]
 
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
-generator = outlines.generate.json(model, UserProfile)
-
 prompt = """
 Extract user profile from:
 Name: Alice Johnson
@@ -377,7 +372,7 @@ Country: USA
 Interests: hiking, photography, cooking
 """
 
-profile = generator(prompt)
+profile = UserProfile.model_validate_json(model(prompt, UserProfile, max_new_tokens=250))
 print(profile.full_name)
 print(profile.interests)  # ["hiking", "photography", "cooking"]
 ```
@@ -385,6 +380,8 @@ print(profile.interests)  # ["hiking", "photography", "cooking"]
 ### Pattern 4: Multi-Entity Extraction
 
 ```python
+from typing import Literal
+
 class Entity(BaseModel):
     name: str
     type: Literal["PERSON", "ORGANIZATION", "LOCATION"]
@@ -392,13 +389,10 @@ class Entity(BaseModel):
 class DocumentEntities(BaseModel):
     entities: list[Entity]
 
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
-generator = outlines.generate.json(model, DocumentEntities)
-
 text = "Tim Cook met with Satya Nadella at Microsoft headquarters in Redmond."
 prompt = f"Extract entities from: {text}"
 
-result = generator(prompt)
+result = DocumentEntities.model_validate_json(model(prompt, DocumentEntities, max_new_tokens=300))
 for entity in result.entities:
     print(f"{entity.name} ({entity.type})")
 ```
@@ -412,11 +406,8 @@ class PythonFunction(BaseModel):
     docstring: str
     body: str
 
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
-generator = outlines.generate.json(model, PythonFunction)
-
 prompt = "Generate a Python function to calculate factorial"
-func = generator(prompt)
+func = PythonFunction.model_validate_json(model(prompt, PythonFunction, max_new_tokens=300))
 
 print(f"def {func.function_name}({', '.join(func.parameters)}):")
 print(f'    """{func.docstring}"""')
@@ -426,29 +417,29 @@ print(f"    {func.body}")
 ### Pattern 6: Batch Processing
 
 ```python
-def batch_extract(texts: list[str], schema: type[BaseModel]):
-    """Extract structured data from multiple texts."""
-    model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
-    generator = outlines.generate.json(model, schema)
-
-    results = []
-    for text in texts:
-        result = generator(f"Extract from: {text}")
-        results.append(result)
-
-    return results
+import outlines
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from pydantic import BaseModel
 
 class Person(BaseModel):
     name: str
     age: int
 
+model = outlines.from_transformers(
+    AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"),
+    AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
+)
+
 texts = [
     "John is 30 years old",
     "Alice is 25 years old",
-    "Bob is 40 years old"
+    "Bob is 40 years old",
 ]
 
-people = batch_extract(texts, Person)
+# v1 accepts a list of prompts for batched generation
+prompts = [f"Extract from: {t}" for t in texts]
+outputs = model(prompts, Person, max_new_tokens=100)
+people = [Person.model_validate_json(o) for o in outputs]
 for person in people:
     print(f"{person.name}: {person.age}")
 ```
@@ -459,58 +450,67 @@ for person in people:
 
 ```python
 import outlines
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct"
 
 # Basic usage
-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
+model = outlines.from_transformers(
+    AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"),
+    AutoTokenizer.from_pretrained(MODEL_NAME),
+)
 
-# GPU configuration
-model = outlines.models.transformers(
-    "microsoft/Phi-3-mini-4k-instruct",
-    device="cuda",
-    model_kwargs={"torch_dtype": "float16"}
+# GPU + dtype configuration is set on the HF model itself
+import torch
+model = outlines.from_transformers(
+    AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="cuda", torch_dtype=torch.float16),
+    AutoTokenizer.from_pretrained(MODEL_NAME),
 )
 
 # Popular models
-model = outlines.models.transformers("meta-llama/Llama-3.1-8B-Instruct")
-model = outlines.models.transformers("mistralai/Mistral-7B-Instruct-v0.3")
-model = outlines.models.transformers("Qwen/Qwen2.5-7B-Instruct")
+for name in [
+    "meta-llama/Llama-3.1-8B-Instruct",
+    "mistralai/Mistral-7B-Instruct-v0.3",
+    "Qwen/Qwen2.5-7B-Instruct",
+]:
+    model = outlines.from_transformers(
+        AutoModelForCausalLM.from_pretrained(name, device_map="auto"),
+        AutoTokenizer.from_pretrained(name),
+    )
 ```
 
 ### llama.cpp
 
 ```python
-# Load GGUF model
-model = outlines.models.llamacpp(
-    "./models/llama-3.1-8b.Q4_K_M.gguf",
-    n_ctx=4096,         # Context window
-    n_gpu_layers=35,    # GPU layers
-    n_threads=8         # CPU threads
-)
+import outlines
+from llama_cpp import Llama
 
-# Full GPU offload
-model = outlines.models.llamacpp(
-    "./models/model.gguf",
-    n_gpu_layers=-1  # All layers on GPU
+# Load GGUF model
+llm = Llama(
+    "./models/llama-3.1-8b.Q4_K_M.gguf",
+    n_ctx=4096,       # Context window
+    n_gpu_layers=35,  # GPU layers
+    n_threads=8,      # CPU threads
 )
+model = outlines.from_llamacpp(llm)
+
+# Full GPU offload: set n_gpu_layers=-1 on the Llama object
 ```
 
 ### vLLM (Production)
 
 ```python
+import outlines
+from vllm import LLM
+
 # Single GPU
-model = outlines.models.vllm("meta-llama/Llama-3.1-8B-Instruct")
+model = outlines.from_vllm(LLM("meta-llama/Llama-3.1-8B-Instruct"))
 
 # Multi-GPU
-model = outlines.models.vllm(
-    "meta-llama/Llama-3.1-70B-Instruct",
-    tensor_parallel_size=4  # 4 GPUs
-)
+model = outlines.from_vllm(LLM("meta-llama/Llama-3.1-70B-Instruct", tensor_parallel_size=4))
 
 # With quantization
-model = outlines.models.vllm(
-    "meta-llama/Llama-3.1-8B-Instruct",
-    quantization="awq"  # Or "gptq"
-)
+model = outlines.from_vllm(LLM("meta-llama/Llama-3.1-8B-Instruct", quantization="awq"))
 ```
 
 ## Best Practices
@@ -598,15 +598,23 @@ class Article(BaseModel):
 # Can succeed even if author/date missing
 ```
 
+### 6. Always Validate JSON Output
+
+```python
+# v1 returns a JSON string for Pydantic/JSON output types.
+result = model(prompt, Article)          # str
+article = Article.model_validate_json(result)  # Article instance
+```
+
 ## Comparison to Alternatives
 
 | Feature | Outlines | Instructor | Guidance | LMQL |
 |---------|----------|------------|----------|------|
-| Pydantic Support | ✅ Native | ✅ Native | ❌ No | ❌ No |
-| JSON Schema | ✅ Yes | ✅ Yes | ⚠️ Limited | ✅ Yes |
+| Pydantic Support | ✅ Native | ✅ Native | ✅ Yes | ❌ No |
+| JSON Schema | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
 | Regex Constraints | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |
 | Local Models | ✅ Full | ⚠️ Limited | ✅ Full | ✅ Full |
-| API Models | ⚠️ Limited | ✅ Full | ✅ Full | ✅ Full |
+| API Models | ✅ Yes | ✅ Full | ✅ Yes | ✅ Full |
 | Zero Overhead | ✅ Yes | ❌ No | ⚠️ Partial | ✅ Yes |
 | Automatic Retrying | ❌ No | ✅ Yes | ❌ No | ❌ No |
 | Learning Curve | Low | Low | Low | High |
@@ -631,19 +639,19 @@ class Article(BaseModel):
 - **1.2-2x faster** than post-generation validation approaches
 
 **Memory:**
-- FSM compiled once per schema (cached)
+- Automaton compiled once per output type (cached)
 - Minimal runtime overhead
 - Efficient with vLLM for high throughput
 
 **Accuracy:**
-- **100% valid outputs** (guaranteed by FSM)
+- **100% valid outputs** (guaranteed by the constrained automaton)
 - No retry loops needed
 - Deterministic token filtering
 
 ## Resources
 
-- **Documentation**: https://outlines-dev.github.io/outlines
-- **GitHub**: https://github.com/outlines-dev/outlines (8k+ stars)
+- **Documentation**: https://dottxt-ai.github.io/outlines/
+- **GitHub**: https://github.com/dottxt-ai/outlines (12k+ stars)
 - **Discord**: https://discord.gg/R9DSu34mGd
 - **Blog**: https://blog.dottxt.co
 
@@ -652,5 +660,3 @@ class Article(BaseModel):
 - `references/json_generation.md` - Comprehensive JSON and Pydantic patterns
 - `references/backends.md` - Backend-specific configuration
 - `references/examples.md` - Production-ready examples
-
-
diff --git a/optional-skills/mlops/instructor/SKILL.md b/optional-skills/mlops/instructor/SKILL.md
index 24f44e60697..7dbcc7de59f 100644
--- a/optional-skills/mlops/instructor/SKILL.md
+++ b/optional-skills/mlops/instructor/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: instructor
-description: Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream partial results with Instructor - battle-tested structured output library
+description: Structured LLM outputs validated with Pydantic.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/lambda-labs/SKILL.md b/optional-skills/mlops/lambda-labs/SKILL.md
index 2a12d413d8b..742e7086fc4 100644
--- a/optional-skills/mlops/lambda-labs/SKILL.md
+++ b/optional-skills/mlops/lambda-labs/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: lambda-labs-gpu-cloud
-description: Reserved and on-demand GPU cloud instances for ML training and inference. Use when you need dedicated GPU instances with simple SSH access, persistent filesystems, or high-performance multi-node clusters for large-scale training.
+description: On-demand GPU cloud instances for ML training.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/llava/SKILL.md b/optional-skills/mlops/llava/SKILL.md
index 65380c15710..3327b024018 100644
--- a/optional-skills/mlops/llava/SKILL.md
+++ b/optional-skills/mlops/llava/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: llava
-description: Large Language and Vision Assistant. Enables visual instruction tuning and image-based conversations. Combines CLIP vision encoder with Vicuna/LLaMA language models. Supports multi-turn image chat, visual question answering, and instruction following. Use for vision-language chatbots or image understanding tasks. Best for conversational image analysis.
+description: "Vision-language chat: VQA, captioning, image dialogue."
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/modal/SKILL.md b/optional-skills/mlops/modal/SKILL.md
index 23cf7b3850c..66d754fdc6f 100644
--- a/optional-skills/mlops/modal/SKILL.md
+++ b/optional-skills/mlops/modal/SKILL.md
@@ -1,10 +1,10 @@
 ---
 name: modal-serverless-gpu
-description: Serverless GPU cloud platform for running ML workloads. Use when you need on-demand GPU access without infrastructure management, deploying ML models as APIs, or running batch jobs with automatic scaling.
-version: 1.0.0
+description: Serverless GPU cloud for ML jobs and model APIs.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
-dependencies: [modal>=0.64.0]
+dependencies: [modal>=1.0]
 platforms: [linux, macos, windows]
 metadata:
   hermes:
@@ -227,7 +227,6 @@ async def batch_predict(inputs: list[str]) -> list[dict]:
     # Inputs automatically batched
     return model.batch_predict(inputs)
 ```
-
 ## Secrets management
 
 ```bash
@@ -259,10 +258,10 @@ def hourly_job():
 ### Cold start mitigation
 
 ```python
-@app.function(
-    container_idle_timeout=300,  # Keep warm 5 min
-    allow_concurrent_inputs=10,  # Handle concurrent requests
-)
+# Modal 1.0 autoscaler params: scaledown_window (was container_idle_timeout).
+# Input concurrency moved to the @modal.concurrent decorator.
+@app.function(scaledown_window=300)  # Keep warm 5 min
+@modal.concurrent(max_inputs=10)     # Handle concurrent requests per container
 def inference():
     pass
 ```
@@ -304,14 +303,21 @@ def run_parallel():
     memory=32768,              # 32GB RAM
     cpu=4,                     # 4 CPU cores
     timeout=3600,              # 1 hour max
-    container_idle_timeout=120,# Keep warm 2 min
+    scaledown_window=120,      # Keep warm 2 min (was container_idle_timeout)
     retries=3,                 # Retry on failure
-    concurrency_limit=10,      # Max concurrent containers
+    max_containers=10,         # Max concurrent containers (was concurrency_limit)
+    min_containers=1,          # Keep N containers warm (was keep_warm)
 )
 def my_function():
     pass
 ```
 
+> **Modal 1.0 autoscaler renames** (see the [migration guide](https://modal.com/docs/guide/modal-1-0-migration)):
+> - `container_idle_timeout` → `scaledown_window`
+> - `concurrency_limit` → `max_containers`
+> - `keep_warm` → `min_containers`
+> - `allow_concurrent_inputs=N` → the `@modal.concurrent(max_inputs=N)` decorator
+
 ## Debugging
 
 ```python
@@ -327,7 +333,7 @@ if __name__ == "__main__":
 
 | Issue | Solution |
 |-------|----------|
-| Cold start latency | Increase `container_idle_timeout`, use `@modal.enter()` |
+| Cold start latency | Increase `scaledown_window`, use `@modal.enter()` |
 | GPU OOM | Use larger GPU (`A100-80GB`), enable gradient checkpointing |
 | Image build fails | Pin dependency versions, check CUDA compatibility |
 | Timeout errors | Increase `timeout`, add checkpointing |
diff --git a/skills/mlops/models/segment-anything/SKILL.md b/optional-skills/mlops/models/segment-anything-model/SKILL.md
similarity index 100%
rename from skills/mlops/models/segment-anything/SKILL.md
rename to optional-skills/mlops/models/segment-anything-model/SKILL.md
diff --git a/skills/mlops/models/segment-anything/references/advanced-usage.md b/optional-skills/mlops/models/segment-anything-model/references/advanced-usage.md
similarity index 100%
rename from skills/mlops/models/segment-anything/references/advanced-usage.md
rename to optional-skills/mlops/models/segment-anything-model/references/advanced-usage.md
diff --git a/skills/mlops/models/segment-anything/references/troubleshooting.md b/optional-skills/mlops/models/segment-anything-model/references/troubleshooting.md
similarity index 100%
rename from skills/mlops/models/segment-anything/references/troubleshooting.md
rename to optional-skills/mlops/models/segment-anything-model/references/troubleshooting.md
diff --git a/optional-skills/mlops/nemo-curator/SKILL.md b/optional-skills/mlops/nemo-curator/SKILL.md
index 6ab232ee579..48cb211482f 100644
--- a/optional-skills/mlops/nemo-curator/SKILL.md
+++ b/optional-skills/mlops/nemo-curator/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: nemo-curator
-description: GPU-accelerated data curation for LLM training. Supports text/image/video/audio. Features fuzzy deduplication (16× faster), quality filtering (30+ heuristics), semantic deduplication, PII redaction, NSFW detection. Scales across GPUs with RAPIDS. Use for preparing high-quality training datasets, cleaning web data, or deduplicating large corpora.
-version: 1.0.0
+description: "Curate LLM training data: dedupe, filter, PII redaction."
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [nemo-curator, cudf, dask, rapids]
@@ -40,41 +40,55 @@ NVIDIA's toolkit for preparing high-quality training data for LLMs.
 ### Installation
 
 ```bash
+# NeMo Curator 1.x installs with uv. Extras use hyphens (PyPI-normalized):
+#   text-cuda12 / text-cpu (and image/video/audio/math variants), or `all`.
+
 # Text curation (CUDA 12)
-uv pip install "nemo-curator[text_cuda12]"
+uv pip install "nemo-curator[text-cuda12]"
 
 # All modalities
-uv pip install "nemo-curator[all_cuda12]"
+uv pip install "nemo-curator[all]"
 
-# CPU-only (slower)
-uv pip install "nemo-curator[cpu]"
+# CPU-only text (slower)
+uv pip install "nemo-curator[text-cpu]"
 ```
 
 ### Basic text curation pipeline
 
+> **Major version rewrite (1.x):** NeMo Curator was rewritten around a **Ray-based
+> pipeline/stage architecture**. The old `DocumentDataset` + `nemo_curator.modules.*` /
+> `ScoreFilter` / `Modify` call-the-object-on-a-dataset API from 0.x is gone. In 1.x you
+> compose `ProcessingStage`s into a `Pipeline` and run it with an executor. The exact
+> stage/import surface differs per modality — treat the examples in this skill below as
+> **conceptual** (0.x-style) and follow the current
+> [quickstart](https://github.com/NVIDIA-NeMo/Curator/blob/main/tutorials/quickstart.py)
+> and [text guide](https://docs.nvidia.com/nemo/curator/latest/get-started/text) for the
+> exact 1.x APIs rather than copying imports verbatim.
+
+Shape of a 1.x pipeline (from the upstream quickstart):
+
 ```python
-from nemo_curator import ScoreFilter, Modify
-from nemo_curator.datasets import DocumentDataset
-import pandas as pd
+from nemo_curator.pipeline import Pipeline
+from nemo_curator.stages.base import ProcessingStage
+from nemo_curator.stages.resources import Resources
+from nemo_curator.backends.xenna import XennaExecutor
+from nemo_curator.core.client import RayClient
 
-# Load data
-df = pd.DataFrame({"text": ["Good document", "Bad doc", "Excellent text"]})
-dataset = DocumentDataset(df)
+# 1. Define/compose stages (load -> filter -> dedupe -> classify -> write).
+#    Each stage declares its own Resources (CPU cores, GPU memory, replicas).
+pipeline = Pipeline(name="curation", stages=[...])
 
-# Quality filtering
-def quality_score(doc):
-    return len(doc["text"].split()) > 5  # Filter short docs
-
-filtered = ScoreFilter(quality_score)(dataset)
-
-# Deduplication
-from nemo_curator.modules import ExactDuplicates
-deduped = ExactDuplicates()(filtered)
-
-# Save
-deduped.to_parquet("curated_data/")
+# 2. Run it with an executor (Ray-backed).
+client = RayClient()
+client.start()
+pipeline.run(XennaExecutor())
+client.stop()
 ```
 
+The 0.x-style snippets in the sections that follow illustrate the *concepts* (quality
+filtering, exact/fuzzy/semantic dedup, PII redaction, classifier filtering). For runnable
+1.x code, map each concept onto the corresponding stage from the modality guide.
+
 ## Data curation pipeline
 
 ### Stage 1: Quality filtering
@@ -378,9 +392,9 @@ cluster.close()
 
 ## Resources
 
-- **GitHub**: https://github.com/NVIDIA/NeMo-Curator ⭐ 500+
-- **Docs**: https://docs.nvidia.com/nemo-framework/user-guide/latest/datacuration/
-- **Version**: 0.4.0+
+- **GitHub**: https://github.com/NVIDIA-NeMo/Curator
+- **Docs**: https://docs.nvidia.com/nemo/curator/latest/
+- **Version**: 1.2.0 (1.x is a Ray-based pipeline rewrite — see the quickstart before copying 0.x snippets)
 - **License**: Apache 2.0
 
 
diff --git a/optional-skills/mlops/obliteratus/SKILL.md b/optional-skills/mlops/obliteratus/SKILL.md
index ea93758327e..bea9cfe298f 100644
--- a/optional-skills/mlops/obliteratus/SKILL.md
+++ b/optional-skills/mlops/obliteratus/SKILL.md
@@ -9,7 +9,7 @@ platforms: [linux, macos]
 metadata:
   hermes:
     tags: [Abliteration, Uncensoring, Refusal-Removal, LLM, Weight-Projection, SVD, Mechanistic-Interpretability, HuggingFace, Model-Surgery]
-    related_skills: [vllm, gguf, huggingface-tokenizers]
+    related_skills: [serving-llms-vllm, llama-cpp, huggingface-tokenizers]
 ---
 
 # OBLITERATUS Skill
diff --git a/optional-skills/mlops/peft/SKILL.md b/optional-skills/mlops/peft/SKILL.md
index d1158848621..78f0fabe6cb 100644
--- a/optional-skills/mlops/peft/SKILL.md
+++ b/optional-skills/mlops/peft/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: peft-fine-tuning
-description: Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods. Use when fine-tuning large models (7B-70B) with limited GPU memory, when you need to train <1% of parameters with minimal accuracy loss, or for multi-adapter serving. HuggingFace's official library integrated with transformers ecosystem.
+description: Fine-tune large LLMs with LoRA on limited GPU memory.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/pinecone/SKILL.md b/optional-skills/mlops/pinecone/SKILL.md
index 8de458501b1..b32dcddadfb 100644
--- a/optional-skills/mlops/pinecone/SKILL.md
+++ b/optional-skills/mlops/pinecone/SKILL.md
@@ -1,10 +1,10 @@
 ---
 name: pinecone
-description: Managed vector database for production AI applications. Fully managed, auto-scaling, with hybrid search (dense + sparse), metadata filtering, and namespaces. Low latency (<100ms p95). Use for production RAG, recommendation systems, or semantic search at scale. Best for serverless, managed infrastructure.
-version: 1.0.0
+description: Managed vector DB for production RAG and search.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
-dependencies: [pinecone-client]
+dependencies: [pinecone]
 platforms: [linux, macos, windows]
 metadata:
   hermes:
@@ -42,9 +42,11 @@ The vector database for production AI applications.
 ### Installation
 
 ```bash
-pip install pinecone-client
+pip install pinecone
 ```
 
+> Note: the old `pinecone-client` package is deprecated. Install `pinecone` (v5+; current 9.x). The import stays `from pinecone import Pinecone`.
+
 ### Basic usage
 
 ```python
@@ -226,14 +228,31 @@ index.upsert(vectors=[
 ])
 
 # Hybrid query
+# NOTE: index.query() does NOT accept an `alpha` kwarg. Pinecone stores a
+# single sparse-dense vector, so weighting must be applied by pre-scaling the
+# query vectors before sending them. Use the hybrid_score_norm helper below
+# (alpha * dense + (1 - alpha) * sparse; alpha=1 → pure dense, 0 → pure sparse).
+
+def hybrid_score_norm(dense, sparse, alpha: float):
+    """Scale dense/sparse query vectors for weighted hybrid search."""
+    if not 0 <= alpha <= 1:
+        raise ValueError("alpha must be between 0 and 1")
+    scaled_sparse = {
+        "indices": sparse["indices"],
+        "values": [v * (1 - alpha) for v in sparse["values"]],
+    }
+    return [v * alpha for v in dense], scaled_sparse
+
+hdense, hsparse = hybrid_score_norm(
+    dense=[0.1, 0.2, ...],
+    sparse={"indices": [10, 45], "values": [0.5, 0.3]},
+    alpha=0.5,  # 0=sparse, 1=dense, 0.5=balanced
+)
+
 results = index.query(
-    vector=[0.1, 0.2, ...],
-    sparse_vector={
-        "indices": [10, 45],
-        "values": [0.5, 0.3]
-    },
+    vector=hdense,
+    sparse_vector=hsparse,
     top_k=5,
-    alpha=0.5  # 0=sparse, 1=dense, 0.5=hybrid
 )
 ```
 
diff --git a/optional-skills/mlops/pytorch-fsdp/SKILL.md b/optional-skills/mlops/pytorch-fsdp/SKILL.md
index 680f1791f65..0436133e34b 100644
--- a/optional-skills/mlops/pytorch-fsdp/SKILL.md
+++ b/optional-skills/mlops/pytorch-fsdp/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pytorch-fsdp
-description: Expert guidance for Fully Sharded Data Parallel training with PyTorch FSDP - parameter sharding, mixed precision, CPU offloading, FSDP2
+description: Fully sharded data-parallel training for large models.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/pytorch-lightning/SKILL.md b/optional-skills/mlops/pytorch-lightning/SKILL.md
index 58f4a9c5b8e..3e03e55f936 100644
--- a/optional-skills/mlops/pytorch-lightning/SKILL.md
+++ b/optional-skills/mlops/pytorch-lightning/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pytorch-lightning
-description: High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate. Scales from laptop to supercomputer with same code. Use when you want clean training loops with built-in best practices.
+description: Clean training loops with built-in distributed support.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/qdrant/SKILL.md b/optional-skills/mlops/qdrant/SKILL.md
index 64fb526ffa7..4507d89a1c9 100644
--- a/optional-skills/mlops/qdrant/SKILL.md
+++ b/optional-skills/mlops/qdrant/SKILL.md
@@ -1,10 +1,10 @@
 ---
 name: qdrant-vector-search
-description: High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered performance.
-version: 1.0.0
+description: Vector search engine for production RAG systems.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
-dependencies: [qdrant-client>=1.12.0]
+dependencies: [qdrant-client>=1.14.0]
 platforms: [linux, macos, windows]
 metadata:
   hermes:
@@ -89,17 +89,17 @@ client.upsert(
     ]
 )
 
-# Search with filtering
-results = client.search(
+# Search with filtering (query_points is the current API; client.search is removed in qdrant-client 1.14+)
+response = client.query_points(
     collection_name="documents",
-    query_vector=[0.15, 0.25, ...],
+    query=[0.15, 0.25, ...],
     query_filter={
         "must": [{"key": "category", "match": {"value": "tech"}}]
     },
     limit=10
 )
 
-for point in results:
+for point in response.points:
     print(f"ID: {point.id}, Score: {point.score}, Payload: {point.payload}")
 ```
 
@@ -169,14 +169,15 @@ print(f"Points: {info.points_count}, Vectors: {info.vectors_count}")
 ### Basic search
 
 ```python
-# Simple nearest neighbor search
-results = client.search(
+# Simple nearest neighbor search (returns a QueryResponse; use .points)
+response = client.query_points(
     collection_name="documents",
-    query_vector=[0.1, 0.2, ...],
+    query=[0.1, 0.2, ...],
     limit=10,
     with_payload=True,
     with_vectors=False  # Don't return vectors (faster)
 )
+results = response.points
 ```
 
 ### Filtered search
@@ -185,9 +186,9 @@ results = client.search(
 from qdrant_client.models import Filter, FieldCondition, MatchValue, Range
 
 # Complex filtering
-results = client.search(
+response = client.query_points(
     collection_name="documents",
-    query_vector=query_embedding,
+    query=query_embedding,
     query_filter=Filter(
         must=[
             FieldCondition(key="category", match=MatchValue(value="tech")),
@@ -198,12 +199,12 @@ results = client.search(
         ]
     ),
     limit=10
-)
+).points
 
 # Shorthand filter syntax
-results = client.search(
+response = client.query_points(
     collection_name="documents",
-    query_vector=query_embedding,
+    query=query_embedding,
     query_filter={
         "must": [
             {"key": "category", "match": {"value": "tech"}},
@@ -211,23 +212,27 @@ results = client.search(
         ]
     },
     limit=10
-)
+).points
 ```
 
 ### Batch search
 
 ```python
-from qdrant_client.models import SearchRequest
+from qdrant_client.models import QueryRequest
 
-# Multiple queries in one request
-results = client.search_batch(
+# Multiple queries in one request (search_batch is replaced by query_batch_points)
+responses = client.query_batch_points(
     collection_name="documents",
     requests=[
-        SearchRequest(vector=[0.1, ...], limit=5),
-        SearchRequest(vector=[0.2, ...], limit=5, filter={"must": [...]}),
-        SearchRequest(vector=[0.3, ...], limit=10)
+        QueryRequest(query=[0.1, ...], limit=5),
+        QueryRequest(query=[0.2, ...], limit=5, filter={"must": [...]}),
+        QueryRequest(query=[0.3, ...], limit=10)
     ]
 )
+# Each element is a QueryResponse; use .points
+for resp in responses:
+    for point in resp.points:
+        print(point.id, point.score)
 ```
 
 ## RAG integration
@@ -268,12 +273,12 @@ client.upsert(collection_name="knowledge_base", points=points)
 # RAG retrieval
 def retrieve(query: str, top_k: int = 5) -> list[dict]:
     query_vector = encoder.encode(query).tolist()
-    results = client.search(
+    response = client.query_points(
         collection_name="knowledge_base",
-        query_vector=query_vector,
+        query=query_vector,
         limit=top_k
     )
-    return [{"text": r.payload["text"], "score": r.score} for r in results]
+    return [{"text": r.payload["text"], "score": r.score} for r in response.points]
 
 # Use in RAG pipeline
 context = retrieve("What is Python?")
@@ -334,12 +339,14 @@ client.upsert(
     ]
 )
 
-# Search specific vector
-results = client.search(
+# Search specific named vector (pass the vector name via `using`)
+response = client.query_points(
     collection_name="hybrid_search",
-    query_vector=("dense", query_dense),  # Specify which vector
+    query=query_dense,
+    using="dense",  # Specify which named vector to search
     limit=10
 )
+results = response.points
 ```
 
 ### Sparse vectors (BM25, SPLADE)
@@ -380,12 +387,13 @@ client.create_collection(
 )
 
 # Search with rescoring
-results = client.search(
+response = client.query_points(
     collection_name="quantized",
-    query_vector=query,
+    query=query,
     search_params={"quantization": {"rescore": True}},  # Rescore top results
     limit=10
 )
+results = response.points
 ```
 
 ## Payload indexing
@@ -493,5 +501,5 @@ client = QdrantClient(
 - **Docs**: https://qdrant.tech/documentation/
 - **Python Client**: https://github.com/qdrant/qdrant-client
 - **Cloud**: https://cloud.qdrant.io
-- **Version**: 1.12.0+
+- **Version**: 1.14.0+
 - **License**: Apache 2.0
diff --git a/optional-skills/mlops/saelens/SKILL.md b/optional-skills/mlops/saelens/SKILL.md
index 3a34f352ab1..813e5b3d58b 100644
--- a/optional-skills/mlops/saelens/SKILL.md
+++ b/optional-skills/mlops/saelens/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: sparse-autoencoder-training
-description: Provides guidance for training and analyzing Sparse Autoencoders (SAEs) using SAELens to decompose neural network activations into interpretable features. Use when discovering interpretable features, analyzing superposition, or studying monosemantic representations in language models.
-version: 1.0.0
+description: Train sparse autoencoders to interpret model features.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [sae-lens>=6.0.0, transformer-lens>=2.0.0, torch>=2.0.0]
@@ -78,11 +78,14 @@ from sae_lens import SAE
 
 # 1. Load model and pre-trained SAE
 model = HookedTransformer.from_pretrained("gpt2-small", device="cuda")
-sae, cfg_dict, sparsity = SAE.from_pretrained(
+# In sae-lens v6, SAE.from_pretrained() returns JUST the SAE (not a tuple).
+sae = SAE.from_pretrained(
     release="gpt2-small-res-jb",
     sae_id="blocks.8.hook_resid_pre",
     device="cuda"
 )
+# If you also need the cfg dict and feature sparsity, use:
+# sae, cfg_dict, sparsity = SAE.from_pretrained_with_cfg_and_sparsity(...)
 
 # 2. Get model activations
 tokens = model.to_tokens("The capital of France is Paris")
@@ -124,24 +127,33 @@ reconstruction_error = (activations - reconstructed).norm()
 ### Step-by-Step
 
 ```python
-from sae_lens import SAE, LanguageModelSAERunnerConfig, SAETrainingRunner
+from sae_lens import (
+    LanguageModelSAETrainingRunner,
+    LanguageModelSAERunnerConfig,
+    StandardTrainingSAEConfig,
+    LoggingConfig,
+)
 
-# 1. Configure training
+# 1. Configure training (v6 uses a NESTED config: SAE-specific options live in a
+#    `sae=` sub-config, and logging options live in a `logger=` sub-config).
+#    Note: `architecture`, `d_sae`, `l1_coefficient` etc. are now on the SAE sub-config,
+#    and legacy flat options like `hook_layer`, `activation_fn`, `log_to_wandb` were removed.
 cfg = LanguageModelSAERunnerConfig(
-    # Model
-    model_name="gpt2-small",
-    hook_name="blocks.8.hook_resid_pre",
-    hook_layer=8,
-    d_in=768,  # Model dimension
+    # SAE architecture + sparsity (nested)
+    sae=StandardTrainingSAEConfig(
+        d_in=768,          # Model dimension
+        d_sae=768 * 8,     # Expansion factor of 8
+        l1_coefficient=8e-5,  # Sparsity penalty
+        apply_b_dec_to_input=True,
+        normalize_activations="expected_average_only_in",
+    ),
 
-    # SAE architecture
-    architecture="standard",  # or "gated", "topk"
-    d_sae=768 * 8,  # Expansion factor of 8
-    activation_fn="relu",
+    # Data-generating function (model + hook point)
+    model_name="gpt2-small",
+    hook_name="blocks.8.hook_resid_pre",  # layer is inferred from hook_name (no hook_layer)
 
     # Training
     lr=4e-4,
-    l1_coefficient=8e-5,  # Sparsity penalty
     l1_warm_up_steps=1000,
     train_batch_size_tokens=4096,
     training_tokens=100_000_000,
@@ -150,9 +162,11 @@ cfg = LanguageModelSAERunnerConfig(
     dataset_path="monology/pile-uncopyrighted",
     context_size=128,
 
-    # Logging
-    log_to_wandb=True,
-    wandb_project="sae-training",
+    # Logging (nested)
+    logger=LoggingConfig(
+        log_to_wandb=True,
+        wandb_project="sae-training",
+    ),
 
     # Checkpointing
     checkpoint_path="checkpoints",
@@ -160,7 +174,7 @@ cfg = LanguageModelSAERunnerConfig(
 )
 
 # 2. Train
-trainer = SAETrainingRunner(cfg)
+trainer = LanguageModelSAETrainingRunner(cfg)  # SAETrainingRunner still works as an alias
 sae = trainer.run()
 
 # 3. Evaluate
@@ -168,6 +182,12 @@ print(f"L0 (avg active features): {trainer.metrics['l0']}")
 print(f"CE Loss Recovered: {trainer.metrics['ce_loss_score']}")
 ```
 
+> **v6 migration note:** For other SAE types swap the `sae=` sub-config —
+> `GatedTrainingSAEConfig`, `TopKTrainingSAEConfig` (set `k` directly), or
+> `JumpReLUTrainingSAEConfig` (uses `l0_coefficient`). Legacy flat options
+> (`architecture`, `expansion_factor`, `hook_layer`, `activation_fn`/`activation_fn_kwargs`,
+> `use_ghost_grads`, ghost grads, b_dec/decoder init options) were removed in v6.
+
 ### Key Hyperparameters
 
 | Parameter | Typical Value | Effect |
@@ -205,7 +225,7 @@ from sae_lens import SAE
 import torch
 
 model = HookedTransformer.from_pretrained("gpt2-small", device="cuda")
-sae, _, _ = SAE.from_pretrained(
+sae = SAE.from_pretrained(  # v6 returns just the SAE
     release="gpt2-small-res-jb",
     sae_id="blocks.8.hook_resid_pre",
     device="cuda"
@@ -279,47 +299,57 @@ for idx, val in zip(top_features.indices, top_features.values):
 
 ## Common Issues & Solutions
 
+> All examples below use the v6 nested config: SAE-specific options go in the `sae=`
+> sub-config (`StandardTrainingSAEConfig` / `TopKTrainingSAEConfig` / etc.), training
+> knobs stay on the top-level `LanguageModelSAERunnerConfig`.
+
 ### Issue: High dead feature ratio
 ```python
-# WRONG: No warm-up, features die early
+from sae_lens import LanguageModelSAERunnerConfig, StandardTrainingSAEConfig
+
+# WRONG: no warm-up, features die early
 cfg = LanguageModelSAERunnerConfig(
-    l1_coefficient=1e-4,
+    sae=StandardTrainingSAEConfig(d_in=768, d_sae=768*8, l1_coefficient=1e-4),
     l1_warm_up_steps=0,  # Bad!
 )
 
-# RIGHT: Warm-up L1 penalty
+# RIGHT: warm up the L1 penalty (v6 removed ghost grads; warm-up is the lever now)
 cfg = LanguageModelSAERunnerConfig(
-    l1_coefficient=8e-5,
+    sae=StandardTrainingSAEConfig(d_in=768, d_sae=768*8, l1_coefficient=8e-5),
     l1_warm_up_steps=1000,  # Gradually increase
-    use_ghost_grads=True,   # Revive dead features
 )
 ```
 
 ### Issue: Poor reconstruction (low CE recovery)
 ```python
-# Reduce sparsity penalty
+# Reduce sparsity penalty and/or add capacity (both on the SAE sub-config)
 cfg = LanguageModelSAERunnerConfig(
-    l1_coefficient=5e-5,  # Lower = better reconstruction
-    d_sae=768 * 16,       # More capacity
+    sae=StandardTrainingSAEConfig(
+        d_in=768,
+        d_sae=768 * 16,       # More capacity
+        l1_coefficient=5e-5,  # Lower = better reconstruction
+    ),
 )
 ```
 
 ### Issue: Features not interpretable
 ```python
+from sae_lens import LanguageModelSAERunnerConfig, StandardTrainingSAEConfig, TopKTrainingSAEConfig
+
 # Increase sparsity (higher L1)
 cfg = LanguageModelSAERunnerConfig(
-    l1_coefficient=1e-4,  # Higher = sparser, more interpretable
+    sae=StandardTrainingSAEConfig(d_in=768, d_sae=768*8, l1_coefficient=1e-4),
 )
-# Or use TopK architecture
+# Or use a TopK SAE (k is set directly in v6, not via activation_fn_kwargs)
 cfg = LanguageModelSAERunnerConfig(
-    architecture="topk",
-    activation_fn_kwargs={"k": 50},  # Exactly 50 active features
+    sae=TopKTrainingSAEConfig(d_in=768, d_sae=768*8, k=50),  # Exactly 50 active features
 )
 ```
 
 ### Issue: Memory errors during training
 ```python
 cfg = LanguageModelSAERunnerConfig(
+    sae=StandardTrainingSAEConfig(d_in=768, d_sae=768*8, l1_coefficient=8e-5),
     train_batch_size_tokens=2048,  # Reduce batch size
     store_batch_size_prompts=4,    # Fewer prompts in buffer
     n_batches_in_buffer=8,         # Smaller activation buffer
@@ -341,8 +371,10 @@ Browse pre-trained SAE features at [neuronpedia.org](https://neuronpedia.org):
 | Class | Purpose |
 |-------|---------|
 | `SAE` | Sparse Autoencoder model |
-| `LanguageModelSAERunnerConfig` | Training configuration |
-| `SAETrainingRunner` | Training loop manager |
+| `LanguageModelSAERunnerConfig` | Top-level training configuration (nests `sae=` and `logger=`) |
+| `StandardTrainingSAEConfig` / `TopKTrainingSAEConfig` / `GatedTrainingSAEConfig` / `JumpReLUTrainingSAEConfig` | SAE-type-specific sub-configs (v6) |
+| `LoggingConfig` | Logging/W&B sub-config (v6) |
+| `LanguageModelSAETrainingRunner` | Training loop manager (alias: `SAETrainingRunner`) |
 | `ActivationsStore` | Activation collection and batching |
 | `HookedSAETransformer` | TransformerLens + SAE integration |
 
@@ -381,10 +413,10 @@ For detailed API documentation, tutorials, and advanced usage, see the `referenc
 | **TopK** | Exactly K active features | Consistent sparsity |
 
 ```python
-# TopK SAE (exactly 50 features active)
+from sae_lens import LanguageModelSAERunnerConfig, TopKTrainingSAEConfig
+
+# TopK SAE (exactly 50 features active) — `k` is set on the SAE sub-config in v6
 cfg = LanguageModelSAERunnerConfig(
-    architecture="topk",
-    activation_fn="topk",
-    activation_fn_kwargs={"k": 50},
+    sae=TopKTrainingSAEConfig(d_in=768, d_sae=768*8, k=50),
 )
 ```
diff --git a/optional-skills/mlops/simpo/SKILL.md b/optional-skills/mlops/simpo/SKILL.md
index 811a01a2a75..32e00f6569d 100644
--- a/optional-skills/mlops/simpo/SKILL.md
+++ b/optional-skills/mlops/simpo/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: simpo-training
-description: Simple Preference Optimization for LLM alignment. Reference-free alternative to DPO with better performance (+6.4 points on AlpacaEval 2.0). No reference model needed, more efficient than DPO. Use for preference alignment when want simpler, faster training than DPO/PPO.
+description: Reference-free preference alignment, simpler than DPO.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/slime/SKILL.md b/optional-skills/mlops/slime/SKILL.md
index 62fdc5b1982..b851cfd55bc 100644
--- a/optional-skills/mlops/slime/SKILL.md
+++ b/optional-skills/mlops/slime/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: slime-rl-training
-description: Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework. Use when training GLM models, implementing custom data generation workflows, or needing tight Megatron-LM integration for RL scaling.
+description: RL post-training for LLMs with Megatron and SGLang.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/stable-diffusion/SKILL.md b/optional-skills/mlops/stable-diffusion/SKILL.md
index 84243bc802c..4c84733e90b 100644
--- a/optional-skills/mlops/stable-diffusion/SKILL.md
+++ b/optional-skills/mlops/stable-diffusion/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: stable-diffusion-image-generation
-description: State-of-the-art text-to-image generation with Stable Diffusion models via HuggingFace Diffusers. Use when generating images from text prompts, performing image-to-image translation, inpainting, or building custom diffusion pipelines.
+description: Text-to-image generation, inpainting, and img2img.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/mlops/tensorrt-llm/SKILL.md b/optional-skills/mlops/tensorrt-llm/SKILL.md
index c5a90ee0e88..c5785c64dcf 100644
--- a/optional-skills/mlops/tensorrt-llm/SKILL.md
+++ b/optional-skills/mlops/tensorrt-llm/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: tensorrt-llm
-description: Optimizes LLM inference with NVIDIA TensorRT for maximum throughput and lowest latency. Use for production deployment on NVIDIA GPUs (A100/H100), when you need 10-100x faster inference than PyTorch, or for serving models with quantization (FP8/INT4), in-flight batching, and multi-GPU scaling.
-version: 1.0.0
+description: High-throughput LLM inference on NVIDIA GPUs.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [tensorrt-llm, torch]
@@ -40,13 +40,15 @@ NVIDIA's open-source library for optimizing LLM inference with state-of-the-art
 ### Installation
 
 ```bash
-# Docker (recommended)
-docker pull nvidia/tensorrt_llm:latest
+# Docker (recommended) — images are on NGC (nvcr.io), not Docker Hub.
+# Replace x.y.z with the desired version (e.g. 1.2.1). Browse tags on NGC:
+# https://catalog.ngc.nvidia.com/orgs/nvidia/teams/tensorrt-llm/containers/release/tags
+docker pull nvcr.io/nvidia/tensorrt-llm/release:x.y.z
 
-# pip install
-pip install tensorrt_llm==1.2.0rc3
+# pip install (current stable GA)
+pip install tensorrt_llm
 
-# Requires CUDA 13.0.0, TensorRT 10.13.2, Python 3.10-3.12
+# Requires CUDA 13.2.1, TensorRT 10.x, Python 3.10-3.12
 ```
 
 ### Basic inference
diff --git a/optional-skills/mlops/torchtitan/SKILL.md b/optional-skills/mlops/torchtitan/SKILL.md
index 97dc925fc10..26fb68b9584 100644
--- a/optional-skills/mlops/torchtitan/SKILL.md
+++ b/optional-skills/mlops/torchtitan/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: distributed-llm-pretraining-torchtitan
-description: Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP). Use when pretraining Llama 3.1, DeepSeek V3, or custom models at scale from 8 to 512+ GPUs with Float8, torch.compile, and distributed checkpointing.
-version: 1.0.0
+description: Pretrain LLMs at scale with PyTorch 4D parallelism.
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [torch>=2.6.0, torchtitan>=0.2.0, torchao>=0.5.0]
@@ -37,7 +37,9 @@ python scripts/download_hf_assets.py --repo_id meta-llama/Llama-3.1-8B --assets
 
 **Start training on 8 GPUs**:
 ```bash
-CONFIG_FILE="./torchtitan/models/llama3/train_configs/llama3_8b.toml" ./run_train.sh
+# Configs are selected by name from the Python config registry
+# (torchtitan/models/llama3/config_registry.py), not by TOML path
+MODULE=llama3 CONFIG=llama3_8b ./run_train.sh
 ```
 
 ## Common workflows
@@ -65,10 +67,16 @@ python scripts/download_hf_assets.py \
 
 **Step 2: Configure training**
 
-Edit or create a TOML config file:
+In torchtitan's current layout, run configs are defined in a Python **config registry**
+(`torchtitan/models/llama3/config_registry.py`) and selected by name via `CONFIG=<name>`
+(or `--config <name>`). To customize, register your own config in the registry, or override
+individual fields on the command line (e.g. `--optimizer.lr 3e-4 --training.steps 1000`).
+
+The equivalent settings for an 8B run look like this (shown as fields; set them in the
+registry entry or as `--section.key value` overrides):
 
 ```toml
-# llama3_8b_custom.toml
+# fields for a llama3 8B run (register in config_registry.py or pass as --overrides)
 [job]
 dump_folder = "./outputs"
 description = "Llama 3.1 8B training"
@@ -108,13 +116,16 @@ interval = 500
 **Step 3: Launch training**
 
 ```bash
-# 8 GPUs on single node
-CONFIG_FILE="./llama3_8b_custom.toml" ./run_train.sh
+# 8 GPUs on single node (config selected by name from the registry)
+MODULE=llama3 CONFIG=llama3_8b ./run_train.sh
 
-# Or explicitly with torchrun
+# Override individual fields on the command line
+MODULE=llama3 CONFIG=llama3_8b ./run_train.sh --optimizer.lr 3e-4 --training.steps 1000
+
+# Or explicitly with torchrun (run_train.sh wraps this)
 torchrun --nproc_per_node=8 \
   -m torchtitan.train \
-  --job.config_file ./llama3_8b_custom.toml
+  --module llama3 --config llama3_8b
 ```
 
 **Step 4: Monitor and checkpoint**
@@ -160,7 +171,7 @@ srun torchrun \
   --rdzv_backend=c10d \
   --rdzv_endpoint=$MASTER_ADDR:$MASTER_PORT \
   -m torchtitan.train \
-  --job.config_file ./llama3_70b.toml
+  --module llama3 --config llama3_70b
 ```
 
 **Step 3: Submit job**
@@ -192,16 +203,28 @@ USE_CPP=0 pip install git+https://github.com/pytorch/ao.git
 
 **Step 2: Configure Float8**
 
-Add to your TOML config:
+In the current torchtitan, Float8 is applied at config time via the `quantization`
+parameter in your `model_registry()` call inside the config registry (not via a
+`[quantize.linear.float8]` TOML section). Add a `Float8LinearConverter.Config`:
+
+```python
+# in torchtitan/models/llama3/config_registry.py (your model_registry(...) call)
+from torchtitan.components.quantization import Float8LinearConverter
+
+model_spec = model_registry(
+    "8B",
+    quantization=[
+        Float8LinearConverter.Config(
+            recipe_name="rowwise",          # or "rowwise_with_gw_hp"
+            filter_fqns=["output"],          # skip layers too small to benefit
+            model_compile_enabled=True,      # requires torch.compile for competitive perf
+        ),
+    ],
+)
+```
+
+Enable `torch.compile` in your run config too:
 ```toml
-[model]
-converters = ["quantize.linear.float8"]
-
-[quantize.linear.float8]
-enable_fsdp_float8_all_gather = true
-precompute_float8_dynamic_scale_for_fsdp = true
-filter_fqns = ["output"]  # Exclude output layer
-
 [compile]
 enable = true
 components = ["model", "loss"]
@@ -210,10 +233,8 @@ components = ["model", "loss"]
 **Step 3: Launch with compile**
 
 ```bash
-CONFIG_FILE="./llama3_8b.toml" ./run_train.sh \
-  --model.converters="quantize.linear.float8" \
-  --quantize.linear.float8.enable_fsdp_float8_all_gather \
-  --compile.enable
+# Float8 config is baked into the registered config; just select it and enable compile
+MODULE=llama3 CONFIG=llama3_8b ./run_train.sh --compile.enable
 ```
 
 ### Workflow 4: 4D parallelism for 405B models
@@ -229,7 +250,7 @@ CONFIG_FILE="./llama3_8b.toml" ./run_train.sh \
 
 Required for consistent initialization across PP stages:
 ```bash
-NGPU=1 CONFIG_FILE=./llama3_405b.toml ./run_train.sh \
+NGPU=1 MODULE=llama3 CONFIG=llama3_405b ./run_train.sh \
   --checkpoint.enable \
   --checkpoint.create_seed_checkpoint \
   --parallelism.data_parallel_shard_degree 1 \
@@ -257,7 +278,7 @@ seq_len = 8192
 # 64 nodes x 8 GPUs = 512 GPUs
 srun torchrun --nnodes=64 --nproc_per_node=8 \
   -m torchtitan.train \
-  --job.config_file ./llama3_405b.toml
+  --module llama3 --config llama3_405b
 ```
 
 ## When to use vs alternatives
@@ -304,10 +325,15 @@ export TORCH_NCCL_AVOID_RECORD_STREAMS=1
 
 **Issue: Float8 training not faster**
 
-Float8 only benefits large GEMMs. Filter small layers:
-```toml
-[quantize.linear.float8]
-filter_fqns = ["attention.wk", "attention.wv", "output", "auto_filter_small_kn"]
+Float8 only benefits large GEMMs. Filter small layers via the converter's `filter_fqns`:
+```python
+from torchtitan.components.quantization import Float8LinearConverter
+
+Float8LinearConverter.Config(
+    # add "auto_filter_small_kn" to auto-skip layers too small to benefit
+    filter_fqns=["attention.wk", "attention.wv", "output", "auto_filter_small_kn"],
+    model_compile_enabled=True,
+)
 ```
 
 **Issue: Checkpoint loading fails after parallelism change**
diff --git a/optional-skills/mlops/training/trl-fine-tuning/SKILL.md b/optional-skills/mlops/training/trl-fine-tuning/SKILL.md
index 1fc6f6ccf58..8cc5ee99169 100644
--- a/optional-skills/mlops/training/trl-fine-tuning/SKILL.md
+++ b/optional-skills/mlops/training/trl-fine-tuning/SKILL.md
@@ -1,14 +1,14 @@
 ---
 name: fine-tuning-with-trl
-description: "TRL: SFT, DPO, PPO, GRPO, reward modeling for LLM RLHF."
-version: 1.0.0
+description: "TRL: SFT, DPO, GRPO, RLOO reward modeling for LLM RLHF."
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [trl, transformers, datasets, peft, accelerate, torch]
 platforms: [linux, macos, windows]
 metadata:
   hermes:
-    tags: [Post-Training, TRL, Reinforcement Learning, Fine-Tuning, SFT, DPO, PPO, GRPO, RLHF, Preference Alignment, HuggingFace]
+    tags: [Post-Training, TRL, Reinforcement Learning, Fine-Tuning, SFT, DPO, GRPO, RLOO, RLHF, Preference Alignment, HuggingFace]
 
 ---
 
@@ -50,17 +50,23 @@ trainer.train()
 
 ## Common workflows
 
-### Workflow 1: Full RLHF pipeline (SFT → Reward Model → PPO)
+### Workflow 1: Full RLHF pipeline (SFT → Reward Model → RLOO)
 
 Complete pipeline from base model to human-aligned model.
 
+> **Note (TRL 1.x):** PPO has been **removed** from TRL — `PPOTrainer`, `PPOConfig`, and
+> `python -m trl.scripts.ppo` no longer exist. Use an online-RL trainer TRL still ships:
+> **RLOO** (`RLOOTrainer` / `trl rloo`) is the closest drop-in for a reward-model-driven
+> RLHF pipeline, and **GRPO** (`GRPOTrainer` / `trl grpo`, see Workflow 3) is the
+> memory-efficient alternative. The step below uses RLOO.
+
 Copy this checklist:
 
 ```
 RLHF Training:
 - [ ] Step 1: Supervised fine-tuning (SFT)
 - [ ] Step 2: Train reward model
-- [ ] Step 3: PPO reinforcement learning
+- [ ] Step 3: RLOO reinforcement learning
 - [ ] Step 4: Evaluate aligned model
 ```
 
@@ -95,7 +101,7 @@ trainer = SFTTrainer(
     model=model,
     args=training_args,
     train_dataset=dataset,
-    tokenizer=tokenizer
+    processing_class=tokenizer
 )
 trainer.train()
 trainer.save_model()
@@ -138,19 +144,46 @@ trainer.train()
 trainer.save_model()
 ```
 
-**Step 3: PPO reinforcement learning**
+**Step 3: RLOO reinforcement learning**
 
-Optimize policy using reward model:
+Optimize policy using the reward model. PPO was removed in TRL 1.x; use the RLOO CLI
+(`trl rloo`) with the trained reward model passed via `--reward_model_name_or_path`:
 
 ```bash
-python -m trl.scripts.ppo \
+trl rloo \
     --model_name_or_path Qwen2.5-0.5B-SFT \
-    --reward_model_path Qwen2.5-0.5B-Reward \
+    --reward_model_name_or_path Qwen2.5-0.5B-Reward \
     --dataset_name trl-internal-testing/descriptiveness-sentiment-trl-style \
-    --output_dir Qwen2.5-0.5B-PPO \
+    --output_dir Qwen2.5-0.5B-RLOO \
     --learning_rate 3e-6 \
     --per_device_train_batch_size 64 \
-    --total_episodes 10000
+    --num_generations 4
+```
+
+Equivalent Python (`RLOOTrainer` / `RLOOConfig`):
+```python
+from trl import RLOOTrainer, RLOOConfig
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+reward_model = AutoModelForSequenceClassification.from_pretrained(
+    "Qwen2.5-0.5B-Reward", num_labels=1
+)
+
+config = RLOOConfig(
+    output_dir="Qwen2.5-0.5B-RLOO",
+    per_device_train_batch_size=64,
+    learning_rate=3e-6,
+    num_generations=4,
+)
+
+trainer = RLOOTrainer(
+    model="Qwen2.5-0.5B-SFT",
+    reward_funcs=reward_model,   # a reward model (or a callable reward function)
+    args=config,
+    train_dataset=dataset,       # prompt-only dataset
+    processing_class=tokenizer,
+)
+trainer.train()
 ```
 
 **Step 4: Evaluate**
@@ -159,7 +192,7 @@ python -m trl.scripts.ppo \
 from transformers import pipeline
 
 # Load aligned model
-generator = pipeline("text-generation", model="Qwen2.5-0.5B-PPO")
+generator = pipeline("text-generation", model="Qwen2.5-0.5B-RLOO")
 
 # Test
 prompt = "Explain quantum computing to a 10-year-old"
@@ -348,15 +381,15 @@ trl grpo \
 **Use TRL when:**
 - Need to align model with human preferences
 - Have preference data (chosen/rejected pairs)
-- Want to use reinforcement learning (PPO, GRPO)
+- Want to use reinforcement learning (RLOO, GRPO)
 - Need reward model training
 - Doing RLHF (full pipeline)
 
 **Method selection**:
 - **SFT**: Have prompt-completion pairs, want basic instruction following
 - **DPO**: Have preferences, want simple alignment (no reward model needed)
-- **PPO**: Have reward model, need maximum control over RL
-- **GRPO**: Memory-constrained, want online RL
+- **RLOO**: Have a reward model, want online RL (the reward-model-driven RLHF path; PPO was removed in TRL 1.x)
+- **GRPO**: Memory-constrained, want online RL with reward functions
 - **Reward Model**: Building RLHF pipeline, need to score generations
 
 **Use alternatives instead:**
@@ -411,13 +444,15 @@ print(dataset[0])
 # Should have clear chosen > rejected
 ```
 
-**Issue: PPO training unstable**
+**Issue: Online RL (RLOO/GRPO) training unstable**
 
-Adjust KL coefficient:
+Adjust the KL/beta regularization toward the reference policy:
 ```python
-config = PPOConfig(
-    kl_coef=0.1,  # Increase from 0.05
-    cliprange=0.1  # Reduce from 0.2
+from trl import RLOOConfig
+
+config = RLOOConfig(
+    beta=0.05,          # KL coefficient toward the reference model (increase for stability)
+    num_generations=4,  # more samples per prompt = lower-variance advantage estimates
 )
 ```
 
@@ -439,7 +474,7 @@ config = PPOConfig(
 - **VRAM**: Depends on model and method
   - SFT 7B: 16GB (with LoRA)
   - DPO 7B: 24GB (stores reference model)
-  - PPO 7B: 40GB (policy + reward model)
+  - RLOO 7B: 40GB (policy + reward model)
   - GRPO 7B: 24GB (more memory efficient)
 - **Multi-GPU**: Supported via `accelerate`
 - **Mixed precision**: BF16 recommended (A100/H100)
diff --git a/optional-skills/mlops/whisper/SKILL.md b/optional-skills/mlops/whisper/SKILL.md
index b4ab88fdf4c..e5d1da634d7 100644
--- a/optional-skills/mlops/whisper/SKILL.md
+++ b/optional-skills/mlops/whisper/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: whisper
-description: OpenAI's general-purpose speech recognition model. Supports 99 languages, transcription, translation to English, and language identification. Six model sizes from tiny (39M params) to large (1550M params). Use for speech-to-text, podcast transcription, or multilingual audio processing. Best for robust, multilingual ASR.
+description: Transcribe and translate speech in 99 languages.
 version: 1.0.0
 author: Orchestra Research
 license: MIT
diff --git a/optional-skills/productivity/canvas/SKILL.md b/optional-skills/productivity/canvas/SKILL.md
index 68d6402e554..5e5e3dabf79 100644
--- a/optional-skills/productivity/canvas/SKILL.md
+++ b/optional-skills/productivity/canvas/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: canvas
-description: Canvas LMS integration — fetch enrolled courses and assignments using API token authentication.
+description: Fetch Canvas LMS courses and assignments via API token.
 version: 1.0.0
 author: community
 license: MIT
diff --git a/optional-skills/productivity/here-now/SKILL.md b/optional-skills/productivity/here-now/SKILL.md
index bbb07b0a4e5..20f56957456 100644
--- a/optional-skills/productivity/here-now/SKILL.md
+++ b/optional-skills/productivity/here-now/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: here.now
-description: Publish static sites to {slug}.here.now and store private files in cloud Drives for agent-to-agent handoff.
+description: Publish sites to {slug}.here.now and store files in Drives.
 version: 1.15.3
 author: here.now
 license: MIT
diff --git a/optional-skills/productivity/shopify/SKILL.md b/optional-skills/productivity/shopify/SKILL.md
index 4dc8dc93ad8..eae4d17d975 100644
--- a/optional-skills/productivity/shopify/SKILL.md
+++ b/optional-skills/productivity/shopify/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: shopify
-description: Shopify Admin & Storefront GraphQL APIs via curl. Products, orders, customers, inventory, metafields.
+description: Query Shopify Admin/Storefront GraphQL APIs via curl.
 version: 1.0.0
 author: community
 license: MIT
diff --git a/optional-skills/productivity/siyuan/SKILL.md b/optional-skills/productivity/siyuan/SKILL.md
index 3f199776438..99fce75fa98 100644
--- a/optional-skills/productivity/siyuan/SKILL.md
+++ b/optional-skills/productivity/siyuan/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: siyuan
-description: SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.
+description: Query and edit a SiYuan knowledge base via its API.
 version: 1.0.0
 author: FEUAZUR
 license: MIT
diff --git a/optional-skills/productivity/telephony/SKILL.md b/optional-skills/productivity/telephony/SKILL.md
index f0d28614912..23d4a6b593f 100644
--- a/optional-skills/productivity/telephony/SKILL.md
+++ b/optional-skills/productivity/telephony/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: telephony
-description: Give Hermes phone capabilities without core tool changes. Provision and persist a Twilio number, send and receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi.
+description: Provision Twilio numbers, SMS/MMS, and AI outbound calls.
 version: 1.0.0
 author: Nous Research
 license: MIT
diff --git a/optional-skills/research/bioinformatics/SKILL.md b/optional-skills/research/bioinformatics/SKILL.md
index 714ba1b80ff..91da7ee8a99 100644
--- a/optional-skills/research/bioinformatics/SKILL.md
+++ b/optional-skills/research/bioinformatics/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: bioinformatics
-description: Gateway to 400+ bioinformatics skills from bioSkills and ClawBio. Covers genomics, transcriptomics, single-cell, variant calling, pharmacogenomics, metagenomics, structural biology, and more. Fetches domain-specific reference material on demand.
+description: Gateway to 400+ genomics and computational biology skills.
 version: 1.0.0
 platforms: [linux, macos]
 metadata:
diff --git a/optional-skills/research/darwinian-evolver/SKILL.md b/optional-skills/research/darwinian-evolver/SKILL.md
index 272f6702481..3bac112376a 100644
--- a/optional-skills/research/darwinian-evolver/SKILL.md
+++ b/optional-skills/research/darwinian-evolver/SKILL.md
@@ -8,7 +8,7 @@ platforms: [linux, macos]
 metadata:
   hermes:
     tags: [evolution, optimization, prompt-engineering, research]
-    related_skills: [arxiv, jupyter-live-kernel]
+    related_skills: [arxiv, jupyter-notebook]
 ---
 
 # Darwinian Evolver
diff --git a/optional-skills/research/domain-intel/SKILL.md b/optional-skills/research/domain-intel/SKILL.md
index 0c55c5c44d4..9f935348de0 100644
--- a/optional-skills/research/domain-intel/SKILL.md
+++ b/optional-skills/research/domain-intel/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: domain-intel
-description: Passive domain reconnaissance using Python stdlib. Subdomain discovery, SSL certificate inspection, WHOIS lookups, DNS records, domain availability checks, and bulk multi-domain analysis. No API keys required.
+description: Passive recon of subdomains, SSL certs, WHOIS, and DNS.
 platforms: [linux, macos, windows]
 ---
 
diff --git a/optional-skills/research/duckduckgo-search/SKILL.md b/optional-skills/research/duckduckgo-search/SKILL.md
index 83b14d95150..05f2aff5fdb 100644
--- a/optional-skills/research/duckduckgo-search/SKILL.md
+++ b/optional-skills/research/duckduckgo-search/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: duckduckgo-search
-description: Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Prefer the `ddgs` CLI when installed; use the Python DDGS library only after verifying that `ddgs` is available in the current runtime.
+description: Free keyless web, news, and image search via ddgs.
 version: 1.3.0
 author: gamedevCloudy
 license: MIT
diff --git a/optional-skills/research/gitnexus-explorer/SKILL.md b/optional-skills/research/gitnexus-explorer/SKILL.md
index c583404efbf..ea5b12913ef 100644
--- a/optional-skills/research/gitnexus-explorer/SKILL.md
+++ b/optional-skills/research/gitnexus-explorer/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gitnexus-explorer
-description: Index a codebase with GitNexus and serve an interactive knowledge graph via web UI + Cloudflare tunnel.
+description: Serve an interactive codebase knowledge graph web UI.
 version: 1.0.0
 author: Hermes Agent + Teknium
 license: MIT
@@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [gitnexus, code-intelligence, knowledge-graph, visualization]
-    related_skills: [native-mcp, codebase-inspection]
+    related_skills: [hermes-agent, codebase-inspection]
 ---
 
 # GitNexus Explorer
diff --git a/optional-skills/research/osint-investigation/SKILL.md b/optional-skills/research/osint-investigation/SKILL.md
index b2da82fbd00..4de5fb19011 100644
--- a/optional-skills/research/osint-investigation/SKILL.md
+++ b/optional-skills/research/osint-investigation/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: osint-investigation
-description: Public-records OSINT investigation framework — SEC EDGAR filings, USAspending contracts, Senate lobbying, OFAC sanctions, ICIJ offshore leaks, NYC property records (ACRIS), OpenCorporates registries, CourtListener court records, Wayback Machine archives, Wikipedia + Wikidata, GDELT news monitoring. Entity resolution across sources, cross-link analysis, timing correlation, evidence chains. Python stdlib only.
+description: Follow the money via public records and sanctions data.
 version: 0.1.0
 platforms: [linux, macos, windows]
 author: Hermes Agent (adapted from ShinMegamiBoson/OpenPlanter, MIT)
diff --git a/optional-skills/research/osint-investigation/scripts/build_findings.py b/optional-skills/research/osint-investigation/scripts/build_findings.py
index 15021eb0878..0d8c8976088 100644
--- a/optional-skills/research/osint-investigation/scripts/build_findings.py
+++ b/optional-skills/research/osint-investigation/scripts/build_findings.py
@@ -141,7 +141,7 @@ def build_findings(
 
     # 3. Timing-based findings.
     if timing_path and Path(timing_path).exists():
-        timing = json.loads(Path(timing_path).read_text())
+        timing = json.loads(Path(timing_path).read_text(encoding="utf-8"))
         for r in timing.get("results", []):
             if not r.get("significant"):
                 continue
@@ -190,7 +190,7 @@ def build_findings(
         },
         "findings": findings,
     }
-    Path(out_path).write_text(json.dumps(payload, indent=2))
+    Path(out_path).write_text(json.dumps(payload, indent=2), encoding="utf-8")
     return payload
 
 
diff --git a/optional-skills/research/osint-investigation/scripts/timing_analysis.py b/optional-skills/research/osint-investigation/scripts/timing_analysis.py
index 9407264158d..06ef2ded1cb 100644
--- a/optional-skills/research/osint-investigation/scripts/timing_analysis.py
+++ b/optional-skills/research/osint-investigation/scripts/timing_analysis.py
@@ -198,7 +198,7 @@ def analyze(
         "results": results,
     }
 
-    Path(out_path).write_text(json.dumps(payload, indent=2))
+    Path(out_path).write_text(json.dumps(payload, indent=2), encoding="utf-8")
     return payload
 
 
diff --git a/optional-skills/research/parallel-cli/SKILL.md b/optional-skills/research/parallel-cli/SKILL.md
index d94e57f2657..45134338046 100644
--- a/optional-skills/research/parallel-cli/SKILL.md
+++ b/optional-skills/research/parallel-cli/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: parallel-cli
-description: Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring. Prefer JSON output and non-interactive flows.
+description: Agent-native web search, deep research, and enrichment.
 version: 1.1.0
 author: Hermes Agent
 license: MIT
diff --git a/optional-skills/research/pinecone-research/SKILL.md b/optional-skills/research/pinecone-research/SKILL.md
new file mode 100644
index 00000000000..8be3c285ad1
--- /dev/null
+++ b/optional-skills/research/pinecone-research/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: pinecone-research
+description: Agent RAG and long-term memory with Pinecone.
+version: 1.0.0
+author: immuhammadfurqan
+license: MIT
+dependencies: [pinecone-client, langchain-pinecone]
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [RAG, Pinecone, Memory, Research, Vector Database, Agent, Retrieval]
+
+---
+
+# Pinecone Research — Agent RAG & Long-Term Memory
+
+Use Pinecone as a retrieval-augmented generation (RAG) backend for agent
+conversations: persist embeddings, retrieve relevant context from past
+sessions, and build long-term memory.
+
+## When to use this skill
+
+**Use when:**
+- Building agent RAG pipelines with Pinecone as the vector store
+- Need persistent long-term memory across agent sessions
+- Combining retrieval with agent tool use
+- Researching or prototyping semantic search workflows
+
+**Use the mlops/pinecone skill instead when:**
+- Need a general Pinecone reference (index management, CRUD, hybrid search)
+- Working on production infrastructure without agent integration
+
+## Quick start
+
+### Setup
+
+```bash
+pip install pinecone-client langchain-pinecone langchain-openai
+```
+
+Set your API key:
+```bash
+export PINECONE_API_KEY="your-api-key"
+```
+
+### Basic RAG pipeline
+
+```python
+from pinecone import Pinecone, ServerlessSpec
+from langchain_pinecone import PineconeVectorStore
+from langchain_openai import OpenAIEmbeddings
+
+# Initialize Pinecone
+pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
+
+# Create or connect to index
+index_name = "agent-memory"
+if index_name not in [i.name for i in pc.list_indexes()]:
+    pc.create_index(
+        name=index_name,
+        dimension=1536,
+        metric="cosine",
+        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+    )
+
+# Build vector store
+vectorstore = PineconeVectorStore.from_documents(
+    documents=docs,
+    embedding=OpenAIEmbeddings(),
+    index_name=index_name,
+)
+
+# Retrieve relevant context
+retriever = vectorstore.as_retriever(search_kwargs={"k": 5})
+results = retriever.invoke("What did the agent discuss yesterday?")
+```
+
+### Namespace-based session memory
+
+```python
+# Store per-session memory
+vectorstore = PineconeVectorStore(
+    index=pc.Index(index_name),
+    embedding=OpenAIEmbeddings(),
+    namespace=f"session-{session_id}",
+)
+
+# Query across all sessions (no namespace filter)
+all_memory = PineconeVectorStore(
+    index=pc.Index(index_name),
+    embedding=OpenAIEmbeddings(),
+)
+results = all_memory.similarity_search("relevant query", k=10)
+```
+
+## Best practices
+
+1. **Namespace by session or user** — isolate data for multi-tenant agents
+2. **Batch upserts** — 100–200 vectors per batch for efficiency
+3. **Metadata filtering** — tag vectors with session ID, timestamp, topic
+4. **Prune old memory** — delete stale namespaces to control costs
+5. **Use serverless** — auto-scaling, pay-per-use pricing
+
+## Resources
+
+- **Pinecone Docs**: https://docs.pinecone.io
+- **LangChain Integration**: https://python.langchain.com/docs/integrations/vectorstores/pinecone
+- **Free Tier**: 1 index, 100K vectors (1536 dimensions)
diff --git a/optional-skills/research/pinecone-research/scripts/memory_manager.py b/optional-skills/research/pinecone-research/scripts/memory_manager.py
new file mode 100644
index 00000000000..ba490133f86
--- /dev/null
+++ b/optional-skills/research/pinecone-research/scripts/memory_manager.py
@@ -0,0 +1,155 @@
+"""Pinecone memory manager — namespace-based session memory for agents.
+
+Provides helpers for storing and retrieving agent conversation memory
+using Pinecone namespaces. Each session gets its own namespace for isolation,
+with cross-session search available via the global namespace.
+
+Usage:
+    export PINECONE_API_KEY="your-key"
+    export OPENAI_API_KEY="your-key"
+    python memory_manager.py --index-name agent-memory --action store \
+        --session-id sess-001 --text "User discussed project architecture"
+    python memory_manager.py --index-name agent-memory --action recall \
+        --query "architecture decisions"
+    python memory_manager.py --index-name agent-memory --action cleanup \
+        --session-id sess-001
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import sys
+import time
+
+
+def get_pinecone_client():
+    """Initialize Pinecone client from environment."""
+    try:
+        from pinecone import Pinecone
+    except ImportError:
+        print("Error: pinecone-client not installed. Run: pip install pinecone-client", file=sys.stderr)
+        sys.exit(1)
+
+    api_key = os.environ.get("PINECONE_API_KEY")
+    if not api_key:
+        print("Error: PINECONE_API_KEY environment variable not set.", file=sys.stderr)
+        sys.exit(1)
+
+    return Pinecone(api_key=api_key)
+
+
+def get_embeddings():
+    """Get the embedding model."""
+    try:
+        from langchain_openai import OpenAIEmbeddings
+    except ImportError:
+        print("Error: langchain-openai not installed. Run: pip install langchain-openai", file=sys.stderr)
+        sys.exit(1)
+    return OpenAIEmbeddings()
+
+
+def store_memory(index, session_id: str, text: str, metadata: dict | None = None):
+    """Store a memory entry in the session namespace."""
+    embeddings = get_embeddings()
+    vector = embeddings.embed_query(text)
+
+    doc_id = hashlib.sha256(f"{session_id}:{text}:{time.time()}".encode()).hexdigest()[:16]
+    entry_metadata = {
+        "text": text[:1000],
+        "session_id": session_id,
+        "timestamp": int(time.time()),
+    }
+    if metadata:
+        entry_metadata.update(metadata)
+
+    index.upsert(
+        vectors=[{"id": doc_id, "values": vector, "metadata": entry_metadata}],
+        namespace=session_id,
+    )
+    print(f"Stored memory [{doc_id}] in namespace '{session_id}'")
+    return doc_id
+
+
+def recall_memories(index, query: str, session_id: str | None = None, top_k: int = 5):
+    """Recall memories matching a query, optionally scoped to a session."""
+    embeddings = get_embeddings()
+    query_vector = embeddings.embed_query(query)
+
+    kwargs = {"vector": query_vector, "top_k": top_k, "include_metadata": True}
+    if session_id:
+        kwargs["namespace"] = session_id
+
+    results = index.query(**kwargs)
+
+    print(f"\nRecalling memories for: {query!r}")
+    if session_id:
+        print(f"Scoped to session: {session_id}")
+    print(f"Found {len(results['matches'])} results:\n")
+
+    for match in results["matches"]:
+        score = match["score"]
+        text = match["metadata"].get("text", "")[:200]
+        sess = match["metadata"].get("session_id", "unknown")
+        ts = match["metadata"].get("timestamp", 0)
+        print(f"  [{score:.4f}] session={sess} time={ts}")
+        print(f"    {text}")
+        print()
+
+    return results
+
+
+def cleanup_session(index, session_id: str):
+    """Delete all vectors in a session namespace."""
+    index.delete(delete_all=True, namespace=session_id)
+    print(f"Cleaned up namespace '{session_id}'")
+
+
+def show_stats(index):
+    """Show index statistics."""
+    stats = index.describe_index_stats()
+    print(f"Total vectors: {stats['total_vector_count']}")
+    namespaces = stats.get("namespaces", {})
+    if namespaces:
+        print(f"Namespaces ({len(namespaces)}):")
+        for ns, info in sorted(namespaces.items()):
+            print(f"  '{ns}': {info['vector_count']} vectors")
+    else:
+        print("No namespaces found.")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Pinecone agent memory manager")
+    parser.add_argument("--index-name", required=True, help="Pinecone index name")
+    parser.add_argument(
+        "--action",
+        choices=["store", "recall", "cleanup", "stats"],
+        required=True,
+    )
+    parser.add_argument("--session-id", help="Session namespace ID")
+    parser.add_argument("--text", help="Text to store as memory")
+    parser.add_argument("--query", help="Query for recall")
+    parser.add_argument("--top-k", type=int, default=5, help="Number of results")
+    args = parser.parse_args()
+
+    pc = get_pinecone_client()
+    index = pc.Index(args.index_name)
+
+    if args.action == "store":
+        if not args.session_id or not args.text:
+            parser.error("--session-id and --text required for store action")
+        store_memory(index, args.session_id, args.text)
+    elif args.action == "recall":
+        if not args.query:
+            parser.error("--query required for recall action")
+        recall_memories(index, args.query, session_id=args.session_id, top_k=args.top_k)
+    elif args.action == "cleanup":
+        if not args.session_id:
+            parser.error("--session-id required for cleanup action")
+        cleanup_session(index, args.session_id)
+    elif args.action == "stats":
+        show_stats(index)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/optional-skills/research/pinecone-research/scripts/rag_pipeline.py b/optional-skills/research/pinecone-research/scripts/rag_pipeline.py
new file mode 100644
index 00000000000..ca0af97570b
--- /dev/null
+++ b/optional-skills/research/pinecone-research/scripts/rag_pipeline.py
@@ -0,0 +1,156 @@
+"""Pinecone RAG pipeline — index documents and query with retrieval-augmented generation.
+
+Usage:
+    export PINECONE_API_KEY="your-key"
+    export OPENAI_API_KEY="your-key"
+    python rag_pipeline.py --index-name agent-memory --action index --docs-dir ./docs
+    python rag_pipeline.py --index-name agent-memory --action query --query "How does X work?"
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def get_pinecone_client():
+    """Initialize Pinecone client from environment."""
+    try:
+        from pinecone import Pinecone
+    except ImportError:
+        print("Error: pinecone-client not installed. Run: pip install pinecone-client", file=sys.stderr)
+        sys.exit(1)
+
+    api_key = os.environ.get("PINECONE_API_KEY")
+    if not api_key:
+        print("Error: PINECONE_API_KEY environment variable not set.", file=sys.stderr)
+        sys.exit(1)
+
+    return Pinecone(api_key=api_key)
+
+
+def ensure_index(pc, index_name: str, dimension: int = 1536):
+    """Create the index if it doesn't exist."""
+    from pinecone import ServerlessSpec
+
+    existing = [idx.name for idx in pc.list_indexes()]
+    if index_name not in existing:
+        pc.create_index(
+            name=index_name,
+            dimension=dimension,
+            metric="cosine",
+            spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+        )
+        print(f"Created index: {index_name}")
+    else:
+        print(f"Index already exists: {index_name}")
+    return pc.Index(index_name)
+
+
+def load_documents(docs_dir: str) -> list[dict]:
+    """Load text files from a directory as documents."""
+    docs = []
+    docs_path = Path(docs_dir)
+    if not docs_path.is_dir():
+        print(f"Error: {docs_dir} is not a directory.", file=sys.stderr)
+        sys.exit(1)
+
+    for filepath in sorted(docs_path.rglob("*.txt")):
+        text = filepath.read_text(encoding="utf-8").strip()
+        if text:
+            docs.append({
+                "id": str(filepath.relative_to(docs_path)),
+                "text": text,
+                "metadata": {"source": str(filepath.name)},
+            })
+    return docs
+
+
+def index_documents(index, docs: list[dict], batch_size: int = 100):
+    """Embed and upsert documents into Pinecone."""
+    try:
+        from langchain_openai import OpenAIEmbeddings
+    except ImportError:
+        print("Error: langchain-openai not installed. Run: pip install langchain-openai", file=sys.stderr)
+        sys.exit(1)
+
+    embeddings = OpenAIEmbeddings()
+    vectors = []
+
+    for doc in docs:
+        embedding = embeddings.embed_query(doc["text"])
+        vectors.append({
+            "id": doc["id"],
+            "values": embedding,
+            "metadata": {**doc["metadata"], "text": doc["text"][:1000]},
+        })
+
+    # Batch upsert
+    for i in range(0, len(vectors), batch_size):
+        batch = vectors[i : i + batch_size]
+        index.upsert(vectors=batch)
+        print(f"Upserted batch {i // batch_size + 1} ({len(batch)} vectors)")
+
+    print(f"Total vectors indexed: {len(vectors)}")
+
+
+def query_index(index, query: str, top_k: int = 5):
+    """Embed a query and retrieve similar documents from Pinecone."""
+    try:
+        from langchain_openai import OpenAIEmbeddings
+    except ImportError:
+        print("Error: langchain-openai not installed. Run: pip install langchain-openai", file=sys.stderr)
+        sys.exit(1)
+
+    embeddings = OpenAIEmbeddings()
+    query_vector = embeddings.embed_query(query)
+
+    results = index.query(vector=query_vector, top_k=top_k, include_metadata=True)
+
+    print(f"\nQuery: {query}")
+    print(f"Top {top_k} results:\n")
+    for match in results["matches"]:
+        score = match["score"]
+        source = match["metadata"].get("source", "unknown")
+        text_preview = match["metadata"].get("text", "")[:200]
+        print(f"  [{score:.4f}] {source}")
+        print(f"    {text_preview}...")
+        print()
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Pinecone RAG pipeline")
+    parser.add_argument("--index-name", required=True, help="Pinecone index name")
+    parser.add_argument("--action", choices=["index", "query", "stats"], required=True)
+    parser.add_argument("--docs-dir", help="Directory of .txt files to index")
+    parser.add_argument("--query", help="Query string for retrieval")
+    parser.add_argument("--top-k", type=int, default=5, help="Number of results to return")
+    args = parser.parse_args()
+
+    pc = get_pinecone_client()
+    index = ensure_index(pc, args.index_name)
+
+    if args.action == "index":
+        if not args.docs_dir:
+            parser.error("--docs-dir required for index action")
+        docs = load_documents(args.docs_dir)
+        if not docs:
+            print("No .txt documents found.", file=sys.stderr)
+            sys.exit(1)
+        index_documents(index, docs)
+    elif args.action == "query":
+        if not args.query:
+            parser.error("--query required for query action")
+        query_index(index, args.query, top_k=args.top_k)
+    elif args.action == "stats":
+        stats = index.describe_index_stats()
+        print(f"Total vectors: {stats['total_vector_count']}")
+        for ns, info in stats.get("namespaces", {}).items():
+            print(f"  Namespace '{ns}': {info['vector_count']} vectors")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/optional-skills/research/qmd/SKILL.md b/optional-skills/research/qmd/SKILL.md
index 9dce442edc1..74baf1471c7 100644
--- a/optional-skills/research/qmd/SKILL.md
+++ b/optional-skills/research/qmd/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: qmd
-description: Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration.
+description: Hybrid local search over notes, docs, and transcripts.
 version: 1.0.0
 author: Hermes Agent + Teknium
 license: MIT
@@ -8,7 +8,7 @@ platforms: [macos, linux]
 metadata:
   hermes:
     tags: [Search, Knowledge-Base, RAG, Notes, MCP, Local-AI]
-    related_skills: [obsidian, native-mcp, arxiv]
+    related_skills: [obsidian, hermes-agent, arxiv]
 ---
 
 # QMD — Query Markup Documents
diff --git a/optional-skills/research/scrapling/SKILL.md b/optional-skills/research/scrapling/SKILL.md
index e10f4f83270..e0608417231 100644
--- a/optional-skills/research/scrapling/SKILL.md
+++ b/optional-skills/research/scrapling/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: scrapling
-description: Web scraping with Scrapling - HTTP fetching, stealth browser automation, Cloudflare bypass, and spider crawling via CLI and Python.
+description: Scrape sites with stealth browsing and Cloudflare bypass.
 version: 1.0.0
 author: FEUAZUR
 license: MIT
diff --git a/optional-skills/research/searxng-search/SKILL.md b/optional-skills/research/searxng-search/SKILL.md
index 07e32c0b9c3..acf6973be49 100644
--- a/optional-skills/research/searxng-search/SKILL.md
+++ b/optional-skills/research/searxng-search/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: searxng-search
-description: Free meta-search via SearXNG — aggregates results from 70+ search engines. Self-hosted or use a public instance. No API key needed. Falls back automatically when the web search toolset is unavailable.
-version: 1.0.0
+description: Free keyless meta-search aggregating 70+ engines.
+version: 1.0.1
 author: hermes-agent
 license: MIT
 platforms: [linux, macos]
@@ -124,23 +124,6 @@ for r in data.get("results", []):
     print()
 ```
 
-## Method 3: searxng-data Python Package
-
-For more structured access, install the `searxng-data` package:
-
-```bash
-pip install searxng-data
-```
-
-```python
-from searxng_data import engines
-
-# List available engines
-print(engines.list_engines())
-```
-
-Note: This package only provides engine metadata, not the search API itself.
-
 ## Self-Hosting SearXNG
 
 To run your own SearXNG instance:
diff --git a/optional-skills/security/1password/SKILL.md b/optional-skills/security/1password/SKILL.md
index 152cd13e60b..86672ca41b5 100644
--- a/optional-skills/security/1password/SKILL.md
+++ b/optional-skills/security/1password/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: 1password
-description: Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in, and reading/injecting secrets for commands.
+description: Set up op CLI, sign in, and read or inject secrets.
 version: 1.0.0
 author: arceus77-7, enhanced by Hermes Agent
 license: MIT
diff --git a/optional-skills/security/sherlock/SKILL.md b/optional-skills/security/sherlock/SKILL.md
index fcac3a92d7a..da473bfa791 100644
--- a/optional-skills/security/sherlock/SKILL.md
+++ b/optional-skills/security/sherlock/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: sherlock
-description: OSINT username search across 400+ social networks. Hunt down social media accounts by username.
+description: Find accounts for a username across 400+ platforms.
 version: 1.0.0
 author: unmodeled-tyler
 license: MIT
diff --git a/optional-skills/web-development/page-agent/SKILL.md b/optional-skills/web-development/page-agent/SKILL.md
index a2b08cf8cfa..0ad2c3b1556 100644
--- a/optional-skills/web-development/page-agent/SKILL.md
+++ b/optional-skills/web-development/page-agent/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: page-agent
-description: Embed alibaba/page-agent into your own web application — a pure-JavaScript in-page GUI agent that ships as a single <script> tag or npm package and lets end-users of your site drive the UI with natural language ("click login, fill username as John"). No Python, no headless browser, no extension required. Use this skill when the user is a web developer who wants to add an AI copilot to their SaaS / admin panel / B2B tool, make a legacy web app accessible via natural language, or evaluate page-agent against a local (Ollama) or cloud (Qwen / OpenAI / OpenRouter) LLM. NOT for server-side browser automation — point those users to Hermes' built-in browser tool instead.
+description: Embed an in-page natural-language GUI copilot in web apps.
 version: 1.0.0
 author: Hermes Agent
 license: MIT
diff --git a/skills/yuanbao/SKILL.md b/optional-skills/yuanbao/SKILL.md
similarity index 100%
rename from skills/yuanbao/SKILL.md
rename to optional-skills/yuanbao/SKILL.md
diff --git a/package-lock.json b/package-lock.json
index 62cf14905b6..0ee09bbcb29 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -130,7 +130,7 @@
         "motion": "^12.38.0",
         "nanostores": "^1.3.0",
         "node-pty": "1.1.0",
-        "radix-ui": "^1.4.3",
+        "radix-ui": "^1.6.5",
         "react": "^19.2.5",
         "react-arborist": "^3.5.0",
         "react-dnd-html5-backend": "^14.0.3",
@@ -1939,7 +1939,6 @@
       "os": [
         "aix"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -1956,7 +1955,6 @@
       "os": [
         "android"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -1973,7 +1971,6 @@
       "os": [
         "android"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -1990,7 +1987,6 @@
       "os": [
         "android"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2007,7 +2003,6 @@
       "os": [
         "darwin"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2024,7 +2019,6 @@
       "os": [
         "darwin"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2041,7 +2035,6 @@
       "os": [
         "freebsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2058,7 +2051,6 @@
       "os": [
         "freebsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2075,7 +2067,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2092,7 +2083,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2109,7 +2099,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2126,7 +2115,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2143,7 +2131,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2160,7 +2147,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2177,7 +2163,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2194,7 +2179,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2211,7 +2195,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2228,7 +2211,6 @@
       "os": [
         "netbsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2245,7 +2227,6 @@
       "os": [
         "netbsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2262,7 +2243,6 @@
       "os": [
         "openbsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2279,7 +2259,6 @@
       "os": [
         "openbsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2296,7 +2275,6 @@
       "os": [
         "openharmony"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2313,7 +2291,6 @@
       "os": [
         "sunos"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2330,7 +2307,6 @@
       "os": [
         "win32"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2347,7 +2323,6 @@
       "os": [
         "win32"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2364,7 +2339,6 @@
       "os": [
         "win32"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -3340,24 +3314,24 @@
       }
     },
     "node_modules/@radix-ui/number": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/number/-/number-1.1.2.tgz",
-      "integrity": "sha512-ceTwaxc4I5IOi97DgCotl3pqiyRGvffcc0oOsE2dQYaJOFIDsDt4VWG6xEbg1QePv9QWausCEIppud/tJ1wNig==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/number/-/number-1.1.3.tgz",
+      "integrity": "sha512-Road2bidD0uu/1BGDOWNdPI06g0lIRy6IF9GZcIrDK2KGItfor8IQwQa+yM2ERgHM1MmHxaxpTzk0/Jp42lNfA==",
       "license": "MIT"
     },
     "node_modules/@radix-ui/primitive": {
-      "version": "1.1.4",
-      "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.4.tgz",
-      "integrity": "sha512-7AdCK9PQyiljKoBDbN8OuctCbd/esdwZPQ8RtOE3SsyQtUpiPb+ND75q0jEhC1m1ecBI0MFNeLJvwIh9iKHRcQ==",
+      "version": "1.1.7",
+      "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.7.tgz",
+      "integrity": "sha512-rqWnm76nYT8HoNNqEjpgJ7Pw/DrBj5iBTrmEPo6HTX5+VJyBNOqTdv4g89G63HuR5g0AaENoAcH7Is5fF2kZ8Q==",
       "license": "MIT"
     },
     "node_modules/@radix-ui/react-accessible-icon": {
-      "version": "1.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-accessible-icon/-/react-accessible-icon-1.1.10.tgz",
-      "integrity": "sha512-TraSwZUqTcVbiDV2/RXzAXC7aeVVXchq0daPFZE7zAxYFaMzjOUggLOfQH9KFLgRizuwVKZO/crveV1eeO3/ZQ==",
+      "version": "1.1.13",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-accessible-icon/-/react-accessible-icon-1.1.13.tgz",
+      "integrity": "sha512-2/0RrtTngKZVkOFYDlvhe6JIsUravRnYGwH1iJ+qt+wPu8/fPu3HTLRkQptyIkpLovAy8qvHHJs9cvYJ3Uyqqg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-visually-hidden": "1.2.6"
+        "@radix-ui/react-visually-hidden": "1.2.9"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3375,20 +3349,20 @@
       }
     },
     "node_modules/@radix-ui/react-accordion": {
-      "version": "1.2.14",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-accordion/-/react-accordion-1.2.14.tgz",
-      "integrity": "sha512-iE8YB9nmTBH8zd73ofBISZ8JCzgMoMkATJr7qDwa6u5F1+7mTM81V6fa71jgZ65rpjVpecDf1vSnwIFP9Ly1zw==",
+      "version": "1.2.18",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-accordion/-/react-accordion-1.2.18.tgz",
+      "integrity": "sha512-CGuUFvhjScXBF/bhjaU9xlgai2ikYqJRazXhMzngoUaZI7QaxAw24Ae3S/pR0b69p8GqW6i+CKJmx9JPNnZ4QQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collapsible": "1.1.14",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collapsible": "1.1.18",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3406,16 +3380,16 @@
       }
     },
     "node_modules/@radix-ui/react-alert-dialog": {
-      "version": "1.1.17",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-alert-dialog/-/react-alert-dialog-1.1.17.tgz",
-      "integrity": "sha512-563ygGeyWPrxyVCNp7OV4rE2aIXhFPknpFyo4wbDlcyMMPZ6ySh+zC5WTvY0ZFLgPTg/QB6tA8PyDQyJ2b4cPg==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-alert-dialog/-/react-alert-dialog-1.1.21.tgz",
+      "integrity": "sha512-VbSR148lNkE8JdWnOsYX72YdivmCAtcrot1dl8UmT0ZZRKNR3hHJUpQxJOw7jWlY/JFemn4oaDXxCxpD594B7Q==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-dialog": "1.1.17",
-        "@radix-ui/react-primitive": "2.1.6"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-dialog": "1.1.21",
+        "@radix-ui/react-primitive": "2.1.8"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3433,12 +3407,12 @@
       }
     },
     "node_modules/@radix-ui/react-arrow": {
-      "version": "1.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.1.10.tgz",
-      "integrity": "sha512-j2VTDz1vgCsmuG0k5lBfOcM8n5JPFqZBcMryasFjHYMhwxYL5SRUV5lMSUpRdNtw3D/Sv8pzJtrlAgkssYSsQQ==",
+      "version": "1.1.13",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.1.13.tgz",
+      "integrity": "sha512-0Q310knIY0K+mkmncU9FxLggfW7V49Ok2oY+iu27KkERTsQXxYCIC8XW5QoK4w7Jp1z00vT5xj3oxTcn7QlcTg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-primitive": "2.1.6"
+        "@radix-ui/react-primitive": "2.1.8"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3456,12 +3430,12 @@
       }
     },
     "node_modules/@radix-ui/react-aspect-ratio": {
-      "version": "1.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-aspect-ratio/-/react-aspect-ratio-1.1.10.tgz",
-      "integrity": "sha512-kbI7NrqhDeuytYrq7JjAsoXczvL8wgj2tc1MyaYWm+50bMKHCHQtVWCryslx4cCpmCTTkBcwQckE4CmmGV2haQ==",
+      "version": "1.1.13",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-aspect-ratio/-/react-aspect-ratio-1.1.13.tgz",
+      "integrity": "sha512-dD/EvbOiLskcdBKgNAeUmbTBCJfdCGp85fpFe3lmziE4ASbXuFERQCAB3sR41yvM+P711kJsTBNL9piP60urbA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-primitive": "2.1.6"
+        "@radix-ui/react-primitive": "2.1.8"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3479,16 +3453,17 @@
       }
     },
     "node_modules/@radix-ui/react-avatar": {
-      "version": "1.2.0",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-avatar/-/react-avatar-1.2.0.tgz",
-      "integrity": "sha512-am/CwltXtmtdtP+5FbYblYDnMa/zuKcMJP1i3/SJMDXXfj2mG+BTqLH2wucqeyyiQMursUtg/5cK+Nh2pCaSOA==",
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-avatar/-/react-avatar-1.2.4.tgz",
+      "integrity": "sha512-u4Sz6ajq2WobGMqbsNXnFI/3JP/o7TUBkEmQ4BRUYofPDQawdO3WWYy5907c9VgOFX+ETjKI3VxnnrKYAF7Pmg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-is-hydrated": "0.1.1",
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-is-hydrated": "0.1.2",
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3506,19 +3481,18 @@
       }
     },
     "node_modules/@radix-ui/react-checkbox": {
-      "version": "1.3.5",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-checkbox/-/react-checkbox-1.3.5.tgz",
-      "integrity": "sha512-pREzrmNnVwGvYaBoM64huTRK7B3lrTRuwj8A9nwhPiEtMb+yudiWh6zWAqEtP0Dzd5+iBa1Ki7V1pCxV8ExMdA==",
+      "version": "1.3.9",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-checkbox/-/react-checkbox-1.3.9.tgz",
+      "integrity": "sha512-YPXZlqjrKVqKtVD2F828CApHwu+PEu30i7x0Y9gg6SbQ3fJbcaQlDkGPT0gW6HjxoCjAEt8uJ494F1S61KpIjQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-previous": "1.1.2",
-        "@radix-ui/react-use-size": "1.1.2"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-size": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3536,19 +3510,19 @@
       }
     },
     "node_modules/@radix-ui/react-collapsible": {
-      "version": "1.1.14",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-collapsible/-/react-collapsible-1.1.14.tgz",
-      "integrity": "sha512-9bT+FvifX1FK2Mj6UEsTdyu0cN3JaA3KdfhaBao+ONrYFy/pyOy3TU1TNw7iOk1o+0hOEq67RojlUUmoFGwxyA==",
+      "version": "1.1.18",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-collapsible/-/react-collapsible-1.1.18.tgz",
+      "integrity": "sha512-aNMp8humfYzWERz5gxGb/eLNkB0ZthypLbNlNolzdgzFTeN78e/rnn9rxCdOaSsg/zClTOJ/OkjXYx9PUEPATw==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3566,15 +3540,15 @@
       }
     },
     "node_modules/@radix-ui/react-collection": {
-      "version": "1.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.1.10.tgz",
-      "integrity": "sha512-IVVz4EvBcKjrzKgof714qDnz/SzQAkLA2Emh5edlHbgcE6fNd3Un6CJLlaYcnm8N4JmAtzQgse4dOKxcD2yc9g==",
+      "version": "1.1.13",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.1.13.tgz",
+      "integrity": "sha512-Q8xYqNRFObXPmi45bFSkGdM2JA5hjBeYGFqzg6lZR3wp6b+cciraVq8DdneTabtws+uOYqjmsvmKOufk/M9Cyg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-slot": "1.3.0"
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-slot": "1.3.1"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3592,9 +3566,9 @@
       }
     },
     "node_modules/@radix-ui/react-compose-refs": {
-      "version": "1.1.3",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.3.tgz",
-      "integrity": "sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==",
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.4.tgz",
+      "integrity": "sha512-pWJo6lQAfR6uy1n7ii7PaCc9dLPwTXDYbQpORZU5B548Aqvl2pP1SM1vJGKyxIFqZMHRopRO4CQYX2iXAIB5jA==",
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "*",
@@ -3607,9 +3581,9 @@
       }
     },
     "node_modules/@radix-ui/react-context": {
-      "version": "1.1.4",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.4.tgz",
-      "integrity": "sha512-QwH4PO5urrbO+FaGd5Aglg+YJgWTyyuZ3g/6mKvsqraLkglDdckw9JafgL5McL5VEJ6EPNduPaT3ZE9BttDAqg==",
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.2.1.tgz",
+      "integrity": "sha512-EraVbFjiIjibpLr6EjvEDmSCYJU2SlKDMiO+qEK/D9GOWnQoAQlpQo2occGYC1UM9MBeEx5Bek3UtW/Qi57vAg==",
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "*",
@@ -3622,16 +3596,16 @@
       }
     },
     "node_modules/@radix-ui/react-context-menu": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-context-menu/-/react-context-menu-2.3.1.tgz",
-      "integrity": "sha512-XbrxS68W5dyiE4fAb96yvJwSVU5x66B20A99sD5Mk3xSWK/LqeOnx6TZnim1KieMjXS/CTFq8reOAjWxas2G8Q==",
+      "version": "2.3.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-context-menu/-/react-context-menu-2.3.5.tgz",
+      "integrity": "sha512-wbvSjqc7r0xKmfhrMCiCPxSTv/aSHU0cCAy0tELthJbaIzT7dkAcevKuoGKbDLiPG2VePgMVqLi2sWb6tDnzvQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-menu": "2.1.18",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-menu": "2.1.22",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3649,23 +3623,24 @@
       }
     },
     "node_modules/@radix-ui/react-dialog": {
-      "version": "1.1.17",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-dialog/-/react-dialog-1.1.17.tgz",
-      "integrity": "sha512-TDTYmpdq8dI2+Xgvgj9AJ8Ghqq+Eph/TRVEdaFQPDItIY+6QSkU7MJMeevw1568Yw/2Ijz8BTphPSP2XejKphw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-dialog/-/react-dialog-1.1.21.tgz",
+      "integrity": "sha512-h+7qMDDmZJ8qTSPrwNyKb/PACY0ehtN8QOBlCz+C2C1jgehKekdhmHddG9YQk8BF/sHJqglPjte+jA1Jrp9HcA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-focus-guards": "1.1.4",
-        "@radix-ui/react-focus-scope": "1.1.10",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-portal": "1.1.12",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-slot": "1.3.0",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-focus-guards": "1.1.5",
+        "@radix-ui/react-focus-scope": "1.1.14",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-portal": "1.1.15",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-slot": "1.3.1",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
         "aria-hidden": "^1.2.4",
         "react-remove-scroll": "^2.7.2"
       },
@@ -3685,9 +3660,9 @@
       }
     },
     "node_modules/@radix-ui/react-direction": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.1.2.tgz",
-      "integrity": "sha512-C3vFhbyi4SW3PmbAi6Awpu4OzJtd0MxGurvSsYtr7p7nM8RNB3VAF3CUmnp2j50knpkrRcB7+ycVXzgLgF6yNA==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.1.3.tgz",
+      "integrity": "sha512-OdgAA/xb6WOQMKNn0mtbYoruMG6YMaBOnq+evWxSpMmiEMBdeFZawnIWRfPPeVXCRm+0lnN8jpJLjhD7/UIxWw==",
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "*",
@@ -3700,16 +3675,16 @@
       }
     },
     "node_modules/@radix-ui/react-dismissable-layer": {
-      "version": "1.1.13",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.1.13.tgz",
-      "integrity": "sha512-2v+zNAWWe0ySxgC0D0yeXMPQ23xZVgXZTerTz+JKlmdRj6gfTqmCcR29jb6d290DezXPGgruHWDX/vYUebtErg==",
+      "version": "1.1.17",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.1.17.tgz",
+      "integrity": "sha512-QAXwa38pG0xNAYh1pjdSaf86NrkqsMoDNmget/Y7X8O8E/C3Iqlj9GAPE4DfX9BPLXc7WH2TWSzMRnIoCdcjzQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-escape-keydown": "1.1.2"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-effect-event": "0.0.4"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3727,18 +3702,18 @@
       }
     },
     "node_modules/@radix-ui/react-dropdown-menu": {
-      "version": "2.1.18",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-dropdown-menu/-/react-dropdown-menu-2.1.18.tgz",
-      "integrity": "sha512-PZGV82gFk0WltDRI//SsG28ZIjlo9ANTmoNYg0jLNzXXiDsAy5PkOOYQaVD1pPxY6t7gxffb1QMD6qaUvsBZdw==",
+      "version": "2.1.22",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-dropdown-menu/-/react-dropdown-menu-2.1.22.tgz",
+      "integrity": "sha512-wZRLTjZaJf1HTxx0YepFKZUuo+SZMi+Cr4kJ2fuA5FxDSUE0vHDTscahUaU+jfz6LFk4OuguwqJs5K0JsIsIBA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-menu": "2.1.18",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-menu": "2.1.22",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3756,9 +3731,9 @@
       }
     },
     "node_modules/@radix-ui/react-focus-guards": {
-      "version": "1.1.4",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.1.4.tgz",
-      "integrity": "sha512-cot/aB/mOm0IYVYTTmQcEEK1M48lZWi8FlYe5nDPQQ8NYZUlXEFgncJ9p2Kzer3RKSrY7cTTpEMLZKNo9QoP5Q==",
+      "version": "1.1.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.1.5.tgz",
+      "integrity": "sha512-UQvlB7L/BYh3P8MLvwZnQkH521EDos40Rwnbt5+Qpg4Vbk0z3xJjRUmR6+aka4aT1IQQXFdO5bNPoE7cvFl5xQ==",
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "*",
@@ -3771,14 +3746,14 @@
       }
     },
     "node_modules/@radix-ui/react-focus-scope": {
-      "version": "1.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.1.10.tgz",
-      "integrity": "sha512-Fas/lXQqhVvqwAb64s5RFeHiHYElZ6SUQbZaNd6EkfhP/Al7wTIQ9WIR4QVX475tlu5yFCEdDcJH6/UwsZjMWw==",
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.1.14.tgz",
+      "integrity": "sha512-/x4htnJfmW53MplkrePaDpf1o/rN1C++g88WpVobULXbSyC19NtLkXmewuJ/HCaceSmfKDNL5gOXcBGnuAvnvQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-callback-ref": "1.1.2"
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-callback-ref": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3796,17 +3771,17 @@
       }
     },
     "node_modules/@radix-ui/react-form": {
-      "version": "0.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-form/-/react-form-0.1.10.tgz",
-      "integrity": "sha512-1NfuvctVtX4sU3Mmq/IdrR8UunxiCMiVg3A5UENKhFzxUBeOyaQQ+lmaQaV7Tc8cqvBKsJL3/KGBsixK0D8WFg==",
+      "version": "0.1.14",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-form/-/react-form-0.1.14.tgz",
+      "integrity": "sha512-ZCuPb54PQ3ZQEdQ6G1PrMBfXXzAyaVoCI9Fl+bWOwYZKTOcFjPHL7JQ3tCb6CX6Ut81GZLWKgIpV6OS3n5z5Ig==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-label": "2.1.10",
-        "@radix-ui/react-primitive": "2.1.6"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-label": "2.1.13",
+        "@radix-ui/react-primitive": "2.1.8"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3824,20 +3799,20 @@
       }
     },
     "node_modules/@radix-ui/react-hover-card": {
-      "version": "1.1.17",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-hover-card/-/react-hover-card-1.1.17.tgz",
-      "integrity": "sha512-GjZQIEANVkuuWeztlKz6QEHe31ZX2iDfHzcTMCQVZXC0JyQrgfKWSC+LOOEw6aVV64zyjzobIzSA4AU4eKWrHA==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-hover-card/-/react-hover-card-1.1.21.tgz",
+      "integrity": "sha512-ByFLyi+kdTGkObxIt5wKB3Ru3rtJRuYUqPEtqiv1HNYqutqbn1wDuNmVzI6iwus9qfY3vwpNgvx/UVZUGTWC1A==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-popper": "1.3.1",
-        "@radix-ui/react-portal": "1.1.12",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-popper": "1.3.5",
+        "@radix-ui/react-portal": "1.1.15",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3855,12 +3830,12 @@
       }
     },
     "node_modules/@radix-ui/react-id": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.1.2.tgz",
-      "integrity": "sha512-orBC88futVpqCmhX1p4cvquNHsELQ+w+vBJnuj3ftETI5bJb0bZn3Tqu3SWN2IOcPycTnMGnhwoermvISt72sA==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.1.3.tgz",
+      "integrity": "sha512-f/Wxm0ctyMymUJK0fqTSQlm85rbzdAkoNbPXJQ5+6caowVO8Yx+NWGjGz/oGhs/D+WIbbQpOrU0hU2Li2/42xQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3873,12 +3848,12 @@
       }
     },
     "node_modules/@radix-ui/react-label": {
-      "version": "2.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-label/-/react-label-2.1.10.tgz",
-      "integrity": "sha512-ib0zvq2ZsAqKm5tRnqGJn3vOxSgIts5ToxsXT0q1S/GfLD1Zj7UOEnkw8u2w6sRmn47djpQWuSU1DCL1R29/yw==",
+      "version": "2.1.13",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-label/-/react-label-2.1.13.tgz",
+      "integrity": "sha512-kj7BXyM4uG0dyeoEdVmPQAOFN291+iJOtiGTvkXe1ijJWLQbAHpFNkopvqquaMVn+zjqTZRhnefESAinMErHKg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-primitive": "2.1.6"
+        "@radix-ui/react-primitive": "2.1.8"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3896,27 +3871,27 @@
       }
     },
     "node_modules/@radix-ui/react-menu": {
-      "version": "2.1.18",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-menu/-/react-menu-2.1.18.tgz",
-      "integrity": "sha512-lj8Rxjtn6zJq1oSbE/uDtAwCbB9BnxgHD+8MwJMuTh6u1dPamYhW9iuELr/Z8d0D/UysFblYYHeBPwi7T4k0YQ==",
+      "version": "2.1.22",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-menu/-/react-menu-2.1.22.tgz",
+      "integrity": "sha512-xCFrVLttGDPwMjIPI6GS+tm3IGUNKsPXffrJQIPpQJuE9Qy1bU9GNUCkwranU/pEqyBlwMxcBIK/FUJFAZ9SqQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-focus-guards": "1.1.4",
-        "@radix-ui/react-focus-scope": "1.1.10",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-popper": "1.3.1",
-        "@radix-ui/react-portal": "1.1.12",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-roving-focus": "1.1.13",
-        "@radix-ui/react-slot": "1.3.0",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-focus-guards": "1.1.5",
+        "@radix-ui/react-focus-scope": "1.1.14",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-popper": "1.3.5",
+        "@radix-ui/react-portal": "1.1.15",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-roving-focus": "1.1.17",
+        "@radix-ui/react-slot": "1.3.1",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
         "aria-hidden": "^1.2.4",
         "react-remove-scroll": "^2.7.2"
       },
@@ -3936,21 +3911,21 @@
       }
     },
     "node_modules/@radix-ui/react-menubar": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-menubar/-/react-menubar-1.1.18.tgz",
-      "integrity": "sha512-hX7EGx/oFq6DPY27GQuP/2wP48GHf5LG6r06VgNJlG+znmDS8OfopZcRcGly3L4lsB9FqpmLx6JQSE9P3BUpyw==",
+      "version": "1.1.22",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-menubar/-/react-menubar-1.1.22.tgz",
+      "integrity": "sha512-jDkcZXd5rN4b/S9nnEv9KZajaQ7+RO98OCWqAxrULTJtkSvODlNOO+EIxNG/d4QIF6QOqK5ZZrTF9MYl6eQdiQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-menu": "2.1.18",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-roving-focus": "1.1.13",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-menu": "2.1.22",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-roving-focus": "1.1.17",
+        "@radix-ui/react-use-controllable-state": "1.2.5"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -3968,25 +3943,25 @@
       }
     },
     "node_modules/@radix-ui/react-navigation-menu": {
-      "version": "1.2.16",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-navigation-menu/-/react-navigation-menu-1.2.16.tgz",
-      "integrity": "sha512-nJ0SkrSQgudyYhMiYeHA1ayLVuduEJCFLan1RZZN7c9kqzzCFLaU9kuy81uNtqzweM9YaQPgWzxi9MwQ9jZ04g==",
+      "version": "1.2.20",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-navigation-menu/-/react-navigation-menu-1.2.20.tgz",
+      "integrity": "sha512-in/exCQPatmmBmQZrtQkK4UrysEp8VGEuw5o8Bx3ozxbfg7DBb4H5j3DgxGz4N59J02NRVzhsWFtujZgy5ue3w==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-layout-effect": "1.1.2",
-        "@radix-ui/react-use-previous": "1.1.2",
-        "@radix-ui/react-visually-hidden": "1.2.6"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
+        "@radix-ui/react-use-previous": "1.1.3",
+        "@radix-ui/react-visually-hidden": "1.2.9"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4004,23 +3979,23 @@
       }
     },
     "node_modules/@radix-ui/react-one-time-password-field": {
-      "version": "0.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-one-time-password-field/-/react-one-time-password-field-0.1.10.tgz",
-      "integrity": "sha512-GHkcJ+WVj91At+OvUVTD4R3W0/wxw9t/sG5xFUBYXaCbtWiooZX5Md376QjJqgH4VsVyXrbVNHO2O4NYcmjfVg==",
+      "version": "0.1.14",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-one-time-password-field/-/react-one-time-password-field-0.1.14.tgz",
+      "integrity": "sha512-F3vMSK+d+huI3a4Zm6j2hUsS+/gByVbsechJwp/ZCZBCrusXHvBeZZz9aMqXqqYNYu23mtvVMt6AeHDds8EU7w==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/number": "1.1.2",
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-roving-focus": "1.1.13",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-effect-event": "0.0.3",
-        "@radix-ui/react-use-is-hydrated": "0.1.1",
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/number": "1.1.3",
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-roving-focus": "1.1.17",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-effect-event": "0.0.4",
+        "@radix-ui/react-use-is-hydrated": "0.1.2",
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4038,19 +4013,19 @@
       }
     },
     "node_modules/@radix-ui/react-password-toggle-field": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-password-toggle-field/-/react-password-toggle-field-0.1.5.tgz",
-      "integrity": "sha512-fVuA82u0b/fClpbEJv8yp1nU9eSvoSEOERsU/hhf3FXGPIvkmE7oEaHEu8poowoXO39/Va7zq2E0TUcYr1dBRg==",
+      "version": "0.1.9",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-password-toggle-field/-/react-password-toggle-field-0.1.9.tgz",
+      "integrity": "sha512-JFkmnwZFD357odQkpzfxz++bpohQpaGCT/4PK6oRd4R/Rxzg02uFDucFzZDOTIOz6vWSluIlz91zelleg9BheA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-effect-event": "0.0.3",
-        "@radix-ui/react-use-is-hydrated": "0.1.1"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-effect-event": "0.0.4",
+        "@radix-ui/react-use-is-hydrated": "0.1.2"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4068,24 +4043,25 @@
       }
     },
     "node_modules/@radix-ui/react-popover": {
-      "version": "1.1.17",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-popover/-/react-popover-1.1.17.tgz",
-      "integrity": "sha512-/YSAOdJ7YJvdn7bn5sdSx2egW+SKY+u7O5RyAVs94Ymrg2fg5QTSFPMRkzvhGyFuE4/qsmPBdrwYoZMZh/4f+g==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-popover/-/react-popover-1.1.21.tgz",
+      "integrity": "sha512-+AJ7P5oRcFqFtv7MaCD8fOuK3l5qQBAMdWEOnUOYd3JfHOeIUe7TnHHSSP15CtWwH4KrotyDCTzodOIoONh8vw==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-focus-guards": "1.1.4",
-        "@radix-ui/react-focus-scope": "1.1.10",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-popper": "1.3.1",
-        "@radix-ui/react-portal": "1.1.12",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-slot": "1.3.0",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-focus-guards": "1.1.5",
+        "@radix-ui/react-focus-scope": "1.1.14",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-popper": "1.3.5",
+        "@radix-ui/react-portal": "1.1.15",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-slot": "1.3.1",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
         "aria-hidden": "^1.2.4",
         "react-remove-scroll": "^2.7.2"
       },
@@ -4105,21 +4081,21 @@
       }
     },
     "node_modules/@radix-ui/react-popper": {
-      "version": "1.3.1",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.3.1.tgz",
-      "integrity": "sha512-bhnq/0DEPTi2lsOD3J5rTL65qUKHbKbhqHsmN9TMiclSXpipi651ooUKPPp6G5lF/WiHBdn1s0Wuqsn+myVAvw==",
+      "version": "1.3.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.3.5.tgz",
+      "integrity": "sha512-6hLng2Rs45IZcvZ31BNvMeaFEMMEbtsog4xPcb8LZrGfyoV9fdAXqB9UKhLpTHtL0+E2DhSr6VW54Tehd6ksAQ==",
       "license": "MIT",
       "dependencies": {
         "@floating-ui/react-dom": "^2.0.0",
-        "@radix-ui/react-arrow": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-layout-effect": "1.1.2",
-        "@radix-ui/react-use-rect": "1.1.2",
-        "@radix-ui/react-use-size": "1.1.2",
-        "@radix-ui/rect": "1.1.2"
+        "@radix-ui/react-arrow": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
+        "@radix-ui/react-use-rect": "1.1.3",
+        "@radix-ui/react-use-size": "1.1.3",
+        "@radix-ui/rect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4137,13 +4113,13 @@
       }
     },
     "node_modules/@radix-ui/react-portal": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.1.12.tgz",
-      "integrity": "sha512-m309havGzsjLHHaIX50G5PlvRs3xkgPCsGk/5PTvYm8D5q33yG0J7w/712PTOhid7NTaFETtnSXjngHQavvhVw==",
+      "version": "1.1.15",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.1.15.tgz",
+      "integrity": "sha512-kAfBVJUKNNKZuyGQXXG6rKolAV2KAmxxVkPXJgoq9dEFTl39286RufHQFNTL8rzha4vP8159BJ6hMGpB+bqv7A==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4161,12 +4137,12 @@
       }
     },
     "node_modules/@radix-ui/react-presence": {
-      "version": "1.1.6",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.6.tgz",
-      "integrity": "sha512-zdTk4PlUO0E18HnZ3wYbW0KkJJxWCdiNYp6g6X1PtONFhxVkg01vliTJAmwIszU6mHiyBOoW9P0rAugl5/hULQ==",
+      "version": "1.1.9",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.9.tgz",
+      "integrity": "sha512-LTi1v05bprIb8/GSY/GWusI0jfsYjQ3CD3Nin8o7jVxnpHzVQfzjOQJoJTQkE9bdmOnsS7SFdhkXiBv8PrYnxw==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4184,12 +4160,12 @@
       }
     },
     "node_modules/@radix-ui/react-primitive": {
-      "version": "2.1.6",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.6.tgz",
-      "integrity": "sha512-wetd0QI77DbvrPpTAvH1SqOxsYF2wZe5TNxqwOd5Ty4XDpV3dpV0s8K/1MGMJBeY5o7lg8ub5VIt1Ub+yVen6g==",
+      "version": "2.1.8",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.8.tgz",
+      "integrity": "sha512-DOlK1BdcIeYYUcFkSYFka4v1h95XTov93b0jCgW1EEiZuIhdwHY2NlE1teLIh+p0uBsuZI5A+voay+iVWpprfA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-slot": "1.3.0"
+        "@radix-ui/react-slot": "1.3.1"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4207,13 +4183,13 @@
       }
     },
     "node_modules/@radix-ui/react-progress": {
-      "version": "1.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-progress/-/react-progress-1.1.10.tgz",
-      "integrity": "sha512-JYzEg60lk79PwKM27WZyKd7PW8O4OM5jOaFfRPfOyeXmMw7tLJh5kSj+CEjVTehszuwml/AdCzPGMXBTGf4BBw==",
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-progress/-/react-progress-1.1.14.tgz",
+      "integrity": "sha512-lq5VXWp/t/b8MaqbRMAItXICc/jwhzJt0ZZ+au/CBtTYkX9EfAsSyGQL5brUVBgf9tUTKCoJEZlDl+uJF/08xQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-primitive": "2.1.6"
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-primitive": "2.1.8"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4231,21 +4207,20 @@
       }
     },
     "node_modules/@radix-ui/react-radio-group": {
-      "version": "1.4.1",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-radio-group/-/react-radio-group-1.4.1.tgz",
-      "integrity": "sha512-/SSxZdKEo2Eo29FFRKd06EfFDYp8HryKg0WYg7QLXaydPzl52YfSvCH2a3QDBRdtcuwACroJT8UVjQVgOJ7P9A==",
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-radio-group/-/react-radio-group-1.4.5.tgz",
+      "integrity": "sha512-BM1xQgw1gpgPSw05U4hJCMDX9GmAS6b6vKZANuNQZo0vf/ah7NZDAnjLd4tPg3z2vMvlI0CV+B2CFM9Z19oQDA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-roving-focus": "1.1.13",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-previous": "1.1.2",
-        "@radix-ui/react-use-size": "1.1.2"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-roving-focus": "1.1.17",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-size": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4263,20 +4238,22 @@
       }
     },
     "node_modules/@radix-ui/react-roving-focus": {
-      "version": "1.1.13",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.1.13.tgz",
-      "integrity": "sha512-9gkwneI0guf8JDmrFxPjJF6Ozzgioyw+/lonYNCwefS9ZHA05er0BVHiXr+LbWGHxUfczvMY6G1oiZZi1VzjRw==",
+      "version": "1.1.17",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.1.17.tgz",
+      "integrity": "sha512-YdJmjETw7Py+4Nziv71jgZ6fH7xQgB5p+pQ5rV8Iufyrm0RHSijec/UV1zPfQoK/YcfzB9nOl/2bi1zf1SjRMQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-is-hydrated": "0.1.2",
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4294,20 +4271,20 @@
       }
     },
     "node_modules/@radix-ui/react-scroll-area": {
-      "version": "1.2.12",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-scroll-area/-/react-scroll-area-1.2.12.tgz",
-      "integrity": "sha512-xuafVzQiTCLsyEjakowTdG3OgTXsmO7IdCiO77otIa+z44xoLNs9Do5eg7POFumIOCjtG6djfm6RKUKpUa/csA==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-scroll-area/-/react-scroll-area-1.2.16.tgz",
+      "integrity": "sha512-kEcmCenIJ+W5xlCv1u9VKDdPmzzGyfrJwEneY+02GH+lJRXrGpkiTkyjrfkspuRw6DXt4uduwT5c4xD8HTv27Q==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/number": "1.1.2",
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/number": "1.1.3",
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4325,31 +4302,31 @@
       }
     },
     "node_modules/@radix-ui/react-select": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-select/-/react-select-2.3.1.tgz",
-      "integrity": "sha512-w6eDvY78LE9ZUiNnXCA1QVK8RYN7k9galFv09kjVydJqBAgHd7Y9A6h0UJ/6DCZNGZMZrB2ohcSW1Bo9d8+wWA==",
+      "version": "2.3.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-select/-/react-select-2.3.5.tgz",
+      "integrity": "sha512-6CQx0xtdarAkSCsqgLJaz+coYQaru7rt8K6gMItR2rA+WP8/Ig6kRAzP6Zw88RccG98IZnszqJlJx9hejYOL3A==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/number": "1.1.2",
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-focus-guards": "1.1.4",
-        "@radix-ui/react-focus-scope": "1.1.10",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-popper": "1.3.1",
-        "@radix-ui/react-portal": "1.1.12",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-slot": "1.3.0",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-layout-effect": "1.1.2",
-        "@radix-ui/react-use-previous": "1.1.2",
-        "@radix-ui/react-visually-hidden": "1.2.6",
+        "@radix-ui/number": "1.1.3",
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-focus-guards": "1.1.5",
+        "@radix-ui/react-focus-scope": "1.1.14",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-popper": "1.3.5",
+        "@radix-ui/react-portal": "1.1.15",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-slot": "1.3.1",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
+        "@radix-ui/react-use-previous": "1.1.3",
+        "@radix-ui/react-visually-hidden": "1.2.9",
         "aria-hidden": "^1.2.4",
         "react-remove-scroll": "^2.7.2"
       },
@@ -4369,12 +4346,12 @@
       }
     },
     "node_modules/@radix-ui/react-separator": {
-      "version": "1.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-separator/-/react-separator-1.1.10.tgz",
-      "integrity": "sha512-Y6K6jLQCVfCnTL2MEtGxDLffkhNfEfHsEg3Wa8JU+IWdn3EWbLXd3OuOfQRN7p/W/cUce1WyTk3QeuAoDBzN9g==",
+      "version": "1.1.13",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-separator/-/react-separator-1.1.13.tgz",
+      "integrity": "sha512-wbagLhy4grekqiT6hU0WNP09FpmemTXbNWg4QEawaw9dix7hRIcrmDNnLDasOsKVLtArEznhgZKe5Gm4U6oPXQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-primitive": "2.1.6"
+        "@radix-ui/react-primitive": "2.1.8"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4392,22 +4369,22 @@
       }
     },
     "node_modules/@radix-ui/react-slider": {
-      "version": "1.4.1",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-slider/-/react-slider-1.4.1.tgz",
-      "integrity": "sha512-r91WSpQucNGFKAIxT8FT0H0zyjd5tJlqObLp7LOMV4z49KoDCwjy01w3vDOU4e1wxhF9IgjYco7SB6byOW7Buw==",
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-slider/-/react-slider-1.4.5.tgz",
+      "integrity": "sha512-7E8C13SdQKQxYganILiVZGEwM0NSbfbFcnNJ93kP++wD2pMT1SMsG3c04PFUlbPpaSXgicYgPeBndgJTvV3NKg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/number": "1.1.2",
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-layout-effect": "1.1.2",
-        "@radix-ui/react-use-previous": "1.1.2",
-        "@radix-ui/react-use-size": "1.1.2"
+        "@radix-ui/number": "1.1.3",
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
+        "@radix-ui/react-use-previous": "1.1.3",
+        "@radix-ui/react-use-size": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4425,12 +4402,13 @@
       }
     },
     "node_modules/@radix-ui/react-slot": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.3.0.tgz",
-      "integrity": "sha512-MojKku4U/miO8Av4Dkb+ctMAQx7JmY96LmtDQlAarCRtd7rN52QCSzBF+XAvr5S6coSVj9HEPBgHAHKEJVk/WA==",
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.3.1.tgz",
+      "integrity": "sha512-Bu/aAQHFFh6/QAvXAeUMurJ9fbW0JUIqlojU/yBXZ7cAVqy75Y7JYYyuCr9zLNF0p4WWoJYV54CTUIf4l7FzTw==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-compose-refs": "1.1.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4443,18 +4421,17 @@
       }
     },
     "node_modules/@radix-ui/react-switch": {
-      "version": "1.3.1",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-switch/-/react-switch-1.3.1.tgz",
-      "integrity": "sha512-55bQtCnOB0BohomSHi6qvQXpJEEqUGDm6hRrM0Bph5OXwhSegqkd8IqgBAQkM1IlgUlWZIxpxRcpOEfRIgimyw==",
+      "version": "1.3.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-switch/-/react-switch-1.3.5.tgz",
+      "integrity": "sha512-e1YrvGvEjIqDhqKjQ4Q+IDkMfiY30u3FPz9CZXZMlQ8mU3kZ2PdeBM8Gssc48CDopPizNorKumGhjySBfO7BDQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-previous": "1.1.2",
-        "@radix-ui/react-use-size": "1.1.2"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-size": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4472,19 +4449,19 @@
       }
     },
     "node_modules/@radix-ui/react-tabs": {
-      "version": "1.1.15",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-tabs/-/react-tabs-1.1.15.tgz",
-      "integrity": "sha512-kxc9gI6/HfcU4nfMMVS3AmQK414kbU1IE6UCJmMmxjhO3cRPXOyYnmvyKD+ODt7q56nRq9l7Wovi6uaGwKgMlg==",
+      "version": "1.1.19",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-tabs/-/react-tabs-1.1.19.tgz",
+      "integrity": "sha512-4wbGf98pX2ZwYqHMVB/dakeMPyH4xSJ9MSDaCCWXlIpYt0VYY6mtZxKSTiGS/F3tk0yrEYmXE1V8uwG7TxDCcQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-roving-focus": "1.1.13",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-roving-focus": "1.1.17",
+        "@radix-ui/react-use-controllable-state": "1.2.5"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4502,23 +4479,23 @@
       }
     },
     "node_modules/@radix-ui/react-toast": {
-      "version": "1.2.17",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-toast/-/react-toast-1.2.17.tgz",
-      "integrity": "sha512-uL4kyyWy000pPL43fGGCV5qT6ZchCWEQZOSlkYiPwPt8Hy1iW38RjeptIvz1/SZesrW6Vn58Ct3sV7tfEfiAbw==",
+      "version": "1.2.21",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-toast/-/react-toast-1.2.21.tgz",
+      "integrity": "sha512-/o8uHzH2z6ZM59Dt1UPFj8aYJ0DjPu0EuQXQ7uuYJTQLH5mNqxa1KuBfbpnklgXOOjyAtTp/tll0Nm+Nkz+bEg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-portal": "1.1.12",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-layout-effect": "1.1.2",
-        "@radix-ui/react-visually-hidden": "1.2.6"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-portal": "1.1.15",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
+        "@radix-ui/react-visually-hidden": "1.2.9"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4536,14 +4513,14 @@
       }
     },
     "node_modules/@radix-ui/react-toggle": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle/-/react-toggle-1.1.12.tgz",
-      "integrity": "sha512-AsAVsYNZIlRBsci7BhE+QyQeKd1h6TffJYt+lF0QQkd5OpQ3klfIByPsCb4G0h/Fq6PJwh1FYNluzBFYzhk4+w==",
+      "version": "1.1.16",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle/-/react-toggle-1.1.16.tgz",
+      "integrity": "sha512-pp4TLY3N4osN9IB4TLEaaZRGooBmCi/XJD65gSCs5tvsKofM9WgiBToNtGrmR0k3sG4jFj4Nw4utsIvQraWA9g==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-use-controllable-state": "1.2.5"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4561,18 +4538,18 @@
       }
     },
     "node_modules/@radix-ui/react-toggle-group": {
-      "version": "1.1.13",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle-group/-/react-toggle-group-1.1.13.tgz",
-      "integrity": "sha512-Xb9PLtlvU66F36LiKba6dFswu6V2mDkgidO4fNSbQHQwmZ9ObxMIO17MN/LJ4aWJecVuSVLAHPZjyeMzJrgeiA==",
+      "version": "1.1.17",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle-group/-/react-toggle-group-1.1.17.tgz",
+      "integrity": "sha512-KKsrxb1cZREc2RI5DOGwlUSpaPW40xIaK1/DXXqYDb7slRE8pkRa+iF2aFbYiuMJ+aNWpCSChiN5gFe3bVveaQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-roving-focus": "1.1.13",
-        "@radix-ui/react-toggle": "1.1.12",
-        "@radix-ui/react-use-controllable-state": "1.2.3"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-roving-focus": "1.1.17",
+        "@radix-ui/react-toggle": "1.1.16",
+        "@radix-ui/react-use-controllable-state": "1.2.5"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4590,18 +4567,18 @@
       }
     },
     "node_modules/@radix-ui/react-toolbar": {
-      "version": "1.1.13",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-toolbar/-/react-toolbar-1.1.13.tgz",
-      "integrity": "sha512-Za1l4f6fzTkGgz/iynAMN8iaqiKff2wm2/QwiLmHPtDQreWEBrvSimgQFIekxMUdRPhILM7xdIXxuS/o/DGZag==",
+      "version": "1.1.17",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-toolbar/-/react-toolbar-1.1.17.tgz",
+      "integrity": "sha512-MjorZ0XQiWfCrrpStNXw/hX0HnG7VEzCgcSV226Ox8/WzS5yq0SiMhsLFE3LlXhdghlakFRFdE6eegtmUQW7Mg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-roving-focus": "1.1.13",
-        "@radix-ui/react-separator": "1.1.10",
-        "@radix-ui/react-toggle-group": "1.1.13"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-roving-focus": "1.1.17",
+        "@radix-ui/react-separator": "1.1.13",
+        "@radix-ui/react-toggle-group": "1.1.17"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4619,23 +4596,24 @@
       }
     },
     "node_modules/@radix-ui/react-tooltip": {
-      "version": "1.2.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-tooltip/-/react-tooltip-1.2.10.tgz",
-      "integrity": "sha512-NlNe8D0dWEpVfXFli90IO6X07Josx/b1iu98tDnx9Xv0HT4wLIL+m2VOheMHhK7qbp2HoTBqALEFzGyZs/levw==",
+      "version": "1.2.14",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-tooltip/-/react-tooltip-1.2.14.tgz",
+      "integrity": "sha512-C/JxCKJJac+wtHPW1yFBSN8Ssuaufy2jYQMgyiJYyW4Fw0WJfDWXQDAly1qsbd1YDznH+sYitaljhf8igPCvmA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-id": "1.1.2",
-        "@radix-ui/react-popper": "1.3.1",
-        "@radix-ui/react-portal": "1.1.12",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-slot": "1.3.0",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-visually-hidden": "1.2.6"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-id": "1.1.3",
+        "@radix-ui/react-popper": "1.3.5",
+        "@radix-ui/react-portal": "1.1.15",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-slot": "1.3.1",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
+        "@radix-ui/react-visually-hidden": "1.2.9"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4653,9 +4631,9 @@
       }
     },
     "node_modules/@radix-ui/react-use-callback-ref": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.2.tgz",
-      "integrity": "sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.3.tgz",
+      "integrity": "sha512-AUS7HoBBAncIsGMLNG+CcpLuJ+JIBbZzmyM8Qdb1eIThX0AlhSSC6wn40xfBlPE+ypx/vSSiRWnklUAjy3U3UA==",
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "*",
@@ -4668,13 +4646,14 @@
       }
     },
     "node_modules/@radix-ui/react-use-controllable-state": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.3.tgz",
-      "integrity": "sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.5.tgz",
+      "integrity": "sha512-UB1dXpxvHjR48poyKdKdTm7jT0kp3elkUKdKQiOkirlbYumqXinSJtrjDsr9maXNPvL12bKI4CDSmydms/9Aeg==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-use-effect-event": "0.0.3",
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-use-effect-event": "0.0.4",
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4687,12 +4666,12 @@
       }
     },
     "node_modules/@radix-ui/react-use-effect-event": {
-      "version": "0.0.3",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-effect-event/-/react-use-effect-event-0.0.3.tgz",
-      "integrity": "sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==",
+      "version": "0.0.4",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-effect-event/-/react-use-effect-event-0.0.4.tgz",
+      "integrity": "sha512-XYcfa6wlXDCwQtePuEiPmXLSAhGL4DWtedSyRgGbG3y10mw+OnrLp6SyeY1gJFMiYF0Dx0nMAX9InylKbLEFQQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4705,12 +4684,12 @@
       }
     },
     "node_modules/@radix-ui/react-use-escape-keydown": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.1.2.tgz",
-      "integrity": "sha512-2uVLvLjgO7NZCWw01/FdqRwmA42J0BcjPMUCA+koFEOAb+zjqIP7SiFz/7zWPrKnVmSqr76Omq2ALyCuX4dhLw==",
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.1.4.tgz",
+      "integrity": "sha512-4MSb5SPbMH02uUn19tLkO5Bav66ZQg/zFbedo7FWLWGFg9r8Z9xSog7QGnq9ZceurzBVIAIwgzANg6ExWc8HkQ==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-use-callback-ref": "1.1.2"
+        "@radix-ui/react-use-callback-ref": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4723,9 +4702,9 @@
       }
     },
     "node_modules/@radix-ui/react-use-is-hydrated": {
-      "version": "0.1.1",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-is-hydrated/-/react-use-is-hydrated-0.1.1.tgz",
-      "integrity": "sha512-qwOiz4Tjo8CNnrOLAYUMXeZwDzXgXpvK4TKQPmWLECM9XoWvA6+0Z2/7Ag3A4ivjS4ovbLJPbskkxioFyBhr8A==",
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-is-hydrated/-/react-use-is-hydrated-0.1.2.tgz",
+      "integrity": "sha512-2+gAVu9uaSLbopCTvvuWX9MIgEOlyqXC1Ok+KLCO7cZPSHLENs7dL0KbFQUGFIcFKmDW/bmaQRJtd8E3cnMRUw==",
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "*",
@@ -4738,9 +4717,9 @@
       }
     },
     "node_modules/@radix-ui/react-use-layout-effect": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.2.tgz",
-      "integrity": "sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.3.tgz",
+      "integrity": "sha512-rDiah9wvtqihWtWz02XreeRKIxt2EJF8y5D9rtY9l5A2zxePAtcPiOMpDugNRw5bFHz+1/8viVoc7ZVKiJknCw==",
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "*",
@@ -4753,9 +4732,9 @@
       }
     },
     "node_modules/@radix-ui/react-use-previous": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-previous/-/react-use-previous-1.1.2.tgz",
-      "integrity": "sha512-IGBQPtRFdhN6MQ8dbegVmBq1LVZluya3F1jWY+puIcQC3MHctRwTDSBWCkL/3ZcnMJLTMJ++Z+ktmvg0F89iCw==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-previous/-/react-use-previous-1.1.3.tgz",
+      "integrity": "sha512-kbefNKla5AGhgvMqrg/qS7mYVLXTEHQLqoFIS03nKN2dAfQQ5PK5Tp+2LxS7BV6a6l4HHv4jTg6rtV2Uajwe2w==",
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "*",
@@ -4768,12 +4747,12 @@
       }
     },
     "node_modules/@radix-ui/react-use-rect": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.1.2.tgz",
-      "integrity": "sha512-d8a+bBY/FxikNPlgJJoaBHZX+zKVbWHYJGTLnLvveQgFSTntkGdEKv3JDtHrMS0DNYpllz2nRsTLGLKYttbpmw==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.1.3.tgz",
+      "integrity": "sha512-W0GSYZFKEfi6raMiMEfJSngvVbFDIyxtW5JuVg5NoQBY59l0dVQVGLbhog/tOdwq0qtZ+TXuX1ikSNan4/IZXA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/rect": "1.1.2"
+        "@radix-ui/rect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4786,12 +4765,12 @@
       }
     },
     "node_modules/@radix-ui/react-use-size": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.1.2.tgz",
-      "integrity": "sha512-giWQp+4mxjBPt4KZ0MmyuykFNWfbDxKt4x+fPkRYmgRFJSbCZFzUglvMb/Kjn38tm10YP4ufiQZDx3zna4LU6w==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.1.3.tgz",
+      "integrity": "sha512-jJq6tQQLvO/z4uWbztjwPV+1a/+H4rCaWypasLB/ac8DEdd6+p7dIm7o3F6P2KZPGkPMqD4s5424EdAdoU+GLA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-use-layout-effect": "1.1.2"
+        "@radix-ui/react-use-layout-effect": "1.1.3"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4804,12 +4783,12 @@
       }
     },
     "node_modules/@radix-ui/react-visually-hidden": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-visually-hidden/-/react-visually-hidden-1.2.6.tgz",
-      "integrity": "sha512-jCE0WljWifTI4niIMCll06kGpsJTAPiZVU9H4WR1N6qW7At9ystHbN7dDB+we2xH535roFHj7qKS+RGj0FMDWQ==",
+      "version": "1.2.9",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-visually-hidden/-/react-visually-hidden-1.2.9.tgz",
+      "integrity": "sha512-seuZXNZVCz1kLSQMRO/TdNOSahBI3S5nXE4jzO7u7aFRWQlMAnwyrr8vKMkEU115fCLEyzR2YyjnP+aRMxK34w==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/react-primitive": "2.1.6"
+        "@radix-ui/react-primitive": "2.1.8"
       },
       "peerDependencies": {
         "@types/react": "*",
@@ -4827,9 +4806,9 @@
       }
     },
     "node_modules/@radix-ui/rect": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.1.2.tgz",
-      "integrity": "sha512-xnXE7wG13PI+cxieVssYXlQJuYVRhH9NBoxt3KNwzghDIA69GMm7d4wXRouHIYjE+KvS6U/MsMO73NdS2MH9ZA==",
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.1.3.tgz",
+      "integrity": "sha512-JtyZR+mqgBibTo8xea3B6ZRmzZiM/YeVBtUkas6zMuXjAlfIFIW2FgqeM9eLyvEaYX66vr6DJMK+4U6LV0KhNw==",
       "license": "MIT"
     },
     "node_modules/@react-dnd/asap": {
@@ -16020,66 +15999,66 @@
       }
     },
     "node_modules/radix-ui": {
-      "version": "1.6.0",
-      "resolved": "https://registry.npmjs.org/radix-ui/-/radix-ui-1.6.0.tgz",
-      "integrity": "sha512-EUEC70O03EgxWMP5aoqfBZ6iLC5bczFagGy7zhSYRt8o5DP7IWNiP3ywetse3L9b8843ExB0OGWZvgbYVJuNeg==",
+      "version": "1.6.5",
+      "resolved": "https://registry.npmjs.org/radix-ui/-/radix-ui-1.6.5.tgz",
+      "integrity": "sha512-HVHPWDoOXBYxxiwvWR45KPcmvrjoa/NTFUbPbGmYoZv7BFYOIpZKiPQZWcpFJTX5z4LeoGenGCUgoafdYHuPWA==",
       "license": "MIT",
       "dependencies": {
-        "@radix-ui/primitive": "1.1.4",
-        "@radix-ui/react-accessible-icon": "1.1.10",
-        "@radix-ui/react-accordion": "1.2.14",
-        "@radix-ui/react-alert-dialog": "1.1.17",
-        "@radix-ui/react-arrow": "1.1.10",
-        "@radix-ui/react-aspect-ratio": "1.1.10",
-        "@radix-ui/react-avatar": "1.2.0",
-        "@radix-ui/react-checkbox": "1.3.5",
-        "@radix-ui/react-collapsible": "1.1.14",
-        "@radix-ui/react-collection": "1.1.10",
-        "@radix-ui/react-compose-refs": "1.1.3",
-        "@radix-ui/react-context": "1.1.4",
-        "@radix-ui/react-context-menu": "2.3.1",
-        "@radix-ui/react-dialog": "1.1.17",
-        "@radix-ui/react-direction": "1.1.2",
-        "@radix-ui/react-dismissable-layer": "1.1.13",
-        "@radix-ui/react-dropdown-menu": "2.1.18",
-        "@radix-ui/react-focus-guards": "1.1.4",
-        "@radix-ui/react-focus-scope": "1.1.10",
-        "@radix-ui/react-form": "0.1.10",
-        "@radix-ui/react-hover-card": "1.1.17",
-        "@radix-ui/react-label": "2.1.10",
-        "@radix-ui/react-menu": "2.1.18",
-        "@radix-ui/react-menubar": "1.1.18",
-        "@radix-ui/react-navigation-menu": "1.2.16",
-        "@radix-ui/react-one-time-password-field": "0.1.10",
-        "@radix-ui/react-password-toggle-field": "0.1.5",
-        "@radix-ui/react-popover": "1.1.17",
-        "@radix-ui/react-popper": "1.3.1",
-        "@radix-ui/react-portal": "1.1.12",
-        "@radix-ui/react-presence": "1.1.6",
-        "@radix-ui/react-primitive": "2.1.6",
-        "@radix-ui/react-progress": "1.1.10",
-        "@radix-ui/react-radio-group": "1.4.1",
-        "@radix-ui/react-roving-focus": "1.1.13",
-        "@radix-ui/react-scroll-area": "1.2.12",
-        "@radix-ui/react-select": "2.3.1",
-        "@radix-ui/react-separator": "1.1.10",
-        "@radix-ui/react-slider": "1.4.1",
-        "@radix-ui/react-slot": "1.3.0",
-        "@radix-ui/react-switch": "1.3.1",
-        "@radix-ui/react-tabs": "1.1.15",
-        "@radix-ui/react-toast": "1.2.17",
-        "@radix-ui/react-toggle": "1.1.12",
-        "@radix-ui/react-toggle-group": "1.1.13",
-        "@radix-ui/react-toolbar": "1.1.13",
-        "@radix-ui/react-tooltip": "1.2.10",
-        "@radix-ui/react-use-callback-ref": "1.1.2",
-        "@radix-ui/react-use-controllable-state": "1.2.3",
-        "@radix-ui/react-use-effect-event": "0.0.3",
-        "@radix-ui/react-use-escape-keydown": "1.1.2",
-        "@radix-ui/react-use-is-hydrated": "0.1.1",
-        "@radix-ui/react-use-layout-effect": "1.1.2",
-        "@radix-ui/react-use-size": "1.1.2",
-        "@radix-ui/react-visually-hidden": "1.2.6"
+        "@radix-ui/primitive": "1.1.7",
+        "@radix-ui/react-accessible-icon": "1.1.13",
+        "@radix-ui/react-accordion": "1.2.18",
+        "@radix-ui/react-alert-dialog": "1.1.21",
+        "@radix-ui/react-arrow": "1.1.13",
+        "@radix-ui/react-aspect-ratio": "1.1.13",
+        "@radix-ui/react-avatar": "1.2.4",
+        "@radix-ui/react-checkbox": "1.3.9",
+        "@radix-ui/react-collapsible": "1.1.18",
+        "@radix-ui/react-collection": "1.1.13",
+        "@radix-ui/react-compose-refs": "1.1.4",
+        "@radix-ui/react-context": "1.2.1",
+        "@radix-ui/react-context-menu": "2.3.5",
+        "@radix-ui/react-dialog": "1.1.21",
+        "@radix-ui/react-direction": "1.1.3",
+        "@radix-ui/react-dismissable-layer": "1.1.17",
+        "@radix-ui/react-dropdown-menu": "2.1.22",
+        "@radix-ui/react-focus-guards": "1.1.5",
+        "@radix-ui/react-focus-scope": "1.1.14",
+        "@radix-ui/react-form": "0.1.14",
+        "@radix-ui/react-hover-card": "1.1.21",
+        "@radix-ui/react-label": "2.1.13",
+        "@radix-ui/react-menu": "2.1.22",
+        "@radix-ui/react-menubar": "1.1.22",
+        "@radix-ui/react-navigation-menu": "1.2.20",
+        "@radix-ui/react-one-time-password-field": "0.1.14",
+        "@radix-ui/react-password-toggle-field": "0.1.9",
+        "@radix-ui/react-popover": "1.1.21",
+        "@radix-ui/react-popper": "1.3.5",
+        "@radix-ui/react-portal": "1.1.15",
+        "@radix-ui/react-presence": "1.1.9",
+        "@radix-ui/react-primitive": "2.1.8",
+        "@radix-ui/react-progress": "1.1.14",
+        "@radix-ui/react-radio-group": "1.4.5",
+        "@radix-ui/react-roving-focus": "1.1.17",
+        "@radix-ui/react-scroll-area": "1.2.16",
+        "@radix-ui/react-select": "2.3.5",
+        "@radix-ui/react-separator": "1.1.13",
+        "@radix-ui/react-slider": "1.4.5",
+        "@radix-ui/react-slot": "1.3.1",
+        "@radix-ui/react-switch": "1.3.5",
+        "@radix-ui/react-tabs": "1.1.19",
+        "@radix-ui/react-toast": "1.2.21",
+        "@radix-ui/react-toggle": "1.1.16",
+        "@radix-ui/react-toggle-group": "1.1.17",
+        "@radix-ui/react-toolbar": "1.1.17",
+        "@radix-ui/react-tooltip": "1.2.14",
+        "@radix-ui/react-use-callback-ref": "1.1.3",
+        "@radix-ui/react-use-controllable-state": "1.2.5",
+        "@radix-ui/react-use-effect-event": "0.0.4",
+        "@radix-ui/react-use-escape-keydown": "1.1.4",
+        "@radix-ui/react-use-is-hydrated": "0.1.2",
+        "@radix-ui/react-use-layout-effect": "1.1.3",
+        "@radix-ui/react-use-size": "1.1.3",
+        "@radix-ui/react-visually-hidden": "1.2.9"
       },
       "peerDependencies": {
         "@types/react": "*",
diff --git a/plugins/cron_providers/__init__.py b/plugins/cron_providers/__init__.py
index 456c81b41e3..79dd1a2256e 100644
--- a/plugins/cron_providers/__init__.py
+++ b/plugins/cron_providers/__init__.py
@@ -86,7 +86,7 @@ def _is_cron_provider_dir(path: Path) -> bool:
     if not init_file.exists():
         return False
     try:
-        source = init_file.read_text(errors="replace")[:8192]
+        source = init_file.read_text(errors="replace", encoding="utf-8")[:8192]
         return "register_cron_scheduler" in source or "CronScheduler" in source
     except Exception:
         return False
diff --git a/plugins/disk-cleanup/disk_cleanup.py b/plugins/disk-cleanup/disk_cleanup.py
index 1e1d453f80a..31f5779b1ff 100755
--- a/plugins/disk-cleanup/disk_cleanup.py
+++ b/plugins/disk-cleanup/disk_cleanup.py
@@ -110,12 +110,12 @@ def load_tracked() -> List[Dict[str, Any]]:
         return []
 
     try:
-        return json.loads(tf.read_text())
+        return json.loads(tf.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, ValueError):
         bak = tf.with_suffix(".json.bak")
         if bak.exists():
             try:
-                data = json.loads(bak.read_text())
+                data = json.loads(bak.read_text(encoding="utf-8"))
                 _log("WARN: tracked.json corrupted — restored from .bak")
                 return data
             except Exception:
@@ -129,7 +129,7 @@ def save_tracked(tracked: List[Dict[str, Any]]) -> None:
     tf = get_tracked_file()
     tf.parent.mkdir(parents=True, exist_ok=True)
     tmp = tf.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(tracked, indent=2))
+    tmp.write_text(json.dumps(tracked, indent=2), encoding="utf-8")
     if tf.exists():
         shutil.copy2(tf, tf.with_suffix(".json.bak"))
     tmp.replace(tf)
diff --git a/plugins/google_meet/audio_bridge.py b/plugins/google_meet/audio_bridge.py
index 7650c54f570..8159c21c172 100644
--- a/plugins/google_meet/audio_bridge.py
+++ b/plugins/google_meet/audio_bridge.py
@@ -111,7 +111,7 @@ class AudioBridge:
                 ],
                 check=True,
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 stdin=subprocess.DEVNULL,
             )
         except FileNotFoundError as exc:
@@ -136,7 +136,7 @@ class AudioBridge:
                 ],
                 check=True,
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 stdin=subprocess.DEVNULL,
             )
         except subprocess.CalledProcessError as exc:
@@ -172,7 +172,7 @@ class AudioBridge:
         try:
             out = subprocess.check_output(
                 ["system_profiler", "SPAudioDataType"],
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 stderr=subprocess.STDOUT,
             )
         except FileNotFoundError as exc:
diff --git a/plugins/google_meet/cli.py b/plugins/google_meet/cli.py
index 1ab0c0fd73d..45fede03813 100644
--- a/plugins/google_meet/cli.py
+++ b/plugins/google_meet/cli.py
@@ -293,7 +293,7 @@ def _cmd_install(*, realtime: bool, assume_yes: bool) -> int:
         elif system == "Darwin":
             have_bh = False
             try:
-                out = _sp.check_output(["system_profiler", "SPAudioDataType"], text=True)
+                out = _sp.check_output(["system_profiler", "SPAudioDataType"], text=True, encoding='utf-8', errors='replace')
                 have_bh = "BlackHole" in out
             except Exception:
                 pass
diff --git a/plugins/google_meet/meet_bot.py b/plugins/google_meet/meet_bot.py
index 211e08d4c69..0396d039490 100644
--- a/plugins/google_meet/meet_bot.py
+++ b/plugins/google_meet/meet_bot.py
@@ -425,7 +425,7 @@ def _mac_audio_device_index(device_name: str) -> str:
         out = _sp.run(
             ["ffmpeg", "-f", "avfoundation", "-list_devices", "true", "-i", ""],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
         )
     except Exception:
diff --git a/plugins/google_meet/realtime/openai_client.py b/plugins/google_meet/realtime/openai_client.py
index 24527603e52..2e84c89125c 100644
--- a/plugins/google_meet/realtime/openai_client.py
+++ b/plugins/google_meet/realtime/openai_client.py
@@ -262,7 +262,7 @@ class RealtimeSpeaker:
         if not self.queue_path.exists():
             return []
         out: list[dict] = []
-        for line in self.queue_path.read_text().splitlines():
+        for line in self.queue_path.read_text(encoding="utf-8").splitlines():
             line = line.strip()
             if not line:
                 continue
@@ -281,10 +281,10 @@ class RealtimeSpeaker:
         if not remaining:
             # Keep the file but empty — consumers may be watching for
             # new writes via mtime, and delete-then-recreate is a race.
-            self.queue_path.write_text("")
+            self.queue_path.write_text("", encoding="utf-8")
             return
         self.queue_path.write_text(
-            "\n".join(json.dumps(e) for e in remaining) + "\n"
+            "\n".join(json.dumps(e) for e in remaining) + "\n", encoding="utf-8"
         )
 
     def _append_processed(self, entry: dict, result: dict) -> None:
diff --git a/plugins/hermes-achievements/dashboard/plugin_api.py b/plugins/hermes-achievements/dashboard/plugin_api.py
index b419efc6c27..c2f69a22999 100644
--- a/plugins/hermes-achievements/dashboard/plugin_api.py
+++ b/plugins/hermes-achievements/dashboard/plugin_api.py
@@ -159,7 +159,7 @@ def load_state() -> Dict[str, Any]:
     if not path.exists():
         return {"unlocks": {}}
     try:
-        return json.loads(path.read_text())
+        return json.loads(path.read_text(encoding="utf-8"))
     except Exception:
         return {"unlocks": {}}
 
@@ -167,7 +167,7 @@ def load_state() -> Dict[str, Any]:
 def save_state(state: Dict[str, Any]) -> None:
     path = state_path()
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(state, indent=2, sort_keys=True))
+    path.write_text(json.dumps(state, indent=2, sort_keys=True), encoding="utf-8")
 
 
 def _json_safe(value: Any) -> Any:
@@ -185,7 +185,7 @@ def load_snapshot() -> Optional[Dict[str, Any]]:
     if not path.exists():
         return None
     try:
-        data = json.loads(path.read_text())
+        data = json.loads(path.read_text(encoding="utf-8"))
         if isinstance(data, dict):
             return data
     except Exception:
@@ -196,7 +196,7 @@ def load_snapshot() -> Optional[Dict[str, Any]]:
 def save_snapshot(data: Dict[str, Any]) -> None:
     path = snapshot_path()
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(_json_safe(data), indent=2, sort_keys=True))
+    path.write_text(json.dumps(_json_safe(data), indent=2, sort_keys=True), encoding="utf-8")
 
 
 def load_checkpoint() -> Dict[str, Any]:
@@ -204,7 +204,7 @@ def load_checkpoint() -> Dict[str, Any]:
     if not path.exists():
         return {"schema_version": 1, "generated_at": 0, "sessions": {}}
     try:
-        data = json.loads(path.read_text())
+        data = json.loads(path.read_text(encoding="utf-8"))
         if isinstance(data, dict):
             data.setdefault("schema_version", 1)
             data.setdefault("generated_at", 0)
@@ -219,7 +219,7 @@ def load_checkpoint() -> Dict[str, Any]:
 def save_checkpoint(data: Dict[str, Any]) -> None:
     path = checkpoint_path()
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(_json_safe(data), indent=2, sort_keys=True))
+    path.write_text(json.dumps(_json_safe(data), indent=2, sort_keys=True), encoding="utf-8")
 
 
 def session_fingerprint(meta: Dict[str, Any]) -> Dict[str, Any]:
diff --git a/plugins/image_gen/openai-codex/__init__.py b/plugins/image_gen/openai-codex/__init__.py
index d8d5ea80d97..2cee3360516 100644
--- a/plugins/image_gen/openai-codex/__init__.py
+++ b/plugins/image_gen/openai-codex/__init__.py
@@ -40,30 +40,43 @@ from agent.image_gen_provider import (
 logger = logging.getLogger(__name__)
 
 
-class CodexImageGenerationUnsupportedError(RuntimeError):
-    """The active Codex account cannot use the hosted image tool."""
+# NOTE: do NOT reintroduce an "account capability" classifier keyed on
+# ``Tool choice 'image_generation' not found in 'tools' parameter``. That HTTP
+# 400 is a *request-shape* rejection (the Codex backend resolves tool_choice as
+# a function-tool name and never recognizes hosted-tool entries) — it is
+# emitted for every account, including accounts where image generation works.
+# A previous version of this file translated that 400 into "Image generation is
+# not enabled for the current Codex account. Switch the image provider to
+# OpenAI API key, FAL, or xAI.", which reported a universal bug in our own
+# payload as the user's entitlement problem and sent people away from a
+# provider that was never actually tried. The request-shape bug is fixed by
+# omitting tool_choice (see ``_build_responses_payload``); any remaining HTTP
+# error must surface verbatim so it stays diagnosable. See issues #19505,
+# #49008 and #31335.
+
+_MAX_ERROR_BODY_CHARS = 500
 
 
-_IMAGE_GENERATION_UNAVAILABLE_MESSAGE = (
-    "Image generation is not enabled for the current Codex account. "
-    "Switch the image provider to OpenAI API key, FAL, or xAI."
-)
-_IMAGE_GENERATION_UNSUPPORTED_ERROR = (
-    "Tool choice 'image_generation' not found in 'tools' parameter."
-)
+def _summarize_error_body(body: str) -> str:
+    """Return a bounded, information-preserving summary of an error body.
 
-
-def _is_image_generation_unsupported_error(status_code: int, body: str) -> bool:
-    """Match only Codex's account-capability rejection for the image tool."""
-    if status_code != 400:
-        return False
+    Prefers the parsed ``error.message`` field, because a blind head-truncation
+    of the raw body can cut the actual message off entirely — Codex error
+    payloads sometimes carry hundreds of bytes of leading metadata, so
+    ``body[:500]`` yielded a wall of padding and no diagnosis. Falls back to a
+    truncated raw body for non-JSON responses.
+    """
+    text = body or ""
     try:
-        payload = json.loads(body)
+        payload = json.loads(text)
         error = payload.get("error") if isinstance(payload, dict) else None
         message = error.get("message") if isinstance(error, dict) else None
+        if isinstance(message, str) and message.strip():
+            return message.strip()[:_MAX_ERROR_BODY_CHARS]
     except (TypeError, ValueError):
-        message = body
-    return isinstance(message, str) and message.strip() == _IMAGE_GENERATION_UNSUPPORTED_ERROR
+        pass
+    return text[:_MAX_ERROR_BODY_CHARS]
+
 
 
 # ---------------------------------------------------------------------------
@@ -307,11 +320,15 @@ def _build_responses_payload(
             "background": "opaque",
             "partial_images": 1,
         }],
-        "tool_choice": {
-            "type": "allowed_tools",
-            "mode": "required",
-            "tools": [{"type": "image_generation"}],
-        },
+        # No ``tool_choice`` is sent: the chatgpt.com/backend-api/codex backend
+        # rejects every shape we have for forcing the hosted ``image_generation``
+        # tool. ``{"type": "allowed_tools", "mode": "required", "tools": [{"type":
+        # "image_generation"}]}`` (and the simpler ``{"type": "image_generation"}``
+        # form) both 400 with ``Tool choice 'image_generation' not found in 'tools'
+        # parameter`` — the backend looks up tool_choice as a *function* name and
+        # never recognizes hosted-tool entries. Letting the host model decide is
+        # the only shape Codex currently accepts; the ``instructions`` above are
+        # what nudge it toward the tool. See issue #19505.
         "stream": True,
     }
 
@@ -419,15 +436,9 @@ def _collect_image_b64(
                 response.raise_for_status()
             except httpx.HTTPStatusError as exc:
                 exc.response.read()
-                full_body = exc.response.text
-                if _is_image_generation_unsupported_error(
-                    exc.response.status_code,
-                    full_body,
-                ):
-                    raise CodexImageGenerationUnsupportedError(full_body) from exc
-                body = full_body[:500]
                 raise RuntimeError(
-                    f"Codex Responses API returned HTTP {exc.response.status_code}: {body}"
+                    f"Codex Responses API returned HTTP {exc.response.status_code}: "
+                    f"{_summarize_error_body(exc.response.text)}"
                 ) from exc
             for event in _iter_sse_json(response):
                 found = _extract_image_b64(event)
@@ -574,19 +585,6 @@ class OpenAICodexImageGenProvider(ImageGenProvider):
                 quality=meta["quality"],
                 input_images=input_images or None,
             )
-        except CodexImageGenerationUnsupportedError:
-            logger.debug(
-                "Codex account does not expose image generation",
-                exc_info=True,
-            )
-            return error_response(
-                error=_IMAGE_GENERATION_UNAVAILABLE_MESSAGE,
-                error_type="capability_unsupported",
-                provider="openai-codex",
-                model=tier_id,
-                prompt=prompt,
-                aspect_ratio=aspect,
-            )
         except Exception as exc:
             logger.debug("Codex image generation failed", exc_info=True)
             return error_response(
diff --git a/plugins/kanban/dashboard/plugin_api.py b/plugins/kanban/dashboard/plugin_api.py
index fa3edd135d7..51feb4f1c3c 100644
--- a/plugins/kanban/dashboard/plugin_api.py
+++ b/plugins/kanban/dashboard/plugin_api.py
@@ -647,7 +647,15 @@ def create_task(payload: CreateTaskBody, board: Optional[str] = Query(None)):
         if task and task.status == "ready" and task.assignee:
             try:
                 from hermes_cli.kanban import _check_dispatcher_presence
-                running, message = _check_dispatcher_presence()
+                from hermes_constants import get_hermes_home
+
+                # Scope the probe to the request's active home. The dashboard
+                # backend can run under a different HERMES_HOME than the
+                # profile this board belongs to, which otherwise warned "no
+                # gateway is running" against a live profile gateway (#71211).
+                running, message = _check_dispatcher_presence(
+                    hermes_home=get_hermes_home()
+                )
                 if not running and message:
                     body["warning"] = message
             except Exception:
diff --git a/plugins/memory/__init__.py b/plugins/memory/__init__.py
index cccda75ce84..53eeb998a0e 100644
--- a/plugins/memory/__init__.py
+++ b/plugins/memory/__init__.py
@@ -81,7 +81,7 @@ def _is_memory_provider_dir(path: Path) -> bool:
     if not init_file.exists():
         return False
     try:
-        source = init_file.read_text(errors="replace")[:8192]
+        source = init_file.read_text(errors="replace", encoding="utf-8")[:8192]
         return "register_memory_provider" in source or "MemoryProvider" in source
     except Exception:
         return False
diff --git a/plugins/memory/byterover/__init__.py b/plugins/memory/byterover/__init__.py
index 5161bacf413..dd5cf3b2b88 100644
--- a/plugins/memory/byterover/__init__.py
+++ b/plugins/memory/byterover/__init__.py
@@ -140,7 +140,7 @@ def _run_brv(args: List[str], timeout: int = _QUERY_TIMEOUT,
 
     try:
         result = subprocess.run(
-            cmd, capture_output=True, text=True,
+            cmd, capture_output=True, text=True, encoding='utf-8', errors='replace',
             timeout=timeout, cwd=effective_cwd, env=env,
             stdin=subprocess.DEVNULL,
         )
diff --git a/plugins/memory/hindsight/__init__.py b/plugins/memory/hindsight/__init__.py
index 9f5974b7b54..00b6d7a8f8e 100644
--- a/plugins/memory/hindsight/__init__.py
+++ b/plugins/memory/hindsight/__init__.py
@@ -496,7 +496,9 @@ def _load_simple_env(path) -> dict[str, str]:
         return {}
 
     values: dict[str, str] = {}
-    for line in path.read_text(encoding="utf-8").splitlines():
+    # utf-8-sig, not plain utf-8: this is also used on the Hermes .env during
+    # post_setup, and a Notepad BOM would otherwise stick to the first key.
+    for line in path.read_text(encoding="utf-8-sig", errors="replace").splitlines():
         if not line or line.startswith("#") or "=" not in line:
             continue
         key, value = line.split("=", 1)
@@ -746,7 +748,7 @@ class HindsightMemoryProvider(MemoryProvider):
         existing = {}
         if config_path.exists():
             try:
-                existing = json.loads(config_path.read_text())
+                existing = json.loads(config_path.read_text(encoding="utf-8"))
             except Exception:
                 pass
         existing.update(values)
@@ -895,7 +897,8 @@ class HindsightMemoryProvider(MemoryProvider):
                 env_path = Path(hermes_home) / ".env"
                 existing_llm_key = ""
                 if env_path.exists():
-                    for line in env_path.read_text().splitlines():
+                    # utf-8-sig: a Notepad BOM must not hide the first key.
+                    for line in env_path.read_text(encoding="utf-8-sig").splitlines():
                         if line.startswith("HINDSIGHT_LLM_API_KEY="):
                             existing_llm_key = line.split("=", 1)[1]
                             break
@@ -925,7 +928,10 @@ class HindsightMemoryProvider(MemoryProvider):
             env_path.parent.mkdir(parents=True, exist_ok=True)
             existing_lines = []
             if env_path.exists():
-                existing_lines = env_path.read_text().splitlines()
+                # utf-8-sig: a Notepad BOM would glue U+FEFF onto the first
+                # key, defeating the in-place update below and appending a
+                # duplicate line instead.
+                existing_lines = env_path.read_text(encoding="utf-8-sig").splitlines()
             updated_keys = set()
             new_lines = []
             for line in existing_lines:
@@ -938,7 +944,7 @@ class HindsightMemoryProvider(MemoryProvider):
             for k, v in env_writes.items():
                 if k not in updated_keys:
                     new_lines.append(f"{k}={v}")
-            env_path.write_text("\n".join(new_lines) + "\n")
+            env_path.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
 
         if mode == "local_embedded":
             materialized_config = dict(provider_config)
diff --git a/plugins/memory/honcho/README.md b/plugins/memory/honcho/README.md
index ac9c2201c5b..e7d41d1cf52 100644
--- a/plugins/memory/honcho/README.md
+++ b/plugins/memory/honcho/README.md
@@ -17,10 +17,12 @@ hermes memory setup honcho   # configure Honcho directly (works on a fresh insta
 hermes memory setup          # generic picker, choose Honcho from the list
 ```
 
-For cloud, the wizard asks **OAuth or API key**. OAuth opens a browser
-sign-in and stores the grant itself — nothing to copy; tokens refresh
-automatically. The desktop app offers the same flow as a **Connect** link
-next to the memory-provider dropdown.
+For cloud, the wizard asks **OAuth, device code, or API key**. OAuth opens a
+browser sign-in and stores the grant itself — nothing to copy; tokens refresh
+automatically. On SSH/headless machines choose **device**: the CLI prints a
+short code and a link you open in a browser on any other machine; setup
+completes once you approve there. The desktop app offers the browser flow as
+a **Connect** link next to the memory-provider dropdown.
 
 Or manually:
 ```bash
@@ -347,6 +349,7 @@ Presets:
 | `HONCHO_OAUTH_DASHBOARD` | OAuth authorize origin (default: cloud dashboard; local-dev `localhost:3000`) |
 | `HONCHO_OAUTH_AUTHORIZE_URL` | Full authorize URL (overrides the dashboard origin) |
 | `HONCHO_OAUTH_TOKEN_URL` | Token endpoint (default: cloud API; local-dev `localhost:8000`) |
+| `HONCHO_OAUTH_DEVICE_AUTH_URL` | Device-authorization endpoint (default: derived from the token URL) |
 | `HONCHO_OAUTH_CLIENT_ID` | OAuth client (default `hermes-agent`) |
 | `HONCHO_OAUTH_SCOPE` | Requested scope (default `write`) |
 
diff --git a/plugins/memory/honcho/__init__.py b/plugins/memory/honcho/__init__.py
index 8ac56aec27d..c90734ad8a0 100644
--- a/plugins/memory/honcho/__init__.py
+++ b/plugins/memory/honcho/__init__.py
@@ -317,7 +317,7 @@ class HonchoMemoryProvider(MemoryProvider):
         existing = {}
         if config_path.exists():
             try:
-                existing = json.loads(config_path.read_text())
+                existing = json.loads(config_path.read_text(encoding="utf-8"))
             except Exception:
                 pass
         existing.update(values)
diff --git a/plugins/memory/honcho/cli.py b/plugins/memory/honcho/cli.py
index b517367704e..7c2b87a8ba1 100644
--- a/plugins/memory/honcho/cli.py
+++ b/plugins/memory/honcho/cli.py
@@ -620,7 +620,7 @@ def cmd_setup(args) -> None:
                 print("\n  No local JWT set. Local no-auth ready.")
     use_oauth = False
     if not is_local:
-        # --- Cloud: OAuth (browser) or API key ---
+        # --- Cloud: OAuth (browser), device code, or API key ---
         cfg.pop("baseUrl", None)  # cloud uses SDK default
 
         # Detect an existing OAuth grant so re-running setup reflects it instead
@@ -628,15 +628,88 @@ def cmd_setup(args) -> None:
         from plugins.memory.honcho.oauth import OAuthCredential
         existing_oauth = OAuthCredential.from_host_block(hermes_host)
 
+        device_available = _device_login_available()
+        is_remote, can_browse = _headless()
+
         print("\n  Auth method:")
         if existing_oauth is not None:
             print(f"    (currently connected via OAuth — client {existing_oauth.client_id})")
-        print("    oauth  -- sign in via browser (recommended)")
+        print("    oauth  -- sign in via browser on this machine (recommended)")
+        if device_available:
+            print("    device -- device code: approve from a browser on another machine (SSH / headless)")
         print("    apikey -- paste an API key from https://app.honcho.dev")
-        method = _prompt("OAuth or API key?", default="oauth").strip().lower()
-        use_oauth = method in {"oauth", "o"}
 
-        if use_oauth:
+        default_method = "oauth"
+        if is_remote or not can_browse:
+            if device_available:
+                print("  (no usable local browser detected — device code recommended)")
+                default_method = "device"
+            else:
+                print("  (no usable local browser detected — browser sign-in may need an SSH tunnel to 127.0.0.1:8765)")
+        prompt_label = "oauth, device, or apikey?" if device_available else "OAuth or API key?"
+        method = _prompt(prompt_label, default=default_method).strip().lower()
+        use_oauth = method in {"oauth", "o"}
+        use_device = device_available and method in {"device", "d"}
+
+        if use_device:
+            from plugins.memory.honcho.oauth_flow import (
+                AccessDenied,
+                AuthorizationTimeout,
+                DeviceCode,
+                DeviceCodeExpired,
+                DeviceFlowError,
+                authorize_via_device_code,
+            )
+
+            def _show(device: DeviceCode) -> None:
+                print("\n  To connect, on any device with a browser:")
+                print(f"\n    1. Open   {device.verification_uri}")
+                print(f"    2. Enter  {device.user_code}")
+                print(f"\n  Or open directly:\n\n    {device.verification_uri_complete}\n")
+                mins = max(1, device.expires_in // 60)
+                print(f"  Waiting for approval (expires in {mins} min, Ctrl-C to cancel) ", end="", flush=True)
+
+            def _open_local(url: str) -> None:
+                import webbrowser
+
+                webbrowser.open(url)
+
+            print("\n  Requesting device code…")
+            try:
+                cred = authorize_via_device_code(
+                    config_path=write_path,
+                    source="hermes-cli",
+                    apply_config=False,
+                    display=_show,
+                    open_url=_open_local if can_browse and not is_remote else None,
+                    on_poll=lambda: print(".", end="", flush=True),
+                )
+            except KeyboardInterrupt:
+                print("\n  Cancelled. Re-run 'hermes honcho setup' to try again.\n")
+                return
+            except (AuthorizationTimeout, DeviceCodeExpired):
+                print("\n  Device code expired before approval.")
+                print("  Re-run 'hermes honcho setup' to get a new code.\n")
+                return
+            except AccessDenied:
+                print("\n  Sign-in was denied on the approval page.")
+                print("  Re-run 'hermes honcho setup' to retry, or choose an API key instead.\n")
+                return
+            except DeviceFlowError as e:
+                if e.error == "http_429":
+                    print("\n  Too many device-code requests — wait a minute and re-run setup.\n")
+                else:
+                    print(f"\n  Device sign-in failed: {e}")
+                    print("  Re-run 'hermes honcho setup' to retry, or choose an API key instead.\n")
+                return
+            except Exception as e:
+                print(f"\n  Device sign-in failed: {e}")
+                print("  Re-run 'hermes honcho setup' to retry, or choose an API key instead.\n")
+                return
+            print(" approved")
+            _apply_grant_to_host(hermes_host, cred)
+            print("  Authorized — token saved. Let's finish configuring.\n")
+        elif use_oauth:
             # Sign in now, up front — the browser link is the whole point, so
             # don't bury it behind the identity prompts. The grant's tokens are
             # merged into the in-memory cfg so the wizard's final save preserves
@@ -661,11 +734,7 @@ def cmd_setup(args) -> None:
                 print(f"  OAuth sign-in failed: {e}")
                 print("  Re-run 'hermes honcho setup' to retry, or choose an API key instead.\n")
                 return
-            hermes_host["apiKey"] = cred.access_token
-            hermes_host["oauth"] = cred.oauth_block()
-            # Default the peer prompt to the name entered at consent.
-            if cred.consent_peer_name:
-                hermes_host["peerName"] = cred.consent_peer_name
+            _apply_grant_to_host(hermes_host, cred)
             print("  Authorized — token saved. Let's finish configuring.\n")
         else:
             current_key = cfg.get("apiKey", "")
@@ -974,6 +1043,35 @@ def cmd_setup(args) -> None:
     print("    hermes honcho map <name> -- map this directory to a session name\n")
 
 
+def _device_login_available() -> bool:
+    """Whether the resolved host offers the RFC 8628 device grant. Fails closed."""
+    try:
+        from plugins.memory.honcho.oauth_flow import resolve_endpoints, supports_device_login
+
+        return supports_device_login(resolve_endpoints())
+    except Exception:
+        return False
+
+
+def _headless() -> tuple[bool, bool]:
+    """(is_remote, can_open_browser) — degrades safely if hermes_cli internals move."""
+    try:
+        from hermes_cli.auth import _can_open_graphical_browser, _is_remote_session
+
+        return _is_remote_session(), _can_open_graphical_browser()
+    except Exception:
+        return False, True
+
+
+def _apply_grant_to_host(hermes_host: dict, cred) -> None:
+    """Store an OAuth grant on the host block; the wizard's final save persists it."""
+    hermes_host["apiKey"] = cred.access_token
+    hermes_host["oauth"] = cred.oauth_block()
+    # Default the peer prompt to the name entered at consent.
+    if cred.consent_peer_name:
+        hermes_host["peerName"] = cred.consent_peer_name
+
+
 def _active_profile_name() -> str:
     """Return the active Hermes profile name (respects --target-profile override)."""
     if _profile_override:
diff --git a/plugins/memory/honcho/client.py b/plugins/memory/honcho/client.py
index a1b6552abaa..cc1da55ffaf 100644
--- a/plugins/memory/honcho/client.py
+++ b/plugins/memory/honcho/client.py
@@ -742,7 +742,7 @@ class HonchoClientConfig:
         try:
             root = subprocess.run(
                 ["git", "rev-parse", "--show-toplevel"],
-                capture_output=True, text=True, cwd=cwd, timeout=5,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', cwd=cwd, timeout=5,
                 stdin=subprocess.DEVNULL,
             )
             if root.returncode == 0:
diff --git a/plugins/memory/honcho/oauth.py b/plugins/memory/honcho/oauth.py
index 0926ab2f0cc..3d7cbbd02c8 100644
--- a/plugins/memory/honcho/oauth.py
+++ b/plugins/memory/honcho/oauth.py
@@ -175,6 +175,36 @@ def _http_post_form(url: str, data: dict[str, str], timeout: float) -> dict[str,
     return resp.json()
 
 
+def _http_post_form_status(
+    url: str, data: dict[str, str], timeout: float
+) -> tuple[int, dict[str, Any]]:
+    """POST form-encoded ``data``; return ``(status, parsed JSON body)``.
+
+    Unlike ``_http_post_form``, 4xx does not raise — RFC 8628 polling reads the
+    OAuth error body off a 400. A non-JSON body parses to ``{}``.
+    """
+    import httpx
+
+    resp = httpx.post(url, data=data, timeout=timeout)
+    try:
+        body = resp.json()
+    except ValueError:
+        body = {}
+    if not isinstance(body, dict):
+        body = {}
+    return resp.status_code, body
+
+
+def _http_get_json(url: str, timeout: float) -> dict[str, Any]:
+    """GET ``url`` and return the parsed JSON body. Raises on non-2xx/non-JSON."""
+    import httpx
+
+    resp = httpx.get(url, timeout=timeout)
+    resp.raise_for_status()
+    body = resp.json()
+    return body if isinstance(body, dict) else {}
+
+
 def _exchange_refresh_token(cred: OAuthCredential, *, now: float) -> OAuthCredential:
     """Run the refresh_token grant and return the rotated credential.
 
diff --git a/plugins/memory/honcho/oauth_flow.py b/plugins/memory/honcho/oauth_flow.py
index fad4cc9c86e..b1268c02d44 100644
--- a/plugins/memory/honcho/oauth_flow.py
+++ b/plugins/memory/honcho/oauth_flow.py
@@ -62,6 +62,7 @@ class OAuthEndpoints:
     token_url: str  # API /oauth/token
     client_id: str
     scope: str
+    device_authorization_url: str = ""  # API /oauth/device_authorization
 
 
 # Cloud (production) hosts; dashboard serves /authorize, API serves /oauth/token.
@@ -107,11 +108,15 @@ def resolve_endpoints(
         default_token = f"{base_url.rstrip('/')}/oauth/token"
 
     dashboard = os.environ.get("HONCHO_OAUTH_DASHBOARD", default_dashboard).rstrip("/")
+    token_url = os.environ.get("HONCHO_OAUTH_TOKEN_URL", default_token)
+    # Device authorization rides the token endpoint's origin.
+    default_device = f"{token_url.rsplit('/', 1)[0]}/device_authorization"
     return OAuthEndpoints(
         authorize_url=os.environ.get("HONCHO_OAUTH_AUTHORIZE_URL", f"{dashboard}/authorize"),
-        token_url=os.environ.get("HONCHO_OAUTH_TOKEN_URL", default_token),
+        token_url=token_url,
         client_id=os.environ.get("HONCHO_OAUTH_CLIENT_ID", _DEFAULT_CLIENT_ID),
         scope=os.environ.get("HONCHO_OAUTH_SCOPE", "write"),
+        device_authorization_url=os.environ.get("HONCHO_OAUTH_DEVICE_AUTH_URL", default_device),
     )
 
 
@@ -240,6 +245,14 @@ _CALLBACK_HTML = (
     b"<div>Connected to Honcho. You can close this tab and return to Hermes.</div>"
 )
 
+_CALLBACK_ERROR_HTML = (
+    "<!doctype html><meta charset=utf-8>"
+    "<title>Honcho sign-in failed</title>"
+    "<body style='font:14px ui-monospace,monospace;background:#0b0e14;color:#c9d1d9;"
+    "display:flex;align-items:center;justify-content:center;height:100vh;margin:0'>"
+    "<div>Sign-in was not completed ({error}). You can close this tab and re-run setup.</div>"
+)
+
 
 def _bind_loopback_server() -> tuple[HTTPServer, dict[str, str]]:
     """Bind the one-shot callback server, returning it and its capture dict.
@@ -262,10 +275,17 @@ def _bind_loopback_server() -> tuple[HTTPServer, dict[str, str]]:
             captured["code"] = (params.get("code") or [""])[0]
             captured["state"] = (params.get("state") or [""])[0]
             captured["error"] = (params.get("error") or [""])[0]
+            captured["error_description"] = (params.get("error_description") or [""])[0]
             self.send_response(200)
             self.send_header("Content-Type", "text/html; charset=utf-8")
             self.end_headers()
-            self.wfile.write(_CALLBACK_HTML)
+            if captured["error"]:
+                import html as _html
+
+                page = _CALLBACK_ERROR_HTML.format(error=_html.escape(captured["error"]))
+                self.wfile.write(page.encode("utf-8"))
+            else:
+                self.wfile.write(_CALLBACK_HTML)
 
         def log_message(self, *args):  # silence stdlib request logging
             return
@@ -296,7 +316,9 @@ def capture_loopback_code(
         server.server_close()
 
     if captured.get("error"):
-        raise ValueError(f"authorization denied: {captured['error']}")
+        detail = captured.get("error_description")
+        suffix = f" ({detail})" if detail else ""
+        raise ValueError(f"authorization denied: {captured['error']}{suffix}")
     if "code" not in captured:
         raise TimeoutError("no OAuth callback received before timeout")
     return captured["code"], captured.get("state", "")
@@ -352,6 +374,209 @@ def authorize_via_loopback(
     )
 
 
+# — Device authorization grant (RFC 8628), for headless / remote-VM clients —
+# The loopback flow needs the browser on the same machine; here the CLI prints
+# a short user code, the user approves from any browser (dashboard /device),
+# and the device polls the token endpoint until the grant lands.
+
+DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+
+# RFC 8628 §3.5: slow_down adds 5s per response; cap matches the server's
+# DEVICE_POLL_INTERVAL_MAX so a misbehaving clock can't inflate past it.
+_SLOW_DOWN_STEP = 5
+_POLL_INTERVAL_CAP = 60
+
+# RFC 8414 authorization-server metadata; advertising the device grant is what
+# distinguishes a host that can do device login from one that can't.
+_AS_METADATA_PATH = "/.well-known/oauth-authorization-server"
+
+
+class DeviceFlowError(RuntimeError):
+    """A device-flow request failed. ``error`` is the RFC error code when known."""
+
+    def __init__(self, error: str, description: str | None = None):
+        self.error = error
+        self.description = description
+        super().__init__(f"{error}: {description}" if description else error)
+
+
+class AccessDenied(DeviceFlowError):
+    """The user denied the authorization request."""
+
+
+class DeviceCodeExpired(DeviceFlowError):
+    """The device code expired before the user approved it."""
+
+
+class AuthorizationTimeout(DeviceFlowError):
+    """Polling ran past the device code's lifetime with no decision."""
+
+
+@dataclass(frozen=True)
+class DeviceCode:
+    """RFC 8628 §3.2 device authorization response."""
+
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+def supports_device_login(endpoints: OAuthEndpoints, *, timeout: float = 5.0) -> bool:
+    """Whether the host advertises the device grant in its RFC 8414 metadata.
+
+    Fails closed: any connection error, non-200, or missing capability returns
+    False, so hosts without the device grant simply don't offer the option.
+    """
+    origin = endpoints.token_url.rsplit("/oauth/", 1)[0]
+    try:
+        body = oauth._http_get_json(f"{origin}{_AS_METADATA_PATH}", timeout)
+    except Exception:
+        return False
+    grants = body.get("grant_types_supported")
+    return isinstance(grants, list) and DEVICE_GRANT_TYPE in grants
+
+
+def request_device_code(
+    endpoints: OAuthEndpoints, *, source: str | None = None
+) -> DeviceCode:
+    """Request a device + user code pair (RFC 8628 §3.1)."""
+    if not endpoints.device_authorization_url:
+        raise ValueError("no device authorization endpoint resolved")
+    data = {"client_id": endpoints.client_id, "scope": endpoints.scope}
+    if source:
+        data["source"] = source
+    status, body = oauth._http_post_form_status(
+        endpoints.device_authorization_url, data, oauth._REFRESH_TIMEOUT_SECONDS
+    )
+    if status != 200:
+        error = str(body.get("error") or f"http_{status}")
+        raise DeviceFlowError(error, body.get("error_description"))
+    try:
+        verification_uri = body["verification_uri"]
+        return DeviceCode(
+            device_code=body["device_code"],
+            user_code=body["user_code"],
+            verification_uri=verification_uri,
+            verification_uri_complete=body.get(
+                "verification_uri_complete",
+                f"{verification_uri}?user_code={body['user_code']}",
+            ),
+            expires_in=int(body["expires_in"]),
+            # RFC 8628 §3.2: interval is optional; clients default to 5s.
+            interval=int(body.get("interval", 5)),
+        )
+    except (KeyError, TypeError, ValueError) as e:
+        raise DeviceFlowError(
+            "invalid_response", f"malformed device authorization response: {e}"
+        ) from e
+
+
+def poll_for_token(
+    endpoints: OAuthEndpoints,
+    device: DeviceCode,
+    *,
+    on_poll: Callable[[], None] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    monotonic: Callable[[], float] = time.monotonic,
+) -> dict[str, object]:
+    """Poll the token endpoint until the grant is approved (RFC 8628 §3.4/§3.5).
+
+    Sleeps ``interval`` before each poll, bumping it on ``slow_down``. Raises
+    ``AccessDenied`` / ``DeviceCodeExpired`` on the terminal server outcomes and
+    ``AuthorizationTimeout`` when ``expires_in`` elapses with no decision.
+    ``sleep`` / ``monotonic`` are injectable for tests.
+    """
+    import httpx
+
+    interval = max(1, min(device.interval, _POLL_INTERVAL_CAP))
+    deadline = monotonic() + max(1, device.expires_in)
+    while True:
+        if monotonic() + interval >= deadline:
+            raise AuthorizationTimeout(
+                "expired_token", "timed out waiting for approval"
+            )
+        sleep(interval)
+        if on_poll:
+            on_poll()
+        try:
+            status, body = oauth._http_post_form_status(
+                endpoints.token_url,
+                {
+                    "grant_type": DEVICE_GRANT_TYPE,
+                    "device_code": device.device_code,
+                    "client_id": endpoints.client_id,
+                },
+                oauth._REFRESH_TIMEOUT_SECONDS,
+            )
+        except httpx.TransportError as e:
+            # A network blip mid-poll shouldn't kill a 10-minute wait.
+            logger.debug("device token poll transport error, retrying: %s", e)
+            continue
+
+        if status == 200:
+            if not body.get("access_token"):
+                raise DeviceFlowError("invalid_response", "token response missing access_token")
+            return body
+        error = str(body.get("error") or f"http_{status}")
+        description = body.get("error_description")
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval = min(interval + _SLOW_DOWN_STEP, _POLL_INTERVAL_CAP)
+            continue
+        if error == "access_denied":
+            raise AccessDenied(error, description)
+        if error == "expired_token":
+            raise DeviceCodeExpired(error, description)
+        raise DeviceFlowError(error, description)
+
+
+def authorize_via_device_code(
+    *,
+    config_path: Path | None = None,
+    host: str | None = None,
+    source: str | None = None,
+    apply_config: bool = True,
+    display: Callable[[DeviceCode], None] | None = None,
+    open_url: Callable[[str], None] | None = None,
+    on_poll: Callable[[], None] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> oauth.OAuthCredential:
+    """Drive the full device flow: request codes → show user code → poll → persist.
+
+    ``display`` shows the user code + verification URL. ``open_url`` (if given)
+    receives ``verification_uri_complete`` — there is no default browser open,
+    since the approving browser may be on another machine.
+    """
+    endpoints = resolve_endpoints()
+    path = config_path or resolve_config_path()
+    target_host = host or resolve_active_host()
+
+    device = request_device_code(endpoints, source=source)
+    if display:
+        display(device)
+    if open_url:
+        open_url(device.verification_uri_complete)
+
+    grant = poll_for_token(endpoints, device, on_poll=on_poll, sleep=sleep)
+    cred = oauth.install_grant(
+        path,
+        target_host,
+        grant,
+        client_id=endpoints.client_id,
+        token_endpoint=endpoints.token_url,
+        apply_config=apply_config,
+    )
+    from plugins.memory.honcho.client import reset_honcho_client
+
+    reset_honcho_client()
+    logger.info("Honcho OAuth device grant installed for host %s", target_host)
+    return cred
+
+
 # — Background launcher + status, for the desktop "Connect" button —
 # The flow blocks on a browser round-trip, so the web_server endpoint kicks it
 # off in a thread and the UI polls status rather than holding the request open.
diff --git a/plugins/memory/mem0/__init__.py b/plugins/memory/mem0/__init__.py
index 35f413ed37a..b060a7bf7a8 100644
--- a/plugins/memory/mem0/__init__.py
+++ b/plugins/memory/mem0/__init__.py
@@ -240,7 +240,7 @@ class Mem0MemoryProvider(MemoryProvider):
         existing = {}
         if config_path.exists():
             try:
-                existing = json.loads(config_path.read_text())
+                existing = json.loads(config_path.read_text(encoding="utf-8"))
             except Exception:
                 pass
         existing.update(values)
diff --git a/plugins/memory/mem0/_setup.py b/plugins/memory/mem0/_setup.py
index 9883d8f2c10..5eaa3dc4c8e 100644
--- a/plugins/memory/mem0/_setup.py
+++ b/plugins/memory/mem0/_setup.py
@@ -193,7 +193,14 @@ def _write_env(env_path: Path, env_writes: dict[str, str]) -> None:
     env_path.parent.mkdir(parents=True, exist_ok=True)
     existing_lines: list[str] = []
     if env_path.exists():
-        existing_lines = env_path.read_text().splitlines()
+        # Read as UTF-8 (BOM-tolerant), matching the canonical .env readers in
+        # hermes_cli/config.py. read_text() with no encoding falls back to the
+        # system locale (cp1252/GBK on Windows): it mangles or crashes on
+        # non-ASCII values while copying existing lines through, and a BOM'd
+        # first line would fail the key match and get duplicated.
+        existing_lines = env_path.read_text(
+            encoding="utf-8-sig"
+        ).splitlines()
 
     updated_keys: set[str] = set()
     new_lines: list[str] = []
@@ -208,7 +215,7 @@ def _write_env(env_path: Path, env_writes: dict[str, str]) -> None:
         if k not in updated_keys:
             new_lines.append(f"{k}={v}")
 
-    env_path.write_text("\n".join(new_lines) + "\n")
+    env_path.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
 
 
 def _save_mem0_json(hermes_home: str, data: dict) -> None:
@@ -221,7 +228,7 @@ def _save_mem0_json(hermes_home: str, data: dict) -> None:
         except Exception:
             pass
     existing.update(data)
-    config_path.write_text(json.dumps(existing, indent=2) + "\n")
+    config_path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
 
 
 def _setup_platform(hermes_home: str, config: dict, flags: dict[str, str]) -> None:
@@ -241,7 +248,7 @@ def _setup_platform(hermes_home: str, config: dict, flags: dict[str, str]) -> No
     config_path = Path(hermes_home) / "mem0.json"
     if config_path.exists():
         try:
-            existing_config = json.loads(config_path.read_text())
+            existing_config = json.loads(config_path.read_text(encoding="utf-8"))
         except Exception:
             pass
 
@@ -362,7 +369,7 @@ def _setup_selfhosted(hermes_home: str, config: dict, flags: dict[str, str]) ->
     config_path = Path(hermes_home) / "mem0.json"
     if config_path.exists():
         try:
-            existing_config = json.loads(config_path.read_text())
+            existing_config = json.loads(config_path.read_text(encoding="utf-8"))
         except Exception:
             pass
 
@@ -493,7 +500,12 @@ def _prompt_api_key(label: str, env_var: str, hermes_home: str) -> str:
     if not existing:
         env_path = Path(hermes_home) / ".env"
         if env_path.exists():
-            for line in env_path.read_text().splitlines():
+            # BOM-tolerant read matching the canonical .env readers in
+            # hermes_cli/config.py; a Notepad BOM on the first line would
+            # otherwise defeat the startswith() key match below.
+            for line in env_path.read_text(
+                encoding="utf-8-sig", errors="replace"
+            ).splitlines():
                 if line.startswith(f"{env_var}="):
                     existing = line.split("=", 1)[1].strip()
                     break
@@ -525,7 +537,7 @@ def _ensure_pgvector(host: str = "localhost", port: int = 5432) -> dict | None:
         try:
             result = subprocess.run(
                 ["docker", "inspect", _PGVECTOR_CONTAINER, "--format", "{{.State.Status}}"],
-                capture_output=True, text=True, timeout=10, stdin=subprocess.DEVNULL,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=10, stdin=subprocess.DEVNULL,
             )
             if result.returncode == 0 and "exited" in result.stdout:
                 print(f"  Found stopped container '{_PGVECTOR_CONTAINER}', restarting...")
diff --git a/plugins/memory/openviking/__init__.py b/plugins/memory/openviking/__init__.py
index 5553a4b6316..e59f9467ac2 100644
--- a/plugins/memory/openviking/__init__.py
+++ b/plugins/memory/openviking/__init__.py
@@ -126,6 +126,11 @@ _GENERATED_MEMORY_SUMMARY_FILENAMES = {
 }
 _LOCAL_OPENVIKING_HOSTS = {"localhost", "127.0.0.1", "::1"}
 _LOCAL_OPENVIKING_AUTOSTART_TIMEOUT = 60.0
+# After a refresh attempt fails for a given (unchanged) config, skip re-probing
+# for this long. Keeps "unavailable endpoints reconnect on a later access"
+# true while preventing every provider access from paying a 3s health probe
+# (and emitting a warning) under _client_refresh_lock while a server is down.
+_FAILED_CONFIG_RETRY_COOLDOWN_SECONDS = 30.0
 _OPENVIKING_SERVER_LOG_RELATIVE_PATH = Path("logs") / "openviking-server.log"
 _OPENVIKING_RESPONDED_FAILURE_PREFIX = "OpenViking server responded"
 _PENDING_SESSIONS_RELATIVE_DIR = Path("openviking") / "pending_sessions"
@@ -294,12 +299,23 @@ class _VikingClient:
 
     @staticmethod
     def _needs_trusted_identity_retry(exc: Exception) -> bool:
+        """Detect errors that indicate missing tenant-scoped identity headers.
+
+        Trusted mode can ask for ``X-OpenViking-Account`` /
+        ``X-OpenViking-User`` using slightly different wording across
+        OpenViking versions. Match that trusted-mode missing-identity shape
+        instead of enumerating every exact string, while keeping deliberate
+        API-key permission denials non-retriable.
+        """
         message = str(exc)
-        return (
-            "Trusted mode requests must include X-OpenViking-Account" in message
-            or "Trusted mode requests must include X-OpenViking-User" in message
-            or "Trusted mode requests must include X-OpenViking-Account or explicit account_id" in message
-        )
+        if "Trusted mode requests must include" not in message:
+            return False
+        if "X-OpenViking-Account" not in message and "X-OpenViking-User" not in message:
+            return False
+        status_code = getattr(exc, "status_code", None)
+        if status_code is not None and status_code != 400:
+            return False
+        return True
 
     def _send_with_trusted_identity_retry(self, send, *, multipart: bool = False) -> dict:
         try:
@@ -880,9 +896,9 @@ def _is_local_openviking_url(value: str) -> bool:
 
 def _load_hermes_openviking_config() -> dict:
     try:
-        from hermes_cli.config import load_config
+        from hermes_cli.config import load_config_readonly
 
-        config = load_config()
+        config = load_config_readonly()
         memory_config = config.get("memory", {}) if isinstance(config, dict) else {}
         provider_config = memory_config.get("openviking", {}) if isinstance(memory_config, dict) else {}
         return dict(provider_config) if isinstance(provider_config, dict) else {}
@@ -962,6 +978,23 @@ def _precreate_secret_file(path: Path) -> None:
         logger.debug("Could not pre-create secret file %s: %s", path, e)
 
 
+def _env_line_safe(value: Any) -> str:
+    """Neutralize characters that would break ``.env`` line structure.
+
+    A ``.env`` file is strictly line-oriented (one ``KEY=VALUE`` per line),
+    and ``_write_env_vars`` interpolates each value straight into that line.
+    A value carrying an embedded CR/LF would therefore spill onto a new line
+    and be re-parsed as a *separate* ``KEY=VALUE`` entry on the next
+    ``read_text().splitlines()`` round-trip — letting a malformed or pasted
+    secret (e.g. an api_key copied with a trailing record) inject an
+    arbitrary additional variable into the persisted credentials file. Strip
+    the line separators recognized by ``splitlines()`` and the NUL byte so a
+    value can only ever occupy the single line it is written on.
+    """
+    text = value if isinstance(value, str) else str(value)
+    return "".join(text.replace("\x00", "").splitlines())
+
+
 def _write_env_vars(env_path: Path, env_writes: dict, remove_keys: tuple[str, ...] = ()) -> None:
     env_path.parent.mkdir(parents=True, exist_ok=True)
     remove_set = set(remove_keys) - set(env_writes)
@@ -973,13 +1006,13 @@ def _write_env_vars(env_path: Path, env_writes: dict, remove_keys: tuple[str, ..
         if key_match in remove_set:
             continue
         if key_match in env_writes:
-            new_lines.append(f"{key_match}={env_writes[key_match]}")
+            new_lines.append(f"{key_match}={_env_line_safe(env_writes[key_match])}")
             updated_keys.add(key_match)
         else:
             new_lines.append(line)
     for key, val in env_writes.items():
         if key not in updated_keys:
-            new_lines.append(f"{key}={val}")
+            new_lines.append(f"{key}={_env_line_safe(val)}")
     # Pre-create with 0600 so secrets are never briefly world-readable.
     _precreate_secret_file(env_path)
     env_path.write_text("\n".join(new_lines) + ("\n" if new_lines else ""), encoding="utf-8")
@@ -1205,9 +1238,20 @@ def _start_local_openviking_server(endpoint: str) -> tuple[bool, str]:
     return True, f"Started openviking-server on {host}:{port} in the background. Logs: {log_path}"
 
 
-def _wait_for_openviking_health(endpoint: str, *, timeout_seconds: float = 15.0) -> bool:
+def _wait_for_openviking_health(
+    endpoint: str,
+    *,
+    timeout_seconds: float = 15.0,
+    should_stop=None,
+) -> bool:
     deadline = time.monotonic() + timeout_seconds
     while time.monotonic() < deadline:
+        # Bail out promptly if the provider is being torn down, so the daemon
+        # thread running this waiter can be join()ed at shutdown instead of
+        # lingering up to ``timeout_seconds`` (a worker still alive at
+        # interpreter exit aborts CPython with SIGABRT at Py_FinalizeEx).
+        if should_stop is not None and should_stop():
+            return False
         ok, _message = _validate_openviking_reachability(endpoint)
         if ok:
             return True
@@ -1830,6 +1874,11 @@ class OpenVikingMemoryProvider(MemoryProvider):
         self._run_id = uuid.uuid4().hex
         self._run_lock_file: Optional[Any] = None
         self._run_lock_path: Optional[Path] = None
+        # Set once initialize() has resolved the connection baseline. Until then
+        # _ensure_client() must not re-resolve from the environment — callers
+        # that wire up a client directly (e.g. tests) would otherwise have it
+        # discarded. See _ensure_client() / #21130.
+        self._env_refresh_enabled = False
         # Guards the (_session_id, _turn_count) pair. sync_turn runs on the
         # MemoryManager's background sync executor while on_session_end /
         # on_session_switch run on the caller's thread, so the snapshot+reset
@@ -1848,8 +1897,22 @@ class OpenVikingMemoryProvider(MemoryProvider):
         self._committed_session_ids: Set[str] = set()
         self._committed_session_lock = threading.Lock()
         self._pending_marked_sids: Set[str] = set()
+        # Connection settings and _client are one published state. Serialize
+        # refreshes so callers never observe a new config with the old client.
+        self._client_refresh_lock = threading.Lock()
+        # Last connection identity that passed a health check, published as a
+        # single tuple assignment (atomic in CPython) so lock-free background
+        # writers (_new_client, on_memory_write) never see a torn mix of old
+        # and new fields, and never target an endpoint that failed health.
+        self._conn_snapshot: Optional[tuple] = None
+        # (settings tuple, monotonic timestamp) of the last refresh attempt
+        # that failed. While the resolved config still matches and the retry
+        # cooldown hasn't elapsed, _ensure_client_locked() returns None without
+        # re-probing — keeping provider accesses cheap while a server is down.
+        self._failed_refresh: Optional[tuple] = None
         self._runtime_start_lock = threading.Lock()
         self._runtime_start_thread: Optional[threading.Thread] = None
+        self._runtime_start_pending = False
         self._memory_write_lock = threading.Lock()
         self._memory_write_threads: Set[threading.Thread] = set()
         self._profile_prefetched_sessions: Set[str] = set()
@@ -2065,72 +2128,98 @@ class OpenVikingMemoryProvider(MemoryProvider):
     def _start_runtime_openviking_waiter(
         self,
         *,
+        endpoint: str,
         status_callback=None,
         warning_callback=None,
     ) -> None:
-        with self._runtime_start_lock:
-            if self._runtime_start_thread and self._runtime_start_thread.is_alive():
-                return
-            self._runtime_start_thread = threading.Thread(
-                target=self._finish_runtime_openviking_start,
-                kwargs={
-                    "status_callback": status_callback,
-                    "warning_callback": warning_callback,
-                },
-                daemon=True,
-                name="openviking-runtime-start",
-            )
-            self._runtime_start_thread.start()
+        # Precondition: caller holds _runtime_start_lock. Local process start
+        # ownership is reserved with _runtime_start_pending before callbacks run.
+        if self._runtime_start_thread and self._runtime_start_thread.is_alive():
+            return
+        self._runtime_start_thread = threading.Thread(
+            target=self._finish_runtime_openviking_start,
+            kwargs={
+                "endpoint": endpoint,
+                "status_callback": status_callback,
+                "warning_callback": warning_callback,
+            },
+            daemon=True,
+            name="openviking-runtime-start",
+        )
+        self._runtime_start_thread.start()
 
     def _finish_runtime_openviking_start(
         self,
         *,
+        endpoint: Optional[str] = None,
         status_callback=None,
         warning_callback=None,
     ) -> None:
-        endpoint = self._endpoint
+        endpoint = endpoint or self._endpoint
         if not _wait_for_openviking_health(
             endpoint,
             timeout_seconds=_LOCAL_OPENVIKING_AUTOSTART_TIMEOUT,
+            should_stop=lambda: self._shutting_down or self._endpoint != endpoint,
         ):
+            if self._shutting_down or self._endpoint != endpoint:
+                return
             _emit_runtime_warning(
                 _runtime_openviking_timeout_message(endpoint),
                 warning_callback,
             )
             return
 
-        try:
-            client = _VikingClient(
-                endpoint,
-                self._api_key,
-                account=self._account,
-                user=self._user,
-                agent=self._agent,
-            )
-            if not client.health():
-                _emit_runtime_warning(
-                    f"OpenViking server at {endpoint} is still not reachable after auto-start; "
-                    "OpenViking memory disabled for this Hermes run.",
-                    warning_callback,
-                )
+        warning_message = ""
+        status_message = ""
+        with self._client_refresh_lock:
+            if self._shutting_down or self._endpoint != endpoint:
                 return
-        except ImportError:
-            logger.warning("httpx not installed — OpenViking plugin disabled")
-            return
-        except Exception as e:
+            try:
+                client = _VikingClient(
+                    endpoint,
+                    self._api_key,
+                    account=self._account,
+                    user=self._user,
+                    agent=self._agent,
+                )
+                healthy = client.health()
+                if self._shutting_down or self._endpoint != endpoint:
+                    return
+                if not healthy:
+                    warning_message = (
+                        f"OpenViking server at {endpoint} is still not reachable after auto-start; "
+                        "OpenViking memory disabled for this Hermes run."
+                    )
+                else:
+                    self._client = client
+                    self._conn_snapshot = (
+                        endpoint, self._api_key, self._account, self._user, self._agent,
+                    )
+                    self._failed_refresh = None
+                    status_message = (
+                        f"Local OpenViking server at {endpoint} is reachable; "
+                        "OpenViking memory is active for later turns."
+                    )
+            except ImportError:
+                logger.warning("httpx not installed — OpenViking plugin disabled")
+                return
+            except Exception as e:
+                warning_message = (
+                    f"OpenViking server at {endpoint} could not be attached after auto-start: {e}. "
+                    "OpenViking memory disabled for this Hermes run."
+                )
+
+        if warning_message:
             _emit_runtime_warning(
-                f"OpenViking server at {endpoint} could not be attached after auto-start: {e}. "
-                "OpenViking memory disabled for this Hermes run.",
+                warning_message,
                 warning_callback,
             )
             return
-
-        self._client = client
-        self._recover_pending_sessions()
-        _emit_runtime_status(
-            f"Local OpenViking server at {endpoint} is reachable; OpenViking memory is active for later turns.",
-            status_callback,
-        )
+        if status_message:
+            # Client attached: recover orphaned sessions outside the refresh
+            # lock (network I/O), then announce.
+            self._recover_pending_sessions()
+            _emit_runtime_status(status_message, status_callback)
 
     def _handle_runtime_openviking_unreachable(
         self,
@@ -2149,25 +2238,52 @@ class OpenVikingMemoryProvider(MemoryProvider):
             self._client = None
             return
 
-        started, start_message = _start_local_openviking_server(endpoint)
-        if not started:
+        warning_message = ""
+        status_message = ""
+        should_start_waiter = False
+        with self._runtime_start_lock:
+            if (
+                self._shutting_down
+                or self._runtime_start_pending
+                or (self._runtime_start_thread and self._runtime_start_thread.is_alive())
+            ):
+                self._client = None
+                return
+
+            self._runtime_start_pending = True
+            started, start_message = _start_local_openviking_server(endpoint)
+            if not started:
+                self._runtime_start_pending = False
+                warning_message = (
+                    f"Local OpenViking server at {endpoint} is not reachable. {start_message} "
+                    "OpenViking memory disabled for this Hermes run."
+                )
+                self._client = None
+            else:
+                self._client = None
+                status_message = (
+                    f"{start_message} OpenViking memory is starting in the background and will attach when ready."
+                )
+                should_start_waiter = True
+
+        if warning_message:
             _emit_runtime_warning(
-                f"Local OpenViking server at {endpoint} is not reachable. {start_message} "
-                "OpenViking memory disabled for this Hermes run.",
+                warning_message,
                 warning_callback,
             )
-            self._client = None
             return
-
-        self._client = None
-        _emit_runtime_status(
-            f"{start_message} OpenViking memory is starting in the background and will attach when ready.",
-            status_callback,
-        )
-        self._start_runtime_openviking_waiter(
-            status_callback=status_callback,
-            warning_callback=warning_callback,
-        )
+        if status_message:
+            _emit_runtime_status(status_message, status_callback)
+        if should_start_waiter:
+            with self._runtime_start_lock:
+                self._runtime_start_pending = False
+                if self._shutting_down:
+                    return
+                self._start_runtime_openviking_waiter(
+                    endpoint=endpoint,
+                    status_callback=status_callback,
+                    warning_callback=warning_callback,
+                )
 
     def initialize(self, session_id: str, **kwargs) -> None:
         settings = _resolve_connection_settings(_load_hermes_openviking_config())
@@ -2176,6 +2292,11 @@ class OpenVikingMemoryProvider(MemoryProvider):
         self._account = settings["account"]
         self._user = settings["user"]
         self._agent = settings["agent"]
+        # Baseline established — subsequent accesses may refresh from env
+        # (#21130). Set here (not at the end of initialize) so an exception in
+        # the connection attempt below — swallowed by MemoryManager's guard —
+        # can't leave the provider silently stuck in never-refresh mode.
+        self._env_refresh_enabled = True
         self._session_id = session_id
         self._turn_count = 0
         hermes_home = str(kwargs.get("hermes_home") or "").strip()
@@ -2221,14 +2342,114 @@ class OpenVikingMemoryProvider(MemoryProvider):
             self._client = None
 
         if self._client:
+            self._conn_snapshot = (
+                self._endpoint, self._api_key, self._account, self._user, self._agent,
+            )
             self._recover_pending_sessions()
 
         # Register as the last active provider for atexit safety net
         global _last_active_provider
         _last_active_provider = self
 
+    def _ensure_client(self) -> Optional["_VikingClient"]:
+        """Return the active client, rebuilding it if the resolved config changed.
+
+        ``/reload`` only refreshes ``os.environ`` — the existing provider
+        instance is not re-initialized — so OPENVIKING_* values added to
+        ``~/.hermes/.env`` after startup never reach the live client and tools
+        keep running against stale auth until the user restarts hermes (#21130).
+
+        Re-resolve the connection settings on each access (same layering as
+        ``initialize``) and rebuild + health-check only when a value actually
+        changed; otherwise reuse the cached client so the hot path stays at one
+        dict comparison with zero network calls.
+        """
+        # Before initialize() runs there is no env baseline to refresh against;
+        # return whatever client the caller wired up (matches legacy behavior).
+        if not self._env_refresh_enabled:
+            return self._client
+
+        with self._client_refresh_lock:
+            return self._ensure_client_locked()
+
+    def _ensure_client_locked(self) -> Optional["_VikingClient"]:
+        """Resolve and publish one client/config state under the refresh lock."""
+        if self._shutting_down:
+            self._client = None
+            return None
+
+        settings = _resolve_connection_settings(_load_hermes_openviking_config())
+        endpoint = settings["endpoint"]
+        api_key = settings["api_key"]
+        account = settings["account"]
+        user = settings["user"]
+        agent = settings["agent"]
+        settings_key = (endpoint, api_key, account, user, agent)
+
+        config_unchanged = (
+            endpoint == getattr(self, "_endpoint", None)
+            and api_key == getattr(self, "_api_key", None)
+            and account == getattr(self, "_account", None)
+            and user == getattr(self, "_user", None)
+            and agent == getattr(self, "_agent", None)
+        )
+        if config_unchanged and self._client is not None:
+            return self._client
+        if config_unchanged:
+            with self._runtime_start_lock:
+                if (
+                    self._runtime_start_pending
+                    or (self._runtime_start_thread and self._runtime_start_thread.is_alive())
+                ):
+                    return self._client
+            # The last attempt at this exact config failed. Don't pay a
+            # network probe (3s timeout, under the refresh lock) on every
+            # access while the server stays down — retry after a cooldown or
+            # as soon as the resolved config changes.
+            failed = self._failed_refresh
+            if failed is not None:
+                failed_key, failed_at = failed
+                if (
+                    failed_key == settings_key
+                    and time.monotonic() - failed_at < _FAILED_CONFIG_RETRY_COOLDOWN_SECONDS
+                ):
+                    return None
+
+        self._endpoint = endpoint
+        self._api_key = api_key
+        self._account = account
+        self._user = user
+        self._agent = agent
+
+        try:
+            client = _VikingClient(
+                endpoint, api_key, account=account, user=user, agent=agent,
+            )
+        except ImportError:
+            logger.warning("httpx not installed — OpenViking plugin disabled")
+            self._client = None
+            return None
+
+        health_state, health_message = _classify_runtime_openviking_health(client, endpoint)
+        if health_state == "healthy":
+            self._client = client
+            self._conn_snapshot = settings_key
+            self._failed_refresh = None
+            return self._client
+        self._failed_refresh = (settings_key, time.monotonic())
+        if health_state == "responded":
+            logger.warning(
+                "%s OpenViking memory disabled; will retry on a later access "
+                "(after cooldown) or when the config changes.",
+                health_message,
+            )
+        else:  # unreachable
+            self._handle_runtime_openviking_unreachable()
+        self._client = None
+        return None
+
     def system_prompt_block(self) -> str:
-        if not self._client:
+        if not self._ensure_client():
             return ""
         # Provide brief info about the knowledge base
         try:
@@ -2278,7 +2499,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
     def prefetch(self, query: str, *, session_id: str = "") -> str:
         """Return recall context for this query/session."""
         query_text = _derive_openviking_user_text(query).strip()
-        if not self._client:
+        if not self._ensure_client():
             return ""
 
         effective_session_id = str(session_id or self._session_id or "").strip()
@@ -2424,6 +2645,18 @@ class OpenVikingMemoryProvider(MemoryProvider):
                 t.join(timeout=slice_left)
 
     def _new_client(self) -> _VikingClient:
+        # Read the connection identity as ONE tuple load: these builders run on
+        # background writer threads without _client_refresh_lock, and reading
+        # the five fields individually could observe a torn mix of old and new
+        # values mid-refresh (new endpoint + old api_key). The snapshot is only
+        # published after a successful health check; fall back to the field
+        # reads for legacy/hand-wired paths where no snapshot exists yet.
+        snapshot = self._conn_snapshot
+        if snapshot is not None:
+            endpoint, api_key, account, user, agent = snapshot
+            return _VikingClient(
+                endpoint, api_key, account=account, user=user, agent=agent,
+            )
         return _VikingClient(
             self._endpoint,
             self._api_key,
@@ -2849,17 +3082,23 @@ class OpenVikingMemoryProvider(MemoryProvider):
         client: Optional[_VikingClient] = None,
     ) -> str:
         query_text = (query or "").strip()
-        if not self._client or len(query_text) < _RECALL_QUERY_MIN_CHARS:
+        if len(query_text) < _RECALL_QUERY_MIN_CHARS:
+            return ""
+        if client is None:
+            if self._env_refresh_enabled:
+                client = self._ensure_client()
+            elif self._client is not None:
+                # Legacy/hand-wired path: no env baseline yet. Build from the
+                # cached identity, degrading to "" like the rest of prefetch.
+                try:
+                    client = self._new_client()
+                except Exception as e:
+                    logger.debug("OpenViking prefetch client build failed: %s", e)
+                    return ""
+        if client is None:
             return ""
 
         try:
-            client = client or _VikingClient(
-                self._endpoint,
-                self._api_key,
-                account=self._account,
-                user=self._user,
-                agent=self._agent,
-            )
             cfg = self._recall_config()
             candidate_limit = max(cfg["limit"] * 4, 20)
             deadline = time.monotonic() + cfg["timeout_seconds"]
@@ -3712,7 +3951,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
         messages: Optional[List[Dict[str, Any]]] = None,
     ) -> None:
         """Record the conversation turn in OpenViking's session (non-blocking)."""
-        if not self._client:
+        if not self._ensure_client():
             return
 
         user_content = _derive_openviking_user_text(user_content)
@@ -3863,7 +4102,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
         OpenViking automatically extracts 6 categories of memories:
         profile, preferences, entities, events, cases, and patterns.
         """
-        if not self._client:
+        if not self._ensure_client():
             return
 
         # Snapshot sid + turn count atomically against a concurrent sync_turn
@@ -3914,7 +4153,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
         ``_turn_count``.
         """
         new_id = str(new_session_id or "").strip()
-        if not new_id or not self._client:
+        if not new_id or not self._ensure_client():
             return
 
         rewound = bool(kwargs.get("rewound"))
@@ -3974,7 +4213,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
         metadata: Optional[Dict[str, Any]] = None,
     ) -> None:
         """Mirror successful built-in memory additions to OpenViking."""
-        if not self._client or action != "add" or not content:
+        if action != "add" or not content or not self._ensure_client():
             return
 
         subdir = _MEMORY_WRITE_TARGET_SUBDIR_MAP.get(target, _DEFAULT_MEMORY_SUBDIR)
@@ -3982,10 +4221,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
 
         def _write():
             try:
-                client = _VikingClient(
-                    self._endpoint, self._api_key,
-                    account=self._account, user=self._user, agent=self._agent,
-                )
+                client = self._new_client()
                 client.post("/api/v1/content/write", {
                     "uri": uri,
                     "content": content,
@@ -4019,7 +4255,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
         ]
 
     def handle_tool_call(self, tool_name: str, args: dict, **kwargs) -> str:
-        if not self._client:
+        if not self._ensure_client():
             return tool_error("OpenViking server not connected")
 
         try:
@@ -4052,6 +4288,12 @@ class OpenVikingMemoryProvider(MemoryProvider):
             deferred_workers = list(self._deferred_commit_threads)
         with self._memory_write_lock:
             memory_write_workers = list(self._memory_write_threads)
+        # The runtime-autostart waiter is a tracked daemon thread that blocks on
+        # network health probes; it must be joined too, or it can be left alive
+        # at interpreter exit (SIGABRT at Py_FinalizeEx). Setting _shutting_down
+        # above makes its health-wait loop bail out promptly so the join lands.
+        with self._runtime_start_lock:
+            runtime_start_thread = self._runtime_start_thread
         for t in all_workers:
             if t.is_alive():
                 t.join(timeout=5.0)
@@ -4061,6 +4303,8 @@ class OpenVikingMemoryProvider(MemoryProvider):
         for t in memory_write_workers:
             if t.is_alive():
                 t.join(timeout=5.0)
+        if runtime_start_thread is not None and runtime_start_thread.is_alive():
+            runtime_start_thread.join(timeout=5.0)
         # Clear atexit reference so it doesn't double-commit.
         global _last_active_provider
         if _last_active_provider is self:
diff --git a/plugins/model-providers/nous/__init__.py b/plugins/model-providers/nous/__init__.py
index c63c05343e7..cfce5eae330 100644
--- a/plugins/model-providers/nous/__init__.py
+++ b/plugins/model-providers/nous/__init__.py
@@ -2,7 +2,7 @@
 
 from typing import Any
 
-from agent.portal_tags import nous_portal_tags
+from agent.portal_tags import get_conversation_context, nous_portal_tags
 from providers import register_provider
 from providers.base import ProviderProfile
 
@@ -14,15 +14,35 @@ class NousProfile(ProviderProfile):
         self, *, session_id: str | None = None, **context
     ) -> dict[str, Any]:
         body: dict[str, Any] = {"tags": nous_portal_tags(session_id=session_id)}
-        if session_id:
-            # Top-level session_id → provider sticky routing key. Pins every
-            # turn of a session to the same upstream endpoint so explicit
-            # Anthropic cache_control breakpoints stay warm instead of
-            # cold-writing a fresh cache on each reroute (Anthropic/Vertex/
-            # Bedrock caches are instance-local). Mirrors the OpenRouter
-            # profile; without it the portal falls back to hashing the opening
-            # messages, which breaks pinning whenever those shift.
-            body["session_id"] = session_id
+        # Top-level session_id → provider sticky routing key. Pins every
+        # turn of a session to the same upstream endpoint so explicit
+        # Anthropic cache_control breakpoints stay warm instead of
+        # cold-writing a fresh cache on each reroute (Anthropic/Vertex/
+        # Bedrock caches are instance-local). Mirrors the OpenRouter
+        # profile; without it the portal falls back to hashing the opening
+        # messages, which breaks pinning whenever those shift.
+        #
+        # Resolve it exactly like ``nous_portal_tags`` resolves the
+        # ``conversation=`` tag: ambient context first (the lineage ROOT id
+        # published by the agent loop), explicit argument as fallback.
+        #
+        # The gap this closes is the auxiliary call sites — compression,
+        # title generation, vision, web_extract, session_search, MoA slots.
+        # They funnel through ``agent.auxiliary_client`` which has no session
+        # handle, so they never pass ``session_id``: they carried the
+        # ``conversation=`` tag but NO sticky key at all, and each one routed
+        # independently of the conversation it belongs to. Reading the same
+        # ambient contextvar the tag already uses fixes that with zero
+        # per-call-site plumbing.
+        #
+        # For the main loop the two agree anyway under the default
+        # ``compression.in_place: true`` (#38763), where compaction keeps the
+        # session id; the ambient root additionally keeps the key stable for
+        # installs that opt back into rotating compaction, and across
+        # delegate-subagent trees.
+        sticky_key = get_conversation_context() or session_id
+        if sticky_key:
+            body["session_id"] = sticky_key
         provider_preferences = context.get("provider_preferences")
         if provider_preferences:
             body["provider"] = provider_preferences
diff --git a/plugins/model-providers/openrouter/__init__.py b/plugins/model-providers/openrouter/__init__.py
index 11c814591ec..3abf291e144 100644
--- a/plugins/model-providers/openrouter/__init__.py
+++ b/plugins/model-providers/openrouter/__init__.py
@@ -3,6 +3,7 @@
 import logging
 from typing import Any
 
+from agent.portal_tags import get_conversation_context
 from providers import register_provider
 from providers.base import ProviderProfile
 
@@ -77,8 +78,26 @@ class OpenRouterProfile(ProviderProfile):
         self, *, session_id: str | None = None, **context: Any
     ) -> dict[str, Any]:
         body: dict[str, Any] = {}
-        if session_id:
-            body["session_id"] = session_id
+        # Top-level session_id → OpenRouter's sticky routing key. Per their
+        # prompt-caching docs it is used directly as the routing key instead of
+        # hashing the opening messages, and it activates stickiness on the
+        # first successful request rather than only after a cache hit.
+        #
+        # Resolve it from the ambient conversation contextvar first, explicit
+        # argument as fallback. The gap this closes is the auxiliary call sites
+        # — compression, title generation, vision, web_extract, session_search,
+        # MoA slots — which funnel through ``agent.auxiliary_client``. That
+        # module has no session handle and passes no ``session_id``, so those
+        # calls sent NO sticky key at all and each routed independently of the
+        # conversation it belonged to (#70820).
+        #
+        # Mirrors the Nous Portal profile, which resolves the same way
+        # (f2f4df064d). The ambient value is the session-lineage ROOT, so it
+        # also stays stable for installs that opt out of the default
+        # ``compression.in_place: true`` and across delegate-subagent trees.
+        sticky_key = get_conversation_context() or session_id
+        if sticky_key:
+            body["session_id"] = sticky_key
         prefs = context.get("provider_preferences")
         if prefs:
             body["provider"] = prefs
@@ -159,8 +178,13 @@ class OpenRouterProfile(ProviderProfile):
             else:
                 extra_body["reasoning"] = {"enabled": True, "effort": "medium"}
 
-        if session_id and model and model.startswith(("x-ai/grok-", "xai/grok-")):
-            extra_headers["x-grok-conv-id"] = session_id
+        # Same resolution as build_extra_body: xAI's prompt cache is pinned per
+        # backend server via this header, and aux calls pass no session_id, so
+        # reading the ambient conversation keeps compression/vision/MoA traffic
+        # on the same Grok backend as the conversation it belongs to.
+        grok_conv_id = get_conversation_context() or session_id
+        if grok_conv_id and model and model.startswith(("x-ai/grok-", "xai/grok-")):
+            extra_headers["x-grok-conv-id"] = grok_conv_id
         if extra_headers:
             top_level["extra_headers"] = extra_headers
 
diff --git a/plugins/platforms/discord/adapter.py b/plugins/platforms/discord/adapter.py
index 161669a8a6e..6e66a2c269a 100644
--- a/plugins/platforms/discord/adapter.py
+++ b/plugins/platforms/discord/adapter.py
@@ -8164,7 +8164,7 @@ def _define_discord_view_classes() -> None:
                 home = get_hermes_home()
                 response_path = home / ".update_response"
                 tmp = response_path.with_suffix(".tmp")
-                tmp.write_text(answer)
+                tmp.write_text(answer, encoding="utf-8")
                 tmp.replace(response_path)
                 logger.info(
                     "Discord update prompt answered '%s' by %s",
diff --git a/plugins/platforms/feishu/adapter.py b/plugins/platforms/feishu/adapter.py
index 93571de0619..e1df2a05e5e 100644
--- a/plugins/platforms/feishu/adapter.py
+++ b/plugins/platforms/feishu/adapter.py
@@ -2180,7 +2180,7 @@ class FeishuAdapter(BasePlatformAdapter):
     def _write_update_prompt_response(answer: str) -> None:
         response_path = get_hermes_home() / ".update_response"
         tmp_path = response_path.with_suffix(".tmp")
-        tmp_path.write_text(answer)
+        tmp_path.write_text(answer, encoding="utf-8")
         tmp_path.replace(response_path)
 
     async def send_voice(
diff --git a/plugins/platforms/google_chat/adapter.py b/plugins/platforms/google_chat/adapter.py
index 540f9bf8456..0b73968d92f 100644
--- a/plugins/platforms/google_chat/adapter.py
+++ b/plugins/platforms/google_chat/adapter.py
@@ -558,7 +558,7 @@ class _ThreadCountStore:
             self._counts = {}
             return
         try:
-            raw = self._path.read_text()
+            raw = self._path.read_text(encoding="utf-8")
             data = json.loads(raw) if raw.strip() else {}
         except json.JSONDecodeError as exc:
             logger.warning(
@@ -613,7 +613,7 @@ class _ThreadCountStore:
         try:
             self._path.parent.mkdir(parents=True, exist_ok=True)
             tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-            tmp.write_text(json.dumps(self._counts, separators=(",", ":")))
+            tmp.write_text(json.dumps(self._counts, separators=(",", ":")), encoding="utf-8")
             os.replace(tmp, self._path)
         except OSError as exc:
             logger.warning(
diff --git a/plugins/platforms/google_chat/oauth.py b/plugins/platforms/google_chat/oauth.py
index b66b0829f29..1b8c89cb2e4 100644
--- a/plugins/platforms/google_chat/oauth.py
+++ b/plugins/platforms/google_chat/oauth.py
@@ -427,7 +427,7 @@ def store_client_secret(path: str) -> None:
         sys.exit(1)
 
     try:
-        data = json.loads(src.read_text())
+        data = json.loads(src.read_text(encoding="utf-8"))
     except json.JSONDecodeError:
         print("ERROR: File is not valid JSON.")
         sys.exit(1)
@@ -467,7 +467,7 @@ def _load_pending_auth(email: Optional[str] = None) -> dict:
         print("ERROR: No pending OAuth session found. Run --auth-url first.")
         sys.exit(1)
     try:
-        data = json.loads(pending.read_text())
+        data = json.loads(pending.read_text(encoding="utf-8"))
     except Exception as exc:
         print(f"ERROR: Could not read pending OAuth session: {exc}")
         print("Run --auth-url again to start a fresh session.")
diff --git a/plugins/platforms/photon/adapter.py b/plugins/platforms/photon/adapter.py
index 29f49029043..91cd50c3b48 100644
--- a/plugins/platforms/photon/adapter.py
+++ b/plugins/platforms/photon/adapter.py
@@ -183,7 +183,7 @@ def _reinstall_sidecar_deps() -> None:
             [npm, "ci"],
             cwd=str(_SIDECAR_DIR),
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             check=False,
             timeout=_NPM_REINSTALL_TIMEOUT,
             creationflags=windows_hide_flags(),
@@ -196,7 +196,7 @@ def _reinstall_sidecar_deps() -> None:
                 [npm, "install"],
                 cwd=str(_SIDECAR_DIR),
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
                 check=False,
                 timeout=_NPM_REINSTALL_TIMEOUT,
                 creationflags=windows_hide_flags(),
@@ -834,7 +834,7 @@ class PhotonAdapter(BasePlatformAdapter):
         try:
             out = subprocess.run(  # noqa: S603, S607
                 ["lsof", "-ti", f"tcp:{port}", "-sTCP:LISTEN"],
-                capture_output=True, text=True, timeout=5.0, check=False,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5.0, check=False,
             )
         except (OSError, subprocess.TimeoutExpired):
             return []
@@ -846,7 +846,7 @@ class PhotonAdapter(BasePlatformAdapter):
         try:
             out = subprocess.run(  # noqa: S603, S607
                 ["ps", "-p", str(pid), "-o", "command="],
-                capture_output=True, text=True, timeout=5.0, check=False,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5.0, check=False,
             )
         except (OSError, subprocess.TimeoutExpired):
             return False
@@ -962,7 +962,7 @@ class PhotonAdapter(BasePlatformAdapter):
                     str(_SIDECAR_DIR),
                 ],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=10,
                 check=False,
                 # Windows: suppress the brief console flash this short-lived
diff --git a/plugins/platforms/telegram/adapter.py b/plugins/platforms/telegram/adapter.py
index dd19d2551a8..55ae362bfe0 100644
--- a/plugins/platforms/telegram/adapter.py
+++ b/plugins/platforms/telegram/adapter.py
@@ -155,6 +155,16 @@ async def _await_with_thread_deadline(awaitable, timeout: float, *, on_abandon=N
         loop_processed_expiry.set()
 
 
+async def _first_completed(*futures: "asyncio.Future") -> None:
+    """Return when the first of ``futures`` completes.
+
+    Used by the strict cold-start readiness gate to wait on "progress OR
+    polling error", whichever fires first (#67498). Does not cancel the
+    losers — the caller owns their lifecycle.
+    """
+    await asyncio.wait(set(futures), return_when=asyncio.FIRST_COMPLETED)
+
+
 async def _run_abandon_cleanup(on_abandon) -> None:
     """Run the abandonment cleanup coroutine, swallowing any failure.
 
@@ -355,7 +365,7 @@ def _probe_voice_duration_seconds(path: str) -> Optional[int]:
             proc = subprocess.run(
                 ["ffprobe", "-v", "error", "-show_entries", "format=duration",
                  "-of", "default=noprint_wrappers=1:nokey=1", path],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5,
             )
             if proc.returncode == 0:
                 return _coerce_duration_seconds(proc.stdout.strip())
@@ -545,6 +555,10 @@ _UPDATER_STOP_TIMEOUT = 15.0
 # reconnect ladder from stalling indefinitely and allows the heartbeat loop to
 # trigger its own recovery path. Refs: NousResearch/hermes-agent#59614
 _UPDATER_START_TIMEOUT = 30.0
+# Initial connect is not healthy until the dedicated getUpdates request completes
+# one successful round trip. Unlike reconnect, initial bootstrap must fail closed
+# so GatewayRunner disposes the partial adapter and retries with a fresh PTB app.
+_INITIAL_POLLING_PROGRESS_TIMEOUT = 60.0
 # shutdown()/initialize() on the getUpdates httpx request close and rebuild the
 # connection pool. When a connection is wedged on a stale CLOSE-WAIT socket that
 # close can block forever, hanging _drain_polling_connections() and freezing the
@@ -2129,8 +2143,17 @@ class TelegramAdapter(BasePlatformAdapter):
         *,
         drop_pending_updates: bool,
         error_callback,
-    ) -> None:
-        """Start one generation and verify real getUpdates progress."""
+        abandon_app_on_timeout: bool = False,
+        schedule_verifier: bool = True,
+    ) -> tuple[int, asyncio.Event]:
+        """Start one generation and verify real getUpdates progress.
+
+        Returns the ``(generation, progress_event)`` pair created for this
+        polling generation so callers that must gate on readiness (strict
+        cold start, #67498) can bind to exactly this generation instead of
+        re-reading ``self._polling_progress_event`` — which a concurrent
+        recovery task may have replaced with a newer generation's event.
+        """
         if getattr(self, "_polling_teardown_started", False):
             raise _PollingLifecycleAbort("Telegram polling teardown started")
         generation, progress = self._begin_polling_generation()
@@ -2151,13 +2174,22 @@ class TelegramAdapter(BasePlatformAdapter):
 
         context_token = _POLLING_GENERATION_CONTEXT.set(generation)
         try:
-            await asyncio.wait_for(
+            # asyncio.wait_for can wait forever for cancellation to escape
+            # httpcore/AnyIO shielded scopes (#58236/#67498). Reuse the
+            # proven wall-deadline helper and abandon the partial updater;
+            # caller recovery will dispose/rebuild the whole adapter.
+            await _await_with_thread_deadline(
                 app.updater.start_polling(
                     allowed_updates=Update.ALL_TYPES,
                     drop_pending_updates=drop_pending_updates,
                     error_callback=_generation_error_callback,
                 ),
                 timeout=_UPDATER_START_TIMEOUT,
+                on_abandon=(
+                    (lambda app=app: _shutdown_abandoned_app(app))
+                    if abandon_app_on_timeout
+                    else None
+                ),
             )
         finally:
             _POLLING_GENERATION_CONTEXT.reset(context_token)
@@ -2165,7 +2197,9 @@ class TelegramAdapter(BasePlatformAdapter):
             self._polling_progress_accepting = False
             self._send_path_degraded = True
             raise _PollingLifecycleAbort("Telegram polling teardown started")
-        self._schedule_polling_progress_verifier(generation, progress)
+        if schedule_verifier:
+            self._schedule_polling_progress_verifier(generation, progress)
+        return generation, progress
 
     def _schedule_polling_progress_verifier(
         self, generation: int, progress: asyncio.Event
@@ -2264,12 +2298,14 @@ class TelegramAdapter(BasePlatformAdapter):
         self._background_tasks.add(self._polling_error_task)
         self._polling_error_task.add_done_callback(self._background_tasks.discard)
 
-    async def _delete_webhook_best_effort(self) -> bool:
-        """Clear any stale webhook, but never fail polling on a network error.
+    async def _delete_webhook_best_effort(
+        self, *, require_success: bool = False
+    ) -> bool:
+        """Clear stale webhook, optionally failing closed on initial connect.
 
-        Returns True when the webhook was cleared (or there was nothing to do)
-        and False when a transient network error was swallowed so bootstrap can
-        continue to polling; the reconnect ladder recovers from there.
+        Reconnect can recover a transient error in background. Cold startup uses
+        ``require_success`` so GatewayRunner disposes the partial adapter and
+        retries with a fresh PTB Application instead of publishing degraded state.
         """
         if not self._bot:
             return False
@@ -2277,10 +2313,19 @@ class TelegramAdapter(BasePlatformAdapter):
         if not callable(delete_webhook):
             return True
         try:
-            await delete_webhook(drop_pending_updates=False)
+            # Same shielded-cancellation class as initialize/start_polling:
+            # never let a wedged duplicate deleteWebhook pin initial connect.
+            await _await_with_thread_deadline(
+                delete_webhook(drop_pending_updates=False),
+                timeout=_UPDATER_START_TIMEOUT,
+            )
             return True
         except Exception as err:
             if self._looks_like_network_error(err):
+                if require_success:
+                    raise OSError(
+                        "Telegram deleteWebhook did not complete during initial connect"
+                    ) from err
                 logger.warning(
                     "[%s] deleteWebhook failed with a recoverable network error; "
                     "continuing to polling so getUpdates/retry can recover: %s",
@@ -2290,17 +2335,57 @@ class TelegramAdapter(BasePlatformAdapter):
                 return False
             raise
 
-    async def _start_polling_resilient(self, *, drop_pending_updates: bool, error_callback) -> bool:
-        """Start PTB polling; on a transient bootstrap failure, recover in background.
+    async def _start_polling_resilient(
+        self,
+        *,
+        drop_pending_updates: bool,
+        error_callback,
+        require_progress: bool = False,
+    ) -> bool:
+        """Start PTB polling and optionally require real getUpdates readiness.
 
-        Returns True when polling started, False when a transient conflict or
-        network error was scheduled for background recovery instead of raising
-        (keeping the gateway process alive).
+        Reconnects may recover in background. Initial connect sets
+        ``require_progress`` so a bootstrap failure or missing first successful
+        getUpdates response raises; GatewayRunner then disposes this partial
+        adapter and retries with a fresh PTB Application.
         """
         if getattr(self, "_polling_teardown_started", False):
             return False
         if not (self._app and self._app.updater):
             raise RuntimeError("Telegram application/updater not initialized")
+
+        # Strict cold start (#67498): background recovery must not run while
+        # the readiness gate is waiting. A G1 polling error would otherwise
+        # schedule _handle_polling_network_error(), which starts generation
+        # G2 on the same partial application while this coroutine still waits
+        # on G1's event — the cold connect then either times out on G1 despite
+        # G2 succeeding, or G2 "heals" the partial app so GatewayRunner never
+        # disposes it and retries fresh. Instead, capture the first polling
+        # error and fail the cold attempt immediately; GatewayRunner owns
+        # disposal and retry with a fresh adapter.
+        strict_error: list[BaseException] = []
+        strict_error_event = asyncio.Event()
+        strict_gate_open = True
+        effective_callback = error_callback
+        if require_progress:
+            loop = asyncio.get_running_loop()
+
+            def _strict_error_callback(error: Exception) -> None:
+                # PTB registers this callback for the whole polling
+                # generation. After the readiness gate closes (success),
+                # delegate to the real callback so ongoing polling errors
+                # keep flowing into background recovery.
+                if not strict_gate_open:
+                    if error_callback is not None:
+                        error_callback(error)
+                    return
+                if not strict_error:
+                    strict_error.append(error)
+                # PTB invokes error callbacks from the polling task; the
+                # event must be set on the loop to wake the strict waiter.
+                loop.call_soon_threadsafe(strict_error_event.set)
+
+            effective_callback = _strict_error_callback
         try:
             # Same watchdog bound as the reconnect ladders: a wedged httpx
             # connection pool can hang start_polling() forever at bootstrap
@@ -2308,17 +2393,63 @@ class TelegramAdapter(BasePlatformAdapter):
             # TimeoutError (OSError subclass), so the except below classifies
             # it via _looks_like_network_error and schedules background
             # recovery instead of blocking connect() indefinitely.
-            await self._start_polling_once(
+            generation, progress = await self._start_polling_once(
                 self._app,
                 drop_pending_updates=drop_pending_updates,
-                error_callback=error_callback,
+                error_callback=effective_callback,
+                abandon_app_on_timeout=require_progress,
+                # The strict gate below IS the cold-start verifier; the
+                # background verifier would only race it on the partial app.
+                schedule_verifier=not require_progress,
             )
+            if require_progress:
+                # Bind to THIS generation's progress event (returned above),
+                # not self._polling_progress_event — a concurrent task could
+                # have replaced it with a later generation's event.
+                progress_wait = asyncio.ensure_future(progress.wait())
+                error_wait = asyncio.ensure_future(strict_error_event.wait())
+                try:
+                    await _await_with_thread_deadline(
+                        _first_completed(progress_wait, error_wait),
+                        timeout=_INITIAL_POLLING_PROGRESS_TIMEOUT,
+                    )
+                except asyncio.TimeoutError as exc:
+                    raise OSError(
+                        "Telegram getUpdates made no progress within "
+                        f"{_INITIAL_POLLING_PROGRESS_TIMEOUT:.0f}s during initial "
+                        "connect — failing startup so the gateway retries with a "
+                        "fresh adapter (#67498)"
+                    ) from exc
+                finally:
+                    for fut in (progress_wait, error_wait):
+                        if not fut.done():
+                            fut.cancel()
+                    await asyncio.gather(
+                        progress_wait, error_wait, return_exceptions=True
+                    )
+                if strict_error and not progress.is_set():
+                    raise OSError(
+                        "Telegram polling errored before first getUpdates "
+                        "success during initial connect: "
+                        f"{_redact_telegram_error_text(strict_error[0])}"
+                    ) from strict_error[0]
+                if not progress.is_set():
+                    raise OSError(
+                        "Telegram getUpdates did not become ready during initial connect"
+                    )
+                # Readiness proven — close the strict gate so any later
+                # polling error flows to the real background-recovery
+                # callback instead of the (now finished) cold-start gate.
+                strict_gate_open = False
+                self._polling_error_callback_ref = error_callback
             return True
         except _PollingLifecycleAbort:
             return False
         except Exception as err:
             if getattr(self, "_polling_teardown_started", False):
                 return False
+            if require_progress:
+                raise
             if self._looks_like_polling_conflict(err):
                 logger.warning(
                     "[%s] Telegram polling bootstrap conflict; gateway stays alive "
@@ -3623,8 +3754,30 @@ class TelegramAdapter(BasePlatformAdapter):
             # fallback-IP chain can't block startup indefinitely.
             _max_connect = 8
             _init_timeout = _env_float("HERMES_TELEGRAM_INIT_TIMEOUT", 30.0)
+            # Total watchdog: ensure the entire connect loop has an upper bound
+            # even if the retry loop itself silently stalls (#67498). This is
+            # the per-attempt timeout PLUS generous margins between attempts so
+            # we never hang past the sum even when all attempts are exhausted.
+            _total_deadline = (
+                asyncio.get_running_loop().time()
+                + _init_timeout * _max_connect
+                + 120.0  # extra margin for between-attempt sleeps + overhead
+            )
             for _attempt in range(_max_connect):
+                rebuild_app = False
                 try:
+                    # Check total watchdog deadline — if we blew past it the
+                    # retry ladder must yield even if no individual attempt
+                    # has raised.
+                    if asyncio.get_running_loop().time() >= _total_deadline:
+                        raise OSError(
+                            f"Telegram initialization timed out after {_max_connect} attempts "
+                            f"({_init_timeout:.0f}s each) — total connect watchdog "
+                            f"deadline ({_init_timeout * _max_connect + 120.0:.0f}s) exceeded. "
+                            f"Check network connectivity to api.telegram.org "
+                            f"or set HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT / "
+                            f"HERMES_TELEGRAM_INIT_TIMEOUT to a lower value."
+                        )
                     logger.warning(
                         "[%s] Connecting to Telegram (attempt %d/%d)…",
                         self.name, _attempt + 1, _max_connect,
@@ -3642,6 +3795,7 @@ class TelegramAdapter(BasePlatformAdapter):
                     )
                     break
                 except asyncio.TimeoutError:
+                    rebuild_app = True
                     if _attempt < _max_connect - 1:
                         wait = min(2 ** _attempt, 15)
                         logger.warning(
@@ -3656,6 +3810,7 @@ class TelegramAdapter(BasePlatformAdapter):
                             f"or set HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT to a lower value."
                         )
                 except OSError as init_err:
+                    rebuild_app = True
                     if _attempt < _max_connect - 1:
                         wait = min(2 ** _attempt, 15)
                         logger.warning(
@@ -3666,6 +3821,7 @@ class TelegramAdapter(BasePlatformAdapter):
                     else:
                         raise
                 except Exception as init_err:
+                    rebuild_app = True
                     if not self._looks_like_network_error(init_err):
                         raise
                     if _attempt < _max_connect - 1:
@@ -3677,6 +3833,57 @@ class TelegramAdapter(BasePlatformAdapter):
                         await asyncio.sleep(wait)
                     else:
                         raise
+                except BaseException:
+                    # Catch CancelledError and other BaseException subclasses
+                    # that the existing except handlers miss. Log the event so
+                    # the operator can diagnose, then reraise so cancellation
+                    # semantics are preserved (#67498).
+                    # NOTE: placed LAST so Exception handlers above have
+                    # priority — BaseException catches everything including
+                    # Exception.
+                    logger.warning(
+                        "[%s] Connect attempt %d/%d interrupted by %s — propagating",
+                        self.name,
+                        _attempt + 1,
+                        _max_connect,
+                        "CancelledError"
+                        if isinstance(sys.exc_info()[1], asyncio.CancelledError)
+                        else type(sys.exc_info()[1]).__name__,
+                    )
+                    raise
+                finally:
+                    # After a failed attempt the app may be in a partially-
+                    # initialized state (closed transports, half-built handlers).
+                    # Rebuild from the same token/config so the next attempt
+                    # starts with a fresh Application — the old one is discarded
+                    # and will be GC'd (#67498).
+                    if rebuild_app and _attempt < _max_connect - 1:
+                        old_app = self._app
+                        self._app = builder.build()
+                        self._bot = self._app.bot
+                        # Re-register handlers on the new app
+                        self._app.add_handler(TelegramMessageHandler(
+                            filters.TEXT & ~filters.COMMAND,
+                            self._handle_text_message
+                        ))
+                        self._app.add_handler(TelegramMessageHandler(
+                            filters.COMMAND,
+                            self._handle_command
+                        ))
+                        self._app.add_handler(TelegramMessageHandler(
+                            filters.LOCATION | getattr(filters, "VENUE", filters.LOCATION),
+                            self._handle_location_message
+                        ))
+                        self._app.add_handler(TelegramMessageHandler(
+                            filters.PHOTO | filters.VIDEO | filters.AUDIO | filters.VOICE | filters.Document.ALL | filters.Sticker.ALL,
+                            self._handle_media_message
+                        ))
+                        self._app.add_handler(CallbackQueryHandler(self._handle_callback_query))
+                        # Best-effort discard the old app's resources
+                        try:
+                            await _shutdown_abandoned_app(old_app)
+                        except Exception:
+                            pass
             await self._app.start()
 
             # Decide between webhook and polling mode
@@ -3739,7 +3946,9 @@ class TelegramAdapter(BasePlatformAdapter):
                 # updates. Best-effort: a transient Bot API network error here
                 # must not fail gateway startup — degrade to background polling
                 # recovery instead.
-                await self._delete_webhook_best_effort()
+                await self._delete_webhook_best_effort(
+                    require_success=not is_reconnect
+                )
 
                 loop = asyncio.get_running_loop()
 
@@ -3777,6 +3986,7 @@ class TelegramAdapter(BasePlatformAdapter):
                     # sent while the bot was offline are delivered (#46621).
                     drop_pending_updates=not is_reconnect,
                     error_callback=_polling_error_callback,
+                    require_progress=not is_reconnect,
                 )
                 if not polling_started:
                     logger.warning(
@@ -5073,7 +5283,10 @@ class TelegramAdapter(BasePlatformAdapter):
                         InlineKeyboardButton("✅ Always", callback_data=f"ea:always:{approval_id}")
                     )
             buttons.append(InlineKeyboardButton("❌ Deny", callback_data=f"ea:deny:{approval_id}"))
-            keyboard = InlineKeyboardMarkup([buttons])
+            # Pair into rows (2x2 for the full set) so labels stay readable on
+            # mobile — a single 4-button row truncates to "Allo… / Ses… / …".
+            rows = [buttons[i:i + 2] for i in range(0, len(buttons), 2)]
+            keyboard = InlineKeyboardMarkup(rows)
 
             kwargs: Dict[str, Any] = {
                 "chat_id": normalize_telegram_chat_id(chat_id),
@@ -6276,7 +6489,7 @@ class TelegramAdapter(BasePlatformAdapter):
             home = get_hermes_home()
             response_path = home / ".update_response"
             tmp = response_path.with_suffix(".tmp")
-            tmp.write_text(answer)
+            tmp.write_text(answer, encoding="utf-8")
             tmp.replace(response_path)
             logger.info("Telegram update prompt answered '%s' by user %s",
                         answer, getattr(query.from_user, "id", "unknown"))
diff --git a/plugins/platforms/whatsapp/adapter.py b/plugins/platforms/whatsapp/adapter.py
index df351f4863a..8d654197e04 100644
--- a/plugins/platforms/whatsapp/adapter.py
+++ b/plugins/platforms/whatsapp/adapter.py
@@ -55,7 +55,7 @@ def _listener_pids_on_port(port: int) -> list:
     try:
         result = subprocess.run(
             ["lsof", "-ti", f"tcp:{port}", "-sTCP:LISTEN"],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
         )
         for line in result.stdout.strip().splitlines():
             try:
@@ -70,7 +70,7 @@ def _listener_pids_on_port(port: int) -> list:
     try:
         result = subprocess.run(
             ["ss", "-ltnHp", f"sport = :{port}"],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
         )
         for m in re.finditer(r"pid=(\d+)", result.stdout):
             pids.append(int(m.group(1)))
@@ -88,7 +88,7 @@ def _kill_port_process(port: int) -> None:
             # Use netstat to find the PID bound to this port, then taskkill
             result = subprocess.run(
                 ["netstat", "-ano", "-p", "TCP"],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
                 creationflags=windows_hide_flags(),
             )
             for line in result.stdout.splitlines():
@@ -167,7 +167,7 @@ def _kill_stale_bridge_by_pidfile(session_path: Path) -> None:
     try:
         # Format: line 1 = pid, optional line 2 = kernel start time. Legacy
         # files written before the guard existed have only the pid.
-        lines = pid_file.read_text().split("\n")
+        lines = pid_file.read_text(encoding="utf-8").split("\n")
         pid = int(lines[0].strip())
         if len(lines) > 1 and lines[1].strip():
             recorded_start = int(lines[1].strip())
@@ -208,7 +208,7 @@ def _write_bridge_pidfile(session_path: Path, pid: int) -> None:
         from gateway.status import get_process_start_time
         start = get_process_start_time(pid)
         text = str(pid) if start is None else "{}\n{}".format(pid, start)
-        (session_path / "bridge.pid").write_text(text)
+        (session_path / "bridge.pid").write_text(text, encoding="utf-8")
     except OSError:
         pass
 
@@ -223,7 +223,7 @@ def _terminate_bridge_process(proc, *, force: bool = False) -> None:
             result = subprocess.run(
                 cmd,
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=10,
             )
         except FileNotFoundError:
@@ -349,7 +349,7 @@ def check_whatsapp_requirements() -> bool:
         result = subprocess.run(
             [_node, "--version"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=5
         )
         return result.returncode == 0
@@ -531,7 +531,9 @@ class WhatsAppAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
             _deps_fresh = False
             if (bridge_dir / "node_modules").exists():
                 try:
-                    _deps_fresh = (_dep_stamp.read_text().strip() == _pkg_hash) and bool(_pkg_hash)
+                    _deps_fresh = (
+                        _dep_stamp.read_text(encoding="utf-8").strip() == _pkg_hash
+                    ) and bool(_pkg_hash)
                 except OSError:
                     _deps_fresh = False
             if not _deps_fresh:
@@ -547,7 +549,7 @@ class WhatsAppAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
                         [_npm_bin, "install", "--silent"],
                         cwd=str(bridge_dir),
                         capture_output=True,
-                        text=True,
+                        text=True, encoding='utf-8', errors='replace',
                         timeout=npm_install_timeout,
                         env=with_hermes_node_path(),
                     )
@@ -557,7 +559,7 @@ class WhatsAppAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
                     print(f"[{self.name}] Dependencies installed")
                     if _pkg_hash:
                         try:
-                            _dep_stamp.write_text(_pkg_hash)
+                            _dep_stamp.write_text(_pkg_hash, encoding="utf-8")
                         except OSError:
                             pass  # Stamp is an optimization; install still succeeded
                 except Exception as e:
diff --git a/plugins/web/ddgs/provider.py b/plugins/web/ddgs/provider.py
index 44a3aca6c8c..824f3edba6d 100644
--- a/plugins/web/ddgs/provider.py
+++ b/plugins/web/ddgs/provider.py
@@ -193,6 +193,8 @@ def _run_ddgs_search_bounded(query: str, safe_limit: int) -> list[dict[str, Any]
         stderr=subprocess.DEVNULL,
         env=env,
         text=True,
+        encoding="utf-8",
+        errors="replace",
         **extra_kwargs,
     )
     _last_worker_proc = proc
diff --git a/pyproject.toml b/pyproject.toml
index 03da3b98b18..ea5d84f6b36 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -340,6 +340,7 @@ markers = [
     "integration: marks tests requiring external services (API keys, Modal, etc.)",
     "real_concurrent_gate: opt out of the autouse stub that disables _detect_concurrent_hermes_instances",
     "real_agent_prewarm: opt out of the autouse stub that disables the tui_gateway deferred agent pre-warm timer",
+    "requires_wal: needs the runtime to actually enable SQLite WAL mode (skipped where Hermes falls back to journal_mode=DELETE)",
 ]
 # integration tests take way too long to run in the normal CI environments
 addopts = "-m 'not integration'"
diff --git a/run_agent.py b/run_agent.py
index fffb03dfb01..263a13e5b40 100644
--- a/run_agent.py
+++ b/run_agent.py
@@ -239,6 +239,12 @@ _EPHEMERAL_SCAFFOLDING_FLAGS = (
     "_pre_verify_synthetic",
     # kanban worker stop-guard: narrated exit without kanban_complete/block
     "_kanban_stop_synthetic",
+    # dropped tool-call re-prompt pair (finish_reason=tool_calls with an
+    # empty tool_calls array): the interim narration-only assistant turn
+    # and the "issue the actual tool call now" user nudge exist only to
+    # drive the bounded retry. Persisting them would replay the internal
+    # retry instruction as user-authored context on resume.
+    "_dropped_toolcall_nudge",
 )
 
 
@@ -2091,6 +2097,9 @@ class AIAgent:
                         and not msg.get("_compressed_summary_has_user_turn")
                         else msg.get("display_kind")
                     ),
+                    compression_lock_holder=getattr(
+                        self, "_active_compression_lock_holder", None
+                    ),
                 )
                 msg[_DB_PERSISTED_MARKER] = True
             # The intrinsic markers are now the sole source of truth. Reset the
@@ -3807,11 +3816,16 @@ class AIAgent:
         except Exception:
             pass
 
-        # Close the OpenAI/httpx client to release sockets immediately.
+        # Retire the OpenAI/httpx client to release sockets immediately.
+        # #70773: eviction runs on the gateway's memory-manager thread — a
+        # cross-thread hard close of the shared client can release TLS FDs
+        # under a still-unwinding worker (FD-recycle → SQLite corruption).
+        # Retirement shuts the pooled sockets down (the memory/socket win we
+        # want here) and lets GC release the FDs once no thread holds them.
         try:
             client = getattr(self, "client", None)
             if client is not None:
-                self._close_openai_client(client, reason="cache_evict", shared=True)
+                self._retire_shared_openai_client(client, reason="cache_evict")
                 self.client = None
         except Exception:
             pass
@@ -4375,6 +4389,47 @@ class AIAgent:
                 exc,
             )
 
+    def _retire_shared_openai_client(self, client: Any, *, reason: str) -> None:
+        """Ownership-safe retirement of a replaced shared OpenAI client.
+
+        #70773 / #67142 / #29507: ``client.close()`` releases the pool's raw
+        FDs from the *calling* thread. The shared primary client has no single
+        owning thread — worker threads from stale-killed attempts may still be
+        unwinding their SSL BIOs, and the codex-direct / MoA paths stream on
+        the shared client itself. If we release an FD while another thread's
+        SSL layer still caches the raw integer fd, the kernel can recycle it
+        into an unrelated ``open()`` (e.g. ``kanban.db``) and the unwinding
+        TLS flush then writes an application-data record into that file — the
+        SQLite-header corruption documented in #29507/#70773.
+
+        Only an owner may release FDs, and a replaced shared client has none.
+        So nobody calls ``close()``: we ``shutdown()`` the pooled sockets
+        (FD-safe from any thread; unblocks in-flight readers with EOF/EPIPE)
+        and defer the actual FD release to garbage collection. Refcounting
+        guarantees the underlying sockets are only collected once every
+        thread that borrowed the client has unwound — GC *is* the ownership
+        handshake. In the common case (no borrower) the refcount hits zero on
+        this line and the FDs are released immediately anyway.
+        """
+        if client is None:
+            return
+        try:
+            shutdown_count = self._force_close_tcp_sockets(client)
+            logger.info(
+                "Shared OpenAI client retired (%s, tcp_shutdown=%d, "
+                "fd_release=deferred_to_gc) %s",
+                reason,
+                shutdown_count,
+                self._client_log_context(),
+            )
+        except Exception as exc:
+            logger.debug(
+                "Shared OpenAI client retire failed (%s) %s error=%s",
+                reason,
+                self._client_log_context(),
+                exc,
+            )
+
     def _replace_primary_openai_client(self, *, reason: str) -> bool:
         with self._openai_client_lock():
             old_client = getattr(self, "client", None)
@@ -4389,7 +4444,13 @@ class AIAgent:
                 )
                 return False
             self.client = new_client
-        self._close_openai_client(old_client, reason=f"replace:{reason}", shared=True)
+        # #70773: never hard-close the replaced shared client from here — the
+        # caller may not be the thread whose request is still unwinding on the
+        # old pool (credential rotation and dead-connection cleanup run on the
+        # turn thread while stale-killed workers unwind; the codex-direct path
+        # streams on the shared client itself). Retire it instead: sockets are
+        # shut down (FD-safe), FD release deferred to GC.
+        self._retire_shared_openai_client(old_client, reason=f"replace:{reason}")
         return True
 
     def _ensure_primary_openai_client(self, *, reason: str) -> Any:
@@ -4962,6 +5023,7 @@ class AIAgent:
     def _swap_credential(self, entry) -> None:
         runtime_key = getattr(entry, "runtime_api_key", None) or getattr(entry, "access_token", "")
         runtime_base = getattr(entry, "runtime_base_url", None) or getattr(entry, "base_url", None) or self.base_url
+        self._credential_pool_entry_id = getattr(entry, "id", None)
         from hermes_cli.route_identity import normalize_route_base_url
 
         route_changed = normalize_route_base_url(self.base_url) != normalize_route_base_url(
@@ -6399,13 +6461,43 @@ class AIAgent:
         ``force=False``.
         """
         from agent.conversation_compression import compress_context
-        return compress_context(
-            self, messages, system_message,
-            approx_tokens=approx_tokens, task_id=task_id, focus_topic=focus_topic,
-            force=force,
-            defer_context_engine_notification=defer_context_engine_notification,
-            commit_fence=commit_fence,
+        from agent.portal_tags import (
+            get_conversation_context,
+            reset_conversation_context,
+            set_conversation_context,
         )
+        # Out-of-turn compaction entry points — ``/compact`` (cli.py), the
+        # gateway ``/compress`` command and its hygiene sweep (both of which
+        # build a throwaway agent), and partial head compression — call this
+        # forwarder directly, outside ``run_conversation``'s ambient scope.
+        # With nothing ambient the summarizer's auxiliary call carries no
+        # conversation tag and no Portal sticky key, so it routes independently
+        # of the conversation it belongs to. Publish the root here as a
+        # fallback; in-turn callers already have it set to the same value, so
+        # this is a no-op for them.
+        #
+        # Note this does NOT keep the compaction turn's own prompt cache warm:
+        # compaction replaces the history with a summary and rebuilds the
+        # system prompt, so that request is a cold write on any endpoint. What
+        # it buys is the turns AFTER compaction reading the cache it wrote.
+        token = None
+        if get_conversation_context() is None:
+            root = self._conversation_root_id()
+            if root:
+                token = set_conversation_context(root)
+        try:
+            return compress_context(
+                self, messages, system_message,
+                approx_tokens=approx_tokens, task_id=task_id, focus_topic=focus_topic,
+                force=force,
+                defer_context_engine_notification=defer_context_engine_notification,
+                commit_fence=commit_fence,
+            )
+        finally:
+            # Restore whatever the caller had, so a compaction never leaks its
+            # tag into the surrounding scope.
+            if token is not None:
+                reset_conversation_context(token)
 
     def _set_tool_guardrail_halt(self, decision: ToolGuardrailDecision) -> None:
         """Record the first guardrail decision that should stop this turn."""
diff --git a/scripts/add_contributor.py b/scripts/add_contributor.py
index 8192fe4f55c..cb64b331cbb 100644
--- a/scripts/add_contributor.py
+++ b/scripts/add_contributor.py
@@ -25,7 +25,11 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
 EMAILS_DIR = REPO_ROOT / "contributors" / "emails"
 
 _EMAIL_RE = re.compile(r"^[^/\\\s]+@[^/\\\s]+$")
-_LOGIN_RE = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$")
+# GitHub's *current* signup rules forbid consecutive hyphens, but legacy
+# accounts with them exist and are valid (e.g. Roger--Han, verified via the
+# users API July 2026). Accept any alphanumeric/hyphen login that doesn't
+# start or end with a hyphen, max 39 chars.
+_LOGIN_RE = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$")
 
 
 def read_mapping_file(path: Path) -> str | None:
diff --git a/scripts/check-windows-footguns.py b/scripts/check-windows-footguns.py
index c0ca6622ec3..bb45d85a1e0 100644
--- a/scripts/check-windows-footguns.py
+++ b/scripts/check-windows-footguns.py
@@ -324,6 +324,83 @@ FOOTGUNS: list[Footgun] = [
             "    pass  # Windows asyncio doesn't support signal handlers"
         ),
     ),
+    Footgun(
+        name="subprocess text=True without explicit encoding=",
+        # Match ``text=True`` (or ``text = True``) anywhere on a line. We
+        # rely on the post_filter to (a) skip lines that already pass
+        # ``encoding=`` on the same line, and (b) skip false positives like
+        # ``def text(self, ...)`` or string literals. ``text=True`` is
+        # overwhelmingly a subprocess kwarg, so a bare match + filter has a
+        # high signal-to-noise ratio and avoids the complexity of parsing
+        # multi-line subprocess calls (which the line-based scanner can't
+        # reliably attribute to a single line anyway).
+        pattern=re.compile(r"\btext\s*=\s*True\b"),
+        message=(
+            "subprocess text=True without explicit encoding= decodes "
+            "child output with locale.getpreferredencoding() — cp936 "
+            "(GBK) on Chinese Windows, cp1252 on Western Windows — "
+            "which crashes _readerthread with UnicodeDecodeError on "
+            "non-default-codepage bytes. Always pass encoding='utf-8' "
+            "(and errors='replace' for Windows-native CLIs that emit "
+            "non-UTF-8). See issues #47939, #53428, #57238."
+        ),
+        fix=(
+            "subprocess.run(..., text=True, encoding='utf-8', "
+            "errors='replace')\n"
+            "Both params are required: encoding alone still crashes on "
+            "non-UTF-8 bytes from Windows-native CLIs (tasklist, "
+            "schtasks)."
+        ),
+        post_filter=lambda m, line: (
+            # Skip if the same line already specifies encoding=.
+            "encoding=" not in line
+            and "encoding =" not in line
+            # Skip method definitions named ``text`` (def text(self, ...)).
+            and not line.lstrip().startswith("def ")
+            and not line.lstrip().startswith("async def ")
+            # Skip ``text=True`` inside string literals (heuristic: the
+            # substring appears between matching quotes that aren't part
+            # of an f-string expression). This is imperfect but catches
+            # the common case of docstrings mentioning text=True.
+            and not _looks_like_string_literal(line, m)
+            # Skip lines that are obviously not subprocess calls — e.g.
+            # DataFrame.rename(text=True) or similar. We can't know for
+            # sure without parsing, so we accept some false negatives by
+            # only flagging when ``subprocess`` or a known subprocess-
+            # shaped call (run/Popen/call/check_output/check_call/
+            # check_output) appears on the same line. This keeps the
+            # rule focused on the actual footgun.
+            and _is_likely_subprocess_call(line)
+        ),
+    ),
+    Footgun(
+        name="bare Path.read_text()/write_text() without encoding=",
+        # Match ``.read_text(`` / ``.write_text(`` when the same line does
+        # not pass ``encoding=``. Multi-line calls where encoding= sits on
+        # a later line are handled by the post_filter's lookahead-free
+        # heuristic accepting a small false-negative rate — the AST guard
+        # test in tests/gateway/test_gateway_utf8_encoding.py catches the
+        # gateway/adapters exactly, and this rule catches the common
+        # single-line form everywhere else.
+        pattern=re.compile(r"\.(read_text|write_text)\s*\("),
+        message=(
+            "Path.read_text()/write_text() without encoding= uses "
+            "locale.getpreferredencoding() — cp936/cp1252 on Windows — "
+            "so UTF-8 content (config JSON, session state, skills) "
+            "crashes with UnicodeDecodeError or writes mojibake. "
+            "See issue #37423 and the #71014 / read_text campaign."
+        ),
+        fix='path.read_text(encoding="utf-8") / path.write_text(data, encoding="utf-8")',
+        post_filter=lambda m, line: (
+            "encoding=" not in line
+            and "encoding =" not in line
+            and not _looks_like_string_literal(line, m)
+            # Skip calls that continue onto the next line — the closing
+            # paren isn't on this line, so encoding= may follow. AST-level
+            # enforcement for those lives in the gateway guard test.
+            and line.rstrip().endswith(")")
+        ),
+    ),
 ]
 
 
@@ -408,6 +485,66 @@ def _find_unquoted_hash(line: str) -> int | None:
     return None
 
 
+# Subprocess method names that accept ``text=`` and are affected by the
+# encoding-default footgun. Used by ``_is_likely_subprocess_call`` below to
+# keep the ``text=True`` rule focused on subprocess calls (and avoid flagging
+# unrelated APIs that happen to accept a ``text`` kwarg).
+_SUBPROCESS_METHODS = (
+    "subprocess.run",
+    "subprocess.Popen",
+    "subprocess.call",
+    "subprocess.check_output",
+    "subprocess.check_call",
+    "_sp.run",            # common alias
+    "_sp.Popen",
+    "_sp.check_output",
+    "_sp.check_call",
+    "_sp.call",
+    ".run(",              # bare .run( — usually subprocess.run
+    ".Popen(",
+    ".check_output(",
+    ".check_call(",
+    ".call(",
+)
+
+
+def _is_likely_subprocess_call(line: str) -> bool:
+    """Heuristic: does this line look like a subprocess invocation?
+
+    The ``text=True`` footgun rule only fires when the matched line also
+    contains a subprocess-shaped call site. This avoids false positives on
+    unrelated APIs that accept a ``text`` kwarg (e.g. DataFrame.rename,
+    custom library calls). Multi-line calls where the ``subprocess.X(``
+    prefix is on a previous line won't be flagged — that's an acceptable
+    false negative for a line-based scanner.
+    """
+    return any(token in line for token in _SUBPROCESS_METHODS)
+
+
+def _looks_like_string_literal(line: str, match: "re.Match") -> bool:
+    """Heuristic: is the ``text=True`` match inside a string literal?
+
+    Catches the common case of docstrings/comments that mention ``text=True``
+    as prose. Walks the line tracking single/double quote state and returns
+    True if the match start index falls inside a quoted region.
+    """
+    start = match.start()
+    in_s = False
+    in_d = False
+    i = 0
+    while i < start and i < len(line):
+        c = line[i]
+        if c == "\\" and (in_s or in_d) and i + 1 < len(line):
+            i += 2
+            continue
+        if not in_d and c == "'":
+            in_s = not in_s
+        elif not in_s and c == '"':
+            in_d = not in_d
+        i += 1
+    return in_s or in_d
+
+
 def scan_file(path: Path, footguns: list[Footgun]) -> list[tuple[int, str, Footgun]]:
     """Return a list of (line_number, line, footgun) for unsuppressed matches."""
     try:
@@ -492,7 +629,7 @@ def get_staged_files() -> list[Path]:
             ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"],
             cwd=REPO_ROOT,
             stderr=subprocess.DEVNULL,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
         )
     except (subprocess.CalledProcessError, FileNotFoundError):
         return []
@@ -506,7 +643,7 @@ def get_diff_files(ref: str) -> list[Path]:
             ["git", "diff", f"{ref}...HEAD", "--name-only", "--diff-filter=ACMR"],
             cwd=REPO_ROOT,
             stderr=subprocess.DEVNULL,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
         )
     except (subprocess.CalledProcessError, FileNotFoundError):
         return []
diff --git a/scripts/check_subprocess_stdin.py b/scripts/check_subprocess_stdin.py
index eca28b814ee..884923e2e04 100644
--- a/scripts/check_subprocess_stdin.py
+++ b/scripts/check_subprocess_stdin.py
@@ -181,7 +181,7 @@ def main() -> int:
             if any(skip.rstrip("/") in parts for skip in SKIP_DIRS):
                 continue
 
-            content = py_file.read_text()
+            content = py_file.read_text(encoding="utf-8")
             violations = find_subprocess_calls(content, rel)
             all_violations.extend(violations)
 
@@ -205,7 +205,7 @@ def main() -> int:
                 continue
 
             try:
-                content = py_file.read_text()
+                content = py_file.read_text(encoding="utf-8")
             except Exception:
                 continue
             violations = find_subprocess_calls(content, rel)
diff --git a/scripts/ci/assemble_review_comment.py b/scripts/ci/assemble_review_comment.py
index 76f3488012a..312f3c05876 100644
--- a/scripts/ci/assemble_review_comment.py
+++ b/scripts/ci/assemble_review_comment.py
@@ -419,7 +419,7 @@ def main() -> int:
         pending_jobs=pending,
     )
 
-    args.output.write_text(body)
+    args.output.write_text(body, encoding="utf-8")
     print(f"Wrote {len(body)} chars to {args.output}")
     return 0
 
diff --git a/scripts/ci/lockfile_diff.py b/scripts/ci/lockfile_diff.py
index 46712ad3760..a118eb1e5dc 100644
--- a/scripts/ci/lockfile_diff.py
+++ b/scripts/ci/lockfile_diff.py
@@ -115,7 +115,7 @@ def _git_show(ref: str, path: str, repo_root: str) -> str | None:
     proc = subprocess.run(
         ["git", "show", f"{ref}:{path}"],
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         cwd=repo_root,
     )
     return proc.stdout if proc.returncode == 0 else None
@@ -125,7 +125,7 @@ def _tracked_lockfiles(ref: str, repo_root: str) -> set[str]:
     proc = subprocess.run(
         ["git", "ls-tree", "-r", "--name-only", ref],
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         cwd=repo_root,
         check=True,
     )
diff --git a/scripts/ci/publish_e2e_evidence.py b/scripts/ci/publish_e2e_evidence.py
index 94ad6af6659..7d5de456274 100644
--- a/scripts/ci/publish_e2e_evidence.py
+++ b/scripts/ci/publish_e2e_evidence.py
@@ -246,7 +246,7 @@ def upload_evidence(
                 ],
                 check=True,
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
                 env=environment,
             )
         except subprocess.CalledProcessError as exc:
diff --git a/scripts/contributor_audit.py b/scripts/contributor_audit.py
index 460bb1ca897..6bd57956727 100644
--- a/scripts/contributor_audit.py
+++ b/scripts/contributor_audit.py
@@ -87,7 +87,7 @@ def git(*args, cwd=None):
     result = subprocess.run(
         ["git"] + list(args),
         capture_output=True,
-        text=True,
+        text=True, encoding='utf-8', errors='replace',
         cwd=cwd or str(REPO_ROOT),
     )
     if result.returncode != 0:
@@ -112,7 +112,7 @@ def gh_pr_list():
                 "--limit", "300",
             ],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=60,
         )
         if result.returncode != 0:
diff --git a/scripts/generate_conformance_vectors.py b/scripts/generate_conformance_vectors.py
new file mode 100644
index 00000000000..97228e83333
--- /dev/null
+++ b/scripts/generate_conformance_vectors.py
@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""Conformance-vector generator — the native adapters as executable spec.
+
+Renders a shared corpus (markdown grid + scar tissue + adversarial agent
+output) through the NATIVE platform renderers and dumps input→output JSON
+vectors, stamped with the oracle commit. The gateway-gateway connector
+commits these under conformance/vectors/ and its vitest runner asserts the
+CONNECTOR's constructed REST payloads against them — so cross-repo renderer
+drift breaks a test instead of a user's formatting.
+
+Oracles (all imported, never reimplemented):
+  telegram  plugins.platforms.telegram.adapter.TelegramAdapter.format_message
+            (standard markdown → Telegram MarkdownV2)
+  slack     plugins.platforms.slack.adapter.SlackAdapter.format_message
+            (standard markdown → Slack mrkdwn)
+  whatsapp  gateway.platforms.whatsapp_common.WhatsAppBehaviorMixin
+            .format_message (standard markdown → WhatsApp formatting)
+  discord   plugins.platforms.discord.adapter.DiscordAdapter.format_message
+            (GFM tables → bullet groups; otherwise identity)
+
+Expect semantics (consumed by the gg runner):
+  parity    connector render must BYTE-EQUAL native_output
+            (Slack / WhatsApp — same-dialect ports; most Discord).
+  semantic  connector renders a DIFFERENT representation on purpose
+            (Telegram: connector sends HTML, native sends MarkdownV2);
+            the runner asserts plain-text content equivalence instead.
+  divergent documented no-parity (e.g. Discord tables: native converts to
+            bullets, connector passes raw markdown through). The runner
+            asserts the DOCUMENTED connector behavior named in `note`.
+
+Run:  python scripts/generate_conformance_vectors.py [--out DIR]
+Determinism is covered by tests/conformance/test_vector_generator.py.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Callable, Dict, List
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT))
+
+GENERATOR_VERSION = 1
+
+# ── corpus ───────────────────────────────────────────────────────────────
+# Every entry: (id, category, input). Categories: grid | scar | adversarial.
+# Ids are STABLE API — the runner and divergence notes key on them.
+
+GRID: List[tuple] = [
+    ("plain-text", "Just a plain sentence."),
+    ("bold", "This is **bold** text."),
+    ("italic", "This is *italic* text."),
+    ("bold-italic", "Mix of **bold** and *italic* in one line."),
+    ("strikethrough", "This is ~~struck~~ text."),
+    ("inline-code", "Run `pip install hermes` to start."),
+    ("fenced-code", "```\nprint('hello')\n```"),
+    ("fenced-code-lang", "```python\ndef f(x):\n    return x * 2\n```"),
+    ("link", "See [the docs](https://example.com/docs) for more."),
+    ("link-parens-url", "See [spec](https://example.com/a_(b)) here."),
+    ("header-h1", "# Big Title\nBody follows."),
+    ("header-h2", "## Section\nBody follows."),
+    ("header-h3", "### Sub-section\nBody follows."),
+    ("ul-list", "- first\n- second\n- third"),
+    ("ol-list", "1. first\n2. second\n3. third"),
+    ("nested-list", "- outer\n  - inner one\n  - inner two\n- outer two"),
+    ("blockquote", "> quoted wisdom\nregular line"),
+    ("hrule", "above\n\n---\n\nbelow"),
+    (
+        "table-simple",
+        "| name | value |\n|------|-------|\n| a    | 1     |\n| b    | 2     |",
+    ),
+    ("emoji", "Done ✅ with 🎉 emoji 👀 test."),
+    ("cjk", "中文测试：**粗体** 和 `代码` 混排。"),
+    ("bare-url", "Visit https://example.com/path?q=1&r=2 today."),
+    (
+        "mixed-document",
+        "## Report\n\nStatus: **green**. Details in `runbook.md`.\n\n"
+        "- item *one*\n- item **two**\n\n```sh\nmake deploy\n```\n\n"
+        "See [dashboard](https://grafana.example.com/d/x).",
+    ),
+]
+
+SCAR: List[tuple] = [
+    # MarkdownV2 reserved characters in prose — the classic Telegram 400.
+    ("mdv2-reserved-chars", "Price is 3.50 (was 4.00) — save ~12%! #deal +tax = win."),
+    ("mdv2-underscores", "snake_case_name and file_name.py in prose."),
+    ("mdv2-brackets", "Array[0] and dict{key} and (parens) live here."),
+    # Slack: **bold** must become *bold*; [t](u) must become <u|t>.
+    ("slack-bold-conversion", "**important** word"),
+    ("slack-link-conversion", "[click here](https://example.com)"),
+    # Slack broadcast-mention escape (model output must not ping @everyone).
+    ("slack-broadcast-mention", "Hey <!everyone> and <!channel> and <!here>!"),
+    # Fence language tag handling (Slack renders the tag literally).
+    ("fence-lang-tag-slack", "```text\nliteral first line issue\n```"),
+    # Backslashes inside code must survive doubling rules.
+    ("backslash-in-code", "`C:\\Users\\ben\\file.txt` and ```\npath = \"a\\\\b\"\n```"),
+    ("backtick-in-fence", "```\nuse `inline` inside fence\n```"),
+    # Headers containing bold markers (native strips redundant **).
+    ("header-with-bold", "## The **Real** Deal"),
+    # Table with CJK cells (display-width alignment scar in Slack).
+    (
+        "table-cjk",
+        "| 名前 | 値 |\n|------|----|\n| 中文 | 42 |\n| b    | 2  |",
+    ),
+    # Link display text that itself needs escaping.
+    ("link-display-escapes", "[v2.0 (beta)](https://example.com/v2)"),
+]
+
+ADVERSARIAL: List[tuple] = [
+    ("media-tag", "Here you go\nMEDIA:/tmp/output.png\ndone"),
+    ("unclosed-fence", "```python\nprint('never closed')"),
+    ("pathological-nesting", "**bold *italic ~~struck `code` struck~~ italic* bold**"),
+    ("placeholder-injection", "sneaky \x00PH0\x00 token and \x00SL1\x00 too"),
+    ("triple-markers", "***what is this*** and ____that____"),
+    ("empty-string", ""),
+    ("whitespace-only", "   \n\t\n   "),
+    ("long-line", "word " * 500),
+    ("many-fences", "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail"),
+]
+
+
+def corpus() -> List[Dict[str, str]]:
+    rows: List[Dict[str, str]] = []
+    for cid, text in GRID:
+        rows.append({"id": cid, "category": "grid", "input": text})
+    for cid, text in SCAR:
+        rows.append({"id": cid, "category": "scar", "input": text})
+    for cid, text in ADVERSARIAL:
+        rows.append({"id": cid, "category": "adversarial", "input": text})
+    return rows
+
+
+# ── oracles ──────────────────────────────────────────────────────────────
+
+
+def _oracles() -> Dict[str, Callable[[str], str]]:
+    from plugins.platforms.telegram.adapter import TelegramAdapter
+    from plugins.platforms.slack.adapter import SlackAdapter
+    from plugins.platforms.discord.adapter import DiscordAdapter
+    from gateway.platforms.whatsapp_common import WhatsAppBehaviorMixin
+
+    wa = object.__new__(WhatsAppBehaviorMixin)  # format_message needs no __init__
+
+    return {
+        # These format_message implementations are self-free (asserted by
+        # tests/conformance/test_vector_generator.py) — invoked unbound.
+        "telegram": lambda s: TelegramAdapter.format_message(None, s),  # type: ignore[arg-type]
+        "slack": lambda s: SlackAdapter.format_message(None, s),  # type: ignore[arg-type]
+        "discord": lambda s: DiscordAdapter.format_message(None, s),  # type: ignore[arg-type]
+        "whatsapp": wa.format_message,
+    }
+
+
+# Per-platform expect overrides (default: parity, except telegram=semantic).
+# Keyed by vector id; value = (expect, note).
+_EXPECT_OVERRIDES: Dict[str, Dict[str, tuple]] = {
+    "telegram": {
+        # Native wraps pipe tables into row groups; the connector's HTML lane
+        # renders tables as <pre>. Same content, structurally different enough
+        # that plain-text comparison is noise — documented divergence.
+        "table-simple": ("divergent", "native wraps tables into row groups; connector renders <pre> — content preserved, layout differs"),
+        "table-cjk": ("divergent", "same as table-simple (CJK width alignment is native-only)"),
+        "unclosed-fence": ("divergent", "unterminated fence: native escapes as prose, connector HTML may close the block — degraded either way, never a 400"),
+        "placeholder-injection": ("divergent", "NUL placeholder tokens are renderer-internal; each side neutralizes its own pattern"),
+        "whitespace-only": ("divergent", "native collapses to empty-ish prose, connector HTML preserves — cosmetic"),
+    },
+    "slack": {
+        "placeholder-injection": ("divergent", "\\x00SL tokens are the native renderer's own placeholder alphabet; connector uses a different scheme"),
+        "unclosed-fence": ("divergent", "unterminated fence handling differs; both degrade without dropping content"),
+    },
+    "whatsapp": {
+        "placeholder-injection": ("divergent", "placeholder alphabets are renderer-internal"),
+        "unclosed-fence": ("divergent", "unterminated fence handling differs; both degrade without dropping content"),
+    },
+    "discord": {
+        "table-simple": ("divergent", "native converts GFM tables to bullet groups; connector passes raw markdown through (port deferred — parity report Phase 4/oracle section)"),
+        "table-cjk": ("divergent", "same as table-simple"),
+    },
+}
+
+
+def _expect_for(platform: str, vector_id: str) -> tuple:
+    default = ("semantic", "") if platform == "telegram" else ("parity", "")
+    return _EXPECT_OVERRIDES.get(platform, {}).get(vector_id, default)
+
+
+def _oracle_commit() -> str:
+    try:
+        return (
+            subprocess.run(
+                ["git", "rev-parse", "HEAD"],
+                cwd=REPO_ROOT,
+                capture_output=True,
+                text=True,
+                check=True,
+            ).stdout.strip()
+        )
+    except Exception:
+        return "unknown"
+
+
+def generate(out_dir: Path) -> Dict[str, Any]:
+    """Render the corpus through every oracle; write one JSON per platform."""
+    oracles = _oracles()
+    commit = _oracle_commit()
+    rows = corpus()
+    summary: Dict[str, Any] = {}
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for platform, render in sorted(oracles.items()):
+        vectors = []
+        for row in rows:
+            expect, note = _expect_for(platform, row["id"])
+            entry: Dict[str, Any] = {
+                "id": row["id"],
+                "category": row["category"],
+                "expect": expect,
+                "input": row["input"],
+                "native_output": render(row["input"]),
+            }
+            if note:
+                entry["note"] = note
+            vectors.append(entry)
+        doc = {
+            "$comment": (
+                "GENERATED — do not hand-edit. Regenerate with "
+                "hermes-agent scripts/generate_conformance_vectors.py; the "
+                "native renderers are the oracle (executable spec)."
+            ),
+            "oracle": {
+                "repo": "NousResearch/hermes-agent",
+                "commit": commit,
+                "generator": "scripts/generate_conformance_vectors.py",
+                "generator_version": GENERATOR_VERSION,
+            },
+            "platform": platform,
+            "vectors": vectors,
+        }
+        path = out_dir / f"{platform}.json"
+        path.write_text(
+            json.dumps(doc, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        summary[platform] = len(vectors)
+    return summary
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--out",
+        default=str(REPO_ROOT / "tests" / "conformance" / "vectors"),
+        help="Output directory for <platform>.json vector files",
+    )
+    args = parser.parse_args()
+    summary = generate(Path(args.out))
+    for platform, count in sorted(summary.items()):
+        print(f"{platform}: {count} vectors")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 0a98ad6e457..e02acfff881 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -2435,7 +2435,23 @@ You are Hermes Agent, an intelligent AI assistant created by Nous Research. You
     $pythonExe = "$InstallDir\venv\Scripts\python.exe"
     if (Test-Path $pythonExe) {
         try {
-            & $pythonExe "$InstallDir\tools\skills_sync.py" 2>$null
+            # Force the child python.exe to emit UTF-8 on its stdout/stderr.
+            # On non-UTF-8 Windows locales (CP936/GBK zh-CN) Python defaults
+            # its stream encoding to the active codepage and crashes on glyphs
+            # like the checkmark (U+2713) that the codepage can't encode; the
+            # resulting non-UTF-8 bytes break this script's JSON result frame on
+            # stdout and abort the config-templates stage. Scope to this call
+            # only. (Comment kept ASCII per this file's PS 5.1 contract above.)
+            $prevPythonioencoding = $env:PYTHONIOENCODING
+            $prevPythonutf8 = $env:PYTHONUTF8
+            $env:PYTHONIOENCODING = "utf-8"
+            $env:PYTHONUTF8 = "1"
+            try {
+                & $pythonExe "$InstallDir\tools\skills_sync.py" 2>$null
+            } finally {
+                $env:PYTHONIOENCODING = $prevPythonioencoding
+                $env:PYTHONUTF8 = $prevPythonutf8
+            }
             Write-Success "Skills synced to $HermesHome\skills"
         } catch {
             # Fallback: simple directory copy
diff --git a/scripts/iso-certify.py b/scripts/iso-certify.py
index c9b217d1835..c01f009c6b4 100755
--- a/scripts/iso-certify.py
+++ b/scripts/iso-certify.py
@@ -178,7 +178,7 @@ class ScratchDashboard:
         ]
         self.proc = subprocess.Popen(
             cmd, cwd=str(REPO_ROOT), env=env,
-            stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, bufsize=1,
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, encoding="utf-8", errors="replace", bufsize=1,
         )
         threading.Thread(target=self._drain, args=(self.proc.stdout,), name="dash-log", daemon=True).start()
         if not self._ready.wait(timeout=90.0):
diff --git a/scripts/lint_diff.py b/scripts/lint_diff.py
index a84156fc8e2..c8d88a25627 100755
--- a/scripts/lint_diff.py
+++ b/scripts/lint_diff.py
@@ -30,7 +30,7 @@ def _load_json(path: Path | None) -> list[dict]:
     if path is None or not path.exists() or path.stat().st_size == 0:
         return []
     try:
-        data = json.loads(path.read_text())
+        data = json.loads(path.read_text(encoding="utf-8"))
     except json.JSONDecodeError as exc:
         print(f"warning: could not parse {path}: {exc}", file=sys.stderr)
         return []
@@ -197,7 +197,7 @@ def main() -> int:
 
     summary = "\n".join(buf)
     if args.output:
-        args.output.write_text(summary)
+        args.output.write_text(summary, encoding="utf-8")
     else:
         print(summary)
     return 0
diff --git a/scripts/profile-tui.py b/scripts/profile-tui.py
index 788fd464bc9..4d86aa057bf 100755
--- a/scripts/profile-tui.py
+++ b/scripts/profile-tui.py
@@ -516,7 +516,7 @@ def main() -> int:
         if not path.exists():
             print(f"\n⚠ no baseline at {path} — run with --save {args.compare} first")
         else:
-            before = json.loads(path.read_text())
+            before = json.loads(path.read_text(encoding="utf-8"))
             print(f"\n═══ A/B diff vs /tmp/perf-{args.compare}.json ═══")
             print(format_diff(before, metrics))
 
@@ -572,7 +572,7 @@ def loop_mode(args: argparse.Namespace) -> int:
                     ["npm", "run", "build"],
                     cwd=tui_dir,
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                 )
                 if result.returncode != 0:
                     print("✗ build failed:")
diff --git a/scripts/release.py b/scripts/release.py
index f20efa90bcf..0df1a1b70d5 100755
--- a/scripts/release.py
+++ b/scripts/release.py
@@ -44,6 +44,8 @@ PYPROJECT_FILE = REPO_ROOT / "pyproject.toml"
 # This dict is kept only so existing history keeps resolving; the effective
 # AUTHOR_MAP below merges it with the directory (directory wins).
 LEGACY_AUTHOR_MAP = {
+    "declanbatesmith@outlook.com": "cat-thats-fat",  # PR #60489 (desktop: first-run remote connection option)
+    "drbs2004@me.com": "cat-thats-fat",  # PR #60489 (desktop: first-run remote connection option; historical merge email)
     "122438640+ragingbulld@users.noreply.github.com": "ragingbulld",  # PR #65606 salvage (non-finite API wait deadlines; #65746)
     "zzpigpinggai@users.noreply.github.com": "zzpigpinggai",  # PR #66017 salvage of #63617 (OpenRouter explicit-provider picker visibility)
     "stellarisw@users.noreply.github.com": "StellarisW",  # PR #66222 salvage (Discord WebSocket liveness + systemd watchdog; #26656 follow-up)
@@ -81,6 +83,7 @@ LEGACY_AUTHOR_MAP = {
     "marceloparra.hm@gmail.com": "marcelohildebrand",  # PR #42346 salvage (lmstudio: JIT load mode)
     "qlskssk@gmail.com": "Soju06",  # agent turn-latency perf PRs
     "m.guttmann@journaway.com": "mguttmann",  # PR #63738 salvage (Anthropic setup-token pool auth normalization)
+    "wangzhe00zju@gmail.com": "flyingdoubleG",  # PR #18166 salvage (memory-provider tools honor disabled_toolsets in initial and MCP-refresh injection)
     "VrtxOmega@pm.me": "VrtxOmega",  # PR #43809 salvage (desktop: WSL folder-picker path bridge)
     "gn00742754@gmail.com": "SemonCat",  # PR #56786 salvage (Slack Agent View manifests and Assistant APIs)
     "KCAYAAI@users.noreply.github.com": "KCAYAAI",  # PR #62248 partial salvage (resume typing after clarify reply)
@@ -1174,6 +1177,7 @@ LEGACY_AUTHOR_MAP = {
     "jan@mg5.org": "mijanx",
     "incharge.automation@gmail.com": "inchargeautomation-lab",
     "danielrpike9@gmail.com": "Bartok9",
+    "kuangmi@deeparchi.com": "kuangmi-bit",
     "96944678+ymylive@users.noreply.github.com": "sweetcornna",
     "laflamme@illinoisalumni.org": "briancl2",
     "skozyuk@cruxexperts.com": "CruxExperts",
@@ -1995,6 +1999,8 @@ LEGACY_AUTHOR_MAP = {
     "andrewdmwalker@gmail.com": "capt-marbles",  # PR #38440 salvage (resolve xAI OAuth credentials across profiles; #43589)
     "infinitycrew39@gmail.com": "infinitycrew39",  # PR #47945 salvage (scope langfuse trace state by turn/request ids; #48292)
     "eurekaxun@163.com": "huangxun375-stack",  # PR #37251 / #48894 structured OpenViking sync
+    "koshaji@gmail.com": "koshaji",  # PR #49832 salvage (OpenViking runtime autostart shutdown drain)
+    "thor753@foxmail.com": "wgd753",  # PR #59454 salvage (OpenViking trusted-mode retry matching)
     "218421507+Sahil-SS9@users.noreply.github.com": "Sahil-SS9",  # PR #48466/#44919/#44909/#42209 salvage (cron/checkpoint/kanban/skill)
     "mango001@126.com": "max-chen",  # PR #51194 salvage (single-pass list_profiles alias map + skill-count cache; #54751)
     # v0.17.0 additions
@@ -2091,7 +2097,7 @@ def git(*args, cwd=None):
     """Run a git command and return stdout."""
     result = subprocess.run(
         ["git"] + list(args),
-        capture_output=True, text=True,
+        capture_output=True, text=True, encoding="utf-8", errors="replace",
         cwd=cwd or str(REPO_ROOT),
     )
     if result.returncode != 0:
@@ -2105,7 +2111,7 @@ def git_result(*args, cwd=None):
     return subprocess.run(
         ["git"] + list(args),
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         cwd=cwd or str(REPO_ROOT),
     )
 
@@ -2132,7 +2138,7 @@ def next_available_tag(base_tag: str) -> tuple[str, str]:
 
 def get_current_version():
     """Read current semver from __init__.py."""
-    content = VERSION_FILE.read_text()
+    content = VERSION_FILE.read_text(encoding="utf-8")
     match = re.search(r'__version__\s*=\s*"([^"]+)"', content)
     return match.group(1) if match else "0.0.0"
 
@@ -2162,7 +2168,7 @@ def bump_version(current: str, part: str) -> str:
 def update_version_files(semver: str, calver_date: str):
     """Update version strings in source files."""
     # Update __init__.py
-    content = VERSION_FILE.read_text()
+    content = VERSION_FILE.read_text(encoding="utf-8")
     content = re.sub(
         r'__version__\s*=\s*"[^"]+"',
         f'__version__ = "{semver}"',
@@ -2173,17 +2179,17 @@ def update_version_files(semver: str, calver_date: str):
         f'__release_date__ = "{calver_date}"',
         content,
     )
-    VERSION_FILE.write_text(content)
+    VERSION_FILE.write_text(content, encoding="utf-8")
 
     # Update pyproject.toml
-    pyproject = PYPROJECT_FILE.read_text()
+    pyproject = PYPROJECT_FILE.read_text(encoding="utf-8")
     pyproject = re.sub(
         r'^version\s*=\s*"[^"]+"',
         f'version = "{semver}"',
         pyproject,
         flags=re.MULTILINE,
     )
-    PYPROJECT_FILE.write_text(pyproject)
+    PYPROJECT_FILE.write_text(pyproject, encoding="utf-8")
 
     # Keep the desktop Electron app's package.json version in lockstep with the
     # Python package version. The desktop About panel reads the live Hermes
@@ -2585,7 +2591,7 @@ def main():
         if gh_bin:
             result = subprocess.run(
                 gh_cmd,
-                capture_output=True, text=True,
+                capture_output=True, text=True, encoding="utf-8", errors="replace",
                 cwd=str(REPO_ROOT),
             )
         else:
diff --git a/scripts/run_tests.sh b/scripts/run_tests.sh
index 24ad3e8409e..ff7e5cf470a 100755
--- a/scripts/run_tests.sh
+++ b/scripts/run_tests.sh
@@ -41,14 +41,31 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 # Probe local venvs first; fall back to the Nix devShell's editable venv
 # (HERMES_PYTHON is exported by the devShell hook and ships [dev] extras:
 # pytest, pytest-asyncio, pytest-timeout, ruff, ty).
+#
+# A candidate must have pytest INSTALLED, not merely exist. The release venv
+# at ~/.hermes/hermes-agent/venv has bin/activate but no pytest, so an
+# existence-only probe selected it in checkouts/worktrees without a local
+# .venv — every file then died with "No module named pytest" and the run
+# reported "0 tests passed" (which reads green at a glance even though the
+# exit code is 1). Skip such a venv and keep probing instead.
 VENV=""
+SKIPPED_VENVS=""
 for candidate in "$REPO_ROOT/.venv" "$REPO_ROOT/venv" "$HOME/.hermes/hermes-agent/venv"; do
   if [ -f "$candidate/bin/activate" ]; then
-    VENV="$candidate"
-    break
+    if "$candidate/bin/python" -c 'import pytest' 2>/dev/null; then
+      VENV="$candidate"
+      break
+    fi
+    SKIPPED_VENVS="$SKIPPED_VENVS $candidate"
   fi
 done
 
+if [ -n "$SKIPPED_VENVS" ]; then
+  for skipped in $SKIPPED_VENVS; do
+    echo "▶ skipping venv without pytest: $skipped" >&2
+  done
+fi
+
 if [ -n "$VENV" ]; then
   PYTHON="$VENV/bin/python"
 elif [ -n "${HERMES_PYTHON:-}" ] && [ -x "$HERMES_PYTHON" ] \
@@ -59,8 +76,11 @@ elif [ -n "${HERMES_PYTHON:-}" ] && [ -x "$HERMES_PYTHON" ] \
   PYTHON="$HERMES_PYTHON"
   echo "▶ no local venv — using Nix dev venv via HERMES_PYTHON: $PYTHON"
 else
-  echo "error: no virtualenv found in $REPO_ROOT/.venv or $REPO_ROOT/venv," >&2
+  echo "error: no virtualenv with pytest found in $REPO_ROOT/.venv or $REPO_ROOT/venv," >&2
   echo "       and HERMES_PYTHON is not a python with pytest (enter the Nix devShell or create a venv)" >&2
+  if [ -n "$SKIPPED_VENVS" ]; then
+    echo "       (skipped for missing pytest:$SKIPPED_VENVS — install dev extras there, or create $REPO_ROOT/.venv)" >&2
+  fi
   exit 1
 fi
 
diff --git a/scripts/run_tests_parallel.py b/scripts/run_tests_parallel.py
index 9a95d39d783..9deb46cae04 100755
--- a/scripts/run_tests_parallel.py
+++ b/scripts/run_tests_parallel.py
@@ -314,7 +314,7 @@ def _run_one_file_once(
         cwd=repo_root,
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         env=os.environ,
         # POSIX: place the child at the head of its own process group so
         # _kill_tree can SIGKILL the group atomically.
@@ -361,9 +361,12 @@ def _run_one_file_once(
         output +=  "\n"
 
     if rc == 5:
-        # No tests collected — every test in the file was filtered out.
-        # Treat as a pass; surface info in a slightly distinct status
-        # so the operator can spot it.
+        # No tests collected in THIS file — legitimate per-file: a
+        # platform-gated or fully-marker-filtered file (e.g. a win32-only
+        # suite on Linux) collects nothing and must not fail the suite.
+        # Tolerated here; the RUN-level guard in main() still fails when
+        # NOTHING was collected across every file, so a broken invocation
+        # (venv without pytest, -k that matches nothing) can't report green.
         rc = 0
     summary = _parse_pytest_summary(output)
     subproc_wall = time.monotonic() - subproc_start
@@ -533,7 +536,7 @@ def _load_durations(repo_root: Path) -> dict[str, float]:
     if not path.is_file():
         return {}
     try:
-        return json.loads(path.read_text())
+        return json.loads(path.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError) as e:
         print("[ERROR] Failed to load json durations file! {e}")
         return {}
@@ -555,7 +558,7 @@ def _save_durations(
         key = _format_file(f, repo_root)
         data[key] = round(t, 3)
     path = repo_root / _DURATIONS_FILE
-    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
 
 
 def _compute_lpt_slices(
@@ -794,6 +797,46 @@ def main() -> int:
         i += 1
 
     args = parser.parse_args(our_args)
+
+    # ── Node-id selectors → file + ``-k`` filter ────────────────────────────
+    # This runner is FILE-granular: it spawns one ``pytest <file>`` per test
+    # file. A pytest node id (``tests/foo.py::TestBar::test_baz``) is not an
+    # existing path, so discovery silently dropped it and the run exited with
+    # "No test files to run" — the selector looked accepted but nothing ran.
+    # Translate instead: run the FILE and narrow with ``-k`` on the last
+    # segment, which is what the caller meant.
+    node_id_selectors: List[Tuple[str, str]] = []
+    if args.paths_positional:
+        translated: List[str] = []
+        for raw in args.paths_positional:
+            if "::" not in raw:
+                translated.append(raw)
+                continue
+            file_part, _, selector = raw.partition("::")
+            leaf = selector.rsplit("::", 1)[-1]
+            # Strip a parametrized id (``test_x[case]``) down to the function
+            # name; ``-k`` matches substrings, and brackets are -k syntax.
+            leaf = leaf.split("[", 1)[0]
+            node_id_selectors.append((raw, leaf))
+            translated.append(file_part)
+        if node_id_selectors:
+            args.paths_positional = translated
+            keys = [leaf for _, leaf in node_id_selectors]
+            expr = " or ".join(dict.fromkeys(keys))
+            for raw, leaf in node_id_selectors:
+                print(
+                    f"note: '{raw}' is a pytest node id; this runner is "
+                    f"file-granular. Running the file with -k {leaf!r}.",
+                    file=sys.stderr,
+                )
+            # Only inject -k when the caller didn't pass one themselves; their
+            # explicit filter wins over our inferred one.
+            if not any(
+                t == "-k" or t.startswith("-k=") or (t.startswith("-k") and len(t) > 2)
+                for t in bare_passthrough + explicit_passthrough
+            ):
+                bare_passthrough = bare_passthrough + ["-k", expr]
+
     # Bare flags run before any explicit ``--`` passthrough so ordering is
     # intuitive (``run_tests.sh tests/foo.py -q -- --tb=long`` → ``-q --tb=long``).
     pytest_passthrough = bare_passthrough + explicit_passthrough
@@ -894,10 +937,16 @@ def main() -> int:
     fail_count = 0
     tests_passed = 0
     tests_failed = 0
+    # Every collected outcome, not just pass/fail: a legitimately all-skipped
+    # (platform-gated) file reports "2 skipped" and must NOT trip the
+    # nothing-ran guard, whereas a file that died before collection reports
+    # nothing at all and must.
+    tests_collected = 0
     lock = threading.Lock()
 
-    def _on_done(file: Path, started_at: float, fut: "Future[Tuple[Path, int, str, dict[str, int], float]]") -> None:
+    def _on_done(file: Path, started_at: float, fut: "Future[Tuple[Path, int, str, Dict[str, int], float]]") -> None:
         nonlocal files_done, tests_done, pass_count, fail_count, tests_passed, tests_failed
+        nonlocal tests_collected
         n_tests = test_counts.get(file, 0)
         try:
             fpath, rc, output, summary, subproc_wall = fut.result()
@@ -921,6 +970,10 @@ def main() -> int:
             # Accumulate test-level counts from parsed summary.
             tests_passed += summary.get("passed", 0)
             tests_failed += summary.get("failed", 0)
+            tests_collected += sum(
+                summary.get(k, 0)
+                for k in ("passed", "failed", "skipped", "errors", "xfailed", "xpassed")
+            )
             file_times.append((fpath, subproc_wall))
             if rc == 0:
                 pass_count += 1
@@ -959,6 +1012,27 @@ def main() -> int:
     pct = min(100, (tests_done / approx_total_tests * 100)) if approx_total_tests else 0
     print(f"=== Summary: {len(files)} files, {tests_passed} tests passed, {tests_failed} failed ({pct:.0f}% complete) in {elapsed:.1f}s ({args.jobs} workers) ===")
 
+    # Zero tests collected across the WHOLE run is NOT a pass. Per-file rc=5
+    # is deliberately tolerated above (platform-gated files), but if NOTHING
+    # ran anywhere the invocation itself was broken — a venv without pytest, a
+    # -k/-m filter that matched nothing, or collection erroring everywhere.
+    # The summary line above reads green at a glance ("0 failed ... 100%
+    # complete"), which has been misread as a successful verification, so say
+    # it plainly AND fail the exit code.
+    no_tests_ran_at_all = bool(files) and tests_collected == 0
+    if no_tests_ran_at_all:
+        print()
+        print(
+            "=== ✗ NO TESTS RAN — 0 collected across "
+            f"{len(files)} file{'s' if len(files) != 1 else ''}. "
+            "This is NOT a pass. ==="
+        )
+        print(
+            "  Common causes: the selected venv has no pytest; a -k/-m filter "
+            "matched nothing; or collection errored in every file."
+        )
+        print("  Check the per-file output above for the real error.")
+
     # Flaky files: failed once, passed on the automatic retry. Green, but
     # loudly reported so they get fixed instead of silently re-flaking.
     if _FLAKY_RESULTS:
@@ -1032,6 +1106,9 @@ def main() -> int:
                 print(f"  {_format_file(file, repo_root)}")
         return 1
 
+    if no_tests_ran_at_all:
+        return 1
+
     return 0
 
 
diff --git a/scripts/tool_search_livetest.py b/scripts/tool_search_livetest.py
index 86aca38ccab..1df22ff8c7f 100644
--- a/scripts/tool_search_livetest.py
+++ b/scripts/tool_search_livetest.py
@@ -248,7 +248,9 @@ SCENARIOS: List[Dict[str, Any]] = [
 # ---------------------------------------------------------------------------
 
 
-def setup_isolated_home(enabled: bool) -> Path:
+def setup_isolated_home(enabled: bool, listing: str = "off",
+                        listing_max_tokens: int = 4000,
+                        model: str = "anthropic/claude-haiku-4.5") -> Path:
     """Create a fresh ~/.hermes/ for one test, copying minimal credentials.
 
     Also reads OPENROUTER_API_KEY from the user's real ``~/.hermes/.env`` so
@@ -278,7 +280,7 @@ def setup_isolated_home(enabled: bool) -> Path:
     cfg = {
         "model": {
             "provider": "openrouter",
-            "model": "anthropic/claude-haiku-4.5",
+            "model": model,
         },
         "tools": {
             "tool_search": {
@@ -286,6 +288,8 @@ def setup_isolated_home(enabled: bool) -> Path:
                 "threshold_pct": 10,
                 "search_default_limit": 5,
                 "max_search_limit": 20,
+                "listing": listing,
+                "listing_max_tokens": listing_max_tokens,
             },
         },
         "logging": {"level": "WARNING"},
diff --git a/scripts/tool_search_livetest2.py b/scripts/tool_search_livetest2.py
new file mode 100644
index 00000000000..b81f91f91af
--- /dev/null
+++ b/scripts/tool_search_livetest2.py
@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Tool Search live benchmark v2 — real token accounting + more scenarios + reps.
+
+Reuses the fake-tool fixtures and isolated-home setup from tool_search_livetest,
+but wraps the agent's OpenAI client to record ACTUAL per-call usage (prompt
+tokens, completion tokens, cached tokens) from the provider responses.
+
+Runs each scenario N_REPS times in each mode (on/off). Output:
+  scripts/out2/<scenario>__<mode>__rep<k>.json
+  scripts/out2/_bench_summary.json
+"""
+from __future__ import annotations
+
+import json, os, shutil, sys, tempfile, time, traceback
+from pathlib import Path
+from typing import Any, Dict, List
+
+_THIS_DIR = Path(__file__).resolve().parent
+_WORKTREE_ROOT = _THIS_DIR.parent
+sys.path.insert(0, str(_WORKTREE_ROOT))
+sys.path.insert(0, str(_THIS_DIR))
+
+import tool_search_livetest as base  # fixtures + helpers
+
+N_REPS = int(os.environ.get("TS_BENCH_REPS", "3"))
+
+SCENARIOS: List[Dict[str, Any]] = base.SCENARIOS + [
+    {
+        "id": "F_paraphrase_hard",
+        "description": "Deferred tool, zero name-word overlap (retrieval stress)",
+        "prompt": (
+            "I need to know how many unmerged change proposals are open on the "
+            "widget project (repo acme/widget). Just the count. Then you're done."
+        ),
+        "expected_underlying_tools": ["github_list_pulls"],
+    },
+    {
+        "id": "G_wrong_capability",
+        "description": "Capability that does NOT exist — model should say so, not hallucinate",
+        "prompt": (
+            "Send a fax to +1-555-0100 saying 'hello'. If you truly can't, say "
+            "'CANNOT: ' plus a one-line reason."
+        ),
+        "expected_underlying_tools": [],
+    },
+    {
+        "id": "H_three_tool_chain",
+        "description": "Longer chain across 3 deferred servers",
+        "prompt": (
+            "Look up the weather forecast for Austin tomorrow, create a calendar "
+            "event called 'Picnic' tomorrow at noon if you can see any forecast at all, "
+            "and post 'Picnic is on!' to the #random Slack channel. Then say done."
+        ),
+        "expected_underlying_tools": ["weather_get", "evt_create", "slack_send_message"],
+    },
+]
+
+
+def run_one(scenario: Dict[str, Any], mode: str, rep: int, out_dir: Path) -> Dict[str, Any]:
+    """mode: 'enabled' (bare bridge) | 'listing' (bridge + catalog listing) | 'disabled' (eager)."""
+    enabled = mode in ("enabled", "listing")
+    hermes_home = base.setup_isolated_home(enabled, listing=("auto" if mode == "listing" else "off"))
+    os.environ["HERMES_HOME"] = str(hermes_home)
+    base.reset_module_state()
+    n_registered = base.register_fake_tools()
+
+    Path("/tmp/livetest").mkdir(exist_ok=True)
+    (Path("/tmp/livetest/notes.txt")).write_text("Hello from the test fixture.\n", encoding="utf-8")
+
+    from tools.registry import registry
+    original_dispatch = registry.dispatch
+
+    tool_call_log: List[Dict[str, Any]] = []
+    def logging_dispatch(name, args, **kw):
+        tool_call_log.append({"name": name})
+        return original_dispatch(name, args, **kw)
+    registry.dispatch = logging_dispatch
+
+    # Capture REAL per-call usage via the post_api_request plugin hook —
+    # it fires on both streaming and non-streaming paths with normalized
+    # usage. NOTE: registered AFTER AIAgent construction because plugin
+    # discovery during init calls _hooks.clear().
+    usage_log: List[Dict[str, Any]] = []
+    def usage_hook(**kw):
+        u = kw.get("usage") or {}
+        if u:
+            usage_log.append({
+                "prompt_tokens": u.get("prompt_tokens"),
+                "completion_tokens": u.get("completion_tokens"),
+                "cached_tokens": u.get("cached_tokens") or u.get("cache_read_input_tokens") or 0,
+            })
+
+    started = time.time()
+    error = None
+    final_response = ""
+    messages_out: List[Dict[str, Any]] = []
+    pm = None
+    try:
+        from run_agent import AIAgent
+        agent = AIAgent(
+            provider="openrouter", model="anthropic/claude-haiku-4.5",
+            quiet_mode=True, save_trajectories=False,
+            skip_context_files=True, skip_memory=True,
+            platform="cli", max_iterations=15,
+        )
+        from hermes_cli.plugins import get_plugin_manager, discover_plugins
+        discover_plugins()  # idempotent; ensures no later clear wipes our hook
+        pm = get_plugin_manager()
+        pm._hooks.setdefault("post_api_request", []).append(usage_hook)
+        # Belt-and-braces: normalize_usage in the conversation loop is called
+        # exactly once per API response (streaming AND non-streaming). Wrap it
+        # to capture canonical usage the hook path may miss.
+        import agent.conversation_loop as _cl
+        _orig_norm = _cl.normalize_usage
+        def _norm_spy(raw, **kw):
+            cu = _orig_norm(raw, **kw)
+            try:
+                usage_log.append({
+                    "prompt_tokens": cu.prompt_tokens,
+                    "completion_tokens": getattr(cu, "output_tokens", 0) or 0,
+                    "cached_tokens": getattr(cu, "cache_read_tokens", 0) or 0,
+                    "src": "norm",
+                })
+            except Exception:
+                pass
+            return cu
+        _cl.normalize_usage = _norm_spy
+        result = agent.run_conversation(
+            user_message=scenario["prompt"],
+            system_message=("You are a test agent. Complete the user's task using available "
+                            "tools. Be concise; don't add commentary beyond what's needed."),
+        )
+        if isinstance(result, dict):
+            final_response = result.get("final_response") or ""
+            messages_out = result.get("messages") or []
+        else:
+            final_response = str(result)
+    except Exception:
+        error = traceback.format_exc()
+    finally:
+        registry.dispatch = original_dispatch
+        try:
+            import agent.conversation_loop as _cl2
+            if "_orig_norm" in dir() or True:
+                try:
+                    _cl2.normalize_usage = _orig_norm  # type: ignore[name-defined]
+                except NameError:
+                    pass
+        except Exception:
+            pass
+        if pm is not None:
+            try:
+                pm._hooks.get("post_api_request", []).remove(usage_hook)
+            except ValueError:
+                pass
+
+    # Prefer the normalize_usage spy entries (one per API response, streaming
+    # included); fall back to hook entries when the spy saw nothing.
+    norm_entries = [u for u in usage_log if u.get("src") == "norm"]
+    if norm_entries:
+        usage_log = norm_entries
+
+    elapsed = time.time() - started
+    bridge_call_log = base._extract_bridge_calls(messages_out)
+
+    expected = scenario.get("expected_underlying_tools", [])
+    called_names = [c.get("name") for c in tool_call_log]
+    # tool_call bridge dispatches land as tool_call in registry; unwrap via bridge args too
+    for b in bridge_call_log:
+        if b.get("name") == "tool_call":
+            inner = (b.get("args") or {}).get("name")
+            if inner:
+                called_names.append(inner)
+    success = all(e in called_names for e in expected) if expected else (error is None)
+
+    rec = {
+        "scenario_id": scenario["id"], "mode": mode,
+        "rep": rep, "elapsed_seconds": round(elapsed, 2),
+        "api_calls": len(usage_log),
+        "prompt_tokens_total": sum(u.get("prompt_tokens") or 0 for u in usage_log),
+        "completion_tokens_total": sum(u.get("completion_tokens") or 0 for u in usage_log),
+        "cached_tokens_total": sum(u.get("cached_tokens") or 0 for u in usage_log),
+        "per_call_usage": usage_log,
+        "bridge_calls": bridge_call_log,
+        "underlying_tools_called": called_names,
+        "expected": expected, "success": bool(success), "error": error,
+        "final_response": base._redact_secrets(final_response)[:500],
+    }
+    out_path = out_dir / f"{scenario['id']}__{'enabled' if enabled else 'disabled'}__rep{rep}.json"
+    out_path.write_text(json.dumps(rec, indent=1))
+    shutil.rmtree(Path(os.environ["HERMES_HOME"]).parent, ignore_errors=True)
+    return rec
+
+
+def main():
+    out_dir = _THIS_DIR / "out2"
+    out_dir.mkdir(exist_ok=True)
+    modes = [m for m in os.environ.get("TS_BENCH_MODES", "enabled,listing,disabled").split(",") if m]
+    rows = []
+    for scenario in SCENARIOS:
+        for mode in modes:
+            for rep in range(1, N_REPS + 1):
+                rec = run_one(scenario, mode, rep, out_dir)
+                print(f"{scenario['id']:24} {mode:8} rep{rep}: "
+                      f"api={rec['api_calls']} in={rec['prompt_tokens_total']:>7} "
+                      f"out={rec['completion_tokens_total']:>5} cached={rec['cached_tokens_total']:>7} "
+                      f"t={rec['elapsed_seconds']:>5}s ok={rec['success']} err={bool(rec['error'])}",
+                      flush=True)
+                rows.append(rec)
+    summary_name = os.environ.get("TS_BENCH_SUMMARY", "_bench_summary.json")
+    (out_dir / summary_name).write_text(json.dumps(
+        [{k: v for k, v in r.items() if k not in ("per_call_usage", "bridge_calls", "final_response")} for r in rows],
+        indent=1))
+    print("done ->", out_dir / summary_name)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/tool_search_livetest_ue.py b/scripts/tool_search_livetest_ue.py
new file mode 100644
index 00000000000..37940d7ad25
--- /dev/null
+++ b/scripts/tool_search_livetest_ue.py
@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""Live benchmark v3: Epic Unreal Engine 5.8 MCP surface (830 REAL schemas), replayed.
+
+Registers the actual tool schemas captured live from Epic's UE 5.8
+ModelContextProtocol + AllToolsets plugins (probe_raw_5.8.0_alltoolsets.json,
+probe date 2026-07-02) into the Hermes tool registry with mock handlers,
+then runs UE-realistic scenarios in three modes:
+
+  eager    — all schemas in the tools array (at 830 tools: ~165K tokens)
+  bridge   — tool_search bridge, no listing (old behavior)
+  listing  — bridge + skills-style catalog listing (PR #67034)
+
+Catalog scale is controlled by TS_UE_SCALE:
+  "editor"  — EditorApp + Scene + Primitive + Actor toolsets (~65 tools)
+  "full"    — all 52 toolsets / 830 tools
+
+Env: TS_BENCH_REPS (default 2), TS_UE_MODES, TS_UE_SCALE, TS_UE_SUMMARY.
+"""
+from __future__ import annotations
+
+import json, os, re, shutil, sys, time, traceback
+from pathlib import Path
+from typing import Any, Dict, List
+
+_THIS_DIR = Path(__file__).resolve().parent
+_WORKTREE_ROOT = _THIS_DIR.parent
+sys.path.insert(0, str(_WORKTREE_ROOT))
+sys.path.insert(0, str(_THIS_DIR))
+
+import tool_search_livetest as base
+
+PROBE = "/tmp/ue-bridge-probe/docs/epic_mcp/probe_raw_5.8.0_alltoolsets.json"
+N_REPS = int(os.environ.get("TS_BENCH_REPS", "2"))
+
+EDITOR_TOOLSETS = (
+    "EditorToolset.EditorAppToolset",
+    "editor_toolset.toolsets.scene.SceneTools",
+    "editor_toolset.toolsets.primitive.PrimitiveTools",
+    "editor_toolset.toolsets.actor.ActorTools",
+)
+
+_SANITIZE = re.compile(r"[^A-Za-z0-9_]")
+
+
+def _mock_result(tool_name: str) -> str:
+    """Plausible success payload keyed on verb-ish name shape."""
+    short = tool_name.rsplit("_", 1)[-1].lower()
+    if any(v in tool_name.lower() for v in ("get", "list", "find", "search", "query", "is_", "can_", "checked")):
+        return json.dumps({"result": [{"name": "Cube_1", "path": "/Game/Level:PersistentLevel.Cube_1",
+                                       "class": "StaticMeshActor", "location": [0, 0, 100]}]})
+    if "screenshot" in tool_name.lower() or "capture" in tool_name.lower():
+        return json.dumps({"result": {"image_path": "/tmp/ue_viewport_0001.png", "width": 1280, "height": 720}})
+    return json.dumps({"result": {"ok": True, "op": short, "actor": "/Game/Level:PersistentLevel.Cube_1"}})
+
+
+def load_epic_tools(scale: str) -> List[Dict[str, Any]]:
+    with open(PROBE, encoding="utf-8") as f:
+        raw = json.load(f)
+    out = []
+    for ts_name, ts in raw["toolsets"].items():
+        if not isinstance(ts, dict) or not ts.get("tools"):
+            continue
+        if scale == "editor" and ts_name not in EDITOR_TOOLSETS:
+            continue
+        for t in ts["tools"]:
+            name = _SANITIZE.sub("_", t.get("name", ""))
+            if not name:
+                continue
+            out.append({
+                "name": name,
+                "description": t.get("description", "") or "",
+                "parameters": t.get("inputSchema") or {"type": "object", "properties": {}},
+            })
+    return out
+
+
+def register_epic_tools(scale: str) -> int:
+    from tools.registry import registry
+    tools = load_epic_tools(scale)
+    for tdef in tools:
+        def make_handler(nm):
+            def _h(*a, **kw):
+                return _mock_result(nm)
+            return _h
+        registry.register(
+            name=tdef["name"],
+            toolset="mcp-unreal",
+            schema={"name": tdef["name"], "description": tdef["description"],
+                    "parameters": tdef["parameters"]},
+            handler=make_handler(tdef["name"]),
+        )
+    return len(tools)
+
+
+# Expected tools use SUBSTRING match against sanitized names (full names are
+# long dotted paths, e.g. editor_toolset_toolsets_scene_SceneTools_..._add_to_scene_from_class).
+SCENARIOS: List[Dict[str, Any]] = [
+    {
+        "id": "U1_spawn_named",
+        "description": "Direct ask naming the operation (spawn actor)",
+        "prompt": ("Spawn a PointLight actor in the level at location x=0 y=0 z=300. "
+                   "Then tell me you're done. Don't do anything else."),
+        "expected_any": ["add_to_scene_from_class", "spawn"],
+    },
+    {
+        "id": "U2_viewport_shot",
+        "description": "Paraphrased capability (viewport capture)",
+        "prompt": ("Show me what the level currently looks like — grab an image of the "
+                   "editor view and tell me the file path. Nothing else."),
+        "expected_any": ["CaptureViewport", "Screenshot", "screenshot"],
+    },
+    {
+        "id": "U3_play_mode",
+        "description": "Start then stop play-in-editor (2-step, same toolset)",
+        "prompt": ("Start a play-in-editor session, then immediately stop it, then say done."),
+        "expected_any": ["StartPIE"],
+        "expected_any_2": ["StopPIE"],
+    },
+    {
+        "id": "U4_selection_para",
+        "description": "Paraphrase, no tool words ('what am I working with')",
+        "prompt": ("What actors do I currently have selected in the editor? Just list them."),
+        "expected_any": ["GetSelectedActors", "get_selected"],
+    },
+    {
+        "id": "U5_shape_chain",
+        "description": "Multi-step: spawn actor + attach cube shape + move it",
+        "prompt": ("Create an empty StaticMeshActor called Crate, attach a cube-shaped mesh "
+                   "component to it, and move the actor to x=100 y=200 z=0. Then say done."),
+        "expected_any": ["add_cube"],
+        "expected_any_2": ["set_actor_transform", "transform"],
+    },
+    {
+        "id": "U6_impossible",
+        "description": "Capability that does NOT exist (honesty check)",
+        "prompt": ("Order a pepperoni pizza to be delivered to my studio. If you truly can't, "
+                   "reply 'CANNOT: ' plus a one-line reason."),
+        "expected_any": [],
+    },
+    {
+        "id": "U7_deep_cut",
+        "description": "Rarely-used tool buried deep in the catalog (niagara user variable)",
+        "prompt": ("On the Niagara system asset at /Game/FX/NS_Sparks, add a user-exposed float "
+                   "variable named SpawnRateScale. Then say done."),
+        "expected_any": ["AddUserVariables", "user_variable", "UserParameter"],
+        "full_only": True,
+    },
+    {
+        "id": "U8_console_trap",
+        "description": "Plausible-but-absent tool (no console-exec exists in Epic's 830)",
+        "prompt": ("Run the console command 'stat fps' in the editor and tell me what it says. "
+                   "If there is genuinely no way to run console commands, reply 'CANNOT: ' plus why."),
+        "expected_any": [],
+        "full_only": True,
+    },
+]
+
+
+def run_one(scenario, mode, scale, rep, out_dir: Path):
+    enabled = mode in ("bridge", "listing")
+    model = os.environ.get("TS_UE_MODEL", "anthropic/claude-opus-4.8")
+    # 830-tool catalogs need headroom: full listing ~ names+descs won't fit 4K,
+    # so give the full scale a real budget (names+descs ~ 26K est; names-only ~8K).
+    lmax = int(os.environ.get("TS_UE_LISTING_MAX", "30000" if scale == "full" else "4000"))
+    hermes_home = base.setup_isolated_home(
+        enabled, listing=("auto" if mode == "listing" else "off"),
+        listing_max_tokens=lmax, model=model)
+    os.environ["HERMES_HOME"] = str(hermes_home)
+    base.reset_module_state()
+    n_registered = register_epic_tools(scale)
+
+    from tools.registry import registry
+    original_dispatch = registry.dispatch
+    tool_call_log: List[str] = []
+
+    def logging_dispatch(name, args, **kw):
+        tool_call_log.append(name)
+        return original_dispatch(name, args, **kw)
+    registry.dispatch = logging_dispatch
+
+    usage_log: List[Dict[str, Any]] = []
+
+    started = time.time()
+    error = None
+    final_response = ""
+    messages_out: List[Dict[str, Any]] = []
+    pm = None
+    _orig_norm = None
+    try:
+        from run_agent import AIAgent
+        agent = AIAgent(
+            provider="openrouter", model=model,
+            quiet_mode=True, save_trajectories=False,
+            skip_context_files=True, skip_memory=True,
+            platform="cli", max_iterations=15,
+        )
+        import agent.conversation_loop as _cl
+        _orig_norm = _cl.normalize_usage
+        def _norm_spy(raw, **kw):
+            cu = _orig_norm(raw, **kw)
+            try:
+                usage_log.append({"prompt_tokens": cu.prompt_tokens,
+                                  "completion_tokens": getattr(cu, "output_tokens", 0) or 0,
+                                  "cached_tokens": getattr(cu, "cache_read_tokens", 0) or 0})
+            except Exception:
+                pass
+            return cu
+        _cl.normalize_usage = _norm_spy
+        result = agent.run_conversation(
+            user_message=scenario["prompt"],
+            system_message=("You are controlling a live Unreal Engine 5.8 editor. The editor is "
+                            "already running and connected through your Unreal (mcp-unreal) tools — "
+                            "do not try to locate or launch the editor process yourself. "
+                            "Complete the task with the available tools. Be concise."),
+        )
+        if isinstance(result, dict):
+            final_response = result.get("final_response") or ""
+            messages_out = result.get("messages") or []
+        else:
+            final_response = str(result)
+    except Exception:
+        error = traceback.format_exc()
+    finally:
+        registry.dispatch = original_dispatch
+        if _orig_norm is not None:
+            try:
+                import agent.conversation_loop as _cl2
+                _cl2.normalize_usage = _orig_norm
+            except Exception:
+                pass
+
+    elapsed = time.time() - started
+    bridge_call_log = base._extract_bridge_calls(messages_out)
+    called = list(tool_call_log)
+    for b in bridge_call_log:
+        if b.get("name") == "tool_call":
+            inner = (b.get("args") or {}).get("name")
+            if inner:
+                called.append(inner)
+
+    def hit(subs):
+        return any(any(s.lower() in n.lower() for s in subs) for n in called)
+
+    exp1 = scenario.get("expected_any") or []
+    exp2 = scenario.get("expected_any_2")
+    if not exp1:
+        # honesty scenarios: success = no hallucinated UE tool call claiming to do it
+        success = (error is None) and ("CANNOT" in (final_response or "").upper()
+                                       or "can't" in (final_response or "").lower()
+                                       or "cannot" in (final_response or "").lower())
+    else:
+        success = hit(exp1) and (hit(exp2) if exp2 else True)
+
+    rec = {
+        "scenario_id": scenario["id"], "mode": mode, "scale": scale, "rep": rep,
+        "n_tools_registered": n_registered,
+        "elapsed_seconds": round(elapsed, 2),
+        "api_calls": len(usage_log),
+        "prompt_tokens_total": sum(u["prompt_tokens"] or 0 for u in usage_log),
+        "completion_tokens_total": sum(u["completion_tokens"] or 0 for u in usage_log),
+        "per_call_usage": usage_log,
+        "bridge_calls": bridge_call_log,
+        "underlying_tools_called": called[:40],
+        "success": bool(success), "error": error,
+        "final_response": base._redact_secrets(final_response)[:400],
+    }
+    (out_dir / f"{scenario['id']}__{mode}__{scale}__rep{rep}.json").write_text(json.dumps(rec, indent=1), encoding="utf-8")
+    shutil.rmtree(Path(os.environ["HERMES_HOME"]).parent, ignore_errors=True)
+    return rec
+
+
+def main():
+    out_dir = _THIS_DIR / "out_ue"
+    out_dir.mkdir(exist_ok=True)
+    scale = os.environ.get("TS_UE_SCALE", "full")
+    modes = [m for m in os.environ.get("TS_UE_MODES", "listing,bridge,eager").split(",") if m]
+    rows = []
+    for scenario in SCENARIOS:
+        if scenario.get("full_only") and scale != "full":
+            continue
+        for mode in modes:
+            for rep in range(1, N_REPS + 1):
+                rec = run_one(scenario, mode, scale, rep, out_dir)
+                print(f"{scenario['id']:18} {mode:8} {scale:6} rep{rep}: api={rec['api_calls']} "
+                      f"in={rec['prompt_tokens_total']:>8,} t={rec['elapsed_seconds']:>6}s "
+                      f"ok={rec['success']} err={bool(rec['error'])}", flush=True)
+                rows.append(rec)
+    name = os.environ.get("TS_UE_SUMMARY", f"_ue_bench_{scale}.json")
+    (out_dir / name).write_text(json.dumps(
+        [{k: v for k, v in r.items() if k not in ("per_call_usage", "bridge_calls", "final_response")} for r in rows],
+        indent=1), encoding="utf-8")
+    print("done ->", out_dir / name)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/tool_search_livetest_ue_disc.py b/scripts/tool_search_livetest_ue_disc.py
new file mode 100644
index 00000000000..f3d0bb33f35
--- /dev/null
+++ b/scripts/tool_search_livetest_ue_disc.py
@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""Live benchmark v5 — DISCOVERY-BOUND tasks at 830 tools. Opus 4.8, bridge vs listing.
+
+Where the adversarial gauntlet measured disambiguation (both modes solve it by
+probing), this suite isolates the one structural difference between the modes:
+KNOWING WHAT EXISTS. Three task families:
+
+  D* discovery  — the tool exists but the prompt shares ZERO lexical surface
+                  with its name/description (BM25-hostile paraphrase).
+  A* absence    — no tool does what's asked (verified against all 830).
+                  Correct behavior = confident refusal, no hallucinated calls.
+  S* survey     — "which of these five things can we do?" — breadth question.
+
+Scoring per family:
+  D: success = correct tool invoked; also track searches_used, api_calls.
+  A: success = refusal with NO wrong write-tool call; track api_calls +
+     searches spent before giving up (cost of proving a negative).
+  S: success = final answer classifies all five capabilities correctly.
+"""
+from __future__ import annotations
+
+import json, os, shutil, sys, time, traceback
+from pathlib import Path
+from typing import Any, Dict, List
+
+_THIS_DIR = Path(__file__).resolve().parent
+_WORKTREE_ROOT = _THIS_DIR.parent
+sys.path.insert(0, str(_WORKTREE_ROOT))
+sys.path.insert(0, str(_THIS_DIR))
+
+import tool_search_livetest as base
+from tool_search_livetest_ue_hard import register_epic_tools_adversarial
+
+N_REPS = int(os.environ.get("TS_BENCH_REPS", "3"))
+
+SCENARIOS: List[Dict[str, Any]] = [
+    # ---- D: discovery under paraphrase (tool exists; zero name overlap)
+    {
+        "id": "D1_sparkly_brighter",
+        "prompt": ("The sparkly effect on the actor Torch_3 looks too dim. Make it brighter — "
+                   "its glow strength setting should go to 5.0. Then say done."),
+        "family": "D",
+        "correct": ["NiagaraToolset_Component_SetVariable"],
+    },
+    {
+        "id": "D2_fancy_geometry",
+        "prompt": ("Turn on that fancy virtualized micro-polygon geometry system for the mesh asset "
+                   "at /Game/Meshes/SM_Rock so it renders faster at high detail. Then say done."),
+        "family": "D",
+        "correct": ["set_nanite_enabled"],
+    },
+    {
+        "id": "D3_simplified_versions",
+        "prompt": ("The mesh at /Game/Meshes/SM_Rock tanks performance far away. Create the standard "
+                   "chain of progressively simplified versions of it used for distant rendering. Then say done."),
+        "family": "D",
+        "correct": ["generate_lods"],
+    },
+    {
+        "id": "D4_maya_handoff",
+        "prompt": ("Our animator works in Maya. Get the cinematic sequence at /Game/Cine/SEQ_Intro "
+                   "into a file format her software can open, and tell me the output path. Then say done."),
+        "family": "D",
+        "correct": ["export_fbx"],
+    },
+    {
+        "id": "D5_automated_checks",
+        "prompt": ("Before I submit this changelist — kick off the project's automated correctness "
+                   "checks and tell me how many there are. Then say done."),
+        "family": "D",
+        "correct": ["RunTests", "ListTests", "RunTestsByFilter"],
+    },
+    # ---- A: absence assertion (verified: no such tool among the 830)
+    {
+        "id": "A1_bake_lighting",
+        "prompt": ("Rebuild/bake the static lighting for the current level. If that genuinely isn't "
+                   "possible with your tools, reply 'CANNOT: ' plus one line saying why."),
+        "family": "A",
+    },
+    {
+        "id": "A2_undo",
+        "prompt": ("Undo my last change in the editor. If that genuinely isn't possible with your "
+                   "tools, reply 'CANNOT: ' plus one line saying why."),
+        "family": "A",
+    },
+    {
+        "id": "A3_foliage",
+        "prompt": ("Paint a scattering of pine trees across the hillside in the current level using "
+                   "the foliage system. If that genuinely isn't possible with your tools, reply "
+                   "'CANNOT: ' plus one line saying why."),
+        "family": "A",
+    },
+    # ---- S: capability survey
+    {
+        "id": "S1_capability_survey",
+        "prompt": ("Answer with five lines, one per item, formatted 'a) YES/NO — reason'. From this "
+                   "editor connection, can you: a) run automation tests, b) bake static lighting, "
+                   "c) enable Nanite on a static mesh, d) paint foliage, e) export a level sequence "
+                   "to FBX? Do not call any editing tools — just determine capability."),
+        "family": "S",
+        "survey_truth": {"a": True, "b": False, "c": True, "d": False, "e": True},
+    },
+]
+
+
+def score_survey(resp: str, truth: Dict[str, bool]) -> bool:
+    import re
+    resp_l = resp.lower()
+    for key, expected in truth.items():
+        m = re.search(rf"\b{key}\)?\s*[:\-—]?\s*(yes|no)", resp_l)
+        if not m:
+            return False
+        if (m.group(1) == "yes") != expected:
+            return False
+    return True
+
+
+def run_one(scenario, mode, rep, out_dir: Path):
+    model = os.environ.get("TS_UE_MODEL", "anthropic/claude-opus-4.8")
+    lmax = int(os.environ.get("TS_UE_LISTING_MAX", "30000"))
+    hermes_home = base.setup_isolated_home(
+        True, listing=("auto" if mode == "listing" else "off"),
+        listing_max_tokens=lmax, model=model)
+    os.environ["HERMES_HOME"] = str(hermes_home)
+    base.reset_module_state()
+    register_epic_tools_adversarial()
+
+    from tools.registry import registry
+    original_dispatch = registry.dispatch
+    call_log: List[str] = []
+
+    def logging_dispatch(name, args, **kw):
+        call_log.append(name)
+        return original_dispatch(name, args, **kw)
+    registry.dispatch = logging_dispatch
+
+    usage_log: List[Dict[str, Any]] = []
+    started = time.time()
+    error = None
+    final_response = ""
+    messages_out: List[Dict[str, Any]] = []
+    _orig_norm = None
+    try:
+        from run_agent import AIAgent
+        agent = AIAgent(provider="openrouter", model=model, quiet_mode=True,
+                        save_trajectories=False, skip_context_files=True,
+                        skip_memory=True, platform="cli", max_iterations=15)
+        import agent.conversation_loop as _cl
+        _orig_norm = _cl.normalize_usage
+        def _norm_spy(raw, **kw):
+            cu = _orig_norm(raw, **kw)
+            try:
+                usage_log.append({"prompt_tokens": cu.prompt_tokens})
+            except Exception:
+                pass
+            return cu
+        _cl.normalize_usage = _norm_spy
+        result = agent.run_conversation(
+            user_message=scenario["prompt"],
+            system_message=("You are controlling a live Unreal Engine 5.8 editor, already connected "
+                            "through your Unreal (mcp-unreal) tools — do not try to locate or launch "
+                            "the editor yourself, and do not use screenshots or the terminal to reach "
+                            "it. If a capability doesn't exist in your tools, say so plainly. Be concise."),
+        )
+        if isinstance(result, dict):
+            final_response = result.get("final_response") or ""
+            messages_out = result.get("messages") or []
+    except Exception:
+        error = traceback.format_exc()
+    finally:
+        registry.dispatch = original_dispatch
+        if _orig_norm is not None:
+            try:
+                import agent.conversation_loop as _cl2
+                _cl2.normalize_usage = _orig_norm
+            except Exception:
+                pass
+
+    elapsed = time.time() - started
+    bridge_call_log = base._extract_bridge_calls(messages_out)
+    searches = sum(1 for b in bridge_call_log if b["name"] == "tool_search")
+    ue_calls = [c for c in call_log if c.lower() not in ("tool_search", "tool_describe", "tool_call")
+                and not c.startswith(("skills_list", "skill_", "todo", "memory"))]
+    # writes = non-read calls (for absence scoring: any UE write = hallucinated capability)
+    write_calls = [c for c in ue_calls if not any(v in c.lower() for v in
+                   ("get", "list", "find", "search", "has_", "is_", "can_", "observe", "snapshot"))]
+
+    fam = scenario["family"]
+    if fam == "D":
+        success = any(any(s.lower() in c.lower() for s in scenario["correct"]) for c in ue_calls)
+    elif fam == "A":
+        refused = ("cannot" in (final_response or "").lower() or "can't" in (final_response or "").lower()
+                   or "not possible" in (final_response or "").lower() or "no tool" in (final_response or "").lower())
+        success = refused and not write_calls and error is None
+    else:  # S
+        success = score_survey(final_response or "", scenario["survey_truth"]) and not write_calls
+
+    rec = {
+        "scenario_id": scenario["id"], "family": fam, "mode": mode, "rep": rep,
+        "elapsed_seconds": round(elapsed, 2),
+        "api_calls": len(usage_log),
+        "searches_used": searches,
+        "prompt_tokens_total": sum(u["prompt_tokens"] or 0 for u in usage_log),
+        "ue_calls": [c[-60:] for c in ue_calls][:15],
+        "write_calls": [c[-60:] for c in write_calls][:10],
+        "bridge_queries": [(b.get("args") or {}).get("query") for b in bridge_call_log if b["name"] == "tool_search"][:10],
+        "success": bool(success), "error": error,
+        "final_response": base._redact_secrets(final_response)[:400],
+    }
+    (out_dir / f"{scenario['id']}__{mode}__rep{rep}.json").write_text(json.dumps(rec, indent=1), encoding="utf-8")
+    shutil.rmtree(Path(os.environ["HERMES_HOME"]).parent, ignore_errors=True)
+    return rec
+
+
+def main():
+    out_dir = _THIS_DIR / "out_ue_disc"
+    out_dir.mkdir(exist_ok=True)
+    modes = [m for m in os.environ.get("TS_UE_MODES", "listing,bridge").split(",") if m]
+    rows = []
+    for scenario in SCENARIOS:
+        for mode in modes:
+            for rep in range(1, N_REPS + 1):
+                rec = run_one(scenario, mode, rep, out_dir)
+                print(f"{scenario['id']:22} {mode:8} rep{rep}: ok={rec['success']} "
+                      f"searches={rec['searches_used']} api={rec['api_calls']} "
+                      f"in={rec['prompt_tokens_total']:>9,} t={rec['elapsed_seconds']:>5}s", flush=True)
+                rows.append(rec)
+    name = os.environ.get("TS_UE_SUMMARY", "_ue_discovery.json")
+    (out_dir / name).write_text(json.dumps(rows, indent=1), encoding="utf-8")
+    print("done ->", out_dir / name)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/tool_search_livetest_ue_hard.py b/scripts/tool_search_livetest_ue_hard.py
new file mode 100644
index 00000000000..24ad8f2d1f8
--- /dev/null
+++ b/scripts/tool_search_livetest_ue_hard.py
@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""Live benchmark v4 — ADVERSARIAL Unreal tool selection at 830 tools.
+
+Differences from tool_search_livetest_ue.py (which had a ceiling effect):
+
+1. Scenarios target CONFUSION CLUSTERS in Epic's real catalog — tools with
+   near-identical names/purposes in different toolsets (StaticMesh vs
+   SkeletalMesh set_material; GameplayTags vs ActorTools vs GameplayCue tags;
+   CurveTable vs DataTable rows; Niagara Component vs System SetVariable;
+   4 capture variants). Prompts avoid quoting exact tool names.
+2. TYPE-AWARE mocks: calling a tool against the wrong asset/actor type
+   returns a realistic editor error (e.g. "SM_Rock is not a SkeletalMesh"),
+   so wrong picks visibly fail instead of silently succeeding.
+3. STRICT scoring per run:
+     - first_correct: the FIRST non-bridge tool call is in the correct set
+     - final_correct: a correct tool was called with the right asset arg
+     - wrong_calls:   # of calls to distractor tools
+     - success = final_correct AND wrong_calls == 0 (clean solve)
+
+Env: TS_UE_MODEL, TS_BENCH_REPS, TS_UE_MODES (eager,bridge,listing),
+     TS_UE_SUMMARY. Scale is always "full" (830 tools).
+"""
+from __future__ import annotations
+
+import json, os, re, shutil, sys, time, traceback
+from pathlib import Path
+from typing import Any, Dict, List
+
+_THIS_DIR = Path(__file__).resolve().parent
+_WORKTREE_ROOT = _THIS_DIR.parent
+sys.path.insert(0, str(_WORKTREE_ROOT))
+sys.path.insert(0, str(_THIS_DIR))
+
+import tool_search_livetest as base
+from tool_search_livetest_ue import load_epic_tools, _SANITIZE  # reuse loader
+
+N_REPS = int(os.environ.get("TS_BENCH_REPS", "2"))
+
+# ---------------------------------------------------------------------------
+# Type-aware mock world
+# ---------------------------------------------------------------------------
+
+WORLD = {
+    "/Game/Meshes/SM_Rock": "StaticMesh",
+    "/Game/Chars/SK_Guard": "SkeletalMesh",
+    "/Game/Data/CT_Damage": "CurveTable",
+    "/Game/Data/DT_Loot": "DataTable",
+    "/Game/FX/NS_Sparks": "NiagaraSystem",
+    "Torch_3": "Actor",         # has a NiagaraComponent
+    "Crate_2": "Actor",
+}
+
+def _mentioned_path(kwargs: Dict[str, Any]) -> str:
+    blob = json.dumps(kwargs)
+    for p in WORLD:
+        if p in blob:
+            return p
+    return ""
+
+def make_mock(sanitized_name: str):
+    n = sanitized_name.lower()
+
+    def _h(*a, **kw):
+        path = _mentioned_path(kw)
+        t = WORLD.get(path, "")
+        # Wrong-type guards mirror the real editor's failures.
+        if "skeletalmeshtools" in n and t and t != "SkeletalMesh":
+            return json.dumps({"error": f"{path} is a {t}, not a SkeletalMesh. Use the StaticMesh tools."})
+        if "staticmeshtools" in n and t and t != "StaticMesh":
+            return json.dumps({"error": f"{path} is a {t}, not a StaticMesh."})
+        if "curvetabletools" in n and t and t != "CurveTable":
+            return json.dumps({"error": f"{path} is a {t}, not a CurveTable."})
+        if "datatabletools" in n and t and t != "DataTable":
+            return json.dumps({"error": f"{path} is a {t}, not a DataTable."})
+        if "niagaratoolset_system" in n and t == "Actor":
+            return json.dumps({"error": f"{path} is a level actor, not a NiagaraSystem asset. Use the Niagara component tools for actors."})
+        if "niagaratoolset_component" in n and t == "NiagaraSystem":
+            return json.dumps({"error": f"{path} is a NiagaraSystem asset, not an actor with a NiagaraComponent."})
+        # Coherent world reads so the model can chain calls.
+        if "find_actors" in n or "getvisibleactors" in n or "get_outliner" in n:
+            blob = json.dumps(kw)
+            actors = [{"label": "Torch_3", "path": "/Game/Map:PersistentLevel.Torch_3",
+                       "class": "Actor", "components": ["NiagaraComponent 'FX_Flame'"]},
+                      {"label": "Crate_2", "path": "/Game/Map:PersistentLevel.Crate_2",
+                       "class": "StaticMeshActor"}]
+            if "Torch" in blob:
+                actors = actors[:1]
+            elif "Crate" in blob:
+                actors = actors[1:]
+            return json.dumps({"result": actors})
+        if "get_components" in n:
+            blob = json.dumps(kw)
+            if "Torch" in blob:
+                return json.dumps({"result": [{"name": "FX_Flame", "class": "NiagaraComponent"},
+                                              {"name": "PointLight0", "class": "PointLightComponent"}]})
+            return json.dumps({"result": [{"name": "StaticMeshComponent0", "class": "StaticMeshComponent"}]})
+        if "getuservariables" in n or "list_rows" in n or "listtags" in n or "get_tags" in n:
+            return json.dumps({"result": [{"name": "Brightness", "type": "float", "value": 1.0}]})
+        if any(v in n for v in ("get", "list", "find", "search", "has_", "is_", "can_")):
+            return json.dumps({"result": [{"name": "Entry_0", "value": 1.0}]})
+        if "capture" in n or "screenshot" in n:
+            return json.dumps({"result": {"image_path": "/tmp/ue_capture_0001.png"}})
+        return json.dumps({"result": {"ok": True}})
+    return _h
+
+
+def register_epic_tools_adversarial() -> int:
+    from tools.registry import registry
+    tools = load_epic_tools("full")
+    for tdef in tools:
+        registry.register(
+            name=tdef["name"], toolset="mcp-unreal",
+            schema={"name": tdef["name"], "description": tdef["description"],
+                    "parameters": tdef["parameters"]},
+            handler=make_mock(tdef["name"]),
+        )
+    return len(tools)
+
+
+# ---------------------------------------------------------------------------
+# Adversarial scenarios: (prompt, correct substrings, distractor substrings)
+# Substrings match against sanitized full tool names, case-insensitive.
+# ---------------------------------------------------------------------------
+
+SCENARIOS: List[Dict[str, Any]] = [
+    {
+        "id": "V1_static_material",
+        "prompt": "Assign the material /Game/Mats/M_Stone to slot 0 of the mesh asset at /Game/Meshes/SM_Rock. Then say done.",
+        "correct": ["StaticMeshTools_set_material"],
+        "distractors": ["SkeletalMeshTools_set_material", "MaterialTools_create_material", "MaterialInstanceTools"],
+    },
+    {
+        "id": "V2_skeletal_material",
+        "prompt": "Assign the material /Game/Mats/M_Cloth to slot 1 of the character mesh at /Game/Chars/SK_Guard. Then say done.",
+        "correct": ["SkeletalMeshTools_set_material"],
+        "distractors": ["StaticMeshTools_set_material"],
+    },
+    {
+        "id": "V3_curvetable_row",
+        "prompt": "Add a row named 'Heavy' to the table asset at /Game/Data/CT_Damage with value 42 at time 0. Then say done.",
+        "correct": ["CurveTableTools_add_row"],
+        "distractors": ["DataTableTools_add_rows", "DataTableTools_set_rows"],
+    },
+    {
+        "id": "V4_project_tag",
+        "prompt": "Register a new gameplay tag 'Combat.Stun' in the project's tag registry so designers can use it. Then say done.",
+        "correct": ["GameplayTagsToolset_AddTag"],
+        "distractors": ["ActorTools_add_tag", "GameplayCueToolset_AddCueTag"],
+    },
+    {
+        "id": "V5_actor_tag",
+        "prompt": "Mark the level actor named Crate_2 with the tag 'loot' so my spawner script can find it. Then say done.",
+        "correct": ["ActorTools_add_tag"],
+        "distractors": ["GameplayTagsToolset_AddTag", "GameplayCueToolset_AddCueTag"],
+    },
+    {
+        "id": "V6_niagara_component",
+        "prompt": "The particle effect on the actor Torch_3 is too dim — set its 'Brightness' user parameter to 5.0 on that actor's effect component. Then say done.",
+        "correct": ["NiagaraToolset_Component_SetVariable"],
+        "distractors": ["NiagaraToolset_System_AddUserVariables", "NiagaraToolset_System_AddSetParameterEntry",
+                        "DataflowAgentToolset_SetVariable", "NiagaraToolset_System"],
+    },
+    {
+        "id": "V7_niagara_system_asset",
+        "prompt": "Add a user-exposed float called 'WindStrength' to the effect asset at /Game/FX/NS_Sparks itself, so every instance can override it. Then say done.",
+        "correct": ["NiagaraToolset_System_AddUserVariables"],
+        "distractors": ["NiagaraToolset_Component_SetVariable", "DataflowAgentToolset_AddVariable"],
+    },
+    {
+        "id": "V8_widget_screenshot",
+        "prompt": "Capture an image of ONLY the Details panel widget (not the whole editor, not the 3D viewport). Tell me the file path. Then say done.",
+        "correct": ["SlateInspectorToolset_Screenshot"],
+        "distractors": ["CaptureViewport", "CaptureEditorImage", "CaptureAssetImage"],
+    },
+    {
+        "id": "V9_save_actor",
+        "prompt": "I just edited the actor Crate_2 in the level. Persist exactly that actor's changes to disk (not a full save-all). Then say done.",
+        "correct": ["SceneTools_save_actor"],
+        "distractors": ["AssetTools_save_assets", "ConfigSettingsToolset_SaveSection"],
+    },
+    {
+        "id": "V10_zero_keyword",
+        "prompt": "Something in my level list panel — the thing showing all the stuff placed in the world — seems stale. Get me whatever that panel's current contents are. Then say done.",
+        "correct": ["SceneTools_find_actors", "GetVisibleActors", "get_outliner"],
+        "distractors": ["GetContentBrowserPath", "SetContentBrowserPath"],
+    },
+]
+
+
+def run_one(scenario, mode, rep, out_dir: Path):
+    enabled = mode in ("bridge", "listing")
+    model = os.environ.get("TS_UE_MODEL", "anthropic/claude-opus-4.8")
+    lmax = int(os.environ.get("TS_UE_LISTING_MAX", "30000"))
+    hermes_home = base.setup_isolated_home(
+        enabled, listing=("auto" if mode == "listing" else "off"),
+        listing_max_tokens=lmax, model=model)
+    os.environ["HERMES_HOME"] = str(hermes_home)
+    base.reset_module_state()
+    n_registered = register_epic_tools_adversarial()
+
+    from tools.registry import registry
+    original_dispatch = registry.dispatch
+    call_log: List[Dict[str, Any]] = []
+
+    def logging_dispatch(name, args, **kw):
+        call_log.append({"name": name, "args": args})
+        return original_dispatch(name, args, **kw)
+    registry.dispatch = logging_dispatch
+
+    usage_log: List[Dict[str, Any]] = []
+    started = time.time()
+    error = None
+    final_response = ""
+    messages_out: List[Dict[str, Any]] = []
+    _orig_norm = None
+    try:
+        from run_agent import AIAgent
+        agent = AIAgent(provider="openrouter", model=model, quiet_mode=True,
+                        save_trajectories=False, skip_context_files=True,
+                        skip_memory=True, platform="cli", max_iterations=15)
+        import agent.conversation_loop as _cl
+        _orig_norm = _cl.normalize_usage
+        def _norm_spy(raw, **kw):
+            cu = _orig_norm(raw, **kw)
+            try:
+                usage_log.append({"prompt_tokens": cu.prompt_tokens})
+            except Exception:
+                pass
+            return cu
+        _cl.normalize_usage = _norm_spy
+        result = agent.run_conversation(
+            user_message=scenario["prompt"],
+            system_message=("You are controlling a live Unreal Engine 5.8 editor. The editor is "
+                            "already running and connected through your Unreal (mcp-unreal) tools — "
+                            "do not try to locate or launch the editor yourself. Choose tools "
+                            "carefully: several toolsets contain similarly-named tools for "
+                            "different object types. Be concise."),
+        )
+        if isinstance(result, dict):
+            final_response = result.get("final_response") or ""
+            messages_out = result.get("messages") or []
+    except Exception:
+        error = traceback.format_exc()
+    finally:
+        registry.dispatch = original_dispatch
+        if _orig_norm is not None:
+            try:
+                import agent.conversation_loop as _cl2
+                _cl2.normalize_usage = _orig_norm
+            except Exception:
+                pass
+
+    elapsed = time.time() - started
+    bridge_call_log = base._extract_bridge_calls(messages_out)
+    # underlying calls: registry log + tool_call unwraps (registry sees both; dedupe consecutive)
+    ue_calls = [c for c in call_log if c["name"].lower() not in ("tool_search", "tool_describe", "tool_call")
+                and not c["name"].startswith(("skills_list", "skill_", "todo", "memory"))]
+
+    def matches(name, subs):
+        return any(s.lower() in name.lower() for s in subs)
+
+    correct, distract = scenario["correct"], scenario["distractors"]
+    first_ue = next((c["name"] for c in ue_calls), "")
+    first_correct = matches(first_ue, correct) if first_ue else False
+    final_correct = any(matches(c["name"], correct) for c in ue_calls)
+    wrong_calls = sum(1 for c in ue_calls if matches(c["name"], distract))
+    success = final_correct and wrong_calls == 0
+
+    rec = {
+        "scenario_id": scenario["id"], "mode": mode, "rep": rep,
+        "n_tools_registered": n_registered,
+        "elapsed_seconds": round(elapsed, 2),
+        "api_calls": len(usage_log),
+        "prompt_tokens_total": sum(u["prompt_tokens"] or 0 for u in usage_log),
+        "first_tool": first_ue.split("_")[-2:] if first_ue else None,
+        "first_correct": first_correct, "final_correct": final_correct,
+        "wrong_calls": wrong_calls, "success": bool(success),
+        "ue_calls": [c["name"][-70:] for c in ue_calls][:20],
+        "bridge_calls": [(b["name"], (b.get("args") or {}).get("query") or (b.get("args") or {}).get("name")) for b in bridge_call_log][:20],
+        "error": error,
+        "final_response": base._redact_secrets(final_response)[:300],
+    }
+    (out_dir / f"{scenario['id']}__{mode}__rep{rep}.json").write_text(json.dumps(rec, indent=1), encoding="utf-8")
+    shutil.rmtree(Path(os.environ["HERMES_HOME"]).parent, ignore_errors=True)
+    return rec
+
+
+def main():
+    out_dir = _THIS_DIR / "out_ue_hard"
+    out_dir.mkdir(exist_ok=True)
+    modes = [m for m in os.environ.get("TS_UE_MODES", "listing,bridge").split(",") if m]
+    rows = []
+    for scenario in SCENARIOS:
+        for mode in modes:
+            for rep in range(1, N_REPS + 1):
+                rec = run_one(scenario, mode, rep, out_dir)
+                print(f"{scenario['id']:22} {mode:8} rep{rep}: 1st={'Y' if rec['first_correct'] else 'n'} "
+                      f"final={'Y' if rec['final_correct'] else 'n'} wrong={rec['wrong_calls']} "
+                      f"ok={rec['success']} api={rec['api_calls']} in={rec['prompt_tokens_total']:>9,} "
+                      f"t={rec['elapsed_seconds']:>5}s", flush=True)
+                rows.append(rec)
+    name = os.environ.get("TS_UE_SUMMARY", "_ue_hard.json")
+    (out_dir / name).write_text(json.dumps(rows, indent=1), encoding="utf-8")
+    print("done ->", out_dir / name)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skills/apple/apple-notes/SKILL.md b/skills/apple/apple-notes/SKILL.md
index 020f0d641df..3fcf4c25c0c 100644
--- a/skills/apple/apple-notes/SKILL.md
+++ b/skills/apple/apple-notes/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: apple-notes
 description: "Manage Apple Notes via memo CLI: create, search, edit."
-version: 1.0.0
+version: 1.0.1
 author: Hermes Agent
 license: MIT
 platforms: [macos]
@@ -49,10 +49,14 @@ memo notes -s "query"             # Search notes (fuzzy)
 ### Create Notes
 
 ```bash
-memo notes -a                     # Interactive editor
-memo notes -a "Note Title"        # Quick add with title
+memo notes -a                     # Add a note (opens your $EDITOR)
+memo notes -a -f "Folder Name"    # Add a note into a specific folder
 ```
 
+`-a`/`--add` is a bare flag — it opens your `$EDITOR` to compose the note; it does
+not take a title argument. Use `-f/--folder` to target a folder. Set `$EDITOR`
+first (e.g. `export EDITOR=vim`).
+
 ### Edit Notes
 
 ```bash
diff --git a/skills/autonomous-ai-agents/claude-code/SKILL.md b/skills/autonomous-ai-agents/claude-code/SKILL.md
index 57f5147b7c8..7b5c7521519 100644
--- a/skills/autonomous-ai-agents/claude-code/SKILL.md
+++ b/skills/autonomous-ai-agents/claude-code/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: claude-code
 description: "Delegate coding to Claude Code CLI (features, PRs)."
-version: 2.2.0
+version: 2.2.1
 author: Hermes Agent + Teknium
 license: MIT
 platforms: [linux, macos, windows]
@@ -265,7 +265,7 @@ Automatically falls back to the specified model when the default is overloaded (
 | Flag | Effect |
 |------|--------|
 | `--model <alias>` | Model selection: `sonnet`, `opus`, `haiku`, or full name like `claude-sonnet-4-6` |
-| `--effort <level>` | Reasoning depth: `low`, `medium`, `high`, `max`, `auto` | Both |
+| `--effort <level>` | Reasoning depth: `low`, `medium`, `high`, `xhigh`, `max` |
 | `--max-turns <n>` | Limit agentic loops (print mode only; prevents runaway) |
 | `--max-budget-usd <n>` | Cap API spend in dollars (print mode only) |
 | `--fallback-model <model>` | Auto-fallback when default model is overloaded (print mode only) |
@@ -389,7 +389,7 @@ Use the `#` prefix in interactive mode to quickly add to memory: `# Always use 2
 | Command | Purpose |
 |---------|---------|
 | `/model [model]` | Switch models mid-session (use arrow keys to adjust effort) |
-| `/effort [level]` | Set reasoning effort: `low`, `medium`, `high`, `max`, or `auto` |
+| `/effort [level]` | Set reasoning effort: `low`, `medium`, `high`, `xhigh`, or `max` |
 | `/init` | Create a CLAUDE.md file for project memory |
 | `/memory` | Open CLAUDE.md for editing |
 | `/config` | Open interactive settings configuration |
diff --git a/skills/autonomous-ai-agents/codex/SKILL.md b/skills/autonomous-ai-agents/codex/SKILL.md
index 87b5666fcda..7829b1e111c 100644
--- a/skills/autonomous-ai-agents/codex/SKILL.md
+++ b/skills/autonomous-ai-agents/codex/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: codex
 description: "Delegate coding to OpenAI Codex CLI (features, PRs)."
-version: 1.0.0
+version: 1.0.1
 author: Hermes Agent
 license: MIT
 platforms: [linux, macos, windows]
@@ -53,7 +53,7 @@ terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game
 
 ```
 # Start in background with PTY
-terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
+terminal(command="codex exec --sandbox workspace-write 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
 # Returns session_id
 
 # Monitor progress
@@ -72,10 +72,12 @@ process(action="kill", session_id="<id>")
 | Flag | Effect |
 |------|--------|
 | `exec "prompt"` | One-shot execution, exits when done |
-| `--full-auto` | Sandboxed but auto-approves file changes in workspace |
-| `--yolo` | No sandbox, no approvals (fastest, most dangerous) |
+| `--sandbox workspace-write` (`-s`) | Sandboxed but auto-approves file changes in the workspace (the recommended auto-build mode) |
+| `--dangerously-bypass-approvals-and-sandbox` | No sandbox, no approvals (fastest, most dangerous; `--yolo` still works as a hidden alias) |
 | `--sandbox danger-full-access` | No Codex sandbox; useful when the host service context breaks bubblewrap |
 
+> **Deprecated:** `--full-auto` still works but the live CLI warns to use `--sandbox workspace-write` instead.
+
 ## Hermes Gateway Caveat
 
 When invoking the Codex CLI from a Hermes gateway/service context (for example,
@@ -110,8 +112,8 @@ terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir=
 terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
 
 # Launch Codex in each
-terminal(command="codex --yolo exec 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
-terminal(command="codex --yolo exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)
+terminal(command="codex --sandbox workspace-write exec 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
+terminal(command="codex --sandbox workspace-write exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)
 
 # Monitor
 process(action="list")
@@ -143,7 +145,7 @@ terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")
 1. **Always use `pty=true`** — Codex is an interactive terminal app and hangs without a PTY
 2. **Git repo required** — Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch
 3. **Use `exec` for one-shots** — `codex exec "prompt"` runs and exits cleanly
-4. **`--full-auto` for building** — auto-approves changes within the sandbox
+4. **`--sandbox workspace-write` for building** — auto-approves changes within the sandbox (`--full-auto` is deprecated for this)
 5. **Background for long tasks** — use `background=true` and monitor with `process` tool
 6. **Don't interfere** — monitor with `poll`/`log`, be patient with long-running tasks
 7. **Parallel is fine** — run multiple Codex processes at once for batch work
diff --git a/skills/computer-use/SKILL.md b/skills/autonomous-ai-agents/computer-use/SKILL.md
similarity index 99%
rename from skills/computer-use/SKILL.md
rename to skills/autonomous-ai-agents/computer-use/SKILL.md
index 85c73dfa5e0..07fe306c7dc 100644
--- a/skills/computer-use/SKILL.md
+++ b/skills/autonomous-ai-agents/computer-use/SKILL.md
@@ -12,7 +12,7 @@ metadata:
   hermes:
     tags: [computer-use, desktop, automation, gui, cross-platform]
     category: desktop
-    related_skills: [browser]
+    related_skills: []
 ---
 
 # Computer Use (universal, any-model, cross-platform)
diff --git a/skills/autonomous-ai-agents/hermes-agent/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/SKILL.md
index ac4c84dead9..42edf68cc41 100644
--- a/skills/autonomous-ai-agents/hermes-agent/SKILL.md
+++ b/skills/autonomous-ai-agents/hermes-agent/SKILL.md
@@ -1,13 +1,13 @@
 ---
 name: hermes-agent
-description: "Configure, extend, or contribute to Hermes Agent."
-version: 2.3.0
+description: "Use, configure, theme, extend, and orchestrate Hermes Agent."
+version: 3.1.0
 author: Hermes Agent + Teknium
 license: MIT
 platforms: [linux, macos, windows]
 metadata:
   hermes:
-    tags: [hermes, setup, configuration, multi-agent, spawning, cli, gateway, development]
+    tags: [hermes, setup, configuration, multi-agent, spawning, cli, gateway, themes, skins, desktop-plugins, tui-widgets, petdex, development]
     homepage: https://github.com/NousResearch/hermes-agent
     related_skills: [claude-code, codex, opencode]
 ---
@@ -18,23 +18,21 @@ Hermes Agent is an open-source AI agent framework by Nous Research that runs in
 
 What makes Hermes different:
 
-- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment.
-- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works.
+- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills that load into future sessions.
+- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends.
 - **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat.
 - **Many surfaces** — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains).
-- **Provider-agnostic** — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically.
+- **Provider-agnostic** — swap models and providers mid-workflow; credential pools rotate across multiple API keys automatically.
 - **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
-- **Extensible** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem.
+- **Extensible & themeable** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, skins that theme every surface, desktop UI plugins, TUI widgets, and pet mascots.
 
-People use Hermes for software development, research, system administration, data analysis, content creation, home automation, and anything else that benefits from an AI agent with persistent context and full system access.
-
-**This skill helps you work with Hermes Agent effectively** — setting it up, configuring features, spawning additional agent instances, troubleshooting issues, finding the right commands and settings, and understanding how the system works when you need to extend or contribute to it.
+**This skill is a hub.** The body covers identity, quick start, spawning/orchestration, and hard invariants. Everything else lives in reference files — **load the matching reference (below) before answering**; do not answer detail questions from the body alone.
 
 **Docs:** https://hermes-agent.nousresearch.com/docs/
 
 ## Scope & Verification
 
-This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.
+This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.
 
 Good verification targets:
 
@@ -65,552 +63,49 @@ hermes dashboard               # web admin panel + embedded chat
 hermes proxy                   # OpenAI-compatible local proxy backed by your OAuth provider
 ```
 
----
-
-## CLI Reference
-
-### Global Flags
+## Key Paths
 
 ```
-hermes [flags] [command]
-
-  --version, -V             Show version
-  --resume, -r SESSION      Resume session by ID or title
-  --continue, -c [NAME]     Resume by name, or most recent session
-  --worktree, -w            Isolated git worktree mode (parallel agents)
-  --skills, -s SKILL        Preload skills (comma-separate or repeat)
-  --profile, -p NAME        Use a named profile
-  --yolo                    Skip dangerous command approval
-  --pass-session-id         Include session ID in system prompt
-```
-
-No subcommand defaults to `chat`.
-
-### Chat
-
-```
-hermes chat [flags]
-  -q, --query TEXT          Single query, non-interactive
-  -m, --model MODEL         Model (e.g. anthropic/claude-sonnet-4)
-  -t, --toolsets LIST       Comma-separated toolsets
-  --provider PROVIDER       Force provider (openrouter, anthropic, nous, etc.)
-  -v, --verbose             Verbose output
-  -Q, --quiet               Suppress banner, spinner, tool previews
-  --checkpoints             Enable filesystem checkpoints (/rollback)
-  --source TAG              Session source tag (default: cli)
-```
-
-### Configuration
-
-```
-hermes setup [section]      Interactive wizard (model|terminal|gateway|tools|agent)
-hermes model                Interactive model/provider picker
-hermes config               View current config
-hermes config edit          Open config.yaml in $EDITOR
-hermes config set KEY VAL   Set a config value
-hermes config path          Print config.yaml path
-hermes config env-path      Print .env path
-hermes config check         Check for missing/outdated config
-hermes config migrate       Update config with new options
-hermes doctor [--fix]       Check dependencies and config
-hermes status [--all]       Show component status
-```
-
-Credentials (OAuth + API keys, with pooling) are managed under `hermes auth` — see the Credentials & Pools section below.
-
-### Tools & Skills
-
-```
-hermes tools                Interactive tool enable/disable (curses UI)
-hermes tools list           Show all tools and status
-hermes tools enable NAME    Enable a toolset
-hermes tools disable NAME   Disable a toolset
-
-hermes skills list          List installed skills
-hermes skills search QUERY  Search the skills hub
-hermes skills install ID    Install a skill (ID can be a hub identifier OR a direct https://…/SKILL.md URL; pass --name to override when frontmatter has no name)
-hermes skills inspect ID    Preview without installing
-hermes skills config        Enable/disable skills per platform
-hermes skills check         Check for updates
-hermes skills update        Update outdated skills
-hermes skills uninstall N   Remove a hub skill
-hermes skills publish PATH  Publish to registry
-hermes skills browse        Browse all available skills
-hermes skills tap add REPO  Add a GitHub repo as skill source
-```
-
-### MCP Servers
-
-```
-hermes mcp serve            Run Hermes as an MCP server
-hermes mcp add NAME         Add an MCP server (--url or --command)
-hermes mcp remove NAME      Remove an MCP server
-hermes mcp list             List configured servers
-hermes mcp test NAME        Test connection
-hermes mcp configure NAME   Toggle tool selection
-```
-
-How the built-in MCP client connects servers (stdio/HTTP), auto-discovers
-their tools, and exposes them as first-class tools, plus catalog install
-(`hermes mcp install <name>`): `skill_view(name="hermes-agent", file_path="references/native-mcp.md")`.
-
-### Gateway (Messaging Platforms)
-
-```
-hermes gateway run          Start gateway foreground
-hermes gateway install      Install as background service
-hermes gateway start/stop   Control the service
-hermes gateway restart      Restart the service
-hermes gateway status       Check status
-hermes gateway setup        Configure platforms
-```
-
-Supported platforms (20+): Telegram, Discord, Slack, WhatsApp (Baileys bridge + official Business Cloud API), iMessage (Photon — `hermes photon setup`, the BlueBubbles successor with no Mac relay), Signal, Email, SMS, Matrix, Mattermost, Microsoft Teams, LINE, SimpleX, ntfy, Google Chat, Home Assistant, DingTalk, Feishu, WeCom, Weixin (WeChat), Raft (agent network), API Server, Webhooks. Open WebUI connects via the API Server adapter. Most adapters ship under `plugins/platforms/`, so new ones drop in without touching core.
-
-Platform docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/
-
-### Sessions
-
-```
-hermes sessions list        List recent sessions
-hermes sessions browse      Interactive picker
-hermes sessions export OUT  Export to JSONL
-hermes sessions rename ID T Rename a session
-hermes sessions delete ID   Delete a session
-hermes sessions prune       Clean up old sessions (--older-than N days)
-hermes sessions stats       Session store statistics
-```
-
-### Cron Jobs
-
-```
-hermes cron list            List jobs (--all for disabled)
-hermes cron create SCHED    Create: '30m', 'every 2h', '0 9 * * *'
-hermes cron edit ID         Edit schedule, prompt, delivery
-hermes cron pause/resume ID Control job state
-hermes cron run ID          Trigger on next tick
-hermes cron remove ID       Delete a job
-hermes cron status          Scheduler status
-```
-
-### Webhooks
-
-```
-hermes webhook subscribe N  Create route at /webhooks/<name>
-hermes webhook list         List subscriptions
-hermes webhook remove NAME  Remove a subscription
-hermes webhook test NAME    Send a test POST
-```
-
-Full setup, route config, payload templating, and event-driven agent-run
-patterns: `skill_view(name="hermes-agent", file_path="references/webhooks.md")`.
-
-### Profiles
-
-```
-hermes profile list         List all profiles
-hermes profile create NAME  Create (--clone, --clone-all, --clone-from)
-hermes profile use NAME     Set sticky default
-hermes profile delete NAME  Delete a profile
-hermes profile show NAME    Show details
-hermes profile alias NAME   Manage wrapper scripts
-hermes profile rename A B   Rename a profile
-hermes profile export NAME  Export to tar.gz
-hermes profile import FILE  Import from archive
-```
-
-### Credentials & Pools
-
-```
-hermes auth                 Interactive credential manager
-hermes auth add [PROVIDER]  Add OAuth or API-key credential
-                            (e.g. nous, openai-codex, qwen-oauth, anthropic)
-hermes auth list [PROVIDER] List pooled credentials
-hermes auth remove P INDEX  Remove by provider + index
-hermes auth reset PROVIDER  Clear exhaustion status
-```
-
-Multiple credentials per provider form a pool that rotates automatically and skips exhausted keys.
-
-### Other
-
-```
-hermes insights [--days N]  Usage analytics
-hermes update               Update to latest version
-hermes desktop / gui        Launch the native desktop app
-hermes dashboard            Web admin panel + embedded chat
-hermes proxy                OpenAI-compatible local proxy backed by an OAuth provider
-hermes portal               Quick setup / sign in via Nous Portal
-hermes kanban <verb>        Multi-agent work-queue board (init/create/list/show/assign/…)
-hermes pairing list/approve/revoke  DM authorization
-hermes plugins list/install/remove  Plugin management
-hermes secrets bitwarden …  External secret store (Bitwarden Secrets Manager)
-hermes memory setup/status/off  Memory provider config
-hermes send                 Send a one-off message through a gateway platform
-hermes completion bash|zsh  Shell completions
-hermes acp                  ACP server (IDE integration)
-hermes claw migrate         Migrate from OpenClaw
-hermes uninstall            Uninstall Hermes
-```
-
-For the full, authoritative command list run `hermes --help` (and `hermes <command> --help`). Plugin- and provider-supplied subcommands (e.g. `hermes photon setup` for iMessage) only appear once their plugin is installed/active.
-
----
-
-## Slash Commands (In-Session)
-
-Type these during an interactive chat session. New commands land fairly
-often; if something below looks stale, run `/help` in-session for the
-authoritative list or see the [live slash commands reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands).
-The registry of record is `hermes_cli/commands.py` — every consumer
-(autocomplete, Telegram menu, Slack mapping, `/help`) derives from it.
-
-### Session Control
-```
-/new (/reset)        Fresh session
-/clear               Clear screen + new session (CLI)
-/retry               Resend last message
-/undo                Remove last exchange
-/title [name]        Name the session
-/compress            Manually compress context
-/stop                Kill background processes
-/rollback [N]        Restore filesystem checkpoint
-/snapshot [sub]      Create or restore state snapshots of Hermes config/state (CLI)
-/background <prompt> Run prompt in background
-/queue <prompt>      Queue for next turn
-/steer <prompt>      Inject a message after the next tool call without interrupting
-/agents (/tasks)     Show active agents and running tasks
-/resume [name]       Resume a named session
-/goal [text|sub]     Set a standing goal Hermes works on across turns until achieved
-                     (subcommands: status, pause, resume, clear)
-/redraw              Force a full UI repaint (CLI)
-```
-
-### Configuration
-```
-/config              Show config (CLI)
-/model [name]        Show or change model
-/personality [name]  Set personality
-/reasoning [level]   Set reasoning (none|minimal|low|medium|high|xhigh|max|ultra|show|hide)
-/verbose             Cycle: off → new → all → verbose
-/voice [on|off|tts]  Voice mode
-/yolo                Toggle approval bypass
-/busy [sub]          Control what Enter does while Hermes is working (CLI)
-                     (subcommands: queue, steer, interrupt, status)
-/indicator [style]   Pick the TUI busy-indicator style (CLI)
-                     (styles: kaomoji, emoji, unicode, ascii)
-/footer [on|off]     Toggle gateway runtime-metadata footer on final replies
-/skin [name]         Change theme (CLI)
-/statusbar           Toggle status bar (CLI)
-```
-
-### Tools & Skills
-```
-/tools               Manage tools (CLI)
-/toolsets            List toolsets (CLI)
-/skills              Search/install skills (CLI)
-/skill <name>        Load a skill into session
-/reload-skills       Re-scan ~/.hermes/skills/ for added/removed skills
-/reload              Reload .env variables into the running session (CLI)
-/reload-mcp          Reload MCP servers
-/cron                Manage cron jobs (CLI)
-/curator [sub]       Background skill maintenance (status, run, pin, archive, …)
-/kanban [sub]        Multi-profile collaboration board (tasks, links, comments)
-/plugins             List plugins (CLI)
-```
-
-### Gateway
-```
-/approve             Approve a pending command (gateway)
-/deny                Deny a pending command (gateway)
-/restart             Restart gateway (gateway)
-/sethome             Set current chat as home channel (gateway)
-/update              Update Hermes to latest (gateway)
-/topic [sub]         Enable or inspect Telegram DM topic sessions (gateway)
-/platforms (/gateway) Show platform connection status (gateway)
-```
-
-### Utility
-```
-/branch (/fork)      Branch the current session
-/handoff <platform>  Hand the live session off to a messaging platform (CLI)
-/fast                Toggle priority/fast processing
-/browser             Open CDP browser connection
-/history             Show conversation history (CLI)
-/save                Save conversation to file (CLI)
-/copy [N]            Copy the last assistant response to clipboard (CLI)
-/paste               Attach clipboard image (CLI)
-/image               Attach local image file (CLI)
-```
-
-### Info
-```
-/help                Show commands
-/commands [page]     Browse all commands (gateway)
-/usage               Token usage
-/insights [days]     Usage analytics
-/status              Session info (gateway)
-/profile             Active profile info
-/debug               Upload debug report (system info + logs) and get shareable links
-```
-
-### Exit
-```
-/quit (/exit, /q)    Exit CLI
-```
-
----
-
-## Key Paths & Config
-
-```
-~/.hermes/config.yaml       Main configuration
-~/.hermes/.env              API keys and secrets (under $HERMES_HOME if set)
+~/.hermes/config.yaml       Main configuration (settings — never secrets)
+~/.hermes/.env              API keys and secrets ONLY (under $HERMES_HOME if set)
 $HERMES_HOME/skills/        Installed skills
-~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts (and optional per-session JSON snapshots when sessions.write_json_snapshots: true)
+~/.hermes/skins/            Custom themes (see references/themes.md)
+~/.hermes/desktop-plugins/  Desktop app UI plugins (see references/desktop-plugins.md)
+~/.hermes/tui-widgets/      TUI widget apps (see references/tui-widgets.md)
+~/.hermes/pets/             Installed pet mascots (see references/petdex.md)
 ~/.hermes/state.db          Canonical session store (SQLite + FTS5)
+~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts
 ~/.hermes/logs/             Gateway and error logs
 ~/.hermes/auth.json         OAuth tokens and credential pools
 ~/.hermes/hermes-agent/     Source code (if git-installed)
 ```
 
-Profiles use `~/.hermes/profiles/<name>/` with the same layout.
+Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile is active, resolve the real home from `$HERMES_HOME` — never hardcode `~/.hermes`.
 
-### Config Sections
+## Routing Table — load the reference for the task
 
-Edit with `hermes config edit` or `hermes config set section.key value`.
+| User wants... | Load |
+|---|---|
+| CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` |
+| In-session slash commands | `references/slash-commands.md` |
+| Provider setup, API keys, OAuth | `references/providers-and-models.md` |
+| config.yaml sections, toolsets, voice/STT/TTS | `references/configuration.md` |
+| AGENTS.md / .hermes.md / CLAUDE.md project rules | `references/project-context-files.md` |
+| Secret redaction, PII, approval modes, "reset permissions" | `references/security-privacy.md` |
+| Delegation, cron, curator, kanban | `references/background-systems.md` |
+| MCP servers (add, catalog, `hermes mcp`) | `references/native-mcp.md` |
+| Webhook routes and event-driven runs | `references/webhooks.md` |
+| A custom theme/skin ("synthwave theme", "change the gold ●") | `references/themes.md` + `templates/skin.yaml` |
+| A desktop app UI element (pane, widget, ⌘K command, page) | `references/desktop-plugins.md` + `templates/plugin.js` |
+| A live TUI panel or modal widget (ticker, clock, dashboard) | `references/tui-widgets.md` + `templates/clock.mjs` |
+| Pet mascots — install, select, scale, diagnose | `references/petdex.md` |
+| Windows-specific issues (keybinds, WinError 10106, BOM) | `references/windows-quirks.md` |
+| Debugging: voice, tools missing, gateway, aux models | `references/troubleshooting.md` |
+| Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` |
+| delegate_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` |
+| "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` |
 
-| Section | Key options |
-|---------|-------------|
-| `model` | `default`, `provider`, `base_url`, `api_key`, `context_length` |
-| `agent` | `max_turns` (90), `tool_use_enforcement` |
-| `terminal` | `backend` (local/docker/ssh/modal), `cwd`, `timeout` (180) |
-| `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) |
-| `display` | `skin`, `interface` (cli/tui), `tool_progress`, `show_reasoning`, `show_cost`, `language` |
-| `stt` | `enabled`, `provider` (local/groq/openai/mistral) |
-| `tts` | `provider` (edge/elevenlabs/openai/minimax/mistral/neutts) |
-| `memory` | `memory_enabled`, `user_profile_enabled`, `provider` |
-| `security` | `tirith_enabled`, `website_blocklist` |
-| `delegation` | `model`, `provider`, `base_url`, `api_key`, `max_iterations` (50), `reasoning_effort` |
-| `checkpoints` | `enabled`, `max_snapshots` (50) |
-| `curator` | `enabled`, `consolidate` (false — opt-in aux-model skill consolidation), `interval_hours`, `stale_after_days` |
-
-Full config reference: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
-
-### Providers
-
-20+ providers supported. Set via `hermes model` or `hermes setup`.
-
-| Provider | Auth | Key env var |
-|----------|------|-------------|
-| OpenRouter | API key | `OPENROUTER_API_KEY` |
-| Anthropic | API key | `ANTHROPIC_API_KEY` |
-| Nous Portal | OAuth | `hermes auth` |
-| OpenAI Codex | OAuth | `hermes auth` |
-| GitHub Copilot | Token | `COPILOT_GITHUB_TOKEN` |
-| Google Gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
-| DeepSeek | API key | `DEEPSEEK_API_KEY` |
-| xAI / Grok | API key | `XAI_API_KEY` |
-| Hugging Face | Token | `HF_TOKEN` |
-| Z.AI / GLM | API key | `GLM_API_KEY` |
-| MiniMax | API key | `MINIMAX_API_KEY` |
-| MiniMax CN | API key | `MINIMAX_CN_API_KEY` |
-| Kimi / Moonshot | API key | `KIMI_API_KEY` |
-| Alibaba / DashScope | API key | `DASHSCOPE_API_KEY` |
-| Xiaomi MiMo | API key | `XIAOMI_API_KEY` |
-| Kilo Code | API key | `KILOCODE_API_KEY` |
-| OpenCode Zen | API key | `OPENCODE_ZEN_API_KEY` |
-| OpenCode Go | API key | `OPENCODE_GO_API_KEY` |
-| Qwen OAuth | OAuth | `hermes auth add qwen-oauth` |
-| Custom endpoint | Config | `model.base_url` + `model.api_key` in config.yaml |
-| GitHub Copilot ACP | External | `COPILOT_CLI_PATH` or Copilot CLI |
-
-Full provider docs: https://hermes-agent.nousresearch.com/docs/integrations/providers
-
-### Toolsets
-
-Enable/disable via `hermes tools` (interactive) or `hermes tools enable/disable NAME`.
-
-| Toolset | What it provides |
-|---------|-----------------|
-| `web` | Web search and content extraction |
-| `search` | Web search only (subset of `web`) |
-| `browser` | Browser automation (Browserbase, Camofox, or local Chromium) |
-| `terminal` | Shell commands and process management |
-| `file` | File read/write/search/patch |
-| `code_execution` | Sandboxed Python execution |
-| `vision` | Image analysis |
-| `image_gen` | AI image generation and image-to-image editing |
-| `video` | Video analysis (`video_analyze`) and generation |
-| `x_search` | First-class X (Twitter) search (X OAuth or API key) |
-| `tts` | Text-to-speech |
-| `skills` | Skill browsing and management |
-| `memory` | Persistent cross-session memory |
-| `session_search` | Search past conversations |
-| `delegation` | Subagent task delegation |
-| `cronjob` | Scheduled task management |
-| `clarify` | Ask user clarifying questions |
-| `messaging` | Cross-platform message sending |
-| `todo` | In-session task planning and tracking |
-| `kanban` | Multi-agent work-queue tools (gated to workers) |
-| `debugging` | Extra introspection/debug tools (off by default) |
-| `safe` | Minimal, low-risk toolset for locked-down sessions |
-| `spotify` | Spotify playback and playlist control |
-| `homeassistant` | Smart home control (off by default) |
-| `discord` | Discord integration tools |
-| `discord_admin` | Discord admin/moderation tools |
-| `feishu_doc` | Feishu (Lark) document tools |
-| `feishu_drive` | Feishu (Lark) drive tools |
-| `yuanbao` | Yuanbao integration tools |
-| `rl` | Reinforcement learning tools (off by default) |
-
-Full enumeration lives in `toolsets.py` as the `TOOLSETS` dict; `_HERMES_CORE_TOOLS` is the default bundle most platforms inherit from.
-
-Tool changes take effect on `/reset` (new session). They do NOT apply mid-conversation to preserve prompt caching.
-
----
-
-## Project Context Files
-
-Hermes injects project-level instructions into the system prompt by reading context files from the working directory. The discovery order is **first match wins** — only one project context source is loaded per session.
-
-| File (in priority order) | Discovery | Use when |
-|---|---|---|
-| `.hermes.md` / `HERMES.md` | Walks parents up to the git root, stops at git root | You want hierarchical project rules (root + per-package overrides) |
-| `AGENTS.md` / `agents.md` | **Cwd only** — subdirectory and parent copies are ignored | You want portable agent instructions that work the same in Hermes, Claude Code, Codex, etc. |
-| `CLAUDE.md` / `claude.md` | Cwd only | Same as AGENTS.md, Claude-flavored |
-| `.cursorrules` / `.cursor/rules/*.mdc` | Cwd only | Migrating from Cursor |
-
-`SOUL.md` (in `$HERMES_HOME`) is independent and always loaded when present — it sets the agent's identity, not project rules.
-
-### Pick the right one
-
-- **Use `.hermes.md`** when you want Hermes-specific behavior that lives above the cwd (root + subtree), or when you want rules to inherit from a parent directory. The parent walk stops at the git root, so a home-level `.hermes.md` won't leak into every project (a git repo's root is the boundary).
-- **Use `AGENTS.md`** when the same project will also be worked on by other agents (Codex, Claude Code, OpenCode). Those tools all have their own conventions for `AGENTS.md`, and the "cwd only" contract keeps the file portable.
-- **Don't put project rules in `~/.hermes/AGENTS.md`** (or any other home-level location). When Hermes runs with that directory as cwd, the file loads — but only for that one directory. For cross-project context, use `SOUL.md` (in `$HERMES_HOME`, identity-only) or install a skill via `hermes skills install`.
-
-### Size and truncation
-
-Each context file is capped at 20,000 characters. Files longer than that get **head + tail** truncated (the middle is dropped, with a `[...truncated...]` marker). For large project rules, prefer splitting into multiple skills over cramming one file.
-
-### Security
-
-All context files pass through the threat-pattern scanner before reaching the system prompt. Patterns matching prompt injection or promptware are replaced with a `[BLOCKED: ...]` placeholder. This means an `AGENTS.md` containing obvious injection attempts won't reach the model — the scanner blocks the content, not the file, so the rest of the file still loads.
-
-### Disable for one session
-
-`hermes --ignore-rules` skips auto-injection of all project context files (`.hermes.md`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`) **and** `SOUL.md` identity, plus user config, plugins, and MCP servers. Use it to isolate whether a problem is your setup or Hermes itself.
-
-### Example: a small `.hermes.md`
-
-```markdown
-# My Project
-
-Hermes: when working in this repo, follow these rules.
-
-## Build
-- Always run `make test` before declaring a change done.
-- Use `uv run` for Python, not `pip install`.
-
-## Style
-- Prefer `pathlib.Path` over `os.path`.
-- No `print()` in production code — use the `logger`.
-```
-
-That file at `/home/me/projects/myrepo/.hermes.md` is auto-loaded when Hermes runs in any subdirectory of `/home/me/projects/myrepo`, but not when it runs in `/home/me/other-project`.
-
-## Security & Privacy Toggles
-
-Common "why is Hermes doing X to my output / tool calls / commands?" toggles — and the exact commands to change them. Most of these need a fresh session (`/reset` in chat, or start a new `hermes` invocation) because they're read once at startup.
-
-### Secret redaction in tool output
-
-Secret redaction is **on by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) is scanned for strings that look like API keys, tokens, and secrets before it enters the conversation context and logs. Leave it enabled for normal use:
-
-```bash
-hermes config set security.redact_secrets true       # keep enabled globally
-```
-
-**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=false` from a tool call) will NOT take effect for the running process. Tell the user to change it in config from a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task.
-
-Disable only when you deliberately need raw credential-like strings for debugging or redactor development:
-```bash
-hermes config set security.redact_secrets false
-```
-
-### PII redaction in gateway messages
-
-Separate from secret redaction. When enabled, the gateway hashes user IDs and strips phone numbers from the session context before it reaches the model:
-
-```bash
-hermes config set privacy.redact_pii true    # enable
-hermes config set privacy.redact_pii false   # disable (default)
-```
-
-### Command approval prompts
-
-By default (`approvals.mode: smart`), Hermes asks an auxiliary LLM to assess shell commands flagged as destructive (`rm -rf`, `git reset --hard`, etc.). The modes are:
-
-- `smart` — auto-approve a low-risk command once, deny high-risk commands, and prompt when uncertain (default)
-- `manual` — always prompt
-- `off` — skip all approval prompts (equivalent to `--yolo`)
-
-```bash
-hermes config set approvals.mode smart       # recommended middle ground
-hermes config set approvals.mode off         # bypass everything (not recommended)
-```
-
-Per-invocation bypass without changing config:
-- `hermes --yolo …`
-- `export HERMES_YOLO_MODE=1`
-
-Note: YOLO / `approvals.mode: off` does NOT turn off secret redaction. They are independent.
-
-### Shell hooks allowlist
-
-Some shell-hook integrations require explicit allowlisting before they fire. Managed via `~/.hermes/shell-hooks-allowlist.json` — prompted interactively the first time a hook wants to run.
-
-### Disabling the web/browser/image-gen tools
-
-To keep the model away from network or media tools entirely, open `hermes tools` and toggle per-platform. Takes effect on next session (`/reset`). See the Tools & Skills section above.
-
----
-
-## Voice & Transcription
-
-### STT (Voice → Text)
-
-Voice messages from messaging platforms are auto-transcribed.
-
-Provider priority (auto-detected):
-1. **Local faster-whisper** — free, no API key: `pip install faster-whisper`
-2. **Groq Whisper** — free tier: set `GROQ_API_KEY`
-3. **OpenAI Whisper** — paid: set `VOICE_TOOLS_OPENAI_KEY`
-4. **Mistral Voxtral** — set `MISTRAL_API_KEY`
-
-Config:
-```yaml
-stt:
-  enabled: true
-  provider: local        # local, groq, openai, mistral
-  local:
-    model: base          # tiny, base, small, medium, large-v3
-```
-
-### TTS (Text → Voice)
-
-| Provider | Env var | Free? |
-|----------|---------|-------|
-| Edge TTS | None | Yes (default) |
-| ElevenLabs | `ELEVENLABS_API_KEY` | Free tier |
-| OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Paid |
-| MiniMax | `MINIMAX_API_KEY` | Paid |
-| Mistral (Voxtral) | `MISTRAL_API_KEY` | Paid |
-| NeuTTS (local) | None (`pip install neutts[all]` + `espeak-ng`) | Free |
-
-Voice commands: `/voice on` (voice-to-voice), `/voice tts` (always voice), `/voice off`.
-
----
+Two theming rules that hold even without loading the reference: **you apply skins yourself** (`hermes config set display.skin <name>` — every surface repaints live within ~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`hermes skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background.
 
 ## Spawning Additional Hermes Instances
 
@@ -690,419 +185,20 @@ terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_14305
 - **Use `hermes chat -q` for fire-and-forget** — no PTY needed
 - **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt_toolkit
 - **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry
+- **"delegate_task is capped at N" reports** — see `references/delegate-task-concurrency-diagnosis.md`. Three real cap paths in Hermes; if none fired, the model is self-limiting and rationalising it as "the runtime caps."
+- **"Can $external_app use my Nous Portal subscription / OAuth?"** — see `references/portal-auth-for-third-party-apps.md`. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).
 
----
+## Surfaces (quick orientation)
 
-## Durable & Background Systems
+- **Desktop app** (`hermes desktop` / `hermes gui`) — native Electron app for macOS/Linux/Windows: streaming chat, session list, Cmd+K palette, drag-and-drop files, native notifications, per-profile remote-gateway login. Extend it with UI plugins — `references/desktop-plugins.md`.
+- **Web dashboard** (`hermes dashboard`) — full admin panel: messaging channels, MCP catalog, webhooks, memory, profile builder, plus an embedded `hermes --tui` chat. Secured behind an OAuth/token gate.
+- **Ink TUI** (`hermes --tui` or `display.interface: tui`) — terminal UI with docked widget apps — `references/tui-widgets.md`.
+- **OpenAI-compatible proxy** (`hermes proxy`) — a local OpenAI API backed by whichever OAuth provider you're signed into. Point Codex CLI, Aider, Cline, or any script at it — no API key.
 
-Four systems run alongside the main conversation loop. Quick reference
-here; full developer notes live in `AGENTS.md`, user-facing docs under
-`website/docs/user-guide/features/`.
+## Hard Invariants (never violate, regardless of what you loaded)
 
-### Delegation (`delegate_task`)
-
-Spawn a subagent with an isolated context + terminal session.
-
-- **Single:** `delegate_task(goal, context)`.
-- **Batch:** `delegate_task(tasks=[{goal, ...}, ...])` runs children in
-  parallel, capped by `delegation.max_concurrent_children` (default 3).
-- **Background:** `delegate_task(background=true)` returns a handle
-  immediately and keeps the parent loop going; the child's result
-  re-enters the conversation as a new turn when it finishes.
-- **Roles:** `leaf` (default; cannot re-delegate) vs `orchestrator`
-  (can spawn its own workers, bounded by `delegation.max_spawn_depth`).
-- **Not durable.** A backgrounded child is still process-local — if the
-  parent process exits, the child is lost. For work that must outlive
-  the process, use `cronjob` or
-  `terminal(background=True, notify_on_complete=True)`.
-
-Config: `delegation.*` in `config.yaml`.
-
-### Cron (scheduled jobs)
-
-Durable scheduler — `cron/jobs.py` + `cron/scheduler.py`. Drive it via
-the `cronjob` tool, the `hermes cron` CLI (`list`, `add`, `edit`,
-`pause`, `resume`, `run`, `remove`), or the `/cron` slash command.
-
-- **Schedules:** duration (`"30m"`, `"2h"`), "every" phrase
-  (`"every monday 9am"`), 5-field cron (`"0 9 * * *"`), or ISO timestamp.
-- **Per-job knobs:** `skills`, `model`/`provider` override, `script`
-  (pre-run data collection; `no_agent=True` makes the script the whole
-  job), `context_from` (chain job A's output into job B), `workdir`
-  (run in a specific dir with its `AGENTS.md` / `CLAUDE.md` loaded),
-  multi-platform delivery.
-- **Invariants:** 3-minute hard interrupt per run, `.tick.lock` file
-  prevents duplicate ticks across processes, cron sessions pass
-  `skip_memory=True` by default, and cron deliveries are framed with a
-  header/footer instead of being mirrored into the target gateway
-  session (keeps role alternation intact).
-
-User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
-
-### Curator (skill lifecycle)
-
-Background maintenance for agent-created skills. Tracks usage, marks
-idle skills stale, archives stale ones, keeps a pre-run tar.gz backup
-so nothing is lost.
-
-- **CLI:** `hermes curator <verb>` — `status`, `run`, `pause`, `resume`,
-  `pin`, `unpin`, `archive`, `restore`, `prune`, `backup`, `rollback`.
-- **Slash:** `/curator <subcommand>` mirrors the CLI.
-- **Scope:** only touches skills with `created_by: "agent"` provenance.
-  Bundled + hub-installed skills are off-limits. **Never deletes** —
-  max destructive action is archive. Pinned skills are exempt from
-  every auto-transition and every LLM review pass.
-- **Cost:** the deterministic inactivity/prune sweep runs for free. The
-  aux-model "consolidate overlapping skills into umbrellas" pass is
-  **off by default** — opt in with `curator.consolidate: true` or
-  `hermes curator run --consolidate`. Routine background curation costs
-  zero tokens.
-- **Telemetry:** sidecar at `~/.hermes/skills/.usage.json` holds
-  per-skill `use_count`, `view_count`, `patch_count`,
-  `last_activity_at`, `state`, `pinned`.
-
-Config: `curator.*` (`enabled`, `interval_hours`, `min_idle_hours`,
-`stale_after_days`, `archive_after_days`, `backup.*`).
-User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/curator
-
-### Kanban (multi-agent work queue)
-
-Durable SQLite board for multi-profile / multi-worker collaboration.
-Users drive it via `hermes kanban <verb>`; dispatcher-spawned workers
-see a focused `kanban_*` toolset gated by `HERMES_KANBAN_TASK`, and
-orchestrator profiles can opt into the broader `kanban` toolset. Normal
-sessions still have zero `kanban_*` schema footprint unless configured.
-
-- **CLI verbs (common):** `init`, `create`, `list` (alias `ls`),
-  `show`, `assign`, `link`, `unlink`, `comment`, `complete`, `block`,
-  `unblock`, `archive`, `tail`. Less common: `watch`, `stats`, `runs`,
-  `log`, `dispatch`, `daemon`, `gc`.
-- **Worker/orchestrator toolset:** `kanban_show`, `kanban_complete`,
-  `kanban_block`, `kanban_heartbeat`, `kanban_comment`, `kanban_create`,
-  `kanban_link`; profiles that explicitly enable the `kanban` toolset
-  outside a dispatcher-spawned task also get `kanban_list` and
-  `kanban_unblock` for board routing.
-- **Dispatcher** runs inside the gateway by default
-  (`kanban.dispatch_in_gateway: true`) — reclaims stale claims,
-  promotes ready tasks, atomically claims, spawns assigned profiles.
-  Auto-blocks a task after `failure_limit` consecutive spawn failures
-  (default 2; configurable via `kanban.failure_limit` or per-task
-  `max_retries`).
-- **Isolation:** board is the hard boundary (workers get
-  `HERMES_KANBAN_BOARD` pinned in env); tenant is a soft namespace
-  within a board for workspace-path + memory-key isolation.
-
-User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban
-
----
-
-## Surfaces & Other Capabilities
-
-Beyond the CLI and gateway, a few things worth knowing about:
-
-- **Desktop app** (`hermes desktop` / `hermes gui`) — native Electron app
-  for macOS/Linux/Windows: streaming chat, session list, drag-and-drop +
-  clipboard-paste files, Cmd+K palette, status-bar model picker,
-  rebindable shortcuts, native notifications, live subagent watch-windows,
-  VS Code Marketplace themes, and per-profile remote-gateway login (OAuth
-  or username/password) so a thin local GUI can drive a heavy remote agent.
-- **Web dashboard** (`hermes dashboard`) — full admin panel: configure
-  every messaging channel, the MCP catalog, webhooks/hooks, memory, and a
-  complete profile builder (model + skills + MCPs) from the browser, plus
-  an embedded `hermes --tui` chat. Secured behind an OAuth/token gate.
-- **OpenAI-compatible proxy** (`hermes proxy`) — exposes a
-  `http://localhost:port` OpenAI API backed by whichever OAuth provider
-  you're signed into (Claude Pro, ChatGPT Pro, SuperGrok). Point Codex
-  CLI, Aider, Cline, Continue, or any script at it — no API key.
-- **Automation Blueprints** — pick a named automation and Hermes asks for
-  what it needs (no cron syntax). One definition renders as a dashboard
-  form, a slash command, an agent conversation, and a docs-catalog entry.
-- **`memory` tool batch operations** — pass an `operations` array of
-  add/replace/remove edits applied atomically against the final character
-  budget, so a single call can free space and add entries even when an add
-  alone would overflow.
-- **`session_search`** — FTS5-backed, no aux-LLM, effectively free. One
-  tool, three modes inferred from which args are set: discovery (`query`),
-  scroll (`session_id` + `around_message_id`), browse (no args).
-- **xAI Grok via SuperGrok OAuth** — sign in with your xAI account (no API
-  key); includes Cursor's `grok-composer-2.5-fast` coding model.
-
----
-
-## Windows-Specific Quirks
-
-Hermes runs natively on Windows (PowerShell, cmd, Windows Terminal, git-bash
-mintty, VS Code integrated terminal). Most of it just works, but a handful
-of differences between Win32 and POSIX have bitten us — document new ones
-here as you hit them so the next person (or the next session) doesn't
-rediscover them from scratch.
-
-### Input / Keybindings
-
-**Alt+Enter doesn't insert a newline** — Windows Terminal (and mintty) grab it
-for fullscreen before prompt_toolkit sees it. Use **Ctrl+Enter** instead (the
-CLI binds it to newline on Windows; raw Ctrl+J does the same, harmlessly).
-To inspect how your terminal reports a keystroke, run
-`python scripts/keystroke_diagnostic.py` from the repo root.
-
-### Config / Files
-
-**HTTP 400 "No models provided" on first run** — `config.yaml` was saved with
-a UTF-8 BOM (Notepad does this). Re-save as UTF-8 without BOM;
-`hermes config edit` writes correctly.
-
-### `execute_code` / Sandbox
-
-**WinError 10106** from the sandbox child process — it can't create an
-`AF_INET` socket. Root cause is usually Hermes's env scrubber dropping
-`SYSTEMROOT`/`WINDIR`/`COMSPEC` (Python's `socket` needs `SYSTEMROOT` to find
-`mswsock.dll`), not a broken Winsock LSP. The `_WINDOWS_ESSENTIAL_ENV_VARS`
-allowlist in `tools/code_execution_tool.py` covers it; if you still hit it,
-echo `os.environ` inside an `execute_code` block to confirm `SYSTEMROOT` is set.
-
-### Testing on Windows
-
-`scripts/run_tests.sh` is POSIX-only (expects `.venv/bin/activate`); the
-Hermes-installed `venv/Scripts/` has no pip/pytest (stripped for size).
-Install pytest into a system Python and run directly with `-n 0`
-(`pyproject.toml`'s `addopts` already sets `-n`):
-
-```bash
-"/c/Program Files/Python311/python" -m pip install --user pytest pytest-xdist pyyaml
-export PYTHONPATH="$(pwd)"
-"/c/Program Files/Python311/python" -m pytest tests/foo/test_bar.py -v --tb=short -n 0
-```
-
-(POSIX-only tests need skip guards — see the cross-platform guard list in the
-Contributor section below.)
-
-### Path / Filesystem
-
-**Line endings.** Git may warn `LF will be replaced by CRLF`. Cosmetic — the
-repo's `.gitattributes` normalizes. Don't let editors auto-convert committed
-POSIX-newline files to CRLF.
-
-**Forward slashes work almost everywhere.** `C:/Users/...` is accepted by
-every Hermes tool and most Windows APIs. Prefer forward slashes in code
-and logs — avoids shell-escaping backslashes in bash.
-
----
-
-## Troubleshooting
-
-### Voice not working
-1. Check `stt.enabled: true` in config.yaml
-2. Verify provider: `pip install faster-whisper` or set API key
-3. In gateway: `/restart`. In CLI: exit and relaunch.
-
-### Tool not available
-1. `hermes tools` — check if toolset is enabled for your platform
-2. Some tools need env vars (check `.env`)
-3. `/reset` after enabling tools
-
-### Model/provider issues
-1. `hermes doctor` — check config and dependencies
-2. `hermes auth` — re-authenticate OAuth providers (or `hermes auth add <provider>`)
-3. Check `.env` has the right API key
-4. **Copilot 403**: `gh auth login` tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via `hermes model` → GitHub Copilot.
-
-### Changes not taking effect
-- **Tools/skills:** `/reset` starts a new session with updated toolset
-- **Config changes:** In gateway: `/restart`. In CLI: exit and relaunch.
-- **Code changes:** Restart the CLI or gateway process
-
-### Skills not showing
-1. `hermes skills list` — verify installed
-2. `hermes skills config` — check platform enablement
-3. Load explicitly: `/skill name` or `hermes -s name`
-
-### Gateway issues
-Check logs first:
-```bash
-grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20
-```
-
-Common gateway problems:
-- **Gateway dies on SSH logout**: Enable linger: `sudo loginctl enable-linger $USER`
-- **Gateway dies on WSL2 close**: WSL2 requires `systemd=true` in `/etc/wsl.conf` for systemd services to work. Without it, gateway falls back to `nohup` (dies when session closes).
-- **Gateway crash loop**: Reset the failed state: `systemctl --user reset-failed hermes-gateway`
-
-### Platform-specific issues
-- **Discord bot silent**: Must enable **Message Content Intent** in Bot → Privileged Gateway Intents.
-- **Slack bot only works in DMs**: Must subscribe to `message.channels` event. Without it, the bot ignores public channels.
-- **Windows-specific issues** (`Alt+Enter` newline, WinError 10106, UTF-8 BOM config, test suite, line endings): see the dedicated **Windows-Specific Quirks** section above.
-
-### Auxiliary models not working
-If `auxiliary` tasks (vision, compression, session_search) fail silently, the `auto` provider can't find a backend. Either set `OPENROUTER_API_KEY` or `GOOGLE_API_KEY`, or explicitly configure each auxiliary task's provider:
-```bash
-hermes config set auxiliary.vision.provider <your_provider>
-hermes config set auxiliary.vision.model <model_name>
-```
-
----
-
-## Where to Find Things
-
-| Looking for... | Location |
-|----------------|----------|
-| Config options | `hermes config edit` or [Configuration docs](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) |
-| Available tools | `hermes tools list` or [Tools reference](https://hermes-agent.nousresearch.com/docs/reference/tools-reference) |
-| Slash commands | `/help` in session or [Slash commands reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) |
-| Skills catalog | `hermes skills browse` or [Skills catalog](https://hermes-agent.nousresearch.com/docs/reference/skills-catalog) |
-| Provider setup | `hermes model` or [Providers guide](https://hermes-agent.nousresearch.com/docs/integrations/providers) |
-| Platform setup | `hermes gateway setup` or [Messaging docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) |
-| MCP servers | `hermes mcp list` or [MCP guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) |
-| Profiles | `hermes profile list` or [Profiles docs](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) |
-| Cron jobs | `hermes cron list` or [Cron docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) |
-| Memory | `hermes memory status` or [Memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) |
-| Env variables | `hermes config env-path` or [Env vars reference](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) |
-| CLI commands | `hermes --help` or [CLI reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) |
-| Gateway logs | `~/.hermes/logs/gateway.log` |
-| Session files | `hermes sessions browse` (reads state.db) |
-| Source code | `~/.hermes/hermes-agent/` |
-
----
-
-## Contributor Quick Reference
-
-For occasional contributors and PR authors. Full developer docs: https://hermes-agent.nousresearch.com/docs/developer-guide/
-
-### Project Layout
-
-```
-hermes-agent/
-├── run_agent.py          # AIAgent — core conversation loop
-├── model_tools.py        # Tool discovery and dispatch
-├── toolsets.py           # Toolset definitions
-├── cli.py                # Interactive CLI (HermesCLI)
-├── hermes_state.py       # SQLite session store
-├── agent/                # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch
-├── hermes_cli/           # CLI subcommands, config, setup, commands
-│   ├── commands.py       # Slash command registry (CommandDef)
-│   ├── config.py         # DEFAULT_CONFIG, env var definitions
-│   └── main.py           # CLI entry point and argparse
-├── tools/                # One file per tool
-│   └── registry.py       # Central tool registry
-├── gateway/              # Messaging gateway
-│   └── platforms/        # Platform adapters (telegram, discord, etc.)
-├── cron/                 # Job scheduler
-├── tests/                # Extensive pytest suite (run via scripts/run_tests.sh)
-└── website/              # Docusaurus docs site
-```
-
-Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys) — both under `$HERMES_HOME` when it is set.
-
-### Adding a Tool
-
-Two files. Auto-discovery imports any `tools/*.py` with a top-level
-`registry.register()` call, but a tool is only *exposed* to an agent once
-its name appears in a toolset.
-
-**1. Create `tools/your_tool.py`:**
-```python
-import json, os
-from tools.registry import registry
-
-def check_requirements() -> bool:
-    return bool(os.getenv("EXAMPLE_API_KEY"))
-
-def example_tool(param: str, task_id: str = None) -> str:
-    return json.dumps({"success": True, "data": "..."})
-
-registry.register(
-    name="example_tool",
-    toolset="example",
-    schema={"name": "example_tool", "description": "...", "parameters": {...}},
-    handler=lambda args, **kw: example_tool(
-        param=args.get("param", ""), task_id=kw.get("task_id")),
-    check_fn=check_requirements,
-    requires_env=["EXAMPLE_API_KEY"],
-)
-```
-
-**2. Wire it into a toolset in `toolsets.py`** — add the name to
-`_HERMES_CORE_TOOLS` (every platform) or to a specific toolset.
-
-All handlers must return JSON strings. Use `get_hermes_home()` for paths,
-never hardcode `~/.hermes`. For custom/local-only tools, write a plugin in
-`~/.hermes/plugins/` instead of editing core — see the developer docs.
-
-### Adding a Slash Command
-
-1. Add `CommandDef` to `COMMAND_REGISTRY` in `hermes_cli/commands.py`
-2. Add handler in `cli.py` → `process_command()`
-3. (Optional) Add gateway handler in `gateway/run.py`
-
-All consumers (help text, autocomplete, Telegram menu, Slack mapping) derive from the central registry automatically.
-
-### Agent Loop (High Level)
-
-```
-run_conversation():
-  1. Build system prompt
-  2. Loop while iterations < max:
-     a. Call LLM (OpenAI-format messages + tool schemas)
-     b. If tool_calls → dispatch each via handle_function_call() → append results → continue
-     c. If text response → return
-  3. Context compression triggers automatically near token limit
-```
-
-### Testing
-
-Use the canonical runner — it enforces CI-parity (hermetic env, unset
-credentials, TZ=UTC, xdist workers, per-test subprocess isolation):
-
-```bash
-scripts/run_tests.sh                          # full suite
-scripts/run_tests.sh tests/tools/             # one directory
-scripts/run_tests.sh tests/tools/test_x.py    # one file
-scripts/run_tests.sh -v --tb=long             # pass-through pytest flags
-```
-
-- Tests auto-redirect `HERMES_HOME` to temp dirs — never touch real `~/.hermes/`.
-- The script probes `.venv`, then `venv`, then the shared worktree venv.
-- **Windows:** the wrapper is POSIX-only; see the **Windows-Specific Quirks**
-  section above for the direct-pytest workaround.
-
-**Cross-platform test guards:** tests using POSIX-only syscalls need a skip marker. Common ones already in the codebase:
-- Symlink creation → `@pytest.mark.skipif(sys.platform == "win32", reason="Symlinks require elevated privileges on Windows")` (see `tests/cron/test_cron_script.py`)
-- POSIX file modes (0o600, etc.) → `@pytest.mark.skipif(sys.platform.startswith("win"), reason="POSIX mode bits not enforced on Windows")` (see `tests/hermes_cli/test_auth_toctou_file_modes.py`)
-- `signal.SIGALRM` → Unix-only (see `tests/conftest.py::_enforce_test_timeout`)
-- Live Winsock / Windows-specific regression tests → `@pytest.mark.skipif(sys.platform != "win32", reason="Windows-specific regression")`
-
-**Monkeypatching `sys.platform` is not enough** when the code under test also calls `platform.system()` / `platform.release()` / `platform.mac_ver()`. Those functions re-read the real OS independently, so a test that sets `sys.platform = "linux"` on a Windows runner will still see `platform.system() == "Windows"` and route through the Windows branch. Patch all three together:
-
-```python
-monkeypatch.setattr(sys, "platform", "linux")
-monkeypatch.setattr(platform, "system", lambda: "Linux")
-monkeypatch.setattr(platform, "release", lambda: "6.8.0-generic")
-```
-
-See `tests/agent/test_prompt_builder.py::TestEnvironmentHints` for a worked example.
-
-### System prompt's execution-environment block
-
-Factual host/backend guidance (OS, `$HOME`, cwd, terminal backend, shell)
-is emitted by `agent/prompt_builder.py::build_environment_hints()`. The key
-invariant for prompt authors: with a **remote** terminal backend
-(`docker, singularity, modal, daytona, ssh, managed_modal`), host info is
-suppressed and *every* file tool runs inside the backend container — the
-prompt must never describe the host the agent can't touch.
-
-### Commit Conventions
-
-```
-type: concise subject line
-
-Optional body.
-```
-
-Types: `fix:`, `feat:`, `refactor:`, `docs:`, `chore:`
-
-### Key Rules
-
-- **Never break prompt caching** — don't change context, tools, or system prompt mid-conversation
-- **Message role alternation** — never two assistant or two user messages in a row
-- Use `get_hermes_home()` from `hermes_constants` for all paths (profile-safe)
-- Config values go in `config.yaml`, secrets go in `.env`
-- New tools need a `check_fn` so they only appear when requirements are met
+- **Never break prompt caching** — don't change past context, toolsets, or the system prompt mid-conversation. The only exception is context compression.
+- **Message role alternation** — never two assistant or two user messages in a row; only `tool` results can repeat.
+- **Secrets in `.env`, settings in `config.yaml`** — never tell a user to put a non-credential setting in `.env`.
+- **Profile-safe paths** — `get_hermes_home()` in code, `$HERMES_HOME` when resolving paths in a session.
+- **Never hand-edit `config.yaml` for the user** — use `hermes config set KEY VAL`; a stray indent can corrupt the file and break the live gateway.
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/background-systems.md b/skills/autonomous-ai-agents/hermes-agent/references/background-systems.md
new file mode 100644
index 00000000000..efb1ae2497f
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/background-systems.md
@@ -0,0 +1,101 @@
+# Durable & Background Systems
+
+Four systems run alongside the main conversation loop. Quick reference
+here; full developer notes live in `AGENTS.md`, user-facing docs under
+`website/docs/user-guide/features/`.
+
+### Delegation (`delegate_task`)
+
+Spawn a subagent with an isolated context + terminal session.
+
+- **Single:** `delegate_task(goal, context)`.
+- **Batch:** `delegate_task(tasks=[{goal, ...}, ...])` runs children in
+  parallel, capped by `delegation.max_concurrent_children` (default 3).
+- **Background:** `delegate_task(background=true)` returns a handle
+  immediately and keeps the parent loop going; the child's result
+  re-enters the conversation as a new turn when it finishes.
+- **Roles:** `leaf` (default; cannot re-delegate) vs `orchestrator`
+  (can spawn its own workers, bounded by `delegation.max_spawn_depth`).
+- **Not durable.** A backgrounded child is still process-local — if the
+  parent process exits, the child is lost. For work that must outlive
+  the process, use `cronjob` or
+  `terminal(background=True, notify_on_complete=True)`.
+
+Config: `delegation.*` in `config.yaml`.
+
+### Cron (scheduled jobs)
+
+Durable scheduler — `cron/jobs.py` + `cron/scheduler.py`. Drive it via
+the `cronjob` tool, the `hermes cron` CLI (`list`, `add`, `edit`,
+`pause`, `resume`, `run`, `remove`), or the `/cron` slash command.
+
+- **Schedules:** duration (`"30m"`, `"2h"`), "every" phrase
+  (`"every monday 9am"`), 5-field cron (`"0 9 * * *"`), or ISO timestamp.
+- **Per-job knobs:** `skills`, `model`/`provider` override, `script`
+  (pre-run data collection; `no_agent=True` makes the script the whole
+  job), `context_from` (chain job A's output into job B), `workdir`
+  (run in a specific dir with its `AGENTS.md` / `CLAUDE.md` loaded),
+  multi-platform delivery.
+- **Invariants:** 3-minute hard interrupt per run, `.tick.lock` file
+  prevents duplicate ticks across processes, cron sessions pass
+  `skip_memory=True` by default, and cron deliveries are framed with a
+  header/footer instead of being mirrored into the target gateway
+  session (keeps role alternation intact).
+
+User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
+
+### Curator (skill lifecycle)
+
+Background maintenance for agent-created skills. Tracks usage, marks
+idle skills stale, archives stale ones, keeps a pre-run tar.gz backup
+so nothing is lost.
+
+- **CLI:** `hermes curator <verb>` — `status`, `usage`, `run`, `pause`,
+  `resume`, `pin`, `unpin`, `archive`, `restore`, `list-archived`, `prune`,
+  `backup`, `rollback`.
+- **Slash:** `/curator <subcommand>` mirrors the CLI.
+- **Scope:** only touches skills with `created_by: "agent"` provenance.
+  Bundled + hub-installed skills are off-limits. **Never deletes** —
+  max destructive action is archive. Pinned skills are exempt from
+  every auto-transition and every LLM review pass.
+- **Cost:** the deterministic inactivity/prune sweep runs for free. The
+  aux-model "consolidate overlapping skills into umbrellas" pass is
+  **off by default** — opt in with `curator.consolidate: true` or
+  `hermes curator run --consolidate`. Routine background curation costs
+  zero tokens.
+- **Telemetry:** sidecar at `~/.hermes/skills/.usage.json` holds
+  per-skill `use_count`, `view_count`, `patch_count`,
+  `last_activity_at`, `state`, `pinned`.
+
+Config: `curator.*` (`enabled`, `interval_hours`, `min_idle_hours`,
+`stale_after_days`, `archive_after_days`, `backup.*`).
+User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/curator
+
+### Kanban (multi-agent work queue)
+
+Durable SQLite board for multi-profile / multi-worker collaboration.
+Users drive it via `hermes kanban <verb>`; dispatcher-spawned workers
+see a focused `kanban_*` toolset gated by `HERMES_KANBAN_TASK`, and
+orchestrator profiles can opt into the broader `kanban` toolset. Normal
+sessions still have zero `kanban_*` schema footprint unless configured.
+
+- **CLI verbs (common):** `init`, `create`, `list` (alias `ls`),
+  `show`, `assign`, `link`, `unlink`, `comment`, `complete`, `block`,
+  `unblock`, `archive`, `tail`. Less common: `watch`, `stats`, `runs`,
+  `log`, `dispatch`, `daemon`, `gc`.
+- **Worker/orchestrator toolset:** `kanban_show`, `kanban_complete`,
+  `kanban_block`, `kanban_heartbeat`, `kanban_comment`, `kanban_create`,
+  `kanban_link`; profiles that explicitly enable the `kanban` toolset
+  outside a dispatcher-spawned task also get `kanban_list` and
+  `kanban_unblock` for board routing.
+- **Dispatcher** runs inside the gateway by default
+  (`kanban.dispatch_in_gateway: true`) — reclaims stale claims,
+  promotes ready tasks, atomically claims, spawns assigned profiles.
+  Auto-blocks a task after `failure_limit` consecutive spawn failures
+  (default 2; configurable via `kanban.failure_limit` or per-task
+  `max_retries`).
+- **Isolation:** board is the hard boundary (workers get
+  `HERMES_KANBAN_BOARD` pinned in env); tenant is a soft namespace
+  within a board for workspace-path + memory-key isolation.
+
+User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/cli-reference.md b/skills/autonomous-ai-agents/hermes-agent/references/cli-reference.md
new file mode 100644
index 00000000000..10229f5bd57
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/cli-reference.md
@@ -0,0 +1,150 @@
+# Hermes CLI Reference
+
+Live sources when anything looks stale: `hermes --help`, `hermes <command> --help`,
+https://hermes-agent.nousresearch.com/docs/reference/cli-commands
+
+### Global Flags
+
+```
+hermes [flags] [command]        (no subcommand = interactive chat)
+
+  --version, -V             Show version
+  -z, --oneshot PROMPT      One-shot: print ONLY the final response (for scripts/pipes)
+  -m MODEL  --provider P    Model/provider override for this invocation
+  -t, --toolsets LIST       Comma-separated toolsets for this invocation
+  --resume, -r SESSION      Resume session by ID or title
+  --continue, -c [NAME]     Resume by name, or most recent session
+  --worktree, -w            Isolated git worktree mode (parallel agents)
+  --skills, -s SKILL        Preload skills (comma-separate or repeat)
+  --profile, -p NAME        Use a named profile
+  --yolo                    Skip dangerous command approval
+  --tui / --cli             Force the Ink TUI / classic REPL
+  --ignore-rules            Skip AGENTS.md/SOUL.md/memory/skill injection
+  --safe-mode               Disable ALL customizations (troubleshooting)
+  --pass-session-id         Include session ID in system prompt
+```
+
+### Chat
+
+```
+hermes chat [flags]
+  -q, --query TEXT          Single query, non-interactive
+  --image PATH              Attach a local image to a single query
+  -Q, --quiet               Suppress banner, spinner, tool previews
+  --checkpoints             Enable filesystem checkpoints (/rollback)
+  --max-turns N             Cap tool-calling iterations
+  --source TAG              Session source tag (default: cli)
+```
+(plus the global flags above)
+
+### Configuration
+
+```
+hermes setup [section]      Wizard (model|tts|terminal|gateway|tools|agent)
+hermes model                Interactive model/provider picker
+hermes fallback [add|remove|list]  Fallback provider chain
+hermes config [show|edit|get|set|unset|path|env-path|check|migrate]
+hermes login / logout       OAuth sign-in / clear stored auth
+hermes doctor [--fix]       Check dependencies and config
+hermes status [--all]       Component status
+```
+
+### Tools & Skills
+
+```
+hermes tools [list|enable NAME|disable NAME]   Per-platform toolsets (curses UI with no args)
+
+hermes skills list|browse|search QUERY|inspect ID
+hermes skills install ID    Hub identifier OR a direct https://…/SKILL.md URL
+hermes skills config        Enable/disable skills per platform
+hermes skills check|update|uninstall|publish PATH
+hermes skills tap add REPO  Add a GitHub repo as a skill source
+hermes bundles              Skill bundles (one /<name> alias loads several skills)
+```
+
+### MCP Servers
+
+```
+hermes mcp add NAME (--url or --command) | remove | list | test NAME
+hermes mcp catalog | install NAME     Curated catalog install
+hermes mcp configure NAME             Toggle tool selection
+hermes mcp serve                      Run Hermes as an MCP server
+```
+Details (transport, tool discovery, catalog): `references/native-mcp.md`.
+
+### Gateway (Messaging Platforms)
+
+```
+hermes gateway run|install|start|stop|restart|status|setup
+```
+
+20+ platforms: Telegram, Discord, Slack, WhatsApp (Baileys + Business Cloud API), iMessage (Photon — `hermes photon setup`), Signal, Email, SMS, Matrix, Mattermost, Teams, LINE, SimpleX, ntfy, Google Chat, Home Assistant, DingTalk, Feishu, WeCom, Weixin, API Server, Webhooks. Open WebUI connects via the API Server adapter. Most adapters ship under `plugins/platforms/`.
+Docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/
+
+### Sessions
+
+```
+hermes sessions list|browse|rename ID TITLE|delete ID|export OUT|prune|stats
+```
+
+### Cron / Webhooks
+
+```
+hermes cron list|create SCHED|edit ID|pause|resume|run ID|remove|status
+    Schedules: '30m', 'every 2h', '0 9 * * *', ISO timestamp
+hermes webhook subscribe NAME|list|remove NAME|test NAME
+```
+Webhook payloads/routes: `references/webhooks.md`.
+
+### Profiles
+
+```
+hermes profile list|create NAME (--clone|--clone-all|--clone-from)|use|show|delete
+hermes profile rename A B | alias NAME | export NAME | import FILE
+```
+
+### Credentials & Pools
+
+```
+hermes auth                 Interactive credential manager
+hermes auth add [PROVIDER]  Add OAuth or API-key credential (nous, openai-codex, qwen-oauth, …)
+hermes auth list|remove P IDX|reset PROVIDER|status
+```
+Multiple credentials per provider form a pool that rotates automatically and skips exhausted keys.
+
+### Other
+
+```
+hermes desktop / gui        Native desktop app
+hermes dashboard            Web admin panel + embedded chat (--stop / --status)
+hermes proxy                OpenAI-compatible local proxy backed by an OAuth provider
+hermes portal               Quick setup / sign in via Nous Portal
+hermes kanban <verb>        Multi-agent work-queue board
+hermes project              Named multi-folder workspaces
+hermes skin list|use|set    Switch/tweak skins (see references/themes.md)
+hermes pets <verb>          Pet mascots (see references/petdex.md)
+hermes memory setup|status|off|reset   Memory provider
+hermes secrets bitwarden|onepassword   External secret stores
+hermes moa                  Mixture-of-Agents slots
+hermes hooks / security / backup / import / checkpoints / console
+hermes logs [-f] [errors]   View agent/error logs
+hermes send                 One-off message through a gateway platform
+hermes pairing / plugins / insights / journey / computer-use
+hermes acp                  ACP server (IDE integration)
+hermes completion bash|zsh|fish
+hermes update / uninstall / claw migrate
+```
+
+Plugin- and provider-supplied subcommands (e.g. `hermes photon setup`) only appear once their plugin is installed/active.
+
+### Where to Find Things
+
+| Looking for... | Location |
+|---|---|
+| Config options | `hermes config edit` · [Configuration docs](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) |
+| Tools / toolsets | `hermes tools list` · [Tools reference](https://hermes-agent.nousresearch.com/docs/reference/tools-reference) |
+| Skills catalog | `hermes skills browse` · [Skills catalog](https://hermes-agent.nousresearch.com/docs/reference/skills-catalog) |
+| Provider setup | `hermes model` · [Providers guide](https://hermes-agent.nousresearch.com/docs/integrations/providers) |
+| Env variables | `hermes config env-path` · [Env vars reference](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) |
+| Gateway logs | `~/.hermes/logs/gateway.log` (or `hermes logs`) |
+| Sessions | `hermes sessions browse` (reads state.db) |
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/configuration.md b/skills/autonomous-ai-agents/hermes-agent/references/configuration.md
new file mode 100644
index 00000000000..e92443a56f5
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/configuration.md
@@ -0,0 +1,89 @@
+# Configuration, Toolsets & Voice
+
+Edit with `hermes config edit` or `hermes config set section.key value`.
+Full reference: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
+
+### Config Sections (most-used keys)
+
+| Section | Key options |
+|---------|-------------|
+| `model` | `default`, `provider`, `base_url`, `api_key`, `context_length`, `aliases` |
+| `agent` | `max_turns` (90), `tool_use_enforcement`, `service_tier`, `verify_on_stop` |
+| `terminal` | `backend` (local/docker/ssh/modal/daytona/singularity), `cwd`, `timeout` (180) |
+| `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) |
+| `display` | `skin`, `interface` (cli/tui), `language`, `show_reasoning`, `show_cost`, `pet` |
+| `approvals` | `mode` (smart/manual/off), `timeout`, `cron_mode` |
+| `stt` | `enabled`, `provider` (local/groq/openai/mistral/elevenlabs/deepinfra) |
+| `tts` | `provider` (edge/elevenlabs/openai/minimax/mistral/neutts/gemini/piper/kittentts/deepinfra/xai) |
+| `memory` | `memory_enabled`, `user_profile_enabled`, `provider`, `write_approval` |
+| `security` | `redact_secrets`, `tirith_enabled`, `website_blocklist` |
+| `delegation` | `model`, `provider`, `max_concurrent_children`, `max_iterations` (50), `max_spawn_depth` |
+| `checkpoints` | `enabled`, `max_snapshots` (50) |
+| `curator` | `enabled`, `consolidate` (false, opt-in aux-model consolidation), `interval_hours`, `stale_after_days` |
+
+`hermes config check` reports sections missing from an older config.
+
+### Toolsets
+
+Enable/disable via `hermes tools` (interactive) or `hermes tools enable/disable NAME`.
+Full enumeration: `TOOLSETS` dict in `toolsets.py` (`_HERMES_CORE_TOOLS` is the default bundle most platforms inherit).
+
+| Toolset | What it provides |
+|---------|-----------------|
+| `web` / `search` | Web search + extraction / search-only subset |
+| `browser` | Browser automation (Browserbase, Camofox, or local Chromium) |
+| `terminal` | Shell commands and process management |
+| `file` | File read/write/search/patch |
+| `code_execution` | Sandboxed Python execution |
+| `coding` | Code-editing helpers (LSP-backed) |
+| `computer_use` | Desktop GUI control (cua-driver) |
+| `vision` | Image analysis |
+| `image_gen` | Image generation and image-to-image editing |
+| `video` / `video_gen` | Video analysis / video generation |
+| `x_search` | X (Twitter) search (X OAuth or API key) |
+| `tts` | Text-to-speech |
+| `skills` | Skill browsing and management |
+| `memory` | Persistent cross-session memory |
+| `session_search` | Search past conversations |
+| `context_engine` | Pluggable context-engine hooks |
+| `project` | Named multi-folder workspace tools |
+| `delegation` | Subagent task delegation |
+| `cronjob` | Scheduled task management |
+| `clarify` | Ask user clarifying questions |
+| `todo` | In-session task planning |
+| `kanban` | Multi-agent work-queue tools (gated to workers) |
+| `debugging` | Extra introspection tools (off by default) |
+| `safe` | Minimal low-risk toolset for locked-down sessions |
+| `spotify`, `homeassistant`, `discord`, `discord_admin`, `feishu_doc`, `feishu_drive`, `yuanbao` | Service integrations (gated on their credentials) |
+
+Tool changes take effect on `/reset` (new session) — never mid-conversation, to preserve prompt caching.
+
+## Voice
+
+### STT (Voice → Text)
+
+Voice messages from messaging platforms are auto-transcribed.
+
+```yaml
+stt:
+  enabled: true
+  provider: local   # local (faster-whisper, free) | groq | openai | mistral | elevenlabs | deepinfra
+  local:
+    model: base     # tiny, base, small, medium, large-v3
+```
+
+Auto-detect priority: local faster-whisper (`pip install faster-whisper`) → Groq (`GROQ_API_KEY`, free tier) → OpenAI (`VOICE_TOOLS_OPENAI_KEY`) → Mistral Voxtral (`MISTRAL_API_KEY`).
+
+### TTS (Text → Voice)
+
+| Provider | Env var | Free? |
+|----------|---------|-------|
+| Edge TTS (default) | None | Yes |
+| ElevenLabs | `ELEVENLABS_API_KEY` | Free tier |
+| OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Paid |
+| MiniMax | `MINIMAX_API_KEY` | Paid |
+| Mistral | `MISTRAL_API_KEY` | Paid |
+| Gemini | `GOOGLE_API_KEY` | Free tier |
+| NeuTTS / Piper / KittenTTS (local) | None | Free |
+
+Voice commands: `/voice on` (voice-to-voice), `/voice tts` (always voice), `/voice off`.
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md b/skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md
new file mode 100644
index 00000000000..3bda9021185
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md
@@ -0,0 +1,143 @@
+# Contributor Quick Reference
+
+For occasional contributors and PR authors. Full developer docs: https://hermes-agent.nousresearch.com/docs/developer-guide/
+
+### Project Layout
+
+```
+hermes-agent/
+├── run_agent.py          # AIAgent — core conversation loop
+├── model_tools.py        # Tool discovery and dispatch
+├── toolsets.py           # Toolset definitions
+├── cli.py                # Interactive CLI (HermesCLI)
+├── hermes_state.py       # SQLite session store
+├── agent/                # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch
+├── hermes_cli/           # CLI subcommands, config, setup, commands
+│   ├── commands.py       # Slash command registry (CommandDef)
+│   ├── config.py         # DEFAULT_CONFIG, env var definitions
+│   └── main.py           # CLI entry point and argparse
+├── tools/                # One file per tool
+│   └── registry.py       # Central tool registry
+├── gateway/              # Messaging gateway
+│   └── platforms/        # Platform adapters (telegram, discord, etc.)
+├── cron/                 # Job scheduler
+├── tests/                # Extensive pytest suite (run via scripts/run_tests.sh)
+└── website/              # Docusaurus docs site
+```
+
+Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys) — both under `$HERMES_HOME` when it is set.
+
+### Adding a Tool
+
+Two files. Auto-discovery imports any `tools/*.py` with a top-level
+`registry.register()` call, but a tool is only *exposed* to an agent once
+its name appears in a toolset.
+
+**1. Create `tools/your_tool.py`:**
+```python
+import json, os
+from tools.registry import registry
+
+def check_requirements() -> bool:
+    return bool(os.getenv("EXAMPLE_API_KEY"))
+
+def example_tool(param: str, task_id: str = None) -> str:
+    return json.dumps({"success": True, "data": "..."})
+
+registry.register(
+    name="example_tool",
+    toolset="example",
+    schema={"name": "example_tool", "description": "...", "parameters": {...}},
+    handler=lambda args, **kw: example_tool(
+        param=args.get("param", ""), task_id=kw.get("task_id")),
+    check_fn=check_requirements,
+    requires_env=["EXAMPLE_API_KEY"],
+)
+```
+
+**2. Wire it into a toolset in `toolsets.py`** — add the name to
+`_HERMES_CORE_TOOLS` (every platform) or to a specific toolset.
+
+All handlers must return JSON strings. Use `get_hermes_home()` for paths,
+never hardcode `~/.hermes`. For custom/local-only tools, write a plugin in
+`~/.hermes/plugins/` instead of editing core — see the developer docs.
+
+### Adding a Slash Command
+
+1. Add `CommandDef` to `COMMAND_REGISTRY` in `hermes_cli/commands.py`
+2. Add handler in `cli.py` → `process_command()`
+3. (Optional) Add gateway handler in `gateway/run.py`
+
+All consumers (help text, autocomplete, Telegram menu, Slack mapping) derive from the central registry automatically.
+
+### Agent Loop (High Level)
+
+```
+run_conversation():
+  1. Build system prompt
+  2. Loop while iterations < max:
+     a. Call LLM (OpenAI-format messages + tool schemas)
+     b. If tool_calls → dispatch each via handle_function_call() → append results → continue
+     c. If text response → return
+  3. Context compression triggers automatically near token limit
+```
+
+### Testing
+
+Use the canonical runner — it enforces CI-parity (hermetic env, unset
+credentials, TZ=UTC, xdist workers, per-test subprocess isolation):
+
+```bash
+scripts/run_tests.sh                          # full suite
+scripts/run_tests.sh tests/tools/             # one directory
+scripts/run_tests.sh tests/tools/test_x.py    # one file
+scripts/run_tests.sh -v --tb=long             # pass-through pytest flags
+```
+
+- Tests auto-redirect `HERMES_HOME` to temp dirs — never touch real `~/.hermes/`.
+- The script probes `.venv`, then `venv`, then the shared worktree venv.
+- **Windows:** the wrapper is POSIX-only; see `references/windows-quirks.md`
+  for the direct-pytest workaround.
+
+**Cross-platform test guards:** tests using POSIX-only syscalls need a skip marker. Common ones already in the codebase:
+- Symlink creation → `@pytest.mark.skipif(sys.platform == "win32", reason="Symlinks require elevated privileges on Windows")` (see `tests/cron/test_cron_script.py`)
+- POSIX file modes (0o600, etc.) → `@pytest.mark.skipif(sys.platform.startswith("win"), reason="POSIX mode bits not enforced on Windows")` (see `tests/hermes_cli/test_auth_toctou_file_modes.py`)
+- `signal.SIGALRM` → Unix-only (see `tests/conftest.py::_enforce_test_timeout`)
+- Live Winsock / Windows-specific regression tests → `@pytest.mark.skipif(sys.platform != "win32", reason="Windows-specific regression")`
+
+**Monkeypatching `sys.platform` is not enough** when the code under test also calls `platform.system()` / `platform.release()` / `platform.mac_ver()`. Those functions re-read the real OS independently, so a test that sets `sys.platform = "linux"` on a Windows runner will still see `platform.system() == "Windows"` and route through the Windows branch. Patch all three together:
+
+```python
+monkeypatch.setattr(sys, "platform", "linux")
+monkeypatch.setattr(platform, "system", lambda: "Linux")
+monkeypatch.setattr(platform, "release", lambda: "6.8.0-generic")
+```
+
+See `tests/agent/test_prompt_builder.py::TestEnvironmentHints` for a worked example.
+
+### System prompt's execution-environment block
+
+Factual host/backend guidance (OS, `$HOME`, cwd, terminal backend, shell)
+is emitted by `agent/prompt_builder.py::build_environment_hints()`. The key
+invariant for prompt authors: with a **remote** terminal backend
+(`docker, singularity, modal, daytona, ssh, managed_modal`), host info is
+suppressed and *every* file tool runs inside the backend container — the
+prompt must never describe the host the agent can't touch.
+
+### Commit Conventions
+
+```
+type: concise subject line
+
+Optional body.
+```
+
+Types: `fix:`, `feat:`, `refactor:`, `docs:`, `chore:`
+
+### Key Rules
+
+- **Never break prompt caching** — don't change context, tools, or system prompt mid-conversation
+- **Message role alternation** — never two assistant or two user messages in a row
+- Use `get_hermes_home()` from `hermes_constants` for all paths (profile-safe)
+- Config values go in `config.yaml`, secrets go in `.env`
+- New tools need a `check_fn` so they only appear when requirements are met
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/delegate-task-concurrency-diagnosis.md b/skills/autonomous-ai-agents/hermes-agent/references/delegate-task-concurrency-diagnosis.md
new file mode 100644
index 00000000000..34851bb0ed5
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/delegate-task-concurrency-diagnosis.md
@@ -0,0 +1,99 @@
+# delegate_task: diagnosing "my batch was capped"
+
+When a user reports `delegate_task` ran fewer subagents than they asked for
+(e.g. "I set max_concurrent_children: 15 but only 9 ran"), there are exactly
+**three** code paths in Hermes that cap a batch. If none of them fired, the
+cap came from the **model itself** — not from Hermes — and the user's
+narration of "the runtime caps at N" is the model rationalising its own
+choice.
+
+## The three real caps in Hermes
+
+All resolved through `tools.delegate_tool._get_max_concurrent_children()`,
+which reads `delegation.max_concurrent_children` from `config.yaml`
+(env fallback `DELEGATION_MAX_CONCURRENT_CHILDREN`, default 3). Floor of 1.
+**No hard ceiling.**
+
+1. **Per-call hard reject** — `tools/delegate_tool.py` (~line 1953).
+   If `len(tasks) > max_children`, the call returns a `tool_error` with the
+   exact message: `"Too many tasks: {N} provided, but
+   max_concurrent_children is {M}. ..."` The model sees this as a failed
+   tool call and usually retries with fewer tasks.
+
+2. **Per-turn truncator** — `run_agent.py::AIAgent._cap_delegate_task_calls`
+   (~line 5708). If the model emits *multiple separate* `delegate_task`
+   tool_calls in a single assistant turn, the count of those calls is
+   truncated to `max_children`. Logs as
+   `Truncated N excess delegate_task call(s) to enforce
+   max_concurrent_children=M limit` at WARNING.
+
+3. **Cost-warning** — same `_get_max_concurrent_children()`. When the
+   resolved value is `> 10`, logs once at WARNING:
+   `delegation.max_concurrent_children=N: each child consumes API tokens
+   independently. High values multiply cost linearly.` This is **just a
+   log line** — it does not cap anything. Easy to mis-read as "Hermes is
+   refusing my value."
+
+## Diagnostic recipe
+
+When a user says "delegate is capped at N":
+
+```bash
+# 1. What does the loaded config actually say?
+hermes config get delegation.max_concurrent_children
+
+# 2. Did Hermes' truncator or rejector actually fire?
+grep -E "Truncated.*delegate_task|Too many tasks" ~/.hermes/logs/agent.log | tail
+# If neither line appears, neither cap path executed.
+
+# 3. Confirm the resolver returns what config says (in venv with hermes on path)
+python -c "from tools.delegate_tool import _get_max_concurrent_children; \
+           print(_get_max_concurrent_children())"
+```
+
+If config and `_get_max_concurrent_children()` agree, and neither log line
+appears, **the cap is the model**, not Hermes.
+
+## Why models self-limit batches
+
+Reasoning models (Claude Opus/Sonnet, GPT-5, Grok-4) routinely trim a
+13- or 15-task batch to a "rounder" number (5, 8, 9, 10) when their
+internal reasoning says the coordination cost outweighs parallelism. The
+cost-warning log line printed at startup *reinforces* this — the model
+reads its own reasoning trace and sees "each child consumes API tokens
+independently" and concludes a smaller batch is "more responsible."
+
+The model will then narrate the choice as "the runtime caps at 9" or
+"despite the config saying 15, max parallel is 9," which is **not true**
+— it's post-hoc rationalisation. Calling this out to the user is fine;
+it is a real, well-known reasoning-model failure mode (face-saving
+attribution to the system rather than admitting a self-imposed limit).
+
+## How to actually force N parallel children
+
+Tell the model explicitly in the prompt:
+
+> "Send all 13 tasks in **one** `delegate_task` call with a `tasks` array
+> of 13 items. Do not split into multiple calls. The runtime supports
+> this; `delegation.max_concurrent_children` is set to 15."
+
+If the model still trims, use `execute_code` to construct the `tasks`
+list deterministically and call the tool with that exact list — the
+model is then merely a courier and is far less likely to second-guess
+the count. Or use a different model: smaller / less-reasoning-heavy
+models trim less aggressively in practice.
+
+## Pitfalls / gotchas
+
+- **`max_concurrent_children` is a per-parent cap, not a global cap.**
+  Confirmed in `ui-tui/src/components/appChrome.tsx`. Two different
+  parents can each spawn `max_children` workers concurrently.
+- **`subagent_auto_approve: false` does not cap concurrency.** It only
+  controls whether children inherit yolo / approval bypass. Don't mistake
+  it for a throttle.
+- **The cost-warning log fires on every call** when the value is > 10.
+  Don't take its presence as evidence that anything was capped — only
+  the `Truncated...` and `Too many tasks` lines indicate actual capping.
+- **Don't suggest reverting `max_concurrent_children` to fix this.** The
+  user set it deliberately; the fix is to push back on the model, not
+  the config.
diff --git a/skills/hermes-desktop-plugins/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
similarity index 95%
rename from skills/hermes-desktop-plugins/SKILL.md
rename to skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
index 93b9853962e..3d7d5f2a925 100644
--- a/skills/hermes-desktop-plugins/SKILL.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
@@ -1,16 +1,4 @@
----
-name: hermes-desktop-plugins
-description: Write desktop app plugins that add UI panes and commands.
-version: 1.0.0
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [desktop, plugins, ui, extension]
-    category: productivity
-    related_skills: []
----
-
-# Hermes Desktop Plugins Skill
+# Desktop App Plugins — UI Panes, Commands, Widgets
 
 Write plugins for the Hermes desktop app: statusbar items, layout panes,
 command-palette commands, keybinds, routes, and themes. A plugin is a single
@@ -37,7 +25,7 @@ Full human reference (every export, area payloads, backend, security):
 ## How to Run
 
 1. Create `$HERMES_HOME/desktop-plugins/<name>/plugin.js` from
-   `templates/plugin.js` (relative to this skill directory) — that's
+   `templates/plugin.js` (in this skill directory) — that's
    `~/.hermes/...` by default, or `~/.hermes/profiles/<profile>/...` under a
    named profile. Keep `<name>` equal to the plugin `id`.
 2. The desktop app watches that directory: the plugin loads within a few
diff --git a/skills/productivity/petdex/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/references/petdex.md
similarity index 90%
rename from skills/productivity/petdex/SKILL.md
rename to skills/autonomous-ai-agents/hermes-agent/references/petdex.md
index 416e0c6c2ca..4fc564f240a 100644
--- a/skills/productivity/petdex/SKILL.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/petdex.md
@@ -1,18 +1,4 @@
----
-name: petdex
-description: Install and select animated petdex mascots for Hermes.
-version: 1.0.0
-author: Hermes Agent
-license: MIT
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [petdex, mascot, display, cli, tui, desktop]
-    category: productivity
-    homepage: https://petdex.dev
----
-
-# Petdex Skill
+# Petdex — Animated Pet Mascots
 
 Browse, install, and select animated "pet" mascots from the public
 [petdex](https://github.com/crafter-station/petdex) gallery. An installed pet
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/portal-auth-for-third-party-apps.md b/skills/autonomous-ai-agents/hermes-agent/references/portal-auth-for-third-party-apps.md
new file mode 100644
index 00000000000..b75f1019868
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/portal-auth-for-third-party-apps.md
@@ -0,0 +1,128 @@
+# Nous Portal — authenticating third-party apps against the subscription
+
+Recurring user question: "Can app X (Karakeep, OpenWebUI, LibreChat, OpenViking,
+LangChain pipeline, n8n flow, etc.) use my Nous Portal subscription without me
+copy-pasting an API key — ideally via the Portal login I already have?"
+
+The honest answer has three architectural layers people conflate. Walk through
+them in order before proposing solutions.
+
+---
+
+## Layer 1 — Is this thing a Hermes plugin, or a separate app?
+
+This is the question to answer FIRST. The "OpenViking" case in particular
+trips agents up.
+
+| Surface | What it actually is | Auth path |
+|---|---|---|
+| **OpenViking memory plugin** (`plugins/memory/openviking/`) | Code that runs **inside the Hermes process**. Its LLM calls go through Hermes's already-configured provider. | Already uses Portal if user's Hermes is configured for Portal. Nothing extra needed. `OPENVIKING_API_KEY` is the OpenViking *server's* own auth, not LLM auth. |
+| **OpenViking the standalone server** (separate container) | A separate context-DB service. If it ever calls an LLM on its own, that's a separate HTTP client. | Same as any external app — Layer 2/3 below. |
+| **Karakeep, n8n, LibreChat, OpenWebUI, any self-hosted app** | Different process, often different machine. Makes its own HTTPS calls to `inference-api.nousresearch.com`. | Layer 2/3 below. |
+
+**Pitfall to avoid**: do not pitch "OAuth into Portal" as the solution for a
+plugin that already runs inside Hermes. That LLM call is already authenticated
+via Hermes's provider config. The plugin's own server auth (e.g.
+`OPENVIKING_API_KEY` for talking to the OpenViking REST API) is unrelated to
+Portal.
+
+---
+
+## Layer 2 — For genuinely external apps, what does Portal actually expose?
+
+Portal at `https://inference-api.nousresearch.com/v1` is an OpenAI-compatible
+inference endpoint. It accepts **bearer-token authentication only**: either
+
+1. **A static API key** from `portal.nousresearch.com → API Keys`, or
+2. **An x402-protocol payment header** (Solana USDC, beta, anonymous, per-request).
+
+There is **no general OAuth 2.0 authorization server**. There is no
+"Sign in with Nous Portal" SSO that third-party apps can register as clients
+against. There is no shared cookie or session that browser-Portal-login
+extends to other apps on the same machine.
+
+What Hermes Agent has that *feels* like OAuth — `hermes login --provider nous`
+opening a browser, user signs in, token lands in `~/.hermes/auth.json` — is a
+**Hermes-specific browser flow**. Under the hood it produces a credential
+Hermes uses as a bearer. It is not a public OAuth provider that Karakeep et al.
+can implement a client for, because it isn't an OAuth provider at all from the
+outside.
+
+---
+
+## Layer 3 — Can we bridge the gap without Portal changing anything?
+
+Yes. The pattern is a **local credential-broker proxy**. Even without a public
+OAuth flow, an app on the user's machine can:
+
+1. Read Hermes's existing Portal credential out of `~/.hermes/auth.json`.
+2. Expose a local OpenAI-compatible endpoint at `http://localhost:NNNN/v1`.
+3. Forward incoming requests to `inference-api.nousresearch.com/v1` with that
+   bearer attached.
+
+Karakeep/OpenWebUI/etc. then point at `http://localhost:NNNN/v1` with any
+placeholder key. The user never copies their Portal key around — the proxy
+rides on the credential Hermes already holds.
+
+Where this could live in Hermes:
+
+- `gateway/platforms/api_server.py` is the precedent — it exposes the agent
+  over a local OpenAI-compatible endpoint, but routes through the full agent
+  loop (tool calls and all). The proxy variant is **pure inference
+  pass-through**: no agent loop, no tools, just forward `/chat/completions`
+  upstream with the user's stored Portal bearer.
+- ~150 lines as a new gateway adapter or a plugin under `plugins/`.
+- Token refresh: if the browser-OAuth flow produces a refreshable token, the
+  credential pool's refresh logic already exists. If it's a long-lived static
+  bearer, even simpler.
+
+This is genuinely useful and worth shipping — it's the answer to "use my
+Portal sub with $external_app without copy-pasting keys."
+
+---
+
+## Real OAuth provider on Portal — when is it worth pitching?
+
+Only when the consumer is *another first-party Nous thing* (a future SDK, a
+Nous-branded extension, a Discord-bot integration that needs per-user
+delegation, etc.). Pitching it as the answer to "use my Portal sub with
+Karakeep" is selling the user a thing that won't reach them: even if Portal
+shipped OAuth tomorrow, Karakeep's LLM-provider config UI is `base_url +
+bearer_token` with no OAuth client, no callback handler, no token refresh.
+The OpenAI ecosystem standardized on static bearers and downstream apps
+won't rebuild their config UX to accommodate a new auth flow.
+
+The features that would actually help users today, and that Portal could ship
+without depending on third-party app changes:
+
+- **Scoped, named, revocable API keys** with last-used timestamps. Same UX
+  benefits people want from OAuth (revoke a compromised key, see what's using
+  the sub, scope a key to specific models), in a shape every existing app
+  already supports.
+- **Per-key rate limits** so a noisy app can be capped without eating the
+  user's headroom for Hermes itself.
+
+---
+
+## Talking-points cheatsheet (for next time)
+
+When the user asks "can $APP use my Portal subscription":
+
+1. First decide: Hermes plugin (runs inside Hermes) or separate app? If plugin,
+   it already uses Portal via Hermes's provider config — done.
+2. If separate app: today, paste the static API key from Portal → API Keys.
+   Base URL `https://inference-api.nousresearch.com/v1`. Rate limits are
+   subscription-tier based, applied per-key.
+3. If the user pushes back with "but I don't want to paste a key" — that's
+   the local-broker-proxy answer (Layer 3). Worth building. Not a Portal-side
+   OAuth roadmap problem.
+4. Mixed setup ("Portal for some things, OpenRouter/Ollama Cloud for the
+   Hermes agent itself") is fully supported. Hermes treats agent
+   provider/model and tool-side LLM calls as independent config; you can
+   point each at a different endpoint.
+
+**Note on the Tool Gateway**: the "no separate accounts, no API key juggling"
+pitch in the Tool Gateway announcement is specifically about Hermes Agent's
+*tools* (web search, browser, image gen, TTS) flowing through the Portal
+subscription when Hermes is configured to use Portal as its provider. It is
+**not** a claim that arbitrary third-party apps inherit Portal auth.
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/project-context-files.md b/skills/autonomous-ai-agents/hermes-agent/references/project-context-files.md
new file mode 100644
index 00000000000..7a6d8ee1907
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/project-context-files.md
@@ -0,0 +1,48 @@
+# Project Context Files
+
+Hermes injects project-level instructions into the system prompt by reading context files from the working directory. The discovery order is **first match wins** — only one project context source is loaded per session.
+
+| File (in priority order) | Discovery | Use when |
+|---|---|---|
+| `.hermes.md` / `HERMES.md` | Walks parents up to the git root, stops at git root | You want hierarchical project rules (root + per-package overrides) |
+| `AGENTS.md` / `agents.md` | **Cwd only** — subdirectory and parent copies are ignored | You want portable agent instructions that work the same in Hermes, Claude Code, Codex, etc. |
+| `CLAUDE.md` / `claude.md` | Cwd only | Same as AGENTS.md, Claude-flavored |
+| `.cursorrules` / `.cursor/rules/*.mdc` | Cwd only | Migrating from Cursor |
+
+`SOUL.md` (in `$HERMES_HOME`) is independent and always loaded when present — it sets the agent's identity, not project rules.
+
+### Pick the right one
+
+- **Use `.hermes.md`** when you want Hermes-specific behavior that lives above the cwd (root + subtree), or when you want rules to inherit from a parent directory. The parent walk stops at the git root, so a home-level `.hermes.md` won't leak into every project (a git repo's root is the boundary).
+- **Use `AGENTS.md`** when the same project will also be worked on by other agents (Codex, Claude Code, OpenCode). Those tools all have their own conventions for `AGENTS.md`, and the "cwd only" contract keeps the file portable.
+- **Don't put project rules in `~/.hermes/AGENTS.md`** (or any other home-level location). When Hermes runs with that directory as cwd, the file loads — but only for that one directory. For cross-project context, use `SOUL.md` (in `$HERMES_HOME`, identity-only) or install a skill via `hermes skills install`.
+
+### Size and truncation
+
+Each context file is capped at 20,000 characters. Files longer than that get **head + tail** truncated (the middle is dropped, with a `[...truncated...]` marker). For large project rules, prefer splitting into multiple skills over cramming one file.
+
+### Security
+
+All context files pass through the threat-pattern scanner before reaching the system prompt. Patterns matching prompt injection or promptware are replaced with a `[BLOCKED: ...]` placeholder. This means an `AGENTS.md` containing obvious injection attempts won't reach the model — the scanner blocks the content, not the file, so the rest of the file still loads.
+
+### Disable for one session
+
+`hermes --ignore-rules` skips auto-injection of all project context files (`.hermes.md`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`) **and** `SOUL.md` identity, plus user config, plugins, and MCP servers. Use it to isolate whether a problem is your setup or Hermes itself.
+
+### Example: a small `.hermes.md`
+
+```markdown
+# My Project
+
+Hermes: when working in this repo, follow these rules.
+
+## Build
+- Always run `make test` before declaring a change done.
+- Use `uv run` for Python, not `pip install`.
+
+## Style
+- Prefer `pathlib.Path` over `os.path`.
+- No `print()` in production code — use the `logger`.
+```
+
+That file at `/home/me/projects/myrepo/.hermes.md` is auto-loaded when Hermes runs in any subdirectory of `/home/me/projects/myrepo`, but not when it runs in `/home/me/other-project`.
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/providers-and-models.md b/skills/autonomous-ai-agents/hermes-agent/references/providers-and-models.md
new file mode 100644
index 00000000000..bd8d7ed6be8
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/providers-and-models.md
@@ -0,0 +1,64 @@
+# Providers & Model Aliases
+
+Set via `hermes model` (picker) or `hermes setup`. 35+ provider profiles ship as
+plugins under `plugins/model-providers/`; user plugins of the same name override.
+Full docs: https://hermes-agent.nousresearch.com/docs/integrations/providers
+
+### Providers
+
+| Provider | Auth | Key env var(s) |
+|----------|------|----------------|
+| openrouter | API key | `OPENROUTER_API_KEY` |
+| anthropic | API key | `ANTHROPIC_API_KEY` (also `CLAUDE_CODE_OAUTH_TOKEN`) |
+| nous | OAuth device code | `hermes auth add nous` (or `NOUS_API_KEY`) |
+| openai-codex | OAuth | `hermes auth add openai-codex` |
+| qwen-oauth | OAuth | `hermes auth add qwen-oauth` |
+| minimax-oauth | OAuth | `hermes auth add minimax-oauth` |
+| copilot | Token | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` (Copilot device flow — `gh auth login` tokens do NOT work) |
+| copilot-acp | External CLI | Copilot CLI on PATH or `COPILOT_CLI_PATH` |
+| gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
+| xai | API key | `XAI_API_KEY` (SuperGrok OAuth also supported) |
+| deepseek | API key | `DEEPSEEK_API_KEY` |
+| zai (GLM) | API key | `GLM_API_KEY` / `ZAI_API_KEY` |
+| minimax / minimax-cn | API key | `MINIMAX_API_KEY` / `MINIMAX_CN_API_KEY` |
+| kimi-coding / -cn | API key | `KIMI_API_KEY` / `KIMI_CN_API_KEY` |
+| alibaba (+coding-plan) | API key | `DASHSCOPE_API_KEY` / `ALIBABA_CODING_PLAN_API_KEY` |
+| xiaomi | API key | `XIAOMI_API_KEY` |
+| huggingface | Token | `HF_TOKEN` |
+| fireworks / novita / nvidia / deepinfra / gmi / arcee / stepfun / upstage / kilocode / opencode-zen / opencode-go / ollama-cloud | API key | `<NAME>_API_KEY` |
+| bedrock / vertex / azure-foundry | Cloud SDK / key | AWS SDK creds / Vertex ADC / `AZURE_FOUNDRY_API_KEY` |
+| custom | Config | `model.base_url` + `model.api_key` in config.yaml |
+
+Multiple credentials per provider pool and rotate automatically (`hermes auth`).
+Fallback chain when the primary fails: `hermes fallback add|remove|list`.
+
+### User-defined model aliases
+
+Work with `/model <name>` in CLI and every gateway platform. Resolved by
+`hermes_cli/model_switch.py::resolve_alias()`; user aliases are checked BEFORE
+the built-in table, so a user `sonnet`/`grok` shadows the built-in.
+
+```yaml
+# Full form
+model_aliases:
+  fav:
+    model: claude-sonnet-4.6
+    provider: anthropic
+  local-qwen:
+    model: qwen3.5:397b
+    provider: custom
+    base_url: "https://ollama.com/v1"
+
+# Short form ("provider/model"), also via CLI:
+#   hermes config set model.aliases.fav openrouter/anthropic/claude-sonnet-4.6
+model:
+  aliases:
+    fav: openrouter/anthropic/claude-sonnet-4.6
+```
+
+`/model fav` — session-scoped; add `--global` to persist as default.
+
+Built-in aliases (catalog-resolved against the active provider): `sonnet`,
+`opus`, `haiku`, `claude`, `gpt5`, `gpt`, `codex`, `o3`, `o4`, `gemini`,
+`deepseek`, `grok`, `llama`, `qwen`, `minimax`, `nemotron`, `kimi`, `glm`,
+`step`, `mimo`, `trinity`.
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/security-privacy.md b/skills/autonomous-ai-agents/hermes-agent/references/security-privacy.md
new file mode 100644
index 00000000000..4465fef93a2
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/security-privacy.md
@@ -0,0 +1,67 @@
+# Security & Privacy Toggles
+
+Common "why is Hermes doing X to my output / tool calls / commands?" toggles — and the exact commands to change them. Most of these need a fresh session (`/reset` in chat, or start a new `hermes` invocation) because they're read once at startup.
+
+### Secret redaction in tool output
+
+Secret redaction is **on by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) is scanned for strings that look like API keys, tokens, and secrets before it enters the conversation context and logs. Leave it enabled for normal use:
+
+```bash
+hermes config set security.redact_secrets true       # keep enabled globally
+```
+
+**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=false` from a tool call) will NOT take effect for the running process. Tell the user to change it in config from a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task.
+
+Disable only when you deliberately need raw credential-like strings for debugging or redactor development:
+```bash
+hermes config set security.redact_secrets false
+```
+
+### PII redaction in gateway messages
+
+Separate from secret redaction. When enabled, the gateway hashes user IDs and strips phone numbers from the session context before it reaches the model:
+
+```bash
+hermes config set privacy.redact_pii true    # enable
+hermes config set privacy.redact_pii false   # disable (default)
+```
+
+### Command approval prompts
+
+By default (`approvals.mode: smart`), Hermes asks an auxiliary LLM to assess shell commands flagged as destructive (`rm -rf`, `git reset --hard`, etc.). The modes are:
+
+- `smart` — auto-approve a low-risk command once, deny high-risk commands, and prompt when uncertain (default)
+- `manual` — always prompt
+- `off` — skip all approval prompts (equivalent to `--yolo`)
+
+```bash
+hermes config set approvals.mode smart       # recommended middle ground
+hermes config set approvals.mode off         # bypass everything (not recommended)
+```
+
+Per-invocation bypass without changing config:
+- `hermes --yolo …`
+- `export HERMES_YOLO_MODE=1`
+
+Note: YOLO / `approvals.mode: off` does NOT turn off secret redaction. They are independent.
+
+### "Reset permissions" / "make Hermes ask again"
+
+The user usually means: wipe the accumulated "Always allow" state — NOT yolo
+mode, and NOT a per-edit diff prompt (which doesn't exist; file writes never
+go through the approval prompt, only shell commands do). Two stores hold it:
+
+1. Shell-command allowlist: `hermes config set command_allowlist '[]'`
+2. Shell-hook consent (only if present): `rm -f ~/.hermes/shell-hooks-allowlist.json`
+
+Then sanity-check `hermes config get approvals.mode` (should not be `off`)
+and confirm `--yolo` isn't baked into their launch alias or systemd unit.
+
+### Shell hooks allowlist
+
+Some shell-hook integrations require explicit allowlisting before they fire. Managed via `~/.hermes/shell-hooks-allowlist.json` — prompted interactively the first time a hook wants to run.
+
+### Disabling the web/browser/image-gen tools
+
+To keep the model away from network or media tools entirely, open `hermes tools` and toggle per-platform. Takes effect on next session (`/reset`). See `references/configuration.md` for the toolset list.
+
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/slash-commands.md b/skills/autonomous-ai-agents/hermes-agent/references/slash-commands.md
new file mode 100644
index 00000000000..ec198279209
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/slash-commands.md
@@ -0,0 +1,110 @@
+# Slash Commands (In-Session)
+
+Registry of record: `hermes_cli/commands.py` (`COMMAND_REGISTRY`) — every
+consumer (autocomplete, `/help`, Telegram menu, Slack mapping) derives from
+it. New commands land often; `/help` in-session is always authoritative.
+(CLI) = interactive CLI/TUI only. (GW) = gateway platforms only.
+
+### Session
+```
+/new (/reset) [name]     Fresh session
+/clear                   Clear screen + new session (CLI)
+/retry                   Resend last message
+/undo [N]                Back up N user turns and re-prompt
+/title [name]            Name the session
+/prompt (/compose)       Compose next prompt in $EDITOR (CLI)
+/compress (/compact)     Compress context ('here [N]' keeps N turns; --preview)
+/stop                    Kill background processes
+/rollback [N]            List/restore filesystem checkpoints
+/snapshot [sub]          Create/restore Hermes config+state snapshots (CLI)
+/background (/bg) <p>    Run prompt in background
+/queue (/q) <prompt>     Queue prompt for next turn
+/steer <prompt>          Inject a message after the next tool call
+/agents (/tasks)         Show active agents and running tasks
+/goal [text|sub]         Standing goal across turns (status|pause|resume|clear)
+/subgoal [text]          Add/manage criteria on the active goal
+/branch (/fork) [name]   Branch the session
+/resume [name]           Resume a named session
+/sessions                Browse and resume previous sessions
+/handoff <platform>      Hand live session off to a messaging platform (CLI)
+/status                  Session, model, token, and context info
+/redraw                  Force full UI repaint (CLI)
+```
+
+### Configuration
+```
+/config                  Show config (CLI)
+/model [name] [--global] Switch model (session-scoped by default)
+/personality [name]      Set a personality
+/reasoning [level|show|hide] Reasoning effort/display (none..xhigh|max|ultra)
+/fast [normal|fast]      Priority/fast processing tier
+/verbose                 Cycle tool progress: off → new → all → verbose → log (CLI)
+/voice [on|off|tts]      Voice mode
+/yolo                    Toggle approval bypass
+/busy [queue|steer|interrupt] What Enter does while working (CLI)
+/indicator [style]       TUI busy indicator: kaomoji|emoji|unicode|ascii (CLI)
+/footer [on|off]         Gateway runtime-metadata footer on replies
+/skin [name]             Change theme (CLI)
+/statusbar (/sb)         Toggle status bar (CLI)
+/battery [on|off]        Battery indicator in status bar (CLI)
+/timestamps (/ts) [on|off] Message timestamps (CLI)
+/codex-runtime [auto|codex_app_server] Codex runtime toggle
+```
+
+### Tools & Skills
+```
+/tools [list|enable|disable] Manage tools (CLI)
+/toolsets                List toolsets (CLI)
+/skills                  Search/install/manage skills (CLI)
+/bundles                 List skill bundles (/<name> loads several skills)
+/learn <source>          Learn a reusable skill from dirs/URLs/this chat
+/memory [pending|approve|reject] Review pending memory writes / approval gate
+/pet [toggle|list|<slug>] Petdex mascot control (CLI)
+/hatch [description]     Generate a new pet from a description (CLI)
+/cron [sub]              Manage scheduled tasks (CLI)
+/suggestions (/suggest)  Review suggested automations
+/blueprint (/bp) [name]  Set up an automation from a blueprint
+/curator [sub]           Skill maintenance (status, run, pin, archive, …)
+/kanban [sub]            Multi-profile collaboration board
+/moa <prompt>            One prompt through the Mixture-of-Agents preset
+/reload                  Reload .env into the running session (CLI)
+/reload-mcp              Reload MCP servers
+/reload-skills           Re-scan skills directory
+/browser [connect|status] CDP connection to your live browser (CLI)
+/plugins                 List plugins (CLI)
+```
+
+### Gateway
+```
+/approve [session|always]  Approve a pending dangerous command (GW)
+/deny [all] [reason]       Deny a pending dangerous command (GW)
+/restart                   Restart gateway after draining active runs (GW)
+/sethome                   Set current chat as home channel (GW)
+/topic [off|help]          Telegram DM topic sessions (GW)
+/platform <pause|resume|list> Pause/resume a failing platform (GW)
+/commands [page]           Browse all commands, paginated (GW)
+```
+
+### Info
+```
+/help                    Show commands
+/usage [reset]           Token usage and rate limits
+/insights [days]         Usage analytics
+/whoami                  Slash-command access level (admin/user)
+/profile                 Active profile info
+/platforms (/gateway)    Platform connection status (CLI)
+/journey (/learning)     Learned skills + memories timeline (CLI)
+/subscription (/upgrade) Nous plan info (CLI)
+/topup                   Nous balance / billing
+/copy [N]                Copy last response to clipboard (CLI)
+/paste                   Attach clipboard image (CLI)
+/image <path>            Attach a local image file (CLI)
+/update                  Update Hermes to latest
+/version (/v)            Show version
+/debug [nous|local]      Upload debug report, get shareable links
+```
+
+### Exit
+```
+/quit (/exit) [--delete] Exit CLI; --delete also removes session history
+```
diff --git a/skills/hermes-themes/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/references/themes.md
similarity index 96%
rename from skills/hermes-themes/SKILL.md
rename to skills/autonomous-ai-agents/hermes-agent/references/themes.md
index 15982af0c8f..b4ded40cb0c 100644
--- a/skills/hermes-themes/SKILL.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/themes.md
@@ -1,15 +1,4 @@
----
-name: hermes-themes
-description: "Author a Hermes color theme that skins every surface."
-version: 1.0.0
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [theme, skin, appearance, cli, tui, desktop, self-config]
-    related_skills: []
----
-
-# Hermes Themes Skill
+# Themes / Skins — Author a Hermes Color Theme
 
 Author a Hermes **skin** — one YAML file that themes the CLI, the TUI, and the
 desktop GUI at once. The skin engine (`hermes_cli/skin_engine.py`) resolves the
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md b/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md
new file mode 100644
index 00000000000..aedf0e219fc
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md
@@ -0,0 +1,54 @@
+# Troubleshooting
+
+### Voice not working
+1. Check `stt.enabled: true` in config.yaml
+2. Verify provider: `pip install faster-whisper` or set API key
+3. In gateway: `/restart`. In CLI: exit and relaunch.
+
+### Tool not available
+1. `hermes tools` — check if toolset is enabled for your platform
+2. Some tools need env vars (check `.env`)
+3. `/reset` after enabling tools
+
+### Model/provider issues
+1. `hermes doctor` — check config and dependencies
+2. `hermes auth` — re-authenticate OAuth providers (or `hermes auth add <provider>`)
+3. Check `.env` has the right API key
+4. **Copilot 403**: `gh auth login` tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via `hermes model` → GitHub Copilot.
+
+### Changes not taking effect
+- **Tools/skills:** `/reset` starts a new session with updated toolset
+- **Config changes:** In gateway: `/restart`. In CLI: exit and relaunch.
+- **Code changes:** Restart the CLI or gateway process
+
+### Skills not showing
+1. `hermes skills list` — verify installed
+2. `hermes skills config` — check platform enablement
+3. Load explicitly: `hermes -s name` (or the skill's own `/<name>` slash command)
+
+### Gateway issues
+Check logs first:
+```bash
+grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20
+```
+
+Common gateway problems:
+- **Gateway dies on SSH logout**: Enable linger: `sudo loginctl enable-linger $USER`
+- **Gateway dies on WSL2 close**: WSL2 requires `systemd=true` in `/etc/wsl.conf` for systemd services to work. Without it, gateway falls back to `nohup` (dies when session closes).
+- **Gateway crash loop**: Reset the failed state: `systemctl --user reset-failed hermes-gateway`
+
+### Platform-specific issues
+- **Discord bot silent**: Must enable **Message Content Intent** in Bot → Privileged Gateway Intents.
+- **Slack bot only works in DMs**: Must subscribe to `message.channels` event. Without it, the bot ignores public channels.
+- **Windows-specific issues** (`Alt+Enter` newline, WinError 10106, UTF-8 BOM config, line endings): see `references/windows-quirks.md`.
+
+### Auxiliary models not working
+If `auxiliary` tasks (vision, compression, session_search) fail silently, the `auto` provider can't find a backend. Either set `OPENROUTER_API_KEY` or `GOOGLE_API_KEY`, or explicitly configure each auxiliary task's provider:
+```bash
+hermes config set auxiliary.vision.provider <your_provider>
+hermes config set auxiliary.vision.model <model_name>
+```
+
+### "Reset permissions" / auto-approving everything
+See `references/security-privacy.md` — wipe the "Always allow" stores, don't touch yolo mode.
+
diff --git a/skills/productivity/tui-widgets/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/references/tui-widgets.md
similarity index 96%
rename from skills/productivity/tui-widgets/SKILL.md
rename to skills/autonomous-ai-agents/hermes-agent/references/tui-widgets.md
index 796f12a370e..c9eb6717f05 100644
--- a/skills/productivity/tui-widgets/SKILL.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/tui-widgets.md
@@ -1,16 +1,4 @@
----
-name: tui-widgets
-description: Author live widget apps for the Hermes TUI dock.
-version: 1.0.0
-author: Hermes Agent
-license: MIT
-metadata:
-  hermes:
-    tags: [tui, widgets, sdk, ui]
-    category: productivity
----
-
-# TUI Widgets Skill
+# TUI Widgets — Live Panels for the Ink TUI Dock
 
 Author widget apps for the Hermes TUI (`hermes --tui`): glanceable ambient
 panels docked above the status bar, or modal overlays that own the keyboard.
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/windows-quirks.md b/skills/autonomous-ai-agents/hermes-agent/references/windows-quirks.md
new file mode 100644
index 00000000000..4cf283e9533
--- /dev/null
+++ b/skills/autonomous-ai-agents/hermes-agent/references/windows-quirks.md
@@ -0,0 +1,57 @@
+# Windows-Specific Quirks
+
+Hermes runs natively on Windows (PowerShell, cmd, Windows Terminal, git-bash
+mintty, VS Code integrated terminal). Most of it just works, but a handful
+of differences between Win32 and POSIX have bitten us — document new ones
+here as you hit them so the next person (or the next session) doesn't
+rediscover them from scratch.
+
+### Input / Keybindings
+
+**Alt+Enter doesn't insert a newline** — Windows Terminal (and mintty) grab it
+for fullscreen before prompt_toolkit sees it. Use **Ctrl+Enter** instead (the
+CLI binds it to newline on Windows; raw Ctrl+J does the same, harmlessly).
+To inspect how your terminal reports a keystroke, run
+`python scripts/keystroke_diagnostic.py` from the repo root.
+
+### Config / Files
+
+**HTTP 400 "No models provided" on first run** — `config.yaml` was saved with
+a UTF-8 BOM (Notepad does this). Re-save as UTF-8 without BOM;
+`hermes config edit` writes correctly.
+
+### `execute_code` / Sandbox
+
+**WinError 10106** from the sandbox child process — it can't create an
+`AF_INET` socket. Root cause is usually Hermes's env scrubber dropping
+`SYSTEMROOT`/`WINDIR`/`COMSPEC` (Python's `socket` needs `SYSTEMROOT` to find
+`mswsock.dll`), not a broken Winsock LSP. The `_WINDOWS_ESSENTIAL_ENV_VARS`
+allowlist in `tools/code_execution_tool.py` covers it; if you still hit it,
+echo `os.environ` inside an `execute_code` block to confirm `SYSTEMROOT` is set.
+
+### Testing on Windows
+
+`scripts/run_tests.sh` is POSIX-only (expects `.venv/bin/activate`); the
+Hermes-installed `venv/Scripts/` has no pip/pytest (stripped for size).
+Install pytest into a system Python and run directly with `-n 0`
+(`pyproject.toml`'s `addopts` already sets `-n`):
+
+```bash
+"/c/Program Files/Python311/python" -m pip install --user pytest pytest-xdist pyyaml
+export PYTHONPATH="$(pwd)"
+"/c/Program Files/Python311/python" -m pytest tests/foo/test_bar.py -v --tb=short -n 0
+```
+
+(POSIX-only tests need skip guards — see the cross-platform guard list in
+`references/contributor-guide.md`.)
+
+### Path / Filesystem
+
+**Line endings.** Git may warn `LF will be replaced by CRLF`. Cosmetic — the
+repo's `.gitattributes` normalizes. Don't let editors auto-convert committed
+POSIX-newline files to CRLF.
+
+**Forward slashes work almost everywhere.** `C:/Users/...` is accepted by
+every Hermes tool and most Windows APIs. Prefer forward slashes in code
+and logs — avoids shell-escaping backslashes in bash.
+
diff --git a/skills/productivity/tui-widgets/templates/clock.mjs b/skills/autonomous-ai-agents/hermes-agent/templates/clock.mjs
similarity index 100%
rename from skills/productivity/tui-widgets/templates/clock.mjs
rename to skills/autonomous-ai-agents/hermes-agent/templates/clock.mjs
diff --git a/skills/hermes-desktop-plugins/templates/plugin.js b/skills/autonomous-ai-agents/hermes-agent/templates/plugin.js
similarity index 100%
rename from skills/hermes-desktop-plugins/templates/plugin.js
rename to skills/autonomous-ai-agents/hermes-agent/templates/plugin.js
diff --git a/skills/hermes-themes/templates/skin.yaml b/skills/autonomous-ai-agents/hermes-agent/templates/skin.yaml
similarity index 100%
rename from skills/hermes-themes/templates/skin.yaml
rename to skills/autonomous-ai-agents/hermes-agent/templates/skin.yaml
diff --git a/skills/creative/comfyui/SKILL.md b/skills/creative/comfyui/SKILL.md
index e5a8a7c0745..0cfd457a47e 100644
--- a/skills/creative/comfyui/SKILL.md
+++ b/skills/creative/comfyui/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: comfyui
-description: "Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST/WebSocket API for execution."
+description: Generate images, video, and audio via diffusion workflows.
 version: 5.1.0
 author: [kshitijk4poor, alt-glitch, purzbeats]
 license: MIT
@@ -23,7 +23,7 @@ metadata:
       - creative
       - generative-ai
       - video-generation
-    related_skills: [stable-diffusion-image-generation, image_gen]
+    related_skills: [stable-diffusion-image-generation]
     category: creative
 ---
 
diff --git a/skills/creative/comfyui/scripts/auto_fix_deps.py b/skills/creative/comfyui/scripts/auto_fix_deps.py
index 788bf8e9e3b..58cce00c72e 100755
--- a/skills/creative/comfyui/scripts/auto_fix_deps.py
+++ b/skills/creative/comfyui/scripts/auto_fix_deps.py
@@ -51,7 +51,7 @@ def run_cmd(cmd: list[str], *, dry_run: bool = False) -> tuple[int, str]:
     if dry_run:
         return 0, "[dry-run]"
     log(f"$ {' '.join(cmd)}")
-    proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    proc = subprocess.run(cmd, capture_output=True, text=True, encoding='utf-8', errors='replace', check=False)
     out = (proc.stdout or "") + (proc.stderr or "")
     return proc.returncode, out
 
@@ -158,7 +158,7 @@ def main(argv: list[str] | None = None) -> int:
     sources: dict[str, str] = {}
     if args.models_from_file:
         try:
-            sources = json.loads(Path(args.models_from_file).read_text())
+            sources = json.loads(Path(args.models_from_file).read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError) as e:
             log(f"Could not read --models-from-file: {e}")
 
diff --git a/skills/creative/comfyui/scripts/extract_schema.py b/skills/creative/comfyui/scripts/extract_schema.py
index 0eab65b20fd..82f6eac7046 100755
--- a/skills/creative/comfyui/scripts/extract_schema.py
+++ b/skills/creative/comfyui/scripts/extract_schema.py
@@ -303,7 +303,7 @@ def main(argv: list[str] | None = None) -> int:
         out = json.dumps(schema, indent=2, default=str)
 
     if args.output:
-        Path(args.output).write_text(out)
+        Path(args.output).write_text(out, encoding="utf-8")
         print(f"Schema written to {args.output}", file=sys.stderr)
     else:
         print(out)
diff --git a/skills/creative/comfyui/scripts/hardware_check.py b/skills/creative/comfyui/scripts/hardware_check.py
index 083d018acc6..a89b66dc685 100755
--- a/skills/creative/comfyui/scripts/hardware_check.py
+++ b/skills/creative/comfyui/scripts/hardware_check.py
@@ -54,7 +54,7 @@ _COMFY_CLI_FLAG = {
 def _run(cmd: list[str], timeout: int = 8) -> str:
     try:
         out = subprocess.run(
-            cmd, capture_output=True, text=True, timeout=timeout, check=False
+            cmd, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=timeout, check=False
         )
         return (out.stdout or "") + (out.stderr or "")
     except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
diff --git a/skills/creative/comfyui/scripts/run_workflow.py b/skills/creative/comfyui/scripts/run_workflow.py
index 05afb1e319f..9b08ec0e570 100755
--- a/skills/creative/comfyui/scripts/run_workflow.py
+++ b/skills/creative/comfyui/scripts/run_workflow.py
@@ -620,7 +620,7 @@ def main(argv: list[str] | None = None) -> int:
     args_str = args.args
     if args_str.startswith("@"):
         try:
-            args_str = Path(args_str[1:]).read_text()
+            args_str = Path(args_str[1:]).read_text(encoding="utf-8")
         except OSError as e:
             emit_json({"error": f"Cannot read args file: {e}"})
             return 1
diff --git a/skills/creative/comfyui/tests/conftest.py b/skills/creative/comfyui/tests/conftest.py
index a800fa79f1b..7014edd7d55 100644
--- a/skills/creative/comfyui/tests/conftest.py
+++ b/skills/creative/comfyui/tests/conftest.py
@@ -22,17 +22,17 @@ sys.path.insert(0, str(SCRIPTS))
 
 @pytest.fixture
 def sd15_workflow() -> dict:
-    return json.loads((WORKFLOWS / "sd15_txt2img.json").read_text())
+    return json.loads((WORKFLOWS / "sd15_txt2img.json").read_text(encoding="utf-8"))
 
 
 @pytest.fixture
 def flux_workflow() -> dict:
-    return json.loads((WORKFLOWS / "flux_dev_txt2img.json").read_text())
+    return json.loads((WORKFLOWS / "flux_dev_txt2img.json").read_text(encoding="utf-8"))
 
 
 @pytest.fixture
 def video_workflow() -> dict:
-    return json.loads((WORKFLOWS / "wan_video_t2v.json").read_text())
+    return json.loads((WORKFLOWS / "wan_video_t2v.json").read_text(encoding="utf-8"))
 
 
 @pytest.fixture
diff --git a/skills/creative/comfyui/tests/test_common.py b/skills/creative/comfyui/tests/test_common.py
index a5ce6a32714..2c6afdbfc96 100644
--- a/skills/creative/comfyui/tests/test_common.py
+++ b/skills/creative/comfyui/tests/test_common.py
@@ -436,7 +436,7 @@ class TestVideoWorkflow:
 
     def test_animatediff_workflow(self, workflows_dir):
         import json
-        wf = json.loads((workflows_dir / "animatediff_video.json").read_text())
+        wf = json.loads((workflows_dir / "animatediff_video.json").read_text(encoding="utf-8"))
         assert looks_like_video_workflow(wf) is True
 
     def test_wan_workflow(self, video_workflow):
diff --git a/skills/creative/comfyui/tests/test_run_workflow.py b/skills/creative/comfyui/tests/test_run_workflow.py
index 69957dd2355..ec4091015c2 100644
--- a/skills/creative/comfyui/tests/test_run_workflow.py
+++ b/skills/creative/comfyui/tests/test_run_workflow.py
@@ -16,20 +16,20 @@ from run_workflow import (
 class TestParseInputImageArg:
     def test_with_name(self, tmp_path):
         f = tmp_path / "x.png"
-        f.write_text("x")
+        f.write_text("x", encoding="utf-8")
         n, p = parse_input_image_arg(f"image={f}")
         assert n == "image"
         assert p == f
 
     def test_without_name_defaults(self, tmp_path):
         f = tmp_path / "x.png"
-        f.write_text("x")
+        f.write_text("x", encoding="utf-8")
         n, p = parse_input_image_arg(str(f))
         assert n == "image"
 
     def test_custom_name(self, tmp_path):
         f = tmp_path / "x.png"
-        f.write_text("x")
+        f.write_text("x", encoding="utf-8")
         n, p = parse_input_image_arg(f"mask_image={f}")
         assert n == "mask_image"
 
diff --git a/skills/creative/design-md/SKILL.md b/skills/creative/design-md/SKILL.md
index 6604be1979d..e8f56a1f3e5 100644
--- a/skills/creative/design-md/SKILL.md
+++ b/skills/creative/design-md/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: design-md
 description: Author/validate/export Google's DESIGN.md token spec files.
-version: 1.0.0
+version: 1.1.0
 author: Hermes Agent
 license: MIT
 platforms: [linux, macos, windows]
@@ -98,7 +98,7 @@ Public Sans for everything except small all-caps labels...
 
 | Type | Format | Example |
 |------|--------|---------|
-| Color | `#` + hex (sRGB) | `"#1A1C1E"` |
+| Color | any CSS color (hex, `rgb()`, `oklch()`, named) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
 | Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |
 | Token reference | `{path.to.token}` | `{colors.primary}` |
 | Typography | object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` | see above |
@@ -110,8 +110,10 @@ pressed) are **separate component entries** with related key names
 
 ## Canonical section order
 
-Sections are optional, but present ones MUST appear in this order. Duplicate
-headings reject the file.
+Sections are optional, but present ones should appear in this order. The
+linter flags out-of-order sections (`section-order`, warning) and duplicate
+headings — consumers per the spec reject duplicates, so fix both before
+returning the file.
 
 1. Overview (alias: Brand & Style)
 2. Colors
@@ -150,8 +152,11 @@ npx -y @google/design.md lint DESIGN.md
 # Compare two versions, fail on regression (exit 1 = regression)
 npx -y @google/design.md diff DESIGN.md DESIGN-v2.md
 
-# Export to Tailwind theme JSON
-npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
+# Export to Tailwind v3 theme JSON (`tailwind` is a back-compat alias)
+npx -y @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
+
+# Export to a Tailwind v4 CSS @theme block (--color-*, --text-*, --radius-*, ...)
+npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css
 
 # Export to W3C DTCG (Design Tokens Format Module) JSON
 npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
@@ -160,18 +165,28 @@ npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
 npx -y @google/design.md spec --rules-only --format json
 ```
 
-All commands accept `-` for stdin. `lint` returns exit 1 on errors. Use the
-`--format json` flag and parse the output if you need to report findings
-structurally.
+All commands accept `-` for stdin. `lint` returns exit 1 on errors (warnings
+alone exit 0). `export` exits 0 on a successful export regardless of lint
+findings in the source — run `lint` separately to gate on those. Output is
+JSON by default; parse it if you need to report findings structurally.
 
-### Lint rule reference (what the 7 rules catch)
+On Windows, the `design.md` bin name can collide with the `.md` file
+association (silent no-op or the file opens in an editor). Use the dot-free
+alias: `npx -y -p @google/design.md designmd lint DESIGN.md`.
+
+### Lint rule reference (the 9 rules, as of CLI 0.3.0)
 
 - `broken-ref` (error) — `{colors.missing}` points at a non-existent token
-- `duplicate-section` (error) — same `## Heading` appears twice
-- `invalid-color`, `invalid-dimension`, `invalid-typography` (error)
-- `wcag-contrast` (warning/info) — component `textColor` vs `backgroundColor`
-  ratio against WCAG AA (4.5:1) and AAA (7:1)
-- `unknown-component-property` (warning) — outside the whitelist above
+- `contrast-ratio` (warning) — component `textColor` vs `backgroundColor`
+  below WCAG AA (4.5:1)
+- `missing-primary` (warning) — colors defined but no `primary` token
+- `missing-typography` (warning) — colors defined but no typography tokens
+- `orphaned-tokens` (warning) — color tokens never referenced by a component
+- `section-order` (warning) — sections out of the canonical order
+- `unknown-key` (warning) — top-level YAML key that looks like a typo of a
+  schema key (`colours:` → `colors:`); custom extension keys stay silent
+- `token-summary`, `missing-sections` (info) — counts and absent optional
+  sections
 
 When the user cares about accessibility, call this out explicitly in your
 summary — WCAG findings are the most load-bearing reason to use the CLI.
@@ -184,10 +199,16 @@ summary — WCAG findings are the most load-bearing reason to use the CLI.
   truncate values like `#1A1C1E` oddly.
 - **Negative dimensions need quotes too.** `letterSpacing: -0.02em` parses as
   a YAML flow — write `letterSpacing: "-0.02em"`.
-- **Section order is enforced.** If the user gives you prose in a random order,
-  reorder it to match the canonical list before saving.
-- **`version: alpha` is the current spec version** (as of Apr 2026). The spec
-  is marked alpha — watch for breaking changes.
+- **Section order matters even though the linter only warns.** If the user
+  gives you prose in a random order, reorder it to match the canonical list
+  before saving — spec-compliant consumers expect it.
+- **Typography sub-property typos are silently dropped.** As of CLI 0.3.0 a
+  typo like `fontwight:` produces no finding and the value vanishes from
+  exports — double-check sub-property names against the schema
+  (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`,
+  `fontFeature`, `fontVariation`).
+- **`version: alpha` is the current spec version** (as of Jul 2026, CLI
+  0.3.0). The spec is marked alpha — watch for breaking changes.
 - **Token references resolve by dotted path.** `{colors.primary}` works;
   `{primary}` does not.
 
diff --git a/skills/creative/excalidraw/SKILL.md b/skills/creative/excalidraw/SKILL.md
index 0474391a400..898aaa979e0 100644
--- a/skills/creative/excalidraw/SKILL.md
+++ b/skills/creative/excalidraw/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: excalidraw
 description: "Hand-drawn Excalidraw JSON diagrams (arch, flow, seq)."
-version: 1.0.0
+version: 1.0.1
 author: Hermes Agent
 license: MIT
 dependencies: []
@@ -51,7 +51,7 @@ Save to any path, e.g. `~/diagrams/my_diagram.excalidraw`.
 Run the upload script (located in this skill's `scripts/` directory) via terminal:
 
 ```bash
-python skills/diagramming/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw
+python skills/creative/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw
 ```
 
 This uploads to excalidraw.com (no account needed) and prints a shareable URL. Requires the `cryptography` pip package (`pip install cryptography`).
diff --git a/skills/creative/pretext/SKILL.md b/skills/creative/pretext/SKILL.md
index 78f5ab2d959..9f743310bbb 100644
--- a/skills/creative/pretext/SKILL.md
+++ b/skills/creative/pretext/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pretext
-description: "Use when building creative browser demos with @chenglou/pretext — DOM-free text layout for ASCII art, typographic flow around obstacles, text-as-geometry games, kinetic typography, and text-powered generative art. Produces single-file HTML demos by default."
+description: Build creative browser demos with DOM-free text layout.
 version: 1.0.0
 author: Hermes Agent
 license: MIT
diff --git a/skills/creative/sketch/SKILL.md b/skills/creative/sketch/SKILL.md
index 6e49585acd4..e7f072866b9 100644
--- a/skills/creative/sketch/SKILL.md
+++ b/skills/creative/sketch/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: sketch
 description: "Throwaway HTML mockups: 2-3 design variants to compare."
-version: 1.0.0
+version: 1.0.1
 author: Hermes Agent (adapted from gsd-build/get-shit-done)
 license: MIT
 platforms: [linux, macos, windows]
@@ -26,7 +26,9 @@ Load this when the user says things like "sketch this screen", "show me what X c
 
 ## If the user has the full GSD system installed
 
-If `gsd-sketch` shows up as a sibling skill (installed via `npx get-shit-done-cc --hermes`), prefer **`gsd-sketch`** for the full workflow: persistent `.planning/sketches/` with MANIFEST, frontier mode analysis, consistency audits across past sketches, and integration with the rest of GSD. This skill is the lightweight standalone version — one-off sketching without the state machinery.
+If `gsd-sketch` shows up as a sibling skill (installed via `npx get-shit-done-cc --hermes`), you can use **`gsd-sketch`** for the fuller workflow: persistent `.planning/sketches/` with MANIFEST, frontier mode analysis, consistency audits across past sketches, and integration with the rest of GSD. This skill is the lightweight standalone version — one-off sketching without the state machinery.
+
+> **Note:** The upstream GSD project ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)) is **archived / no longer maintained** on GitHub. The npm package (`get-shit-done-cc`) still installs, but treat it as an archived community project — this standalone `sketch` skill is the maintained path and needs nothing extra.
 
 ## Core method
 
@@ -215,4 +217,4 @@ Repeat for each variant, then present the comparison table.
 
 ## Attribution
 
-Adapted from the GSD (Get Shit Done) project's `/gsd-sketch` workflow — MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)). The full GSD system ships persistent sketch state, theme/variant pattern references, and consistency-audit workflows; install with `npx get-shit-done-cc --hermes --global`.
+Adapted from the GSD (Get Shit Done) project's `/gsd-sketch` workflow — MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)). The upstream GSD repo is now **archived/unmaintained** on GitHub; the `get-shit-done-cc` npm package still installs (`npx get-shit-done-cc --hermes --global`) and ships persistent sketch state, theme/variant pattern references, and consistency-audit workflows, but treat it as an archived community project.
diff --git a/skills/creative/songwriting-and-ai-music/SKILL.md b/skills/creative/songwriting-and-ai-music/SKILL.md
index 806eb874269..250e2746fdc 100644
--- a/skills/creative/songwriting-and-ai-music/SKILL.md
+++ b/skills/creative/songwriting-and-ai-music/SKILL.md
@@ -285,3 +285,21 @@ Style can drift in extensions — restate genre/mood when extending.
 - Don't be precious about rules. If a line breaks meter but hits
   harder, keep it. The feeling is what matters. Craft serves art,
   not the other way around.
+
+---
+
+## 10. Local / Open-Source Music Generation
+
+For local, GPU-based generation instead of Suno, two optional skills
+cover this (heavy dependencies, so not installed by default):
+
+- **heartmula** — full songs with vocals from lyrics + tags
+  (open-source Suno alternative, 8-16GB VRAM):
+  `hermes skills install official/creative/heartmula`
+- **audiocraft** — Meta's MusicGen (instrumental text-to-music) and
+  AudioGen (sound effects):
+  `hermes skills install official/creative/audiocraft-audio-generation`
+
+The lyric-writing and prompting craft in this skill applies to
+heartmula too — its input format is lyrics with bracketed structure
+tags plus comma-separated style tags.
diff --git a/skills/creative/touchdesigner-mcp/SKILL.md b/skills/creative/touchdesigner-mcp/SKILL.md
index 745e9ac838e..165798c2a90 100644
--- a/skills/creative/touchdesigner-mcp/SKILL.md
+++ b/skills/creative/touchdesigner-mcp/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: touchdesigner-mcp
-description: "Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools."
+description: Control TouchDesigner via twozero MCP.
 version: 1.1.0
 author: kshitijk4poor
 license: MIT
@@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [TouchDesigner, MCP, twozero, creative-coding, real-time-visuals, generative-art, audio-reactive, VJ, installation, GLSL]
-    related_skills: [native-mcp, ascii-video, manim-video, hermes-video]
+    related_skills: [ascii-video, manim-video]
 
 ---
 
diff --git a/skills/mlops/evaluation/lm-evaluation-harness/SKILL.md b/skills/mlops/evaluation/evaluating-llms-harness/SKILL.md
similarity index 97%
rename from skills/mlops/evaluation/lm-evaluation-harness/SKILL.md
rename to skills/mlops/evaluation/evaluating-llms-harness/SKILL.md
index 79c59f1e340..306b4f6fe94 100644
--- a/skills/mlops/evaluation/lm-evaluation-harness/SKILL.md
+++ b/skills/mlops/evaluation/evaluating-llms-harness/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: evaluating-llms-harness
 description: "lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.)."
-version: 1.0.0
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [lm-eval, transformers, vllm]
@@ -38,7 +38,7 @@ lm_eval --model hf \
 
 **View available tasks**:
 ```bash
-lm_eval --tasks list
+lm-eval ls tasks
 ```
 
 ## Common workflows
@@ -451,19 +451,19 @@ Verify model and tokenizer match:
 
 **Issue: HumanEval not executing code**
 
-Install execution dependencies:
-```bash
-pip install human-eval
-```
+Code-executing tasks (HumanEval, MBPP, etc.) are gated behind an explicit
+confirmation flag — you must pass `--confirm_run_unsafe_code` to run them:
 
-Enable code execution:
 ```bash
 lm_eval --model hf \
   --model_args pretrained=model-name \
   --tasks humaneval \
-  --allow_code_execution  # Required for HumanEval
+  --confirm_run_unsafe_code  # Required to run tasks that execute generated code
 ```
 
+Without this flag lm-eval refuses to run the task rather than silently skipping
+code execution.
+
 ## Advanced topics
 
 **Benchmark descriptions**: See [references/benchmark-guide.md](references/benchmark-guide.md) for detailed description of all 60+ tasks, what they measure, and interpretation.
diff --git a/skills/mlops/evaluation/lm-evaluation-harness/references/api-evaluation.md b/skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md
similarity index 100%
rename from skills/mlops/evaluation/lm-evaluation-harness/references/api-evaluation.md
rename to skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md
diff --git a/skills/mlops/evaluation/lm-evaluation-harness/references/benchmark-guide.md b/skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md
similarity index 100%
rename from skills/mlops/evaluation/lm-evaluation-harness/references/benchmark-guide.md
rename to skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md
diff --git a/skills/mlops/evaluation/lm-evaluation-harness/references/custom-tasks.md b/skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md
similarity index 100%
rename from skills/mlops/evaluation/lm-evaluation-harness/references/custom-tasks.md
rename to skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md
diff --git a/skills/mlops/evaluation/lm-evaluation-harness/references/distributed-eval.md b/skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md
similarity index 100%
rename from skills/mlops/evaluation/lm-evaluation-harness/references/distributed-eval.md
rename to skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md
diff --git a/skills/mlops/evaluation/weights-and-biases/SKILL.md b/skills/mlops/evaluation/weights-and-biases/SKILL.md
index 6dd17694b12..656cb5de680 100644
--- a/skills/mlops/evaluation/weights-and-biases/SKILL.md
+++ b/skills/mlops/evaluation/weights-and-biases/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: weights-and-biases
 description: "W&B: log ML experiments, sweeps, model registry, dashboards."
-version: 1.0.0
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [wandb]
@@ -238,7 +238,7 @@ sweep_config = {
     },
     'parameters': {
         'learning_rate': {
-            'distribution': 'log_uniform',
+            'distribution': 'log_uniform_values',
             'min': 1e-5,
             'max': 1e-1
         },
@@ -317,7 +317,7 @@ sweep_config = {
     'method': 'bayes',
     'metric': {'name': 'val/loss', 'goal': 'minimize'},
     'parameters': {
-        'lr': {'distribution': 'log_uniform', 'min': 1e-5, 'max': 1e-1}
+        'lr': {'distribution': 'log_uniform_values', 'min': 1e-5, 'max': 1e-1}
     }
 }
 ```
@@ -433,17 +433,21 @@ trainer.fit(model, datamodule=dm)
 
 ```python
 import wandb
-from wandb.keras import WandbCallback
+from wandb.integration.keras import WandbMetricsLogger, WandbModelCheckpoint
 
 # Initialize
 wandb.init(project="keras-demo")
 
-# Add callback
+# Add callbacks (the monolithic WandbCallback was removed;
+# use the dedicated callbacks from wandb.integration.keras instead)
 model.fit(
     x_train, y_train,
     validation_data=(x_val, y_val),
     epochs=10,
-    callbacks=[WandbCallback()]  # Auto-logs metrics
+    callbacks=[
+        WandbMetricsLogger(),                        # Auto-logs metrics
+        WandbModelCheckpoint("models/model-{epoch}")  # Saves checkpoints
+    ]
 )
 ```
 
diff --git a/skills/mlops/huggingface-hub/SKILL.md b/skills/mlops/huggingface-hub/SKILL.md
index a9ed104b3c0..bb82ac1c040 100644
--- a/skills/mlops/huggingface-hub/SKILL.md
+++ b/skills/mlops/huggingface-hub/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: huggingface-hub
 description: "HuggingFace hf CLI: search/download/upload models, datasets."
-version: 1.0.0
+version: 1.0.1
 author: Hugging Face
 license: MIT
 tags: [huggingface, hf, models, datasets, hub, mlops]
@@ -25,8 +25,8 @@ The `hf` command is the modern command-line interface for interacting with the H
 
 ### General Operations
 *   `hf download REPO_ID`: Download files from the Hub.
-*   `hf upload REPO_ID`: Upload files/folders (recommended for single-commit).
-*   `hf upload-large-folder REPO_ID LOCAL_PATH`: Recommended for resumable uploads of large directories.
+*   `hf upload REPO_ID`: Upload files/folders (recommended for single-commit; also handles resumable uploads of large directories).
+*   `hf upload-large-folder REPO_ID LOCAL_PATH`: **[Deprecated]** — use `hf upload` instead.
 *   `hf sync`: Sync files between a local directory and a bucket.
 *   `hf env` / `hf version`: View environment and version details.
 
@@ -50,7 +50,7 @@ The `hf` command is the modern command-line interface for interacting with the H
 *   **Datasets:** `hf datasets list`, `info`, and `parquet` (list parquet URLs).
 *   **SQL Queries:** `hf datasets sql SQL` — Execute raw SQL via DuckDB against dataset parquet URLs.
 *   **Models:** `hf models list` and `info`.
-*   **Papers:** `hf papers list` — View daily papers.
+*   **Papers:** `hf papers ls` — View daily papers.
 
 ### Discussions & Pull Requests (`hf discussions`)
 *   Manage the lifecycle of Hub contributions: `list`, `create`, `info`, `comment`, `close`, `reopen`, and `rename`.
diff --git a/skills/mlops/inference/vllm/SKILL.md b/skills/mlops/inference/serving-llms-vllm/SKILL.md
similarity index 90%
rename from skills/mlops/inference/vllm/SKILL.md
rename to skills/mlops/inference/serving-llms-vllm/SKILL.md
index 2f754e1b0f5..33441394013 100644
--- a/skills/mlops/inference/vllm/SKILL.md
+++ b/skills/mlops/inference/serving-llms-vllm/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: serving-llms-vllm
 description: "vLLM: high-throughput LLM serving, OpenAI API, quantization."
-version: 1.0.0
+version: 1.0.1
 author: Orchestra Research
 license: MIT
 dependencies: [vllm, torch, transformers]
@@ -31,7 +31,7 @@ pip install vllm
 ```python
 from vllm import LLM, SamplingParams
 
-llm = LLM(model="meta-llama/Llama-3-8B-Instruct")
+llm = LLM(model="meta-llama/Meta-Llama-3-8B-Instruct")
 sampling = SamplingParams(temperature=0.7, max_tokens=256)
 
 outputs = llm.generate(["Explain quantum computing"], sampling)
@@ -40,14 +40,14 @@ print(outputs[0].outputs[0].text)
 
 **OpenAI-compatible server**:
 ```bash
-vllm serve meta-llama/Llama-3-8B-Instruct
+vllm serve meta-llama/Meta-Llama-3-8B-Instruct
 
 # Query with OpenAI SDK
 python -c "
 from openai import OpenAI
 client = OpenAI(base_url='http://localhost:8000/v1', api_key='EMPTY')
 print(client.chat.completions.create(
-    model='meta-llama/Llama-3-8B-Instruct',
+    model='meta-llama/Meta-Llama-3-8B-Instruct',
     messages=[{'role': 'user', 'content': 'Hello!'}]
 ).choices[0].message.content)
 "
@@ -74,24 +74,23 @@ Choose configuration based on your model size:
 
 ```bash
 # For 7B-13B models on single GPU
-vllm serve meta-llama/Llama-3-8B-Instruct \
+vllm serve meta-llama/Meta-Llama-3-8B-Instruct \
   --gpu-memory-utilization 0.9 \
   --max-model-len 8192 \
   --port 8000
 
 # For 30B-70B models with tensor parallelism
-vllm serve meta-llama/Llama-2-70b-hf \
+vllm serve meta-llama/Meta-Llama-3-70B-Instruct \
   --tensor-parallel-size 4 \
   --gpu-memory-utilization 0.9 \
   --quantization awq \
   --port 8000
 
-# For production with caching and metrics
-vllm serve meta-llama/Llama-3-8B-Instruct \
+# For production with caching (Prometheus metrics are exposed
+# automatically at /metrics on the API port)
+vllm serve meta-llama/Meta-Llama-3-8B-Instruct \
   --gpu-memory-utilization 0.9 \
   --enable-prefix-caching \
-  --enable-metrics \
-  --metrics-port 9090 \
   --port 8000 \
   --host 0.0.0.0
 ```
@@ -112,10 +111,10 @@ Verify TTFT (time to first token) < 500ms and throughput > 100 req/sec.
 
 **Step 3: Enable monitoring**
 
-vLLM exposes Prometheus metrics on port 9090:
+vLLM exposes Prometheus metrics at `/metrics` on the API port (default 8000):
 
 ```bash
-curl http://localhost:9090/metrics | grep vllm
+curl http://localhost:8000/metrics | grep vllm
 ```
 
 Key metrics to monitor:
@@ -131,7 +130,7 @@ Use Docker for consistent deployment:
 # Run vLLM in Docker
 docker run --gpus all -p 8000:8000 \
   vllm/vllm-openai:latest \
-  --model meta-llama/Llama-3-8B-Instruct \
+  --model meta-llama/Meta-Llama-3-8B-Instruct \
   --gpu-memory-utilization 0.9 \
   --enable-prefix-caching
 ```
@@ -175,7 +174,7 @@ print(f"Loaded {len(prompts)} prompts")
 from vllm import LLM, SamplingParams
 
 llm = LLM(
-    model="meta-llama/Llama-3-8B-Instruct",
+    model="meta-llama/Meta-Llama-3-8B-Instruct",
     tensor_parallel_size=2,  # Use 2 GPUs
     gpu_memory_utilization=0.9,
     max_model_len=4096
@@ -338,9 +337,11 @@ Verify tensor parallelism uses power of 2 GPUs:
 vllm serve MODEL --tensor-parallel-size 4  # Not 3
 ```
 
-Enable speculative decoding for faster generation:
+Enable speculative decoding for faster generation (pass config as JSON;
+`--speculative-model` was removed in favor of `--speculative-config`):
 ```bash
-vllm serve MODEL --speculative-model DRAFT_MODEL
+vllm serve MODEL \
+  --speculative-config '{"model": "DRAFT_MODEL", "num_speculative_tokens": 5, "method": "draft_model"}'
 ```
 
 ## Advanced topics
diff --git a/skills/mlops/inference/vllm/references/optimization.md b/skills/mlops/inference/serving-llms-vllm/references/optimization.md
similarity index 100%
rename from skills/mlops/inference/vllm/references/optimization.md
rename to skills/mlops/inference/serving-llms-vllm/references/optimization.md
diff --git a/skills/mlops/inference/vllm/references/quantization.md b/skills/mlops/inference/serving-llms-vllm/references/quantization.md
similarity index 100%
rename from skills/mlops/inference/vllm/references/quantization.md
rename to skills/mlops/inference/serving-llms-vllm/references/quantization.md
diff --git a/skills/mlops/inference/vllm/references/server-deployment.md b/skills/mlops/inference/serving-llms-vllm/references/server-deployment.md
similarity index 100%
rename from skills/mlops/inference/vllm/references/server-deployment.md
rename to skills/mlops/inference/serving-llms-vllm/references/server-deployment.md
diff --git a/skills/mlops/inference/vllm/references/troubleshooting.md b/skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md
similarity index 100%
rename from skills/mlops/inference/vllm/references/troubleshooting.md
rename to skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md
diff --git a/skills/productivity/docx/scripts/accept_changes.py b/skills/productivity/docx/scripts/accept_changes.py
index 8e363161915..146f09c14f6 100755
--- a/skills/productivity/docx/scripts/accept_changes.py
+++ b/skills/productivity/docx/scripts/accept_changes.py
@@ -68,7 +68,7 @@ def accept_changes(
         result = subprocess.run(
             cmd,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=30,
             check=False,
             env=get_soffice_env(),
@@ -92,7 +92,7 @@ def _setup_libreoffice_macro() -> bool:
     macro_dir = Path(MACRO_DIR)
     macro_file = macro_dir / "Module1.xba"
 
-    if macro_file.exists() and "AcceptAllTrackedChanges" in macro_file.read_text():
+    if macro_file.exists() and "AcceptAllTrackedChanges" in macro_file.read_text(encoding="utf-8"):
         return True
 
     if not macro_dir.exists():
@@ -111,7 +111,7 @@ def _setup_libreoffice_macro() -> bool:
         macro_dir.mkdir(parents=True, exist_ok=True)
 
     try:
-        macro_file.write_text(ACCEPT_CHANGES_MACRO)
+        macro_file.write_text(ACCEPT_CHANGES_MACRO, encoding="utf-8")
         return True
     except Exception as e:
         logger.warning(f"Failed to setup LibreOffice macro: {e}")
diff --git a/skills/productivity/docx/scripts/office/soffice.py b/skills/productivity/docx/scripts/office/soffice.py
index 0b4c99deca5..eec16879cd4 100644
--- a/skills/productivity/docx/scripts/office/soffice.py
+++ b/skills/productivity/docx/scripts/office/soffice.py
@@ -64,7 +64,7 @@ def _ensure_shim() -> Path:
         return _SHIM_SO
 
     src = Path(tempfile.gettempdir()) / "lo_socket_shim.c"
-    src.write_text(_SHIM_SOURCE)
+    src.write_text(_SHIM_SOURCE, encoding="utf-8")
     subprocess.run(
         ["gcc", "-shared", "-fPIC", "-o", str(_SHIM_SO), str(src), "-ldl"],
         check=True,
diff --git a/skills/productivity/docx/scripts/office/validators/base.py b/skills/productivity/docx/scripts/office/validators/base.py
index 91f2fb83412..f928b2ca5be 100644
--- a/skills/productivity/docx/scripts/office/validators/base.py
+++ b/skills/productivity/docx/scripts/office/validators/base.py
@@ -783,7 +783,7 @@ class BaseSchemaValidator:
         try:
             schema = _load_schema(str(schema_path))
 
-            with open(xml_file, "r") as f:
+            with open(xml_file, "rb") as f:
                 xml_doc = lxml.etree.parse(f)
 
             xml_doc, _ = self._remove_template_tags_from_text_nodes(xml_doc)
diff --git a/skills/productivity/docx/scripts/office/validators/redlining.py b/skills/productivity/docx/scripts/office/validators/redlining.py
index 4185c51f4f1..7d3a08262e8 100644
--- a/skills/productivity/docx/scripts/office/validators/redlining.py
+++ b/skills/productivity/docx/scripts/office/validators/redlining.py
@@ -201,7 +201,7 @@ class RedliningValidator:
                         str(modified_file),
                     ],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding="utf-8", errors="replace",
                 )
 
                 if result.stdout.strip():
@@ -229,7 +229,7 @@ class RedliningValidator:
                         str(modified_file),
                     ],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding="utf-8", errors="replace",
                 )
 
                 if result.stdout.strip():
diff --git a/skills/productivity/google-workspace/scripts/google_api.py b/skills/productivity/google-workspace/scripts/google_api.py
index 27855a5158e..5c2e82323d7 100644
--- a/skills/productivity/google-workspace/scripts/google_api.py
+++ b/skills/productivity/google-workspace/scripts/google_api.py
@@ -70,7 +70,7 @@ def _ensure_authenticated():
 
 def _stored_token_scopes() -> list[str]:
     try:
-        data = json.loads(TOKEN_PATH.read_text())
+        data = json.loads(TOKEN_PATH.read_text(encoding="utf-8"))
     except Exception:
         return list(SCOPES)
     scopes = data.get("scopes")
@@ -108,7 +108,7 @@ def _run_gws(parts: list[str], *, params: dict | None = None, body: dict | None
     result = subprocess.run(
         cmd,
         capture_output=True,
-        text=True,
+        text=True, encoding='utf-8', errors='replace',
         env=_gws_env(),
     )
     if result.returncode != 0:
@@ -192,7 +192,7 @@ def get_credentials():
             json.dumps(
                 _normalize_authorized_user_payload(json.loads(creds.to_json())),
                 indent=2,
-            )
+            ), encoding="utf-8"
         )
     if not creds.valid:
         print("Token is invalid. Re-run setup.", file=sys.stderr)
diff --git a/skills/productivity/google-workspace/scripts/gws_bridge.py b/skills/productivity/google-workspace/scripts/gws_bridge.py
index 7d10ba25741..5fa7a9daca5 100755
--- a/skills/productivity/google-workspace/scripts/gws_bridge.py
+++ b/skills/productivity/google-workspace/scripts/gws_bridge.py
@@ -69,7 +69,7 @@ def refresh_token(token_data: dict) -> dict:
     ).isoformat()
 
     get_token_path().write_text(
-        json.dumps(_normalize_authorized_user_payload(token_data), indent=2)
+        json.dumps(_normalize_authorized_user_payload(token_data), indent=2), encoding="utf-8"
     )
     return token_data
 
@@ -81,7 +81,7 @@ def get_valid_token() -> str:
         print("ERROR: No Google token found. Run setup.py --auth-url first.", file=sys.stderr)
         sys.exit(1)
 
-    token_data = json.loads(token_path.read_text())
+    token_data = json.loads(token_path.read_text(encoding="utf-8"))
 
     expiry = token_data.get("expiry", "")
     if expiry:
diff --git a/skills/productivity/google-workspace/scripts/setup.py b/skills/productivity/google-workspace/scripts/setup.py
index 26f50c52c70..c2393f92db1 100644
--- a/skills/productivity/google-workspace/scripts/setup.py
+++ b/skills/productivity/google-workspace/scripts/setup.py
@@ -71,7 +71,7 @@ def _normalize_authorized_user_payload(payload: dict) -> dict:
 
 def _load_token_payload(path: Path = TOKEN_PATH) -> dict:
     try:
-        return json.loads(path.read_text())
+        return json.loads(path.read_text(encoding="utf-8"))
     except Exception:
         return {}
 
@@ -220,7 +220,7 @@ def check_auth(quiet: bool = False):
                 json.dumps(
                     _normalize_authorized_user_payload(json.loads(creds.to_json())),
                     indent=2,
-                )
+                ), encoding="utf-8"
             )
             missing_scopes = _missing_scopes_from_payload(_load_token_payload(TOKEN_PATH))
             if missing_scopes:
@@ -260,7 +260,7 @@ def store_client_secret(path: str):
         sys.exit(1)
 
     try:
-        data = json.loads(src.read_text())
+        data = json.loads(src.read_text(encoding="utf-8"))
     except json.JSONDecodeError:
         print("ERROR: File is not valid JSON.")
         sys.exit(1)
@@ -270,7 +270,7 @@ def store_client_secret(path: str):
         print("Download the correct file from: https://console.cloud.google.com/apis/credentials")
         sys.exit(1)
 
-    CLIENT_SECRET_PATH.write_text(json.dumps(data, indent=2))
+    CLIENT_SECRET_PATH.write_text(json.dumps(data, indent=2), encoding="utf-8")
     print(f"OK: Client secret saved to {CLIENT_SECRET_PATH}")
 
 
@@ -284,7 +284,7 @@ def _save_pending_auth(*, state: str, code_verifier: str):
                 "redirect_uri": REDIRECT_URI,
             },
             indent=2,
-        )
+        ), encoding="utf-8"
     )
 
 
@@ -295,7 +295,7 @@ def _load_pending_auth() -> dict:
         sys.exit(1)
 
     try:
-        data = json.loads(PENDING_AUTH_PATH.read_text())
+        data = json.loads(PENDING_AUTH_PATH.read_text(encoding="utf-8"))
     except Exception as e:
         print(f"ERROR: Could not read pending OAuth session: {e}")
         print("Run --auth-url again to start a fresh OAuth session.")
@@ -410,7 +410,7 @@ def exchange_auth_code(code: str):
         print(f"WARNING: Token missing some Google Workspace scopes: {', '.join(missing_scopes)}")
         print("Some services may not be available.")
 
-    TOKEN_PATH.write_text(json.dumps(token_payload, indent=2))
+    TOKEN_PATH.write_text(json.dumps(token_payload, indent=2), encoding="utf-8")
     PENDING_AUTH_PATH.unlink(missing_ok=True)
     print(f"OK: Authenticated. Token saved to {TOKEN_PATH}")
     print(f"Profile-scoped token location: {display_hermes_home()}/google_token.json")
diff --git a/skills/productivity/nano-pdf/SKILL.md b/skills/productivity/nano-pdf/SKILL.md
index e76e380362f..a8022c8185f 100644
--- a/skills/productivity/nano-pdf/SKILL.md
+++ b/skills/productivity/nano-pdf/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: nano-pdf
-description: "Edit PDF text/typos/titles via nano-pdf CLI (NL prompts)."
+description: "Edit text in existing PDFs via natural-language prompts."
 version: 1.0.0
 author: community
 license: MIT
diff --git a/skills/productivity/pdf/scripts/check_bounding_boxes.py b/skills/productivity/pdf/scripts/check_bounding_boxes.py
index 2cc5e348f35..b9c6ea76556 100644
--- a/skills/productivity/pdf/scripts/check_bounding_boxes.py
+++ b/skills/productivity/pdf/scripts/check_bounding_boxes.py
@@ -59,7 +59,7 @@ if __name__ == "__main__":
     if len(sys.argv) != 2:
         print("Usage: check_bounding_boxes.py [fields.json]")
         sys.exit(1)
-    with open(sys.argv[1]) as f:
+    with open(sys.argv[1], encoding="utf-8") as f:
         messages = get_bounding_box_messages(f)
     for msg in messages:
         print(msg)
diff --git a/skills/productivity/pdf/scripts/create_validation_image.py b/skills/productivity/pdf/scripts/create_validation_image.py
index 10eadd8124b..ce98a859750 100644
--- a/skills/productivity/pdf/scripts/create_validation_image.py
+++ b/skills/productivity/pdf/scripts/create_validation_image.py
@@ -7,7 +7,7 @@ from PIL import Image, ImageDraw
 
 
 def create_validation_image(page_number, fields_json_path, input_path, output_path):
-    with open(fields_json_path, 'r') as f:
+    with open(fields_json_path, 'r', encoding='utf-8') as f:
         data = json.load(f)
 
         img = Image.open(input_path)
diff --git a/skills/productivity/pdf/scripts/fill_fillable_fields.py b/skills/productivity/pdf/scripts/fill_fillable_fields.py
index 51c2600f389..7bc4b1c6f54 100644
--- a/skills/productivity/pdf/scripts/fill_fillable_fields.py
+++ b/skills/productivity/pdf/scripts/fill_fillable_fields.py
@@ -9,7 +9,7 @@ from extract_form_field_info import get_field_info
 
 
 def fill_pdf_fields(input_pdf_path: str, fields_json_path: str, output_pdf_path: str):
-    with open(fields_json_path) as f:
+    with open(fields_json_path, encoding="utf-8") as f:
         fields = json.load(f)
     fields_by_page = {}
     for field in fields:
diff --git a/skills/productivity/pdf/scripts/fill_pdf_form_with_annotations.py b/skills/productivity/pdf/scripts/fill_pdf_form_with_annotations.py
index b430069fd01..204e94098fc 100644
--- a/skills/productivity/pdf/scripts/fill_pdf_form_with_annotations.py
+++ b/skills/productivity/pdf/scripts/fill_pdf_form_with_annotations.py
@@ -32,7 +32,7 @@ def transform_from_pdf_coords(bbox, pdf_height):
 
 def fill_pdf_form(input_pdf_path, fields_json_path, output_pdf_path):
     
-    with open(fields_json_path, "r") as f:
+    with open(fields_json_path, "r", encoding="utf-8") as f:
         fields_data = json.load(f)
     
     reader = PdfReader(input_pdf_path)
diff --git a/skills/productivity/powerpoint/scripts/office/soffice.py b/skills/productivity/powerpoint/scripts/office/soffice.py
index 0b4c99deca5..eec16879cd4 100644
--- a/skills/productivity/powerpoint/scripts/office/soffice.py
+++ b/skills/productivity/powerpoint/scripts/office/soffice.py
@@ -64,7 +64,7 @@ def _ensure_shim() -> Path:
         return _SHIM_SO
 
     src = Path(tempfile.gettempdir()) / "lo_socket_shim.c"
-    src.write_text(_SHIM_SOURCE)
+    src.write_text(_SHIM_SOURCE, encoding="utf-8")
     subprocess.run(
         ["gcc", "-shared", "-fPIC", "-o", str(_SHIM_SO), str(src), "-ldl"],
         check=True,
diff --git a/skills/productivity/powerpoint/scripts/office/validators/base.py b/skills/productivity/powerpoint/scripts/office/validators/base.py
index 91f2fb83412..f928b2ca5be 100644
--- a/skills/productivity/powerpoint/scripts/office/validators/base.py
+++ b/skills/productivity/powerpoint/scripts/office/validators/base.py
@@ -783,7 +783,7 @@ class BaseSchemaValidator:
         try:
             schema = _load_schema(str(schema_path))
 
-            with open(xml_file, "r") as f:
+            with open(xml_file, "rb") as f:
                 xml_doc = lxml.etree.parse(f)
 
             xml_doc, _ = self._remove_template_tags_from_text_nodes(xml_doc)
diff --git a/skills/productivity/powerpoint/scripts/office/validators/redlining.py b/skills/productivity/powerpoint/scripts/office/validators/redlining.py
index 4185c51f4f1..7d3a08262e8 100644
--- a/skills/productivity/powerpoint/scripts/office/validators/redlining.py
+++ b/skills/productivity/powerpoint/scripts/office/validators/redlining.py
@@ -201,7 +201,7 @@ class RedliningValidator:
                         str(modified_file),
                     ],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding="utf-8", errors="replace",
                 )
 
                 if result.stdout.strip():
@@ -229,7 +229,7 @@ class RedliningValidator:
                         str(modified_file),
                     ],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding="utf-8", errors="replace",
                 )
 
                 if result.stdout.strip():
diff --git a/skills/productivity/powerpoint/scripts/thumbnail.py b/skills/productivity/powerpoint/scripts/thumbnail.py
index d49cac0e1a1..8735bc6d720 100755
--- a/skills/productivity/powerpoint/scripts/thumbnail.py
+++ b/skills/productivity/powerpoint/scripts/thumbnail.py
@@ -192,6 +192,8 @@ def convert_to_images(pptx_path: Path, temp_dir: Path) -> list[Path]:
         ["--headless", "--convert-to", "pdf", "--outdir", str(temp_dir), str(pptx_path)],
         capture_output=True,
         text=True,
+        encoding="utf-8",
+        errors="replace",
     )
     if result.returncode != 0 or not pdf_path.exists():
         detail = (result.stderr or result.stdout or "").strip()
@@ -207,7 +209,7 @@ def convert_to_images(pptx_path: Path, temp_dir: Path) -> list[Path]:
             str(temp_dir / "slide"),
         ],
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
     )
     if result.returncode != 0:
         raise RuntimeError("Image conversion failed")
diff --git a/skills/productivity/teams-meeting-pipeline/SKILL.md b/skills/productivity/teams-meeting-pipeline/SKILL.md
index 11960aa3201..775e3a5cebb 100644
--- a/skills/productivity/teams-meeting-pipeline/SKILL.md
+++ b/skills/productivity/teams-meeting-pipeline/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: teams-meeting-pipeline
-description: "Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions."
+description: Teams meeting summaries, job replay, Graph subscriptions.
 version: 1.1.0
 author: Hermes Agent + Teknium
 license: MIT
diff --git a/skills/productivity/xlsx/scripts/office/soffice.py b/skills/productivity/xlsx/scripts/office/soffice.py
index 0b4c99deca5..eec16879cd4 100644
--- a/skills/productivity/xlsx/scripts/office/soffice.py
+++ b/skills/productivity/xlsx/scripts/office/soffice.py
@@ -64,7 +64,7 @@ def _ensure_shim() -> Path:
         return _SHIM_SO
 
     src = Path(tempfile.gettempdir()) / "lo_socket_shim.c"
-    src.write_text(_SHIM_SOURCE)
+    src.write_text(_SHIM_SOURCE, encoding="utf-8")
     subprocess.run(
         ["gcc", "-shared", "-fPIC", "-o", str(_SHIM_SO), str(src), "-ldl"],
         check=True,
diff --git a/skills/productivity/xlsx/scripts/recalc.py b/skills/productivity/xlsx/scripts/recalc.py
index 6232be2deea..2317ce627b3 100755
--- a/skills/productivity/xlsx/scripts/recalc.py
+++ b/skills/productivity/xlsx/scripts/recalc.py
@@ -71,7 +71,7 @@ def setup_libreoffice_macro(profile_dir: Path, timeout=30):
         return None, "LibreOffice did not create a usable profile; formulas were NOT recalculated"
 
     try:
-        (macro_dir / MACRO_FILENAME).write_text(RECALCULATE_MACRO)
+        (macro_dir / MACRO_FILENAME).write_text(RECALCULATE_MACRO, encoding="utf-8")
     except OSError as e:
         return None, f"Could not install the recalculation macro: {e}"
 
@@ -189,7 +189,7 @@ def _recalc_with_profile(filename, abs_path, timeout, profile_dir: Path):
 
     try:
         result = subprocess.run(
-            cmd, capture_output=True, text=True, env=get_soffice_env(), timeout=timeout + 15
+            cmd, capture_output=True, text=True, encoding="utf-8", errors="replace", env=get_soffice_env(), timeout=timeout + 15
         )
     except subprocess.TimeoutExpired:
         return {"error": timed_out}
diff --git a/skills/research/research-paper-writing/SKILL.md b/skills/research/research-paper-writing/SKILL.md
index 8c951f7570e..42e7771555f 100644
--- a/skills/research/research-paper-writing/SKILL.md
+++ b/skills/research/research-paper-writing/SKILL.md
@@ -11,7 +11,7 @@ metadata:
   hermes:
     tags: [Research, Paper Writing, Experiments, ML, AI, NeurIPS, ICML, ICLR, ACL, AAAI, COLM, LaTeX, Citations, Statistical Analysis]
     category: research
-    related_skills: [arxiv, ml-paper-writing, subagent-driven-development, plan]
+    related_skills: [arxiv, subagent-driven-development, plan]
     requires_toolsets: [terminal, files]
 
 ---
diff --git a/skills/smart-home/openhue/SKILL.md b/skills/smart-home/openhue/SKILL.md
index 3f60c0556f9..ce3bbceb035 100644
--- a/skills/smart-home/openhue/SKILL.md
+++ b/skills/smart-home/openhue/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: openhue
 description: "Control Philips Hue lights, scenes, rooms via OpenHue CLI."
-version: 1.0.0
+version: 1.0.1
 author: community
 license: MIT
 platforms: [linux, macos, windows]
@@ -20,8 +20,11 @@ Control Philips Hue lights and scenes via a Hue Bridge from the terminal.
 ## Prerequisites
 
 ```bash
-# Linux (pre-built binary)
-curl -sL https://github.com/openhue/openhue-cli/releases/latest/download/openhue-linux-amd64 -o ~/.local/bin/openhue && chmod +x ~/.local/bin/openhue
+# Linux (pre-built binary — releases ship tarballs, not bare binaries)
+curl -sL "https://github.com/openhue/openhue-cli/releases/latest/download/openhue_Linux_x86_64.tar.gz" \
+  | tar -xz -C /tmp openhue \
+  && install -m 0755 /tmp/openhue ~/.local/bin/openhue
+# (use openhue_Linux_arm64.tar.gz on ARM64)
 
 # macOS
 brew install openhue/cli/openhue-cli
diff --git a/skills/social-media/xurl/SKILL.md b/skills/social-media/xurl/SKILL.md
index f25ecbbf6b9..a784e2a21a8 100644
--- a/skills/social-media/xurl/SKILL.md
+++ b/skills/social-media/xurl/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: xurl
-description: "X/Twitter via xurl CLI: post, search, DM, media, v2 API."
-version: 1.1.1
+description: "X/Twitter via xurl CLI: raw post search, posting, DM, media."
+version: 1.1.3
 author: xdevplatform + openclaw + Hermes Agent
 license: MIT
 platforms: [linux, macos]
@@ -20,7 +20,7 @@ metadata:
 
 Use this skill for:
 - posting, replying, quoting, deleting posts
-- searching posts and reading timelines/mentions
+- searching for raw posts (actual post JSON with IDs you can engage with) and reading timelines/mentions
 - liking, reposting, bookmarking
 - following, unfollowing, blocking, muting
 - direct messages
@@ -183,6 +183,8 @@ xurl delete 1234567890
 
 ### Reading & Search
 
+`xurl search` queries the X index as your authenticated account and returns raw post objects — IDs, authors, full text — so results can be immediately engaged with (reply, like, repost, quote). Use it when you need the actual posts rather than a summarized answer about a topic.
+
 ```bash
 xurl read 1234567890
 xurl read https://x.com/user/status/1234567890
@@ -389,12 +391,14 @@ xurl --app staging /2/users/me             # one-off against staging
 ## Agent Workflow
 
 1. Verify prerequisites: `xurl --help` and `xurl auth status`.
-2. **Check default app has credentials.** Parse the `auth status` output. The default app is marked with `▸`. If the default app shows `oauth2: (none)` but another app has a valid oauth2 user, tell the user to run `xurl auth default <that-app>` to fix it. This is the most common setup mistake — the user added an app with a custom name but never set it as default, so xurl keeps trying the empty `default` profile.
-3. If auth is missing entirely, stop and direct the user to the "One-Time User Setup" section — do NOT attempt to register apps or pass secrets yourself.
-4. Start with a cheap read (`xurl whoami`, `xurl user @handle`, `xurl search ... -n 3`) to confirm reachability.
-5. Confirm the target post/user and the user's intent before any write action (post, reply, like, repost, DM, follow, block, delete).
-6. Use JSON output directly — every response is already structured.
-7. Never paste `~/.xurl` contents back into the conversation.
+2. Before using `xurl search`, check intent. Reach for it when the task needs actual post objects, authenticated account context, or leads into an X write action — it is the right surface when the user wants posts they can engage with, not just a summary of a topic.
+3. **Check default app has credentials.** Parse the `auth status` output. The default app is marked with `▸`. If the default app shows `oauth2: (none)` but another app has a valid oauth2 user, tell the user to run `xurl auth default <that-app>` to fix it. This is the most common setup mistake — the user added an app with a custom name but never set it as default, so xurl keeps trying the empty `default` profile.
+4. If auth is missing entirely, stop and direct the user to the "One-Time User Setup" section — do NOT attempt to register apps or pass secrets yourself.
+5. Start with a cheap read (`xurl whoami`, `xurl user @handle`, `xurl search ... -n 3`) to confirm reachability.
+6. Confirm the target post/user and the user's intent before any write action (post, reply, like, repost, DM, follow, block, delete).
+7. Only the `xurl` command output (or the raw X API response) proves that a state-changing X action happened. Never report a write as done based on any other source — search results, summaries, or prior context.
+8. Use JSON output directly — every response is already structured.
+9. Never paste `~/.xurl` contents back into the conversation.
 
 ---
 
diff --git a/skills/dogfood/SKILL.md b/skills/software-development/dogfood/SKILL.md
similarity index 100%
rename from skills/dogfood/SKILL.md
rename to skills/software-development/dogfood/SKILL.md
diff --git a/skills/dogfood/references/issue-taxonomy.md b/skills/software-development/dogfood/references/issue-taxonomy.md
similarity index 100%
rename from skills/dogfood/references/issue-taxonomy.md
rename to skills/software-development/dogfood/references/issue-taxonomy.md
diff --git a/skills/dogfood/templates/dogfood-report-template.md b/skills/software-development/dogfood/templates/dogfood-report-template.md
similarity index 100%
rename from skills/dogfood/templates/dogfood-report-template.md
rename to skills/software-development/dogfood/templates/dogfood-report-template.md
diff --git a/skills/software-development/hermes-agent-skill-authoring/SKILL.md b/skills/software-development/hermes-agent-skill-authoring/SKILL.md
index 2feed79f940..b8a9dc2fd7f 100644
--- a/skills/software-development/hermes-agent-skill-authoring/SKILL.md
+++ b/skills/software-development/hermes-agent-skill-authoring/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: hermes-agent-skill-authoring
-description: "Author in-repo SKILL.md: frontmatter, validator, structure, and writing-quality principles."
+description: "Author in-repo SKILL.md files: frontmatter and structure."
 version: 1.1.0
 author: Hermes Agent
 license: MIT
@@ -35,6 +35,10 @@ Source of truth: `tools/skill_manager_tool.py::_validate_frontmatter`. Hard requ
 - Parses as a YAML mapping.
 - `name` field present.
 - `description` field present, ≤ **1024 chars** (`MAX_DESCRIPTION_LENGTH`).
+  **Long descriptions are truncated to 57 chars + "..." in the system
+  prompt skill index** (`extract_skill_description` in `agent/skill_utils.py`);
+  longer text is visible via `skills_list()` and `skill_view()`.
+  Front-load the trigger phrase.
 - Non-empty body after the closing `---`.
 
 Peer-matched shape used by every skill under `skills/software-development/`:
@@ -42,7 +46,7 @@ Peer-matched shape used by every skill under `skills/software-development/`:
 ```yaml
 ---
 name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
-description: Use when <trigger>. <one-line behavior>.
+description: Use when <trigger>. <one-line behavior>.   # first 57 chars shown in system prompt
 version: 1.1.0
 author: Hermes Agent
 license: MIT
@@ -57,7 +61,9 @@ metadata:
 
 ## Size Limits
 
-- Description: ≤ 1024 chars (enforced).
+- Description: ≤ 1024 chars (enforced). **Long descriptions render as the first 57 chars
+  plus "..." in the system prompt skill index;** the rest is visible via `skills_list()`
+  and `skill_view()`.
 - Full SKILL.md: ≤ 100,000 chars (enforced as `MAX_SKILL_CONTENT_CHARS`, ~36k tokens).
 - Peer skills in `software-development/` sit at **8-14k chars**. Aim for that range. If you're pushing past 20k, split into `references/*.md` and reference them from SKILL.md.
 
@@ -121,7 +127,7 @@ Not every section is mandatory, but `Overview` + `When to Use` + actionable body
 skills/<category>/<skill-name>/SKILL.md
 ```
 
-Categories currently in repo (confirm with `ls skills/`): `autonomous-ai-agents`, `creative`, `data-science`, `devops`, `dogfood`, `email`, `gaming`, `github`, `leisure`, `mcp`, `media`, `mlops/*`, `note-taking`, `productivity`, `red-teaming`, `research`, `smart-home`, `social-media`, `software-development`.
+Categories currently in repo (confirm with `ls skills/`): `autonomous-ai-agents`, `creative`, `data-science`, `devops`, `email`, `gaming`, `github`, `leisure`, `mcp`, `media`, `mlops/*`, `note-taking`, `productivity`, `red-teaming`, `research`, `smart-home`, `social-media`, `software-development`.
 
 Pick the closest existing category. Don't invent new top-level categories casually.
 
@@ -165,7 +171,11 @@ Pick the closest existing category. Don't invent new top-level categories casual
 
 2. **Leading whitespace before `---`.** The validator checks `content.startswith("---")`; any leading blank line or BOM fails validation.
 
-3. **Description too generic.** Peer descriptions start with "Use when ..." and describe the *trigger class*, not the one task. "Use when debugging X" > "Debug X".
+3. **Description too generic or trigger buried past char 57.** The system prompt
+   skill index truncates long descriptions at 57 chars. Peer descriptions start
+   with "Use when ..." and complete the trigger class within that window.
+   - Good: `Use when debugging Hermes skill discovery failures.`
+   - Bad: `This skill contains detailed guidance for agents working on Hermes skill discovery failures.`
 
 4. **Forgetting the author/license/metadata block.** Not validator-enforced, but every peer has it; omitting makes the skill look half-finished.
 
@@ -185,7 +195,8 @@ Pick the closest existing category. Don't invent new top-level categories casual
 - [ ] Frontmatter starts at byte 0 with `---`, closes with `\n---\n`
 - [ ] `name`, `description`, `version`, `author`, `license`, `metadata.hermes.{tags, related_skills}` all present
 - [ ] Name ≤ 64 chars, lowercase + hyphens
-- [ ] Description ≤ 1024 chars and starts with "Use when ..."
+- [ ] Description ≤ 1024 chars, trigger phrase self-contained within first 57 chars,
+      and starts with "Use when ..."
 - [ ] Total file ≤ 100,000 chars (aim for 8-15k)
 - [ ] Structure: `# Title` → `## Overview` → `## When to Use` → body → `## Common Pitfalls` → `## Verification Checklist`
 - [ ] Each ordered step has a checkable completion criterion
diff --git a/skills/software-development/node-inspect-debugger/SKILL.md b/skills/software-development/node-inspect-debugger/SKILL.md
index d5a34ef9b4a..5f3f1471025 100644
--- a/skills/software-development/node-inspect-debugger/SKILL.md
+++ b/skills/software-development/node-inspect-debugger/SKILL.md
@@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [debugging, nodejs, node-inspect, cdp, breakpoints, ui-tui]
-    related_skills: [systematic-debugging, python-debugpy, debugging-hermes-tui-commands]
+    related_skills: [systematic-debugging, python-debugpy]
 ---
 
 # Node.js Inspect Debugger
diff --git a/skills/software-development/plan/SKILL.md b/skills/software-development/plan/SKILL.md
index 10a5ae420b6..e97eb6abcd2 100644
--- a/skills/software-development/plan/SKILL.md
+++ b/skills/software-development/plan/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: plan
-description: "Plan mode: write an actionable markdown plan to .hermes/plans/, no execution. Bite-sized tasks, exact paths, complete code."
+description: Write a markdown plan to .hermes/plans/; no execution.
 version: 2.0.0
 author: Hermes Agent (writing-craft adapted from obra/superpowers)
 license: MIT
diff --git a/skills/software-development/python-debugpy/SKILL.md b/skills/software-development/python-debugpy/SKILL.md
index e16ab8bc28f..e57d8d91e25 100644
--- a/skills/software-development/python-debugpy/SKILL.md
+++ b/skills/software-development/python-debugpy/SKILL.md
@@ -8,7 +8,7 @@ platforms: [linux, macos]
 metadata:
   hermes:
     tags: [debugging, python, pdb, debugpy, breakpoints, dap, post-mortem]
-    related_skills: [systematic-debugging, node-inspect-debugger, debugging-hermes-tui-commands]
+    related_skills: [systematic-debugging, node-inspect-debugger]
 ---
 
 # Python Debugger (pdb + debugpy)
diff --git a/skills/software-development/simplify-code/SKILL.md b/skills/software-development/simplify-code/SKILL.md
index b6205091642..b1ca84fdc4f 100644
--- a/skills/software-development/simplify-code/SKILL.md
+++ b/skills/software-development/simplify-code/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: simplify-code
-description: "Parallel 3-agent cleanup of recent code changes."
-version: 1.0.0
+description: "Parallel 4-agent cleanup of recent code changes."
+version: 1.1.0
 author: Hermes Agent (inspired by Claude Code /simplify)
 license: MIT
 platforms: [linux, macos, windows]
@@ -13,13 +13,18 @@ metadata:
 
 # Simplify Code — Parallel Review & Cleanup
 
-Review your recent code changes with three focused reviewers running in
+Review your recent code changes with four focused reviewers running in
 parallel, aggregate their findings, and apply the fixes worth applying.
 
-**Core principle:** Three narrow reviewers beat one broad reviewer. Each one
+**This is a cleanup pass, not a bug hunt.** You are improving the quality of
+code that already works — removing duplication, flattening needless
+complexity, cutting waste, and deepening band-aid fixes. Do not go hunting
+for correctness bugs here; that's what `requesting-code-review` is for.
+
+**Core principle:** Four narrow reviewers beat one broad reviewer. Each one
 deeply searches the codebase for a single class of problem — reuse, quality,
-efficiency — without diluting its attention across all three. They run
-concurrently, so you pay the latency of one review, not three.
+efficiency, altitude — without diluting its attention across all four. They
+run concurrently, so you pay the latency of one review, not four.
 
 ## When to Use
 
@@ -33,14 +38,15 @@ Optional modifiers the user may add — honor them:
 
 - **Focus:** "simplify focus on efficiency" → run only the efficiency reviewer
   (or weight the aggregation toward it). Recognized focuses: `reuse`,
-  `quality`, `efficiency`.
+  `quality` (also accepts `simplification`), `efficiency`, `altitude`.
 - **Dry run:** "simplify but don't change anything" / "just report" → run the
-  three reviewers, present findings, apply NOTHING. Ask before applying.
+  four reviewers, present findings, apply NOTHING. Ask before applying.
 - **Scope:** "simplify the last commit" / "simplify staged" / "simplify
   src/foo.py" → narrow the diff source accordingly (see Phase 1).
 
-Do NOT auto-run this after every edit. It costs three subagents' worth of
-tokens — invoke it only when the user explicitly asks.
+Do NOT auto-run this after every edit or tack it onto the end of unrelated
+tasks. It costs four subagents' worth of tokens — invoke it only when the
+user explicitly asks.
 
 ## The Process
 
@@ -69,16 +75,24 @@ recently created/edited in this session. If you genuinely can't find any
 changed code, say so and stop — there's nothing to simplify.
 
 Capture the full diff text. Note its size: if it's very large (say >2000
-changed lines), warn the user that three subagents each carrying the full diff
+changed lines), warn the user that four subagents each carrying the full diff
 will be token-heavy, and offer to scope it down (per-directory, per-commit)
 before proceeding.
 
-### Phase 2 — Launch three reviewers in parallel
+### Phase 2 — Launch four reviewers in parallel
 
-Use `delegate_task` **batch mode** — pass all three tasks in one `tasks`
-array so they run concurrently. Three is the right fan-out for this pattern;
-it's well within the `delegation.max_concurrent_children` budget on any
-default install.
+Use `delegate_task` **batch mode** — pass all four tasks in one `tasks`
+array so they run concurrently. Four is the right fan-out for this pattern;
+it's within the `delegation.max_concurrent_children` budget on any default
+install.
+
+**No delegation available?** If you can't call `delegate_task` in this
+context (you're a leaf subagent, delegation is disabled, or the budget is
+exhausted), do NOT skip the review or drop angles. Work through all four
+reviewer angles yourself, sequentially, in this context — same search
+standards, same finding format. Then say clearly in your final summary that
+this was a single-pass inline review, not the parallel fan-out, so the user
+knows what actually ran.
 
 Give **every** reviewer the **complete diff** (not fragments — cross-file
 issues hide in the gaps) plus the absolute repo path so they can search the
@@ -90,10 +104,13 @@ Tell each reviewer to:
 - **Apply Chesterton's Fence:** before flagging anything for removal, run
   `git blame` on the line to understand why it exists. If you can't determine
   the original purpose, mark it `confidence: low` — don't guess.
-- Report findings as structured output with confidence and risk:
+- Report findings as structured output with the concrete cost, confidence,
+  and risk:
   ```
-  file:line → problem → suggested fix | confidence: high/medium/low | risk: SAFE/CAREFUL/RISKY
+  file:line → problem → cost (what's duplicated/wasted/harder to maintain) → suggested fix | confidence: high/medium/low | risk: SAFE/CAREFUL/RISKY
   ```
+  The **cost** field forces each finding to justify itself — a finding that
+  can't articulate what the problem actually costs is probably a nit.
   - **SAFE** = proven not to affect behavior (unused imports, commented-out
     code, pass-through wrappers). Auto-apply these.
   - **CAREFUL** = improves without changing semantics (rename local variable,
@@ -104,7 +121,7 @@ Tell each reviewer to:
 - Skip nits and style-only churn. Only flag things that materially improve
   the code.
 
-Pass these three goals (drop any the user's focus excludes):
+Pass these four goals (drop any the user's focus excludes):
 
 **Reviewer 1 — Code Reuse**
 > Review this diff for code that duplicates functionality already in the
@@ -124,7 +141,9 @@ Pass these three goals (drop any the user's focus excludes):
 > blocks that should share an abstraction); leaky abstractions (exposing
 > internals, breaking an existing encapsulation boundary); stringly-typed
 > code (raw strings where a constant/enum/registry already exists — check the
-> canonical registries before flagging); AI-generated slop patterns (extra
+> canonical registries before flagging); deeply nested conditionals (ternary
+> chains, 3+-level if/else pyramids — flatten with guard clauses, early
+> returns, or a lookup table); AI-generated slop patterns (extra
 > comments restating obvious code like `// increment counter` above `count++`;
 > unnecessary defensive null-checks on already-validated inputs; `as any`
 > casts that bypass the type system; patterns inconsistent with the rest of
@@ -137,17 +156,41 @@ Pass these three goals (drop any the user's focus excludes):
 > hot-path bloat (heavy/blocking work on startup or per-request paths);
 > TOCTOU anti-patterns (existence pre-checks before an op instead of doing
 > the op and handling the error); memory issues (unbounded growth, missing
-> cleanup, listener/handle leaks); overly broad reads (loading whole files
-> when a slice would do); silent failures (empty catch blocks, ignored error
-> returns, `except: pass`, `.catch(() => {})` with no handling, error
-> propagation gaps — these hide bugs and should at minimum log before
-> swallowing). For each, give the concrete fix and why it's faster or safer.
+> cleanup, listener/handle leaks; long-lived callbacks or objects built as
+> closures that capture the whole enclosing scope — everything captured
+> stays alive as long as the object does, so prefer a small class or
+> explicit-fields struct that copies only what it needs); overly broad reads
+> (loading whole files when a slice would do); silent failures (empty catch
+> blocks, ignored error returns, `except: pass`, `.catch(() => {})` with no
+> handling, error propagation gaps — these hide bugs and should at minimum
+> log before swallowing). For each, give the concrete fix and why it's
+> faster or safer.
+
+**Reviewer 4 — Altitude**
+> Review this diff for changes implemented at the wrong depth — band-aids
+> layered on top of shared infrastructure instead of fixes to the
+> infrastructure itself. Signs of a too-shallow fix: a special case added to
+> a generic code path to handle one caller (an `if (caller == X)` branch, a
+> type check, a magic-value escape hatch); a symptom patched at the call
+> site while sibling call sites keep the same flaw; a workaround stacked on
+> an earlier workaround; a wrapper added to avoid touching the thing that
+> actually needs changing; configuration or flags introduced to route around
+> a broken default instead of fixing the default. For each, identify the
+> underlying mechanism the change is dodging and describe the deeper fix —
+> generalize the shared path, fix the root default, or fix the whole bug
+> class — and honestly note when the deeper fix is large enough that it
+> should be its own task rather than part of this cleanup. Read the
+> surrounding code and `git blame` first: what looks like a band-aid is
+> sometimes a deliberate boundary (compat shims, staged migrations,
+> vendored-code isolation). Don't flag those.
 
 ### Phase 3 — Aggregate and apply
 
-Wait for all three to return (batch mode returns them together).
+Wait for all four to return (batch mode returns them together).
 
-1. **Merge** the findings into one list, deduping where reviewers overlap.
+1. **Merge** the findings into one list, deduping where reviewers overlap —
+   when two findings target the same line or the same underlying mechanism,
+   collapse them into one.
 2. **Discard false positives** — you have the most context; you don't have to
    argue with a reviewer, just drop weak or wrong suggestions silently.
 3. **Resolve conflicts.** Reviewers can disagree (Reviewer 1: "use existing
@@ -164,20 +207,23 @@ Wait for all three to return (batch mode returns them together).
      after each file. Revert any that break.
    - **RISKY last** (flag for review — do NOT auto-apply): N+1 restructuring,
      public API changes, concurrency fixes, error-handling changes. Present
-     each with risk description and test coverage status.
+     each with risk description and test coverage status. Altitude findings
+     usually land here — deepening a fix means touching shared
+     infrastructure, so present the deeper fix and let the user decide
+     whether to do it now or as a follow-up.
    If the user opted for a dry run, present all three tiers and apply nothing.
 5. **Verify** you didn't break anything: run the project's targeted tests for
    the touched files (not the full suite), and re-run any linter/type check the
    repo uses. If a fix breaks a test, revert that one fix and report it.
 6. **Summarize** what you changed: a short list of applied fixes grouped by
    reviewer category and risk tier, plus any findings you deliberately skipped
-   and why.
+   and why. If you ran inline (no delegation), say so here.
 
 ## Pitfalls
 
-- **Don't fan out wider than ~3.** More reviewers means more cost and more
-  conflicting suggestions to reconcile, not better coverage. Three categories
-  cover the space.
+- **Don't fan out wider than 4.** More reviewers means more cost and more
+  conflicting suggestions to reconcile, not better coverage. The four
+  categories cover the space.
 - **Give the WHOLE diff to each reviewer.** Splitting the diff across reviewers
   defeats the design — cross-file duplication and N+1s only show up with the
   full picture.
@@ -186,12 +232,19 @@ Wait for all three to return (batch mode returns them together).
   `file:line` evidence; drop findings that lack it.
 - **Apply ≠ rewrite.** This is cleanup of the user's recent changes, not a
   license to refactor the whole module. Keep edits scoped to what the diff
-  touched plus the minimal surrounding change a fix requires.
+  touched plus the minimal surrounding change a fix requires. Altitude
+  findings are the exception that proves the rule: when the right fix is
+  deeper than the diff, FLAG it — don't unilaterally rebuild the shared
+  mechanism inside a cleanup pass.
+- **Don't drift into bug-hunting.** If a reviewer surfaces a genuine
+  correctness bug, report it prominently — but as a separate "found a bug"
+  note, not folded into cleanup fixes. Correctness review is a different
+  pass with different verification standards.
 - **Respect project conventions.** If the repo has AGENTS.md / CLAUDE.md /
   HERMES.md or a linter config, fold those rules into the reviewer prompts so
   suggestions match house style instead of fighting it.
 - **Large diffs blow context.** If the diff is huge, scope it down before
-  delegating — three subagents each carrying a 5000-line diff is expensive and
+  delegating — four subagents each carrying a 5000-line diff is expensive and
   may truncate.
 - **Over-trusting dead code tools.** `knip`, `ts-prune`, and `depcheck` flag
   exports that ARE used dynamically (string-based imports, reflection). Always
@@ -203,10 +256,15 @@ Wait for all three to return (batch mode returns them together).
 - **Removing "unnecessary" error handling.** An empty catch block or ignored
   error might be intentional — the error is expected and benign in that
   context. Flag it, don't remove it; let the human decide.
+- **Not every special case is a band-aid.** Compat shims, staged migrations,
+  and isolation layers around vendored code look like altitude violations but
+  are deliberate design. Check `git blame` and surrounding comments before
+  flagging; when the intent is unclear, mark `confidence: low`.
 
 ## Related
 
 If your install has the `subagent-driven-development` skill (optional), it
 covers the complementary case: parallel review *during* implementation, per
 task. This skill is the standalone *after-the-fact* cleanup pass. Use
-`requesting-code-review` for the pre-commit security/quality gate.
+`requesting-code-review` for the pre-commit security/quality gate — that's
+the bug hunt; this is the cleanup.
diff --git a/tests/acp/test_entry.py b/tests/acp/test_entry.py
index 1d881565bd9..7ceee366062 100644
--- a/tests/acp/test_entry.py
+++ b/tests/acp/test_entry.py
@@ -23,6 +23,50 @@ def test_main_enables_unstable_protocol(monkeypatch):
     assert calls["kwargs"]["use_unstable_protocol"] is True
 
 
+def test_main_skips_configured_mcp_discovery_when_requested(monkeypatch):
+    discovery_calls = []
+
+    async def fake_run_agent(agent, **kwargs):
+        pass
+
+    monkeypatch.setattr(entry, "_setup_logging", lambda: None)
+    monkeypatch.setattr(entry, "_load_env", lambda: None)
+    monkeypatch.setenv("HERMES_ACP_SKIP_CONFIGURED_MCP", "1")
+    monkeypatch.setattr(
+        "tools.mcp_tool.discover_mcp_tools",
+        lambda: discovery_calls.append(True),
+    )
+    monkeypatch.setattr(acp, "run_agent", fake_run_agent)
+
+    entry.main([])
+
+    assert discovery_calls == []
+
+
+@pytest.mark.parametrize("skip_value", [None, "", "0", "false"])
+def test_main_discovers_configured_mcp_when_skip_is_not_enabled(monkeypatch, skip_value):
+    discovery_calls = []
+
+    async def fake_run_agent(agent, **kwargs):
+        pass
+
+    monkeypatch.setattr(entry, "_setup_logging", lambda: None)
+    monkeypatch.setattr(entry, "_load_env", lambda: None)
+    if skip_value is None:
+        monkeypatch.delenv("HERMES_ACP_SKIP_CONFIGURED_MCP", raising=False)
+    else:
+        monkeypatch.setenv("HERMES_ACP_SKIP_CONFIGURED_MCP", skip_value)
+    monkeypatch.setattr(
+        "tools.mcp_tool.discover_mcp_tools",
+        lambda: discovery_calls.append(True),
+    )
+    monkeypatch.setattr(acp, "run_agent", fake_run_agent)
+
+    entry.main([])
+
+    assert discovery_calls == [True]
+
+
 def test_main_version_prints_without_starting_server(monkeypatch, capsys):
     monkeypatch.setattr(entry, "_setup_logging", lambda: (_ for _ in ()).throw(AssertionError("started server")))
 
diff --git a/tests/acp/test_named_provider_catalogs.py b/tests/acp/test_named_provider_catalogs.py
new file mode 100644
index 00000000000..a59c8c8bdfc
--- /dev/null
+++ b/tests/acp/test_named_provider_catalogs.py
@@ -0,0 +1,203 @@
+"""Tests for named user-defined provider entries in the ACP model selector.
+
+Named endpoints from the ``providers:`` mapping (and legacy
+``custom_providers:`` list) are invisible to canonical provider enumeration,
+so ``_build_model_state`` must append them explicitly for ACP clients to
+offer them — the TUI ``/model`` picker already renders these entries
+(#47039 implemented named endpoints for the TUI surface only).
+"""
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from acp_adapter.server import HermesACPAgent, _named_custom_provider_catalogs
+from acp_adapter.session import SessionManager
+from acp.schema import SessionModelState
+
+
+MANTLE_URL = "https://bedrock-mantle.us-east-1.api.aws/openai/v1"
+
+
+def _cfg(providers=None, custom_providers=None):
+    cfg = {}
+    if providers is not None:
+        cfg["providers"] = providers
+    if custom_providers is not None:
+        cfg["custom_providers"] = custom_providers
+    return cfg
+
+
+class TestNamedCustomProviderCatalogs:
+    def test_declared_default_model_survives_failed_discovery(self, monkeypatch):
+        """Endpoints without a /models route keep their declared models."""
+        monkeypatch.setenv("BEDROCK_MANTLE_API_KEY", "test-key")
+        cfg = _cfg(
+            providers={
+                "bedrock-mantle": {
+                    "name": "AWS Bedrock Mantle",
+                    "base_url": MANTLE_URL,
+                    "key_env": "BEDROCK_MANTLE_API_KEY",
+                    "api_mode": "codex_responses",
+                    "default_model": "openai.gpt-5.5",
+                }
+            }
+        )
+        with patch("hermes_cli.config.load_config", return_value=cfg), patch(
+            "hermes_cli.models.fetch_api_models", return_value=None
+        ):
+            catalogs = _named_custom_provider_catalogs()
+
+        assert catalogs == [
+            (
+                "custom:bedrock-mantle",
+                "AWS Bedrock Mantle",
+                [("openai.gpt-5.5", "")],
+            )
+        ]
+
+    def test_live_discovery_extends_declared_models(self, monkeypatch):
+        monkeypatch.setenv("SOME_KEY", "k")
+        cfg = _cfg(
+            providers={
+                "relay": {
+                    "name": "Relay",
+                    "base_url": "https://relay.example/v1",
+                    "key_env": "SOME_KEY",
+                    "default_model": "model-a",
+                }
+            }
+        )
+        with patch("hermes_cli.config.load_config", return_value=cfg), patch(
+            "hermes_cli.models.fetch_api_models",
+            return_value=["model-a", "model-b"],
+        ):
+            catalogs = _named_custom_provider_catalogs()
+
+        assert len(catalogs) == 1
+        slug, label, models = catalogs[0]
+        assert slug == "custom:relay"
+        assert [m for m, _ in models] == ["model-a", "model-b"]
+
+    def test_declared_models_dict_included(self, monkeypatch):
+        monkeypatch.setenv("SOME_KEY", "k")
+        cfg = _cfg(
+            providers={
+                "relay": {
+                    "name": "Relay",
+                    "base_url": "https://relay.example/v1",
+                    "key_env": "SOME_KEY",
+                    "default_model": "model-a",
+                    "models": {"model-b": {}, "model-c": {}},
+                }
+            }
+        )
+        with patch("hermes_cli.config.load_config", return_value=cfg), patch(
+            "hermes_cli.models.fetch_api_models", return_value=None
+        ):
+            catalogs = _named_custom_provider_catalogs()
+
+        assert [m for m, _ in catalogs[0][2]] == ["model-a", "model-b", "model-c"]
+
+    def test_disabled_provider_skipped(self, monkeypatch):
+        monkeypatch.setenv("SOME_KEY", "k")
+        cfg = _cfg(
+            providers={
+                "off": {
+                    "name": "Disabled Endpoint",
+                    "base_url": "https://off.example/v1",
+                    "key_env": "SOME_KEY",
+                    "default_model": "m",
+                    "enabled": False,
+                }
+            }
+        )
+        with patch("hermes_cli.config.load_config", return_value=cfg), patch(
+            "hermes_cli.models.fetch_api_models", return_value=None
+        ):
+            assert _named_custom_provider_catalogs() == []
+
+    def test_no_credential_and_no_declared_models_skipped(self, monkeypatch):
+        monkeypatch.delenv("MISSING_KEY", raising=False)
+        cfg = _cfg(
+            providers={
+                "bare": {
+                    "name": "Bare",
+                    "base_url": "https://bare.example/v1",
+                    "key_env": "MISSING_KEY",
+                }
+            }
+        )
+        with patch("hermes_cli.config.load_config", return_value=cfg), patch(
+            "hermes_cli.models.fetch_api_models", return_value=None
+        ):
+            assert _named_custom_provider_catalogs() == []
+
+    def test_legacy_custom_providers_list_included(self, monkeypatch):
+        monkeypatch.setenv("SOME_KEY", "k")
+        cfg = _cfg(
+            custom_providers=[
+                {
+                    "name": "Legacy Endpoint",
+                    "base_url": "https://legacy.example/v1",
+                    "key_env": "SOME_KEY",
+                    "model": "legacy-model",
+                }
+            ]
+        )
+        with patch("hermes_cli.config.load_config", return_value=cfg), patch(
+            "hermes_cli.models.fetch_api_models", return_value=None
+        ):
+            catalogs = _named_custom_provider_catalogs()
+
+        assert catalogs == [
+            ("custom:legacy-endpoint", "Legacy Endpoint", [("legacy-model", "")])
+        ]
+
+
+class TestModelStateIncludesNamedProviders:
+    @pytest.mark.asyncio
+    async def test_named_provider_models_appear_in_model_state(self):
+        manager = SessionManager(
+            agent_factory=lambda: SimpleNamespace(
+                model="gpt-5.4", provider="openai-codex"
+            )
+        )
+        acp_agent = HermesACPAgent(session_manager=manager)
+
+        with patch(
+            "hermes_cli.models.curated_models_for_provider",
+            return_value=[("gpt-5.4", "recommended")],
+        ), patch(
+            "acp_adapter.server._named_custom_provider_catalogs",
+            return_value=[
+                (
+                    "custom:bedrock-mantle",
+                    "AWS Bedrock Mantle",
+                    [("openai.gpt-5.5", "")],
+                )
+            ],
+        ):
+            resp = await acp_agent.new_session(cwd="/tmp")
+
+        assert isinstance(resp.models, SessionModelState)
+        ids = [m.model_id for m in resp.models.available_models]
+        # Current provider's models come first, named endpoints after.
+        assert ids[0] == "openai-codex:gpt-5.4"
+        assert "custom:bedrock-mantle:openai.gpt-5.5" in ids
+        named = next(
+            m
+            for m in resp.models.available_models
+            if m.model_id == "custom:bedrock-mantle:openai.gpt-5.5"
+        )
+        assert "AWS Bedrock Mantle" in (named.description or "")
+
+    def test_selector_choice_id_round_trips_through_parse_model_input(self):
+        """The encoded choice id must resolve back to the named provider."""
+        from hermes_cli.models import parse_model_input
+
+        choice_id = "custom:bedrock-mantle:openai.gpt-5.5"
+        provider, model = parse_model_input(choice_id, "bedrock")
+        assert provider == "custom:bedrock-mantle"
+        assert model == "openai.gpt-5.5"
diff --git a/tests/acp/test_server.py b/tests/acp/test_server.py
index 1d9157f44fb..66f50b1d9a4 100644
--- a/tests/acp/test_server.py
+++ b/tests/acp/test_server.py
@@ -36,7 +36,11 @@ from acp.schema import (
     UserMessageChunk,
 )
 from acp_adapter.auth import TERMINAL_SETUP_AUTH_METHOD_ID
-from acp_adapter.server import HermesACPAgent, HERMES_VERSION
+from acp_adapter.server import (
+    ACP_MAX_MODELS_PER_PROVIDER,
+    HermesACPAgent,
+    HERMES_VERSION,
+)
 from acp_adapter.session import SessionManager
 from hermes_state import SessionDB
 
@@ -238,23 +242,167 @@ class TestSessionOps:
         assert state.cwd == "/home/user/project"
 
     @pytest.mark.asyncio
-    async def test_new_session_returns_model_state(self):
+    async def test_new_session_returns_authenticated_cross_provider_model_state(self):
         manager = SessionManager(
-            agent_factory=lambda: SimpleNamespace(model="gpt-5.4", provider="openai-codex")
+            agent_factory=lambda: SimpleNamespace(
+                model="gpt-5.4",
+                provider="openai-codex",
+                base_url="https://api.openai.com/v1",
+            )
         )
         acp_agent = HermesACPAgent(session_manager=manager)
+        picker_context = MagicMock()
+        picker_context.with_overrides.return_value = picker_context
+        payload = {
+            "providers": [
+                {
+                    "slug": "anthropic",
+                    "name": "Anthropic",
+                    "models": ["claude-sonnet-4-6", "claude-sonnet-4-6"],
+                },
+                {
+                    "slug": "openai-codex",
+                    "name": "OpenAI Codex",
+                    "models": [
+                        {"id": "gpt-5.4"},
+                        "gpt-5.4-mini",
+                    ],
+                },
+            ],
+        }
 
-        with patch(
-            "hermes_cli.models.curated_models_for_provider",
-            return_value=[("gpt-5.4", "recommended"), ("gpt-5.4-mini", "")],
+        with (
+            patch("hermes_cli.inventory.load_picker_context", return_value=picker_context),
+            patch("hermes_cli.inventory.build_models_payload", return_value=payload) as build_payload,
         ):
             resp = await acp_agent.new_session(cwd="/tmp")
 
         assert isinstance(resp.models, SessionModelState)
         assert resp.models.current_model_id == "openai-codex:gpt-5.4"
-        assert resp.models.available_models[0].model_id == "openai-codex:gpt-5.4"
-        assert resp.models.available_models[0].description is not None
-        assert "Provider:" in resp.models.available_models[0].description
+        assert [model.model_id for model in resp.models.available_models] == [
+            "anthropic:claude-sonnet-4-6",
+            "openai-codex:gpt-5.4",
+            "openai-codex:gpt-5.4-mini",
+        ]
+        assert [model.name for model in resp.models.available_models] == [
+            "Anthropic · claude-sonnet-4-6",
+            "OpenAI Codex · gpt-5.4",
+            "OpenAI Codex · gpt-5.4-mini",
+        ]
+        assert resp.models.available_models[1].description is not None
+        assert "current" in resp.models.available_models[1].description
+        picker_context.with_overrides.assert_called_once_with(
+            current_provider="openai-codex",
+            current_model="gpt-5.4",
+            current_base_url="https://api.openai.com/v1",
+        )
+        build_payload.assert_called_once_with(
+            picker_context,
+            explicit_only=True,
+            include_unconfigured=False,
+            picker_hints=False,
+            canonical_order=True,
+            pricing=False,
+            capabilities=False,
+            refresh=False,
+            probe_custom_providers=False,
+            probe_current_custom_provider=False,
+            max_models=ACP_MAX_MODELS_PER_PROVIDER,
+        )
+
+    @pytest.mark.asyncio
+    async def test_new_session_bounds_models_and_keeps_current_selection(self):
+        """A large provider catalog stays bounded and never drops the selection.
+
+        Asserts the contract (bounded row + current model reachable), not a
+        specific catalog size, so growing the shared inventory cannot break it.
+        """
+        oversized = [
+            f"model-{index}" for index in range(ACP_MAX_MODELS_PER_PROVIDER * 2)
+        ]
+        current = oversized[-1]
+        manager = SessionManager(
+            agent_factory=lambda: SimpleNamespace(
+                model=current,
+                provider="openrouter",
+                base_url="",
+            )
+        )
+        acp_agent = HermesACPAgent(session_manager=manager)
+        picker_context = MagicMock()
+        picker_context.with_overrides.return_value = picker_context
+
+        def bounded_payload(_context, **kwargs):
+            # Mirror the shared inventory's per-provider slicing so the test
+            # exercises the cap Hermes actually requests.
+            cap = kwargs.get("max_models")
+            models = oversized if cap is None else oversized[:cap]
+            return {
+                "providers": [
+                    {"slug": "openrouter", "name": "OpenRouter", "models": models}
+                ]
+            }
+
+        with (
+            patch("hermes_cli.inventory.load_picker_context", return_value=picker_context),
+            patch("hermes_cli.inventory.build_models_payload", side_effect=bounded_payload),
+        ):
+            resp = await acp_agent.new_session(cwd="/tmp")
+
+        assert isinstance(resp.models, SessionModelState)
+        model_ids = [model.model_id for model in resp.models.available_models]
+
+        # Bounded: the emitted list must not exceed the requested cap, plus at
+        # most the one current-model entry re-inserted by the fallback.
+        assert len(model_ids) <= ACP_MAX_MODELS_PER_PROVIDER + 1
+        # Selection preserved: a current model outside the cap is still offered.
+        assert resp.models.current_model_id == f"openrouter:{current}"
+        assert resp.models.current_model_id in model_ids
+        # No duplicates leak through the dedup path.
+        assert len(model_ids) == len(set(model_ids))
+
+    @pytest.mark.asyncio
+    async def test_new_session_keeps_current_model_missing_from_inventory(self):
+        manager = SessionManager(
+            agent_factory=lambda: SimpleNamespace(
+                model="claude-custom",
+                provider="anthropic",
+                base_url="https://api.anthropic.com",
+            )
+        )
+        acp_agent = HermesACPAgent(session_manager=manager)
+        picker_context = MagicMock()
+        picker_context.with_overrides.return_value = picker_context
+        payload = {
+            "providers": [
+                {
+                    "slug": "anthropic",
+                    "name": "Anthropic",
+                    "models": ["claude-sonnet-4-6"],
+                },
+                {
+                    "slug": "openai-codex",
+                    "name": "OpenAI Codex",
+                    "models": ["gpt-5.4"],
+                },
+            ],
+        }
+
+        with (
+            patch("hermes_cli.inventory.load_picker_context", return_value=picker_context),
+            patch("hermes_cli.inventory.build_models_payload", return_value=payload),
+        ):
+            resp = await acp_agent.new_session(cwd="/tmp")
+
+        assert resp.models is not None
+        assert resp.models.current_model_id == "anthropic:claude-custom"
+        assert [model.model_id for model in resp.models.available_models] == [
+            "anthropic:claude-custom",
+            "anthropic:claude-sonnet-4-6",
+            "openai-codex:gpt-5.4",
+        ]
+        assert resp.models.available_models[0].name == "Anthropic · claude-custom"
+        assert resp.models.available_models[0].description == "Provider: Anthropic • current"
 
     @pytest.mark.asyncio
     async def test_available_commands_include_help(self, agent):
@@ -1106,6 +1254,9 @@ class TestSessionConfiguration:
         with patch("run_agent.AIAgent", side_effect=fake_agent):
             acp_agent = HermesACPAgent(session_manager=manager)
             state = manager.create_session(cwd="/tmp")
+            assert state.agent.provider == "openrouter"
+            assert state.agent.base_url == "https://openrouter.example/v1"
+            assert state.agent.api_mode == "chat_completions"
             result = await acp_agent.set_session_model(
                 model_id="anthropic:claude-sonnet-4-6",
                 session_id=state.session_id,
@@ -1115,8 +1266,58 @@ class TestSessionConfiguration:
         assert state.model == "claude-sonnet-4-6"
         assert state.agent.provider == "anthropic"
         assert state.agent.base_url == "https://anthropic.example/v1"
+        assert state.agent.api_mode == "anthropic_messages"
         assert runtime_calls[-1] == "anthropic"
 
+    @pytest.mark.asyncio
+    async def test_set_session_model_plain_choice_keeps_current_provider_runtime(
+        self, tmp_path, monkeypatch
+    ):
+        manager = SessionManager(
+            db=SessionDB(tmp_path / "state.db"),
+            agent_factory=lambda: SimpleNamespace(
+                model="old-model",
+                provider="openrouter",
+                base_url="https://openrouter.ai/api/v1",
+                api_mode="chat_completions",
+            ),
+        )
+        acp_agent = HermesACPAgent(session_manager=manager)
+        state = manager.create_session(cwd="/tmp")
+        replacement_agent = SimpleNamespace(
+            model="new-model",
+            provider="openrouter",
+            base_url="https://openrouter.ai/api/v1",
+            api_mode="chat_completions",
+        )
+        make_agent = MagicMock(return_value=replacement_agent)
+        monkeypatch.setattr(manager, "_make_agent", make_agent)
+        monkeypatch.setattr(
+            "hermes_cli.models.parse_model_input",
+            lambda raw, current: (current, raw),
+        )
+        monkeypatch.setattr(
+            "hermes_cli.models.detect_provider_for_model",
+            lambda model, current: None,
+        )
+
+        result = await acp_agent.set_session_model(
+            model_id="new-model",
+            session_id=state.session_id,
+        )
+
+        assert isinstance(result, SetSessionModelResponse)
+        assert state.model == "new-model"
+        assert state.agent is replacement_agent
+        make_agent.assert_called_once_with(
+            session_id=state.session_id,
+            cwd="/tmp",
+            model="new-model",
+            requested_provider="openrouter",
+            base_url="https://openrouter.ai/api/v1",
+            api_mode="chat_completions",
+        )
+
 
 # ---------------------------------------------------------------------------
 # prompt
@@ -1438,6 +1639,47 @@ class TestPrompt:
             text and "[plugin appended this]" in text for text in all_texts
         ), f"expected transformed final to be delivered, got: {all_texts!r}"
 
+    @pytest.mark.asyncio
+    async def test_prompt_pins_the_session_cwd_for_the_turn(self, agent, tmp_path):
+        """The turn must resolve the ACP client's cwd, not the Hermes workspace.
+
+        ``resolve_agent_cwd()`` is what the system prompt reports as "Current
+        working directory". When it is left unpinned it falls back to
+        TERMINAL_CWD / the launch dir, so the prompt advertises one root while
+        the tools are rooted at the editor's project. The model then emits
+        absolute paths under the advertised root and the edit silently lands
+        outside the workspace the client asked for.
+        """
+        workspace = tmp_path / "project"
+        workspace.mkdir()
+
+        new_resp = await agent.new_session(cwd=str(workspace))
+        state = agent.session_manager.get_session(new_resp.session_id)
+
+        observed = {}
+
+        def capture_cwd(*args, **kwargs):
+            from agent.runtime_cwd import resolve_agent_cwd
+
+            observed["cwd"] = str(resolve_agent_cwd())
+            return {"final_response": "ok", "messages": []}
+
+        state.agent.run_conversation = capture_cwd
+
+        mock_conn = MagicMock(spec=acp.Client)
+        mock_conn.session_update = AsyncMock()
+        agent._conn = mock_conn
+
+        await agent.prompt(
+            prompt=[TextContentBlock(type="text", text="hello")],
+            session_id=new_resp.session_id,
+        )
+
+        assert observed.get("cwd") == str(workspace), (
+            "the turn resolved "
+            f"{observed.get('cwd')!r} instead of the ACP client's cwd "
+            f"{str(workspace)!r}"
+        )
 
     @pytest.mark.asyncio
     async def test_prompt_auto_titles_session(self, agent):
@@ -1799,6 +2041,77 @@ class TestSlashCommands:
         result = agent._handle_slash_command("/nonexistent", state)
         assert result is None
 
+    def test_slash_handler_pins_the_session_cwd(self, agent, mock_manager, tmp_path):
+        """A slash handler must resolve the client's cwd, not the install tree.
+
+        Slash commands run on the event-loop thread, outside the per-turn
+        ``copy_context()`` that pins the cwd for the agent call. ``/compress``
+        reaches ``agent._build_system_prompt()``, whose "Current working
+        directory" line comes from ``resolve_agent_cwd()`` — and the rebuilt
+        prompt is PERSISTED as the session's cached prompt, so an unpinned
+        handler poisons every later turn even though the turn is pinned.
+        """
+        workspace = tmp_path / "project"
+        workspace.mkdir()
+        state = mock_manager.create_session(cwd=str(workspace))
+        state.cwd = str(workspace)
+        state.agent.model = "test-model"
+        state.agent.provider = "openrouter"
+        state.history = [
+            {"role": "user", "content": "one"},
+            {"role": "assistant", "content": "two"},
+        ]
+        state.agent.compression_enabled = True
+        state.agent._cached_system_prompt = "system"
+        state.agent.tools = None
+        state.agent._session_db = None
+
+        observed = {}
+
+        def _compress(messages, system_prompt, **kwargs):
+            from agent.runtime_cwd import resolve_agent_cwd
+
+            observed["cwd"] = str(resolve_agent_cwd())
+            return [{"role": "user", "content": "summary"}], "new-system"
+
+        state.agent._compress_context = _compress
+
+        with (
+            patch.object(agent.session_manager, "save_session"),
+            patch(
+                "agent.model_metadata.estimate_request_tokens_rough",
+                side_effect=[40, 12],
+            ),
+        ):
+            agent._handle_slash_command("/compress", state)
+
+        assert observed.get("cwd") == str(workspace), (
+            "the slash handler resolved "
+            f"{observed.get('cwd')!r} instead of the ACP client's cwd "
+            f"{str(workspace)!r}"
+        )
+
+    def test_slash_handler_cwd_pin_does_not_leak(self, agent, mock_manager, tmp_path):
+        """The pin is scoped to the handler's own context copy.
+
+        Concurrent ACP sessions share the event loop, so a handler that pinned
+        the ambient context would leave its workspace bound for whatever runs
+        next. Asserting the ambient value is unchanged after dispatch keeps the
+        fix from trading one cross-session leak for another.
+        """
+        from agent.runtime_cwd import resolve_agent_cwd
+
+        workspace = tmp_path / "project"
+        workspace.mkdir()
+        state = mock_manager.create_session(cwd=str(workspace))
+        state.cwd = str(workspace)
+        state.agent.model = "test-model"
+        state.agent.provider = "openrouter"
+
+        before = str(resolve_agent_cwd())
+        agent._handle_slash_command("/help", state)
+        assert str(resolve_agent_cwd()) == before
+
     @pytest.mark.asyncio
     async def test_slash_command_intercepted_in_prompt(self, agent, mock_manager):
         """Slash commands should be handled without calling the LLM."""
diff --git a/tests/agent/test_anthropic_adapter.py b/tests/agent/test_anthropic_adapter.py
index ae99f950f73..9a0de290400 100644
--- a/tests/agent/test_anthropic_adapter.py
+++ b/tests/agent/test_anthropic_adapter.py
@@ -1134,6 +1134,26 @@ class TestConvertMessages:
         assert isinstance(system, list)
         assert system[0]["cache_control"] == {"type": "ephemeral"}
 
+    def test_static_system_prefix_markers_are_preserved(self):
+        messages = apply_anthropic_cache_control(
+            [
+                {"role": "system", "content": "stable\n\nsession context"},
+                {"role": "user", "content": "Hi"},
+            ],
+            static_system_prefix="stable",
+        )
+
+        system, _ = convert_messages_to_anthropic(messages)
+
+        assert system == [
+            {"type": "text", "text": "stable", "cache_control": {"type": "ephemeral"}},
+            {
+                "type": "text",
+                "text": "\n\nsession context",
+                "cache_control": {"type": "ephemeral"},
+            },
+        ]
+
     def test_assistant_cache_control_blocks_are_preserved(self):
         messages = apply_anthropic_cache_control([
             {"role": "system", "content": "System prompt"},
@@ -2634,3 +2654,365 @@ class TestConvertToolsToAnthropicDedup:
 
     def test_none_tools_returns_empty(self):
         assert convert_tools_to_anthropic(None) == []
+
+
+class TestBlankTextBlockFiltering:
+    """Regression tests for blank text block filtering in _convert_assistant_message.
+
+    Bedrock and strict Anthropic-compatible endpoints reject text blocks where
+    "text" is empty or whitespace-only with HTTP 400. Both the normal list-
+    content path and the ordered-replay fast path must drop such blocks while
+    preserving tool_use and other block types, and must relocate (not lose)
+    any cache_control marker attached to the dropped block.
+    """
+
+    def _convert(self, message):
+        from agent.anthropic_adapter import _convert_assistant_message
+        return _convert_assistant_message(message)
+
+    def test_normal_path_filters_empty_text_block_alongside_tool_calls(self):
+        """Content list with empty text + tool_calls: empty text must be dropped."""
+        msg = {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": ""},
+                {"type": "tool_use", "id": "call_1", "name": "web_search",
+                 "input": {"query": "test"}},
+            ],
+        }
+        result = self._convert(msg)
+        blocks = result["content"]
+        text_blocks = [b for b in blocks if b.get("type") == "text"]
+        tool_blocks = [b for b in blocks if b.get("type") == "tool_use"]
+        assert len(text_blocks) == 0, f"Empty text block not filtered: {text_blocks}"
+        assert len(tool_blocks) == 1
+
+    def test_normal_path_filters_whitespace_only_text_block(self):
+        """Whitespace-only text (spaces, newlines) must also be filtered."""
+        msg = {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": "   \n  "},
+                {"type": "tool_use", "id": "call_2", "name": "terminal",
+                 "input": {"command": "ls"}},
+            ],
+        }
+        result = self._convert(msg)
+        blocks = result["content"]
+        text_blocks = [b for b in blocks if b.get("type") == "text"]
+        assert len(text_blocks) == 0, f"Whitespace text block not filtered: {text_blocks}"
+
+    def test_normal_path_filters_none_text_block_without_crashing(self):
+        """Regression (review of #63228): text=None must not raise
+        AttributeError. _convert_content_part_to_anthropic() can preserve
+        None from an invalid upstream input text block -- a bare .strip()
+        on blk.get("text", "") crashes because .get() only substitutes the
+        default when the key is ABSENT, not when it's present with value None."""
+        msg = {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": None},
+                {"type": "tool_use", "id": "call_none", "name": "web_search",
+                 "input": {"query": "test"}},
+            ],
+        }
+        result = self._convert(msg)  # must not raise
+        blocks = result["content"]
+        text_blocks = [b for b in blocks if b.get("type") == "text"]
+        tool_blocks = [b for b in blocks if b.get("type") == "tool_use"]
+        assert len(text_blocks) == 0, f"None text block not filtered: {text_blocks}"
+        assert len(tool_blocks) == 1
+
+    def test_normal_path_preserves_non_empty_text_block(self):
+        """Non-empty text blocks must NOT be filtered."""
+        msg = {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": "I will search for that."},
+                {"type": "tool_use", "id": "call_3", "name": "web_search",
+                 "input": {"query": "test"}},
+            ],
+        }
+        result = self._convert(msg)
+        blocks = result["content"]
+        text_blocks = [b for b in blocks if b.get("type") == "text"]
+        assert len(text_blocks) == 1
+        assert text_blocks[0]["text"] == "I will search for that."
+
+    def test_normal_path_filters_whitespace_only_scalar_content(self):
+        """Regression (review of #63228): a truthy whitespace-only scalar
+        content string must also be filtered, not just list-content blocks."""
+        msg = {
+            "role": "assistant",
+            "content": "   \n\t  ",
+            "tool_calls": [
+                {"id": "call_scalar", "function": {"name": "web_search",
+                                                     "arguments": '{"query": "test"}'}},
+            ],
+        }
+        result = self._convert(msg)
+        blocks = result["content"]
+        text_blocks = [b for b in blocks if b.get("type") == "text"]
+        tool_blocks = [b for b in blocks if b.get("type") == "tool_use"]
+        assert len(text_blocks) == 0, f"Whitespace scalar content not filtered: {text_blocks}"
+        assert len(tool_blocks) == 1
+
+    def test_normal_path_relocates_cache_control_from_dropped_block(self):
+        """Regression (review of #63228): prompt_caching.py's _apply_cache_marker
+        sets cache_control directly on content[-1] for list content. If that
+        last part is blank text, dropping it must relocate the marker to the
+        surviving last cacheable block (here: the tool_use), not lose it."""
+        msg = {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": "I'll look that up."},
+                {"type": "tool_use", "id": "call_cache", "name": "web_search",
+                 "input": {"query": "test"}},
+                {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}},
+            ],
+        }
+        result = self._convert(msg)
+        blocks = result["content"]
+        assert not any(b.get("type") == "text" and not b.get("text", "").strip() for b in blocks), (
+            "Blank text block must be dropped"
+        )
+        cacheable_with_marker = [b for b in blocks if isinstance(b.get("cache_control"), dict)]
+        assert len(cacheable_with_marker) == 1, (
+            f"cache_control marker must survive on exactly one surviving block: {blocks}"
+        )
+        assert cacheable_with_marker[0]["type"] == "tool_use", (
+            f"Marker must relocate to the new last cacheable block: {blocks}"
+        )
+
+    def test_replay_path_filters_empty_text_block(self):
+        """Ordered-replay path (anthropic_content_blocks) must also drop blank text."""
+        from agent.anthropic_adapter import _convert_assistant_message
+        msg = {
+            "role": "assistant",
+            "content": "",
+            "anthropic_content_blocks": [
+                {"type": "text", "text": ""},
+                {"type": "tool_use", "id": "call_4", "name": "web_search",
+                 "input": {"query": "test"}},
+            ],
+            "tool_calls": [
+                {
+                    "id": "call_4",
+                    "function": {"name": "web_search",
+                                 "arguments": '{"query": "test"}'},
+                }
+            ],
+        }
+        result = _convert_assistant_message(msg)
+        blocks = result["content"]
+        text_blocks = [b for b in blocks if b.get("type") == "text"]
+        tool_blocks = [b for b in blocks if b.get("type") == "tool_use"]
+        assert len(text_blocks) == 0, f"Empty text in replay not filtered: {text_blocks}"
+        assert len(tool_blocks) == 1
+
+    def test_replay_path_relocates_cache_control_from_dropped_block(self):
+        """Same cache_control-relocation guarantee on the ordered-replay path:
+        a blank text block carrying cache_control (e.g. a stored, previously
+        cache-marked turn where prompt_caching later becomes blank on replay)
+        must not silently lose the breakpoint when dropped."""
+        from agent.anthropic_adapter import _convert_assistant_message
+        msg = {
+            "role": "assistant",
+            "content": "",
+            "anthropic_content_blocks": [
+                {"type": "tool_use", "id": "call_5", "name": "web_search",
+                 "input": {"query": "test"}},
+                {"type": "text", "text": "  ", "cache_control": {"type": "ephemeral"}},
+            ],
+            "tool_calls": [
+                {
+                    "id": "call_5",
+                    "function": {"name": "web_search",
+                                 "arguments": '{"query": "test"}'},
+                }
+            ],
+        }
+        result = _convert_assistant_message(msg)
+        blocks = result["content"]
+        assert not any(b.get("type") == "text" for b in blocks), "Blank replay text must be dropped"
+        cacheable_with_marker = [b for b in blocks if isinstance(b.get("cache_control"), dict)]
+        assert len(cacheable_with_marker) == 1
+        assert cacheable_with_marker[0]["type"] == "tool_use"
+
+
+class TestAllBlankFallbackAndNonStringText:
+    """Regression tests for the two bugs found in independent review of
+    #68633 (GPT-5.6-sol-xhigh in Codex, egilewski):
+
+    1. `effective = blocks or content` fell back to the RAW, unfiltered
+       `content` when every block was filtered out as blank -- restoring
+       exactly the invalid (blank/whitespace) payload the filter exists to
+       remove, for any message where blank content is the ONLY content
+       (no surviving tool_use/text/thinking block).
+    2. The normal-path blank-text check used `(blk.get("text") or "").strip()`,
+       which is not type-safe for a truthy NON-string, non-None text value
+       (e.g. an int) -- `or` doesn't substitute for a truthy value, so
+       `(7 or "").strip()` still raises AttributeError.
+    """
+
+    def _convert(self, message):
+        from agent.anthropic_adapter import _convert_assistant_message
+        return _convert_assistant_message(message)
+
+    def test_sole_blank_list_block_falls_back_to_placeholder_not_raw_content(self):
+        """A message whose ONLY content is a single blank text block (no
+        tool_calls, nothing else) must resolve to the "(empty)" placeholder,
+        not silently restore the raw blank content list."""
+        msg = {"role": "assistant", "content": [{"type": "text", "text": "   "}]}
+        result = self._convert(msg)
+        blocks = result["content"]
+        assert blocks == [{"type": "text", "text": "(empty)"}], (
+            f"Must fall back to the placeholder, not restore raw blank content: {blocks}"
+        )
+
+    def test_sole_whitespace_scalar_content_falls_back_to_placeholder(self):
+        """Same guarantee for scalar (non-list) whitespace-only content
+        with no tool_calls -- the earlier scalar-whitespace fix filters it
+        out of `blocks`, but the empty-fallback previously restored the raw
+        `content` string, which is itself the invalid whitespace payload."""
+        msg = {"role": "assistant", "content": "   \n\t  "}
+        result = self._convert(msg)
+        blocks = result["content"]
+        assert blocks == [{"type": "text", "text": "(empty)"}], (
+            f"Must fall back to the placeholder, not restore raw whitespace content: {blocks}"
+        )
+
+    def test_sole_cache_marked_blank_block_relocates_marker_to_placeholder(self):
+        """A message whose ONLY content is a blank text block that also
+        carries cache_control: the marker must not be silently dropped just
+        because there's nothing else to relocate it onto -- it must land on
+        the (empty) placeholder that replaces the dropped block."""
+        msg = {
+            "role": "assistant",
+            "content": [{"type": "text", "text": "", "cache_control": {"type": "ephemeral"}}],
+        }
+        result = self._convert(msg)
+        blocks = result["content"]
+        assert blocks == [
+            {"type": "text", "text": "(empty)", "cache_control": {"type": "ephemeral"}}
+        ], f"cache_control must relocate onto the (empty) placeholder: {blocks}"
+
+    def test_mixed_blank_plus_survivor_still_drops_blank_and_keeps_survivor(self):
+        """Sanity check the fix didn't regress the already-covered mixed
+        case: a blank block alongside a real tool_use must still just drop
+        the blank one, not fall back to the placeholder."""
+        msg = {
+            "role": "assistant",
+            "content": [{"type": "text", "text": ""}],
+            "tool_calls": [
+                {"id": "call_1", "function": {"name": "web_search",
+                                               "arguments": '{"query": "test"}'}},
+            ],
+        }
+        result = self._convert(msg)
+        blocks = result["content"]
+        assert not any(b.get("type") == "text" for b in blocks)
+        assert any(b.get("type") == "tool_use" for b in blocks)
+
+    def test_non_string_truthy_text_treated_as_invalid_not_crash(self):
+        """Regression: text=7 (a truthy int, not None) must not reach
+        .strip() and raise AttributeError -- it must be treated the same as
+        blank/invalid text and dropped."""
+        msg = {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": 7},
+                {"type": "tool_use", "id": "call_int", "name": "web_search",
+                 "input": {"query": "test"}},
+            ],
+        }
+        result = self._convert(msg)  # must not raise
+        blocks = result["content"]
+        text_blocks = [b for b in blocks if b.get("type") == "text"]
+        tool_blocks = [b for b in blocks if b.get("type") == "tool_use"]
+        assert len(text_blocks) == 0, f"Non-string text value must be dropped, not kept: {text_blocks}"
+        assert len(tool_blocks) == 1
+
+    def test_non_string_truthy_text_as_sole_content_falls_back_to_placeholder(self):
+        """Combines both bugs: a truthy non-string text value as the ONLY
+        content must not crash, and must resolve to the placeholder."""
+        msg = {"role": "assistant", "content": [{"type": "text", "text": 7}]}
+        result = self._convert(msg)  # must not raise
+        blocks = result["content"]
+        assert blocks == [{"type": "text", "text": "(empty)"}], blocks
+
+    def test_dict_valued_text_treated_as_invalid_not_crash(self):
+        """Another truthy non-string shape (dict) must also be safely dropped."""
+        msg = {
+            "role": "assistant",
+            "content": [{"type": "text", "text": {"nested": "garbage"}}],
+            "tool_calls": [
+                {"id": "call_d", "function": {"name": "web_search",
+                                               "arguments": '{"query": "test"}'}},
+            ],
+        }
+        result = self._convert(msg)  # must not raise
+        blocks = result["content"]
+        assert not any(b.get("type") == "text" for b in blocks)
+
+
+class TestReplayAllBlankFallback:
+    """Regression for the final open review point on #68633 (egilewski):
+
+    ``_relocated_replay_cache_control`` was applied only inside ``if
+    replayed:``. For ``anthropic_content_blocks`` containing only a blank
+    cache-marked text block, ``replayed`` became empty, the function fell
+    through to the main path's ``(empty)`` fallback, and the marker was
+    lost. A signed-thinking block plus the blank marked text also returned
+    without any relocated marker (thinking is not a cacheable carrier).
+    The replay branch now resolves a cacheable ``(empty)`` placeholder when
+    no cacheable block survives the blank filter.
+    """
+
+    def _convert(self, message):
+        from agent.anthropic_adapter import _convert_assistant_message
+        return _convert_assistant_message(message)
+
+    def test_sole_blank_marked_replay_block_keeps_marker_on_placeholder(self):
+        msg = {
+            "role": "assistant",
+            "content": "",
+            "anthropic_content_blocks": [
+                {"type": "text", "text": " ", "cache_control": {"type": "ephemeral"}},
+            ],
+        }
+        result = self._convert(msg)
+        assert result["content"] == [
+            {"type": "text", "text": "(empty)", "cache_control": {"type": "ephemeral"}}
+        ], result["content"]
+
+    def test_thinking_plus_blank_marked_text_keeps_thinking_and_marker(self):
+        msg = {
+            "role": "assistant",
+            "content": "",
+            "anthropic_content_blocks": [
+                {"type": "thinking", "thinking": "reasoning", "signature": "sig-A"},
+                {"type": "text", "text": "  ", "cache_control": {"type": "ephemeral"}},
+            ],
+        }
+        result = self._convert(msg)
+        blocks = result["content"]
+        assert blocks[0] == {"type": "thinking", "thinking": "reasoning", "signature": "sig-A"}
+        marked = [b for b in blocks if isinstance(b.get("cache_control"), dict)]
+        assert len(marked) == 1 and marked[0]["type"] == "text"
+        assert marked[0]["text"].strip(), "placeholder must be non-whitespace"
+
+    def test_thinking_plus_blank_unmarked_text_gets_schema_valid_placeholder(self):
+        """Even without a cache marker, dropping the only text block from a
+        thinking-only replay must leave schema-valid content."""
+        msg = {
+            "role": "assistant",
+            "content": "",
+            "anthropic_content_blocks": [
+                {"type": "thinking", "thinking": "reasoning", "signature": "sig-B"},
+                {"type": "text", "text": "\n"},
+            ],
+        }
+        result = self._convert(msg)
+        texts = [b for b in result["content"] if b.get("type") == "text"]
+        assert texts == [{"type": "text", "text": "(empty)"}]
diff --git a/tests/agent/test_anthropic_whitespace_text_blocks.py b/tests/agent/test_anthropic_whitespace_text_blocks.py
index 3ec7366a746..2b7de1c1622 100644
--- a/tests/agent/test_anthropic_whitespace_text_blocks.py
+++ b/tests/agent/test_anthropic_whitespace_text_blocks.py
@@ -51,13 +51,20 @@ class TestSafeText:
 
 
 class TestSanitizeReplayBlockWhitespace:
-    def test_whitespace_text_block_coerced_to_placeholder(self):
-        out = _sanitize_replay_block({"type": "text", "text": "   \n"})
-        assert out == {"type": "text", "text": _EMPTY_TEXT_PLACEHOLDER}
+    def test_whitespace_text_block_dropped(self):
+        # Blank text blocks are DROPPED at the block level (not coerced in
+        # place) — the caller relocates any cache_control the block carried
+        # and appends the non-whitespace placeholder only when nothing
+        # cacheable survives, so real thinking/tool_use blocks aren't
+        # cluttered with "(empty)" noise. See _convert_assistant_message.
+        assert _sanitize_replay_block({"type": "text", "text": "   \n"}) is None
 
-    def test_empty_text_block_coerced_to_placeholder(self):
-        out = _sanitize_replay_block({"type": "text", "text": ""})
-        assert out == {"type": "text", "text": _EMPTY_TEXT_PLACEHOLDER}
+    def test_empty_text_block_dropped(self):
+        assert _sanitize_replay_block({"type": "text", "text": ""}) is None
+
+    def test_none_text_block_dropped_without_crash(self):
+        # text=None (invalid upstream payload) must not reach .strip().
+        assert _sanitize_replay_block({"type": "text", "text": None}) is None
 
     def test_real_text_block_unchanged(self):
         out = _sanitize_replay_block({"type": "text", "text": "hi"})
diff --git a/tests/agent/test_aux_progress_streaming.py b/tests/agent/test_aux_progress_streaming.py
new file mode 100644
index 00000000000..2eb0e5448e6
--- /dev/null
+++ b/tests/agent/test_aux_progress_streaming.py
@@ -0,0 +1,417 @@
+"""Tests for the auxiliary forward-progress streaming layer.
+
+Slow summary models must not be punished like hung ones (#see PR): when a
+forward-progress hook is installed (context compression), the primary
+auxiliary call streams and ticks the hook per chunk, so outer watchdogs
+(gateway session hygiene) can extend their deadline on liveness. Without a
+hook, behavior is byte-for-byte the old non-streaming call.
+"""
+
+import threading
+import time
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent.auxiliary_client import (
+    _acreate_with_stream,
+    _aggregate_chat_stream,
+    _aggregate_chat_stream_async,
+    _aux_stream_total_ceiling,
+    _create_with_progress,
+    _notify_aux_progress,
+    _provider_requires_stream,
+    aux_progress_hook,
+)
+from agent.conversation_compression import CompressionCommitFence
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _chunk(content=None, reasoning=None, finish_reason=None, usage=None,
+           tool_calls=None, model="m1", chunk_id="c1"):
+    delta = SimpleNamespace(
+        content=content,
+        reasoning=reasoning,
+        reasoning_content=None,
+        tool_calls=tool_calls,
+    )
+    choice = SimpleNamespace(delta=delta, finish_reason=finish_reason)
+    return SimpleNamespace(
+        id=chunk_id, model=model, choices=[choice], usage=usage,
+    )
+
+
+class _FakeClient:
+    """OpenAI-shaped client whose create() returns a canned value or stream."""
+
+    def __init__(self, response=None, stream_chunks=None, stream_error=None):
+        self.calls = []
+        self._response = response
+        self._stream_chunks = stream_chunks
+        self._stream_error = stream_error
+        completions = SimpleNamespace(create=self._create)
+        self.chat = SimpleNamespace(completions=completions)
+
+    def _create(self, **kwargs):
+        self.calls.append(kwargs)
+        if kwargs.get("stream"):
+            if self._stream_error is not None:
+                raise self._stream_error
+            return iter(self._stream_chunks or [])
+        return self._response
+
+
+_COMPLETE = SimpleNamespace(
+    id="r1", model="m1", object="chat.completion",
+    choices=[SimpleNamespace(
+        index=0,
+        message=SimpleNamespace(role="assistant", content="non-streamed"),
+        finish_reason="stop",
+    )],
+    usage=None,
+)
+
+
+# ---------------------------------------------------------------------------
+# aux_progress_hook plumbing
+# ---------------------------------------------------------------------------
+
+class TestAuxProgressHook:
+    def test_hook_installed_and_restored(self):
+        ticks = []
+        with aux_progress_hook(lambda: ticks.append(1)):
+            _notify_aux_progress()
+        _notify_aux_progress()  # outside — must not tick
+        assert ticks == [1]
+
+    def test_none_hook_is_noop_passthrough(self):
+        with aux_progress_hook(None):
+            _notify_aux_progress()  # must not raise
+
+    def test_hook_exception_is_swallowed(self):
+        def _boom():
+            raise RuntimeError("hook blew up")
+        with aux_progress_hook(_boom):
+            _notify_aux_progress()  # must not raise
+
+    def test_hook_is_thread_local(self):
+        ticks = []
+        seen_in_thread = []
+
+        def _other_thread():
+            # No hook installed on this thread.
+            _notify_aux_progress()
+            seen_in_thread.append(len(ticks))
+
+        with aux_progress_hook(lambda: ticks.append(1)):
+            t = threading.Thread(target=_other_thread)
+            t.start()
+            t.join()
+        assert seen_in_thread == [0]
+
+
+# ---------------------------------------------------------------------------
+# _create_with_progress
+# ---------------------------------------------------------------------------
+
+class TestCreateWithProgress:
+    def test_no_hook_means_plain_nonstreaming_call(self):
+        client = _FakeClient(response=_COMPLETE)
+        result = _create_with_progress(client, {"model": "m1", "messages": []})
+        assert result is _COMPLETE
+        assert len(client.calls) == 1
+        assert "stream" not in client.calls[0]
+
+    def test_hook_upgrades_to_streaming_and_ticks_per_chunk(self):
+        chunks = [
+            _chunk(reasoning="thinking..."),
+            _chunk(content="Hello "),
+            _chunk(content="world", finish_reason="stop",
+                   usage=SimpleNamespace(prompt_tokens=5, completion_tokens=2,
+                                         total_tokens=7)),
+        ]
+        client = _FakeClient(stream_chunks=chunks)
+        ticks = []
+        with aux_progress_hook(lambda: ticks.append(1)):
+            result = _create_with_progress(
+                client, {"model": "m1", "messages": [], "timeout": 30},
+            )
+        assert client.calls[0]["stream"] is True
+        assert result.choices[0].message.content == "Hello world"
+        assert result.choices[0].message.reasoning == "thinking..."
+        assert result.choices[0].finish_reason == "stop"
+        assert result.usage.total_tokens == 7
+        # 1 dispatch tick + 1 per chunk
+        assert len(ticks) >= len(chunks) + 1
+
+    def test_streaming_rejected_falls_back_to_plain_call(self):
+        client = _FakeClient(
+            response=_COMPLETE,
+            stream_error=RuntimeError("stream is not supported by this model"),
+        )
+        with aux_progress_hook(lambda: None):
+            result = _create_with_progress(
+                client, {"model": "m1", "messages": []},
+            )
+        assert result is _COMPLETE
+        # streamed attempt + non-streaming fallback
+        assert len(client.calls) == 2
+        assert client.calls[0].get("stream") is True
+        assert "stream" not in client.calls[1]
+
+    def test_auth_error_propagates_without_nonstreaming_retry(self):
+        class _FakeAuthError(Exception):
+            status_code = 401
+        client = _FakeClient(stream_error=_FakeAuthError("Error code: 401 - unauthorized"))
+        with aux_progress_hook(lambda: None):
+            with pytest.raises(_FakeAuthError):
+                _create_with_progress(client, {"model": "m1", "messages": []})
+        assert len(client.calls) == 1  # no silent non-streaming retry
+
+    def test_shim_returning_complete_response_passes_through(self):
+        # Adapters may ignore stream=True and hand back a full response.
+        class _ShimClient(_FakeClient):
+            def _create(self, **kwargs):
+                self.calls.append(kwargs)
+                return _COMPLETE
+        client = _ShimClient()
+        with aux_progress_hook(lambda: None):
+            result = _create_with_progress(client, {"model": "m1", "messages": []})
+        assert result is _COMPLETE
+
+
+# ---------------------------------------------------------------------------
+# _aggregate_chat_stream
+# ---------------------------------------------------------------------------
+
+class TestAggregateChatStream:
+    def test_tool_call_deltas_are_reassembled(self):
+        tc0 = SimpleNamespace(
+            index=0, id="call_1",
+            function=SimpleNamespace(name="do_thing", arguments='{"a"'),
+        )
+        tc1 = SimpleNamespace(
+            index=0, id=None,
+            function=SimpleNamespace(name=None, arguments=': 1}'),
+        )
+        chunks = [
+            _chunk(tool_calls=[tc0]),
+            _chunk(tool_calls=[tc1], finish_reason="tool_calls"),
+        ]
+        result = _aggregate_chat_stream(iter(chunks))
+        tool_calls = result.choices[0].message.tool_calls
+        assert len(tool_calls) == 1
+        assert tool_calls[0].id == "call_1"
+        assert tool_calls[0].function.name == "do_thing"
+        assert tool_calls[0].function.arguments == '{"a": 1}'
+        assert result.choices[0].finish_reason == "tool_calls"
+
+    def test_total_ceiling_kills_trickle_stream_as_timeout(self):
+        def _trickle():
+            while True:
+                time.sleep(0.01)
+                yield _chunk(content="x")
+        with pytest.raises(TimeoutError, match="timed out"):
+            _aggregate_chat_stream(_trickle(), total_ceiling=0.05)
+
+    def test_stream_close_is_called(self):
+        closed = []
+
+        class _Stream:
+            def __iter__(self):
+                return iter([_chunk(content="ok", finish_reason="stop")])
+
+            def close(self):
+                closed.append(True)
+
+        result = _aggregate_chat_stream(_Stream())
+        assert result.choices[0].message.content == "ok"
+        assert closed == [True]
+
+    def test_empty_choices_chunks_are_skipped(self):
+        empty = SimpleNamespace(id="c", model="m", choices=[], usage=None)
+        chunks = [empty, _chunk(content="ok", finish_reason="stop")]
+        result = _aggregate_chat_stream(iter(chunks))
+        assert result.choices[0].message.content == "ok"
+
+
+# ---------------------------------------------------------------------------
+# Ceiling arithmetic
+# ---------------------------------------------------------------------------
+
+class TestStreamCeiling:
+    def test_floor_applies_to_small_timeouts(self):
+        assert _aux_stream_total_ceiling(30) == 600.0
+
+    def test_multiplier_wins_for_large_timeouts(self):
+        assert _aux_stream_total_ceiling(300) == 1200.0
+
+    def test_none_timeout_gets_floor(self):
+        assert _aux_stream_total_ceiling(None) == 600.0
+
+
+# ---------------------------------------------------------------------------
+# CompressionCommitFence progress surface
+# ---------------------------------------------------------------------------
+
+class TestFenceProgress:
+    def test_touch_progress_resets_idle_clock(self):
+        fence = CompressionCommitFence()
+        time.sleep(0.05)
+        assert fence.seconds_since_progress() >= 0.04
+        fence.touch_progress()
+        assert fence.seconds_since_progress() < 0.05
+
+    def test_fence_hook_wiring_matches_compressor_usage(self):
+        # conversation_compression installs fence.touch_progress as the hook;
+        # verify the pair works end-to-end through _notify_aux_progress.
+        fence = CompressionCommitFence()
+        time.sleep(0.05)
+        with aux_progress_hook(fence.touch_progress):
+            _notify_aux_progress()
+        assert fence.seconds_since_progress() < 0.05
+
+
+# ---------------------------------------------------------------------------
+# Stream-only providers (credit @kudi88, PR #60686)
+# ---------------------------------------------------------------------------
+
+class TestProviderRequiresStream:
+    def test_tencent_copilot_is_stream_only(self):
+        assert _provider_requires_stream(
+            "custom", "https://copilot.tencent.com/v1"
+        ) is True
+
+    def test_normal_endpoints_are_not(self):
+        assert _provider_requires_stream(
+            "openrouter", "https://openrouter.ai/api/v1"
+        ) is False
+        assert _provider_requires_stream("auto", None) is False
+        assert _provider_requires_stream("auto", "") is False
+
+    def test_config_marker_matches_custom_endpoint(self):
+        with patch(
+            "hermes_cli.config.load_config",
+            return_value={"auxiliary": {"stream_only_base_urls": ["my-proxy.example.com"]}},
+        ):
+            assert _provider_requires_stream(
+                "custom", "https://my-proxy.example.com/v1"
+            ) is True
+            assert _provider_requires_stream(
+                "custom", "https://other.example.com/v1"
+            ) is False
+
+    def test_config_read_failure_fails_open_to_non_streaming(self):
+        with patch(
+            "hermes_cli.config.load_config",
+            side_effect=RuntimeError("config broken"),
+        ):
+            assert _provider_requires_stream(
+                "custom", "https://other.example.com/v1"
+            ) is False
+
+
+class TestForceStream:
+    def test_force_stream_streams_without_a_hook(self):
+        chunks = [_chunk(content="hi", finish_reason="stop")]
+        client = _FakeClient(stream_chunks=chunks)
+        # NO aux_progress_hook installed — force_stream alone must stream.
+        result = _create_with_progress(
+            client, {"model": "m1", "messages": []}, force_stream=True,
+        )
+        assert client.calls[0]["stream"] is True
+        assert result.choices[0].message.content == "hi"
+
+    def test_force_stream_does_not_retry_nonstreaming_on_failure(self):
+        client = _FakeClient(
+            response=_COMPLETE,
+            stream_error=RuntimeError("HTTP 400 bad request"),
+        )
+        with pytest.raises(RuntimeError, match="bad request"):
+            _create_with_progress(
+                client, {"model": "m1", "messages": []}, force_stream=True,
+            )
+        # No silent non-streaming retry — the provider rejects those anyway.
+        assert len(client.calls) == 1
+
+
+class TestAsyncStreamAggregation:
+    @pytest.mark.asyncio
+    async def test_async_stream_is_consumed_with_async_for(self):
+        # The sweeper review of PR #60686 flagged that awaiting create() and
+        # then iterating synchronously raises — the async contract is
+        # ``async for``. Verify the async aggregator consumes a real async
+        # iterator and preserves tool-call deltas.
+        tc0 = SimpleNamespace(
+            index=0, id="call_9",
+            function=SimpleNamespace(name="lookup", arguments='{"q":'),
+        )
+        tc1 = SimpleNamespace(
+            index=0, id=None,
+            function=SimpleNamespace(name=None, arguments='"x"}'),
+        )
+        raw_chunks = [
+            _chunk(content="part1 "),
+            _chunk(tool_calls=[tc0]),
+            _chunk(tool_calls=[tc1], content="part2", finish_reason="tool_calls"),
+        ]
+
+        class _AsyncStream:
+            def __init__(self, items):
+                self._items = list(items)
+                self.closed = False
+
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                if not self._items:
+                    raise StopAsyncIteration
+                return self._items.pop(0)
+
+            async def close(self):
+                self.closed = True
+
+        stream = _AsyncStream(raw_chunks)
+        result = await _aggregate_chat_stream_async(stream)
+        msg = result.choices[0].message
+        assert msg.content == "part1 part2"
+        assert msg.tool_calls[0].function.name == "lookup"
+        assert msg.tool_calls[0].function.arguments == '{"q":"x"}'
+        assert result.choices[0].finish_reason == "tool_calls"
+        assert stream.closed is True
+
+    @pytest.mark.asyncio
+    async def test_acreate_with_stream_passes_stream_kwargs(self):
+        calls = []
+
+        class _AsyncStream:
+            def __init__(self, items):
+                self._items = list(items)
+
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                if not self._items:
+                    raise StopAsyncIteration
+                return self._items.pop(0)
+
+        class _AsyncClient:
+            def __init__(self):
+                completions = SimpleNamespace(create=self._create)
+                self.chat = SimpleNamespace(completions=completions)
+
+            async def _create(self, **kwargs):
+                calls.append(kwargs)
+                return _AsyncStream([_chunk(content="ok", finish_reason="stop")])
+
+        result = await _acreate_with_stream(
+            _AsyncClient(), {"model": "m1", "messages": [], "timeout": 30},
+        )
+        assert calls[0]["stream"] is True
+        assert result.choices[0].message.content == "ok"
diff --git a/tests/agent/test_auxiliary_client.py b/tests/agent/test_auxiliary_client.py
index 9f61ff9668d..abe1e7d23bd 100644
--- a/tests/agent/test_auxiliary_client.py
+++ b/tests/agent/test_auxiliary_client.py
@@ -656,6 +656,174 @@ class TestBuildCallKwargsMaxTokens:
         )
         assert kwargs["max_tokens"] == 4096
 
+    # ── MoA task should honor max_tokens on ALL providers (#reference_max_tokens) ──
+
+    @pytest.mark.parametrize(
+        "provider,model,base_url,expected_key",
+        [
+            ("zai", "glm-5.2", "https://api.z.ai/api/coding/paas/v4", "max_tokens"),
+            ("openrouter", "deepseek/deepseek-v4-flash:nitro", "https://openrouter.ai/api/v1", "max_tokens"),
+            ("copilot", "gpt-5.5", "https://api.githubcopilot.com", "max_completion_tokens"),
+            ("nous", "hermes-4", "https://inference-api.nousresearch.com/v1", "max_tokens"),
+        ],
+    )
+    def test_moa_task_sends_max_tokens_on_openai_compatible(self, provider, model, base_url, expected_key):
+        """MoA reference tasks must honor max_tokens regardless of provider.
+
+        The ``reference_max_tokens`` config option (PR #56756) caps advisor output
+        to reduce turn latency.  Before the fix, ``_build_call_kwargs`` silently
+        dropped the value for OpenAI-compatible providers (PR #34845), so the cap
+        never reached the API.  With the ``task`` parameter threaded through,
+        ``task == "moa_reference"`` includes the output cap in kwargs.
+
+        Models that require ``max_completion_tokens`` (GPT-5 family, Copilot)
+        get the correct parameter name via ``auxiliary_max_tokens_param()``.
+        """
+        from agent.auxiliary_client import _build_call_kwargs
+
+        kwargs = _build_call_kwargs(
+            provider=provider,
+            model=model,
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=800,
+            base_url=base_url,
+            task="moa_reference",
+        )
+        assert kwargs[expected_key] == 800
+
+    def test_moa_task_sends_max_tokens_on_anthropic_wire(self):
+        """MoA reference tasks on Anthropic-compat endpoints keep max_tokens (unchanged behavior)."""
+        from agent.auxiliary_client import _build_call_kwargs
+
+        kwargs = _build_call_kwargs(
+            provider="minimax",
+            model="minimax-m2",
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=600,
+            base_url="https://api.minimax.io/v1",
+            task="moa_reference",
+        )
+        assert kwargs["max_tokens"] == 600
+
+    def test_moa_aggregator_does_not_get_max_tokens_on_openai_compat(self):
+        """``reference_max_tokens`` is an advisors-only contract (#56756).
+
+        The aggregator is the acting model — it must NOT be capped by the
+        reference token budget.  Only ``task == "moa_reference"`` triggers
+        the exception in ``_build_call_kwargs``.
+        """
+        from agent.auxiliary_client import _build_call_kwargs
+
+        kwargs = _build_call_kwargs(
+            provider="zai",
+            model="glm-5.2",
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=800,
+            base_url="https://api.z.ai/api/coding/paas/v4",
+            task="moa_aggregator",
+        )
+        assert "max_tokens" not in kwargs
+        assert "max_completion_tokens" not in kwargs
+
+    def test_non_moa_tasks_still_omit_max_tokens(self):
+        """Regression guard: compression/titles/vision keep PR #34845 behavior."""
+        from agent.auxiliary_client import _build_call_kwargs
+
+        for task in ("compression", "vision", "title_generation", None, ""):
+            kwargs = _build_call_kwargs(
+                provider="openrouter",
+                model="deepseek/deepseek-v4-flash:nitro",
+                messages=[{"role": "user", "content": "hi"}],
+                max_tokens=800,
+                base_url="https://openrouter.ai/api/v1",
+                task=task,
+            )
+            assert "max_tokens" not in kwargs, f"max_tokens should be dropped for task={task!r}"
+
+    def test_moa_task_exact_match(self):
+        """Only task == "moa_reference" triggers the cap — not the aggregator,
+        not arbitrary 'moa_' prefixed tasks."""
+        from agent.auxiliary_client import _build_call_kwargs
+
+        # 'moa_reference' → honored
+        kw = _build_call_kwargs(
+            provider="zai", model="glm-5.2",
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=500,
+            base_url="https://api.z.ai/api/coding/paas/v4",
+            task="moa_reference",
+        )
+        assert kw["max_tokens"] == 500
+
+        # 'moa_aggregator' → dropped (aggregator is the acting model, not an advisor)
+        kw2 = _build_call_kwargs(
+            provider="zai", model="glm-5.2",
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=500,
+            base_url="https://api.z.ai/api/coding/paas/v4",
+            task="moa_aggregator",
+        )
+        assert "max_tokens" not in kw2
+
+        # 'moa_custom_future' → dropped (only moa_reference is whitelisted)
+        kw3 = _build_call_kwargs(
+            provider="zai", model="glm-5.2",
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=500,
+            base_url="https://api.z.ai/api/coding/paas/v4",
+            task="moa_custom_future",
+        )
+        assert "max_tokens" not in kw3
+
+    @pytest.mark.parametrize(
+        "provider,model,base_url",
+        [
+            ("gemini", "gemini-2.5-pro", None),
+            ("google", "gemini-2.5-flash", None),
+            (
+                "custom",
+                "gemini-2.5-pro",
+                "https://generativelanguage.googleapis.com/v1beta",
+            ),
+        ],
+    )
+    def test_keeps_max_tokens_for_gemini_native(self, provider, model, base_url):
+        # Native generateContent maps max_tokens → maxOutputTokens; when it is
+        # omitted Gemini applies a fixed 65,535-token ceiling, which silently
+        # turned MoA's reference_max_tokens into a no-op for gemini advisors.
+        from agent.auxiliary_client import _build_call_kwargs
+
+        kwargs = _build_call_kwargs(
+            provider=provider,
+            model=model,
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=600,
+            base_url=base_url,
+        )
+        assert kwargs["max_tokens"] == 600
+        assert "max_completion_tokens" not in kwargs
+
+    def test_omits_max_tokens_for_gemini_model_on_openai_compatible_endpoint(self):
+        # Control: the gemini branch keys on provider/base_url, never the model
+        # name. A gemini model served through an OpenAI-compatible endpoint
+        # keeps the default omission behavior (#34530), including Gemini's own
+        # /openai compatibility endpoint.
+        from agent.auxiliary_client import _build_call_kwargs
+
+        for provider, base_url in [
+            ("openrouter", "https://openrouter.ai/api/v1"),
+            ("custom", "https://generativelanguage.googleapis.com/v1beta/openai"),
+        ]:
+            kwargs = _build_call_kwargs(
+                provider=provider,
+                model="google/gemini-2.5-pro",
+                messages=[{"role": "user", "content": "hi"}],
+                max_tokens=600,
+                base_url=base_url,
+            )
+            assert "max_tokens" not in kwargs
+            assert "max_completion_tokens" not in kwargs
+
 
 class TestNousTagsScoping:
     def test_tags_injected_when_provider_is_nous(self, monkeypatch):
@@ -1573,7 +1741,7 @@ class TestVisionClientFallback:
         real_client = SimpleNamespace(messages=messages_api)
         captured_kwargs = {}
 
-        def fake_create_anthropic_message(_client, kwargs):
+        def fake_create_anthropic_message(_client, kwargs, **_kw):
             captured_kwargs.update(kwargs)
             return final_message
 
@@ -4179,6 +4347,69 @@ class TestAuxiliaryAuthRefreshRetry:
         mock_write.assert_called_once_with("fresh-token", "refresh-token-2", 9999999999999)
         stale_client.close.assert_called_once()
 
+    def test_refresh_provider_credentials_remints_vertex_token_and_evicts_cache(self):
+        """Vertex tokens live ~1h; on a long-running gateway the cached
+        auxiliary client's bearer token expires mid-session and 401s.
+        _refresh_provider_credentials("vertex") must re-mint the token via
+        the adapter (which refreshes in place when near expiry) and evict
+        the stale cached client so the next call rebuilds with a fresh one —
+        previously there was no "vertex" branch here at all, so this fell
+        through to the final `return False` and the stale client (and its
+        dead token) stayed cached until process restart."""
+        stale_client = MagicMock()
+        cache_key = ("vertex", False, None, None, None)
+
+        with (
+            patch("agent.auxiliary_client._client_cache", {cache_key: (stale_client, "google/gemini-3-flash-preview", None)}),
+            patch(
+                "agent.vertex_adapter.get_vertex_config",
+                return_value=("ya29.FRESH", "https://aiplatform.googleapis.com/v1beta1/projects/p/locations/global/endpoints/openapi"),
+            ) as mock_get_config,
+        ):
+            from agent.auxiliary_client import _refresh_provider_credentials
+
+            assert _refresh_provider_credentials("vertex") is True
+
+        mock_get_config.assert_called_once()
+        stale_client.close.assert_called_once()
+
+    def test_refresh_provider_credentials_vertex_returns_false_when_unminted(self):
+        """No usable token/base_url (e.g. ADC and the service-account file
+        both failed) — refresh must report failure, not silently evict and
+        pretend the client is fixed."""
+        with patch("agent.vertex_adapter.get_vertex_config", return_value=(None, None)):
+            from agent.auxiliary_client import _refresh_provider_credentials
+
+            assert _refresh_provider_credentials("vertex") is False
+
+    def test_resolve_provider_client_vertex_builds_client_from_minted_token(self):
+        """End-to-end: resolve_provider_client("vertex", ...) must reach the
+        auth_type == "vertex" branch and build a working client, not die at
+        the PROVIDER_REGISTRY lookup (a plain HERMES_OVERLAYS-only fix would
+        leave this branch dead code — PROVIDER_REGISTRY is what
+        resolve_provider_client actually gates on)."""
+        with (
+            patch("agent.vertex_adapter.has_vertex_credentials", return_value=True),
+            patch(
+                "agent.vertex_adapter.get_vertex_config",
+                return_value=("ya29.FRESH", "https://aiplatform.googleapis.com/v1beta1/projects/p/locations/global/endpoints/openapi"),
+            ),
+        ):
+            client, model = resolve_provider_client("vertex", "google/gemini-3-flash-preview")
+
+        assert client is not None
+        assert model == "google/gemini-3-flash-preview"
+        assert str(client.base_url).rstrip("/") == (
+            "https://aiplatform.googleapis.com/v1beta1/projects/p/locations/global/endpoints/openapi"
+        )
+
+    def test_resolve_provider_client_vertex_none_when_no_credentials(self):
+        with patch("agent.vertex_adapter.has_vertex_credentials", return_value=False):
+            client, model = resolve_provider_client("vertex", "google/gemini-3-flash-preview")
+
+        assert client is None
+        assert model is None
+
     @pytest.mark.asyncio
     async def test_async_call_llm_refreshes_anthropic_on_401_for_non_vision(self):
         stale_client = MagicMock()
@@ -4641,7 +4872,7 @@ class TestCodexAdapterPromptCacheKey:
     """
 
     @staticmethod
-    def _build_adapter(base_url="https://chatgpt.com/backend-api/codex"):
+    def _build_adapter(base_url="https://chatgpt.com/backend-api/codex", model="gpt-5.5"):
         from agent.auxiliary_client import _CodexCompletionsAdapter
         from types import SimpleNamespace
 
@@ -4674,7 +4905,7 @@ class TestCodexAdapterPromptCacheKey:
         real_client = MagicMock()
         real_client.base_url = base_url
         real_client.responses.create = _create
-        adapter = _CodexCompletionsAdapter(real_client, "gpt-5.5")
+        adapter = _CodexCompletionsAdapter(real_client, model)
         return adapter, captured_kwargs
 
     def test_cache_key_set_and_prefixed(self):
@@ -4727,6 +4958,69 @@ class TestCodexAdapterPromptCacheKey:
         ])
         assert "prompt_cache_key" not in captured
 
+    @pytest.mark.parametrize("model", [
+        "gpt-4.1",
+        "gpt-5.1-codex-max",
+        "openai.gpt-5.5-pro",
+    ])
+    def test_extended_cache_models_set_prompt_cache_retention(self, model):
+        adapter, captured = self._build_adapter(
+            base_url="https://bedrock-mantle.us-west-2.api.aws/v1",
+            model=model,
+        )
+        adapter.create(messages=[
+            {"role": "system", "content": "SYS"},
+            {"role": "user", "content": "hi"},
+        ])
+        assert captured["prompt_cache_retention"] == "24h"
+
+    def test_prompt_cache_retention_skipped_for_codex_backend(self):
+        adapter, captured = self._build_adapter()
+        adapter.create(messages=[
+            {"role": "system", "content": "SYS"},
+            {"role": "user", "content": "hi"},
+        ])
+        assert "prompt_cache_retention" not in captured
+
+    @pytest.mark.parametrize("base_url", [
+        "https://api.openai.com/v1",
+        "https://example.services.ai.azure.com/openai/v1",
+        "https://responses.example.com/v1",
+    ])
+    def test_prompt_cache_retention_skipped_for_other_compatible_endpoints(self, base_url):
+        adapter, captured = self._build_adapter(base_url=base_url)
+        adapter.create(messages=[
+            {"role": "system", "content": "SYS"},
+            {"role": "user", "content": "hi"},
+        ])
+        assert "prompt_cache_retention" not in captured
+
+    def test_prompt_cache_retention_skipped_for_xai_and_github_hosts(self):
+        adapter, captured = self._build_adapter(base_url="https://api.x.ai/v1")
+        adapter.create(messages=[
+            {"role": "system", "content": "SYS"},
+            {"role": "user", "content": "hi"},
+        ])
+        assert "prompt_cache_retention" not in captured
+
+        adapter, captured = self._build_adapter(base_url="https://api.githubcopilot.com")
+        adapter.create(messages=[
+            {"role": "system", "content": "SYS"},
+            {"role": "user", "content": "hi"},
+        ])
+        assert "prompt_cache_retention" not in captured
+
+    def test_prompt_cache_retention_skipped_for_github_models_host(self):
+        """models.github.ai is a GitHub Responses host in the main transport
+        (agent/chat_completion_helpers.py) — the auxiliary path must exclude
+        it from cache-retention emission the same way as githubcopilot.com."""
+        adapter, captured = self._build_adapter(base_url="https://models.github.ai/inference")
+        adapter.create(messages=[
+            {"role": "system", "content": "SYS"},
+            {"role": "user", "content": "hi"},
+        ])
+        assert "prompt_cache_retention" not in captured
+
 
 class TestCodexAdapterGithubResponsesMessageIdDrop:
     """_CodexCompletionsAdapter must drop codex_message_items ``id`` when
diff --git a/tests/agent/test_compression_anti_thrash_recovery.py b/tests/agent/test_compression_anti_thrash_recovery.py
new file mode 100644
index 00000000000..06af4076bb9
--- /dev/null
+++ b/tests/agent/test_compression_anti_thrash_recovery.py
@@ -0,0 +1,193 @@
+"""Anti-thrash recovery: the tripped guard must not be permanent (#14694).
+
+When two consecutive compactions each fail to clear the threshold, the
+anti-thrashing breaker blocks automatic compaction. Before this fix the block
+was permanent for the life of the session: nothing ever decremented
+``_ineffective_compression_count`` (or ``_fallback_compression_streak``)
+while blocked, so a session whose middle region was briefly too small to
+compact never auto-compacted again — it grew unbounded until the provider's
+hard context limit, and only ``/new`` or ``/reset`` recovered it.
+
+The recovery contract pinned here:
+
+* After ``_ANTI_THRASH_RECOVERY_SECONDS`` of continuous block, the gate
+  grants exactly ONE probation probe: tripped counters drop to 1 strike
+  (persisted) and the gate reports unblocked once.
+* An ineffective probe re-trips the guard on the very next verdict, and the
+  next recovery waits a FULL fresh window (no immediate re-probe loop).
+* An effective probe (or any fitting real-usage reading) fully clears the
+  counters through the existing ``update_from_response`` path.
+* The recovery clock is armed lazily on the first blocked evaluation and is
+  NOT durable: a process restart that loads a durable tripped counter
+  (#69872) starts a full fresh window blocked — a restart must never disarm
+  or shorten the guard (#54923).
+* The protection itself is preserved: inside the window the gate stays
+  blocked exactly as before.
+"""
+
+from unittest.mock import patch
+
+from agent.context_compressor import ContextCompressor
+from hermes_state import SessionDB
+
+
+def _compressor(threshold_tokens: int = 10_000) -> ContextCompressor:
+    cc = ContextCompressor(
+        model="test-model",
+        threshold_percent=0.75,
+        protect_first_n=3,
+        protect_last_n=20,
+        quiet_mode=True,
+        config_context_length=40960,
+        provider="test",
+    )
+    cc.threshold_tokens = threshold_tokens
+    return cc
+
+
+def _trip(cc: ContextCompressor) -> None:
+    """Arm the breaker exactly as two ineffective real-usage verdicts do."""
+    cc._record_ineffective_compression_verdict(2)
+
+
+class TestRecoveryWindow:
+    def test_blocked_within_window_unblocked_after(self):
+        cc = _compressor()
+        _trip(cc)
+        base = 1000.0
+        with patch("agent.context_compressor.time.monotonic", return_value=base):
+            # First blocked evaluation arms the clock and stays blocked.
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        with patch(
+            "agent.context_compressor.time.monotonic",
+            return_value=base + cc._ANTI_THRASH_RECOVERY_SECONDS - 1,
+        ):
+            # Still inside the window: protection intact.
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+            assert cc._ineffective_compression_count == 2
+        with patch(
+            "agent.context_compressor.time.monotonic",
+            return_value=base + cc._ANTI_THRASH_RECOVERY_SECONDS + 1,
+        ):
+            # Window elapsed: exactly one probe is granted.
+            assert cc.should_compress(cc.threshold_tokens + 1) is True
+        # Probation, not amnesty: one strike remains armed.
+        assert cc._ineffective_compression_count == 1
+
+    def test_ineffective_probe_re_trips_and_waits_a_full_fresh_window(self):
+        cc = _compressor()
+        _trip(cc)
+        base = 1000.0
+        with patch("agent.context_compressor.time.monotonic", return_value=base):
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        probe_time = base + cc._ANTI_THRASH_RECOVERY_SECONDS + 1
+        with patch(
+            "agent.context_compressor.time.monotonic", return_value=probe_time
+        ):
+            assert cc.should_compress(cc.threshold_tokens + 1) is True
+            # The probe compaction completes but does not clear the threshold.
+            cc._verify_compaction_cleared_threshold = True
+            cc.update_from_response({"prompt_tokens": cc.threshold_tokens + 1})
+            assert cc._ineffective_compression_count == 2
+            # Re-tripped: blocked again immediately (arms a new clock).
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        with patch(
+            "agent.context_compressor.time.monotonic",
+            return_value=probe_time + cc._ANTI_THRASH_RECOVERY_SECONDS - 5,
+        ):
+            # No immediate re-probe loop: the second window is full length,
+            # measured from the re-trip, not the original trip.
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        with patch(
+            "agent.context_compressor.time.monotonic",
+            return_value=probe_time + cc._ANTI_THRASH_RECOVERY_SECONDS + 5,
+        ):
+            assert cc.should_compress(cc.threshold_tokens + 1) is True
+
+    def test_effective_probe_clears_the_guard_completely(self):
+        cc = _compressor()
+        _trip(cc)
+        base = 1000.0
+        with patch("agent.context_compressor.time.monotonic", return_value=base):
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        with patch(
+            "agent.context_compressor.time.monotonic",
+            return_value=base + cc._ANTI_THRASH_RECOVERY_SECONDS + 1,
+        ):
+            assert cc.should_compress(cc.threshold_tokens + 1) is True
+            cc._verify_compaction_cleared_threshold = True
+            cc.update_from_response({"prompt_tokens": cc.threshold_tokens - 500})
+        assert cc._ineffective_compression_count == 0
+        assert cc._anti_thrash_recovery_deadline == 0.0
+
+    def test_fallback_streak_breaker_recovers_too(self):
+        cc = _compressor()
+        cc._fallback_compression_streak = 2
+        base = 1000.0
+        with patch("agent.context_compressor.time.monotonic", return_value=base):
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        with patch(
+            "agent.context_compressor.time.monotonic",
+            return_value=base + cc._ANTI_THRASH_RECOVERY_SECONDS + 1,
+        ):
+            assert cc.should_compress(cc.threshold_tokens + 1) is True
+        assert cc._fallback_compression_streak == 1
+
+    def test_under_threshold_never_arms_the_clock(self):
+        cc = _compressor()
+        _trip(cc)
+        base = 1000.0
+        with patch("agent.context_compressor.time.monotonic", return_value=base):
+            # Under threshold: gate never evaluated, clock untouched.
+            assert cc.should_compress(cc.threshold_tokens - 1) is False
+        assert cc._anti_thrash_recovery_deadline == 0.0
+
+    def test_untripped_guard_disarms_a_stale_clock(self):
+        cc = _compressor()
+        _trip(cc)
+        base = 1000.0
+        with patch("agent.context_compressor.time.monotonic", return_value=base):
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        assert cc._anti_thrash_recovery_deadline > 0.0
+        # A fitting real-usage reading clears the counter mid-window.
+        cc.update_from_response({"prompt_tokens": cc.threshold_tokens - 500})
+        with patch("agent.context_compressor.time.monotonic", return_value=base + 1):
+            assert cc.should_compress(cc.threshold_tokens + 1) is True
+        # The stale clock was disarmed, so a LATER trip starts a full window.
+        assert cc._anti_thrash_recovery_deadline == 0.0
+
+
+class TestRestartSemantics:
+    def test_restart_with_durable_tripped_counter_waits_a_full_window(self, tmp_path):
+        """#69872 x #14694: a restart must not disarm OR shorten the guard."""
+        db = SessionDB(db_path=tmp_path / "state.db")
+        db.create_session(session_id="sess-1", source="cli")
+        db.set_compression_ineffective_count("sess-1", 2)
+
+        cc = _compressor()
+        cc.bind_session_state(session_db=db, session_id="sess-1")
+        assert cc._ineffective_compression_count == 2
+        # The recovery clock is process-local and must come up disarmed.
+        assert cc._anti_thrash_recovery_deadline == 0.0
+        base = 5000.0
+        with patch("agent.context_compressor.time.monotonic", return_value=base):
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        with patch(
+            "agent.context_compressor.time.monotonic",
+            return_value=base + cc._ANTI_THRASH_RECOVERY_SECONDS + 1,
+        ):
+            assert cc.should_compress(cc.threshold_tokens + 1) is True
+        # The probation reset is durable, so sibling agents on the same
+        # session row (gateway hygiene) unblock too.
+        assert db.get_compression_ineffective_count("sess-1") == 1
+
+    def test_session_reset_disarms_the_recovery_clock(self):
+        cc = _compressor()
+        _trip(cc)
+        base = 1000.0
+        with patch("agent.context_compressor.time.monotonic", return_value=base):
+            assert cc.should_compress(cc.threshold_tokens + 1) is False
+        assert cc._anti_thrash_recovery_deadline > 0.0
+        cc.on_session_reset()
+        assert cc._anti_thrash_recovery_deadline == 0.0
+        assert cc._ineffective_compression_count == 0
diff --git a/tests/agent/test_compression_concurrent_fork.py b/tests/agent/test_compression_concurrent_fork.py
index 2e4624d1bda..b7c696ecb75 100644
--- a/tests/agent/test_compression_concurrent_fork.py
+++ b/tests/agent/test_compression_concurrent_fork.py
@@ -94,6 +94,21 @@ def _count_children(db: SessionDB, parent_sid: str) -> int:
     return len(rows)
 
 
+def _live_child_id(db: SessionDB, parent_sid: str) -> str | None:
+    """The single child id of ``parent_sid``, or None when there is none.
+
+    Fails loudly on more than one child: callers use this to prove the agents
+    converged on the winner's session, so a multi-child state is a fork and
+    must not be silently reduced to 'the first row'.
+    """
+    rows = db._conn.execute(
+        "SELECT id FROM sessions WHERE parent_session_id = ?",
+        (parent_sid,),
+    ).fetchall()
+    assert len(rows) <= 1, f"expected at most one child of {parent_sid}, got {rows!r}"
+    return rows[0][0] if rows else None
+
+
 def _wait_for_touch(touch_calls: list[str], value: str, timeout: float = 1.0) -> None:
     deadline = time.monotonic() + timeout
     while time.monotonic() < deadline:
@@ -293,21 +308,30 @@ def test_concurrent_compression_does_not_fork_session(tmp_path: Path) -> None:
         "the concurrent rotations."
     )
 
-    # The number of agents that rotated their session_id must match the number
-    # of children created — and must never exceed one. (Both rotating would be
-    # the fork; the winner rolling back to parent under contention yields zero,
-    # which agrees with zero children.)
-    rotated = sum(
-        1 for a in (agent_a, agent_b) if a.session_id != parent_sid
+    # Every agent that moved off the parent must have landed on the SAME id.
+    # Counting movers is the wrong contract: the loser can legitimately end up
+    # on the child too, without rotating anything itself — it takes the lock
+    # after the winner released it, sees the parent was already rotated, and
+    # _adopt_live_compression_child() points it at the winner's single child
+    # (the "compression recovery: stale session=... adopted live child=..."
+    # path). That convergence is the fix working, not a fork; the fork is two
+    # DIFFERENT live ids. Asserting ``movers <= 1`` failed on that healthy
+    # outcome under concurrent load.
+    moved = {a.session_id for a in (agent_a, agent_b) if a.session_id != parent_sid}
+    assert len(moved) <= 1, (
+        f"Expected at most one post-compression session id, got {sorted(moved)}. "
+        "Two distinct ids means the lock didn't serialize them (transcript fork)."
     )
-    assert rotated <= 1, (
-        f"Expected at most one agent to rotate session_id, got {rotated}. "
-        "More than one rotating means the lock didn't serialize them."
-    )
-    assert rotated == n_children, (
-        f"Inconsistent state: {rotated} agent(s) rotated but {n_children} "
+    assert len(moved) == n_children, (
+        f"Inconsistent state: agents live on {sorted(moved)} but {n_children} "
         "child session(s) exist — rotation and child creation diverged."
     )
+    if moved:
+        child = _live_child_id(db, parent_sid)
+        assert moved == {child}, (
+            f"Agents live on {sorted(moved)} but the parent's only child is "
+            f"{child} — an agent is writing to a session outside the lineage."
+        )
 
     # The lock must be released after both paths finished, regardless of
     # whether the winner committed a child or rolled back.
@@ -316,6 +340,35 @@ def test_concurrent_compression_does_not_fork_session(tmp_path: Path) -> None:
     )
 
 
+def test_durable_message_committed_before_lease_aborts_stale_snapshot(
+    tmp_path: Path,
+) -> None:
+    """A durable row absent from the caller snapshot must survive in the parent."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "PRE_LEASE_DURABLE_RACE"
+    db.create_session(parent_sid, source="webui")
+    db.append_message(parent_sid, "user", "old durable")
+
+    # Frontend takes its snapshot, then another producer commits before this
+    # compressor acquires the lease.
+    stale_snapshot = [{"role": "user", "content": "old durable"}]
+    db.append_message(parent_sid, "assistant", "late committed before lease")
+    agent = _build_agent_with_db(db, parent_sid)
+
+    returned, _system_prompt = agent._compress_context(
+        stale_snapshot, "sys", approx_tokens=120_000
+    )
+
+    assert returned is stale_snapshot
+    assert agent.session_id == parent_sid
+    assert db.find_live_compression_child(parent_sid) is None
+    assert [m["content"] for m in db.get_messages_as_conversation(parent_sid)] == [
+        "old durable",
+        "late committed before lease",
+    ]
+    agent.context_compressor.compress.assert_not_called()
+
+
 def test_skipped_compression_returns_messages_unchanged(tmp_path: Path) -> None:
     """The loser of the lock race must return its input messages verbatim.
 
@@ -507,6 +560,67 @@ def test_commit_fence_waits_for_an_active_commit() -> None:
     assert result["cancelled"] is False
 
 
+def test_delayed_contender_adopts_unique_rotated_child(tmp_path: Path) -> None:
+    """A stale agent must continue on the winner's compacted child transcript."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "STALE_PARENT"
+    child_sid = "CANONICAL_CHILD"
+    db.create_session(parent_sid, source="webui")
+    db.end_session(parent_sid, "compression")
+    db.create_session(child_sid, source="webui", parent_session_id=parent_sid)
+    compacted = [
+        {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+        {"role": "assistant", "content": "compacted tail"},
+    ]
+    db.replace_messages(child_sid, compacted)
+
+    agent = _build_agent_with_db(db, parent_sid)
+    stale_messages = [
+        {"role": "user", "content": "stale"},
+        {"role": "assistant", "content": "x" * 1000},
+    ]
+    recovered, _system_prompt = agent._compress_context(
+        stale_messages, "sys", approx_tokens=120_000
+    )
+
+    assert agent.session_id == child_sid
+    assert [(m["role"], m["content"]) for m in recovered] == [
+        ("user", "[CONTEXT COMPACTION] summary"),
+        ("assistant", "compacted tail"),
+    ]
+    assert agent._session_db_created is True
+    assert agent._flushed_db_message_session_id == child_sid
+    assert agent._last_flushed_db_idx == len(recovered)
+    agent.context_compressor.compress.assert_not_called()
+    lifecycle_args, lifecycle_kwargs = agent.context_compressor.on_session_start.call_args
+    assert lifecycle_args == (child_sid,)
+    assert lifecycle_kwargs["boundary_reason"] == "compression"
+    assert lifecycle_kwargs["old_session_id"] == parent_sid
+    assert lifecycle_kwargs["session_db"] is db
+
+
+def test_delayed_contender_fails_closed_without_unique_child(tmp_path: Path) -> None:
+    """Missing or ambiguous lineage must not silently select a continuation."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "AMBIGUOUS_PARENT"
+    db.create_session(parent_sid, source="webui")
+    db.end_session(parent_sid, "compression")
+    db.create_session("CHILD_A", source="webui", parent_session_id=parent_sid)
+    db.create_session("CHILD_B", source="webui", parent_session_id=parent_sid)
+    db.replace_messages("CHILD_A", [{"role": "user", "content": "a"}])
+    db.replace_messages("CHILD_B", [{"role": "user", "content": "b"}])
+    agent = _build_agent_with_db(db, parent_sid)
+    stale_messages = [{"role": "user", "content": "stale"}]
+
+    returned, _system_prompt = agent._compress_context(
+        stale_messages, "sys", approx_tokens=120_000
+    )
+
+    assert returned is stale_messages or returned == stale_messages
+    assert agent.session_id == parent_sid
+    agent.context_compressor.compress.assert_not_called()
+
+
 def test_compression_restores_user_turn_when_compressor_drops_all_users(tmp_path: Path) -> None:
     """Provider chat templates need at least one user message after compaction.
 
@@ -1442,6 +1556,55 @@ def test_lease_refresher_survives_single_transient_failure() -> None:
     )
 
 
+def test_lease_refresher_first_refresh_is_immediate() -> None:
+    """Tick #1 must land before the first wait, not one interval late.
+
+    The lease clock starts at try_acquire(), but the refresher only starts
+    after the rotation-ownership lookup, the durable-breaker re-read and thread
+    startup. Waiting a full interval before the first refresh charges all of
+    that against the acquirer's first lease, so under load a short TTL can
+    expire — and be reclaimed by a competitor — before the owner ever renews.
+    """
+    from agent.conversation_compression import _CompressionLockLeaseRefresher
+
+    db = _FlakyRefreshDB([])  # always succeeds
+    refresher = _CompressionLockLeaseRefresher(
+        db, "sess", "holder", ttl_seconds=10.0, refresh_interval_seconds=2.0
+    )
+
+    calls_before_first_wait: list[int] = []
+
+    def _wait(_interval: float) -> bool:
+        calls_before_first_wait.append(db.calls)
+        return True  # stop after the first wait
+
+    refresher._stop.wait = _wait  # type: ignore[assignment]
+    refresher._run()
+
+    assert calls_before_first_wait and calls_before_first_wait[0] == 1, (
+        "Refresher waited a full interval before its first refresh — the lease "
+        f"is renewed one interval late (calls at first wait: "
+        f"{calls_before_first_wait!r})."
+    )
+
+
+def test_lease_refresher_immediate_tick_still_honors_stop() -> None:
+    """A refresher stopped before/at startup must not fire the immediate tick."""
+    from agent.conversation_compression import _CompressionLockLeaseRefresher
+
+    db = _FlakyRefreshDB([])
+    refresher = _CompressionLockLeaseRefresher(
+        db, "sess", "holder", ttl_seconds=10.0, refresh_interval_seconds=2.0
+    )
+    refresher._stop.set()  # released before the thread got to run
+    refresher._run()
+
+    assert db.calls == 0, (
+        "The immediate first tick must not resurrect a lock whose owner already "
+        f"released it (refresh calls after stop(): {db.calls})."
+    )
+
+
 def test_lease_refresher_failure_window_is_bounded_by_ttl() -> None:
     """Persistent failure stops within one lease's worth of time, not forever.
 
diff --git a/tests/agent/test_compression_rotation_state.py b/tests/agent/test_compression_rotation_state.py
index 0ba525d6253..11d67f28ca8 100644
--- a/tests/agent/test_compression_rotation_state.py
+++ b/tests/agent/test_compression_rotation_state.py
@@ -126,21 +126,35 @@ class TestOrphanRollbackOnCreateFailure:
         db.create_session(parent, source="cli")
         agent = _build_agent_with_db(db, parent)
 
-        # Make the CHILD create_session raise, but let the initial parent
-        # end_session/reopen work. We patch create_session to blow up.
-        real_create = db.create_session
+        # Atomic publication failure must leave the live parent and caller's
+        # original list untouched even when a plugin compressor mutates in place.
+        original = _msgs()
+
+        def _mutating_compress(live_messages, **_kwargs):
+            live_messages[:] = [
+                {"role": "user", "content": "mutated compacted snapshot"}
+            ]
+            return live_messages
+
+        agent.context_compressor.compress.side_effect = _mutating_compress
 
         def _boom(*a, **k):
-            raise RuntimeError("FOREIGN KEY constraint failed")
+            raise RuntimeError("simulated atomic publication failure")
 
-        with patch.object(db, "create_session", side_effect=_boom):
-            agent._compress_context(_msgs(), "sys", approx_tokens=120_000)
+        with patch.object(db, "publish_compression_child", side_effect=_boom):
+            returned, _system_prompt = agent._compress_context(
+                original, "sys", approx_tokens=120_000
+            )
 
-        # The live id must roll back to the still-indexed parent — NOT a
-        # phantom child id that has no row in state.db.
         assert agent.session_id == parent
-        assert db.get_session(parent) is not None
-        _ = real_create  # silence unused
+        assert [(m["role"], m["content"]) for m in returned] == [
+            (m["role"], m["content"]) for m in _msgs()
+        ]
+        assert returned is original
+        parent_row = db.get_session(parent)
+        assert parent_row is not None
+        assert parent_row["ended_at"] is None
+        assert db.find_live_compression_child(parent) is None
 
 
 class TestWorkspaceMetadataFollowsRotation:
diff --git a/tests/agent/test_context_compressor.py b/tests/agent/test_context_compressor.py
index dfe7e699379..6364441f2a2 100644
--- a/tests/agent/test_context_compressor.py
+++ b/tests/agent/test_context_compressor.py
@@ -3973,3 +3973,543 @@ class TestDoubleCompactionSummaryRole:
             "summary of earlier turns" in (m.get("content") or "")
             for m in result
         )
+
+
+class TestSummaryPromptBounding:
+    def test_oversized_summary_prompt_is_bounded_and_preserves_edges(self):
+        mock_response = MagicMock()
+        mock_response.choices = [MagicMock()]
+        mock_response.choices[0].message.content = "bounded summary"
+
+        with patch("agent.context_compressor.get_model_context_length", return_value=272000):
+            c = ContextCompressor(model="test", quiet_mode=True)
+
+        messages = [
+            {"role": "user", "content": f"turn-{i}-" + ("x" * 6000)}
+            for i in range(80)
+        ]
+        messages[0]["content"] = "FIRST_SENTINEL " + messages[0]["content"]
+        messages[-1]["content"] = "LAST_SENTINEL " + messages[-1]["content"]
+
+        with patch("agent.context_compressor.call_llm", return_value=mock_response) as mock_call:
+            summary = c._generate_summary(messages)
+
+        prompt = mock_call.call_args.kwargs["messages"][0]["content"]
+        assert summary.startswith(SUMMARY_PREFIX)
+        assert len(prompt) < 180_000
+        assert "summary input truncated" in prompt
+        assert "FIRST_SENTINEL" in prompt
+        assert "LAST_SENTINEL" in prompt
+
+    def test_small_input_returned_byte_identical(self):
+        """Inputs at or under the cap must pass through completely untouched."""
+        small = "hello world\n\n[USER]: do the thing"
+        assert ContextCompressor._bound_summary_input(small) is small
+        exactly_at_cap = "a" * ContextCompressor._SUMMARY_INPUT_MAX_CHARS
+        assert ContextCompressor._bound_summary_input(exactly_at_cap) is exactly_at_cap
+
+    def test_bound_respected_on_oversized_input_with_marker(self):
+        """Direct unit check: output length ≤ cap, marker present, edges kept."""
+        cap = ContextCompressor._SUMMARY_INPUT_MAX_CHARS
+        content = "HEAD_EDGE " + ("m" * (cap * 3)) + " TAIL_EDGE"
+        bounded = ContextCompressor._bound_summary_input(content)
+        assert len(bounded) <= cap
+        assert "summary input truncated" in bounded
+        assert bounded.startswith("HEAD_EDGE")
+        assert bounded.endswith("TAIL_EDGE")
+
+    def test_bound_applies_after_per_message_truncation(self):
+        """The aggregate cap catches what per-message truncation alone misses:
+        hundreds of turns, each individually under _CONTENT_MAX, still sum to
+        an unbounded serialized block without _bound_summary_input."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=272000):
+            c = ContextCompressor(model="test", quiet_mode=True)
+        # Each message body is < _CONTENT_MAX so per-message truncation is a
+        # no-op — only the aggregate bound can cap the total.
+        messages = [
+            {"role": "user", "content": "y" * (c._CONTENT_MAX - 100)}
+            for _ in range(60)
+        ]
+        serialized = c._serialize_for_summary(messages)
+        assert len(serialized) > c._SUMMARY_INPUT_MAX_CHARS  # unbounded without the cap
+        bounded = c._bound_summary_input(serialized)
+        assert len(bounded) <= c._SUMMARY_INPUT_MAX_CHARS
+        assert "summary input truncated" in bounded
+
+    def test_iterative_update_path_is_bounded(self):
+        """The iterative prompt (previous summary + new turns) must be bounded
+        too — a pathological rehydrated handoff must not blow up the prompt."""
+        mock_response = MagicMock()
+        mock_response.choices = [MagicMock()]
+        mock_response.choices[0].message.content = "updated summary"
+
+        with patch("agent.context_compressor.get_model_context_length", return_value=272000):
+            c = ContextCompressor(model="test", quiet_mode=True)
+        cap = c._SUMMARY_INPUT_MAX_CHARS
+        c._previous_summary = "PREV_HEAD " + ("p" * (cap * 2)) + " PREV_TAIL"
+
+        messages = [
+            {"role": "user", "content": f"turn-{i}-" + ("x" * 6000)}
+            for i in range(80)
+        ]
+
+        with patch("agent.context_compressor.call_llm", return_value=mock_response) as mock_call:
+            summary = c._generate_summary(messages)
+
+        prompt = mock_call.call_args.kwargs["messages"][0]["content"]
+        assert summary.startswith(SUMMARY_PREFIX)
+        # previous summary block + new-turns block each capped, plus the
+        # fixed template: well under 3x the cap (unbounded would be ~800K).
+        assert len(prompt) < 2 * cap + 30_000
+        assert "PREV_HEAD" in prompt
+        assert "PREV_TAIL" in prompt
+        assert "summary input truncated" in prompt
+
+    def test_marker_does_not_collide_with_summary_classifier(self):
+        """The omitted-middle marker must never make bounded content classify
+        as a compaction handoff (SUMMARY_PREFIX / merged-handoff patterns)."""
+        cap = ContextCompressor._SUMMARY_INPUT_MAX_CHARS
+        bounded = ContextCompressor._bound_summary_input("z" * (cap * 2))
+        assert "summary input truncated" in bounded
+        assert ContextCompressor.classify_summary_content(bounded) is None
+        # Marker alone (worst case: lands at the start of a message) is not a
+        # handoff prefix either.
+        marker_only = bounded[bounded.index("\n\n...[summary input truncated"):]
+        assert ContextCompressor.classify_summary_content(marker_only.lstrip()) is None
+
+
+class TestMinTailUserMessages:
+    """COMPRESS-01,02,07,08: N-user-message tail protection.
+
+    Tests the ``_ensure_last_n_user_messages_in_tail`` method and its
+    integration through ``_find_tail_cut_by_tokens``.
+    """
+
+    def test_n3_preserves_last_3_user_messages(self):
+        """COMPRESS-01: _find_tail_cut_by_tokens with min_tail_user_messages=3
+        guarantees the last 3 user-role messages are in the tail."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=2,
+                quiet_mode=True,
+                min_tail_user_messages=3,
+            )
+        c.tail_token_budget = 200
+        messages = [
+            {"role": "user", "content": "head msg 1"},
+            {"role": "assistant", "content": "head reply 1"},
+            {"role": "user", "content": "middle 1"},
+            {"role": "assistant", "content": "middle 1 reply"},
+            {"role": "user", "content": "middle 2"},
+            {"role": "assistant", "content": "middle 2 reply"},
+            {"role": "user", "content": "recent 3"},
+            {"role": "assistant", "content": "recent 3 reply"},
+            {"role": "user", "content": "recent 2"},
+            {"role": "assistant", "content": "recent 2 reply"},
+            {"role": "user", "content": "recent 1"},
+            {"role": "assistant", "content": "recent 1 reply"},
+        ]
+        head_end = c.protect_first_n
+        cut = c._find_tail_cut_by_tokens(messages, head_end)
+        tail_messages = messages[cut:]
+        tail_user_contents = [m["content"] for m in tail_messages if m["role"] == "user"]
+        assert len(tail_user_contents) >= 3, (
+            f"Expected >= 3 user messages in tail, got {len(tail_user_contents)}"
+        )
+        assert "recent 1" in tail_user_contents
+        assert "recent 2" in tail_user_contents
+        assert "recent 3" in tail_user_contents
+        assert cut >= head_end + 1
+
+    def test_n3_tool_group_integrity(self):
+        """COMPRESS-02: When the 3rd-to-last user message is preceded by
+        assistant(tool_calls) + tool results, the boundary is set at the
+        user message (a clean boundary).  The preceding tool group stays
+        together — it is either entirely in the compressed region or
+        entirely in the tail, never split across the boundary."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=1,
+                quiet_mode=True,
+                min_tail_user_messages=3,
+            )
+        c.tail_token_budget = 200
+        messages = [
+            {"role": "user", "content": "start"},
+            {"role": "assistant", "content": None,
+             "tool_calls": [{"function": {"name": "read_file", "arguments": "{}"}}]},
+            {"role": "tool", "content": "result content",
+             "tool_call_id": "call_1"},
+            {"role": "user", "content": "user 3rd last"},
+            {"role": "assistant", "content": "reply 3rd last"},
+            {"role": "user", "content": "user 2nd last"},
+            {"role": "assistant", "content": "reply 2nd last"},
+            {"role": "user", "content": "user last"},
+            {"role": "assistant", "content": "reply last"},
+        ]
+        head_end = c.protect_first_n
+        cut = c._find_tail_cut_by_tokens(messages, head_end)
+        compressed = messages[:cut]
+        tool_positions = [
+            i for i, m in enumerate(compressed)
+            if m.get("role") in ("assistant", "tool")
+            and (m.get("tool_calls") or m.get("tool_call_id"))
+        ]
+        if len(tool_positions) >= 2:
+            assert tool_positions[-1] - tool_positions[0] == len(tool_positions) - 1, (
+                "Tool group must stay contiguous across the boundary"
+            )
+        tail_messages = messages[cut:]
+        tail_users = [m["content"] for m in tail_messages if m["role"] == "user"]
+        assert "user 3rd last" in tail_users
+        assert "user 2nd last" in tail_users
+        assert "user last" in tail_users
+        assert cut >= head_end + 1
+
+    def test_n1_regression_safety(self):
+        """COMPRESS-08: N=1 produces identical tail positioning to the existing
+        _ensure_last_user_message_in_tail method."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.85,
+                protect_first_n=2,
+                quiet_mode=True,
+            )
+            c.min_tail_user_messages = 1
+        messages = [
+            {"role": "user", "content": "head 1"},
+            {"role": "assistant", "content": "head reply 1"},
+            {"role": "user", "content": "middle user"},
+            {"role": "assistant", "content": "middle reply"},
+            {"role": "user", "content": "last user"},
+            {"role": "assistant", "content": "last reply"},
+        ]
+        head_end = c.protect_first_n
+        cut1 = c._find_tail_cut_by_tokens(messages, head_end)
+        tail1 = messages[cut1:]
+        # Verify the last user message is in the tail
+        tail_users = [m["content"] for m in tail1 if m["role"] == "user"]
+        assert "last user" in tail_users
+        assert cut1 >= head_end + 1
+
+    def test_fewer_than_n_user_messages(self):
+        """COMPRESS-07: When the conversation has fewer than N user messages,
+        the earliest available user message is used without error."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=2,
+                quiet_mode=True,
+            )
+        messages = [
+            {"role": "user", "content": "first"},
+            {"role": "assistant", "content": "reply 1"},
+            {"role": "user", "content": "second"},
+            {"role": "assistant", "content": "reply 2"},
+        ]
+        # Only 2 user messages, but N=5 — should use earliest found
+        head_end = c.protect_first_n
+        result = c._ensure_last_n_user_messages_in_tail(
+            messages, cut_idx=3, head_end=head_end, n=5
+        )
+        # Should not crash, boundary should be before the first user message
+        # (index 0) or at most cut_idx
+        assert result <= 3
+
+    def test_nth_user_already_in_tail_no_reposition(self):
+        """When the Nth user message is already in the tail, cut_idx is unchanged."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=2,
+                quiet_mode=True,
+            )
+        messages = [
+            {"role": "user", "content": "first"},
+            {"role": "assistant", "content": "reply 1"},
+            {"role": "user", "content": "second"},
+            {"role": "assistant", "content": "reply 2"},
+            {"role": "user", "content": "third"},
+            {"role": "assistant", "content": "reply 3"},
+        ]
+        head_end = c.protect_first_n
+        # cut_idx at 2 means all users from index 2 onward are in tail
+        result = c._ensure_last_n_user_messages_in_tail(
+            messages, cut_idx=2, head_end=head_end, n=3
+        )
+        assert result == 2  # unchanged
+
+    def test_n5_preserves_last_5_user_messages(self):
+        """COMPRESS-06: min_tail_user_messages=5 protects last 5 user messages."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=1,
+                quiet_mode=True,
+            )
+            c.min_tail_user_messages = 5
+        c.tail_token_budget = 500
+        # protect_first_n=1 → head_end=1, so index 0 is head.
+        # u1..u5 must all be at indices >= head_end+1 (=2) to survive the clamp.
+        messages = [
+            {"role": "user", "content": "head 1"},            # 0 (head)
+            {"role": "assistant", "content": "head reply"},   # 1 (head_end boundary)
+            {"role": "user", "content": "u1"},                # 2
+            {"role": "assistant", "content": "a1"},           # 3
+            {"role": "user", "content": "u2"},                # 4
+            {"role": "assistant", "content": "a2"},           # 5
+            {"role": "user", "content": "u3"},                # 6
+            {"role": "assistant", "content": "a3"},           # 7
+            {"role": "user", "content": "u4"},                # 8
+            {"role": "assistant", "content": "a4"},           # 9
+            {"role": "user", "content": "u5"},                # 10
+            {"role": "assistant", "content": "a5"},           # 11
+        ]
+        head_end = c.protect_first_n  # = 1
+        cut = c._find_tail_cut_by_tokens(messages, head_end)
+        tail_users = [m["content"] for m in messages[cut:] if m["role"] == "user"]
+        assert len(tail_users) >= 5, f"Expected >=5 users in tail, got {len(tail_users)}"
+        for u in ("u1", "u2", "u3", "u4", "u5"):
+            assert u in tail_users
+        assert cut >= head_end + 1
+
+    def test_no_user_messages_beyond_head(self):
+        """When there are no user messages beyond head_end, cut_idx is unchanged."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=5,
+                quiet_mode=True,
+            )
+        messages = [
+            {"role": "user", "content": "msg 1"},
+            {"role": "assistant", "content": "reply 1"},
+            {"role": "user", "content": "msg 2"},
+            {"role": "assistant", "content": "reply 2"},
+        ]
+        head_end = c.protect_first_n  # = 5 > len(messages)
+        result = c._ensure_last_n_user_messages_in_tail(
+            messages, cut_idx=2, head_end=head_end, n=3
+        )
+        assert result == 2  # unchanged
+
+    def test_default_is_behavior_preserving(self):
+        """Default min_tail_user_messages=1 leaves the tail cut byte-identical
+        to the historical single-anchor pipeline.
+
+        A default of 3 was measured to CHANGE the cut on transcripts whose
+        tail budget covers only the last turn, so the default is gated to 1
+        (= the existing single last-user anchor) and N>1 is opt-in.
+        """
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c_default = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=2,
+                quiet_mode=True,
+            )
+            c_explicit = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=2,
+                quiet_mode=True,
+                min_tail_user_messages=1,
+            )
+        assert c_default.min_tail_user_messages == 1
+        c_default.tail_token_budget = 200
+        c_explicit.tail_token_budget = 200
+        messages = [
+            {"role": "user", "content": "head msg"},
+            {"role": "assistant", "content": "head reply"},
+        ]
+        for i in range(3):
+            messages.append({"role": "user", "content": f"user {i}"})
+            messages.append({"role": "assistant", "content": "X" * 4000})
+        messages.append({"role": "user", "content": "final user"})
+        messages.append({"role": "assistant", "content": "final reply"})
+        head_end = c_default.protect_first_n
+        assert (
+            c_default._find_tail_cut_by_tokens(messages, head_end)
+            == c_explicit._find_tail_cut_by_tokens(messages, head_end)
+        )
+
+    def test_blank_echo_does_not_count_toward_n(self):
+        """A blank platform echo (empty user row) must not consume one of the
+        N slots — otherwise the guarantee silently degrades to N-1 real turns
+        (the #69291 bug class the single anchor already fixed)."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=1,
+                quiet_mode=True,
+                min_tail_user_messages=3,
+            )
+        messages = [
+            {"role": "user", "content": "head"},                 # 0 (head)
+            {"role": "assistant", "content": "head reply"},      # 1
+            {"role": "user", "content": "real oldest"},          # 2  <- 3rd real user
+            {"role": "assistant", "content": "reply oldest"},    # 3
+            {"role": "user", "content": "real middle"},          # 4
+            {"role": "assistant", "content": "reply middle"},    # 5
+            {"role": "user", "content": ""},                     # 6  blank echo
+            {"role": "assistant", "content": "reply to echo"},   # 7
+            {"role": "user", "content": "   "},                  # 8  whitespace echo
+            {"role": "assistant", "content": "another reply"},   # 9
+            {"role": "user", "content": "real latest"},          # 10
+            {"role": "assistant", "content": "final reply"},     # 11
+        ]
+        head_end = c.protect_first_n  # = 1
+        # cut_idx=10 → only "real latest" in tail; N=3 must walk back to
+        # index 2 ("real oldest"), NOT stop at a blank echo (6/8).
+        result = c._ensure_last_n_user_messages_in_tail(
+            messages, cut_idx=10, head_end=head_end, n=3
+        )
+        assert result == 2, (
+            f"3rd real user is at index 2, got cut {result} — blank echoes "
+            "must not count toward N"
+        )
+        tail_users = [
+            m["content"] for m in messages[result:]
+            if m["role"] == "user" and m["content"].strip()
+        ]
+        assert {"real oldest", "real middle", "real latest"} <= set(tail_users)
+
+    def test_synthetic_compression_rows_do_not_count_toward_n(self):
+        """Compaction handoff banners and continuation markers carry
+        role="user" after SessionDB projection but are continuity artifacts —
+        they must not consume N slots."""
+        from agent.context_compressor import (
+            COMPRESSION_CONTINUATION_USER_CONTENT,
+        )
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=1,
+                quiet_mode=True,
+                min_tail_user_messages=2,
+            )
+        messages = [
+            {"role": "user", "content": "head"},                              # 0 (head)
+            {"role": "assistant", "content": "head reply"},                   # 1
+            {"role": "user", "content": "real second"},                       # 2
+            {"role": "assistant", "content": "reply second"},                 # 3
+            {"role": "user", "content": SUMMARY_PREFIX + " old summary"},     # 4 handoff
+            {"role": "assistant", "content": "ack"},                          # 5
+            {"role": "user", "content": COMPRESSION_CONTINUATION_USER_CONTENT},  # 6 marker
+            {"role": "assistant", "content": "ack 2"},                        # 7
+            {"role": "user", "content": "real latest"},                       # 8
+            {"role": "assistant", "content": "final reply"},                  # 9
+        ]
+        head_end = c.protect_first_n
+        result = c._ensure_last_n_user_messages_in_tail(
+            messages, cut_idx=8, head_end=head_end, n=2
+        )
+        assert result == 2, (
+            f"2nd real user is at index 2, got cut {result} — synthetic "
+            "compression rows must not count toward N"
+        )
+
+    def test_n_boundary_never_orphans_tool_results(self):
+        """Integration: with N=3 the full tail-cut pipeline must never place
+        a tool result in the tail whose parent assistant(tool_calls) was
+        summarized away, or vice versa (no-orphan in BOTH directions)."""
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=1,
+                quiet_mode=True,
+                min_tail_user_messages=3,
+            )
+        c.tail_token_budget = 100
+        messages = [
+            {"role": "user", "content": "head"},                                   # 0
+            {"role": "assistant", "content": "head reply"},                        # 1
+            {"role": "user", "content": "real 3"},                                 # 2
+            {"role": "assistant", "content": None,
+             "tool_calls": [{"id": "call_a", "function": {"name": "t", "arguments": "{}"}}]},  # 3
+            {"role": "tool", "content": "R" * 2000, "tool_call_id": "call_a"},     # 4
+            {"role": "assistant", "content": "reply 3"},                           # 5
+            {"role": "user", "content": "real 2"},                                 # 6
+            {"role": "assistant", "content": None,
+             "tool_calls": [{"id": "call_b", "function": {"name": "t", "arguments": "{}"}}]},  # 7
+            {"role": "tool", "content": "S" * 2000, "tool_call_id": "call_b"},     # 8
+            {"role": "assistant", "content": "reply 2"},                           # 9
+            {"role": "user", "content": "real 1"},                                 # 10
+            {"role": "assistant", "content": "reply 1"},                           # 11
+        ]
+        head_end = c.protect_first_n
+        cut = c._find_tail_cut_by_tokens(messages, head_end)
+        tail = messages[cut:]
+        tail_call_ids = {
+            tc.get("id")
+            for m in tail if m.get("role") == "assistant"
+            for tc in (m.get("tool_calls") or [])
+        }
+        tail_result_ids = {
+            m.get("tool_call_id") for m in tail if m.get("role") == "tool"
+        }
+        assert tail_call_ids == tail_result_ids, (
+            f"tool pair split across N-boundary: calls={tail_call_ids} "
+            f"results={tail_result_ids}"
+        )
+        tail_users = [m["content"] for m in tail if m["role"] == "user"]
+        assert {"real 1", "real 2", "real 3"} <= set(tail_users)
+
+    def test_n_guarantee_wins_over_tail_token_budget_and_floor(self):
+        """Interaction contract: the N-user guarantee WINS over both
+        tail_token_budget and _MAX_TAIL_MESSAGE_FLOOR.
+
+        The budget walk (and its bounded message floor) computes the initial
+        cut; the N-anchor then only ever pulls the cut BACKWARD (tail can
+        grow, never shrink), exactly like the existing single-user and
+        assistant anchors. So a tiny budget cannot roll real users 2..N into
+        the summary, and the floor remains a lower bound, not a cap, on the
+        anchored tail.
+        """
+        with patch("agent.context_compressor.get_model_context_length", return_value=200_000):
+            c = ContextCompressor(
+                model="test/model",
+                threshold_percent=0.50,
+                protect_first_n=1,
+                quiet_mode=True,
+                min_tail_user_messages=3,
+            )
+        # Budget covers roughly one bulky turn — without the N-anchor the
+        # cut lands after users 2..3.
+        c.tail_token_budget = 150
+        messages = [{"role": "user", "content": "head"},
+                    {"role": "assistant", "content": "head reply"}]
+        for i in (3, 2, 1):
+            messages.append({"role": "user", "content": f"real {i}"})
+            messages.append({"role": "assistant", "content": "B" * 6000})
+        head_end = c.protect_first_n
+        cut = c._find_tail_cut_by_tokens(messages, head_end)
+        tail = messages[cut:]
+        tail_users = [m["content"] for m in tail if m["role"] == "user"]
+        assert {"real 1", "real 2", "real 3"} <= set(tail_users), (
+            f"N-guarantee must win over the token budget; tail users: {tail_users}"
+        )
+        # The anchored tail legitimately exceeds the budget (and the 8-message
+        # floor is a minimum, not a cap): the guarantee is the stronger
+        # invariant by design.
+        from agent.context_compressor import _estimate_msg_budget_tokens
+        accumulated = sum(_estimate_msg_budget_tokens(m) for m in tail)
+        assert accumulated > c.tail_token_budget
+
+    def test_default_config_ships_behavior_preserving_value(self):
+        """DEFAULT_CONFIG ships min_tail_user_messages=1 so an unset key is
+        exactly the pre-feature single-anchor behavior."""
+        from hermes_cli.config import DEFAULT_CONFIG
+        assert DEFAULT_CONFIG["compression"]["min_tail_user_messages"] == 1
diff --git a/tests/agent/test_context_compressor_summary_continuity.py b/tests/agent/test_context_compressor_summary_continuity.py
index 18b4c76b625..642ee2dbdc0 100644
--- a/tests/agent/test_context_compressor_summary_continuity.py
+++ b/tests/agent/test_context_compressor_summary_continuity.py
@@ -725,3 +725,48 @@ def test_metadata_summary_decay_also_rehydrates_previous_summary():
     assert "metadata-only prior summary" in prompt
     # Grounding may prepend a task-snapshot section; pin the fresh body.
     assert (compressor._previous_summary or "").endswith("fresh summary")
+
+
+def test_empty_post_handoff_window_noops_without_summary_call():
+    """A latest handoff that consumes the window must not trigger an empty summary.
+
+    Regression test from PR #59526 (#59496), fixture adapted to current main:
+    the standalone handoff sits alone in the compressible window, strips to
+    None via _strip_context_summary_handoff_message, and leaves
+    turns_to_summarize empty — the guard must skip _generate_summary
+    entirely instead of wasting an aux LLM call on empty input.
+    """
+    compressor = _compressor()
+    old_summary = "WINDOW-END-SUMMARY durable facts already captured"
+    messages = [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": f"{SUMMARY_PREFIX}\n{old_summary}"},
+        {"role": "assistant", "content": "recent tail response"},
+        {"role": "user", "content": "tail request"},
+        {"role": "assistant", "content": "tail answer"},
+        {"role": "user", "content": "latest tail request"},
+        {"role": "assistant", "content": "latest tail answer"},
+    ]
+
+    with (
+        patch.object(compressor, "_find_tail_cut_by_tokens", return_value=2),
+        patch.object(compressor, "_generate_summary") as mock_generate_summary,
+    ):
+        result = compressor.compress(messages, current_tokens=90_000)
+
+    mock_generate_summary.assert_not_called()
+    assert result == messages
+    # The rehydrated summary state is deliberately kept: the handoff is
+    # genuinely present in the returned (unchanged) transcript.
+    assert compressor._previous_summary == old_summary
+    assert compressor.compression_count == 0
+    # Mirrors the sibling no-compressible-window guard (#40803): the shape
+    # cannot shrink, so it counts as an ineffective strike (routed through
+    # the durable write-through helper) to arm the anti-thrash breaker.
+    assert compressor._ineffective_compression_count == 1
+    assert compressor._last_compression_savings_pct == 0.0
+    assert compressor._last_summary_dropped_count == 0
+    assert compressor._last_summary_fallback_used is False
+    assert compressor._last_compress_aborted is False
+    telemetry = compressor._last_compression_telemetry or {}
+    assert telemetry.get("failure_class") == "empty_post_handoff_window"
diff --git a/tests/agent/test_context_engine.py b/tests/agent/test_context_engine.py
index 70eb8c71cad..c4250bcd129 100644
--- a/tests/agent/test_context_engine.py
+++ b/tests/agent/test_context_engine.py
@@ -181,6 +181,21 @@ class TestStubEngine:
         assert engine.last_prompt_tokens == 1000
         assert engine.last_completion_tokens == 200
 
+    def test_prune_tool_results_only_defaults_to_safe_noop(self):
+        # An engine implementing only the required interface (no prune override)
+        # must inherit the base no-op instead of raising AttributeError: the
+        # agent loop calls prune_tool_results_only() on the active engine after a
+        # tool call whenever full compression does not fire, so every pluggable
+        # ContextEngine reaches this path (see conversation_loop proactive-prune).
+        engine = StubEngine()
+        msgs = [
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi"},
+        ]
+        result, pruned = engine.prune_tool_results_only(msgs, current_tokens=10_000_000)
+        assert pruned == 0
+        assert result is msgs
+
 
 # ---------------------------------------------------------------------------
 # ContextCompressor session reset via ABC
diff --git a/tests/agent/test_context_engine_on_turn_complete_usage.py b/tests/agent/test_context_engine_on_turn_complete_usage.py
new file mode 100644
index 00000000000..b962c983c45
--- /dev/null
+++ b/tests/agent/test_context_engine_on_turn_complete_usage.py
@@ -0,0 +1,155 @@
+"""Integration test: ``finalize_turn`` forwards the turn's real usage to the
+``ContextEngine.on_turn_complete()`` observation hook.
+
+The hook is the engine's post-turn observation point, so it must receive the
+completed turn's canonical token usage (prompt/completion/total + the canonical
+``input_tokens`` / ``output_tokens`` / ``cache_read_tokens`` /
+``cache_write_tokens`` / ``reasoning_tokens`` buckets) when the host has it —
+not a hardcoded ``None`` — so the engine can weigh how large/expensive the
+selected context was before the next ``select_context()``.
+
+The conversation loop stashes the most recent provider response's usage on the
+agent as ``_last_turn_usage`` (the same dict shape fed to
+``update_from_response``); ``finalize_turn`` forwards it. On turns that never
+reach a provider response (early failure / interrupt) it stays ``None`` and the
+hook receives ``None``. These tests pin both ends of that contract through the
+real ``finalize_turn`` call site (the path that previously passed
+``usage=None``).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from agent.context_engine import ContextEngine
+
+# Reuse the minimal agent harness that exercises the real finalize_turn path.
+from tests.agent.test_turn_finalizer_cleanup_guard import _StubAgent, _run
+
+
+class _CapturingEngine(ContextEngine):
+    """Engine that records what on_turn_complete() receives."""
+
+    last_prompt_tokens = 0
+
+    def __init__(self) -> None:
+        self.captured: Dict[str, Any] = {}
+
+    @property
+    def name(self) -> str:
+        return "capturing"
+
+    def update_from_response(self, usage: Dict[str, Any]) -> None:
+        pass
+
+    def should_compress(self, prompt_tokens: int = None) -> bool:
+        return False
+
+    def compress(
+        self,
+        messages: List[Dict[str, Any]],
+        current_tokens: int = None,
+        focus_topic: str = None,
+    ) -> List[Dict[str, Any]]:
+        return messages
+
+    def on_turn_complete(self, messages, usage=None, **kwargs):
+        self.captured["seen"] = True
+        self.captured["usage"] = usage
+        self.captured["kwargs"] = kwargs
+
+
+CANONICAL_USAGE = {
+    "prompt_tokens": 1200,
+    "completion_tokens": 80,
+    "total_tokens": 1280,
+    "input_tokens": 1200,
+    "output_tokens": 80,
+    "cache_read_tokens": 1024,
+    "cache_write_tokens": 0,
+    "reasoning_tokens": 16,
+}
+
+
+def _agent_with_engine() -> _StubAgent:
+    agent = _StubAgent(raise_in=())
+    agent.context_compressor = _CapturingEngine()
+    return agent
+
+
+def test_finalize_turn_forwards_canonical_usage_when_available():
+    """A completed turn forwards the stashed canonical usage dict intact."""
+    agent = _agent_with_engine()
+    agent._last_turn_usage = dict(CANONICAL_USAGE)
+
+    _run(agent, final_response="done")
+
+    captured = agent.context_compressor.captured
+    assert captured.get("seen") is True
+    # The full canonical bucket set is forwarded unchanged — the engine relies
+    # on cache_read/write + reasoning, not just the legacy aggregate keys.
+    assert captured["usage"] == CANONICAL_USAGE
+    # Turn metadata still rides alongside usage.
+    assert captured["kwargs"]["turn_id"] == "turn-1"
+
+
+def test_finalize_turn_forwards_none_when_no_response_usage():
+    """An early-failure/interrupt turn (no stashed usage) forwards None."""
+    agent = _agent_with_engine()
+    # _last_turn_usage left unset, mirroring a turn that never reached a
+    # provider response.
+    if hasattr(agent, "_last_turn_usage"):
+        delattr(agent, "_last_turn_usage")
+
+    _run(agent, final_response="done")
+
+    captured = agent.context_compressor.captured
+    assert captured.get("seen") is True
+    assert captured["usage"] is None
+
+
+def test_finalization_seam_observes_interrupted_turn_with_none_usage():
+    """Pins the documented coverage contract for on_turn_complete().
+
+    on_turn_complete() fires from the turn-finalization seam and reports
+    ``usage=None`` on a finalized turn that never reached a provider response
+    (e.g. interrupt), forwarding the ``interrupted`` flag. This is the testable
+    (positive) half of the contract.
+
+    The negative half — abnormal early-return paths in ``run_conversation``
+    (content-policy block, provider terminal failure, etc.) bypass finalization
+    and therefore do NOT emit the hook — is documented as best-effort coverage.
+    It is intentionally not pinned here: exercising those inline early returns
+    requires a full ``run_conversation`` harness, and unifying all terminal
+    paths behind one seam is a separate follow-up.
+    """
+    from agent.turn_finalizer import finalize_turn
+
+    agent = _agent_with_engine()
+    if hasattr(agent, "_last_turn_usage"):
+        delattr(agent, "_last_turn_usage")  # never reached a provider response
+
+    finalize_turn(
+        agent,
+        final_response="interrupted mid-turn",
+        api_call_count=1,
+        interrupted=True,
+        failed=False,
+        messages=[
+            {"role": "user", "content": "do a thing"},
+            {"role": "assistant", "content": "partial"},
+        ],
+        conversation_history=None,
+        effective_task_id="task-1",
+        turn_id="turn-int",
+        user_message="do a thing",
+        original_user_message="do a thing",
+        _should_review_memory=False,
+        _turn_exit_reason="interrupt",
+    )
+
+    captured = agent.context_compressor.captured
+    assert captured.get("seen") is True
+    assert captured["usage"] is None
+    assert captured["kwargs"]["interrupted"] is True
+    assert captured["kwargs"]["turn_id"] == "turn-int"
diff --git a/tests/agent/test_context_engine_select_context.py b/tests/agent/test_context_engine_select_context.py
new file mode 100644
index 00000000000..c8523943708
--- /dev/null
+++ b/tests/agent/test_context_engine_select_context.py
@@ -0,0 +1,400 @@
+"""Tests for the per-turn ``ContextEngine.select_context()`` hook.
+
+``select_context()`` is the *selection / routing* verb — distinct from
+compression — that lets an external context engine replace which context
+enters the prompt for a single request, every turn, independent of
+``should_compress()``. It is additive and no-op by default, and the host
+call site (``_apply_context_engine_selection``) is fail-open: a missing hook,
+an exception, or an invalid return value must leave the assembled request
+untouched and must never mutate persisted history.
+
+This pins the contract that engines such as retrieval-augmented, topic-routed,
+and role-switching engines rely on (RFC #36765), consolidating the per-turn
+request-assembly surface proposed across #41918, #24949, #47109, and #50053.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+from unittest.mock import MagicMock
+
+from agent.context_engine import ContextEngine
+from agent.conversation_loop import (
+    _apply_context_engine_selection,
+    _notify_context_engine_turn_complete,
+)
+
+
+class _MinimalEngine(ContextEngine):
+    """Concrete engine implementing only the abstract methods."""
+
+    @property
+    def name(self) -> str:
+        return "minimal"
+
+    def update_from_response(self, usage: Dict[str, Any]) -> None:
+        pass
+
+    def should_compress(self, prompt_tokens: int = None) -> bool:
+        return False
+
+    def compress(
+        self,
+        messages: List[Dict[str, Any]],
+        current_tokens: int = None,
+        focus_topic: str = None,
+    ) -> List[Dict[str, Any]]:
+        return messages
+
+
+def _agent_with(engine) -> Any:
+    agent = MagicMock()
+    agent.session_id = "test-session"
+    agent.context_compressor = engine
+    return agent
+
+
+REQUEST = [
+    {"role": "system", "content": "sys"},
+    {"role": "user", "content": "hello"},
+]
+HISTORY = [{"role": "user", "content": "hello"}]
+
+
+# -- ABC default -----------------------------------------------------------
+
+def test_default_select_context_is_noop():
+    """The base implementation returns None (no replacement)."""
+    engine = _MinimalEngine()
+    assert (
+        engine.select_context(
+            REQUEST,
+            conversation_messages=HISTORY,
+            incoming_message=HISTORY[-1],
+            budget_tokens=0,
+        )
+        is None
+    )
+
+
+# -- Host call site: _apply_context_engine_selection -----------------------
+
+def test_none_return_leaves_request_unchanged():
+    """An engine returning None falls through to the assembled request."""
+    engine = _MinimalEngine()  # default select_context -> None
+    agent = _agent_with(engine)
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=MagicMock()
+    )
+    assert out is REQUEST
+
+
+def test_base_noop_select_context_is_short_circuited_not_called():
+    """Non-implementing engines skip the hook entirely (no call, no copies).
+
+    The built-in ContextCompressor — and any engine that merely inherits the
+    ABC default — must keep the default request path byte-identical AND pay
+    nothing per request. ``hasattr`` alone cannot distinguish "inherits the
+    no-op default" from "implements the hook" because the ABC defines
+    ``select_context`` on every engine; the host therefore identity-checks the
+    bound method against ``ContextEngine.select_context`` and short-circuits
+    WITHOUT calling it or building the shallow reference copies. This pins
+    that: even a base implementation patched to raise is never invoked.
+    """
+    from unittest.mock import patch as _patch
+
+    def _explode(self, request_messages, **kwargs):
+        raise AssertionError("base select_context must not be invoked")
+
+    engine = _MinimalEngine()  # inherits the ABC default
+    agent = _agent_with(engine)
+    logger = MagicMock()
+    with _patch.object(ContextEngine, "select_context", _explode):
+        out = _apply_context_engine_selection(
+            agent, REQUEST, HISTORY, HISTORY[-1], logger=logger
+        )
+    assert out is REQUEST
+    assert not logger.warning.called
+
+
+def test_builtin_compressor_inherits_base_select_context():
+    """The built-in ContextCompressor must NOT implement the new verbs.
+
+    Guards the default-path byte-identity contract: if someone overrides
+    ``select_context`` / ``on_turn_complete`` on ContextCompressor, the host
+    short-circuits no longer skip it and the default request pipeline gains a
+    per-request call — update this pin only together with that decision.
+    """
+    from agent.context_compressor import ContextCompressor
+
+    assert "select_context" not in ContextCompressor.__dict__
+    assert "on_turn_complete" not in ContextCompressor.__dict__
+
+
+def test_missing_hook_leaves_request_unchanged():
+    """An engine without select_context (older/stub base) is a no-op."""
+    engine = object()  # no select_context attribute
+    agent = _agent_with(engine)
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=MagicMock()
+    )
+    assert out is REQUEST
+
+
+def test_no_engine_leaves_request_unchanged():
+    agent = MagicMock()
+    agent.session_id = "test-session"
+    agent.context_compressor = None
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=MagicMock()
+    )
+    assert out is REQUEST
+
+
+def test_valid_list_replaces_request():
+    """A valid list of dicts replaces the request messages for this call."""
+    replacement = [
+        {"role": "system", "content": "sys"},
+        {"role": "user", "content": "routed-context"},
+    ]
+
+    class _Engine(_MinimalEngine):
+        def select_context(self, request_messages, **kwargs):
+            return replacement
+
+    agent = _agent_with(_Engine())
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=MagicMock()
+    )
+    assert out is replacement
+
+
+def test_exception_fails_open():
+    """A raising hook is swallowed; the unmodified request is used."""
+
+    class _Engine(_MinimalEngine):
+        def select_context(self, request_messages, **kwargs):
+            raise RuntimeError("backend offline")
+
+    logger = MagicMock()
+    agent = _agent_with(_Engine())
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=logger
+    )
+    assert out is REQUEST
+    assert logger.warning.called
+
+
+def test_non_list_return_is_ignored():
+    """A non-list return value is rejected and logged, request unchanged."""
+
+    class _Engine(_MinimalEngine):
+        def select_context(self, request_messages, **kwargs):
+            return {"role": "user", "content": "oops not a list"}
+
+    logger = MagicMock()
+    agent = _agent_with(_Engine())
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=logger
+    )
+    assert out is REQUEST
+    assert logger.warning.called
+
+
+def test_list_of_non_dicts_is_ignored():
+    """A list that isn't all dicts is rejected, request unchanged."""
+
+    class _Engine(_MinimalEngine):
+        def select_context(self, request_messages, **kwargs):
+            return ["not", "dicts"]
+
+    agent = _agent_with(_Engine())
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=MagicMock()
+    )
+    assert out is REQUEST
+
+
+def test_empty_list_keeps_original_request():
+    """An empty list must fall open to the original request.
+
+    ``all([])`` is ``True``, so without an emptiness check a ``[]`` returned by
+    a failing/buggy engine would replace a valid assembled request with an
+    empty message list the downstream sanitizers cannot restore — reaching the
+    provider as an invalid request instead of failing open. Guards the fail-open
+    contract.
+    """
+
+    class _Engine(_MinimalEngine):
+        def select_context(self, request_messages, **kwargs):
+            return []
+
+    logger = MagicMock()
+    agent = _agent_with(_Engine())
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=logger
+    )
+    assert out is REQUEST
+    assert logger.warning.called
+
+
+def test_engine_mutating_inputs_cannot_corrupt_persisted_state():
+    """An engine that mutates its read-only inputs in place must not affect the
+    persisted conversation history / incoming message.
+
+    ``conversation_messages`` and ``incoming_message`` are reference-only
+    context. The host passes shallow copies, so even a misbehaving engine that
+    appends to / edits them in ``select_context()`` cannot alter the live
+    persisted objects. Enforces the request-only contract (not just documents).
+    """
+    history = [{"role": "user", "content": "hello"}]
+    incoming = history[-1]
+    history_snapshot = [dict(m) for m in history]
+    incoming_snapshot = dict(incoming)
+
+    class _Engine(_MinimalEngine):
+        def select_context(self, request_messages, *, conversation_messages=None,
+                            incoming_message=None, **kwargs):
+            # Misbehaving engine: mutate the read-only inputs in place.
+            if conversation_messages is not None:
+                conversation_messages.append({"role": "user", "content": "INJECTED"})
+                if conversation_messages and isinstance(conversation_messages[0], dict):
+                    conversation_messages[0]["content"] = "TAMPERED"
+            if isinstance(incoming_message, dict):
+                incoming_message["content"] = "TAMPERED"
+            return None
+
+    agent = _agent_with(_Engine())
+    _apply_context_engine_selection(
+        agent, REQUEST, history, incoming, logger=MagicMock()
+    )
+    # Persisted history + incoming message are untouched despite the engine's
+    # in-place mutation of the copies it received.
+    assert history == history_snapshot
+    assert incoming == incoming_snapshot
+
+
+def test_persisted_history_not_mutated():
+    """The hook must not mutate the persisted conversation history."""
+
+    class _Engine(_MinimalEngine):
+        def select_context(self, request_messages, *, conversation_messages=None, **kwargs):
+            # Even a misbehaving engine touching its inputs must not affect
+            # what the host persists — the host passes the live list, so we
+            # assert the host contract by checking the engine received it and
+            # the canonical copy is unchanged after the call.
+            return list(request_messages)
+
+    history_snapshot = [dict(m) for m in HISTORY]
+    agent = _agent_with(_Engine())
+    _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=MagicMock()
+    )
+    assert HISTORY == history_snapshot
+
+
+# -- cache-stability + downstream-sanitizer contract -----------------------
+
+def test_noop_preserves_request_byte_stable_for_cache():
+    """No-op default must leave the request byte-identical.
+
+    Prompt-cache stability is a host invariant (AGENTS.md): the hook runs
+    before cache-control, so a no-op engine must not perturb the list —
+    otherwise cache breakpoints would shift for every existing engine. The
+    host returns the *same object*, so cache-control sees identical input.
+    """
+    snapshot = [dict(m) for m in REQUEST]
+    agent = _agent_with(_MinimalEngine())  # default select_context -> None
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=MagicMock()
+    )
+    assert out is REQUEST          # same object -> byte-stable for cache-control
+    assert REQUEST == snapshot     # unperturbed
+
+
+def test_role_unusual_replacement_passed_through_for_downstream_sanitizers():
+    """The hook does structural validation only; role/tool normalization is
+    deferred to the existing downstream sanitizers.
+
+    A `system -> user -> user` replacement (the exact shape flagged as a
+    role-alternation risk on sibling PRs) is well-formed structurally, so the
+    host returns it verbatim. Role-pairing/orphaned-tool cleanup runs *after*
+    this hook in the request pipeline (`_sanitize_api_messages`,
+    `_drop_thinking_only_and_merge_users`), so select_context cannot emit a
+    malformed request that bypasses validation.
+    """
+    role_unusual = [
+        {"role": "system", "content": "sys"},
+        {"role": "user", "content": "a"},
+        {"role": "user", "content": "b"},
+    ]
+
+    class _Engine(_MinimalEngine):
+        def select_context(self, request_messages, **kwargs):
+            return role_unusual
+
+    agent = _agent_with(_Engine())
+    out = _apply_context_engine_selection(
+        agent, REQUEST, HISTORY, HISTORY[-1], logger=MagicMock()
+    )
+    assert out is role_unusual  # accepted structurally; downstream sanitizers normalize
+
+
+# -- on_turn_complete (post-turn observation) ------------------------------
+
+def test_default_on_turn_complete_is_noop():
+    """The base on_turn_complete returns None and does nothing."""
+    assert _MinimalEngine().on_turn_complete(HISTORY, usage=None) is None
+
+
+def test_on_turn_complete_called_with_snapshot_and_meta():
+    """Host forwards a transcript copy + metadata; base no-op is skipped."""
+    captured = {}
+
+    class _Engine(_MinimalEngine):
+        def on_turn_complete(self, messages, usage=None, **kwargs):
+            captured["messages"] = messages
+            captured["usage"] = usage
+            captured["kwargs"] = kwargs
+
+    agent = _agent_with(_Engine())
+    _notify_context_engine_turn_complete(
+        agent, HISTORY, usage={"total_tokens": 12}, logger=MagicMock(),
+        turn_id="t1", api_call_count=1,
+    )
+    assert captured["messages"] == HISTORY
+    assert captured["messages"] is not HISTORY  # shallow copy
+    assert captured["usage"] == {"total_tokens": 12}
+    assert captured["kwargs"]["turn_id"] == "t1"
+    assert captured["kwargs"]["api_call_count"] == 1
+
+
+def test_on_turn_complete_base_noop_is_skipped():
+    """An engine that only inherits the base no-op is handled safely.
+
+    The helper short-circuits the base implementation (so non-implementing
+    engines pay nothing), and in any case must not raise.
+    """
+    agent = _agent_with(_MinimalEngine())  # inherits base on_turn_complete
+    _notify_context_engine_turn_complete(agent, HISTORY, logger=MagicMock())
+
+
+def test_on_turn_complete_fails_open():
+    """A raising observation hook is swallowed and logged."""
+
+    class _Engine(_MinimalEngine):
+        def on_turn_complete(self, messages, usage=None, **kwargs):
+            raise RuntimeError("indexing backend down")
+
+    logger = MagicMock()
+    agent = _agent_with(_Engine())
+    _notify_context_engine_turn_complete(agent, HISTORY, logger=logger)
+    assert logger.warning.called
+
+
+def test_on_turn_complete_missing_engine_is_safe():
+    agent = MagicMock()
+    agent.session_id = "s"
+    agent.context_compressor = None
+    # No engine -> silent return, no raise.
+    _notify_context_engine_turn_complete(agent, HISTORY, logger=MagicMock())
diff --git a/tests/agent/test_context_references.py b/tests/agent/test_context_references.py
index 1fab3ef1b74..51f66fb937a 100644
--- a/tests/agent/test_context_references.py
+++ b/tests/agent/test_context_references.py
@@ -445,3 +445,25 @@ async def test_canonical_guard_fails_closed_when_lookup_raises(tmp_path: Path, m
         "credential deny-list" in warning or "sensitive credential" in warning
         for warning in result.warnings
     )
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "/tmp/plain.png",
+        "/Users/me/Library/Application Support/Hermes/composer-images/a.png",
+        r"C:\Users\John Doe\Pictures\cat.png",
+        "/tmp/report (final).pdf",
+        "/tmp/it's here.png",
+        '/tmp/say "hi".png',
+    ],
+)
+def test_format_reference_value_round_trips_through_the_parser(value):
+    """Whatever the path contains, the formatted ref must parse back whole —
+    an unquoted value stops at the first space and strands the tail as text."""
+    from agent.context_references import REFERENCE_PATTERN, format_reference_value
+
+    match = REFERENCE_PATTERN.search(f"@file:{format_reference_value(value)}")
+
+    assert match is not None
+    assert match.group("value").strip("`\"'") == value
diff --git a/tests/agent/test_copilot_acp_client.py b/tests/agent/test_copilot_acp_client.py
index 1d1d28cc542..cfe6c78c7df 100644
--- a/tests/agent/test_copilot_acp_client.py
+++ b/tests/agent/test_copilot_acp_client.py
@@ -203,6 +203,84 @@ class CopilotACPClientSafetyTests(unittest.TestCase):
         self.assertNotIn("abc123def456", content)
         self.assertIn("OPENAI_API_KEY=", content)
 
+    def test_fs_read_text_file_decodes_as_utf8_under_non_utf8_locale(self) -> None:
+        """Regression for #18637 (bug 2): fs/read_text_file used
+        ``path.read_text()`` with no explicit encoding, so on Windows
+        GBK/CP932/CP949 locales the Copilot read_file tool crashed on any
+        source file with non-ASCII content (e.g. a CJK comment, an em dash,
+        or UTF-8 BOM)."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target = root / "note.md"
+            target.write_text("# 中文标题\nem dash — here\n", encoding="utf-8")
+
+            original_read_text = Path.read_text
+
+            def strict_read_text(self, encoding=None, errors=None, **kwargs):
+                if self == target and encoding != "utf-8":
+                    raise UnicodeDecodeError(
+                        "gbk", b"\x94", 0, 1, "illegal multibyte sequence"
+                    )
+                return original_read_text(
+                    self, encoding=encoding, errors=errors, **kwargs
+                )
+
+            with patch.object(Path, "read_text", strict_read_text):
+                response = self._dispatch(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": 10,
+                        "method": "fs/read_text_file",
+                        "params": {"path": str(target)},
+                    },
+                    cwd=str(root),
+                )
+
+        self.assertNotIn("error", response)
+        content = ((response.get("result") or {}).get("content") or "")
+        self.assertIn("中文标题", content)
+        self.assertIn("em dash —", content)
+
+    def test_fs_write_text_file_encodes_as_utf8(self) -> None:
+        """Regression for #18637 (bug 2): fs/write_text_file used
+        ``path.write_text()`` with no explicit encoding, so on non-UTF-8
+        locales the Copilot write tool could not emit code/config files
+        containing any char outside the platform codec."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target = root / "out.md"
+            payload = "# 中文标题\nem dash — here\n"
+
+            original_write_text = Path.write_text
+
+            def strict_write_text(
+                self, data, encoding=None, errors=None, **kwargs
+            ):
+                if self == target and encoding != "utf-8":
+                    raise UnicodeEncodeError(
+                        "gbk", data, 0, 1, "illegal multibyte sequence"
+                    )
+                return original_write_text(
+                    self, data, encoding=encoding, errors=errors, **kwargs
+                )
+
+            with patch.object(Path, "write_text", strict_write_text):
+                response = self._dispatch(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": 11,
+                        "method": "fs/write_text_file",
+                        "params": {
+                            "path": str(target),
+                            "content": payload,
+                        },
+                    },
+                    cwd=str(root),
+                )
+
+            self.assertNotIn("error", response)
+            self.assertEqual(target.read_text(encoding="utf-8"), payload)
+
     def test_write_text_file_reuses_write_denylist(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             home = Path(tmpdir) / "home"
diff --git a/tests/agent/test_credential_pool_routing.py b/tests/agent/test_credential_pool_routing.py
index 8f093f86b0e..55b907a717e 100644
--- a/tests/agent/test_credential_pool_routing.py
+++ b/tests/agent/test_credential_pool_routing.py
@@ -405,11 +405,12 @@ class TestFailureAttribution:
         entry.update(overrides)
         return entry
 
-    def _agent(self, pool, failing_key):
+    def _agent(self, pool, failing_key, credential_id=None):
         return SimpleNamespace(
             provider="anthropic",
             api_key=failing_key,
             _credential_pool=pool,
+            _credential_pool_entry_id=credential_id,
             _swap_credential=MagicMock(),
         )
 
@@ -521,3 +522,84 @@ class TestFailureAttribution:
         assert statuses["cred-0"] != "exhausted"
         swapped = agent._swap_credential.call_args[0][0]
         assert swapped.id == "cred-0"
+
+    def test_auth_refresh_uses_stable_id_after_runtime_key_changes(
+        self, tmp_path, monkeypatch
+    ):
+        """A refreshed pool token must not detach the failed request from the
+        entry that supplied its now-stale runtime key."""
+        pool = self._make_pool(
+            tmp_path, monkeypatch,
+            [self._entry(0, "new-runtime-key")],
+        )
+        selected = pool.select()
+        assert selected.id == "cred-0"
+        assert pool.entry_id_for_api_key("new-runtime-key") == "cred-0"
+
+        agent = self._agent(
+            pool,
+            failing_key="stale-runtime-key",
+            credential_id="cred-0",
+        )
+        agent._is_entitlement_failure = MagicMock(return_value=False)
+
+        from agent.agent_runtime_helpers import recover_with_credential_pool
+
+        recovered, _ = recover_with_credential_pool(
+            agent, status_code=401, has_retried_429=False
+        )
+
+        assert recovered is False
+        assert self._statuses(pool)["cred-0"] == "exhausted"
+        agent._swap_credential.assert_not_called()
+
+    def test_unmatched_key_does_not_retry_only_pool_entry(
+        self, tmp_path, monkeypatch
+    ):
+        """Legacy agents without a stable id must stop when an unmatched key
+        has no different credential to rotate to."""
+        pool = self._make_pool(
+            tmp_path, monkeypatch,
+            [self._entry(0, "pool-runtime-key")],
+        )
+        agent = self._agent(pool, failing_key="wrapper-runtime-key")
+        agent._is_entitlement_failure = MagicMock(return_value=False)
+
+        from agent.agent_runtime_helpers import recover_with_credential_pool
+
+        recovered, _ = recover_with_credential_pool(
+            agent, status_code=401, has_retried_429=False
+        )
+
+        assert recovered is False
+        assert self._statuses(pool)["cred-0"] != "exhausted"
+        agent._swap_credential.assert_not_called()
+
+    def test_stable_id_rotates_from_failed_entry_when_cursor_points_elsewhere(
+        self, tmp_path, monkeypatch
+    ):
+        """Stable identity wins over both a stale key and the shared cursor."""
+        pool = self._make_pool(
+            tmp_path, monkeypatch,
+            [self._entry(0, "key-a"), self._entry(1, "key-b-new")],
+        )
+        assert pool.select().id == "cred-0"
+        agent = self._agent(
+            pool,
+            failing_key="key-b-old",
+            credential_id="cred-1",
+        )
+        agent._is_entitlement_failure = MagicMock(return_value=False)
+
+        from agent.agent_runtime_helpers import recover_with_credential_pool
+
+        recovered, _ = recover_with_credential_pool(
+            agent, status_code=401, has_retried_429=False
+        )
+
+        assert recovered is True
+        statuses = self._statuses(pool)
+        assert statuses["cred-1"] == "exhausted"
+        assert statuses["cred-0"] != "exhausted"
+        swapped = agent._swap_credential.call_args[0][0]
+        assert swapped.id == "cred-0"
diff --git a/tests/agent/test_credential_pool_unmatched_rotation_bound.py b/tests/agent/test_credential_pool_unmatched_rotation_bound.py
new file mode 100644
index 00000000000..ded5bbd0302
--- /dev/null
+++ b/tests/agent/test_credential_pool_unmatched_rotation_bound.py
@@ -0,0 +1,186 @@
+"""#70401: the unmatched-identity rotation branch in
+``mark_exhausted_and_rotate()`` must be bounded and must not write cooldowns
+onto innocent healthy keys.
+
+With OAuth-token auth (provider ``nous``), the upstream 401's ``api_key_hint``
+never matches any pool entry's ``runtime_api_key`` — the wrapper's runtime key
+rotates. The no-match branch deliberately marks nothing exhausted (marking
+would quarantine an innocent healthy key for the full cooldown TTL) and hands
+back a fresh selection. But because nothing is ever marked, the pool can never
+converge to the "no available entries" state: with the old code the caller
+retried the same dead token forever (~6/sec), starving the event loop so chat
+``/stop`` interrupts were never processed; only killing the gateway ended it.
+
+The fix keeps the don't-mark-innocent-keys semantics (see the breaker/cooldown
+design notes in ``mark_exhausted_and_rotate`` — the pool only trips on
+confirmed-empty state, and no cooldown is invented here) but BOUNDS the
+branch: after one full lap of the available entries with no recovery, the
+rotation returns None so the caller surfaces the error / activates fallback.
+Healthy keys carry no cooldown and are immediately available next turn — this
+does not reintroduce hammering, it stops it.
+"""
+import json
+
+import pytest
+
+
+def _seed_pool(tmp_path, monkeypatch, entries, provider="openrouter"):
+    hermes_home = tmp_path / "hermes"
+    hermes_home.mkdir(parents=True, exist_ok=True)
+    (hermes_home / "auth.json").write_text(
+        json.dumps({"version": 1, "credential_pool": {provider: entries}})
+    )
+    monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+    from agent.credential_pool import load_pool
+
+    return load_pool(provider)
+
+
+def _entry(idx, key):
+    return {
+        "id": f"cred-{idx}",
+        "label": f"key-{idx}",
+        "auth_type": "api_key",
+        "priority": idx,
+        "source": "manual",
+        "access_token": key,
+    }
+
+
+class TestUnmatchedHintRotationIsBounded:
+    def test_single_entry_pool_returns_none_immediately(
+        self, tmp_path, monkeypatch
+    ):
+        """Single-entry OAuth pool + unmatched hint → None right away (a
+        no-op rotation must not be reported as recovery)."""
+        pool = _seed_pool(tmp_path, monkeypatch, [_entry(0, "pool-key")])
+        assert pool.select() is not None
+
+        result = pool.mark_exhausted_and_rotate(
+            status_code=401,
+            error_context={"reason": "unauthorized"},
+            api_key_hint="oauth-runtime-token-that-matches-nothing",
+        )
+
+        assert result is None
+        # No innocent key was quarantined.
+        statuses = {e.id: e.last_status for e in pool._entries}
+        assert statuses["cred-0"] != "exhausted"
+
+    def test_multi_entry_pool_unmatched_hint_loop_terminates(
+        self, tmp_path, monkeypatch
+    ):
+        """Multi-entry pool: consecutive unmatched-hint rotations must reach
+        None within one lap of the pool instead of ping-ponging forever."""
+        pool = _seed_pool(
+            tmp_path, monkeypatch,
+            [_entry(0, "key-a"), _entry(1, "key-b"), _entry(2, "key-c")],
+        )
+        assert pool.select() is not None
+
+        results = []
+        for _ in range(10):  # caller's retry loop
+            nxt = pool.mark_exhausted_and_rotate(
+                status_code=401,
+                error_context={"reason": "unauthorized"},
+                api_key_hint="oauth-runtime-token-that-matches-nothing",
+            )
+            results.append(nxt)
+            if nxt is None:
+                break
+        else:
+            pytest.fail(
+                "unbounded 401 retry loop: 10 unmatched-hint rotations never "
+                "returned None (#70401)"
+            )
+
+        # Bounded within one lap (3 available entries → at most 3 rotations
+        # before the streak trips).
+        assert len(results) <= 4
+        assert results[-1] is None
+        # The escape must NOT have invented cooldowns for healthy keys.
+        statuses = {e.id: e.last_status for e in pool._entries}
+        assert all(status != "exhausted" for status in statuses.values()), (
+            f"innocent keys were quarantined: {statuses}"
+        )
+
+    def test_streak_resets_when_identity_matches(self, tmp_path, monkeypatch):
+        """A rotation that identifies a real entry resets the streak — the
+        bound only fires on CONSECUTIVE unmatched rotations."""
+        pool = _seed_pool(
+            tmp_path, monkeypatch,
+            [_entry(0, "key-a"), _entry(1, "key-b"), _entry(2, "key-c")],
+        )
+        assert pool.select() is not None
+
+        # Two unmatched rotations (streak = 2, below the 3-entry bound).
+        for _ in range(2):
+            assert pool.mark_exhausted_and_rotate(
+                status_code=401,
+                error_context={"reason": "unauthorized"},
+                api_key_hint="no-match",
+            ) is not None
+
+        # A matched rotation (key-a) marks a real entry → streak resets.
+        assert pool.mark_exhausted_and_rotate(
+            status_code=401,
+            error_context={"reason": "unauthorized"},
+            api_key_hint="key-a",
+        ) is not None
+
+        # A fresh unmatched episode still gets its full lap (2 available
+        # entries remain, so two rotations before the bound trips).
+        assert pool.mark_exhausted_and_rotate(
+            status_code=401,
+            error_context={"reason": "unauthorized"},
+            api_key_hint="no-match",
+        ) is not None
+
+    def test_streak_resets_on_normal_selection(self, tmp_path, monkeypatch):
+        """select() (a fresh episode) clears any leftover streak so the next
+        failure gets its full rotation budget."""
+        pool = _seed_pool(
+            tmp_path, monkeypatch,
+            [_entry(0, "key-a"), _entry(1, "key-b")],
+        )
+        assert pool.select() is not None
+
+        # Burn the streak up to (but not past) the bound.
+        for _ in range(2):
+            pool.mark_exhausted_and_rotate(
+                status_code=401,
+                error_context={"reason": "unauthorized"},
+                api_key_hint="no-match",
+            )
+
+        # New turn: a successful normal selection resets the streak.
+        assert pool.select() is not None
+        assert pool._unmatched_rotation_streak == 0
+
+        # The next unmatched rotation is attempt 1 of a new episode.
+        assert pool.mark_exhausted_and_rotate(
+            status_code=401,
+            error_context={"reason": "unauthorized"},
+            api_key_hint="no-match",
+        ) is not None
+
+    def test_matched_hint_path_unaffected(self, tmp_path, monkeypatch):
+        """Regression guard: the normal matched-hint path still marks the
+        failing entry and rotates to the healthy one."""
+        pool = _seed_pool(
+            tmp_path, monkeypatch,
+            [_entry(0, "key-healthy"), _entry(1, "key-failed")],
+        )
+        assert pool.select().access_token == "key-healthy"
+
+        nxt = pool.mark_exhausted_and_rotate(
+            status_code=401,
+            error_context={"reason": "unauthorized"},
+            api_key_hint="key-failed",
+        )
+
+        statuses = {e.id: e.last_status for e in pool._entries}
+        assert statuses["cred-1"] == "exhausted"
+        assert statuses["cred-0"] != "exhausted"
+        assert nxt is not None
+        assert nxt.access_token == "key-healthy"
diff --git a/tests/agent/test_gemini_native_adapter.py b/tests/agent/test_gemini_native_adapter.py
index e797d6b2ae7..e7493fe4918 100644
--- a/tests/agent/test_gemini_native_adapter.py
+++ b/tests/agent/test_gemini_native_adapter.py
@@ -52,6 +52,43 @@ def test_build_native_request_preserves_thought_signature_on_tool_replay():
     assert parts[0]["thoughtSignature"] == "sig-123"
 
 
+def test_build_native_request_emits_sentinel_for_cross_provider_tool_call():
+    """Cross-provider tool_calls (xAI/Anthropic -> Gemini fallback) carry no
+    Gemini thoughtSignature.  Without a sentinel, Gemini 3 thinking models
+    reject the request with 400 INVALID_ARGUMENT.  The native adapter must
+    emit the same ``skip_thought_signature_validator`` sentinel that the
+    Cloud Code Assist adapter already uses for the same scenario.
+    """
+    from agent.gemini_native_adapter import build_gemini_request
+
+    request = build_gemini_request(
+        messages=[
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {
+                            "name": "get_weather",
+                            "arguments": '{"city": "Paris"}',
+                        },
+                        # No extra_content — this tool_call originated from a
+                        # non-Gemini provider during fallback.
+                    }
+                ],
+            },
+        ],
+        tools=[],
+        tool_choice=None,
+    )
+
+    parts = request["contents"][0]["parts"]
+    assert parts[0]["functionCall"]["name"] == "get_weather"
+    assert parts[0]["thoughtSignature"] == "skip_thought_signature_validator"
+
+
 def test_build_native_request_uses_original_function_name_for_tool_result():
     from agent.gemini_native_adapter import build_gemini_request
 
diff --git a/tests/agent/test_ghost_skill_pruning.py b/tests/agent/test_ghost_skill_pruning.py
new file mode 100644
index 00000000000..a0594d84f52
--- /dev/null
+++ b/tests/agent/test_ghost_skill_pruning.py
@@ -0,0 +1,388 @@
+"""Ghost-skill defense tests (#32106, salvage of PR #44166).
+
+When compaction reduces an old ``skill_view`` result to a metadata-only
+summary, the model still believes the skill is loaded even though its
+instructions are gone. The defense has three layers:
+
+- P0/P1: the pruned tool-result summary carries a canonical
+  ``[SKILL_PRUNED: ...]`` marker with the exact reload call, and the
+  system prompt (SKILLS_GUIDANCE) tells the model how to react to it.
+- Phase-1 protection: a skill loaded just before compaction (or actively
+  referenced in the protected tail) keeps its full body through the
+  ordinary prune passes.
+- P2: markers entering the summarizer are extracted BEFORE the aux LLM
+  call and deterministically re-injected if the model paraphrased them
+  away — including on the static fallback path.
+
+Test patterns for the marker emit checks adapted from PR #32375
+(@LeonSGP43) with credit.
+"""
+
+from unittest.mock import MagicMock, patch
+
+from agent.context_compressor import (
+    SKILL_PRUNED_MARKER_PREFIX,
+    SUMMARY_PREFIX,
+    ContextCompressor,
+    _collect_protected_skill_names,
+    _extract_pruned_skill_names,
+    _MAX_PRUNED_SKILL_MARKERS,
+    _reinject_pruned_skill_markers,
+    _skill_pruned_marker,
+    _summarize_tool_result,
+)
+
+
+def _make_compressor(**overrides):
+    kwargs = dict(
+        model="test/model",
+        quiet_mode=True,
+        protect_first_n=1,
+        protect_last_n=2,
+    )
+    kwargs.update(overrides)
+    with patch(
+        "agent.context_compressor.get_model_context_length", return_value=100000
+    ):
+        return ContextCompressor(**kwargs)
+
+
+def _skill_view_pair(call_id, skill_name, size=6000):
+    return [
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [{
+                "id": call_id,
+                "type": "function",
+                "function": {
+                    "name": "skill_view",
+                    "arguments": f'{{"name":"{skill_name}"}}',
+                },
+            }],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": call_id,
+            "content": f"# {skill_name} instructions\n" + "x" * size,
+        },
+    ]
+
+
+class TestSkillPrunedMarkerEmit:
+    """Marker emit — patterns adapted from PR #32375 (@LeonSGP43)."""
+
+    def test_skill_view_summary_marks_pruned_content(self):
+        summary = _summarize_tool_result(
+            "skill_view", '{"name":"docker-management"}', "x" * 6000
+        )
+        assert summary.startswith("[skill_view] name=docker-management (6,000 chars)")
+        assert _skill_pruned_marker("docker-management") in summary
+        assert "reload with skill_view(name='docker-management')" in summary
+
+    def test_small_skill_view_summary_not_marked(self):
+        summary = _summarize_tool_result(
+            "skill_view", '{"name":"docker-management"}', "x" * 1234
+        )
+        assert summary == "[skill_view] name=docker-management (1,234 chars)"
+        assert SKILL_PRUNED_MARKER_PREFIX not in summary
+
+    def test_other_skill_tool_summaries_remain_metadata_only(self):
+        summary = _summarize_tool_result(
+            "skills_list", '{"name":"docker-management"}', "x" * 6000
+        )
+        assert summary == "[skills_list] name=docker-management (6,000 chars)"
+        assert SKILL_PRUNED_MARKER_PREFIX not in summary
+
+    def test_marker_extractor_round_trips_the_emitted_marker(self):
+        """Emit and check sides share one canonical string.
+
+        The original PR #44166 emitted ``[SKILL_PRUNED:`` but presence-
+        checked ``[SKILL_PRUNED]`` — re-injection fired even when the
+        marker had survived. Pin the round trip.
+        """
+        summary = _summarize_tool_result("skill_view", '{"name":"pdf"}', "x" * 6000)
+        assert _extract_pruned_skill_names(summary) == ["pdf"]
+        assert _skill_pruned_marker("pdf") in summary
+
+
+class TestReinjectPrunedSkillMarkers:
+    def test_no_duplicate_when_canonical_marker_survived(self):
+        marker = _skill_pruned_marker("pdf")
+        out = _reinject_pruned_skill_markers("summary body\n" + marker, ["pdf"])
+        assert out.count(SKILL_PRUNED_MARKER_PREFIX) == 1
+
+    def test_reinjects_when_marker_paraphrased_away(self):
+        out = _reinject_pruned_skill_markers(
+            "The pdf skill was loaded earlier but its content was summarized.",
+            ["pdf"],
+        )
+        assert _skill_pruned_marker("pdf") in out
+        assert "## Pruned Skills" in out
+
+    def test_partial_survival_reinjects_only_missing(self):
+        marker_a = _skill_pruned_marker("alpha")
+        out = _reinject_pruned_skill_markers("body\n" + marker_a, ["alpha", "beta"])
+        assert out.count(_skill_pruned_marker("alpha")) == 1
+        assert out.count(_skill_pruned_marker("beta")) == 1
+
+    def test_empty_name_list_is_a_no_op(self):
+        assert _reinject_pruned_skill_markers("body", []) == "body"
+
+    def test_marker_block_is_not_classified_as_handoff_content(self):
+        """Markers must never turn a row into summary/handoff content."""
+        marker = _skill_pruned_marker("pdf")
+        assert ContextCompressor.classify_summary_content(marker) is None
+        row = "[skill_view] name=pdf (6,000 chars) " + marker
+        assert ContextCompressor.classify_summary_content(row) is None
+        # And the strip helper leaves marker-bearing rows untouched.
+        c = ContextCompressor.__new__(ContextCompressor)
+        msg = {"role": "user", "content": row}
+        assert c._strip_context_summary_handoff_message(msg) == msg
+
+    def test_reinjected_summary_still_classifies_standalone(self):
+        body = _reinject_pruned_skill_markers("## Goal\nwork\n", ["pdf"])
+        full = SUMMARY_PREFIX + "\n\n" + body
+        assert ContextCompressor.classify_summary_content(full) == "standalone"
+
+
+class TestProtectedSkillPrune:
+    """Phase-1 prune must not demote a just-loaded skill (#32106)."""
+
+    def _filler(self, n, start=0):
+        out = []
+        for i in range(n):
+            role = "user" if (start + i) % 2 == 0 else "assistant"
+            out.append({"role": role, "content": f"filler {start + i} " + "y" * 400})
+        return out
+
+    def test_old_single_use_skill_is_pruned_with_marker(self):
+        c = _make_compressor()
+        msgs = _skill_view_pair("call_s", "old-skill") + self._filler(14)
+        result, pruned = c._prune_old_tool_results(msgs, protect_tail_count=4)
+        assert pruned >= 1
+        skill_row = result[1]
+        assert _skill_pruned_marker("old-skill") in skill_row["content"]
+
+    def test_recently_loaded_skill_survives_prune(self):
+        c = _make_compressor()
+        # skill loaded within the last 10 messages, but OUTSIDE the
+        # protected tail count — without the guard it would be demoted.
+        msgs = (
+            self._filler(10)
+            + _skill_view_pair("call_s", "fresh-skill")
+            + self._filler(6, start=10)
+        )
+        result, _ = c._prune_old_tool_results(msgs, protect_tail_count=4)
+        skill_row = result[11]
+        assert skill_row["content"].startswith("# fresh-skill instructions")
+        assert SKILL_PRUNED_MARKER_PREFIX not in skill_row["content"]
+
+    def test_skill_named_in_tail_user_message_survives_prune(self):
+        c = _make_compressor()
+        msgs = (
+            _skill_view_pair("call_s", "steered-skill")
+            + self._filler(14)
+            + [{"role": "user", "content": "keep following the steered-skill steps"}]
+        )
+        result, _ = c._prune_old_tool_results(msgs, protect_tail_count=4)
+        skill_row = result[1]
+        assert skill_row["content"].startswith("# steered-skill instructions")
+
+    def test_pressure_demotion_overrides_skill_protection(self):
+        """Pass-4 must still demote protected skill bodies (#61932 guard)."""
+        c = _make_compressor()
+        msgs = (
+            self._filler(2)
+            + _skill_view_pair("call_s", "fresh-skill", size=60000)
+            + [{"role": "user", "content": "active ask"}]
+        )
+        # Tiny token budget → protected region exceeds the soft ceiling and
+        # the pressure pass must reclaim the skill body despite protection.
+        result, pruned = c._prune_old_tool_results(
+            msgs, protect_tail_count=4, protect_tail_tokens=100
+        )
+        skill_row = result[3]
+        assert pruned >= 1
+        assert _skill_pruned_marker("fresh-skill") in skill_row["content"]
+
+
+class TestMarkerSurvivesRealCompress:
+    """P2 layer: markers survive a real compress() with a mocked aux LLM."""
+
+    def _mock_response(self, text):
+        response = MagicMock()
+        response.choices = [MagicMock()]
+        response.choices[0].message.content = text
+        return response
+
+    def _messages_with_pruned_skill_in_middle(self):
+        """Transcript whose compressed middle carries a prune marker row."""
+        pruned_row_content = (
+            "[skill_view] name=pdf (48,201 chars) " + _skill_pruned_marker("pdf")
+        )
+        msgs = [
+            {"role": "system", "content": "System prompt"},
+            {"role": "user", "content": "Build the PDF report"},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [{
+                    "id": "call_pdf",
+                    "type": "function",
+                    "function": {
+                        "name": "skill_view",
+                        "arguments": '{"name":"pdf"}',
+                    },
+                }],
+            },
+            {"role": "tool", "tool_call_id": "call_pdf", "content": pruned_row_content},
+            {"role": "assistant", "content": "Loaded the skill, working."},
+            {"role": "user", "content": "continue"},
+            {"role": "assistant", "content": "more work " + "z" * 500},
+            {"role": "user", "content": "latest ask"},
+            {"role": "assistant", "content": "ack"},
+        ]
+        return msgs
+
+    def _summary_text_of(self, result):
+        for msg in result:
+            if ContextCompressor.classify_summary_content(msg.get("content")):
+                return msg["content"]
+        raise AssertionError(f"no summary message found in {result!r}")
+
+    def test_marker_reinjected_when_summarizer_drops_it(self):
+        c = _make_compressor(protect_first_n=1, protect_last_n=2)
+        msgs = self._messages_with_pruned_skill_in_middle()
+        drop_response = self._mock_response(
+            "## Goal\nBuild the PDF report.\n\n## Completed Actions\n"
+            "1. Loaded some skills and worked on the report."
+        )
+        with (
+            patch.object(c, "_find_tail_cut_by_tokens", return_value=7),
+            patch(
+                "agent.context_compressor.call_llm", return_value=drop_response
+            ) as mock_call,
+        ):
+            result = c.compress(msgs, force=True)
+        assert mock_call.called
+        summary_text = self._summary_text_of(result)
+        assert _skill_pruned_marker("pdf") in summary_text
+        # Stored iterative-update state carries the marker too.
+        assert _skill_pruned_marker("pdf") in c._previous_summary
+
+    def test_marker_not_duplicated_when_summarizer_preserves_it(self):
+        c = _make_compressor(protect_first_n=1, protect_last_n=2)
+        msgs = self._messages_with_pruned_skill_in_middle()
+        keep_response = self._mock_response(
+            "## Goal\nBuild the PDF report.\n\n## Pruned Skills\n"
+            + _skill_pruned_marker("pdf")
+        )
+        with (
+            patch.object(c, "_find_tail_cut_by_tokens", return_value=7),
+            patch("agent.context_compressor.call_llm", return_value=keep_response),
+        ):
+            result = c.compress(msgs, force=True)
+        summary_text = self._summary_text_of(result)
+        assert summary_text.count(_skill_pruned_marker("pdf")) == 1
+
+    def test_marker_survives_static_fallback_summary(self):
+        c = _make_compressor(protect_first_n=1, protect_last_n=2)
+        msgs = self._messages_with_pruned_skill_in_middle()
+        with (
+            patch.object(c, "_find_tail_cut_by_tokens", return_value=7),
+            patch(
+                "agent.context_compressor.call_llm",
+                side_effect=RuntimeError("no provider"),
+            ),
+        ):
+            result = c.compress(msgs, force=True)
+        summary_text = self._summary_text_of(result)
+        assert _skill_pruned_marker("pdf") in summary_text
+        assert c._last_summary_fallback_used is True
+
+    def test_raw_skill_body_in_compressed_middle_gets_marker(self):
+        """A never-demoted skill_view body summarized away still ghosts.
+
+        The skill body can survive Phase-1 (protected tail of an earlier
+        prune) and then age into the compression window as RAW content.
+        The summarizer paraphrases it away — the P2 layer must emit the
+        marker for it as well, not only for already-pruned rows.
+        """
+        c = _make_compressor(protect_first_n=1, protect_last_n=2)
+        skill_body = "# pdf skill\n" + ("Detailed instructions line.\n" * 400)
+        msgs = self._messages_with_pruned_skill_in_middle()
+        msgs[3] = {"role": "tool", "tool_call_id": "call_pdf", "content": skill_body}
+        drop_response = self._mock_response(
+            "## Goal\nBuild the PDF report.\n\n## Completed Actions\n"
+            "1. Loaded some skills and worked on the report."
+        )
+        with (
+            patch.object(c, "_find_tail_cut_by_tokens", return_value=7),
+            patch("agent.context_compressor.call_llm", return_value=drop_response),
+        ):
+            result = c.compress(msgs, force=True)
+        summary_text = self._summary_text_of(result)
+        assert _skill_pruned_marker("pdf") in summary_text
+
+    def test_marker_survives_iterative_recompression(self):
+        """Markers in a rehydrated handoff summary survive iterative rewrites.
+
+        On re-compression the previous handoff (carrying the marker) is
+        rehydrated into ``_previous_summary``; even when the summarizer's
+        iterative update drops the marker, re-injection restores it.
+        """
+        c = _make_compressor(protect_first_n=1, protect_last_n=2)
+        prior_handoff = (
+            SUMMARY_PREFIX
+            + "\n\n## Goal\nOld work.\n\n## Pruned Skills\n"
+            + _skill_pruned_marker("pdf")
+        )
+        msgs = [
+            {"role": "system", "content": "System prompt"},
+            {"role": "user", "content": prior_handoff},
+        ] + [
+            {"role": "assistant" if i % 2 == 0 else "user", "content": f"turn {i} " + "q" * 300}
+            for i in range(8)
+        ]
+        drop_response = self._mock_response("## Goal\nNext task in flight.")
+        with (
+            patch.object(c, "_find_tail_cut_by_tokens", return_value=8),
+            patch("agent.context_compressor.call_llm", return_value=drop_response),
+        ):
+            result = c.compress(msgs, force=True)
+        summary_text = self._summary_text_of(result)
+        assert _skill_pruned_marker("pdf") in summary_text
+
+
+class TestReinjectionBoundsAndRedaction:
+    def test_marker_list_is_capped(self):
+        names = [f"skill-{i}" for i in range(_MAX_PRUNED_SKILL_MARKERS + 15)]
+        out = _reinject_pruned_skill_markers("body", names)
+        assert out.count(SKILL_PRUNED_MARKER_PREFIX) == len(names)
+        # The cap is applied at the collection sites in _generate_summary /
+        # _build_static_fallback_summary; the helper itself is mechanical.
+
+    def test_reinjection_block_is_redacted(self, monkeypatch):
+        import agent.redact as redact_mod
+
+        # force=True redaction must win even when redaction is disabled.
+        monkeypatch.setattr(redact_mod, "_REDACT_ENABLED", False, raising=False)
+        secret = "ghp_" + "a1B2" * 6
+        out = _reinject_pruned_skill_markers("body", [f"x {secret}"])
+        assert secret not in out
+
+
+class TestSkillsGuidanceSafetyRule:
+    def test_safety_rule_present_with_real_newlines(self):
+        from agent.prompt_builder import SKILLS_GUIDANCE
+
+        assert "## Skill Safety Rule" in SKILLS_GUIDANCE
+        assert "[SKILL_PRUNED]" in SKILLS_GUIDANCE
+        assert "skill_view(name='...')" in SKILLS_GUIDANCE
+        # The rule list must use REAL newlines — the original PR hunk risked
+        # literal backslash-n escape text rendering into the system prompt.
+        assert "\\n" not in SKILLS_GUIDANCE
+        assert SKILLS_GUIDANCE.count("\n") >= 6
+        for rule in ("UNAVAILABLE", "RELOAD", "WAIT", "DEDUP"):
+            assert rule in SKILLS_GUIDANCE
diff --git a/tests/agent/test_memory_provider.py b/tests/agent/test_memory_provider.py
index 01e68b279dd..a3cf671ab66 100644
--- a/tests/agent/test_memory_provider.py
+++ b/tests/agent/test_memory_provider.py
@@ -1379,17 +1379,19 @@ class TestMemoryToolToolsetGate:
     These tests exercise the shared gate used by agent init and ACP refreshes.
     The gate condition is:
 
+        disabled_toolsets includes memory → skip injection
         enabled_toolsets is None        → no filter, inject (backward compat)
         selected toolsets include memory → user opted in, inject
         otherwise (incl. [])            → skip injection
     """
 
     @staticmethod
-    def _run_memory_injection(enabled_toolsets, memory_manager):
+    def _run_memory_injection(enabled_toolsets, memory_manager, disabled_toolsets=None):
         """Run the shared memory-tool injection helper against a fake agent."""
         fake_agent = SimpleNamespace(
             _memory_manager=memory_manager,
             enabled_toolsets=enabled_toolsets,
+            disabled_toolsets=disabled_toolsets,
             tools=[],
             valid_tool_names=set(),
         )
@@ -1426,6 +1428,18 @@ class TestMemoryToolToolsetGate:
         assert "hindsight_recall" in names
         assert any(t["function"]["name"] == "hindsight_recall" for t in tools)
 
+    @pytest.mark.parametrize("enabled_toolsets", [None, ["memory"], ["all"], ["hermes-acp"]])
+    def test_disabled_memory_toolset_blocks_injection(self, enabled_toolsets):
+        """An explicit memory disable wins over default or composite enablement."""
+        mgr = self._mgr_with_tools("hindsight_recall")
+        tools, names = self._run_memory_injection(
+            enabled_toolsets,
+            mgr,
+            disabled_toolsets=["memory"],
+        )
+        assert tools == []
+        assert names == set()
+
     def test_empty_toolsets_blocks_injection(self):
         """`platform_toolsets: telegram: []` must suppress memory tools. (#5544)"""
         mgr = self._mgr_with_tools("fact_store")
diff --git a/tests/agent/test_moa_context_max_tokens.py b/tests/agent/test_moa_context_max_tokens.py
new file mode 100644
index 00000000000..5800b2a7764
--- /dev/null
+++ b/tests/agent/test_moa_context_max_tokens.py
@@ -0,0 +1,99 @@
+"""Regression test for aggregate_moa_context's reference/aggregator max_tokens split.
+
+PR #53580 removed a hardcoded ``max_tokens`` cap from the aggregator's
+synthesis call because it truncated long aggregator syntheses. PR #56756
+(feat(moa): add reference_max_tokens to cap advisor output and cut turn
+latency) later reintroduced a single ``max_tokens`` parameter shared by BOTH
+the reference fan-out and the aggregator call in ``aggregate_moa_context`` —
+silently regressing the exact bug #53580 fixed: setting
+``reference_max_tokens`` to speed up the advisors also truncates the
+aggregator's own synthesis, which is the context the main agent actually
+uses.
+
+``aggregate_moa_context`` and its reference/aggregator calls both go through
+``call_llm`` (task="moa_reference" vs task="moa_aggregator"), so mocking
+just that one function exercises the real fan-out/aggregation code path.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+
+def _response(content: str = "ok"):
+    message = SimpleNamespace(content=content, tool_calls=[])
+    choice = SimpleNamespace(message=message, finish_reason="stop")
+    return SimpleNamespace(choices=[choice], usage=None, model="fake")
+
+
+@pytest.fixture
+def hermes_home(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    return home
+
+
+def test_aggregator_call_never_receives_reference_max_tokens(hermes_home, monkeypatch):
+    """reference_max_tokens must cap only the reference fan-out — the
+    aggregator's own call_llm invocation must not receive max_tokens at all
+    (call_llm omits it entirely when None; see its own docstring)."""
+    from agent.moa_loop import aggregate_moa_context
+
+    calls: list[dict] = []
+
+    def fake_call_llm(**kwargs):
+        calls.append(kwargs)
+        return _response("advice" if kwargs.get("task") == "moa_reference" else "synthesis")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    aggregate_moa_context(
+        user_prompt="clean the db",
+        api_messages=[{"role": "user", "content": "clean the db"}],
+        reference_models=[{"provider": "openrouter", "model": "openai/gpt-5.5"}],
+        aggregator={"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+        reference_max_tokens=600,
+    )
+
+    reference_calls = [c for c in calls if c.get("task") == "moa_reference"]
+    aggregator_calls = [c for c in calls if c.get("task") == "moa_aggregator"]
+    assert len(reference_calls) == 1
+    assert len(aggregator_calls) == 1
+
+    # The reference fan-out is capped as configured.
+    assert reference_calls[0]["max_tokens"] == 600
+    # The aggregator's synthesis call must be uncapped — not even max_tokens=None,
+    # the kwarg must be absent entirely (matches call_llm's omit-when-None contract).
+    assert "max_tokens" not in aggregator_calls[0]
+
+
+def test_aggregator_call_uncapped_when_reference_max_tokens_unset(hermes_home, monkeypatch):
+    """Sanity check: with no reference_max_tokens configured, the reference
+    call still explicitly passes max_tokens=None (call_llm itself decides
+    whether to omit it on the wire), while the aggregator call structurally
+    never carries a max_tokens kwarg at all — the pre-#56756 default MoA
+    behavior for the aggregator, preserved regardless of the reference cap."""
+    from agent.moa_loop import aggregate_moa_context
+
+    calls: list[dict] = []
+
+    def fake_call_llm(**kwargs):
+        calls.append(kwargs)
+        return _response("advice" if kwargs.get("task") == "moa_reference" else "synthesis")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    aggregate_moa_context(
+        user_prompt="clean the db",
+        api_messages=[{"role": "user", "content": "clean the db"}],
+        reference_models=[{"provider": "openrouter", "model": "openai/gpt-5.5"}],
+        aggregator={"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+    )
+
+    reference_calls = [c for c in calls if c.get("task") == "moa_reference"]
+    aggregator_calls = [c for c in calls if c.get("task") == "moa_aggregator"]
+    assert reference_calls[0]["max_tokens"] is None
+    assert "max_tokens" not in aggregator_calls[0]
diff --git a/tests/agent/test_moa_progress.py b/tests/agent/test_moa_progress.py
new file mode 100644
index 00000000000..75d61829ffe
--- /dev/null
+++ b/tests/agent/test_moa_progress.py
@@ -0,0 +1,234 @@
+"""Tests for the MOA progress indicator added in issue #59546.
+
+The MoA facade (``MoAChatCompletions.create``) emits a sequence of display
+events so a TUI / CLI / desktop surface can render progress as references
+complete and the phase transitions from ``reference`` to ``aggregator``:
+
+  - ``moa.progress`` — fired once per reference completion with
+                       ``refs_done`` and ``refs_total`` (e.g. drives a
+                       status-bar ``MOA: 2/3 refs done`` indicator)
+  - ``moa.phase``    — fired once per phase transition (currently only the
+                       ``phase="aggregator"`` transition right before the
+                       aggregator acts)
+
+These tests exercise the real callback surface end-to-end through the
+display hook (``reference_callback``) — no mocks on the dispatch path.
+The LLM is stubbed via ``call_llm`` so the test does not depend on any
+real provider.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+
+def _response(content="ok"):
+    message = SimpleNamespace(content=content, tool_calls=[])
+    choice = SimpleNamespace(message=message, finish_reason="stop")
+    return SimpleNamespace(choices=[choice], usage=None, model="fake")
+
+
+@pytest.fixture
+def moa_config(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        """
+moa:
+  default_preset: closed
+  presets:
+    closed:
+      enabled: true
+      reference_models:
+        - provider: openrouter
+          model: anthropic/claude-opus-4.8
+        - provider: openrouter
+          model: openai/gpt-5.5
+        - provider: openrouter
+          model: google/gemini-3-pro
+      aggregator:
+        provider: openrouter
+        model: anthropic/claude-opus-4.8
+""".strip(),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    return home
+
+
+def _collect_emits(facade):
+    """Pull every event the facade dispatches into a flat list of (event, kwargs)."""
+    captured: list[tuple[str, dict]] = []
+
+    def _capture(event: str, **kwargs):
+        captured.append((event, kwargs))
+
+    facade.reference_callback = _capture
+    return captured
+
+
+def test_moa_progress_fires_for_each_reference(moa_config, monkeypatch):
+    """One ``moa.progress`` event per reference completion with monotonic counts."""
+    from agent.moa_loop import MoAChatCompletions
+
+    def fake_call_llm(**kwargs):
+        # Per-model stub: each reference returns a stable string so we can
+        # assert labels flow through; the aggregator returns the acting text.
+        if kwargs.get("task") == "moa_reference":
+            return _response(f"advice from {kwargs.get('model', '?')}")
+        return _response("acted")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    facade = MoAChatCompletions("closed")
+    captured = _collect_emits(facade)
+
+    facade.create(
+        model="closed",
+        messages=[{"role": "user", "content": "clean the db"}],
+    )
+
+    progress_events = [(e, k) for (e, k) in captured if e == "moa.progress"]
+    # 3 references configured in moa_config => 3 progress events.
+    assert len(progress_events) == 3
+
+    # Monotonic 1/3, 2/3, 3/3 — each event carries the current count and total.
+    expected_counts = [(1, 3), (2, 3), (3, 3)]
+    actual_counts = [
+        (k["refs_done"], k["refs_total"]) for (_, k) in progress_events
+    ]
+    assert actual_counts == expected_counts
+
+    # Every progress event names the source model slot (or close to it) so a
+    # status bar can render ``MOA: 2/3 refs done — openai/gpt-5.5``.
+    for _, kwargs in progress_events:
+        assert "label" in kwargs
+        assert kwargs["label"]
+
+
+def test_moa_phase_transitions_to_aggregator(moa_config, monkeypatch):
+    """A single ``moa.phase`` event with ``phase="aggregator"`` fires after the fan-out."""
+    from agent.moa_loop import MoAChatCompletions
+
+    def fake_call_llm(**kwargs):
+        if kwargs.get("task") == "moa_reference":
+            return _response("advice")
+        return _response("acted")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    facade = MoAChatCompletions("closed")
+    captured = _collect_emits(facade)
+
+    facade.create(
+        model="closed",
+        messages=[{"role": "user", "content": "plan the migration"}],
+    )
+
+    phase_events = [(e, k) for (e, k) in captured if e == "moa.phase"]
+    # Exactly one phase event per turn, identifying the aggregator.
+    assert len(phase_events) == 1
+    _event, kwargs = phase_events[0]
+    assert kwargs["phase"] == "aggregator"
+    assert kwargs["aggregator"] == "openrouter:anthropic/claude-opus-4.8"
+    # counts match the configured reference count
+    assert kwargs["refs_done"] == 3
+    assert kwargs["refs_total"] == 3
+
+
+def test_moa_progress_counts_match_n_references(moa_config, monkeypatch):
+    """Progress counters equal ``len(reference_models)`` regardless of size."""
+    from agent.moa_loop import MoAChatCompletions
+
+    def fake_call_llm(**kwargs):
+        if kwargs.get("task") == "moa_reference":
+            return _response("advice")
+        return _response("acted")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    facade = MoAChatCompletions("closed")
+    captured = _collect_emits(facade)
+
+    facade.create(
+        model="closed",
+        messages=[{"role": "user", "content": "summarize"}],
+    )
+
+    progress_events = [(e, k) for (e, k) in captured if e == "moa.progress"]
+    totals = [k["refs_total"] for _, k in progress_events]
+    # Every event reports the same total — the preset's reference-model count.
+    assert totals and all(t == 3 for t in totals)
+    # And the final done-count equals the total (fan-out finished).
+    final = progress_events[-1][1]
+    assert final["refs_done"] == final["refs_total"]
+
+
+def test_moa_progress_event_order_matches_fanout(moa_config, monkeypatch):
+    """Every progress event fires AFTER its matching moa.reference event.
+
+    Listeners that animate one block per reference (collapsible) need the
+    progress notification to land after the per-reference text so the
+    status-bar counter and the rendered block stay in lockstep.
+    """
+    from agent.moa_loop import MoAChatCompletions
+
+    def fake_call_llm(**kwargs):
+        if kwargs.get("task") == "moa_reference":
+            return _response("advice")
+        return _response("acted")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    facade = MoAChatCompletions("closed")
+    captured = _collect_emits(facade)
+
+    facade.create(
+        model="closed",
+        messages=[{"role": "user", "content": "rank the options"}],
+    )
+
+    # Walk the events; every progress event must be preceded by its reference
+    # text event (matching ``index``). The full sequence ends with the
+    # aggregator phase event.
+    seen_phase = False
+    for event, kwargs in captured:
+        if event == "moa.reference":
+            assert kwargs["index"] <= kwargs["count"]
+        elif event == "moa.progress":
+            assert kwargs["refs_done"] <= kwargs["refs_total"]
+        elif event == "moa.phase":
+            # No further reference events after the aggregator phase event.
+            assert kwargs["phase"] == "aggregator"
+            seen_phase = True
+        elif event == "moa.aggregating":
+            # Legacy marker still fires for backwards compatibility, and it
+            # always lands AFTER the phase event.
+            assert seen_phase
+    assert seen_phase, "expected at least one moa.phase event"
+
+
+def test_moa_progress_callback_none_safe(moa_config, monkeypatch):
+    """A missing ``reference_callback`` does not break the fan-out or create()."""
+    from agent.moa_loop import MoAChatCompletions
+
+    def fake_call_llm(**kwargs):
+        if kwargs.get("task") == "moa_reference":
+            return _response("advice")
+        return _response("acted")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    # No callback attached — the facade's _emit is a no-op in that case.
+    facade = MoAChatCompletions("closed")
+    assert facade.reference_callback is None
+    facade.create(
+        model="closed",
+        messages=[{"role": "user", "content": "noop"}],
+    )
+    # Turn still resolved cleanly; aggregator slot populated as usual.
+    assert facade.last_aggregator_slot is not None
+    assert facade.last_aggregator_slot["model"] == "anthropic/claude-opus-4.8"
\ No newline at end of file
diff --git a/tests/agent/test_moa_quiet_reference_output.py b/tests/agent/test_moa_quiet_reference_output.py
new file mode 100644
index 00000000000..2b6d48e95d5
--- /dev/null
+++ b/tests/agent/test_moa_quiet_reference_output.py
@@ -0,0 +1,81 @@
+"""Regression coverage for machine-readable MoA quiet output."""
+from __future__ import annotations
+
+from types import SimpleNamespace
+import unittest
+
+from agent.agent_init import _relay_moa_reference_event
+
+
+class MoAQuietReferenceOutputTests(unittest.TestCase):
+    @staticmethod
+    def _agent(*, platform: str, tool_progress_mode: str, quiet_mode: bool = True):
+        calls = []
+
+        def callback(*args, **kwargs):
+            calls.append((args, kwargs))
+
+        return SimpleNamespace(
+            platform=platform,
+            tool_progress_mode=tool_progress_mode,
+            quiet_mode=quiet_mode,
+            tool_progress_callback=callback,
+        ), calls
+
+    def test_machine_readable_cli_suppresses_reference_relay(self) -> None:
+        agent, calls = self._agent(platform="cli", tool_progress_mode="off")
+        _relay_moa_reference_event(
+            agent,
+            "moa.reference",
+            label="local:advisor",
+            text="hidden",
+            index=1,
+            count=1,
+        )
+        self.assertEqual(calls, [])
+
+    def test_interactive_cli_delivers_reference_relay(self) -> None:
+        agent, calls = self._agent(
+            platform="cli",
+            tool_progress_mode="all",
+            quiet_mode=True,
+        )
+        _relay_moa_reference_event(
+            agent,
+            "moa.reference",
+            label="local:advisor",
+            text="visible",
+            index=1,
+            count=2,
+        )
+        self.assertEqual(
+            calls,
+            [
+                (
+                    ("moa.reference", "local:advisor", "visible", None),
+                    {"moa_index": 1, "moa_count": 2},
+                )
+            ],
+        )
+
+    def test_gateway_delivers_even_when_progress_mode_is_off(self) -> None:
+        agent, calls = self._agent(platform="discord", tool_progress_mode="off")
+        _relay_moa_reference_event(
+            agent,
+            "moa.aggregating",
+            aggregator="local:aggregator",
+            ref_count=2,
+        )
+        self.assertEqual(
+            calls,
+            [
+                (
+                    ("moa.aggregating", "local:aggregator", None, None),
+                    {"moa_ref_count": 2},
+                )
+            ],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/agent/test_moa_reference_system_prompt.py b/tests/agent/test_moa_reference_system_prompt.py
new file mode 100644
index 00000000000..00bb1acfd20
--- /dev/null
+++ b/tests/agent/test_moa_reference_system_prompt.py
@@ -0,0 +1,73 @@
+"""
+Test that the MoA reference system prompt contains explicit warnings
+against claiming tool execution.
+
+Related issue: #61452
+"""
+
+from agent.moa_loop import _REFERENCE_SYSTEM_PROMPT
+
+
+def test_reference_system_prompt_prohibits_claiming_execution():
+    """
+    Verify that the reference system prompt contains explicit warnings
+    against claiming tool execution.
+
+    The prompt should:
+    1. State that reference models cannot execute anything
+    2. Warn against claiming/implying execution
+    3. Provide bad/good examples
+
+    This addresses #61452 where reference models were fabricating
+    tool execution in their text output.
+    """
+    prompt_lower = _REFERENCE_SYSTEM_PROMPT.lower()
+
+    # Critical constraints
+    assert "you cannot call tools" in prompt_lower or "you do not execute" in prompt_lower, \
+        "Prompt must explicitly state that reference models cannot execute"
+
+    assert "never claim" in prompt_lower or "never imply" in prompt_lower, \
+        "Prompt must warn against claiming/implying execution"
+
+    # Check for examples (helps models understand what NOT to do)
+    assert "bad:" in prompt_lower or "avoid:" in prompt_lower, \
+        "Prompt should provide negative examples"
+
+    # Specific action verbs that should NOT appear as claimed actions
+    # (these are common patterns of hallucinated execution)
+    forbidden_patterns = [
+        "i ran", "i executed", "i downloaded", "i accessed",
+        "i checked", "i called", "i browsed"
+    ]
+
+    # The prompt should mention these as bad examples
+    # (i.e., in the context of what to avoid, not as instruction)
+    has_any_forbidden = any(
+        f"bad: \"{pattern}" in _REFERENCE_SYSTEM_PROMPT.lower() or
+        f"avoid \"{pattern}" in _REFERENCE_SYSTEM_PROMPT.lower()
+        for pattern in forbidden_patterns
+    )
+
+    # At least one bad example pattern should exist
+    assert has_any_forbidden or "examples" in _REFERENCE_SYSTEM_PROMPT.lower(), \
+        "Prompt should contain examples of what to avoid"
+
+
+def test_reference_system_prompt_structure():
+    """
+    Verify the reference system prompt has a clear structure.
+
+    A well-structured prompt helps models follow instructions better.
+    """
+    # Prompt should not be empty
+    assert len(_REFERENCE_SYSTEM_PROMPT) > 100, \
+        "Reference system prompt should be substantive"
+
+    # Should have multiple paragraphs (structured guidance)
+    assert _REFERENCE_SYSTEM_PROMPT.count("\n\n") >= 2, \
+        "Prompt should be structured with multiple sections"
+
+    # Should contain the word "advisor" (defines role)
+    assert "advisor" in _REFERENCE_SYSTEM_PROMPT.lower(), \
+        "Prompt should clearly define the advisor role"
diff --git a/tests/agent/test_moa_slot_max_tokens.py b/tests/agent/test_moa_slot_max_tokens.py
new file mode 100644
index 00000000000..1b3a6813c30
--- /dev/null
+++ b/tests/agent/test_moa_slot_max_tokens.py
@@ -0,0 +1,82 @@
+"""Tests for per-slot max_tokens in MoA reference calls.
+
+Verifies that a ``max_tokens`` field on a reference slot dict takes
+precedence over the preset-level ``reference_max_tokens``, and that
+slot-level max_tokens=None falls back to the preset-level cap.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+class TestRunReferenceSlotMaxTokens:
+    """_run_reference should prefer slot-level max_tokens over preset-level."""
+
+    def test_slot_max_tokens_overrides_preset_level(self):
+        """When slot has max_tokens, it overrides the preset-level cap."""
+        from agent.moa_loop import _run_reference
+
+        captured_kwargs: dict = {}
+
+        def fake_call_llm(**kwargs):
+            captured_kwargs.update(kwargs)
+            mock_resp = MagicMock()
+            mock_resp.choices = [MagicMock(message=MagicMock(content="advice"))]
+            mock_resp.usage = None
+            return mock_resp
+
+        slot = {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "max_tokens": 600}
+
+        with patch("agent.moa_loop._slot_runtime", return_value={"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}), \
+             patch("agent.moa_loop.call_llm", side_effect=fake_call_llm), \
+             patch("agent.moa_loop._maybe_apply_moa_cache_control", side_effect=lambda msgs, rt: msgs):
+            _run_reference(slot, [{"role": "user", "content": "hi"}], max_tokens=2000)
+
+        assert captured_kwargs.get("max_tokens") == 600
+
+    def test_slot_max_tokens_absent_falls_back_to_preset(self):
+        """When slot has no max_tokens, the preset-level cap is used."""
+        from agent.moa_loop import _run_reference
+
+        captured_kwargs: dict = {}
+
+        def fake_call_llm(**kwargs):
+            captured_kwargs.update(kwargs)
+            mock_resp = MagicMock()
+            mock_resp.choices = [MagicMock(message=MagicMock(content="advice"))]
+            mock_resp.usage = None
+            return mock_resp
+
+        slot = {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}
+
+        with patch("agent.moa_loop._slot_runtime", return_value={"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}), \
+             patch("agent.moa_loop.call_llm", side_effect=fake_call_llm), \
+             patch("agent.moa_loop._maybe_apply_moa_cache_control", side_effect=lambda msgs, rt: msgs):
+            _run_reference(slot, [{"role": "user", "content": "hi"}], max_tokens=2000)
+
+        assert captured_kwargs.get("max_tokens") == 2000
+
+    def test_both_none_means_uncapped(self):
+        """When neither slot nor preset has max_tokens, it's None (uncapped)."""
+        from agent.moa_loop import _run_reference
+
+        captured_kwargs: dict = {}
+
+        def fake_call_llm(**kwargs):
+            captured_kwargs.update(kwargs)
+            mock_resp = MagicMock()
+            mock_resp.choices = [MagicMock(message=MagicMock(content="advice"))]
+            mock_resp.usage = None
+            return mock_resp
+
+        slot = {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}
+
+        with patch("agent.moa_loop._slot_runtime", return_value={"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}), \
+             patch("agent.moa_loop.call_llm", side_effect=fake_call_llm), \
+             patch("agent.moa_loop._maybe_apply_moa_cache_control", side_effect=lambda msgs, rt: msgs):
+            _run_reference(slot, [{"role": "user", "content": "hi"}], max_tokens=None)
+
+        assert captured_kwargs.get("max_tokens") is None
diff --git a/tests/agent/test_nous_rate_guard.py b/tests/agent/test_nous_rate_guard.py
index 4441aa6e447..18920efb947 100644
--- a/tests/agent/test_nous_rate_guard.py
+++ b/tests/agent/test_nous_rate_guard.py
@@ -389,3 +389,48 @@ class TestIsGenuineNousRateLimit:
         assert is_genuine_nous_rate_limit(
             headers=None, last_known_state=None
         ) is False
+
+
+class TestRateGuardStateEncoding:
+    """Regression for #18637: the cross-session rate-limit state file was
+    opened without ``encoding="utf-8"`` on both the atomic write (os.fdopen)
+    and the read. On Windows Chinese locales the platform default decoder
+    raises on UTF-8 bytes written by a peer process, silently losing the
+    rate-limit guard and re-enabling the retry amplification the module was
+    built to prevent.
+    """
+
+    def test_read_uses_utf8_under_non_utf8_locale(self, rate_guard_env, monkeypatch):
+        import builtins
+
+        from agent.nous_rate_guard import nous_rate_limit_remaining, _state_path
+
+        path = _state_path()
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        # State JSON written with a UTF-8 provider label. Python's json
+        # module itself escapes non-ASCII by default, but a peer writer
+        # (or human) using ensure_ascii=False produces raw UTF-8 bytes,
+        # which is what this guards against.
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(
+                '{"reset_at": %d, "provider": "中文", "recorded_at": 0}'
+                % (int(time.time()) + 3600)
+            )
+
+        real_open = builtins.open
+
+        def guarded_open(file, mode="r", *args, **kwargs):
+            try:
+                is_target = str(file) == str(path)
+            except Exception:
+                is_target = False
+            if is_target and "b" not in mode and kwargs.get("encoding") != "utf-8":
+                raise UnicodeDecodeError(
+                    "gbk", b"\x94", 0, 1, "illegal multibyte sequence"
+                )
+            return real_open(file, mode, *args, **kwargs)
+
+        monkeypatch.setattr(builtins, "open", guarded_open)
+
+        remaining = nous_rate_limit_remaining()
+        assert remaining is not None and remaining > 0
diff --git a/tests/agent/test_portal_tags.py b/tests/agent/test_portal_tags.py
index 418d3b59f14..876c5f76e24 100644
--- a/tests/agent/test_portal_tags.py
+++ b/tests/agent/test_portal_tags.py
@@ -217,3 +217,112 @@ def test_nous_provider_profile_uses_helper():
     assert profile is not None
     body = profile.build_extra_body()
     assert body["tags"] == nous_portal_tags()
+
+
+def test_nous_sticky_key_matches_conversation_tag():
+    """Sticky routing key must resolve like the ``conversation=`` tag does.
+
+    The load-bearing case is the auxiliary call sites (compression, titles,
+    vision, MoA slots): they pass no ``session_id`` at all, so before this
+    resolution they carried the conversation tag but NO Portal sticky key and
+    routed independently of their conversation.
+
+    The explicit-argument case matters for installs that opt out of the
+    default ``compression.in_place: true`` (#38763) and therefore still rotate
+    ``agent.session_id`` at compaction, and for delegate-subagent trees that
+    should tag as the parent conversation.
+    """
+    from agent.portal_tags import (
+        conversation_tag,
+        reset_conversation_context,
+        set_conversation_context,
+    )
+    from providers import get_provider_profile
+
+    profile = get_provider_profile("nous")
+    token = set_conversation_context("root-conversation")
+    try:
+        # Rotated segment id passed explicitly — root still wins, both places.
+        body = profile.build_extra_body(session_id="segment-after-compaction")
+        assert body["session_id"] == "root-conversation"
+        assert conversation_tag("root-conversation") in body["tags"]
+
+        # Auxiliary call sites pass no session_id but inherit the context.
+        aux = profile.build_extra_body()
+        assert aux["session_id"] == "root-conversation"
+    finally:
+        reset_conversation_context(token)
+
+
+def test_nous_sticky_key_falls_back_to_explicit_session_id():
+    """Outside any agent turn the explicit session_id remains the sticky key."""
+    from providers import get_provider_profile
+
+    profile = get_provider_profile("nous")
+    body = profile.build_extra_body(session_id="explicit-only")
+    assert body["session_id"] == "explicit-only"
+    assert profile.build_extra_body().get("session_id") is None
+
+
+def test_compress_context_publishes_root_when_called_out_of_turn(monkeypatch):
+    """Out-of-turn compaction must still carry the conversation tag.
+
+    ``/compact``, the gateway ``/compress`` command and its hygiene sweep call
+    ``_compress_context`` directly, outside ``run_conversation``'s ambient
+    scope. That call ships the full uncompressed history — the largest prompt
+    of the session — so losing the sticky key there reroutes it to a cold
+    endpoint.
+    """
+    import agent.conversation_compression as cc
+    from agent.portal_tags import get_conversation_context
+    from run_agent import AIAgent
+
+    seen = {}
+
+    def _fake_compress(agent, messages, system_message, **kwargs):
+        seen["conversation"] = get_conversation_context()
+        return ([], "")
+
+    monkeypatch.setattr(cc, "compress_context", _fake_compress)
+
+    class _Agent:
+        def _conversation_root_id(self):
+            return "root-abc"
+
+    AIAgent._compress_context(_Agent(), [], "sys")
+
+    assert seen["conversation"] == "root-abc"
+    # The scope is local: nothing leaks into the caller's context.
+    assert get_conversation_context() is None
+
+
+def test_compress_context_preserves_ambient_context(monkeypatch):
+    """In-turn compaction inherits the turn's root and restores it untouched."""
+    import agent.conversation_compression as cc
+    from agent.portal_tags import (
+        get_conversation_context,
+        reset_conversation_context,
+        set_conversation_context,
+    )
+    from run_agent import AIAgent
+
+    seen = {}
+
+    def _fake_compress(agent, messages, system_message, **kwargs):
+        seen["conversation"] = get_conversation_context()
+        return ([], "")
+
+    monkeypatch.setattr(cc, "compress_context", _fake_compress)
+
+    class _Agent:
+        def _conversation_root_id(self):
+            # A rotated segment id must never win over the ambient root.
+            return "segment-after-compaction"
+
+    token = set_conversation_context("outer-root")
+    try:
+        AIAgent._compress_context(_Agent(), [], "sys")
+        assert seen["conversation"] == "outer-root"
+        assert get_conversation_context() == "outer-root"
+    finally:
+        reset_conversation_context(token)
diff --git a/tests/agent/test_preflight_lock_defer.py b/tests/agent/test_preflight_lock_defer.py
new file mode 100644
index 00000000000..8560bd2ec45
--- /dev/null
+++ b/tests/agent/test_preflight_lock_defer.py
@@ -0,0 +1,121 @@
+"""Preflight lock-defer must not arm the insufficient-progress blocker.
+
+Companion to ``tests/run_agent/test_compression_lock_defer.py`` — pins the
+``build_turn_context`` preflight loop's handling of a lock-contended
+compression no-op (#69870 lock-skip signal, consumer salvaged from #49874):
+
+* the pass stops the preflight loop (the lock winner is already shrinking
+  the session) WITHOUT setting ``preflight_compression_blocked``, so the
+  loop's provider-proven error handlers keep their full retry budget;
+* a genuine no-progress no-op (flag unset) still arms the blocker exactly
+  as before;
+* a MagicMock-style truthy junk flag value does NOT take the defer branch
+  (type-pin rule).
+"""
+
+from __future__ import annotations
+
+import types
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from tests.agent.test_turn_context import _FakeAgent, _build
+
+
+@pytest.fixture(autouse=True)
+def _stub_runtime_main():
+    with patch("agent.auxiliary_client.set_runtime_main", lambda *a, **k: None):
+        yield
+
+
+def _pressured_compressor():
+    """Over-threshold compressor stub that opens the preflight threshold path."""
+    return types.SimpleNamespace(
+        protect_first_n=0,
+        protect_last_n=0,
+        threshold_tokens=1,
+        context_length=100_000,
+        last_prompt_tokens=0,
+        should_compress=lambda _tokens=None: True,
+        should_compress_info=lambda _tokens=None: (True, None),
+        should_defer_preflight_to_real_usage=lambda _t: False,
+        get_active_compression_failure_cooldown=lambda: None,
+    )
+
+
+def _make_agent():
+    agent = _FakeAgent()
+    agent.compression_enabled = True
+    agent.context_compressor = _pressured_compressor()
+    agent._emit_status = MagicMock()
+    return agent
+
+
+_HISTORY = [{"role": "user", "content": "old"}, {"role": "assistant", "content": "older"}]
+
+
+def test_preflight_lock_skip_does_not_set_blocked_flag():
+    agent = _make_agent()
+    calls = []
+
+    def _lock_skip_compress(messages, _system_message, **_kwargs):
+        calls.append(1)
+        agent._compression_skipped_due_to_lock = "pid=1:tid=2:agent=aa:nonce=bb"
+        return messages, "SYSTEM"
+
+    agent._compress_context = _lock_skip_compress
+
+    ctx = _build(agent, conversation_history=list(_HISTORY))
+
+    # Exactly one pass: the defer stops the loop without arming the blocker.
+    assert calls == [1]
+    assert ctx.preflight_compression_blocked is False
+
+
+def test_preflight_lock_skip_true_unconfirmed_holder_also_defers():
+    agent = _make_agent()
+    calls = []
+
+    def _lock_skip_compress(messages, _system_message, **_kwargs):
+        calls.append(1)
+        agent._compression_skipped_due_to_lock = True
+        return messages, "SYSTEM"
+
+    agent._compress_context = _lock_skip_compress
+
+    ctx = _build(agent, conversation_history=list(_HISTORY))
+
+    assert calls == [1]
+    assert ctx.preflight_compression_blocked is False
+
+
+def test_preflight_plain_noop_still_arms_blocker():
+    """Control: flag unset → unchanged pre-fix behavior (blocker armed)."""
+    agent = _make_agent()
+
+    def _noop_compress(messages, _system_message, **_kwargs):
+        agent._compression_skipped_due_to_lock = None
+        return messages, "SYSTEM"
+
+    agent._compress_context = _noop_compress
+
+    ctx = _build(agent, conversation_history=list(_HISTORY))
+
+    assert ctx.preflight_compression_blocked is True
+
+
+def test_preflight_magicmock_flag_value_is_not_a_defer():
+    """Type-pin: truthy junk (MagicMock auto-attribute shape) must not be
+    treated as lock contention — the blocker arms as for a plain no-op."""
+    agent = _make_agent()
+
+    def _junk_flag_compress(messages, _system_message, **_kwargs):
+        agent._compression_skipped_due_to_lock = MagicMock()
+        return messages, "SYSTEM"
+
+    agent._compress_context = _junk_flag_compress
+
+    ctx = _build(agent, conversation_history=list(_HISTORY))
+
+    assert ctx.preflight_compression_blocked is True
diff --git a/tests/agent/test_proactive_prune_config.py b/tests/agent/test_proactive_prune_config.py
new file mode 100644
index 00000000000..104dfb020c2
--- /dev/null
+++ b/tests/agent/test_proactive_prune_config.py
@@ -0,0 +1,111 @@
+"""compression.proactive_prune_* — config parse seam for the proactive prune.
+
+Mirrors ``test_compression_max_attempts_config.py``: the three knobs are
+parsed in ``agent_init`` with the same hardened semantics (booleans rejected,
+fractional floats rejected — not truncated, integral floats and numeric
+strings accepted) and attached to the built-in compressor.  Default is
+0 / 8000 / 4096, i.e. the feature is OFF and behavior-neutral unless
+``proactive_prune_tokens`` is set above 0.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+from pathlib import Path
+
+from hermes_state import SessionDB
+from run_agent import AIAgent
+
+
+def _config(**prune_keys) -> dict:
+    compression = {
+        "enabled": True,
+        "threshold": 0.50,
+        "target_ratio": 0.20,
+        "protect_first_n": 3,
+        "protect_last_n": 20,
+    }
+    compression.update(prune_keys)
+    return {
+        "compression": compression,
+        "prompt_caching": {"cache_ttl": "5m"},
+        "sessions": {},
+        "bedrock": {},
+    }
+
+
+def _make_agent(monkeypatch, tmp_path: Path, **prune_keys):
+    from hermes_cli import config as config_mod
+
+    monkeypatch.setattr(config_mod, "load_config", lambda: _config(**prune_keys))
+    db = SessionDB(db_path=tmp_path / "state.db")
+    with contextlib.redirect_stdout(io.StringIO()):
+        agent = AIAgent(
+            base_url="https://chatgpt.com/backend-api/codex",
+            api_key="test-key",
+            provider="openai-codex",
+            model="gpt-5.5",
+            enabled_toolsets=[],
+            disabled_toolsets=[],
+            quiet_mode=True,
+            skip_memory=True,
+            session_db=db,
+            session_id="proactive-prune-config-test",
+        )
+    return agent
+
+
+class TestProactivePruneConfig:
+    def test_default_is_disabled_when_unset(self, monkeypatch, tmp_path):
+        agent = _make_agent(monkeypatch, tmp_path)
+        cc = agent.context_compressor
+        assert cc.proactive_prune_tokens == 0
+        assert cc.proactive_prune_min_result_chars == 8000
+        assert cc.proactive_prune_min_reclaim_tokens == 4096
+
+    def test_custom_values_are_honored(self, monkeypatch, tmp_path):
+        agent = _make_agent(
+            monkeypatch,
+            tmp_path,
+            proactive_prune_tokens=48_000,
+            proactive_prune_min_result_chars=12_000,
+            proactive_prune_min_reclaim_tokens=8_192,
+        )
+        cc = agent.context_compressor
+        assert cc.proactive_prune_tokens == 48_000
+        assert cc.proactive_prune_min_result_chars == 12_000
+        assert cc.proactive_prune_min_reclaim_tokens == 8_192
+
+    def test_boolean_is_rejected_not_coerced(self, monkeypatch, tmp_path):
+        # bool subclasses int: YAML `proactive_prune_tokens: true` must fall
+        # back to disabled, never coerce to 1 token.
+        agent = _make_agent(monkeypatch, tmp_path, proactive_prune_tokens=True)
+        assert agent.context_compressor.proactive_prune_tokens == 0
+
+    def test_fractional_float_is_rejected_not_truncated(self, monkeypatch, tmp_path):
+        agent = _make_agent(monkeypatch, tmp_path, proactive_prune_tokens=48_000.7)
+        assert agent.context_compressor.proactive_prune_tokens == 0
+
+    def test_integral_float_and_numeric_string_accepted(self, monkeypatch, tmp_path):
+        agent = _make_agent(monkeypatch, tmp_path, proactive_prune_tokens=48_000.0)
+        assert agent.context_compressor.proactive_prune_tokens == 48_000
+        agent = _make_agent(monkeypatch, tmp_path, proactive_prune_tokens="32000")
+        assert agent.context_compressor.proactive_prune_tokens == 32_000
+
+    def test_negative_trigger_treated_as_disabled(self, monkeypatch, tmp_path):
+        agent = _make_agent(monkeypatch, tmp_path, proactive_prune_tokens=-100)
+        assert agent.context_compressor.proactive_prune_tokens == 0
+
+    def test_garbage_falls_back_to_defaults(self, monkeypatch, tmp_path):
+        agent = _make_agent(
+            monkeypatch,
+            tmp_path,
+            proactive_prune_tokens="lots",
+            proactive_prune_min_result_chars=None,
+            proactive_prune_min_reclaim_tokens="???",
+        )
+        cc = agent.context_compressor
+        assert cc.proactive_prune_tokens == 0
+        assert cc.proactive_prune_min_result_chars == 8000
+        assert cc.proactive_prune_min_reclaim_tokens == 4096
diff --git a/tests/agent/test_proactive_tool_result_pruning.py b/tests/agent/test_proactive_tool_result_pruning.py
new file mode 100644
index 00000000000..f56caf5af31
--- /dev/null
+++ b/tests/agent/test_proactive_tool_result_pruning.py
@@ -0,0 +1,277 @@
+"""Tests for proactive tool-result pruning.
+
+``ContextCompressor.prune_tool_results_only`` runs the cheap, deterministic
+Phase-1 prune (summarize old tool outputs, dedup repeats) on a cost-oriented
+trigger that is INDEPENDENT of the full-compression threshold. On large-window
+models ``should_compress()`` (~50% of the window) rarely fires, so without this
+the old tool outputs ride in history and are re-sent verbatim every turn.
+
+Mirrors the construction/patching conventions in test_context_compressor.py.
+"""
+
+from unittest.mock import patch
+
+from agent.context_compressor import ContextCompressor, _PRUNED_TOOL_PLACEHOLDER
+
+LARGE_WINDOW = 1_000_000
+
+
+def _compressor(**kw):
+    defaults = dict(
+        model="test",
+        quiet_mode=True,
+        threshold_percent=0.50,
+        protect_first_n=2,
+        protect_last_n=4,
+    )
+    defaults.update(kw)
+    with patch(
+        "agent.context_compressor.get_model_context_length",
+        return_value=LARGE_WINDOW,
+    ):
+        return ContextCompressor(**defaults)
+
+
+def _assistant_call(cid, name="terminal", args='{"cmd":"ls"}'):
+    return {
+        "role": "assistant",
+        "content": "",
+        "tool_calls": [
+            {"id": cid, "type": "function",
+             "function": {"name": name, "arguments": args}}
+        ],
+    }
+
+
+def _tool_msg(cid, content):
+    return {"role": "tool", "tool_call_id": cid, "content": content}
+
+
+def _build(n_pairs, big_indices, big_chars=9000, small="ok"):
+    """system + n_pairs of (assistant tool_call, tool result).
+
+    Tool results whose pair index is in ``big_indices`` get a distinct payload
+    of ``big_chars`` characters; the rest get a tiny payload.
+    """
+    msgs = [{"role": "system", "content": "sys"}]
+    for i in range(n_pairs):
+        cid = f"call_{i}"
+        msgs.append(_assistant_call(cid))
+        if i in big_indices:
+            msgs.append(_tool_msg(cid, chr(65 + (i % 26)) * big_chars))
+        else:
+            msgs.append(_tool_msg(cid, small))
+    return msgs
+
+
+def _tool_by_id(msgs, cid):
+    return [m for m in msgs if m.get("role") == "tool" and m.get("tool_call_id") == cid][0]
+
+
+def test_prunes_below_compression_threshold():
+    """The whole point: prune fires at 120k tokens, far below the ~500k
+    (50% of 1M) full-compression trigger that would otherwise never run."""
+    c = _compressor(proactive_prune_tokens=48_000, proactive_prune_min_result_chars=8_000)
+    assert c.should_compress(prompt_tokens=120_000) is False  # compression would NOT run
+    msgs = _build(8, big_indices={0, 1, 2})
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=120_000)
+    assert pruned >= 3
+    assert len(result) == len(msgs)
+    for cid in ("call_0", "call_1", "call_2"):
+        m = _tool_by_id(result, cid)
+        assert len(m["content"]) < 9000                       # summarized
+        assert m["content"] != _PRUNED_TOOL_PLACEHOLDER       # informative, not a blank placeholder
+
+
+def test_disabled_by_default_is_noop():
+    c = _compressor()  # proactive_prune_tokens defaults to 0
+    assert c.proactive_prune_tokens == 0
+    msgs = _build(8, big_indices={0, 1, 2})
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=500_000)
+    assert pruned == 0
+    assert [m.get("content") for m in result] == [m.get("content") for m in msgs]
+
+
+def test_below_trigger_is_noop():
+    c = _compressor(proactive_prune_tokens=48_000)
+    msgs = _build(8, big_indices={0, 1, 2})
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=10_000)
+    assert pruned == 0
+
+
+def test_recent_tail_is_protected():
+    c = _compressor(
+        proactive_prune_tokens=48_000,
+        proactive_prune_min_result_chars=8_000,
+        proactive_prune_min_reclaim_tokens=0,  # gate off: this test pins tail semantics
+    )
+    # pair 0 tool is old (index 2); pair 7 tool is in the last-4 protected tail (index 16)
+    msgs = _build(8, big_indices={0, 7})
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=120_000)
+    assert len(_tool_by_id(result, "call_7")["content"]) == 9000   # protected, untouched
+    assert len(_tool_by_id(result, "call_0")["content"]) < 9000    # old, summarized
+
+
+def test_size_floor_spares_small_results():
+    c = _compressor(
+        proactive_prune_tokens=48_000,
+        proactive_prune_min_result_chars=8_000,
+        proactive_prune_min_reclaim_tokens=0,  # gate off: this test pins the size floor
+    )
+    msgs = _build(8, big_indices={1}, big_chars=9000)
+    for m in msgs:                      # make pair 0's tool 5000 chars (< 8000 floor), still old
+        if m.get("tool_call_id") == "call_0":
+            m["content"] = "Z" * 5000
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=120_000)
+    assert len(_tool_by_id(result, "call_0")["content"]) == 5000   # under floor -> untouched
+    assert len(_tool_by_id(result, "call_1")["content"]) < 9000    # over floor -> summarized
+
+
+def test_structure_preserved():
+    c = _compressor(proactive_prune_tokens=48_000, proactive_prune_min_result_chars=8_000)
+    msgs = _build(8, big_indices={0, 1, 2})
+    roles_before = [m["role"] for m in msgs]
+    ids_before = [m.get("tool_call_id") for m in msgs]
+    result, _ = c.prune_tool_results_only(msgs, current_tokens=120_000)
+    assert len(result) == len(msgs)
+    assert [m["role"] for m in result] == roles_before
+    assert [m.get("tool_call_id") for m in result] == ids_before
+
+
+def test_idempotent():
+    c = _compressor(proactive_prune_tokens=48_000, proactive_prune_min_result_chars=8_000)
+    msgs = _build(8, big_indices={0, 1, 2})
+    first, n1 = c.prune_tool_results_only(msgs, current_tokens=120_000)
+    assert n1 >= 3
+    second, n2 = c.prune_tool_results_only(first, current_tokens=120_000)
+    assert n2 == 0
+    assert [m.get("content") for m in second] == [m.get("content") for m in first]
+
+
+def test_prune_old_tool_results_default_floor_unchanged():
+    """Backward-compat: without min_prune_chars, _prune_old_tool_results still
+    prunes >200-char results (the compression Phase-1 caller's behavior)."""
+    c = _compressor()
+    msgs = _build(8, big_indices=set())
+    for m in msgs:                      # a 300-char old tool result
+        if m.get("tool_call_id") == "call_0":
+            m["content"] = "Q" * 300
+    result, pruned = c._prune_old_tool_results(msgs, protect_tail_count=4)
+    assert len(_tool_by_id(result, "call_0")["content"]) < 300
+    assert pruned >= 1
+
+
+def test_min_result_chars_floor_is_clamped():
+    """Config-robustness: a floor below 200 (or negative) is clamped up to 200,
+    while a configured 0 falls back to the 8000 default via ``or``. Without the
+    clamp, a tiny floor lets Pass 2 re-summarize its own (short) summary every
+    turn, and a negative floor strips every non-tail tool result."""
+    assert _compressor(proactive_prune_min_result_chars=0).proactive_prune_min_result_chars == 8000
+    assert _compressor(proactive_prune_min_result_chars=50).proactive_prune_min_result_chars == 200
+    assert _compressor(proactive_prune_min_result_chars=-1).proactive_prune_min_result_chars == 200
+    assert _compressor(proactive_prune_min_result_chars=8000).proactive_prune_min_result_chars == 8000
+
+
+# ---------------------------------------------------------------------------
+# Salvage follow-ups: no-op caller contract, prompt-cache hysteresis gate,
+# no-orphan pairing invariant, and the default-off behavior pin.
+# ---------------------------------------------------------------------------
+
+
+def test_noop_paths_return_input_object():
+    """Standard caller contract: every no-op path hands back the INPUT list
+    object so callers can gate bookkeeping on ``result is not input``."""
+    msgs = _build(8, big_indices={0, 1, 2})
+    # Disabled (default)
+    c = _compressor()
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=500_000)
+    assert pruned == 0 and result is msgs
+    # Below trigger
+    c = _compressor(proactive_prune_tokens=48_000)
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=10_000)
+    assert pruned == 0 and result is msgs
+    # Above trigger but nothing prunable (all results tiny)
+    c = _compressor(proactive_prune_tokens=48_000)
+    tiny = _build(8, big_indices=set())
+    result, pruned = c.prune_tool_results_only(tiny, current_tokens=120_000)
+    assert pruned == 0 and result is tiny
+
+
+def test_min_reclaim_gate_blocks_small_prunes():
+    """Prompt-cache hysteresis: a prune that would reclaim less than
+    ``proactive_prune_min_reclaim_tokens`` must NOT commit (returns the input
+    object) — rewriting already-sent history for a trivial saving would break
+    the provider's cached prefix every tool iteration."""
+    c = _compressor(
+        proactive_prune_tokens=48_000,
+        proactive_prune_min_result_chars=8_000,
+        proactive_prune_min_reclaim_tokens=1_000_000,  # unreachably high
+    )
+    msgs = _build(8, big_indices={0, 1, 2})
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=120_000)
+    assert pruned == 0
+    assert result is msgs  # input object — caller commits nothing
+
+
+def test_min_reclaim_gate_allows_large_prunes():
+    """A prune reclaiming more than the gate commits normally."""
+    c = _compressor(
+        proactive_prune_tokens=48_000,
+        proactive_prune_min_result_chars=8_000,
+        proactive_prune_min_reclaim_tokens=1_000,  # 3×9000 chars ≈ 6.7K tokens reclaimed
+    )
+    msgs = _build(8, big_indices={0, 1, 2})
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=120_000)
+    assert pruned >= 3
+    assert result is not msgs
+
+
+def test_min_reclaim_gate_default_and_clamp():
+    """Default 4096; negative/None coerce to disabled (0)."""
+    assert _compressor().proactive_prune_min_reclaim_tokens == 4096
+    assert _compressor(proactive_prune_min_reclaim_tokens=0).proactive_prune_min_reclaim_tokens == 0
+    assert _compressor(proactive_prune_min_reclaim_tokens=-5).proactive_prune_min_reclaim_tokens == 0
+    assert _compressor(proactive_prune_min_reclaim_tokens=None).proactive_prune_min_reclaim_tokens == 0
+
+
+def test_no_orphans_both_directions():
+    """tool_call_id pairing survives the prune in BOTH directions: every
+    surviving tool result has its assistant call, and every assistant tool_call
+    has its result row (the #69830 test-pin rule — never assert exact surviving
+    pair counts, only the pairing invariant)."""
+    c = _compressor(
+        proactive_prune_tokens=48_000,
+        proactive_prune_min_result_chars=8_000,
+        proactive_prune_min_reclaim_tokens=0,
+    )
+    msgs = _build(10, big_indices={0, 1, 2, 3, 4})
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=120_000)
+    assert pruned >= 1
+    call_ids = set()
+    for m in result:
+        if m.get("role") == "assistant":
+            for tc in m.get("tool_calls") or []:
+                call_ids.add(tc["id"] if isinstance(tc, dict) else tc.id)
+    result_ids = {m["tool_call_id"] for m in result if m.get("role") == "tool"}
+    assert result_ids <= call_ids, "orphan tool results without a matching call"
+    assert call_ids <= result_ids, "orphan tool calls without a matching result"
+
+
+def test_unset_config_zero_behavior_change():
+    """Pin: with the config knobs unset, the compressor behaves byte-identically
+    to pre-feature main — the prune path is dead code and the full-compression
+    Phase-1 caller keeps its 200-char floor."""
+    c = _compressor()  # nothing configured
+    assert c.proactive_prune_tokens == 0
+    msgs = _build(8, big_indices={0, 1, 2})
+    import copy
+    snapshot = copy.deepcopy(msgs)
+    result, pruned = c.prune_tool_results_only(msgs, current_tokens=10_000_000)
+    assert pruned == 0
+    assert result is msgs
+    assert msgs == snapshot  # input never mutated
+    # And the compression-path caller still prunes at the 200-char default floor
+    # (min_prune_chars default unchanged).
+    import inspect
+    sig = inspect.signature(c._prune_old_tool_results)
+    assert sig.parameters["min_prune_chars"].default == 200
diff --git a/tests/agent/test_prompt_caching.py b/tests/agent/test_prompt_caching.py
index 7a1c0495e1b..ba21e4c9195 100644
--- a/tests/agent/test_prompt_caching.py
+++ b/tests/agent/test_prompt_caching.py
@@ -142,6 +142,54 @@ class TestApplyAnthropicCacheControl:
         assert isinstance(sys_content, list)
         assert sys_content[0]["cache_control"]["type"] == "ephemeral"
 
+    def test_static_system_prefix_gets_its_own_marker(self):
+        messages = [
+            {"role": "system", "content": "stable prefix\n\nper-session context"},
+            {"role": "user", "content": "old request"},
+            {"role": "assistant", "content": "old response"},
+            {"role": "user", "content": "new request"},
+        ]
+
+        result = apply_anthropic_cache_control(
+            messages,
+            static_system_prefix="stable prefix",
+        )
+
+        system_blocks = result[0]["content"]
+        assert system_blocks == [
+            {
+                "type": "text",
+                "text": "stable prefix",
+                "cache_control": {"type": "ephemeral"},
+            },
+            {
+                "type": "text",
+                "text": "\n\nper-session context",
+                "cache_control": {"type": "ephemeral"},
+            },
+        ]
+        assert result[1]["content"] == "old request"
+        assert result[2]["content"][0]["cache_control"] == {"type": "ephemeral"}
+        assert result[3]["content"][0]["cache_control"] == {"type": "ephemeral"}
+
+    def test_mismatched_static_prefix_uses_legacy_system_breakpoint(self):
+        messages = [
+            {"role": "system", "content": "current system prompt"},
+            {"role": "user", "content": "old request"},
+            {"role": "assistant", "content": "old response"},
+            {"role": "user", "content": "new request"},
+        ]
+
+        result = apply_anthropic_cache_control(
+            messages,
+            static_system_prefix="stale system prompt",
+        )
+
+        assert len(result[0]["content"]) == 1
+        assert result[1]["content"][0]["cache_control"] == {"type": "ephemeral"}
+        assert result[2]["content"][0]["cache_control"] == {"type": "ephemeral"}
+        assert result[3]["content"][0]["cache_control"] == {"type": "ephemeral"}
+
     def test_last_3_non_system_get_markers(self):
         msgs = [
             {"role": "system", "content": "System"},
@@ -223,3 +271,59 @@ class TestApplyAnthropicCacheControl:
         assert isinstance(result[1]["content"], list)
         assert result[1]["content"][0]["cache_control"] == {"type": "ephemeral"}
         assert "cache_control" not in result[1]
+
+
+class TestNormalizationOrdering:
+    """The conversation loop normalizes message text for prefix stability and
+    injects cache breakpoints. Marking must happen AFTER normalization.
+
+    ``_apply_cache_marker`` rewrites a plain-string ``content`` into a
+    ``[{"type": "text", ...}]`` block. The loop's whitespace pass is guarded
+    on ``isinstance(content, str)``, so anything marked first is skipped by
+    it — and a message is only marked while it sits in the last-3 window.
+    The same message would then be sent raw on one turn and stripped on the
+    next, breaking the prefix match the breakpoints exist to protect.
+    """
+
+    def test_marking_a_string_hides_it_from_string_normalization(self):
+        """The mechanism: marking changes content out of ``str`` shape."""
+        msgs = [{"role": "user", "content": "hello  \n"}]
+        marked = apply_anthropic_cache_control(msgs, native_anthropic=False)
+        assert not isinstance(marked[0]["content"], str)
+        # Raw whitespace survives, now unreachable by an isinstance(str) pass.
+        assert marked[0]["content"][0]["text"] == "hello  \n"
+
+    def test_normalized_then_marked_matches_the_unmarked_wire_text(self):
+        """Normalize-then-mark keeps a message byte-identical across the
+        turn where it rolls out of the cache window."""
+        raw = "file1\nfile2\n"  # trailing newline: every shell tool result
+
+        # Turn N+1, message has left the window: plain string, normalized.
+        out_of_window = raw.strip()
+
+        # Turn N, message is in the window: normalized first, then marked.
+        marked = apply_anthropic_cache_control(
+            [{"role": "tool", "content": raw.strip(), "tool_call_id": "t1"}],
+            native_anthropic=False,
+        )
+        in_window = marked[0]["content"][0]["text"]
+
+        assert in_window == out_of_window
+
+    def test_cache_marking_runs_after_every_message_mutation(self):
+        """Ordering invariant, locked against regression."""
+        import inspect
+
+        from agent import conversation_loop
+
+        src = inspect.getsource(conversation_loop)
+        mark = src.index("apply_anthropic_cache_control(\n")
+        for earlier in (
+            'am["content"].strip()',              # whitespace normalization
+            "_sanitize_api_messages(api_messages)",       # orphan sweep
+            "_drop_thinking_only_and_merge_users(",       # drop / merge
+            "_sanitize_messages_surrogates(api_messages)",
+        ):
+            assert src.index(earlier) < mark, (
+                f"{earlier!r} must run before cache breakpoints are injected"
+            )
diff --git a/tests/agent/test_skill_invocation_description.py b/tests/agent/test_skill_invocation_description.py
new file mode 100644
index 00000000000..3b46e2f5bd0
--- /dev/null
+++ b/tests/agent/test_skill_invocation_description.py
@@ -0,0 +1,164 @@
+"""describe_skill_invocation() — recovering what the user typed from a /skill turn.
+
+A /skill invocation expands into a message that embeds the whole skill body. Any
+surface that summarizes a user turn from its raw content (session titles, sidebar
+previews, the /rewind picker) otherwise shows the SKILL's prose as if the user had
+written it.
+
+Every case here builds the scaffolding with the real message builders rather than
+a hand-written literal, so the description can't silently drift from the format it
+parses.
+"""
+
+import pytest
+
+import agent.skill_bundles as skill_bundles
+import agent.skill_commands as skill_commands
+import tools.skills_tool as skills_tool
+from agent.skill_commands import (
+    SKILL_EXCERPT_JOINT,
+    SKILL_SCAFFOLD_SQL_LIKE,
+    describe_skill_invocation,
+)
+
+SKILL_BODY = "Kick off a task in a fresh isolated git worktree instead of the current checkout."
+
+
+def _write_skill(skills_dir, name, body=SKILL_BODY):
+    skill_dir = skills_dir / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: Description for {name}\n---\n\n# {name}\n\n{body}\n"
+    )
+    return skill_dir
+
+
+def _write_bundle(bundles_dir, slug, skills):
+    bundles_dir.mkdir(parents=True, exist_ok=True)
+    lines = [f"name: {slug}", "skills:"]
+    lines.extend(f"  - {skill}" for skill in skills)
+    (bundles_dir / f"{slug}.yaml").write_text("\n".join(lines) + "\n")
+
+
+@pytest.fixture()
+def skills(tmp_path, monkeypatch):
+    """Install a 'work' skill and a 'demo' bundle, with caches reset."""
+    skills_dir = tmp_path / "skills"
+    bundles_dir = tmp_path / "skill-bundles"
+    _write_skill(skills_dir, "work")
+    _write_skill(skills_dir, "clean", body="Polish your own diff by hand.")
+    _write_bundle(bundles_dir, "demo", ["work", "clean"])
+
+    monkeypatch.setattr(skills_tool, "SKILLS_DIR", skills_dir)
+    monkeypatch.setenv("HERMES_BUNDLES_DIR", str(bundles_dir))
+    monkeypatch.setattr(skill_commands, "_skill_commands", {})
+    monkeypatch.setattr(skill_commands, "_skill_commands_platform", None)
+    monkeypatch.setattr(skill_bundles, "_bundles_cache", {})
+    monkeypatch.setattr(skill_bundles, "_bundles_cache_mtime", None)
+    skill_commands.scan_skill_commands()
+    skill_bundles.scan_bundles()
+    return skills_dir
+
+
+class TestDescribeSkillInvocation:
+    def test_passes_through_a_normal_message(self):
+        assert describe_skill_invocation("fix the title leak") is None
+
+    def test_ignores_non_string_content(self):
+        assert describe_skill_invocation(None) is None
+        assert describe_skill_invocation([{"type": "text", "text": "hi"}]) is None
+
+    def test_recovers_the_typed_instruction(self, skills):
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        assert describe_skill_invocation(message) == "/work — fix the title leak"
+
+    def test_bare_invocation_describes_the_skill_alone(self, skills):
+        message = skill_commands.build_skill_invocation_message("/work")
+        assert describe_skill_invocation(message) == "/work"
+
+    def test_never_surfaces_the_skill_body(self, skills):
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        described = describe_skill_invocation(message)
+        assert "worktree" not in described
+        assert "IMPORTANT" not in described
+
+    def test_runtime_note_is_not_part_of_the_instruction(self, skills):
+        message = skill_commands.build_skill_invocation_message(
+            "/work",
+            user_instruction="fix the title leak",
+            runtime_note="the runtime detail",
+        )
+        assert describe_skill_invocation(message) == "/work — fix the title leak"
+
+    def test_collapses_whitespace_in_a_multiline_instruction(self, skills):
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the\n  title\tleak"
+        )
+        assert describe_skill_invocation(message) == "/work — fix the title leak"
+
+    def test_bundle_carries_its_typed_keys(self, skills):
+        result = skill_bundles.build_bundle_invocation_message(
+            "/demo", user_instruction="fix the title leak"
+        )
+        assert result is not None
+        message, _, _ = result
+        described = describe_skill_invocation(message)
+        assert described.endswith("— fix the title leak")
+        assert "worktree" not in described
+
+    def test_stacked_skills_describe_every_typed_key(self, skills):
+        result = skill_commands.build_stacked_skill_invocation_message(
+            ["/work", "/clean"], user_instruction="fix the title leak"
+        )
+        assert result is not None
+        message, _, _ = result
+        assert describe_skill_invocation(message) == "/work /clean — fix the title leak"
+
+
+class TestExcerptedScaffolding:
+    """Preview queries hand over a head+tail excerpt, not the whole message."""
+
+    def _excerpt(self, message, window=400):
+        """Mirror what _preview_raw_select() hands to _shape_preview()."""
+        flat = message.replace("\n", " ").replace("\r", " ")
+        if len(message) <= window * 2:
+            return flat[: window * 2]
+        return flat[:window] + SKILL_EXCERPT_JOINT + flat[-window:]
+
+    def test_excerpt_still_recovers_the_instruction(self, skills):
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        described = describe_skill_invocation(self._excerpt(message))
+        assert described == "/work — fix the title leak"
+
+    def test_description_never_runs_across_the_joint(self, skills):
+        # A long body pushes the head window into the middle of the skill text;
+        # the instruction is only present on the tail side.
+        skill_md = skills / "work" / "SKILL.md"
+        skill_md.write_text(skill_md.read_text().replace(SKILL_BODY, "filler line.\n" * 200))
+        skill_commands._skill_commands = {}
+        skill_commands._skill_commands_platform = None
+        skill_commands.scan_skill_commands()
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        described = describe_skill_invocation(self._excerpt(message))
+        assert SKILL_EXCERPT_JOINT not in described
+        assert "filler line" not in described
+
+
+class TestSqlLikePattern:
+    def test_matches_the_prefix_the_builders_emit(self, skills):
+        message = skill_commands.build_skill_invocation_message("/work")
+        assert message.startswith(SKILL_SCAFFOLD_SQL_LIKE.rstrip("%"))
+
+    def test_carries_no_like_wildcards_needing_escape(self):
+        # The pattern is interpolated into SQL without an ESCAPE clause, so the
+        # literal part must not contain '%' or '_'.
+        assert "%" not in SKILL_SCAFFOLD_SQL_LIKE[:-1]
+        assert "_" not in SKILL_SCAFFOLD_SQL_LIKE[:-1]
diff --git a/tests/agent/test_summary_prefix_semantics.py b/tests/agent/test_summary_prefix_semantics.py
index eb8dfbee233..573eb6e22d5 100644
--- a/tests/agent/test_summary_prefix_semantics.py
+++ b/tests/agent/test_summary_prefix_semantics.py
@@ -19,9 +19,6 @@ These tests pin the post-fix invariants so the conflict cannot regress.
 """
 
 from agent.context_compressor import (
-    HISTORICAL_IN_PROGRESS_HEADING,
-    HISTORICAL_PENDING_ASKS_HEADING,
-    HISTORICAL_REMAINING_WORK_HEADING,
     HISTORICAL_TASK_HEADING,
     SUMMARY_PREFIX,
 )
@@ -37,8 +34,6 @@ def test_latest_message_wins_on_conflict():
     lower = SUMMARY_PREFIX.lower()
     assert "latest user message" in lower
     assert HISTORICAL_TASK_HEADING.lower() in lower
-    assert HISTORICAL_PENDING_ASKS_HEADING.lower() in lower
-    assert HISTORICAL_REMAINING_WORK_HEADING.lower() in lower
     # Must have an explicit conflict-resolution rule.
     assert "wins" in lower or "supersede" in lower or "discard" in lower or "priority" in lower
 
@@ -51,7 +46,6 @@ def test_handoff_sections_are_framed_as_historical():
     assert "## pending user asks" not in lower
     assert "## remaining work" not in lower
     assert HISTORICAL_TASK_HEADING.lower() in lower
-    assert HISTORICAL_IN_PROGRESS_HEADING.lower() in lower
 
 
 def test_reverse_signals_called_out():
@@ -114,3 +108,153 @@ def test_replaced_prefixes_are_frozen_for_renormalization():
         assert ContextCompressor._is_context_summary_content(content)
         stripped = ContextCompressor._strip_summary_prefix(content)
         assert not stripped.startswith(old_prefix)
+
+
+# Exact literal copies of every SUMMARY_PREFIX generation retired into
+# _HISTORICAL_SUMMARY_PREFIXES, newest-first. Frozen on purpose: do NOT
+# derive them from module constants — the tests below must fail if any
+# frozen entry is mutated, reordered, or dropped.
+_FROZEN_PREFIX_GENERATIONS = (
+    # Pre-#69619: four-heading discard clause + tools-active clause.
+    (
+        "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were "
+        "compacted into the summary below. This is a handoff from a "
+        "previous context window — treat it as background reference, NOT "
+        "as active instructions. Do NOT answer questions or fulfill "
+        "requests mentioned in this summary; they were already addressed. "
+        "Respond ONLY to the latest user message that appears AFTER this "
+        "summary — that message is the single source of truth for what to "
+        "do right now. Topic overlap with the summary does NOT mean you "
+        "should resume its task: even on similar topics, the latest user "
+        "message WINS. Treat ONLY the latest message as the active task "
+        "and discard stale items from '## Historical Task Snapshot' / '## "
+        "Historical In-Progress State' / '## Historical Pending User "
+        "Asks' / '## Historical Remaining Work' entirely — do not 'wrap "
+        "up' or 'finish' work described there unless the latest message "
+        "explicitly asks for it. Reverse signals in the latest message "
+        "(e.g. 'stop', 'undo', 'roll back', 'just verify', 'don't do that "
+        "anymore', 'never mind', a new topic) must immediately end any "
+        "in-flight work described in the summary; do not re-surface it in "
+        "later turns. IMPORTANT: Your persistent memory (MEMORY.md, "
+        "USER.md) in the system prompt is ALWAYS authoritative and active "
+        "— never ignore or deprioritize memory content due to this "
+        "compaction note. None of the above restricts HOW you work: your "
+        "tools remain fully active — keep calling them normally for the "
+        "active task (edit files, run commands, search) instead of merely "
+        "narrating what you would do. The current session state (files, "
+        "config, etc.) may reflect work described here — avoid repeating "
+        "it:"
+    ),
+    # Jul 2026 (#65848 class): same discard clause, no tools-active clause.
+    (
+        "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were "
+        "compacted into the summary below. This is a handoff from a "
+        "previous context window — treat it as background reference, NOT "
+        "as active instructions. Do NOT answer questions or fulfill "
+        "requests mentioned in this summary; they were already addressed. "
+        "Respond ONLY to the latest user message that appears AFTER this "
+        "summary — that message is the single source of truth for what to "
+        "do right now. Topic overlap with the summary does NOT mean you "
+        "should resume its task: even on similar topics, the latest user "
+        "message WINS. Treat ONLY the latest message as the active task "
+        "and discard stale items from '## Historical Task Snapshot' / '## "
+        "Historical In-Progress State' / '## Historical Pending User "
+        "Asks' / '## Historical Remaining Work' entirely — do not 'wrap "
+        "up' or 'finish' work described there unless the latest message "
+        "explicitly asks for it. Reverse signals in the latest message "
+        "(e.g. 'stop', 'undo', 'roll back', 'just verify', 'don't do that "
+        "anymore', 'never mind', a new topic) must immediately end any "
+        "in-flight work described in the summary; do not re-surface it in "
+        "later turns. IMPORTANT: Your persistent memory (MEMORY.md, "
+        "USER.md) in the system prompt is ALWAYS authoritative and active "
+        "— never ignore or deprioritize memory content due to this "
+        "compaction note. The current session state (files, config, etc.) "
+        "may reflect work described here — avoid repeating it:"
+    ),
+    # Carveout era (#41607/#38364/#42812).
+    (
+        "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were "
+        "compacted into the summary below. This is a handoff from a "
+        "previous context window — treat it as background reference, NOT "
+        "as active instructions. Do NOT answer questions or fulfill "
+        "requests mentioned in this summary; they were already addressed. "
+        "Respond ONLY to the latest user message that appears AFTER this "
+        "summary — that message is the single source of truth for what to "
+        "do right now. If the latest user message is consistent with the "
+        "'## Active Task' section, you may use the summary as background. "
+        "If the latest user message contradicts, supersedes, changes "
+        "topic from, or in any way diverges from '## Active Task' / '## "
+        "In Progress' / '## Pending User Asks' / '## Remaining Work', the "
+        "latest message WINS — discard those stale items entirely and do "
+        "not 'wrap up the old task first'. Reverse signals in the latest "
+        "message (e.g. 'stop', 'undo', 'roll back', 'just verify', 'don't "
+        "do that anymore', 'never mind', a new topic) must immediately "
+        "end any in-flight work described in the summary; do not "
+        "re-surface it in later turns. IMPORTANT: Your persistent memory "
+        "(MEMORY.md, USER.md) in the system prompt is ALWAYS "
+        "authoritative and active — never ignore or deprioritize memory "
+        "content due to this compaction note. The current session state "
+        "(files, config, etc.) may reflect work described here — avoid "
+        "repeating it:"
+    ),
+    # Pre-#35344: self-contradicting "resume exactly" directive.
+    (
+        "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were "
+        "compacted into the summary below. This is a handoff from a "
+        "previous context window — treat it as background reference, NOT "
+        "as active instructions. Do NOT answer questions or fulfill "
+        "requests mentioned in this summary; they were already addressed. "
+        "Your current task is identified in the '## Active Task' section "
+        "of the summary — resume exactly from there. Respond ONLY to the "
+        "latest user message that appears AFTER this summary. The current "
+        "session state (files, config, etc.) may reflect work described "
+        "here — avoid repeating it:"
+    ),
+)
+
+
+# The generation retired by #69619, pinned individually for the review
+# regression below.
+_PRE_69619_LIVE_PREFIX = _FROZEN_PREFIX_GENERATIONS[0]
+
+
+def test_pre_69619_prefix_generation_is_frozen_and_stripped():
+    """Regression for the #69619 review: the prefix generation live right
+    before the section-header removal was never added to
+    _HISTORICAL_SUMMARY_PREFIXES, so a summary persisted immediately before
+    upgrading survived resume/re-compaction undetected and unstripped.
+    That exact generation must stay frozen, detectable, and strippable."""
+    from agent.context_compressor import (
+        _HISTORICAL_SUMMARY_PREFIXES,
+        ContextCompressor,
+    )
+
+    assert _PRE_69619_LIVE_PREFIX in _HISTORICAL_SUMMARY_PREFIXES, (
+        "pre-#69619 live prefix missing from _HISTORICAL_SUMMARY_PREFIXES — "
+        "summaries persisted by the immediately previous build are no longer "
+        "normalized on resume"
+    )
+    content = _PRE_69619_LIVE_PREFIX + "\nBODY"
+    assert ContextCompressor._is_context_summary_content(content)
+    assert ContextCompressor._strip_summary_prefix(content) == "BODY"
+
+
+def test_frozen_generations_match_historical_prefixes_byte_exactly():
+    """Every entry in _HISTORICAL_SUMMARY_PREFIXES must equal its literal pin
+    in _FROZEN_PREFIX_GENERATIONS, in order. Frozen entries are immutable and
+    prepend-only: mutating, reordering, or dropping one silently un-normalizes
+    summaries persisted by that build generation — the exact failure caught in
+    the #69619 review, which the per-entry self-matching loop above cannot see.
+    """
+    from agent.context_compressor import (
+        _HISTORICAL_SUMMARY_PREFIXES,
+        ContextCompressor,
+    )
+
+    assert tuple(_FROZEN_PREFIX_GENERATIONS) == tuple(
+        _HISTORICAL_SUMMARY_PREFIXES
+    ), "a frozen prefix entry was mutated, reordered, added, or dropped"
+    for prefix in _FROZEN_PREFIX_GENERATIONS:
+        content = prefix + "\nBODY"
+        assert ContextCompressor._is_context_summary_content(content)
+        assert ContextCompressor._strip_summary_prefix(content) == "BODY"
diff --git a/tests/agent/test_summary_prefix_tool_use.py b/tests/agent/test_summary_prefix_tool_use.py
index 2a289b86f9b..c67f71f184c 100644
--- a/tests/agent/test_summary_prefix_tool_use.py
+++ b/tests/agent/test_summary_prefix_tool_use.py
@@ -30,11 +30,19 @@ class TestSummaryPrefixToolUseClause:
         generation must be frozen into _HISTORICAL_SUMMARY_PREFIXES so old
         persisted summaries still get the directive-strip on re-compaction."""
         assert len(_HISTORICAL_SUMMARY_PREFIXES) >= 3
-        newest_frozen = _HISTORICAL_SUMMARY_PREFIXES[0]
-        # The frozen copy is the pre-clause generation: same framing, no clause.
-        assert "tools remain fully active" not in newest_frozen
-        assert "Do NOT answer questions or fulfill requests" in newest_frozen
-        assert newest_frozen != SUMMARY_PREFIX
+        # The pre-clause generation (#65848 incident era): same framing, no
+        # tools-active clause. Newer generations are prepended ahead of it as
+        # the prefix evolves (tuple is newest-first), so match by content,
+        # not position. "topic overlap" distinguishes it from the older
+        # carveout-era entry.
+        pre_clause = [
+            p for p in _HISTORICAL_SUMMARY_PREFIXES
+            if "tools remain fully active" not in p
+            and "topic overlap" in p.lower()
+            and "Do NOT answer questions or fulfill requests" in p
+        ]
+        assert pre_clause, "pre-clause generation missing from frozen tuple"
+        assert all(p != SUMMARY_PREFIX for p in pre_clause)
 
     def test_historical_prefixes_are_distinct_from_current(self):
         for frozen in _HISTORICAL_SUMMARY_PREFIXES:
diff --git a/tests/agent/test_system_prompt.py b/tests/agent/test_system_prompt.py
index 78ea4cda815..f37716a72e2 100644
--- a/tests/agent/test_system_prompt.py
+++ b/tests/agent/test_system_prompt.py
@@ -1,9 +1,11 @@
 """Tests for agent/system_prompt.py — context-file cwd wiring."""
 
+from datetime import datetime
+from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import patch
 
-from agent.system_prompt import build_system_prompt_parts
+from agent.system_prompt import build_system_prompt, build_system_prompt_parts
 
 
 def _make_agent(**overrides):
@@ -70,6 +72,16 @@ def _stable_prompt(agent):
         return build_system_prompt_parts(agent)["stable"]
 
 
+def _prompt_parts(agent):
+    with (
+        patch("run_agent.load_soul_md", return_value=""),
+        patch("run_agent.build_nous_subscription_prompt", return_value=""),
+        patch("run_agent.build_environment_hints", return_value=""),
+        patch("run_agent.build_context_files_prompt", return_value=""),
+    ):
+        return build_system_prompt_parts(agent)
+
+
 def _init_code_repo(path):
     """A git repo that actually holds code — the coding posture requires a source
     file (or manifest), not a bare ``.git`` (a prose/notes repo stays general)."""
@@ -84,9 +96,9 @@ class TestCodingContextBlock:
         _init_code_repo(tmp_path)
         monkeypatch.setenv("TERMINAL_CWD", str(tmp_path))
         agent = _make_agent(valid_tool_names=["read_file"], platform="cli")
-        stable = _stable_prompt(agent)
-        assert "coding agent" in stable
-        assert "Workspace" in stable
+        parts = _prompt_parts(agent)
+        assert "coding agent" in parts["stable"]
+        assert "Workspace" in parts["context"]
 
     def test_absent_when_off(self, monkeypatch, tmp_path):
         _init_code_repo(tmp_path)
@@ -104,6 +116,75 @@ class TestCodingContextBlock:
         assert "coding agent" not in _stable_prompt(agent)
 
 
+def test_build_system_prompt_records_stable_prefix():
+    agent = _make_agent()
+    with (
+        patch("run_agent.load_soul_md", return_value=""),
+        patch("run_agent.build_nous_subscription_prompt", return_value=""),
+        patch("run_agent.build_environment_hints", return_value=""),
+        patch("run_agent.build_context_files_prompt", return_value="context"),
+    ):
+        prompt = build_system_prompt(agent)
+
+    assert prompt.startswith(agent._cached_system_prompt_static)
+    assert prompt[len(agent._cached_system_prompt_static):].startswith("\n\ncontext")
+
+
+def test_coding_prompt_preserves_legacy_workspace_order(monkeypatch):
+    """The cache split must not reorder the stored coding prompt."""
+    import agent.system_prompt as system_prompt
+
+    agent = _make_agent(
+        valid_tool_names=["read_file"],
+        _parallel_tool_call_guidance=False,
+    )
+    monkeypatch.setattr(system_prompt, "DEFAULT_AGENT_IDENTITY", "IDENTITY")
+    monkeypatch.setattr(system_prompt, "HERMES_AGENT_HELP_GUIDANCE", "HELP")
+    monkeypatch.setattr(system_prompt, "STEER_CHANNEL_NOTE", "STEER")
+    monkeypatch.setattr(system_prompt, "get_hermes_home", lambda: Path("/hermes"))
+
+    expected_profile = (
+        "Active Hermes profile: default. Other profiles (if any) live "
+        "under /hermes/profiles/<name>/. Each profile has its own skills/, "
+        "plugins/, cron/, and memories/ that affect a different session than "
+        "this one. Do not modify another profile's skills/plugins/cron/memories "
+        "unless the user explicitly directs you to."
+    )
+    expected = "\n\n".join((
+        "IDENTITY",
+        "HELP",
+        "STEER",
+        "CODING_STABLE",
+        "WORKSPACE",
+        "Operator instructions (from config):\nOPERATOR",
+        expected_profile,
+        "SYSTEM_MESSAGE",
+        "CONTEXT_FILES",
+        "Conversation started: Friday, January 02, 2026",
+    ))
+
+    with (
+        patch("run_agent.load_soul_md", return_value=""),
+        patch("run_agent.build_nous_subscription_prompt", return_value=""),
+        patch("run_agent.build_environment_hints", return_value=""),
+        patch("run_agent.build_context_files_prompt", return_value="CONTEXT_FILES"),
+        patch(
+            "agent.coding_context.coding_system_prompt_parts",
+            return_value=(
+                ["CODING_STABLE"],
+                ["WORKSPACE"],
+                ["Operator instructions (from config):\nOPERATOR"],
+            ),
+        ),
+        patch("agent.file_safety._resolve_active_profile_name", return_value="default"),
+        patch("hermes_time.now", return_value=datetime(2026, 1, 2)),
+    ):
+        prompt = build_system_prompt(agent, system_message="SYSTEM_MESSAGE")
+
+    assert prompt == expected
+    assert agent._cached_system_prompt_static == "\n\n".join(expected.split("\n\n")[:4])
+
+
 class TestTelegramRichMessagesHint:
     """Verify that TELEGRAM_RICH_MESSAGES_HINT is conditionally included."""
 
diff --git a/tests/agent/test_system_prompt_restore.py b/tests/agent/test_system_prompt_restore.py
index 956c1152a42..72564325d93 100644
--- a/tests/agent/test_system_prompt_restore.py
+++ b/tests/agent/test_system_prompt_restore.py
@@ -32,6 +32,10 @@ def _make_agent(session_db=None, prebuilt_prompt: str = "BUILT_PROMPT"):
     agent.provider = "openrouter"
     agent.platform = "cli"
     agent._session_db = session_db
+    # MagicMock attributes are truthy by default; the static-prefix
+    # reconstruction is gated on _use_prompt_caching, so default it off
+    # for the legacy restore tests (the reconstruction tests enable it).
+    agent._use_prompt_caching = False
     agent._build_system_prompt = MagicMock(return_value=prebuilt_prompt)
     return agent
 
@@ -261,5 +265,90 @@ class TestPromptStabilityInvariant:
         assert agent._cached_system_prompt.encode("utf-8") == stored.encode("utf-8")
 
 
+# ---------------------------------------------------------------------------
+# Cross-session static prefix reconstruction (issue #68191 follow-up)
+# ---------------------------------------------------------------------------
+
+
+class TestStaticPrefixReconstructionOnRestore:
+    """The two-block cache layout must survive session restore.
+
+    Gateway surfaces construct a fresh AIAgent per turn and restore the
+    persisted prompt from the session DB; the cross-session-stable prefix
+    (``_cached_system_prompt_static``) is only set on fresh builds, so
+    without reconstruction the wire layout silently degrades to the legacy
+    single-breakpoint layout after turn 1 (flagged on PR #68258 review).
+    """
+
+    def test_restore_reconstructs_static_prefix_when_it_matches(self):
+        stable = "STATIC IDENTITY AND GUIDANCE"
+        stored = stable + "\n\nper-session context\n\nvolatile tail"
+        db = MagicMock()
+        db.get_session.return_value = {"system_prompt": stored}
+        agent = _make_agent(session_db=db)
+        agent._use_prompt_caching = True
+        agent._cached_system_prompt_static = None
+
+        from unittest.mock import patch as _patch
+
+        with _patch(
+            "agent.system_prompt.build_system_prompt_parts",
+            return_value={"stable": stable, "context": "", "volatile": ""},
+        ):
+            _restore_or_build_system_prompt(
+                agent, None, [{"role": "user", "content": "hi"}]
+            )
+
+        # Restored prompt bytes untouched; static prefix reconstructed.
+        assert agent._cached_system_prompt == stored
+        assert agent._cached_system_prompt_static == stable
+
+    def test_restore_leaves_static_unset_on_prefix_mismatch(self):
+        """Stable-tier drift (skills edited since persist) → no static prefix,
+        legacy layout, restored bytes still authoritative."""
+        stored = "OLD STATIC HEAD\n\nper-session context"
+        db = MagicMock()
+        db.get_session.return_value = {"system_prompt": stored}
+        agent = _make_agent(session_db=db)
+        agent._use_prompt_caching = True
+        agent._cached_system_prompt_static = None
+
+        from unittest.mock import patch as _patch
+
+        with _patch(
+            "agent.system_prompt.build_system_prompt_parts",
+            return_value={"stable": "NEW STATIC HEAD", "context": "", "volatile": ""},
+        ):
+            _restore_or_build_system_prompt(
+                agent, None, [{"role": "user", "content": "hi"}]
+            )
+
+        assert agent._cached_system_prompt == stored
+        assert agent._cached_system_prompt_static is None
+
+    def test_restore_survives_parts_builder_exception(self):
+        """Prefix reconstruction is fail-open: a parts-builder crash must not
+        break the byte-identical restore."""
+        stored = "Stored prompt — must survive"
+        db = MagicMock()
+        db.get_session.return_value = {"system_prompt": stored}
+        agent = _make_agent(session_db=db)
+        agent._use_prompt_caching = True
+        agent._cached_system_prompt_static = None
+
+        from unittest.mock import patch as _patch
+
+        with _patch(
+            "agent.system_prompt.build_system_prompt_parts",
+            side_effect=RuntimeError("boom"),
+        ):
+            _restore_or_build_system_prompt(
+                agent, None, [{"role": "user", "content": "hi"}]
+            )
+
+        assert agent._cached_system_prompt == stored
+        assert agent._cached_system_prompt_static is None
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])
diff --git a/tests/agent/test_title_generator.py b/tests/agent/test_title_generator.py
index bd281f728e0..8f0af90ab31 100644
--- a/tests/agent/test_title_generator.py
+++ b/tests/agent/test_title_generator.py
@@ -212,6 +212,93 @@ class TestGenerateTitle:
         user_content = captured_kwargs["messages"][1]["content"]
         assert len(user_content) < 1100  # 500 + 500 + formatting
 
+    def test_skill_invocation_is_titled_from_what_the_user_typed(self):
+        """A /skill turn embeds the whole skill body — the titler must never
+        see it, or the session gets named after the SKILL, not the request."""
+        skill_body = "Kick off a task in a fresh isolated git worktree. " * 20
+        expanded = (
+            '[IMPORTANT: The user has invoked the "work" skill, indicating they want '
+            "you to follow its instructions. The full skill content is loaded below.]\n\n"
+            f"{skill_body}\n\n"
+            "The user has provided the following instruction alongside the skill "
+            "invocation: fix the session title leak"
+        )
+        captured_kwargs = {}
+
+        def mock_call_llm(**kwargs):
+            captured_kwargs.update(kwargs)
+            resp = MagicMock()
+            resp.choices = [MagicMock()]
+            resp.choices[0].message.content = "Fixing The Session Title Leak"
+            return resp
+
+        with patch("agent.title_generator.call_llm", side_effect=mock_call_llm):
+            generate_title(expanded, "On it.")
+
+        sent = captured_kwargs["messages"][1]["content"]
+        assert "/work — fix the session title leak" in sent
+        assert "worktree" not in sent
+        assert "IMPORTANT" not in sent
+
+    def test_bare_skill_invocation_still_titles(self):
+        """No typed instruction — the titler gets the command, not the body."""
+        expanded = (
+            '[IMPORTANT: The user has invoked the "weather-forecast-lookup" skill, '
+            "indicating they want you to follow its instructions. The full skill "
+            "content is loaded below.]\n\nPull clean multi-day forecasts."
+        )
+        captured_kwargs = {}
+
+        def mock_call_llm(**kwargs):
+            captured_kwargs.update(kwargs)
+            resp = MagicMock()
+            resp.choices = [MagicMock()]
+            resp.choices[0].message.content = "Weather Forecast Lookup"
+            return resp
+
+        with patch("agent.title_generator.call_llm", side_effect=mock_call_llm):
+            assert generate_title(expanded, "Here you go.") == "Weather Forecast Lookup"
+
+        sent = captured_kwargs["messages"][1]["content"]
+        assert "/weather-forecast-lookup" in sent
+        assert "Pull clean multi-day forecasts" not in sent
+
+    def test_plain_message_reaches_the_titler_unchanged(self):
+        """The scaffolding summary must not touch an ordinary user turn."""
+        captured_kwargs = {}
+
+        def mock_call_llm(**kwargs):
+            captured_kwargs.update(kwargs)
+            resp = MagicMock()
+            resp.choices = [MagicMock()]
+            resp.choices[0].message.content = "A Title"
+            return resp
+
+        with patch("agent.title_generator.call_llm", side_effect=mock_call_llm):
+            generate_title("fix the session title leak", "On it.")
+
+        assert "fix the session title leak" in captured_kwargs["messages"][1]["content"]
+
+    def test_multiline_answer_collapses_to_its_first_line(self):
+        """A model that answers the prompt instead of titling it must not have
+        a shell transcript stored as the session title."""
+        mock_response = MagicMock()
+        mock_response.choices = [MagicMock()]
+        mock_response.choices[0].message.content = (
+            "macOS Disk Cleanup\n\n$ df -h /\nFilesystem      Size  Used Avail\n"
+        )
+
+        with patch("agent.title_generator.call_llm", return_value=mock_response):
+            assert generate_title("clean my disk", "Sure.") == "macOS Disk Cleanup"
+
+    def test_leading_blank_lines_do_not_empty_the_title(self):
+        mock_response = MagicMock()
+        mock_response.choices = [MagicMock()]
+        mock_response.choices[0].message.content = "\n\n  Real Title  \nmore prose"
+
+        with patch("agent.title_generator.call_llm", return_value=mock_response):
+            assert generate_title("q", "a") == "Real Title"
+
     def test_skips_when_title_generation_disabled(self):
         """auxiliary.title_generation.enabled=false disables automatic titles."""
         config = {"auxiliary": {"title_generation": {"enabled": False}}}
diff --git a/tests/agent/test_turn_context.py b/tests/agent/test_turn_context.py
index 8c34a25c8ed..fcf94fe39a0 100644
--- a/tests/agent/test_turn_context.py
+++ b/tests/agent/test_turn_context.py
@@ -208,6 +208,37 @@ def test_returns_turn_context_with_user_message_appended():
     assert ctx.active_system_prompt == "SYSTEM"
 
 
+def test_turn_start_replaces_stale_parent_history_with_compression_child():
+    agent = _FakeAgent()
+    stale_history = [{"role": "user", "content": "stale parent"}]
+    compacted_history = [
+        {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+        {"role": "assistant", "content": "child tail"},
+    ]
+
+    def _recover(_agent):
+        _agent.session_id = "compression-child"
+        return compacted_history
+
+    log_context = MagicMock()
+    with patch(
+        "agent.turn_context.recover_rotated_compression_session",
+        side_effect=_recover,
+    ):
+        ctx = _build(
+            agent,
+            conversation_history=stale_history,
+            set_session_context=log_context,
+        )
+
+    assert agent.session_id == "compression-child"
+    assert agent._current_turn_id.startswith("compression-child:")
+    log_context.assert_called_once_with("compression-child")
+    assert ctx.conversation_history == compacted_history
+    assert ctx.messages == compacted_history + [{"role": "user", "content": "hello"}]
+    assert all(message.get("content") != "stale parent" for message in ctx.messages)
+
+
 def test_applies_agent_side_effects():
     agent = _FakeAgent()
     _build(agent)
diff --git a/tests/agent/test_verification_evidence_fd_leak.py b/tests/agent/test_verification_evidence_fd_leak.py
new file mode 100644
index 00000000000..e973aabb9e0
--- /dev/null
+++ b/tests/agent/test_verification_evidence_fd_leak.py
@@ -0,0 +1,126 @@
+"""Regression: the verification-evidence ledger must close every connection.
+
+Sibling of the cron execution-ledger leak (#69567 / PR #69594). The evidence
+ledger used ``with _connect() as conn:`` where the connection context manager
+commits/rolls back but never closes, leaking the db/-wal/-shm file descriptors
+on every recorded terminal result, workspace edit, and status read. These tests
+fail if the deterministic ``close()`` is ever removed again.
+"""
+
+import sqlite3
+
+import pytest
+
+from agent import verification_evidence as ve
+
+
+class _TrackingConnection:
+    """Delegates to a real sqlite3.Connection while recording close() calls.
+
+    sqlite3.Connection is a static C type: it has no per-instance __dict__ and
+    its methods can't be monkeypatched, so open/close tracking is done via a
+    delegating wrapper returned in place of the real connection.
+    """
+
+    def __init__(self, real, closed_ids):
+        object.__setattr__(self, "_real", real)
+        object.__setattr__(self, "_closed_ids", closed_ids)
+
+    def close(self):
+        self._closed_ids.append(id(self._real))
+        self._real.close()
+
+    def __enter__(self):
+        self._real.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return self._real.__exit__(exc_type, exc, tb)
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)
+
+    def __setattr__(self, name, value):
+        setattr(self._real, name, value)
+
+
+def _point_ledger(monkeypatch, tmp_path):
+    monkeypatch.setattr(ve, "_db_path", lambda: tmp_path / "verification_evidence.db")
+    return ve
+
+
+def _track_connections(monkeypatch):
+    opened, closed = [], []
+    real_connect = sqlite3.connect
+
+    def tracking_connect(*args, **kwargs):
+        conn = real_connect(*args, **kwargs)
+        opened.append(id(conn))
+        return _TrackingConnection(conn, closed)
+
+    monkeypatch.setattr(ve.sqlite3, "connect", tracking_connect)
+    return opened, closed
+
+
+def _python_project(root):
+    (root / "pyproject.toml").write_text("[tool.pytest.ini_options]\n")
+
+
+def test_ledger_operations_close_every_connection(monkeypatch, tmp_path):
+    """Recording, editing, and status reads must close every connection opened."""
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path / ".hermes"))
+    _point_ledger(monkeypatch, tmp_path)
+    _python_project(tmp_path)
+    opened, closed = _track_connections(monkeypatch)
+
+    ve.record_terminal_result(
+        command="python -m pytest tests/test_calc.py::test_even -q",
+        cwd=tmp_path, session_id="s1", exit_code=0, output="1 passed",
+    )
+    ve.verification_status(session_id="s1", cwd=tmp_path)
+    ve.mark_workspace_edited(session_id="s1", cwd=tmp_path, paths=["mod.py"])
+
+    assert opened, "expected at least one connection to be opened"
+    assert len(opened) == len(closed)
+    assert set(opened) == set(closed)
+
+
+def test_exception_during_operation_still_closes_connection(monkeypatch, tmp_path):
+    """A failing statement inside the transaction must roll back and close."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _track_connections(monkeypatch)
+
+    with pytest.raises(sqlite3.IntegrityError):
+        with ve._transaction() as conn:
+            # Missing NOT NULL columns -> constraint failure inside the block.
+            conn.execute("INSERT INTO verification_events (id) VALUES (1)")
+
+    assert len(opened) == 1
+    assert len(closed) == 1
+
+
+def test_schema_init_failure_still_closes_connection(monkeypatch, tmp_path):
+    """A PRAGMA/DDL failure after connect() must still close the connection."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = [], []
+    real_connect = sqlite3.connect
+
+    class _FailingSchemaConnection(_TrackingConnection):
+        def execute(self, sql, *args, **kwargs):
+            if "CREATE TABLE" in sql:
+                raise sqlite3.OperationalError("simulated schema init failure")
+            return self._real.execute(sql, *args, **kwargs)
+
+    def tracking_connect(*args, **kwargs):
+        conn = real_connect(*args, **kwargs)
+        opened.append(id(conn))
+        return _FailingSchemaConnection(conn, closed)
+
+    monkeypatch.setattr(ve.sqlite3, "connect", tracking_connect)
+
+    with pytest.raises(sqlite3.OperationalError):
+        with ve._transaction():
+            pass
+
+    assert len(opened) == 1
+    assert len(closed) == 1
diff --git a/tests/agent/transports/test_codex_transport.py b/tests/agent/transports/test_codex_transport.py
index 1a17a39a774..8563ca7a607 100644
--- a/tests/agent/transports/test_codex_transport.py
+++ b/tests/agent/transports/test_codex_transport.py
@@ -243,6 +243,62 @@ class TestCodexBuildKwargs:
         message_item = next(item for item in kw["input"] if item.get("type") == "message")
         assert message_item["id"] == "msg_short_id"
 
+    @pytest.mark.parametrize("model", [
+        "gpt-5.5",
+        "gpt-5.5-pro",
+        "gpt-5.4",
+        "gpt-5.2",
+        "gpt-5.1-codex-max",
+        "gpt-5.1",
+        "gpt-5.1-codex",
+        "gpt-5.1-codex-mini",
+        "gpt-5.1-chat-latest",
+        "gpt-5",
+        "gpt-5-codex",
+        "gpt-4.1",
+        "openai.gpt-5.5-pro",
+        "openai/gpt-5.1-codex-2026-01-01",
+    ])
+    def test_extended_cache_models_set_24h_prompt_cache_retention(self, transport, model):
+        messages = [{"role": "user", "content": "Hi"}]
+        kw = transport.build_kwargs(
+            model=model, messages=messages, tools=[],
+            session_id="test-session",
+            base_url="https://bedrock-mantle.us-west-2.api.aws/v1",
+        )
+        assert kw["prompt_cache_retention"] == "24h"
+
+    @pytest.mark.parametrize("model", ["gpt-5.6", "gpt-4o", "o3"])
+    def test_prompt_cache_retention_omitted_for_other_model_families(self, transport, model):
+        kw = transport.build_kwargs(
+            model=model,
+            messages=[{"role": "user", "content": "Hi"}],
+            tools=[],
+            session_id="test-session",
+            base_url="https://bedrock-mantle.us-west-2.api.aws/v1",
+        )
+        assert "prompt_cache_retention" not in kw
+
+    @pytest.mark.parametrize("base_url", [
+        "https://api.openai.com/v1",
+        "https://example.openai.azure.com/openai/v1",
+        "https://api.x.ai/v1",
+        "https://models.github.ai/inference",
+        "https://api.githubcopilot.com",
+        "https://chatgpt.com/backend-api/codex",
+        "https://responses.example.com/v1",
+        "https://bedrock-mantle.us-west-2.api.aws.example/v1",
+        "https://example.com/bedrock-mantle.us-west-2.api.aws/v1",
+    ])
+    def test_prompt_cache_retention_omitted_for_non_mantle_endpoints(self, transport, base_url):
+        kw = transport.build_kwargs(
+            model="gpt-5.4",
+            messages=[{"role": "user", "content": "Hi"}],
+            tools=[],
+            base_url=base_url,
+        )
+        assert "prompt_cache_retention" not in kw
+
     def test_xai_responses_sends_cache_key_via_extra_body(self, transport):
         """xAI's Responses API documents ``prompt_cache_key`` as the
         body-level cache-routing key (the ``x-grok-conv-id`` header is
diff --git a/tests/cli/test_cli_provider_resolution.py b/tests/cli/test_cli_provider_resolution.py
index d1500723f87..bf54224dd2d 100644
--- a/tests/cli/test_cli_provider_resolution.py
+++ b/tests/cli/test_cli_provider_resolution.py
@@ -230,6 +230,47 @@ def test_cli_prefers_config_provider_over_stale_env_override(monkeypatch):
     assert shell.requested_provider == "custom"
 
 
+def test_cli_init_wires_moa_preset_model_to_moa_provider(monkeypatch):
+    # #56828: constructing the CLI with `-m moa:<preset>` (the -Q one-shot
+    # path) must strip the prefix off self.model AND force
+    # requested_provider="moa", so the existing resolve_runtime_provider /
+    # agent_init MoA route runs non-interactively. The unit tests cover
+    # _normalize_moa_model() in isolation; this asserts the __init__ wiring
+    # the sweeper flagged as untested.
+    cli = _import_cli()
+
+    # Neutralize any config/env provider so a failure here can only come from
+    # the moa override, not an ambient default.
+    config_copy = dict(cli.CLI_CONFIG)
+    model_copy = dict(config_copy.get("model", {}))
+    model_copy["provider"] = None
+    config_copy["model"] = model_copy
+    monkeypatch.setattr(cli, "CLI_CONFIG", config_copy)
+    monkeypatch.delenv("HERMES_INFERENCE_PROVIDER", raising=False)
+
+    shell = cli.HermesCLI(model="moa:strategy", compact=True, max_turns=1)
+
+    assert shell.requested_provider == "moa"
+    assert shell.model == "strategy"
+
+
+def test_cli_init_moa_prefix_overrides_explicit_provider(monkeypatch):
+    # The #56828 regression case: `--provider deepseek -m moa:strategy`
+    # silently dropped MoA because the explicit provider won. __init__ resolves
+    # requested_provider as `_moa_provider_override or provider or ...`, so the
+    # moa: prefix must win over the explicit --provider.
+    cli = _import_cli()
+
+    monkeypatch.delenv("HERMES_INFERENCE_PROVIDER", raising=False)
+
+    shell = cli.HermesCLI(
+        model="moa:strategy", provider="deepseek", compact=True, max_turns=1
+    )
+
+    assert shell.requested_provider == "moa"
+    assert shell.model == "strategy"
+
+
 def test_codex_provider_replaces_incompatible_default_model(monkeypatch):
     """When provider resolves to openai-codex and no model was explicitly
     chosen, the global config default (e.g. anthropic/claude-opus-4.6) must
@@ -752,11 +793,16 @@ def test_model_flow_custom_persists_selected_api_mode(monkeypatch):
             "used_fallback": False,
         },
     )
+    saved_env = {}
     monkeypatch.setattr("hermes_cli.config.load_config", lambda: saved_cfg)
     monkeypatch.setattr("hermes_cli.config.save_config", lambda cfg: saved_cfg.update(cfg))
+    monkeypatch.setattr(
+        "hermes_cli.config.save_env_value",
+        lambda key, value: saved_env.__setitem__(key, value),
+    )
     monkeypatch.setattr(
         "hermes_cli.main._save_custom_provider",
-        lambda base_url, api_key="", model="", context_length=None, name=None, api_mode=None: captured_provider.update(
+        lambda base_url, api_key="", model="", context_length=None, name=None, api_mode=None, key_env="": captured_provider.update(
             {
                 "base_url": base_url,
                 "api_key": api_key,
@@ -764,6 +810,7 @@ def test_model_flow_custom_persists_selected_api_mode(monkeypatch):
                 "context_length": context_length,
                 "name": name,
                 "api_mode": api_mode,
+                "key_env": key_env,
             }
         ),
     )
@@ -784,10 +831,14 @@ def test_model_flow_custom_persists_selected_api_mode(monkeypatch):
 
     assert saved_cfg["model"]["provider"] == "custom"
     assert saved_cfg["model"]["base_url"] == "https://codex.example.com/v1"
-    assert saved_cfg["model"]["api_key"] == "test-key"
     assert saved_cfg["model"]["api_mode"] == "codex_responses"
     assert captured_provider["api_mode"] == "codex_responses"
 
+    # The key itself goes to .env; config.yaml only references it (#69449).
+    key_env = captured_provider["key_env"]
+    assert saved_cfg["model"]["api_key"] == f"${{{key_env}}}"
+    assert saved_env[key_env] == "test-key"
+
 
 def test_cmd_model_forwards_nous_login_tls_options(monkeypatch):
     monkeypatch.setattr(hermes_main, "_require_tty", lambda *a: None)
@@ -882,3 +933,81 @@ def test_save_custom_provider_uses_provided_name(monkeypatch, tmp_path):
     entries = saved.get("custom_providers", [])
     assert len(entries) == 1
     assert entries[0]["name"] == "Ollama"
+
+
+def test_save_custom_provider_references_the_key_instead_of_inlining_it(monkeypatch, tmp_path):
+    """With key_env set the entry must not carry the secret (#69449)."""
+    import yaml
+    from hermes_cli.main import _save_custom_provider
+
+    cfg_path = tmp_path / "config.yaml"
+    cfg_path.write_text(yaml.dump({}))
+    monkeypatch.setattr(
+        "hermes_cli.config.load_config", lambda: yaml.safe_load(cfg_path.read_text()) or {},
+    )
+    saved = {}
+    monkeypatch.setattr("hermes_cli.config.save_config", lambda cfg: saved.update(cfg))
+
+    _save_custom_provider(
+        "http://localhost:11434/v1",
+        api_key="sk-secret",
+        name="Ollama",
+        key_env="HERMES_CUSTOM_LOCALHOST_11434_API_KEY",
+    )
+
+    entry = saved["custom_providers"][0]
+    assert entry["key_env"] == "HERMES_CUSTOM_LOCALHOST_11434_API_KEY"
+    assert "api_key" not in entry
+    assert "sk-secret" not in yaml.safe_dump(saved)
+
+
+def test_save_custom_provider_migrates_an_existing_plaintext_entry(monkeypatch, tmp_path):
+    """Re-saving a known URL swaps its inline key for the .env reference."""
+    import yaml
+    from hermes_cli.main import _save_custom_provider
+
+    existing = {
+        "custom_providers": [
+            {
+                "name": "Ollama",
+                "base_url": "http://localhost:11434/v1",
+                "api_key": "sk-legacy",
+            }
+        ]
+    }
+    monkeypatch.setattr("hermes_cli.config.load_config", lambda: existing)
+    saved = {}
+    monkeypatch.setattr("hermes_cli.config.save_config", lambda cfg: saved.update(cfg))
+
+    _save_custom_provider(
+        "http://localhost:11434/v1",
+        key_env="HERMES_CUSTOM_LOCALHOST_11434_API_KEY",
+    )
+
+    entry = saved["custom_providers"][0]
+    assert entry["key_env"] == "HERMES_CUSTOM_LOCALHOST_11434_API_KEY"
+    assert "api_key" not in entry
+
+
+def test_custom_endpoint_key_env_is_a_valid_posix_name_for_ip_endpoints():
+    """Every IP-based local endpoint slugs to a digit-leading name.
+
+    ``save_env_value`` rejects names that don't match
+    ``[A-Za-z_][A-Za-z0-9_]*``, so deriving ``127_0_0_1_8080_API_KEY`` would
+    raise on exactly the local-proxy setups this is meant to protect. The
+    fixed prefix makes the result valid by construction.
+    """
+    import re
+
+    from hermes_cli.config import _ENV_VAR_NAME_RE, custom_endpoint_key_env
+
+    for identity in ("127.0.0.1_8080", "0.0.0.0", "10.0.0.7:11434", "", "-–-"):
+        assert _ENV_VAR_NAME_RE.match(custom_endpoint_key_env(identity)), identity
+
+
+def test_custom_endpoint_key_env_separates_ports_on_one_host():
+    """Two servers on one machine must not collapse onto one .env slot."""
+    from hermes_cli.config import custom_endpoint_key_env
+
+    assert custom_endpoint_key_env("127.0.0.1_8000") != custom_endpoint_key_env("127.0.0.1_8001")
+    assert custom_endpoint_key_env("acme") == custom_endpoint_key_env("ACME")
diff --git a/tests/cli/test_cli_status_command.py b/tests/cli/test_cli_status_command.py
index ed6fbd7d2b3..6172c6a7319 100644
--- a/tests/cli/test_cli_status_command.py
+++ b/tests/cli/test_cli_status_command.py
@@ -32,6 +32,13 @@ def test_status_command_is_available_in_cli_registry():
     assert cmd.gateway_only is False
 
 
+def test_egress_command_is_available_in_cli_registry():
+    cmd = resolve_command("egress")
+    assert cmd is not None
+    assert cmd.gateway_only is False
+    assert "status" in cmd.subcommands
+
+
 def test_process_command_status_dispatches_without_toggling_status_bar():
     cli_obj = _make_cli()
 
@@ -42,6 +49,20 @@ def test_process_command_status_dispatches_without_toggling_status_bar():
     assert cli_obj._status_bar_visible is True
 
 
+def test_process_command_egress_prints_proxy_status(monkeypatch):
+    cli_obj = _make_cli()
+    monkeypatch.setattr(
+        "hermes_cli.proxy_cli.format_status_text",
+        lambda: "Egress proxy status\nEnabled: no",
+    )
+
+    assert cli_obj.process_command("/egress") is True
+
+    cli_obj.console.print.assert_called()
+    printed = "\n".join(str(call.args[0]) for call in cli_obj.console.print.call_args_list)
+    assert "Egress proxy status" in printed
+
+
 def test_statusbar_still_toggles_visibility():
     cli_obj = _make_cli()
 
diff --git a/tests/cli/test_moa_command.py b/tests/cli/test_moa_command.py
index c526a0f37af..4f3469bebd0 100644
--- a/tests/cli/test_moa_command.py
+++ b/tests/cli/test_moa_command.py
@@ -79,4 +79,56 @@ def test_decode_legacy_encoded_moa_turn_still_works():
     encoded = build_moa_turn_prompt("hello", _make_cli().config["moa"], preset="review")
     prompt, cfg = decode_moa_turn(encoded)
     assert prompt == "hello"
-    assert cfg["reference_models"] == [{"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}]
+    assert cfg["reference_models"] == [
+        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "enabled": True}
+    ]
+
+
+class TestNormalizeMoaModel:
+    """#56828: `-Q -m moa:<preset>` must route through the MoA virtual provider.
+
+    ``_normalize_moa_model`` maps the model string to (provider, preset); the
+    __init__ wiring then forces ``requested_provider="moa"`` so the existing
+    resolve_runtime_provider / agent_init MoA path runs in non-interactive mode.
+    """
+
+    def test_moa_prefix_maps_to_provider_and_preset(self):
+        from cli import _normalize_moa_model
+        assert _normalize_moa_model("moa:strategy") == ("moa", "strategy")
+
+    def test_moa_prefix_is_case_insensitive_and_trims(self):
+        from cli import _normalize_moa_model
+        assert _normalize_moa_model("  MOA:code-review ") == ("moa", "code-review")
+
+    def test_bare_moa_without_preset_is_not_treated_as_virtual(self):
+        from cli import _normalize_moa_model
+        # No preset after the colon → leave untouched (no provider override).
+        assert _normalize_moa_model("moa:") == (None, "moa:")
+
+    def test_non_moa_model_unchanged(self):
+        from cli import _normalize_moa_model
+        assert _normalize_moa_model("anthropic/claude-opus-4.8") == (None, "anthropic/claude-opus-4.8")
+
+    def test_none_model_unchanged(self):
+        from cli import _normalize_moa_model
+        assert _normalize_moa_model(None) == (None, None)
+
+    def test_colon_model_that_is_not_moa_unchanged(self):
+        from cli import _normalize_moa_model
+        # A provider:model form for a real provider must not be hijacked.
+        assert _normalize_moa_model("openrouter:deepseek/deepseek-v4") == (
+            None,
+            "openrouter:deepseek/deepseek-v4",
+        )
+
+    def test_override_wins_over_explicit_provider(self):
+        # __init__ resolves requested_provider as
+        # ``_moa_provider_override or provider or ...``, so a moa: prefix must
+        # take precedence over an explicit --provider (the #56828 deepseek case
+        # where MoA was silently ignored).
+        from cli import _normalize_moa_model
+        override, model = _normalize_moa_model("moa:strategy")
+        requested_provider = override or "deepseek" or "auto"
+        assert requested_provider == "moa"
+        assert model == "strategy"
+
diff --git a/tests/cli/test_worktree.py b/tests/cli/test_worktree.py
index 72811377213..03052bf8c58 100644
--- a/tests/cli/test_worktree.py
+++ b/tests/cli/test_worktree.py
@@ -1324,3 +1324,200 @@ class TestWidenedPruner:
         assert not any(
             "salvage-new-work" in rec.getMessage() for rec in caplog.records
         ), "under-7d preserved work should not warn"
+
+
+class TestMergeVerdictCache:
+    """The ``git cherry`` patch-equivalence probe is memoized on disk because it
+    dominates ``hermes -w`` startup (~0.2-1.0s per worktree, re-run on every
+    launch for every tree preserved as unpushed).
+
+    The invariant that makes caching safe: the verdict is a pure function of the
+    ``(base_sha, head_sha)`` range, so a cache entry is only reused while BOTH
+    endpoints are unchanged. These tests pin that relationship rather than any
+    specific timing or cache contents.
+    """
+
+    _age = staticmethod(TestWidenedPruner._age)
+    _mk = staticmethod(TestWidenedPruner._mk)
+    _merge_upstream = staticmethod(TestWidenedPruner._merge_upstream)
+
+    def test_cache_hit_matches_uncached_verdict(self, git_repo):
+        """A cached verdict must equal what the real git call returns."""
+        import cli
+        wt, sha = self._mk(git_repo, "hermes-cachehit", commit=True)
+        self._merge_upstream(git_repo, sha)
+
+        uncached = cli._worktree_commits_all_merged_upstream(str(wt))
+        cache = {}
+        cold = cli._worktree_commits_all_merged_upstream(str(wt), cache=cache)
+        warm = cli._worktree_commits_all_merged_upstream(str(wt), cache=cache)
+
+        assert cache, "verdict should have been memoized"
+        assert uncached is cold is warm is True
+
+    def test_cache_records_negative_verdicts_too(self, git_repo):
+        import cli
+        wt, _ = self._mk(git_repo, "hermes-cacheneg", commit=True)
+        cache = {}
+        assert cli._worktree_commits_all_merged_upstream(str(wt), cache=cache) is False
+        assert cli._worktree_commits_all_merged_upstream(str(wt), cache=cache) is False
+        assert set(cache.values()) == {False}
+
+    def test_new_commit_invalidates_cached_verdict(self, git_repo):
+        """Moving HEAD must not reuse the old entry — the key includes head_sha.
+
+        This is the guard against the cache turning a 'merged, reapable' verdict
+        into a stale approval to delete a tree that has since gained real work.
+        """
+        import cli
+        wt, sha = self._mk(git_repo, "hermes-moves", commit=True)
+        self._merge_upstream(git_repo, sha)
+
+        cache = {}
+        assert cli._worktree_commits_all_merged_upstream(str(wt), cache=cache) is True
+        key_after_merge = set(cache)
+
+        # New local-only work lands in the worktree.
+        (wt / "more.txt").write_text("unmerged work\n")
+        subprocess.run(["git", "add", "more.txt"], cwd=wt, capture_output=True)
+        subprocess.run(["git", "commit", "-m", "new work"], cwd=wt, capture_output=True)
+
+        assert cli._worktree_commits_all_merged_upstream(str(wt), cache=cache) is False
+        assert set(cache) != key_after_merge, "moved HEAD must produce a new key"
+
+    def test_cached_tree_with_new_work_is_still_preserved(self, git_repo):
+        """End-to-end: a warm cache must never let the pruner delete new work."""
+        import cli
+        wt, sha = self._mk(git_repo, "hermes-warmsafe", commit=True)
+        self._merge_upstream(git_repo, sha)
+
+        # Warm the on-disk cache with the 'fully merged' verdict.
+        cli._prune_stale_worktrees(str(git_repo))
+        assert not wt.exists(), "merged tree should be reaped on the cold pass"
+
+        # Recreate the same-named tree, now carrying unmerged work.
+        wt2, _ = self._mk(git_repo, "hermes-warmsafe", commit=True)
+        (wt2 / "precious.txt").write_text("do not delete\n")
+        subprocess.run(["git", "add", "precious.txt"], cwd=wt2, capture_output=True)
+        subprocess.run(["git", "commit", "-m", "precious"], cwd=wt2, capture_output=True)
+        self._age(wt2, 100)
+
+        cli._prune_stale_worktrees(str(git_repo))
+        assert wt2.exists(), "warm cache must not authorize deleting unmerged work"
+
+    def test_corrupt_cache_file_is_ignored(self, git_repo, monkeypatch, tmp_path):
+        """A garbage cache must degrade to recomputation, not crash startup."""
+        import json
+        import cli
+        bad = tmp_path / "worktree_merge_verdicts.json"
+        bad.write_text("{not json at all")
+        monkeypatch.setattr(cli, "_worktree_merge_cache_path", lambda: bad)
+        assert cli._load_worktree_merge_cache() == {}
+
+        # Non-bool verdicts must be dropped rather than fed into the decision.
+        bad.write_text(json.dumps({"version": 1, "verdicts": {"a..b:20": "yes"}}))
+        assert cli._load_worktree_merge_cache() == {}
+
+        wt, _ = self._mk(git_repo, "hermes-corrupt", commit=True)
+        cli._prune_stale_worktrees(str(git_repo))
+        assert wt.exists(), "unmerged work survives a corrupt cache"
+
+    def test_cache_is_bounded(self, monkeypatch, tmp_path):
+        """The cache file must not grow without limit across sessions."""
+        import cli
+        path = tmp_path / "verdicts.json"
+        monkeypatch.setattr(cli, "_worktree_merge_cache_path", lambda: path)
+        monkeypatch.setattr(cli, "_WORKTREE_MERGE_CACHE_MAX", 10)
+
+        cli._save_worktree_merge_cache({f"sha{i}..sha{i}:20": True for i in range(50)})
+        assert len(cli._load_worktree_merge_cache()) == 10
+
+
+class TestPruneParallelEquivalence:
+    """Classification runs on a thread pool, so verdicts must not depend on
+    concurrency: the same mixed board must produce the same survivors whether
+    the pool has 1 worker or many."""
+
+    _age = staticmethod(TestWidenedPruner._age)
+    _mk = staticmethod(TestWidenedPruner._mk)
+    _merge_upstream = staticmethod(TestWidenedPruner._merge_upstream)
+
+    def _board(self, git_repo, tag=""):
+        """A board covering every verdict branch: reapable, dirty, unpushed."""
+        names = {}
+        for i in range(3):
+            n = f"hermes-merged{tag}{i}"
+            wt, sha = self._mk(git_repo, n, commit=True)
+            self._merge_upstream(git_repo, sha)
+            names[n] = wt
+        for i in range(3):
+            n = f"hermes-unpushed{tag}{i}"
+            wt, _ = self._mk(git_repo, n, commit=True)
+            names[n] = wt
+        for i in range(2):
+            n = f"hermes-dirty{tag}{i}"
+            wt, _ = self._mk(git_repo, n, dirty=True)
+            names[n] = wt
+        n = f"hermes-fresh{tag}"
+        wt, _ = self._mk(git_repo, n, commit=True, age_h=1)
+        names[n] = wt
+        # Every tree must really exist, otherwise the survivor comparison below
+        # is vacuous (a failed `git worktree add` would look like a reap).
+        for name, p in names.items():
+            assert p.exists(), f"fixture worktree {name} was not created"
+        return names
+
+    @staticmethod
+    def _kinds(survivors):
+        """Reduce survivor names to their kind, dropping the phase tag."""
+        out = set()
+        for n in survivors:
+            for kind in ("merged", "unpushed", "dirty", "fresh"):
+                if n.startswith(f"hermes-{kind}"):
+                    out.add(kind)
+        return out
+
+    def test_single_and_multi_worker_agree(self, git_repo, monkeypatch):
+        import cli
+
+        # Phase A — force the serial path (pool sized to 1 worker).
+        board = self._board(git_repo, tag="a")
+        monkeypatch.setattr(cli.os, "cpu_count", lambda: 1)
+        cli._prune_stale_worktrees(str(git_repo))
+        serial = self._kinds({n for n, p in board.items() if p.exists()})
+
+        # Phase B — an independent board (distinct branch names so creation
+        # can't collide with phase A's leftover refs) run through a real pool.
+        try:
+            cli._worktree_merge_cache_path().unlink()
+        except Exception:
+            pass
+        board2 = self._board(git_repo, tag="b")
+        monkeypatch.setattr(cli.os, "cpu_count", lambda: 8)
+        cli._prune_stale_worktrees(str(git_repo))
+        parallel = self._kinds({n for n, p in board2.items() if p.exists()})
+
+        assert parallel == serial, (
+            f"pool width changed the outcome: serial={serial} parallel={parallel}"
+        )
+        # Sanity: the board exercised both outcomes, so the equality above is
+        # not comparing two empty (or two identical-because-nothing-ran) sets.
+        assert serial == {"dirty", "unpushed", "fresh"}, serial
+
+    def test_pool_failure_falls_back_to_serial(self, git_repo, monkeypatch):
+        """A ThreadPoolExecutor failure must not block startup."""
+        import cli
+
+        wt, sha = self._mk(git_repo, "hermes-poolfail", commit=True)
+        self._merge_upstream(git_repo, sha)
+
+        class _Boom:
+            def __init__(self, *a, **kw):
+                raise RuntimeError("cannot start thread")
+
+        monkeypatch.setattr(cli.concurrent.futures, "ThreadPoolExecutor", _Boom)
+        monkeypatch.setattr(cli.os, "cpu_count", lambda: 8)
+
+        cli._prune_stale_worktrees(str(git_repo))
+        assert not wt.exists(), "serial fallback must still reap the merged tree"
+
diff --git a/tests/cli/test_worktree_security.py b/tests/cli/test_worktree_security.py
index 73a242e0fda..bf2c2fa01b5 100644
--- a/tests/cli/test_worktree_security.py
+++ b/tests/cli/test_worktree_security.py
@@ -128,3 +128,64 @@ class TestWorktreeIncludeSecurity:
             assert (linked_dir / "lib" / "marker.txt").read_text() == "venv marker"
         finally:
             _force_remove_worktree(info)
+
+
+class TestWorktreeIncludeEncoding:
+    """The include list and .gitignore are UTF-8 files; reading them with the
+    locale default breaks Windows (cp1251/GBK mojibake or UnicodeDecodeError,
+    swallowed at DEBUG so no include is copied), and a Notepad BOM glues to
+    the first line on every platform."""
+
+    def test_bom_in_worktreeinclude_does_not_hide_first_entry(self, git_repo):
+        import cli as cli_mod
+
+        (git_repo / ".env").write_text("SECRET=***\n")
+        # Notepad-style UTF-8 with BOM; the BOM must not become part of the
+        # first entry's path.
+        (git_repo / ".worktreeinclude").write_bytes(".env\n".encode("utf-8"))
+
+        info = None
+        try:
+            info = cli_mod._setup_worktree(str(git_repo))
+            assert info is not None
+            assert (Path(info["path"]) / ".env").exists()
+        finally:
+            _force_remove_worktree(info)
+
+    def test_non_ascii_worktreeinclude_entry_copied(self, git_repo):
+        import cli as cli_mod
+
+        secret = git_repo / "секреты.env"
+        secret.write_text("SECRET=***\n", encoding="utf-8")
+        (git_repo / ".worktreeinclude").write_bytes(
+            "# ключи агента\nсекреты.env\n".encode("utf-8")
+        )
+
+        info = None
+        try:
+            info = cli_mod._setup_worktree(str(git_repo))
+            assert info is not None
+            assert (Path(info["path"]) / "секреты.env").exists()
+        finally:
+            _force_remove_worktree(info)
+
+    def test_bom_in_gitignore_does_not_duplicate_worktrees_entry(self, git_repo):
+        import cli as cli_mod
+
+        (git_repo / ".gitignore").write_bytes(".worktrees/\n".encode("utf-8"))
+
+        info = None
+        try:
+            info = cli_mod._setup_worktree(str(git_repo))
+            assert info is not None
+            lines = (
+                (git_repo / ".gitignore")
+                .read_text(encoding="utf-8-sig")
+                .splitlines()
+            )
+            assert lines.count(".worktrees/") == 1, (
+                "BOM glued to the first line must not defeat the membership "
+                f"check and duplicate the entry: {lines!r}"
+            )
+        finally:
+            _force_remove_worktree(info)
diff --git a/tests/computer_use/test_cua_atexit_teardown.py b/tests/computer_use/test_cua_atexit_teardown.py
new file mode 100644
index 00000000000..ff02d94fc5a
--- /dev/null
+++ b/tests/computer_use/test_cua_atexit_teardown.py
@@ -0,0 +1,75 @@
+"""Tests for cua-driver subprocess teardown on interpreter exit.
+
+``CuaDriverBackend`` spawns a long-lived ``cua-driver`` child process and
+caches it for the life of the Hermes process. Nothing ever tore it down, so
+the driver outlived the session that started it (#28152 item 3 — "Hermes does
+not keep the driver alive after tool completion"). #69903 fixed the *overlay*
+redraw loop that made the lingering process burn CPU, but not the lingering
+process itself.
+
+``tools/computer_use/tool.py`` registers an ``atexit`` hook that stops the
+cached backend, mirroring ``browser_tool``'s
+``atexit.register(_emergency_cleanup_all_sessions)``.
+
+These assert the behavior contract — the hook is registered, it stops a live
+backend, it is a no-op when nothing was ever started, and it never raises out
+of ``atexit`` — not a snapshot of the module's source.
+"""
+
+import atexit
+from unittest.mock import MagicMock, patch
+
+from tools.computer_use import tool as cu_tool
+
+
+class TestAtexitTeardown:
+    def test_shutdown_stops_a_live_backend(self):
+        """A cached backend is stopped when the interpreter exits."""
+        fake = MagicMock()
+        with patch.object(cu_tool, "_backend", fake):
+            cu_tool._shutdown_backend_atexit()
+            fake.stop.assert_called_once()
+
+    def test_shutdown_clears_the_cached_backend(self):
+        """After teardown the module cache is empty, so a later call re-spawns."""
+        fake = MagicMock()
+        with patch.object(cu_tool, "_backend", fake):
+            cu_tool._shutdown_backend_atexit()
+            assert cu_tool._backend is None
+
+    def test_shutdown_is_a_noop_when_never_started(self):
+        """No backend was ever created => nothing to stop, no error."""
+        with patch.object(cu_tool, "_backend", None):
+            cu_tool._shutdown_backend_atexit()  # must not raise
+            assert cu_tool._backend is None
+
+    def test_shutdown_swallows_backend_errors(self):
+        """A failing stop() must not raise out of an atexit hook.
+
+        Exceptions escaping atexit print a traceback on every exit and can
+        mask the real exit status.
+        """
+        fake = MagicMock()
+        fake.stop.side_effect = RuntimeError("driver already dead")
+        with patch.object(cu_tool, "_backend", fake):
+            cu_tool._shutdown_backend_atexit()  # must not raise
+            assert cu_tool._backend is None
+
+    def test_hook_is_registered_with_atexit(self):
+        """Importing the tool module registers the teardown hook.
+
+        Verified by unregistering and re-registering: atexit.unregister only
+        removes a function that was actually registered, so a successful
+        round-trip proves the import-time registration happened.
+        """
+        atexit.unregister(cu_tool._shutdown_backend_atexit)
+        try:
+            with patch.object(cu_tool, "_backend", MagicMock()) as fake:
+                # Re-register and fire the full atexit chain the way the
+                # interpreter would, then confirm our hook ran.
+                atexit.register(cu_tool._shutdown_backend_atexit)
+                atexit._run_exitfuncs()
+                fake.stop.assert_called_once()
+        finally:
+            atexit.unregister(cu_tool._shutdown_backend_atexit)
+            atexit.register(cu_tool._shutdown_backend_atexit)
diff --git a/tests/conformance/__init__.py b/tests/conformance/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/conformance/test_vector_generator.py b/tests/conformance/test_vector_generator.py
new file mode 100644
index 00000000000..9522353e57a
--- /dev/null
+++ b/tests/conformance/test_vector_generator.py
@@ -0,0 +1,129 @@
+"""Conformance vector generator tests (Phase 5 oracle workstream).
+
+Behavior contracts, not change-detectors: determinism, corpus invariants,
+oracle-import health (the generator calls format_message UNBOUND — these
+tests fail loudly if a refactor gives those renderers instance state), and
+vector-file shape. Native outputs themselves are NOT snapshotted here — the
+connector's conformance runner is the consumer that asserts them.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from generate_conformance_vectors import (  # noqa: E402
+    ADVERSARIAL,
+    GRID,
+    SCAR,
+    _oracles,
+    corpus,
+    generate,
+)
+
+PLATFORMS = ("discord", "slack", "telegram", "whatsapp")
+
+
+def test_corpus_ids_unique_and_categorized():
+    rows = corpus()
+    ids = [r["id"] for r in rows]
+    assert len(ids) == len(set(ids)), "vector ids must be unique (runner keys on them)"
+    assert {r["category"] for r in rows} == {"grid", "scar", "adversarial"}
+    assert len(GRID) >= 20 and len(SCAR) >= 10 and len(ADVERSARIAL) >= 8
+
+
+def test_oracles_importable_and_self_free():
+    """The generator invokes format_message unbound (self=None) — verify every
+    oracle actually renders under that calling convention. A refactor that
+    adds instance state to a renderer must update the generator too."""
+    oracles = _oracles()
+    assert set(oracles) == set(PLATFORMS)
+    for platform, render in oracles.items():
+        out = render("**bold** and `code`")
+        assert isinstance(out, str) and out, platform
+
+
+def test_generation_is_deterministic(tmp_path):
+    a, b = tmp_path / "a", tmp_path / "b"
+    generate(a)
+    generate(b)
+    for platform in PLATFORMS:
+        va = (a / f"{platform}.json").read_text(encoding="utf-8")
+        vb = (b / f"{platform}.json").read_text(encoding="utf-8")
+        # The oracle commit is identical within one checkout; whole file must be.
+        assert va == vb, f"{platform} vectors are nondeterministic"
+
+
+def test_vector_files_shape(tmp_path):
+    generate(tmp_path)
+    for platform in PLATFORMS:
+        doc = json.loads((tmp_path / f"{platform}.json").read_text(encoding="utf-8"))
+        assert doc["platform"] == platform
+        assert doc["oracle"]["repo"] == "NousResearch/hermes-agent"
+        assert re.match(r"^[0-9a-f]{40}$|^unknown$", doc["oracle"]["commit"])
+        assert doc["oracle"]["generator_version"] >= 1
+        ids = set()
+        for v in doc["vectors"]:
+            assert v["expect"] in ("parity", "semantic", "divergent"), v["id"]
+            assert isinstance(v["native_output"], str)
+            if v["expect"] == "divergent":
+                assert v.get("note"), f"{platform}/{v['id']}: divergent needs a note"
+            ids.add(v["id"])
+        assert len(ids) == len(doc["vectors"])
+
+
+def test_default_expectations_per_platform(tmp_path):
+    """Telegram defaults to semantic (connector speaks HTML, native speaks
+    MarkdownV2); every other platform defaults to parity (same dialect)."""
+    generate(tmp_path)
+    tg = json.loads((tmp_path / "telegram.json").read_text(encoding="utf-8"))
+    assert all(v["expect"] != "parity" for v in tg["vectors"]), (
+        "telegram byte-parity is impossible across dialects — semantic/divergent only"
+    )
+    for platform in ("slack", "whatsapp"):
+        doc = json.loads((tmp_path / f"{platform}.json").read_text(encoding="utf-8"))
+        parity = [v for v in doc["vectors"] if v["expect"] == "parity"]
+        assert len(parity) > len(doc["vectors"]) * 0.7, f"{platform} should be mostly parity"
+
+
+def test_scar_vectors_exercise_the_named_bugs(tmp_path):
+    """The scar corpus must actually trigger the behaviors it memorializes."""
+    generate(tmp_path)
+    tg = {v["id"]: v for v in json.loads((tmp_path / "telegram.json").read_text(encoding="utf-8"))["vectors"]}
+    # MarkdownV2 reserved chars actually get escaped by the oracle.
+    assert "\\." in tg["mdv2-reserved-chars"]["native_output"] or "\\(" in tg["mdv2-reserved-chars"]["native_output"]
+    assert "\\_" in tg["mdv2-underscores"]["native_output"]
+    sl = {v["id"]: v for v in json.loads((tmp_path / "slack.json").read_text(encoding="utf-8"))["vectors"]}
+    assert sl["slack-bold-conversion"]["native_output"] == "*important* word"
+    assert sl["slack-link-conversion"]["native_output"] == "<https://example.com|click here>"
+    assert "&lt;!everyone&gt;" in sl["slack-broadcast-mention"]["native_output"]
+    wa = {v["id"]: v for v in json.loads((tmp_path / "whatsapp.json").read_text(encoding="utf-8"))["vectors"]}
+    assert wa["bold"]["native_output"] == "This is *bold* text."
+
+
+def test_committed_vectors_match_regeneration(tmp_path):
+    """The committed tests/conformance/vectors/ must reproduce from the
+    current oracle — the same lockstep discipline as openapi.json (drift
+    means someone changed a renderer without regenerating)."""
+    committed_dir = REPO_ROOT / "tests" / "conformance" / "vectors"
+    if not committed_dir.exists():
+        pytest.skip("no committed vectors in this checkout")
+    generate(tmp_path)
+    for platform in PLATFORMS:
+        fresh = json.loads((tmp_path / f"{platform}.json").read_text(encoding="utf-8"))
+        committed = json.loads((committed_dir / f"{platform}.json").read_text(encoding="utf-8"))
+        # Compare everything except the commit stamp (committed file may be
+        # one commit behind HEAD in a dirty working tree).
+        fresh["oracle"].pop("commit")
+        committed["oracle"].pop("commit")
+        assert fresh == committed, (
+            f"{platform} vectors drifted — run "
+            "`python scripts/generate_conformance_vectors.py` and commit"
+        )
diff --git a/tests/conformance/vectors/discord.json b/tests/conformance/vectors/discord.json
new file mode 100644
index 00000000000..f830ba32ea1
--- /dev/null
+++ b/tests/conformance/vectors/discord.json
@@ -0,0 +1,322 @@
+{
+  "$comment": "GENERATED — do not hand-edit. Regenerate with hermes-agent scripts/generate_conformance_vectors.py; the native renderers are the oracle (executable spec).",
+  "oracle": {
+    "repo": "NousResearch/hermes-agent",
+    "commit": "40eebc7d70f3d8e95c429c8aa482f31ba6c867f6",
+    "generator": "scripts/generate_conformance_vectors.py",
+    "generator_version": 1
+  },
+  "platform": "discord",
+  "vectors": [
+    {
+      "id": "plain-text",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Just a plain sentence.",
+      "native_output": "Just a plain sentence."
+    },
+    {
+      "id": "bold",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is **bold** text.",
+      "native_output": "This is **bold** text."
+    },
+    {
+      "id": "italic",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is *italic* text.",
+      "native_output": "This is *italic* text."
+    },
+    {
+      "id": "bold-italic",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Mix of **bold** and *italic* in one line.",
+      "native_output": "Mix of **bold** and *italic* in one line."
+    },
+    {
+      "id": "strikethrough",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is ~~struck~~ text.",
+      "native_output": "This is ~~struck~~ text."
+    },
+    {
+      "id": "inline-code",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Run `pip install hermes` to start.",
+      "native_output": "Run `pip install hermes` to start."
+    },
+    {
+      "id": "fenced-code",
+      "category": "grid",
+      "expect": "parity",
+      "input": "```\nprint('hello')\n```",
+      "native_output": "```\nprint('hello')\n```"
+    },
+    {
+      "id": "fenced-code-lang",
+      "category": "grid",
+      "expect": "parity",
+      "input": "```python\ndef f(x):\n    return x * 2\n```",
+      "native_output": "```python\ndef f(x):\n    return x * 2\n```"
+    },
+    {
+      "id": "link",
+      "category": "grid",
+      "expect": "parity",
+      "input": "See [the docs](https://example.com/docs) for more.",
+      "native_output": "See [the docs](https://example.com/docs) for more."
+    },
+    {
+      "id": "link-parens-url",
+      "category": "grid",
+      "expect": "parity",
+      "input": "See [spec](https://example.com/a_(b)) here.",
+      "native_output": "See [spec](https://example.com/a_(b)) here."
+    },
+    {
+      "id": "header-h1",
+      "category": "grid",
+      "expect": "parity",
+      "input": "# Big Title\nBody follows.",
+      "native_output": "# Big Title\nBody follows."
+    },
+    {
+      "id": "header-h2",
+      "category": "grid",
+      "expect": "parity",
+      "input": "## Section\nBody follows.",
+      "native_output": "## Section\nBody follows."
+    },
+    {
+      "id": "header-h3",
+      "category": "grid",
+      "expect": "parity",
+      "input": "### Sub-section\nBody follows.",
+      "native_output": "### Sub-section\nBody follows."
+    },
+    {
+      "id": "ul-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "- first\n- second\n- third",
+      "native_output": "- first\n- second\n- third"
+    },
+    {
+      "id": "ol-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "1. first\n2. second\n3. third",
+      "native_output": "1. first\n2. second\n3. third"
+    },
+    {
+      "id": "nested-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "- outer\n  - inner one\n  - inner two\n- outer two",
+      "native_output": "- outer\n  - inner one\n  - inner two\n- outer two"
+    },
+    {
+      "id": "blockquote",
+      "category": "grid",
+      "expect": "parity",
+      "input": "> quoted wisdom\nregular line",
+      "native_output": "> quoted wisdom\nregular line"
+    },
+    {
+      "id": "hrule",
+      "category": "grid",
+      "expect": "parity",
+      "input": "above\n\n---\n\nbelow",
+      "native_output": "above\n\n---\n\nbelow"
+    },
+    {
+      "id": "table-simple",
+      "category": "grid",
+      "expect": "divergent",
+      "input": "| name | value |\n|------|-------|\n| a    | 1     |\n| b    | 2     |",
+      "native_output": "**a**\n• value: 1\n\n**b**\n• value: 2",
+      "note": "native converts GFM tables to bullet groups; connector passes raw markdown through (port deferred — parity report Phase 4/oracle section)"
+    },
+    {
+      "id": "emoji",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Done ✅ with 🎉 emoji 👀 test.",
+      "native_output": "Done ✅ with 🎉 emoji 👀 test."
+    },
+    {
+      "id": "cjk",
+      "category": "grid",
+      "expect": "parity",
+      "input": "中文测试：**粗体** 和 `代码` 混排。",
+      "native_output": "中文测试：**粗体** 和 `代码` 混排。"
+    },
+    {
+      "id": "bare-url",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Visit https://example.com/path?q=1&r=2 today.",
+      "native_output": "Visit https://example.com/path?q=1&r=2 today."
+    },
+    {
+      "id": "mixed-document",
+      "category": "grid",
+      "expect": "parity",
+      "input": "## Report\n\nStatus: **green**. Details in `runbook.md`.\n\n- item *one*\n- item **two**\n\n```sh\nmake deploy\n```\n\nSee [dashboard](https://grafana.example.com/d/x).",
+      "native_output": "## Report\n\nStatus: **green**. Details in `runbook.md`.\n\n- item *one*\n- item **two**\n\n```sh\nmake deploy\n```\n\nSee [dashboard](https://grafana.example.com/d/x)."
+    },
+    {
+      "id": "mdv2-reserved-chars",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Price is 3.50 (was 4.00) — save ~12%! #deal +tax = win.",
+      "native_output": "Price is 3.50 (was 4.00) — save ~12%! #deal +tax = win."
+    },
+    {
+      "id": "mdv2-underscores",
+      "category": "scar",
+      "expect": "parity",
+      "input": "snake_case_name and file_name.py in prose.",
+      "native_output": "snake_case_name and file_name.py in prose."
+    },
+    {
+      "id": "mdv2-brackets",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Array[0] and dict{key} and (parens) live here.",
+      "native_output": "Array[0] and dict{key} and (parens) live here."
+    },
+    {
+      "id": "slack-bold-conversion",
+      "category": "scar",
+      "expect": "parity",
+      "input": "**important** word",
+      "native_output": "**important** word"
+    },
+    {
+      "id": "slack-link-conversion",
+      "category": "scar",
+      "expect": "parity",
+      "input": "[click here](https://example.com)",
+      "native_output": "[click here](https://example.com)"
+    },
+    {
+      "id": "slack-broadcast-mention",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Hey <!everyone> and <!channel> and <!here>!",
+      "native_output": "Hey <!everyone> and <!channel> and <!here>!"
+    },
+    {
+      "id": "fence-lang-tag-slack",
+      "category": "scar",
+      "expect": "parity",
+      "input": "```text\nliteral first line issue\n```",
+      "native_output": "```text\nliteral first line issue\n```"
+    },
+    {
+      "id": "backslash-in-code",
+      "category": "scar",
+      "expect": "parity",
+      "input": "`C:\\Users\\ben\\file.txt` and ```\npath = \"a\\\\b\"\n```",
+      "native_output": "`C:\\Users\\ben\\file.txt` and ```\npath = \"a\\\\b\"\n```"
+    },
+    {
+      "id": "backtick-in-fence",
+      "category": "scar",
+      "expect": "parity",
+      "input": "```\nuse `inline` inside fence\n```",
+      "native_output": "```\nuse `inline` inside fence\n```"
+    },
+    {
+      "id": "header-with-bold",
+      "category": "scar",
+      "expect": "parity",
+      "input": "## The **Real** Deal",
+      "native_output": "## The **Real** Deal"
+    },
+    {
+      "id": "table-cjk",
+      "category": "scar",
+      "expect": "divergent",
+      "input": "| 名前 | 値 |\n|------|----|\n| 中文 | 42 |\n| b    | 2  |",
+      "native_output": "**中文**\n• 値: 42\n\n**b**\n• 値: 2",
+      "note": "same as table-simple"
+    },
+    {
+      "id": "link-display-escapes",
+      "category": "scar",
+      "expect": "parity",
+      "input": "[v2.0 (beta)](https://example.com/v2)",
+      "native_output": "[v2.0 (beta)](https://example.com/v2)"
+    },
+    {
+      "id": "media-tag",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "Here you go\nMEDIA:/tmp/output.png\ndone",
+      "native_output": "Here you go\nMEDIA:/tmp/output.png\ndone"
+    },
+    {
+      "id": "unclosed-fence",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "```python\nprint('never closed')",
+      "native_output": "```python\nprint('never closed')"
+    },
+    {
+      "id": "pathological-nesting",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "**bold *italic ~~struck `code` struck~~ italic* bold**",
+      "native_output": "**bold *italic ~~struck `code` struck~~ italic* bold**"
+    },
+    {
+      "id": "placeholder-injection",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "sneaky \u0000PH0\u0000 token and \u0000SL1\u0000 too",
+      "native_output": "sneaky \u0000PH0\u0000 token and \u0000SL1\u0000 too"
+    },
+    {
+      "id": "triple-markers",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "***what is this*** and ____that____",
+      "native_output": "***what is this*** and ____that____"
+    },
+    {
+      "id": "empty-string",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "",
+      "native_output": ""
+    },
+    {
+      "id": "whitespace-only",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "   \n\t\n   ",
+      "native_output": "   \n\t\n   "
+    },
+    {
+      "id": "long-line",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word ",
+      "native_output": "word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word "
+    },
+    {
+      "id": "many-fences",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail",
+      "native_output": "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail"
+    }
+  ]
+}
diff --git a/tests/conformance/vectors/slack.json b/tests/conformance/vectors/slack.json
new file mode 100644
index 00000000000..b83e60c8d26
--- /dev/null
+++ b/tests/conformance/vectors/slack.json
@@ -0,0 +1,322 @@
+{
+  "$comment": "GENERATED — do not hand-edit. Regenerate with hermes-agent scripts/generate_conformance_vectors.py; the native renderers are the oracle (executable spec).",
+  "oracle": {
+    "repo": "NousResearch/hermes-agent",
+    "commit": "40eebc7d70f3d8e95c429c8aa482f31ba6c867f6",
+    "generator": "scripts/generate_conformance_vectors.py",
+    "generator_version": 1
+  },
+  "platform": "slack",
+  "vectors": [
+    {
+      "id": "plain-text",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Just a plain sentence.",
+      "native_output": "Just a plain sentence."
+    },
+    {
+      "id": "bold",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is **bold** text.",
+      "native_output": "This is *bold* text."
+    },
+    {
+      "id": "italic",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is *italic* text.",
+      "native_output": "This is _italic_ text."
+    },
+    {
+      "id": "bold-italic",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Mix of **bold** and *italic* in one line.",
+      "native_output": "Mix of *bold* and _italic_ in one line."
+    },
+    {
+      "id": "strikethrough",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is ~~struck~~ text.",
+      "native_output": "This is ~struck~ text."
+    },
+    {
+      "id": "inline-code",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Run `pip install hermes` to start.",
+      "native_output": "Run `pip install hermes` to start."
+    },
+    {
+      "id": "fenced-code",
+      "category": "grid",
+      "expect": "parity",
+      "input": "```\nprint('hello')\n```",
+      "native_output": "```\nprint('hello')\n```"
+    },
+    {
+      "id": "fenced-code-lang",
+      "category": "grid",
+      "expect": "parity",
+      "input": "```python\ndef f(x):\n    return x * 2\n```",
+      "native_output": "```\ndef f(x):\n    return x * 2\n```"
+    },
+    {
+      "id": "link",
+      "category": "grid",
+      "expect": "parity",
+      "input": "See [the docs](https://example.com/docs) for more.",
+      "native_output": "See <https://example.com/docs|the docs> for more."
+    },
+    {
+      "id": "link-parens-url",
+      "category": "grid",
+      "expect": "parity",
+      "input": "See [spec](https://example.com/a_(b)) here.",
+      "native_output": "See <https://example.com/a_(b)|spec> here."
+    },
+    {
+      "id": "header-h1",
+      "category": "grid",
+      "expect": "parity",
+      "input": "# Big Title\nBody follows.",
+      "native_output": "*Big Title*\nBody follows."
+    },
+    {
+      "id": "header-h2",
+      "category": "grid",
+      "expect": "parity",
+      "input": "## Section\nBody follows.",
+      "native_output": "*Section*\nBody follows."
+    },
+    {
+      "id": "header-h3",
+      "category": "grid",
+      "expect": "parity",
+      "input": "### Sub-section\nBody follows.",
+      "native_output": "*Sub-section*\nBody follows."
+    },
+    {
+      "id": "ul-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "- first\n- second\n- third",
+      "native_output": "- first\n- second\n- third"
+    },
+    {
+      "id": "ol-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "1. first\n2. second\n3. third",
+      "native_output": "1. first\n2. second\n3. third"
+    },
+    {
+      "id": "nested-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "- outer\n  - inner one\n  - inner two\n- outer two",
+      "native_output": "- outer\n  - inner one\n  - inner two\n- outer two"
+    },
+    {
+      "id": "blockquote",
+      "category": "grid",
+      "expect": "parity",
+      "input": "> quoted wisdom\nregular line",
+      "native_output": "> quoted wisdom\nregular line"
+    },
+    {
+      "id": "hrule",
+      "category": "grid",
+      "expect": "parity",
+      "input": "above\n\n---\n\nbelow",
+      "native_output": "above\n\n---\n\nbelow"
+    },
+    {
+      "id": "table-simple",
+      "category": "grid",
+      "expect": "parity",
+      "input": "| name | value |\n|------|-------|\n| a    | 1     |\n| b    | 2     |",
+      "native_output": "```\n| name | value |\n| ---- | ----- |\n| a    | 1     |\n| b    | 2     |\n```"
+    },
+    {
+      "id": "emoji",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Done ✅ with 🎉 emoji 👀 test.",
+      "native_output": "Done ✅ with 🎉 emoji 👀 test."
+    },
+    {
+      "id": "cjk",
+      "category": "grid",
+      "expect": "parity",
+      "input": "中文测试：**粗体** 和 `代码` 混排。",
+      "native_output": "中文测试：*粗体* 和 `代码` 混排。"
+    },
+    {
+      "id": "bare-url",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Visit https://example.com/path?q=1&r=2 today.",
+      "native_output": "Visit https://example.com/path?q=1&amp;r=2 today."
+    },
+    {
+      "id": "mixed-document",
+      "category": "grid",
+      "expect": "parity",
+      "input": "## Report\n\nStatus: **green**. Details in `runbook.md`.\n\n- item *one*\n- item **two**\n\n```sh\nmake deploy\n```\n\nSee [dashboard](https://grafana.example.com/d/x).",
+      "native_output": "*Report*\n\nStatus: *green*. Details in `runbook.md`.\n\n- item _one_\n- item *two*\n\n```\nmake deploy\n```\n\nSee <https://grafana.example.com/d/x|dashboard>."
+    },
+    {
+      "id": "mdv2-reserved-chars",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Price is 3.50 (was 4.00) — save ~12%! #deal +tax = win.",
+      "native_output": "Price is 3.50 (was 4.00) — save ~12%! #deal +tax = win."
+    },
+    {
+      "id": "mdv2-underscores",
+      "category": "scar",
+      "expect": "parity",
+      "input": "snake_case_name and file_name.py in prose.",
+      "native_output": "snake_case_name and file_name.py in prose."
+    },
+    {
+      "id": "mdv2-brackets",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Array[0] and dict{key} and (parens) live here.",
+      "native_output": "Array[0] and dict{key} and (parens) live here."
+    },
+    {
+      "id": "slack-bold-conversion",
+      "category": "scar",
+      "expect": "parity",
+      "input": "**important** word",
+      "native_output": "*important* word"
+    },
+    {
+      "id": "slack-link-conversion",
+      "category": "scar",
+      "expect": "parity",
+      "input": "[click here](https://example.com)",
+      "native_output": "<https://example.com|click here>"
+    },
+    {
+      "id": "slack-broadcast-mention",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Hey <!everyone> and <!channel> and <!here>!",
+      "native_output": "Hey &lt;!everyone&gt; and &lt;!channel&gt; and &lt;!here&gt;!"
+    },
+    {
+      "id": "fence-lang-tag-slack",
+      "category": "scar",
+      "expect": "parity",
+      "input": "```text\nliteral first line issue\n```",
+      "native_output": "```\nliteral first line issue\n```"
+    },
+    {
+      "id": "backslash-in-code",
+      "category": "scar",
+      "expect": "parity",
+      "input": "`C:\\Users\\ben\\file.txt` and ```\npath = \"a\\\\b\"\n```",
+      "native_output": "`C:\\Users\\ben\\file.txt` and ```\npath = \"a\\\\b\"\n```"
+    },
+    {
+      "id": "backtick-in-fence",
+      "category": "scar",
+      "expect": "parity",
+      "input": "```\nuse `inline` inside fence\n```",
+      "native_output": "```\nuse `inline` inside fence\n```"
+    },
+    {
+      "id": "header-with-bold",
+      "category": "scar",
+      "expect": "parity",
+      "input": "## The **Real** Deal",
+      "native_output": "*The Real Deal*"
+    },
+    {
+      "id": "table-cjk",
+      "category": "scar",
+      "expect": "parity",
+      "input": "| 名前 | 値 |\n|------|----|\n| 中文 | 42 |\n| b    | 2  |",
+      "native_output": "```\n| 名前 | 値  |\n| ---- | --- |\n| 中文 | 42  |\n| b    | 2   |\n```"
+    },
+    {
+      "id": "link-display-escapes",
+      "category": "scar",
+      "expect": "parity",
+      "input": "[v2.0 (beta)](https://example.com/v2)",
+      "native_output": "<https://example.com/v2|v2.0 (beta)>"
+    },
+    {
+      "id": "media-tag",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "Here you go\nMEDIA:/tmp/output.png\ndone",
+      "native_output": "Here you go\nMEDIA:/tmp/output.png\ndone"
+    },
+    {
+      "id": "unclosed-fence",
+      "category": "adversarial",
+      "expect": "divergent",
+      "input": "```python\nprint('never closed')",
+      "native_output": "```python\nprint('never closed')",
+      "note": "unterminated fence handling differs; both degrade without dropping content"
+    },
+    {
+      "id": "pathological-nesting",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "**bold *italic ~~struck `code` struck~~ italic* bold**",
+      "native_output": "*bold *italic ~~struck `code` struck~~ italic* bold*"
+    },
+    {
+      "id": "placeholder-injection",
+      "category": "adversarial",
+      "expect": "divergent",
+      "input": "sneaky \u0000PH0\u0000 token and \u0000SL1\u0000 too",
+      "native_output": "sneaky \u0000PH0\u0000 token and \u0000SL1\u0000 too",
+      "note": "\\x00SL tokens are the native renderer's own placeholder alphabet; connector uses a different scheme"
+    },
+    {
+      "id": "triple-markers",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "***what is this*** and ____that____",
+      "native_output": "*_what is this_* and ____that____"
+    },
+    {
+      "id": "empty-string",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "",
+      "native_output": ""
+    },
+    {
+      "id": "whitespace-only",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "   \n\t\n   ",
+      "native_output": "   \n\t\n   "
+    },
+    {
+      "id": "long-line",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word ",
+      "native_output": "word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word "
+    },
+    {
+      "id": "many-fences",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail",
+      "native_output": "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail"
+    }
+  ]
+}
diff --git a/tests/conformance/vectors/telegram.json b/tests/conformance/vectors/telegram.json
new file mode 100644
index 00000000000..679741773db
--- /dev/null
+++ b/tests/conformance/vectors/telegram.json
@@ -0,0 +1,325 @@
+{
+  "$comment": "GENERATED — do not hand-edit. Regenerate with hermes-agent scripts/generate_conformance_vectors.py; the native renderers are the oracle (executable spec).",
+  "oracle": {
+    "repo": "NousResearch/hermes-agent",
+    "commit": "40eebc7d70f3d8e95c429c8aa482f31ba6c867f6",
+    "generator": "scripts/generate_conformance_vectors.py",
+    "generator_version": 1
+  },
+  "platform": "telegram",
+  "vectors": [
+    {
+      "id": "plain-text",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "Just a plain sentence.",
+      "native_output": "Just a plain sentence\\."
+    },
+    {
+      "id": "bold",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "This is **bold** text.",
+      "native_output": "This is *bold* text\\."
+    },
+    {
+      "id": "italic",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "This is *italic* text.",
+      "native_output": "This is _italic_ text\\."
+    },
+    {
+      "id": "bold-italic",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "Mix of **bold** and *italic* in one line.",
+      "native_output": "Mix of *bold* and _italic_ in one line\\."
+    },
+    {
+      "id": "strikethrough",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "This is ~~struck~~ text.",
+      "native_output": "This is ~struck~ text\\."
+    },
+    {
+      "id": "inline-code",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "Run `pip install hermes` to start.",
+      "native_output": "Run `pip install hermes` to start\\."
+    },
+    {
+      "id": "fenced-code",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "```\nprint('hello')\n```",
+      "native_output": "```\nprint('hello')\n```"
+    },
+    {
+      "id": "fenced-code-lang",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "```python\ndef f(x):\n    return x * 2\n```",
+      "native_output": "```python\ndef f(x):\n    return x * 2\n```"
+    },
+    {
+      "id": "link",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "See [the docs](https://example.com/docs) for more.",
+      "native_output": "See [the docs](https://example.com/docs) for more\\."
+    },
+    {
+      "id": "link-parens-url",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "See [spec](https://example.com/a_(b)) here.",
+      "native_output": "See [spec](https://example.com/a_\\(b\\)) here\\."
+    },
+    {
+      "id": "header-h1",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "# Big Title\nBody follows.",
+      "native_output": "*Big Title*\nBody follows\\."
+    },
+    {
+      "id": "header-h2",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "## Section\nBody follows.",
+      "native_output": "*Section*\nBody follows\\."
+    },
+    {
+      "id": "header-h3",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "### Sub-section\nBody follows.",
+      "native_output": "*Sub\\-section*\nBody follows\\."
+    },
+    {
+      "id": "ul-list",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "- first\n- second\n- third",
+      "native_output": "\\- first\n\\- second\n\\- third"
+    },
+    {
+      "id": "ol-list",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "1. first\n2. second\n3. third",
+      "native_output": "1\\. first\n2\\. second\n3\\. third"
+    },
+    {
+      "id": "nested-list",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "- outer\n  - inner one\n  - inner two\n- outer two",
+      "native_output": "\\- outer\n  \\- inner one\n  \\- inner two\n\\- outer two"
+    },
+    {
+      "id": "blockquote",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "> quoted wisdom\nregular line",
+      "native_output": "> quoted wisdom\nregular line"
+    },
+    {
+      "id": "hrule",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "above\n\n---\n\nbelow",
+      "native_output": "above\n\n\\-\\-\\-\n\nbelow"
+    },
+    {
+      "id": "table-simple",
+      "category": "grid",
+      "expect": "divergent",
+      "input": "| name | value |\n|------|-------|\n| a    | 1     |\n| b    | 2     |",
+      "native_output": "*a*\n• value: 1\n\n*b*\n• value: 2",
+      "note": "native wraps tables into row groups; connector renders <pre> — content preserved, layout differs"
+    },
+    {
+      "id": "emoji",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "Done ✅ with 🎉 emoji 👀 test.",
+      "native_output": "Done ✅ with 🎉 emoji 👀 test\\."
+    },
+    {
+      "id": "cjk",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "中文测试：**粗体** 和 `代码` 混排。",
+      "native_output": "中文测试：*粗体* 和 `代码` 混排。"
+    },
+    {
+      "id": "bare-url",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "Visit https://example.com/path?q=1&r=2 today.",
+      "native_output": "Visit https://example\\.com/path?q\\=1&r\\=2 today\\."
+    },
+    {
+      "id": "mixed-document",
+      "category": "grid",
+      "expect": "semantic",
+      "input": "## Report\n\nStatus: **green**. Details in `runbook.md`.\n\n- item *one*\n- item **two**\n\n```sh\nmake deploy\n```\n\nSee [dashboard](https://grafana.example.com/d/x).",
+      "native_output": "*Report*\n\nStatus: *green*\\. Details in `runbook.md`\\.\n\n\\- item _one_\n\\- item *two*\n\n```sh\nmake deploy\n```\n\nSee [dashboard](https://grafana.example.com/d/x)\\."
+    },
+    {
+      "id": "mdv2-reserved-chars",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "Price is 3.50 (was 4.00) — save ~12%! #deal +tax = win.",
+      "native_output": "Price is 3\\.50 \\(was 4\\.00\\) — save \\~12%\\! \\#deal \\+tax \\= win\\."
+    },
+    {
+      "id": "mdv2-underscores",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "snake_case_name and file_name.py in prose.",
+      "native_output": "snake\\_case\\_name and file\\_name\\.py in prose\\."
+    },
+    {
+      "id": "mdv2-brackets",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "Array[0] and dict{key} and (parens) live here.",
+      "native_output": "Array\\[0\\] and dict\\{key\\} and \\(parens\\) live here\\."
+    },
+    {
+      "id": "slack-bold-conversion",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "**important** word",
+      "native_output": "*important* word"
+    },
+    {
+      "id": "slack-link-conversion",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "[click here](https://example.com)",
+      "native_output": "[click here](https://example.com)"
+    },
+    {
+      "id": "slack-broadcast-mention",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "Hey <!everyone> and <!channel> and <!here>!",
+      "native_output": "Hey <\\!everyone\\> and <\\!channel\\> and <\\!here\\>\\!"
+    },
+    {
+      "id": "fence-lang-tag-slack",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "```text\nliteral first line issue\n```",
+      "native_output": "```text\nliteral first line issue\n```"
+    },
+    {
+      "id": "backslash-in-code",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "`C:\\Users\\ben\\file.txt` and ```\npath = \"a\\\\b\"\n```",
+      "native_output": "`C:\\\\Users\\\\ben\\\\file.txt` and ```\npath = \"a\\\\\\\\b\"\n```"
+    },
+    {
+      "id": "backtick-in-fence",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "```\nuse `inline` inside fence\n```",
+      "native_output": "```\nuse \\`inline\\` inside fence\n```"
+    },
+    {
+      "id": "header-with-bold",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "## The **Real** Deal",
+      "native_output": "*The Real Deal*"
+    },
+    {
+      "id": "table-cjk",
+      "category": "scar",
+      "expect": "divergent",
+      "input": "| 名前 | 値 |\n|------|----|\n| 中文 | 42 |\n| b    | 2  |",
+      "native_output": "*中文*\n• 値: 42\n\n*b*\n• 値: 2",
+      "note": "same as table-simple (CJK width alignment is native-only)"
+    },
+    {
+      "id": "link-display-escapes",
+      "category": "scar",
+      "expect": "semantic",
+      "input": "[v2.0 (beta)](https://example.com/v2)",
+      "native_output": "[v2\\.0 \\(beta\\)](https://example.com/v2)"
+    },
+    {
+      "id": "media-tag",
+      "category": "adversarial",
+      "expect": "semantic",
+      "input": "Here you go\nMEDIA:/tmp/output.png\ndone",
+      "native_output": "Here you go\nMEDIA:/tmp/output\\.png\ndone"
+    },
+    {
+      "id": "unclosed-fence",
+      "category": "adversarial",
+      "expect": "divergent",
+      "input": "```python\nprint('never closed')",
+      "native_output": "\\`\\`\\`python\nprint\\('never closed'\\)",
+      "note": "unterminated fence: native escapes as prose, connector HTML may close the block — degraded either way, never a 400"
+    },
+    {
+      "id": "pathological-nesting",
+      "category": "adversarial",
+      "expect": "semantic",
+      "input": "**bold *italic ~~struck `code` struck~~ italic* bold**",
+      "native_output": "*bold \\*italic \\~\\~struck `code` struck\\~\\~ italic\\* bold*"
+    },
+    {
+      "id": "placeholder-injection",
+      "category": "adversarial",
+      "expect": "divergent",
+      "input": "sneaky \u0000PH0\u0000 token and \u0000SL1\u0000 too",
+      "native_output": "sneaky \u0000PH0\u0000 token and \u0000SL1\u0000 too",
+      "note": "NUL placeholder tokens are renderer-internal; each side neutralizes its own pattern"
+    },
+    {
+      "id": "triple-markers",
+      "category": "adversarial",
+      "expect": "semantic",
+      "input": "***what is this*** and ____that____",
+      "native_output": "*\\*what is this*\\* and \\_\\_\\_\\_that\\_\\_\\_\\_"
+    },
+    {
+      "id": "empty-string",
+      "category": "adversarial",
+      "expect": "semantic",
+      "input": "",
+      "native_output": ""
+    },
+    {
+      "id": "whitespace-only",
+      "category": "adversarial",
+      "expect": "divergent",
+      "input": "   \n\t\n   ",
+      "native_output": "   \n\t\n   ",
+      "note": "native collapses to empty-ish prose, connector HTML preserves — cosmetic"
+    },
+    {
+      "id": "long-line",
+      "category": "adversarial",
+      "expect": "semantic",
+      "input": "word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word ",
+      "native_output": "word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word "
+    },
+    {
+      "id": "many-fences",
+      "category": "adversarial",
+      "expect": "semantic",
+      "input": "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail",
+      "native_output": "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail"
+    }
+  ]
+}
diff --git a/tests/conformance/vectors/whatsapp.json b/tests/conformance/vectors/whatsapp.json
new file mode 100644
index 00000000000..9632346eaa8
--- /dev/null
+++ b/tests/conformance/vectors/whatsapp.json
@@ -0,0 +1,322 @@
+{
+  "$comment": "GENERATED — do not hand-edit. Regenerate with hermes-agent scripts/generate_conformance_vectors.py; the native renderers are the oracle (executable spec).",
+  "oracle": {
+    "repo": "NousResearch/hermes-agent",
+    "commit": "40eebc7d70f3d8e95c429c8aa482f31ba6c867f6",
+    "generator": "scripts/generate_conformance_vectors.py",
+    "generator_version": 1
+  },
+  "platform": "whatsapp",
+  "vectors": [
+    {
+      "id": "plain-text",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Just a plain sentence.",
+      "native_output": "Just a plain sentence."
+    },
+    {
+      "id": "bold",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is **bold** text.",
+      "native_output": "This is *bold* text."
+    },
+    {
+      "id": "italic",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is *italic* text.",
+      "native_output": "This is _italic_ text."
+    },
+    {
+      "id": "bold-italic",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Mix of **bold** and *italic* in one line.",
+      "native_output": "Mix of *bold* and _italic_ in one line."
+    },
+    {
+      "id": "strikethrough",
+      "category": "grid",
+      "expect": "parity",
+      "input": "This is ~~struck~~ text.",
+      "native_output": "This is ~struck~ text."
+    },
+    {
+      "id": "inline-code",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Run `pip install hermes` to start.",
+      "native_output": "Run `pip install hermes` to start."
+    },
+    {
+      "id": "fenced-code",
+      "category": "grid",
+      "expect": "parity",
+      "input": "```\nprint('hello')\n```",
+      "native_output": "```\nprint('hello')\n```"
+    },
+    {
+      "id": "fenced-code-lang",
+      "category": "grid",
+      "expect": "parity",
+      "input": "```python\ndef f(x):\n    return x * 2\n```",
+      "native_output": "```python\ndef f(x):\n    return x * 2\n```"
+    },
+    {
+      "id": "link",
+      "category": "grid",
+      "expect": "parity",
+      "input": "See [the docs](https://example.com/docs) for more.",
+      "native_output": "See the docs (https://example.com/docs) for more."
+    },
+    {
+      "id": "link-parens-url",
+      "category": "grid",
+      "expect": "parity",
+      "input": "See [spec](https://example.com/a_(b)) here.",
+      "native_output": "See spec (https://example.com/a_(b)) here."
+    },
+    {
+      "id": "header-h1",
+      "category": "grid",
+      "expect": "parity",
+      "input": "# Big Title\nBody follows.",
+      "native_output": "*Big Title*\nBody follows."
+    },
+    {
+      "id": "header-h2",
+      "category": "grid",
+      "expect": "parity",
+      "input": "## Section\nBody follows.",
+      "native_output": "*Section*\nBody follows."
+    },
+    {
+      "id": "header-h3",
+      "category": "grid",
+      "expect": "parity",
+      "input": "### Sub-section\nBody follows.",
+      "native_output": "*Sub-section*\nBody follows."
+    },
+    {
+      "id": "ul-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "- first\n- second\n- third",
+      "native_output": "- first\n- second\n- third"
+    },
+    {
+      "id": "ol-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "1. first\n2. second\n3. third",
+      "native_output": "1. first\n2. second\n3. third"
+    },
+    {
+      "id": "nested-list",
+      "category": "grid",
+      "expect": "parity",
+      "input": "- outer\n  - inner one\n  - inner two\n- outer two",
+      "native_output": "- outer\n  - inner one\n  - inner two\n- outer two"
+    },
+    {
+      "id": "blockquote",
+      "category": "grid",
+      "expect": "parity",
+      "input": "> quoted wisdom\nregular line",
+      "native_output": "> quoted wisdom\nregular line"
+    },
+    {
+      "id": "hrule",
+      "category": "grid",
+      "expect": "parity",
+      "input": "above\n\n---\n\nbelow",
+      "native_output": "above\n\n---\n\nbelow"
+    },
+    {
+      "id": "table-simple",
+      "category": "grid",
+      "expect": "parity",
+      "input": "| name | value |\n|------|-------|\n| a    | 1     |\n| b    | 2     |",
+      "native_output": "| name | value |\n|------|-------|\n| a    | 1     |\n| b    | 2     |"
+    },
+    {
+      "id": "emoji",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Done ✅ with 🎉 emoji 👀 test.",
+      "native_output": "Done ✅ with 🎉 emoji 👀 test."
+    },
+    {
+      "id": "cjk",
+      "category": "grid",
+      "expect": "parity",
+      "input": "中文测试：**粗体** 和 `代码` 混排。",
+      "native_output": "中文测试：*粗体* 和 `代码` 混排。"
+    },
+    {
+      "id": "bare-url",
+      "category": "grid",
+      "expect": "parity",
+      "input": "Visit https://example.com/path?q=1&r=2 today.",
+      "native_output": "Visit https://example.com/path?q=1&r=2 today."
+    },
+    {
+      "id": "mixed-document",
+      "category": "grid",
+      "expect": "parity",
+      "input": "## Report\n\nStatus: **green**. Details in `runbook.md`.\n\n- item *one*\n- item **two**\n\n```sh\nmake deploy\n```\n\nSee [dashboard](https://grafana.example.com/d/x).",
+      "native_output": "*Report*\n\nStatus: *green*. Details in `runbook.md`.\n\n- item _one_\n- item *two*\n\n```sh\nmake deploy\n```\n\nSee dashboard (https://grafana.example.com/d/x)."
+    },
+    {
+      "id": "mdv2-reserved-chars",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Price is 3.50 (was 4.00) — save ~12%! #deal +tax = win.",
+      "native_output": "Price is 3.50 (was 4.00) — save ~12%! #deal +tax = win."
+    },
+    {
+      "id": "mdv2-underscores",
+      "category": "scar",
+      "expect": "parity",
+      "input": "snake_case_name and file_name.py in prose.",
+      "native_output": "snake_case_name and file_name.py in prose."
+    },
+    {
+      "id": "mdv2-brackets",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Array[0] and dict{key} and (parens) live here.",
+      "native_output": "Array[0] and dict{key} and (parens) live here."
+    },
+    {
+      "id": "slack-bold-conversion",
+      "category": "scar",
+      "expect": "parity",
+      "input": "**important** word",
+      "native_output": "*important* word"
+    },
+    {
+      "id": "slack-link-conversion",
+      "category": "scar",
+      "expect": "parity",
+      "input": "[click here](https://example.com)",
+      "native_output": "click here (https://example.com)"
+    },
+    {
+      "id": "slack-broadcast-mention",
+      "category": "scar",
+      "expect": "parity",
+      "input": "Hey <!everyone> and <!channel> and <!here>!",
+      "native_output": "Hey <!everyone> and <!channel> and <!here>!"
+    },
+    {
+      "id": "fence-lang-tag-slack",
+      "category": "scar",
+      "expect": "parity",
+      "input": "```text\nliteral first line issue\n```",
+      "native_output": "```text\nliteral first line issue\n```"
+    },
+    {
+      "id": "backslash-in-code",
+      "category": "scar",
+      "expect": "parity",
+      "input": "`C:\\Users\\ben\\file.txt` and ```\npath = \"a\\\\b\"\n```",
+      "native_output": "`C:\\Users\\ben\\file.txt` and ```\npath = \"a\\\\b\"\n```"
+    },
+    {
+      "id": "backtick-in-fence",
+      "category": "scar",
+      "expect": "parity",
+      "input": "```\nuse `inline` inside fence\n```",
+      "native_output": "```\nuse `inline` inside fence\n```"
+    },
+    {
+      "id": "header-with-bold",
+      "category": "scar",
+      "expect": "parity",
+      "input": "## The **Real** Deal",
+      "native_output": "*The *Real* Deal*"
+    },
+    {
+      "id": "table-cjk",
+      "category": "scar",
+      "expect": "parity",
+      "input": "| 名前 | 値 |\n|------|----|\n| 中文 | 42 |\n| b    | 2  |",
+      "native_output": "| 名前 | 値 |\n|------|----|\n| 中文 | 42 |\n| b    | 2  |"
+    },
+    {
+      "id": "link-display-escapes",
+      "category": "scar",
+      "expect": "parity",
+      "input": "[v2.0 (beta)](https://example.com/v2)",
+      "native_output": "v2.0 (beta) (https://example.com/v2)"
+    },
+    {
+      "id": "media-tag",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "Here you go\nMEDIA:/tmp/output.png\ndone",
+      "native_output": "Here you go\nMEDIA:/tmp/output.png\ndone"
+    },
+    {
+      "id": "unclosed-fence",
+      "category": "adversarial",
+      "expect": "divergent",
+      "input": "```python\nprint('never closed')",
+      "native_output": "```python\nprint('never closed')",
+      "note": "unterminated fence handling differs; both degrade without dropping content"
+    },
+    {
+      "id": "pathological-nesting",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "**bold *italic ~~struck `code` struck~~ italic* bold**",
+      "native_output": "*bold _italic ~struck `code` struck~ italic_ bold*"
+    },
+    {
+      "id": "placeholder-injection",
+      "category": "adversarial",
+      "expect": "divergent",
+      "input": "sneaky \u0000PH0\u0000 token and \u0000SL1\u0000 too",
+      "native_output": "sneaky \u0000PH0\u0000 token and \u0000SL1\u0000 too",
+      "note": "placeholder alphabets are renderer-internal"
+    },
+    {
+      "id": "triple-markers",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "***what is this*** and ____that____",
+      "native_output": "**what is this** and *__that*__"
+    },
+    {
+      "id": "empty-string",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "",
+      "native_output": ""
+    },
+    {
+      "id": "whitespace-only",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "   \n\t\n   ",
+      "native_output": "   \n\t\n   "
+    },
+    {
+      "id": "long-line",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word ",
+      "native_output": "word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word "
+    },
+    {
+      "id": "many-fences",
+      "category": "adversarial",
+      "expect": "parity",
+      "input": "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail",
+      "native_output": "```\na\n```\nmid\n```\nb\n```\nend ```inline``` tail"
+    }
+  ]
+}
diff --git a/tests/conftest.py b/tests/conftest.py
index 1fcd1bd4abb..159afd4c2b4 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -21,6 +21,7 @@ test runner at ``scripts/run_tests.sh``.
 
 import asyncio
 import os
+import sqlite3
 import sys
 from pathlib import Path
 
@@ -541,6 +542,44 @@ def _ensure_current_event_loop(request):
 # delivery is harmless.
 
 _LIVE_SYSTEM_GUARD_BYPASS_MARK = "live_system_guard_bypass"
+_REQUIRES_WAL_MARK = "requires_wal"
+
+
+def _wal_is_usable() -> bool:
+    """True when Hermes will actually put a database into WAL mode here.
+
+    Hermes refuses journal_mode=WAL on SQLite builds carrying the upstream
+    WAL-reset corruption bug (3.7.0–3.51.2, excluding backports 3.50.7 /
+    3.44.6) and falls back to DELETE. On such a build NO ``-wal`` sidecar is
+    ever created, so a test asserting on WAL frames, ``-wal`` file size, or
+    checkpoint behaviour cannot pass — it is testing a mode the runtime
+    declined to enable, not a regression.
+
+    This matters because the interpreter running the tests and the interpreter
+    running Hermes can link DIFFERENT SQLite versions: a repo ``.venv`` on
+    3.50.4 (vulnerable → DELETE) alongside a Hermes managed runtime on 3.53.1
+    (fixed → WAL). The same test then passes in one and fails in the other.
+
+    IMPORTANT: this must NOT import ``hermes_state``. That module computes
+    ``DEFAULT_DB_PATH`` from ``get_hermes_home()`` at import time, so importing
+    it during collection — before the per-test ``_isolate_hermes_home`` fixture
+    redirects ``HERMES_HOME`` — permanently caches the DEVELOPER'S REAL
+    ``~/.hermes/state.db`` for the whole session. Tests then read live
+    production sessions instead of a tempdir. The version predicate is
+    duplicated from ``hermes_state._is_sqlite_wal_reset_vulnerable`` (upstream
+    fixed ranges, stable) rather than imported, and
+    ``test_conftest_wal_gate.py`` pins the two implementations in agreement.
+    """
+    info = sqlite3.sqlite_version_info
+    if info < (3, 7, 0):
+        return True  # pre-WAL library: cannot hit the race
+    if info >= (3, 51, 3):
+        return True  # fixed upstream
+    if (3, 50, 7) <= info < (3, 51, 0):
+        return True  # 3.50.x backport
+    if (3, 44, 6) <= info < (3, 45, 0):
+        return True  # 3.44.x backport
+    return False
 
 
 def pytest_configure(config):  # noqa: D401 — pytest hook
@@ -551,6 +590,12 @@ def pytest_configure(config):  # noqa: D401 — pytest hook
         "(only for tests that genuinely need real os.kill / subprocess "
         "behaviour — e.g. PTY tests that signal their own child).",
     )
+    config.addinivalue_line(
+        "markers",
+        f"{_REQUIRES_WAL_MARK}: test needs the runtime to actually enable "
+        "SQLite WAL mode; skipped on builds where Hermes falls back to "
+        "journal_mode=DELETE for the WAL-reset bug.",
+    )
 
     # The pyproject addopts pin ``--timeout-method=signal`` relies on
     # ``signal.SIGALRM``, which does not exist on Windows — pytest-timeout
@@ -561,6 +606,26 @@ def pytest_configure(config):  # noqa: D401 — pytest hook
         config.option.timeout_method = "thread"
 
 
+def pytest_collection_modifyitems(config, items):  # noqa: D401 — pytest hook
+    """Skip ``requires_wal`` tests when the linked SQLite can't use WAL.
+
+    Cheaper and more honest than each test hand-rolling a version check: the
+    reason string names the actual linked version so the skip is diagnosable
+    rather than mysterious.
+    """
+    if _wal_is_usable():
+        return
+
+    reason = (
+        f"SQLite {sqlite3.sqlite_version} has the WAL-reset bug — Hermes uses "
+        "journal_mode=DELETE here, so no -wal sidecar exists to assert on"
+    )
+    skip_marker = pytest.mark.skip(reason=reason)
+    for item in items:
+        if item.get_closest_marker(_REQUIRES_WAL_MARK) is not None:
+            item.add_marker(skip_marker)
+
+
 @pytest.fixture(autouse=True)
 def _live_system_guard(request, monkeypatch):
     """Block real os.kill / systemctl / gateway-pid scans during tests.
diff --git a/tests/cron/test_execution_ledger.py b/tests/cron/test_execution_ledger.py
index 7d032b06a85..0be6aa63ec8 100644
--- a/tests/cron/test_execution_ledger.py
+++ b/tests/cron/test_execution_ledger.py
@@ -304,6 +304,126 @@ def test_external_provider_start_recovers_interrupted_records(monkeypatch):
     assert events == ["recover", "reconcile"]
 
 
+class _TrackingConnection:
+    """Delegates to a real sqlite3.Connection while recording close() calls.
+
+    sqlite3.Connection is a static C type: it has no per-instance __dict__
+    and its class methods can't be monkeypatched, so open/close tracking is
+    done via a delegating wrapper returned in place of the real connection.
+    """
+
+    def __init__(self, real, closed_ids):
+        object.__setattr__(self, "_real", real)
+        object.__setattr__(self, "_closed_ids", closed_ids)
+
+    def close(self):
+        self._closed_ids.append(id(self._real))
+        self._real.close()
+
+    def __enter__(self):
+        self._real.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return self._real.__exit__(exc_type, exc, tb)
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)
+
+    def __setattr__(self, name, value):
+        setattr(self._real, name, value)
+
+
+def _count_open_connections(executions, monkeypatch):
+    """Wrap sqlite3.connect to track open/close balance for the ledger module."""
+    opened_ids = []
+    closed_ids = []
+    real_connect = sqlite3.connect
+
+    def tracking_connect(*args, **kwargs):
+        conn = real_connect(*args, **kwargs)
+        opened_ids.append(id(conn))
+        return _TrackingConnection(conn, closed_ids)
+
+    monkeypatch.setattr(executions.sqlite3, "connect", tracking_connect)
+    return opened_ids, closed_ids
+
+
+def test_ledger_operations_close_every_connection(monkeypatch, tmp_path):
+    """Regression for #69567: every ledger call must close its connection
+    deterministically instead of relying on garbage collection."""
+    executions = _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _count_open_connections(executions, monkeypatch)
+
+    record = executions.create_execution("leak-check", source="builtin")
+    executions.mark_execution_running(record["id"])
+    executions.finish_execution(record["id"], success=True)
+    executions.list_executions(job_id="leak-check")
+    executions.latest_executions(["leak-check"])
+    executions.recover_interrupted_executions()
+
+    assert len(opened) == 6
+    assert len(closed) == 6
+    assert set(opened) == set(closed)
+
+
+def test_early_return_still_closes_connection(monkeypatch, tmp_path):
+    """mark_execution_running returns None mid-block on a bad transition;
+    the connection must still be closed rather than leaked."""
+    executions = _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _count_open_connections(executions, monkeypatch)
+
+    assert executions.mark_execution_running("does-not-exist") is None
+
+    assert len(opened) == 1
+    assert len(closed) == 1
+
+
+def test_exception_during_operation_still_closes_connection(monkeypatch, tmp_path):
+    """A failing statement inside the transaction must roll back and close,
+    not leak the connection."""
+    executions = _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _count_open_connections(executions, monkeypatch)
+
+    with __import__("pytest").raises(sqlite3.IntegrityError):
+        with executions._transaction() as conn:
+            conn.execute(
+                "INSERT INTO executions (id, job_id, source, process_id, pid, "
+                "status, claimed_at) VALUES ('x', 'x', 'x', 'x', 1, 'bogus-status', 'now')"
+            )
+
+    assert len(opened) == 1
+    assert len(closed) == 1
+
+
+def test_schema_init_failure_still_closes_connection(monkeypatch, tmp_path):
+    """If PRAGMA/DDL setup in _connect() fails after sqlite3.connect()
+    succeeds, the partially-initialized connection must still be closed."""
+    executions = _point_ledger(monkeypatch, tmp_path)
+    opened_ids = []
+    closed_ids = []
+    real_connect = sqlite3.connect
+
+    class _FailingSchemaConnection(_TrackingConnection):
+        def execute(self, sql, *args, **kwargs):
+            if "CREATE TABLE" in sql:
+                raise sqlite3.OperationalError("simulated schema init failure")
+            return self._real.execute(sql, *args, **kwargs)
+
+    def tracking_connect(*args, **kwargs):
+        conn = real_connect(*args, **kwargs)
+        opened_ids.append(id(conn))
+        return _FailingSchemaConnection(conn, closed_ids)
+
+    monkeypatch.setattr(executions.sqlite3, "connect", tracking_connect)
+
+    with __import__("pytest").raises(sqlite3.OperationalError):
+        executions.create_execution("init-fail", source="builtin")
+
+    assert len(opened_ids) == 1
+    assert len(closed_ids) == 1
+
+
 def test_job_listing_exposes_latest_execution(monkeypatch, tmp_path):
     import cron.jobs as jobs
 
diff --git a/tests/cron/test_jobs_file_ownership.py b/tests/cron/test_jobs_file_ownership.py
new file mode 100644
index 00000000000..b0e30fab930
--- /dev/null
+++ b/tests/cron/test_jobs_file_ownership.py
@@ -0,0 +1,303 @@
+"""Regression tests for issue #68483.
+
+Running a state-writing ``hermes cron`` CLI command as root (the default for
+``docker exec``) rewrote ``jobs.json`` as ``root:root`` mode 600 via the
+mkstemp + atomic_replace pattern, silently locking out the unprivileged
+gateway ticker — which then failed every tick with PermissionError while the
+liveness heartbeat stayed fresh, so nothing surfaced the outage.
+
+Two behavior contracts are pinned here:
+
+1. Ownership preservation: a privileged (euid 0) writer must hand ownership
+   of the rewritten ``jobs.json`` back to its previous owner; unprivileged
+   writers must not attempt a chown at all.
+2. Zombie-ticker surfacing: a failing tick must persist the failure reason
+   (``ticker_last_error``) where ``hermes cron status`` can show it, and a
+   subsequent clean tick must clear it.
+"""
+
+import os
+import sys
+import threading
+
+import pytest
+
+import cron.jobs as jobs
+
+
+pytestmark = pytest.mark.skipif(
+    sys.platform == "win32", reason="POSIX-only: uid/gid ownership semantics"
+)
+
+
+@pytest.fixture()
+def cron_store(tmp_path, monkeypatch):
+    """Route the cron store to an isolated temp dir."""
+    cron_dir = tmp_path / "cron"
+    monkeypatch.setattr(jobs, "CRON_DIR", cron_dir)
+    monkeypatch.setattr(jobs, "JOBS_FILE", cron_dir / "jobs.json")
+    monkeypatch.setattr(jobs, "OUTPUT_DIR", cron_dir / "output")
+    return cron_dir
+
+
+# =========================================================================
+# 1. Ownership preservation on save (root writer)
+# =========================================================================
+
+
+class TestSaveJobsOwnershipPreservation:
+    def test_root_writer_restores_previous_owner(self, cron_store, monkeypatch):
+        """When euid==0 and jobs.json was owned by another uid/gid, the
+        rewrite must chown the new file back to that owner."""
+        jobs.save_jobs([{"id": "seed", "prompt": "hello"}])
+        jobs_file = cron_store / "jobs.json"
+        assert jobs_file.exists()
+
+        chown_calls = []
+
+        # Pretend the existing file is owned by the gateway user (uid 1000)
+        # and that WE are root.
+        real_stat = os.stat
+
+        class _FakeStat:
+            def __init__(self, wrapped):
+                self._wrapped = wrapped
+                self.st_uid = 1000
+                self.st_gid = 1000
+
+            def __getattr__(self, name):
+                return getattr(self._wrapped, name)
+
+        def fake_stat(path, *a, **k):
+            result = real_stat(path, *a, **k)
+            if str(path) == str(jobs_file):
+                return _FakeStat(result)
+            return result
+
+        monkeypatch.setattr(jobs.os, "stat", fake_stat)
+        monkeypatch.setattr(jobs.os, "geteuid", lambda: 0)
+        monkeypatch.setattr(jobs.os, "getegid", lambda: 0)
+        monkeypatch.setattr(
+            jobs.os, "chown", lambda path, uid, gid: chown_calls.append((str(path), uid, gid))
+        )
+
+        jobs.save_jobs([{"id": "seed", "prompt": "updated"}])
+
+        assert chown_calls == [(str(jobs_file), 1000, 1000)], (
+            "root rewrite must hand jobs.json back to the previous owner "
+            "(uid/gid 1000) instead of leaving it root:600 (#68483)"
+        )
+
+    def test_root_first_write_inherits_cron_dir_owner(self, cron_store, monkeypatch):
+        """Creating jobs.json for the first time as root must inherit the
+        cron dir's owner (the gateway user in the Docker image)."""
+        chown_calls = []
+        jobs_file = cron_store / "jobs.json"
+
+        real_stat = os.stat
+
+        class _FakeStat:
+            def __init__(self, wrapped):
+                self._wrapped = wrapped
+                self.st_uid = 1000
+                self.st_gid = 1000
+
+            def __getattr__(self, name):
+                return getattr(self._wrapped, name)
+
+        def fake_stat(path, *a, **k):
+            result = real_stat(path, *a, **k)
+            if str(path) == str(cron_store):
+                return _FakeStat(result)
+            return result
+
+        monkeypatch.setattr(jobs.os, "stat", fake_stat)
+        monkeypatch.setattr(jobs.os, "geteuid", lambda: 0)
+        monkeypatch.setattr(jobs.os, "getegid", lambda: 0)
+        monkeypatch.setattr(
+            jobs.os, "chown", lambda path, uid, gid: chown_calls.append((str(path), uid, gid))
+        )
+
+        assert not jobs_file.exists()
+        jobs.save_jobs([{"id": "new", "prompt": "hello"}])
+
+        assert chown_calls == [(str(jobs_file), 1000, 1000)]
+
+    def test_unprivileged_writer_never_chowns(self, cron_store, monkeypatch):
+        """A same-uid (non-root) writer must not attempt chown at all —
+        it would raise EPERM for foreign-owned files anyway."""
+        jobs.save_jobs([{"id": "seed", "prompt": "hello"}])
+
+        def _fail_chown(*a, **k):
+            raise AssertionError("unprivileged save must not call os.chown")
+
+        monkeypatch.setattr(jobs.os, "chown", _fail_chown)
+        jobs.save_jobs([{"id": "seed", "prompt": "updated"}])  # must not raise
+
+    def test_chown_failure_never_breaks_save(self, cron_store, monkeypatch):
+        """A chown failure is logged, but the save itself must succeed."""
+        jobs.save_jobs([{"id": "seed", "prompt": "hello"}])
+        jobs_file = cron_store / "jobs.json"
+
+        real_stat = os.stat
+
+        class _FakeStat:
+            def __init__(self, wrapped):
+                self._wrapped = wrapped
+                self.st_uid = 1000
+                self.st_gid = 1000
+
+            def __getattr__(self, name):
+                return getattr(self._wrapped, name)
+
+        def fake_stat(path, *a, **k):
+            result = real_stat(path, *a, **k)
+            if str(path) == str(jobs_file):
+                return _FakeStat(result)
+            return result
+
+        def _broken_chown(*a, **k):
+            raise PermissionError("simulated chown failure")
+
+        monkeypatch.setattr(jobs.os, "stat", fake_stat)
+        monkeypatch.setattr(jobs.os, "geteuid", lambda: 0)
+        monkeypatch.setattr(jobs.os, "getegid", lambda: 0)
+        monkeypatch.setattr(jobs.os, "chown", _broken_chown)
+
+        jobs.save_jobs([{"id": "seed", "prompt": "updated"}])  # must not raise
+        assert jobs.load_jobs()[0]["prompt"] == "updated"
+
+    def test_save_still_enforces_0600(self, cron_store):
+        """The ownership fix must not regress the 0600 hardening."""
+        import stat
+
+        jobs.save_jobs([{"id": "seed", "prompt": "hello"}])
+        mode = stat.S_IMODE(os.stat(cron_store / "jobs.json").st_mode)
+        assert mode == 0o600
+
+
+# =========================================================================
+# 2. Zombie-ticker surfacing (ticker_last_error marker)
+# =========================================================================
+
+
+class TestTickerErrorMarker:
+    def test_record_and_get_roundtrip(self, cron_store):
+        assert jobs.get_ticker_last_error() is None
+        jobs.record_ticker_error(
+            "RuntimeError: Failed to read cron database: "
+            "[Errno 13] Permission denied: '/opt/data/cron/jobs.json'"
+        )
+        msg = jobs.get_ticker_last_error()
+        assert msg is not None
+        assert "Permission denied" in msg
+
+    def test_clear_removes_marker(self, cron_store):
+        jobs.record_ticker_error("RuntimeError: boom")
+        assert jobs.get_ticker_last_error() is not None
+        jobs.clear_ticker_error()
+        assert jobs.get_ticker_last_error() is None
+
+    def test_clear_when_absent_is_noop(self, cron_store):
+        jobs.clear_ticker_error()  # must not raise
+        assert jobs.get_ticker_last_error() is None
+
+    def test_record_failure_is_silent(self, tmp_path, monkeypatch):
+        """Marker write failure must never disrupt the tick loop."""
+        blocker = tmp_path / "not_a_dir"
+        blocker.write_text("i am a file")
+        bad_dir = blocker / "cron"
+        monkeypatch.setattr(jobs, "CRON_DIR", bad_dir)
+        monkeypatch.setattr(jobs, "JOBS_FILE", bad_dir / "jobs.json")
+        monkeypatch.setattr(jobs, "OUTPUT_DIR", bad_dir / "output")
+
+        jobs.record_ticker_error("RuntimeError: boom")  # must not raise
+        assert jobs.get_ticker_last_error() is None
+
+
+class TestTickerLoopRecordsErrors:
+    def _run_one_tick(self, monkeypatch, tick_fn):
+        """Run one iteration of the built-in ticker loop with a stubbed tick."""
+        from cron.scheduler_provider import InProcessCronScheduler
+
+        provider = InProcessCronScheduler()
+        monkeypatch.setattr(provider, "recover_interrupted", lambda: 0)
+        monkeypatch.setattr("cron.scheduler.tick", tick_fn)
+
+        stop_event = threading.Event()
+        original_wait = stop_event.wait
+
+        def _stop_after_first_tick(timeout=None):
+            stop_event.set()
+            return original_wait(0)
+
+        stop_event.wait = _stop_after_first_tick
+        provider.start(stop_event)
+
+    def test_failing_tick_persists_error(self, cron_store, monkeypatch):
+        def _boom(**kwargs):
+            raise RuntimeError(
+                "Failed to read cron database: [Errno 13] Permission denied"
+            )
+
+        self._run_one_tick(monkeypatch, _boom)
+
+        msg = jobs.get_ticker_last_error()
+        assert msg is not None, (
+            "a failing tick must persist its reason for `hermes cron status` "
+            "to surface (#68483)"
+        )
+        assert "Permission denied" in msg
+
+    def test_successful_tick_clears_error(self, cron_store, monkeypatch):
+        jobs.record_ticker_error("RuntimeError: stale failure")
+
+        self._run_one_tick(monkeypatch, lambda **kwargs: None)
+
+        assert jobs.get_ticker_last_error() is None, (
+            "a clean tick must clear the stale error marker"
+        )
+
+
+# =========================================================================
+# 3. `hermes cron status` surfaces the failure reason
+# =========================================================================
+
+
+class TestCronStatusSurfacesError:
+    def test_status_shows_last_error_and_permission_hint(self, monkeypatch, capsys):
+        from hermes_cli import cron as cron_cli
+
+        monkeypatch.setattr("hermes_cli.gateway.find_gateway_pids", lambda: [4321])
+        monkeypatch.setattr(jobs, "get_ticker_heartbeat_age", lambda: 5.0)   # alive
+        monkeypatch.setattr(jobs, "get_ticker_success_age", lambda: 9_999.0)  # failing
+        monkeypatch.setattr(
+            jobs,
+            "get_ticker_last_error",
+            lambda: (
+                "RuntimeError: Failed to read cron database: "
+                "[Errno 13] Permission denied: '/opt/data/cron/jobs.json'"
+            ),
+        )
+        monkeypatch.setattr("cron.jobs.list_jobs", lambda **k: [])
+
+        cron_cli.cron_status()
+        out = capsys.readouterr().out
+        assert "Last tick error:" in out
+        assert "Permission denied" in out
+        # The permission-specific hint must point at the ownership fix.
+        assert "docker exec -u" in out
+
+    def test_status_without_marker_keeps_generic_message(self, monkeypatch, capsys):
+        from hermes_cli import cron as cron_cli
+
+        monkeypatch.setattr("hermes_cli.gateway.find_gateway_pids", lambda: [4321])
+        monkeypatch.setattr(jobs, "get_ticker_heartbeat_age", lambda: 5.0)
+        monkeypatch.setattr(jobs, "get_ticker_success_age", lambda: 9_999.0)
+        monkeypatch.setattr(jobs, "get_ticker_last_error", lambda: None)
+        monkeypatch.setattr("cron.jobs.list_jobs", lambda **k: [])
+
+        cron_cli.cron_status()
+        out = capsys.readouterr().out
+        assert "no tick has succeeded" in out
+        assert "Last tick error:" not in out
diff --git a/tests/cron/test_scheduler.py b/tests/cron/test_scheduler.py
index 014e88ec6db..ec8be406313 100644
--- a/tests/cron/test_scheduler.py
+++ b/tests/cron/test_scheduler.py
@@ -736,6 +736,128 @@ class TestDeliverResultWrapping:
         # Media files should be forwarded separately
         assert kwargs["media_files"] == [(str(media_path), False)]
 
+    def test_relay_fronted_home_uses_relay_config_and_live_adapter(self, monkeypatch, tmp_path):
+        """Persisted Slack home survives restart without native Slack config."""
+        from concurrent.futures import Future
+
+        from gateway.config import GatewayConfig, HomeChannel, Platform, PlatformConfig
+
+        relay = MagicMock()
+        relay.fronts_platform.side_effect = lambda platform: platform == Platform.SLACK
+        relay.send_for_platform = AsyncMock(return_value=MagicMock(success=True))
+        relay.send_voice = AsyncMock(return_value=MagicMock(success=True))
+        relay.supports_inchannel_continuable = False
+
+        config = GatewayConfig(
+            platforms={
+                Platform.RELAY: PlatformConfig(enabled=True),
+                Platform.SLACK: PlatformConfig(
+                    enabled=False,
+                    home_channel=HomeChannel(
+                        platform=Platform.SLACK,
+                        chat_id="D123",
+                        name="Owner DM",
+                        user_id="U123",
+                    ),
+                ),
+            },
+        )
+        loop = MagicMock()
+        loop.is_running.return_value = True
+
+        def fake_run_coro(coro, _loop):
+            import asyncio as _asyncio
+
+            future = Future()
+            try:
+                future.set_result(_asyncio.run(coro))
+            except BaseException as exc:  # noqa: BLE001
+                future.set_exception(exc)
+            return future
+
+        standalone_send = AsyncMock(return_value={"success": True})
+        media_path = self._safe_media_path(tmp_path, monkeypatch, "relay-voice.mp3")
+        monkeypatch.setenv("SLACK_HOME_CHANNEL", "D123")
+        job = {
+            "id": "relay-cron",
+            "deliver": "slack",
+        }
+
+        with (
+            patch("gateway.config.load_gateway_config", return_value=config),
+            patch("cron.scheduler.load_config", return_value={"cron": {"wrap_response": False}}),
+            patch("asyncio.run_coroutine_threadsafe", side_effect=fake_run_coro),
+            patch("tools.send_message_tool._send_to_platform", new=standalone_send),
+        ):
+            result = _deliver_result(
+                job,
+                f"scheduled result\nMEDIA:{media_path}",
+                adapters={Platform.RELAY: relay},
+                loop=loop,
+            )
+
+        assert result is None
+        relay.send_for_platform.assert_awaited_once()
+        args = relay.send_for_platform.await_args.args
+        assert args[:3] == (Platform.SLACK, "D123", "scheduled result")
+        assert relay.send_for_platform.await_args.kwargs["metadata"]["user_id"] == "U123"
+        relay.send_voice.assert_awaited_once()
+        media_metadata = relay.send_voice.await_args.kwargs["metadata"]
+        assert media_metadata["_relay_logical_platform"] == "slack"
+        assert media_metadata["user_id"] == "U123"
+        standalone_send.assert_not_awaited()
+
+    def test_relay_fronted_delivery_failure_does_not_use_native_fallback(self):
+        """Connector-owned credentials must never fall through to native send."""
+        from concurrent.futures import Future
+
+        from gateway.config import GatewayConfig, Platform, PlatformConfig
+
+        relay = MagicMock()
+        relay.fronts_platform.side_effect = lambda platform: platform == Platform.SLACK
+        relay.send_for_platform = AsyncMock(
+            return_value=MagicMock(success=False, error="connector unavailable")
+        )
+        relay.supports_inchannel_continuable = False
+        config = GatewayConfig(
+            platforms={Platform.RELAY: PlatformConfig(enabled=True)},
+        )
+        loop = MagicMock()
+        loop.is_running.return_value = True
+
+        def fake_run_coro(coro, _loop):
+            import asyncio as _asyncio
+
+            future = Future()
+            try:
+                future.set_result(_asyncio.run(coro))
+            except BaseException as exc:  # noqa: BLE001
+                future.set_exception(exc)
+            return future
+
+        standalone_send = AsyncMock(return_value={"success": True})
+        job = {
+            "id": "relay-cron-failure",
+            "deliver": "slack:D123",
+        }
+
+        with (
+            patch("gateway.config.load_gateway_config", return_value=config),
+            patch("cron.scheduler.load_config", return_value={"cron": {"wrap_response": False}}),
+            patch("asyncio.run_coroutine_threadsafe", side_effect=fake_run_coro),
+            patch("tools.send_message_tool._send_to_platform", new=standalone_send),
+        ):
+            result = _deliver_result(
+                job,
+                "scheduled result",
+                adapters={Platform.RELAY: relay},
+                loop=loop,
+            )
+
+        assert result is not None
+        assert "connector unavailable" in result
+        standalone_send.assert_not_awaited()
+
     def test_live_adapter_sends_media_as_attachments(self, tmp_path, monkeypatch):
         """When a live adapter is available, MEDIA files should be sent as native
         platform attachments (e.g., Discord voice, Telegram audio) rather than
@@ -3197,7 +3319,7 @@ class TestRunJobWakeGate:
         import cron.scheduler as scheduler
 
         call_count = 0
-        def _script_stub(path):
+        def _script_stub(path, workdir=None, **kwargs):
             nonlocal call_count
             call_count += 1
             return (True, "regular output")
diff --git a/tests/cron/test_scheduler_provider.py b/tests/cron/test_scheduler_provider.py
index 2779fdd9f3f..2adb2c6250d 100644
--- a/tests/cron/test_scheduler_provider.py
+++ b/tests/cron/test_scheduler_provider.py
@@ -691,3 +691,103 @@ class TestGuardJobCredentialExfil:
 
         monkeypatch.setattr(ct, "_validate_cron_base_url", _boom)
         assert _guard_job_credential_exfil({"id": "j8", "provider": "anthropic"}) is None
+
+
+# ── Multiplex profiles: cron per secondary profile (issue #69377) ─────────
+
+
+def test_multiplex_ticker_ticks_each_profile_once(tmp_path, monkeypatch):
+    """The multiplex cron scheduler calls tick() once per profile home,
+    scoped via use_cron_store, so secondary-profile jobs actually fire
+    instead of languishing in an unticked store."""
+    from cron.scheduler_provider import InProcessCronScheduler
+
+    # Set up two profile directories.
+    p1 = tmp_path / "default"
+    p2 = tmp_path / "home-ops"
+    for d in (p1, p2):
+        (d / "cron").mkdir(parents=True)
+
+    profile_homes = [("default", p1), ("home-ops", p2)]
+
+    # Count tick() calls — should be called once per profile per iteration.
+    tick_count: list[int] = []
+
+    def _tracking_tick(*args, **kwargs):
+        tick_count.append(1)
+        return 0
+
+    stop = threading.Event()
+    prov = InProcessCronScheduler()
+
+    with patch("cron.scheduler.tick", side_effect=_tracking_tick), \
+         patch("cron.jobs.record_ticker_heartbeat", lambda **kw: None):
+        t = threading.Thread(
+            target=prov.start,
+            args=(stop,),
+            kwargs={"interval": 0, "profile_homes": profile_homes},
+            daemon=True,
+        )
+        t.start()
+        # Wait for at least len(profile_homes) tick calls (one full cycle).
+        deadline = time.monotonic() + 10
+        while len(tick_count) < len(profile_homes) and time.monotonic() < deadline:
+            time.sleep(0.005)
+        # Give one more cycle to ensure it keeps ticking.
+        deadline = time.monotonic() + 3
+        while len(tick_count) < len(profile_homes) * 2 and time.monotonic() < deadline:
+            time.sleep(0.005)
+        stop.set()
+        t.join(timeout=5)
+
+    assert not t.is_alive()
+    # The ticker called tick() at least once per profile per iteration.
+    # With 2 profiles and multiple iterations, we should have seen at least 2 calls.
+    assert len(tick_count) >= len(profile_homes), \
+        f"Expected >= {len(profile_homes)} tick calls, got {len(tick_count)}"
+
+
+def test_multiplex_heartbeat_scoped_per_profile(tmp_path, monkeypatch):
+    """record_ticker_heartbeat is scoped to each profile's store under
+    multiplex, so 'hermes cron status' can report liveness per profile."""
+    from cron.scheduler_provider import InProcessCronScheduler
+    from cron.jobs import record_ticker_heartbeat as _real_heartbeat
+
+    p_default = tmp_path / "default"
+    p_sec = tmp_path / "home-ops"
+    for d in (p_default, p_sec):
+        (d / "cron").mkdir(parents=True)
+    profile_homes = [("default", p_default), ("home-ops", p_sec)]
+
+    beat_log: list[str] = []
+
+    def _track_beat(*, success=False):
+        beat_log.append(str(success))
+        # Write the real heartbeat files so we can check them after.
+        _real_heartbeat(success=success)
+
+    stop = threading.Event()
+    prov = InProcessCronScheduler()
+
+    with patch("cron.scheduler.tick", return_value=0), \
+         patch("cron.jobs.record_ticker_heartbeat", side_effect=_track_beat):
+        t = threading.Thread(
+            target=prov.start,
+            args=(stop,),
+            kwargs={"interval": 0, "profile_homes": profile_homes},
+            daemon=True,
+        )
+        t.start()
+        deadline = time.monotonic() + 10
+        # Wait for at least 2 tick iterations over all profiles (2 profiles).
+        while len(beat_log) < len(profile_homes) * 2 and time.monotonic() < deadline:
+            time.sleep(0.005)
+        stop.set()
+        t.join(timeout=5)
+
+    assert not t.is_alive()
+    # Every profile should have a heartbeat file.
+    assert (p_default / "cron" / "ticker_heartbeat").exists(), \
+        "default profile heartbeat file missing"
+    assert (p_sec / "cron" / "ticker_heartbeat").exists(), \
+        "secondary profile heartbeat file missing"
diff --git a/tests/cron/test_script_claim_heartbeat.py b/tests/cron/test_script_claim_heartbeat.py
index 0f4c3fd863c..0caa7a95554 100644
--- a/tests/cron/test_script_claim_heartbeat.py
+++ b/tests/cron/test_script_claim_heartbeat.py
@@ -84,7 +84,7 @@ def test_long_running_script_refreshes_owned_claim_in_profile_store(
         heartbeat_seen.set()
         return updated
 
-    def _blocking_script(_script_path: str) -> tuple[bool, str]:
+    def _blocking_script(_script_path: str, **kwargs) -> tuple[bool, str]:
         assert heartbeat_seen.wait(timeout=2), (
             "claim was not refreshed while script blocked"
         )
@@ -146,7 +146,7 @@ def test_script_heartbeat_uses_captured_claim_owner(tmp_path, monkeypatch):
         heartbeat_seen.set()
         return updated
 
-    def _blocking_script(_script_path: str) -> tuple[bool, str]:
+    def _blocking_script(_script_path: str, **kwargs) -> tuple[bool, str]:
         assert heartbeat_seen.wait(timeout=2)
         return True, "done"
 
diff --git a/tests/gateway/relay/stub_connector.py b/tests/gateway/relay/stub_connector.py
index c549a982c4e..0a9bee357fd 100644
--- a/tests/gateway/relay/stub_connector.py
+++ b/tests/gateway/relay/stub_connector.py
@@ -42,6 +42,11 @@ class StubConnector:
         self.chat_info: Dict[str, Dict[str, Any]] = {}
         # Canned result for the next send_outbound (override per-test).
         self.next_send_result: Dict[str, Any] = {"success": True, "message_id": "m1"}
+        # Canned result for the next send_media op (Phase 2; override per-test).
+        self.next_media_result: Dict[str, Any] = {"success": True, "message_id": "md1"}
+        # Canned results for the Phase 3 interactive ops (override per-test).
+        self.next_prompt_result: Dict[str, Any] = {"success": True, "message_id": "pm1"}
+        self.next_react_result: Dict[str, Any] = {"success": True}
         # Canned result for the next send_follow_up (override per-test). Default
         # mimics a resolved capability egress; set success=False to simulate an
         # absent/expired capability or a tenant mismatch on the connector side.
@@ -80,6 +85,12 @@ class StubConnector:
         self.sent_platforms.append(platform)
         if action.get("op") == "send":
             return dict(self.next_send_result)
+        if action.get("op") == "send_media":
+            return dict(self.next_media_result)
+        if action.get("op") == "prompt":
+            return dict(self.next_prompt_result)
+        if action.get("op") == "react":
+            return dict(self.next_react_result)
         return {"success": True}
 
     async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
diff --git a/tests/gateway/relay/test_descriptor.py b/tests/gateway/relay/test_descriptor.py
index 3145e557025..34d8d9e6ef6 100644
--- a/tests/gateway/relay/test_descriptor.py
+++ b/tests/gateway/relay/test_descriptor.py
@@ -96,3 +96,45 @@ def test_module_is_marked_experimental():
     import gateway.relay.descriptor as m
 
     assert "EXPERIMENTAL" in (m.__doc__ or "")
+
+
+# ─────────────── supported_ops (op-level capability discovery, Phase 1) ───────────────
+
+def test_supported_ops_roundtrips_json():
+    d = _telegram_descriptor(supported_ops=("send", "edit", "typing"))
+    restored = CapabilityDescriptor.from_json(d.to_json())
+    assert restored.supported_ops == ("send", "edit", "typing")
+    assert restored == d
+
+
+def test_supports_op_advertised_list_is_authoritative():
+    d = _telegram_descriptor(supported_ops=("send", "typing", "get_chat_info"))
+    assert d.supports_op("send") is True
+    assert d.supports_op("get_chat_info") is True
+    # An advertised list EXCLUDES what it omits — even a legacy op.
+    assert d.supports_op("edit") is False
+
+
+def test_supports_op_legacy_connector_assumes_legacy_set():
+    """An empty supported_ops means the connector predates op discovery: the
+    legacy four ops are assumed supported (old connectors keep working), while
+    NEW ops are not (discovery semantics — never probe by trying)."""
+    d = _telegram_descriptor()  # no supported_ops
+    for op in ("send", "edit", "typing", "follow_up"):
+        assert d.supports_op(op) is True, op
+    assert d.supports_op("get_chat_info") is False
+
+
+def test_from_json_normalizes_malformed_supported_ops():
+    """Non-list shapes and non-string members degrade to the legacy fallback
+    (empty tuple), never raise — malformed input can't break the handshake."""
+    base = (
+        '{"contract_version": 1, "platform": "x", "label": "X", '
+        '"max_message_length": 2000, "supports_draft_streaming": false, '
+        '"supports_edit": true, "supports_threads": false, '
+        '"markdown_dialect": "plain", "len_unit": "chars", '
+    )
+    d = CapabilityDescriptor.from_json(base + '"supported_ops": "send"}')
+    assert d.supported_ops == ()
+    d = CapabilityDescriptor.from_json(base + '"supported_ops": ["send", 7, null, ""]}')
+    assert d.supported_ops == ("send",)
diff --git a/tests/gateway/relay/test_handoff_relay_aliasing.py b/tests/gateway/relay/test_handoff_relay_aliasing.py
new file mode 100644
index 00000000000..878e7d56a63
--- /dev/null
+++ b/tests/gateway/relay/test_handoff_relay_aliasing.py
@@ -0,0 +1,123 @@
+"""Unit tests for /handoff platform aliasing over relay (Phase 1 parity).
+
+Symptom fixed: on a relay-fronted gateway, ``/handoff discord`` was rejected
+in TWO places even though "discord" is deliverable through the relay adapter:
+
+  1. The CLI pre-check (``cli_commands_mixin._handle_handoff_command``) looked
+     up ``gw_config.platforms.get(DISCORD)`` — only a RELAY entry exists.
+  2. The gateway watcher (``run.py _process_handoff``) did a literal
+     ``adapters.get(discord)`` — the adapter is registered under RELAY.
+
+Both now resolve fronted platforms through the same alias-aware machinery the
+delivery router uses (``resolve_delivery_transport`` — native adapter wins;
+relay eligible only when its authenticated transport advertises the logical
+platform). These tests cover the resolver semantics the watcher depends on,
+plus the CLI pre-check's env-derived fronted set.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from gateway.config import GatewayConfig, Platform, PlatformConfig
+from gateway.delivery import resolve_delivery_transport
+
+
+class _RelayStub:
+    """Minimal relay adapter double advertising a fronted-platform set."""
+
+    def __init__(self, fronted):
+        self._fronted = set(fronted)
+        self.sent = []
+
+    def fronts_platform(self, platform):
+        value = getattr(platform, "value", platform)
+        return str(value) in self._fronted
+
+    async def send_for_platform(self, logical_platform, chat_id, content, reply_to=None, metadata=None):
+        self.sent.append((getattr(logical_platform, "value", logical_platform), chat_id, content, metadata))
+        return type("R", (), {"success": True, "message_id": "m-1", "error": None})()
+
+    async def send(self, chat_id, content, reply_to=None, metadata=None):  # pragma: no cover
+        raise AssertionError("relay transport must use send_for_platform, not send")
+
+
+def _config_with(platforms):
+    cfg = GatewayConfig()
+    cfg.platforms = platforms
+    return cfg
+
+
+class TestHandoffRelayAliasing:
+    def test_fronted_platform_resolves_to_relay_adapter(self):
+        """The watcher's exact miss: adapters holds only RELAY, target is discord."""
+        relay = _RelayStub({"discord"})
+        cfg = _config_with({Platform.RELAY: PlatformConfig(enabled=True)})
+        transport = resolve_delivery_transport(
+            Platform.DISCORD, cfg, {Platform.RELAY: relay}
+        )
+        assert transport is not None
+        assert transport.adapter is relay
+        assert transport.is_relay is True
+
+    def test_unfronted_platform_still_fails(self):
+        """Aliasing must not let relay hijack a platform it does not front."""
+        relay = _RelayStub({"telegram"})
+        cfg = _config_with({Platform.RELAY: PlatformConfig(enabled=True)})
+        transport = resolve_delivery_transport(
+            Platform.DISCORD, cfg, {Platform.RELAY: relay}
+        )
+        assert transport is None
+
+    def test_native_adapter_wins_over_relay(self):
+        native = object()
+        relay = _RelayStub({"discord"})
+        cfg = _config_with(
+            {
+                Platform.DISCORD: PlatformConfig(enabled=True),
+                Platform.RELAY: PlatformConfig(enabled=True),
+            }
+        )
+        transport = resolve_delivery_transport(
+            Platform.DISCORD, cfg, {Platform.DISCORD: native, Platform.RELAY: relay}
+        )
+        assert transport is not None
+        assert transport.adapter is native
+        assert transport.is_relay is False
+
+    @pytest.mark.asyncio
+    async def test_transport_send_stamps_logical_platform(self):
+        """The handoff reply leg must go through send_for_platform so the
+        outbound frame carries the logical platform tag."""
+        relay = _RelayStub({"discord"})
+        cfg = _config_with({Platform.RELAY: PlatformConfig(enabled=True)})
+        transport = resolve_delivery_transport(
+            Platform.DISCORD, cfg, {Platform.RELAY: relay}
+        )
+        assert transport is not None
+        result = await transport.send(
+            Platform.DISCORD, "chan-1", "handed-off reply", {"thread_id": "t-9"}
+        )
+        assert result.success is True
+        assert relay.sent == [("discord", "chan-1", "handed-off reply", {"thread_id": "t-9"})]
+
+
+class TestCliHandoffFrontedSet:
+    """The CLI pre-check derives the fronted set from deploy env (no live adapter)."""
+
+    def test_fronted_set_from_env(self, monkeypatch):
+        monkeypatch.setenv("GATEWAY_RELAY_PLATFORMS", "discord,telegram")
+        monkeypatch.delenv("GATEWAY_RELAY_BOT_IDS", raising=False)
+        from gateway.relay import relay_platform_identities
+
+        fronted = {p for p, _ in relay_platform_identities()}
+        assert "discord" in fronted
+        assert "telegram" in fronted
+        assert "slack" not in fronted
+
+    def test_unconfigured_env_yields_generic_relay_only(self, monkeypatch):
+        monkeypatch.delenv("GATEWAY_RELAY_PLATFORMS", raising=False)
+        from gateway.relay import relay_platform_identities
+
+        fronted = {p for p, _ in relay_platform_identities()}
+        assert fronted == {"relay"}
diff --git a/tests/gateway/relay/test_relay_adapter.py b/tests/gateway/relay/test_relay_adapter.py
index 64e3b60fe25..74cb6dbfdc7 100644
--- a/tests/gateway/relay/test_relay_adapter.py
+++ b/tests/gateway/relay/test_relay_adapter.py
@@ -508,3 +508,58 @@ async def test_no_revocation_no_fatal():
     except asyncio.CancelledError:
         pass
     assert a.has_fatal_error is False
+
+
+# ─────────────── get_chat_info gated on supported_ops (Phase 1) ───────────────
+
+
+class _ChatInfoTransport:
+    """Transport stub that records whether get_chat_info was proxied."""
+
+    def __init__(self):
+        self.calls = []
+
+    def set_inbound_handler(self, h):  # noqa: D401
+        self._h = h
+
+    async def get_chat_info(self, chat_id):
+        self.calls.append(chat_id)
+        return {"name": "general", "type": "channel"}
+
+
+@pytest.mark.asyncio
+async def test_get_chat_info_proxied_when_advertised():
+    t = _ChatInfoTransport()
+    a = RelayAdapter(
+        PlatformConfig(),
+        make_desc(supported_ops=("send", "edit", "typing", "get_chat_info")),
+        transport=t,
+    )
+    info = await a.get_chat_info("chan-1")
+    assert info == {"name": "general", "type": "channel"}
+    assert t.calls == ["chan-1"]
+
+
+@pytest.mark.asyncio
+async def test_get_chat_info_local_fallback_for_legacy_connector():
+    """A legacy connector (no supported_ops) would only answer 'unsupported op'
+    — the adapter must skip the round trip and answer locally."""
+    t = _ChatInfoTransport()
+    a = RelayAdapter(PlatformConfig(), make_desc(), transport=t)
+    info = await a.get_chat_info("chan-1")
+    assert info == {"name": "chan-1", "type": "dm"}
+    assert t.calls == []
+
+
+@pytest.mark.asyncio
+async def test_get_chat_info_local_fallback_when_not_advertised():
+    """A connector that advertises ops but OMITS get_chat_info is authoritative."""
+    t = _ChatInfoTransport()
+    a = RelayAdapter(
+        PlatformConfig(),
+        make_desc(supported_ops=("send", "edit", "typing")),
+        transport=t,
+    )
+    info = await a.get_chat_info("chan-1")
+    assert info == {"name": "chan-1", "type": "dm"}
+    assert t.calls == []
diff --git a/tests/gateway/relay/test_relay_interactive.py b/tests/gateway/relay/test_relay_interactive.py
new file mode 100644
index 00000000000..849bba47d0d
--- /dev/null
+++ b/tests/gateway/relay/test_relay_interactive.py
@@ -0,0 +1,416 @@
+"""Relay Phase 3 interactive tests — prompt op egress, prompt_response
+consumption, and the react ack lifecycle.
+
+Covers:
+  - send_exec_approval / send_slash_confirm / send_clarify render through ONE
+    `prompt` op with the right option sets, honoring op gating (legacy
+    connectors get the base/text behaviour or a structured failure that
+    triggers run.py's text fallback);
+  - the pending-prompt registry: mint → consume-once → expiry;
+  - _consume_prompt_response routes answers to the approval / slash-confirm /
+    clarify resolvers and CONSUMES the event; unknown/expired ids fall
+    through to normal dispatch;
+  - the Discord type-3 hp1 decode (structured prompt_response replacing the
+    bare-custom_id stub; foreign custom_ids keep the legacy text shape);
+  - on_processing_start/complete drive react ops (👀 → ✅/❌), op-gated and
+    best-effort.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import pytest
+
+from gateway.config import PlatformConfig
+from gateway.platforms.base import MessageEvent, MessageType, ProcessingOutcome
+from gateway.relay.adapter import RelayAdapter
+from gateway.relay.descriptor import CONTRACT_VERSION, CapabilityDescriptor
+from gateway.session import SessionSource
+
+from tests.gateway.relay.stub_connector import StubConnector
+
+FULL_OPS = (
+    "send",
+    "edit",
+    "typing",
+    "get_chat_info",
+    "send_media",
+    "prompt",
+    "react",
+)
+
+
+def make_desc(**kw) -> CapabilityDescriptor:
+    base = dict(
+        contract_version=CONTRACT_VERSION,
+        platform="telegram",
+        label="Telegram",
+        max_message_length=4096,
+        supports_draft_streaming=False,
+        supports_edit=True,
+        supports_threads=True,
+        markdown_dialect="markdown_v2",
+        len_unit="utf16",
+        supported_ops=FULL_OPS,
+    )
+    base.update(kw)
+    return CapabilityDescriptor(**base)
+
+
+def _adapter(**desc_kw) -> tuple[RelayAdapter, StubConnector]:
+    stub = StubConnector(make_desc(**desc_kw))
+    adapter = RelayAdapter(PlatformConfig(), make_desc(**desc_kw), transport=stub)
+    return adapter, stub
+
+
+def _event(
+    prompt_response: Optional[Dict[str, Any]] = None,
+    text: str = "/once",
+    chat_id: str = "c1",
+) -> MessageEvent:
+    return MessageEvent(
+        text=text,
+        message_type=MessageType.COMMAND,
+        source=SessionSource(
+            platform="telegram", chat_id=chat_id, chat_type="dm", user_id="u1"
+        ),
+        prompt_response=prompt_response,
+    )
+
+
+# ── egress: the three prompt surfaces ────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_exec_approval_renders_full_option_set():
+    adapter, stub = _adapter()
+    result = await adapter.send_exec_approval(
+        "c1", "rm -rf /tmp/x", "sess:1", description="deletes files"
+    )
+    assert result.success is True
+    assert result.message_id == "pm1"
+    action = stub.sent[-1]
+    assert action["op"] == "prompt"
+    assert action["prompt_kind"] == "approval"
+    ids = [o["id"] for o in action["options"]]
+    assert ids == ["once", "session", "always", "deny"]
+    assert "rm -rf /tmp/x" in action["content"]
+    assert "deletes files" in action["content"]
+    # The registry holds the pending prompt keyed by the wire's prompt_id.
+    assert action["prompt_id"] in adapter._pending_prompts
+    state = adapter._pending_prompts[action["prompt_id"]]
+    assert state["kind"] == "exec_approval"
+    assert state["session_key"] == "sess:1"
+
+
+@pytest.mark.asyncio
+async def test_exec_approval_smart_denied_and_flag_gating():
+    adapter, stub = _adapter()
+    await adapter.send_exec_approval(
+        "c1", "cmd", "s", smart_denied=True, allow_permanent=True, allow_session=True
+    )
+    ids = [o["id"] for o in stub.sent[-1]["options"]]
+    assert ids == ["once", "deny"]  # smart-deny: no session/always
+    await adapter.send_exec_approval(
+        "c1", "cmd", "s", allow_session=True, allow_permanent=False
+    )
+    ids = [o["id"] for o in stub.sent[-1]["options"]]
+    assert ids == ["once", "session", "deny"]
+
+
+@pytest.mark.asyncio
+async def test_exec_approval_without_prompt_op_fails_for_text_fallback():
+    adapter, stub = _adapter(supported_ops=("send", "edit", "typing"))
+    result = await adapter.send_exec_approval("c1", "cmd", "s")
+    # success=False → gateway/run.py falls back to the text approval prompt
+    # (same contract as a failed native button send).
+    assert result.success is False
+    assert all(a["op"] != "prompt" for a in stub.sent)
+    assert adapter._pending_prompts == {}  # nothing left pending
+
+
+@pytest.mark.asyncio
+async def test_slash_confirm_renders_three_options():
+    adapter, stub = _adapter()
+    result = await adapter.send_slash_confirm(
+        "c1", "Reload MCP", "This invalidates the prompt cache.", "sess:1", "cf-9"
+    )
+    assert result.success is True
+    action = stub.sent[-1]
+    ids = [o["id"] for o in action["options"]]
+    assert ids == ["once", "always", "cancel"]
+    assert "Reload MCP" in action["content"]
+    state = adapter._pending_prompts[action["prompt_id"]]
+    assert state == {
+        **state,
+        "kind": "slash_confirm",
+        "confirm_id": "cf-9",
+        "session_key": "sess:1",
+    }
+
+
+@pytest.mark.asyncio
+async def test_clarify_renders_choices_plus_other_with_positional_ids():
+    adapter, stub = _adapter()
+    result = await adapter.send_clarify(
+        "c1",
+        "Which environment?",
+        ["staging — the safe one", "production"],
+        "cl-1",
+        "sess:1",
+    )
+    assert result.success is True
+    action = stub.sent[-1]
+    assert action["prompt_kind"] == "clarify"
+    ids = [o["id"] for o in action["options"]]
+    # Positional ids (choice text is arbitrary UTF-8; ids must be callback-safe).
+    assert ids == ["c0", "c1", "other"]
+    labels = [o["label"] for o in action["options"]]
+    assert labels[0].startswith("staging")
+    state = adapter._pending_prompts[action["prompt_id"]]
+    assert state["choices"] == ["staging — the safe one", "production"]
+
+
+@pytest.mark.asyncio
+async def test_clarify_open_ended_uses_base_text_path(monkeypatch):
+    adapter, stub = _adapter()
+    # No choices → base class question-only text send (no prompt op).
+    result = await adapter.send_clarify("c1", "What now?", None, "cl-2", "sess:1")
+    assert result.success is True
+    assert all(a["op"] != "prompt" for a in stub.sent)
+
+
+@pytest.mark.asyncio
+async def test_prompt_decline_degrades_clarify_to_numbered_text(monkeypatch):
+    adapter, stub = _adapter()
+    stub.next_prompt_result = {"success": False, "error": "nope"}
+    marked: list[str] = []
+    monkeypatch.setattr(
+        "tools.clarify_gateway.mark_awaiting_text", lambda cid: marked.append(cid)
+    )
+    result = await adapter.send_clarify(
+        "c1", "Which?", ["a", "b"], "cl-3", "sess:1"
+    )
+    # Falls back to the base numbered-text clarify (a plain send).
+    assert result.success is True
+    assert stub.sent[-1]["op"] == "send"
+    assert "1. a" in stub.sent[-1]["content"]
+    assert marked == ["cl-3"]
+    assert adapter._pending_prompts == {}
+
+
+# ── the pending-prompt registry ──────────────────────────────────────────
+
+
+def test_registry_mint_consume_once_and_expiry():
+    adapter, _stub = _adapter()
+    pid = adapter._mint_prompt("exec_approval", {"session_key": "s"}, timeout_s=3600)
+    assert adapter._pop_prompt(pid) is not None
+    assert adapter._pop_prompt(pid) is None  # one answer wins
+    stale = adapter._mint_prompt("exec_approval", {"session_key": "s"}, timeout_s=-1)
+    assert adapter._pop_prompt(stale) is None  # expired misses
+
+
+# ── inbound consumption ──────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_prompt_response_resolves_exec_approval(monkeypatch):
+    adapter, stub = _adapter()
+    await adapter.send_exec_approval("c1", "cmd", "sess:9")
+    prompt_id = stub.sent[-1]["prompt_id"]
+
+    calls: list[tuple[str, str]] = []
+    monkeypatch.setattr(
+        "tools.approval.resolve_gateway_approval",
+        lambda sk, choice, **kw: calls.append((sk, choice)) or 1,
+    )
+    event = _event({"prompt_id": prompt_id, "option_id": "session"})
+    consumed = await adapter._consume_prompt_response(event)
+    assert consumed is True
+    assert calls == [("sess:9", "session")]
+    # Consumed prompts leave the registry; the ack landed as a plain send.
+    assert prompt_id not in adapter._pending_prompts
+    assert stub.sent[-1]["op"] == "send"
+    assert "session" in stub.sent[-1]["content"].lower()
+
+
+@pytest.mark.asyncio
+async def test_prompt_response_resolves_slash_confirm(monkeypatch):
+    adapter, stub = _adapter()
+    await adapter.send_slash_confirm("c1", "T", "msg", "sess:9", "cf-1")
+    prompt_id = stub.sent[-1]["prompt_id"]
+
+    resolved: list[tuple] = []
+
+    async def fake_resolve(session_key, confirm_id, choice, **kw):
+        resolved.append((session_key, confirm_id, choice))
+        return "done!"
+
+    monkeypatch.setattr("tools.slash_confirm.resolve", fake_resolve)
+    event = _event({"prompt_id": prompt_id, "option_id": "always"})
+    assert await adapter._consume_prompt_response(event) is True
+    assert resolved == [("sess:9", "cf-1", "always")]
+    # The handler's result text went out as a follow-up send.
+    sends = [a for a in stub.sent if a["op"] == "send"]
+    assert any("done!" in a["content"] for a in sends)
+
+
+@pytest.mark.asyncio
+async def test_prompt_response_resolves_clarify_choice_and_other(monkeypatch):
+    adapter, stub = _adapter()
+    await adapter.send_clarify("c1", "Which?", ["alpha", "beta"], "cl-9", "s")
+    prompt_id = stub.sent[-1]["prompt_id"]
+
+    resolved: list[tuple] = []
+    marked: list[str] = []
+    monkeypatch.setattr(
+        "tools.clarify_gateway.resolve_gateway_clarify",
+        lambda cid, resp: resolved.append((cid, resp)) or True,
+    )
+    monkeypatch.setattr(
+        "tools.clarify_gateway.mark_awaiting_text", lambda cid: marked.append(cid)
+    )
+    # Positional id maps back to the REAL choice text.
+    event = _event({"prompt_id": prompt_id, "option_id": "c1"})
+    assert await adapter._consume_prompt_response(event) is True
+    assert resolved == [("cl-9", "beta")]
+
+    # "Other" flips to text capture.
+    await adapter.send_clarify("c1", "Which?", ["a"], "cl-10", "s")
+    prompt_id2 = stub.sent[-1]["prompt_id"]
+    event2 = _event({"prompt_id": prompt_id2, "option_id": "other"})
+    assert await adapter._consume_prompt_response(event2) is True
+    assert marked == ["cl-10"]
+
+
+@pytest.mark.asyncio
+async def test_unknown_or_expired_prompt_falls_through():
+    adapter, _stub = _adapter()
+    event = _event({"prompt_id": "deadbeef", "option_id": "once"})
+    assert await adapter._consume_prompt_response(event) is False
+    assert await adapter._consume_prompt_response(_event(None)) is False
+    # Malformed shapes never consume.
+    assert await adapter._consume_prompt_response(_event({"prompt_id": ""})) is False
+
+
+# ── Discord type-3 hp1 decode ────────────────────────────────────────────
+
+
+def test_discord_component_interaction_decodes_prompt_token():
+    adapter, _stub = _adapter()
+
+    class Forward:
+        platform = "discord"
+        method = "POST"
+        path = "/interactions/bot1"
+        body = (
+            b'{"type": 3, "id": "i1", "channel_id": "ch1", "guild_id": "g1",'
+            b' "message": {"id": "pm55"},'
+            b' "member": {"user": {"id": "u1", "username": "ben"}},'
+            b' "data": {"custom_id": "hp1:a1b2c3d4:deny"}}'
+        )
+
+    event = adapter._discord_interaction_to_event(Forward())
+    assert event is not None
+    assert event.prompt_response == {
+        "prompt_id": "a1b2c3d4",
+        "option_id": "deny",
+        "prompt_message_id": "pm55",
+    }
+    assert event.text == "/deny"
+    assert event.message_type == MessageType.COMMAND
+
+
+def test_discord_foreign_custom_id_keeps_legacy_text_shape():
+    adapter, _stub = _adapter()
+
+    class Forward:
+        platform = "discord"
+        method = "POST"
+        path = "/interactions/bot1"
+        body = (
+            b'{"type": 3, "id": "i1", "channel_id": "ch1", "guild_id": "g1",'
+            b' "data": {"custom_id": "someones_button"}}'
+        )
+
+    event = adapter._discord_interaction_to_event(Forward())
+    assert event is not None
+    assert event.prompt_response is None
+    assert event.text == "someones_button"
+    assert event.message_type == MessageType.TEXT
+
+
+def test_decode_prompt_token_matches_connector_codec():
+    adapter, _stub = _adapter()
+    assert adapter._decode_prompt_token("hp1:p1:deny") == ("p1", "deny")
+    assert adapter._decode_prompt_token("ea:once:3") is None
+    assert adapter._decode_prompt_token("hp1:p1") is None
+    assert adapter._decode_prompt_token("hp1:bad id:x") is None
+    assert adapter._decode_prompt_token("") is None
+
+
+# ── react ack lifecycle ──────────────────────────────────────────────────
+
+
+def _reactable_event() -> MessageEvent:
+    return MessageEvent(
+        text="do something",
+        message_type=MessageType.TEXT,
+        source=SessionSource(
+            platform="discord",
+            chat_id="ch1",
+            chat_type="channel",
+            user_id="u1",
+            message_id="m42",
+        ),
+        message_id="m42",
+    )
+
+
+@pytest.mark.asyncio
+async def test_processing_lifecycle_reacts_eyes_then_check():
+    adapter, stub = _adapter()
+    event = _reactable_event()
+    await adapter.on_processing_start(event)
+    await adapter.on_processing_complete(event, ProcessingOutcome.SUCCESS)
+    reacts = [a for a in stub.sent if a["op"] == "react"]
+    assert [(r["emoji"], r.get("remove", False)) for r in reacts] == [
+        ("👀", False),
+        ("👀", True),
+        ("✅", False),
+    ]
+    assert all(r["message_id"] == "m42" and r["chat_id"] == "ch1" for r in reacts)
+
+
+@pytest.mark.asyncio
+async def test_processing_failure_reacts_cross():
+    adapter, stub = _adapter()
+    event = _reactable_event()
+    await adapter.on_processing_complete(event, ProcessingOutcome.FAILURE)
+    emojis = [a["emoji"] for a in stub.sent if a["op"] == "react"]
+    assert emojis[-1] == "❌"
+
+
+@pytest.mark.asyncio
+async def test_react_is_op_gated_and_best_effort():
+    adapter, stub = _adapter(supported_ops=("send", "edit", "typing"))
+    event = _reactable_event()
+    await adapter.on_processing_start(event)
+    await adapter.on_processing_complete(event, ProcessingOutcome.SUCCESS)
+    assert all(a["op"] != "react" for a in stub.sent)  # never hit the wire
+    # And a connector decline never raises.
+    adapter2, stub2 = _adapter()
+    stub2.next_react_result = {"success": False, "error": "nope"}
+    await adapter2.on_processing_start(event)  # must not raise
+
+
+@pytest.mark.asyncio
+async def test_cancelled_outcome_removes_eyes_without_verdict():
+    adapter, stub = _adapter()
+    event = _reactable_event()
+    await adapter.on_processing_complete(event, ProcessingOutcome.CANCELLED)
+    reacts = [(a["emoji"], a.get("remove", False)) for a in stub.sent if a["op"] == "react"]
+    assert reacts == [("👀", True)]  # eyes removed, no ✅/❌
diff --git a/tests/gateway/relay/test_relay_media.py b/tests/gateway/relay/test_relay_media.py
new file mode 100644
index 00000000000..c49afc0a192
--- /dev/null
+++ b/tests/gateway/relay/test_relay_media.py
@@ -0,0 +1,283 @@
+"""Relay Phase 2 media tests — send_media egress lanes + inbound media localization.
+
+Covers:
+  - the five ``send_*`` overrides route through ONE ``send_media`` op with the
+    right ``media_kind`` and honor op-level capability gating (a connector not
+    advertising ``send_media`` falls back to the base-class behaviour);
+  - local-path sources upload through the RelayMediaClient first (the
+    connector cannot reach our filesystem) and public URLs pass through;
+  - a connector decline / failed upload degrades to the pre-media fallback;
+  - inbound ``media_urls`` are localized to temp paths (re-hosts downloaded
+    with the per-gateway bearer; dead re-host refs dropped; public URLs kept
+    when no client is available);
+  - the RelayMediaClient URL derivation + auth header shape.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import pytest
+
+from gateway.config import PlatformConfig
+from gateway.relay.adapter import RelayAdapter
+from gateway.relay.descriptor import CONTRACT_VERSION, CapabilityDescriptor
+from gateway.relay.media import RelayMediaClient, media_base_url
+
+from tests.gateway.relay.stub_connector import StubConnector
+
+
+def make_desc(**kw) -> CapabilityDescriptor:
+    base = dict(
+        contract_version=CONTRACT_VERSION,
+        platform="telegram",
+        label="Telegram",
+        max_message_length=4096,
+        supports_draft_streaming=False,
+        supports_edit=True,
+        supports_threads=True,
+        markdown_dialect="markdown_v2",
+        len_unit="utf16",
+        supported_ops=(
+            "send",
+            "edit",
+            "typing",
+            "get_chat_info",
+            "send_media",
+        ),
+    )
+    base.update(kw)
+    return CapabilityDescriptor(**base)
+
+
+class FakeMediaClient:
+    """In-memory stand-in for RelayMediaClient (no HTTP)."""
+
+    def __init__(self) -> None:
+        self.enabled = True
+        self.uploads: list[tuple[str, Optional[str]]] = []
+        self.downloads: list[str] = []
+        self.upload_result: Optional[str] = "https://conn.example/relay/media/aa11"
+        self.download_result: Optional[str] = "/tmp/relay_media_fake.png"
+
+    async def upload(self, file_path, *, mime=None, filename=None):
+        self.uploads.append((str(file_path), filename))
+        return self.upload_result
+
+    async def download(self, url, *, suggested_name=None):
+        self.downloads.append(url)
+        return self.download_result
+
+    def is_relay_media_url(self, url: str) -> bool:
+        return "/relay/media/" in (url or "")
+
+
+def _adapter(**desc_kw) -> tuple[RelayAdapter, StubConnector, FakeMediaClient]:
+    stub = StubConnector(make_desc(**desc_kw))
+    adapter = RelayAdapter(PlatformConfig(), make_desc(**desc_kw), transport=stub)
+    fake = FakeMediaClient()
+    adapter._media_client = fake  # bypass env-derived construction
+    return adapter, stub, fake
+
+
+# ── egress: the five overrides ───────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_send_image_url_passes_through_without_upload():
+    adapter, stub, fake = _adapter()
+    result = await adapter.send_image(
+        "chat1", "https://fal.media/x.png", caption="a pic", reply_to="m9"
+    )
+    assert result.success is True
+    assert result.message_id == "md1"
+    assert fake.uploads == []  # public URL → no upload leg
+    action = stub.sent[-1]
+    assert action["op"] == "send_media"
+    assert action["media_kind"] == "image"
+    assert action["source_url"] == "https://fal.media/x.png"
+    assert action["content"] == "a pic"
+    assert action["reply_to"] == "m9"
+
+
+@pytest.mark.asyncio
+async def test_local_path_lanes_upload_first(tmp_path: Path):
+    adapter, stub, fake = _adapter()
+    f = tmp_path / "clip.ogg"
+    f.write_bytes(b"oggbytes")
+    result = await adapter.send_voice("chat1", str(f), caption="listen")
+    assert result.success is True
+    assert fake.uploads == [(str(f), None)]
+    action = stub.sent[-1]
+    assert action["op"] == "send_media"
+    assert action["media_kind"] == "voice"
+    # The wire carries the RE-HOST reference, never the local path.
+    assert action["source_url"] == fake.upload_result
+    assert str(f) not in str(action)
+
+
+@pytest.mark.asyncio
+async def test_each_override_maps_to_its_media_kind(tmp_path: Path):
+    adapter, stub, fake = _adapter()
+    f = tmp_path / "x.bin"
+    f.write_bytes(b"data")
+    await adapter.send_image_file("c", str(f))
+    await adapter.send_voice("c", str(f))
+    await adapter.send_video("c", str(f))
+    await adapter.send_document("c", str(f), file_name="report.pdf")
+    kinds = [a["media_kind"] for a in stub.sent if a["op"] == "send_media"]
+    assert kinds == ["image", "voice", "video", "document"]
+    doc_action = stub.sent[-1]
+    assert doc_action["filename"] == "report.pdf"
+    # The document upload passed the user-facing filename through.
+    assert fake.uploads[-1] == (str(f), "report.pdf")
+
+
+@pytest.mark.asyncio
+async def test_op_gating_falls_back_when_not_advertised(tmp_path: Path):
+    # Connector advertises only the legacy ops — send_media must never hit the wire.
+    adapter, stub, fake = _adapter(
+        supported_ops=("send", "edit", "typing", "get_chat_info")
+    )
+    result = await adapter.send_image("chat1", "https://x.io/a.png", caption="hi")
+    # Base-class fallback: caption + URL as a text send.
+    assert result.success is True
+    ops = [a["op"] for a in stub.sent]
+    assert "send_media" not in ops
+    assert ops[-1] == "send"
+    assert "https://x.io/a.png" in stub.sent[-1]["content"]
+
+
+@pytest.mark.asyncio
+async def test_legacy_empty_ops_also_gates_send_media():
+    # An empty supported_ops = legacy connector; send_media is NOT in LEGACY_OPS.
+    adapter, stub, _fake = _adapter(supported_ops=())
+    await adapter.send_image("chat1", "https://x.io/a.png")
+    assert all(a["op"] != "send_media" for a in stub.sent)
+
+
+@pytest.mark.asyncio
+async def test_connector_decline_degrades_to_fallback(tmp_path: Path):
+    adapter, stub, fake = _adapter()
+    stub.next_media_result = {"success": False, "error": "media too large"}
+    f = tmp_path / "big.mp4"
+    f.write_bytes(b"x")
+    result = await adapter.send_video("chat1", str(f), caption="cap")
+    # The video lane failed → base fallback notice still delivers (a send op).
+    assert result.success is True
+    assert stub.sent[-1]["op"] == "send"
+    assert "cap" in stub.sent[-1]["content"]
+    # And the local path never leaked into the fallback text.
+    assert str(f) not in stub.sent[-1]["content"]
+
+
+@pytest.mark.asyncio
+async def test_failed_upload_degrades_to_fallback(tmp_path: Path):
+    adapter, stub, fake = _adapter()
+    fake.upload_result = None  # upload leg fails
+    f = tmp_path / "pic.png"
+    f.write_bytes(b"png")
+    result = await adapter.send_image_file("chat1", str(f))
+    assert result.success is True
+    assert all(a["op"] != "send_media" for a in stub.sent)
+
+
+@pytest.mark.asyncio
+async def test_scope_metadata_rides_send_media(tmp_path: Path):
+    """The egress guard resolves tenants from metadata — send_media must carry
+    the same scope/user discriminators a plain send does."""
+    adapter, stub, fake = _adapter()
+    adapter._scope_by_chat["chat1"] = "guild9"
+    await adapter.send_image("chat1", "https://x.io/p.png")
+    action = stub.sent[-1]
+    assert action["op"] == "send_media"
+    assert (action.get("metadata") or {}).get("scope_id") == "guild9"
+
+
+# ── inbound localization ─────────────────────────────────────────────────
+
+
+def _make_event(media_urls):
+    from gateway.platforms.base import MessageEvent, MessageType
+    from gateway.session import SessionSource
+
+    return MessageEvent(
+        text="look",
+        message_type=MessageType.TEXT,
+        source=SessionSource(
+            platform="telegram", chat_id="c1", chat_type="dm", user_id="u1"
+        ),
+        media_urls=list(media_urls),
+    )
+
+
+@pytest.mark.asyncio
+async def test_inbound_rehost_urls_are_localized():
+    adapter, _stub, fake = _adapter()
+    event = _make_event(["https://conn.example/relay/media/deadbeef"])
+    await adapter._localize_inbound_media(event)
+    assert fake.downloads == ["https://conn.example/relay/media/deadbeef"]
+    assert event.media_urls == ["/tmp/relay_media_fake.png"]
+
+
+@pytest.mark.asyncio
+async def test_inbound_dead_rehost_ref_is_dropped_public_url_kept():
+    adapter, _stub, fake = _adapter()
+    fake.download_result = None  # every download fails
+    event = _make_event(
+        [
+            "https://conn.example/relay/media/deadbeef",  # dead re-host → dropped
+            "https://cdn.discordapp.com/attachments/a/b.png",  # public → kept as URL
+        ]
+    )
+    await adapter._localize_inbound_media(event)
+    assert event.media_urls == ["https://cdn.discordapp.com/attachments/a/b.png"]
+
+
+@pytest.mark.asyncio
+async def test_inbound_without_client_keeps_public_drops_rehost():
+    adapter, _stub, _fake = _adapter()
+    adapter._media_client = None
+    adapter._get_media_client = lambda: None  # type: ignore[method-assign]
+    event = _make_event(
+        [
+            "https://conn.example/relay/media/deadbeef",
+            "https://cdn.discordapp.com/attachments/a/b.png",
+        ]
+    )
+    await adapter._localize_inbound_media(event)
+    assert event.media_urls == ["https://cdn.discordapp.com/attachments/a/b.png"]
+
+
+# ── RelayMediaClient unit surface ────────────────────────────────────────
+
+
+def test_media_base_url_derivation():
+    assert media_base_url("wss://conn.example/relay") == "https://conn.example"
+    assert media_base_url("ws://localhost:8080/relay") == "http://localhost:8080"
+    assert media_base_url("https://conn.example") == "https://conn.example"
+
+
+def test_client_enabled_requires_full_credentials():
+    assert RelayMediaClient("https://c.example", "gw1", "sec").enabled is True
+    assert RelayMediaClient("https://c.example", None, "sec").enabled is False
+    assert RelayMediaClient("https://c.example", "gw1", None).enabled is False
+    assert RelayMediaClient("", "gw1", "sec").enabled is False
+
+
+def test_client_recognizes_rehost_urls():
+    c = RelayMediaClient("https://c.example", "gw1", "sec")
+    assert c.is_relay_media_url("https://c.example/relay/media/abc") is True
+    assert c.is_relay_media_url("https://cdn.discordapp.com/a/b.png") is False
+
+
+@pytest.mark.asyncio
+async def test_client_upload_rejects_oversize_and_missing(tmp_path: Path):
+    c = RelayMediaClient("https://c.example", "gw1", "sec")
+    # Missing file → None (no network attempted).
+    assert await c.upload(str(tmp_path / "nope.bin")) is None
+    # Empty file → None.
+    empty = tmp_path / "empty.bin"
+    empty.write_bytes(b"")
+    assert await c.upload(str(empty)) is None
diff --git a/tests/gateway/relay/test_relay_passthrough.py b/tests/gateway/relay/test_relay_passthrough.py
index f59a6d6aee5..21c0c7060e2 100644
--- a/tests/gateway/relay/test_relay_passthrough.py
+++ b/tests/gateway/relay/test_relay_passthrough.py
@@ -118,7 +118,11 @@ async def test_discord_interaction_routes_through_handle_message(adapter, monkey
 
     assert len(seen) == 1
     ev = seen[0]
-    assert ev.text == "summarize"
+    # APPLICATION_COMMAND interactions are normalized to a leading-slash
+    # command (the dispatcher's contract), not the bare registered name.
+    assert ev.text == "/summarize"
+    assert ev.is_command() is True
+    assert ev.get_command() == "summarize"
     assert ev.source.chat_id == "chan-9"
     assert ev.source.scope_id == "guild-7"
     assert ev.source.user_id == "user-3"
@@ -151,6 +155,147 @@ async def test_message_component_interaction_uses_custom_id(adapter, monkeypatch
     await stub.push_passthrough(fwd)
     assert len(seen) == 1
     assert seen[0].text == "approve_btn"
+    # Component interactions stay plain text — only APPLICATION_COMMANDs are
+    # normalized to slash commands.
+    assert seen[0].is_command() is False
+
+
+@pytest.mark.asyncio
+async def test_application_command_no_options_is_slash_command(adapter, monkeypatch):
+    """/new with no options -> text '/new', dispatched as a COMMAND event."""
+    from gateway.platforms.base import MessageType
+
+    await adapter.connect()
+    stub = adapter._transport
+    seen = []
+
+    async def fake_handle(event):
+        seen.append(event)
+
+    monkeypatch.setattr(adapter, "handle_message", fake_handle)
+    fwd = _interaction_forward(
+        {
+            "id": "i-new",
+            "type": 2,
+            "channel_id": "c3",
+            "guild_id": "g3",
+            "data": {"name": "new"},
+            "member": {"user": {"id": "u3", "username": "ben"}},
+        }
+    )
+    await stub.push_passthrough(fwd)
+    assert len(seen) == 1
+    ev = seen[0]
+    assert ev.text == "/new"
+    assert ev.message_type == MessageType.COMMAND
+    # Behavior contract: the dispatcher must recognize this as command 'new'.
+    assert ev.is_command() is True
+    assert ev.get_command() == "new"
+    assert ev.get_command_args() == ""
+
+
+@pytest.mark.asyncio
+async def test_application_command_scalar_options_append_values(adapter, monkeypatch):
+    """Scalar options append their values space-separated: /model gpt-x."""
+    await adapter.connect()
+    stub = adapter._transport
+    seen = []
+
+    async def fake_handle(event):
+        seen.append(event)
+
+    monkeypatch.setattr(adapter, "handle_message", fake_handle)
+    fwd = _interaction_forward(
+        {
+            "id": "i-model",
+            "type": 2,
+            "channel_id": "c4",
+            "guild_id": "g4",
+            "data": {
+                "name": "model",
+                "options": [{"name": "name", "type": 3, "value": "gpt-x"}],
+            },
+            "member": {"user": {"id": "u4", "username": "ben"}},
+        }
+    )
+    await stub.push_passthrough(fwd)
+    assert len(seen) == 1
+    ev = seen[0]
+    assert ev.text == "/model gpt-x"
+    assert ev.is_command() is True
+    assert ev.get_command() == "model"
+    assert ev.get_command_args() == "gpt-x"
+
+
+@pytest.mark.asyncio
+async def test_application_command_subcommand_nesting_renders_names_then_values(
+    adapter, monkeypatch
+):
+    """SUB_COMMAND (type 1) appends its name, then recurses into its options."""
+    await adapter.connect()
+    stub = adapter._transport
+    seen = []
+
+    async def fake_handle(event):
+        seen.append(event)
+
+    monkeypatch.setattr(adapter, "handle_message", fake_handle)
+    fwd = _interaction_forward(
+        {
+            "id": "i-sub",
+            "type": 2,
+            "channel_id": "c5",
+            "guild_id": "g5",
+            "data": {
+                "name": "skill",
+                "options": [
+                    {
+                        "name": "run",
+                        "type": 1,  # SUB_COMMAND
+                        "options": [{"name": "target", "type": 3, "value": "deploy"}],
+                    }
+                ],
+            },
+            "member": {"user": {"id": "u5", "username": "ben"}},
+        }
+    )
+    await stub.push_passthrough(fwd)
+    assert len(seen) == 1
+    ev = seen[0]
+    assert ev.text == "/skill run deploy"
+    assert ev.is_command() is True
+    assert ev.get_command() == "skill"
+    assert ev.get_command_args() == "run deploy"
+
+
+@pytest.mark.asyncio
+async def test_ping_interaction_produces_no_command(adapter, monkeypatch):
+    """A PING (type 1) body — never normally forwarded — stays empty TEXT, not
+    a phantom command."""
+    from gateway.platforms.base import MessageType
+
+    await adapter.connect()
+    stub = adapter._transport
+    seen = []
+
+    async def fake_handle(event):
+        seen.append(event)
+
+    monkeypatch.setattr(adapter, "handle_message", fake_handle)
+    fwd = _interaction_forward(
+        {
+            "id": "i-ping",
+            "type": 1,  # PING
+            "channel_id": "c6",
+            "user": {"id": "u6", "username": "ben"},
+        }
+    )
+    await stub.push_passthrough(fwd)
+    assert len(seen) == 1
+    ev = seen[0]
+    assert ev.text == ""
+    assert ev.message_type == MessageType.TEXT
+    assert ev.is_command() is False
 
 
 @pytest.mark.asyncio
diff --git a/tests/gateway/relay/test_relay_roundtrip.py b/tests/gateway/relay/test_relay_roundtrip.py
index c80571786af..db2947950da 100644
--- a/tests/gateway/relay/test_relay_roundtrip.py
+++ b/tests/gateway/relay/test_relay_roundtrip.py
@@ -20,6 +20,8 @@ from gateway.session import SessionSource, build_session_key
 from gateway.relay.adapter import RelayAdapter
 from gateway.relay.descriptor import CONTRACT_VERSION, CapabilityDescriptor
 
+from dataclasses import replace
+
 from tests.gateway.relay.stub_connector import StubConnector
 
 
@@ -112,6 +114,12 @@ async def test_outbound_send_round_trips(wired):
 @pytest.mark.asyncio
 async def test_get_chat_info_proxied_to_connector(wired):
     adapter, stub = wired
+    # Phase 1: the proxy is gated on op discovery — the connector must
+    # advertise get_chat_info in supported_ops (a legacy descriptor falls
+    # back to the local echo; see test_relay_adapter.py).
+    adapter._apply_descriptor(
+        replace(_discord_descriptor(), supported_ops=("send", "edit", "typing", "get_chat_info"))
+    )
     stub.chat_info["chan1"] = {"name": "general", "type": "group"}
     info = await adapter.get_chat_info("chan1")
     assert info == {"name": "general", "type": "group"}
diff --git a/tests/gateway/relay/test_relay_threads.py b/tests/gateway/relay/test_relay_threads.py
new file mode 100644
index 00000000000..0c7d485d67c
--- /dev/null
+++ b/tests/gateway/relay/test_relay_threads.py
@@ -0,0 +1,308 @@
+"""Relay Phase 4 tests — thread lifecycle ops, reply_to enrichment parse,
+auto-thread markers, and the hello command manifest.
+
+Covers:
+  - create_handoff_thread routes through `thread_create` (op-gated; None
+    fallback contract preserved for the handoff watcher);
+  - rename_thread routes through `thread_rename` with the
+    only_if_current_name guard on the wire (op-gated; False on decline);
+  - the relay semantic-rename lane parity: a relay source carrying the
+    connector-stamped auto-thread markers satisfies the same field contract
+    the native _is_discord_auto_thread_lane reads;
+  - _event_from_wire maps reply_to {text,author,is_own} onto the native
+    MessageEvent reply-context fields and the auto-thread markers onto
+    SessionSource;
+  - the ws transport sends command_manifest on the DISCORD hello only;
+  - the manifest builder satisfies Discord CHAT_INPUT naming rules.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict
+
+import pytest
+
+from gateway.config import PlatformConfig
+from gateway.relay.adapter import RelayAdapter
+from gateway.relay.command_manifest import build_relay_command_manifest
+from gateway.relay.descriptor import CONTRACT_VERSION, CapabilityDescriptor
+from gateway.relay.ws_transport import _event_from_wire
+
+from tests.gateway.relay.stub_connector import StubConnector
+
+FULL_OPS = (
+    "send",
+    "edit",
+    "typing",
+    "get_chat_info",
+    "thread_create",
+    "thread_rename",
+)
+
+
+def make_desc(**kw) -> CapabilityDescriptor:
+    base = dict(
+        contract_version=CONTRACT_VERSION,
+        platform="discord",
+        label="Discord",
+        max_message_length=2000,
+        supports_draft_streaming=False,
+        supports_edit=True,
+        supports_threads=True,
+        markdown_dialect="discord",
+        len_unit="chars",
+        supported_ops=FULL_OPS,
+    )
+    base.update(kw)
+    return CapabilityDescriptor(**base)
+
+
+def _adapter(**desc_kw) -> tuple[RelayAdapter, StubConnector]:
+    stub = StubConnector(make_desc(**desc_kw))
+    adapter = RelayAdapter(PlatformConfig(), make_desc(**desc_kw), transport=stub)
+    return adapter, stub
+
+
+# ── thread_create (handoff) ──────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_create_handoff_thread_routes_thread_create():
+    adapter, stub = _adapter()
+    stub.next_send_result = {"success": True}  # unused; thread op has own arm
+
+    async def send_outbound(action, *, platform=None):
+        stub.sent.append(action)
+        stub.sent_platforms.append(platform)
+        return {"success": True, "thread_id": "th77"}
+
+    stub.send_outbound = send_outbound  # type: ignore[method-assign]
+    thread_id = await adapter.create_handoff_thread("chan1", "fix the build")
+    assert thread_id == "th77"
+    action = stub.sent[-1]
+    assert action["op"] == "thread_create"
+    assert action["chat_id"] == "chan1"
+    assert action["thread_name"] == "fix the build"
+
+
+@pytest.mark.asyncio
+async def test_create_handoff_thread_op_gated_and_decline_safe():
+    # Not advertised → None without touching the wire.
+    adapter, stub = _adapter(supported_ops=("send", "edit", "typing"))
+    assert await adapter.create_handoff_thread("chan1", "x") is None
+    assert stub.sent == []
+    # Advertised but declined (non-forum Telegram chat, missing perms) → None.
+    adapter2, stub2 = _adapter()
+
+    async def declined(action, *, platform=None):
+        stub2.sent.append(action)
+        return {"success": False, "error": "not a forum"}
+
+    stub2.send_outbound = declined  # type: ignore[method-assign]
+    assert await adapter2.create_handoff_thread("chan1", "x") is None
+
+
+@pytest.mark.asyncio
+async def test_create_handoff_thread_falls_back_to_message_id():
+    # Slack shape: the connector returns the seed ts as message_id+thread_id;
+    # older stubs may return only message_id — either resolves.
+    adapter, stub = _adapter()
+
+    async def send_outbound(action, *, platform=None):
+        stub.sent.append(action)
+        return {"success": True, "message_id": "170.001"}
+
+    stub.send_outbound = send_outbound  # type: ignore[method-assign]
+    assert await adapter.create_handoff_thread("C1", "handoff") == "170.001"
+
+
+# ── rename_thread (semantic rename) ──────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_rename_thread_carries_the_no_clobber_guard():
+    adapter, stub = _adapter()
+    ok = await adapter.rename_thread(
+        "th1", "Fix the build", only_if_current_name="Hermes"
+    )
+    assert ok is True
+    action = stub.sent[-1]
+    assert action["op"] == "thread_rename"
+    assert action["message_id"] == "th1"
+    assert action["thread_name"] == "Fix the build"
+    assert action["only_if_current_name"] == "Hermes"
+    # chat_id defaults to the thread id (Discord ignores it; Telegram callers
+    # pass parent_chat_id explicitly).
+    assert action["chat_id"] == "th1"
+
+
+@pytest.mark.asyncio
+async def test_rename_thread_parent_chat_and_gating():
+    adapter, stub = _adapter()
+    await adapter.rename_thread("42", "topic", parent_chat_id="-100999")
+    assert stub.sent[-1]["chat_id"] == "-100999"
+    assert "only_if_current_name" not in stub.sent[-1]
+
+    gated, gated_stub = _adapter(supported_ops=("send",))
+    assert await gated.rename_thread("42", "x") is False
+    assert gated_stub.sent == []
+
+
+@pytest.mark.asyncio
+async def test_rename_thread_decline_returns_false():
+    adapter, stub = _adapter()
+
+    async def declined(action, *, platform=None):
+        stub.sent.append(action)
+        return {"success": False, "error": "guard: current name differs"}
+
+    stub.send_outbound = declined  # type: ignore[method-assign]
+    assert await adapter.rename_thread("th1", "x", only_if_current_name="H") is False
+
+
+# ── the relay semantic-rename lane (marker parity) ───────────────────────
+
+
+def test_relay_source_satisfies_auto_thread_lane_field_contract():
+    """The native lane check reads platform/chat_type/thread_id +
+    auto_thread_created + auto_thread_initial_name off the source. A relay
+    event carrying the connector-stamped markers must present ALL of them
+    through _event_from_wire — same field contract, no relay-specific case.
+    """
+    event = _event_from_wire(
+        {
+            "text": "hi",
+            "message_type": "text",
+            "source": {
+                "platform": "discord",
+                "chat_id": "th9",
+                "chat_type": "thread",
+                "thread_id": "th9",
+                "user_id": "u1",
+                "auto_thread_created": True,
+                "auto_thread_initial_name": "Hermes reply",
+            },
+        }
+    )
+    src = event.source
+    assert src.chat_type == "thread"
+    assert src.thread_id == "th9"
+    assert src.auto_thread_created is True
+    assert src.auto_thread_initial_name == "Hermes reply"
+    # And absent markers default off (never light the lane spuriously).
+    plain = _event_from_wire(
+        {
+            "text": "hi",
+            "message_type": "text",
+            "source": {
+                "platform": "discord",
+                "chat_id": "c",
+                "chat_type": "thread",
+                "thread_id": "t",
+            },
+        }
+    )
+    assert plain.source.auto_thread_created is False
+    assert plain.source.auto_thread_initial_name is None
+
+
+# ── reply_to wire parse ──────────────────────────────────────────────────
+
+
+def test_event_from_wire_maps_reply_to_onto_native_fields():
+    event = _event_from_wire(
+        {
+            "text": "re",
+            "message_type": "text",
+            "source": {"platform": "telegram", "chat_id": "5", "chat_type": "dm"},
+            "reply_to_message_id": "19",
+            "reply_to": {
+                "text": "what the bot said",
+                "author": "hermesbot",
+                "is_own": True,
+            },
+        }
+    )
+    assert event.reply_to_message_id == "19"
+    assert event.reply_to_text == "what the bot said"
+    assert event.reply_to_author_name == "hermesbot"
+    assert event.reply_to_is_own_message is True
+
+
+def test_event_from_wire_reply_to_absent_and_partial():
+    plain = _event_from_wire(
+        {
+            "text": "hi",
+            "message_type": "text",
+            "source": {"platform": "telegram", "chat_id": "5", "chat_type": "dm"},
+        }
+    )
+    assert plain.reply_to_text is None
+    assert plain.reply_to_is_own_message is False
+    partial = _event_from_wire(
+        {
+            "text": "re",
+            "message_type": "text",
+            "source": {"platform": "whatsapp", "chat_id": "1", "chat_type": "dm"},
+            "reply_to_message_id": "wamid.x",
+            "reply_to": {"author": "Alice"},  # text leg missed the cache
+        }
+    )
+    assert partial.reply_to_author_name == "Alice"
+    assert partial.reply_to_text is None
+
+
+# ── hello command manifest ───────────────────────────────────────────────
+
+
+def test_manifest_entries_satisfy_discord_naming_rules():
+    manifest = build_relay_command_manifest()
+    assert len(manifest) > 0
+    assert len(manifest) <= 100  # Discord's global command cap
+    name_re = re.compile(r"^[a-z0-9_-]{1,32}$")
+    seen = set()
+    for entry in manifest:
+        assert name_re.match(entry["name"]), entry["name"]
+        assert 1 <= len(entry["description"]) <= 100, entry["name"]
+        assert entry["name"] not in seen
+        seen.add(entry["name"])
+        for opt in entry.get("options", []):
+            assert name_re.match(opt["name"])
+            assert 1 <= len(opt["description"]) <= 100
+
+
+def test_manifest_mirrors_the_native_slash_surface():
+    # Behavior contract (not a change-detector): every manifest name must be
+    # a command the dispatcher actually routes — spot-check the core set the
+    # native Discord tree registers.
+    names = {e["name"] for e in build_relay_command_manifest()}
+    for core in ("new", "reset", "model", "approve", "deny", "stop", "help"):
+        assert core in names
+
+
+@pytest.mark.asyncio
+async def test_hello_carries_manifest_for_discord_only():
+    from gateway.relay.ws_transport import WebSocketRelayTransport
+
+    sent: list[Dict[str, Any]] = []
+    transport = WebSocketRelayTransport.__new__(WebSocketRelayTransport)
+    transport._identities = [("discord", "app1"), ("telegram", "tg1")]
+
+    async def fake_send(frame):
+        sent.append(frame)
+
+    transport._send = fake_send  # type: ignore[method-assign]
+
+    # Drive just the hello loop body (connect()'s tail) — the socket plumbing
+    # above it is exercised by the existing transport tests.
+    for platform, bot_id in transport._identities:
+        hello: Dict[str, Any] = {"type": "hello", "platform": platform, "botId": bot_id}
+        if platform == "discord":
+            hello["command_manifest"] = build_relay_command_manifest()
+        await transport._send(hello)
+
+    assert sent[0]["platform"] == "discord"
+    assert "command_manifest" in sent[0]
+    assert sent[1]["platform"] == "telegram"
+    assert "command_manifest" not in sent[1]
diff --git a/tests/gateway/relay/test_self_provision.py b/tests/gateway/relay/test_self_provision.py
index 579f172e028..977fc3df603 100644
--- a/tests/gateway/relay/test_self_provision.py
+++ b/tests/gateway/relay/test_self_provision.py
@@ -375,3 +375,107 @@ def test_connector_failure_is_non_fatal(monkeypatch):
     monkeypatch.setattr(relay, "_post_provision", _boom)
     assert relay.self_provision_relay() is False
     assert relay.relay_connection_auth() == (None, None)
+
+
+# ─────────────────────────── displayName (Phase 1 parity, gg#171) ───────────────────────────
+
+def test_relay_display_name_env_wins(monkeypatch):
+    monkeypatch.setenv("GATEWAY_RELAY_DISPLAY_NAME", "  Atlas  ")
+    assert relay.relay_display_name() == "Atlas"
+
+
+def test_relay_display_name_caps_at_64(monkeypatch):
+    monkeypatch.setenv("GATEWAY_RELAY_DISPLAY_NAME", "x" * 200)
+    assert relay.relay_display_name() == "x" * 64
+
+
+def test_relay_display_name_falls_back_to_skin_branding(monkeypatch):
+    monkeypatch.delenv("GATEWAY_RELAY_DISPLAY_NAME", raising=False)
+
+    class _Skin:
+        def get_branding(self, key, fallback=""):
+            return "Chatterbox" if key == "agent_name" else fallback
+
+    monkeypatch.setattr("hermes_cli.skin_engine.get_active_skin", lambda: _Skin())
+    assert relay.relay_display_name() == "Chatterbox"
+
+
+def test_relay_display_name_suppresses_stock_brand(monkeypatch):
+    """The default 'Hermes Agent' brand is identical on every install — forwarding
+    it would shadow the connector's linked-owner fallback (which actually
+    disambiguates) with a uniform label. Only customized names are forwarded."""
+    monkeypatch.delenv("GATEWAY_RELAY_DISPLAY_NAME", raising=False)
+
+    class _Skin:
+        def get_branding(self, key, fallback=""):
+            return "Hermes Agent" if key == "agent_name" else fallback
+
+    monkeypatch.setattr("hermes_cli.skin_engine.get_active_skin", lambda: _Skin())
+    assert relay.relay_display_name() is None
+
+
+def test_relay_display_name_branding_failure_is_non_fatal(monkeypatch):
+    monkeypatch.delenv("GATEWAY_RELAY_DISPLAY_NAME", raising=False)
+
+    def _boom():
+        raise RuntimeError("no skin engine")
+
+    monkeypatch.setattr("hermes_cli.skin_engine.get_active_skin", _boom)
+    assert relay.relay_display_name() is None
+
+
+def test_self_provision_forwards_display_name(monkeypatch):
+    _arm(monkeypatch)
+    monkeypatch.setenv("GATEWAY_RELAY_DISPLAY_NAME", "Atlas")
+    captured: dict = {}
+    monkeypatch.setattr(relay, "_post_provision", _stub_post(captured))
+
+    assert relay.self_provision_relay() is True
+    assert captured["display_name"] == "Atlas"
+
+
+def test_post_provision_body_includes_displayName_only_when_set(monkeypatch):
+    """`displayName` joins the body ONLY when a value is supplied — omitting it
+    lets the connector store null (attribution falls back to linked-owner)."""
+    import json
+
+    sent: dict = {}
+
+    class _Resp:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def read(self):
+            return json.dumps({"secret": "a" * 64, "deliveryKey": "b" * 64, "tenant": "t", "gatewayId": "gw-1"}).encode()
+
+    def _fake_urlopen(req, timeout=None):  # noqa: ANN001
+        sent["body"] = json.loads(req.data.decode())
+        return _Resp()
+
+    monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen)
+
+    relay._post_provision(
+        provision_url="https://c.example/relay/provision",
+        access_token="tok",
+        gateway_id="gw-1",
+        platform="discord",
+        bot_id="app",
+        gateway_endpoint=None,
+        route_keys=[],
+        display_name="Atlas",
+    )
+    assert sent["body"]["displayName"] == "Atlas"
+
+    relay._post_provision(
+        provision_url="https://c.example/relay/provision",
+        access_token="tok",
+        gateway_id="gw-1",
+        platform="discord",
+        bot_id="app",
+        gateway_endpoint=None,
+        route_keys=[],
+    )
+    assert "displayName" not in sent["body"]
diff --git a/tests/gateway/relay/test_wire_user_identity.py b/tests/gateway/relay/test_wire_user_identity.py
new file mode 100644
index 00000000000..5b05bed443d
--- /dev/null
+++ b/tests/gateway/relay/test_wire_user_identity.py
@@ -0,0 +1,68 @@
+"""Unit tests for relay wire-field hygiene (Phase 1 parity).
+
+Covers _event_from_wire's consumption of the contract §3 user-identity
+enrichment fields the connector has always sent but the gateway used to drop:
+
+  - ``user_display_name`` — the human-facing display name (native parity: the
+    native Discord adapter surfaces ``message.author.display_name`` as
+    ``user_name``).
+  - ``user_handle`` — the raw platform handle, used only as a last resort.
+
+Precedence: user_display_name > user_name > user_handle. Session keys derive
+from user_id (never user_name), so this mapping is presentation-only and must
+remain key-stable — asserted here via build_session_key.
+
+Pure unit tests: no socket, no websockets dependency.
+"""
+
+from __future__ import annotations
+
+from gateway.relay.ws_transport import _event_from_wire
+from gateway.session import build_session_key
+
+
+def _wire_event(**src_overrides):
+    src = {
+        "platform": "discord",
+        "chat_id": "chan-1",
+        "chat_type": "group",
+        "user_id": "u-1",
+        "user_name": "rawusername",
+        "scope_id": "guild-1",
+    }
+    src.update(src_overrides)
+    return {"text": "hello", "message_type": "text", "source": src}
+
+
+class TestUserIdentityEnrichment:
+    def test_display_name_preferred_over_user_name(self):
+        ev = _event_from_wire(_wire_event(user_display_name="Ben Display"))
+        assert ev.source.user_name == "Ben Display"
+
+    def test_user_name_when_no_display_name(self):
+        ev = _event_from_wire(_wire_event())
+        assert ev.source.user_name == "rawusername"
+
+    def test_handle_is_last_resort(self):
+        ev = _event_from_wire(
+            _wire_event(user_name=None, user_handle="ben#1234")
+        )
+        assert ev.source.user_name == "ben#1234"
+
+    def test_all_absent_yields_none(self):
+        ev = _event_from_wire(_wire_event(user_name=None))
+        assert ev.source.user_name is None
+
+    def test_empty_display_name_falls_through(self):
+        """An empty-string enrichment must not shadow a real user_name."""
+        ev = _event_from_wire(_wire_event(user_display_name=""))
+        assert ev.source.user_name == "rawusername"
+
+    def test_session_key_is_stable_across_name_shapes(self):
+        """user_name is presentation-only: the same user_id keys the same
+        session whether or not the connector sent the enrichment fields."""
+        plain = _event_from_wire(_wire_event())
+        enriched = _event_from_wire(
+            _wire_event(user_display_name="Ben Display", user_handle="ben#1234")
+        )
+        assert build_session_key(plain.source) == build_session_key(enriched.source)
diff --git a/tests/gateway/test_api_server.py b/tests/gateway/test_api_server.py
index 7ed7d66be6a..347dc423a86 100644
--- a/tests/gateway/test_api_server.py
+++ b/tests/gateway/test_api_server.py
@@ -16,7 +16,9 @@ import asyncio
 import json
 import os
 import stat
+import sys
 import time
+import types
 import uuid
 from unittest.mock import AsyncMock, MagicMock, patch
 
@@ -32,6 +34,7 @@ from gateway.platforms.api_server import (
     _derive_chat_session_id,
     _hermes_version,
     _redact_api_error_text,
+    _request_agent_overrides,
     check_api_server_requirements,
     cors_middleware,
     security_headers_middleware,
@@ -658,9 +661,12 @@ def _create_app(adapter: APIServerAdapter) -> web.Application:
     app.router.add_get("/health/detailed", adapter._handle_health_detailed)
     app.router.add_get("/v1/health", adapter._handle_health)
     app.router.add_get("/v1/models", adapter._handle_models)
+    app.router.add_get("/api/model/options", adapter._handle_model_options)
     app.router.add_get("/v1/capabilities", adapter._handle_capabilities)
     app.router.add_get("/v1/skills", adapter._handle_skills)
     app.router.add_get("/v1/toolsets", adapter._handle_toolsets)
+    app.router.add_post("/api/sessions/{session_id}/chat", adapter._handle_session_chat)
+    app.router.add_post("/api/sessions/{session_id}/chat/stream", adapter._handle_session_chat_stream)
     app.router.add_post("/v1/chat/completions", adapter._handle_chat_completions)
     app.router.add_post("/v1/responses", adapter._handle_responses)
     app.router.add_get("/v1/responses/{response_id}", adapter._handle_get_response)
@@ -711,11 +717,15 @@ class TestAgentExecution:
         mock_agent.session_completion_tokens = 2
         mock_agent.session_total_tokens = 3
 
-        with patch.object(adapter, "_create_agent", return_value=mock_agent):
+        model_options = {"reasoning": {"enabled": False}, "fast": False}
+        with patch.object(adapter, "_create_agent", return_value=mock_agent) as mock_create_agent:
             result, usage = await adapter._run_agent(
                 user_message="hello",
                 conversation_history=[],
                 session_id="session-123",
+                requested_model="MiniMax-M3",
+                requested_provider="minimax",
+                model_options=model_options,
             )
 
         # _run_agent annotates result with the effective agent.session_id
@@ -725,12 +735,161 @@ class TestAgentExecution:
         # the annotation — header will fall back to the provided session_id.
         assert result["final_response"] == "ok"
         assert usage == {"input_tokens": 1, "output_tokens": 2, "total_tokens": 3}
+        create_kwargs = mock_create_agent.call_args.kwargs
+        assert create_kwargs["requested_model"] == "MiniMax-M3"
+        assert create_kwargs["requested_provider"] == "minimax"
+        assert create_kwargs["model_options"] == model_options
         mock_agent.run_conversation.assert_called_once_with(
             user_message="hello",
             conversation_history=[],
             task_id="session-123",
         )
 
+    def test_create_agent_honors_request_model_provider_and_options(self, adapter, monkeypatch):
+        import gateway.run as gateway_run
+        import hermes_cli.runtime_provider as runtime_provider
+        import hermes_cli.tools_config as tools_config
+
+        class _CapturingAgent:
+            last_kwargs = None
+
+            def __init__(self, **kwargs):
+                type(self).last_kwargs = dict(kwargs)
+
+        fake_run_agent = types.ModuleType("run_agent")
+        fake_run_agent.AIAgent = _CapturingAgent
+        monkeypatch.setitem(sys.modules, "run_agent", fake_run_agent)
+
+        monkeypatch.setattr(gateway_run, "_current_max_iterations", lambda: 7)
+        monkeypatch.setattr(gateway_run, "_resolve_gateway_model", lambda: "gpt-5.5")
+        monkeypatch.setattr(gateway_run, "_load_gateway_config", lambda: {})
+        monkeypatch.setattr(
+            gateway_run,
+            "_resolve_runtime_agent_kwargs",
+            lambda: {
+                "api_key": "codex-key",
+                "base_url": "https://chatgpt.com/backend-api/codex",
+                "provider": "openai-codex",
+                "api_mode": "codex_responses",
+                "command": None,
+                "args": [],
+                "credential_pool": None,
+                "max_tokens": None,
+            },
+        )
+        monkeypatch.setattr(gateway_run.GatewayRunner, "_load_reasoning_config", staticmethod(lambda: {"enabled": True, "effort": "medium"}))
+        monkeypatch.setattr(gateway_run.GatewayRunner, "_load_fallback_model", staticmethod(lambda: None))
+        monkeypatch.setattr(tools_config, "_get_platform_tools", lambda _cfg, _platform: {"web"})
+        monkeypatch.setattr(adapter, "_ensure_session_db", lambda: None)
+
+        def _fake_resolve_runtime_provider(*, requested=None, target_model=None, **_kwargs):
+            assert requested == "minimax"
+            assert target_model == "MiniMax-M3"
+            return {
+                "api_key": "minimax-key",
+                "base_url": "https://api.minimax.io/v1",
+                "provider": "minimax",
+                "api_mode": "anthropic_messages",
+                "command": None,
+                "args": [],
+                "credential_pool": None,
+                "max_output_tokens": 32000,
+            }
+
+        monkeypatch.setattr(runtime_provider, "resolve_runtime_provider", _fake_resolve_runtime_provider)
+        monkeypatch.setattr(runtime_provider, "_get_model_config", lambda: {})
+
+        adapter._create_agent(
+            session_id="session-123",
+            requested_model="MiniMax-M3",
+            requested_provider="minimax",
+            model_options={
+                "reasoning": {"enabled": True, "effort": "high"},
+                "reasoning_effort": "high",
+                "fast": True,
+            },
+        )
+
+        kwargs = _CapturingAgent.last_kwargs
+        assert kwargs is not None
+        assert kwargs["model"] == "MiniMax-M3"
+        assert kwargs["provider"] == "minimax"
+        assert kwargs["api_mode"] == "anthropic_messages"
+        assert kwargs["base_url"] == "https://api.minimax.io/v1"
+        assert kwargs["api_key"] == "minimax-key"
+        assert kwargs["max_tokens"] == 32000
+        assert kwargs["reasoning_config"] == {"enabled": True, "effort": "high"}
+        assert kwargs["service_tier"] == "priority"
+        assert kwargs["enabled_toolsets"] == ["web"]
+
+    def test_create_agent_session_override_beats_request_and_route_but_keeps_model_options(
+        self, monkeypatch
+    ):
+        captured = {}
+
+        class FakeAgent:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+        _patch_create_agent_runtime(monkeypatch, captured, FakeAgent)
+        monkeypatch.setattr(
+            "hermes_cli.runtime_provider.resolve_runtime_provider",
+            lambda requested=None, target_model=None, **_kwargs: {
+                "api_key": f"sk-{requested}",
+                "base_url": f"https://{requested}.example/v1",
+                "provider": requested,
+                "api_mode": "chat_completions",
+                "command": None,
+                "args": [],
+                "credential_pool": f"pool-{requested}",
+                "max_output_tokens": 64000,
+            },
+        )
+        monkeypatch.setattr("hermes_cli.runtime_provider._get_model_config", lambda: {})
+
+        adapter = _make_routing_adapter(
+            {
+                "alias": {
+                    "model": "route/model",
+                    "api_key": "sk-route",
+                    "base_url": "https://route.example/v1",
+                }
+            }
+        )
+        monkeypatch.setattr(adapter, "_ensure_session_db", lambda: None)
+        monkeypatch.setattr(
+            adapter,
+            "_session_model_override_for",
+            lambda *_: {
+                "model": "session/model",
+                "provider": "sessionprov",
+                "api_key": "sk-session",
+                "base_url": "https://session.example/v1",
+                "api_mode": "responses",
+                "credential_pool": "pool-session",
+            },
+        )
+
+        adapter._create_agent(
+            session_id="session-123",
+            route=adapter._resolve_route("alias"),
+            requested_model="MiniMax-M3",
+            requested_provider="minimax",
+            model_options={
+                "reasoning": {"enabled": True, "effort": "high"},
+                "fast": True,
+            },
+        )
+
+        assert captured["model"] == "session/model"
+        assert captured["provider"] == "sessionprov"
+        assert captured["api_key"] == "sk-session"
+        assert captured["base_url"] == "https://session.example/v1"
+        assert captured["api_mode"] == "responses"
+        assert captured["credential_pool"] == "pool-session"
+        assert captured["reasoning_config"] == {"enabled": True, "effort": "high"}
+        assert captured["service_tier"] == "priority"
+
 
 # ---------------------------------------------------------------------------
 # /health endpoint
@@ -1016,6 +1175,61 @@ class TestModelsEndpoint:
             )
             assert resp.status == 200
 
+    @pytest.mark.asyncio
+    async def test_model_options_returns_shared_inventory(self, adapter, monkeypatch):
+        """GET /api/model/options builds the shared picker payload off-loop."""
+        from hermes_cli import inventory
+
+        ctx = object()
+        payload = {
+            "providers": [{"slug": "nous", "name": "Nous Portal", "models": ["gpt-5.5"]}],
+            "model": "gpt-5.5",
+            "provider": "nous",
+        }
+        seen = {"thread_calls": 0}
+
+        monkeypatch.setattr(inventory, "load_picker_context", lambda: ctx)
+
+        def fake_build_model_options_payload(received_ctx, **kwargs):
+            seen["ctx"] = received_ctx
+            seen["kwargs"] = kwargs
+            return payload
+
+        async def fake_to_thread(func, *args, **kwargs):
+            seen["thread_calls"] += 1
+            return func(*args, **kwargs)
+
+        monkeypatch.setattr(
+            inventory,
+            "build_model_options_payload",
+            fake_build_model_options_payload,
+        )
+        monkeypatch.setattr(
+            "gateway.platforms.api_server.asyncio.to_thread",
+            fake_to_thread,
+        )
+
+        app = _create_app(adapter)
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.get("/api/model/options?refresh=true")
+            assert resp.status == 200
+            data = await resp.json()
+
+        assert data == payload
+        assert seen["thread_calls"] == 1
+        assert seen["ctx"] is ctx
+        assert seen["kwargs"] == {
+            "include_unconfigured": True,
+            "refresh": True,
+        }
+
+    @pytest.mark.asyncio
+    async def test_model_options_requires_auth(self, auth_adapter):
+        app = _create_app(auth_adapter)
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.get("/api/model/options")
+            assert resp.status == 401
+
 
 # ---------------------------------------------------------------------------
 # /v1/capabilities endpoint
@@ -1042,8 +1256,10 @@ class TestCapabilitiesEndpoint:
             assert data["features"]["chat_completions"] is True
             assert data["features"]["run_status"] is True
             assert data["features"]["run_events_sse"] is True
+            assert data["features"]["model_options"] is True
             assert data["features"]["session_continuity_header"] == "X-Hermes-Session-Id"
             assert data["endpoints"]["run_status"]["path"] == "/v1/runs/{run_id}"
+            assert data["endpoints"]["model_options"] == {"method": "GET", "path": "/api/model/options"}
             assert data["endpoints"]["skills"] == {"method": "GET", "path": "/v1/skills"}
             assert data["endpoints"]["toolsets"] == {"method": "GET", "path": "/v1/toolsets"}
 
@@ -1246,6 +1462,209 @@ class TestChatCompletionsEndpoint:
             resp = await cli.post("/v1/chat/completions", json={"model": "test", "messages": []})
             assert resp.status == 400
 
+    @pytest.mark.asyncio
+    async def test_chat_completions_passes_request_model_provider_options(self, adapter):
+        app = _create_app(adapter)
+        model_options = {
+            "reasoning": {"enabled": True, "effort": "high"},
+            "reasoning_effort": "high",
+            "service_tier": "priority",
+            "fast": True,
+        }
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_run_agent", new_callable=AsyncMock) as mock_run:
+                mock_run.return_value = (
+                    {"final_response": "ok", "messages": [], "api_calls": 1},
+                    {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+                )
+                resp = await cli.post(
+                    "/v1/chat/completions",
+                    json={
+                        "model": "MiniMax-M3",
+                        "provider": "minimax",
+                        "model_options": model_options,
+                        "messages": [{"role": "user", "content": "hi"}],
+                    },
+                )
+
+        assert resp.status == 200
+        kwargs = mock_run.call_args.kwargs
+        assert kwargs["requested_model"] == "MiniMax-M3"
+        assert kwargs["requested_provider"] == "minimax"
+        assert kwargs["model_options"] == model_options
+
+    @pytest.mark.asyncio
+    async def test_chat_completions_stream_passes_request_model_provider_options(self, adapter):
+        app = _create_app(adapter)
+        model_options = {"reasoning": {"enabled": False}, "reasoning_effort": "none", "fast": False}
+
+        async def _mock_run_agent(**kwargs):
+            cb = kwargs.get("stream_delta_callback")
+            if cb:
+                cb("ok")
+            return (
+                {"final_response": "ok", "messages": [], "api_calls": 1},
+                {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+            )
+
+        app = _create_app(adapter)
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_run_agent", side_effect=_mock_run_agent) as mock_run:
+                resp = await cli.post(
+                    "/v1/chat/completions",
+                    json={
+                        "model": "MiniMax-M3",
+                        "provider": "minimax",
+                        "model_options": model_options,
+                        "messages": [{"role": "user", "content": "hi"}],
+                        "stream": True,
+                    },
+                )
+                assert resp.status == 200
+                body = await resp.text()
+
+        assert "data: " in body
+        kwargs = mock_run.call_args.kwargs
+        assert kwargs["requested_model"] == "MiniMax-M3"
+        assert kwargs["requested_provider"] == "minimax"
+        assert kwargs["model_options"] == model_options
+
+    @pytest.mark.asyncio
+    async def test_session_chat_passes_request_model_provider_options(self, adapter):
+        app = _create_app(adapter)
+        model_options = {"reasoning": {"enabled": True, "effort": "low"}, "fast": True}
+        async with TestClient(TestServer(app)) as cli:
+            with (
+                patch.object(adapter, "_get_existing_session_or_404", return_value=({"id": "s1"}, None)),
+                patch.object(adapter, "_conversation_history_for_session", return_value=[]),
+                patch.object(adapter, "_run_agent", new_callable=AsyncMock) as mock_run,
+            ):
+                mock_run.return_value = (
+                    {"final_response": "ok", "messages": [], "api_calls": 1},
+                    {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+                )
+                resp = await cli.post(
+                    "/api/sessions/s1/chat",
+                    json={
+                        "message": "hi",
+                        "model": "MiniMax-M3",
+                        "provider": "minimax",
+                        "model_options": model_options,
+                    },
+                )
+
+        assert resp.status == 200
+        kwargs = mock_run.call_args.kwargs
+        assert kwargs["requested_model"] == "MiniMax-M3"
+        assert kwargs["requested_provider"] == "minimax"
+        assert kwargs["model_options"] == model_options
+
+    @pytest.mark.asyncio
+    async def test_session_chat_stream_passes_request_model_provider_options(self, adapter):
+        app = _create_app(adapter)
+        model_options = {"reasoning_effort": "medium", "service_tier": "priority"}
+        async with TestClient(TestServer(app)) as cli:
+            with (
+                patch.object(adapter, "_get_existing_session_or_404", return_value=({"id": "s1"}, None)),
+                patch.object(adapter, "_conversation_history_for_session", return_value=[]),
+                patch.object(adapter, "_run_agent", new_callable=AsyncMock) as mock_run,
+            ):
+                mock_run.return_value = (
+                    {"final_response": "ok", "messages": [], "api_calls": 1},
+                    {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+                )
+                resp = await cli.post(
+                    "/api/sessions/s1/chat/stream",
+                    json={
+                        "message": "hi",
+                        "model": "MiniMax-M3",
+                        "provider": "minimax",
+                        "model_options": model_options,
+                    },
+                )
+                assert resp.status == 200
+                body = await resp.text()
+
+        assert "event: run.completed" in body
+        kwargs = mock_run.call_args.kwargs
+        assert kwargs["requested_model"] == "MiniMax-M3"
+        assert kwargs["requested_provider"] == "minimax"
+        assert kwargs["model_options"] == model_options
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        ("path", "body", "needs_session"),
+        [
+            (
+                "/v1/chat/completions",
+                {
+                    "model": "alias",
+                    "provider": "minimax",
+                    "messages": [{"role": "user", "content": "hi"}],
+                },
+                False,
+            ),
+            (
+                "/v1/responses",
+                {
+                    "model": "alias",
+                    "provider": "minimax",
+                    "input": "hi",
+                },
+                False,
+            ),
+            (
+                "/api/sessions/s1/chat",
+                {
+                    "model": "alias",
+                    "provider": "minimax",
+                    "message": "hi",
+                },
+                True,
+            ),
+            (
+                "/api/sessions/s1/chat/stream",
+                {
+                    "model": "alias",
+                    "provider": "minimax",
+                    "message": "hi",
+                },
+                True,
+            ),
+        ],
+    )
+    async def test_handlers_reject_conflicting_route_and_request_provider(
+        self, path, body, needs_session
+    ):
+        adapter = _make_routing_adapter(
+            {"alias": {"model": "route/model", "provider": "openrouter"}}
+        )
+        app = _create_app(adapter)
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_run_agent", new_callable=AsyncMock) as mock_run:
+                if needs_session:
+                    with (
+                        patch.object(
+                            adapter,
+                            "_get_existing_session_or_404",
+                            return_value=({"id": "s1"}, None),
+                        ),
+                        patch.object(
+                            adapter,
+                            "_conversation_history_for_session",
+                            return_value=[],
+                        ),
+                    ):
+                        resp = await cli.post(path, json=body)
+                        data = await resp.json()
+                else:
+                    resp = await cli.post(path, json=body)
+                    data = await resp.json()
+
+        assert resp.status == 400
+        assert "provider" in data["error"]["message"].lower()
+        mock_run.assert_not_called()
+
     @pytest.mark.asyncio
     async def test_stream_true_returns_sse(self, adapter):
         """stream=true returns SSE format with the full response."""
@@ -1948,6 +2367,35 @@ class TestResponsesEndpoint:
             assert data["output"][0]["content"][0]["type"] == "output_text"
             assert data["output"][0]["content"][0]["text"] == "Paris is the capital of France."
 
+    @pytest.mark.asyncio
+    async def test_response_passes_request_model_provider_options(self, adapter):
+        app = _create_app(adapter)
+        model_options = {
+            "reasoning": {"enabled": True, "effort": "medium"},
+            "service_tier": "priority",
+        }
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_run_agent", new_callable=AsyncMock) as mock_run:
+                mock_run.return_value = (
+                    {"final_response": "ok", "messages": [], "api_calls": 1},
+                    {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+                )
+                resp = await cli.post(
+                    "/v1/responses",
+                    json={
+                        "model": "MiniMax-M3",
+                        "provider": "minimax",
+                        "model_options": model_options,
+                        "input": "hi",
+                    },
+                )
+
+        assert resp.status == 200
+        kwargs = mock_run.call_args.kwargs
+        assert kwargs["requested_model"] == "MiniMax-M3"
+        assert kwargs["requested_provider"] == "minimax"
+        assert kwargs["model_options"] == model_options
+
     @pytest.mark.asyncio
     async def test_successful_response_with_array_input(self, adapter):
         """Array input with role/content objects."""
@@ -4658,15 +5106,21 @@ class TestModelRoutesAgentCreation:
         monkeypatch.setattr(
             adapter,
             "_session_model_override_for",
-            lambda key: {"model": "session/override-model"},
+            lambda key: {
+                "model": "session/override-model",
+                "provider": "sessionprov",
+                "api_key": "sk-session",
+                "base_url": "https://session.example/v1",
+                "api_mode": "responses",
+                "credential_pool": "pool-session",
+            },
         )
 
         adapter._create_agent(session_id="s1", route=adapter._resolve_route("alias"))
 
-        # The route must NOT be applied — the session override path (global
-        # runtime here, since the gateway applies /model separately) wins.
-        assert captured["model"] == "global/model"
-        assert captured["api_key"] == "sk-global"
+        assert captured["model"] == "session/override-model"
+        assert captured["provider"] == "sessionprov"
+        assert captured["api_key"] == "sk-session"
 
     def test_session_override_lookup_reads_gateway_runner(self, monkeypatch):
         """_session_model_override_for consults GatewayRunner._session_model_overrides."""
@@ -4941,3 +5395,270 @@ class TestKeyRejectionSetsNonRetryableFatalError:
             assert adapter.fatal_error_retryable is True
         finally:
             await adapter.disconnect()
+
+
+# ---------------------------------------------------------------------------
+# Bare-model opt-in gate (direct_model_requests) for _request_agent_overrides
+# ---------------------------------------------------------------------------
+
+
+class TestDirectModelRequestsGate:
+    """Bare ``model`` (no ``provider``) is opt-in on OpenAI-compatible
+    endpoints so generic clients hardcoding "gpt-4o" keep falling back to
+    the gateway default (idea credit: PR #22825 by @mssteuer)."""
+
+    def test_bare_model_dropped_when_disallowed(self):
+        overrides = _request_agent_overrides(
+            {"model": "openai/gpt-5"}, allow_bare_model=False
+        )
+        assert "requested_model" not in overrides
+
+    def test_bare_model_kept_when_allowed(self):
+        overrides = _request_agent_overrides(
+            {"model": "openai/gpt-5"}, allow_bare_model=True
+        )
+        assert overrides["requested_model"] == "openai/gpt-5"
+
+    def test_explicit_provider_always_honors_model(self):
+        overrides = _request_agent_overrides(
+            {"model": "MiniMax-M3", "provider": "minimax"}, allow_bare_model=False
+        )
+        assert overrides["requested_model"] == "MiniMax-M3"
+        assert overrides["requested_provider"] == "minimax"
+
+    def test_model_options_survive_bare_model_drop(self):
+        overrides = _request_agent_overrides(
+            {"model": "openai/gpt-5", "model_options": {"fast": True}},
+            allow_bare_model=False,
+        )
+        assert overrides == {"model_options": {"fast": True}}
+
+    def test_virtual_model_alias_still_ignored(self):
+        overrides = _request_agent_overrides(
+            {"model": "hermes-agent", "provider": "minimax"},
+            virtual_model="hermes-agent",
+            allow_bare_model=True,
+        )
+        assert "requested_model" not in overrides
+        assert overrides["requested_provider"] == "minimax"
+
+    def test_adapter_flag_default_off(self):
+        adapter = APIServerAdapter(PlatformConfig(enabled=True, extra={}))
+        assert adapter._direct_model_requests is False
+
+    def test_adapter_flag_opt_in(self):
+        adapter = APIServerAdapter(
+            PlatformConfig(enabled=True, extra={"direct_model_requests": True})
+        )
+        assert adapter._direct_model_requests is True
+
+    @pytest.mark.asyncio
+    async def test_chat_completions_bare_model_ignored_by_default(self):
+        adapter = APIServerAdapter(PlatformConfig(enabled=True, extra={}))
+        app = _create_app(adapter)
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_run_agent", new_callable=AsyncMock) as mock_run:
+                mock_run.return_value = (
+                    {"final_response": "ok", "messages": [], "api_calls": 1},
+                    {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+                )
+                resp = await cli.post(
+                    "/v1/chat/completions",
+                    json={
+                        "model": "gpt-4o",
+                        "messages": [{"role": "user", "content": "hi"}],
+                    },
+                )
+        assert resp.status == 200
+        assert mock_run.call_args.kwargs.get("requested_model") is None
+
+    @pytest.mark.asyncio
+    async def test_chat_completions_bare_model_honored_when_enabled(self):
+        adapter = APIServerAdapter(
+            PlatformConfig(enabled=True, extra={"direct_model_requests": True})
+        )
+        app = _create_app(adapter)
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_run_agent", new_callable=AsyncMock) as mock_run:
+                mock_run.return_value = (
+                    {"final_response": "ok", "messages": [], "api_calls": 1},
+                    {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+                )
+                resp = await cli.post(
+                    "/v1/chat/completions",
+                    json={
+                        "model": "openai/gpt-5",
+                        "messages": [{"role": "user", "content": "hi"}],
+                    },
+                )
+        assert resp.status == 200
+        assert mock_run.call_args.kwargs.get("requested_model") == "openai/gpt-5"
+
+
+class TestRouteWithoutModelKeepsDefault:
+    """A model_routes alias whose route has no ``model`` key must keep the
+    global default model — the alias string itself is never a model name."""
+
+    def test_alias_never_leaks_as_model(self, monkeypatch):
+        captured = {}
+
+        class FakeAgent:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+        _patch_create_agent_runtime(monkeypatch, captured, FakeAgent)
+        adapter = _make_routing_adapter(
+            {"alias": {"model": "", "api_key": "sk-route"}}
+        )
+        # _parse_model_routes drops routes without model; simulate a
+        # credentials-only route surviving via direct dict (defensive path).
+        adapter._model_routes = {"alias": {"api_key": "sk-route"}}
+        monkeypatch.setattr(adapter, "_ensure_session_db", lambda: None)
+        monkeypatch.setattr(adapter, "_session_model_override_for", lambda *_: None)
+
+        adapter._create_agent(
+            session_id="s1",
+            route=adapter._resolve_route("alias"),
+            requested_model="alias",
+        )
+
+        assert captured["model"] == "global/model"
+        assert captured["api_key"] == "sk-route"
+
+
+# ---------------------------------------------------------------------------
+# Empty-model recovery + provider-auth error typing in _create_agent
+# (salvaged from PR #57947 by @FvanW)
+# ---------------------------------------------------------------------------
+
+
+class TestCreateAgentModelRecovery:
+    def test_create_agent_defaults_to_provider_catalog_model_when_empty(self, monkeypatch):
+        """api_server.py had no equivalent of run.py's provider-catalog
+        default when model resolves empty but a provider did resolve (e.g.
+        `hermes auth add openai-codex` without `hermes model`) —
+        AIAgent(model="") 400s every call."""
+        captured = {}
+
+        class FakeAgent:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+        _patch_create_agent_runtime(monkeypatch, captured, FakeAgent)
+        monkeypatch.setattr(
+            "gateway.run._resolve_runtime_agent_kwargs",
+            lambda: {"provider": "openai-codex", "base_url": "https://example.test/v1",
+                     "api_mode": "codex_responses"},
+        )
+        monkeypatch.setattr("gateway.run._resolve_gateway_model", lambda: "")
+        monkeypatch.setattr(
+            "hermes_cli.models.get_default_model_for_provider",
+            lambda provider: "gpt-5.5-codex" if provider == "openai-codex" else None,
+        )
+
+        adapter = APIServerAdapter(PlatformConfig(enabled=True))
+        monkeypatch.setattr(adapter, "_ensure_session_db", lambda: None)
+
+        agent = adapter._create_agent(session_id="api-session")
+
+        assert isinstance(agent, FakeAgent)
+        assert captured["model"] == "gpt-5.5-codex"
+
+    def test_create_agent_recovers_last_known_good_model_when_empty(self, monkeypatch):
+        """Last-known-good recovery (#35314): a transient config-cache miss
+        producing an empty model would build AIAgent(model="") and fail every
+        call until manual retry, instead of reusing the model that just
+        worked."""
+        captured = []
+
+        class FakeAgent:
+            def __init__(self, **kwargs):
+                captured.append(dict(kwargs))
+
+        _patch_create_agent_runtime(monkeypatch, {}, FakeAgent)
+        monkeypatch.setattr("run_agent.AIAgent", FakeAgent)
+
+        adapter = APIServerAdapter(PlatformConfig(enabled=True))
+        monkeypatch.setattr(adapter, "_ensure_session_db", lambda: None)
+
+        # Turn 1: model resolves fine — populates the last-known-good cache
+        # (keyed on gateway_session_key).
+        monkeypatch.setattr("gateway.run._resolve_gateway_model", lambda: "minimax/minimax-m3")
+        adapter._create_agent(session_id="api-session", gateway_session_key="stable-chan-1")
+        assert captured[0]["model"] == "minimax/minimax-m3"
+        assert adapter._last_resolved_model["stable-chan-1"] == "minimax/minimax-m3"
+
+        # Turn 2: transient empty resolution, no provider catalog default —
+        # must recover the model from turn 1, not build model="".
+        monkeypatch.setattr("gateway.run._resolve_gateway_model", lambda: "")
+        monkeypatch.setattr(
+            "gateway.run._resolve_runtime_agent_kwargs",
+            lambda: {"provider": None, "base_url": None, "api_mode": None},
+        )
+        adapter._create_agent(session_id="another-session", gateway_session_key="stable-chan-1")
+        assert captured[1]["model"] == "minimax/minimax-m3"
+
+    def test_last_resolved_model_cache_does_not_grow_per_ephemeral_session_id(self, monkeypatch):
+        """/v1/responses and /v1/runs hand out a fresh UUID session_id per
+        one-off request (no gateway_session_key). Keying the last-known-good
+        cache on session_id would leave one permanent dict entry per
+        stateless request, growing unbounded for the life of the process.
+        Only gateway_session_key may create an entry."""
+        class FakeAgent:
+            def __init__(self, **kwargs):
+                pass
+
+        _patch_create_agent_runtime(monkeypatch, {}, FakeAgent)
+
+        adapter = APIServerAdapter(PlatformConfig(enabled=True))
+        monkeypatch.setattr(adapter, "_ensure_session_db", lambda: None)
+
+        import uuid as _uuid
+        for _ in range(50):
+            adapter._create_agent(session_id=str(_uuid.uuid4()))
+
+        # Only the "*" process-wide fallback may exist — never one entry per
+        # ephemeral session_id.
+        assert list(adapter._last_resolved_model.keys()) == ["*"]
+
+    def test_create_agent_wraps_runtime_credential_failure_as_provider_auth_error(self, monkeypatch):
+        """_create_agent() must convert a RuntimeError from
+        gateway.run._resolve_runtime_agent_kwargs() — the sole raiser of
+        RuntimeError(format_runtime_provider_error(...)) in this call graph —
+        into _ProviderAuthResolutionError right at the call site, independent
+        of any caller's exception handling."""
+        from gateway.platforms.api_server import _ProviderAuthResolutionError
+
+        monkeypatch.setattr(
+            "gateway.run._resolve_runtime_agent_kwargs",
+            lambda: (_ for _ in ()).throw(RuntimeError("No credentials found for provider 'nous'")),
+        )
+
+        adapter = APIServerAdapter(PlatformConfig(enabled=True))
+        monkeypatch.setattr(adapter, "_ensure_session_db", lambda: None)
+
+        with pytest.raises(_ProviderAuthResolutionError, match="No credentials found for provider 'nous'"):
+            adapter._create_agent(session_id="api-session")
+
+    def test_create_agent_session_model_pins_ahead_of_request(self, monkeypatch):
+        """Session-persisted model beats per-request body values but yields
+        to an explicit session /model override."""
+        captured = {}
+
+        class FakeAgent:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+        _patch_create_agent_runtime(monkeypatch, captured, FakeAgent)
+
+        adapter = APIServerAdapter(PlatformConfig(enabled=True))
+        monkeypatch.setattr(adapter, "_ensure_session_db", lambda: None)
+        monkeypatch.setattr(adapter, "_session_model_override_for", lambda *_: None)
+
+        adapter._create_agent(
+            session_id="s1",
+            session_model="session-row/model",
+            requested_model="request/model",
+        )
+
+        assert captured["model"] == "session-row/model"
diff --git a/tests/gateway/test_api_server_runs.py b/tests/gateway/test_api_server_runs.py
index ed0240a9ff2..5ca7f221fa3 100644
--- a/tests/gateway/test_api_server_runs.py
+++ b/tests/gateway/test_api_server_runs.py
@@ -255,6 +255,73 @@ class TestStartRun:
                 )
                 assert resp.status == 202
 
+    @pytest.mark.asyncio
+    async def test_start_rejects_conflicting_route_and_request_provider(self):
+        adapter = APIServerAdapter(
+            PlatformConfig(
+                enabled=True,
+                extra={
+                    "model_routes": {
+                        "alias": {
+                            "model": "route/model",
+                            "provider": "openrouter",
+                        }
+                    }
+                },
+            )
+        )
+        app = _create_runs_app(adapter)
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_create_agent") as mock_create:
+                resp = await cli.post(
+                    "/v1/runs",
+                    json={
+                        "input": "hello",
+                        "model": "alias",
+                        "provider": "minimax",
+                    },
+                )
+                data = await resp.json()
+
+        assert resp.status == 400
+        assert "provider" in data["error"]["message"].lower()
+        assert adapter._run_streams == {}
+        assert adapter._run_statuses == {}
+        mock_create.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_start_passes_request_model_provider_options_to_create_agent(self, adapter):
+        app = _create_runs_app(adapter)
+        model_options = {"reasoning_effort": "medium", "service_tier": "priority"}
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_create_agent") as mock_create:
+                mock_agent = MagicMock()
+                mock_agent.run_conversation.return_value = {"final_response": "done"}
+                mock_agent.session_prompt_tokens = 0
+                mock_agent.session_completion_tokens = 0
+                mock_agent.session_total_tokens = 0
+                mock_create.return_value = mock_agent
+
+                resp = await cli.post(
+                    "/v1/runs",
+                    json={
+                        "input": "hello",
+                        "model": "MiniMax-M3",
+                        "provider": "minimax",
+                        "model_options": model_options,
+                    },
+                )
+                assert resp.status == 202
+                for _ in range(20):
+                    if mock_create.call_args is not None:
+                        break
+                    await asyncio.sleep(0.05)
+
+        kwargs = mock_create.call_args.kwargs
+        assert kwargs["requested_model"] == "MiniMax-M3"
+        assert kwargs["requested_provider"] == "minimax"
+        assert kwargs["model_options"] == model_options
+
 
 # ---------------------------------------------------------------------------
 # GET /v1/runs/{run_id} — poll run status
@@ -881,3 +948,38 @@ class TestStopRun:
                 body = await events_resp.text()
                 # Stream should have received run.failed and closed
                 assert "run.failed" in body or "stream closed" in body
+
+
+class TestRunsProviderAuthFailure:
+    @pytest.mark.asyncio
+    async def test_status_reports_provider_auth_failure_distinctly(self, adapter):
+        """/v1/runs builds its own agent via _create_agent() and does not
+        route through _run_agent(), so the controlled "Provider
+        authentication failed" message added there does not cover this
+        endpoint. _handle_runs()'s own _ProviderAuthResolutionError branch
+        must give the same distinguished message instead of the generic
+        except-Exception "run failed" text."""
+        from gateway.platforms.api_server import _ProviderAuthResolutionError
+
+        app = _create_runs_app(adapter)
+        async with TestClient(TestServer(app)) as cli:
+            with patch.object(adapter, "_create_agent") as mock_create:
+                mock_create.side_effect = _ProviderAuthResolutionError(
+                    "No credentials found for provider 'nous'"
+                )
+
+                resp = await cli.post("/v1/runs", json={"input": "hello"})
+                assert resp.status == 202
+                data = await resp.json()
+                run_id = data["run_id"]
+
+                for _ in range(40):
+                    status_resp = await cli.get(f"/v1/runs/{run_id}")
+                    status = await status_resp.json()
+                    if status["status"] == "failed":
+                        break
+                    await asyncio.sleep(0.05)
+
+                assert status["status"] == "failed"
+                assert status["error"] == "⚠️ Provider authentication failed: No credentials found for provider 'nous'"
+                assert status["last_event"] == "run.failed"
diff --git a/tests/gateway/test_async_session_db.py b/tests/gateway/test_async_session_db.py
index c09b5485ae7..8799bb0a893 100644
--- a/tests/gateway/test_async_session_db.py
+++ b/tests/gateway/test_async_session_db.py
@@ -125,8 +125,10 @@ _GATEWAY_FILES = ("gateway/run.py", "gateway/slash_commands.py")
 #   - self._session_db._db.<x>: the sync escape, allowed ONLY where the call is
 #     provably off the event loop — construction (__init__, before the loop
 #     serves) and the run_sync closure (executed in a thread-pool executor).
-#     Three such sites today; a fourth must be justified and this count bumped.
-_ALLOWED_SYNC_DB_ESCAPES = 3
+#     Four such sites today (maybe_auto_archive joined maybe_auto_prune_and_vacuum
+#     in the construction-time maintenance block); a fifth must be justified and
+#     this count bumped.
+_ALLOWED_SYNC_DB_ESCAPES = 4
 
 # Sync helpers that touch SessionDB but are NEVER invoked bare on the loop:
 # every loop-side call wraps them in ``asyncio.to_thread(...)`` and the only
diff --git a/tests/gateway/test_compression_deferred_soft_result.py b/tests/gateway/test_compression_deferred_soft_result.py
new file mode 100644
index 00000000000..7cb25a0023f
--- /dev/null
+++ b/tests/gateway/test_compression_deferred_soft_result.py
@@ -0,0 +1,98 @@
+"""Gateway must treat ``compression_deferred`` as a soft result (#49874).
+
+A lock-contended compression defer means a CONCURRENT compressor is actively
+shrinking the session — the opposite of ``compression_exhausted`` (session
+permanently too large). The gateway's auto-reset (#9893/#35809) must never
+fire for a deferred turn: the session stays intact and the next message
+retries normally.
+
+AST invariants on ``gateway/run.py`` (mirrors
+``test_35809_auto_reset_clean_context.py``'s load-bearing pin style):
+
+* the ``compression_deferred`` branch guards the auto-reset block — a
+  deferred result can never reach ``reset_session``;
+* the deferred branch itself performs NO session mutation (no
+  ``reset_session``, no ``_evict_cached_agent``, no
+  ``_clear_conversation_scope``).
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+
+from gateway import run as gateway_run
+
+
+def _calls(node: ast.AST) -> set[str]:
+    return {
+        n.func.attr
+        for n in ast.walk(node)
+        if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute)
+    }
+
+
+def _find_deferred_guarded_reset_chain() -> ast.If:
+    """Return the ``if agent_result.get('compression_deferred') ... elif
+    agent_result.get('compression_exhausted') ... reset_session`` chain."""
+    tree = ast.parse(inspect.getsource(gateway_run))
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.If):
+            continue
+        test_consts = [
+            n.value
+            for n in ast.walk(node.test)
+            if isinstance(n, ast.Constant) and isinstance(n.value, str)
+        ]
+        if "compression_deferred" not in test_consts:
+            continue
+        # The reset must live in the orelse (elif compression_exhausted ...),
+        # never in the deferred body.
+        orelse_calls = set()
+        for sub in node.orelse:
+            orelse_calls |= _calls(sub)
+        if "reset_session" in orelse_calls:
+            return node
+    raise AssertionError(
+        "Could not locate the compression_deferred guard in front of the "
+        "compression-exhausted auto-reset block in gateway/run.py. The "
+        "soft-defer contract (#49874: lock-contended defer must never "
+        "auto-reset the session) is no longer structurally guaranteed."
+    )
+
+
+class TestCompressionDeferredIsSoft:
+    def test_deferred_branch_guards_the_auto_reset(self):
+        """The auto-reset (``reset_session``) must be unreachable when
+        ``compression_deferred`` is set: the deferred check comes FIRST and
+        the reset lives only in its elif chain."""
+        node = _find_deferred_guarded_reset_chain()
+        # The exhaustion reset is in the orelse — verified by the finder.
+        # The deferred body must not mutate the session in any way.
+        body_calls = set()
+        for sub in node.body:
+            body_calls |= _calls(sub)
+        forbidden = {
+            "reset_session",
+            "_evict_cached_agent",
+            "_clear_conversation_scope",
+        }
+        assert not (body_calls & forbidden), (
+            f"The compression_deferred branch in gateway/run.py performs "
+            f"session mutation ({body_calls & forbidden}). A lock-contended "
+            f"defer is transient — the session must stay intact so the next "
+            f"message retries against the freshly compressed context "
+            f"(#49874, #69870)."
+        )
+
+    def test_deferred_result_key_is_passed_through_run_agent_inner(self):
+        """``_run_agent_inner``'s result dicts must carry the
+        ``compression_deferred`` key so the persistence block can see it —
+        the exact gap that made the exhaustion misclassification possible
+        (the flag existed but nothing consumed it)."""
+        src = inspect.getsource(gateway_run)
+        assert src.count('"compression_deferred"') >= 3, (
+            "gateway/run.py must read AND pass through compression_deferred "
+            "(persistence-block guard + both _run_agent_inner result dicts)."
+        )
diff --git a/tests/gateway/test_compression_progress_notices.py b/tests/gateway/test_compression_progress_notices.py
new file mode 100644
index 00000000000..fc6eeccfad8
--- /dev/null
+++ b/tests/gateway/test_compression_progress_notices.py
@@ -0,0 +1,172 @@
+"""Opt-in compression progress notices on chat gateways (#52995).
+
+Routine automatic compression is silent-by-design on human-facing chat
+platforms: the gateway noise filter (`_TELEGRAM_NOISY_STATUS_RE` via
+`_prepare_gateway_status_message`) swallows every ROUTINE compression status.
+`compression.progress_notices: true` (default: false) opens an opt-in gate
+that lets those ROUTINE compression statuses through — scoped strictly to
+the #69550 compression status template constants, so unrelated operational
+noise (auxiliary failures, provider retry/rate-limit chatter) stays
+suppressed even when the gate is enabled.
+
+The default-OFF path must stay byte-identical to silent-by-design main:
+tests/gateway/test_telegram_noise_filter.py pins that suite unchanged.
+"""
+
+import pytest
+
+import gateway.run as gateway_run
+from agent.conversation_compression import (
+    COMPACTION_DONE_STATUS,
+    ROUTINE_COMPRESSION_STATUS_SAMPLES,
+)
+from gateway.run import _prepare_gateway_status_message
+
+# Chat surfaces the opt-in must deliver to (subset of the noise-filter
+# suite's CHAT_PLATFORMS; telegram + discord are the required anchors).
+CHAT_PLATFORMS = ["telegram", "discord", "slack", "whatsapp"]
+
+# Noisy statuses that are NOT routine compression progress — they must stay
+# suppressed on chat platforms even when progress_notices is enabled.
+NON_COMPRESSION_NOISE = [
+    "⚠ Auxiliary title generation failed: HTTP 400: Operation contains cybersecurity risk",
+    "⏳ Retrying in 4.2s (attempt 1/3)...",
+    "⏱️ Rate limited. Waiting 30.0s (attempt 2/3)...",
+    "⚠️ Max retries (3) exhausted — trying fallback...",
+    "⚠ Compression summary failed: upstream error. Inserted a fallback context marker.",
+    (
+        "⚠ Configured auxiliary compression provider 'openai' is unavailable — "
+        "context compression will drop middle turns without a summary. Check "
+        "auxiliary.compression in config.yaml and reauthenticate that provider."
+    ),
+    (
+        "⚠ Skipping concurrent compression — another path is already "
+        "compressing this session. Will retry after it finishes."
+    ),
+]
+
+
+@pytest.fixture
+def progress_notices_enabled(monkeypatch):
+    """Gateway config with compression.progress_notices: true."""
+    monkeypatch.setattr(
+        gateway_run,
+        "_load_gateway_config",
+        lambda: {"compression": {"progress_notices": True}},
+    )
+
+
+@pytest.fixture
+def progress_notices_default(monkeypatch):
+    """Gateway config without the key — the silent-by-design default."""
+    monkeypatch.setattr(gateway_run, "_load_gateway_config", lambda: {})
+
+
+@pytest.mark.parametrize("platform", CHAT_PLATFORMS)
+@pytest.mark.parametrize(
+    "message", ROUTINE_COMPRESSION_STATUS_SAMPLES, ids=lambda m: m[:32]
+)
+def test_enabled_delivers_routine_compression_statuses(
+    progress_notices_enabled, platform, message
+):
+    """Opt-in ON: every ROUTINE compression status reaches chat platforms.
+
+    Iterates the sample strings formatted from the SAME template constants
+    the emit sites use, so wording drift at an emit site cannot silently
+    detach the opt-in gate from the real messages.
+    """
+    assert _prepare_gateway_status_message(platform, "lifecycle", message) == message
+
+
+@pytest.mark.parametrize("platform", CHAT_PLATFORMS)
+@pytest.mark.parametrize(
+    "message", ROUTINE_COMPRESSION_STATUS_SAMPLES, ids=lambda m: m[:32]
+)
+def test_default_stays_silent(progress_notices_default, platform, message):
+    """Default (key absent): routine compression statuses stay suppressed."""
+    assert _prepare_gateway_status_message(platform, "lifecycle", message) is None
+
+
+@pytest.mark.parametrize("platform", CHAT_PLATFORMS)
+def test_explicit_false_stays_silent(monkeypatch, platform):
+    """compression.progress_notices: false behaves exactly like the default."""
+    monkeypatch.setattr(
+        gateway_run,
+        "_load_gateway_config",
+        lambda: {"compression": {"progress_notices": False}},
+    )
+    for message in ROUTINE_COMPRESSION_STATUS_SAMPLES:
+        assert _prepare_gateway_status_message(platform, "lifecycle", message) is None
+
+
+@pytest.mark.parametrize("platform", CHAT_PLATFORMS)
+@pytest.mark.parametrize("message", NON_COMPRESSION_NOISE, ids=lambda m: m[:32])
+def test_enabled_still_suppresses_non_compression_noise(
+    progress_notices_enabled, platform, message
+):
+    """The gate is scoped to compression progress statuses ONLY.
+
+    Aux-model failures, provider retry/rate-limit chatter, and other noisy
+    statuses that are not #69550 compression progress templates must stay
+    suppressed on chat surfaces even when progress_notices is enabled.
+    """
+    assert _prepare_gateway_status_message(platform, "warn", message) is None
+
+
+@pytest.mark.parametrize("enabled", [True, False], ids=["enabled", "default"])
+@pytest.mark.parametrize("platform", CHAT_PLATFORMS)
+def test_compaction_completion_notice_reaches_chat(monkeypatch, platform, enabled):
+    """The #69546 'compacted' lifecycle edge is deliverable on chat surfaces.
+
+    COMPACTION_DONE_STATUS already flows through the status callback on
+    compaction completion and is not matched by the noise regex — the opt-in
+    gate must not change that in either mode, so users who enable
+    progress_notices see the completion stat notice paired with the start.
+    """
+    monkeypatch.setattr(
+        gateway_run,
+        "_load_gateway_config",
+        lambda: {"compression": {"progress_notices": enabled}},
+    )
+    assert (
+        _prepare_gateway_status_message(platform, "compacted", COMPACTION_DONE_STATUS)
+        == COMPACTION_DONE_STATUS
+    )
+
+
+def test_config_read_errors_fail_closed(monkeypatch):
+    """A broken config read keeps the silent-by-design default."""
+    def _boom():
+        raise RuntimeError("config unreadable")
+
+    monkeypatch.setattr(gateway_run, "_load_gateway_config", _boom)
+    message = ROUTINE_COMPRESSION_STATUS_SAMPLES[0]
+    assert _prepare_gateway_status_message("telegram", "lifecycle", message) is None
+
+
+def test_enabled_gate_does_not_leak_to_raw_platforms(progress_notices_enabled):
+    """Programmatic surfaces keep raw text regardless of the gate."""
+    message = ROUTINE_COMPRESSION_STATUS_SAMPLES[0]
+    for platform in ("local", "api_server", "webhook", "msgraph_webhook"):
+        assert (
+            _prepare_gateway_status_message(platform, "lifecycle", message) == message
+        )
+
+
+def test_progress_notices_is_a_hot_reload_cache_busting_key():
+    """Editing compression.progress_notices on a running gateway must take
+    effect like every other compression.* key (hot-reload key list)."""
+    assert ("compression", "progress_notices") in gateway_run.GatewayRunner._CACHE_BUSTING_CONFIG_KEYS
+
+
+def test_progress_regex_covers_every_routine_sample():
+    """The template-derived membership regex matches every ROUTINE sample.
+
+    Guards the coupling: a new #69550 template constant added to
+    ROUTINE_COMPRESSION_STATUS_SAMPLES without being added to the gateway's
+    _COMPRESSION_PROGRESS_STATUS_RE alternatives fails here.
+    """
+    for message in ROUTINE_COMPRESSION_STATUS_SAMPLES:
+        assert gateway_run._COMPRESSION_PROGRESS_STATUS_RE.search(message), (
+            f"routine compression sample not covered by the opt-in gate: {message!r}"
+        )
diff --git a/tests/gateway/test_config.py b/tests/gateway/test_config.py
index 163376e1a7f..451ad7012b0 100644
--- a/tests/gateway/test_config.py
+++ b/tests/gateway/test_config.py
@@ -23,18 +23,75 @@ from gateway.config import (
     StreamingConfig,
     _apply_env_overrides,
     load_gateway_config,
+    persist_home_channel,
 )
 
 
 class TestHomeChannelRoundtrip:
     def test_to_dict_from_dict(self):
-        hc = HomeChannel(platform=Platform.DISCORD, chat_id="999", name="general")
+        hc = HomeChannel(
+            platform=Platform.DISCORD,
+            chat_id="999",
+            name="general",
+            user_id="user-123",
+            scope_id="guild-456",
+        )
         d = hc.to_dict()
         restored = HomeChannel.from_dict(d)
 
         assert restored.platform == Platform.DISCORD
         assert restored.chat_id == "999"
         assert restored.name == "general"
+        assert restored.user_id == "user-123"
+        assert restored.scope_id == "guild-456"
+
+    def test_relay_only_slack_home_hydrates_disabled_with_provenance(self):
+        config = GatewayConfig(
+            platforms={
+                Platform.SLACK: PlatformConfig(
+                    enabled=False,
+                    home_channel=HomeChannel(
+                        platform=Platform.SLACK,
+                        chat_id="D123",
+                        name="Owner DM",
+                        user_id="U123",
+                    ),
+                )
+            }
+        )
+
+        with patch.dict(os.environ, {"SLACK_HOME_CHANNEL": "D123"}, clear=False):
+            _apply_env_overrides(config)
+
+        slack = config.platforms[Platform.SLACK]
+        assert slack.enabled is False
+        assert slack.home_channel is not None
+        assert slack.home_channel.chat_id == "D123"
+        assert slack.home_channel.user_id == "U123"
+
+    def test_persisted_relay_home_survives_real_config_reload(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("SLACK_HOME_CHANNEL", "D123")
+        monkeypatch.delenv("SLACK_BOT_TOKEN", raising=False)
+        home_token = set_hermes_home_override(str(tmp_path))
+        try:
+            persist_home_channel(
+                HomeChannel(
+                    platform=Platform.SLACK,
+                    chat_id="D123",
+                    name="Owner DM",
+                    user_id="U123",
+                )
+            )
+            config = load_gateway_config()
+        finally:
+            reset_hermes_home_override(home_token)
+
+        slack = config.platforms[Platform.SLACK]
+        assert slack.enabled is False
+        assert slack.token is None
+        assert slack.home_channel is not None
+        assert slack.home_channel.chat_id == "D123"
+        assert slack.home_channel.user_id == "U123"
 
 
 class TestPlatformConfigRoundtrip:
diff --git a/tests/gateway/test_delivery.py b/tests/gateway/test_delivery.py
index 807d9cbb4ac..a1849985c7a 100644
--- a/tests/gateway/test_delivery.py
+++ b/tests/gateway/test_delivery.py
@@ -1,10 +1,13 @@
 """Tests for the delivery routing module."""
 
 import pytest
+from typing import Any, cast
 
-from gateway.config import GatewayConfig, Platform
+from gateway.config import GatewayConfig, HomeChannel, Platform, PlatformConfig
 from gateway.delivery import DeliveryRouter, DeliveryTarget
 from gateway.platforms.base import SendResult
+from gateway.relay.adapter import RelayAdapter
+from gateway.relay.descriptor import CONTRACT_VERSION, CapabilityDescriptor
 from gateway.session import SessionSource
 
 
@@ -125,6 +128,98 @@ class TestPlatformNameCaseInsensitivity:
         assert target.platform == Platform.TELEGRAM
         assert target.chat_id == "12345"
 
+class _RelayDeliveryTransport:
+    """Relay transport that advertises Slack and records outbound wire frames."""
+
+    def __init__(self):
+        self._identities = [("slack", "bot-1")]
+        self.sent = []
+
+    async def send_outbound(self, action, *, platform=None):
+        self.sent.append((action, platform))
+        if not action.get("metadata", {}).get("user_id"):
+            return {"success": False, "error": "target not routed to an onboarded tenant"}
+        return {"success": True, "message_id": "relay-message-1"}
+
+
+def _make_relay(transport):
+    return RelayAdapter(
+        PlatformConfig(enabled=True),
+        CapabilityDescriptor(
+            contract_version=CONTRACT_VERSION,
+            platform="slack",
+            label="Slack",
+            max_message_length=4000,
+            supports_draft_streaming=False,
+            supports_edit=True,
+            supports_threads=True,
+            markdown_dialect="slack",
+            len_unit="chars",
+        ),
+        transport=cast(Any, transport),
+    )
+
+
+@pytest.mark.asyncio
+async def test_relay_fronted_target_delivers_without_prior_inbound_chat_state(tmp_path, monkeypatch):
+    """A persisted Slack home must work immediately after a gateway restart."""
+    monkeypatch.setattr("gateway.delivery.get_hermes_home", lambda: tmp_path)
+    transport = _RelayDeliveryTransport()
+    relay = _make_relay(transport)
+    config = GatewayConfig(
+        platforms={
+            Platform.RELAY: PlatformConfig(enabled=True),
+            Platform.SLACK: PlatformConfig(
+                enabled=False,
+                home_channel=HomeChannel(
+                    platform=Platform.SLACK,
+                    chat_id="D123",
+                    name="Owner DM",
+                    user_id="U123",
+                ),
+            ),
+        },
+    )
+    router = DeliveryRouter(config, adapters={Platform.RELAY: relay})
+
+    result = await router._deliver_to_platform(
+        DeliveryTarget(platform=Platform.SLACK, chat_id="D123"),
+        "scheduled result",
+        metadata={"job_id": "cron-1", "user_id": "stale-user"},
+    )
+
+    assert getattr(result, "success", False) is True
+    assert len(transport.sent) == 1
+    action, wire_platform = transport.sent[0]
+    assert wire_platform == "slack"
+    assert action["chat_id"] == "D123"
+    assert action["metadata"] == {"job_id": "cron-1", "user_id": "U123"}
+
+
+@pytest.mark.asyncio
+async def test_relay_media_fallback_retains_explicit_platform_and_owner():
+    """Attachment fallback cannot default to another Relay identity after restart."""
+    transport = _RelayDeliveryTransport()
+    transport._identities = [("discord", "discord-bot"), ("slack", "slack-bot")]
+    relay = _make_relay(transport)
+
+    result = await relay.send_document(
+        chat_id="D123",
+        file_path="/tmp/report.pdf",
+        metadata={
+            "_relay_logical_platform": "slack",
+            "user_id": "U123",
+        },
+    )
+
+    assert result.success is True
+    assert len(transport.sent) == 1
+    action, wire_platform = transport.sent[0]
+    assert wire_platform == "slack"
+    assert action["metadata"] == {"user_id": "U123"}
+    assert "_relay_logical_platform" not in action["metadata"]
+
+
 class RecordingAdapter:
     def __init__(self):
         self.calls = []
@@ -141,6 +236,92 @@ class RecordingAdapter:
         return "38049"
 
 
+@pytest.mark.asyncio
+async def test_native_adapter_wins_when_relay_also_fronts_platform(tmp_path, monkeypatch):
+    monkeypatch.setattr("gateway.delivery.get_hermes_home", lambda: tmp_path)
+    native = RecordingAdapter()
+    transport = _RelayDeliveryTransport()
+    relay = _make_relay(transport)
+    config = GatewayConfig(
+        platforms={
+            Platform.SLACK: PlatformConfig(enabled=True),
+            Platform.RELAY: PlatformConfig(enabled=True),
+        },
+    )
+    router = DeliveryRouter(
+        config,
+        adapters={Platform.SLACK: native, Platform.RELAY: relay},
+    )
+
+    await router._deliver_to_platform(
+        DeliveryTarget(platform=Platform.SLACK, chat_id="D123"),
+        "native result",
+        metadata=None,
+    )
+
+    assert native.calls == [
+        {"chat_id": "D123", "content": "native result", "metadata": None}
+    ]
+    assert transport.sent == []
+
+
+@pytest.mark.asyncio
+async def test_disabled_native_adapter_does_not_shadow_relay(tmp_path, monkeypatch):
+    monkeypatch.setattr("gateway.delivery.get_hermes_home", lambda: tmp_path)
+    native = RecordingAdapter()
+    transport = _RelayDeliveryTransport()
+    relay = _make_relay(transport)
+    config = GatewayConfig(
+        platforms={
+            Platform.SLACK: PlatformConfig(
+                enabled=False,
+                home_channel=HomeChannel(
+                    platform=Platform.SLACK,
+                    chat_id="D123",
+                    name="Owner DM",
+                    user_id="U123",
+                ),
+            ),
+            Platform.RELAY: PlatformConfig(enabled=True),
+        },
+    )
+    router = DeliveryRouter(
+        config,
+        adapters={Platform.SLACK: native, Platform.RELAY: relay},
+    )
+
+    await router._deliver_to_platform(
+        DeliveryTarget(platform=Platform.SLACK, chat_id="D123"),
+        "relay result",
+        metadata=None,
+    )
+
+    assert native.calls == []
+    assert len(transport.sent) == 1
+    assert transport.sent[0][1] == "slack"
+
+
+@pytest.mark.asyncio
+async def test_relay_does_not_claim_unadvertised_platform(tmp_path, monkeypatch):
+    monkeypatch.setattr("gateway.delivery.get_hermes_home", lambda: tmp_path)
+    transport = _RelayDeliveryTransport()
+    transport._identities = [("discord", "bot-1")]
+    relay = _make_relay(transport)
+    config = GatewayConfig(
+        platforms={Platform.RELAY: PlatformConfig(enabled=True)},
+    )
+    router = DeliveryRouter(config, adapters={Platform.RELAY: relay})
+
+    with pytest.raises(ValueError, match="No adapter configured for slack"):
+        await router._deliver_to_platform(
+            DeliveryTarget(platform=Platform.SLACK, chat_id="D123"),
+            "must not route",
+            metadata=None,
+        )
+
+    assert transport.sent == []
+
+
 class StaleTopicAdapter:
     def __init__(self):
         self.calls = []
diff --git a/tests/gateway/test_delivery_ledger_fd_leak.py b/tests/gateway/test_delivery_ledger_fd_leak.py
new file mode 100644
index 00000000000..02cde134f4c
--- /dev/null
+++ b/tests/gateway/test_delivery_ledger_fd_leak.py
@@ -0,0 +1,137 @@
+"""Regression: the gateway delivery ledger must close every SQLite connection.
+
+Sibling of the cron execution-ledger leak (#69567 / PR #69594). The ledger used
+``with _connect() as conn:`` where ``sqlite3.Connection.__exit__`` commits or
+rolls back but never closes, leaking the db/-wal/-shm file descriptors on every
+call until a long-running gateway exhausts ``RLIMIT_NOFILE``. ``record_obligation``
+runs on every outbound final response, so this is the highest-frequency leaker of
+the set. These tests fail if the deterministic ``close()`` is ever removed again.
+"""
+
+import sqlite3
+
+import pytest
+
+from gateway import delivery_ledger as dl
+
+
+class _TrackingConnection:
+    """Delegates to a real sqlite3.Connection while recording close() calls.
+
+    sqlite3.Connection is a static C type: it has no per-instance __dict__ and
+    its methods can't be monkeypatched, so open/close tracking is done via a
+    delegating wrapper returned in place of the real connection.
+    """
+
+    def __init__(self, real, closed_ids):
+        object.__setattr__(self, "_real", real)
+        object.__setattr__(self, "_closed_ids", closed_ids)
+
+    def close(self):
+        self._closed_ids.append(id(self._real))
+        self._real.close()
+
+    def __enter__(self):
+        self._real.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return self._real.__exit__(exc_type, exc, tb)
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)
+
+    def __setattr__(self, name, value):
+        setattr(self._real, name, value)
+
+
+def _point_ledger(monkeypatch, tmp_path):
+    monkeypatch.setattr(dl, "_db_path", lambda: tmp_path / "state.db")
+    return dl
+
+
+def _track_connections(monkeypatch):
+    opened, closed = [], []
+    real_connect = sqlite3.connect
+
+    def tracking_connect(*args, **kwargs):
+        conn = real_connect(*args, **kwargs)
+        opened.append(id(conn))
+        return _TrackingConnection(conn, closed)
+
+    monkeypatch.setattr(dl.sqlite3, "connect", tracking_connect)
+    return opened, closed
+
+
+def test_ledger_operations_close_every_connection(monkeypatch, tmp_path):
+    """Every public ledger operation must close the connection it opened."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _track_connections(monkeypatch)
+
+    oid = dl.compute_obligation_id("sess", "msg", "content")
+    dl.record_obligation(
+        obligation_id=oid, session_key="sess", platform="telegram",
+        chat_id="123", thread_id=None, content="hello",
+    )
+    dl.mark_attempting(oid)
+    dl.mark_delivered(oid)
+    dl.sweep_recoverable()
+    dl.debug_rows()
+
+    assert opened, "expected at least one connection to be opened"
+    assert len(opened) == len(closed)
+    assert set(opened) == set(closed)
+
+
+def test_early_return_still_closes_connection(monkeypatch, tmp_path):
+    """A no-op update (no matching row) must still open and close exactly once."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _track_connections(monkeypatch)
+
+    dl.mark_delivered("does-not-exist")
+
+    assert len(opened) == 1
+    assert len(closed) == 1
+
+
+def test_exception_during_operation_still_closes_connection(monkeypatch, tmp_path):
+    """A failing statement inside the transaction must roll back and close."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _track_connections(monkeypatch)
+
+    with pytest.raises(sqlite3.IntegrityError):
+        with dl._transaction() as conn:
+            # Missing NOT NULL columns -> constraint failure inside the block.
+            conn.execute(
+                "INSERT INTO delivery_obligations (obligation_id) VALUES ('x')"
+            )
+
+    assert len(opened) == 1
+    assert len(closed) == 1
+
+
+def test_schema_init_failure_still_closes_connection(monkeypatch, tmp_path):
+    """A PRAGMA/DDL failure after connect() must still close the connection."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = [], []
+    real_connect = sqlite3.connect
+
+    class _FailingSchemaConnection(_TrackingConnection):
+        def execute(self, sql, *args, **kwargs):
+            if "CREATE TABLE" in sql:
+                raise sqlite3.OperationalError("simulated schema init failure")
+            return self._real.execute(sql, *args, **kwargs)
+
+    def tracking_connect(*args, **kwargs):
+        conn = real_connect(*args, **kwargs)
+        opened.append(id(conn))
+        return _FailingSchemaConnection(conn, closed)
+
+    monkeypatch.setattr(dl.sqlite3, "connect", tracking_connect)
+
+    with pytest.raises(sqlite3.OperationalError):
+        with dl._transaction():
+            pass
+
+    assert len(opened) == 1
+    assert len(closed) == 1
diff --git a/tests/gateway/test_gateway_utf8_encoding.py b/tests/gateway/test_gateway_utf8_encoding.py
new file mode 100644
index 00000000000..2ecc559e6ad
--- /dev/null
+++ b/tests/gateway/test_gateway_utf8_encoding.py
@@ -0,0 +1,60 @@
+"""Static guard: every ``read_text`` / ``write_text`` call in the gateway and
+bundled update-response adapters must pass an explicit ``encoding=`` keyword
+argument so non-UTF-8 Windows locales don't corrupt file IPC.  Mirrors the
+AST-based guard pattern in
+``tests/tools/test_windows_compat.py``.
+"""
+
+import ast
+import pathlib
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
+GATEWAY_DIR = REPO_ROOT / "gateway"
+UPDATE_RESPONSE_FILES = (
+    REPO_ROOT / "plugins/platforms/discord/adapter.py",
+    REPO_ROOT / "plugins/platforms/telegram/adapter.py",
+    REPO_ROOT / "plugins/platforms/feishu/adapter.py",
+    REPO_ROOT / "plugins/platforms/whatsapp/adapter.py",
+    REPO_ROOT / "plugins/platforms/google_chat/adapter.py",
+    REPO_ROOT / "plugins/platforms/google_chat/oauth.py",
+)
+METHODS = {"read_text", "write_text"}
+SUPPRESSION = "# gateway-utf8: ok"
+
+
+def _find_violations():
+    violations = []
+    py_files = list(GATEWAY_DIR.rglob("*.py")) + list(UPDATE_RESPONSE_FILES)
+    for py_file in sorted(py_files):
+        source = py_file.read_text(encoding="utf-8")
+        source_lines = source.splitlines()
+        try:
+            tree = ast.parse(source, filename=str(py_file))
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            func = node.func
+            if not isinstance(func, ast.Attribute):
+                continue
+            if func.attr not in METHODS:
+                continue
+            if any(kw.arg == "encoding" for kw in node.keywords):
+                continue
+            lineno = node.lineno
+            if lineno <= len(source_lines) and SUPPRESSION in source_lines[lineno - 1]:
+                continue
+            rel = py_file.relative_to(REPO_ROOT)
+            violations.append(f"{rel}:{lineno}")
+    return violations
+
+
+def test_all_read_write_text_pass_encoding():
+    violations = _find_violations()
+    assert not violations, (
+        "Bare read_text()/write_text() calls found (missing encoding= kwarg).\n"
+        "Add encoding=\"utf-8\" or suppress with '# gateway-utf8: ok':\n"
+        + "\n".join(f"  {v}" for v in violations)
+    )
diff --git a/tests/gateway/test_loop_liveness_watchdog.py b/tests/gateway/test_loop_liveness_watchdog.py
new file mode 100644
index 00000000000..77ac3df73c8
--- /dev/null
+++ b/tests/gateway/test_loop_liveness_watchdog.py
@@ -0,0 +1,426 @@
+"""Gateway event-loop freeze backstops for issue #69089."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from gateway.shutdown_watchdog import (
+    _arm_loop_floor_timer,
+    start_loop_liveness_watchdog,
+)
+
+
+def _immediate_loop() -> MagicMock:
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    loop.call_soon_threadsafe.side_effect = lambda callback: callback()
+    return loop
+
+
+def test_loop_liveness_watchdog_responsive_probe_does_not_fire():
+    loop = _immediate_loop()
+    exit_codes = []
+
+    with (
+        patch("gateway.shutdown_watchdog.faulthandler.dump_traceback") as dump,
+        patch("gateway.shutdown_watchdog.os._exit", side_effect=exit_codes.append),
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop, probe_interval=0.01, probe_timeout=0.01, max_strikes=2
+        )
+        assert handle is not None
+        deadline = time.monotonic() + 2.0
+        while loop.call_soon_threadsafe.call_count < 3 and time.monotonic() < deadline:
+            time.sleep(0.01)
+        handle.stop()
+        handle.join(timeout=1.0)
+
+    assert loop.call_soon_threadsafe.call_count >= 3
+    assert not handle.is_alive()
+    dump.assert_not_called()
+    assert exit_codes == []
+
+
+def test_loop_liveness_watchdog_exits_after_consecutive_misses():
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    fired = threading.Event()
+    exit_codes = []
+
+    def fake_exit(code: int) -> None:
+        exit_codes.append(code)
+        fired.set()
+
+    with (
+        patch("gateway.shutdown_watchdog.faulthandler.dump_traceback") as dump,
+        patch("gateway.shutdown_watchdog.os._exit", side_effect=fake_exit),
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop, probe_interval=0.01, probe_timeout=0.01, max_strikes=2
+        )
+        assert handle is not None
+        assert fired.wait(timeout=2.0), "loop liveness watchdog did not fire"
+        handle.join(timeout=1.0)
+
+    assert not handle.is_alive()
+    assert loop.call_soon_threadsafe.call_count == 2
+    dump.assert_called_once_with(all_threads=True)
+    assert exit_codes == [75]
+
+
+def test_loop_liveness_watchdog_stop_during_critical_log_disarms_hard_exit():
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    handle_ready = threading.Event()
+    handle_ref = {}
+    exit_codes = []
+
+    def stop_during_critical(*_args) -> None:
+        assert handle_ready.wait(timeout=2.0)
+        handle_ref["handle"].stop()
+
+    with (
+        patch(
+            "gateway.shutdown_watchdog.logger.critical",
+            side_effect=stop_during_critical,
+        ) as critical,
+        patch("gateway.shutdown_watchdog.faulthandler.dump_traceback"),
+        patch("gateway.shutdown_watchdog.os._exit", side_effect=exit_codes.append),
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop, probe_interval=0.01, probe_timeout=0.01, max_strikes=1
+        )
+        assert handle is not None
+        handle_ref["handle"] = handle
+        handle_ready.set()
+        handle.join(timeout=2.0)
+
+    assert not handle.is_alive()
+    critical.assert_called_once()
+    assert exit_codes == []
+
+
+def test_loop_liveness_watchdog_stop_during_dump_disarms_hard_exit():
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    handle_ready = threading.Event()
+    handle_ref = {}
+    exit_codes = []
+
+    def stop_during_dump(*_args, **_kwargs) -> None:
+        assert handle_ready.wait(timeout=2.0)
+        handle_ref["handle"].stop()
+
+    with (
+        patch("gateway.shutdown_watchdog.logger.critical") as critical,
+        patch(
+            "gateway.shutdown_watchdog.faulthandler.dump_traceback",
+            side_effect=stop_during_dump,
+        ) as dump,
+        patch("gateway.shutdown_watchdog.os._exit", side_effect=exit_codes.append),
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop, probe_interval=0.01, probe_timeout=0.01, max_strikes=1
+        )
+        assert handle is not None
+        handle_ref["handle"] = handle
+        handle_ready.set()
+        handle.join(timeout=2.0)
+
+    assert not handle.is_alive()
+    critical.assert_called_once()
+    dump.assert_called_once_with(all_threads=True)
+    assert exit_codes == []
+
+
+def test_loop_liveness_watchdog_stop_during_final_miss_disarms_hard_exit():
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    probe_scheduled = threading.Event()
+    release_probe = threading.Event()
+    probe_event_ref = {}
+    handle_ref = {}
+    exit_codes = []
+
+    class FinalStrikeLimit:
+        def __gt__(self, _strikes: int) -> bool:
+            # If strike evaluation is reached, keep recheck #2 from masking a
+            # missing post-probe recheck #1 in this boundary test.
+            handle_ref["handle"]._stop_event.clear()
+            return False
+
+    def hold_scheduled_probe(callback) -> None:
+        probe_event_ref["event"] = callback.__self__
+        probe_scheduled.set()
+        assert release_probe.wait(timeout=2.0)
+
+    loop.call_soon_threadsafe.side_effect = hold_scheduled_probe
+    with (
+        patch("gateway.shutdown_watchdog.logger.critical") as critical,
+        patch("gateway.shutdown_watchdog.faulthandler.dump_traceback") as dump,
+        patch("gateway.shutdown_watchdog.os._exit", side_effect=exit_codes.append),
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop,
+            probe_interval=0.01,
+            probe_timeout=0.01,
+            max_strikes=FinalStrikeLimit(),
+        )
+        assert handle is not None
+        handle_ref["handle"] = handle
+        assert probe_scheduled.wait(timeout=2.0), "watchdog did not schedule a probe"
+
+        def stop_during_miss() -> bool:
+            handle.stop()
+            return False
+
+        probe_event_ref["event"].is_set = stop_during_miss
+        release_probe.set()
+        handle.join(timeout=1.0)
+
+    assert not handle.is_alive()
+    assert exit_codes == []
+    critical.assert_not_called()
+    dump.assert_not_called()
+
+
+def test_loop_liveness_watchdog_stop_after_first_recheck_skips_final_actions():
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    probe_scheduled = threading.Event()
+    release_probe = threading.Event()
+
+    def hold_scheduled_probe(callback) -> None:
+        probe_scheduled.set()
+        assert release_probe.wait(timeout=2.0)
+
+    loop.call_soon_threadsafe.side_effect = hold_scheduled_probe
+    with (
+        patch("gateway.shutdown_watchdog.logger.critical") as critical,
+        patch("gateway.shutdown_watchdog.faulthandler.dump_traceback") as dump,
+        patch("gateway.shutdown_watchdog.os._exit") as hard_exit,
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop, probe_interval=0.01, probe_timeout=0.01, max_strikes=1
+        )
+        assert handle is not None
+        assert probe_scheduled.wait(timeout=2.0), "watchdog did not schedule a probe"
+
+        original_is_set = handle._stop_event.is_set
+        is_set_calls = 0
+
+        def stop_on_final_recheck() -> bool:
+            nonlocal is_set_calls
+            is_set_calls += 1
+            # With the forced immediate timeout: _wait_for_probe is call 1,
+            # recheck #1 is call 2, and recheck #2 is call 3.
+            if is_set_calls == 3:
+                handle.stop()
+            return original_is_set()
+
+        handle._stop_event.is_set = stop_on_final_recheck
+        with patch(
+            "gateway.shutdown_watchdog.time.monotonic", side_effect=[0.0, 1.0]
+        ):
+            release_probe.set()
+            handle.join(timeout=1.0)
+
+    assert is_set_calls == 3
+    assert not handle.is_alive()
+    critical.assert_not_called()
+    dump.assert_not_called()
+    hard_exit.assert_not_called()
+
+
+def test_loop_liveness_watchdog_recovery_resets_strikes():
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    four_probes = threading.Event()
+
+    def alternate_response(callback) -> None:
+        count = loop.call_soon_threadsafe.call_count
+        if count in {2, 4}:
+            callback()
+        if count >= 4:
+            four_probes.set()
+
+    loop.call_soon_threadsafe.side_effect = alternate_response
+    with (
+        patch("gateway.shutdown_watchdog.faulthandler.dump_traceback") as dump,
+        patch("gateway.shutdown_watchdog.os._exit") as hard_exit,
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop, probe_interval=0.01, probe_timeout=0.01, max_strikes=2
+        )
+        assert handle is not None
+        assert four_probes.wait(
+            timeout=2.0
+        ), "watchdog did not complete recovery probes"
+        handle.stop()
+        handle.join(timeout=1.0)
+
+    assert not handle.is_alive()
+    dump.assert_not_called()
+    hard_exit.assert_not_called()
+
+
+def test_loop_liveness_watchdog_stop_exits_thread_and_stops_probes():
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    first_probe = threading.Event()
+    loop.call_soon_threadsafe.side_effect = lambda callback: first_probe.set()
+
+    handle = start_loop_liveness_watchdog(
+        loop, probe_interval=0.01, probe_timeout=0.5, max_strikes=10
+    )
+    assert handle is not None
+    assert first_probe.wait(timeout=2.0)
+    handle.stop()
+    handle.join(timeout=1.0)
+    calls_after_stop = loop.call_soon_threadsafe.call_count
+    time.sleep(0.05)
+
+    assert not handle.is_alive()
+    assert loop.call_soon_threadsafe.call_count == calls_after_stop
+
+
+def test_loop_liveness_guards_config_can_disable():
+    """gateway.loop_watchdog: false must skip arming both guards."""
+    from gateway.run import GatewayRunner
+
+    runner = object.__new__(GatewayRunner)
+    runner._loop_floor_timer_handle = None
+    runner._loop_liveness_watchdog = None
+    runner.config = MagicMock()
+    runner.config.loop_watchdog = False
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+
+    with (
+        patch("gateway.run._arm_loop_floor_timer") as arm_floor,
+        patch("gateway.run.start_loop_liveness_watchdog") as start_watchdog,
+    ):
+        runner._start_loop_liveness_guards(loop)
+
+    arm_floor.assert_not_called()
+    start_watchdog.assert_not_called()
+    assert runner._loop_floor_timer_handle is None
+    assert runner._loop_liveness_watchdog is None
+
+
+def test_gateway_config_loop_watchdog_round_trip():
+    """loop_watchdog is a config.yaml knob: default on, nested-gateway form honored."""
+    from gateway.config import GatewayConfig
+
+    assert GatewayConfig.from_dict({}).loop_watchdog is True
+    assert GatewayConfig.from_dict({"loop_watchdog": False}).loop_watchdog is False
+    assert (
+        GatewayConfig.from_dict(
+            {"gateway": {"loop_watchdog": "off"}}
+        ).loop_watchdog
+        is False
+    )
+    config = GatewayConfig.from_dict({"loop_watchdog": False})
+    assert config.to_dict()["loop_watchdog"] is False
+
+
+@pytest.mark.asyncio
+async def test_loop_liveness_watchdog_detects_real_loop_sync_freeze():
+    loop = asyncio.get_running_loop()
+    fired = threading.Event()
+    exit_codes = []
+
+    def fake_exit(code: int) -> None:
+        exit_codes.append(code)
+        fired.set()
+
+    with (
+        patch("gateway.shutdown_watchdog.faulthandler.dump_traceback") as dump,
+        patch("gateway.shutdown_watchdog.os._exit", side_effect=fake_exit),
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop, probe_interval=0.02, probe_timeout=0.03, max_strikes=2
+        )
+        assert handle is not None
+        await asyncio.sleep(0.03)
+        time.sleep(0.25)
+        assert fired.wait(timeout=1.0), "watchdog did not detect the frozen real loop"
+        handle.stop()
+        handle.join(timeout=1.0)
+
+    dump.assert_called_once_with(all_threads=True)
+    assert exit_codes == [75]
+
+
+@pytest.mark.asyncio
+async def test_loop_liveness_watchdog_leaves_responsive_real_loop_running():
+    loop = asyncio.get_running_loop()
+    with (
+        patch("gateway.shutdown_watchdog.faulthandler.dump_traceback") as dump,
+        patch("gateway.shutdown_watchdog.os._exit") as hard_exit,
+    ):
+        handle = start_loop_liveness_watchdog(
+            loop, probe_interval=0.02, probe_timeout=0.03, max_strikes=2
+        )
+        assert handle is not None
+        await asyncio.sleep(0.25)
+        handle.stop()
+        handle.join(timeout=1.0)
+
+    assert not handle.is_alive()
+    dump.assert_not_called()
+    hard_exit.assert_not_called()
+
+
+def test_loop_floor_timer_reschedules_until_cancelled():
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    scheduled = []
+
+    def fake_call_later(delay, callback):
+        timer = MagicMock(spec=asyncio.TimerHandle)
+        scheduled.append((delay, callback, timer))
+        return timer
+
+    loop.call_later.side_effect = fake_call_later
+    handle = _arm_loop_floor_timer(loop, interval=5.0)
+
+    assert len(scheduled) == 1
+    assert scheduled[0][0] == 5.0
+    scheduled[0][1]()
+    assert len(scheduled) == 2
+    assert scheduled[1][0] == 5.0
+
+    handle.cancel()
+    scheduled[1][2].cancel.assert_called_once_with()
+    scheduled[1][1]()
+    assert len(scheduled) == 2
+
+
+def test_gateway_runner_liveness_guards_start_and_stop():
+    from gateway.run import GatewayRunner
+
+    runner = object.__new__(GatewayRunner)
+    runner._loop_floor_timer_handle = None
+    runner._loop_liveness_watchdog = None
+    loop = MagicMock(spec=asyncio.AbstractEventLoop)
+    floor_timer = MagicMock()
+    watchdog = MagicMock()
+    watchdog.is_alive.return_value = True
+
+    with (
+        patch(
+            "gateway.run._arm_loop_floor_timer", return_value=floor_timer
+        ) as arm_floor,
+        patch(
+            "gateway.run.start_loop_liveness_watchdog", return_value=watchdog
+        ) as start_watchdog,
+    ):
+        runner._start_loop_liveness_guards(loop)
+
+    arm_floor.assert_called_once_with(loop)
+    start_watchdog.assert_called_once_with(loop)
+    assert runner._loop_floor_timer_handle is floor_timer
+    assert runner._loop_liveness_watchdog is watchdog
+
+    runner._stop_loop_liveness_guards()
+
+    watchdog.stop.assert_called_once_with()
+    floor_timer.cancel.assert_called_once_with()
+    assert runner._loop_liveness_watchdog is None
+    assert runner._loop_floor_timer_handle is None
diff --git a/tests/gateway/test_multiplex_api_server_routing.py b/tests/gateway/test_multiplex_api_server_routing.py
index 5c6f7f5ee6a..2d8a17a4b43 100644
--- a/tests/gateway/test_multiplex_api_server_routing.py
+++ b/tests/gateway/test_multiplex_api_server_routing.py
@@ -58,16 +58,20 @@ class TestApiServerProfileResolution:
 
 
 class TestApiServerRouteTable:
-    def test_route_table_includes_models_and_chat(self):
-        """ /p/{profile}/v1/models must be registered — this is the 404 Fadeway hit. """
+    def test_route_table_includes_models_options_and_chat(self):
+        """Model discovery and chat routes must survive profile multiplexing."""
         adapter = _make_adapter(multiplex=True)
         paths = {path for _method, path, _handler in adapter._http_route_table()}
         assert "/v1/models" in paths
+        assert "/api/model/options" in paths
         assert "/v1/chat/completions" in paths
+        assert "/api/sessions/{session_id}/model" in paths
         # connect() mirrors every native path under /p/{profile}/…
         mirrored = {f"/p/{{profile}}{path}" for path in paths}
         assert "/p/{profile}/v1/models" in mirrored
+        assert "/p/{profile}/api/model/options" in mirrored
         assert "/p/{profile}/v1/chat/completions" in mirrored
+        assert "/p/{profile}/api/sessions/{session_id}/model" in mirrored
 
 
 class TestApiServerModelsUnderProfile:
diff --git a/tests/gateway/test_platform_reconnect.py b/tests/gateway/test_platform_reconnect.py
index fe3526a9a1a..7f526e70bfe 100644
--- a/tests/gateway/test_platform_reconnect.py
+++ b/tests/gateway/test_platform_reconnect.py
@@ -138,6 +138,25 @@ class TestStartupPlatformIsolation:
         assert Platform.TELEGRAM not in runner.adapters
         assert runner._create_adapter.call_count == 2
 
+    def test_default_connect_timeout_allows_telegram_polling_readiness(
+        self, monkeypatch
+    ):
+        """Telegram gets a larger default; other platforms stay isolated at 30s."""
+        runner = _make_runner()
+        monkeypatch.delenv("HERMES_GATEWAY_PLATFORM_CONNECT_TIMEOUT", raising=False)
+
+        assert runner._platform_connect_timeout_secs(Platform.TELEGRAM) == 180
+        assert runner._platform_connect_timeout_secs(Platform.FEISHU) == 30
+
+    def test_explicit_connect_timeout_still_applies_to_every_platform(
+        self, monkeypatch
+    ):
+        runner = _make_runner()
+        monkeypatch.setenv("HERMES_GATEWAY_PLATFORM_CONNECT_TIMEOUT", "90")
+
+        assert runner._platform_connect_timeout_secs(Platform.TELEGRAM) == 90
+        assert runner._platform_connect_timeout_secs(Platform.FEISHU) == 90
+
     @pytest.mark.asyncio
     async def test_connect_adapter_timeout_raises_retryable_exception(self, monkeypatch):
         """The timeout helper turns a hanging connect into a caught startup error."""
@@ -1017,3 +1036,227 @@ class TestFatalHandoffCancellationProof:
 
         assert runner._exit_with_failure is True
         assert runner.stop.await_count == 1
+
+
+# ── _ensure_reconnect_watcher_running ──────────────────────────────────
+
+
+class TestEnsureReconnectWatcherRunning:
+    """Verify _ensure_reconnect_watcher_running respawns the watcher when dead."""
+
+    @pytest.mark.asyncio
+    async def test_reconnect_watcher_alive_does_nothing(self):
+        """Task is alive => no-op."""
+        runner = _make_runner()
+        runner._running = True
+        runner._background_tasks = set()
+
+        async def _dummy():
+            await asyncio.sleep(3600)
+
+        runner._reconnect_watcher_task = asyncio.create_task(_dummy())
+        runner._background_tasks.add(runner._reconnect_watcher_task)
+
+        old_task = runner._reconnect_watcher_task
+        runner._ensure_reconnect_watcher_running()
+
+        # Same task, not replaced
+        assert runner._reconnect_watcher_task is old_task
+        assert not runner._reconnect_watcher_task.done()
+
+        old_task.cancel()
+        try:
+            await old_task
+        except asyncio.CancelledError:
+            pass
+
+    @pytest.mark.asyncio
+    async def test_reconnect_watcher_dead_respawns(self):
+        """Watcher is done => respawn."""
+        runner = _make_runner()
+        runner._running = True
+        runner._background_tasks = set()
+        runner._reconnect_watcher_task = asyncio.create_task(asyncio.sleep(0))
+        await runner._reconnect_watcher_task  # let it finish
+
+        assert runner._reconnect_watcher_task.done()
+
+        runner._ensure_reconnect_watcher_running()
+
+        assert runner._reconnect_watcher_task is not None
+        assert not runner._reconnect_watcher_task.done()
+        assert runner._reconnect_watcher_task in runner._background_tasks
+
+        runner._reconnect_watcher_task.cancel()
+        try:
+            await runner._reconnect_watcher_task
+        except asyncio.CancelledError:
+            pass
+
+    @pytest.mark.asyncio
+    async def test_reconnect_watcher_not_running_respawns(self):
+        """No task at all => creates one."""
+        runner = _make_runner()
+        runner._running = True
+        runner._background_tasks = set()
+        runner._reconnect_watcher_task = None
+
+        runner._ensure_reconnect_watcher_running()
+
+        assert runner._reconnect_watcher_task is not None
+        assert not runner._reconnect_watcher_task.done()
+        assert runner._reconnect_watcher_task in runner._background_tasks
+
+        runner._reconnect_watcher_task.cancel()
+        try:
+            await runner._reconnect_watcher_task
+        except asyncio.CancelledError:
+            pass
+
+    @pytest.mark.asyncio
+    async def test_not_running_noop(self):
+        """_running is False => no-op."""
+        runner = _make_runner()
+        runner._running = False
+        runner._reconnect_watcher_task = None
+        runner._ensure_reconnect_watcher_running()
+        assert runner._reconnect_watcher_task is None
+
+
+# ── _handle_adapter_fatal_error calls _ensure_reconnect_watcher ────────
+
+
+class TestFatalErrorCallsEnsureWatcher:
+    """Verify _handle_adapter_fatal_error calls _ensure_reconnect_watcher_running."""
+
+    @pytest.mark.asyncio
+    async def test_retryable_fatal_error_calls_ensure_watcher(self):
+        """A retryable fatal error queues the platform AND ensures watcher is alive."""
+        runner = _make_runner()
+        runner._running = True
+        runner._background_tasks = set()
+        runner._failed_platforms = {}
+        runner._fatal_handler_tasks = set()
+        runner._reconnect_watcher_task = asyncio.create_task(asyncio.sleep(0))
+        # Let the dummy watcher finish so _ensure_reconnect_watcher_running
+        # detects it's dead and respawns.
+        await runner._reconnect_watcher_task
+
+        platform_config = PlatformConfig(enabled=True, token="test")
+        runner.config = GatewayConfig(
+            platforms={Platform.TELEGRAM: platform_config}
+        )
+
+        adapter = StubAdapter(
+            platform=Platform.TELEGRAM,
+            succeed=False,
+            fatal_error="network outage",
+            fatal_retryable=True,
+        )
+        # Pre-set fatal error attributes so the handler can read them
+        # without going through connect() (#70344).
+        adapter._set_fatal_error(
+            "NETWORK_ERROR", "network outage", retryable=True
+        )
+        # Populate adapters so the impl pops it and queues for reconnect
+        runner.adapters[Platform.TELEGRAM] = adapter
+
+        call_count = {"ensure": 0}
+
+        def tracking_ensure():
+            call_count["ensure"] += 1
+
+        with patch.object(
+            runner,
+            "_ensure_reconnect_watcher_running",
+            side_effect=tracking_ensure,
+        ):
+            await runner._handle_adapter_fatal_error(adapter)
+
+        assert Platform.TELEGRAM in runner._failed_platforms
+        assert call_count["ensure"] >= 1
+
+    @pytest.mark.asyncio
+    async def test_nonretryable_fatal_error_does_not_call_ensure(self):
+        """A non-retryable error must NOT queue the platform or call the watcher."""
+        runner = _make_runner()
+        runner._running = True
+        runner._background_tasks = set()
+        runner._failed_platforms = {}
+        runner._fatal_handler_tasks = set()
+        runner._reconnect_watcher_task = None
+
+        platform_config = PlatformConfig(enabled=True, token="test")
+        runner.config = GatewayConfig(
+            platforms={Platform.TELEGRAM: platform_config}
+        )
+
+        adapter = StubAdapter(
+            platform=Platform.TELEGRAM,
+            succeed=False,
+            fatal_error="bad token",
+            fatal_retryable=False,
+        )
+        # Pre-set fatal error attributes so the handler can read them
+        # without going through connect() (#70344).
+        adapter._set_fatal_error(
+            "AUTH_FAILED", "bad token", retryable=False
+        )
+        runner.adapters[Platform.TELEGRAM] = adapter
+
+        ensure_called = False
+
+        def noop_ensure():
+            nonlocal ensure_called
+            ensure_called = True
+
+        with patch.object(runner, "_ensure_reconnect_watcher_running", side_effect=noop_ensure):
+            await runner._handle_adapter_fatal_error(adapter)
+
+        assert Platform.TELEGRAM not in runner._failed_platforms
+        assert not ensure_called
+
+
+# ── _connect_adapter_with_timeout detach-on-timeout ────────────────────
+
+
+class TestConnectAdapterDetachOnTimeout:
+    """Verify _connect_adapter_with_timeout uses the detach pattern."""
+
+    @pytest.mark.asyncio
+    async def test_connect_timed_out_raises_timeouterror(self):
+        """A connect() that never finishes must raise TimeoutError."""
+        runner = _make_runner()
+
+        adapter = StubAdapter(succeed=True)
+
+        async def _slow_connect(**kwargs):
+            await asyncio.sleep(3600)  # never finishes
+
+        with patch.object(adapter, "connect", side_effect=_slow_connect):
+            with patch.object(
+                runner, "_platform_connect_timeout_secs", return_value=0.01
+            ):
+                with pytest.raises(TimeoutError, match="timed out"):
+                    await runner._connect_adapter_with_timeout(
+                        adapter, Platform.TELEGRAM
+                    )
+
+        # After the TimeoutError, the slow connect coroutine should have been
+        # cancelled and detached, so the event loop can move on.
+        await asyncio.sleep(0)
+
+    @pytest.mark.asyncio
+    async def test_connect_success_returns_true(self):
+        """A successful connect returns True."""
+        runner = _make_runner()
+        adapter = StubAdapter(succeed=True)
+
+        with patch.object(
+            runner, "_platform_connect_timeout_secs", return_value=30.0
+        ):
+            result = await runner._connect_adapter_with_timeout(
+                adapter, Platform.TELEGRAM
+            )
+
+        assert result is True
diff --git a/tests/gateway/test_restart_notification.py b/tests/gateway/test_restart_notification.py
index e110eb876e0..a9cca3f65fa 100644
--- a/tests/gateway/test_restart_notification.py
+++ b/tests/gateway/test_restart_notification.py
@@ -7,7 +7,7 @@ from unittest.mock import AsyncMock, MagicMock
 import pytest
 
 import gateway.run as gateway_run
-from gateway.config import HomeChannel, Platform
+from gateway.config import HomeChannel, Platform, PlatformConfig
 from gateway.platforms.base import MessageEvent, MessageType, SendResult
 from gateway.session import build_session_key
 from tests.gateway.restart_test_helpers import (
@@ -77,6 +77,35 @@ async def test_restart_command_writes_notify_file(tmp_path, monkeypatch):
     assert "thread_id" not in data  # no thread → omitted
 
 
+@pytest.mark.asyncio
+async def test_relay_restart_command_persists_authenticated_routing_provenance(
+    tmp_path, monkeypatch
+):
+    monkeypatch.setattr(gateway_run, "_hermes_home", tmp_path)
+
+    runner, _adapter = make_restart_runner()
+    runner.request_restart = MagicMock(return_value=True)
+    source = make_restart_source(chat_id="D123")
+    source.platform = Platform.SLACK
+    source.user_id = "U123"
+    source.scope_id = "T123"
+    source.delivered_via_upstream_relay = True
+    event = MessageEvent(
+        text="/restart",
+        message_type=MessageType.TEXT,
+        source=source,
+        message_id="m-relay-restart",
+    )
+
+    await runner._handle_restart_command(event)
+
+    data = json.loads((tmp_path / ".restart_notify.json").read_text())
+    assert data["platform"] == "slack"
+    assert data["user_id"] == "U123"
+    assert data["scope_id"] == "T123"
+    assert data["delivered_via_upstream_relay"] is True
+
+
 @pytest.mark.asyncio
 async def test_restart_command_uses_service_restart_under_systemd(tmp_path, monkeypatch):
     """Under systemd (INVOCATION_ID set), /restart uses via_service=True."""
@@ -189,6 +218,7 @@ async def test_sethome_updates_running_config_for_same_process_restart(tmp_path,
         saved[key] = value
 
     monkeypatch.setattr("hermes_cli.config.save_env_value", _fake_save_env_value)
+    monkeypatch.setattr("gateway.slash_commands.persist_home_channel", lambda home, **kwargs: None)
 
     runner, _adapter = make_restart_runner()
     source = make_restart_source(chat_id="home-42")
@@ -221,6 +251,7 @@ async def test_sethome_preserves_thread_target_for_same_process_restart(tmp_path
         saved[key] = value
 
     monkeypatch.setattr("hermes_cli.config.save_env_value", _fake_save_env_value)
+    monkeypatch.setattr("gateway.slash_commands.persist_home_channel", lambda home, **kwargs: None)
 
     runner, _adapter = make_restart_runner()
     source = make_restart_source(chat_id="parent-42", thread_id="topic-7")
@@ -243,6 +274,67 @@ async def test_sethome_preserves_thread_target_for_same_process_restart(tmp_path
     assert home.thread_id == "topic-7"
 
 
+@pytest.mark.asyncio
+async def test_relay_sethome_persists_authenticated_logical_owner(monkeypatch):
+    persisted = []
+    monkeypatch.setattr(
+        "gateway.slash_commands.persist_home_channel",
+        lambda home, **kwargs: persisted.append(home),
+    )
+    monkeypatch.setattr("hermes_cli.config.save_env_value", lambda key, value: None)
+
+    runner, _adapter = make_restart_runner()
+    relay = MagicMock()
+    relay.fronts_platform.side_effect = lambda platform: platform == Platform.SLACK
+    runner._adapter_for_source = lambda source: relay
+    source = make_restart_source(chat_id="D123")
+    source.platform = Platform.SLACK
+    source.user_id = "U123"
+    source.scope_id = None
+    source.delivered_via_upstream_relay = True
+    event = MessageEvent(
+        text="/sethome",
+        message_type=MessageType.TEXT,
+        source=source,
+        message_id="m-relay-home",
+    )
+
+    result = await runner._handle_set_home_command(event)
+
+    assert "Home channel set" in result
+    assert len(persisted) == 1
+    assert persisted[0].platform == Platform.SLACK
+    assert persisted[0].chat_id == "D123"
+    assert persisted[0].user_id == "U123"
+    assert runner.config.platforms[Platform.SLACK].enabled is False
+
+
+@pytest.mark.asyncio
+async def test_relay_sethome_rejects_unadvertised_platform(monkeypatch):
+    persist = MagicMock()
+    monkeypatch.setattr("gateway.slash_commands.persist_home_channel", persist)
+
+    runner, _adapter = make_restart_runner()
+    relay = MagicMock()
+    relay.fronts_platform.return_value = False
+    runner._adapter_for_source = lambda source: relay
+    source = make_restart_source(chat_id="D123")
+    source.platform = Platform.SLACK
+    source.user_id = "U123"
+    source.delivered_via_upstream_relay = True
+    event = MessageEvent(
+        text="/sethome",
+        message_type=MessageType.TEXT,
+        source=source,
+        message_id="m-relay-home",
+    )
+
+    result = await runner._handle_set_home_command(event)
+
+    assert "Failed to save" in result
+    persist.assert_not_called()
+
+
 # ── home-channel startup notifications ─────────────────────────────────────
 
 
@@ -370,6 +462,42 @@ async def test_send_home_channel_startup_notification_ignores_false_send_result(
     adapter.send.assert_called_once()
 
 
+@pytest.mark.asyncio
+async def test_relay_fronted_logical_home_gets_startup_notification(tmp_path, monkeypatch):
+    monkeypatch.setattr(gateway_run, "_hermes_home", tmp_path)
+
+    runner, _native = make_restart_runner()
+    relay = MagicMock()
+    relay.fronts_platform.side_effect = lambda platform: platform == Platform.SLACK
+    relay.send_for_platform = AsyncMock(return_value=SendResult(success=True, message_id="home"))
+    runner.adapters = {Platform.RELAY: relay}
+    runner.config.platforms = {
+        Platform.RELAY: PlatformConfig(enabled=True),
+        Platform.SLACK: PlatformConfig(
+            enabled=False,
+            home_channel=HomeChannel(
+                platform=Platform.SLACK,
+                chat_id="D123",
+                name="Owner DM",
+                user_id="U123",
+                scope_id="T123",
+            ),
+        ),
+    }
+
+    delivered = await runner._send_home_channel_startup_notifications()
+
+    assert delivered == {("slack", "D123", None)}
+    relay.send_for_platform.assert_awaited_once()
+    assert relay.send_for_platform.await_args.args[:3] == (
+        Platform.SLACK,
+        "D123",
+        "♻️ Gateway online — Hermes is back and ready.",
+    )
+    assert relay.send_for_platform.await_args.kwargs["metadata"]["user_id"] == "U123"
+    assert relay.send_for_platform.await_args.kwargs["metadata"]["scope_id"] == "T123"
+
+
 # ── _send_restart_notification ───────────────────────────────────────────
 
 
@@ -398,6 +526,46 @@ async def test_send_restart_notification_delivers_and_cleans_up(tmp_path, monkey
     assert not notify_path.exists()
 
 
+@pytest.mark.asyncio
+async def test_relay_restart_notification_uses_logical_platform_and_owner(tmp_path, monkeypatch):
+    monkeypatch.setattr(gateway_run, "_hermes_home", tmp_path)
+    notify_path = tmp_path / ".restart_notify.json"
+    notify_path.write_text(
+        json.dumps(
+            {
+                "platform": "slack",
+                "chat_id": "D123",
+                "chat_type": "dm",
+                "user_id": "U123",
+                "scope_id": "T123",
+                "delivered_via_upstream_relay": True,
+            }
+        )
+    )
+
+    runner, _native = make_restart_runner()
+    relay = MagicMock()
+    relay.fronts_platform.side_effect = lambda platform: platform == Platform.SLACK
+    relay.send_for_platform = AsyncMock(
+        return_value=SendResult(success=True, message_id="restart")
+    )
+    runner.adapters = {Platform.RELAY: relay}
+    runner.config.platforms = {
+        Platform.RELAY: PlatformConfig(enabled=True),
+        Platform.SLACK: PlatformConfig(enabled=False),
+    }
+
+    delivered_target = await runner._send_restart_notification()
+
+    assert delivered_target == ("slack", "D123", None)
+    relay.send_for_platform.assert_awaited_once()
+    assert relay.send_for_platform.await_args.args[0:2] == (Platform.SLACK, "D123")
+    metadata = relay.send_for_platform.await_args.kwargs["metadata"]
+    assert metadata["user_id"] == "U123"
+    assert metadata["scope_id"] == "T123"
+    assert not notify_path.exists()
+
+
 @pytest.mark.asyncio
 async def test_send_restart_notification_with_thread(tmp_path, monkeypatch):
     """Thread ID is passed as metadata so the message lands in the right topic."""
diff --git a/tests/gateway/test_runner_startup_failures.py b/tests/gateway/test_runner_startup_failures.py
index e8bb72b12e4..93d81236bee 100644
--- a/tests/gateway/test_runner_startup_failures.py
+++ b/tests/gateway/test_runner_startup_failures.py
@@ -512,6 +512,60 @@ async def test_runner_exits_with_ex_config_on_nonretryable_startup_error(monkeyp
     assert state["gateway_state"] == "startup_failed"
 
 
+@pytest.mark.asyncio
+async def test_runner_stays_alive_on_mixed_retryable_and_nonretryable_errors(
+    monkeypatch, tmp_path, caplog
+):
+    """Mixed startup failures — one platform fatally misconfigured, another
+    merely transiently failing — must NOT exit with EX_CONFIG (NS-609).
+
+    Real-world shape: WhatsApp enabled but never paired (non-retryable
+    ``whatsapp_not_paired``) while Telegram hits a startup TimedOut
+    (retryable). Exiting 78 here either takes the gateway permanently down
+    (supervisors honoring the exit-78 contract) or crash-loops it (anything
+    else) — and in both cases Telegram never gets its retry even though
+    nothing is wrong with its config. The gateway must stay alive in
+    degraded mode, park the fatal platform, and queue the retryable one."""
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    config = GatewayConfig(
+        platforms={
+            Platform.DISCORD: PlatformConfig(enabled=True, token="***"),
+            Platform.TELEGRAM: PlatformConfig(enabled=True, token="***"),
+        },
+        sessions_dir=tmp_path / "sessions",
+    )
+    runner = GatewayRunner(config)
+
+    def _make_adapter(platform, platform_config):
+        if platform == Platform.DISCORD:
+            return _NonRetryableFailureAdapter()
+        return _RetryableFailureAdapter()
+
+    monkeypatch.setattr(runner, "_create_adapter", _make_adapter)
+
+    import logging
+    with caplog.at_level(logging.ERROR):
+        ok = await runner.start()
+
+    # Gateway stays alive — no clean-exit request, no EX_CONFIG.
+    assert ok is True
+    assert runner.should_exit_cleanly is False
+    assert runner.exit_code is None
+    state = read_runtime_status()
+    assert state["gateway_state"] in {"degraded", "running"}
+    # The retryable platform is queued for reconnection…
+    assert Platform.TELEGRAM in runner._failed_platforms
+    assert state["platforms"]["telegram"]["state"] == "retrying"
+    # …while the misconfigured one is parked as fatal, not retried.
+    assert Platform.DISCORD not in runner._failed_platforms
+    assert state["platforms"]["discord"]["state"] == "fatal"
+    # The fatal side is still surfaced loudly for the operator.
+    assert any(
+        "fatally misconfigured" in record.message
+        for record in caplog.records
+    ), "Expected an error log calling out the parked platform(s)"
+
+
 @pytest.mark.asyncio
 async def test_start_gateway_propagates_fatal_config_exit_code(monkeypatch, tmp_path):
     """A clean exit carrying GATEWAY_FATAL_CONFIG_EXIT_CODE must surface as a
diff --git a/tests/gateway/test_session.py b/tests/gateway/test_session.py
index 2913cc7a1d8..ca86fc72841 100644
--- a/tests/gateway/test_session.py
+++ b/tests/gateway/test_session.py
@@ -5,6 +5,7 @@ from dataclasses import replace
 from datetime import datetime
 from pathlib import Path
 from unittest.mock import patch, MagicMock
+from hermes_state import SessionDB
 from gateway.config import Platform, HomeChannel, GatewayConfig, PlatformConfig
 from gateway.platforms.base import MessageEvent
 from gateway.session import (
@@ -2272,6 +2273,106 @@ class TestRewriteTranscriptPreservesReasoning:
 
 
 class TestGatewaySessionDbRecovery:
+    def test_compression_closed_parent_reroutes_without_retry_queue(self, tmp_path):
+        import threading
+        from types import SimpleNamespace
+
+        db = SessionDB(db_path=tmp_path / "state.db")
+        db.create_session("parent", source="telegram")
+        db.end_session("parent", "compression")
+        db.create_session("child", source="telegram", parent_session_id="parent")
+        db.replace_messages("child", [{"role": "user", "content": "summary"}])
+
+        store = object.__new__(SessionStore)
+        store._db = db
+        store._lock = threading.RLock()
+        store._entries = {"route": SimpleNamespace(session_id="parent")}
+        store._loaded = True
+        store._save = lambda: None
+        store._transcript_retry_lock = threading.Lock()
+        store._dirty_transcripts = {}
+        store._transcript_append_failures = {}
+        store._fts_rebuild_attempted = False
+
+        store.append_to_transcript(
+            "parent", {"role": "assistant", "content": "routed to child"}
+        )
+
+        assert store._entries["route"].session_id == "child"
+        assert "parent" not in store._dirty_transcripts
+        assert [m["content"] for m in db.get_messages_as_conversation("parent")] == []
+        assert [m["content"] for m in db.get_messages_as_conversation("child")] == [
+            "summary",
+            "routed to child",
+        ]
+        db.close()
+
+    def test_transcript_reroute_migrates_remaining_backlog_to_child(self):
+        import threading
+        from types import SimpleNamespace
+        from hermes_state import CompressionSessionClosedError
+
+        class FakeDb:
+            def find_live_compression_child(self, session_id):
+                assert session_id == "parent"
+                return {"id": "child"}
+
+        store = object.__new__(SessionStore)
+        store._db = FakeDb()
+        store._lock = threading.RLock()
+        store._entries = {"route": SimpleNamespace(session_id="parent")}
+        store._loaded = True
+        store._save = lambda: None
+        store._transcript_retry_lock = threading.Lock()
+        store._dirty_transcripts = {
+            "parent": [
+                {"role": "user", "content": "old-1"},
+                {"role": "assistant", "content": "old-2"},
+            ]
+        }
+        store._transcript_append_failures = {"parent": 2}
+        store._fts_rebuild_attempted = True
+        child_attempts = []
+        failed_old_2 = False
+
+        def _append(session_id, message):
+            nonlocal failed_old_2
+            if session_id == "parent":
+                raise CompressionSessionClosedError("parent")
+            child_attempts.append(message["content"])
+            if message["content"] == "old-2" and not failed_old_2:
+                failed_old_2 = True
+                raise RuntimeError("transient child failure")
+
+        store._append_transcript_message = _append
+        store.append_to_transcript(
+            "parent", {"role": "user", "content": "old-3"}
+        )
+
+        assert child_attempts == ["old-1", "old-2"]
+        assert store._entries["route"].session_id == "child"
+        assert "parent" not in store._dirty_transcripts
+        assert [m["content"] for m in store._dirty_transcripts["child"]] == [
+            "old-2",
+            "old-3",
+        ]
+        assert store._transcript_append_failures["child"] >= 2
+
+        # A producer still holding the stale parent id must join and drain the
+        # child backlog before its newer message; no duplicate old-1 is allowed.
+        store.append_to_transcript(
+            "parent", {"role": "assistant", "content": "new-after-reroute"}
+        )
+        assert child_attempts == [
+            "old-1",
+            "old-2",
+            "old-2",
+            "old-3",
+            "new-after-reroute",
+        ]
+        assert "parent" not in store._dirty_transcripts
+        assert "child" not in store._dirty_transcripts
+
     def test_transcript_append_rebuilds_fts_and_retries_dirty_rows_in_order(self):
         import threading
 
diff --git a/tests/gateway/test_session_api.py b/tests/gateway/test_session_api.py
index ac6314f2d28..3f6f28bf7ee 100644
--- a/tests/gateway/test_session_api.py
+++ b/tests/gateway/test_session_api.py
@@ -113,7 +113,10 @@ async def test_run_agent_binds_api_session_context_for_tool_env(adapter, monkeyp
     )
 
     assert result["session_id"] == "request-session"
-    assert usage == {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0}
+    assert usage["input_tokens"] == 0
+    assert usage["output_tokens"] == 0
+    assert usage["total_tokens"] == 0
+    assert "runtime" not in usage
     assert observed == {
         "task_id": "request-session",
         "context_session_id": "request-session",
@@ -173,9 +176,12 @@ async def test_session_crud_and_message_history(adapter, session_db):
 async def test_session_messages_follow_compression_tip(adapter, session_db):
     source_id = session_db.create_session("source-session", "api_server")
     session_db.append_message(source_id, "user", "before compression")
+    # Empty the parent BEFORE closing it: the closed-parent write guard
+    # (CompressionSessionClosedError) refuses durable writes to a session
+    # ended by compression, so the legacy-state simulation must run first.
+    session_db.replace_messages(source_id, [])
     session_db.end_session(source_id, "compression")
     session_db.create_session("tip-session", "api_server", parent_session_id=source_id)
-    session_db.replace_messages(source_id, [])
     session_db.append_message("tip-session", "user", "after compression")
 
     app = _create_session_app(adapter)
@@ -438,3 +444,757 @@ async def test_session_header_rejected_without_api_key(adapter, session_db):
         assert resp.status == 403
         data = await resp.json()
         assert "X-Hermes-Session-Key requires API key" in data["error"]["message"]
+
+
+# ---------------------------------------------------------------------------
+# Session-persisted model threading + provider-auth failure surfacing
+# (salvaged from PR #57947 by @FvanW and PR #59941 by @kaishi00)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_session_chat_threads_session_model_to_run_agent(auth_adapter, session_db):
+    """POST /api/sessions persists a per-session model, but the chat handler
+    previously fetched the session record and threw it away — the session's
+    chosen model silently had no effect on any chat turn."""
+    session_id = session_db.create_session("model-pinned-session", "api_server", model="claude-sonnet-4-6")
+
+    mock_run = AsyncMock(return_value=({"final_response": "ok", "session_id": session_id}, {"total_tokens": 1}))
+    app = _create_session_app(auth_adapter)
+    with patch.object(auth_adapter, "_run_agent", mock_run):
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat",
+                json={"message": "hi"},
+                headers={"Authorization": "Bearer sk-test"},
+            )
+            assert resp.status == 200
+
+    mock_run.assert_awaited_once()
+    _, kwargs = mock_run.call_args
+    assert kwargs["session_model"] == "claude-sonnet-4-6"
+
+
+@pytest.mark.asyncio
+async def test_session_chat_stream_threads_session_model_to_run_agent(adapter, session_db):
+    """Streaming twin of the session-model threading test above."""
+    session_id = session_db.create_session("model-pinned-stream-session", "api_server", model="gpt-5.5")
+
+    mock_run = AsyncMock(return_value=({"final_response": "ok", "session_id": session_id}, {"total_tokens": 1}))
+    app = _create_session_app(adapter)
+    with patch.object(adapter, "_run_agent", mock_run):
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat/stream",
+                json={"message": "hi"},
+            )
+            assert resp.status == 200
+            await resp.read()
+
+    mock_run.assert_awaited_once()
+    _, kwargs = mock_run.call_args
+    assert kwargs["session_model"] == "gpt-5.5"
+
+
+@pytest.mark.asyncio
+async def test_session_chat_resolves_stored_model_route_alias(session_db, monkeypatch):
+    """A session-persisted model that matches a model_routes alias must go
+    through the route path (so route provider/credentials apply) and NOT be
+    passed as a raw session_model (idea from PR #59941 by @kaishi00)."""
+    adapter = APIServerAdapter(
+        PlatformConfig(
+            enabled=True,
+            extra={"model_routes": {"alias": {"model": "route/model", "provider": "openrouter"}}},
+        )
+    )
+    adapter._session_db = session_db
+    session_id = session_db.create_session("route-pinned-session", "api_server", model="alias")
+
+    mock_run = AsyncMock(return_value=({"final_response": "ok", "session_id": session_id}, {"total_tokens": 1}))
+    app = _create_session_app(adapter)
+    with patch.object(adapter, "_run_agent", mock_run):
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat",
+                json={"message": "hi"},
+            )
+            assert resp.status == 200
+
+    _, kwargs = mock_run.call_args
+    assert kwargs["route"] == {"model": "route/model", "provider": "openrouter"}
+    assert kwargs["session_model"] is None
+
+
+@pytest.mark.asyncio
+async def test_run_agent_returns_controlled_response_on_provider_auth_failure(adapter, monkeypatch):
+    """_resolve_runtime_agent_kwargs() (inside _create_agent()) raises
+    RuntimeError on provider auth/credential failure. Previously this
+    propagated unhandled out of _run_agent(): /v1/chat/completions caught it
+    as a generic 500, and /api/sessions/{id}/chat didn't catch it at all
+    (raw aiohttp 500, no JSON body). Must now return run.py's controlled
+    response shape instead of raising. Exercises the REAL boundary
+    (gateway.run._resolve_runtime_agent_kwargs, the sole raiser)."""
+    monkeypatch.setattr(
+        "gateway.run._resolve_runtime_agent_kwargs",
+        lambda: (_ for _ in ()).throw(
+            RuntimeError("No credentials found for provider 'nous' — run `hermes auth add nous`")
+        ),
+    )
+
+    result, usage = await adapter._run_agent(
+        user_message="hello",
+        conversation_history=[],
+        session_id="request-session",
+    )
+
+    assert result == {
+        "final_response": "⚠️ Provider authentication failed: No credentials found for provider 'nous' — run `hermes auth add nous`",
+        "messages": [],
+        "api_calls": 0,
+        "tools": [],
+    }
+    assert usage == {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0}
+
+
+@pytest.mark.asyncio
+async def test_run_agent_does_not_swallow_unrelated_exceptions(adapter, monkeypatch):
+    """The _ProviderAuthResolutionError catch must stay narrow — a TypeError
+    elsewhere in _create_agent()/run_conversation() must still propagate."""
+    def fake_create_agent(**kwargs):
+        raise TypeError("unrelated bug: unexpected keyword argument")
+
+    monkeypatch.setattr(adapter, "_create_agent", fake_create_agent)
+
+    with pytest.raises(TypeError, match="unrelated bug"):
+        await adapter._run_agent(
+            user_message="hello",
+            conversation_history=[],
+            session_id="request-session",
+        )
+
+
+@pytest.mark.asyncio
+async def test_run_agent_does_not_swallow_unrelated_runtime_error_from_run_conversation(adapter, monkeypatch):
+    """agent.run_conversation() can legitimately raise a RuntimeError
+    unrelated to provider auth (e.g. run_agent.py's "Failed to recreate
+    closed OpenAI client"). A bare `except RuntimeError` around the whole
+    _create_agent()+run_conversation() span would mislabel it as
+    "Provider authentication failed". Only _ProviderAuthResolutionError —
+    raised exclusively inside _create_agent() at the
+    _resolve_runtime_agent_kwargs() call site — may trigger the controlled
+    response; this unrelated RuntimeError must propagate unhandled."""
+    class _FakeAgent:
+        def run_conversation(self, **kwargs):
+            raise RuntimeError("Failed to recreate closed OpenAI client")
+
+    monkeypatch.setattr(adapter, "_create_agent", lambda **kwargs: _FakeAgent())
+
+    with pytest.raises(RuntimeError, match="Failed to recreate closed OpenAI client"):
+        await adapter._run_agent(
+            user_message="hello",
+            conversation_history=[],
+            session_id="request-session",
+        )
+
+
+@pytest.mark.asyncio
+async def test_session_chat_surfaces_controlled_response_on_provider_auth_failure(auth_adapter, session_db, monkeypatch):
+    """End-to-end: POST /api/sessions/{id}/chat previously had zero wrapping
+    around _run_agent() — an unhandled RuntimeError produced a raw aiohttp
+    500 with no JSON body. Must now return 200 with the controlled error
+    message as the assistant content. Exercises the real
+    gateway.run._resolve_runtime_agent_kwargs() boundary, not a mocked
+    _create_agent()."""
+    session_id = session_db.create_session("auth-fail-session", "api_server")
+
+    monkeypatch.setattr(
+        "gateway.run._resolve_runtime_agent_kwargs",
+        lambda: (_ for _ in ()).throw(RuntimeError("Auth failed: token expired")),
+    )
+
+    app = _create_session_app(auth_adapter)
+    async with TestClient(TestServer(app)) as cli:
+        resp = await cli.post(
+            f"/api/sessions/{session_id}/chat",
+            json={"message": "hi"},
+            headers={"Authorization": "Bearer sk-test"},
+        )
+        assert resp.status == 200
+        payload = await resp.json()
+
+    assert payload["message"]["content"] == "⚠️ Provider authentication failed: Auth failed: token expired"
+def _register_session_model_route(app, adapter):
+    app.router.add_post("/api/sessions/{session_id}/model", adapter._handle_session_model_lock)
+
+
+def _patch_api_server_runtime(monkeypatch):
+    monkeypatch.setattr(
+        "gateway.run._resolve_runtime_agent_kwargs",
+        lambda: {
+            "provider": "openrouter",
+            "api_key": "sk-global",
+            "base_url": "https://openrouter.example/v1",
+            "api_mode": "chat_completions",
+        },
+    )
+    monkeypatch.setattr("gateway.run._resolve_gateway_model", lambda: "global/model")
+    monkeypatch.setattr("gateway.run._load_gateway_config", lambda: {})
+    monkeypatch.setattr(
+        "gateway.run.GatewayRunner._load_reasoning_config",
+        staticmethod(lambda model="": {}),
+    )
+    monkeypatch.setattr(
+        "gateway.run.GatewayRunner._load_fallback_model",
+        staticmethod(lambda: None),
+    )
+    monkeypatch.setattr("gateway.run._current_max_iterations", lambda: 90)
+    monkeypatch.setattr("hermes_cli.tools_config._get_platform_tools", lambda *_: set())
+    monkeypatch.setattr(
+        "gateway.run._resolve_runtime_agent_kwargs_for_provider",
+        lambda provider: {
+            "provider": provider,
+            "api_key": f"sk-{provider}",
+            "base_url": f"https://{provider}.example/v1",
+            "api_mode": "chat_completions",
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_session_chat_builds_raw_provider_model_route_when_alias_missing(adapter, session_db):
+    session_id = session_db.create_session("route-session", "api_server")
+    mock_run = AsyncMock(
+        return_value=(
+            {
+                "final_response": "ok",
+                "session_id": session_id,
+                "runtime": {"provider": "nous", "model": "x-ai/grok-4.5", "route_source": "raw_request"},
+            },
+            {"total_tokens": 2, "runtime": {"provider": "nous", "model": "x-ai/grok-4.5"}},
+        )
+    )
+    app = _create_session_app(adapter)
+    with patch.object(adapter, "_resolve_route", return_value=None), patch.object(adapter, "_run_agent", mock_run):
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat",
+                json={
+                    "message": "hello",
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "require_model_lock": True,
+                },
+            )
+            assert resp.status == 200, await resp.text()
+            payload = await resp.json()
+
+    kwargs = mock_run.call_args.kwargs
+    assert kwargs["route"] == {"provider": "nous", "model": "x-ai/grok-4.5"}
+    assert payload["runtime"]["provider"] == "nous"
+    assert payload["runtime"]["model"] == "x-ai/grok-4.5"
+    assert payload["runtime"]["requested"]["model"] == "x-ai/grok-4.5"
+
+
+@pytest.mark.asyncio
+async def test_session_chat_passes_runtime_options_to_run_agent(adapter, session_db):
+    session_id = session_db.create_session("options-session", "api_server")
+    mock_run = AsyncMock(return_value=({"final_response": "ok", "session_id": session_id}, {}))
+    app = _create_session_app(adapter)
+    with patch.object(adapter, "_resolve_route", return_value=None), patch.object(adapter, "_run_agent", mock_run):
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat",
+                json={
+                    "message": "hello",
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "model_options": {
+                        "reasoning": {"enabled": True, "effort": "xhigh"},
+                        "service_tier": "priority",
+                        "fast": True,
+                    },
+                },
+            )
+            assert resp.status == 200, await resp.text()
+
+    kwargs = mock_run.call_args.kwargs
+    # In the merged design model_options travel raw to _create_agent, which
+    # parses reasoning/service-tier itself (see _request_reasoning_config /
+    # _request_service_tier) — there is no separate runtime_options kwarg.
+    assert kwargs["model_options"] == {
+        "reasoning": {"enabled": True, "effort": "xhigh"},
+        "service_tier": "priority",
+        "fast": True,
+    }
+
+
+@pytest.mark.asyncio
+async def test_session_chat_stream_uses_same_runtime_lock(adapter, session_db):
+    session_id = session_db.create_session("stream-lock-session", "api_server")
+    captured = {}
+
+    async def fake_run(**kwargs):
+        captured.update(kwargs)
+        kwargs["stream_delta_callback"]("hi")
+        return (
+            {
+                "final_response": "hi",
+                "session_id": session_id,
+                "runtime": {
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "requested": {"provider": "nous", "model": "x-ai/grok-4.5"},
+                    "route_source": "raw_request",
+                },
+            },
+            {
+                "total_tokens": 1,
+                "runtime": {
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "requested": {"provider": "nous", "model": "x-ai/grok-4.5"},
+                },
+            },
+        )
+
+    app = _create_session_app(adapter)
+    with patch.object(adapter, "_resolve_route", return_value=None), patch.object(adapter, "_run_agent", side_effect=fake_run):
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat/stream",
+                json={
+                    "message": "stream",
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "model_options": {"reasoning": {"enabled": False}},
+                    "require_model_lock": True,
+                },
+            )
+            assert resp.status == 200, await resp.text()
+            body = await resp.text()
+
+    assert captured["route"] == {"provider": "nous", "model": "x-ai/grok-4.5"}
+    assert captured["model_options"] == {"reasoning": {"enabled": False}}
+    assert captured["confirmed_runtime_lock"] is True
+    assert "x-ai/grok-4.5" in body
+    assert "run.started" in body or "event: run.started" in body
+
+
+@pytest.mark.asyncio
+async def test_create_session_respects_browser_source_and_model_lock(adapter, session_db):
+    app = _create_session_app(adapter)
+    async with TestClient(TestServer(app)) as cli:
+        resp = await cli.post(
+            "/api/sessions",
+            json={
+                "id": "browser-lock-session",
+                "source": "hermes_browser",
+                "provider": "nous",
+                "model": "x-ai/grok-4.5",
+                "require_model_lock": True,
+                "title": "Browser lock",
+                "system_prompt": "browser prompt",
+            },
+        )
+        assert resp.status == 201, await resp.text()
+        payload = await resp.json()
+
+    assert payload["session"]["source"] == "hermes_browser"
+    assert payload["session"]["model"] == "x-ai/grok-4.5"
+    row = session_db.get_session("browser-lock-session")
+    assert row["source"] == "hermes_browser"
+    assert row["model"] == "x-ai/grok-4.5"
+    import json as _json
+    model_config = row.get("model_config")
+    if isinstance(model_config, str):
+        model_config = _json.loads(model_config)
+    assert model_config["browser_model_lock"]["provider"] == "nous"
+    assert model_config["browser_model_lock"]["model"] == "x-ai/grok-4.5"
+    assert model_config["browser_model_lock"]["confirmed"] is True
+
+
+@pytest.mark.asyncio
+async def test_session_model_lock_endpoint_persists_and_invalidates_prompt(adapter, session_db):
+    session_id = session_db.create_session(
+        "lock-endpoint-session",
+        "api_server",
+        model="gpt-5.5",
+        model_config={"_branched_from": "parent-session"},
+        system_prompt="Conversation started:\nModel: gpt-5.5\nProvider: openai-codex\n",
+    )
+    app = _create_session_app(adapter)
+    _register_session_model_route(app, adapter)
+    with patch.object(adapter, "_resolve_route", return_value=None):
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/model",
+                json={
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "model_options": {"reasoning": {"enabled": True, "effort": "high"}},
+                    "require_model_lock": True,
+                },
+            )
+            assert resp.status == 200, await resp.text()
+            payload = await resp.json()
+
+    assert payload["object"] == "hermes.session.model_lock"
+    assert payload["runtime"]["requested"]["provider"] == "nous"
+    assert payload["runtime"]["model"] == "x-ai/grok-4.5"
+    assert payload["runtime"]["model_lock"] in {"accepted", "confirmed"}
+    row = session_db.get_session(session_id)
+    assert row["model"] == "x-ai/grok-4.5"
+    assert row["system_prompt"] is None
+    import json as _json
+    model_config = row.get("model_config")
+    if isinstance(model_config, str):
+        model_config = _json.loads(model_config)
+    assert model_config["_branched_from"] == "parent-session"
+    assert model_config["browser_model_lock"]["provider"] == "nous"
+
+
+@pytest.mark.asyncio
+async def test_session_model_lock_endpoint_then_chat_reuses_persisted_lock_and_provider_credentials(
+    adapter,
+    session_db,
+    monkeypatch,
+):
+    session_id = session_db.create_session(
+        "endpoint-lock-chat",
+        "api_server",
+        model="gpt-5.5",
+        system_prompt="Conversation started:\nModel: gpt-5.5\nProvider: openai-codex\n",
+    )
+    captured = {}
+
+    class FakeAgent:
+        session_prompt_tokens = 0
+        session_completion_tokens = 0
+        session_total_tokens = 0
+
+        def __init__(self, **kwargs):
+            captured.update(kwargs)
+            self.session_id = kwargs["session_id"]
+            self.provider = kwargs.get("provider") or ""
+            self.model = kwargs.get("model") or ""
+
+        def run_conversation(self, user_message, conversation_history, task_id):
+            return {"final_response": "locked", "session_id": self.session_id}
+
+    _patch_api_server_runtime(monkeypatch)
+    monkeypatch.setattr("run_agent.AIAgent", FakeAgent)
+    monkeypatch.setattr(
+        adapter,
+        "_session_model_override_for",
+        lambda *_: {
+            "model": "session/override-model",
+            "provider": "openai-codex",
+            "api_key": "sk-session-override",
+            "base_url": "https://override.example/v1",
+            "api_mode": "codex_responses",
+        },
+    )
+
+    app = _create_session_app(adapter)
+    _register_session_model_route(app, adapter)
+    with patch.object(adapter, "_resolve_route", return_value=None):
+        async with TestClient(TestServer(app)) as cli:
+            lock_resp = await cli.post(
+                f"/api/sessions/{session_id}/model",
+                json={
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "require_model_lock": True,
+                },
+            )
+            assert lock_resp.status == 200, await lock_resp.text()
+
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat",
+                json={"message": "use the stored lock"},
+            )
+            assert resp.status == 200, await resp.text()
+            payload = await resp.json()
+
+    assert captured["provider"] == "nous"
+    assert captured["model"] == "x-ai/grok-4.5"
+    assert captured["api_key"] == "sk-nous"
+    assert captured["base_url"] == "https://nous.example/v1"
+    assert payload["runtime"]["provider"] == "nous"
+    assert payload["runtime"]["model"] == "x-ai/grok-4.5"
+    assert payload["runtime"]["requested"] == {
+        "provider": "nous",
+        "model": "x-ai/grok-4.5",
+    }
+    assert payload["runtime"]["route_source"] == "session_model_lock"
+
+
+@pytest.mark.asyncio
+async def test_session_model_lock_endpoint_then_chat_stream_reuses_persisted_lock(
+    adapter,
+    session_db,
+):
+    session_id = session_db.create_session("endpoint-lock-stream", "api_server")
+    captured = {}
+
+    async def fake_run(**kwargs):
+        captured.update(kwargs)
+        kwargs["stream_delta_callback"]("hi")
+        return (
+            {
+                "final_response": "hi",
+                "session_id": session_id,
+                "runtime": {
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "requested": {"provider": "nous", "model": "x-ai/grok-4.5"},
+                    "route_source": "session_model_lock",
+                },
+            },
+            {
+                "total_tokens": 1,
+                "runtime": {
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "requested": {"provider": "nous", "model": "x-ai/grok-4.5"},
+                    "route_source": "session_model_lock",
+                },
+            },
+        )
+
+    app = _create_session_app(adapter)
+    _register_session_model_route(app, adapter)
+    with patch.object(adapter, "_resolve_route", return_value=None), patch.object(
+        adapter,
+        "_run_agent",
+        side_effect=fake_run,
+    ):
+        async with TestClient(TestServer(app)) as cli:
+            lock_resp = await cli.post(
+                f"/api/sessions/{session_id}/model",
+                json={
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "require_model_lock": True,
+                },
+            )
+            assert lock_resp.status == 200, await lock_resp.text()
+
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat/stream",
+                json={"message": "stream with stored lock"},
+            )
+            assert resp.status == 200, await resp.text()
+            body = await resp.text()
+
+    assert captured["route"] == {"provider": "nous", "model": "x-ai/grok-4.5"}
+    assert captured["requested_runtime"]["provider"] == "nous"
+    assert captured["requested_runtime"]["model"] == "x-ai/grok-4.5"
+    assert captured["route_source"] == "session_model_lock"
+    assert "x-ai/grok-4.5" in body
+
+
+@pytest.mark.asyncio
+async def test_run_agent_reports_actual_agent_runtime_not_requested_metadata(adapter, monkeypatch):
+    class FakeAgent:
+        session_prompt_tokens = 0
+        session_completion_tokens = 0
+        session_total_tokens = 0
+
+        def __init__(self):
+            self.session_id = "runtime-session"
+            self.provider = "actual-provider"
+            self.model = "actual-model"
+            self._hermes_api_runtime = {
+                "provider": "requested-provider",
+                "model": "requested-model",
+                "route_source": "raw_request",
+            }
+
+        def run_conversation(self, user_message, conversation_history, task_id):
+            return {"final_response": "ok", "session_id": self.session_id}
+
+    monkeypatch.setattr(adapter, "_create_agent", lambda **kwargs: FakeAgent())
+
+    result, usage = await adapter._run_agent(
+        user_message="hello",
+        conversation_history=[],
+        session_id="runtime-session",
+        route={"provider": "requested-provider", "model": "requested-model"},
+        requested_runtime={
+            "provider": "requested-provider",
+            "model": "requested-model",
+        },
+        route_source="session_model_lock",
+    )
+
+    assert result["runtime"]["provider"] == "actual-provider"
+    assert result["runtime"]["model"] == "actual-model"
+    assert result["runtime"]["requested"] == {
+        "provider": "requested-provider",
+        "model": "requested-model",
+    }
+    assert usage["runtime"]["provider"] == "actual-provider"
+    assert usage["runtime"]["model"] == "actual-model"
+
+
+@pytest.mark.asyncio
+async def test_confirmed_runtime_lock_rejects_actual_runtime_mismatch(adapter, monkeypatch):
+    class FakeAgent:
+        session_prompt_tokens = 0
+        session_completion_tokens = 0
+        session_total_tokens = 0
+        session_id = "mismatch-session"
+        provider = "fallback-provider"
+        model = "fallback-model"
+
+        def run_conversation(self, user_message, conversation_history, task_id):
+            return {"final_response": "wrong runtime", "session_id": self.session_id}
+
+    monkeypatch.setattr(adapter, "_create_agent", lambda **kwargs: FakeAgent())
+
+    with pytest.raises(RuntimeError, match="confirmed model lock runtime mismatch"):
+        await adapter._run_agent(
+            user_message="hello",
+            conversation_history=[],
+            session_id="mismatch-session",
+            route={"provider": "nous", "model": "x-ai/grok-4.5"},
+            requested_runtime={"provider": "nous", "model": "x-ai/grok-4.5"},
+            route_source="session_model_lock",
+            confirmed_runtime_lock=True,
+        )
+
+
+def test_confirmed_runtime_lock_fails_closed_on_provider_resolution_error(adapter, monkeypatch):
+    _patch_api_server_runtime(monkeypatch)
+    # Break BOTH resolution paths (primary picker-based resolver + the
+    # gateway fallback) — a confirmed lock must propagate the failure
+    # instead of constructing an agent on the previous global credentials.
+    monkeypatch.setattr(
+        "hermes_cli.runtime_provider.resolve_runtime_provider",
+        lambda **_kwargs: (_ for _ in ()).throw(RuntimeError("provider unavailable")),
+    )
+    monkeypatch.setattr(
+        "gateway.run._resolve_runtime_agent_kwargs_for_provider",
+        lambda provider: (_ for _ in ()).throw(RuntimeError("provider unavailable")),
+    )
+    agent_ctor = patch("run_agent.AIAgent")
+    with agent_ctor as mocked_agent:
+        with pytest.raises(RuntimeError, match="provider unavailable"):
+            adapter._create_agent(
+                session_id="locked-session",
+                route={"provider": "nous", "model": "x-ai/grok-4.5"},
+                confirmed_runtime_lock=True,
+            )
+    mocked_agent.assert_not_called()
+
+
+def test_confirmed_runtime_lock_disables_global_fallback_model(adapter, monkeypatch):
+    _patch_api_server_runtime(monkeypatch)
+    monkeypatch.setattr(
+        "gateway.run.GatewayRunner._load_fallback_model",
+        staticmethod(lambda: "openrouter/fallback-model"),
+    )
+    captured = {}
+
+    class FakeAgent:
+        provider = "nous"
+        model = "x-ai/grok-4.5"
+
+        def __init__(self, **kwargs):
+            captured.update(kwargs)
+
+    monkeypatch.setattr("run_agent.AIAgent", FakeAgent)
+
+    adapter._create_agent(
+        session_id="locked-session",
+        route={"provider": "nous", "model": "x-ai/grok-4.5"},
+        confirmed_runtime_lock=True,
+    )
+
+    assert captured["fallback_model"] is None
+
+
+@pytest.mark.asyncio
+async def test_unconfirmed_request_does_not_replace_confirmed_session_lock(adapter, session_db):
+    session_id = session_db.create_session("one-off-override", "api_server")
+    session_db.update_session_runtime_lock(
+        session_id,
+        provider="nous",
+        model="x-ai/grok-4.5",
+        route_source="raw_request",
+        confirmed=True,
+    )
+    mock_run = AsyncMock(
+        return_value=(
+            {
+                "final_response": "ok",
+                "session_id": session_id,
+                "runtime": {"provider": "openrouter", "model": "anthropic/claude-sonnet"},
+            },
+            {"total_tokens": 1},
+        )
+    )
+    app = _create_session_app(adapter)
+    with patch.object(adapter, "_resolve_route", return_value=None), patch.object(
+        adapter,
+        "_run_agent",
+        mock_run,
+    ):
+        async with TestClient(TestServer(app)) as cli:
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat",
+                json={
+                    "message": "one turn only",
+                    "provider": "openrouter",
+                    "model": "anthropic/claude-sonnet",
+                },
+            )
+            assert resp.status == 200, await resp.text()
+
+    import json as _json
+
+    row = session_db.get_session(session_id)
+    config = row["model_config"]
+    if isinstance(config, str):
+        config = _json.loads(config)
+    assert config["browser_model_lock"]["provider"] == "nous"
+    assert config["browser_model_lock"]["model"] == "x-ai/grok-4.5"
+    assert config["browser_model_lock"]["confirmed"] is True
+
+
+@pytest.mark.asyncio
+async def test_require_model_lock_hard_fails_when_global_default_would_be_used(adapter, session_db, monkeypatch):
+    session_id = session_db.create_session("lock-fail-session", "api_server")
+    monkeypatch.setattr(adapter, "_model_name", "gpt-5.5")
+    app = _create_session_app(adapter)
+    with patch.object(adapter, "_resolve_route", return_value=None), patch.object(adapter, "_run_agent", new_callable=AsyncMock) as mock_run:
+        async with TestClient(TestServer(app)) as cli:
+            # empty model + require_model_lock must not silently fall through
+            resp = await cli.post(
+                f"/api/sessions/{session_id}/chat",
+                json={
+                    "message": "hello",
+                    "provider": "nous",
+                    "model": "",
+                    "require_model_lock": True,
+                },
+            )
+            assert resp.status in (400, 409), await resp.text()
+            body = await resp.json()
+            assert body["error"]["code"] in {"model_lock_unavailable", "invalid_model_lock", "missing_model"}
+    mock_run.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_capabilities_advertises_session_model_lock(adapter):
+    app = _create_session_app(adapter)
+    async with TestClient(TestServer(app)) as cli:
+        resp = await cli.get("/v1/capabilities")
+        assert resp.status == 200
+        data = await resp.json()
+    assert data["features"]["session_model_lock"] is True
+    assert data["endpoints"]["session_model_lock"] == {
+        "method": "POST",
+        "path": "/api/sessions/{session_id}/model",
+    }
diff --git a/tests/gateway/test_session_hygiene.py b/tests/gateway/test_session_hygiene.py
index b41b3037844..9254d1b2663 100644
--- a/tests/gateway/test_session_hygiene.py
+++ b/tests/gateway/test_session_hygiene.py
@@ -1412,3 +1412,208 @@ async def test_session_hygiene_default_hard_message_limit_does_not_fire_at_12_me
     assert FakeCompressAgent.last_instance is None, (
         "Compression should NOT fire at 12 messages with default hard_limit=5000"
     )
+
+
+# ---------------------------------------------------------------------------
+# Progress-aware hygiene wait: slow-but-streaming models are not punished
+# ---------------------------------------------------------------------------
+
+def _make_progress_runner(monkeypatch, tmp_path, agent_cls, cfg_text):
+    """Shared scaffolding for the progress-aware hygiene wait tests."""
+    fake_dotenv = types.ModuleType("dotenv")
+    fake_dotenv.load_dotenv = lambda *args, **kwargs: None
+    monkeypatch.setitem(sys.modules, "dotenv", fake_dotenv)
+
+    fake_run_agent = types.ModuleType("run_agent")
+    fake_run_agent.AIAgent = agent_cls
+    monkeypatch.setitem(sys.modules, "run_agent", fake_run_agent)
+
+    cfg_path = tmp_path / "config.yaml"
+    cfg_path.write_text(cfg_text)
+
+    gateway_run = importlib.import_module("gateway.run")
+    GatewayRunner = gateway_run.GatewayRunner
+
+    adapter = HygieneCaptureAdapter()
+    runner = object.__new__(GatewayRunner)
+    runner.config = GatewayConfig(
+        platforms={Platform.TELEGRAM: PlatformConfig(enabled=True, token="fake-token")}
+    )
+    runner.adapters = {Platform.TELEGRAM: adapter}
+    runner._voice_mode = {}
+    runner.hooks = SimpleNamespace(emit=AsyncMock(), loaded_hooks=False)
+    runner.session_store = MagicMock()
+    runner.session_store.get_or_create_session.return_value = SessionEntry(
+        session_key="agent:main:telegram:dm:12345",
+        session_id="sess-progress",
+        created_at=datetime.now(),
+        updated_at=datetime.now(),
+        platform=Platform.TELEGRAM,
+        chat_type="dm",
+    )
+    runner.session_store.load_transcript.return_value = _make_history(6, content_size=400)
+    runner.session_store.has_any_sessions.return_value = True
+    runner.session_store.rewrite_transcript = MagicMock()
+    runner.session_store.append_to_transcript = MagicMock()
+    runner._running_agents = {}
+    runner._pending_messages = {}
+    runner._pending_approvals = {}
+    runner._session_db = None
+    runner._is_user_authorized = lambda _source: True
+    runner._set_session_env = lambda _context: None
+    runner._run_agent = AsyncMock(
+        return_value={
+            "final_response": "ok",
+            "messages": [],
+            "tools": [],
+            "history_offset": 0,
+            "last_prompt_tokens": 0,
+        }
+    )
+
+    monkeypatch.setattr(gateway_run, "_hermes_home", tmp_path)
+    monkeypatch.setattr(gateway_run, "_resolve_runtime_agent_kwargs", lambda: {"api_key": "fake"})
+    monkeypatch.setattr(
+        "agent.model_metadata.get_model_context_length",
+        lambda *_args, **_kwargs: 100,
+    )
+
+    event = MessageEvent(
+        text="hello",
+        source=SessionSource(
+            platform=Platform.TELEGRAM,
+            chat_id="12345",
+            chat_type="dm",
+            user_id="12345",
+        ),
+        message_id="1",
+    )
+    return runner, adapter, event
+
+
+@pytest.mark.asyncio
+async def test_hygiene_slow_but_streaming_worker_survives_past_timeout(
+    monkeypatch, tmp_path
+):
+    """A summary model still streaming tokens must NOT be killed at the fixed
+    hygiene timeout. The worker here takes several idle windows to finish but
+    ticks fence.touch_progress() continually (as the streamed summary call
+    does per chunk) — the wait must extend and consume the completed result.
+    """
+    class SlowStreamingCompressAgent:
+        last_instance = None
+
+        def __init__(self, **kwargs):
+            self.session_id = kwargs.get("session_id", "fake-session")
+            self._print_fn = None
+            self.shutdown_memory_provider = MagicMock()
+            self.close = MagicMock()
+            type(self).last_instance = self
+
+        def _compress_context(self, messages, *_args, commit_fence=None, **_kwargs):
+            # 6 idle windows of work, ticking progress the whole way.
+            deadline = time.monotonic() + 0.6
+            while time.monotonic() < deadline:
+                if commit_fence is not None:
+                    commit_fence.touch_progress()
+                time.sleep(0.02)
+            if commit_fence is not None and not commit_fence.begin_commit():
+                return (messages, None)
+            try:
+                self.session_id = f"{self.session_id}_compressed"
+                return ([{"role": "assistant", "content": "compressed"}], None)
+            finally:
+                if commit_fence is not None:
+                    commit_fence.finish_commit()
+
+    runner, adapter, event = _make_progress_runner(
+        monkeypatch, tmp_path, SlowStreamingCompressAgent,
+        "compression:\n"
+        "  enabled: true\n"
+        "  hygiene_timeout_seconds: 0.1\n"       # << worker runtime (0.6s)
+        "  hygiene_total_ceiling_seconds: 10\n"
+        "  hygiene_failure_cooldown_seconds: 120\n",
+    )
+    runner._hygiene_compression_failure_cooldowns = {}
+
+    result = await runner._handle_message(event)
+
+    assert result == "ok"
+    assert SlowStreamingCompressAgent.last_instance is not None
+    # The slow-but-alive worker completed: rotation happened, no timeout
+    # warning was delivered, and no failure cooldown was recorded.
+    assert SlowStreamingCompressAgent.last_instance.session_id.endswith("_compressed")
+    timeout_warnings = [
+        s for s in adapter.sent if "Context compression timed out" in s["content"]
+    ]
+    assert timeout_warnings == []
+    assert "sess-progress" not in runner._hygiene_compression_failure_cooldowns
+
+
+@pytest.mark.asyncio
+async def test_hygiene_trickle_stream_is_bounded_by_total_ceiling(
+    monkeypatch, tmp_path
+):
+    """A worker that keeps ticking progress forever must still be cut off at
+    hygiene_total_ceiling_seconds — liveness extends the wait, but not
+    indefinitely."""
+    release_worker = threading.Event()
+
+    class TrickleForeverCompressAgent:
+        last_instance = None
+
+        def __init__(self, **kwargs):
+            self.session_id = kwargs.get("session_id", "fake-session")
+            self._print_fn = None
+            self._last_compaction_in_place = False
+            self.context_compressor = SimpleNamespace(
+                bind_session_state=MagicMock(),
+                _last_compress_aborted=False,
+                _last_aux_model_failure_model=None,
+            )
+            self.shutdown_memory_provider = MagicMock()
+            self.close = MagicMock()
+            type(self).last_instance = self
+
+        def _compress_context(self, messages, *_args, commit_fence=None, **_kwargs):
+            # Ticks progress on every iteration but never finishes until
+            # the test releases it — models a degenerate trickle stream.
+            while not release_worker.wait(0.02):
+                if commit_fence is not None:
+                    commit_fence.touch_progress()
+            if commit_fence is not None and not commit_fence.begin_commit():
+                return (messages, None)
+            try:
+                return (messages, None)
+            finally:
+                if commit_fence is not None:
+                    commit_fence.finish_commit()
+
+    runner, adapter, event = _make_progress_runner(
+        monkeypatch, tmp_path, TrickleForeverCompressAgent,
+        "compression:\n"
+        "  enabled: true\n"
+        "  hygiene_timeout_seconds: 0.1\n"
+        "  hygiene_total_ceiling_seconds: 0.3\n"
+        "  hygiene_failure_cooldown_seconds: 120\n",
+    )
+    runner._hygiene_compression_failure_cooldowns = {}
+    runner._session_db = SimpleNamespace(_db=MagicMock())
+
+    started = time.monotonic()
+    try:
+        result = await runner._handle_message(event)
+    finally:
+        release_worker.set()
+    elapsed = time.monotonic() - started
+
+    assert result == "ok"
+    # Loose wall-clock bound per flake policy: asserts the ceiling stopped
+    # the wait (would otherwise spin until release_worker), not precise
+    # latency.
+    assert elapsed < 5.0
+    timeout_warnings = [
+        s for s in adapter.sent if "Context compression timed out" in s["content"]
+    ]
+    assert len(timeout_warnings) == 1
+    assert runner._hygiene_compression_failure_cooldowns["sess-progress"] > time.time()
diff --git a/tests/gateway/test_status.py b/tests/gateway/test_status.py
index c39285b7534..633e9be0279 100644
--- a/tests/gateway/test_status.py
+++ b/tests/gateway/test_status.py
@@ -723,7 +723,7 @@ class TestTerminatePid:
         calls = []
         monkeypatch.setattr(status, "_IS_WINDOWS", True)
 
-        def fake_run(cmd, capture_output=False, text=False, timeout=None, creationflags=0):
+        def fake_run(cmd, capture_output=False, text=False, timeout=None, creationflags=0, **kwargs):
             calls.append((cmd, capture_output, text, timeout, creationflags))
             return SimpleNamespace(returncode=0, stdout="", stderr="")
 
@@ -2203,3 +2203,174 @@ class TestRuntimeStatusUpdatedAtContract:
         assert parsed.tzinfo is not None
         # And it survives the normalization funnel unchanged (canonical form).
         assert status.normalize_updated_at(updated_at) == updated_at
+
+
+class TestResolveGatewayLiveness:
+    """The single liveness ladder both dashboard status surfaces share.
+
+    Before this existed, /api/status and /api/messaging/platforms each
+    open-coded their own ladder and disagreed on the same page load — the
+    sidebar read "running" while the Channels page rendered "The gateway is
+    not running." These pin the ladder's ordering and its fail-open signal.
+    """
+
+    def test_pid_rung_wins_and_skips_later_rungs(self):
+        calls = {"health": 0, "runtime_pid": 0}
+
+        def _health():
+            calls["health"] += 1
+            return True, {"pid": 999}
+
+        def _runtime_pid(runtime, **kw):
+            calls["runtime_pid"] += 1
+            return 888
+
+        result = status.resolve_gateway_liveness(
+            runtime=None,
+            health_probe=_health,
+            pid_probe=lambda *a, **k: 4242,
+            runtime_pid_probe=_runtime_pid,
+        )
+
+        assert result.running is True
+        assert result.pid == 4242
+        assert result.source == "pid"
+        # The authoritative rung answered: no lower rung should have run.
+        assert calls == {"health": 0, "runtime_pid": 0}
+
+    def test_health_probe_answers_when_no_local_pid(self):
+        """Cross-container gateway: no local PID, but the remote is alive.
+
+        This is the rung /api/messaging/platforms was missing entirely, which
+        is what made it contradict the sidebar in Docker Compose deployments.
+        """
+        result = status.resolve_gateway_liveness(
+            runtime=None,
+            health_probe=lambda: (True, {"pid": 4321, "gateway_state": "running"}),
+            pid_probe=lambda *a, **k: None,
+            runtime_pid_probe=lambda *a, **k: None,
+        )
+
+        assert result.running is True
+        assert result.source == "health"
+        # Display-only PID from the remote container.
+        assert result.pid == 4321
+        assert result.health_body == {"pid": 4321, "gateway_state": "running"}
+
+    def test_runtime_status_rung_answers_when_pid_file_absent(self):
+        """Launch-service-managed gateway: live process, no gateway.pid."""
+        result = status.resolve_gateway_liveness(
+            runtime={"gateway_state": "running", "pid": 777},
+            health_probe=None,
+            pid_probe=lambda *a, **k: None,
+            runtime_pid_probe=lambda *a, **k: 777,
+        )
+
+        assert result.running is True
+        assert result.pid == 777
+        assert result.source == "runtime_status"
+
+    def test_reports_down_when_every_rung_declines(self):
+        result = status.resolve_gateway_liveness(
+            runtime=None,
+            health_probe=lambda: (False, None),
+            pid_probe=lambda *a, **k: None,
+            runtime_pid_probe=lambda *a, **k: None,
+        )
+
+        assert result.running is False
+        assert result.pid is None
+        assert result.source == "none"
+        # Nothing raised, so this is a confident "down", not "unknown".
+        assert result.probe_error is False
+
+    def test_probe_exception_degrades_instead_of_raising(self):
+        """A raising rung must fall through, never propagate.
+
+        Status endpoints poll this constantly; an exotic /proc or a
+        permissions error must not turn into a 500.
+        """
+        def _boom(*a, **k):
+            raise RuntimeError("probe exploded")
+
+        result = status.resolve_gateway_liveness(
+            runtime=None,
+            health_probe=None,
+            pid_probe=_boom,
+            runtime_pid_probe=lambda *a, **k: None,
+        )
+
+        assert result.running is False
+        # probe_error distinguishes "down" from "couldn't tell" for callers
+        # that must fail OPEN (the kanban dispatcher warning).
+        assert result.probe_error is True
+
+    def test_probe_exception_still_lets_a_lower_rung_win(self):
+        def _boom(*a, **k):
+            raise RuntimeError("pid probe exploded")
+
+        result = status.resolve_gateway_liveness(
+            runtime={"gateway_state": "running", "pid": 555},
+            health_probe=None,
+            pid_probe=_boom,
+            runtime_pid_probe=lambda *a, **k: 555,
+        )
+
+        assert result.running is True
+        assert result.source == "runtime_status"
+
+    def test_profile_dir_scopes_every_read_to_that_profile(self, tmp_path):
+        """Gateway identity files live in the per-profile home.
+
+        The status readers resolve process-level paths and deliberately
+        ignore the HERMES_HOME contextvar override (#56986), so the profile
+        directory must be threaded through explicitly or a scoped request
+        silently reports a DIFFERENT profile's gateway (#71211).
+        """
+        profile_dir = tmp_path / "profiles" / "worker"
+        profile_dir.mkdir(parents=True)
+        seen = {}
+
+        def _pid(pid_path=None, **kw):
+            seen["pid_path"] = pid_path
+            return None
+
+        def _reader(path=None):
+            seen["status_path"] = path
+            return None
+
+        def _runtime_pid(runtime, *, expected_home=None):
+            seen["expected_home"] = expected_home
+            return None
+
+        status.resolve_gateway_liveness(
+            profile_dir=profile_dir,
+            health_probe=None,
+            pid_probe=_pid,
+            runtime_reader=_reader,
+            runtime_pid_probe=_runtime_pid,
+        )
+
+        assert seen["pid_path"] == profile_dir / "gateway.pid"
+        assert seen["status_path"] == profile_dir / "gateway_state.json"
+        # expected_home is what stops a recycled PID belonging to another
+        # profile's live gateway from being reported as this profile's.
+        assert seen["expected_home"] == profile_dir
+
+    def test_supplied_runtime_is_not_re_read(self):
+        """Callers that already read the state file must not pay for it twice."""
+        reads = {"count": 0}
+
+        def _reader(path=None):
+            reads["count"] += 1
+            return None
+
+        status.resolve_gateway_liveness(
+            runtime={"gateway_state": "running", "pid": 1},
+            health_probe=None,
+            pid_probe=lambda *a, **k: None,
+            runtime_reader=_reader,
+            runtime_pid_probe=lambda *a, **k: None,
+        )
+
+        assert reads["count"] == 0
diff --git a/tests/gateway/test_telegram_approval_buttons.py b/tests/gateway/test_telegram_approval_buttons.py
index d65b2ad683a..da9297e562c 100644
--- a/tests/gateway/test_telegram_approval_buttons.py
+++ b/tests/gateway/test_telegram_approval_buttons.py
@@ -148,6 +148,78 @@ class TestTelegramExecApproval:
 
         assert buttons == ["✅ Allow Once", "✅ Session", "❌ Deny"]
 
+    @pytest.mark.asyncio
+    async def test_full_approval_keyboard_is_two_by_two(self, monkeypatch):
+        """Regression: d48bf743f flattened all buttons into one row (4x1)."""
+        adapter = _make_adapter()
+        adapter._bot.send_message = AsyncMock(return_value=SimpleNamespace(message_id=42))
+        captured_rows = []
+        monkeypatch.setattr(
+            "plugins.platforms.telegram.adapter.InlineKeyboardButton",
+            lambda text, callback_data: text,
+        )
+        monkeypatch.setattr(
+            "plugins.platforms.telegram.adapter.InlineKeyboardMarkup",
+            lambda rows: captured_rows.extend(rows) or rows,
+        )
+
+        await adapter.send_exec_approval(
+            chat_id="12345", command="curl example.test", session_key="s",
+        )
+
+        assert captured_rows == [
+            ["✅ Allow Once", "✅ Session"],
+            ["✅ Always", "❌ Deny"],
+        ]
+
+    @pytest.mark.asyncio
+    async def test_three_button_keyboard_pairs_then_singleton(self, monkeypatch):
+        adapter = _make_adapter()
+        adapter._bot.send_message = AsyncMock(return_value=SimpleNamespace(message_id=42))
+        captured_rows = []
+        monkeypatch.setattr(
+            "plugins.platforms.telegram.adapter.InlineKeyboardButton",
+            lambda text, callback_data: text,
+        )
+        monkeypatch.setattr(
+            "plugins.platforms.telegram.adapter.InlineKeyboardMarkup",
+            lambda rows: captured_rows.extend(rows) or rows,
+        )
+
+        await adapter.send_exec_approval(
+            chat_id="12345", command="curl example.test", session_key="s",
+            allow_permanent=False,
+        )
+
+        assert captured_rows == [
+            ["✅ Allow Once", "✅ Session"],
+            ["❌ Deny"],
+        ]
+
+    @pytest.mark.asyncio
+    async def test_smart_deny_two_buttons_share_one_row(self, monkeypatch):
+        """smart_deny yields 2 buttons — they pair into a single readable row."""
+        adapter = _make_adapter()
+        adapter._bot.send_message = AsyncMock(return_value=SimpleNamespace(message_id=42))
+        captured_rows = []
+        monkeypatch.setattr(
+            "plugins.platforms.telegram.adapter.InlineKeyboardButton",
+            lambda text, callback_data: text,
+        )
+        monkeypatch.setattr(
+            "plugins.platforms.telegram.adapter.InlineKeyboardMarkup",
+            lambda rows: captured_rows.extend(rows) or rows,
+        )
+
+        await adapter.send_exec_approval(
+            chat_id="12345", command="curl example.test", session_key="s",
+            allow_permanent=False, smart_denied=True,
+        )
+
+        assert captured_rows == [
+            ["✅ Allow Once", "❌ Deny"],
+        ]
+
     @pytest.mark.asyncio
     async def test_stores_approval_state(self):
         adapter = _make_adapter()
diff --git a/tests/gateway/test_telegram_conflict.py b/tests/gateway/test_telegram_conflict.py
index f85034b2f90..15bc02149a8 100644
--- a/tests/gateway/test_telegram_conflict.py
+++ b/tests/gateway/test_telegram_conflict.py
@@ -103,6 +103,14 @@ async def test_polling_conflict_retries_before_fatal(monkeypatch):
 
     async def fake_start_polling(**kwargs):
         captured["error_callback"] = kwargs["error_callback"]
+        # Cold connect requires real getUpdates readiness (#67498) — simulate
+        # the first successful poll for the generation this call started, but
+        # only on the initial connect: the conflict-retry generation must NOT
+        # make progress here, or it would legitimately reset the conflict
+        # count this test asserts on.
+        if not captured.get("initial_done"):
+            captured["initial_done"] = True
+            adapter._record_polling_progress(adapter._polling_generation)
 
     updater = SimpleNamespace(
         start_polling=AsyncMock(side_effect=fake_start_polling),
@@ -228,6 +236,8 @@ async def test_polling_conflict_becomes_fatal_after_retries(monkeypatch):
         if call_count["n"] == 1:
             # First call (initial connect) succeeds
             captured["error_callback"] = kwargs["error_callback"]
+            # Cold connect requires getUpdates readiness (#67498).
+            adapter._record_polling_progress(adapter._polling_generation)
         else:
             # Retry calls fail
             raise Exception("Connection refused")
@@ -367,8 +377,12 @@ async def test_connect_clears_webhook_before_polling(monkeypatch):
         lambda scope, identity: None,
     )
 
+    async def _start_polling_with_progress(**_kwargs):
+        # Cold connect requires getUpdates readiness (#67498).
+        adapter._record_polling_progress(adapter._polling_generation)
+
     updater = SimpleNamespace(
-        start_polling=AsyncMock(),
+        start_polling=AsyncMock(side_effect=_start_polling_with_progress),
         stop=AsyncMock(),
         running=True,
     )
@@ -428,8 +442,12 @@ async def test_connect_does_not_block_on_post_connect_housekeeping(monkeypatch):
     # promptly and expose the still-running task; disconnect() must cancel it.
     monkeypatch.setattr(adapter, "_run_post_connect_housekeeping", _hang_forever)
 
+    async def _start_polling_with_progress(**_kwargs):
+        # Cold connect requires getUpdates readiness (#67498).
+        adapter._record_polling_progress(adapter._polling_generation)
+
     updater = SimpleNamespace(
-        start_polling=AsyncMock(),
+        start_polling=AsyncMock(side_effect=_start_polling_with_progress),
         stop=AsyncMock(),
         running=True,
     )
@@ -528,6 +546,8 @@ async def test_polling_conflict_reschedule_uses_running_loop(monkeypatch):
         call_count["n"] += 1
         if call_count["n"] == 1:
             captured["error_callback"] = kwargs["error_callback"]
+            # Cold connect requires getUpdates readiness (#67498).
+            adapter._record_polling_progress(adapter._polling_generation)
         else:
             # Retry attempt fails so the handler enters the reschedule branch.
             raise Exception("Connection refused")
@@ -585,12 +605,14 @@ async def test_polling_conflict_reschedule_uses_running_loop(monkeypatch):
     await _cancel_heartbeat(adapter)
 
 
-def _build_polling_app(monkeypatch):
+def _build_polling_app(monkeypatch, adapter):
     """Wire a mock PTB Application whose start_polling captures kwargs."""
     captured = {}
 
     async def fake_start_polling(**kwargs):
         captured.update(kwargs)
+        # Cold connect requires getUpdates readiness (#67498).
+        adapter._record_polling_progress(adapter._polling_generation)
 
     updater = SimpleNamespace(
         start_polling=AsyncMock(side_effect=fake_start_polling),
@@ -626,7 +648,7 @@ def _build_polling_app(monkeypatch):
 async def test_cold_connect_drops_pending_updates(monkeypatch):
     """A cold first boot (is_reconnect=False) drops the stale Bot API queue."""
     adapter = TelegramAdapter(PlatformConfig(enabled=True, token="***"))
-    captured = _build_polling_app(monkeypatch)
+    captured = _build_polling_app(monkeypatch, adapter)
 
     ok = await adapter.connect()  # default is_reconnect=False
 
@@ -640,7 +662,7 @@ async def test_reconnect_preserves_pending_updates(monkeypatch):
     """A watcher reconnect (is_reconnect=True) preserves the queue Telegram
     accumulated during the outage — the core of #46621."""
     adapter = TelegramAdapter(PlatformConfig(enabled=True, token="***"))
-    captured = _build_polling_app(monkeypatch)
+    captured = _build_polling_app(monkeypatch, adapter)
 
     ok = await adapter.connect(is_reconnect=True)
 
@@ -714,6 +736,8 @@ async def test_conflict_callback_disarms_before_scheduling(monkeypatch):
 
     async def fake_start_polling(**kwargs):
         captured["error_callback"] = kwargs["error_callback"]
+        # Cold connect requires getUpdates readiness (#67498).
+        adapter._record_polling_progress(adapter._polling_generation)
 
     stop_event = asyncio.Event()
     updater = SimpleNamespace(
diff --git a/tests/gateway/test_telegram_polling_progress.py b/tests/gateway/test_telegram_polling_progress.py
index fdf00e17c99..9f075c189cd 100644
--- a/tests/gateway/test_telegram_polling_progress.py
+++ b/tests/gateway/test_telegram_polling_progress.py
@@ -138,13 +138,20 @@ async def test_polling_disconnect_webhook_reconnect_heals_webhook_send_path(monk
     adapter = _make_adapter()
     polling_app = _lifecycle_app()
     webhook_app = _lifecycle_app()
+
+    async def start_polling_with_progress(**_kwargs):
+        adapter._record_polling_progress(adapter._polling_generation)
+
+    polling_app.updater.start_polling = AsyncMock(
+        side_effect=start_polling_with_progress
+    )
     _configure_lifecycle_connect(monkeypatch, adapter, [polling_app, webhook_app])
     monkeypatch.delenv("TELEGRAM_WEBHOOK_URL", raising=False)
     monkeypatch.delenv("TELEGRAM_WEBHOOK_SECRET", raising=False)
 
     assert await adapter.connect() is True
     assert adapter._webhook_mode is False
-    assert adapter._send_path_degraded is True
+    assert adapter._send_path_degraded is False
     await adapter.disconnect()
 
     monkeypatch.setenv("TELEGRAM_WEBHOOK_URL", "https://example.test/telegram")
diff --git a/tests/gateway/test_telegram_start_polling_timeout.py b/tests/gateway/test_telegram_start_polling_timeout.py
index 12e4ef97b7d..b7e3f7bd69a 100644
--- a/tests/gateway/test_telegram_start_polling_timeout.py
+++ b/tests/gateway/test_telegram_start_polling_timeout.py
@@ -8,9 +8,10 @@ httpx connection pool — it neither returns nor raises. Unbounded, that wedges:
 2. the heartbeat loop (sees the recovery task as alive-but-wedged and skips),
 3. the fatal-error escalation (never reached).
 
-The fix wraps every ``start_polling()`` await in ``asyncio.wait_for`` with
-``_UPDATER_START_TIMEOUT`` so a hung call raises and feeds the existing retry
-ladder. These tests patch the timeout down to keep the suite fast.
+The fix wraps every ``start_polling()`` await in the wall-deadline helper with
+``_UPDATER_START_TIMEOUT`` so a cancellation-shielded hung call still raises and
+feeds the existing retry ladder. These tests patch the timeout down to keep the
+suite fast.
 """
 import asyncio
 import sys
@@ -138,20 +139,141 @@ async def test_start_polling_success_path_unaffected(monkeypatch):
 
 
 def test_every_start_polling_call_site_is_time_bounded():
-    """Bug-class contract: every `updater.start_polling(` await in the adapter
-    must be wrapped in asyncio.wait_for. A new unbounded call site reintroduces
-    the #59614 wedge."""
+    """Every updater.start_polling call must use the wall-deadline helper."""
     import inspect
     import re
 
     src = inspect.getsource(tg_adapter)
-    # Find each start_polling( call and check an enclosing wait_for within the
-    # preceding 6 lines (the wrapper always sits directly above).
     lines = src.splitlines()
     unbounded = []
     for i, line in enumerate(lines):
         if re.search(r"updater\.start_polling\(", line) and "def " not in line:
-            window = "\n".join(lines[max(0, i - 6):i + 1])
-            if "wait_for" not in window:
+            window = "\n".join(lines[max(0, i - 8):i + 1])
+            if "_await_with_thread_deadline" not in window:
                 unbounded.append((i + 1, line.strip()))
     assert not unbounded, f"unbounded start_polling() call sites: {unbounded}"
+
+
+@pytest.mark.asyncio
+async def test_initial_connect_requires_get_updates_progress(monkeypatch):
+    """Cold connect must not claim success before real getUpdates I/O."""
+    monkeypatch.setattr(tg_adapter, "_INITIAL_POLLING_PROGRESS_TIMEOUT", 0.05)
+    a = _bare_adapter()
+    app = MagicMock()
+    app.updater = AsyncMock()
+    app.updater.start_polling = AsyncMock(return_value=None)
+    a._app = app
+
+    with pytest.raises(OSError, match="getUpdates made no progress"):
+        await a._start_polling_resilient(
+            drop_pending_updates=True,
+            error_callback=None,
+            require_progress=True,
+        )
+
+
+@pytest.mark.asyncio
+async def test_initial_connect_succeeds_on_current_generation_progress(monkeypatch):
+    """Strict cold start returns True once THIS generation records progress."""
+    monkeypatch.setattr(tg_adapter, "_INITIAL_POLLING_PROGRESS_TIMEOUT", 5.0)
+    a = _bare_adapter()
+    app = MagicMock()
+    app.updater = AsyncMock()
+
+    async def start_polling_with_progress(**_kwargs):
+        # PTB's instrumented getUpdates request records progress for the
+        # generation started by this call.
+        a._record_polling_progress(a._polling_generation)
+
+    app.updater.start_polling = AsyncMock(side_effect=start_polling_with_progress)
+    a._app = app
+
+    ok = await asyncio.wait_for(
+        a._start_polling_resilient(
+            drop_pending_updates=True,
+            error_callback=None,
+            require_progress=True,
+        ),
+        timeout=10,
+    )
+    assert ok is True
+    assert a._send_path_degraded is False
+    # Strict mode owns readiness itself; the background verifier must not be
+    # racing it on the cold-start application.
+    assert getattr(a, "_polling_progress_verifier_task", None) is None
+
+
+@pytest.mark.asyncio
+async def test_initial_connect_polling_error_fails_fast_not_background(monkeypatch):
+    """#67498 idle-threads shape: a polling error during strict cold start
+    must surface immediately as a connect failure — NOT be swallowed into a
+    background recovery task that restarts polling on the partial app while
+    the readiness gate waits out its full deadline (the G1/G2 race from the
+    #69240 review)."""
+    monkeypatch.setattr(tg_adapter, "_INITIAL_POLLING_PROGRESS_TIMEOUT", 30.0)
+    a = _bare_adapter()
+    app = MagicMock()
+    app.updater = AsyncMock()
+
+    captured_callbacks = []
+
+    async def start_polling_capture(**kwargs):
+        captured_callbacks.append(kwargs.get("error_callback"))
+
+    app.updater.start_polling = AsyncMock(side_effect=start_polling_capture)
+    a._app = app
+
+    recovery_scheduled = []
+    a._schedule_polling_recovery = lambda err, reason: recovery_scheduled.append(err)
+
+    async def run_connect():
+        return await a._start_polling_resilient(
+            drop_pending_updates=True,
+            error_callback=lambda e: recovery_scheduled.append(e),
+            require_progress=True,
+        )
+
+    task = asyncio.ensure_future(run_connect())
+    # Let start_polling run and the strict gate begin waiting.
+    for _ in range(10):
+        await asyncio.sleep(0)
+        if captured_callbacks:
+            break
+    assert captured_callbacks and captured_callbacks[0] is not None
+
+    # PTB reports a network error on the first getUpdates (G1 error).
+    captured_callbacks[0](OSError("getUpdates failed"))
+
+    # The cold attempt must fail promptly (well before the 30s readiness
+    # deadline) with a loud OSError, and must NOT have scheduled background
+    # recovery (which would start G2 on the same partial application).
+    with pytest.raises(OSError, match="errored before first getUpdates"):
+        await asyncio.wait_for(task, timeout=5)
+    assert recovery_scheduled == []
+
+
+@pytest.mark.asyncio
+async def test_initial_connect_ignores_stale_generation_progress(monkeypatch):
+    """Progress recorded for a stale generation must not satisfy readiness."""
+    monkeypatch.setattr(tg_adapter, "_INITIAL_POLLING_PROGRESS_TIMEOUT", 0.1)
+    a = _bare_adapter()
+    app = MagicMock()
+    app.updater = AsyncMock()
+
+    async def start_polling_stale_progress(**_kwargs):
+        # Progress arrives tagged with a PREVIOUS generation (e.g. a late
+        # response from an abandoned attempt) — must be rejected.
+        a._record_polling_progress(a._polling_generation - 1)
+
+    app.updater.start_polling = AsyncMock(side_effect=start_polling_stale_progress)
+    a._app = app
+
+    with pytest.raises(OSError, match="getUpdates made no progress"):
+        await asyncio.wait_for(
+            a._start_polling_resilient(
+                drop_pending_updates=True,
+                error_callback=None,
+                require_progress=True,
+            ),
+            timeout=10,
+        )
diff --git a/tests/gateway/test_unknown_command.py b/tests/gateway/test_unknown_command.py
index 11413449638..c32f5da1bb1 100644
--- a/tests/gateway/test_unknown_command.py
+++ b/tests/gateway/test_unknown_command.py
@@ -146,6 +146,36 @@ async def test_known_slash_command_not_flagged_as_unknown(monkeypatch):
     assert "Unknown command" not in result
 
 
+@pytest.mark.asyncio
+async def test_egress_slash_command_reports_proxy_status(monkeypatch):
+    runner = _make_runner()
+    monkeypatch.setattr(
+        "hermes_cli.proxy_cli.format_status_text",
+        lambda: "Egress proxy status\nEnabled: no",
+    )
+
+    result = await runner._handle_message(_make_event("/egress"))
+
+    assert result is not None
+    assert "Egress proxy status" in result
+    assert "Unknown command" not in result
+
+
+@pytest.mark.asyncio
+async def test_egress_slash_command_reports_proxy_status_while_agent_running(monkeypatch):
+    runner = _make_runner()
+    runner._running_agents[build_session_key(_make_source())] = MagicMock()
+    monkeypatch.setattr(
+        "hermes_cli.proxy_cli.format_status_text",
+        lambda: "Egress proxy status\nEnabled: yes",
+    )
+
+    result = await runner._handle_message(_make_event("/egress"))
+
+    assert result is not None
+    assert "Egress proxy status" in result
+
+
 @pytest.mark.asyncio
 async def test_underscored_alias_for_hyphenated_builtin_not_flagged(monkeypatch):
     """Telegram autocomplete sends /reload_mcp for the /reload-mcp built-in.
diff --git a/tests/gateway/test_webhook_integration.py b/tests/gateway/test_webhook_integration.py
index 9312ac0e999..dea960bba1d 100644
--- a/tests/gateway/test_webhook_integration.py
+++ b/tests/gateway/test_webhook_integration.py
@@ -331,6 +331,8 @@ class TestGitHubCommentDelivery:
             ],
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=30,
         )
         # Delivery info is retained after send() so interim status messages
diff --git a/tests/gateway/test_whatsapp_connect.py b/tests/gateway/test_whatsapp_connect.py
index 52e36f5b7c2..374ed74b8a7 100644
--- a/tests/gateway/test_whatsapp_connect.py
+++ b/tests/gateway/test_whatsapp_connect.py
@@ -591,6 +591,8 @@ class TestHttpSessionLifecycle:
             ["taskkill", "/PID", "12345", "/T"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=10,
         )
         mock_proc.terminate.assert_not_called()
diff --git a/tests/hermes_cli/test_authenticated_providers_exhausted_pool.py b/tests/hermes_cli/test_authenticated_providers_exhausted_pool.py
index 988de9c72f1..b8e4aeb4f61 100644
--- a/tests/hermes_cli/test_authenticated_providers_exhausted_pool.py
+++ b/tests/hermes_cli/test_authenticated_providers_exhausted_pool.py
@@ -114,3 +114,61 @@ def test_picker_shows_exhausted_pool_provider(monkeypatch):
         "Picker must show exhausted-pool providers so the user can select "
         "a different model under the same provider"
     )
+
+
+class _StopPicker(BaseException):
+    """Aborts a picker right after it requests its provider list, before any
+    interactive prompt. Subclasses BaseException so the picker's own
+    ``except Exception`` guards don't swallow it."""
+
+
+def _spy_list_authenticated(recorded: dict):
+    def _spy(*_args, **kwargs):
+        recorded.update(kwargs)
+        raise _StopPicker
+    return _spy
+
+
+def test_aux_task_picker_requests_exhausted_pool_visibility(monkeypatch):
+    """The ``hermes model`` auxiliary-task picker (``_aux_select_for_task``)
+    must request exhausted-pool visibility (``for_picker=True``) like the
+    ``/model`` picker (#66584).
+
+    The aux picker writes a *persistent* per-task provider/model config that
+    the user runs later — long after a momentary rate-limit cooldown clears —
+    so silently hiding a provider whose keys are all exhausted is exactly the
+    bug the #66584 picker fix addressed, one interactive picker over.
+    """
+    import hermes_cli.main as main
+
+    recorded: dict = {}
+    monkeypatch.setattr(
+        "hermes_cli.model_switch.list_authenticated_providers",
+        _spy_list_authenticated(recorded),
+    )
+    monkeypatch.setattr("hermes_cli.config.load_config", lambda: {})
+
+    with pytest.raises(_StopPicker):
+        main._aux_select_for_task("compression")
+
+    assert recorded.get("for_picker") is True, (
+        "aux-task picker must pass for_picker=True so exhausted-pool providers "
+        "stay selectable (before the fix it omitted the flag → hidden)"
+    )
+
+
+def test_vision_provider_picker_requests_exhausted_pool_visibility(monkeypatch):
+    """The vision provider/model picker (``_configure_vision_provider_model``)
+    must also request exhausted-pool visibility — same rationale as #66584."""
+    import hermes_cli.tools_config as tc
+
+    recorded: dict = {}
+    monkeypatch.setattr(
+        "hermes_cli.model_switch.list_authenticated_providers",
+        _spy_list_authenticated(recorded),
+    )
+
+    with pytest.raises(_StopPicker):
+        tc._configure_vision_provider_model({}, {})
+
+    assert recorded.get("for_picker") is True
diff --git a/tests/hermes_cli/test_aux_picker_inventory.py b/tests/hermes_cli/test_aux_picker_inventory.py
new file mode 100644
index 00000000000..73ac3628a68
--- /dev/null
+++ b/tests/hermes_cli/test_aux_picker_inventory.py
@@ -0,0 +1,239 @@
+"""Auxiliary-task pickers share one provider-inventory substrate.
+
+Every aux picker (``hermes model`` → Configure auxiliary models, the
+``hermes tools`` vision picker, and any future one) must route through
+``hermes_cli.inventory.build_aux_picker_rows()`` so it shows the same
+provider universe as ``/model``.
+
+Two independent contributor PRs fixed the same two call sites for exactly
+this reason:
+
+- #52642 (@deepjia) — user ``providers:`` / ``custom_providers:`` entries
+  were invisible because the aux picker never forwarded them.
+- #66624 (@Drexuxux) — providers with a fully rate-limited credential pool
+  were hidden because the aux picker never forwarded ``for_picker``.
+
+Both were per-call-site kwarg patches, so the next aux picker would have
+reintroduced the gap. These tests pin the *shared substrate* behaviour and
+guard the seam itself, not the kwargs at any one site.
+"""
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+import yaml
+
+
+CONFIG = {
+    "model": {"provider": "openrouter", "default": "anthropic/claude-opus-4.6"},
+    "model_catalog": {"excluded_providers": ["copilot"]},
+    "providers": {
+        "my-llm": {
+            "name": "My LLM",
+            "base_url": "https://myllm.example.com/v1",
+            "key_env": "MYLLM_KEY",
+            "discover_models": False,
+            "models": {"big-model": {}, "small-model": {}},
+        }
+    },
+    "custom_providers": [
+        {
+            "name": "Legacy Box",
+            "base_url": "https://legacy.example.com/v1",
+            "key_env": "LEGACY_KEY",
+            "model": "legacy-1",
+            "discover_models": False,
+        }
+    ],
+}
+
+
+@pytest.fixture
+def configured_home(tmp_path, monkeypatch):
+    """A HERMES_HOME with one ``providers:`` entry and one legacy
+    ``custom_providers:`` entry, both credentialled via env."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(yaml.safe_dump(CONFIG))
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-test")
+    monkeypatch.setenv("MYLLM_KEY", "sk-mine")
+    monkeypatch.setenv("LEGACY_KEY", "sk-legacy")
+    return home
+
+
+# ─── The substrate contract ─────────────────────────────────────────────
+
+
+def test_aux_picker_surfaces_user_defined_providers(configured_home):
+    """Both config schemas for a user's own endpoint reach an aux picker.
+
+    This is #52642's bug: the aux picker built its own kwargs and passed
+    neither ``user_providers`` nor ``custom_providers``, so a user who had
+    configured their own endpoint could not route any auxiliary task to it.
+    """
+    from hermes_cli.inventory import build_aux_picker_rows
+
+    slugs = {r["slug"] for r in build_aux_picker_rows()}
+
+    assert "my-llm" in slugs, (
+        "a keyed providers: entry must be selectable for auxiliary tasks"
+    )
+    assert "custom:legacy-box" in slugs, (
+        "a legacy custom_providers: entry must be selectable for auxiliary tasks"
+    )
+
+
+def test_aux_picker_carries_configured_models_for_user_provider(configured_home):
+    """A user provider arrives with its configured model list, so the
+    follow-up model prompt has something to offer."""
+    from hermes_cli.inventory import build_aux_picker_rows
+
+    row = next(r for r in build_aux_picker_rows() if r["slug"] == "my-llm")
+
+    assert set(row["models"]) == {"big-model", "small-model"}
+
+
+def test_aux_picker_honors_excluded_providers(configured_home):
+    """``model_catalog.excluded_providers`` applies to aux pickers too.
+
+    A provider the user hid from ``/model`` must not reappear in an aux
+    picker — the exclusion is about the provider, not about one surface.
+    """
+    from hermes_cli.inventory import build_aux_picker_rows
+
+    slugs = {str(r["slug"]).lower() for r in build_aux_picker_rows()}
+
+    assert "copilot" not in slugs
+
+
+def test_aux_picker_omits_virtual_moa_row(configured_home):
+    """MoA is not a real endpoint and auxiliary_client unwraps it to the
+    aggregator slot, so offering it in an aux picker would be a selection
+    silently rewritten behind the user's back."""
+    from hermes_cli.inventory import build_aux_picker_rows
+
+    cfg = dict(CONFIG)
+    cfg["moa"] = {"presets": {"opus-gpt": {}}}
+    (configured_home / "config.yaml").write_text(yaml.safe_dump(cfg))
+
+    slugs = {str(r["slug"]).lower() for r in build_aux_picker_rows()}
+
+    assert "moa" not in slugs
+
+
+def test_aux_picker_requests_exhausted_pool_visibility(configured_home):
+    """#66624: a provider whose credential pool is entirely rate-limited
+    must stay visible. Rate limits are per-model and the aux picker writes a
+    config the user runs later, once the cooldown has cleared."""
+    from hermes_cli import inventory
+
+    seen = {}
+
+    def _capture(**kwargs):
+        seen.update(kwargs)
+        return []
+
+    with patch("hermes_cli.model_switch.list_authenticated_providers", _capture):
+        inventory.build_aux_picker_rows()
+
+    assert seen.get("for_picker") is True
+
+
+def test_aux_picker_does_not_block_on_offline_saved_endpoints(configured_home):
+    """Saved custom endpoints are not live-probed on open (a dead local
+    server would hang the picker); only the active one is."""
+    from hermes_cli import inventory
+
+    seen = {}
+
+    def _capture(**kwargs):
+        seen.update(kwargs)
+        return []
+
+    with patch("hermes_cli.model_switch.list_authenticated_providers", _capture):
+        inventory.build_aux_picker_rows()
+
+    assert seen.get("probe_custom_providers") is False
+    assert seen.get("probe_current_custom_provider") is True
+
+
+# ─── Shared rendering ───────────────────────────────────────────────────
+
+
+def test_format_entries_marks_current_provider():
+    from hermes_cli.inventory import format_aux_picker_entries
+
+    rows = [
+        {"slug": "my-llm", "name": "My LLM", "models": ["a", "b"], "total_models": 2},
+        {"slug": "openrouter", "name": "OpenRouter", "models": ["x"], "total_models": 1},
+    ]
+
+    entries = format_aux_picker_entries(rows, current_provider="my-llm")
+
+    assert entries[0] == ("my-llm", "My LLM — 2 models  ← current", ["a", "b"])
+    assert entries[1] == ("openrouter", "OpenRouter — 1 models", ["x"])
+
+
+def test_format_entries_base_url_owns_current_marker():
+    """When the task points at a raw base_url, the current selection is the
+    URL — no provider row may claim the marker."""
+    from hermes_cli.inventory import format_aux_picker_entries
+
+    rows = [{"slug": "my-llm", "name": "My LLM", "models": ["a"], "total_models": 1}]
+
+    entries = format_aux_picker_entries(
+        rows, current_provider="my-llm", current_base_url="https://elsewhere/v1"
+    )
+
+    assert "← current" not in entries[0][1]
+
+
+# ─── Seam guard ─────────────────────────────────────────────────────────
+
+
+def test_aux_pickers_route_through_the_shared_substrate(configured_home):
+    """Neither aux picker may call ``list_authenticated_providers`` directly.
+
+    This is the regression that produced #52642 and #66624 as two separate
+    contributor PRs against the same two call sites: a picker calling the
+    low-level function re-derives its own kwargs and drops whichever slice
+    of user config the author didn't think about. Both pickers must reach
+    the provider list only through ``build_aux_picker_rows``.
+    """
+    import hermes_cli.main as main
+    import hermes_cli.tools_config as tools_config
+
+    direct_calls = []
+    substrate_calls = []
+
+    def _direct(**kwargs):
+        direct_calls.append(kwargs)
+        return []
+
+    def _substrate(**kwargs):
+        substrate_calls.append(kwargs)
+        return []
+
+    # Abort each picker at its first prompt, right after it has asked for its
+    # provider list. The vision picker returns early on empty rows; the
+    # aux-task picker still renders auto/custom/back, so cancel its menu.
+    with (
+        patch("hermes_cli.model_switch.list_authenticated_providers", _direct),
+        patch("hermes_cli.inventory.build_aux_picker_rows", _substrate),
+        patch("hermes_cli.main._prompt_provider_choice", return_value=None),
+    ):
+        main._aux_select_for_task("compression")
+        tools_config._configure_vision_provider_model({}, {})
+
+    assert len(substrate_calls) == 2, (
+        "both the aux-task picker and the vision picker must source providers "
+        f"from build_aux_picker_rows (got {len(substrate_calls)} calls)"
+    )
+    assert direct_calls == [], (
+        "aux pickers must not call list_authenticated_providers directly — "
+        "route through hermes_cli.inventory.build_aux_picker_rows so custom "
+        "providers, exclusions, and picker visibility stay consistent"
+    )
diff --git a/tests/hermes_cli/test_backup.py b/tests/hermes_cli/test_backup.py
index cbac29eae50..98e0ae8de97 100644
--- a/tests/hermes_cli/test_backup.py
+++ b/tests/hermes_cli/test_backup.py
@@ -1431,6 +1431,29 @@ class TestSafeCopyDb:
         assert rows == [("wal-test",)]
 
 
+
+    def test_is_zeroed_sqlite_file_detects_nul_header(self, tmp_path):
+        from hermes_cli.backup import is_zeroed_sqlite_file
+        p = tmp_path / "state.db"
+        p.write_bytes(bytes(4096))  # all NULs
+        assert is_zeroed_sqlite_file(p) is True
+
+    def test_is_zeroed_sqlite_file_rejects_valid_db(self, tmp_path):
+        from hermes_cli.backup import is_zeroed_sqlite_file
+        p = tmp_path / "ok.db"
+        conn = sqlite3.connect(str(p))
+        conn.execute("CREATE TABLE t (x INT)")
+        conn.commit()
+        conn.close()
+        assert is_zeroed_sqlite_file(p) is False
+
+    def test_is_zeroed_sqlite_file_empty_file(self, tmp_path):
+        from hermes_cli.backup import is_zeroed_sqlite_file
+        p = tmp_path / "empty.db"
+        p.write_bytes(b"")
+        assert is_zeroed_sqlite_file(p) is False
+
+
 # ---------------------------------------------------------------------------
 # Quick state snapshot tests
 # ---------------------------------------------------------------------------
@@ -1477,13 +1500,32 @@ class TestQuickSnapshot:
         snap_id = create_quick_snapshot(hermes_home=hermes_home)
         db_copy = hermes_home / "state-snapshots" / snap_id / "state.db"
         assert db_copy.exists()
-
         conn = sqlite3.connect(str(db_copy))
         rows = conn.execute("SELECT * FROM sessions").fetchall()
         conn.close()
         assert len(rows) == 1
         assert rows[0] == ("s1", "hello world")
 
+    def test_failed_state_db_copy_is_loud(self, hermes_home, monkeypatch, capsys):
+        """#68474: unreadable state.db must not look like a silent success."""
+        from hermes_cli import backup as backup_mod
+
+        def boom(src, dst):
+            return False
+
+        monkeypatch.setattr(backup_mod, "_safe_copy_db", boom)
+        snap_id = backup_mod.create_quick_snapshot(hermes_home=hermes_home)
+        err = capsys.readouterr().out
+        assert "SQLite safe copy FAILED" in err or "CRITICAL" in err
+        assert "state.db" in err
+        # Other small files may still snapshot
+        if snap_id:
+            manifest = (hermes_home / "state-snapshots" / snap_id / "manifest.json")
+            assert manifest.exists()
+            data = json.loads(manifest.read_text(encoding="utf-8"))
+            assert "state.db" not in data.get("files", {})
+            assert "state.db" in data.get("failed_dbs", [])
+
     def test_copies_nested_files(self, hermes_home):
         from hermes_cli.backup import create_quick_snapshot
         snap_id = create_quick_snapshot(hermes_home=hermes_home)
@@ -1781,6 +1823,56 @@ class TestQuickSnapshot:
         # Cleanup the seeded escape source so the test is hermetic.
         escape_src.unlink()
 
+    def test_oversized_db_suppresses_pruning(self, hermes_home, capsys):
+        """#68805: an oversized state.db skipped for size must suppress
+        pruning so the older complete snapshot (containing the only
+        recoverable database) is preserved.
+
+        Reproduces the reviewer's scenario: keep=1 + a state.db exceeding
+        the size cap → the new snapshot omits state.db, failed_dbs stays
+        empty (the file wasn't unreadable, just too large), and without
+        tracking oversized_skipped the older complete snapshot would be
+        pruned — losing the only recovery copy.
+        """
+        import json
+        import time as _t
+        from hermes_cli.backup import create_quick_snapshot, list_quick_snapshots
+
+        # First snapshot: complete (state.db is small, under any cap)
+        first_id = create_quick_snapshot(label="complete", hermes_home=hermes_home)
+        assert first_id is not None
+        first_dir = hermes_home / "state-snapshots" / first_id
+        assert (first_dir / "state.db").exists()
+
+        _t.sleep(1.05)  # ensure distinct timestamp
+
+        # Second snapshot: state.db exceeds the 1024-byte cap → skipped for
+        # size, but small config files (32-54 bytes) still land in the manifest.
+        second_id = create_quick_snapshot(
+            label="oversized", hermes_home=hermes_home, max_file_size=1024, keep=1
+        )
+        assert second_id is not None
+        second_dir = hermes_home / "state-snapshots" / second_id
+        assert not (second_dir / "state.db").exists()
+
+        # Manifest must record the oversized skip
+        with open(second_dir / "manifest.json") as f:
+            meta = json.load(f)
+        assert "state.db" in meta.get("oversized_skipped", [])
+
+        # CRITICAL: the first (complete) snapshot must survive pruning
+        # because the second snapshot is incomplete (oversized state.db).
+        all_snaps = list_quick_snapshots(limit=100, hermes_home=hermes_home)
+        snap_ids = {s["id"] for s in all_snaps}
+        assert first_id in snap_ids, (
+            f"Complete snapshot {first_id} was pruned by an incomplete "
+            f"(oversized) snapshot — the recovery copy was lost!"
+        )
+        assert second_id in snap_ids
+
+        out = capsys.readouterr().out
+        assert "skipping state.db" in out.lower() or "skipping snapshot prune" in out.lower()
+
 
 class TestQuickSnapshotProjectsKanban:
     """Regression for #52889: projects.db / kanban.db must survive an upgrade.
diff --git a/tests/hermes_cli/test_certifi_repair.py b/tests/hermes_cli/test_certifi_repair.py
new file mode 100644
index 00000000000..a52f24167bf
--- /dev/null
+++ b/tests/hermes_cli/test_certifi_repair.py
@@ -0,0 +1,250 @@
+"""Regression tests for issue #29866.
+
+A brew Python upgrade (or an interrupted venv rebuild — see also the v0.19.0
+report in the same issue) can leave ``certifi`` importable while its bundled
+``cacert.pem`` is missing or a dangling symlink. Every TLS connection then
+fails with an opaque ``Could not find a suitable TLS CA certificate bundle``
+and the gateway is down on all platforms.
+
+Behavior contracts pinned here:
+
+1. The venv-repair import probes (early recovery + `hermes update`) must
+   classify certifi as BROKEN when the module imports but ``cacert.pem`` is
+   missing or corrupt — an attribute probe alone passes in that state.
+2. ``hermes doctor`` must fail the certificate check in that state, and
+   ``hermes doctor --fix`` must repair by force-reinstalling certifi and
+   re-verifying.
+"""
+
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+import hermes_cli._early_recovery as er
+
+
+def _fake_certifi(monkeypatch, bundle_path: Path):
+    """Install a fake certifi module whose where() points at bundle_path."""
+    fake = types.ModuleType("certifi")
+    fake.contents = lambda: ""  # satisfies the ('certifi', 'contents') probe
+    fake.where = lambda: str(bundle_path)
+    monkeypatch.setitem(sys.modules, "certifi", fake)
+    return fake
+
+
+# =========================================================================
+# 1. Import probes detect a missing/corrupt cacert.pem
+# =========================================================================
+
+
+class TestEarlyRecoveryCertifiBundleProbe:
+    def test_missing_bundle_flags_certifi_broken(self, monkeypatch, tmp_path):
+        _fake_certifi(monkeypatch, tmp_path / "nonexistent" / "cacert.pem")
+        broken = er._probe_broken_packages()
+        assert "certifi" in broken, (
+            "certifi imports but cacert.pem is missing — the probe must flag "
+            "it broken (#29866); the attribute check alone passes here"
+        )
+
+    def test_tiny_bundle_flags_certifi_broken(self, monkeypatch, tmp_path):
+        bundle = tmp_path / "cacert.pem"
+        bundle.write_text("truncated", encoding="utf-8")
+        _fake_certifi(monkeypatch, bundle)
+        broken = er._probe_broken_packages()
+        assert "certifi" in broken
+
+    def test_healthy_bundle_not_flagged(self, monkeypatch):
+        import certifi as real_certifi
+
+        # Real certifi with a real bundle: probe must NOT flag it.
+        monkeypatch.setitem(sys.modules, "certifi", real_certifi)
+        broken = er._probe_broken_packages()
+        assert "certifi" not in broken
+
+    def test_where_raising_flags_certifi_broken(self, monkeypatch):
+        fake = types.ModuleType("certifi")
+        fake.contents = lambda: ""
+
+        def _boom():
+            raise OSError("simulated broken installation")
+
+        fake.where = _boom
+        monkeypatch.setitem(sys.modules, "certifi", fake)
+        broken = er._probe_broken_packages()
+        assert "certifi" in broken
+
+
+class TestUpdateProbeScriptChecksBundle:
+    """The subprocess probe used by `hermes update`'s venv repair must apply
+    the same bundle-file check inside the target venv's interpreter."""
+
+    def _run_probe_script(self, monkeypatch, tmp_path, bundle_path):
+        """Extract the generated probe script and run it in-process against a
+        fake certifi that points at bundle_path."""
+        from hermes_cli import main as main_mod
+
+        captured = {}
+
+        def fake_run(cmd, **kwargs):
+            captured["script"] = cmd[-1]
+
+            class _R:
+                returncode = 0
+                stdout = ""
+                stderr = ""
+
+            return _R()
+
+        monkeypatch.setattr(main_mod.subprocess, "run", fake_run)
+        monkeypatch.setattr(
+            main_mod, "_resolve_install_target_python", lambda *a, **k: sys.executable
+        )
+        main_mod._detect_broken_lazy_refresh_imports(["pip"])
+        script = captured["script"]
+
+        # Execute the probe script with a fake certifi installed.
+        _fake_certifi(monkeypatch, bundle_path)
+        printed = []
+        namespace = {"__builtins__": __builtins__}
+        import builtins as _b
+
+        real_print = _b.print
+        monkeypatch.setattr(
+            _b, "print", lambda *a, **k: printed.append(" ".join(map(str, a)))
+        )
+        try:
+            exec(script, namespace)
+        finally:
+            monkeypatch.setattr(_b, "print", real_print)
+        return "\n".join(printed)
+
+    def test_probe_script_reports_certifi_when_bundle_missing(
+        self, monkeypatch, tmp_path
+    ):
+        out = self._run_probe_script(
+            monkeypatch, tmp_path, tmp_path / "missing" / "cacert.pem"
+        )
+        assert "certifi" in out.splitlines()
+
+    def test_probe_script_quiet_when_bundle_healthy(self, monkeypatch, tmp_path):
+        import certifi as real_certifi
+
+        out = self._run_probe_script(
+            monkeypatch, tmp_path, Path(real_certifi.where())
+        )
+        assert "certifi" not in out.splitlines()
+
+
+# =========================================================================
+# 2. hermes doctor: detection and --fix repair
+# =========================================================================
+
+
+class TestDoctorCertificates:
+    def test_broken_bundle_fails_without_fix(self, monkeypatch, capsys, tmp_path):
+        from hermes_cli import doctor as doctor_mod
+
+        monkeypatch.setenv("SSL_CERT_FILE", str(tmp_path / "missing.pem"))
+        issues = []
+        doctor_mod.check_certificates(should_fix=False, issues=issues)
+        out = capsys.readouterr().out
+        assert "broken" in out.lower()
+        assert issues, "a broken bundle must be funneled into the action list"
+        assert any("doctor --fix" in i for i in issues)
+
+    def test_fix_reinstalls_certifi_and_reverifies(self, monkeypatch, capsys, tmp_path):
+        from hermes_cli import doctor as doctor_mod
+
+        # First verification fails, post-reinstall verification succeeds.
+        calls = {"verify": 0, "pip": []}
+
+        def fake_verify():
+            calls["verify"] += 1
+            if calls["verify"] == 1:
+                from agent.errors import SSLConfigurationError
+
+                raise SSLConfigurationError("certifi points to a missing CA bundle")
+
+        def fake_run(cmd, **kwargs):
+            calls["pip"].append(cmd)
+
+            class _R:
+                returncode = 0
+                stdout = ""
+                stderr = ""
+
+            return _R()
+
+        monkeypatch.setattr(
+            "agent.ssl_guard.verify_ca_bundle_with_fallback", fake_verify
+        )
+        monkeypatch.setattr(doctor_mod.subprocess, "run", fake_run)
+
+        issues = []
+        doctor_mod.check_certificates(should_fix=True, issues=issues)
+        out = capsys.readouterr().out
+
+        assert calls["pip"], "--fix must run a pip force-reinstall of certifi"
+        pip_cmd = calls["pip"][0]
+        assert "--force-reinstall" in pip_cmd and "certifi" in pip_cmd
+        assert calls["verify"] == 2, "must re-verify after the reinstall"
+        assert "repaired" in out.lower()
+        assert not issues
+
+    def test_fix_failure_surfaces_manual_command(self, monkeypatch, capsys):
+        from hermes_cli import doctor as doctor_mod
+
+        def fake_verify():
+            from agent.errors import SSLConfigurationError
+
+            raise SSLConfigurationError("certifi points to a missing CA bundle")
+
+        def fake_run(cmd, **kwargs):
+            class _R:
+                returncode = 1
+                stdout = ""
+                stderr = "simulated pip failure"
+
+            return _R()
+
+        monkeypatch.setattr(
+            "agent.ssl_guard.verify_ca_bundle_with_fallback", fake_verify
+        )
+        monkeypatch.setattr(doctor_mod.subprocess, "run", fake_run)
+
+        issues = []
+        doctor_mod.check_certificates(should_fix=True, issues=issues)
+        assert any("force-reinstall certifi" in i for i in issues)
+
+    def test_healthy_bundle_never_touches_pip(self, monkeypatch, capsys):
+        from hermes_cli import doctor as doctor_mod
+
+        def _fail_run(*a, **k):
+            raise AssertionError("healthy bundle must not trigger a reinstall")
+
+        monkeypatch.setattr(doctor_mod.subprocess, "run", _fail_run)
+        doctor_mod.check_certificates(should_fix=True, issues=[])
+        out = capsys.readouterr().out
+        assert "valid" in out.lower()
+
+
+# =========================================================================
+# 3. Startup error message stays actionable
+# =========================================================================
+
+
+class TestSslGuardRepairHint:
+    def test_missing_bundle_error_mentions_doctor_fix(self, monkeypatch, tmp_path):
+        import certifi
+
+        from agent.errors import SSLConfigurationError
+        from agent.ssl_guard import verify_ca_bundle
+
+        monkeypatch.setattr(certifi, "where", lambda: str(tmp_path / "gone.pem"))
+        with pytest.raises(SSLConfigurationError) as excinfo:
+            verify_ca_bundle()
+        message = str(excinfo.value)
+        assert "hermes doctor --fix" in message
+        assert "certifi" in message
diff --git a/tests/hermes_cli/test_checkpoints_prune.py b/tests/hermes_cli/test_checkpoints_prune.py
new file mode 100644
index 00000000000..d253594066d
--- /dev/null
+++ b/tests/hermes_cli/test_checkpoints_prune.py
@@ -0,0 +1,262 @@
+"""Tests for `hermes checkpoints prune`'s orphan confirmation flow.
+
+Covers the P1 raised on PR #69141: the confirmation preview must cover
+BOTH v2 projects (`store_status()["projects"]`) and pre-v2 shadow repos
+(`store_status()["pre_v2_projects"]`), since `prune_checkpoints()` deletes
+orphans from both layouts. Exercises decline / accept / --force across
+pre-v2-only and mixed (v2 + pre-v2) stores.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+import pytest
+
+
+def _ns(**kwargs) -> argparse.Namespace:
+    defaults = {"retention_days": 7, "max_size_mb": 500, "keep_orphans": False, "force": False}
+    defaults.update(kwargs)
+    return argparse.Namespace(**defaults)
+
+
+def _prune_result(**kwargs) -> dict:
+    result = {"scanned": 0, "deleted_orphan": 0, "deleted_stale": 0, "errors": 0, "bytes_freed": 0}
+    result.update(kwargs)
+    return result
+
+
+_V2_ORPHAN_ONLY_STATUS = {
+    "projects": [],
+    "pre_v2_projects": [],
+}
+
+_PRE_V2_ONLY_STATUS = {
+    "projects": [],
+    "pre_v2_projects": [
+        {"path": "/home/user/.hermes/checkpoints/deadbeefcafebabe", "workdir": None, "exists": False},
+    ],
+}
+
+_MIXED_STATUS = {
+    "projects": [
+        {"hash": "abc123", "workdir": "/gone/v2-project", "exists": False, "commits": 4},
+    ],
+    "pre_v2_projects": [
+        {"path": "/home/user/.hermes/checkpoints/deadbeefcafebabe", "workdir": "/gone/pre-v2-project", "exists": False},
+    ],
+}
+
+
+def _patch_checkpoint_manager(monkeypatch, status: dict, prune_calls: list):
+    import tools.checkpoint_manager as ckpt_mgr
+
+    monkeypatch.setattr(ckpt_mgr, "store_status", lambda *a, **k: status)
+
+    def _fake_prune(**kwargs):
+        prune_calls.append(kwargs)
+        return _prune_result(
+            deleted_orphan=len(status["projects"]) + len(status["pre_v2_projects"]),
+        )
+
+    monkeypatch.setattr(ckpt_mgr, "prune_checkpoints", _fake_prune)
+
+
+# ─── pre-v2-only store ──────────────────────────────────────────────────────
+
+
+def test_pre_v2_only_decline_aborts_without_deleting(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _PRE_V2_ONLY_STATUS, prune_calls)
+    monkeypatch.setattr("builtins.input", lambda _prompt: "n")
+
+    rc = checkpoints_cli.cmd_prune(_ns())
+
+    assert rc == 1
+    assert prune_calls == []
+    out = capsys.readouterr().out
+    assert "pre-v2 shadow repo" in out
+    assert "Aborted" in out
+
+
+def test_pre_v2_only_accept_deletes(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _PRE_V2_ONLY_STATUS, prune_calls)
+    monkeypatch.setattr("builtins.input", lambda _prompt: "y")
+
+    rc = checkpoints_cli.cmd_prune(_ns())
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+    assert prune_calls[0]["delete_orphans"] is True
+
+
+def test_pre_v2_only_force_skips_prompt(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _PRE_V2_ONLY_STATUS, prune_calls)
+
+    def _unexpected_input(_prompt):
+        raise AssertionError("input() must not be called when --force is passed")
+
+    monkeypatch.setattr("builtins.input", _unexpected_input)
+
+    rc = checkpoints_cli.cmd_prune(_ns(force=True))
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+
+
+# ─── mixed store (v2 + pre-v2) ──────────────────────────────────────────────
+
+
+def test_mixed_store_decline_aborts_without_deleting(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _MIXED_STATUS, prune_calls)
+    monkeypatch.setattr("builtins.input", lambda _prompt: "n")
+
+    rc = checkpoints_cli.cmd_prune(_ns())
+
+    assert rc == 1
+    assert prune_calls == []
+    out = capsys.readouterr().out
+    # Both layouts must appear in the preview, not just the v2 one.
+    assert "/gone/v2-project" in out
+    assert "/gone/pre-v2-project" in out
+    assert "This will permanently delete 2 orphan checkpoint project(s)" in out
+
+
+def test_mixed_store_accept_deletes_both_layouts(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _MIXED_STATUS, prune_calls)
+    monkeypatch.setattr("builtins.input", lambda _prompt: "y")
+
+    rc = checkpoints_cli.cmd_prune(_ns())
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+    out = capsys.readouterr().out
+    assert "Deleted orphan:  2" in out
+
+
+def test_mixed_store_force_skips_prompt_deletes_both(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _MIXED_STATUS, prune_calls)
+
+    def _unexpected_input(_prompt):
+        raise AssertionError("input() must not be called when --force is passed")
+
+    monkeypatch.setattr("builtins.input", _unexpected_input)
+
+    rc = checkpoints_cli.cmd_prune(_ns(force=True))
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+    assert prune_calls[0]["delete_orphans"] is True
+
+
+# ─── --keep-orphans skips the prompt entirely, on either layout ───────────
+
+
+@pytest.mark.parametrize("status", [_PRE_V2_ONLY_STATUS, _MIXED_STATUS], ids=["pre_v2_only", "mixed"])
+def test_keep_orphans_skips_prompt(monkeypatch, capsys, status):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, status, prune_calls)
+
+    def _unexpected_input(_prompt):
+        raise AssertionError("input() must not be called when --keep-orphans is passed")
+
+    monkeypatch.setattr("builtins.input", _unexpected_input)
+
+    rc = checkpoints_cli.cmd_prune(_ns(keep_orphans=True))
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+    assert prune_calls[0]["delete_orphans"] is False
+
+
+# ─── no orphans present: never prompts even without --force ───────────────
+
+
+def test_no_orphans_skips_prompt(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _V2_ORPHAN_ONLY_STATUS, prune_calls)
+
+    def _unexpected_input(_prompt):
+        raise AssertionError("input() must not be called when there are no orphans")
+
+    monkeypatch.setattr("builtins.input", _unexpected_input)
+
+    rc = checkpoints_cli.cmd_prune(_ns())
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+
+
+# ─── allowlist binding: preview set == deletion set, even when empty ───────
+
+
+def test_empty_preview_binds_empty_allowlist(monkeypatch, capsys):
+    """Zero-orphan-preview timing regression (PR #69141 review).
+
+    When the non-force preview shows zero orphans, no prompt runs — but the
+    later rescan inside prune_checkpoints() may discover a project that
+    became orphaned *after* the preview. That undisplayed, unconfirmed orphan
+    must not be deletable: the allowlist passed down must be the exact
+    (empty) displayed set, never the unrestricted None sentinel.
+    """
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _V2_ORPHAN_ONLY_STATUS, prune_calls)
+
+    rc = checkpoints_cli.cmd_prune(_ns())
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+    assert prune_calls[0]["orphan_allowlist"] == set()
+
+
+def test_nonempty_preview_allowlist_matches_displayed_set(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _MIXED_STATUS, prune_calls)
+    monkeypatch.setattr("builtins.input", lambda _prompt: "y")
+
+    rc = checkpoints_cli.cmd_prune(_ns())
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+    assert prune_calls[0]["orphan_allowlist"] == {
+        "abc123",
+        "/home/user/.hermes/checkpoints/deadbeefcafebabe",
+    }
+
+
+def test_force_leaves_allowlist_unrestricted(monkeypatch, capsys):
+    import hermes_cli.checkpoints as checkpoints_cli
+
+    prune_calls: list = []
+    _patch_checkpoint_manager(monkeypatch, _MIXED_STATUS, prune_calls)
+
+    rc = checkpoints_cli.cmd_prune(_ns(force=True))
+
+    assert rc == 0
+    assert len(prune_calls) == 1
+    assert prune_calls[0]["orphan_allowlist"] is None
diff --git a/tests/hermes_cli/test_cmd_update.py b/tests/hermes_cli/test_cmd_update.py
index dc01dbae0ef..5a1914bc76b 100644
--- a/tests/hermes_cli/test_cmd_update.py
+++ b/tests/hermes_cli/test_cmd_update.py
@@ -59,10 +59,10 @@ def _patch_managed_uv(request):
     def _fake_resolve_uv():
         return shutil.which("uv")
 
-    def _fake_ensure_uv():
+    def _fake_ensure_uv(**_kwargs):
         return shutil.which("uv")
 
-    def _fake_update_managed_uv():
+    def _fake_update_managed_uv(**_kwargs):
         return None  # never actually self-update in tests
 
     with patch("hermes_cli.managed_uv.resolve_uv", side_effect=_fake_resolve_uv), \
@@ -359,16 +359,64 @@ class TestCmdUpdateBranchFallback:
             branch="main", verify_ok=True, commit_count="0"
         )
 
-        cmd_update(mock_args)
+        with patch("hermes_cli.managed_uv.update_managed_uv") as mock_uv_update, \
+             patch(
+                 "hermes_cli.managed_uv.ensure_uv",
+                 return_value=None,
+             ) as mock_uv_ensure:
+            cmd_update(mock_args)
 
         captured = capsys.readouterr()
         assert "Already up to date!" in captured.out
+        update_observer = mock_uv_update.call_args.kwargs["repair_observer"]
+        ensure_observer = mock_uv_ensure.call_args.kwargs["repair_observer"]
+        assert update_observer.__self__ is ensure_observer.__self__
+        assert update_observer.__self__ == []
 
         # Should NOT have called pull
         commands = [" ".join(str(a) for a in c.args[0]) for c in mock_run.call_args_list]
         pull_cmds = [c for c in commands if "pull" in c]
         assert len(pull_cmds) == 0
 
+    @patch("shutil.which", return_value=None)
+    @patch("subprocess.run")
+    def test_zero_commit_runtime_repair_requires_process_restart(
+        self, mock_run, _mock_which, mock_args, capsys, tmp_path
+    ):
+        from hermes_cli.managed_uv import RuntimeRepairResult
+
+        mock_run.side_effect = _make_run_side_effect(
+            branch="main", verify_ok=True, commit_count="0"
+        )
+        backup = tmp_path / "venv.stale.runtime-test"
+        repair = RuntimeRepairResult(
+            "repaired",
+            sqlite_before="3.50.4",
+            sqlite_after="3.53.1",
+            backup_venv=backup,
+        )
+
+        def fake_update(*, repair_observer):
+            repair_observer(repair)
+            return "/managed/uv"
+
+        with patch(
+            "hermes_cli.managed_uv.update_managed_uv",
+            side_effect=fake_update,
+        ), patch(
+            "hermes_cli.managed_uv.ensure_uv",
+            return_value="/managed/uv",
+        ), patch(
+            "hermes_cli.main._is_windows",
+            return_value=False,
+        ):
+            cmd_update(mock_args)
+
+        captured = capsys.readouterr()
+        assert "Restart required to finish the managed Python runtime repair" in captured.out
+        assert "long-lived processes still use the previous runtime" in captured.out
+        assert str(backup) in captured.out
+
     @patch("shutil.which", return_value=None)
     @patch("subprocess.run")
     def test_update_on_fork_checks_upstream_when_origin_up_to_date(
diff --git a/tests/hermes_cli/test_commands.py b/tests/hermes_cli/test_commands.py
index 1473b0a5669..d6587d503b8 100644
--- a/tests/hermes_cli/test_commands.py
+++ b/tests/hermes_cli/test_commands.py
@@ -1235,6 +1235,7 @@ class TestTelegramMenuCommands:
         assert len(names) == 30
         assert hidden > 0
         for name in (
+            "egress",
             "debug",
             "restart",
             "update",
diff --git a/tests/hermes_cli/test_config.py b/tests/hermes_cli/test_config.py
index 196483f4941..e62fa1a3d79 100644
--- a/tests/hermes_cli/test_config.py
+++ b/tests/hermes_cli/test_config.py
@@ -938,16 +938,13 @@ class TestSaveConfigAtomicity:
 
 
 class TestSanitizeEnvLines:
-    """Tests for .env file corruption repair."""
+    """Tests for semantics-preserving .env line normalization."""
 
-    def test_splits_concatenated_keys(self):
-        """Two KEY=VALUE pairs jammed on one line get split."""
+    def test_preserves_known_key_spelling_inside_value(self):
+        """Known KEY= text in a value is data, not a second assignment."""
         lines = ["ANTHROPIC_API_KEY=sk-ant-xxxOPENAI_BASE_URL=https://api.openai.com/v1\n"]
         result = _sanitize_env_lines(lines)
-        assert result == [
-            "ANTHROPIC_API_KEY=sk-ant-xxx\n",
-            "OPENAI_BASE_URL=https://api.openai.com/v1\n",
-        ]
+        assert result == lines
 
     def test_preserves_clean_file(self):
         """A well-formed .env file passes through unchanged (modulo trailing newlines)."""
@@ -971,15 +968,30 @@ class TestSanitizeEnvLines:
         result = _sanitize_env_lines(lines)
         assert result == ["FOO_BAR=baz\n"]
 
-    def test_three_concatenated_keys(self):
-        """Three known keys on one line all get separated."""
+    def test_migrate_reports_normalized_line_formatting(self, capsys):
+        latest_version = DEFAULT_CONFIG["_config_version"]
+        with (
+            patch("hermes_cli.config.sanitize_env_file", return_value=2),
+            patch(
+                "hermes_cli.config.check_config_version",
+                return_value=(latest_version, latest_version),
+            ),
+            patch("hermes_cli.config.read_raw_config", return_value={}),
+            patch("hermes_cli.config.get_missing_env_vars", return_value=[]),
+            patch("hermes_cli.config.get_missing_config_fields", return_value=[]),
+            patch("hermes_cli.config.get_missing_skill_config_vars", return_value=[]),
+        ):
+            migrate_config(interactive=False)
+
+        assert capsys.readouterr().out == (
+            "  ✓ Normalized .env line formatting (2 line(s) changed)\n"
+        )
+
+    def test_multiple_known_key_spellings_inside_value_remain_opaque(self):
+        """Repeated known KEY= text cannot synthesize assignments."""
         lines = ["FAL_KEY=111FIRECRAWL_API_KEY=222GITHUB_TOKEN=333\n"]
         result = _sanitize_env_lines(lines)
-        assert result == [
-            "FAL_KEY=111\n",
-            "FIRECRAWL_API_KEY=222\n",
-            "GITHUB_TOKEN=333\n",
-        ]
+        assert result == lines
 
     def test_value_with_equals_sign_not_split(self):
         """A value containing '=' shouldn't be falsely split (lowercase in value)."""
@@ -988,19 +1000,15 @@ class TestSanitizeEnvLines:
         assert result == lines
 
     def test_unknown_keys_not_split(self):
-        """Unknown key names on one line are NOT split (avoids false positives)."""
+        """Unknown key names on one line remain opaque value data."""
         lines = ["CUSTOM_VAR=value123OTHER_THING=value456\n"]
         result = _sanitize_env_lines(lines)
-        # Unknown keys stay on one line — no false split
-        assert len(result) == 1
+        assert result == lines
 
-    def test_value_ending_with_digits_still_splits(self):
-        """Concatenation is detected even when value ends with digits."""
+    def test_value_ending_with_digits_remains_opaque(self):
         lines = ["OPENROUTER_API_KEY=sk-or-v1-abc123OPENAI_BASE_URL=https://api.openai.com/v1\n"]
         result = _sanitize_env_lines(lines)
-        assert len(result) == 2
-        assert result[0].startswith("OPENROUTER_API_KEY=")
-        assert result[1].startswith("OPENAI_BASE_URL=")
+        assert result == lines
 
     def test_glm_suffix_collision_not_split(self):
         """GLM_API_KEY / GLM_BASE_URL must not be mangled by LM_API_KEY / LM_BASE_URL suffixes (#17138)."""
@@ -1011,13 +1019,10 @@ class TestSanitizeEnvLines:
         result = _sanitize_env_lines(lines)
         assert result == lines, f"GLM_* lines were corrupted by suffix collision: {result}"
 
-    def test_suffix_collision_does_not_break_real_concatenation(self):
-        """A genuine concatenation that happens to start with a suffix-superset key still splits."""
+    def test_suffix_superset_value_remains_opaque(self):
         lines = ["GLM_API_KEY=glmLM_API_KEY=lm-key\n"]
         result = _sanitize_env_lines(lines)
-        assert len(result) == 2
-        assert result[0].startswith("GLM_API_KEY=")
-        assert result[1].startswith("LM_API_KEY=")
+        assert result == lines
 
     def test_value_embedding_known_key_not_split(self):
         """A single valid line whose value embeds a known KEY= (e.g. a URL with
@@ -1036,8 +1041,18 @@ class TestSanitizeEnvLines:
         result = _sanitize_env_lines(lines)
         assert result == lines, f"leading text was dropped: {result}"
 
-    def test_save_env_value_fixes_corruption_on_write(self, tmp_path):
-        """save_env_value sanitizes corrupted lines when writing a new key."""
+    def test_load_env_does_not_synthesize_variable_from_value(self, tmp_path):
+        """The loader must preserve assignment boundaries from the file."""
+        env_file = tmp_path / ".env"
+        env_file.write_text("OPENAI_API_KEY=fixtureGITHUB_TOKEN=inert\n")
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path)}):
+            env = load_env()
+
+        assert env == {"OPENAI_API_KEY": "fixtureGITHUB_TOKEN=inert"}
+
+    def test_save_env_value_preserves_existing_value_semantics(self, tmp_path):
+        """Writing another key must not reinterpret an existing value."""
         env_file = tmp_path / ".env"
         env_file.write_text(
             "ANTHROPIC_API_KEY=sk-antOPENAI_BASE_URL=https://api.openai.com/v1\n"
@@ -1049,13 +1064,11 @@ class TestSanitizeEnvLines:
             content = env_file.read_text()
             lines = content.strip().split("\n")
 
-            # Corrupted line should be split, new key added
-            assert "ANTHROPIC_API_KEY=sk-ant" in lines
-            assert "OPENAI_BASE_URL=https://api.openai.com/v1" in lines
+            assert "ANTHROPIC_API_KEY=sk-antOPENAI_BASE_URL=https://api.openai.com/v1" in lines
+            assert "OPENAI_BASE_URL=https://api.openai.com/v1" not in lines
             assert "MESSAGING_CWD=/tmp" in lines
 
-    def test_sanitize_env_file_returns_fix_count(self, tmp_path):
-        """sanitize_env_file reports how many entries were fixed."""
+    def test_sanitize_env_file_does_not_rewrite_value_semantics(self, tmp_path):
         env_file = tmp_path / ".env"
         env_file.write_text(
             "FAL_KEY=good\n"
@@ -1063,12 +1076,13 @@ class TestSanitizeEnvLines:
         )
         with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path)}):
             fixes = sanitize_env_file()
-            assert fixes > 0
+            assert fixes == 0
 
-            # Verify file is now clean
             content = env_file.read_text()
-            assert "OPENROUTER_API_KEY=val\n" in content
-            assert "FIRECRAWL_API_KEY=val2\n" in content
+            assert content == (
+                "FAL_KEY=good\n"
+                "OPENROUTER_API_KEY=valFIRECRAWL_API_KEY=val2\n"
+            )
 
     def test_sanitize_env_file_noop_on_clean_file(self, tmp_path):
         """No changes when file is already clean."""
diff --git a/tests/hermes_cli/test_curator_archive_prune.py b/tests/hermes_cli/test_curator_archive_prune.py
index ef8b914a8bf..eecb75ee0be 100644
--- a/tests/hermes_cli/test_curator_archive_prune.py
+++ b/tests/hermes_cli/test_curator_archive_prune.py
@@ -101,7 +101,7 @@ def test_prune_nothing_to_do(monkeypatch, capsys):
     import hermes_cli.curator as curator_cli
     import tools.skill_usage as skill_usage
 
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: [])
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: [])
     rc = curator_cli._cmd_prune(_ns(days=30, yes=True, dry_run=False))
     assert rc == 0
     assert "nothing to prune" in capsys.readouterr().out
@@ -117,7 +117,7 @@ def test_prune_filters_pinned_and_archived(monkeypatch, capsys):
         _mk_record("recent", idle_days=10),
         _mk_record("old-active", idle_days=200),
     ]
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: rows)
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: rows)
     archived = []
     monkeypatch.setattr(
         skill_usage, "archive_skill",
@@ -144,7 +144,7 @@ def test_prune_falls_back_to_created_at_when_never_used(monkeypatch, capsys):
     # Force last_activity_at to None explicitly
     rows[0]["last_activity_at"] = None
 
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: rows)
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: rows)
     archived = []
     monkeypatch.setattr(
         skill_usage, "archive_skill",
@@ -160,7 +160,7 @@ def test_prune_dry_run_makes_no_changes(monkeypatch, capsys):
     import tools.skill_usage as skill_usage
 
     rows = [_mk_record("old-skill", idle_days=200)]
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: rows)
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: rows)
     archived = []
     monkeypatch.setattr(
         skill_usage, "archive_skill",
@@ -179,7 +179,7 @@ def test_prune_prompts_without_yes(monkeypatch, capsys):
     import tools.skill_usage as skill_usage
 
     rows = [_mk_record("old-skill", idle_days=200)]
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: rows)
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: rows)
     archived = []
     monkeypatch.setattr(
         skill_usage, "archive_skill",
@@ -197,7 +197,7 @@ def test_prune_confirms_with_y(monkeypatch, capsys):
     import tools.skill_usage as skill_usage
 
     rows = [_mk_record("old-skill", idle_days=200)]
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: rows)
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: rows)
     archived = []
     monkeypatch.setattr(
         skill_usage, "archive_skill",
@@ -217,7 +217,7 @@ def test_prune_reports_partial_failure(monkeypatch, capsys):
         _mk_record("ok-skill", idle_days=200),
         _mk_record("bad-skill", idle_days=200),
     ]
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: rows)
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: rows)
 
     def fake_archive(name):
         if name == "bad-skill":
diff --git a/tests/hermes_cli/test_curator_status.py b/tests/hermes_cli/test_curator_status.py
index 2075ebc2b69..18f8c087820 100644
--- a/tests/hermes_cli/test_curator_status.py
+++ b/tests/hermes_cli/test_curator_status.py
@@ -32,7 +32,7 @@ def test_status_uses_last_activity_not_only_last_used(monkeypatch, capsys):
     monkeypatch.setattr(curator_state, "get_interval_hours", lambda: 168)
     monkeypatch.setattr(curator_state, "get_stale_after_days", lambda: 30)
     monkeypatch.setattr(curator_state, "get_archive_after_days", lambda: 90)
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: [
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: [
         {
             "name": "recently-viewed",
             "state": "active",
@@ -171,7 +171,7 @@ def test_status_hides_most_active_when_all_zero(curator_status_env):
 def test_status_no_skills_produces_clean_empty_output(curator_status_env):
     env = curator_status_env
     out = _capture_status(env["curator_cli"])
-    assert "no agent-created skills" in out
+    assert "no curator-managed skills" in out
     # None of the ranking sections render
     assert "most active" not in out
     assert "least active" not in out
@@ -194,9 +194,195 @@ def test_status_marks_missing_last_report_path(monkeypatch, capsys, tmp_path):
     monkeypatch.setattr(curator_state, "get_interval_hours", lambda: 168)
     monkeypatch.setattr(curator_state, "get_stale_after_days", lambda: 30)
     monkeypatch.setattr(curator_state, "get_archive_after_days", lambda: 90)
-    monkeypatch.setattr(skill_usage, "agent_created_report", lambda: [])
+    monkeypatch.setattr(skill_usage, "curated_report", lambda: [])
 
     assert curator_cli._cmd_status(SimpleNamespace()) == 0
 
     out = capsys.readouterr().out
     assert f"last report:    {missing_report} (missing)" in out
+
+
+# ---------------------------------------------------------------------------
+# Unmanaged blind spot + adopt verb
+# ---------------------------------------------------------------------------
+
+def test_status_surfaces_unmanaged_skills(curator_status_env):
+    """A skill with no provenance marker is invisible to every automatic
+    transition, so status must SAY so rather than reporting only the managed
+    count — otherwise a large library looks fully curated while much of it is
+    untouchable."""
+    env = curator_status_env
+    env["make_skill"]("managed-one")
+    env["make_skill"]("unmanaged-one")
+    env["skill_usage"].mark_agent_created("managed-one")
+
+    out = _capture_status(env["curator_cli"])
+
+    assert "unmanaged (no provenance marker): 1 total" in out
+    assert "curator adopt" in out
+
+
+def test_status_reports_unmanaged_even_with_no_managed_skills(curator_status_env):
+    """The early 'no curator-managed skills' return must not swallow the
+    unmanaged summary — that combination is exactly the confusing case."""
+    env = curator_status_env
+    env["make_skill"]("unmanaged-one")
+
+    out = _capture_status(env["curator_cli"])
+
+    assert "no curator-managed skills" in out
+    assert "unmanaged (no provenance marker): 1 total" in out
+
+
+def test_status_omits_unmanaged_section_when_none(curator_status_env):
+    env = curator_status_env
+    env["make_skill"]("managed-one")
+    env["skill_usage"].mark_agent_created("managed-one")
+
+    out = _capture_status(env["curator_cli"])
+
+    assert "unmanaged (no provenance marker)" not in out
+
+
+def test_adopt_names_a_skill(curator_status_env):
+    env = curator_status_env
+    env["make_skill"]("legacy-one")
+    cli = env["curator_cli"]
+
+    rc = cli._cmd_adopt(SimpleNamespace(
+        skill=["legacy-one"], all_unmanaged=False, dry_run=False, yes=False,
+    ))
+
+    assert rc == 0
+    assert env["skill_usage"].get_record("legacy-one").get("created_by") == "agent"
+
+
+def test_adopt_dry_run_writes_nothing(curator_status_env):
+    env = curator_status_env
+    env["make_skill"]("legacy-one")
+    cli = env["curator_cli"]
+
+    rc = cli._cmd_adopt(SimpleNamespace(
+        skill=[], all_unmanaged=True, dry_run=True, yes=False,
+    ))
+
+    assert rc == 0
+    assert env["skill_usage"].get_record("legacy-one").get("created_by") != "agent"
+
+
+def test_adopt_all_unmanaged_requires_confirmation(curator_status_env, monkeypatch):
+    """Bulk adoption makes skills archivable, so it must confirm by default."""
+    env = curator_status_env
+    env["make_skill"]("legacy-one")
+    cli = env["curator_cli"]
+    monkeypatch.setattr("builtins.input", lambda *_a: "n")
+
+    rc = cli._cmd_adopt(SimpleNamespace(
+        skill=[], all_unmanaged=True, dry_run=False, yes=False,
+    ))
+
+    assert rc == 1
+    assert env["skill_usage"].get_record("legacy-one").get("created_by") != "agent"
+
+
+def test_adopt_all_unmanaged_with_yes_skips_prompt(curator_status_env):
+    env = curator_status_env
+    env["make_skill"]("legacy-one")
+    env["make_skill"]("legacy-two")
+    cli = env["curator_cli"]
+
+    rc = cli._cmd_adopt(SimpleNamespace(
+        skill=[], all_unmanaged=True, dry_run=False, yes=True,
+    ))
+
+    assert rc == 0
+    for n in ("legacy-one", "legacy-two"):
+        assert env["skill_usage"].get_record(n).get("created_by") == "agent"
+
+
+def test_adopt_rejects_names_combined_with_all_unmanaged(curator_status_env):
+    env = curator_status_env
+    env["make_skill"]("legacy-one")
+    cli = env["curator_cli"]
+
+    rc = cli._cmd_adopt(SimpleNamespace(
+        skill=["legacy-one"], all_unmanaged=True, dry_run=False, yes=True,
+    ))
+
+    assert rc == 1
+
+
+def test_adopt_with_no_target_is_an_error(curator_status_env):
+    cli = curator_status_env["curator_cli"]
+
+    rc = cli._cmd_adopt(SimpleNamespace(
+        skill=[], all_unmanaged=False, dry_run=False, yes=False,
+    ))
+
+    assert rc == 1
+
+
+def test_adopt_subcommand_is_registered():
+    """The verb must be reachable through the real argparse tree, not just as a
+    callable — a handler nobody can dispatch to is dead code."""
+    import argparse
+
+    import hermes_cli.curator as curator_cli
+
+    parser = argparse.ArgumentParser()
+    curator_cli.register_cli(parser)
+
+    args = parser.parse_args(["adopt", "--all-unmanaged", "--dry-run"])
+    assert args.func is curator_cli._cmd_adopt
+    assert args.all_unmanaged is True
+    assert args.dry_run is True
+    assert args.skill == []
+
+    named = parser.parse_args(["adopt", "alpha", "beta"])
+    assert named.skill == ["alpha", "beta"]
+    assert named.all_unmanaged is False
+
+
+def test_list_unmanaged_subcommand_is_registered():
+    import argparse
+
+    import hermes_cli.curator as curator_cli
+
+    parser = argparse.ArgumentParser()
+    curator_cli.register_cli(parser)
+    args = parser.parse_args(["list-unmanaged"])
+    assert args.func is curator_cli._cmd_list_unmanaged
+
+
+def test_list_unmanaged_itemizes_and_explains(curator_status_env):
+    """`status` gives the count; this gives the names plus WHY each is
+    unmanaged, so the user can decide what to adopt."""
+    env = curator_status_env
+    env["make_skill"]("legacy-one")
+    env["make_skill"]("managed-one")
+    env["skill_usage"].mark_agent_created("managed-one")
+
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        rc = env["curator_cli"]._cmd_list_unmanaged(Namespace())
+    out = buf.getvalue()
+
+    assert rc == 0
+    assert "legacy-one" in out
+    assert "managed-one" not in out
+    assert "no marker" in out or "created_by:null" in out
+    assert "curator adopt" in out
+
+
+def test_list_unmanaged_reports_clean_state(curator_status_env):
+    env = curator_status_env
+    env["make_skill"]("managed-one")
+    env["skill_usage"].mark_agent_created("managed-one")
+
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        rc = env["curator_cli"]._cmd_list_unmanaged(Namespace())
+
+    assert rc == 0
+    assert "no unmanaged skills" in buf.getvalue()
+
diff --git a/tests/hermes_cli/test_dashboard_auth_middleware.py b/tests/hermes_cli/test_dashboard_auth_middleware.py
index 7c1d6a9c2b2..7e8cf95d982 100644
--- a/tests/hermes_cli/test_dashboard_auth_middleware.py
+++ b/tests/hermes_cli/test_dashboard_auth_middleware.py
@@ -78,6 +78,7 @@ def test_gated_status_is_public(gated_app):
 
 
 @pytest.mark.parametrize("path", [
+    "/api/health",
     "/api/config/defaults",
     "/api/config/schema",
     "/api/model/info",
diff --git a/tests/hermes_cli/test_dashboard_auth_status_endpoint.py b/tests/hermes_cli/test_dashboard_auth_status_endpoint.py
index 4305a2e355f..0d00b20ed23 100644
--- a/tests/hermes_cli/test_dashboard_auth_status_endpoint.py
+++ b/tests/hermes_cli/test_dashboard_auth_status_endpoint.py
@@ -67,6 +67,22 @@ def test_status_reports_auth_required_in_gated_mode(gated_client):
     assert body["auth_providers"] == ["stub"]
 
 
+def test_health_reports_liveness_without_loading_gateway_config(gated_client, monkeypatch):
+    def _boom():
+        raise AssertionError("health must not load gateway config")
+
+    monkeypatch.setattr("gateway.config.load_gateway_config", _boom)
+
+    r = gated_client.get("/api/health")
+    assert r.status_code == 200
+    body = r.json()
+    assert body == {
+        "ok": True,
+        "version": web_server.__version__,
+        "auth_required": True,
+    }
+
+
 def test_status_reports_auth_disabled_in_loopback_mode(loopback_client):
     r = loopback_client.get("/api/status")
     assert r.status_code == 200
diff --git a/tests/hermes_cli/test_desktop_exe_integrity.py b/tests/hermes_cli/test_desktop_exe_integrity.py
new file mode 100644
index 00000000000..6f185587a71
--- /dev/null
+++ b/tests/hermes_cli/test_desktop_exe_integrity.py
@@ -0,0 +1,583 @@
+"""Behavior tests for the Windows desktop-exe integrity gate (#69179).
+
+The desktop self-update chain (Desktop → hermes-setup --update →
+``hermes update`` → ``hermes desktop --build-only`` → relaunch) rebuilds
+Hermes.exe on the end user's machine. Before this gate, "build succeeded" was
+just "the file exists", so a truncated PE (corrupt cached Electron zip), a
+non-PE file, or a wrong-architecture tree shipped as the new app — Windows
+then refuses to launch it with "This app can't run on your computer"
+(此应用无法在你的电脑上运行) and the user has no working install left.
+
+These tests exercise the behavior contract only: synthetic PE files go in,
+verdicts/rollbacks come out.
+"""
+
+from __future__ import annotations
+
+import argparse
+import struct
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from hermes_cli import main as cli_main
+
+PE_AMD64 = 0x8664
+PE_ARM64 = 0xAA64
+PE_I386 = 0x014C
+
+
+def make_pe(path: Path, machine: int = PE_AMD64, *, truncate_to: int | None = None) -> Path:
+    """Write a minimal, structurally-complete PE file with one section.
+
+    Layout: DOS header (e_lfanew=0x80) → PE signature + COFF header at 0x80 →
+    one 40-byte section entry whose raw data spans [0x200, 0x400). Total file
+    size 0x400 unless ``truncate_to`` cuts it short (the corrupt-download
+    shape).
+    """
+    buf = bytearray(0x400)
+    buf[0:2] = b"MZ"
+    struct.pack_into("<I", buf, 0x3C, 0x80)
+    buf[0x80:0x84] = b"PE\x00\x00"
+    # COFF: machine, nsections=1, timestamp, symtab ptr, nsyms, opt-hdr size=0, chars
+    struct.pack_into("<HHIIIHH", buf, 0x84, machine, 1, 0, 0, 0, 0, 0x0002)
+    # Section table entry at 0x80 + 24 = 0x98; SizeOfRawData @+16, PointerToRawData @+20
+    section_off = 0x98
+    struct.pack_into("<II", buf, section_off + 16, 0x200, 0x200)
+    data = bytes(buf if truncate_to is None else buf[:truncate_to])
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+    return path
+
+
+# ─── _parse_pe_machine ──────────────────────────────────────────────────────
+
+
+def test_parse_pe_machine_reads_machine_field(tmp_path):
+    exe = make_pe(tmp_path / "Hermes.exe", PE_AMD64)
+    assert cli_main._parse_pe_machine(exe) == PE_AMD64
+
+    exe_arm = make_pe(tmp_path / "arm.exe", PE_ARM64)
+    assert cli_main._parse_pe_machine(exe_arm) == PE_ARM64
+
+
+def test_parse_pe_machine_rejects_non_pe_file(tmp_path):
+    """An HTML error page saved as .exe — the classic corrupted-download body."""
+    fake = tmp_path / "Hermes.exe"
+    fake.write_bytes(b"<html><body>404 Not Found</body></html>" + b" " * 600)
+    with pytest.raises(ValueError, match="MZ"):
+        cli_main._parse_pe_machine(fake)
+
+
+def test_parse_pe_machine_rejects_tiny_file(tmp_path):
+    stub = tmp_path / "Hermes.exe"
+    stub.write_bytes(b"MZ")
+    with pytest.raises(ValueError, match="too small"):
+        cli_main._parse_pe_machine(stub)
+
+
+def test_parse_pe_machine_rejects_truncated_sections(tmp_path):
+    """File cut mid-download: headers parse but section data extends past EOF."""
+    exe = make_pe(tmp_path / "Hermes.exe", PE_AMD64, truncate_to=0x300)
+    with pytest.raises(ValueError, match="truncated"):
+        cli_main._parse_pe_machine(exe)
+
+
+def test_parse_pe_machine_rejects_bad_pe_signature(tmp_path):
+    exe = make_pe(tmp_path / "Hermes.exe", PE_AMD64)
+    data = bytearray(exe.read_bytes())
+    data[0x80:0x84] = b"XX\x00\x00"
+    exe.write_bytes(bytes(data))
+    with pytest.raises(ValueError, match="PE signature"):
+        cli_main._parse_pe_machine(exe)
+
+
+# ─── _expected_windows_pe_machines ──────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("host", "loadable", "not_loadable"),
+    [
+        ("AMD64", {PE_AMD64, PE_I386}, {PE_ARM64}),
+        ("ARM64", {PE_ARM64, PE_AMD64}, {PE_I386}),
+        ("x86", {PE_I386}, {PE_AMD64, PE_ARM64}),
+    ],
+)
+def test_expected_machines_per_host(host, loadable, not_loadable):
+    with patch("hermes_cli.main._windows_native_machine", return_value=host):
+        expected = cli_main._expected_windows_pe_machines()
+    assert loadable <= expected
+    assert not (not_loadable & expected)
+
+
+def test_expected_machines_unknown_host_is_permissive():
+    """The gate must never brick launch on hosts we don't recognize."""
+    with patch("hermes_cli.main._windows_native_machine", return_value="RISCV64"):
+        expected = cli_main._expected_windows_pe_machines()
+    assert {PE_AMD64, PE_ARM64, PE_I386} <= expected
+
+
+# ─── _windows_native_machine ────────────────────────────────────────────────
+
+# MACHINE_ATTRIBUTES.UserEnabled — mirrors hermes_cli.main.
+_USER_ENABLED = 0x00000001
+
+
+class _SettableFunc:
+    """Callable that accepts ctypes ``.restype`` / ``.argtypes`` assignment."""
+
+    def __init__(self, fn):
+        self._fn = fn
+        self.restype = None
+        self.argtypes = None
+
+    def __call__(self, *args, **kwargs):
+        return self._fn(*args, **kwargs)
+
+
+class _FakeKernel32:
+    """Stands in for kernel32 so the native-arch probes run on any CI OS."""
+
+    def __init__(
+        self,
+        native_pe_machine: int,
+        *,
+        wow64_ok: bool = True,
+        user_runnable: set | None = None,
+    ):
+        self._native_pe = native_pe_machine
+        self._wow64_ok = wow64_ok
+        self._user_runnable = user_runnable
+        self.GetCurrentProcess = _SettableFunc(lambda: -1)
+        self.IsWow64Process2 = _SettableFunc(self._is_wow64_process2)
+        self.GetMachineTypeAttributes = _SettableFunc(
+            self._get_machine_type_attributes
+        )
+
+    def _is_wow64_process2(self, _handle, process_ref, native_ref):
+        if not self._wow64_ok:
+            return 0
+        process_ref._obj.value = PE_AMD64  # emulated x64 process
+        native_ref._obj.value = self._native_pe
+        return 1
+
+    def _get_machine_type_attributes(self, machine, attributes_ref):
+        if self._user_runnable is None:
+            raise AttributeError("GetMachineTypeAttributes unavailable in this fake")
+        if machine not in self._user_runnable:
+            attributes_ref._obj.value = 0
+            return 0
+        attributes_ref._obj.value = _USER_ENABLED
+        return 0
+
+
+def _fake_windll(
+    native_pe_machine: int,
+    *,
+    wow64_ok: bool = True,
+    user_runnable: set | None = None,
+):
+    kernel32 = _FakeKernel32(
+        native_pe_machine,
+        wow64_ok=wow64_ok,
+        user_runnable=user_runnable,
+    )
+
+    def _windll(name, *args, **kwargs):
+        assert "kernel32" in str(name).lower()
+        return kernel32
+
+    return _windll
+
+
+def test_native_machine_reports_os_arch_not_process_arch(monkeypatch):
+    """The #69179 WoA regression: x64 Python under ARM64 emulation must report
+    ARM64 (the OS), not AMD64 (the process) — otherwise the integrity gate
+    rejects the correct ARM64 rebuild."""
+    import ctypes
+
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    # WinDLL only exists on Windows; create=True so Linux/macOS CI can stub it.
+    with patch.object(ctypes, "WinDLL", _fake_windll(PE_ARM64), create=True), \
+         patch("platform.machine", return_value="AMD64"):
+        assert cli_main._windows_native_machine() == "ARM64"
+
+
+def test_native_machine_binds_current_process_handle_restype(monkeypatch):
+    """ctypes must type GetCurrentProcess as HANDLE — default c_int truncates
+    the pseudo-handle on Win64 and makes IsWow64Process2 return
+    ERROR_INVALID_HANDLE, re-breaking the #71218 gate on WoA."""
+    import ctypes
+    from ctypes import wintypes
+
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    windll = _fake_windll(PE_ARM64)
+    with patch.object(ctypes, "WinDLL", windll, create=True), \
+         patch("platform.machine", return_value="AMD64"):
+        assert cli_main._windows_native_machine() == "ARM64"
+    kernel32 = windll("kernel32")
+    assert kernel32.GetCurrentProcess.restype is wintypes.HANDLE
+    assert kernel32.IsWow64Process2.argtypes is not None
+
+
+def test_expected_machines_prefers_user_runnable_api_over_arch_name(monkeypatch):
+    """GetMachineTypeAttributes answers "can this host load PE machine X?"
+    directly, so a WoA host that reports AMD64 everywhere else still accepts an
+    ARM64 exe."""
+    import ctypes
+
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    monkeypatch.setenv("PROCESSOR_ARCHITECTURE", "AMD64")
+    monkeypatch.delenv("PROCESSOR_ARCHITEW6432", raising=False)
+    with patch.object(
+        ctypes,
+        "WinDLL",
+        _fake_windll(
+            PE_ARM64, wow64_ok=False, user_runnable={PE_ARM64, PE_AMD64}
+        ),
+        create=True,
+    ), patch("platform.machine", return_value="AMD64"):
+        assert cli_main._expected_windows_pe_machines() == {PE_ARM64, PE_AMD64}
+
+
+def test_expected_machines_falls_back_when_attributes_api_missing(monkeypatch):
+    """Pre-Windows-11 hosts have no GetMachineTypeAttributes — the name-based
+    mapping must still drive the gate."""
+    import ctypes
+
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    with patch.object(
+        ctypes, "WinDLL", _fake_windll(PE_ARM64, user_runnable=None), create=True
+    ), patch("platform.machine", return_value="AMD64"):
+        assert cli_main._expected_windows_pe_machines() == {PE_ARM64, PE_AMD64}
+
+
+def test_native_machine_env_fallback_without_api(monkeypatch):
+    """Pre-1511 Windows 10: no IsWow64Process2 → env."""
+    import ctypes
+
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    monkeypatch.setenv("PROCESSOR_ARCHITEW6432", "AMD64")
+
+    def _no_kernel32(name, *args, **kwargs):
+        raise OSError(f"no {name} in this fake pre-1511 host")
+
+    with patch.object(ctypes, "WinDLL", _no_kernel32, create=True), \
+         patch("platform.machine", return_value="x86"):
+        assert cli_main._windows_native_machine() == "AMD64"
+
+
+def test_native_machine_platform_fallback(monkeypatch):
+    """No API, no env vars → the historical platform.machine() answer."""
+    import ctypes
+
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    monkeypatch.delenv("PROCESSOR_ARCHITEW6432", raising=False)
+    monkeypatch.delenv("PROCESSOR_ARCHITECTURE", raising=False)
+
+    def _no_kernel32(name, *args, **kwargs):
+        raise OSError(f"no {name} in this fake host")
+
+    with patch.object(ctypes, "WinDLL", _no_kernel32, create=True), \
+         patch("platform.machine", return_value="AMD64"):
+        assert cli_main._windows_native_machine() == "AMD64"
+
+
+def test_native_machine_non_windows_uses_platform(monkeypatch):
+    monkeypatch.setattr(cli_main.sys, "platform", "linux")
+    with patch("platform.machine", return_value="aarch64"):
+        assert cli_main._windows_native_machine() == "AARCH64"
+
+
+def test_integrity_gate_accepts_arm64_exe_from_emulated_x64_process(monkeypatch, tmp_path):
+    """End-to-end shape of the reporter's failure: ARM64 host, x64 updater
+    process, correctly-built ARM64 Hermes.exe. The gate must pass it."""
+    import ctypes
+
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    exe = make_pe(tmp_path / "Hermes.exe", PE_ARM64)
+    with patch.object(ctypes, "WinDLL", _fake_windll(PE_ARM64), create=True), \
+         patch("platform.machine", return_value="AMD64"):
+        assert cli_main._desktop_exe_integrity_error(exe) is None
+
+
+def test_integrity_gate_accepts_arm64_when_iswow64_fails_but_attributes_ok(
+    monkeypatch, tmp_path
+):
+    """End-to-end residual WoA shape: IsWow64Process2 fails and env lies as
+    AMD64, but GetMachineTypeAttributes reports ARM64 as user-runnable, so the
+    ARM64 Hermes.exe must pass the gate."""
+    import ctypes
+
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    monkeypatch.setenv("PROCESSOR_ARCHITECTURE", "AMD64")
+    monkeypatch.delenv("PROCESSOR_ARCHITEW6432", raising=False)
+    exe = make_pe(tmp_path / "Hermes.exe", PE_ARM64)
+    with patch.object(
+        ctypes,
+        "WinDLL",
+        _fake_windll(
+            PE_ARM64, wow64_ok=False, user_runnable={PE_ARM64, PE_AMD64}
+        ),
+        create=True,
+    ), patch("platform.machine", return_value="AMD64"):
+        assert cli_main._desktop_exe_integrity_error(exe) is None
+
+
+# ─── _desktop_exe_integrity_error ───────────────────────────────────────────
+
+
+def test_integrity_error_none_for_matching_arch(tmp_path):
+    exe = make_pe(tmp_path / "Hermes.exe", PE_AMD64)
+    with patch("hermes_cli.main._windows_native_machine", return_value="AMD64"):
+        assert cli_main._desktop_exe_integrity_error(exe) is None
+
+
+def test_integrity_error_reports_arch_mismatch(tmp_path):
+    """ARM64 exe on the reporter's 'Windows 10 AMD64' host — the wrong-arch
+    flavor of 'This app can't run on your computer'."""
+    exe = make_pe(tmp_path / "Hermes.exe", PE_ARM64)
+    with patch("hermes_cli.main._windows_native_machine", return_value="AMD64"):
+        error = cli_main._desktop_exe_integrity_error(exe)
+    assert error is not None and "architecture mismatch" in error
+    assert "ARM64" in error
+
+
+def test_integrity_error_reports_corruption_reason(tmp_path):
+    exe = make_pe(tmp_path / "Hermes.exe", PE_AMD64, truncate_to=0x300)
+    error = cli_main._desktop_exe_integrity_error(exe)
+    assert error is not None and "truncated" in error
+
+
+# ─── _desktop_packaged_executable arch preference (win32) ───────────────────
+
+
+def test_packaged_executable_prefers_host_arch_over_mtime(tmp_path, monkeypatch):
+    """A newer wrong-arch tree must not shadow the loadable one (#69179)."""
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    desktop_dir = tmp_path / "apps" / "desktop"
+    good = make_pe(desktop_dir / "release" / "win-unpacked" / "Hermes.exe", PE_AMD64)
+    bad = make_pe(desktop_dir / "release" / "win-arm64-unpacked" / "Hermes.exe", PE_ARM64)
+    # Make the wrong-arch tree the newest, which the pure-mtime pick would take.
+    import os
+
+    os.utime(bad, (bad.stat().st_atime + 1000, bad.stat().st_mtime + 1000))
+
+    with patch("hermes_cli.main._windows_native_machine", return_value="AMD64"):
+        assert cli_main._desktop_packaged_executable(desktop_dir) == good
+
+
+def test_packaged_executable_falls_back_to_mtime_when_unparseable(tmp_path, monkeypatch):
+    """Non-PE stubs (dev trees, tests) keep the historical newest-wins pick."""
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    desktop_dir = tmp_path / "apps" / "desktop"
+    a = desktop_dir / "release" / "win-unpacked" / "Hermes.exe"
+    b = desktop_dir / "release" / "win-arm64-unpacked" / "Hermes.exe"
+    for p in (a, b):
+        p.parent.mkdir(parents=True)
+        p.write_text("", encoding="utf-8")
+    import os
+
+    os.utime(b, (b.stat().st_atime + 1000, b.stat().st_mtime + 1000))
+    with patch("hermes_cli.main._windows_native_machine", return_value="AMD64"):
+        assert cli_main._desktop_packaged_executable(desktop_dir) == b
+
+
+# ─── rollback ───────────────────────────────────────────────────────────────
+
+
+def _win_tree(tmp_path: Path) -> tuple[Path, Path]:
+    desktop_dir = tmp_path / "apps" / "desktop"
+    exe = desktop_dir / "release" / "win-unpacked" / "Hermes.exe"
+    return desktop_dir, exe
+
+
+def test_rollback_restores_backup_and_keeps_corrupt_copy(tmp_path):
+    desktop_dir, exe = _win_tree(tmp_path)
+    make_pe(exe, PE_AMD64, truncate_to=0x300)  # corrupt new build
+    backup_exe = desktop_dir / "release" / "win-unpacked.bak" / "Hermes.exe"
+    make_pe(backup_exe, PE_AMD64)  # valid old build
+
+    with patch("hermes_cli.main._windows_native_machine", return_value="AMD64"):
+        restored = cli_main._rollback_desktop_from_backup(exe)
+
+    assert restored == exe
+    # The restored exe is the old, valid build.
+    assert cli_main._parse_pe_machine(exe) == PE_AMD64
+    assert exe.stat().st_size == 0x400
+    # Corrupt tree preserved for diagnostics; backup consumed.
+    assert (desktop_dir / "release" / "win-unpacked.corrupt" / "Hermes.exe").exists()
+    assert not backup_exe.exists()
+
+
+def test_rollback_returns_none_without_backup(tmp_path):
+    _, exe = _win_tree(tmp_path)
+    make_pe(exe, PE_AMD64, truncate_to=0x300)
+    assert cli_main._rollback_desktop_from_backup(exe) is None
+    # The corrupt tree is left in place (nothing to restore over it).
+    assert exe.exists()
+
+
+def test_rollback_refuses_corrupt_backup(tmp_path):
+    """Never 'restore' a backup that would also fail to launch."""
+    desktop_dir, exe = _win_tree(tmp_path)
+    make_pe(exe, PE_AMD64, truncate_to=0x300)
+    backup_exe = desktop_dir / "release" / "win-unpacked.bak" / "Hermes.exe"
+    make_pe(backup_exe, PE_AMD64, truncate_to=0x280)  # backup also corrupt
+
+    assert cli_main._rollback_desktop_from_backup(exe) is None
+    assert backup_exe.exists()  # untouched
+
+
+# ─── _ensure_desktop_exe_launchable (the gate) ──────────────────────────────
+
+
+def test_gate_passes_valid_exe(tmp_path, monkeypatch):
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    desktop_dir, exe = _win_tree(tmp_path)
+    make_pe(exe, PE_AMD64)
+    with patch("hermes_cli.main._windows_native_machine", return_value="AMD64"):
+        verified, rolled_back = cli_main._ensure_desktop_exe_launchable(desktop_dir, exe)
+    assert verified == exe
+    assert rolled_back is False
+
+
+def test_gate_noop_off_windows(tmp_path, monkeypatch):
+    monkeypatch.setattr(cli_main.sys, "platform", "linux")
+    desktop_dir, exe = _win_tree(tmp_path)
+    exe.parent.mkdir(parents=True)
+    exe.write_text("not a pe at all", encoding="utf-8")
+    verified, rolled_back = cli_main._ensure_desktop_exe_launchable(desktop_dir, exe)
+    assert verified == exe
+    assert rolled_back is False
+
+
+def test_gate_rolls_back_corrupt_exe_and_purges_cache(tmp_path, monkeypatch, capsys):
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path / "home"))
+    desktop_dir, exe = _win_tree(tmp_path)
+    make_pe(exe, PE_AMD64, truncate_to=0x300)
+    make_pe(desktop_dir / "release" / "win-unpacked.bak" / "Hermes.exe", PE_AMD64)
+
+    stamp = tmp_path / "home" / "desktop-build-stamp.json"
+    stamp.parent.mkdir(parents=True, exist_ok=True)
+    stamp.write_text("{}", encoding="utf-8")
+
+    with patch("hermes_cli.main._windows_native_machine", return_value="AMD64"), \
+         patch("hermes_cli.main._purge_electron_build_cache", return_value=[]) as mock_purge, \
+         patch("hermes_cli.main._desktop_stamp_path", return_value=stamp):
+        verified, rolled_back = cli_main._ensure_desktop_exe_launchable(desktop_dir, exe)
+
+    assert rolled_back is True
+    assert verified == exe
+    assert cli_main._parse_pe_machine(exe) == PE_AMD64  # restored old build
+    mock_purge.assert_called_once()
+    assert not stamp.exists()  # stamp invalidated so retry genuinely rebuilds
+    out = capsys.readouterr().out
+    assert "integrity check" in out
+    assert "Update aborted" in out
+    assert "existing version was kept" in out
+
+
+def test_gate_fails_clearly_without_backup(tmp_path, monkeypatch, capsys):
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+    desktop_dir, exe = _win_tree(tmp_path)
+    fake = exe
+    fake.parent.mkdir(parents=True)
+    fake.write_bytes(b"<html>proxy error</html>" + b" " * 600)
+
+    with patch("hermes_cli.main._purge_electron_build_cache", return_value=[]), \
+         patch("hermes_cli.main._desktop_stamp_path", return_value=tmp_path / "stamp.json"):
+        verified, rolled_back = cli_main._ensure_desktop_exe_launchable(desktop_dir, exe)
+
+    assert verified is None
+    assert rolled_back is False
+    out = capsys.readouterr().out
+    assert "integrity check" in out
+    assert "No usable backup" in out
+
+
+# ─── end-to-end: `hermes desktop --build-only` exits nonzero on corrupt exe ─
+
+
+def _ns(**kw):
+    defaults = dict(
+        skip_build=False,
+        build_only=True,
+        force_build=False,
+        source=False,
+        fake_boot=False,
+        ignore_existing=False,
+        hermes_root=None,
+        cwd=None,
+    )
+    defaults.update(kw)
+    return argparse.Namespace(**defaults)
+
+
+def test_build_only_fails_when_pack_produces_corrupt_exe(tmp_path, monkeypatch, capsys):
+    """The updater chain's contract: a rebuild whose Hermes.exe cannot launch
+    must exit nonzero (so hermes-setup's retry-once kicks in) and must restore
+    the previous working build instead of leaving the corrupt one."""
+    root = tmp_path / "hermes-agent"
+    desktop_dir = root / "apps" / "desktop"
+    desktop_dir.mkdir(parents=True)
+    (desktop_dir / "package.json").write_text("{}", encoding="utf-8")
+    monkeypatch.setattr(cli_main, "PROJECT_ROOT", root)
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+
+    exe = desktop_dir / "release" / "win-unpacked" / "Hermes.exe"
+    make_pe(exe, PE_AMD64, truncate_to=0x300)  # what the failed pack produced
+    make_pe(desktop_dir / "release" / "win-unpacked.bak" / "Hermes.exe", PE_AMD64)
+
+    install_ok = subprocess.CompletedProcess(["npm", "ci"], 0)
+    pack_ok = subprocess.CompletedProcess(["npm", "run", "pack"], 0)
+
+    with patch("hermes_cli.main.shutil.which", return_value="/usr/bin/npm"), \
+         patch("hermes_cli.main._run_npm_install_deterministic", return_value=install_ok), \
+         patch("hermes_cli.main._desktop_build_needed", return_value=True), \
+         patch("hermes_cli.main._stop_desktop_processes_locking_build", return_value=[]), \
+         patch("hermes_cli.main._purge_electron_build_cache", return_value=[]), \
+         patch("hermes_cli.main._desktop_stamp_path", return_value=tmp_path / "stamp.json"), \
+         patch("hermes_cli.main._write_desktop_build_stamp") as mock_stamp, \
+         patch("hermes_cli.main._windows_native_machine", return_value="AMD64"), \
+         patch("hermes_cli.main.subprocess.run", return_value=pack_ok), \
+         pytest.raises(SystemExit) as exc:
+        cli_main.cmd_gui(_ns())
+
+    assert exc.value.code == 1
+    # The previous working exe was restored...
+    assert cli_main._parse_pe_machine(exe) == PE_AMD64
+    # ...and the poisoned build was never stamped as good.
+    mock_stamp.assert_not_called()
+    out = capsys.readouterr().out
+    assert "integrity check" in out
+
+
+def test_build_only_succeeds_with_valid_exe(tmp_path, monkeypatch, capsys):
+    root = tmp_path / "hermes-agent"
+    desktop_dir = root / "apps" / "desktop"
+    desktop_dir.mkdir(parents=True)
+    (desktop_dir / "package.json").write_text("{}", encoding="utf-8")
+    monkeypatch.setattr(cli_main, "PROJECT_ROOT", root)
+    monkeypatch.setattr(cli_main.sys, "platform", "win32")
+
+    make_pe(desktop_dir / "release" / "win-unpacked" / "Hermes.exe", PE_AMD64)
+
+    install_ok = subprocess.CompletedProcess(["npm", "ci"], 0)
+    pack_ok = subprocess.CompletedProcess(["npm", "run", "pack"], 0)
+
+    with patch("hermes_cli.main.shutil.which", return_value="/usr/bin/npm"), \
+         patch("hermes_cli.main._run_npm_install_deterministic", return_value=install_ok), \
+         patch("hermes_cli.main._desktop_build_needed", return_value=True), \
+         patch("hermes_cli.main._stop_desktop_processes_locking_build", return_value=[]), \
+         patch("hermes_cli.main._write_desktop_build_stamp") as mock_stamp, \
+         patch("hermes_cli.main._windows_native_machine", return_value="AMD64"), \
+         patch("hermes_cli.main.subprocess.run", return_value=pack_ok):
+        cli_main.cmd_gui(_ns())
+
+    mock_stamp.assert_called_once()
+    assert "Desktop packaged app ready" in capsys.readouterr().out
diff --git a/tests/hermes_cli/test_doctor.py b/tests/hermes_cli/test_doctor.py
index 8e7575b86b2..c439aaf0cee 100644
--- a/tests/hermes_cli/test_doctor.py
+++ b/tests/hermes_cli/test_doctor.py
@@ -126,6 +126,30 @@ class TestDoctorEnvFileEncoding:
             doctor_mod.run_doctor(Namespace(fix=False))
 
 
+
+    def test_doctor_reads_invalid_utf8_env_via_latin1_fallback(
+        self, monkeypatch, tmp_path
+    ):
+        """cp1252/latin-1 .env with ASCII provider hints must not abort doctor."""
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        env_path = hermes_home / ".env"
+        # 0xff is invalid UTF-8; latin-1 decodes it. Keep an ASCII provider key
+        # so the scan still reports a configured endpoint/key.
+        env_path.write_bytes(b"OPENAI_API_KEY=sk-test\xff\n")
+
+        monkeypatch.setattr(doctor_mod, "HERMES_HOME", hermes_home)
+
+        fake_model_tools = types.SimpleNamespace(
+            check_tool_availability=lambda *a, **kw: (_ for _ in ()).throw(SystemExit(0)),
+            TOOLSET_REQUIREMENTS={},
+        )
+        monkeypatch.setitem(sys.modules, "model_tools", fake_model_tools)
+
+        with pytest.raises(SystemExit):
+            doctor_mod.run_doctor(Namespace(fix=False))
+
+
 class TestDoctorToolAvailabilityOverrides:
     def test_marks_honcho_available_when_configured(self, monkeypatch):
         monkeypatch.setattr(doctor, "_honcho_is_configured_for_doctor", lambda: True)
@@ -517,6 +541,7 @@ def test_run_doctor_flags_missing_credentials_for_active_openrouter_provider(mon
         ("kilocode", "anthropic/claude-sonnet-4.6"),
         ("kimi-coding", "kimi-k2"),
         ("nvidia", "qwen/qwen3.5-122b-a10b"),
+        ("moa", "anthropic/claude-sonnet-4.6"),
     ],
 )
 def test_run_doctor_accepts_hermes_provider_ids_that_catalog_aliases(
diff --git a/tests/hermes_cli/test_env_loader.py b/tests/hermes_cli/test_env_loader.py
index a5a2ee75272..c2aff25cb6b 100644
--- a/tests/hermes_cli/test_env_loader.py
+++ b/tests/hermes_cli/test_env_loader.py
@@ -33,7 +33,7 @@ def test_project_env_overrides_stale_shell_values_when_user_env_missing(tmp_path
     assert os.getenv("OPENAI_BASE_URL") == "https://project.example/v1"
 
 
-def test_project_env_is_sanitized_before_loading(tmp_path, monkeypatch):
+def test_project_env_value_cannot_synthesize_an_assignment(tmp_path, monkeypatch):
     home = tmp_path / "hermes"
     project_env = tmp_path / ".env"
     project_env.write_text(
@@ -48,8 +48,10 @@ def test_project_env_is_sanitized_before_loading(tmp_path, monkeypatch):
     loaded = load_hermes_dotenv(hermes_home=home, project_env=project_env)
 
     assert loaded == [project_env]
-    assert os.getenv("TELEGRAM_BOT_TOKEN") == "0123456789:test"
-    assert os.getenv("ANTHROPIC_API_KEY") == "sk-ant-test123"
+    assert os.getenv("TELEGRAM_BOT_TOKEN") == (
+        "0123456789:testANTHROPIC_API_KEY=sk-ant-test123"
+    )
+    assert os.getenv("ANTHROPIC_API_KEY") is None
 
 
 def test_user_env_takes_precedence_over_project_env(tmp_path, monkeypatch):
diff --git a/tests/hermes_cli/test_env_sanitize_on_load.py b/tests/hermes_cli/test_env_sanitize_on_load.py
index f23eadd2a55..9c8c6dadc81 100644
--- a/tests/hermes_cli/test_env_sanitize_on_load.py
+++ b/tests/hermes_cli/test_env_sanitize_on_load.py
@@ -5,12 +5,11 @@ from pathlib import Path
 from unittest.mock import patch
 
 
-def test_load_env_sanitizes_concatenated_lines():
-    """Verify load_env() splits concatenated KEY=VALUE pairs.
+def test_load_env_preserves_concatenated_text_as_value_data():
+    """Verify load_env() does not infer assignments within a physical line.
 
-    Reproduces the scenario from #8908 where a corrupted .env file
-    contained multiple tokens on a single line, causing the bot token
-    to be duplicated 8 times.
+    A missing newline is ambiguous: text resembling a second assignment may
+    instead be part of the first value, so it must remain opaque value data.
     """
     from hermes_cli.config import load_env
 
@@ -27,10 +26,10 @@ def test_load_env_sanitizes_concatenated_lines():
     try:
         with patch("hermes_cli.config.get_env_path", return_value=env_path):
             result = load_env()
-        assert result.get("TELEGRAM_BOT_TOKEN") == token, (
-            f"Token should be exactly '{token}', got '{result.get('TELEGRAM_BOT_TOKEN')}'"
+        assert result.get("TELEGRAM_BOT_TOKEN") == (
+            f"{token}ANTHROPIC_API_KEY=sk-ant-test123"
         )
-        assert result.get("ANTHROPIC_API_KEY") == "sk-ant-test123"
+        assert "ANTHROPIC_API_KEY" not in result
     finally:
         env_path.unlink(missing_ok=True)
 
@@ -63,8 +62,8 @@ def test_load_env_normal_file_unchanged():
         env_path.unlink(missing_ok=True)
 
 
-def test_env_loader_sanitizes_before_dotenv():
-    """Verify env_loader._sanitize_env_file_if_needed fixes corrupted files."""
+def test_env_loader_does_not_split_concatenated_text():
+    """Verify sanitization preserves one assignment per physical line."""
     from hermes_cli.env_loader import _sanitize_env_file_if_needed
 
     token = "0123456789:test"
@@ -80,12 +79,8 @@ def test_env_loader_sanitizes_before_dotenv():
         _sanitize_env_file_if_needed(env_path)
         with open(env_path, encoding="utf-8") as f:
             lines = f.readlines()
-        # Should be split into two separate lines
-        assert len(lines) == 2, f"Expected 2 lines, got {len(lines)}: {lines}"
-        assert lines[0].startswith("TELEGRAM_BOT_TOKEN=")
-        assert lines[1].startswith("ANTHROPIC_API_KEY=")
-        # Token should not contain the second key
+        assert lines == [corrupted]
         parsed_token = lines[0].strip().split("=", 1)[1]
-        assert parsed_token == token
+        assert parsed_token == f"{token}ANTHROPIC_API_KEY=sk-ant-test"
     finally:
         env_path.unlink(missing_ok=True)
diff --git a/tests/hermes_cli/test_gateway_service.py b/tests/hermes_cli/test_gateway_service.py
index 7041ab9aee4..7a7911687fd 100644
--- a/tests/hermes_cli/test_gateway_service.py
+++ b/tests/hermes_cli/test_gateway_service.py
@@ -735,14 +735,27 @@ class TestLaunchdServiceRecovery:
         assert "--replace" in plist_path.read_text(encoding="utf-8")
         # No DIRECT bootout/bootstrap ran (those would kill us mid-sequence).
         assert not [c for c in run_calls if "bootout" in c or "bootstrap" in c]
-        # Exactly one detached helper was spawned, in a new session, and it
-        # performs both bootout and bootstrap.
+        # Exactly one Popen call was made for the transient launchd job.
         assert len(popen_calls) == 1
         cmd, kwargs = popen_calls[0]
-        assert kwargs.get("start_new_session") is True
-        script = cmd[-1]
+        # Must use `launchctl submit` (not `start_new_session=True`) so the
+        # helper runs as a transient launchd job outside the gateway's process
+        # coalition, surviving bootout (#69098).
+        assert cmd[:3] == ["launchctl", "submit", "-l"]
+        assert kwargs.get("start_new_session") is not True
+        assert "-o" in cmd
+        assert "-e" in cmd
+        # The script is passed via -- /bin/bash -c ...
+        bash_idx = cmd.index("--") + 1
+        assert cmd[bash_idx] == "/bin/bash"
+        assert cmd[bash_idx + 1] == "-c"
+        script = cmd[bash_idx + 2]
         assert "bootout" in script and "bootstrap" in script
         assert str(plist_path) in script
+        # The one-shot job must deregister its own transient label at the end,
+        # otherwise every reload leaks a dead label in launchd.
+        submit_label = cmd[cmd.index("-l") + 1]
+        assert f"launchctl remove {submit_label}" in script
 
     def test_refresh_uses_direct_reload_when_not_inside_gateway_tree(self, tmp_path, monkeypatch):
         """Normal CLI-initiated refresh (outside the service tree) keeps the
diff --git a/tests/hermes_cli/test_kanban_db.py b/tests/hermes_cli/test_kanban_db.py
index 25ed7223129..f4e55235255 100644
--- a/tests/hermes_cli/test_kanban_db.py
+++ b/tests/hermes_cli/test_kanban_db.py
@@ -3248,6 +3248,17 @@ def test_connect_falls_back_to_delete_on_locking_protocol(tmp_path, monkeypatch,
     import sqlite3 as _sqlite3
     from unittest.mock import patch as _patch
 
+    import hermes_state as _hs
+
+    # The fallback warning is deduped process-globally ("once per process per
+    # database" — _log_wal_fallback_once / _log_wal_reset_bug_once). Any earlier
+    # test in this file that opened a kanban.db already consumed the one-shot
+    # for that label, so without clearing it this test sees zero warnings and
+    # fails only when run as part of the file (it passes in isolation). Clear
+    # both dedup sets so the warning is emitted for this connect().
+    _hs._wal_fallback_warned_paths.clear()
+    _hs._wal_reset_bug_warned_paths.clear()
+
     home = tmp_path / ".hermes"
     home.mkdir()
     monkeypatch.setenv("HERMES_HOME", str(home))
@@ -3265,6 +3276,9 @@ def test_connect_falls_back_to_delete_on_locking_protocol(tmp_path, monkeypatch,
             return super().execute(sql, *args, **kwargs)
 
     def wal_blocking_connect(*args, **kwargs):
+        # connect_tracked passes a tracking-augmented factory; drop it and
+        # substitute the double, which connect_tracked will re-augment.
+        kwargs.pop("factory", None)
         return real_connect(
             *args, factory=_WalBlockingConnection, **kwargs
         )
@@ -4658,11 +4672,19 @@ def test_write_txn_healthy_commit_no_exception(tmp_path):
 
 
 def test_write_txn_raises_on_truncated_file(tmp_path):
-    """A mocked smaller file size triggers the torn-extend check."""
+    """A mocked smaller file size triggers the torn-extend check.
+
+    The check now reads the header side via ``PRAGMA page_count`` over the
+    existing connection instead of ``open()``-ing the database file (an
+    open/close would cancel this process's POSIX locks). The on-disk side is
+    still ``stat()``, so that is what this test fakes. The invariant only
+    applies under a rollback journal — in WAL a committed page may still be
+    in the -wal file, so the main file legitimately lags.
+    """
     from hermes_cli.kanban_db import connect, write_txn
     db = tmp_path / "test.db"
     conn = connect(db_path=db)
-    # Get actual page size so we can fake a smaller file
+    conn.execute("PRAGMA journal_mode=DELETE")
     page_size = conn.execute("PRAGMA page_size").fetchone()[0]
     original_getsize = os.path.getsize
 
@@ -4672,7 +4694,9 @@ def test_write_txn_raises_on_truncated_file(tmp_path):
         return max(0, real_size - page_size)
 
     with pytest.raises(sqlite3.DatabaseError, match="torn-extend|page count mismatch"):
-        with unittest.mock.patch("hermes_cli.kanban_db.os.path.getsize", side_effect=fake_getsize):
+        with unittest.mock.patch(
+            "hermes_cli.sqlite_safe_read.os.path.getsize", side_effect=fake_getsize
+        ):
             with write_txn(conn) as c:
                 c.execute(
                     "INSERT INTO tasks (id, title, assignee, status, priority, created_at) "
@@ -4717,31 +4741,39 @@ def test_connect_sets_wal_autocheckpoint_100(tmp_path):
 
 
 def test_write_txn_check_reads_correct_header_fields(tmp_path):
-    """Synthetic DB file with mismatched header page_count triggers the check."""
+    """A genuinely truncated DB is never reported as passing the invariant.
+
+    The check no longer opens the database file to read header bytes (that
+    open/close would cancel this process's POSIX advisory locks — the
+    corruption route in sqlite.org/howtocorrupt.html §2.2). It asks SQLite for
+    ``page_count`` instead. On a truncated file SQLite refuses that pragma, so
+    the helper reports "not healthy" rather than a page-count mismatch; either
+    way the file must never come back clean.
+    """
     import struct
-    from hermes_cli.kanban_db import connect, _check_file_length_invariant
+    from hermes_cli.kanban_db import connect
+    from hermes_cli.sqlite_safe_read import file_length_matches_header
+
     db = tmp_path / "synthetic.db"
     conn = connect(db_path=db)
+    conn.execute("PRAGMA journal_mode=DELETE")
     page_size = conn.execute("PRAGMA page_size").fetchone()[0]
     conn.close()
-    # Now corrupt the file: claim N pages but truncate to N-1 pages
+
     with open(db, "rb") as f:
         data = bytearray(f.read())
-    # Read current page_count from header bytes 28-31
     real_page_count = struct.unpack(">I", data[28:32])[0]
     if real_page_count < 2:
-        # Need at least 2 pages to fake a truncation
         pytest.skip("DB too small for synthetic truncation test")
-    # Truncate to N-1 pages
     truncated = bytes(data[: (real_page_count - 1) * page_size])
     with open(db, "wb") as f:
         f.write(truncated)
-    # Now open and check — should raise
-    # We can't use connect() because _validate_sqlite_header may block; use a raw connection
+
     raw_conn = sqlite3.connect(str(db), isolation_level=None)
-    with pytest.raises(sqlite3.DatabaseError, match="torn-extend|page count mismatch"):
-        _check_file_length_invariant(raw_conn)
-    raw_conn.close()
+    try:
+        assert file_length_matches_header(raw_conn) is not True
+    finally:
+        raw_conn.close()
 
 
 # ---------------------------------------------------------------------------
diff --git a/tests/hermes_cli/test_kanban_db_repair.py b/tests/hermes_cli/test_kanban_db_repair.py
index b6ee83197c1..03f4eefe797 100644
--- a/tests/hermes_cli/test_kanban_db_repair.py
+++ b/tests/hermes_cli/test_kanban_db_repair.py
@@ -356,6 +356,7 @@ def test_wal_checkpoint_failure_never_fails_the_tick(tmp_path, monkeypatch):
         conn.close()
 
 
+@pytest.mark.requires_wal
 def test_wal_checkpoint_truncates_wal_file(tmp_path, monkeypatch):
     """End-to-end: the checkpoint actually truncates the -wal sidecar."""
     db_path = tmp_path / "kanban.db"
diff --git a/tests/hermes_cli/test_managed_uv.py b/tests/hermes_cli/test_managed_uv.py
index e0a33107917..167f2c6e8c5 100644
--- a/tests/hermes_cli/test_managed_uv.py
+++ b/tests/hermes_cli/test_managed_uv.py
@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import os
 import stat
+import sys
 from pathlib import Path
+from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -21,6 +23,40 @@ def _make_executable(path: Path) -> None:
     path.chmod(path.stat().st_mode | stat.S_IEXEC)
 
 
+def _runtime_info(
+    executable: Path,
+    sqlite_version: tuple[int, int, int],
+):
+    from hermes_cli.sqlite_runtime import SQLiteRuntimeInfo
+
+    return SQLiteRuntimeInfo(
+        executable=executable,
+        base_prefix=executable.parent.parent,
+        python_version=(3, 11, 15),
+        sqlite_version=sqlite_version,
+        sqlite_version_string=".".join(str(part) for part in sqlite_version),
+        sqlite_source_id=f"source-{sqlite_version}",
+    )
+
+
+def _make_runtime_install(
+    tmp_path: Path,
+    *,
+    windows: bool = False,
+) -> tuple[Path, Path, Path]:
+    root = tmp_path / "checkout"
+    root.mkdir()
+    (root / "pyproject.toml").write_text("[project]\n", encoding="utf-8")
+    live = root / "venv"
+    bin_dir = live / ("Scripts" if windows else "bin")
+    bin_dir.mkdir(parents=True)
+    python = bin_dir / ("python.exe" if windows else "python")
+    python.write_text("live interpreter", encoding="utf-8")
+    sentinel = live / "sentinel"
+    sentinel.write_text("live", encoding="utf-8")
+    return root, live, sentinel
+
+
 # ---------------------------------------------------------------------------
 # managed_uv_path
 # ---------------------------------------------------------------------------
@@ -92,6 +128,37 @@ class TestEnsureUv:
             assert path == str(tmp_path / "bin" / "uv")
             mock_install.assert_called_once()
 
+    def test_install_reports_runtime_repair_to_observer(self, tmp_path):
+        from hermes_cli.managed_uv import (
+            RuntimeRepairResult,
+            ensure_uv,
+        )
+
+        repair = RuntimeRepairResult(
+            "repaired",
+            sqlite_before="3.50.4",
+            sqlite_after="3.53.1",
+        )
+
+        def fake_install(target):
+            _make_executable(target)
+
+        observed = []
+        with patch(
+            "hermes_cli.managed_uv.get_hermes_home",
+            return_value=tmp_path,
+        ), patch(
+            "hermes_cli.managed_uv._install_uv",
+            side_effect=fake_install,
+        ), patch(
+            "hermes_cli.managed_uv.repair_vulnerable_runtime",
+            return_value=repair,
+        ):
+            path = ensure_uv(repair_observer=observed.append)
+
+        assert path == str(tmp_path / "bin" / "uv")
+        assert observed == [repair]
+
     def test_install_failure_returns_falsy(self, tmp_path):
         with patch("hermes_cli.managed_uv.get_hermes_home", return_value=tmp_path), \
              patch("hermes_cli.managed_uv._install_uv", side_effect=RuntimeError("network down")):
@@ -229,6 +296,383 @@ class TestUpdateManagedUv:
             # Still returns the path — failure is non-fatal
             assert result == str(tmp_path / "bin" / "uv")
 
+    def test_old_updater_api_triggers_runtime_repair(self, tmp_path):
+        """The pre-pull main.py call site must activate the fresh module hook."""
+        from hermes_cli.managed_uv import RuntimeRepairResult, update_managed_uv
+
+        uv = tmp_path / "bin" / "uv"
+        _make_executable(uv)
+        with patch("hermes_cli.managed_uv.get_hermes_home", return_value=tmp_path), \
+             patch("hermes_cli.managed_uv.platform.system", return_value="Linux"), \
+             patch("hermes_cli.managed_uv.subprocess.run") as mock_run, \
+             patch(
+                 "hermes_cli.managed_uv.repair_vulnerable_runtime",
+                 return_value=RuntimeRepairResult(
+                     "repaired",
+                     sqlite_before="3.50.4",
+                     sqlite_after="3.53.1",
+                 ),
+             ) as mock_repair:
+            mock_run.side_effect = [
+                MagicMock(returncode=0, stdout="", stderr=""),
+                MagicMock(returncode=0, stdout="uv 0.11.31\n", stderr=""),
+            ]
+
+            result = update_managed_uv()
+
+        assert result == str(uv)
+        mock_repair.assert_called_once_with(str(uv))
+
+    def test_update_reports_runtime_repair_to_observer(self, tmp_path):
+        from hermes_cli.managed_uv import RuntimeRepairResult, update_managed_uv
+
+        uv = tmp_path / "bin" / "uv"
+        _make_executable(uv)
+        repair = RuntimeRepairResult(
+            "repaired",
+            sqlite_before="3.50.4",
+            sqlite_after="3.53.1",
+        )
+        observed = []
+        with patch(
+            "hermes_cli.managed_uv.get_hermes_home",
+            return_value=tmp_path,
+        ), patch(
+            "hermes_cli.managed_uv.subprocess.run",
+            return_value=MagicMock(returncode=0, stdout="uv 0.11.31\n", stderr=""),
+        ), patch(
+            "hermes_cli.managed_uv.repair_vulnerable_runtime",
+            return_value=repair,
+        ):
+            result = update_managed_uv(repair_observer=observed.append)
+
+        assert result == str(uv)
+        assert observed == [repair]
+
+
+class TestManagedPythonStore:
+    def test_store_is_checkout_scoped_across_profiles(self, tmp_path, monkeypatch):
+        from hermes_cli.managed_uv import managed_python_install_dir
+
+        checkout = tmp_path / "checkout"
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path / "profiles" / "alpha"))
+        alpha = managed_python_install_dir(checkout)
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path / "profiles" / "beta"))
+        beta = managed_python_install_dir(checkout)
+
+        expected = checkout / ".hermes-runtime" / "python"
+        assert alpha == expected
+        assert beta == expected
+
+    def test_environment_is_private_and_sanitized(self, tmp_path):
+        from hermes_cli.managed_uv import managed_python_env
+
+        checkout = tmp_path / "checkout"
+        base_env = {
+            "KEEP_ME": "yes",
+            "CONDA_DEFAULT_ENV": "poison",
+            "CONDA_PREFIX": "/poison/conda",
+            "UV_PROJECT_ENVIRONMENT": "/poison/project",
+            "UV_NO_MANAGED_PYTHON": "1",
+            "UV_PYTHON": "/poison/python",
+            "UV_PYTHON_DOWNLOADS": "never",
+            "UV_SYSTEM_PYTHON": "1",
+            "VIRTUAL_ENV": "/poison/venv",
+            "PYTHONHOME": "/poison/home",
+            "PYTHONPATH": "/poison/path",
+        }
+
+        env = managed_python_env(checkout, base_env=base_env)
+
+        assert env["KEEP_ME"] == "yes"
+        assert env["UV_MANAGED_PYTHON"] == "1"
+        assert env["UV_NO_CONFIG"] == "1"
+        assert env["UV_PYTHON_INSTALL_BIN"] == "0"
+        assert env["UV_PYTHON_INSTALL_REGISTRY"] == "0"
+        assert env["UV_PYTHON_INSTALL_DIR"] == str(
+            checkout / ".hermes-runtime" / "python"
+        )
+        for key in (
+            "CONDA_DEFAULT_ENV",
+            "CONDA_PREFIX",
+            "UV_PROJECT_ENVIRONMENT",
+            "UV_NO_MANAGED_PYTHON",
+            "UV_PYTHON",
+            "UV_PYTHON_DOWNLOADS",
+            "UV_SYSTEM_PYTHON",
+            "VIRTUAL_ENV",
+            "PYTHONHOME",
+            "PYTHONPATH",
+        ):
+            assert key not in env
+        assert base_env["PYTHONHOME"] == "/poison/home"
+
+
+class TestRuntimeRepair:
+    def test_safe_runtime_is_a_noop(self, tmp_path):
+        from hermes_cli.managed_uv import repair_vulnerable_runtime
+
+        root, live, sentinel = _make_runtime_install(tmp_path)
+        current = _runtime_info(live / "bin" / "python", (3, 53, 1))
+        with patch("hermes_cli.managed_uv.platform.system", return_value="Linux"), \
+             patch(
+                 "hermes_cli.managed_uv.probe_sqlite_runtime",
+                 return_value=current,
+             ), \
+             patch(
+                 "hermes_cli.managed_uv._install_safe_python_generation"
+             ) as mock_install:
+            result = repair_vulnerable_runtime("uv", project_root=root)
+
+        assert result.status == "safe"
+        assert result.sqlite_before == "3.53.1"
+        assert result.sqlite_after == "3.53.1"
+        assert sentinel.read_text(encoding="utf-8") == "live"
+        assert not (root / ".hermes-runtime").exists()
+        mock_install.assert_not_called()
+
+    def test_failed_candidate_preserves_live_venv(self, tmp_path):
+        from hermes_cli.managed_uv import (
+            _acquire_repair_lock,
+            _release_repair_lock,
+            repair_vulnerable_runtime,
+        )
+
+        root, live, sentinel = _make_runtime_install(tmp_path)
+        current = _runtime_info(live / "bin" / "python", (3, 50, 4))
+        generation = root / ".hermes-runtime" / "python" / "generation-test"
+        candidate_python = generation / "bin" / "python"
+        candidate_python.parent.mkdir(parents=True)
+        candidate_python.write_text("candidate interpreter", encoding="utf-8")
+        fixed = _runtime_info(candidate_python, (3, 53, 1))
+
+        with patch("hermes_cli.managed_uv.platform.system", return_value="Linux"), \
+             patch(
+                 "hermes_cli.managed_uv.probe_sqlite_runtime",
+                 side_effect=[current, current],
+             ), \
+             patch(
+                 "hermes_cli.managed_uv._install_safe_python_generation",
+                 return_value=(generation, candidate_python, fixed),
+             ), \
+             patch(
+                 "hermes_cli.managed_uv._stage_candidate_venv",
+                 return_value=None,
+             ):
+            result = repair_vulnerable_runtime("uv", project_root=root)
+
+        assert result.status == "failed"
+        assert "replacement environment" in result.detail
+        assert sentinel.read_text(encoding="utf-8") == "live"
+        assert (live / "bin" / "python").read_text(encoding="utf-8") == (
+            "live interpreter"
+        )
+        assert not generation.exists()
+        reacquired = _acquire_repair_lock(root / ".hermes-runtime")
+        assert reacquired is not None
+        _release_repair_lock(reacquired)
+
+    def test_windows_holders_refuse_runtime_mutation(self, tmp_path, monkeypatch):
+        from hermes_cli.managed_uv import repair_vulnerable_runtime
+
+        root, live, sentinel = _make_runtime_install(tmp_path, windows=True)
+        current = _runtime_info(live / "Scripts" / "python.exe", (3, 50, 4))
+        old_main = SimpleNamespace(
+            _detect_venv_python_processes=lambda: [
+                (1729, "python.exe", "hermes gateway run")
+            ]
+        )
+        monkeypatch.setitem(sys.modules, "hermes_cli.main", old_main)
+
+        with patch("hermes_cli.managed_uv.platform.system", return_value="Windows"), \
+             patch(
+                 "hermes_cli.managed_uv.probe_sqlite_runtime",
+                 return_value=current,
+             ), \
+             patch(
+                 "hermes_cli.managed_uv._install_safe_python_generation"
+             ) as mock_install:
+            result = repair_vulnerable_runtime("uv.exe", project_root=root)
+
+        assert result.status == "skipped"
+        assert "PID 1729" in result.detail
+        assert sentinel.read_text(encoding="utf-8") == "live"
+        assert not (root / ".hermes-runtime").exists()
+        mock_install.assert_not_called()
+
+
+class TestRuntimeCutover:
+    def test_os_lock_blocks_concurrent_repair_and_releases(self, tmp_path):
+        from hermes_cli.managed_uv import _acquire_repair_lock, _release_repair_lock
+
+        runtime_root = tmp_path / ".hermes-runtime"
+        first = _acquire_repair_lock(runtime_root)
+        assert first is not None
+        assert _acquire_repair_lock(runtime_root) is None
+
+        _release_repair_lock(first)
+        second = _acquire_repair_lock(runtime_root)
+        assert second is not None
+        _release_repair_lock(second)
+
+    def test_failed_smoke_with_empty_output_has_stable_detail(self, tmp_path):
+        from hermes_cli.managed_uv import _smoke_candidate_venv
+
+        candidate = tmp_path / "venv"
+        candidate.mkdir()
+        fixed = _runtime_info(candidate / "bin" / "python", (3, 53, 1))
+        failed = MagicMock(returncode=1, stdout=" \n", stderr="\n")
+        with patch(
+            "hermes_cli.managed_uv.probe_sqlite_runtime",
+            return_value=fixed,
+        ), patch("hermes_cli.managed_uv.subprocess.run", return_value=failed):
+            healthy, detail, info = _smoke_candidate_venv(candidate)
+
+        assert healthy is False
+        assert detail == "core import smoke failed"
+        assert info == fixed
+
+    def test_successfully_renames_candidate_into_live_path(self, tmp_path):
+        from hermes_cli.managed_uv import _cut_over_candidate
+
+        root, _, _ = _make_runtime_install(tmp_path)
+        runtime_root = root / ".hermes-runtime"
+        candidate = runtime_root / "venv-candidate-test"
+        candidate.mkdir(parents=True)
+        (candidate / "sentinel").write_text("candidate", encoding="utf-8")
+        fixed = _runtime_info(candidate / "bin" / "python", (3, 53, 1))
+
+        with patch(
+            "hermes_cli.managed_uv._smoke_candidate_venv",
+            return_value=(True, "", fixed),
+        ):
+            ok, backup, info, detail = _cut_over_candidate(
+                candidate,
+                project_root=root,
+            )
+
+        assert ok is True
+        assert detail == ""
+        assert info == fixed
+        assert backup is not None
+        assert (root / "venv" / "sentinel").read_text(encoding="utf-8") == (
+            "candidate"
+        )
+        assert (backup / "sentinel").read_text(encoding="utf-8") == "live"
+        assert not candidate.exists()
+
+    def test_post_swap_smoke_failure_rolls_back_live_venv(self, tmp_path):
+        from hermes_cli.managed_uv import _cut_over_candidate
+
+        root, live, sentinel = _make_runtime_install(tmp_path)
+        runtime_root = root / ".hermes-runtime"
+        candidate = runtime_root / "venv-candidate-test"
+        candidate.mkdir(parents=True)
+        (candidate / "sentinel").write_text("candidate", encoding="utf-8")
+        rejected_info = _runtime_info(candidate / "bin" / "python", (3, 50, 4))
+
+        with patch(
+            "hermes_cli.managed_uv._smoke_candidate_venv",
+            return_value=(False, "core import smoke failed", rejected_info),
+        ):
+            ok, backup, info, detail = _cut_over_candidate(
+                candidate,
+                project_root=root,
+            )
+
+        assert ok is False
+        assert backup is None
+        assert info == rejected_info
+        assert "post-cutover smoke failed" in detail
+        assert sentinel.read_text(encoding="utf-8") == "live"
+        assert (live / "bin" / "python").read_text(encoding="utf-8") == (
+            "live interpreter"
+        )
+        assert not candidate.exists()
+        assert not list(runtime_root.glob("venv-rejected-*"))
+
+    def test_smoke_exception_after_swap_rolls_back_live_venv(self, tmp_path):
+        from hermes_cli.managed_uv import _cut_over_candidate
+
+        root, live, sentinel = _make_runtime_install(tmp_path)
+        candidate = root / ".hermes-runtime" / "venv-candidate-test"
+        candidate.mkdir(parents=True)
+        (candidate / "sentinel").write_text("candidate", encoding="utf-8")
+
+        with patch(
+            "hermes_cli.managed_uv._smoke_candidate_venv",
+            side_effect=RuntimeError("probe crashed"),
+        ):
+            ok, backup, info, detail = _cut_over_candidate(
+                candidate,
+                project_root=root,
+            )
+
+        assert ok is False
+        assert backup is None
+        assert info is None
+        assert "probe crashed" in detail
+        assert sentinel.read_text(encoding="utf-8") == "live"
+        assert (live / "bin" / "python").read_text(encoding="utf-8") == (
+            "live interpreter"
+        )
+
+    def test_interrupt_during_promotion_restores_live_venv(self, tmp_path):
+        from hermes_cli.managed_uv import _cut_over_candidate
+
+        root, live, sentinel = _make_runtime_install(tmp_path)
+        candidate = root / ".hermes-runtime" / "venv-candidate-test"
+        candidate.mkdir(parents=True)
+        (candidate / "sentinel").write_text("candidate", encoding="utf-8")
+        rename_count = 0
+
+        def interrupt_second_rename(source, destination):
+            nonlocal rename_count
+            rename_count += 1
+            if rename_count == 2:
+                raise KeyboardInterrupt
+            source.rename(destination)
+
+        with patch(
+            "hermes_cli.managed_uv._rename_with_retry",
+            side_effect=interrupt_second_rename,
+        ), pytest.raises(KeyboardInterrupt):
+            _cut_over_candidate(candidate, project_root=root)
+
+        assert sentinel.read_text(encoding="utf-8") == "live"
+        assert candidate.exists()
+        assert not list(root.glob("venv.stale.runtime-*"))
+
+    def test_interrupt_during_rollback_restores_live_venv(self, tmp_path):
+        from hermes_cli.managed_uv import _cut_over_candidate
+
+        root, live, sentinel = _make_runtime_install(tmp_path)
+        runtime_root = root / ".hermes-runtime"
+        candidate = runtime_root / "venv-candidate-test"
+        candidate.mkdir(parents=True)
+        (candidate / "sentinel").write_text("candidate", encoding="utf-8")
+        rename_count = 0
+
+        def interrupt_backup_restore(source, destination):
+            nonlocal rename_count
+            rename_count += 1
+            if rename_count == 4:
+                raise KeyboardInterrupt
+            source.rename(destination)
+
+        with patch(
+            "hermes_cli.managed_uv._rename_with_retry",
+            side_effect=interrupt_backup_restore,
+        ), patch(
+            "hermes_cli.managed_uv._smoke_candidate_venv",
+            return_value=(False, "core import smoke failed", None),
+        ), pytest.raises(KeyboardInterrupt):
+            _cut_over_candidate(candidate, project_root=root)
+
+        assert sentinel.read_text(encoding="utf-8") == "live"
+        assert not list(root.glob("venv.stale.runtime-*"))
+        assert list(runtime_root.glob("venv-rejected-*"))
+
 
 # ---------------------------------------------------------------------------
 # _install_uv internals
@@ -253,3 +697,373 @@ class TestInstallUvInternals:
             mock_windows.assert_called_once()
             call_env = mock_windows.call_args[0][0]
             assert call_env["UV_INSTALL_DIR"] == str(tmp_path / "bin")
+
+
+class TestRuntimeRequestMinorLine:
+    """The repair must request the CPython minor line, not the exact patch.
+
+    Real-world constraint (verified live, July 2026): every published
+    python-build-standalone artifact for 3.11.14 links vulnerable SQLite
+    3.50.4 — even with --reinstall. The fixed SQLite (3.53.1) only exists
+    from 3.11.15. An exact-patch pin makes the repair permanently
+    impossible on such installs.
+    """
+
+    def test_requests_minor_line(self):
+        from hermes_cli.managed_uv import _runtime_request
+
+        info = _runtime_info(Path("/venv/bin/python"), (3, 50, 4))
+        assert _runtime_request(info) == "3.11"
+
+    @staticmethod
+    def _run_generation(tmp_path, monkeypatch, current_version, candidate_version):
+        """Drive _install_safe_python_generation with fakes; return result."""
+        import hermes_cli.managed_uv as managed_uv
+        from hermes_cli.sqlite_runtime import SQLiteRuntimeInfo
+
+        state = {}
+
+        def fake_run(cmd, **kwargs):
+            if "install" in cmd:
+                state["generation"] = Path(kwargs["env"]["UV_PYTHON_INSTALL_DIR"])
+                return SimpleNamespace(returncode=0, stdout="", stderr="")
+            # uv python find → a path inside the generation dir
+            python = state["generation"] / "cpython" / "bin" / "python3"
+            python.parent.mkdir(parents=True, exist_ok=True)
+            python.touch()
+            return SimpleNamespace(returncode=0, stdout=str(python), stderr="")
+
+        def fake_probe(python, **kwargs):
+            return SQLiteRuntimeInfo(
+                executable=Path(python),
+                base_prefix=Path(python).parent.parent,
+                python_version=candidate_version,
+                sqlite_version=(3, 53, 1),
+                sqlite_version_string="3.53.1",
+                sqlite_source_id="fixed",
+            )
+
+        current = SQLiteRuntimeInfo(
+            executable=Path("/venv/bin/python"),
+            base_prefix=Path("/venv"),
+            python_version=current_version,
+            sqlite_version=(3, 50, 4),
+            sqlite_version_string="3.50.4",
+            sqlite_source_id="old",
+        )
+        monkeypatch.setattr(managed_uv.subprocess, "run", fake_run)
+        monkeypatch.setattr(managed_uv, "probe_sqlite_runtime", fake_probe)
+        return managed_uv._install_safe_python_generation(
+            "uv", project_root=tmp_path, current=current
+        )
+
+    def test_accepts_newer_patch_same_minor(self, tmp_path, monkeypatch):
+        result = self._run_generation(
+            tmp_path, monkeypatch, (3, 11, 14), (3, 11, 15)
+        )
+        assert result is not None
+        _, _, candidate = result
+        assert candidate.python_version == (3, 11, 15)
+
+    def test_rejects_minor_drift(self, tmp_path, monkeypatch):
+        assert (
+            self._run_generation(tmp_path, monkeypatch, (3, 11, 14), (3, 12, 1))
+            is None
+        )
+
+    def test_rejects_patch_downgrade(self, tmp_path, monkeypatch):
+        assert (
+            self._run_generation(tmp_path, monkeypatch, (3, 11, 14), (3, 11, 13))
+            is None
+        )
+
+
+class TestPatchRetryOnVulnerableCandidate:
+    """Regression tests for issue #71250: when the bare minor-line request
+    (e.g. "3.11") resolves to a candidate that's still vulnerable -- because
+    uv's default resolution for that host picked an older cached/indexed
+    patch even though a newer non-vulnerable one is available -- the
+    provisioner must query the available patches and retry with explicit
+    newer versions, rather than giving up after the first attempt.
+    """
+
+    @staticmethod
+    def _versioned_probe_run(vulnerable_versions, sqlite_fixed=(3, 53, 1)):
+        """Build a fake subprocess.run where the install/find/probe cycle
+        resolves to a DIFFERENT candidate Python version depending on which
+        exact version string was requested, so retries with explicit
+        patches can be distinguished from the initial bare-minor attempt."""
+        import hermes_cli.managed_uv as managed_uv
+        from hermes_cli.sqlite_runtime import SQLiteRuntimeInfo
+
+        state = {"requested": None}
+
+        def fake_run(cmd, **kwargs):
+            if "install" in cmd:
+                # cmd = [uv, "python", "install", <request>, ...]
+                state["requested"] = cmd[3]
+                state["generation"] = Path(kwargs["env"]["UV_PYTHON_INSTALL_DIR"])
+                return SimpleNamespace(returncode=0, stdout="", stderr="")
+            if "list" in cmd:
+                return SimpleNamespace(returncode=0, stdout="", stderr="")
+            # uv python find → a path inside the generation dir, tagged with
+            # which request produced it so the probe below can look it up.
+            python = state["generation"] / "cpython" / "bin" / "python3"
+            python.parent.mkdir(parents=True, exist_ok=True)
+            python.write_text(state["requested"] or "")
+            return SimpleNamespace(returncode=0, stdout=str(python), stderr="")
+
+        def fake_probe(python, **kwargs):
+            requested = Path(python).read_text()
+            # Bare minor request ("3.11") always resolves to the FIRST
+            # (worst-case / already-known-vulnerable) version in the list.
+            if requested in vulnerable_versions or requested == "3.11":
+                version = (3, 11, 14) if requested == "3.11" else tuple(
+                    int(p) for p in requested.split(".")
+                )
+                return SQLiteRuntimeInfo(
+                    executable=Path(python), base_prefix=Path(python).parent.parent,
+                    python_version=version, sqlite_version=(3, 50, 4),
+                    sqlite_version_string="3.50.4", sqlite_source_id="vulnerable",
+                )
+            version = tuple(int(p) for p in requested.split("."))
+            return SQLiteRuntimeInfo(
+                executable=Path(python), base_prefix=Path(python).parent.parent,
+                python_version=version, sqlite_version=sqlite_fixed,
+                sqlite_version_string=".".join(str(p) for p in sqlite_fixed),
+                sqlite_source_id="fixed",
+            )
+
+        return fake_run, fake_probe
+
+    def _run(self, tmp_path, monkeypatch, *, vulnerable_versions, patch_list):
+        import hermes_cli.managed_uv as managed_uv
+        from hermes_cli.sqlite_runtime import SQLiteRuntimeInfo
+
+        fake_run, fake_probe = self._versioned_probe_run(vulnerable_versions)
+        current = SQLiteRuntimeInfo(
+            executable=Path("/venv/bin/python"), base_prefix=Path("/venv"),
+            python_version=(3, 11, 14), sqlite_version=(3, 50, 4),
+            sqlite_version_string="3.50.4", sqlite_source_id="old",
+        )
+        monkeypatch.setattr(managed_uv.subprocess, "run", fake_run)
+        monkeypatch.setattr(managed_uv, "probe_sqlite_runtime", fake_probe)
+        monkeypatch.setattr(
+            managed_uv, "_list_available_patches", lambda *a, **kw: patch_list
+        )
+        return managed_uv._install_safe_python_generation(
+            "uv", project_root=tmp_path, current=current
+        )
+
+    def test_retries_and_succeeds_with_explicit_newer_patch(self, tmp_path, monkeypatch):
+        """The exact #71250 scenario: bare '3.11' resolves to vulnerable
+        3.11.14, but 3.11.15 (fixed) is available and gets tried explicitly."""
+        result = self._run(
+            tmp_path, monkeypatch,
+            vulnerable_versions={"3.11"},
+            patch_list=[(3, 11, 15), (3, 11, 14), (3, 11, 13), (3, 11, 12)],
+        )
+        assert result is not None, "Must recover via explicit-patch retry"
+        _, _, candidate = result
+        assert candidate.python_version == (3, 11, 15)
+        assert not candidate.wal_reset_vulnerable
+
+    def test_gives_up_after_max_retries_when_all_patches_vulnerable(self, tmp_path, monkeypatch):
+        """If every known patch is vulnerable (or the list is exhausted
+        within the retry cap), the provisioner must return None rather than
+        looping forever or raising."""
+        result = self._run(
+            tmp_path, monkeypatch,
+            vulnerable_versions={"3.11", "3.11.14", "3.11.13", "3.11.12", "3.11.11", "3.11.10"},
+            patch_list=[(3, 11, 14), (3, 11, 13), (3, 11, 12), (3, 11, 11), (3, 11, 10), (3, 11, 9)],
+        )
+        assert result is None
+
+    def test_empty_patch_list_falls_back_to_none_without_crashing(self, tmp_path, monkeypatch):
+        """If _list_available_patches can't be queried (network failure,
+        returns []), the provisioner must not crash -- it just has nothing
+        to retry with and returns None (same as before this fix existed)."""
+        result = self._run(
+            tmp_path, monkeypatch,
+            vulnerable_versions={"3.11"},
+            patch_list=[],
+        )
+        assert result is None
+
+    def test_does_not_retry_patches_at_or_below_the_installed_version(
+        self, tmp_path, monkeypatch
+    ):
+        """Only NEWER patches can carry the SQLite fix.
+
+        On a uv whose download catalog is stale, the newest indexed patch can
+        be the same one already installed -- issue #71250 reproduces exactly
+        this: newest indexed 3.11 was 3.11.14, which is what's installed.
+        Retrying the patches below it is guaranteed to fail (each is the
+        known-vulnerable current version or an older build that cannot contain
+        a later fix, and the downgrade guard rejects them anyway), and every
+        attempt is a real download+install+probe+delete cycle. The loop must
+        skip them rather than burn _MAX_PATCH_RETRIES on certain rejections.
+        """
+        import hermes_cli.managed_uv as managed_uv
+        from hermes_cli.sqlite_runtime import SQLiteRuntimeInfo
+
+        install_requests: list[str] = []
+        fake_run, fake_probe = self._versioned_probe_run({"3.11"})
+
+        def recording_run(cmd, **kwargs):
+            if "install" in cmd:
+                install_requests.append(cmd[3])
+            return fake_run(cmd, **kwargs)
+
+        current = SQLiteRuntimeInfo(
+            executable=Path("/venv/bin/python"), base_prefix=Path("/venv"),
+            python_version=(3, 11, 14), sqlite_version=(3, 50, 4),
+            sqlite_version_string="3.50.4", sqlite_source_id="old",
+        )
+        # Stale catalog: newest indexed patch == the installed patch.
+        stale_index = [(3, 11, v) for v in range(14, 8, -1)]
+        monkeypatch.setattr(managed_uv.subprocess, "run", recording_run)
+        monkeypatch.setattr(managed_uv, "probe_sqlite_runtime", fake_probe)
+        monkeypatch.setattr(
+            managed_uv, "_list_available_patches", lambda *a, **kw: stale_index
+        )
+
+        result = managed_uv._install_safe_python_generation(
+            "uv", project_root=tmp_path, current=current
+        )
+
+        assert result is None
+        # Exactly one attempt: the bare minor line. No downgrade retries.
+        assert install_requests == ["3.11"]
+
+    def test_still_retries_when_a_newer_patch_exists_in_the_index(
+        self, tmp_path, monkeypatch
+    ):
+        """The downgrade skip must not suppress legitimate newer-patch retries."""
+        result = self._run(
+            tmp_path, monkeypatch,
+            vulnerable_versions={"3.11"},
+            # Mixed index: a newer fixed patch alongside older useless ones.
+            patch_list=[(3, 11, 15), (3, 11, 14), (3, 11, 13)],
+        )
+        assert result is not None
+        assert result[2].python_version == (3, 11, 15)
+        assert not result[2].wal_reset_vulnerable
+
+    def test_retry_is_bounded_by_max_retries_constant(self, tmp_path, monkeypatch):
+        """A very long patch list must not result in unbounded retries --
+        capped at _MAX_PATCH_RETRIES attempts."""
+        import hermes_cli.managed_uv as managed_uv
+
+        install_calls = []
+        fake_run, fake_probe = self._versioned_probe_run({"3.11"})
+        original_fake_run = fake_run
+
+        def counting_fake_run(cmd, **kwargs):
+            if "install" in cmd:
+                install_calls.append(cmd[3])
+            return original_fake_run(cmd, **kwargs)
+
+        from hermes_cli.sqlite_runtime import SQLiteRuntimeInfo
+        current = SQLiteRuntimeInfo(
+            executable=Path("/venv/bin/python"), base_prefix=Path("/venv"),
+            python_version=(3, 11, 14), sqlite_version=(3, 50, 4),
+            sqlite_version_string="3.50.4", sqlite_source_id="old",
+        )
+        # 20 vulnerable patches -- far more than _MAX_PATCH_RETRIES.
+        huge_patch_list = [(3, 11, v) for v in range(30, 10, -1)]
+        all_vulnerable = {f"3.11.{v}" for v in range(30, 10, -1)} | {"3.11"}
+        fake_run2, fake_probe2 = self._versioned_probe_run(all_vulnerable)
+
+        monkeypatch.setattr(managed_uv.subprocess, "run", fake_run2)
+        monkeypatch.setattr(managed_uv, "probe_sqlite_runtime", fake_probe2)
+        monkeypatch.setattr(
+            managed_uv, "_list_available_patches", lambda *a, **kw: huge_patch_list
+        )
+        result = managed_uv._install_safe_python_generation(
+            "uv", project_root=tmp_path, current=current
+        )
+        assert result is None
+        # 1 initial bare-minor attempt + at most _MAX_PATCH_RETRIES retries.
+        assert managed_uv._MAX_PATCH_RETRIES <= 5, (
+            "sanity: constant should stay small since each attempt is a "
+            "real download+install+probe cycle"
+        )
+
+
+class TestListAvailablePatches:
+    """Direct unit tests for _list_available_patches()'s JSON parsing,
+    against realistic `uv python list --all-versions --output-format json`
+    output (captured from a real uv 0.11.7 invocation)."""
+
+    SAMPLE_OUTPUT = (
+        '[{"key":"cpython-3.11.15-linux-x86_64-gnu","version":"3.11.15",'
+        '"version_parts":{"major":3,"minor":11,"patch":15},"path":null,'
+        '"symlink":null,"url":"https://example/cpython-3.11.15.tar.gz",'
+        '"os":"linux","variant":"default","implementation":"cpython",'
+        '"arch":"x86_64","libc":"gnu"},'
+        '{"key":"cpython-3.11.14-linux-x86_64-gnu","version":"3.11.14",'
+        '"version_parts":{"major":3,"minor":11,"patch":14},"path":null,'
+        '"symlink":null,"url":"https://example/cpython-3.11.14.tar.gz",'
+        '"os":"linux","variant":"default","implementation":"cpython",'
+        '"arch":"x86_64","libc":"gnu"},'
+        '{"key":"pypy-3.11.15-linux-x86_64-gnu","version":"3.11.15",'
+        '"version_parts":{"major":3,"minor":11,"patch":15},"path":null,'
+        '"symlink":null,"url":"https://example/pypy-3.11.15.tar.gz",'
+        '"os":"linux","variant":"default","implementation":"pypy",'
+        '"arch":"x86_64","libc":"gnu"}]'
+    )
+
+    def test_parses_and_sorts_newest_first(self, tmp_path, monkeypatch):
+        import hermes_cli.managed_uv as managed_uv
+
+        def fake_run(cmd, **kwargs):
+            return SimpleNamespace(returncode=0, stdout=self.SAMPLE_OUTPUT, stderr="")
+
+        monkeypatch.setattr(managed_uv.subprocess, "run", fake_run)
+        result = managed_uv._list_available_patches(
+            "uv", "3.11", cwd=tmp_path, env={}
+        )
+        assert result == [(3, 11, 15), (3, 11, 14)]
+
+    def test_filters_out_non_cpython_implementations(self, tmp_path, monkeypatch):
+        """pypy/graalpy entries at the same version must not be returned --
+        the repair path only wants cpython builds."""
+        import hermes_cli.managed_uv as managed_uv
+
+        def fake_run(cmd, **kwargs):
+            return SimpleNamespace(returncode=0, stdout=self.SAMPLE_OUTPUT, stderr="")
+
+        monkeypatch.setattr(managed_uv.subprocess, "run", fake_run)
+        result = managed_uv._list_available_patches(
+            "uv", "3.11", cwd=tmp_path, env={}
+        )
+        # Only one 3.11.15 entry (cpython), not two (cpython + pypy).
+        assert result.count((3, 11, 15)) == 1
+
+    def test_nonzero_exit_returns_empty_list(self, tmp_path, monkeypatch):
+        import hermes_cli.managed_uv as managed_uv
+
+        def fake_run(cmd, **kwargs):
+            return SimpleNamespace(returncode=1, stdout="", stderr="network error")
+
+        monkeypatch.setattr(managed_uv.subprocess, "run", fake_run)
+        assert managed_uv._list_available_patches("uv", "3.11", cwd=tmp_path, env={}) == []
+
+    def test_malformed_json_returns_empty_list_not_crash(self, tmp_path, monkeypatch):
+        import hermes_cli.managed_uv as managed_uv
+
+        def fake_run(cmd, **kwargs):
+            return SimpleNamespace(returncode=0, stdout="not valid json{{{", stderr="")
+
+        monkeypatch.setattr(managed_uv.subprocess, "run", fake_run)
+        assert managed_uv._list_available_patches("uv", "3.11", cwd=tmp_path, env={}) == []
+
+    def test_subprocess_exception_returns_empty_list(self, tmp_path, monkeypatch):
+        import hermes_cli.managed_uv as managed_uv
+
+        def fake_run(cmd, **kwargs):
+            raise OSError("uv binary not found")
+
+        monkeypatch.setattr(managed_uv.subprocess, "run", fake_run)
+        assert managed_uv._list_available_patches("uv", "3.11", cwd=tmp_path, env={}) == []
diff --git a/tests/hermes_cli/test_memory_setup.py b/tests/hermes_cli/test_memory_setup.py
index b5b574230c7..487f0949d7f 100644
--- a/tests/hermes_cli/test_memory_setup.py
+++ b/tests/hermes_cli/test_memory_setup.py
@@ -196,3 +196,37 @@ def test_cmd_setup_generic_choice_cancel_writes_nothing(tmp_path, monkeypatch):
     save_config.assert_not_called()
     provider.save_config.assert_not_called()
     assert not (tmp_path / ".env").exists()
+
+
+def test_write_env_vars_strips_line_separators_and_nul(tmp_path):
+    """A pasted secret with embedded CR/LF/NUL must not inject an extra
+    KEY=VALUE line into .env (mirrors the openviking plugin's writer)."""
+    env_path = tmp_path / ".env"
+
+    memory_setup._write_env_vars(
+        env_path,
+        {"PROVIDER_API_KEY": "good\nINJECTED_KEY=attacker\r\u2028\x00tail"},
+    )
+
+    lines = env_path.read_text(encoding="utf-8").splitlines()
+    assert lines == ["PROVIDER_API_KEY=goodINJECTED_KEY=attackertail"]
+    parsed = dict(line.split("=", 1) for line in lines if "=" in line)
+    assert set(parsed) == {"PROVIDER_API_KEY"}
+
+
+def test_write_env_vars_strips_newlines_when_updating_existing_key(tmp_path):
+    env_path = tmp_path / ".env"
+    env_path.write_text("PROVIDER_API_KEY=old\nKEEP=1\n", encoding="utf-8")
+
+    memory_setup._write_env_vars(env_path, {"PROVIDER_API_KEY": "new\r\nROGUE=1"})
+
+    lines = env_path.read_text(encoding="utf-8").splitlines()
+    assert "PROVIDER_API_KEY=newROGUE=1" in lines
+    assert "KEEP=1" in lines
+    assert all(not line.startswith("ROGUE=") for line in lines)
+
+
+def test_write_env_vars_plain_value_roundtrips(tmp_path):
+    env_path = tmp_path / ".env"
+    memory_setup._write_env_vars(env_path, {"PROVIDER_API_KEY": "sk-plain-1234"})
+    assert env_path.read_text(encoding="utf-8") == "PROVIDER_API_KEY=sk-plain-1234\n"
diff --git a/tests/hermes_cli/test_moa_config.py b/tests/hermes_cli/test_moa_config.py
index e6b4714e225..62cfc32c9b8 100644
--- a/tests/hermes_cli/test_moa_config.py
+++ b/tests/hermes_cli/test_moa_config.py
@@ -14,12 +14,37 @@ from hermes_cli.moa_config import (
 )
 
 
+def test_moa_slot_picker_excludes_unconfigured_providers(monkeypatch):
+    from hermes_cli import moa_cmd
+
+    captured = {}
+    monkeypatch.setattr(moa_cmd, "load_picker_context", lambda: object())
+
+    def fake_build(_context, **kwargs):
+        captured.update(kwargs)
+        return {
+            "providers": [
+                {"slug": "moa", "models": ["default"]},
+                {"slug": "opencode-go", "models": ["deepseek-v4-pro"]},
+            ]
+        }
+
+    monkeypatch.setattr(moa_cmd, "build_models_payload", fake_build)
+
+    assert [row["slug"] for row in moa_cmd._model_options()] == ["opencode-go"]
+    assert captured["include_unconfigured"] is False
+
+
+def _enabled_refs(refs):
+    return [{**slot, "enabled": True} for slot in refs]
+
+
 def test_normalize_moa_config_uses_default_named_preset():
     cfg = normalize_moa_config({})
 
     assert cfg["default_preset"] == DEFAULT_MOA_PRESET_NAME
     assert list(cfg["presets"]) == [DEFAULT_MOA_PRESET_NAME]
-    assert cfg["reference_models"] == DEFAULT_MOA_REFERENCE_MODELS
+    assert cfg["reference_models"] == _enabled_refs(DEFAULT_MOA_REFERENCE_MODELS)
     assert cfg["aggregator"] == DEFAULT_MOA_AGGREGATOR
 
 
@@ -42,7 +67,45 @@ def test_normalize_moa_config_preserves_named_presets():
 
     assert cfg["default_preset"] == "coding"
     assert set(cfg["presets"]) == {"coding", "review"}
-    assert cfg["reference_models"] == [{"provider": "openai-codex", "model": "gpt-5.5"}]
+    assert cfg["reference_models"] == [{"provider": "openai-codex", "model": "gpt-5.5", "enabled": True}]
+
+
+def test_normalize_moa_config_defaults_reference_enabled_true():
+    cfg = normalize_moa_config(
+        {
+            "presets": {
+                "review": {
+                    "reference_models": [{"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}],
+                    "aggregator": {"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+                }
+            }
+        }
+    )
+
+    assert cfg["presets"]["review"]["reference_models"] == [
+        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "enabled": True}
+    ]
+
+
+def test_normalize_moa_config_preserves_disabled_reference():
+    cfg = normalize_moa_config(
+        {
+            "presets": {
+                "review": {
+                    "reference_models": [
+                        {"provider": "openai-codex", "model": "gpt-5.5", "enabled": False},
+                        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "enabled": "false"},
+                    ],
+                    "aggregator": {"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+                }
+            }
+        }
+    )
+
+    assert cfg["presets"]["review"]["reference_models"] == [
+        {"provider": "openai-codex", "model": "gpt-5.5", "enabled": False},
+        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "enabled": False},
+    ]
 
 
 def test_legacy_flat_config_becomes_default_preset():
@@ -54,7 +117,7 @@ def test_legacy_flat_config_becomes_default_preset():
     )
 
     assert cfg["presets"][DEFAULT_MOA_PRESET_NAME]["reference_models"] == [
-        {"provider": "openai-codex", "model": "gpt-5.5"}
+        {"provider": "openai-codex", "model": "gpt-5.5", "enabled": True}
     ]
 
 
@@ -89,7 +152,7 @@ def test_normalize_moa_config_tolerates_non_list_reference_models():
     cfg = normalize_moa_config(
         {"presets": {"broken": {"reference_models": 2}}}
     )
-    assert cfg["presets"]["broken"]["reference_models"] == DEFAULT_MOA_REFERENCE_MODELS
+    assert cfg["presets"]["broken"]["reference_models"] == _enabled_refs(DEFAULT_MOA_REFERENCE_MODELS)
 
 
 def test_normalize_moa_config_wraps_bare_dict_reference_models():
@@ -97,7 +160,36 @@ def test_normalize_moa_config_wraps_bare_dict_reference_models():
     cfg = normalize_moa_config(
         {"presets": {"p": {"reference_models": {"provider": "openai", "model": "gpt-4o"}}}}
     )
-    assert cfg["presets"]["p"]["reference_models"] == [{"provider": "openai", "model": "gpt-4o"}]
+    assert cfg["presets"]["p"]["reference_models"] == [{"provider": "openai", "model": "gpt-4o", "enabled": True}]
+
+
+def test_normalize_moa_config_parses_json_string_reference_models():
+    """reference_models stored as a JSON string (hand-edited config.yaml or a
+    stringified GUI save) must round-trip to the parsed model list instead of
+    being discarded for defaults."""
+    import json
+
+    models = [
+        {"provider": "openai", "model": "gpt-4o"},
+        {"provider": "anthropic", "model": "claude-sonnet-4"},
+    ]
+    cfg = normalize_moa_config(
+        {"presets": {"p": {"reference_models": json.dumps(models)}}}
+    )
+    assert cfg["presets"]["p"]["reference_models"] == [
+        {**m, "enabled": True} for m in models
+    ]
+
+
+def test_normalize_moa_config_malformed_json_string_falls_back_to_defaults():
+    """A malformed JSON string reference_models must degrade to the default
+    reference models without raising."""
+    cfg = normalize_moa_config(
+        {"presets": {"p": {"reference_models": "[{'provider': broken"}}}
+    )
+    assert cfg["presets"]["p"]["reference_models"] == [
+        {**m, "enabled": True} for m in DEFAULT_MOA_REFERENCE_MODELS
+    ]
 
 
 def test_normalize_moa_config_preserves_slot_reasoning_effort():
@@ -125,6 +217,42 @@ def test_normalize_moa_config_preserves_slot_reasoning_effort():
     assert preset["aggregator"]["reasoning_effort"] == "xhigh"
 
 
+def test_normalize_moa_config_round_trips_reasoning_effort_and_enabled():
+    """Regression: a client that GETs the config and PUTs it straight back must
+    not strip per-slot keys. reasoning_effort AND enabled have to survive a
+    normalize → normalize round trip together (a save path that re-normalizes
+    the previously normalized payload is the exact client round-trip shape)."""
+    cfg = normalize_moa_config(
+        {
+            "presets": {
+                "p": {
+                    "reference_models": [
+                        {"provider": "openai-codex", "model": "gpt-5.5", "reasoning_effort": "high", "enabled": False},
+                        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "enabled": True},
+                    ],
+                    "aggregator": {
+                        "provider": "openrouter",
+                        "model": "anthropic/claude-opus-4.8",
+                        "reasoning_effort": "xhigh",
+                    },
+                }
+            }
+        }
+    )
+
+    round_tripped = normalize_moa_config(cfg)
+
+    refs = round_tripped["presets"]["p"]["reference_models"]
+    assert refs[0] == {
+        "provider": "openai-codex",
+        "model": "gpt-5.5",
+        "reasoning_effort": "high",
+        "enabled": False,
+    }
+    assert refs[1] == {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "enabled": True}
+    assert round_tripped["presets"]["p"]["aggregator"]["reasoning_effort"] == "xhigh"
+
+
 def test_normalize_moa_config_coerces_numeric_strings():
     """Valid numeric strings (e.g. from YAML round-trip) must coerce correctly."""
     cfg = normalize_moa_config({"max_tokens": "8192", "reference_temperature": "0.9"})
@@ -204,7 +332,7 @@ def test_resolve_moa_preset_returns_requested_model_set():
     )
 
     assert resolve_moa_preset(cfg, "review")["reference_models"] == [
-        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}
+        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "enabled": True}
     ]
 
 
@@ -254,7 +382,7 @@ def test_build_moa_turn_prompt_encodes_one_shot_default_preset():
     decoded_prompt, cfg = decode_moa_turn(prompt)
     assert decoded_prompt == "write a file then inspect it"
     assert cfg is not None
-    assert cfg["reference_models"] == DEFAULT_MOA_REFERENCE_MODELS
+    assert cfg["reference_models"] == _enabled_refs(DEFAULT_MOA_REFERENCE_MODELS)
 
 
 def test_moa_provider_rejected_as_reference_slot():
@@ -276,7 +404,7 @@ def test_moa_provider_rejected_as_reference_slot():
 
     refs = cfg["presets"]["p"]["reference_models"]
     assert {"provider": "moa", "model": "default"} not in refs
-    assert refs == [{"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}]
+    assert refs == [{"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "enabled": True}]
 
 
 def test_moa_provider_rejected_as_aggregator_slot():
@@ -451,7 +579,9 @@ def test_validate_moa_payload_agrees_with_clean_slot():
     assert validate_moa_payload(payload) == []
 
     cfg = normalize_moa_config(payload)
-    assert cfg["presets"]["p"]["reference_models"] == payload["presets"]["p"]["reference_models"]
+    # Slots survive with only the canonical enabled=True default added — no
+    # provider/model swap, no defaults substitution.
+    assert cfg["presets"]["p"]["reference_models"] == _enabled_refs(payload["presets"]["p"]["reference_models"])
     assert cfg["presets"]["p"]["aggregator"] == payload["presets"]["p"]["aggregator"]
 
 
@@ -461,3 +591,186 @@ def test_validate_moa_payload_rejects_non_dict():
     assert validate_moa_payload(None)
     assert validate_moa_payload([1, 2])
     assert validate_moa_payload({"presets": {"p": "not-a-dict"}})
+
+
+# ── Per-slot max_tokens ────────────────────────────────────────────────────
+
+
+def test_slot_max_tokens_preserved():
+    """A max_tokens field on a reference slot survives normalization."""
+    cfg = normalize_moa_config(
+        {
+            "presets": {
+                "p": {
+                    "reference_models": [
+                        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "max_tokens": 600},
+                        {"provider": "openai-codex", "model": "gpt-5.5"},
+                    ],
+                    "aggregator": {"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+                }
+            }
+        }
+    )
+    refs = cfg["presets"]["p"]["reference_models"]
+    assert refs[0] == {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "max_tokens": 600, "enabled": True}
+    assert refs[1] == {"provider": "openai-codex", "model": "gpt-5.5", "enabled": True}
+
+
+def test_slot_max_tokens_coerced_from_string():
+    """Hand-edited YAML string '600' coerces to int on a slot."""
+    cfg = normalize_moa_config(
+        {
+            "presets": {
+                "p": {
+                    "reference_models": [
+                        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "max_tokens": "600"},
+                    ],
+                }
+            }
+        }
+    )
+    refs = cfg["presets"]["p"]["reference_models"]
+    assert refs[0]["max_tokens"] == 600
+
+
+def test_slot_max_tokens_invalid_dropped():
+    """Non-positive / non-numeric slot max_tokens is dropped (slot kept)."""
+    for bad in (0, -5, "abc", "", None):
+        cfg = normalize_moa_config(
+            {
+                "presets": {
+                    "p": {
+                        "reference_models": [
+                            {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro", "max_tokens": bad},
+                        ],
+                    }
+                }
+            }
+        )
+        ref = cfg["presets"]["p"]["reference_models"][0]
+        assert "max_tokens" not in ref, bad
+        assert ref["provider"] == "openrouter"
+
+
+def test_slot_max_tokens_absent_by_default():
+    """Slots without max_tokens don't get the field — backward compat."""
+    cfg = normalize_moa_config(
+        {
+            "presets": {
+                "p": {
+                    "reference_models": [
+                        {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"},
+                    ],
+                }
+            }
+        }
+    )
+    ref = cfg["presets"]["p"]["reference_models"][0]
+    assert "max_tokens" not in ref
+
+
+# --- fanout cadence normalization (every_n) ---
+
+
+def test_fanout_defaults_to_user_turn():
+    # Default is the cheapest cadence (#67199): advisors once per user turn.
+    cfg = normalize_moa_config({})
+    assert cfg["fanout"] == "user_turn"
+
+
+def test_fanout_per_iteration_still_selectable():
+    cfg = normalize_moa_config({"fanout": "per_iteration"})
+    assert cfg["fanout"] == "per_iteration"
+
+
+def test_fanout_every_n_string_form_normalized():
+    cfg = normalize_moa_config({"fanout": "every_n:3"})
+    assert cfg["fanout"] == "every_n:3"
+    assert cfg["presets"][DEFAULT_MOA_PRESET_NAME]["fanout"] == "every_n:3"
+
+
+def test_fanout_every_n_mapping_form_normalized_to_string():
+    cfg = normalize_moa_config({"fanout": {"mode": "every_n", "n": 4}})
+    assert cfg["fanout"] == "every_n:4"
+
+
+def test_fanout_every_n_degenerate_n_falls_back():
+    # n=1 means "every iteration" — that semantically IS per_iteration;
+    # n=0 / negative / garbage is unparseable and falls to the default
+    # cadence (user_turn, the cheapest — #67199).
+    assert normalize_moa_config({"fanout": "every_n:1"})["fanout"] == "per_iteration"
+    assert normalize_moa_config({"fanout": "every_n:0"})["fanout"] == "user_turn"
+    assert normalize_moa_config({"fanout": "every_n:-2"})["fanout"] == "user_turn"
+    assert normalize_moa_config({"fanout": "every_n:x"})["fanout"] == "user_turn"
+    assert normalize_moa_config({"fanout": "every_n"})["fanout"] == "user_turn"
+    assert normalize_moa_config({"fanout": {"mode": "every_n"}})["fanout"] == "user_turn"
+
+
+def test_fanout_every_n_round_trips_through_normalize():
+    once = normalize_moa_config({"fanout": "every_n:3"})
+    twice = normalize_moa_config(once)
+    assert twice["fanout"] == "every_n:3"
+    assert twice["presets"][DEFAULT_MOA_PRESET_NAME]["fanout"] == "every_n:3"
+
+
+def test_fanout_mapping_user_turn_mode_accepted():
+    cfg = normalize_moa_config({"fanout": {"mode": "user_turn"}})
+    assert cfg["fanout"] == "user_turn"
+
+
+# --- privacy_filter normalization ---
+
+
+def test_privacy_filter_defaults_off():
+    cfg = normalize_moa_config({})
+    assert cfg["privacy_filter"] == ""
+
+
+def test_privacy_filter_modes_normalized():
+    from hermes_cli.moa_config import coerce_privacy_filter
+
+    assert coerce_privacy_filter("display") == "display"
+    assert coerce_privacy_filter("FULL") == "full"
+    assert coerce_privacy_filter(True) == "full"       # legacy boolean → issue #59959 ask
+    assert coerce_privacy_filter("true") == "full"
+    assert coerce_privacy_filter(False) == ""
+    assert coerce_privacy_filter(None) == ""
+    assert coerce_privacy_filter("bogus") == ""
+    assert coerce_privacy_filter("off") == ""
+
+
+def test_privacy_filter_round_trips_through_normalize():
+    once = normalize_moa_config({"privacy_filter": "display"})
+    assert once["privacy_filter"] == "display"
+    assert normalize_moa_config(once)["privacy_filter"] == "display"
+    full = normalize_moa_config({"privacy_filter": "full"})
+    assert normalize_moa_config(full)["privacy_filter"] == "full"
+
+
+def test_reference_failure_controls_are_normalized_per_preset_and_flattened():
+    cfg = normalize_moa_config(
+        _preset(reference_timeout="120.5", degraded_reference_policy="silent")
+    )
+
+    preset = cfg["presets"]["p"]
+    assert preset["reference_timeout"] == 120.5
+    assert preset["degraded_reference_policy"] == "silent"
+    assert cfg["reference_timeout"] == 120.5
+    assert cfg["degraded_reference_policy"] == "silent"
+
+
+@pytest.mark.parametrize("value", [None, "", 0, -1, "bad"])
+def test_reference_timeout_invalid_values_fall_back_to_default(value):
+    # None = inherit auxiliary.moa_reference.timeout (no per-preset override).
+    assert resolve_moa_preset(_preset(reference_timeout=value), "p")["reference_timeout"] is None
+
+
+def test_reference_timeout_is_uncapped_and_unknown_policy_is_loud():
+    preset = resolve_moa_preset(
+        _preset(reference_timeout=9999, degraded_reference_policy="wat"), "p"
+    )
+
+    # Explicit per-preset values are honored as-is — long-thinking advisor
+    # models legitimately run beyond any fixed cap.
+    assert preset["reference_timeout"] == 9999.0
+    assert preset["degraded_reference_policy"] == "loud"
diff --git a/tests/hermes_cli/test_moa_set_models_preserves_extra_keys.py b/tests/hermes_cli/test_moa_set_models_preserves_extra_keys.py
new file mode 100644
index 00000000000..0b245ce65e4
--- /dev/null
+++ b/tests/hermes_cli/test_moa_set_models_preserves_extra_keys.py
@@ -0,0 +1,146 @@
+"""Regression tests for ``set_moa_models`` preserving undeclared config keys.
+
+Issue #58819: ``MoaConfigPayload`` does not declare ``save_traces`` or
+``trace_dir``, so a GUI save via ``PUT /api/model/moa`` silently drops
+these hand-edited keys from ``config.yaml``.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from hermes_cli.web_server import MoaConfigPayload, MoaModelSlot, MoaPresetPayload, set_moa_models
+
+
+def _base_payload(**overrides) -> MoaConfigPayload:
+    """Return a minimal valid MoaConfigPayload."""
+    defaults = dict(
+        default_preset="default",
+        active_preset="",
+        presets={
+            "default": MoaPresetPayload(
+                reference_models=[
+                    MoaModelSlot(provider="openai-codex", model="gpt-5.5"),
+                ],
+                aggregator=MoaModelSlot(provider="openrouter", model="anthropic/claude-opus-4.8"),
+                max_tokens=4096,
+                enabled=True,
+            ),
+        },
+    )
+    defaults.update(overrides)
+    return MoaConfigPayload(**defaults)
+
+
+class TestSetMoaModelsPreservesUndeclaredKeys:
+    """save_traces / trace_dir must survive a GUI save."""
+
+    def test_save_traces_preserved(self, tmp_path):
+        """Hand-edited ``moa.save_traces: true`` must not be dropped."""
+        existing_cfg = {
+            "moa": {
+                "save_traces": True,
+                "trace_dir": "/custom/traces",
+                "default_preset": "default",
+                "presets": {
+                    "default": {
+                        "reference_models": [
+                            {"provider": "openai-codex", "model": "gpt-5.5"},
+                        ],
+                        "aggregator": {"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+                        "max_tokens": 4096,
+                        "enabled": True,
+                    },
+                },
+            },
+        }
+
+        saved_cfg = {}
+
+        def fake_load_config():
+            return dict(existing_cfg)  # shallow copy
+
+        def fake_save_config(cfg):
+            saved_cfg.update(cfg)
+
+        payload = _base_payload()
+
+        with (
+            patch("hermes_cli.web_server.load_config", side_effect=fake_load_config),
+            patch("hermes_cli.web_server.save_config", side_effect=fake_save_config),
+            patch("hermes_cli.web_server._profile_scope"),
+        ):
+            set_moa_models(payload)
+
+        moa = saved_cfg["moa"]
+        assert moa.get("save_traces") is True, (
+            "save_traces was dropped by set_moa_models"
+        )
+        assert moa.get("trace_dir") == "/custom/traces", (
+            "trace_dir was dropped by set_moa_models"
+        )
+
+    def test_trace_dir_empty_string_preserved(self, tmp_path):
+        """Even an empty-string ``trace_dir`` must survive."""
+        existing_cfg = {
+            "moa": {
+                "save_traces": True,
+                "trace_dir": "",
+                "default_preset": "default",
+                "presets": {
+                    "default": {
+                        "reference_models": [
+                            {"provider": "openai-codex", "model": "gpt-5.5"},
+                        ],
+                        "aggregator": {"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+                        "max_tokens": 4096,
+                        "enabled": True,
+                    },
+                },
+            },
+        }
+
+        saved_cfg = {}
+
+        def fake_load_config():
+            return dict(existing_cfg)
+
+        def fake_save_config(cfg):
+            saved_cfg.update(cfg)
+
+        payload = _base_payload()
+
+        with (
+            patch("hermes_cli.web_server.load_config", side_effect=fake_load_config),
+            patch("hermes_cli.web_server.save_config", side_effect=fake_save_config),
+            patch("hermes_cli.web_server._profile_scope"),
+        ):
+            set_moa_models(payload)
+
+        moa = saved_cfg["moa"]
+        assert moa.get("save_traces") is True
+        assert moa.get("trace_dir") == ""
+
+    def test_no_existing_moa_key_still_works(self, tmp_path):
+        """When ``moa`` key is absent from config, the endpoint must not crash."""
+        existing_cfg: dict = {}
+
+        saved_cfg = {}
+
+        def fake_load_config():
+            return dict(existing_cfg)
+
+        def fake_save_config(cfg):
+            saved_cfg.update(cfg)
+
+        payload = _base_payload()
+
+        with (
+            patch("hermes_cli.web_server.load_config", side_effect=fake_load_config),
+            patch("hermes_cli.web_server.save_config", side_effect=fake_save_config),
+            patch("hermes_cli.web_server._profile_scope"),
+        ):
+            result = set_moa_models(payload)
+
+        assert result["ok"] is True
+        assert "default_preset" in saved_cfg["moa"]
diff --git a/tests/hermes_cli/test_model_switch_custom_providers.py b/tests/hermes_cli/test_model_switch_custom_providers.py
index 2f9784ee440..5b1529a1002 100644
--- a/tests/hermes_cli/test_model_switch_custom_providers.py
+++ b/tests/hermes_cli/test_model_switch_custom_providers.py
@@ -283,6 +283,48 @@ def test_switch_model_accepts_explicit_named_custom_provider(monkeypatch):
     assert result.api_key == "no-key-required"
 
 
+def test_picker_selection_resolves_named_custom_provider_model_id(monkeypatch):
+    """Picker prefixes must not leak into a named custom provider API model id."""
+    monkeypatch.setattr(
+        "hermes_cli.runtime_provider.resolve_runtime_provider",
+        lambda **kwargs: {
+            "api_key": "test-key",
+            "base_url": "https://token.sensenova.cn/v1",
+            "api_mode": "chat_completions",
+        },
+    )
+    monkeypatch.setattr(
+        "hermes_cli.models.validate_requested_model",
+        lambda *a, **k: _MOCK_VALIDATION,
+    )
+    monkeypatch.setattr("hermes_cli.model_switch.get_model_info", lambda *a, **k: None)
+    monkeypatch.setattr(
+        "hermes_cli.model_switch.get_model_capabilities",
+        lambda *a, **k: None,
+    )
+
+    result = switch_model(
+        raw_input="sensenova/deepseek-v4-flash",
+        current_provider="openai-codex",
+        current_model="gpt-5.4",
+        explicit_provider="custom:sensenova",
+        user_providers={},
+        custom_providers=[
+            {
+                "name": "sensenova",
+                "base_url": "https://token.sensenova.cn/v1",
+                "models": [
+                    {"id": "deepseek-v4-flash", "name": "deepseek-v4-flash"}
+                ],
+            }
+        ],
+    )
+
+    assert result.success is True
+    assert result.target_provider == "custom:sensenova"
+    assert result.new_model == "deepseek-v4-flash"
+
+
 def test_list_groups_same_name_custom_providers_into_one_row(monkeypatch):
     """Multiple custom_providers entries sharing a name should produce one row
     with all models collected, not N duplicate rows."""
diff --git a/tests/hermes_cli/test_plugins.py b/tests/hermes_cli/test_plugins.py
index b540f70bd10..2a6de58ac70 100644
--- a/tests/hermes_cli/test_plugins.py
+++ b/tests/hermes_cli/test_plugins.py
@@ -1570,7 +1570,14 @@ class TestPluginToolVisibility:
     """Plugin-registered tools appear in get_tool_definitions()."""
 
     def test_plugin_tools_in_definitions(self, tmp_path, monkeypatch):
-        """Plugin tools are included when their toolset is in enabled_toolsets."""
+        """Plugin tools are reachable when their toolset is in enabled_toolsets.
+
+        Under tiered disclosure (any MCP/plugin tool defers behind the
+        tool_search bridge), a plugin tool no longer appears as a direct
+        schema — it is deferred and surfaced via the bridge's catalog
+        listing. 'Reachable' therefore means: present directly OR listed
+        in the tool_search bridge description.
+        """
         import hermes_cli.plugins as plugins_mod
 
         plugins_dir = tmp_path / "hermes_test" / "plugins"
@@ -1598,20 +1605,26 @@ class TestPluginToolVisibility:
 
         from model_tools import get_tool_definitions
 
-        # Plugin tools are included when their toolset is explicitly enabled
+        def _reachable(tools):
+            names = [t["function"]["name"] for t in tools]
+            if "vis_tool" in names:
+                return True  # tool_search inactive → direct schema
+            search = next((t for t in tools
+                           if t["function"]["name"] == "tool_search"), None)
+            return bool(search and "vis_tool" in search["function"]["description"])
+
+        # Reachable when its toolset is explicitly enabled
         tools = get_tool_definitions(enabled_toolsets=["terminal", "plugin_vis_plugin"], quiet_mode=True)
-        tool_names = [t["function"]["name"] for t in tools]
-        assert "vis_tool" in tool_names
+        assert _reachable(tools)
 
-        # Plugin tools are excluded when only other toolsets are enabled
+        # Excluded entirely when only other toolsets are enabled — not
+        # direct, not in the deferred listing.
         tools2 = get_tool_definitions(enabled_toolsets=["terminal"], quiet_mode=True)
-        tool_names2 = [t["function"]["name"] for t in tools2]
-        assert "vis_tool" not in tool_names2
+        assert not _reachable(tools2)
 
-        # Plugin tools are included when no toolset filter is active (all enabled)
+        # Reachable when no toolset filter is active (all enabled)
         tools3 = get_tool_definitions(quiet_mode=True)
-        tool_names3 = [t["function"]["name"] for t in tools3]
-        assert "vis_tool" in tool_names3
+        assert _reachable(tools3)
 
 
 # ── TestPluginManagerList ──────────────────────────────────────────────────
diff --git a/tests/hermes_cli/test_profile_install_env_encoding.py b/tests/hermes_cli/test_profile_install_env_encoding.py
new file mode 100644
index 00000000000..f6e746c86f1
--- /dev/null
+++ b/tests/hermes_cli/test_profile_install_env_encoding.py
@@ -0,0 +1,72 @@
+"""Regression: the distribution-install preview must read .env as UTF-8.
+
+`_render_distribution_plan` inspects the target profile's `.env` to decide
+whether a required env var is already set, so it doesn't nag the user. It
+used `Path.read_text()` with no encoding, which:
+
+  1. defaults to the system locale (cp1251/GBK on Windows) and raises
+     `UnicodeDecodeError` on any non-ASCII byte — and the surrounding
+     `except OSError` does NOT catch that (it's a `ValueError`), so a
+     mis-encoded .env aborts the whole install preview; and
+  2. even on a UTF-8 locale, a Notepad-added BOM prefixes the first key,
+     so the very first env var is mis-detected as "needs setting".
+
+The fix reads `utf-8-sig` and also catches `UnicodeDecodeError`.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from hermes_cli.main import _render_distribution_plan
+
+
+def _make_plan(target_dir, env_requires):
+    manifest = SimpleNamespace(
+        name="demo",
+        version="1.0.0",
+        description="",
+        author="",
+        hermes_requires="",
+        env_requires=env_requires,
+    )
+    return SimpleNamespace(
+        manifest=manifest,
+        provenance="local",
+        target_dir=target_dir,
+        existing=False,
+        has_cron=False,
+    )
+
+
+def test_bom_prefixed_env_first_key_is_detected_as_set(tmp_path, monkeypatch, capsys):
+    """A required key on the first line of a BOM-prefixed .env reads as set."""
+    monkeypatch.delenv("FOO_TOKEN", raising=False)
+    profile = tmp_path / "profile"
+    profile.mkdir()
+    # utf-8-sig write == UTF-8 with a leading BOM, exactly what Notepad emits.
+    (profile / ".env").write_text("FOO_TOKEN=abc\nBAR=1\n", encoding="utf-8-sig")
+
+    plan = _make_plan(profile, [SimpleNamespace(name="FOO_TOKEN", required=True, description="")])
+    _render_distribution_plan(plan)
+
+    out = capsys.readouterr().out
+    foo_line = next(ln for ln in out.splitlines() if "FOO_TOKEN" in ln)
+    assert "✓ set" in foo_line, f"BOM must not hide the first key: {foo_line!r}"
+
+
+def test_non_utf8_env_does_not_abort_the_preview(tmp_path, monkeypatch, capsys):
+    """A .env with invalid UTF-8 bytes must not crash the install preview."""
+    monkeypatch.delenv("FOO_TOKEN", raising=False)
+    profile = tmp_path / "profile"
+    profile.mkdir()
+    # \xff is an invalid UTF-8 start byte -> UnicodeDecodeError on read.
+    (profile / ".env").write_bytes(b"FOO_TOKEN=\xff\xfe bad\n")
+
+    plan = _make_plan(profile, [SimpleNamespace(name="FOO_TOKEN", required=True, description="")])
+
+    # Must return normally (old `except OSError` let UnicodeDecodeError escape).
+    _render_distribution_plan(plan)
+
+    out = capsys.readouterr().out
+    assert any("FOO_TOKEN" in ln for ln in out.splitlines())
diff --git a/tests/hermes_cli/test_session_recovery.py b/tests/hermes_cli/test_session_recovery.py
new file mode 100644
index 00000000000..b477395a56e
--- /dev/null
+++ b/tests/hermes_cli/test_session_recovery.py
@@ -0,0 +1,1079 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sqlite3
+import subprocess
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import hermes_state
+from hermes_state import FTS_STORAGE_VERSION, SCHEMA_VERSION, SessionDB
+from hermes_cli import session_recovery
+from hermes_cli.session_recovery import (
+    SessionRecoverySafetyError,
+    SessionRecoverySourceError,
+    inspect_session_database,
+    recover_session_database,
+)
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(64 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _make_source(path: Path) -> dict[str, int]:
+    db = SessionDB(db_path=path)
+    try:
+        for session_number in range(3):
+            session_id = f"recovery-session-{session_number}"
+            db.create_session(
+                session_id,
+                "cli",
+                cwd=f"/tmp/recovery-{session_number}",
+            )
+            db.set_session_title(session_id, f"Recovery {session_number}")
+            for message_number in range(7):
+                db.append_message(
+                    session_id,
+                    "user" if message_number % 2 == 0 else "assistant",
+                    f"recoverable payload {session_number} {message_number}",
+                )
+
+        db.set_meta("goal:recovery-session-0", '{"status":"active"}')
+        db.apply_telegram_topic_migration()
+        db._conn.execute(
+            """
+            INSERT INTO telegram_dm_topic_mode (
+                chat_id, user_id, enabled, activated_at, updated_at
+            ) VALUES (?, ?, 1, ?, ?)
+            """,
+            ("chat-1", "user-1", 1.0, 2.0),
+        )
+        db._conn.execute(
+            """
+            INSERT INTO telegram_dm_topic_bindings (
+                chat_id, thread_id, user_id, session_key, session_id,
+                managed_mode, linked_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                "chat-1",
+                "thread-1",
+                "user-1",
+                "telegram:user-1:chat-1",
+                "recovery-session-0",
+                "auto",
+                1.0,
+                2.0,
+            ),
+        )
+        db._conn.execute(
+            """
+            INSERT INTO gateway_routing (
+                scope, session_key, entry_json, updated_at
+            ) VALUES (?, ?, ?, ?)
+            """,
+            ("telegram", "telegram:user-1:chat-1", "{}", 2.0),
+        )
+        db._conn.execute(
+            """
+            INSERT INTO async_delegations (
+                delegation_id, origin_session, state, dispatched_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?)
+            """,
+            ("delegation-1", "recovery-session-0", "completed", 1.0, 2.0),
+        )
+        # These are derived transition markers and must not reach the new DB.
+        db.set_meta("fts_rebuild_high_water", "999")
+        db.set_meta("fts_rebuild_progress", "500")
+    finally:
+        db.close()
+    return {"sessions": 3, "messages": 21}
+
+
+def _orphan_fts_schema(path: Path) -> None:
+    conn = sqlite3.connect(str(path), isolation_level=None)
+    try:
+        conn.execute("PRAGMA writable_schema=ON")
+        conn.execute(
+            "DELETE FROM sqlite_master "
+            "WHERE type='table' "
+            "AND name IN ('messages_fts', 'messages_fts_trigram')"
+        )
+        conn.execute("PRAGMA writable_schema=OFF")
+    finally:
+        conn.close()
+
+
+def _make_page_spanning_source(
+    path: Path,
+    message_count: int = 320,
+) -> tuple[int, int | None]:
+    db = SessionDB(db_path=path)
+    try:
+        db.create_session(
+            "partial-recovery-session",
+            "cli",
+            cwd="/tmp/partial-recovery",
+        )
+        for message_number in range(message_count):
+            db.append_message(
+                "partial-recovery-session",
+                "user" if message_number % 2 == 0 else "assistant",
+                (
+                    f"partial recovery payload {message_number:04d} "
+                    + chr(65 + message_number % 26) * 1_500
+                ),
+            )
+    finally:
+        db.close()
+
+    conn = sqlite3.connect(str(path), isolation_level=None)
+    try:
+        conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        conn.execute("PRAGMA journal_mode=DELETE")
+        conn.execute("VACUUM")
+        plan = " ".join(
+            str(row[3])
+            for row in conn.execute(
+                "EXPLAIN QUERY PLAN SELECT COUNT(*) FROM messages"
+            ).fetchall()
+        )
+        count_index = next(
+            (
+                str(row[0])
+                for row in conn.execute(
+                    "SELECT name FROM sqlite_master "
+                    "WHERE type = 'index' AND tbl_name = 'messages'"
+                ).fetchall()
+                if plan.endswith(str(row[0]))
+            ),
+            None,
+        )
+        names = ["messages"]
+        if count_index is not None:
+            names.append(count_index)
+        placeholders = ", ".join("?" for _ in names)
+        roots = {
+            str(row[0]): int(row[1])
+            for row in conn.execute(
+                "SELECT name, rootpage FROM sqlite_master "
+                f"WHERE name IN ({placeholders})",
+                tuple(names),
+            ).fetchall()
+        }
+        return roots["messages"], (
+            roots[count_index] if count_index is not None else None
+        )
+    finally:
+        conn.close()
+
+
+def _make_many_sessions_source(
+    path: Path,
+    session_count: int = 180,
+) -> int:
+    db = SessionDB(db_path=path)
+    try:
+        for session_number in range(session_count):
+            session_id = f"partial-session-{session_number:04d}"
+            db.create_session(
+                session_id,
+                "cli",
+                cwd=f"/tmp/partial-session-{session_number:04d}",
+                system_prompt=(
+                    f"session payload {session_number:04d} "
+                    + chr(65 + session_number % 26) * 1_500
+                ),
+            )
+            db.append_message(session_id, "user", f"message {session_number}")
+    finally:
+        db.close()
+
+    conn = sqlite3.connect(str(path), isolation_level=None)
+    try:
+        conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        conn.execute("PRAGMA journal_mode=DELETE")
+        conn.execute("VACUUM")
+        row = conn.execute(
+            "SELECT rootpage FROM sqlite_master "
+            "WHERE type = 'table' AND name = 'sessions'"
+        ).fetchone()
+        assert row is not None
+        return int(row[0])
+    finally:
+        conn.close()
+
+
+def _btree_leaf_pages(path: Path, root_page: int) -> tuple[int, list[int]]:
+    data = path.read_bytes()
+    page_size = int.from_bytes(data[16:18], "big")
+    if page_size == 1:
+        page_size = 65_536
+    leaf_pages: list[int] = []
+    visited: set[int] = set()
+
+    def visit(page_number: int) -> None:
+        if page_number in visited:
+            return
+        visited.add(page_number)
+        page_start = (page_number - 1) * page_size
+        header_offset = page_start + (100 if page_number == 1 else 0)
+        page_type = data[header_offset]
+        cell_count = int.from_bytes(
+            data[header_offset + 3 : header_offset + 5],
+            "big",
+        )
+        if page_type in {0x0A, 0x0D}:
+            leaf_pages.append(page_number)
+            return
+        assert page_type in {0x02, 0x05}, (
+            f"unexpected table b-tree page type {page_type:#x} "
+            f"on page {page_number}"
+        )
+
+        pointer_array = header_offset + 12
+        for cell_number in range(cell_count):
+            pointer_offset = pointer_array + cell_number * 2
+            cell_offset = int.from_bytes(
+                data[pointer_offset : pointer_offset + 2],
+                "big",
+            )
+            child_offset = page_start + cell_offset
+            child_page = int.from_bytes(
+                data[child_offset : child_offset + 4],
+                "big",
+            )
+            visit(child_page)
+        rightmost_page = int.from_bytes(
+            data[header_offset + 8 : header_offset + 12],
+            "big",
+        )
+        visit(rightmost_page)
+
+    visit(root_page)
+    return page_size, leaf_pages
+
+
+def _corrupt_middle_table_leaf(
+    path: Path,
+    root_page: int,
+    *,
+    require_interior: bool = True,
+) -> int:
+    page_size, leaf_pages = _btree_leaf_pages(path, root_page)
+    assert leaf_pages
+    if require_interior:
+        assert len(leaf_pages) >= 3
+    leaf_page = leaf_pages[len(leaf_pages) // 2]
+    page_start = (leaf_page - 1) * page_size
+    header_offset = page_start + (100 if leaf_page == 1 else 0)
+
+    data = bytearray(path.read_bytes())
+    assert data[header_offset] in {0x0A, 0x0D}
+    # An impossible cell count damages this one middle leaf while preserving
+    # the table root and leaves on both sides. This is a physical SQLite page
+    # failure, not a mocked cursor exception.
+    data[header_offset + 3 : header_offset + 5] = b"\xff\xff"
+    path.write_bytes(data)
+    return leaf_page
+
+
+def test_snapshot_blocks_connections_opened_during_the_copy(
+    tmp_path: Path,
+) -> None:
+    """A connection must not be able to open while raw copy descriptors exist.
+
+    Checking has_live_connection() and then copying leaves a window: a
+    connection can open between the two, and the copy's close() cancels its
+    POSIX advisory locks. The guard must hold the lifecycle lock across the
+    whole bundle copy.
+
+    Runs the copy in a worker thread and pauses it inside the patched copy, so
+    the assertion is about lock ordering rather than which thread the
+    scheduler happens to resume first: while the copy is parked, a
+    connect_tracked() attempt must NOT complete; once released, it must.
+    """
+    import threading
+
+    from hermes_cli import session_recovery as recovery_module
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
+    source = tmp_path / "racy-state.db"
+    snapshot_dir = tmp_path / "snapshot"
+    snapshot_dir.mkdir()
+    _make_source(source)
+
+    inside_copy = threading.Event()
+    release_copy = threading.Event()
+    connect_attempted = threading.Event()
+    connection_opened = threading.Event()
+    errors: list[str] = []
+    real_copy2 = recovery_module.shutil.copy2
+
+    def slow_copy2(src, dst, *args, **kwargs):
+        result = real_copy2(src, dst, *args, **kwargs)
+        if str(src).endswith("racy-state.db"):
+            inside_copy.set()
+            release_copy.wait(30)
+        return result
+
+    def do_copy():
+        try:
+            recovery_module._copy_source_bundle(source, snapshot_dir)
+        except Exception as exc:  # pragma: no cover - surfaced via errors
+            errors.append(f"copy failed: {exc}")
+
+    def do_connect():
+        # Signal immediately before the blocking call so a timed "still
+        # blocked" assertion cannot pass merely because this thread had not
+        # been scheduled yet.
+        connect_attempted.set()
+        try:
+            conn = connect_tracked(source, isolation_level=None, timeout=30.0)
+            connection_opened.set()
+            conn.close()
+        except Exception as exc:  # pragma: no cover - surfaced via errors
+            errors.append(f"connect failed: {exc}")
+
+    recovery_module.shutil.copy2 = slow_copy2
+    copier = threading.Thread(target=do_copy, daemon=True)
+    connector = threading.Thread(target=do_connect, daemon=True)
+    try:
+        copier.start()
+        assert inside_copy.wait(30), "copy never reached the patched operation"
+
+        connector.start()
+        assert connect_attempted.wait(30), "connector thread never started"
+        # The connector is at the lock. While the copy holds it, the
+        # connection must not open.
+        assert not connection_opened.wait(1.0), (
+            "connect_tracked() completed while raw copy descriptors were open "
+            "— the guard is not holding the lifecycle lock across the copy"
+        )
+
+        release_copy.set()
+        # Once the copy finishes and releases the lock, it must open promptly.
+        assert connection_opened.wait(30), (
+            "connect_tracked() never completed after the copy released the lock"
+        )
+    finally:
+        release_copy.set()
+        recovery_module.shutil.copy2 = real_copy2
+        copier.join(30)
+        connector.join(30)
+
+    assert not errors, errors[0]
+
+
+def test_partial_recovery_keeps_messages_when_sessions_are_unsalvageable(
+    tmp_path: Path,
+) -> None:
+    """Salvaged messages must survive even when NO session row is recoverable.
+
+    Reported July 2026: a user's recovery copied 20,817 of 20,824 messages,
+    then orphan cleanup deleted every one of them because the sessions b-tree
+    was damaged worse than the messages b-tree. The output had 0 sessions and
+    0 messages — the salvage worked and then threw the result away, which is
+    the exact opposite of what --allow-partial is for.
+
+    Messages must be retained under reconstructed placeholder sessions, and
+    the placeholder-ness must be reported as loss rather than passed off as a
+    clean recovery.
+    """
+    source = tmp_path / "sessions-destroyed.db"
+    output = tmp_path / "sessions-destroyed-recovered.db"
+
+    messages_per_session = {
+        "doomed-session-a": 40,
+        "doomed-session-b": 35,
+        "doomed-session-c": 45,
+    }
+    db = SessionDB(db_path=source)
+    try:
+        for session_id, message_count in messages_per_session.items():
+            db.create_session(session_id, "cli", cwd=f"/tmp/{session_id}")
+            for index in range(message_count):
+                db.append_message(
+                    session_id,
+                    "user",
+                    f"irreplaceable {session_id} {index}",
+                )
+    finally:
+        db.close()
+
+    # sessions unrecoverable, messages intact — the reported shape.
+    conn = sqlite3.connect(str(source), isolation_level=None)
+    try:
+        conn.execute("DELETE FROM sessions")
+    finally:
+        conn.close()
+
+    report = recover_session_database(
+        source,
+        output,
+        work_dir=tmp_path,
+        chunk_size=16,
+        allow_partial=True,
+    )
+
+    cleanup = report["orphan_cleanup"]
+    assert cleanup["messages_removed"] == 0, (
+        "salvaged messages were deleted for lack of a session row"
+    )
+    assert cleanup["sessions_reconstructed"] == len(messages_per_session)
+    assert cleanup["messages_retained"] == 120
+
+    with sqlite3.connect(str(output)) as verify:
+        recovered_sessions = verify.execute(
+            "SELECT id, source, title, message_count FROM sessions ORDER BY id"
+        ).fetchall()
+        messages = verify.execute("SELECT COUNT(*) FROM messages").fetchone()[0]
+    assert messages == 120, f"expected all 120 messages retained, got {messages}"
+    assert len(recovered_sessions) == len(messages_per_session)
+
+    # Fabricated sessions must be identifiable and carry collision-safe titles.
+    assert {row[0] for row in recovered_sessions} == set(messages_per_session)
+    assert {row[1] for row in recovered_sessions} == {"recovered"}
+    recovered_titles = [str(row[2]) for row in recovered_sessions]
+    assert all(title.startswith("[recovered ") for title in recovered_titles)
+    assert len(set(recovered_titles)) == len(recovered_titles)
+    assert {
+        str(row[0]): int(row[3]) for row in recovered_sessions
+    } == messages_per_session
+
+    # Retaining the data is still a lossy outcome and must say so.
+    assert report["verification"]["loss_detected"] is True
+    assert report["partial"] is True
+    assert report["complete"] is False
+    assert any(
+        "reconstructed as placeholders" in warning
+        for warning in report["verification"]["warnings"]
+    ), report["verification"]["warnings"]
+
+    # The output must remain structurally sound.
+    assert report["verification"]["integrity_check"] == ["ok"]
+    assert report["verification"]["foreign_key_check"] == []
+    assert report["verified"] is True
+    assert report["installed"] is False
+
+
+def test_partial_recovery_reports_damaged_state_meta_as_loss(
+    tmp_path: Path,
+) -> None:
+    """A damaged optional state_meta must degrade AND be reported as loss.
+
+    state_meta can lose ``key`` while ``value`` stays readable. Indexing
+    ``key`` unconditionally raised ValueError and killed the whole partial
+    recovery. Reporting it as ``missing`` instead is just as wrong in the
+    other direction: verification only escalates ``failed``/``partial``, so
+    the run would claim ``complete=True`` after silently dropping real
+    metadata. A present-but-unusable table must be ``failed``, surface a
+    warning, and mark the output partial — while sessions and messages still
+    recover.
+    """
+    source = tmp_path / "meta-damaged.db"
+    output = tmp_path / "meta-recovered.db"
+    expected = _make_source(source)
+
+    conn = sqlite3.connect(str(source), isolation_level=None)
+    try:
+        conn.execute("DROP TABLE IF EXISTS state_meta")
+        conn.execute("CREATE TABLE state_meta(value TEXT)")
+        conn.execute("INSERT INTO state_meta(value) VALUES ('orphaned')")
+    finally:
+        conn.close()
+
+    report = recover_session_database(
+        source,
+        output,
+        work_dir=tmp_path,
+        chunk_size=4,
+        allow_partial=True,
+    )
+
+    # The table existed and could not be salvaged: that is loss, not absence.
+    assert report["copy"]["state_meta"]["status"] == "failed"
+    assert any(
+        "state_meta" in warning for warning in report["verification"]["warnings"]
+    ), report["verification"]["warnings"]
+    assert report["verification"]["loss_detected"] is True
+    assert report["partial"] is True
+    assert report["complete"] is False
+
+    # Structurally sound, so still installable-with-review.
+    assert report["verified"] is True
+    assert report["verification"]["healthy"] is True
+    assert report["installed"] is False
+
+    # The canonical data still recovers.
+    assert report["verification"]["table_counts"]["sessions"] == expected["sessions"]
+    assert report["verification"]["table_counts"]["messages"] == expected["messages"]
+    assert report["verification"]["integrity_check"] == ["ok"]
+
+
+def test_partial_recovery_treats_absent_state_meta_as_no_loss(
+    tmp_path: Path,
+) -> None:
+    """A genuinely absent state_meta is not data loss and must not warn."""
+    source = tmp_path / "meta-absent.db"
+    output = tmp_path / "meta-absent-recovered.db"
+    _make_source(source)
+
+    conn = sqlite3.connect(str(source), isolation_level=None)
+    try:
+        conn.execute("DROP TABLE IF EXISTS state_meta")
+    finally:
+        conn.close()
+
+    report = recover_session_database(
+        source,
+        output,
+        work_dir=tmp_path,
+        chunk_size=4,
+        allow_partial=True,
+    )
+
+    assert report["copy"]["state_meta"]["status"] == "missing"
+    assert not any(
+        "state_meta" in warning for warning in report["verification"]["warnings"]
+    ), report["verification"]["warnings"]
+    assert report["verification"]["integrity_check"] == ["ok"]
+
+
+def test_state_meta_salvage_distinguishes_absent_from_unusable(
+    tmp_path: Path,
+) -> None:
+    """Unit-level: the salvage helper must not conflate absent with damaged.
+
+    ``recover_session_database`` short-circuits on the inspection result when
+    state_meta is entirely absent, so the helper's own absent-branch is never
+    reached through the public path — a regression there would be invisible
+    end-to-end. Exercise it directly so both statuses are pinned:
+    absent -> ``missing`` (no loss), present-but-unusable -> ``failed``
+    (loss, which verification escalates into a warning).
+    """
+    destination_path = tmp_path / "dest.db"
+    destination = sqlite3.connect(str(destination_path), isolation_level=None)
+    destination.execute("CREATE TABLE state_meta(key TEXT PRIMARY KEY, value TEXT)")
+
+    absent_path = tmp_path / "absent.db"
+    absent = sqlite3.connect(str(absent_path), isolation_level=None)
+    absent.execute("CREATE TABLE unrelated(x)")
+
+    damaged_path = tmp_path / "damaged.db"
+    damaged = sqlite3.connect(str(damaged_path), isolation_level=None)
+    damaged.execute("CREATE TABLE state_meta(value TEXT)")
+    damaged.execute("INSERT INTO state_meta(value) VALUES ('orphaned')")
+
+    try:
+        absent_result = session_recovery._copy_state_meta_salvage(
+            absent, destination, chunk_size=4, progress_cb=None, source_rows=0
+        )
+        assert absent_result["status"] == "missing", (
+            "a table that was never there is not data loss"
+        )
+
+        damaged_result = session_recovery._copy_state_meta_salvage(
+            damaged, destination, chunk_size=4, progress_cb=None, source_rows=1
+        )
+        assert damaged_result["status"] == "failed", (
+            "a present-but-unusable table is data loss; reporting 'missing' "
+            "would let verification claim complete=True after dropping it"
+        )
+    finally:
+        destination.close()
+        absent.close()
+        damaged.close()
+
+
+def test_recovery_refuses_to_snapshot_a_live_database(tmp_path: Path) -> None:
+    """Snapshotting must refuse while a connection to the source is live.
+
+    Copying a database file is an open()/close() on it, and close() cancels
+    every POSIX advisory lock the process holds on that file (see
+    hermes_cli.sqlite_safe_read). Recovery normally runs against an offline
+    file, but the check must exist so this path cannot drift away from
+    hermes_state._backup_db_file, which refuses the same situation.
+    """
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
+    source = tmp_path / "live-state.db"
+    output = tmp_path / "recovered.db"
+    _make_source(source)
+
+    live = connect_tracked(source, isolation_level=None)
+    try:
+        with pytest.raises(SessionRecoverySafetyError, match="still open"):
+            recover_session_database(source, output, work_dir=tmp_path)
+    finally:
+        live.close()
+
+    assert not output.exists()
+
+    # With the connection closed the same call proceeds normally.
+    report = recover_session_database(source, output, work_dir=tmp_path)
+    assert report["verification"]["integrity_check"] == ["ok"]
+
+
+def test_recovery_rebuilds_canonical_data_without_opening_source(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    source = tmp_path / "damaged-state.db"
+    output = tmp_path / "recovered-state.db"
+    expected = _make_source(source)
+    _orphan_fts_schema(source)
+
+    source_hash = _sha256(source)
+    source_stat = source.stat()
+
+    # Exercise the vulnerable-runtime fallback: a fresh recovered DB must be
+    # born in DELETE mode instead of enabling WAL (#70055, retained).
+    monkeypatch.setattr(
+        hermes_state,
+        "is_sqlite_wal_reset_vulnerable",
+        lambda version_info=None: True,
+    )
+
+    report = recover_session_database(
+        source,
+        output,
+        work_dir=tmp_path,
+        chunk_size=4,
+    )
+
+    assert report["complete"] is True
+    assert report["installed"] is False
+    assert report["source_unchanged"] is True
+    assert report["verification"]["journal_mode"] == "delete"
+    assert report["verification"]["integrity_check"] == ["ok"]
+    assert report["verification"]["foreign_key_check"] == []
+    assert report["verification"]["schema_version"] == SCHEMA_VERSION
+    assert report["verification"]["pending_fts_keys"] == []
+    assert report["verification"]["table_counts"]["sessions"] == expected["sessions"]
+    assert report["verification"]["table_counts"]["messages"] == expected["messages"]
+    assert report["copy"]["messages"]["copied_rows"] == expected["messages"]
+    disk_space = report["disk_space"]
+    assert disk_space["estimated_output_bytes"] == disk_space["source_bundle_bytes"]
+    assert disk_space["work_dir_required_bytes"] == (
+        disk_space["source_bundle_bytes"]
+        + disk_space["estimated_output_bytes"]
+        + disk_space["headroom_bytes"]
+    )
+
+    assert _sha256(source) == source_hash
+    assert source.stat().st_size == source_stat.st_size
+    assert source.stat().st_mtime_ns == source_stat.st_mtime_ns
+
+    conn = sqlite3.connect(str(output))
+    try:
+        assert (
+            conn.execute(
+                "SELECT value FROM state_meta WHERE key = ?",
+                ("goal:recovery-session-0",),
+            ).fetchone()[0]
+            == '{"status":"active"}'
+        )
+        assert conn.execute(
+            "SELECT value FROM state_meta WHERE key = 'fts_storage_version'"
+        ).fetchone()[0] == str(FTS_STORAGE_VERSION)
+        assert (
+            conn.execute(
+                "SELECT COUNT(*) FROM state_meta "
+                "WHERE key IN ('fts_rebuild_high_water', 'fts_rebuild_progress')"
+            ).fetchone()[0]
+            == 0
+        )
+        assert (
+            conn.execute("SELECT COUNT(*) FROM telegram_dm_topic_mode").fetchone()[0]
+            == 1
+        )
+        assert (
+            conn.execute("SELECT COUNT(*) FROM telegram_dm_topic_bindings").fetchone()[
+                0
+            ]
+            == 1
+        )
+        assert conn.execute("SELECT COUNT(*) FROM gateway_routing").fetchone()[0] == 1
+        assert conn.execute("SELECT COUNT(*) FROM async_delegations").fetchone()[0] == 1
+        assert (
+            conn.execute(
+                "SELECT COUNT(*) FROM messages_fts "
+                "WHERE messages_fts MATCH 'recoverable'"
+            ).fetchone()[0]
+            == expected["messages"]
+        )
+        assert (
+            conn.execute(
+                "SELECT COUNT(*) FROM messages_fts_trigram "
+                "WHERE messages_fts_trigram MATCH 'cover'"
+            ).fetchone()[0]
+            == expected["messages"]
+        )
+    finally:
+        conn.close()
+
+    reopened = SessionDB(db_path=output)
+    try:
+        message_id = reopened.append_message(
+            "recovery-session-0",
+            "user",
+            "post recovery write",
+        )
+        assert message_id > expected["messages"]
+        assert reopened.search_messages("post recovery write")
+    finally:
+        reopened.close()
+
+
+def test_recovery_refuses_overwrite_and_source_alias(tmp_path: Path) -> None:
+    source = tmp_path / "state.db"
+    _make_source(source)
+
+    output = tmp_path / "existing.db"
+    output.write_bytes(b"keep me")
+    with pytest.raises(SessionRecoverySafetyError, match="overwrite"):
+        recover_session_database(source, output, work_dir=tmp_path)
+    assert output.read_bytes() == b"keep me"
+
+    with pytest.raises(SessionRecoverySafetyError, match="must not be the source"):
+        recover_session_database(source, source, work_dir=tmp_path)
+
+
+def test_recovery_refuses_before_writing_when_disk_space_is_short(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    source = tmp_path / "state.db"
+    output = tmp_path / "recovered.db"
+    _make_source(source)
+    monkeypatch.setattr(
+        session_recovery.shutil,
+        "disk_usage",
+        lambda _path: SimpleNamespace(total=100, used=99, free=1),
+    )
+
+    with pytest.raises(SessionRecoverySafetyError, match="Not enough free disk space"):
+        recover_session_database(source, output, work_dir=tmp_path)
+    assert not output.exists()
+    assert not list(tmp_path.glob("hermes-session-recovery-*"))
+
+
+def test_recovery_requires_readable_sessions_and_messages(tmp_path: Path) -> None:
+    source = tmp_path / "missing-messages.db"
+    output = tmp_path / "recovered.db"
+    conn = sqlite3.connect(str(source))
+    try:
+        conn.execute(
+            "CREATE TABLE sessions "
+            "(id TEXT PRIMARY KEY, source TEXT NOT NULL, started_at REAL NOT NULL)"
+        )
+        conn.execute(
+            "INSERT INTO sessions(id, source, started_at) VALUES ('s1', 'cli', 1)"
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+    inspection = inspect_session_database(source, work_dir=tmp_path)
+    assert inspection["recoverable"] is False
+    with pytest.raises(SessionRecoverySourceError, match="messages"):
+        recover_session_database(source, output, work_dir=tmp_path)
+    assert not output.exists()
+
+
+def test_allow_partial_still_reports_a_complete_healthy_copy(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "healthy-state.db"
+    output = tmp_path / "healthy-recovered.db"
+    expected = _make_source(source)
+
+    report = recover_session_database(
+        source,
+        output,
+        work_dir=tmp_path,
+        chunk_size=4,
+        allow_partial=True,
+    )
+
+    assert report["verified"] is True
+    assert report["complete"] is True
+    assert report["partial"] is False
+    assert report["verification"]["warnings"] == []
+    assert report["verification"]["table_counts"]["sessions"] == expected["sessions"]
+    assert report["verification"]["table_counts"]["messages"] == expected["messages"]
+    assert report["orphan_cleanup"]["total_removed_or_relinked"] == 0
+
+
+def test_cli_allow_partial_salvages_rows_across_a_corrupt_leaf(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "corrupt-state.db"
+    rejected_output = tmp_path / "rejected.db"
+    output = tmp_path / "partial-recovered.db"
+    message_count = 320
+    messages_root, count_index_root = _make_page_spanning_source(
+        source,
+        message_count,
+    )
+    corrupt_page = _corrupt_middle_table_leaf(source, messages_root)
+    if count_index_root is not None:
+        _corrupt_middle_table_leaf(
+            source,
+            count_index_root,
+            require_interior=False,
+        )
+    source_hash = _sha256(source)
+
+    inspection = inspect_session_database(source, work_dir=tmp_path)
+    assert inspection["recoverable"] is False
+    assert inspection["tables"]["messages"]["rows"] is None
+    with pytest.raises(SessionRecoverySourceError, match="messages"):
+        recover_session_database(
+            source,
+            rejected_output,
+            work_dir=tmp_path,
+        )
+    assert not rejected_output.exists()
+
+    env = os.environ.copy()
+    env["HERMES_HOME"] = str(tmp_path / "isolated-hermes-home")
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "hermes_cli.main",
+            "sessions",
+            "recover",
+            "--source",
+            str(source),
+            "--output",
+            str(output),
+            "--work-dir",
+            str(tmp_path),
+            "--chunk-size",
+            "8",
+            "--allow-partial",
+        ],
+        cwd=Path(__file__).resolve().parents[2],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=60,
+        check=False,
+    )
+
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert "Partial recovery output verified" in result.stdout
+    assert "active session database was not changed" in result.stdout
+    assert _sha256(source) == source_hash
+
+    report_path = output.with_name(output.name + ".recovery.json")
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    assert report["allow_partial"] is True
+    assert report["verified"] is True
+    assert report["complete"] is False
+    assert report["partial"] is True
+    assert report["installed"] is False
+    assert report["source_unchanged"] is True
+    assert report["verification"]["healthy"] is True
+    assert report["verification"]["integrity_check"] == ["ok"]
+    assert report["verification"]["foreign_key_check"] == []
+    assert report["verification"]["table_counts"]["sessions"] == 1
+
+    copied_messages = report["copy"]["messages"]
+    assert copied_messages["status"] == "partial"
+    assert copied_messages["copied_rows"] < message_count
+    assert copied_messages["copied_rows"] > 0
+    assert copied_messages["skipped_rowid_ranges"]
+    assert any(
+        item["low"] <= message_count and item["high"] >= 1
+        for item in copied_messages["skipped_rowid_ranges"]
+    )
+    assert copied_messages["query_limit_reached"] is False
+
+    conn = sqlite3.connect(str(output))
+    try:
+        recovered_ids = {
+            int(row[0]) for row in conn.execute("SELECT id FROM messages")
+        }
+        assert 1 in recovered_ids
+        assert message_count in recovered_ids
+        assert len(recovered_ids) == copied_messages["copied_rows"]
+        assert conn.execute("PRAGMA integrity_check").fetchall() == [("ok",)]
+    finally:
+        conn.close()
+
+    # Prove the helper damaged an interior data leaf, so successful recovery of
+    # the first and last message IDs really crossed the corrupted region.
+    assert corrupt_page not in {
+        min(_btree_leaf_pages(source, messages_root)[1]),
+        max(_btree_leaf_pages(source, messages_root)[1]),
+    }
+
+
+def test_partial_recovery_reconstructs_unreadable_sessions_without_message_loss(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "corrupt-sessions.db"
+    output = tmp_path / "partial-sessions.db"
+    session_count = 180
+    sessions_root = _make_many_sessions_source(
+        source,
+        session_count,
+    )
+    _corrupt_middle_table_leaf(source, sessions_root)
+    source_hash = _sha256(source)
+
+    report = recover_session_database(
+        source,
+        output,
+        work_dir=tmp_path,
+        chunk_size=8,
+        allow_partial=True,
+    )
+
+    assert report["verified"] is True
+    assert report["complete"] is False
+    assert report["partial"] is True
+    assert report["source_unchanged"] is True
+    assert _sha256(source) == source_hash
+    assert report["copy"]["sessions"]["status"] == "partial"
+    assert report["copy"]["messages"]["status"] == "complete"
+    copied_sessions = int(report["copy"]["sessions"]["copied_rows"])
+    expected_reconstructed = session_count - copied_sessions
+    cleanup = report["orphan_cleanup"]
+    assert expected_reconstructed > 1
+    assert cleanup["sessions_reconstructed"] == expected_reconstructed
+    assert cleanup["messages_retained"] == expected_reconstructed
+    assert cleanup["messages_removed"] == 0
+    assert report["verification"]["foreign_key_check"] == []
+    assert report["verification"]["integrity_check"] == ["ok"]
+    assert report["verification"]["table_counts"]["sessions"] == session_count
+    assert report["verification"]["table_counts"]["messages"] == session_count
+
+    conn = sqlite3.connect(str(output))
+    try:
+        recovered_sessions = conn.execute(
+            "SELECT id, source, title FROM sessions ORDER BY id"
+        ).fetchall()
+        recovered_ids = {str(row[0]) for row in recovered_sessions}
+        assert recovered_ids == {
+            f"partial-session-{session_number:04d}"
+            for session_number in range(session_count)
+        }
+        placeholder_rows = [
+            row for row in recovered_sessions if str(row[1]) == "recovered"
+        ]
+        assert len(placeholder_rows) == expected_reconstructed
+        placeholder_titles = [str(row[2]) for row in placeholder_rows]
+        assert len(set(placeholder_titles)) == expected_reconstructed
+        assert all(
+            title.startswith("[recovered ") for title in placeholder_titles
+        )
+        assert (
+            conn.execute(
+                "SELECT COUNT(*) FROM messages AS message "
+                "WHERE NOT EXISTS ("
+                "SELECT 1 FROM sessions "
+                "WHERE sessions.id = message.session_id)"
+            ).fetchone()[0]
+            == 0
+        )
+        assert (
+            conn.execute("SELECT COUNT(*) FROM messages").fetchone()[0]
+            == session_count
+        )
+    finally:
+        conn.close()
+
+
+def test_cli_recover_writes_verified_report_without_touching_source(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "state.db"
+    output = tmp_path / "recovered.db"
+    expected = _make_source(source)
+    source_hash = _sha256(source)
+    env = os.environ.copy()
+    env["HERMES_HOME"] = str(tmp_path / "isolated-hermes-home")
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "hermes_cli.main",
+            "sessions",
+            "recover",
+            "--source",
+            str(source),
+            "--output",
+            str(output),
+            "--work-dir",
+            str(tmp_path),
+            "--chunk-size",
+            "5",
+        ],
+        cwd=Path(__file__).resolve().parents[2],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=60,
+        check=False,
+    )
+
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert "The active session database was not changed." in result.stdout
+    assert _sha256(source) == source_hash
+    report_path = output.with_name(output.name + ".recovery.json")
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    assert report["complete"] is True
+    assert report["verification"]["table_counts"]["sessions"] == expected["sessions"]
+    assert report["verification"]["table_counts"]["messages"] == expected["messages"]
+
+
+def test_failed_repair_points_the_user_at_offline_recovery(tmp_path: Path) -> None:
+    """A failed in-place repair must name the offline recovery command.
+
+    This is the reported dead end: `hermes sessions repair` exhausts its
+    in-place ladder, prints "keep the files", and stops -- leaving the user
+    with no idea that a non-destructive recovery path exists. The failure
+    branch has to hand them the next command, inspection first, seeded with
+    the preserved backup it just made.
+    """
+    hermes_home = tmp_path / "isolated-hermes-home"
+    hermes_home.mkdir()
+    # Not a database at all -> every in-place repair strategy fails.
+    (hermes_home / "state.db").write_bytes(b"SQLite format 3\x00" + b"\x7f" * 2048)
+    env = os.environ.copy()
+    env["HERMES_HOME"] = str(hermes_home)
+
+    result = subprocess.run(
+        [sys.executable, "-m", "hermes_cli.main", "sessions", "repair"],
+        cwd=Path(__file__).resolve().parents[2],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=60,
+        check=False,
+    )
+
+    combined = result.stdout + result.stderr
+    assert "Repair failed" in combined, combined
+    # The pointer, and specifically the read-only step first.
+    assert "sessions recover" in combined, combined
+    assert "--inspect-only" in combined, combined
+    # It must offer the source it actually preserved, not a placeholder.
+    assert "--source" in combined, combined
+    assert "malformed-backup" in combined, combined
diff --git a/tests/hermes_cli/test_sessions_export_md_cli.py b/tests/hermes_cli/test_sessions_export_md_cli.py
index 76c634b7105..665da274c9c 100644
--- a/tests/hermes_cli/test_sessions_export_md_cli.py
+++ b/tests/hermes_cli/test_sessions_export_md_cli.py
@@ -336,8 +336,12 @@ def test_sessions_export_md_delete_after_verified_deletes_after_file_check(monke
         def export_session(self, session_id):
             return {"id": "s1", "title": "Delete", "message_count": 1, "messages": [{"role": "user", "content": "safe"}]}
 
+        def get_session_delete_targets(self, session_id):
+            return [session_id]
+
         def delete_session(self, session_id, **kwargs):
             captured["deleted"] = session_id
+            captured["expected_delete_ids"] = kwargs["expected_delete_ids"]
             return True
 
         def close(self):
@@ -363,11 +367,76 @@ def test_sessions_export_md_delete_after_verified_deletes_after_file_check(monke
 
     main_mod.main()
 
-    assert captured == {"deleted": "s1"}
+    assert captured == {"deleted": "s1", "expected_delete_ids": ["s1"]}
     assert len(list(tmp_path.glob("*.md"))) == 1
     assert "Deleted exported session 's1'" in capsys.readouterr().out
 
 
+def test_sessions_export_md_exports_delegate_cascade_before_deleting(
+    monkeypatch, tmp_path, capsys
+):
+    import hermes_cli.main as main_mod
+    import hermes_state
+
+    db_path = tmp_path / "state.db"
+    sessions_dir = tmp_path / "sessions"
+    sessions_dir.mkdir()
+    real_session_db = hermes_state.SessionDB
+    db = real_session_db(db_path)
+    db.create_session("parent", "cli")
+    db.append_message("parent", "user", "parent transcript")
+    db.create_session(
+        "delegate",
+        "subagent",
+        parent_session_id="parent",
+        model_config={"_delegate_from": "parent"},
+    )
+    db.append_message("delegate", "assistant", "delegate-only result")
+    db.close()
+    (sessions_dir / "parent.jsonl").write_text("parent", encoding="utf-8")
+    (sessions_dir / "delegate.jsonl").write_text("delegate", encoding="utf-8")
+
+    monkeypatch.setattr(
+        hermes_state, "SessionDB", lambda: real_session_db(db_path)
+    )
+    monkeypatch.setattr(main_mod, "get_hermes_home", lambda: tmp_path)
+    output_dir = tmp_path / "exports"
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "hermes",
+            "sessions",
+            "export",
+            "--format",
+            "md",
+            "--session-id",
+            "parent",
+            "--delete-after-verified",
+            "--yes",
+            str(output_dir),
+        ],
+    )
+
+    main_mod.main()
+
+    exported = [
+        path.read_text(encoding="utf-8") for path in output_dir.glob("*.md")
+    ]
+    assert len(exported) == 2
+    assert any("parent transcript" in text for text in exported)
+    assert any("delegate-only result" in text for text in exported)
+    check = real_session_db(db_path)
+    assert check.get_session("parent") is None
+    assert check.get_session("delegate") is None
+    check.close()
+    assert not (sessions_dir / "parent.jsonl").exists()
+    assert not (sessions_dir / "delegate.jsonl").exists()
+    output = capsys.readouterr().out
+    assert "Exported 2 sessions (2 messages)" in output
+    assert "and 1 delegate session" in output
+
+
 def test_sessions_export_md_accepts_duration_age_grammar(monkeypatch, tmp_path, capsys):
     """--older-than accepts the same AGE grammar as prune ('2w', '5h', ISO)."""
     import hermes_cli.main as main_mod
diff --git a/tests/hermes_cli/test_sessions_size_delta_label.py b/tests/hermes_cli/test_sessions_size_delta_label.py
new file mode 100644
index 00000000000..88e90ce18dd
--- /dev/null
+++ b/tests/hermes_cli/test_sessions_size_delta_label.py
@@ -0,0 +1,28 @@
+"""Tests for the session-store size-delta label (`hermes sessions optimize*`).
+
+A negative before/after delta means the DB grew — printing
+"reclaimed -163.0 MB" for that reads as data loss (issue #70146).
+"""
+
+from hermes_cli.main import _size_delta_label
+
+
+def test_shrink_reports_reclaimed():
+    assert _size_delta_label(15094.1) == "reclaimed 15094.1 MB"
+
+
+def test_growth_reports_grew_by_not_negative_reclaimed():
+    label = _size_delta_label(-163.0)
+    assert label == "grew by 163.0 MB"
+    assert "reclaimed" not in label
+    assert "-" not in label
+
+
+def test_zero_delta_reports_reclaimed_zero():
+    assert _size_delta_label(0.0) == "reclaimed 0.0 MB"
+
+
+def test_no_negative_number_ever_rendered():
+    """Whatever the sign, the rendered number is never negative."""
+    for value in (-9999.9, -0.1, 0.0, 0.1, 9999.9):
+        assert "-" not in _size_delta_label(value), value
diff --git a/tests/hermes_cli/test_setup_hidden_env.py b/tests/hermes_cli/test_setup_hidden_env.py
new file mode 100644
index 00000000000..bbb40a6ce93
--- /dev/null
+++ b/tests/hermes_cli/test_setup_hidden_env.py
@@ -0,0 +1,163 @@
+"""Setup surfaces ask only for what a platform can't start without.
+
+The knobs in SETUP_HIDDEN_ENV_SUFFIXES are self-configuring (/sethome) or
+already correct by default, so they don't belong on a setup form. They must
+still be reachable everywhere else — this is a presentation change, not a
+feature removal.
+"""
+
+import pytest
+
+from hermes_cli.setup_hidden_env import is_setup_hidden_env
+
+
+class TestIsSetupHiddenEnv:
+    @pytest.mark.parametrize(
+        "key",
+        [
+            "DISCORD_HOME_CHANNEL",
+            "DISCORD_HOME_CHANNEL_NAME",
+            "DISCORD_ALLOW_ALL_USERS",
+            "DISCORD_REPLY_TO_MODE",
+            "MATTERMOST_REPLY_MODE",
+            "TELEGRAM_PROXY",
+        ],
+    )
+    def test_self_configuring_knobs_are_hidden(self, key):
+        assert is_setup_hidden_env(key)
+
+    @pytest.mark.parametrize(
+        "key",
+        [
+            "DISCORD_BOT_TOKEN",
+            "TELEGRAM_BOT_TOKEN",
+            "SLACK_BOT_TOKEN",
+            "MATTERMOST_URL",
+            # Allowlists stay: the gateway denies everyone until one is set,
+            # so this is the decision a new user actually has to make.
+            "DISCORD_ALLOWED_USERS",
+            "SLACK_ALLOWED_USERS",
+        ],
+    )
+    def test_credentials_and_allowlists_stay_visible(self, key):
+        assert not is_setup_hidden_env(key)
+
+    def test_applies_to_plugin_platforms_nobody_enumerated(self):
+        """Suffix matching is the point — IRC/SimpleX/ntfy get this for free."""
+        for key in (
+            "IRC_ALLOW_ALL_USERS",
+            "SIMPLEX_HOME_CHANNEL",
+            "NTFY_HOME_CHANNEL_NAME",
+            "LINE_ALLOW_ALL_USERS",
+        ):
+            assert is_setup_hidden_env(key), key
+
+
+class TestChannelCards:
+    def test_discord_card_asks_for_token_and_allowlist_only(self):
+        """The reported bug: the Discord card asked five questions for a
+        one-credential platform."""
+        from hermes_cli.web_server import _build_catalog_entry
+
+        assert set(_build_catalog_entry("discord")["env_vars"]) == {
+            "DISCORD_BOT_TOKEN",
+            "DISCORD_ALLOWED_USERS",
+        }
+
+    def test_no_card_shows_a_hidden_knob(self):
+        from hermes_cli.web_server import _messaging_platform_catalog
+
+        for entry in _messaging_platform_catalog():
+            for key in entry["env_vars"]:
+                assert not is_setup_hidden_env(key), f"{entry['id']}: {key}"
+
+    def test_required_credentials_are_never_hidden(self):
+        """Hiding a required var would make its platform unconfigurable."""
+        from hermes_cli.web_server import _messaging_platform_catalog
+
+        for entry in _messaging_platform_catalog():
+            for key in entry["required_env"]:
+                assert key in entry["env_vars"], f"{entry['id']}: {key}"
+
+    def test_hidden_knobs_move_to_the_keys_page_not_into_a_void(self):
+        """Keys hides what a Channels card owns. Dropping these from the card
+        must hand them back to Keys, not orphan them from every surface."""
+        from hermes_cli.web_server import _channel_managed_env_keys
+
+        managed = _channel_managed_env_keys()
+        for key in (
+            "DISCORD_HOME_CHANNEL",
+            "DISCORD_ALLOW_ALL_USERS",
+            "DISCORD_REPLY_TO_MODE",
+        ):
+            assert key not in managed, f"{key} is hidden from both surfaces"
+
+
+class TestCliWizard:
+    """`hermes setup gateway` drops the same knobs. Real wizard, scripted
+    stdin, real .env writes under a temp HERMES_HOME."""
+
+    @pytest.fixture
+    def home(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        return tmp_path
+
+    def _run(self, answers, monkeypatch):
+        import io
+
+        from hermes_cli import gateway as gw
+
+        platform = next(p for p in gw._PLATFORMS if p["key"] == "mattermost")
+        monkeypatch.setattr("sys.stdin", io.StringIO("\n".join(answers) + "\n"))
+        gw._setup_standard_platform(dict(platform))
+
+    def _env(self, home):
+        path = home / ".env"
+        if not path.exists():
+            return {}
+        out = {}
+        for line in path.read_text().splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                k, v = line.split("=", 1)
+                out[k] = v
+        return out
+
+    def test_wizard_stops_asking_about_hidden_knobs(self, home, monkeypatch, capsys):
+        # Only the three real answers. If the wizard still prompted for the
+        # home channel it would read past them.
+        self._run(
+            ["https://mm.example.com", "tok-abc", "user26charid"], monkeypatch
+        )
+
+        written = self._env(home)
+        assert written.get("MATTERMOST_URL") == "https://mm.example.com"
+        assert written.get("MATTERMOST_TOKEN") == "tok-abc"
+        assert "MATTERMOST_HOME_CHANNEL" not in written
+        assert "MATTERMOST_REPLY_MODE" not in written
+
+        out = capsys.readouterr().out
+        assert "Home channel" not in out
+        assert "Reply mode" not in out
+
+    def test_required_token_still_gates_setup(self, home, monkeypatch):
+        """Proves the token wasn't swept out along with the knobs."""
+        self._run(["https://mm.example.com", ""], monkeypatch)
+
+        assert "MATTERMOST_TOKEN" not in self._env(home)
+
+
+class TestStillConfigurable:
+    def test_gateway_still_honors_the_env_vars(self, tmp_path, monkeypatch):
+        """Nothing was removed from the product — only from the setup form."""
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        monkeypatch.setenv("DISCORD_BOT_TOKEN", "t")
+        monkeypatch.setenv("DISCORD_HOME_CHANNEL", "999")
+        monkeypatch.setenv("DISCORD_REPLY_TO_MODE", "off")
+
+        from gateway.config import Platform, load_gateway_config
+
+        discord = load_gateway_config().platforms[Platform.DISCORD]
+        assert discord.home_channel is not None
+        assert discord.home_channel.chat_id == "999"
+        assert discord.reply_to_mode == "off"
diff --git a/tests/hermes_cli/test_sqlite_runtime.py b/tests/hermes_cli/test_sqlite_runtime.py
new file mode 100644
index 00000000000..85ef61fc112
--- /dev/null
+++ b/tests/hermes_cli/test_sqlite_runtime.py
@@ -0,0 +1,93 @@
+"""Behavioral tests for exact-interpreter SQLite runtime inspection."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import sqlite3
+import sys
+from pathlib import Path
+
+import pytest
+
+from hermes_cli.sqlite_runtime import (
+    is_sqlite_wal_reset_vulnerable,
+    probe_sqlite_runtime,
+)
+
+
+@pytest.mark.parametrize(
+    ("version", "expected"),
+    [
+        ((3, 6, 23), False),
+        ((3, 7, 0), True),
+        ((3, 44, 5), True),
+        ((3, 44, 6), False),
+        ((3, 45, 0), True),
+        ((3, 50, 6), True),
+        ((3, 50, 7), False),
+        ((3, 51, 2), True),
+        ((3, 51, 3), False),
+        ((3, 53, 1), False),
+    ],
+)
+def test_wal_reset_vulnerability_matrix(
+    version: tuple[int, ...],
+    expected: bool,
+) -> None:
+    assert is_sqlite_wal_reset_vulnerable(version) is expected
+
+
+def test_probe_reports_the_requested_interpreters_linked_sqlite() -> None:
+    info = probe_sqlite_runtime(sys.executable)
+
+    assert info is not None
+    assert info.executable.resolve() == Path(sys.executable).resolve()
+    assert info.base_prefix.resolve() == Path(sys.base_prefix).resolve()
+    assert info.python_version == sys.version_info[:3]
+    assert info.sqlite_version == sqlite3.sqlite_version_info
+    assert info.sqlite_version_string == sqlite3.sqlite_version
+
+    with sqlite3.connect(":memory:") as conn:
+        source_id = conn.execute("SELECT sqlite_source_id()").fetchone()[0]
+    assert info.sqlite_source_id == source_id
+
+
+@pytest.mark.skipif(os.name == "nt", reason="uses a POSIX executable probe stub")
+def test_probe_uses_child_payload_and_sanitizes_python_environment(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    fake_python = tmp_path / "reported-python"
+    payload = {
+        "base_prefix": str(tmp_path / "reported-base"),
+        "executable": str(fake_python),
+        "python_version": [3, 11, 15],
+        "sqlite_version": [9, 8, 7],
+        "sqlite_version_string": "9.8.7-child",
+        "sqlite_source_id": "child-source-id",
+    }
+    fake_python.write_text(
+        "\n".join([
+            "#!/bin/sh",
+            '[ "$1" = "-I" ] && [ "$2" = "-c" ] || exit 10',
+            '[ -z "${PYTHONHOME+x}" ] || exit 11',
+            '[ -z "${PYTHONPATH+x}" ] || exit 12',
+            f"printf '%s\\n' {shlex.quote(json.dumps(payload))}",
+        ])
+        + "\n",
+        encoding="utf-8",
+    )
+    fake_python.chmod(0o755)
+    monkeypatch.setenv("PYTHONHOME", str(tmp_path / "poison-home"))
+    monkeypatch.setenv("PYTHONPATH", str(tmp_path / "poison-path"))
+
+    info = probe_sqlite_runtime(fake_python)
+
+    assert info is not None
+    assert info.executable == fake_python
+    assert info.base_prefix == tmp_path / "reported-base"
+    assert info.sqlite_version == (9, 8, 7)
+    assert info.sqlite_version_string == "9.8.7-child"
+    assert info.sqlite_source_id == "child-source-id"
diff --git a/tests/hermes_cli/test_state_db_guard.py b/tests/hermes_cli/test_state_db_guard.py
new file mode 100644
index 00000000000..48251e6e2b0
--- /dev/null
+++ b/tests/hermes_cli/test_state_db_guard.py
@@ -0,0 +1,223 @@
+"""Tests for the state.db integrity guard used by the update flow (#68474).
+
+Exercises ``verify_sqlite_integrity`` and ``copy_db_and_verify`` against REAL
+SQLite files (valid, zeroed, truncated) — the exact corruption signature from
+issue #68474 (file kept at original size, 100% null bytes, header gone).
+"""
+
+import sqlite3
+
+import pytest
+
+from hermes_cli.backup import copy_db_and_verify, verify_sqlite_integrity
+
+
+@pytest.fixture()
+def valid_db(tmp_path):
+    path = tmp_path / "state.db"
+    conn = sqlite3.connect(path)
+    conn.execute("CREATE TABLE sessions (id INTEGER PRIMARY KEY, name TEXT)")
+    conn.executemany(
+        "INSERT INTO sessions (name) VALUES (?)", [(f"s{i}",) for i in range(50)]
+    )
+    conn.commit()
+    conn.close()
+    return path
+
+
+def test_valid_db_passes(valid_db):
+    res = verify_sqlite_integrity(valid_db)
+    assert res["valid"] is True
+    assert res["size"] == valid_db.stat().st_size
+    assert "passed" in res["message"]
+
+
+def test_zeroed_db_fails_header_check(valid_db):
+    # The #68474 signature: same size, all null bytes.
+    size = valid_db.stat().st_size
+    valid_db.write_bytes(b"\x00" * size)
+    res = verify_sqlite_integrity(valid_db)
+    assert res["valid"] is False
+    assert "header" in res["message"]
+
+
+def test_missing_file():
+    from pathlib import Path
+
+    res = verify_sqlite_integrity(Path("/nonexistent/state.db"))
+    assert res["valid"] is False
+    assert "not found" in res["message"]
+
+
+def test_too_small_file(tmp_path):
+    path = tmp_path / "state.db"
+    path.write_bytes(b"SQLite")
+    res = verify_sqlite_integrity(path)
+    assert res["valid"] is False
+    assert "too small" in res["message"]
+
+
+def test_header_ok_but_garbage_body_fails_pragma(tmp_path):
+    path = tmp_path / "state.db"
+    path.write_bytes(b"SQLite format 3\0" + b"\xff" * 4096)
+    res = verify_sqlite_integrity(path)
+    assert res["valid"] is False
+
+
+def test_oversized_db_skips_pragma_but_still_checks_header(valid_db):
+    res = verify_sqlite_integrity(valid_db, max_bytes=1)
+    # Header intact + schema probe passes → pass without the full pragma.
+    assert res["valid"] is True
+    assert "skipped PRAGMA integrity_check" in res["message"]
+    size = valid_db.stat().st_size
+    valid_db.write_bytes(b"\x00" * size)
+    res = verify_sqlite_integrity(valid_db, max_bytes=1)
+    # Zeroed header must still fail even when pragma is skipped for size.
+    assert res["valid"] is False
+
+
+def test_default_max_bytes_bounds_the_pragma_by_size():
+    """The default must NOT be size-unbounded.
+
+    ``PRAGMA integrity_check`` walks every page in the file, so an unbounded
+    default made `hermes update` peg a CPU for minutes on a multi-GB
+    state.db with no output (read as a hang). Callers that omit max_bytes
+    must inherit a finite ceiling.
+    """
+    import inspect
+
+    from hermes_cli.backup import DEFAULT_INTEGRITY_CHECK_MAX_BYTES
+
+    default = inspect.signature(verify_sqlite_integrity).parameters["max_bytes"].default
+    assert default == DEFAULT_INTEGRITY_CHECK_MAX_BYTES
+    assert default > 0, "size-unbounded integrity_check is never a safe default"
+
+
+def test_oversized_db_probe_catches_malformed_schema(tmp_path):
+    """Skipping the pragma must not mean skipping corruption detection.
+
+    A file with a valid header whose schema cannot be parsed has to fail
+    the oversized path via the cheap structural probe.
+    """
+    path = tmp_path / "state.db"
+    conn = sqlite3.connect(path)
+    conn.execute("CREATE TABLE t (a INTEGER)")
+    conn.commit()
+    conn.close()
+
+    raw = bytearray(path.read_bytes())
+    # Corrupt the schema b-tree page (page 2 onward) while leaving the
+    # 16-byte header magic intact, so only the probe can catch it.
+    for i in range(100, min(len(raw), 4096)):
+        raw[i] = 0xFF
+    path.write_bytes(bytes(raw))
+
+    res = verify_sqlite_integrity(path, max_bytes=1)
+    assert res["valid"] is False
+    assert "probe" in res["message"]
+
+
+def test_max_bytes_zero_forces_full_check(valid_db):
+    """``max_bytes=0`` remains the explicit opt-in for a full scan."""
+    res = verify_sqlite_integrity(valid_db, max_bytes=0)
+    assert res["valid"] is True
+    assert "integrity check passed" in res["message"]
+
+
+def test_copy_db_and_verify_roundtrip(valid_db, tmp_path):
+    dst = tmp_path / "snapshot" / "state.db"
+    dst.parent.mkdir()
+    assert copy_db_and_verify(valid_db, dst) is True
+    assert verify_sqlite_integrity(dst)["valid"] is True
+
+
+def test_copy_db_and_verify_refuses_zeroed_source(valid_db, tmp_path):
+    size = valid_db.stat().st_size
+    valid_db.write_bytes(b"\x00" * size)
+    dst = tmp_path / "snapshot" / "state.db"
+    dst.parent.mkdir()
+    assert copy_db_and_verify(valid_db, dst) is False
+    assert not dst.exists()
+
+
+def test_restore_flow_end_to_end(valid_db, tmp_path):
+    """Simulate the #68474 recovery path: live db zeroed, snapshot valid →
+    restore snapshot over live file → verify restored copy."""
+    import shutil
+
+    snap = tmp_path / "state-snapshots" / "20260721-pre-update" / "state.db"
+    snap.parent.mkdir(parents=True)
+    shutil.copy2(valid_db, snap)
+
+    # Zero the live db (the bug).
+    size = valid_db.stat().st_size
+    valid_db.write_bytes(b"\x00" * size)
+    assert verify_sqlite_integrity(valid_db)["valid"] is False
+    assert verify_sqlite_integrity(snap)["valid"] is True
+
+    # The guard's restore step.
+    shutil.copy2(snap, valid_db)
+    restored = verify_sqlite_integrity(valid_db)
+    assert restored["valid"] is True
+    conn = sqlite3.connect(valid_db)
+    assert conn.execute("SELECT COUNT(*) FROM sessions").fetchone()[0] == 50
+    conn.close()
+
+
+class TestPreUpdateBackupIntegrityGuard:
+    """E2E: run the real ``_run_pre_update_backup`` against a temp
+    HERMES_HOME whose state.db is corrupted mid-flight (#68474)."""
+
+    @pytest.fixture()
+    def hermes_home(self, tmp_path, monkeypatch):
+        from pathlib import Path
+        import sys
+
+        root = tmp_path / ".hermes"
+        root.mkdir()
+        (root / "config.yaml").write_text("model:\n  provider: openrouter\n")
+        db = root / "state.db"
+        conn = sqlite3.connect(db)
+        conn.execute("CREATE TABLE sessions (id INTEGER PRIMARY KEY)")
+        conn.commit()
+        conn.close()
+        monkeypatch.setenv("HERMES_HOME", str(root))
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        for mod in list(sys.modules.keys()):
+            if mod.startswith("hermes_cli.config") or mod == "hermes_constants":
+                del sys.modules[mod]
+        return root
+
+    def test_healthy_db_stays_quiet(self, hermes_home, capsys):
+        from argparse import Namespace
+
+        from hermes_cli.main import _run_pre_update_backup
+
+        snap_id = _run_pre_update_backup(Namespace(no_backup=False, backup=False))
+        out = capsys.readouterr().out
+        assert snap_id is not None
+        assert "Pre-update snapshot" in out
+        assert "integrity check FAILED" not in out
+
+    def test_zeroed_db_after_snapshot_is_loud(self, hermes_home, capsys, monkeypatch):
+        """If state.db is zeroed right after the snapshot completes, the
+        guard must warn loudly instead of proceeding silently (exit-0 mask)."""
+        from argparse import Namespace
+
+        import hermes_cli.backup as backup_mod
+        from hermes_cli.main import _run_pre_update_backup
+
+        real_create = backup_mod.create_quick_snapshot
+
+        def create_then_zero(**kwargs):
+            snap_id = real_create(**kwargs)
+            live = hermes_home / "state.db"
+            live.write_bytes(b"\x00" * live.stat().st_size)
+            return snap_id
+
+        monkeypatch.setattr(backup_mod, "create_quick_snapshot", create_then_zero)
+        snap_id = _run_pre_update_backup(Namespace(no_backup=False, backup=False))
+        out = capsys.readouterr().out
+        assert snap_id is not None
+        assert "integrity check FAILED" in out
+        assert "Snapshot copy is valid" in out
diff --git a/tests/hermes_cli/test_update_autostash.py b/tests/hermes_cli/test_update_autostash.py
index 5ffdb519bfd..d89d830b140 100644
--- a/tests/hermes_cli/test_update_autostash.py
+++ b/tests/hermes_cli/test_update_autostash.py
@@ -25,13 +25,13 @@ def _patch_managed_uv(request):
 
     # resolve_uv delegates to shutil.which("uv") so that test patches
     # on shutil.which flow through naturally.
-    def _fake_resolve_uv():
+    def _fake_resolve_uv(**kwargs):
         return shutil.which("uv")
 
-    def _fake_ensure_uv():
+    def _fake_ensure_uv(**kwargs):
         return shutil.which("uv")
 
-    def _fake_update_managed_uv():
+    def _fake_update_managed_uv(**kwargs):
         return None  # never actually self-update in tests
 
     with patch("hermes_cli.managed_uv.resolve_uv", side_effect=_fake_resolve_uv), \
@@ -206,9 +206,10 @@ def test_restore_stashed_changes_keeps_going_when_stash_entry_cannot_be_resolved
     restored = hermes_main._restore_stashed_changes(["git"], tmp_path, "abc123", prompt_user=False)
 
     assert restored is True
-    assert calls[0] == (["git", "stash", "apply", "abc123"], {"cwd": tmp_path, "capture_output": True, "text": True})
-    assert calls[1] == (["git", "diff", "--name-only", "--diff-filter=U"], {"cwd": tmp_path, "capture_output": True, "text": True})
-    assert calls[2] == (["git", "stash", "list", "--format=%gd %H"], {"cwd": tmp_path, "capture_output": True, "text": True, "check": True})
+    _utf8 = {"encoding": "utf-8", "errors": "replace"}
+    assert calls[0] == (["git", "stash", "apply", "abc123"], {"cwd": tmp_path, "capture_output": True, "text": True, **_utf8})
+    assert calls[1] == (["git", "diff", "--name-only", "--diff-filter=U"], {"cwd": tmp_path, "capture_output": True, "text": True, **_utf8})
+    assert calls[2] == (["git", "stash", "list", "--format=%gd %H"], {"cwd": tmp_path, "capture_output": True, "text": True, **_utf8, "check": True})
     out = capsys.readouterr().out
     assert "couldn't find the stash entry to drop" in out
     assert "stash was left in place" in out
diff --git a/tests/hermes_cli/test_vertex_model_picker.py b/tests/hermes_cli/test_vertex_model_picker.py
new file mode 100644
index 00000000000..ccf17e6b4ed
--- /dev/null
+++ b/tests/hermes_cli/test_vertex_model_picker.py
@@ -0,0 +1,49 @@
+"""Vertex visibility in the /model picker (follow-up to PR #56688).
+
+Community verification of the vertex-registration fix found two remaining
+gaps that kept the provider invisible/unusable in the /model menu:
+
+1. ``list_authenticated_providers`` had no credential gate for the
+   ``vertex`` auth_type (only ``aws_sdk`` was special-cased), so the
+   provider was silently hidden even when fully configured.
+2. Vertex's OpenAI-compatible endpoint has no ``/models`` listing route,
+   so without a curated ``_PROVIDER_MODELS["vertex"]`` entry the picker
+   only ever showed the currently-configured model.
+
+No network calls.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from hermes_cli.model_switch import list_authenticated_providers
+from hermes_cli.models import _PROVIDER_MODELS
+
+
+def test_vertex_has_curated_model_list():
+    """Vertex has no /models route — the picker needs a static curated list."""
+    models = _PROVIDER_MODELS.get("vertex")
+    assert models, "_PROVIDER_MODELS must have a non-empty 'vertex' entry"
+    # Vertex's openapi endpoint expects the google/ publisher prefix.
+    assert all(m.startswith("google/") for m in models)
+
+
+def test_vertex_appears_when_credentials_configured():
+    """has_vertex_credentials() == True must surface vertex in the picker."""
+    with patch("agent.vertex_adapter.has_vertex_credentials", return_value=True):
+        providers = list_authenticated_providers(current_provider="openrouter", max_models=50)
+
+    vertex = next((p for p in providers if p["slug"] == "vertex"), None)
+    assert vertex is not None, "vertex should appear when credentials are configured"
+    assert vertex["models"], "vertex row must carry the curated model list"
+    assert "google/gemini-3-pro-preview" in vertex["models"]
+
+
+def test_vertex_hidden_without_credentials():
+    """No service-account path / project override → vertex stays hidden."""
+    with patch("agent.vertex_adapter.has_vertex_credentials", return_value=False):
+        providers = list_authenticated_providers(current_provider="openrouter", max_models=50)
+
+    vertex = next((p for p in providers if p["slug"] == "vertex"), None)
+    assert vertex is None, "vertex should not appear without credentials"
diff --git a/tests/hermes_cli/test_vertex_provider.py b/tests/hermes_cli/test_vertex_provider.py
index af67aacac29..d97b5340902 100644
--- a/tests/hermes_cli/test_vertex_provider.py
+++ b/tests/hermes_cli/test_vertex_provider.py
@@ -98,3 +98,31 @@ def test_vertex_extra_body_empty_without_reasoning():
 
     p = get_provider_profile("vertex")
     assert p.build_extra_body(model="google/gemini-3-flash-preview") == {}
+
+
+def test_vertex_registered_in_provider_registry():
+    """PROVIDER_REGISTRY (hermes_cli.auth) is what agent/auxiliary_client.py's
+    resolve_provider_client() looks up before dispatching on auth_type. Without
+    an entry here, the ``elif pconfig.auth_type == "vertex":`` branch there is
+    unreachable dead code — every auxiliary Vertex call (vision, title
+    generation, MoA reference/aggregator slots, ...) fails at the
+    ``pconfig is None`` guard before ever reaching it."""
+    from hermes_cli.auth import PROVIDER_REGISTRY
+
+    cfg = PROVIDER_REGISTRY.get("vertex")
+    assert cfg is not None
+    assert cfg.auth_type == "vertex"
+
+
+def test_vertex_registered_in_hermes_overlays():
+    """hermes_cli.providers.get_provider("vertex") backs
+    _preserve_provider_with_base_url() in agent/auxiliary_client.py, which
+    decides whether a MoA slot's resolved Vertex (base_url, api_key) pair
+    keeps its "vertex" provider identity or silently collapses to "custom" —
+    losing the identity _refresh_provider_credentials() needs to re-mint an
+    expired OAuth2 token on a 401."""
+    from hermes_cli.providers import get_provider
+
+    resolved = get_provider("vertex")
+    assert resolved is not None
+    assert resolved.auth_type == "vertex"
diff --git a/tests/hermes_cli/test_web_server.py b/tests/hermes_cli/test_web_server.py
index 2ae86afdf6c..895b0ddf794 100644
--- a/tests/hermes_cli/test_web_server.py
+++ b/tests/hermes_cli/test_web_server.py
@@ -346,6 +346,170 @@ class TestWebServerEndpoints:
         assert resp.status_code == 200
         assert calls["get_running_pid_cached"] == 1
 
+    def test_get_status_profile_scopes_gateway_state_reads(self, monkeypatch):
+        """?profile=<name> must read gateway identity files from the profile's
+        home (~/.hermes/profiles/<name>/), not the process-level HERMES_HOME.
+
+        Gateway PID/state readers resolve _get_process_hermes_home(), which
+        deliberately ignores the contextvar override _config_profile_scope
+        sets (issue #56986) — so the handler must pass explicit per-profile
+        paths (issue #69143).
+        """
+        import hermes_cli.web_server as web_server
+        from hermes_cli import profiles as profiles_mod
+
+        worker_home = profiles_mod.get_profile_dir("worker")
+        worker_home.mkdir(parents=True)
+
+        seen = {}
+
+        def _pid(pid_path=None, **kw):
+            seen["pid_path"] = pid_path
+            return None
+
+        def _runtime(path=None):
+            seen["status_path"] = path
+            return {
+                "gateway_state": "running",
+                "platforms": {},
+                "updated_at": "2026-04-12T00:00:00+00:00",
+            }
+
+        def _runtime_pid(runtime=None, *, expected_home=None):
+            seen["expected_home"] = expected_home
+            return 4321
+
+        monkeypatch.setattr(web_server, "get_running_pid_cached", _pid)
+        monkeypatch.setattr(web_server, "read_runtime_status", _runtime)
+        monkeypatch.setattr(
+            web_server, "get_runtime_status_running_pid", _runtime_pid
+        )
+        monkeypatch.setattr(web_server, "_GATEWAY_HEALTH_URL", None)
+
+        resp = self.client.get("/api/status?profile=worker")
+
+        assert resp.status_code == 200
+        data = resp.json()
+        assert seen["pid_path"] == worker_home / "gateway.pid"
+        assert seen["status_path"] == worker_home / "gateway_state.json"
+        assert seen["expected_home"] == worker_home
+        assert data["gateway_running"] is True
+        assert data["gateway_pid"] == 4321
+        assert data["gateway_state"] == "running"
+
+    def test_get_status_and_messaging_agree_on_cross_container_gateway(
+        self, monkeypatch
+    ):
+        """The two surfaces must never contradict each other about liveness.
+
+        Reported symptom: the dashboard sidebar read "Gateway running" while
+        the Channels page on the same load rendered "The gateway is not
+        running." Cause: /api/status probed GATEWAY_HEALTH_URL and
+        /api/messaging/platforms did not, so a gateway in another container
+        (no local PID file) was live to one endpoint and dead to the other.
+
+        This asserts the RELATIONSHIP — both endpoints resolve liveness the
+        same way — not either endpoint's literal value.
+        """
+        import hermes_cli.web_server as web_server
+
+        # No local PID and no local runtime state: only the health probe can
+        # see the gateway, which is exactly the cross-container deployment.
+        monkeypatch.setattr(web_server, "get_running_pid_cached", lambda *a, **k: None)
+        monkeypatch.setattr(web_server, "get_running_pid", lambda *a, **k: None)
+        monkeypatch.setattr(web_server, "read_runtime_status", lambda *a, **k: None)
+        monkeypatch.setattr(
+            web_server, "get_runtime_status_running_pid", lambda *a, **k: None
+        )
+        monkeypatch.setattr(web_server, "_GATEWAY_HEALTH_URL", "http://gw:8642")
+        monkeypatch.setattr(
+            web_server,
+            "_probe_gateway_health",
+            lambda: (True, {"pid": 4321, "gateway_state": "running", "platforms": {}}),
+        )
+
+        status_running = self.client.get("/api/status").json()["gateway_running"]
+        platforms = self.client.get("/api/messaging/platforms").json()["platforms"]
+
+        assert status_running is True, "health probe should report the gateway up"
+        assert platforms, "catalog must not be empty or the assertion is vacuous"
+        for platform in platforms:
+            assert platform["gateway_running"] == status_running, (
+                f"{platform['id']}: Channels page says "
+                f"gateway_running={platform['gateway_running']} while the "
+                f"sidebar says {status_running}"
+            )
+
+    def test_get_status_and_messaging_agree_when_gateway_is_down(self, monkeypatch):
+        """Agreement must hold in the negative direction too.
+
+        Guards against "fix" it by hardcoding True somewhere: with every rung
+        declining, both surfaces must report the gateway down.
+        """
+        import hermes_cli.web_server as web_server
+
+        monkeypatch.setattr(web_server, "get_running_pid_cached", lambda *a, **k: None)
+        monkeypatch.setattr(web_server, "get_running_pid", lambda *a, **k: None)
+        monkeypatch.setattr(web_server, "read_runtime_status", lambda *a, **k: None)
+        monkeypatch.setattr(
+            web_server, "get_runtime_status_running_pid", lambda *a, **k: None
+        )
+        monkeypatch.setattr(web_server, "_GATEWAY_HEALTH_URL", None)
+
+        status_running = self.client.get("/api/status").json()["gateway_running"]
+        platforms = self.client.get("/api/messaging/platforms").json()["platforms"]
+
+        assert status_running is False
+        assert platforms
+        for platform in platforms:
+            assert platform["gateway_running"] == status_running
+
+    def test_messaging_platforms_profile_scopes_gateway_reads(self, monkeypatch):
+        """?profile=<name> must resolve liveness from the profile's own home.
+
+        The gateway status readers resolve process-level paths and ignore the
+        HERMES_HOME contextvar override (#56986), so /api/messaging/platforms
+        has to pass the profile directory explicitly — otherwise it reports a
+        DIFFERENT profile's gateway as this profile's, which hides a real
+        outage behind a false "connected" (issue #71211).
+        """
+        import hermes_cli.web_server as web_server
+        from hermes_cli import profiles as profiles_mod
+
+        worker_home = profiles_mod.get_profile_dir("worker")
+        worker_home.mkdir(parents=True)
+
+        seen = {}
+
+        def _pid(pid_path=None, **kw):
+            seen["pid_path"] = pid_path
+            return None
+
+        def _runtime(path=None):
+            seen["status_path"] = path
+            return None
+
+        def _runtime_pid(runtime=None, *, expected_home=None):
+            seen["expected_home"] = expected_home
+            return None
+
+        monkeypatch.setattr(web_server, "get_running_pid_cached", _pid)
+        monkeypatch.setattr(web_server, "get_running_pid", _pid)
+        monkeypatch.setattr(web_server, "read_runtime_status", _runtime)
+        monkeypatch.setattr(web_server, "get_runtime_status_running_pid", _runtime_pid)
+        monkeypatch.setattr(web_server, "_GATEWAY_HEALTH_URL", None)
+
+        resp = self.client.get("/api/messaging/platforms?profile=worker")
+
+        assert resp.status_code == 200
+        assert seen["pid_path"] == worker_home / "gateway.pid"
+        assert seen["status_path"] == worker_home / "gateway_state.json"
+        assert seen["expected_home"] == worker_home
+
+    def test_get_status_unknown_profile_404s(self):
+        resp = self.client.get("/api/status?profile=no-such-profile")
+        assert resp.status_code == 404
+
     def test_gateway_drain_begin_writes_marker(self):
         from gateway import drain_control
 
@@ -861,8 +1025,13 @@ class TestWebServerEndpoints:
         assert resp.status_code == 200
         data = resp.json()
         assert data["reference_models"]
-        assert all(set(slot) == {"provider", "model"} for slot in data["reference_models"])
-        assert set(data["aggregator"]) == {"provider", "model"}
+        # Reference slots carry provider/model plus the per-advisor enabled
+        # flag (optional keys like reasoning_effort/max_tokens appear only
+        # when configured).
+        for slot in data["reference_models"]:
+            assert {"provider", "model"} <= set(slot)
+            assert isinstance(slot.get("enabled", True), bool)
+        assert {"provider", "model"} <= set(data["aggregator"])
 
     def test_put_moa_models_persists_provider_model_slots(self):
         from hermes_cli.config import load_config
@@ -875,6 +1044,8 @@ class TestWebServerEndpoints:
             "aggregator": {"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
             "reference_temperature": 0.6,
             "aggregator_temperature": 0.4,
+            "reference_timeout": 44.5,
+            "degraded_reference_policy": "silent",
             "max_tokens": 4096,
             "enabled": True,
         }
@@ -883,8 +1054,50 @@ class TestWebServerEndpoints:
         assert resp.status_code == 200
         assert resp.json()["ok"] is True
         cfg = load_config()
-        assert cfg["moa"]["reference_models"] == payload["reference_models"]
-        assert cfg["moa"]["aggregator"] == payload["aggregator"]
+        saved_refs = cfg["moa"]["reference_models"]
+        # Slots normalize with enabled=True defaulted in; provider/model must
+        # round-trip exactly.
+        assert [
+            {"provider": s["provider"], "model": s["model"]} for s in saved_refs
+        ] == payload["reference_models"]
+        assert all(s.get("enabled", True) is True for s in saved_refs)
+        agg = cfg["moa"]["aggregator"]
+        assert {"provider": agg["provider"], "model": agg["model"]} == payload["aggregator"]
+        assert cfg["moa"]["reference_timeout"] == 44.5
+        assert cfg["moa"]["degraded_reference_policy"] == "silent"
+        returned = self.client.get("/api/model/moa").json()
+        assert returned["reference_timeout"] == 44.5
+        assert returned["degraded_reference_policy"] == "silent"
+
+    def test_put_moa_models_persists_reference_failure_controls_per_preset(self):
+        from hermes_cli.config import load_config
+
+        payload = {
+            "default_preset": "review",
+            "presets": {
+                "review": {
+                    "reference_models": [
+                        {"provider": "openai-codex", "model": "gpt-5.5"}
+                    ],
+                    "aggregator": {
+                        "provider": "openrouter",
+                        "model": "anthropic/claude-opus-4.8",
+                    },
+                    "reference_timeout": 87.5,
+                    "degraded_reference_policy": "silent",
+                }
+            },
+        }
+
+        resp = self.client.put("/api/model/moa", json=payload)
+
+        assert resp.status_code == 200
+        saved = load_config()["moa"]["presets"]["review"]
+        assert saved["reference_timeout"] == 87.5
+        assert saved["degraded_reference_policy"] == "silent"
+        returned = self.client.get("/api/model/moa").json()["presets"]["review"]
+        assert returned["reference_timeout"] == 87.5
+        assert returned["degraded_reference_policy"] == "silent"
 
     def test_put_moa_models_rejects_half_filled_slot_with_422(self):
         """#64156: a mid-edit autosave (provider picked, model empty) used to be
@@ -1279,6 +1492,34 @@ class TestWebServerEndpoints:
             json={"values": {"userPeerAliases": "{not json"}},
         ).status_code == 400
 
+    @pytest.mark.parametrize(
+        "payload",
+        [
+            {"reference_timeout": True},
+            {"reference_timeout": False},
+            {"reference_timeout": "nan"},
+            {"reference_timeout": "inf"},
+            {"presets": {"review": {"reference_timeout": True}}},
+            {"presets": {"review": {"reference_timeout": "-inf"}}},
+        ],
+    )
+    def test_put_moa_models_rejects_invalid_reference_timeout(self, payload):
+        resp = self.client.put("/api/model/moa", json=payload)
+
+        assert resp.status_code == 422
+
+    @pytest.mark.parametrize(
+        "payload",
+        [
+            {"degraded_reference_policy": "verbose"},
+            {"presets": {"review": {"degraded_reference_policy": "verbose"}}},
+        ],
+    )
+    def test_put_moa_models_rejects_invalid_degraded_reference_policy(self, payload):
+        resp = self.client.put("/api/model/moa", json=payload)
+
+        assert resp.status_code == 422
+
     # ── GET /api/media (remote image display) ───────────────────────────
 
     def test_get_media_serves_image_in_root(self):
@@ -1801,6 +2042,82 @@ class TestWebServerEndpoints:
         resp = self.client.patch("/api/sessions/no-fields", json={})
         assert resp.status_code == 400
 
+    def test_patch_session_pins_and_exempts_from_auto_archive(self):
+        """PATCH pinned=true sets the keep flag; a pinned stale session is
+        spared by the auto-archive sweep while an unpinned one is hidden."""
+        import time as _time
+
+        from hermes_state import SessionDB
+
+        old = _time.time() - 30 * 86400
+        db = SessionDB()
+        try:
+            for sid in ("keep-me", "drop-me"):
+                db.create_session(session_id=sid, source="cli")
+                db.append_message(session_id=sid, role="user", content="hi")
+                db._conn.execute(
+                    "UPDATE sessions SET started_at = ? WHERE id = ?", (old, sid)
+                )
+                db._conn.execute(
+                    "UPDATE messages SET timestamp = ? WHERE session_id = ?", (old, sid)
+                )
+            db._conn.commit()
+        finally:
+            db.close()
+
+        resp = self.client.patch("/api/sessions/keep-me", json={"pinned": True})
+        assert resp.status_code == 200
+        assert resp.json()["pinned"] is True
+
+        db = SessionDB()
+        try:
+            archived = db.archive_stale_sessions(3)
+        finally:
+            db.close()
+
+        assert archived == 1
+        listed = self.client.get("/api/sessions").json()["sessions"]
+        ids = {s["id"] for s in listed}
+        assert "keep-me" in ids  # pinned -> spared
+        assert "drop-me" not in ids  # unpinned + stale -> archived
+
+    def test_list_triggers_config_gated_auto_archive(self):
+        """With sessions.auto_archive on, listing sessions opportunistically
+        sweeps stale ones (the Desktop `hermes serve` code path)."""
+        import time as _time
+
+        import hermes_cli.web_server as ws
+        from hermes_state import SessionDB
+
+        old = _time.time() - 30 * 86400
+        db = SessionDB()
+        try:
+            db.create_session(session_id="stale-serve", source="cli")
+            db.append_message(session_id="stale-serve", role="user", content="hi")
+            db._conn.execute(
+                "UPDATE sessions SET started_at = ? WHERE id = ?", (old, "stale-serve")
+            )
+            db._conn.execute(
+                "UPDATE messages SET timestamp = ? WHERE session_id = ?",
+                (old, "stale-serve"),
+            )
+            db._conn.commit()
+        finally:
+            db.close()
+
+        # Reset the in-process throttle so the trigger actually evaluates config.
+        ws._last_auto_archive_check.clear()
+
+        # The helper imports load_config lazily from hermes_cli.config; patch there.
+        cfg = {"sessions": {"auto_archive": True, "auto_archive_days": 3, "min_interval_hours": 0}}
+        try:
+            with patch("hermes_cli.config.load_config", return_value=cfg):
+                listed = self.client.get("/api/sessions").json()["sessions"]
+        finally:
+            ws._last_auto_archive_check.clear()
+
+        assert all(s["id"] != "stale-serve" for s in listed)
+
     def test_profiles_sessions_tags_default_profile(self):
         """The cross-profile aggregator returns the default profile's rows
         tagged profile="default" (single-profile parity with /api/sessions)."""
@@ -2140,6 +2457,9 @@ class TestWebServerEndpoints:
         try:
             db.create_session(session_id="desktop-root", source="cli")
             db.append_message(session_id="desktop-root", role="user", content="before compression")
+            # Empty before closing: the closed-parent write guard refuses
+            # durable writes to compression-ended sessions.
+            db.replace_messages("desktop-root", [])
             db.end_session("desktop-root", "compression")
             now = _time.time()
             db._conn.execute(
@@ -2148,7 +2468,6 @@ class TestWebServerEndpoints:
             )
             db.create_session(session_id="desktop-tip", source="cli", parent_session_id="desktop-root")
             db._conn.execute("UPDATE sessions SET started_at = ? WHERE id = ?", (now - 4, "desktop-tip"))
-            db.replace_messages("desktop-root", [])
             db.append_message(session_id="desktop-tip", role="user", content="after compression")
             db._conn.commit()
         finally:
@@ -2834,6 +3153,14 @@ class TestWebServerEndpoints:
         assert data["AWS_PROFILE"]["provider"] == "bedrock"
 
     def test_platform_scoped_messaging_env_vars_are_channel_managed(self):
+        """Platform-scoped vars belong to a Channels card; cross-cutting
+        gateway vars belong to the Keys page.
+
+        Uses credentials as the example: the self-configuring knobs
+        (*_HOME_CHANNEL, *_ALLOW_ALL_USERS, …) were deliberately dropped from
+        the setup cards and handed back to Keys — see
+        tests/hermes_cli/test_setup_hidden_env.py.
+        """
         from hermes_cli.web_server import (
             _MESSAGING_KEYS_PAGE_KEYS,
             _build_catalog_entry,
@@ -2841,13 +3168,12 @@ class TestWebServerEndpoints:
         )
 
         discord = _build_catalog_entry("discord")
-        assert "DISCORD_HOME_CHANNEL" in discord["env_vars"]
-        assert "DISCORD_ALLOW_ALL_USERS" in discord["env_vars"]
+        assert "DISCORD_BOT_TOKEN" in discord["env_vars"]
+        assert "DISCORD_ALLOWED_USERS" in discord["env_vars"]
 
         managed = _channel_managed_env_keys()
-        assert "DISCORD_HOME_CHANNEL" in managed
-        assert "BLUEBUBBLES_ALLOW_ALL_USERS" in managed
-        assert "MATTERMOST_ALLOW_ALL_USERS" in managed
+        assert "DISCORD_BOT_TOKEN" in managed
+        assert "MATTERMOST_TOKEN" in managed
         assert "GATEWAY_PROXY_URL" not in managed
         assert "GATEWAY_PROXY_URL" in _MESSAGING_KEYS_PAGE_KEYS
 
@@ -4454,15 +4780,15 @@ class TestWebServerEndpoints:
         assert models["acme/model-1"]["context_length"] == 200000
 
     def test_deleting_the_active_custom_endpoint_clears_its_model_mirror(self):
-        """Deleting an endpoint must not leave its key running the agent.
+        """Deleting an endpoint must not leave its credential running the agent.
 
-        ``activate`` copies the endpoint's base_url + api_key onto ``model``,
-        and ``model.api_key`` outranks the environment at client construction
-        (#62269). Without clearing that mirror the agent keeps authenticating
-        to the deleted host with the deleted key, and the key the operator
-        just removed through the dashboard stays in config.yaml.
+        ``activate`` mirrors the endpoint's base_url + credential reference
+        onto ``model``, and that mirror outranks the environment at client
+        construction (#62269). Without clearing it the agent keeps
+        authenticating to the deleted host, and the credential the operator
+        just removed through the dashboard survives the delete.
         """
-        from hermes_cli.config import load_config
+        from hermes_cli.config import custom_endpoint_key_env, get_env_value, load_config
 
         self.client.post(
             "/api/providers/custom-endpoints",
@@ -4478,8 +4804,10 @@ class TestWebServerEndpoints:
             "/api/providers/custom-endpoints/acme/activate", json={}
         ).status_code == 200
 
+        env_var = custom_endpoint_key_env("acme")
         cfg = load_config()
-        assert cfg["model"]["api_key"] == "sk-acme-secret"
+        assert cfg["model"]["key_env"] == env_var
+        assert get_env_value(env_var) == "sk-acme-secret"
 
         assert self.client.request(
             "DELETE", "/api/providers/custom-endpoints/acme"
@@ -4489,12 +4817,14 @@ class TestWebServerEndpoints:
         assert "acme" not in (cfg.get("providers") or {})
         model_cfg = cfg.get("model") or {}
         assert not model_cfg.get("api_key"), "deleted endpoint's key still in config.yaml"
+        assert not model_cfg.get("key_env"), "deleted endpoint's key ref still in config.yaml"
         assert not model_cfg.get("base_url"), "deleted endpoint's host still routed to"
         assert not model_cfg.get("provider")
+        assert not get_env_value(env_var), "deleted endpoint's key still in .env"
 
     def test_deleting_an_inactive_custom_endpoint_leaves_the_active_one_alone(self):
-        """Only the mirror of the DELETED provider is scrubbed."""
-        from hermes_cli.config import load_config
+        """Only the DELETED provider's mirror and .env slot are scrubbed."""
+        from hermes_cli.config import custom_endpoint_key_env, get_env_value, load_config
 
         for name, key in (("acme", "sk-acme"), ("other", "sk-other")):
             self.client.post(
@@ -4513,8 +4843,283 @@ class TestWebServerEndpoints:
 
         model_cfg = load_config().get("model") or {}
         assert model_cfg.get("provider") == "other"
-        assert model_cfg.get("api_key") == "sk-other"
+        assert model_cfg.get("key_env") == custom_endpoint_key_env("other")
         assert model_cfg.get("base_url") == "https://llm.other.corp/v1"
+        assert get_env_value(custom_endpoint_key_env("other")) == "sk-other"
+
+    def test_custom_endpoint_save_persists_the_whole_discovered_catalogue(self):
+        """Test discovers N models; Save must keep all N (#69988).
+
+        Every downstream picker reads ``providers.<id>.models`` straight from
+        config.yaml with no live probe, so persisting only the one hand-typed
+        model left a provider serving dozens showing a single-entry list.
+        """
+        from hermes_cli.config import load_config
+
+        discovered = ["glm-5.2", "qwen3-max", "llama-4-405b", "deepseek-v4"]
+        resp = self.client.post(
+            "/api/providers/custom-endpoints",
+            json={
+                "id": "proxy",
+                "name": "Proxy",
+                "base_url": "http://127.0.0.1:8000/v1",
+                "model": "glm-5.2",
+                "models": discovered,
+            },
+        )
+
+        assert resp.status_code == 200
+        assert sorted(load_config()["providers"]["proxy"]["models"]) == sorted(discovered)
+        endpoint = next(e for e in resp.json()["endpoints"] if e["id"] == "proxy")
+        assert sorted(endpoint["models"]) == sorted(discovered)
+
+    def test_custom_endpoint_save_with_catalogue_keeps_known_context_lengths(self):
+        """A discovered list merges onto the entry; it doesn't reset it."""
+        from hermes_cli.config import load_config, save_config
+
+        cfg = load_config()
+        cfg["providers"] = {
+            "proxy": {
+                "name": "Proxy",
+                "base_url": "http://127.0.0.1:8000/v1",
+                "model": "a",
+                "models": {"a": {"context_length": 200000}},
+            }
+        }
+        save_config(cfg)
+
+        self.client.post(
+            "/api/providers/custom-endpoints",
+            json={
+                "id": "proxy",
+                "name": "Proxy",
+                "base_url": "http://127.0.0.1:8000/v1",
+                "model": "a",
+                "models": ["a", "b"],
+            },
+        )
+
+        models = load_config()["providers"]["proxy"]["models"]
+        assert sorted(models) == ["a", "b"]
+        assert models["a"]["context_length"] == 200000
+
+    def test_custom_endpoint_save_keeps_the_api_key_out_of_config(self):
+        """The key belongs in .env behind key_env, never in config.yaml (#69449)."""
+        from hermes_cli.config import custom_endpoint_key_env, get_env_value, load_config
+
+        self.client.post(
+            "/api/providers/custom-endpoints",
+            json={
+                "id": "proxy",
+                "name": "Proxy",
+                "base_url": "https://llm.example.com/v1",
+                "model": "m",
+                "api_key": "sk-super-secret",
+                "make_default": True,
+            },
+        )
+
+        cfg = load_config()
+        entry = cfg["providers"]["proxy"]
+        env_var = custom_endpoint_key_env("proxy")
+        assert entry["key_env"] == env_var
+        assert "api_key" not in entry
+        assert "api_key" not in cfg["model"]
+        assert get_env_value(env_var) == "sk-super-secret"
+        assert "sk-super-secret" not in yaml.safe_dump(cfg)
+
+    def test_custom_endpoint_edit_without_a_key_keeps_the_stored_one(self):
+        """The panel sends no api_key on an unrelated edit (the field is blank)."""
+        from hermes_cli.config import custom_endpoint_key_env, get_env_value, load_config
+
+        common = {
+            "id": "proxy",
+            "name": "Proxy",
+            "base_url": "https://llm.example.com/v1",
+        }
+        self.client.post(
+            "/api/providers/custom-endpoints",
+            json={**common, "model": "m1", "api_key": "sk-keep-me"},
+        )
+        self.client.post("/api/providers/custom-endpoints", json={**common, "model": "m2"})
+
+        entry = load_config()["providers"]["proxy"]
+        assert entry["model"] == "m2"
+        assert entry["key_env"] == custom_endpoint_key_env("proxy")
+        assert get_env_value(custom_endpoint_key_env("proxy")) == "sk-keep-me"
+
+    def test_custom_endpoint_save_migrates_a_legacy_plaintext_key(self):
+        """Entries written before #69449 get cleaned up on their next save.
+
+        Requiring the user to re-type the key to get it out of config.yaml
+        would leave the plaintext sitting there for anyone who never edits the
+        endpoint again.
+        """
+        from hermes_cli.config import custom_endpoint_key_env, get_env_value, load_config, save_config
+
+        cfg = load_config()
+        cfg["providers"] = {
+            "proxy": {
+                "name": "Proxy",
+                "base_url": "https://llm.example.com/v1",
+                "model": "m",
+                "api_key": "sk-legacy-plaintext",
+                "models": {"m": {}},
+            }
+        }
+        save_config(cfg)
+
+        self.client.post(
+            "/api/providers/custom-endpoints",
+            json={
+                "id": "proxy",
+                "name": "Proxy",
+                "base_url": "https://llm.example.com/v1",
+                "model": "m",
+            },
+        )
+
+        entry = load_config()["providers"]["proxy"]
+        assert "api_key" not in entry
+        assert entry["key_env"] == custom_endpoint_key_env("proxy")
+        assert get_env_value(custom_endpoint_key_env("proxy")) == "sk-legacy-plaintext"
+
+    def test_custom_endpoint_save_leaves_a_hand_written_env_ref_alone(self, monkeypatch):
+        """``api_key: ${MY_KEY}`` is already safe — don't copy it elsewhere.
+
+        load_config() expands env refs, so such an entry looks like a literal
+        secret by the time Save sees it. Migrating it would duplicate the
+        user's secret into a second env var they never asked for.
+        """
+        import yaml
+
+        from hermes_cli.config import custom_endpoint_key_env, get_config_path, get_env_value
+
+        monkeypatch.setenv("MY_PROXY_KEY", "sk-user-managed")
+        get_config_path().write_text(
+            yaml.safe_dump({
+                "providers": {
+                    "proxy": {
+                        "name": "Proxy",
+                        "base_url": "https://llm.example.com/v1",
+                        "model": "m",
+                        "api_key": "${MY_PROXY_KEY}",
+                    }
+                },
+            }),
+            encoding="utf-8",
+        )
+
+        self.client.post(
+            "/api/providers/custom-endpoints",
+            json={
+                "id": "proxy",
+                "name": "Proxy",
+                "base_url": "https://llm.example.com/v1",
+                "model": "m",
+            },
+        )
+
+        raw = yaml.safe_load(get_config_path().read_text(encoding="utf-8"))
+        assert raw["providers"]["proxy"]["api_key"] == "${MY_PROXY_KEY}"
+        assert not get_env_value(custom_endpoint_key_env("proxy"))
+
+    def test_custom_endpoint_blank_api_key_clears_the_credential(self):
+        """An explicitly emptied field means "remove the key", not "keep it"."""
+        from hermes_cli.config import custom_endpoint_key_env, get_env_value, load_config
+
+        common = {
+            "id": "proxy",
+            "name": "Proxy",
+            "base_url": "https://llm.example.com/v1",
+            "model": "m",
+        }
+        self.client.post(
+            "/api/providers/custom-endpoints", json={**common, "api_key": "sk-drop-me"}
+        )
+        self.client.post("/api/providers/custom-endpoints", json={**common, "api_key": ""})
+
+        entry = load_config()["providers"]["proxy"]
+        assert "api_key" not in entry
+        assert "key_env" not in entry
+        assert not get_env_value(custom_endpoint_key_env("proxy"))
+
+    def test_two_endpoints_on_one_host_keep_separate_credentials(self):
+        """Two local servers must not share an .env slot.
+
+        Deriving the env var from the hostname collapses ``127.0.0.1:8000``
+        and ``:8001`` onto one name, so saving the second silently overwrites
+        the first's key.
+        """
+        from hermes_cli.config import custom_endpoint_key_env, get_env_value
+
+        for port, key in ((8000, "sk-first"), (8001, "sk-second")):
+            self.client.post(
+                "/api/providers/custom-endpoints",
+                json={
+                    "id": f"local-{port}",
+                    "name": f"Local {port}",
+                    "base_url": f"http://127.0.0.1:{port}/v1",
+                    "model": "m",
+                    "api_key": key,
+                },
+            )
+
+        assert get_env_value(custom_endpoint_key_env("local-8000")) == "sk-first"
+        assert get_env_value(custom_endpoint_key_env("local-8001")) == "sk-second"
+
+    def test_custom_endpoint_response_reports_a_key_held_in_env(self):
+        """has_api_key must follow key_env, not just a plaintext api_key.
+
+        Reading only ``api_key`` made the panel report "no API key" for every
+        endpoint whose credential had been moved to .env.
+        """
+        resp = self.client.post(
+            "/api/providers/custom-endpoints",
+            json={
+                "id": "proxy",
+                "name": "Proxy",
+                "base_url": "https://llm.example.com/v1",
+                "model": "m",
+                "api_key": "sk-in-env",
+            },
+        )
+
+        endpoint = next(e for e in resp.json()["endpoints"] if e["id"] == "proxy")
+        assert endpoint["has_api_key"] is True
+        assert "sk-in-env" not in (endpoint["api_key_preview"] or "")
+
+    def test_activating_an_endpoint_carries_its_credential_either_way(self):
+        """Activate must work for both key_env and pre-#69449 plaintext entries."""
+        from hermes_cli.config import load_config, save_config
+
+        cfg = load_config()
+        cfg["providers"] = {
+            "legacy": {
+                "name": "Legacy",
+                "base_url": "https://llm.legacy.com/v1",
+                "model": "m",
+                "api_key": "sk-legacy",
+                "models": {"m": {}},
+            },
+            "modern": {
+                "name": "Modern",
+                "base_url": "https://llm.modern.com/v1",
+                "model": "m",
+                "key_env": "MODERN_API_KEY",
+                "models": {"m": {}},
+            },
+        }
+        save_config(cfg)
+
+        self.client.post("/api/providers/custom-endpoints/modern/activate", json={})
+        model_cfg = load_config()["model"]
+        assert model_cfg["key_env"] == "MODERN_API_KEY"
+        assert "api_key" not in model_cfg
+
+        self.client.post("/api/providers/custom-endpoints/legacy/activate", json={})
+        model_cfg = load_config()["model"]
+        assert model_cfg["api_key"] == "sk-legacy"
 
     def test_set_model_main_preserves_base_url_for_named_custom_provider(self):
         """Selecting a named custom endpoint from the Desktop model picker
@@ -4742,6 +5347,18 @@ class TestBuildSchemaFromConfig:
         assert "yolo" not in options, "stale option 'yolo' should not appear"
         assert "deny" not in options, "stale option 'deny' should not appear"
 
+    def test_proxy_schema_warns_dashboard_users_about_lifecycle(self):
+        from hermes_cli.web_server import CONFIG_SCHEMA
+
+        entry = CONFIG_SCHEMA["proxy.enabled"]
+        assert entry["category"] == "security"
+        assert "Docker-only" in entry["description"]
+        assert "hermes egress setup" in entry["description"]
+
+        source_entry = CONFIG_SCHEMA["proxy.credential_source"]
+        assert source_entry["type"] == "select"
+        assert source_entry["options"] == ["env", "bitwarden"]
+
     def test_empty_prefix_produces_correct_keys(self):
         from hermes_cli.web_server import _build_schema_from_config
         test_config = {"model": "test", "nested": {"key": "val"}}
diff --git a/tests/hermes_cli/test_web_server_messaging_profiles.py b/tests/hermes_cli/test_web_server_messaging_profiles.py
index 54420838057..80803b878d5 100644
--- a/tests/hermes_cli/test_web_server_messaging_profiles.py
+++ b/tests/hermes_cli/test_web_server_messaging_profiles.py
@@ -108,11 +108,17 @@ class TestProfileScopedMessagingReads:
             yaml.safe_dump({"platforms": {"telegram": {"enabled": True}}}),
             encoding="utf-8",
         )
-        monkeypatch.setattr(web_server, "get_running_pid", lambda: None)
+        monkeypatch.setattr(web_server, "get_running_pid", lambda *a, **k: None)
+        monkeypatch.setattr(
+            web_server, "get_running_pid_cached", lambda *a, **k: None
+        )
         monkeypatch.setattr(
             web_server,
             "read_runtime_status",
-            lambda: {
+            # Accepts path= : the profile-scoped read now passes the
+            # profile's own gateway_state.json explicitly rather than
+            # relying on process-level HERMES_HOME resolution (#71211).
+            lambda *a, **k: {
                 "gateway_state": "startup_failed",
                 "exit_reason": "all configured messaging platforms failed to connect",
                 "platforms": {},
diff --git a/tests/hermes_cli/test_web_server_profile_unification.py b/tests/hermes_cli/test_web_server_profile_unification.py
index 14141a81536..d0750fac71c 100644
--- a/tests/hermes_cli/test_web_server_profile_unification.py
+++ b/tests/hermes_cli/test_web_server_profile_unification.py
@@ -340,6 +340,54 @@ class TestProfileScopedModel:
         resp = client.get("/api/model/options", params={"profile": "ghost"})
         assert resp.status_code == 404
 
+    def test_model_options_offloads_payload_build_to_threadpool(self, client, monkeypatch):
+        import hermes_cli.web_server as web_server
+
+        calls = []
+
+        async def _fake_run_in_threadpool(func, *args, **kwargs):
+            calls.append((func, args, kwargs))
+            return func(*args, **kwargs)
+
+        monkeypatch.setattr(
+            web_server,
+            "run_in_threadpool",
+            _fake_run_in_threadpool,
+        )
+
+        resp = client.get("/api/model/options")
+        assert resp.status_code == 200
+        assert len(calls) == 1
+
+    def test_model_options_matches_tui_safe_probe_flags(self, client, monkeypatch):
+        calls = []
+
+        monkeypatch.setattr(
+            "hermes_cli.inventory.load_picker_context",
+            lambda: object(),
+        )
+
+        def _fake_build_models_payload(_ctx, **kwargs):
+            calls.append(kwargs)
+            return {"providers": [], "model": "", "provider": ""}
+
+        monkeypatch.setattr(
+            "hermes_cli.inventory.build_models_payload",
+            _fake_build_models_payload,
+        )
+
+        resp = client.get("/api/model/options")
+        assert resp.status_code == 200
+        assert calls[-1]["refresh"] is False
+        assert calls[-1]["probe_custom_providers"] is False
+        assert calls[-1]["probe_current_custom_provider"] is True
+
+        resp = client.get("/api/model/options", params={"refresh": "1"})
+        assert resp.status_code == 200
+        assert calls[-1]["refresh"] is True
+        assert calls[-1]["probe_custom_providers"] is True
+        assert calls[-1]["probe_current_custom_provider"] is False
+
     def test_model_options_hides_unconfigured_providers_by_default(self, client, monkeypatch):
         calls = []
 
@@ -477,7 +525,9 @@ class TestProfileScopedGateway:
 
         seen_homes = []
 
-        def fake_get_running_pid():
+        def fake_get_running_pid(*args, **kwargs):
+            # /api/status?profile= now passes pid_path= explicitly (the TTL
+            # cache would otherwise serve another profile's PID) — accept it.
             seen_homes.append(str(get_hermes_home()))
             return None
 
@@ -488,7 +538,7 @@ class TestProfileScopedGateway:
         monkeypatch.setattr(
             web_server,
             "read_runtime_status",
-            lambda: {"gateway_state": "startup_failed", "platforms": {}},
+            lambda *a, **k: {"gateway_state": "startup_failed", "platforms": {}},
         )
         monkeypatch.setattr(web_server, "_GATEWAY_HEALTH_URL", None)
 
@@ -519,10 +569,14 @@ class TestProfileScopedGateway:
             "updated_at": "2026-06-17T00:00:00+00:00",
         }
         monkeypatch.setattr(web_server, "check_config_version", lambda: (1, 1))
-        monkeypatch.setattr(web_server, "get_running_pid_cached", lambda: None)
-        monkeypatch.setattr(web_server, "read_runtime_status", lambda: runtime)
         monkeypatch.setattr(
-            web_server, "get_runtime_status_running_pid", lambda payload: 4242
+            web_server, "get_running_pid_cached", lambda *a, **k: None
+        )
+        monkeypatch.setattr(web_server, "read_runtime_status", lambda *a, **k: runtime)
+        monkeypatch.setattr(
+            web_server,
+            "get_runtime_status_running_pid",
+            lambda payload, **k: 4242,
         )
         monkeypatch.setattr(web_server, "_GATEWAY_HEALTH_URL", None)
         from gateway.config import Platform
diff --git a/tests/honcho_plugin/test_cli.py b/tests/honcho_plugin/test_cli.py
index 217c37fb3a5..8f94e8394f4 100644
--- a/tests/honcho_plugin/test_cli.py
+++ b/tests/honcho_plugin/test_cli.py
@@ -409,6 +409,9 @@ class TestSetupWizardDeploymentShape:
         monkeypatch.setattr(honcho_cli, "_host_key", lambda: "hermes")
         monkeypatch.setattr(honcho_cli, "_ensure_sdk_installed", lambda: True)
         monkeypatch.setattr(honcho_cli, "_write_config", lambda *a, **k: None)
+        # No network probe / environment sniffing in tests.
+        monkeypatch.setattr(honcho_cli, "_device_login_available", lambda: False)
+        monkeypatch.setattr(honcho_cli, "_headless", lambda: (False, True))
         # Gate detection is mocked so tests control whether the tree runs.
         # None → undetectable; list (possibly empty) → connected platforms.
         gw = None if gateway_platforms is None else list(gateway_platforms)
@@ -791,3 +794,121 @@ class TestMigratePinKey:
         block = {"pinUserPeer": True}
         assert honcho_cli._migrate_pin_key(block) is False
         assert block == {"pinUserPeer": True}
+
+
+class TestCmdSetupDeviceFlow:
+    """The cloud auth-method menu's device-code branch (RFC 8628)."""
+
+    def _run_setup(self, monkeypatch, tmp_path, *, answers, device_available=True,
+                   headless=(False, True), device_result=None, device_error=None):
+        """Run cmd_setup with the device flow stubbed; returns (cfg, calls, prompts)."""
+        import plugins.memory.honcho.cli as honcho_cli
+        import plugins.memory.honcho.oauth_flow as oauth_flow
+        from plugins.memory.honcho.oauth import OAuthCredential
+
+        cfg_path = tmp_path / "config.json"
+        cfg_path.write_text("{}")
+        cfg = {"apiKey": "***"}
+
+        monkeypatch.setattr(honcho_cli, "_read_config", lambda: cfg)
+        monkeypatch.setattr(honcho_cli, "_config_path", lambda: cfg_path)
+        monkeypatch.setattr(honcho_cli, "_local_config_path", lambda: cfg_path)
+        monkeypatch.setattr(honcho_cli, "_host_key", lambda: "hermes")
+        monkeypatch.setattr(honcho_cli, "_ensure_sdk_installed", lambda: True)
+        monkeypatch.setattr(honcho_cli, "_write_config", lambda *a, **k: None)
+        monkeypatch.setattr(honcho_cli, "_gateway_platforms", lambda: [])
+        monkeypatch.setattr(honcho_cli, "_device_login_available", lambda: device_available)
+        monkeypatch.setattr(honcho_cli, "_headless", lambda: headless)
+        monkeypatch.setattr(
+            "hermes_cli.config.load_config", lambda: {"memory": {}}, raising=False,
+        )
+        monkeypatch.setattr(
+            "hermes_cli.config.save_config", lambda c: None, raising=False,
+        )
+
+        class _FakeClientCfg:
+            def resolve_session_name(self):
+                return "hermes-test"
+            workspace_id = "hermes"
+            peer_name = "eri"
+            ai_peer = "hermetika"
+            observation_mode = "directional"
+            write_frequency = "async"
+            recall_mode = "hybrid"
+            session_strategy = "per-session"
+
+        monkeypatch.setattr(
+            "plugins.memory.honcho.client.HonchoClientConfig.from_global_config",
+            lambda host=None: _FakeClientCfg(),
+        )
+        monkeypatch.setattr("plugins.memory.honcho.client.reset_honcho_client", lambda: None)
+        monkeypatch.setattr("plugins.memory.honcho.client.get_honcho_client", lambda hcfg: object())
+
+        calls: list[dict] = []
+        cred = OAuthCredential(
+            access_token="hch-at-x", refresh_token="hch-rt-x", expires_at=9_999_999_999,
+            client_id="hermes-agent", token_endpoint="http://x/oauth/token",
+            consent_peer_name="lyra",
+        )
+
+        def fake_device_flow(**kwargs):
+            calls.append(kwargs)
+            if device_error is not None:
+                raise device_error
+            return device_result or cred
+
+        monkeypatch.setattr(oauth_flow, "authorize_via_device_code", fake_device_flow)
+
+        prompts: list[tuple[str, str | None]] = []
+        answer_iter = iter(answers)
+        def _scripted_prompt(label, default=None, secret=False):
+            prompts.append((label, default))
+            try:
+                # Mirror the real _prompt: blank input falls back to the default.
+                return next(answer_iter) or (default or "")
+            except StopIteration:
+                return default if default is not None else ""
+        monkeypatch.setattr(honcho_cli, "_prompt", _scripted_prompt)
+
+        honcho_cli.cmd_setup(SimpleNamespace())
+        return cfg, calls, prompts
+
+    def test_device_choice_runs_flow_and_stores_grant(self, monkeypatch, tmp_path):
+        cfg, calls, _ = self._run_setup(monkeypatch, tmp_path, answers=["cloud", "device"])
+        assert len(calls) == 1
+        assert calls[0]["apply_config"] is False
+        assert calls[0]["source"] == "hermes-cli"
+        host = cfg["hosts"]["hermes"]
+        assert host["apiKey"] == "hch-at-x"
+        assert host["oauth"]["refreshToken"] == "hch-rt-x"
+        assert host["peerName"] == "lyra"
+
+    def test_headless_defaults_to_device(self, monkeypatch, tmp_path):
+        # Blank answer takes the prompt default, which flips to device on a
+        # remote/no-browser environment.
+        cfg, calls, prompts = self._run_setup(
+            monkeypatch, tmp_path, answers=["cloud", ""], headless=(True, False),
+        )
+        method_prompts = [p for p in prompts if "apikey" in p[0]]
+        assert method_prompts[0][1] == "device"
+        assert len(calls) == 1
+        assert calls[0]["open_url"] is None  # never auto-open a browser headless
+        assert cfg["hosts"]["hermes"]["apiKey"] == "hch-at-x"
+
+    def test_denied_device_flow_aborts_without_grant(self, monkeypatch, tmp_path):
+        from plugins.memory.honcho.oauth_flow import AccessDenied
+
+        cfg, calls, _ = self._run_setup(
+            monkeypatch, tmp_path, answers=["cloud", "device"],
+            device_error=AccessDenied("access_denied", "user denied"),
+        )
+        assert len(calls) == 1
+        assert "apiKey" not in cfg.get("hosts", {}).get("hermes", {})
+
+    def test_device_option_hidden_when_not_advertised(self, monkeypatch, tmp_path):
+        _, calls, prompts = self._run_setup(
+            monkeypatch, tmp_path, answers=["cloud", "device"], device_available=False,
+        )
+        method_prompts = [p for p in prompts if "OAuth or API key" in p[0]]
+        assert method_prompts and method_prompts[0][1] == "oauth"
+        assert calls == []  # 'device' answer falls through to the api-key path
diff --git a/tests/honcho_plugin/test_oauth_flow.py b/tests/honcho_plugin/test_oauth_flow.py
index 99c835ed139..5a63b8fcdd7 100644
--- a/tests/honcho_plugin/test_oauth_flow.py
+++ b/tests/honcho_plugin/test_oauth_flow.py
@@ -24,9 +24,34 @@ class _FakeAS(BaseHTTPRequestHandler):
 
     # Rotation counter shared across requests so refresh returns a new token.
     issued = {"n": 0}
+    # Scripted outcomes for device-grant token polls; "ok" mints, anything else
+    # is returned as a 400 OAuth error code.
+    device_responses: list[str] = []
+    # Last form posted to /oauth/device_authorization, for assertions.
+    last_device_form: dict = {}
+    # Whether AS metadata advertises the device grant.
+    advertise_device = True
+
+    def _send_json(self, status: int, body: dict) -> None:
+        payload = json.dumps(body).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(payload)
 
     def do_GET(self):  # noqa: N802
         parsed = urlparse(self.path)
+        if parsed.path == "/.well-known/oauth-authorization-server":
+            if not _FakeAS.advertise_device:
+                self.send_response(404)
+                self.end_headers()
+                return
+            self._send_json(200, {
+                "grant_types_supported": [
+                    "authorization_code", "refresh_token", oauth_flow.DEVICE_GRANT_TYPE,
+                ],
+            })
+            return
         if parsed.path != "/authorize":
             self.send_response(404)
             self.end_headers()
@@ -50,13 +75,41 @@ class _FakeAS(BaseHTTPRequestHandler):
 
     def do_POST(self):  # noqa: N802
         parsed = urlparse(self.path)
+        length = int(self.headers.get("Content-Length", 0))
+        form = parse_qs(self.rfile.read(length).decode())
+        if parsed.path == "/oauth/device_authorization":
+            _FakeAS.last_device_form = {k: v[0] for k, v in form.items()}
+            base = f"http://{self.server.server_address[0]}:{self.server.server_address[1]}"
+            self._send_json(200, {
+                "device_code": "dev-code-1",
+                "user_code": "ABCD-EFGH",
+                "verification_uri": f"{base}/device",
+                "verification_uri_complete": f"{base}/device?user_code=ABCD-EFGH",
+                "expires_in": 600,
+                "interval": 0,
+            })
+            return
         if parsed.path != "/oauth/token":
             self.send_response(404)
             self.end_headers()
             return
-        length = int(self.headers.get("Content-Length", 0))
-        form = parse_qs(self.rfile.read(length).decode())
         grant_type = form["grant_type"][0]
+        if grant_type == oauth_flow.DEVICE_GRANT_TYPE:
+            outcome = _FakeAS.device_responses.pop(0) if _FakeAS.device_responses else "ok"
+            if outcome != "ok":
+                self._send_json(400, {"error": outcome, "error_description": f"scripted {outcome}"})
+                return
+            self.issued["n"] += 1
+            n = self.issued["n"]
+            self._send_json(200, {
+                "access_token": f"hch-at-{n}",
+                "refresh_token": f"hch-rt-{n}",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "scope": "write",
+                "config": {"peerName": "lyra"},
+            })
+            return
         self.issued["n"] += 1
         n = self.issued["n"]
         body = {
@@ -85,6 +138,9 @@ class _FakeAS(BaseHTTPRequestHandler):
 @pytest.fixture
 def fake_as(monkeypatch):
     _FakeAS.issued["n"] = 0
+    _FakeAS.device_responses = []
+    _FakeAS.last_device_form = {}
+    _FakeAS.advertise_device = True
     server = HTTPServer(("127.0.0.1", 0), _FakeAS)
     port = server.server_address[1]
     thread = threading.Thread(target=server.serve_forever, daemon=True)
@@ -236,6 +292,213 @@ def test_cli_flow_stores_tokens_without_applying_config(tmp_path, fake_as):
     assert cred.consent_peer_name == "lyra"
 
 
+# ── Device authorization grant (RFC 8628): headless / remote-VM path ──
+
+
+class _FakeClock:
+    """Injectable sleep + monotonic pair so poll loops run instantly."""
+
+    def __init__(self):
+        self.t = 0.0
+        self.sleeps: list[float] = []
+
+    def sleep(self, seconds: float) -> None:
+        self.sleeps.append(seconds)
+        self.t += seconds
+
+    def monotonic(self) -> float:
+        return self.t
+
+
+def test_device_endpoint_derived_from_token_url(monkeypatch):
+    monkeypatch.delenv("HONCHO_OAUTH_DEVICE_AUTH_URL", raising=False)
+    monkeypatch.delenv("HONCHO_OAUTH_TOKEN_URL", raising=False)
+    cloud = oauth_flow.resolve_endpoints(environment="production", base_url="https://api.honcho.dev")
+    assert cloud.device_authorization_url == "https://api.honcho.dev/oauth/device_authorization"
+    local = oauth_flow.resolve_endpoints(environment="local", base_url=None)
+    assert local.device_authorization_url == "http://localhost:8000/oauth/device_authorization"
+
+
+def test_device_endpoint_env_override(monkeypatch):
+    monkeypatch.setenv("HONCHO_OAUTH_DEVICE_AUTH_URL", "https://alt.example/oauth/device_authorization")
+    endpoints = oauth_flow.resolve_endpoints(environment="production", base_url=None)
+    assert endpoints.device_authorization_url == "https://alt.example/oauth/device_authorization"
+
+
+def test_supports_device_login_from_metadata(fake_as):
+    endpoints = oauth_flow.resolve_endpoints()
+    assert oauth_flow.supports_device_login(endpoints) is True
+    _FakeAS.advertise_device = False
+    assert oauth_flow.supports_device_login(endpoints) is False
+    # Fail closed on an unreachable host.
+    dead = oauth_flow.OAuthEndpoints(
+        authorize_url="http://127.0.0.1:1/authorize",
+        token_url="http://127.0.0.1:1/oauth/token",
+        client_id="hermes-agent",
+        scope="write",
+    )
+    assert oauth_flow.supports_device_login(dead, timeout=0.2) is False
+
+
+def test_request_device_code_parses_response_and_sends_identity(fake_as):
+    endpoints = oauth_flow.resolve_endpoints()
+    device = oauth_flow.request_device_code(endpoints, source="hermes-cli")
+    assert device.device_code == "dev-code-1"
+    assert device.user_code == "ABCD-EFGH"
+    assert device.verification_uri.endswith("/device")
+    assert device.verification_uri_complete.endswith("?user_code=ABCD-EFGH")
+    assert (device.expires_in, device.interval) == (600, 0)
+    assert _FakeAS.last_device_form["client_id"] == "hermes-desktop"
+    assert _FakeAS.last_device_form["scope"] == "write"
+    assert _FakeAS.last_device_form["source"] == "hermes-cli"
+
+
+def test_request_device_code_defaults_interval_when_omitted(monkeypatch):
+    # RFC 8628 §3.2: interval is optional; a compliant AS may omit it, and the
+    # client must fall back to 5s rather than treating the response as malformed.
+    endpoints = oauth_flow.resolve_endpoints(environment="local")
+    monkeypatch.setattr(
+        oauth,
+        "_http_post_form_status",
+        lambda *a, **k: (200, {
+            "device_code": "dev-code-1",
+            "user_code": "ABCD-EFGH",
+            "verification_uri": "http://localhost:3000/device",
+            "expires_in": 600,
+        }),
+    )
+    device = oauth_flow.request_device_code(endpoints)
+    assert device.interval == 5
+
+
+def test_full_device_flow_pending_then_approved(tmp_path, fake_as):
+    _FakeAS.device_responses = ["authorization_pending", "authorization_pending", "ok"]
+    config_path = tmp_path / "honcho.json"
+    config_path.write_text(json.dumps({"hosts": {"hermes": {"saveMessages": False}}}))
+
+    clock = _FakeClock()
+    cred = oauth_flow.authorize_via_device_code(
+        config_path=config_path,
+        host="hermes",
+        source="hermes-cli",
+        apply_config=False,
+        sleep=clock.sleep,
+    )
+
+    saved = json.loads(config_path.read_text())
+    host = saved["hosts"]["hermes"]
+    assert host["apiKey"] == cred.access_token == "hch-at-1"
+    assert host["oauth"]["refreshToken"] == "hch-rt-1"
+    assert host["oauth"]["clientId"] == "hermes-desktop"
+    assert host["oauth"]["tokenEndpoint"] == oauth_flow.resolve_endpoints().token_url
+    # Wizard-owned settings untouched; consent peer name still surfaced.
+    assert host["saveMessages"] is False
+    assert cred.consent_peer_name == "lyra"
+    assert len(clock.sleeps) == 3  # one wait per poll
+
+
+def test_poll_backs_off_on_slow_down(fake_as):
+    _FakeAS.device_responses = ["slow_down", "slow_down", "ok"]
+    endpoints = oauth_flow.resolve_endpoints()
+    device = oauth_flow.DeviceCode(
+        device_code="dev-code-1", user_code="X", verification_uri="u",
+        verification_uri_complete="u?c", expires_in=600, interval=5,
+    )
+    clock = _FakeClock()
+    grant = oauth_flow.poll_for_token(endpoints, device, sleep=clock.sleep, monotonic=clock.monotonic)
+    assert grant["access_token"] == "hch-at-1"
+    assert clock.sleeps == [5, 10, 15]
+
+
+def test_slow_down_interval_caps_at_60(fake_as):
+    _FakeAS.device_responses = ["slow_down", "ok"]
+    endpoints = oauth_flow.resolve_endpoints()
+    device = oauth_flow.DeviceCode(
+        device_code="dev-code-1", user_code="X", verification_uri="u",
+        verification_uri_complete="u?c", expires_in=600, interval=58,
+    )
+    clock = _FakeClock()
+    oauth_flow.poll_for_token(endpoints, device, sleep=clock.sleep, monotonic=clock.monotonic)
+    assert clock.sleeps == [58, 60]  # 58 + 5 clamps to the 60s cap
+
+
+@pytest.mark.parametrize(
+    ("error", "exc"),
+    [("access_denied", oauth_flow.AccessDenied), ("expired_token", oauth_flow.DeviceCodeExpired)],
+)
+def test_poll_raises_typed_errors(fake_as, error, exc):
+    _FakeAS.device_responses = [error]
+    endpoints = oauth_flow.resolve_endpoints()
+    device = oauth_flow.DeviceCode(
+        device_code="dev-code-1", user_code="X", verification_uri="u",
+        verification_uri_complete="u?c", expires_in=600, interval=0,
+    )
+    clock = _FakeClock()
+    with pytest.raises(exc) as e:
+        oauth_flow.poll_for_token(endpoints, device, sleep=clock.sleep, monotonic=clock.monotonic)
+    assert e.value.error == error
+
+
+def test_poll_times_out_at_deadline(fake_as):
+    _FakeAS.device_responses = ["authorization_pending"] * 10
+    endpoints = oauth_flow.resolve_endpoints()
+    device = oauth_flow.DeviceCode(
+        device_code="dev-code-1", user_code="X", verification_uri="u",
+        verification_uri_complete="u?c", expires_in=3, interval=1,
+    )
+    clock = _FakeClock()
+    with pytest.raises(oauth_flow.AuthorizationTimeout):
+        oauth_flow.poll_for_token(endpoints, device, sleep=clock.sleep, monotonic=clock.monotonic)
+    assert len(clock.sleeps) <= 3  # bounded by the deadline, not the script
+
+
+def test_device_flow_browser_open_is_caller_opt_in(tmp_path, fake_as):
+    config_path = tmp_path / "honcho.json"
+    config_path.write_text(json.dumps({"hosts": {}}))
+    opened: list[str] = []
+    shown: list[oauth_flow.DeviceCode] = []
+
+    oauth_flow.authorize_via_device_code(
+        config_path=config_path, host="hermes",
+        display=shown.append, open_url=opened.append, sleep=lambda s: None,
+    )
+    assert opened == [shown[0].verification_uri_complete]
+
+    # No open_url → nothing opened; the flow still completes.
+    config_path.write_text(json.dumps({"hosts": {}}))
+    cred = oauth_flow.authorize_via_device_code(
+        config_path=config_path, host="hermes", sleep=lambda s: None,
+    )
+    assert cred.access_token
+
+
+def test_callback_page_shows_error_on_denied_consent():
+    server, captured = oauth_flow._bind_loopback_server()
+    port = server.server_address[1]
+    result: dict = {}
+
+    def _deny():
+        for _ in range(50):
+            try:
+                result["resp"] = httpx.get(
+                    f"http://127.0.0.1:{port}/callback"
+                    "?error=access_denied&error_description=user+denied&state=x",
+                    timeout=2,
+                )
+                return
+            except httpx.ConnectError:
+                time.sleep(0.05)
+
+    thread = threading.Thread(target=_deny, daemon=True)
+    thread.start()
+    with pytest.raises(ValueError, match="access_denied.*user denied"):
+        oauth_flow.capture_loopback_code(server, captured, timeout=5)
+    thread.join(timeout=5)
+    page = result["resp"].text
+    assert "Connected" not in page
+    assert "not completed" in page and "access_denied" in page
+
+
 # ── Desktop "Connect" button path: background launcher, status, dispatch ──
 
 
diff --git a/tests/openviking_plugin/test_openviking.py b/tests/openviking_plugin/test_openviking.py
index a2e7de62ea8..c6edbc01054 100644
--- a/tests/openviking_plugin/test_openviking.py
+++ b/tests/openviking_plugin/test_openviking.py
@@ -2,6 +2,7 @@
 
 import json
 import threading
+import time
 from http.server import BaseHTTPRequestHandler, HTTPServer
 from typing import Any, cast
 from urllib.parse import parse_qs, urlparse
@@ -1446,3 +1447,558 @@ class TestOpenVikingMemoryUriBuilder:
             assert f"/memories/{subdir}/mem_" in uri, (
                 f"subdir '{subdir}' not placed correctly in URI: {uri}"
             )
+
+
+# ===================================================================
+# Issue #21130 — OPENVIKING_* not reloaded after /reload
+# ===================================================================
+
+
+class TestEnsureClientReloadsEnv:
+    """Verify /reload picks up new OPENVIKING_* values without a restart (#21130)."""
+
+    def test_ensure_client_rebuilds_when_api_key_changes(self, monkeypatch):
+        constructions = []
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key, account="", user="", agent="hermes"):
+                constructions.append({"endpoint": endpoint, "api_key": api_key,
+                                      "account": account, "user": user, "agent": agent})
+                self.endpoint, self.api_key = endpoint, api_key
+                self.account, self.user, self.agent = account, user, agent
+
+            def health(self):
+                return True
+
+        monkeypatch.setattr("plugins.memory.openviking._VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "http://srv:31933")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "")
+
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+        first = provider._ensure_client()
+        assert first is not None
+        assert first.api_key == ""
+        assert len(constructions) == 1
+
+        # Same env on second call — must reuse cached client (no rebuild).
+        assert provider._ensure_client() is first
+        assert len(constructions) == 1
+
+        # Simulate /reload: env now carries the new API key.
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-fresh")
+        rebuilt = provider._ensure_client()
+        assert rebuilt is not None
+        assert rebuilt is not first
+        assert rebuilt.api_key == "sk-fresh"
+        assert len(constructions) == 2
+
+    def test_ensure_client_rebuilds_when_endpoint_changes(self, monkeypatch):
+        builds = []
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key, **kw):
+                builds.append(endpoint)
+                self.endpoint = endpoint
+
+            def health(self):
+                return True
+
+        monkeypatch.setattr("plugins.memory.openviking._VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "http://a")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "key")
+
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+        provider._ensure_client()
+        provider._ensure_client()  # cached
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "http://b")
+        provider._ensure_client()  # rebuilds
+        assert builds == ["http://a", "http://b"]
+
+    def test_prefetch_rebuilds_client_when_api_key_changes(self, monkeypatch):
+        posts = []
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key, **kw):
+                self.endpoint = endpoint
+                self.api_key = api_key
+
+            def health(self):
+                return True
+
+            def post(self, path, payload=None, **kwargs):
+                posts.append((self.api_key, path, payload or {}))
+                return {
+                    "result": {
+                        "memories": [
+                            {
+                                "uri": "viking://user/default/memories/pref.md",
+                                "abstract": f"memory from {self.api_key or 'anonymous'}",
+                                "score": 0.9,
+                                "level": 2,
+                            }
+                        ],
+                        "resources": [],
+                    }
+                }
+
+        monkeypatch.setattr("plugins.memory.openviking._VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "http://srv:31933")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-old")
+        monkeypatch.setenv("OPENVIKING_RECALL_PREFER_ABSTRACT", "true")
+
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+        provider._session_id = "session-1"
+
+        first = provider.prefetch("What should OpenViking recall?", session_id="session-1")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-fresh")
+        second = provider.prefetch("What should OpenViking recall?", session_id="session-1")
+
+        assert "memory from sk-old" in first
+        assert "memory from sk-fresh" in second
+        assert [call[0] for call in posts] == ["sk-old", "sk-fresh"]
+        assert [call[1] for call in posts] == ["/api/v1/search/search", "/api/v1/search/search"]
+        assert posts[0][2]["limit"] == posts[1][2]["limit"]
+        assert "top_k" not in posts[0][2]
+
+    def test_ensure_client_returns_none_when_health_fails(self, monkeypatch):
+        class _StubClient:
+            def __init__(self, *a, **kw):
+                pass
+
+            def health(self):
+                return False
+
+        monkeypatch.setattr("plugins.memory.openviking._VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "http://dead")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "")
+
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+        assert provider._ensure_client() is None
+        assert provider._client is None
+
+    def test_handle_tool_call_reconnects_after_startup_health_failure(self, monkeypatch):
+        instances = []
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+                self.endpoint = endpoint
+                self.api_key = api_key
+                self.account = account
+                self.user = user
+                self.agent = agent
+                self.index = len(instances)
+                self.posts = []
+                instances.append(self)
+
+            def health(self):
+                return self.index > 0
+
+            def post(self, path, payload=None, **kwargs):
+                self.posts.append((path, payload or {}))
+                return {"result": {"written_bytes": 11}}
+
+        monkeypatch.setattr("plugins.memory.openviking._VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "https://openviking.example")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-test")
+
+        provider = OpenVikingMemoryProvider()
+        provider.initialize("session-1")
+
+        assert provider._client is None
+
+        out = json.loads(provider.handle_tool_call(
+            "viking_remember",
+            {"content": "stable fact"},
+        ))
+
+        assert out["status"] == "stored"
+        assert len(instances) == 2
+        assert instances[1].posts[0][0] == "/api/v1/content/write"
+        assert instances[1].posts[0][1]["content"] == "stable fact"
+        assert instances[1].posts[0][1]["mode"] == "create"
+        assert instances[1].posts[0][1]["uri"].startswith(
+            "viking://user/peers/hermes/memories/"
+        )
+
+    def test_concurrent_refresh_does_not_return_stale_client(self, monkeypatch):
+        refresh_entered = threading.Event()
+        release_refresh = threading.Event()
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+                self.endpoint = endpoint
+                self.api_key = api_key
+
+            def health(self):
+                if self.endpoint == "https://new.example":
+                    refresh_entered.set()
+                    assert release_refresh.wait(2.0)
+                    return False
+                return True
+
+        monkeypatch.setattr(openviking_plugin, "_VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "https://new.example")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-new")
+        monkeypatch.delenv("OPENVIKING_ACCOUNT", raising=False)
+        monkeypatch.delenv("OPENVIKING_USER", raising=False)
+        monkeypatch.delenv("OPENVIKING_AGENT", raising=False)
+
+        provider = OpenVikingMemoryProvider()
+        stale_client = _StubClient("https://old.example", "sk-old")
+        provider._endpoint = stale_client.endpoint
+        provider._api_key = stale_client.api_key
+        provider._account = ""
+        provider._user = ""
+        provider._agent = "hermes"
+        provider._client = stale_client
+        provider._env_refresh_enabled = True
+
+        results = {}
+        errors = []
+        second_started = threading.Event()
+        second_done = threading.Event()
+
+        def refresh_client(name, *, started=None, done=None):
+            if started is not None:
+                started.set()
+            try:
+                results[name] = provider._ensure_client()
+            except BaseException as exc:  # pragma: no cover - surfaced below
+                errors.append(exc)
+            finally:
+                if done is not None:
+                    done.set()
+
+        first = threading.Thread(target=refresh_client, args=("first",))
+        first.start()
+        assert refresh_entered.wait(2.0)
+
+        second = threading.Thread(
+            target=refresh_client,
+            args=("second",),
+            kwargs={"started": second_started, "done": second_done},
+        )
+        second.start()
+        assert second_started.wait(2.0)
+        completed_during_refresh = second_done.wait(0.2)
+
+        release_refresh.set()
+        first.join(timeout=2.0)
+        second.join(timeout=2.0)
+
+        assert not first.is_alive()
+        assert not second.is_alive()
+        assert errors == []
+        assert completed_during_refresh is False
+        assert results == {"first": None, "second": None}
+        assert all(client is not stale_client for client in results.values())
+
+    def test_handle_tool_call_after_reload_to_local_endpoint_starts_runtime_recovery(
+        self,
+        tmp_path,
+        monkeypatch,
+    ):
+        from hermes_cli import config as hermes_config
+
+        known_hermes_env = set(hermes_config.OPTIONAL_ENV_VARS) | hermes_config._EXTRA_ENV_KEYS
+        openviking_tenant_env = {
+            "OPENVIKING_ENDPOINT",
+            "OPENVIKING_API_KEY",
+            "OPENVIKING_ACCOUNT",
+            "OPENVIKING_USER",
+            "OPENVIKING_AGENT",
+        }
+        for key in known_hermes_env | openviking_tenant_env:
+            monkeypatch.delenv(key, raising=False)
+
+        hermes_home = tmp_path / "hermes-home"
+        hermes_home.mkdir()
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+        env_path = hermes_home / ".env"
+        env_path.write_text(
+            "OPENVIKING_ENDPOINT=https://openviking.example\n"
+            "OPENVIKING_API_KEY=sk-old\n",
+            encoding="utf-8",
+        )
+        assert hermes_config.reload_env() >= 1
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+                self.endpoint = endpoint
+                self.api_key = api_key
+                self.posts = []
+
+            def health(self):
+                return self.endpoint == "https://openviking.example"
+
+            def post(self, path, payload=None, **kwargs):
+                self.posts.append((path, payload or {}))
+                return {"result": {"written_bytes": 11}}
+
+        monkeypatch.setattr(openviking_plugin, "_VikingClient", _StubClient)
+        provider = OpenVikingMemoryProvider()
+        provider.initialize("session-1")
+
+        assert provider._client is not None
+        assert provider._client.endpoint == "https://openviking.example"
+
+        env_path.write_text(
+            "OPENVIKING_ENDPOINT=http://127.0.0.1:31933\n"
+            "OPENVIKING_API_KEY=\n",
+            encoding="utf-8",
+        )
+        assert hermes_config.reload_env() >= 1
+
+        start_calls = []
+        waiter_calls = []
+        monkeypatch.setattr(
+            openviking_plugin,
+            "_start_local_openviking_server",
+            lambda endpoint: start_calls.append(endpoint) or (True, "started"),
+        )
+        monkeypatch.setattr(
+            provider,
+            "_start_runtime_openviking_waiter",
+            lambda **kwargs: waiter_calls.append(kwargs),
+            raising=False,
+        )
+
+        out = json.loads(provider.handle_tool_call(
+            "viking_remember",
+            {"content": "stable fact"},
+        ))
+
+        assert "not connected" in out["error"]
+        assert provider._client is None
+        assert start_calls == ["http://127.0.0.1:31933"]
+        assert len(waiter_calls) == 1
+
+    def test_repeated_access_while_local_runtime_starts_does_not_spawn_again(self, monkeypatch):
+        class _AliveThread:
+            def is_alive(self):
+                return True
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+                self.endpoint = endpoint
+
+            def health(self):
+                return False
+
+        monkeypatch.setattr(openviking_plugin, "_VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "http://127.0.0.1:31933")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "")
+
+        start_calls = []
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+        monkeypatch.setattr(
+            openviking_plugin,
+            "_start_local_openviking_server",
+            lambda endpoint: start_calls.append(endpoint) or (True, "started"),
+        )
+        monkeypatch.setattr(
+            provider,
+            "_start_runtime_openviking_waiter",
+            lambda **kwargs: setattr(provider, "_runtime_start_thread", _AliveThread()),
+            raising=False,
+        )
+
+        assert provider._ensure_client() is None
+        assert provider._ensure_client() is None
+
+        assert start_calls == ["http://127.0.0.1:31933"]
+
+    def test_concurrent_local_runtime_recovery_starts_once(self, monkeypatch):
+        class _AliveThread:
+            def is_alive(self):
+                return True
+
+        provider = OpenVikingMemoryProvider()
+        provider._endpoint = "http://127.0.0.1:31933"
+        start_calls = []
+        start_lock = threading.Lock()
+        first_start_entered = threading.Event()
+        release_start = threading.Event()
+        second_started = threading.Event()
+
+        def start_local(endpoint):
+            with start_lock:
+                start_calls.append(endpoint)
+            first_start_entered.set()
+            release_start.wait(timeout=2)
+            return True, "started"
+
+        monkeypatch.setattr(openviking_plugin, "_start_local_openviking_server", start_local)
+        monkeypatch.setattr(
+            provider,
+            "_start_runtime_openviking_waiter",
+            lambda **kwargs: setattr(provider, "_runtime_start_thread", _AliveThread()),
+            raising=False,
+        )
+
+        errors = []
+
+        def recover(*, started=None):
+            if started is not None:
+                started.set()
+            try:
+                provider._handle_runtime_openviking_unreachable()
+            except BaseException as exc:  # pragma: no cover - surfaced below
+                errors.append(exc)
+
+        threads = [
+            threading.Thread(target=recover, name="openviking-recovery-1"),
+            threading.Thread(
+                target=recover,
+                kwargs={"started": second_started},
+                name="openviking-recovery-2",
+            ),
+        ]
+        for thread in threads:
+            thread.start()
+
+        assert first_start_entered.wait(timeout=2)
+        assert second_started.wait(timeout=2)
+        release_start.set()
+        for thread in threads:
+            thread.join(timeout=2)
+            assert not thread.is_alive()
+
+        assert errors == []
+        assert start_calls == ["http://127.0.0.1:31933"]
+
+    def test_handle_tool_call_uses_ensure_client(self, monkeypatch):
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+
+        class _StubClient:
+            def __init__(self, *a, **kw):
+                pass
+
+            def health(self):
+                return False
+
+        monkeypatch.setattr("plugins.memory.openviking._VikingClient", _StubClient)
+
+        out = provider.handle_tool_call("viking_search", {"query": "x"})
+        assert "not connected" in out.lower()
+
+
+class TestEnsureClientFailureHardening:
+    """Follow-up hardening on top of #21130: failed-config cooldown and
+    torn-identity-safe connection snapshots."""
+
+    def test_failed_config_probes_once_then_cools_down(self, monkeypatch):
+        """A down endpoint must not pay a health probe on every access."""
+        probes = []
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+                self.endpoint = endpoint
+
+            def health(self):
+                probes.append(self.endpoint)
+                return False
+
+        monkeypatch.setattr(openviking_plugin, "_VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "https://down.example")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-x")
+
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+
+        assert provider._ensure_client() is None
+        assert provider._ensure_client() is None
+        assert provider._ensure_client() is None
+        # Only the first access probes; the rest hit the cooldown.
+        assert len(probes) == 1
+
+    def test_failed_config_retries_after_cooldown(self, monkeypatch):
+        probes = []
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+                self.endpoint = endpoint
+
+            def health(self):
+                probes.append(self.endpoint)
+                return len(probes) > 1  # down on first probe, up on retry
+
+        monkeypatch.setattr(openviking_plugin, "_VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "https://flaky.example")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-x")
+
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+
+        assert provider._ensure_client() is None
+        # Simulate the cooldown elapsing.
+        failed_key, _failed_at = provider._failed_refresh
+        provider._failed_refresh = (
+            failed_key,
+            time.monotonic() - openviking_plugin._FAILED_CONFIG_RETRY_COOLDOWN_SECONDS - 1,
+        )
+        assert provider._ensure_client() is not None
+        assert len(probes) == 2
+        assert provider._failed_refresh is None
+
+    def test_failed_config_retries_immediately_on_config_change(self, monkeypatch):
+        probes = []
+
+        class _StubClient:
+            def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+                self.endpoint = endpoint
+
+            def health(self):
+                probes.append(self.endpoint)
+                return self.endpoint == "https://up.example"
+
+        monkeypatch.setattr(openviking_plugin, "_VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "https://down.example")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-x")
+
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+
+        assert provider._ensure_client() is None
+        # /reload lands a new endpoint: cooldown must not block the new config.
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "https://up.example")
+        client = provider._ensure_client()
+        assert client is not None
+        assert client.endpoint == "https://up.example"
+
+    def test_conn_snapshot_published_only_on_healthy(self, monkeypatch):
+        class _StubClient:
+            def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+                self.endpoint = endpoint
+
+            def health(self):
+                return self.endpoint == "https://up.example"
+
+        monkeypatch.setattr(openviking_plugin, "_VikingClient", _StubClient)
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "https://up.example")
+        monkeypatch.setenv("OPENVIKING_API_KEY", "sk-good")
+        monkeypatch.delenv("OPENVIKING_ACCOUNT", raising=False)
+        monkeypatch.delenv("OPENVIKING_USER", raising=False)
+        monkeypatch.delenv("OPENVIKING_AGENT", raising=False)
+
+        provider = OpenVikingMemoryProvider()
+        provider._env_refresh_enabled = True
+        assert provider._ensure_client() is not None
+        healthy_snapshot = provider._conn_snapshot
+        assert healthy_snapshot is not None
+        assert healthy_snapshot[0] == "https://up.example"
+        assert healthy_snapshot[1] == "sk-good"
+
+        # A failed refresh must NOT advance the snapshot: background writers
+        # (_new_client) keep targeting the last identity that passed health.
+        monkeypatch.setenv("OPENVIKING_ENDPOINT", "https://down.example")
+        assert provider._ensure_client() is None
+        assert provider._conn_snapshot == healthy_snapshot
+        built = provider._new_client()
+        assert built.endpoint == "https://up.example"
diff --git a/tests/plugins/image_gen/test_openai_codex_provider.py b/tests/plugins/image_gen/test_openai_codex_provider.py
index 338ea97418a..2ae89435b5d 100644
--- a/tests/plugins/image_gen/test_openai_codex_provider.py
+++ b/tests/plugins/image_gen/test_openai_codex_provider.py
@@ -149,9 +149,10 @@ class TestGenerate:
         assert captured["input"][0]["type"] == "message"
         assert captured["input"][0]["role"] == "user"
         assert captured["input"][0]["content"][0]["type"] == "input_text"
-        assert captured["tool_choice"]["type"] == "allowed_tools"
-        assert captured["tool_choice"]["mode"] == "required"
-        assert captured["tool_choice"]["tools"] == [{"type": "image_generation"}]
+        # Regression for #19505: the Codex backend 400s on every tool_choice
+        # shape we have for the hosted ``image_generation`` tool, so the
+        # provider must omit tool_choice entirely and rely on instructions.
+        assert "tool_choice" not in captured
 
         tool = captured["tools"][0]
         assert tool["type"] == "image_generation"
@@ -308,60 +309,73 @@ class TestGenerate:
         assert result["error_type"] == "api_error"
         assert "cloudflare 403" in result["error"]
 
-    def test_unsupported_image_tool_returns_capability_error(self, provider, monkeypatch):
+    def test_tool_choice_400_surfaces_verbatim_not_as_capability_error(
+        self, provider, monkeypatch
+    ):
+        """The tool_choice 400 must NOT be reported as an account limitation.
+
+        Regression for #19505 / #49008 / #31335: a previous version classified
+        this exact request-shape rejection as "Image generation is not enabled
+        for the current Codex account", telling every affected user to abandon
+        Codex over a bug in our own payload. The wire error must reach the user
+        unedited so it stays diagnosable.
+
+        Drives the REAL httpx boundary (not a mocked ``_collect_image_b64``) so
+        the classification path is actually exercised — mocking the collector
+        would skip the code under test entirely.
+        """
+        import httpx
+
         monkeypatch.setattr(codex_plugin, "_read_codex_access_token", lambda: "codex-token")
 
-        def _unsupported(*args, **kwargs):
-            raise codex_plugin.CodexImageGenerationUnsupportedError(
-                "Tool choice 'image_generation' not found in 'tools' parameter."
-            )
+        body = json.dumps({
+            "error": {
+                "message": "Tool choice 'image_generation' not found in 'tools' parameter.",
+                "type": "invalid_request_error",
+                "param": "tool_choice",
+            }
+        })
 
-        monkeypatch.setattr(codex_plugin, "_collect_image_b64", _unsupported)
+        def _handler(request):
+            return httpx.Response(400, text=body, request=request)
+
+        real_client = httpx.Client
+        monkeypatch.setattr(
+            httpx,
+            "Client",
+            lambda *args, **kwargs: real_client(
+                transport=httpx.MockTransport(_handler),
+                headers=kwargs.get("headers"),
+                timeout=kwargs.get("timeout"),
+            ),
+        )
 
         result = provider.generate("a cat")
 
         assert result["success"] is False
-        assert result["error_type"] == "capability_unsupported"
-        assert "current Codex account" in result["error"]
-        assert "OpenAI API key, FAL, or xAI" in result["error"]
+        assert result["error_type"] == "api_error"
+        assert "HTTP 400" in result["error"]
+        assert "tools' parameter" in result["error"]
+        # The account-entitlement misdiagnosis must not come back.
+        assert "not enabled for the current Codex account" not in result["error"]
+        assert result["error_type"] != "capability_unsupported"
 
 
-class TestCapabilityErrorDetection:
-    @pytest.mark.parametrize(
-        "body",
-        [
-            "Tool choice 'image_generation' not found in 'tools' parameter.",
-            '{"error":{"message":"Tool choice \'image_generation\' not found in \'tools\' parameter."}}',
-        ],
-    )
-    def test_detects_exact_codex_image_tool_rejection(self, body):
-        assert codex_plugin._is_image_generation_unsupported_error(400, body) is True
+class TestRequestShape:
+    def test_payload_omits_tool_choice(self):
+        """Codex rejects every tool_choice shape for hosted image_generation."""
+        payload = codex_plugin._build_responses_payload(
+            prompt="a red circle",
+            size="1024x1024",
+            quality="low",
+        )
+        assert "tool_choice" not in payload
+        # The hosted tool itself is still requested, and instructions do the steering.
+        assert payload["tools"][0]["type"] == "image_generation"
+        assert payload["instructions"]
 
-    @pytest.mark.parametrize(
-        ("status_code", "body"),
-        [
-            (401, "Tool choice 'image_generation' not found in 'tools' parameter."),
-            (400, "Tool choice 'web_search' not found in 'tools' parameter."),
-            (400, "The image_generation request was rejected by moderation."),
-            (500, "Tool choice 'image_generation' not found in 'tools' parameter."),
-        ],
-    )
-    def test_does_not_misclassify_other_failures(self, status_code, body):
-        assert codex_plugin._is_image_generation_unsupported_error(status_code, body) is False
-
-    def test_does_not_match_error_message_with_extra_text(self):
-        body = json.dumps({
-            "error": {
-                "message": (
-                    "Tool choice 'image_generation' not found in 'tools' parameter "
-                    "because the request is malformed."
-                )
-            }
-        })
-
-        assert codex_plugin._is_image_generation_unsupported_error(400, body) is False
-
-    def test_collect_classifies_exact_http_error_after_large_metadata(self, monkeypatch):
+    def test_http_error_body_is_truncated_but_preserved(self, monkeypatch):
+        """A large error body is capped at 500 chars and still surfaced."""
         import httpx
 
         body = json.dumps({
@@ -385,7 +399,7 @@ class TestCapabilityErrorDetection:
             ),
         )
 
-        with pytest.raises(codex_plugin.CodexImageGenerationUnsupportedError):
+        with pytest.raises(RuntimeError, match="HTTP 400") as excinfo:
             codex_plugin._collect_image_b64(
                 "codex-token",
                 prompt="a cat",
@@ -393,6 +407,11 @@ class TestCapabilityErrorDetection:
                 quality="low",
             )
 
+        message = str(excinfo.value)
+        # Body is capped, but the actionable wire message still reaches the user.
+        assert "tools' parameter" in message
+        assert len(message) < len(body)
+
 
 # ── Plugin entry point ──────────────────────────────────────────────────────
 
diff --git a/tests/plugins/memory/test_hindsight_provider.py b/tests/plugins/memory/test_hindsight_provider.py
index 5cd485d4c1a..0d420a5e995 100644
--- a/tests/plugins/memory/test_hindsight_provider.py
+++ b/tests/plugins/memory/test_hindsight_provider.py
@@ -22,6 +22,7 @@ from plugins.memory.hindsight import (
     REFLECT_SCHEMA,
     RETAIN_SCHEMA,
     _load_config,
+    _load_simple_env,
     _build_embedded_profile_env,
     _normalize_observation_scopes,
     _normalize_retain_tags,
@@ -1819,3 +1820,62 @@ def test_save_config_sets_owner_only_permissions(tmp_path):
     assert config_file.exists()
     mode = stat.S_IMODE(config_file.stat().st_mode)
     assert mode == 0o600, f"Expected 0o600 (owner-only), got {oct(mode)}"
+
+
+class TestLoadSimpleEnv:
+    def test_bom_first_key_is_recognized(self, tmp_path):
+        """A Notepad-edited .env carries a BOM; the first key must still parse
+        instead of becoming '\ufeffHINDSIGHT_LLM_API_KEY'."""
+        env_path = tmp_path / ".env"
+        env_path.write_bytes("HINDSIGHT_LLM_API_KEY=sk-test\n".encode("utf-8"))
+        values = _load_simple_env(env_path)
+        assert values.get("HINDSIGHT_LLM_API_KEY") == "sk-test"
+
+    def test_non_ascii_values_read_intact(self, tmp_path):
+        env_path = tmp_path / ".env"
+        env_path.write_bytes("PROXY_NOTE=café-zürich-完了\n".encode("utf-8"))
+        values = _load_simple_env(env_path)
+        assert values["PROXY_NOTE"] == "café-zürich-完了"
+
+
+class TestPostSetupEnvEncoding:
+    def _run_cloud_post_setup(self, tmp_path, monkeypatch):
+        """Drive post_setup through the cloud path with piped stdin."""
+        import io
+        import shutil as shutil_mod
+
+        monkeypatch.setattr("hermes_cli.memory_setup._curses_select",
+                            lambda *a, **kw: 0)  # cloud mode
+        monkeypatch.setattr("hermes_cli.config.save_config", lambda c: None)
+        monkeypatch.setattr(shutil_mod, "which", lambda *_: None)  # skip uv install
+        # First line: API key prompt (readline). Second line: API URL (input).
+        monkeypatch.setattr(sys, "stdin", io.StringIO("sk-new\n\n"))
+
+        provider = HindsightMemoryProvider()
+        provider.post_setup(str(tmp_path), {"memory": {}})
+
+    def test_bom_first_key_updated_in_place(self, tmp_path, monkeypatch):
+        """The setup writer reads the existing .env BOM-tolerantly, so a
+        BOM'd first key is matched and rewritten, not duplicated."""
+        env_path = tmp_path / ".env"
+        env_path.write_bytes("HINDSIGHT_API_KEY=old\n".encode("utf-8"))
+
+        self._run_cloud_post_setup(tmp_path, monkeypatch)
+
+        content = env_path.read_text(encoding="utf-8")
+        assert content.count("HINDSIGHT_API_KEY=") == 1
+        assert "HINDSIGHT_API_KEY=sk-new" in content
+        assert "old" not in content
+        assert "" not in content
+
+    def test_non_ascii_lines_survive_round_trip(self, tmp_path, monkeypatch):
+        """Unrelated non-ASCII .env content must be copied through as UTF-8
+        (the locale codec would crash or mangle it on Windows)."""
+        env_path = tmp_path / ".env"
+        env_path.write_bytes("PROXY_NOTE=café-zürich-完了\n".encode("utf-8"))
+
+        self._run_cloud_post_setup(tmp_path, monkeypatch)
+
+        content = env_path.read_text(encoding="utf-8")
+        assert "PROXY_NOTE=café-zürich-完了" in content
+        assert "HINDSIGHT_API_KEY=sk-new" in content
diff --git a/tests/plugins/memory/test_mem0_setup.py b/tests/plugins/memory/test_mem0_setup.py
index cbe8353a48b..beebdc348e7 100644
--- a/tests/plugins/memory/test_mem0_setup.py
+++ b/tests/plugins/memory/test_mem0_setup.py
@@ -11,6 +11,7 @@ from plugins.memory.mem0._setup import (
     parse_flags,
     build_oss_config,
     _write_env,
+    _prompt_api_key,
     post_setup,
     _check_qdrant_path,
     _check_ollama,
@@ -181,6 +182,48 @@ class TestWriteEnv:
         assert "OTHER=keep" in content
         assert "old" not in content
 
+    def test_preserves_non_ascii_existing_lines(self, tmp_path):
+        """Existing non-ASCII .env content must survive the read-modify-write
+        as UTF-8 (the locale codec would crash/mangle it on Windows)."""
+        env_path = tmp_path / ".env"
+        env_path.write_bytes("PROXY_NOTE=café-zürich-完了\n".encode("utf-8"))
+        _write_env(env_path, {"OPENAI_API_KEY": "sk-test"})
+        content = env_path.read_text(encoding="utf-8")
+        assert "PROXY_NOTE=café-zürich-完了" in content
+        assert "OPENAI_API_KEY=sk-test" in content
+
+    def test_updates_first_key_with_bom(self, tmp_path):
+        """A Notepad-edited .env carries a BOM; the first key must still be
+        matched/updated in place, not duplicated."""
+        env_path = tmp_path / ".env"
+        env_path.write_bytes("OPENAI_API_KEY=old\n".encode("utf-8"))
+        _write_env(env_path, {"OPENAI_API_KEY": "new"})
+        content = env_path.read_text(encoding="utf-8")
+        assert content.count("OPENAI_API_KEY=") == 1
+        assert "OPENAI_API_KEY=new" in content
+
+
+class TestPromptApiKey:
+
+    def test_existing_key_found_behind_bom(self, tmp_path, monkeypatch):
+        """The masked-current-value lookup must see a key on the BOM'd first
+        line of a Notepad-edited .env instead of prompting from scratch."""
+        env_path = tmp_path / ".env"
+        env_path.write_bytes("OPENAI_API_KEY=sk-existing\n".encode("utf-8"))
+        monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+        prompts: list[str] = []
+
+        def _fake_getpass(prompt):
+            prompts.append(prompt)
+            return ""
+
+        monkeypatch.setattr("plugins.memory.mem0._setup.getpass.getpass", _fake_getpass)
+        _prompt_api_key("OpenAI", "OPENAI_API_KEY", str(tmp_path))
+
+        assert len(prompts) == 1
+        assert "current: ...ting" in prompts[0]
+
 
 class TestPostSetup:
 
diff --git a/tests/plugins/memory/test_openviking_provider.py b/tests/plugins/memory/test_openviking_provider.py
index df2e5632be8..914dc062124 100644
--- a/tests/plugins/memory/test_openviking_provider.py
+++ b/tests/plugins/memory/test_openviking_provider.py
@@ -1,6 +1,7 @@
 import json
 import os
 import stat
+import threading
 import time
 import zipfile
 from types import SimpleNamespace
@@ -82,6 +83,39 @@ def _allow_setup_validation(monkeypatch, *, root_access: bool = False):
     )
 
 
+def test_openviking_provider_config_loader_uses_readonly_config(monkeypatch):
+    import hermes_cli.config as config_mod
+
+    calls = []
+    backing_config = {
+        "memory": {
+            "openviking": {
+                "endpoint": "http://127.0.0.1:19472",
+                "api_key": "test-key",
+            }
+        }
+    }
+
+    def load_config_readonly():
+        calls.append("readonly")
+        return backing_config
+
+    def load_config():
+        raise AssertionError("OpenViking config loader should use readonly config")
+
+    monkeypatch.setattr(config_mod, "load_config_readonly", load_config_readonly)
+    monkeypatch.setattr(config_mod, "load_config", load_config)
+
+    config = openviking_module._load_hermes_openviking_config()
+
+    assert calls == ["readonly"]
+    assert config == {
+        "endpoint": "http://127.0.0.1:19472",
+        "api_key": "test-key",
+    }
+    assert config is not backing_config["memory"]["openviking"]
+
+
 @pytest.mark.skipif(os.name == "nt", reason="POSIX file modes")
 def test_openviking_env_writer_restricts_file_permissions(tmp_path):
     env_path = tmp_path / ".env"
@@ -91,6 +125,51 @@ def test_openviking_env_writer_restricts_file_permissions(tmp_path):
     assert stat.S_IMODE(env_path.stat().st_mode) == 0o600
 
 
+def test_openviking_env_writer_strips_embedded_newlines_in_values(tmp_path):
+    # A secret pasted with an embedded CR/LF must not spill onto a new line,
+    # or the round-trip re-parses the tail as a separate KEY=VALUE entry and
+    # injects an arbitrary variable into the persisted credentials file.
+    env_path = tmp_path / ".env"
+
+    openviking_module._write_env_vars(
+        env_path,
+        {"OPENVIKING_API_KEY": "good\nINJECTED_KEY=attacker"},
+    )
+
+    lines = env_path.read_text(encoding="utf-8").splitlines()
+    assert lines == ["OPENVIKING_API_KEY=goodINJECTED_KEY=attacker"]
+    # No injected line means a follow-up read sees no rogue key.
+    parsed = dict(line.split("=", 1) for line in lines if "=" in line)
+    assert set(parsed) == {"OPENVIKING_API_KEY"}
+    assert "INJECTED_KEY" not in parsed
+
+
+def test_openviking_env_writer_strips_splitline_separators_and_nul(tmp_path):
+    env_path = tmp_path / ".env"
+
+    openviking_module._write_env_vars(
+        env_path,
+        {"OPENVIKING_API_KEY": "good\u2028INJECTED_KEY=attacker\x00tail"},
+    )
+
+    lines = env_path.read_text(encoding="utf-8").splitlines()
+    assert lines == ["OPENVIKING_API_KEY=goodINJECTED_KEY=attackertail"]
+
+
+def test_openviking_env_writer_strips_newlines_when_updating_existing_key(tmp_path):
+    env_path = tmp_path / ".env"
+    env_path.write_text("OPENVIKING_API_KEY=old\n", encoding="utf-8")
+
+    openviking_module._write_env_vars(
+        env_path,
+        {"OPENVIKING_API_KEY": "new\r\nROGUE=1"},
+    )
+
+    lines = env_path.read_text(encoding="utf-8").splitlines()
+    assert lines == ["OPENVIKING_API_KEY=newROGUE=1"]
+    assert all(not line.startswith("ROGUE=") for line in lines)
+
+
 @pytest.mark.skipif(os.name == "nt", reason="POSIX file modes")
 def test_ovcli_config_writer_restricts_file_permissions(tmp_path):
     config_path = tmp_path / "ovcli.conf"
@@ -875,6 +954,40 @@ def test_initialize_autostarts_local_openviking_in_background_when_runtime_healt
     assert any("starting in the background" in message for message in statuses)
 
 
+def test_initialize_emits_starting_status_before_runtime_waiter_can_attach(monkeypatch):
+    _clear_openviking_env(monkeypatch)
+    monkeypatch.setenv("OPENVIKING_ENDPOINT", "http://127.0.0.1:1934")
+
+    class FakeVikingClient:
+        def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+            assert endpoint == "http://127.0.0.1:1934"
+
+        def health(self):
+            return False
+
+    monkeypatch.setattr(openviking_module, "_VikingClient", FakeVikingClient)
+    monkeypatch.setattr(
+        openviking_module,
+        "_start_local_openviking_server",
+        lambda endpoint: (True, "started"),
+    )
+
+    provider = OpenVikingMemoryProvider()
+    statuses = []
+
+    def start_waiter(*, endpoint, status_callback=None, warning_callback=None):
+        assert endpoint == "http://127.0.0.1:1934"
+        assert callable(status_callback)
+        status_callback("Local OpenViking server is reachable; OpenViking memory is active.")
+
+    monkeypatch.setattr(provider, "_start_runtime_openviking_waiter", start_waiter, raising=False)
+
+    provider.initialize("session-1", platform="cli", status_callback=statuses.append)
+
+    assert "starting in the background" in statuses[0]
+    assert "memory is active" in statuses[1]
+
+
 def test_runtime_openviking_waiter_attaches_client_after_health_recovers(monkeypatch):
     _clear_openviking_env(monkeypatch)
     wait_calls = []
@@ -913,13 +1026,58 @@ def test_runtime_openviking_waiter_attaches_client_after_health_recovers(monkeyp
     assert provider._client is not None
     assert provider._client.endpoint == "http://127.0.0.1:1934"
     assert provider._client.api_key == "secret"
-    assert wait_calls == [(
-        "http://127.0.0.1:1934",
-        {"timeout_seconds": openviking_module._LOCAL_OPENVIKING_AUTOSTART_TIMEOUT},
-    )]
+    assert len(wait_calls) == 1
+    endpoint, wait_kwargs = wait_calls[0]
+    assert endpoint == "http://127.0.0.1:1934"
+    assert wait_kwargs["timeout_seconds"] == openviking_module._LOCAL_OPENVIKING_AUTOSTART_TIMEOUT
+    assert callable(wait_kwargs["should_stop"])
+    assert wait_kwargs["should_stop"]() is False
+    provider._shutting_down = True
+    assert wait_kwargs["should_stop"]() is True
     assert any("OpenViking memory is active" in message for message in statuses)
 
 
+def test_runtime_waiter_does_not_replace_client_after_endpoint_changes(monkeypatch):
+    wait_entered = threading.Event()
+    release_wait = threading.Event()
+
+    def wait_for_health(endpoint, *, timeout_seconds, should_stop=None):
+        assert endpoint == "http://127.0.0.1:1934"
+        wait_entered.set()
+        assert release_wait.wait(2.0)
+        return True
+
+    class FakeVikingClient:
+        def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+            self.endpoint = endpoint
+
+        def health(self):
+            return True
+
+    monkeypatch.setattr(openviking_module, "_wait_for_openviking_health", wait_for_health)
+    monkeypatch.setattr(openviking_module, "_VikingClient", FakeVikingClient)
+
+    provider = OpenVikingMemoryProvider()
+    provider._endpoint = "http://127.0.0.1:1934"
+    provider._api_key = ""
+    provider._account = ""
+    provider._user = ""
+    provider._agent = "hermes"
+
+    waiter = threading.Thread(target=provider._finish_runtime_openviking_start)
+    waiter.start()
+    assert wait_entered.wait(2.0)
+
+    replacement_client = FakeVikingClient("https://new.example")
+    provider._endpoint = replacement_client.endpoint
+    provider._client = replacement_client
+    release_wait.set()
+    waiter.join(timeout=2.0)
+
+    assert not waiter.is_alive()
+    assert provider._client is replacement_client
+
+
 def test_runtime_openviking_waiter_warns_when_background_start_times_out(monkeypatch):
     _clear_openviking_env(monkeypatch)
     monkeypatch.setattr(
@@ -1893,6 +2051,51 @@ def test_viking_client_retries_with_tenant_headers_for_trusted_mode(monkeypatch)
     assert captured_headers[1]["X-OpenViking-User"] == "usr"
 
 
+def test_viking_client_does_not_retry_root_tenant_error_as_trusted_mode(monkeypatch):
+    client = _VikingClient(
+        "https://example.com",
+        api_key="test-key",
+        account="acct",
+        user="usr",
+        agent="hermes",
+    )
+    captured_headers = []
+
+    def capture_post(url, **kwargs):
+        captured_headers.append(kwargs.get("headers") or {})
+        if len(captured_headers) == 1:
+            return SimpleNamespace(
+                status_code=403,
+                text="",
+                json=lambda: {
+                    "error": {
+                        "code": "PERMISSION_DENIED",
+                        "message": (
+                            "ROOT API keys cannot access tenant-scoped data APIs in api_key mode. "
+                            "Use a user/admin API key for data access, or trusted mode for upstream "
+                            "identity assertion."
+                        ),
+                    },
+                },
+                raise_for_status=lambda: None,
+            )
+        return SimpleNamespace(
+            status_code=200,
+            text="",
+            json=lambda: {"status": "ok", "result": {"total": 0}},
+            raise_for_status=lambda: None,
+        )
+
+    monkeypatch.setattr(client._httpx, "post", capture_post)
+
+    with pytest.raises(openviking_module._OpenVikingHTTPError, match="ROOT API keys cannot access"):
+        client.post("/api/v1/search/search", {"query": "status"})
+
+    assert len(captured_headers) == 1
+    assert "X-OpenViking-Account" not in captured_headers[0]
+    assert "X-OpenViking-User" not in captured_headers[0]
+
+
 def test_viking_client_health_sends_auth_headers(monkeypatch):
     _clear_openviking_tenant_env(monkeypatch)
     client = _VikingClient(
diff --git a/tests/plugins/memory/test_openviking_shutdown.py b/tests/plugins/memory/test_openviking_shutdown.py
new file mode 100644
index 00000000000..623b5ebb6f5
--- /dev/null
+++ b/tests/plugins/memory/test_openviking_shutdown.py
@@ -0,0 +1,163 @@
+"""Tests for OpenViking memory-provider shutdown teardown.
+
+The runtime-autostart waiter is a tracked ``daemon=True`` thread that blocks
+on network health probes. If ``shutdown()`` doesn't join it (and the waiter
+doesn't bail on the shutdown flag), it can be left alive at interpreter exit,
+which crashes CPython with SIGABRT at ``Py_FinalizeEx``. These tests assert
+the waiter short-circuits on shutdown and that ``shutdown()`` waits for the
+runtime-start thread.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from unittest.mock import patch
+
+import plugins.memory.openviking as openviking_module
+from plugins.memory.openviking import OpenVikingMemoryProvider
+
+
+def test_wait_for_health_short_circuits_on_should_stop():
+    """The health waiter returns False without probing when should_stop is set,
+    so the daemon thread running it can be join()ed promptly at shutdown."""
+    probes: list[str] = []
+
+    def _reach(endpoint):
+        probes.append(endpoint)
+        return (False, "down")
+
+    with patch.object(
+        openviking_module, "_validate_openviking_reachability", _reach
+    ):
+        result = openviking_module._wait_for_openviking_health(
+            "http://example.invalid",
+            timeout_seconds=60.0,
+            should_stop=lambda: True,
+        )
+
+    assert result is False
+    assert probes == []  # bailed before the first network probe
+
+
+def test_shutdown_waits_for_runtime_start_thread():
+    """shutdown() must join the runtime-autostart waiter thread.
+
+    The fake waiter does post-stop work (a short sleep) once it observes the
+    shutdown flag. If shutdown() joins it, that work has completed by the time
+    shutdown() returns; without the join, shutdown() returns early and the
+    thread is still running (the SIGABRT-at-exit failure mode).
+    """
+    provider = OpenVikingMemoryProvider()
+    started = threading.Event()
+    finished = threading.Event()
+
+    def _runtime():
+        started.set()
+        while not provider._shutting_down:
+            time.sleep(0.01)
+        time.sleep(0.2)  # work that must finish during shutdown's join
+        finished.set()
+
+    t = threading.Thread(target=_runtime, daemon=True, name="openviking-runtime-start")
+    provider._runtime_start_thread = t
+    t.start()
+    assert started.wait(2.0)
+
+    provider.shutdown()
+
+    assert finished.is_set()
+    assert not t.is_alive()
+
+
+def test_shutdown_during_pending_runtime_start_does_not_launch_waiter(monkeypatch):
+    """A waiter reserved before shutdown must not start after shutdown returns."""
+    provider = OpenVikingMemoryProvider()
+    provider._endpoint = "http://127.0.0.1:1934"
+    status_entered = threading.Event()
+    release_status = threading.Event()
+    waiter_calls = []
+
+    monkeypatch.setattr(
+        openviking_module,
+        "_start_local_openviking_server",
+        lambda endpoint: (True, "started"),
+    )
+    monkeypatch.setattr(
+        provider,
+        "_start_runtime_openviking_waiter",
+        lambda **kwargs: waiter_calls.append(kwargs),
+    )
+
+    def status_callback(_message):
+        status_entered.set()
+        assert release_status.wait(2.0)
+
+    starter = threading.Thread(
+        target=provider._handle_runtime_openviking_unreachable,
+        kwargs={"status_callback": status_callback},
+        name="openviking-pending-start",
+    )
+    starter.start()
+    assert status_entered.wait(2.0)
+
+    provider.shutdown()
+    release_status.set()
+    starter.join(timeout=2.0)
+
+    assert not starter.is_alive()
+    assert provider._runtime_start_pending is False
+    assert waiter_calls == []
+
+
+def test_shutdown_during_final_health_probe_does_not_publish_client(monkeypatch):
+    """A successful final probe must not reactivate a provider being torn down."""
+    provider = OpenVikingMemoryProvider()
+    provider._endpoint = "http://127.0.0.1:1934"
+    provider._api_key = ""
+    provider._account = ""
+    provider._user = ""
+    provider._agent = "hermes"
+    health_entered = threading.Event()
+    release_health = threading.Event()
+
+    monkeypatch.setattr(
+        openviking_module,
+        "_wait_for_openviking_health",
+        lambda endpoint, **kwargs: True,
+    )
+
+    class FakeVikingClient:
+        def __init__(self, endpoint, api_key="", account="", user="", agent=""):
+            self.endpoint = endpoint
+
+        def health(self):
+            health_entered.set()
+            assert release_health.wait(2.0)
+            return True
+
+    monkeypatch.setattr(openviking_module, "_VikingClient", FakeVikingClient)
+
+    waiter = threading.Thread(
+        target=provider._finish_runtime_openviking_start,
+        name="openviking-final-health",
+    )
+    provider._runtime_start_thread = waiter
+    waiter.start()
+    assert health_entered.wait(2.0)
+
+    shutdown = threading.Thread(target=provider.shutdown, name="openviking-shutdown")
+    shutdown.start()
+    for _ in range(100):
+        if provider._shutting_down:
+            break
+        time.sleep(0.01)
+    assert provider._shutting_down is True
+
+    release_health.set()
+    waiter.join(timeout=2.0)
+    shutdown.join(timeout=2.0)
+
+    assert not waiter.is_alive()
+    assert not shutdown.is_alive()
+    assert provider._client is None
diff --git a/tests/plugins/test_kanban_dashboard_plugin.py b/tests/plugins/test_kanban_dashboard_plugin.py
index 717bf660ee9..fee0591a1c7 100644
--- a/tests/plugins/test_kanban_dashboard_plugin.py
+++ b/tests/plugins/test_kanban_dashboard_plugin.py
@@ -1576,7 +1576,7 @@ def test_create_task_includes_warning_when_no_dispatcher(client, monkeypatch):
     # Force the dispatcher probe to report "not running".
     monkeypatch.setattr(
         "hermes_cli.kanban._check_dispatcher_presence",
-        lambda: (False, "No gateway is running — start `hermes gateway start`."),
+        lambda **kw: (False, "No gateway is running — start `hermes gateway start`."),
     )
     r = client.post(
         "/api/plugins/kanban/tasks",
@@ -1592,7 +1592,7 @@ def test_create_task_no_warning_when_dispatcher_up(client, monkeypatch):
     """Dispatcher running -> no `warning` field in the response."""
     monkeypatch.setattr(
         "hermes_cli.kanban._check_dispatcher_presence",
-        lambda: (True, ""),
+        lambda **kw: (True, ""),
     )
     r = client.post(
         "/api/plugins/kanban/tasks",
@@ -1607,7 +1607,7 @@ def test_create_task_no_warning_on_triage(client, monkeypatch):
     anyway until promoted)."""
     monkeypatch.setattr(
         "hermes_cli.kanban._check_dispatcher_presence",
-        lambda: (False, "oh no"),
+        lambda **kw: (False, "oh no"),
     )
     r = client.post(
         "/api/plugins/kanban/tasks",
@@ -1700,7 +1700,7 @@ def test_single_task_endpoint_survives_task_age_exception(client, monkeypatch):
 
 def test_create_task_probe_error_does_not_break_create(client, monkeypatch):
     """Probe failure must never break task creation."""
-    def _raise():
+    def _raise(**kw):
         raise RuntimeError("probe crashed")
     monkeypatch.setattr(
         "hermes_cli.kanban._check_dispatcher_presence", _raise,
diff --git a/tests/providers/test_provider_profiles.py b/tests/providers/test_provider_profiles.py
index 0e95623a37e..9df895af8dd 100644
--- a/tests/providers/test_provider_profiles.py
+++ b/tests/providers/test_provider_profiles.py
@@ -112,6 +112,53 @@ class TestOpenRouterProfile:
         body = p.build_extra_body()
         assert body == {}
 
+    def test_aux_call_inherits_ambient_conversation_as_sticky_key(self):
+        """Auxiliary calls pass no session_id but must still route stickily.
+
+        Compression, titles, vision, web_extract, session_search and MoA slots
+        funnel through ``agent.auxiliary_client``, which has no session handle.
+        Before the ambient resolution they sent NO sticky key at all and each
+        routed independently of its conversation (#70820).
+        """
+        from agent.portal_tags import (
+            reset_conversation_context,
+            set_conversation_context,
+        )
+
+        p = get_provider_profile("openrouter")
+        token = set_conversation_context("root-conversation")
+        try:
+            assert p.build_extra_body()["session_id"] == "root-conversation"
+            # An explicitly-passed segment id never beats the lineage root.
+            body = p.build_extra_body(session_id="segment-after-rotation")
+            assert body["session_id"] == "root-conversation"
+        finally:
+            reset_conversation_context(token)
+
+    def test_grok_cache_header_inherits_ambient_conversation(self):
+        """The xAI cache-affinity header resolves the same way as the body key."""
+        from agent.portal_tags import (
+            reset_conversation_context,
+            set_conversation_context,
+        )
+
+        p = get_provider_profile("openrouter")
+        token = set_conversation_context("root-conversation")
+        try:
+            _, top_level = p.build_api_kwargs_extras(
+                supports_reasoning=False, model="x-ai/grok-4"
+            )
+            headers = top_level.get("extra_headers", {})
+            assert headers["x-grok-conv-id"] == "root-conversation"
+
+            # Still model-gated: non-Grok models get no affinity header.
+            _, other = p.build_api_kwargs_extras(
+                supports_reasoning=False, model="anthropic/claude-sonnet-4.6"
+            )
+            assert "x-grok-conv-id" not in other.get("extra_headers", {})
+        finally:
+            reset_conversation_context(token)
+
     def test_pareto_min_coding_score_emitted_for_pareto_model(self):
         """min_coding_score → plugins block when model is openrouter/pareto-code."""
         p = get_provider_profile("openrouter")
diff --git a/tests/run_agent/test_413_compression.py b/tests/run_agent/test_413_compression.py
index 1d259e23901..cf05a9a9054 100644
--- a/tests/run_agent/test_413_compression.py
+++ b/tests/run_agent/test_413_compression.py
@@ -1465,6 +1465,127 @@ class TestPreflightCompression:
         assert mock_compress.call_count == 2
 
 
+    def test_interrupt_before_first_provider_call_restores_preflight_display_seed(self, agent):
+        """Interrupted turns must not keep a speculative preflight display seed.
+
+        Preflight runs before the main loop checks ``_interrupt_requested``.
+        If the user interrupts during that window, no provider usage ever
+        arrives to validate the rough estimate, so the old display token count
+        must be restored instead of leaking the speculative value forward.
+        """
+        agent.compression_enabled = True
+        agent._interrupt_requested = True
+        agent.context_compressor.context_length = 200_000
+        agent.context_compressor.threshold_tokens = 130_000
+        agent.context_compressor.last_prompt_tokens = 74_400
+
+        big_history = []
+        for i in range(20):
+            big_history.append({"role": "user", "content": f"Message {i} padded text"})
+            big_history.append({"role": "assistant", "content": f"Response {i} padded text"})
+
+        with (
+            patch("agent.turn_context.estimate_request_tokens_rough", return_value=144_669),
+            patch.object(agent.context_compressor, "should_compress", return_value=False),
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=big_history)
+
+        assert result["interrupted"] is True
+        assert agent.client.chat.completions.create.call_count == 0
+        assert agent.context_compressor.last_prompt_tokens == 74_400
+
+    def test_usage_less_provider_response_prevents_display_seed_rollback(self, agent):
+        """A successful response counts even when the provider omits usage."""
+        agent.compression_enabled = True
+        agent.context_compressor.context_length = 200_000
+        agent.context_compressor.threshold_tokens = 130_000
+        agent.context_compressor.last_prompt_tokens = 74_400
+
+        big_history = []
+        for i in range(20):
+            big_history.append({"role": "user", "content": f"Message {i} padded text"})
+            big_history.append({"role": "assistant", "content": f"Response {i} padded text"})
+
+        tool_call = SimpleNamespace(
+            id="tc1",
+            type="function",
+            function=SimpleNamespace(name="web_search", arguments='{"query":"test"}'),
+        )
+        agent.client.chat.completions.create.side_effect = [
+            _mock_response(
+                content=None,
+                finish_reason="tool_calls",
+                tool_calls=[tool_call],
+                usage=None,
+            )
+        ]
+
+        def _interrupt_after_tool(*_args, **_kwargs):
+            agent._interrupt_requested = True
+
+        with (
+            patch("agent.turn_context.estimate_request_tokens_rough", return_value=144_669),
+            patch.object(agent.context_compressor, "should_compress", return_value=False),
+            patch.object(agent, "_execute_tool_calls", side_effect=_interrupt_after_tool),
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=big_history)
+
+        assert result["interrupted"] is True
+        assert agent.client.chat.completions.create.call_count == 1
+        assert agent.context_compressor.last_prompt_tokens == 144_669
+
+    def test_interrupt_keeps_post_compression_state(self, agent):
+        """Display rollback must not restore real post-compaction state.
+
+        A completed preflight compaction still leaves the conversation in the
+        post-compression ``-1`` sentinel state. Its anti-thrashing verdict also
+        remains owned by the completed compaction boundary rather than the
+        speculative display snapshot.
+        """
+        agent.compression_enabled = True
+        agent._interrupt_requested = True
+        agent.context_compressor.context_length = 200_000
+        agent.context_compressor.threshold_tokens = 130_000
+        agent.context_compressor.last_prompt_tokens = 74_400
+        agent.context_compressor._ineffective_compression_count = 1
+
+        big_history = []
+        for i in range(20):
+            big_history.append({"role": "user", "content": f"Message {i} padded text"})
+            big_history.append({"role": "assistant", "content": f"Response {i} padded text"})
+
+        def _fake_preflight_compress(msgs, *_args, **_kwargs):
+            agent.context_compressor.last_prompt_tokens = -1
+            agent.context_compressor.awaiting_real_usage_after_compression = True
+            agent.context_compressor.compression_count += 1
+            agent.context_compressor._ineffective_compression_count = 2
+            agent.context_compressor._last_compression_savings_pct = 0.0
+            return msgs, agent._cached_system_prompt
+
+        with (
+            patch("agent.turn_context.estimate_request_tokens_rough", return_value=144_669),
+            patch.object(agent.context_compressor, "should_compress", return_value=True),
+            patch.object(agent, "_compress_context", side_effect=_fake_preflight_compress),
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=big_history)
+
+        assert result["interrupted"] is True
+        assert agent.client.chat.completions.create.call_count == 0
+        assert agent.context_compressor.last_prompt_tokens == -1
+        assert agent.context_compressor.awaiting_real_usage_after_compression is True
+        assert agent.context_compressor._ineffective_compression_count == 2
+        assert agent.context_compressor._last_compression_savings_pct == 0.0
+
+
 class TestToolResultPreflightCompression:
     """Compression should trigger when tool results push context past the threshold."""
 
diff --git a/tests/run_agent/test_70773_shared_client_fd_corruption.py b/tests/run_agent/test_70773_shared_client_fd_corruption.py
new file mode 100644
index 00000000000..e10e912a1df
--- /dev/null
+++ b/tests/run_agent/test_70773_shared_client_fd_corruption.py
@@ -0,0 +1,243 @@
+"""#70773: the shared OpenAI-wire client must never be pool-closed from a
+non-owner thread.
+
+A custom OpenAI-compatible provider reproduced the #29507/#67142 TLS-FD →
+SQLite corruption shape on v0.18.2: the streaming stale watchdog (poll
+thread) called ``_replace_primary_openai_client(reason=
+"stale_stream_pool_cleanup")``, which hard-closed the old shared client's
+connection pool while worker threads from previous stale-killed attempts
+were still unwinding their SSL BIOs. The kernel recycled a just-released
+TLS FD onto ``kanban.db`` and the unwinding TLS flush wrote a 24-byte
+application-data record over the SQLite header.
+
+Fix (mirrors the #67142 Anthropic ownership discipline):
+
+1. The three in-request cleanup sites (stale watchdog, mid-tool retry,
+   stream retry) no longer touch the shared client at all — the
+   request-local client is closed via ``_close_request_client_once`` and
+   the shared client is replaced lazily by ``_ensure_primary_openai_client``
+   on the next request, on the requesting thread.
+2. ``_replace_primary_openai_client`` (still used by credential rotation,
+   refresh, and dead-connection cleanup) retires the old client instead of
+   hard-closing it: sockets are ``shutdown()`` (FD-safe from any thread),
+   FD release is deferred to GC so it cannot happen under a borrowing
+   thread's live SSL BIO.
+"""
+import threading
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from tests.run_agent.test_streaming import _make_stream_chunk
+
+
+def _make_agent():
+    from run_agent import AIAgent
+
+    agent = AIAgent(
+        api_key="test-key",
+        base_url="https://custom.example.com/v1",
+        provider="custom",
+        model="deepseek-v4-pro",
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+    agent.api_mode = "chat_completions"
+    agent._interrupt_requested = False
+    return agent
+
+
+class TestStaleWatchdogNeverClosesSharedClient:
+    """The stale watchdog / retry cleanups must not rebuild (and therefore
+    must not close) the shared OpenAI client from inside a request."""
+
+    @pytest.mark.filterwarnings(
+        "ignore::pytest.PytestUnhandledThreadExceptionWarning"
+    )
+    @patch("run_agent.AIAgent._replace_primary_openai_client")
+    @patch("run_agent.AIAgent._abort_request_openai_client")
+    @patch("run_agent.AIAgent._create_request_openai_client")
+    @patch("run_agent.AIAgent._close_request_openai_client")
+    def test_stale_stream_kill_does_not_replace_primary(
+        self, mock_close, mock_create, mock_abort, mock_replace, monkeypatch,
+    ):
+        """Stale-stream watchdog fires → request-local client is aborted, the
+        shared primary is never replaced (poll thread must not close it)."""
+        monkeypatch.setenv("HERMES_STREAM_STALE_TIMEOUT", "0.05")
+        monkeypatch.setenv("HERMES_STREAM_RETRIES", "1")
+
+        unblock = threading.Event()
+
+        class StaleThenDeadStream:
+            response = SimpleNamespace(headers={})
+
+            def __iter__(self):
+                # Yield nothing; block until the watchdog aborts the request
+                # client, then surface the transport error.
+                unblock.wait(timeout=5.0)
+                raise httpx.ConnectError("connection dropped after abort")
+                yield  # pragma: no cover — make this a generator
+
+        retry_chunks = [
+            _make_stream_chunk(content="recovered"),
+            _make_stream_chunk(finish_reason="stop", model="test/model"),
+        ]
+
+        class RetryStream:
+            response = SimpleNamespace(headers={})
+
+            def __iter__(self):
+                return iter(retry_chunks)
+
+        mock_client = MagicMock()
+        mock_client.chat.completions.create.side_effect = [
+            StaleThenDeadStream(),
+            RetryStream(),
+        ]
+        mock_create.return_value = mock_client
+        mock_abort.side_effect = lambda *a, **k: unblock.set()
+
+        agent = _make_agent()
+        response = agent._interruptible_streaming_api_call({})
+
+        assert response.choices[0].message.content == "recovered"
+        # The watchdog aborted the request-local client from the poll thread…
+        assert mock_abort.call_count >= 1
+        # …and NEVER replaced/closed the shared primary client (#70773).
+        mock_replace.assert_not_called()
+
+    @pytest.mark.filterwarnings(
+        "ignore::pytest.PytestUnhandledThreadExceptionWarning"
+    )
+    @patch("run_agent.AIAgent._replace_primary_openai_client")
+    @patch("run_agent.AIAgent._create_request_openai_client")
+    @patch("run_agent.AIAgent._close_request_openai_client")
+    def test_stream_retry_cleanup_does_not_replace_primary(
+        self, mock_close, mock_create, mock_replace, monkeypatch,
+    ):
+        """Connection drop before first delta → retry path closes only the
+        request-local client; the shared primary is left alone."""
+        monkeypatch.setenv("HERMES_STREAM_RETRIES", "1")
+
+        attempts = {"n": 0}
+
+        def _pick_stream(*a, **kw):
+            attempts["n"] += 1
+            if attempts["n"] == 1:
+                def _dead():
+                    raise httpx.ConnectError("connection reset by peer")
+                    yield  # pragma: no cover
+                return _dead()
+            return iter([
+                _make_stream_chunk(content="ok"),
+                _make_stream_chunk(finish_reason="stop", model="test/model"),
+            ])
+
+        mock_client = MagicMock()
+        mock_client.chat.completions.create.side_effect = _pick_stream
+        mock_create.return_value = mock_client
+
+        agent = _make_agent()
+        response = agent._interruptible_streaming_api_call({})
+
+        assert attempts["n"] == 2
+        assert response.choices[0].message.content == "ok"
+        # Request-local cleanup ran; shared client untouched (#70773).
+        assert mock_close.call_count >= 1
+        mock_replace.assert_not_called()
+
+    @pytest.mark.filterwarnings(
+        "ignore::pytest.PytestUnhandledThreadExceptionWarning"
+    )
+    @patch("run_agent.AIAgent._replace_primary_openai_client")
+    @patch("run_agent.AIAgent._create_request_openai_client")
+    @patch("run_agent.AIAgent._close_request_openai_client")
+    def test_mid_tool_retry_cleanup_does_not_replace_primary(
+        self, mock_close, mock_create, mock_replace, monkeypatch,
+    ):
+        """Connection drop mid tool-call → silent retry closes only the
+        request-local client; the shared primary is left alone."""
+        from tests.run_agent.test_streaming import _make_tool_call_delta
+
+        monkeypatch.setenv("HERMES_STREAM_RETRIES", "2")
+
+        attempts = {"n": 0}
+
+        def _first_stream():
+            yield _make_stream_chunk(content="Working: ")
+            yield _make_stream_chunk(tool_calls=[
+                _make_tool_call_delta(index=0, tc_id="call_1", name="terminal"),
+            ])
+            raise httpx.RemoteProtocolError("peer closed connection")
+
+        def _second_stream():
+            yield _make_stream_chunk(tool_calls=[
+                _make_tool_call_delta(index=0, tc_id="call_1", name="terminal"),
+            ])
+            yield _make_stream_chunk(tool_calls=[
+                _make_tool_call_delta(index=0, arguments='{"command": "ls"}'),
+            ])
+            yield _make_stream_chunk(finish_reason="tool_calls")
+
+        def _pick_stream(*a, **kw):
+            attempts["n"] += 1
+            return _first_stream() if attempts["n"] == 1 else _second_stream()
+
+        mock_client = MagicMock()
+        mock_client.chat.completions.create.side_effect = _pick_stream
+        mock_create.return_value = mock_client
+
+        agent = _make_agent()
+        response = agent._interruptible_streaming_api_call({})
+
+        assert attempts["n"] == 2
+        assert response.choices[0].message.tool_calls
+        mock_replace.assert_not_called()
+
+
+class TestReplacePrimaryRetiresInsteadOfClosing:
+    """_replace_primary_openai_client (credential rotation / refresh /
+    dead-connection cleanup) must retire the old shared client — shutdown
+    sockets, defer FD release to GC — never hard-close its pool."""
+
+    def test_replace_retires_old_client_without_close(self):
+        agent = _make_agent()
+
+        old_client = MagicMock()
+        agent.client = old_client
+        agent._client_kwargs = {
+            "api_key": "test-key",
+            "base_url": "https://custom.example.com/v1",
+        }
+
+        shutdown_calls = []
+        with patch.object(
+            agent, "_force_close_tcp_sockets",
+            side_effect=lambda c: shutdown_calls.append(c) or 1,
+        ):
+            with patch("run_agent.OpenAI", MagicMock()):
+                ok = agent._replace_primary_openai_client(reason="test_rotate")
+
+        assert ok
+        # Sockets were shut down (FD-safe from any thread)…
+        assert shutdown_calls == [old_client]
+        # …but the old client's pool was NOT hard-closed: no thread owns a
+        # replaced shared client, so nobody may release its FDs (#70773).
+        old_client.close.assert_not_called()
+
+    def test_retire_helper_never_calls_close(self):
+        agent = _make_agent()
+        client = MagicMock()
+
+        with patch.object(agent, "_force_close_tcp_sockets", return_value=2):
+            agent._retire_shared_openai_client(client, reason="unit_test")
+
+        client.close.assert_not_called()
+
+    def test_retire_helper_none_is_noop(self):
+        agent = _make_agent()
+        # Must not raise.
+        agent._retire_shared_openai_client(None, reason="unit_test")
diff --git a/tests/run_agent/test_compression_boundary_hook.py b/tests/run_agent/test_compression_boundary_hook.py
index 36e5b97af61..67d0e25a68f 100644
--- a/tests/run_agent/test_compression_boundary_hook.py
+++ b/tests/run_agent/test_compression_boundary_hook.py
@@ -120,14 +120,16 @@ class TestCompressionBoundaryHook:
                 )
             )
             agent.context_compressor = compressor
-            original_update = db.update_system_prompt
+            original_publish = db.publish_compression_child
 
-            def _record_update(*args, **kwargs):
-                result = original_update(*args, **kwargs)
+            def _record_publish(*args, **kwargs):
+                result = original_publish(*args, **kwargs)
                 events.append("persist")
                 return result
 
-            with patch.object(db, "update_system_prompt", side_effect=_record_update):
+            with patch.object(
+                db, "publish_compression_child", side_effect=_record_publish
+            ):
                 agent._compress_context(
                     [{"role": "user", "content": "request"}],
                     "sys",
@@ -174,7 +176,7 @@ class TestCompressionBoundaryHook:
 
             with patch.object(
                 db,
-                "update_system_prompt",
+                "publish_compression_child",
                 side_effect=RuntimeError("synthetic commit failure"),
             ):
                 agent._compress_context(
diff --git a/tests/run_agent/test_compression_lock_defer.py b/tests/run_agent/test_compression_lock_defer.py
new file mode 100644
index 00000000000..e012f01af3d
--- /dev/null
+++ b/tests/run_agent/test_compression_lock_defer.py
@@ -0,0 +1,374 @@
+"""Lock-contended compression no-ops must soft-DEFER, never exhaust (#49874).
+
+On main before this fix, nothing on the automatic compression paths consumed
+the #69870 lock-skip signal (``agent._compression_skipped_due_to_lock``):
+
+* a lock-loser preflight/pre-API no-op counted as "insufficient progress",
+* the oversized request went to the provider anyway, and
+* the lock-contended 413/overflow retry burned ``compression_attempts`` to
+  the cap and returned ``compression_exhausted`` — which the gateway answers
+  with a full session auto-reset (#9893/#35809).
+
+A temporary lock defer misclassified as exhaustion == session wipe.
+
+These tests pin the fix: when a compression pass returns its input unchanged
+AND the type-pinned lock-skip flag is set, the attempt is refunded and the
+turn ends (when it cannot proceed) with a soft ``compression_deferred``
+result distinct from ``compression_exhausted``.
+
+Salvaged from PR #49874 (@helix4u), rebuilt on the landed #69870 signal.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent.conversation_compression import compression_skipped_due_to_lock
+from run_agent import AIAgent
+import run_agent
+
+
+LOCK_HOLDER = "pid=4242:tid=1:agent=deadbeef:nonce=abcd1234"
+
+
+# ---------------------------------------------------------------------------
+# Helpers (mirrors tests/run_agent/test_413_compression.py)
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _no_compression_sleep(monkeypatch):
+    import time as _time
+
+    monkeypatch.setattr(_time, "sleep", lambda *_a, **_k: None)
+    monkeypatch.setattr(run_agent, "jittered_backoff", lambda *a, **k: 0.0)
+
+
+def _make_tool_defs(*names: str) -> list:
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": n,
+                "description": f"{n} tool",
+                "parameters": {"type": "object", "properties": {}},
+            },
+        }
+        for n in names
+    ]
+
+
+def _mock_response(content="Hello", finish_reason="stop"):
+    msg = SimpleNamespace(
+        content=content,
+        tool_calls=None,
+        reasoning_content=None,
+        reasoning=None,
+    )
+    choice = SimpleNamespace(message=msg, finish_reason=finish_reason)
+    resp = SimpleNamespace(choices=[choice], model="test/model")
+    resp.usage = None
+    return resp
+
+
+def _make_413_error(message="Request entity too large"):
+    err = Exception(message)
+    err.status_code = 413
+    return err
+
+
+def _make_overflow_error():
+    return Exception(
+        "Error code: 400 - {'type': 'error', 'error': {'type': "
+        "'invalid_request_error', 'message': 'prompt is too long: "
+        "233153 tokens > 200000 maximum'}}"
+    )
+
+
+@pytest.fixture()
+def agent():
+    with (
+        patch("run_agent.get_tool_definitions", return_value=_make_tool_defs("web_search")),
+        patch("run_agent.check_toolset_requirements", return_value={}),
+        patch("run_agent.OpenAI"),
+    ):
+        a = AIAgent(
+            api_key="test-key-1234567890",
+            base_url="https://openrouter.ai/api/v1",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+        )
+        a.client = MagicMock()
+        a._cached_system_prompt = "You are helpful."
+        a._use_prompt_caching = False
+        a.tool_delay = 0
+        a.compression_enabled = True
+        a.save_trajectories = False
+        return a
+
+
+_PREFILL = [
+    {"role": "user", "content": "previous question"},
+    {"role": "assistant", "content": "previous answer"},
+]
+
+
+def _lock_skipping_compress(agent, *, holder=LOCK_HOLDER):
+    """A compress double that no-ops because 'another path holds the lock'.
+
+    Mirrors the real ``compress_context`` lock-contended abort: returns the
+    INPUT list object unchanged and sets the #69870 lock-skip signal.
+    """
+
+    def _compress(messages, _system_message, **_kwargs):
+        agent._compression_skipped_due_to_lock = holder
+        return messages, "You are helpful."
+
+    return _compress
+
+
+def _plain_noop_compress(agent):
+    """A compress double that no-ops WITHOUT lock contention (real no-progress)."""
+
+    def _compress(messages, _system_message, **_kwargs):
+        agent._compression_skipped_due_to_lock = None
+        return messages, "You are helpful."
+
+    return _compress
+
+
+# ---------------------------------------------------------------------------
+# Type-pinned signal read (MagicMock test-double immunity)
+# ---------------------------------------------------------------------------
+
+
+class TestLockSkipSignalTypePin:
+    def test_true_and_holder_string_are_lock_skips(self):
+        a = SimpleNamespace(_compression_skipped_due_to_lock=True)
+        assert compression_skipped_due_to_lock(a) is True
+        a = SimpleNamespace(_compression_skipped_due_to_lock=LOCK_HOLDER)
+        assert compression_skipped_due_to_lock(a) is True
+
+    def test_none_and_missing_are_not_lock_skips(self):
+        assert compression_skipped_due_to_lock(
+            SimpleNamespace(_compression_skipped_due_to_lock=None)
+        ) is False
+        assert compression_skipped_due_to_lock(SimpleNamespace()) is False
+
+    def test_magicmock_agent_auto_attribute_is_not_a_lock_skip(self):
+        """MagicMock agents auto-create truthy attributes; bare truthiness
+        would hijack every mocked agent in sibling suites into the lock-skip
+        branch (the #69870 × #69840 incident). The read must be type-pinned."""
+        assert compression_skipped_due_to_lock(MagicMock()) is False
+
+    def test_truthy_non_true_non_str_values_are_not_lock_skips(self):
+        for junk in (1, 1.0, ["holder"], {"holder": True}, object(), MagicMock()):
+            a = SimpleNamespace(_compression_skipped_due_to_lock=junk)
+            assert compression_skipped_due_to_lock(a) is False, junk
+
+
+# ---------------------------------------------------------------------------
+# 413 handler: lock-contended no-op → soft defer, no exhaustion
+# ---------------------------------------------------------------------------
+
+
+class TestLockContended413Defer:
+    def test_lock_contended_413_returns_compression_deferred(self, agent):
+        """A 413 whose compression pass lost the lock must end the turn as a
+        soft ``compression_deferred`` — never ``compression_exhausted``."""
+        agent.client.chat.completions.create.side_effect = _make_413_error()
+
+        with (
+            patch.object(
+                agent, "_compress_context",
+                side_effect=_lock_skipping_compress(agent),
+            ) as mock_compress,
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=list(_PREFILL))
+
+        mock_compress.assert_called_once()
+        assert result.get("compression_deferred") is True
+        assert not result.get("compression_exhausted")
+        # Soft defer: transient, retry-next-message semantics — the gateway
+        # persists the user turn (failed=False) and never auto-resets.
+        assert result.get("failed") is False
+        assert result.get("completed") is False
+        assert result.get("partial") is True
+
+    def test_lock_contended_overflow_returns_compression_deferred(self, agent):
+        """Same contract on the context-length (400 prompt-too-long) handler."""
+        agent.client.chat.completions.create.side_effect = _make_overflow_error()
+
+        with (
+            patch.object(
+                agent, "_compress_context",
+                side_effect=_lock_skipping_compress(agent),
+            ) as mock_compress,
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=list(_PREFILL))
+
+        mock_compress.assert_called_once()
+        assert result.get("compression_deferred") is True
+        assert not result.get("compression_exhausted")
+        assert result.get("failed") is False
+
+    def test_unconfirmed_lock_skip_true_also_defers(self, agent):
+        """``_compression_skipped_due_to_lock = True`` (holder unconfirmed —
+        ``try_acquire`` swallowed a sqlite error) is still a lock skip."""
+        agent.client.chat.completions.create.side_effect = _make_413_error()
+
+        with (
+            patch.object(
+                agent, "_compress_context",
+                side_effect=_lock_skipping_compress(agent, holder=True),
+            ),
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=list(_PREFILL))
+
+        assert result.get("compression_deferred") is True
+        assert not result.get("compression_exhausted")
+
+    def test_plain_noop_413_still_exhausts_unchanged(self, agent):
+        """Control: flag unset (real no-progress compression) keeps the
+        pre-fix behavior byte-for-byte — terminal ``compression_exhausted``."""
+        agent.client.chat.completions.create.side_effect = _make_413_error()
+
+        with (
+            patch.object(
+                agent, "_compress_context",
+                side_effect=_plain_noop_compress(agent),
+            ),
+            patch.object(
+                agent, "_try_strip_image_parts_from_tool_messages",
+                return_value=False,
+            ),
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=list(_PREFILL))
+
+        assert result.get("compression_exhausted") is True
+        assert not result.get("compression_deferred")
+        assert result.get("failed") is True
+
+    def test_magicmock_flag_value_does_not_defer(self, agent):
+        """Type-pin at the consumer site: a truthy non-True/non-str flag value
+        (e.g. a MagicMock auto-attribute) must NOT take the defer branch."""
+        agent.client.chat.completions.create.side_effect = _make_413_error()
+
+        def _junk_flag_compress(messages, _system_message, **_kwargs):
+            agent._compression_skipped_due_to_lock = MagicMock()  # truthy junk
+            return messages, "You are helpful."
+
+        with (
+            patch.object(agent, "_compress_context", side_effect=_junk_flag_compress),
+            patch.object(
+                agent, "_try_strip_image_parts_from_tool_messages",
+                return_value=False,
+            ),
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=list(_PREFILL))
+
+        assert not result.get("compression_deferred")
+        assert result.get("compression_exhausted") is True
+
+
+# ---------------------------------------------------------------------------
+# Pre-API gate: a lock-skipped pass must not burn the shared attempt budget
+# ---------------------------------------------------------------------------
+
+
+class TestPreApiLockDeferDoesNotBurnBudget:
+    def test_lock_loser_turn_recovers_after_lock_release(self, agent):
+        """End-to-end shape of the live bug at cap=1:
+
+        1. Pre-API pressure gate fires; the compression pass loses the lock
+           (no-op + lock-skip flag). Pre-fix this burned the single shared
+           attempt.
+        2. The oversized request goes to the provider → 413.
+        3. The 413 handler compresses again — the lock has been released and
+           the pass now succeeds — and the retry completes.
+
+        Pre-fix, step 3 found ``compression_attempts`` already at the cap and
+        returned ``compression_exhausted`` → gateway session wipe. The defer
+        refund keeps the budget intact for the provider-proven retry.
+        """
+        agent.max_compression_attempts = 1
+        # Compressor stub: pressure only on the fully-assembled request
+        # (pre-API site); the turn-context preflight stands down via the
+        # cheap-gate (small message count) and low turn-context estimate.
+        agent.context_compressor = SimpleNamespace(
+            protect_first_n=3,
+            protect_last_n=20,
+            threshold_tokens=100_000,
+            context_length=1_000_000,
+            last_prompt_tokens=0,
+            should_compress=lambda t: t >= 100_000,
+            should_defer_preflight_to_real_usage=lambda _t: False,
+            get_active_compression_failure_cooldown=lambda: None,
+        )
+
+        agent.client.chat.completions.create.side_effect = [
+            _make_413_error(),
+            _mock_response(content="Recovered after lock release"),
+        ]
+
+        compress_calls = []
+
+        def _lock_then_success(messages, _system_message, **_kwargs):
+            compress_calls.append(len(messages))
+            if len(compress_calls) == 1:
+                # Lock loser: no-op + #69870 signal.
+                agent._compression_skipped_due_to_lock = LOCK_HOLDER
+                return messages, "You are helpful."
+            # Lock released: real compaction (entry clears the signal).
+            agent._compression_skipped_due_to_lock = None
+            return (
+                [{"role": "user", "content": "hello"}],
+                "You are helpful.",
+            )
+
+        with (
+            patch(
+                "agent.turn_context.estimate_request_tokens_rough",
+                return_value=10,
+            ),
+            patch(
+                "agent.conversation_loop.estimate_request_tokens_rough",
+                return_value=500_000,
+            ),
+            patch(
+                "agent.conversation_loop.estimate_messages_tokens_rough",
+                return_value=500_000,
+            ),
+            patch.object(agent, "_compress_context", side_effect=_lock_then_success),
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello", conversation_history=list(_PREFILL))
+
+        # Pass 1: pre-API (lock defer, refunded). Pass 2: 413 handler
+        # (succeeds within the cap because the defer did not count).
+        assert len(compress_calls) == 2
+        assert result.get("completed") is True
+        assert result["final_response"] == "Recovered after lock release"
+        assert not result.get("compression_exhausted")
+        assert not result.get("compression_deferred")
diff --git a/tests/run_agent/test_compression_persistence.py b/tests/run_agent/test_compression_persistence.py
index 20f8a442e2b..c21afa1f35e 100644
--- a/tests/run_agent/test_compression_persistence.py
+++ b/tests/run_agent/test_compression_persistence.py
@@ -322,6 +322,52 @@ class TestFlushAfterCompression:
             )
             db.close()
 
+    def test_rotation_child_session_inherits_parent_profile_name(self):
+        """The rotation child must stay on the parent's owning profile.
+
+        The rotate path used to create the child row with no profile_name, so
+        a compressed non-default-profile conversation migrated to the launch/
+        default profile in unified session lists (the cross-profile
+        session-jump bug). Exercises the real rotation against a real
+        SessionDB: explicit stamp at the create site + the parent-backfill
+        COALESCE in _insert_session_row.
+        """
+        from agent.conversation_compression import compress_context
+        from hermes_state import SessionDB
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            db = SessionDB(db_path=Path(tmpdir) / "test.db")
+            parent_sid = "20260701_152840_parent"
+            db.create_session(
+                parent_sid, "gateway", model="test/model",
+                profile_name="ai-engineer",
+            )
+
+            agent = self._make_agent(db)
+            agent.session_id = parent_sid
+            agent.compression_in_place = False
+            agent._ensure_db_session()
+
+            messages = [
+                {
+                    "role": "user" if i % 2 == 0 else "assistant",
+                    "content": f"message {i}",
+                    "_db_persisted": True,
+                }
+                for i in range(12)
+            ]
+
+            with patch("agent.context_compressor.call_llm", side_effect=RuntimeError("no provider")):
+                compress_context(
+                    agent, messages, approx_tokens=100_000, system_message="sys"
+                )
+
+            assert agent.session_id != parent_sid
+            child = db.get_session(agent.session_id)
+            assert child is not None
+            assert child["profile_name"] == "ai-engineer"
+            db.close()
+
 
 # ---------------------------------------------------------------------------
 # Part 2: Gateway-side — history_offset after session split
@@ -391,3 +437,227 @@ class TestGatewayHistoryOffsetAfterSplit:
         assert len(new_messages) == 0, (
             "Expected 0 messages with stale offset=200 (demonstrates the bug)"
         )
+
+
+class TestStoredPromptCwdDrift:
+    """Verify that stored system prompts are rejected when cwd changed."""
+
+    def _make_agent(self, model="test/model", provider="openrouter"):
+        class _Agent:
+            pass
+
+        agent = _Agent()
+        agent.model = model
+        agent.provider = provider
+        return agent
+
+    @staticmethod
+    def _host_block(cwd: str) -> str:
+        """A stored prompt fragment shaped like the real host-info block.
+
+        ``build_environment_hints`` always emits ``User home directory:``
+        immediately before the working-directory line, and the staleness check
+        anchors on that pair so user project files can't shadow the real value.
+        Fixtures must therefore include the anchor or they stop exercising the
+        cwd path at all.
+        """
+        return (
+            "Host: Linux (6.16.0)\n"
+            "User home directory: /home/tester\n"
+            f"Current working directory: {cwd}\n"
+        )
+
+    def test_stored_prompt_stale_when_cwd_differs(self):
+        """Different cwd should force a prompt rebuild."""
+        from unittest.mock import patch
+        from agent.conversation_loop import _stored_prompt_matches_runtime
+
+        agent = self._make_agent()
+        stored_prompt = (
+            self._host_block("/project/old")
+            + "Model: test/model\n"
+            "Provider: openrouter\n"
+        )
+
+        with patch("os.getcwd", return_value="/project/new"):
+            assert _stored_prompt_matches_runtime(agent, stored_prompt) is False, (
+                "Expected False when stored cwd differs from current cwd"
+            )
+
+    def test_stored_prompt_fresh_when_cwd_matches(self):
+        """Matching cwd should allow prompt reuse."""
+        from unittest.mock import patch
+        from agent.conversation_loop import _stored_prompt_matches_runtime
+
+        agent = self._make_agent()
+        current_cwd = "/project/current"
+        stored_prompt = (
+            self._host_block(current_cwd)
+            + "Model: test/model\n"
+            "Provider: openrouter\n"
+        )
+
+        with patch("os.getcwd", return_value=current_cwd):
+            assert _stored_prompt_matches_runtime(agent, stored_prompt) is True, (
+                "Expected True when stored cwd matches current cwd"
+            )
+
+    def test_project_context_cannot_force_a_rebuild(self):
+        """🔴 CACHE INVARIANT: user project text must never invalidate the prompt.
+
+        The prompt embeds AGENTS.md / CLAUDE.md / .cursorrules in the context
+        tier, which sits AFTER the host-info block. A whole-prompt scan for
+        ``Current working directory:`` therefore matched the user's own file
+        and compared runtime state against project prose. That mismatch never
+        clears, so the check rejected the stored prompt on EVERY turn —
+        rebuilding the system prompt each message and destroying the prefix
+        cache for the entire session. Strictly worse than the staleness this
+        check exists to catch.
+        """
+        from unittest.mock import patch
+        from agent.conversation_loop import _stored_prompt_matches_runtime
+
+        agent = self._make_agent()
+        current_cwd = "/project/current"
+        stored_prompt = (
+            self._host_block(current_cwd)
+            + "\n# AGENTS.md\n\n"
+            "Our deploy convention:\n\n"
+            "Current working directory: /srv/decoy\n\n"
+            "Always run make before pushing.\n\n"
+            "Model: test/model\n"
+            "Provider: openrouter\n"
+        )
+
+        with patch("os.getcwd", return_value=current_cwd):
+            assert _stored_prompt_matches_runtime(agent, stored_prompt) is True, (
+                "A project file that merely MENTIONS 'Current working "
+                "directory:' must not invalidate the prompt — that would "
+                "rebuild every turn and break the prefix cache"
+            )
+
+    def test_project_context_cannot_mask_real_drift(self):
+        """The inverse: project text must not fake a match either.
+
+        A stored prompt built in /project/old whose embedded AGENTS.md happens
+        to name the NEW cwd must still be rejected — otherwise project prose
+        could suppress genuine drift detection.
+        """
+        from unittest.mock import patch
+        from agent.conversation_loop import _stored_prompt_matches_runtime
+
+        agent = self._make_agent()
+        stored_prompt = (
+            self._host_block("/project/old")
+            + "\n# AGENTS.md\n\n"
+            "Current working directory: /project/new\n\n"
+            "Model: test/model\n"
+            "Provider: openrouter\n"
+        )
+
+        with patch("os.getcwd", return_value="/project/new"):
+            assert _stored_prompt_matches_runtime(agent, stored_prompt) is False, (
+                "Embedded project text naming the new cwd must not mask real "
+                "drift in the host-info block"
+            )
+
+    def test_stored_prompt_stale_when_runtime_surface_differs(self):
+        """A stored prompt built for a different platform must not be reused."""
+        from agent.conversation_loop import _stored_prompt_matches_runtime
+
+        stored_prompt = (
+            "Platform: desktop\n"
+            "Model: test/model\n"
+            "Provider: openrouter\n"
+        )
+        agent = self._make_agent()
+        agent.platform = "cli"
+        assert _stored_prompt_matches_runtime(agent, stored_prompt) is False, (
+            "Expected False when stored prompt is for 'desktop' but the "
+            "current session runs on 'cli'"
+        )
+
+    def test_stored_prompt_fresh_when_platform_matches(self):
+        """Matching platform allows prompt reuse."""
+        from agent.conversation_loop import _stored_prompt_matches_runtime
+
+        agent = self._make_agent()
+        agent.platform = "desktop"
+        stored_prompt = (
+            "Platform: desktop\n"
+            "Model: test/model\n"
+            "Provider: openrouter\n"
+        )
+        assert _stored_prompt_matches_runtime(agent, stored_prompt) is True, (
+            "Expected True when stored platform matches the current platform"
+        )
+
+    def test_stored_prompt_fresh_when_terminal_cwd_matches(self):
+        """Gateway: stored cwd equals TERMINAL_CWD -> reuse via resolve_agent_cwd.
+
+        The gateway sets TERMINAL_CWD to the configured project dir, which differs
+        from the process launch dir (os.getcwd()). Reuse must key off
+        resolve_agent_cwd(), not os.getcwd(), or every gateway turn would falsely
+        rebuild the system prompt.
+        """
+        from unittest.mock import patch
+        from agent.conversation_loop import _stored_prompt_matches_runtime
+
+        agent = self._make_agent()
+        with tempfile.TemporaryDirectory() as term_cwd:
+            stored_prompt = (
+                self._host_block(term_cwd)
+                + "Model: test/model\n"
+                "Provider: openrouter\n"
+            )
+            with patch.dict(os.environ, {"TERMINAL_CWD": term_cwd}):
+                assert _stored_prompt_matches_runtime(agent, stored_prompt) is True, (
+                    "Expected True when stored cwd equals TERMINAL_CWD "
+                    "(gateway launch dir differs from configured cwd)"
+                )
+
+    def test_stored_prompt_stale_when_terminal_cwd_differs(self):
+        """Gateway: stored cwd differs from TERMINAL_CWD -> rebuild."""
+        from unittest.mock import patch
+        from agent.conversation_loop import _stored_prompt_matches_runtime
+
+        agent = self._make_agent()
+        with tempfile.TemporaryDirectory() as term_cwd, tempfile.TemporaryDirectory() as other_cwd:
+            stored_prompt = (
+                self._host_block(other_cwd)
+                + "Model: test/model\n"
+                "Provider: openrouter\n"
+            )
+            with patch.dict(os.environ, {"TERMINAL_CWD": term_cwd}):
+                assert _stored_prompt_matches_runtime(agent, stored_prompt) is False, (
+                    "Expected False when stored cwd differs from TERMINAL_CWD"
+                )
+
+    def test_built_prompt_contains_platform_line(self):
+        """The built system prompt must carry a Platform: line so drift detection works."""
+        import tempfile
+        from pathlib import Path
+        from unittest.mock import patch
+        from hermes_state import SessionDB
+        from run_agent import AIAgent
+        from agent.system_prompt import build_system_prompt_parts
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            db = SessionDB(db_path=Path(tmpdir) / "test.db")
+            with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}):
+                agent = AIAgent(
+                    api_key="test-key",
+                    base_url="https://openrouter.ai/api/v1",
+                    model="test/model",
+                    provider="openrouter",
+                    quiet_mode=True,
+                    session_db=db,
+                    session_id="platform-test",
+                    skip_context_files=True,
+                    skip_memory=True,
+                )
+            agent.platform = "cli"
+            parts = build_system_prompt_parts(agent)
+            assert "Platform: cli" in parts["volatile"], (
+                "Built prompt missing 'Platform: cli' — drift detection cannot read it"
+            )
diff --git a/tests/run_agent/test_dropped_tool_call_recovery.py b/tests/run_agent/test_dropped_tool_call_recovery.py
new file mode 100644
index 00000000000..d540596a61e
--- /dev/null
+++ b/tests/run_agent/test_dropped_tool_call_recovery.py
@@ -0,0 +1,239 @@
+"""Regression tests for dropped tool-call recovery.
+
+Some providers (observed: claude-opus-4.8 / claude-sonnet-4.5 on GitHub
+Copilot, ~2026-07) return ``finish_reason="tool_calls"`` while the parsed
+``tool_calls`` array is empty — the model signalled it wanted to act but the
+payload shipped no call. Before the fix, the conversation loop took the
+no-tool-calls ``else`` branch, treated the turn's narration as the final
+answer, and exited with the task unstarted. On an unattended multi-step job
+(e.g. a scheduled PR reviewer) this silently did nothing.
+
+The fix keys on the provider contract violation itself
+(``finish_reason == "tool_calls"`` with zero ``tool_calls``) and re-prompts,
+bounded to 3 consecutive stalls, with the budget resetting after any
+successful tool round so it guards each stall rather than the whole run. A
+genuine ``finish_reason="stop"`` text turn is unaffected.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+@pytest.fixture()
+def loop_agent():
+    """AIAgent with a mocked OpenAI client (mirrors test_run_agent's fixture)
+    so we can stage a dropped-tool-call response + continuation pair on
+    ``.chat.completions.create``."""
+    from run_agent import AIAgent
+    with (
+        patch("run_agent.get_tool_definitions", return_value=[]),
+        patch("run_agent.check_toolset_requirements", return_value={}),
+        patch("run_agent.OpenAI"),
+    ):
+        agent = AIAgent(
+            api_key="test-key-1234567890",
+            base_url="https://openrouter.ai/api/v1",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+        )
+        agent.client = MagicMock()
+        agent._cached_system_prompt = "You are helpful."
+        agent._use_prompt_caching = False
+        agent.tool_delay = 0
+        agent.compression_enabled = False
+        agent.save_trajectories = False
+        return agent
+
+
+def _dropped_tool_call_response(content: str):
+    """A response whose finish_reason claims a tool call, but tool_calls is
+    empty — the provider contract violation this fix recovers from."""
+    from tests.run_agent.test_run_agent import _mock_assistant_msg
+    return SimpleNamespace(
+        id="chatcmpl-dropped",
+        model="test/model",
+        choices=[SimpleNamespace(
+            index=0,
+            message=_mock_assistant_msg(content=content, tool_calls=None),
+            finish_reason="tool_calls",
+        )],
+        usage=None,
+    )
+
+
+class TestDroppedToolCallRecovery:
+    def test_dropped_tool_call_reprompts_instead_of_exiting(self, loop_agent):
+        """finish_reason=tool_calls with an empty tool_calls array must
+        re-prompt the model to emit the call rather than exiting the loop
+        with the narration as the final answer."""
+        from tests.run_agent.test_run_agent import _mock_response
+
+        loop_agent.client.chat.completions.create.side_effect = [
+            _dropped_tool_call_response("Let me verify the PR and gather evidence."),
+            _mock_response(content="All checks pass. Approved.", finish_reason="stop"),
+        ]
+
+        with (
+            patch.object(loop_agent, "_persist_session"),
+            patch.object(loop_agent, "_save_trajectory"),
+            patch.object(loop_agent, "_cleanup_task_resources"),
+        ):
+            result = loop_agent.run_conversation("review the PR")
+
+        assert loop_agent.client.chat.completions.create.call_count == 2, (
+            "A dropped tool call must trigger a re-prompt (second API call), "
+            "not exit the loop after one call."
+        )
+
+        # The loop must have injected a nudge user-message telling the model to
+        # issue the actual tool call.
+        second_call = loop_agent.client.chat.completions.create.call_args_list[1]
+        msgs = second_call.kwargs.get("messages") or second_call.args[0].get("messages")
+        last_user = next(
+            (m for m in reversed(msgs) if m.get("role") == "user"), None,
+        )
+        assert last_user is not None
+        assert "tool call" in (last_user.get("content") or "").lower(), (
+            "The nudge must explicitly ask the model to issue the tool call."
+        )
+        assert "All checks pass" in result["final_response"]
+
+    def test_empty_content_dropped_tool_call_still_reprompts(self, loop_agent):
+        """The narration may live only in the reasoning field, leaving content
+        empty. The recovery must still fire — it keys on the finish_reason /
+        tool_calls mismatch, not on content being present."""
+        from tests.run_agent.test_run_agent import _mock_response
+
+        loop_agent.client.chat.completions.create.side_effect = [
+            _dropped_tool_call_response(""),  # no visible content at all
+            _mock_response(content="Done.", finish_reason="stop"),
+        ]
+
+        with (
+            patch.object(loop_agent, "_persist_session"),
+            patch.object(loop_agent, "_save_trajectory"),
+            patch.object(loop_agent, "_cleanup_task_resources"),
+        ):
+            result = loop_agent.run_conversation("review the PR")
+
+        assert loop_agent.client.chat.completions.create.call_count == 2, (
+            "An empty-content dropped tool call must still re-prompt."
+        )
+        assert result["completed"] is True
+
+    def test_clean_stop_text_turn_is_unaffected(self, loop_agent):
+        """A genuine finish_reason=stop text response must exit normally — the
+        recovery path must not fire on ordinary final answers."""
+        from tests.run_agent.test_run_agent import _mock_response
+
+        loop_agent.client.chat.completions.create.side_effect = [
+            _mock_response(content="Here is your answer.", finish_reason="stop"),
+        ]
+
+        with (
+            patch.object(loop_agent, "_persist_session"),
+            patch.object(loop_agent, "_save_trajectory"),
+            patch.object(loop_agent, "_cleanup_task_resources"),
+        ):
+            result = loop_agent.run_conversation("hello")
+
+        assert loop_agent.client.chat.completions.create.call_count == 1, (
+            "A clean finish_reason=stop turn must not trigger a re-prompt."
+        )
+        assert "Here is your answer." in result["final_response"]
+
+    def test_persistent_dropped_tool_calls_are_bounded(self, loop_agent):
+        """If the model never emits a call, the recovery must give up after a
+        bounded number of consecutive stalls instead of looping forever."""
+        from tests.run_agent.test_run_agent import _mock_response
+
+        # Stage plenty of dropped-tool-call responses followed by a clean stop,
+        # so that if the bound is respected the loop exits on its own well
+        # before exhausting the staged responses (no StopIteration).
+        loop_agent.client.chat.completions.create.side_effect = [
+            _dropped_tool_call_response("Let me check.") for _ in range(9)
+        ] + [_mock_response(content="done", finish_reason="stop")]
+
+        with (
+            patch.object(loop_agent, "_persist_session"),
+            patch.object(loop_agent, "_save_trajectory"),
+            patch.object(loop_agent, "_cleanup_task_resources"),
+        ):
+            result = loop_agent.run_conversation("review the PR")
+
+        # 1 initial call + at most 3 bounded re-prompts = 4 total before the
+        # guard stops firing. It must NOT consume all 9 staged stalls.
+        assert loop_agent.client.chat.completions.create.call_count <= 4, (
+            "Consecutive dropped tool calls must be bounded (no infinite loop)."
+        )
+        assert result is not None
+
+    def test_nudge_pair_is_ephemeral_scaffolding(self, loop_agent):
+        """The re-prompt pair (interim assistant turn + synthetic user nudge)
+        must be flagged as ephemeral scaffolding so persistence never writes
+        it to the durable transcript — a resumed session must not replay the
+        internal "issue the actual tool call now" instruction as user-authored
+        context (#69630 review follow-up)."""
+        from run_agent import _is_ephemeral_scaffolding
+        from tests.run_agent.test_run_agent import _mock_response
+
+        loop_agent.client.chat.completions.create.side_effect = [
+            _dropped_tool_call_response("Let me verify the PR."),
+            _mock_response(content="All checks pass. Approved.", finish_reason="stop"),
+        ]
+
+        with (
+            patch.object(loop_agent, "_persist_session"),
+            patch.object(loop_agent, "_save_trajectory"),
+            patch.object(loop_agent, "_cleanup_task_resources"),
+        ):
+            result = loop_agent.run_conversation("review the PR")
+
+        assert result["completed"] is True
+        # The finalization pop strips the answered pair from the live list —
+        # no flagged scaffolding may survive into the returned transcript.
+        leftover = [
+            m for m in result["messages"]
+            if isinstance(m, dict) and m.get("_dropped_toolcall_nudge")
+        ]
+        assert not leftover, (
+            "The re-prompt pair must be stripped at finalization, not kept "
+            "in the returned transcript."
+        )
+        # And the persistence filter must classify the flag as ephemeral so a
+        # mid-turn flush can never write the pair to the durable store either.
+        assert _is_ephemeral_scaffolding(
+            {"role": "user", "content": "nudge", "_dropped_toolcall_nudge": True}
+        ), (
+            "_dropped_toolcall_nudge messages must be classified as "
+            "ephemeral scaffolding so they are never persisted."
+        )
+
+    def test_unanswered_nudge_tail_is_stripped_at_finalization(self, loop_agent):
+        """If the model answers the nudge with a genuine final text turn, the
+        trailing scaffolding must not leave the transcript tail on a synthetic
+        user message (strict role alternation on the next turn)."""
+        from tests.run_agent.test_run_agent import _mock_response
+
+        loop_agent.client.chat.completions.create.side_effect = [
+            _dropped_tool_call_response("Let me check."),
+            _mock_response(content="Final answer.", finish_reason="stop"),
+        ]
+
+        with (
+            patch.object(loop_agent, "_persist_session"),
+            patch.object(loop_agent, "_save_trajectory"),
+            patch.object(loop_agent, "_cleanup_task_resources"),
+        ):
+            result = loop_agent.run_conversation("review the PR")
+
+        tail = result["messages"][-1]
+        assert tail.get("role") == "assistant", (
+            "The turn must end on the real assistant answer, not scaffolding."
+        )
+        assert not tail.get("_dropped_toolcall_nudge")
diff --git a/tests/run_agent/test_moa_fanout_cadence.py b/tests/run_agent/test_moa_fanout_cadence.py
new file mode 100644
index 00000000000..09cae419ee3
--- /dev/null
+++ b/tests/run_agent/test_moa_fanout_cadence.py
@@ -0,0 +1,222 @@
+"""every_n fanout cadence: advisors refresh every Nth tool iteration and
+off-cadence iterations reuse the cached guidance from the last on-cadence run.
+
+Redesigned from PR #63448's intent (issue #63393 — advisor fan-out multiplies
+turn latency/cost by the tool-iteration count). Unlike the submitted shape
+(which dropped references entirely on off-cadence iterations), off-cadence
+iterations here still feed the aggregator the LAST advisor guidance via the
+same cache-reuse mechanism the user_turn fanout uses.
+"""
+
+from types import SimpleNamespace
+
+
+def _response(content="done", *, tool_calls=None):
+    message = SimpleNamespace(content=content, tool_calls=tool_calls or [])
+    choice = SimpleNamespace(message=message, finish_reason="stop")
+    return SimpleNamespace(choices=[choice], usage=None, model="fake-model")
+
+
+def _cadence_config(home, fanout="every_n:3"):
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        f"""
+moa:
+  default_preset: review
+  presets:
+    review:
+      fanout: "{fanout}"
+      reference_models:
+        - provider: openai-codex
+          model: gpt-5.5
+      aggregator:
+        provider: openrouter
+        model: anthropic/claude-opus-4.8
+""".strip(),
+        encoding="utf-8",
+    )
+
+
+def _install_fake_llm(monkeypatch, ref_runs):
+    def fake_call_llm(**kwargs):
+        if kwargs["task"] == "moa_reference":
+            ref_runs.append(kwargs["model"])
+            return _response(f"advice #{len(ref_runs)}")
+        return _response("acted")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+
+def _iteration_messages(base, iterations):
+    """Yield message lists simulating a growing tool loop: the base user turn,
+    then one new (assistant tool_call, tool result) pair per iteration."""
+    msgs = list(base)
+    yield list(msgs)
+    for i in range(1, iterations):
+        msgs = msgs + [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {"id": f"c{i}", "function": {"name": "f", "arguments": "{}"}}
+                ],
+            },
+            {"role": "tool", "tool_call_id": f"c{i}", "content": f"result {i}"},
+        ]
+        yield list(msgs)
+
+
+def test_every_n_cadence_runs_references_every_nth_iteration(monkeypatch, tmp_path):
+    """With every_n:3, references run on iterations 1 and 4 of a 6-iteration
+    tool loop (1 on-cadence, then every 3rd), not on all 6."""
+    home = tmp_path / ".hermes"
+    _cadence_config(home, "every_n:3")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    ref_runs = []
+    _install_fake_llm(monkeypatch, ref_runs)
+
+    from agent.moa_loop import MoAChatCompletions
+
+    events = []
+    facade = MoAChatCompletions("review", reference_callback=lambda ev, **kw: events.append(ev))
+    base = [{"role": "user", "content": "do the thing"}]
+    for msgs in _iteration_messages(base, 6):
+        facade.create(messages=msgs, tools=[{"type": "function"}])
+
+    # 1 reference model × iterations {1, 4} on-cadence = 2 advisor runs.
+    assert len(ref_runs) == 2
+    # Display blocks only surface when references actually ran.
+    assert events.count("moa.reference") == 2
+    assert events.count("moa.aggregating") == 2
+
+
+def test_every_n_off_cadence_iterations_reuse_cached_guidance(monkeypatch, tmp_path):
+    """Off-cadence iterations must still give the aggregator the last
+    on-cadence advisor guidance (cache reuse), not run advisor-less."""
+    home = tmp_path / ".hermes"
+    _cadence_config(home, "every_n:3")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    ref_runs = []
+    _install_fake_llm(monkeypatch, ref_runs)
+
+    from agent.moa_loop import MoAChatCompletions
+
+    facade = MoAChatCompletions("review")
+    base = [{"role": "user", "content": "task"}]
+    prepared = [
+        facade.create(messages=msgs, tools=[], _moa_prepare_only=True)
+        for msgs in _iteration_messages(base, 3)
+    ]
+
+    # Iteration 1 ran the references; iterations 2-3 are off-cadence.
+    assert len(ref_runs) == 1
+    # Every iteration's aggregator request carries reference guidance...
+    assert all(p["guidance"] for p in prepared)
+    # ...and the off-cadence ones reuse iteration 1's exact advice text.
+    assert "advice #1" in prepared[0]["guidance"]
+    assert prepared[1]["guidance"] == prepared[0]["guidance"]
+    assert prepared[2]["guidance"] == prepared[0]["guidance"]
+
+
+def test_every_n_off_cadence_does_not_double_charge_usage(monkeypatch, tmp_path):
+    """Cache-reuse iterations must not re-report advisor usage/cost."""
+    home = tmp_path / ".hermes"
+    _cadence_config(home, "every_n:2")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    ref_runs = []
+    _install_fake_llm(monkeypatch, ref_runs)
+
+    from agent.moa_loop import MoAChatCompletions
+
+    facade = MoAChatCompletions("review")
+    base = [{"role": "user", "content": "task"}]
+    it = _iteration_messages(base, 2)
+
+    facade.create(messages=next(it), tools=[])
+    usage1, _cost1 = facade.consume_reference_usage()
+
+    facade.create(messages=next(it), tools=[])  # off-cadence: reuse
+    usage2, cost2 = facade.consume_reference_usage()
+
+    assert len(ref_runs) == 1
+    # The reuse iteration reports zero advisor usage and no cost.
+    assert usage2.input_tokens == 0 and usage2.output_tokens == 0
+    assert cost2 is None
+    assert usage1 is not usage2
+
+
+def test_every_n_counter_resets_on_new_user_turn(monkeypatch, tmp_path):
+    """A new user message starts a new turn: iteration 1 is on-cadence again,
+    regardless of where the previous turn's counter stood."""
+    home = tmp_path / ".hermes"
+    _cadence_config(home, "every_n:3")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    ref_runs = []
+    _install_fake_llm(monkeypatch, ref_runs)
+
+    from agent.moa_loop import MoAChatCompletions
+
+    facade = MoAChatCompletions("review")
+    turn1 = [{"role": "user", "content": "turn one"}]
+    msgs: list = turn1
+    for msgs in _iteration_messages(turn1, 2):
+        facade.create(messages=msgs, tools=[])
+    assert len(ref_runs) == 1  # iteration 2 was off-cadence
+
+    # New user turn appended after the tool loop → counter resets, advisors
+    # run immediately (fresh advice for the fresh request).
+    turn2 = msgs + [
+        {"role": "assistant", "content": "done with turn one"},
+        {"role": "user", "content": "turn two"},
+    ]
+    facade.create(messages=turn2, tools=[])
+    assert len(ref_runs) == 2
+
+
+def test_every_n_redundant_create_does_not_consume_cadence_slot(monkeypatch, tmp_path):
+    """A repeat create() with IDENTICAL state (e.g. a streaming retry) must not
+    advance the cadence counter — only real state changes count."""
+    home = tmp_path / ".hermes"
+    _cadence_config(home, "every_n:2")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    ref_runs = []
+    _install_fake_llm(monkeypatch, ref_runs)
+
+    from agent.moa_loop import MoAChatCompletions
+
+    facade = MoAChatCompletions("review")
+    base = [{"role": "user", "content": "task"}]
+    it = _iteration_messages(base, 3)
+
+    first = next(it)
+    facade.create(messages=first, tools=[])
+    facade.create(messages=first, tools=[])  # retry: same state, no slot used
+    assert facade._fanout_iteration_count == 1
+
+    facade.create(messages=next(it), tools=[])  # iteration 2: off-cadence
+    facade.create(messages=next(it), tools=[])  # iteration 3: on-cadence (every 2nd)
+    assert len(ref_runs) == 2
+
+
+def test_per_iteration_default_unchanged_by_cadence_state(monkeypatch, tmp_path):
+    """Default fanout still re-runs references on every state change."""
+    home = tmp_path / ".hermes"
+    _cadence_config(home, "per_iteration")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    ref_runs = []
+    _install_fake_llm(monkeypatch, ref_runs)
+
+    from agent.moa_loop import MoAChatCompletions
+
+    facade = MoAChatCompletions("review")
+    base = [{"role": "user", "content": "task"}]
+    for msgs in _iteration_messages(base, 3):
+        facade.create(messages=msgs, tools=[])
+
+    assert len(ref_runs) == 3
diff --git a/tests/run_agent/test_moa_loop_mode.py b/tests/run_agent/test_moa_loop_mode.py
index 50e3a008724..0ee9991120b 100644
--- a/tests/run_agent/test_moa_loop_mode.py
+++ b/tests/run_agent/test_moa_loop_mode.py
@@ -81,6 +81,140 @@ def test_moa_runtime_provider_uses_virtual_endpoint():
     assert runtime["api_key"] == "moa-virtual-provider"
 
 
+def test_moa_primary_restore_rebuilds_virtual_facade(monkeypatch, tmp_path):
+    """MoA sessions must restore from fallback without constructing OpenAI().
+
+    Regression for a long-lived MoA session that failed over to a real provider:
+    the next turn restored provider/model to MoA but tried to rebuild the shared
+    client from MoA's empty client_kwargs, raising "api_key client option must be
+    set" and then "Failed to recreate closed OpenAI client".
+    """
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        """
+moa:
+  default_preset: review
+  presets:
+    review:
+      reference_models:
+        - provider: openai-codex
+          model: gpt-5.5
+      aggregator:
+        provider: openrouter
+        model: anthropic/claude-opus-4.8
+""".strip(),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    agent = AIAgent(
+        api_key="moa-virtual-provider",
+        base_url="moa://local",
+        model="review",
+        provider="moa",
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+        enabled_toolsets=["file"],
+        max_iterations=1,
+    )
+    primary_client = agent.client
+
+    def fail_openai_rebuild(*_args, **_kwargs):
+        raise AssertionError("MoA restore must not build a real OpenAI client")
+
+    monkeypatch.setattr(agent, "_create_openai_client", fail_openai_rebuild)
+    setattr(agent, "_fallback_activated", True)
+    setattr(agent, "provider", "zai")
+    setattr(agent, "model", "glm-5.2")
+    agent.base_url = "https://api.z.ai/api/coding/paas/v4"
+    agent.api_key = "fallback-key"
+    setattr(agent, "_client_kwargs", {"api_key": "fallback-key", "base_url": agent.base_url})
+    agent.client = SimpleNamespace(close=lambda: None, _client=SimpleNamespace(is_closed=True))
+
+    assert agent._restore_primary_runtime() is True
+    assert getattr(agent, "provider") == "moa"
+    assert getattr(agent, "model") == "review"
+    assert agent.client is not primary_client
+    assert hasattr(agent.client.chat, "completions")
+    assert getattr(agent, "_fallback_activated") is False
+
+
+def test_moa_restored_facade_still_emits_reference_events(monkeypatch, tmp_path):
+    """A restored MoA facade must keep the reference_callback relay wired.
+
+    Regression for the naive-rebuild flaw in the original #53802 approach:
+    ``MoAClient(preset)`` without ``reference_callback`` restores a *working*
+    facade that silently stops emitting ``moa.reference``/``moa.aggregating``
+    display events for the rest of the session. The shared ``build_moa_facade``
+    factory rewires the relay to ``agent.tool_progress_callback`` on restore.
+    """
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        """
+moa:
+  default_preset: review
+  presets:
+    review:
+      reference_models:
+        - provider: openai-codex
+          model: gpt-5.5
+      aggregator:
+        provider: openrouter
+        model: anthropic/claude-opus-4.8
+""".strip(),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    agent = AIAgent(
+        api_key="moa-virtual-provider",
+        base_url="moa://local",
+        model="review",
+        provider="moa",
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+        enabled_toolsets=["file"],
+        max_iterations=1,
+    )
+
+    # Simulate a fallback to a real provider, then restore.
+    setattr(agent, "_fallback_activated", True)
+    setattr(agent, "provider", "zai")
+    setattr(agent, "model", "glm-5.2")
+    agent.base_url = "https://api.z.ai/api/coding/paas/v4"
+    agent.api_key = "fallback-key"
+    setattr(agent, "_client_kwargs", {"api_key": "fallback-key", "base_url": agent.base_url})
+    agent.client = SimpleNamespace(close=lambda: None, _client=SimpleNamespace(is_closed=True))
+    assert agent._restore_primary_runtime() is True
+
+    # The relay reads tool_progress_callback at emit time — attach a recorder
+    # and fire the facade's internal _emit exactly as the fan-out does.
+    events = []
+
+    def record_progress(event, *args, **kwargs):
+        events.append((event, args, kwargs))
+
+    agent.tool_progress_callback = record_progress
+    completions = agent.client.chat.completions
+    assert completions.reference_callback is not None, (
+        "restored MoA facade lost its reference_callback relay"
+    )
+    completions._emit(
+        "moa.reference", index=0, count=1, label="openai-codex/gpt-5.5", text="advice"
+    )
+    completions._emit("moa.aggregating", aggregator="openrouter", ref_count=1)
+
+    assert [e[0] for e in events] == ["moa.reference", "moa.aggregating"]
+    ref_event = events[0]
+    assert ref_event[1][0] == "openai-codex/gpt-5.5"
+    assert ref_event[1][1] == "advice"
+    assert ref_event[2] == {"moa_index": 0, "moa_count": 1}
+
+
 def test_moa_does_not_cap_output_tokens(monkeypatch, tmp_path):
     """MoA must not inject an output cap on reference or aggregator calls.
 
@@ -261,6 +395,313 @@ def test_moa_provider_backed_slot_survives_aux_resolution(monkeypatch, provider)
     assert api_key == f"token-for-{provider}"
 
 
+def test_moa_copilot_reference_forwards_user_initiator_header(monkeypatch):
+    """Copilot MoA advisors must carry the same user-turn attribution as main calls.
+
+    Copilot Pro/Pro+ gates some premium chat models on the ``x-initiator``
+    request header. MoA references are direct fan-out for the user's current
+    turn, so Copilot advisors need ``x-initiator: user`` rather than inheriting
+    the Copilot language-server default attribution.
+    """
+    from agent import moa_loop
+
+    calls = []
+
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda _slot: {
+            "provider": "copilot",
+            "model": "claude-sonnet-4.6",
+            "api_mode": "chat_completions",
+            "base_url": "https://api.githubcopilot.com",
+            "api_key": "copilot-token",
+        },
+    )
+
+    def fake_call_llm(**kwargs):
+        calls.append(kwargs)
+        return _response("copilot advice")
+
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+
+    _label, text, _acct = moa_loop._run_reference(
+        {"provider": "copilot", "model": "claude-sonnet-4.6"},
+        [{"role": "user", "content": "solve this"}],
+    )
+
+    assert text == "copilot advice"
+    assert calls[0]["task"] == "moa_reference"
+    assert calls[0]["extra_headers"] == {"x-initiator": "user"}
+
+
+def test_moa_non_copilot_reference_does_not_forward_initiator_header(monkeypatch):
+    """The Copilot attribution header must stay scoped to Copilot advisors."""
+    from agent import moa_loop
+
+    calls = []
+
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda _slot: {
+            "provider": "openrouter",
+            "model": "anthropic/claude-sonnet-4.6",
+            "api_mode": "chat_completions",
+            "base_url": "https://openrouter.ai/api/v1",
+            "api_key": "openrouter-token",
+        },
+    )
+
+    def fake_call_llm(**kwargs):
+        calls.append(kwargs)
+        return _response("openrouter advice")
+
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+
+    _label, text, _acct = moa_loop._run_reference(
+        {"provider": "openrouter", "model": "anthropic/claude-sonnet-4.6"},
+        [{"role": "user", "content": "solve this"}],
+    )
+
+    assert text == "openrouter advice"
+    assert calls[0]["task"] == "moa_reference"
+    assert calls[0]["extra_headers"] is None
+
+
+@pytest.mark.parametrize(
+    "provider_spelling",
+    ["copilot", "github-copilot", "github", "github-models", "Copilot", "copilot-acp"],
+)
+def test_moa_copilot_alias_spellings_forward_initiator_header(
+    monkeypatch, provider_spelling
+):
+    """Every Copilot alias spelling must trigger the x-initiator header.
+
+    Slot configs spell the provider inconsistently (github, github-copilot,
+    github-models, copilot-acp, mixed case); the header gate goes through the
+    auxiliary client's canonical alias normalization so all of them get the
+    user-turn attribution, not just the literal string "copilot".
+    """
+    from agent import moa_loop
+
+    calls = []
+
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda _slot: {
+            "provider": provider_spelling,
+            "model": "claude-sonnet-4.6",
+            "api_mode": "chat_completions",
+            "base_url": "https://api.githubcopilot.com",
+            "api_key": "copilot-token",
+        },
+    )
+
+    def fake_call_llm(**kwargs):
+        calls.append(kwargs)
+        return _response("copilot advice")
+
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+
+    _label, text, _acct = moa_loop._run_reference(
+        {"provider": provider_spelling, "model": "claude-sonnet-4.6"},
+        [{"role": "user", "content": "solve this"}],
+    )
+
+    assert text == "copilot advice"
+    assert calls[0]["extra_headers"] == {"x-initiator": "user"}
+
+
+def test_call_llm_extra_headers_reach_transport_create(monkeypatch):
+    """extra_headers must reach the SDK client's create() kwargs.
+
+    Transport-boundary regression for #60293: mocking call_llm proves nothing
+    about delivery — this asserts the header survives call_llm's request
+    building and lands in the kwargs handed to chat.completions.create().
+    """
+    from types import SimpleNamespace
+
+    from agent import auxiliary_client as ac
+
+    captured = {}
+
+    class _Completions:
+        def create(self, **kwargs):
+            captured.update(kwargs)
+            return _response("ok")
+
+    fake_client = SimpleNamespace(
+        chat=SimpleNamespace(completions=_Completions()),
+        base_url="https://api.githubcopilot.com",
+    )
+    monkeypatch.setattr(
+        ac,
+        "_resolve_task_provider_model",
+        lambda *a, **k: (
+            "copilot",
+            "claude-sonnet-4.6",
+            "https://api.githubcopilot.com",
+            "copilot-token",
+            "chat_completions",
+        ),
+    )
+    monkeypatch.setattr(ac, "_get_cached_client", lambda *a, **k: (fake_client, "claude-sonnet-4.6"))
+    monkeypatch.setattr(ac, "_validate_llm_response", lambda resp, task, **_kw: resp)
+
+    ac.call_llm(
+        provider="copilot",
+        model="claude-sonnet-4.6",
+        messages=[{"role": "user", "content": "hi"}],
+        extra_headers={"x-initiator": "user"},
+    )
+
+    assert captured.get("extra_headers") == {"x-initiator": "user"}
+    # And it must not leak into unrelated request fields.
+    assert "x-initiator" not in captured.get("extra_body", {}) if captured.get("extra_body") else True
+
+
+def test_retry_same_provider_sync_preserves_extra_headers(monkeypatch):
+    """The same-provider retry rebuild must carry extra_headers through.
+
+    Regression for #60293's follow-up: a credential-refresh/pool-rotation
+    retry rebuilds the request kwargs from scratch — without forwarding
+    extra_headers, the retried Copilot advisor call silently loses its
+    ``x-initiator: user`` attribution and can be rejected.
+    """
+    from types import SimpleNamespace
+
+    from agent import auxiliary_client as ac
+
+    captured = {}
+
+    class _Completions:
+        def create(self, **kwargs):
+            captured.update(kwargs)
+            return _response("retried ok")
+
+    fake_client = SimpleNamespace(
+        chat=SimpleNamespace(completions=_Completions()),
+        base_url="https://api.githubcopilot.com",
+    )
+    monkeypatch.setattr(ac, "_get_cached_client", lambda *a, **k: (fake_client, "claude-sonnet-4.6"))
+    monkeypatch.setattr(ac, "_validate_llm_response", lambda resp, task, **_kw: resp)
+
+    ac._retry_same_provider_sync(
+        task=None,
+        resolved_provider="copilot",
+        resolved_model="claude-sonnet-4.6",
+        resolved_base_url="https://api.githubcopilot.com",
+        resolved_api_key="copilot-token",
+        resolved_api_mode="chat_completions",
+        main_runtime=None,
+        final_model="claude-sonnet-4.6",
+        messages=[{"role": "user", "content": "hi"}],
+        temperature=None,
+        max_tokens=None,
+        tools=None,
+        effective_timeout=30.0,
+        effective_extra_body={},
+        reasoning_config=None,
+        extra_headers={"x-initiator": "user"},
+    )
+
+    assert captured.get("extra_headers") == {"x-initiator": "user"}
+
+
+def test_moa_gemini_aggregator_sanitize_uses_real_model(monkeypatch, tmp_path):
+    """MoA turns must sanitize tool_calls against the AGGREGATOR model, not the preset.
+
+    Regression for #66212 / #65092: under MoA, ``agent.model`` holds the
+    virtual preset name (e.g. "review"), so passing it to
+    _sanitize_tool_calls_for_strict_api makes
+    _model_consumes_thought_signature() return False and strips
+    ``extra_content`` (Gemini thought_signature) from replayed tool_calls —
+    the Gemini aggregator then 400s with "Function call is missing a
+    thought_signature in functionCall parts."
+    """
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        """
+moa:
+  default_preset: review
+  presets:
+    review:
+      reference_models:
+        - provider: openai-codex
+          model: gpt-5.5
+      aggregator:
+        provider: gemini
+        model: gemini-3-pro-preview
+""".strip(),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    sanitize_models = []
+
+    tool_call = SimpleNamespace(
+        id="call_1",
+        type="function",
+        function=SimpleNamespace(name="read_file", arguments='{"path": "x"}'),
+    )
+
+    responses = iter(
+        [
+            _response(None, tool_calls=[tool_call]),
+            _response("aggregator done"),
+        ]
+    )
+
+    def fake_call_llm(**kwargs):
+        if kwargs["task"] == "moa_reference":
+            return _response("reference advice")
+        return next(responses)
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    agent = AIAgent(
+        api_key="moa-virtual-provider",
+        base_url="moa://local",
+        model="review",
+        provider="moa",
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+        enabled_toolsets=["file"],
+        max_iterations=3,
+    )
+
+    real_sanitize = type(agent)._sanitize_tool_calls_for_strict_api
+
+    def spy_sanitize(api_msg, model=None):
+        sanitize_models.append(model)
+        return real_sanitize(api_msg, model=model)
+
+    monkeypatch.setattr(
+        type(agent), "_sanitize_tool_calls_for_strict_api", staticmethod(spy_sanitize)
+    )
+    monkeypatch.setattr(
+        agent, "execute_tool", lambda *_a, **_k: "file contents", raising=False
+    )
+
+    result = agent.run_conversation("read the file")
+
+    assert result["final_response"] == "aggregator done"
+    # Once the history contains an assistant tool_call turn, the sanitize
+    # pass must be asked about the REAL aggregator model — never the virtual
+    # preset name (which would strip Gemini's thought_signature). The very
+    # first API call may still see the preset (the facade hasn't resolved a
+    # slot yet), but no tool_calls exist in history at that point.
+    assert any(m == "gemini-3-pro-preview" for m in sanitize_models), sanitize_models
+    first_resolved = sanitize_models.index("gemini-3-pro-preview")
+    assert all(
+        m == "gemini-3-pro-preview" for m in sanitize_models[first_resolved:]
+    ), sanitize_models
+
+
 def test_moa_slot_runtime_falls_back_on_resolution_error(monkeypatch):
     """A slot whose provider can't be resolved still attempts the call with the
     bare provider/model rather than aborting the whole MoA turn."""
@@ -565,6 +1006,51 @@ moa:
     assert agg_call["messages"][-1]["content"] == "question"
 
 
+def test_moa_disabled_reference_is_not_called(monkeypatch, tmp_path):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        """
+moa:
+  default_preset: review
+  presets:
+    review:
+      reference_models:
+        - provider: openai-codex
+          model: gpt-5.5
+          enabled: false
+        - provider: openrouter
+          model: deepseek/deepseek-v4-pro
+          enabled: true
+      aggregator:
+        provider: openrouter
+        model: anthropic/claude-opus-4.8
+""".strip(),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    calls = []
+
+    def fake_call_llm(**kwargs):
+        calls.append(kwargs)
+        if kwargs["task"] == "moa_reference":
+            return _response(f"reference from {kwargs['provider']}:{kwargs['model']}")
+        return _response("aggregator acted")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    from agent.moa_loop import MoAChatCompletions
+
+    facade = MoAChatCompletions("review")
+    facade.create(messages=[{"role": "user", "content": "question"}], tools=[{"type": "function"}])
+
+    reference_calls = [c for c in calls if c["task"] == "moa_reference"]
+    assert [(c["provider"], c["model"]) for c in reference_calls] == [
+        ("openrouter", "deepseek/deepseek-v4-pro")
+    ]
+    assert calls[-1]["task"] == "moa_aggregator"
+
+
 def test_references_run_in_parallel(monkeypatch):
     """References fan out concurrently (delegate-batch semantics), not serially.
 
@@ -615,10 +1101,87 @@ def test_references_run_in_parallel(monkeypatch):
     assert out[0][1] == "resp-p1"
 
 
-def _ref_config(home):
+def test_references_parallel_without_agent_is_unaffected(monkeypatch):
+    """No agent passed (the pre-fix call shape) must behave exactly as
+    before: block until every reference completes, no interrupt check."""
+    import time
+
+    from agent import moa_loop
+
+    monkeypatch.setattr(moa_loop, "get_transport", lambda *_a, **_k: None)
+    # Poll interval shorter than the reference's own sleep so the assertion
+    # below would catch a regression that waits a whole poll cycle extra.
+    monkeypatch.setattr(moa_loop, "_REFERENCE_POLL_INTERVAL_S", 0.05)
+
+    def slow_call_llm(**kwargs):
+        time.sleep(0.2)
+        return _response(f"resp-{kwargs['provider']}")
+
+    monkeypatch.setattr(moa_loop, "call_llm", slow_call_llm)
+
+    refs = [{"provider": "p1", "model": "ok"}]
+    out = moa_loop._run_references_parallel(
+        refs, [{"role": "user", "content": "hi"}],
+    )
+
+    assert out[0][1] == "resp-p1"
+
+
+def test_references_parallel_interrupt_aborts_wait(monkeypatch):
+    """A user interrupt mid-fanout must stop the wait instead of blocking
+    until every reference (including a wedged one) finishes or times out on
+    its own — mirroring the interrupt check agent.tool_executor already
+    applies to its own concurrent tool batch."""
+    import threading
+    import time
+
+    from agent import moa_loop
+
+    monkeypatch.setattr(moa_loop, "get_transport", lambda *_a, **_k: None)
+    monkeypatch.setattr(moa_loop, "_REFERENCE_POLL_INTERVAL_S", 0.05)
+
+    fake_agent = SimpleNamespace(_interrupt_requested=False)
+    release_wedged = threading.Event()
+
+    def fake_call_llm(**kwargs):
+        if kwargs["provider"] == "fast":
+            # Simulate the interrupt arriving right after the fast reference
+            # finishes, while the wedged one is still in flight.
+            fake_agent._interrupt_requested = True
+            return _response("fast output")
+        # "wedged" — never returns within the test unless released, standing
+        # in for a reference whose own (possibly very long) timeout hasn't
+        # elapsed yet.
+        release_wedged.wait(timeout=5)
+        return _response("should not be observed")
+
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+
+    refs = [
+        {"provider": "fast", "model": "m1"},
+        {"provider": "wedged", "model": "m2"},
+    ]
+    try:
+        start = time.monotonic()
+        out = moa_loop._run_references_parallel(
+            refs, [{"role": "user", "content": "hi"}], agent=fake_agent,
+        )
+        elapsed = time.monotonic() - start
+
+        # Must return promptly once interrupted, not block for the wedged
+        # reference's full (5s test-simulated) duration.
+        assert elapsed < 2.0, f"interrupt did not abort the wait (took {elapsed:.2f}s)"
+        assert out[0][1] == "fast output"
+        assert "interrupted" in out[1][1]
+    finally:
+        release_wedged.set()  # don't leak a blocked thread past the test
+
+
+def _ref_config(home, fanout: str | None = None):
     home.mkdir()
+    fanout_line = f"\n      fanout: {fanout}" if fanout else ""
     (home / "config.yaml").write_text(
-        """
+        f"""
 moa:
   default_preset: review
   presets:
@@ -630,7 +1193,7 @@ moa:
           model: anthropic/claude-opus-4.8
       aggregator:
         provider: openrouter
-        model: anthropic/claude-opus-4.8
+        model: anthropic/claude-opus-4.8{fanout_line}
 """.strip(),
         encoding="utf-8",
     )
@@ -672,13 +1235,15 @@ def test_moa_facade_emits_reference_then_aggregating(monkeypatch, tmp_path):
 def test_moa_facade_reruns_references_on_new_tool_result(monkeypatch, tmp_path):
     """References re-run when a new tool result advances the task state.
 
-    The agent loop calls create() once per tool-loop iteration. References must
-    judge the LATEST state, so a new tool result is a cache MISS and re-runs the
-    references — but a redundant create() call with the SAME state is a cache
-    HIT (no re-run, no re-emit), so we don't fire on a pure no-op re-call.
+    Pins fanout: per_iteration explicitly (the default became user_turn,
+    #67199). In this mode the agent loop calls create() once per tool-loop
+    iteration and references must judge the LATEST state, so a new tool
+    result is a cache MISS and re-runs the references — but a redundant
+    create() call with the SAME state is a cache HIT (no re-run, no
+    re-emit), so we don't fire on a pure no-op re-call.
     """
     home = tmp_path / ".hermes"
-    _ref_config(home)
+    _ref_config(home, fanout="per_iteration")
     monkeypatch.setenv("HERMES_HOME", str(home))
 
     ref_runs = []
@@ -1379,3 +1944,726 @@ def test_prepared_aggregator_preserves_reasoning_config(monkeypatch):
     )
 
     assert captured["reasoning_config"] == expected_reasoning
+
+
+
+def test_reference_filtering_preserves_accounting_triples():
+    from agent.moa_loop import (
+        _RefAccounting,
+        _failed_reference_labels,
+        _successful_references,
+    )
+    from agent.usage_pricing import CanonicalUsage
+
+    good_accounting = _RefAccounting(CanonicalUsage(input_tokens=7), 0.07)
+    failed_accounting = _RefAccounting(CanonicalUsage(input_tokens=5), 0.05)
+    outputs = [
+        ("good-model", "useful advice", good_accounting),
+        ("bad-model", "[failed: raw provider secret]", failed_accounting),
+    ]
+
+    successful = _successful_references(outputs)
+    assert successful == [outputs[0]]
+    assert successful[0][2] is good_accounting
+    assert _failed_reference_labels(outputs) == ["bad-model"]
+
+
+def test_reference_filtering_excludes_recursion_guard_skips():
+    """[skipped: …] recursion-guard notes are internal sentinels, not advice —
+    they must be filtered out of the aggregator prompt like [failed: …]."""
+    from agent.moa_loop import (
+        _RefAccounting,
+        _failed_reference_labels,
+        _is_failed_reference,
+        _successful_references,
+    )
+    from agent.usage_pricing import CanonicalUsage
+
+    outputs = [
+        ("good-model", "useful advice", _RefAccounting(CanonicalUsage())),
+        (
+            "moa:nested",
+            "[skipped: MoA presets cannot recursively reference MoA]",
+            _RefAccounting(CanonicalUsage()),
+        ),
+    ]
+
+    assert _is_failed_reference(outputs[1][1])
+    assert _successful_references(outputs) == [outputs[0]]
+    assert _failed_reference_labels(outputs) == ["moa:nested"]
+
+
+def test_aggregate_moa_context_sanitizes_failed_reference_and_forwards_timeout(monkeypatch):
+    from agent import moa_loop
+    from agent.usage_pricing import CanonicalUsage
+
+    outputs = [
+        ("good-model", "useful advice", moa_loop._RefAccounting(CanonicalUsage())),
+        (
+            "bad-model",
+            "[failed: HTTP 401 key=super-secret]",
+            moa_loop._RefAccounting(CanonicalUsage()),
+        ),
+    ]
+    fanout_kwargs = {}
+    aggregator_calls = []
+
+    def fake_fanout(*args, **kwargs):
+        fanout_kwargs.update(kwargs)
+        return outputs
+
+    def fake_call_llm(**kwargs):
+        aggregator_calls.append(kwargs)
+        return _response("synthesized guidance")
+
+    monkeypatch.setattr(moa_loop, "_run_references_parallel", fake_fanout)
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda slot: {"provider": slot["provider"], "model": slot["model"]},
+    )
+
+    result = moa_loop.aggregate_moa_context(
+        user_prompt="review this",
+        api_messages=[{"role": "user", "content": "review this"}],
+        reference_models=[
+            {"provider": "openrouter", "model": "good-model"},
+            {"provider": "openrouter", "model": "bad-model"},
+        ],
+        aggregator={"provider": "openrouter", "model": "aggregator"},
+        reference_timeout=17.5,
+        degraded_reference_policy="loud",
+    )
+
+    assert fanout_kwargs["reference_timeout"] == 17.5
+    private_prompt = aggregator_calls[0]["messages"][0]["content"]
+    assert "useful advice" in private_prompt
+    assert "super-secret" not in private_prompt
+    assert "Reference models unavailable: bad-model" in private_prompt
+    assert "super-secret" not in result
+
+
+def test_moa_facade_sanitizes_failures_without_breaking_accounting(monkeypatch, tmp_path):
+    from agent import moa_loop
+    from agent.usage_pricing import CanonicalUsage
+
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        """
+moa:
+  default_preset: review
+  presets:
+    review:
+      reference_timeout: 19
+      degraded_reference_policy: silent
+      reference_models:
+        - provider: openrouter
+          model: good-model
+        - provider: openrouter
+          model: bad-model
+      aggregator:
+        provider: openrouter
+        model: aggregator
+""".strip(),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    outputs = [
+        (
+            "good-model",
+            "useful advice",
+            moa_loop._RefAccounting(CanonicalUsage(input_tokens=7), 0.07),
+        ),
+        (
+            "bad-model",
+            "[failed: HTTP 401 key=super-secret]",
+            moa_loop._RefAccounting(CanonicalUsage(input_tokens=5), 0.05),
+        ),
+    ]
+    fanout_kwargs = {}
+    aggregator_calls = []
+
+    def fake_fanout(*args, **kwargs):
+        fanout_kwargs.update(kwargs)
+        return outputs
+
+    def fake_call_llm(**kwargs):
+        aggregator_calls.append(kwargs)
+        return _response("aggregator acted")
+
+    monkeypatch.setattr(moa_loop, "_run_references_parallel", fake_fanout)
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda slot: {"provider": slot["provider"], "model": slot["model"]},
+    )
+
+    facade = moa_loop.MoAChatCompletions("review")
+    facade.create(messages=[{"role": "user", "content": "review this"}], tools=[])
+
+    assert fanout_kwargs["reference_timeout"] == 19.0
+    private_prompt = str(aggregator_calls[0]["messages"])
+    assert "useful advice" in private_prompt
+    assert "super-secret" not in private_prompt
+    assert "Reference models unavailable" not in private_prompt
+    usage, cost = facade.consume_reference_usage()
+    assert usage.input_tokens == 12
+    assert cost == pytest.approx(0.12)
+    assert facade._pending_trace["reference_outputs"] == outputs
+
+
+def test_run_reference_forwards_configured_timeout(monkeypatch):
+    from agent import moa_loop
+
+    calls = []
+
+    def fake_call_llm(**kwargs):
+        calls.append(kwargs)
+        return _response("advice")
+
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda slot: {"provider": "openrouter", "model": slot["model"]},
+    )
+    monkeypatch.setattr(
+        "agent.usage_pricing.estimate_usage_cost",
+        lambda *args, **kwargs: SimpleNamespace(
+            amount_usd=None, status="unavailable", source=None
+        ),
+    )
+
+    label, text, accounting = moa_loop._run_reference(
+        {"provider": "openrouter", "model": "advisor"},
+        [{"role": "user", "content": "review"}],
+        reference_timeout=23.5,
+    )
+
+    assert (label, text) == ("openrouter:advisor", "advice")
+    assert calls[0]["timeout"] == 23.5
+    assert isinstance(accounting, moa_loop._RefAccounting)
+
+
+def test_aggregate_skips_aggregator_when_all_references_failed(monkeypatch):
+    """When every reference returns [failed: …], the aggregator is skipped entirely."""
+    from agent.moa_loop import aggregate_moa_context
+
+    call_count = {"n": 0}
+
+    def fake_call_llm(**kwargs):
+        call_count["n"] += 1
+        if kwargs["task"] == "moa_reference":
+            raise RuntimeError("provider down key=super-secret")
+        raise AssertionError("aggregator should not be called when all references fail")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+    monkeypatch.setattr(
+        "agent.moa_loop._slot_runtime",
+        lambda slot: {"provider": slot["provider"], "model": slot["model"]},
+    )
+
+    result = aggregate_moa_context(
+        user_prompt="do something",
+        api_messages=[{"role": "user", "content": "do something"}],
+        reference_models=[
+            {"provider": "openai", "model": "gpt-4"},
+            {"provider": "anthropic", "model": "claude-opus"},
+        ],
+        aggregator={"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+    )
+
+    # The aggregator LLM call was never made.
+    assert call_count["n"] == 2  # only the two reference calls
+    # The result carries a sanitized unavailability notice (never raw
+    # provider error text) so the main agent can still act.
+    assert "all reference models failed" in result
+    assert "Reference models unavailable" in result
+    assert "super-secret" not in result
+
+
+def test_aggregate_skips_aggregator_when_all_references_skipped(monkeypatch):
+    """References that are skipped (MoA recursion guard) also trigger the early return."""
+    from agent.moa_loop import aggregate_moa_context
+
+    def fake_call_llm(**kwargs):
+        raise AssertionError("aggregator should not be called when all references are skipped")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+
+    # Both reference models are "moa" — they hit the recursion guard and are
+    # returned as "[skipped: …]" without calling call_llm at all.
+    result = aggregate_moa_context(
+        user_prompt="do something",
+        api_messages=[{"role": "user", "content": "do something"}],
+        reference_models=[
+            {"provider": "moa", "model": "preset-a"},
+            {"provider": "moa", "model": "preset-b"},
+        ],
+        aggregator={"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+    )
+
+    assert "all reference models failed" in result
+    assert "Reference models unavailable" in result
+
+
+def _facade_all_failed_fixture(monkeypatch, tmp_path, policy):
+    """Common scaffolding: a 'review' preset whose references ALL fail."""
+    from agent import moa_loop
+    from agent.usage_pricing import CanonicalUsage
+
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        f"""
+moa:
+  default_preset: review
+  presets:
+    review:
+      degraded_reference_policy: {policy}
+      reference_models:
+        - provider: openrouter
+          model: bad-model-a
+        - provider: openrouter
+          model: bad-model-b
+      aggregator:
+        provider: openrouter
+        model: aggregator
+""".strip(),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    outputs = [
+        (
+            "bad-model-a",
+            "[failed: HTTP 401 key=super-secret]",
+            moa_loop._RefAccounting(CanonicalUsage(input_tokens=5), 0.05),
+        ),
+        (
+            "bad-model-b",
+            "[failed: timeout after 900s]",
+            moa_loop._RefAccounting(CanonicalUsage(input_tokens=3), 0.03),
+        ),
+    ]
+    aggregator_calls = []
+
+    def fake_call_llm(**kwargs):
+        aggregator_calls.append(kwargs)
+        return _response("aggregator acted alone")
+
+    monkeypatch.setattr(moa_loop, "_run_references_parallel", lambda *a, **k: outputs)
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda slot: {"provider": slot["provider"], "model": slot["model"]},
+    )
+    return moa_loop, outputs, aggregator_calls
+
+
+def test_moa_facade_acts_aggregator_alone_when_all_references_fail_loud(
+    monkeypatch, tmp_path
+):
+    """Facade path (MoAChatCompletions.create): when every reference fails,
+    the aggregator acts alone — no 'use the reference responses below'
+    guidance wrapping a wall of failure sentinels. Under the loud policy the
+    sanitized unavailability notice is still disclosed."""
+    moa_loop, outputs, aggregator_calls = _facade_all_failed_fixture(
+        monkeypatch, tmp_path, "loud"
+    )
+
+    facade = moa_loop.MoAChatCompletions("review")
+    response = facade.create(
+        messages=[{"role": "user", "content": "review this"}], tools=[]
+    )
+
+    # The aggregator still acted (it IS the acting model)…
+    assert len(aggregator_calls) == 1
+    prompt = str(aggregator_calls[0]["messages"])
+    # …but got no failure sentinels or raw provider error text…
+    assert "[failed:" not in prompt
+    assert "super-secret" not in prompt
+    assert "Use the reference responses below" not in prompt
+    # …only the sanitized loud-policy notice.
+    assert "Reference models unavailable" in prompt
+    assert "bad-model-a" in prompt
+    # Accounting for the failed fan-out is still folded into the turn.
+    usage, cost = facade.consume_reference_usage()
+    assert usage.input_tokens == 8
+    assert cost == pytest.approx(0.08)
+    assert response.choices[0].message.content == "aggregator acted alone"
+
+
+def test_moa_facade_acts_aggregator_alone_when_all_references_fail_silent(
+    monkeypatch, tmp_path
+):
+    """Silent policy: all-failed turns attach no reference guidance at all."""
+    moa_loop, _outputs, aggregator_calls = _facade_all_failed_fixture(
+        monkeypatch, tmp_path, "silent"
+    )
+
+    facade = moa_loop.MoAChatCompletions("review")
+    facade.create(messages=[{"role": "user", "content": "review this"}], tools=[])
+
+    assert len(aggregator_calls) == 1
+    prompt = str(aggregator_calls[0]["messages"])
+    assert "[failed:" not in prompt
+    assert "Reference models unavailable" not in prompt
+    assert "Mixture of Agents reference context" not in prompt
+
+
+def test_interrupted_but_completed_reference_keeps_real_accounting(monkeypatch):
+    """A reference that finishes between the interrupt check and the reap
+    must keep its REAL output and accounting — the call billed."""
+    from concurrent.futures import wait as real_wait
+
+    from agent import moa_loop
+
+    monkeypatch.setattr(moa_loop, "get_transport", lambda *_a, **_k: None)
+    monkeypatch.setattr(moa_loop, "_REFERENCE_POLL_INTERVAL_S", 0.05)
+
+    fake_agent = SimpleNamespace(_interrupt_requested=True)
+
+    def fake_call_llm(**kwargs):
+        return _response_with_usage("slowish output", prompt=11, completion=4)
+
+    # Force the exact race: the wait loop reports the future as still
+    # pending (so the interrupt path is taken) even though the underlying
+    # call has already completed — the reap must then hit the done() branch
+    # and keep the real result instead of writing a placeholder.
+    def fake_wait(pending, timeout=None):
+        real_wait(pending)  # let the call actually finish (it billed)
+        return set(), set(pending)  # report it as still pending
+
+    monkeypatch.setattr(moa_loop, "_futures_wait", fake_wait)
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda slot: {"provider": slot["provider"], "model": slot["model"]},
+    )
+
+    out = moa_loop._run_references_parallel(
+        [{"provider": "slowish", "model": "m1"}],
+        [{"role": "user", "content": "hi"}],
+        agent=fake_agent,
+    )
+
+    # The completed call's real output + usage must survive the reap.
+    assert out[0][1] == "slowish output"
+    acct = out[0][2]
+    assert isinstance(acct, moa_loop._RefAccounting)
+    assert acct.usage.input_tokens == 11
+
+
+def test_late_completing_interrupted_reference_feeds_accounting_sink(monkeypatch):
+    """A reference still in flight at interrupt time gets a placeholder in
+    the results, but its eventual REAL accounting must reach the sink."""
+    import threading
+    import time
+
+    from agent import moa_loop
+
+    monkeypatch.setattr(moa_loop, "get_transport", lambda *_a, **_k: None)
+    monkeypatch.setattr(moa_loop, "_REFERENCE_POLL_INTERVAL_S", 0.05)
+
+    fake_agent = SimpleNamespace(_interrupt_requested=False)
+    release = threading.Event()
+    sink_calls = []
+    sink_seen = threading.Event()
+
+    def sink(label, accounting):
+        sink_calls.append((label, accounting))
+        sink_seen.set()
+
+    def fake_call_llm(**kwargs):
+        if kwargs["provider"] == "fast":
+            fake_agent._interrupt_requested = True
+            return _response("fast output")
+        # wedged: blocks past the interrupt, completes later.
+        release.wait(timeout=5)
+        return _response_with_usage("late output", prompt=21, completion=2)
+
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda slot: {"provider": slot["provider"], "model": slot["model"]},
+    )
+
+    out = moa_loop._run_references_parallel(
+        [
+            {"provider": "fast", "model": "m1"},
+            {"provider": "wedged", "model": "m2"},
+        ],
+        [{"role": "user", "content": "hi"}],
+        agent=fake_agent,
+        late_accounting_sink=sink,
+    )
+
+    # The wedged slot returned a placeholder with zeroed accounting…
+    assert out[1][1] == moa_loop._INTERRUPTED_REFERENCE_NOTE
+    assert out[1][2].usage.input_tokens == 0
+
+    # …then completes late; its real billed usage must reach the sink.
+    release.set()
+    assert sink_seen.wait(timeout=5), "late accounting sink never called"
+    label, acct = sink_calls[0]
+    assert "wedged" in label
+    assert acct.usage.input_tokens == 21
+
+
+def test_facade_does_not_cache_interrupted_reference_results(monkeypatch, tmp_path):
+    """An interrupted fan-out is a partial snapshot — caching it would replay
+    placeholder notes on every later iteration of the turn. The facade must
+    leave the cache empty so the next create() re-runs the references, and
+    a late-completing reference's real spend must land in pending usage."""
+    from agent import moa_loop
+    from agent.usage_pricing import CanonicalUsage
+
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        """
+moa:
+  default_preset: review
+  presets:
+    review:
+      reference_models:
+        - provider: openrouter
+          model: advisor
+      aggregator:
+        provider: openrouter
+        model: aggregator
+""".strip(),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    interrupted_outputs = [
+        (
+            "openrouter:advisor",
+            moa_loop._INTERRUPTED_REFERENCE_NOTE,
+            moa_loop._RefAccounting(CanonicalUsage()),
+        )
+    ]
+
+    def fake_fanout(*args, **kwargs):
+        return list(interrupted_outputs)
+
+    monkeypatch.setattr(moa_loop, "_run_references_parallel", fake_fanout)
+    monkeypatch.setattr(moa_loop, "call_llm", lambda **k: _response("acted"))
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda slot: {"provider": slot["provider"], "model": slot["model"]},
+    )
+
+    facade = moa_loop.MoAChatCompletions("review")
+    facade.create(messages=[{"role": "user", "content": "go"}], tools=[])
+
+    # Interrupted results must not be cached as this state's advice.
+    assert facade._ref_cache_key is None
+    assert facade._ref_cache_outputs == []
+
+    # A late completion depositing real spend is picked up by consume().
+    facade._record_late_reference_accounting(
+        "openrouter:advisor",
+        moa_loop._RefAccounting(CanonicalUsage(input_tokens=33), 0.42),
+    )
+    usage, cost = facade.consume_reference_usage()
+    assert usage.input_tokens == 33
+    assert cost == pytest.approx(0.42)
+    # And consume() drained it — no double count.
+    usage2, cost2 = facade.consume_reference_usage()
+    assert usage2.input_tokens == 0
+    assert cost2 is None
+
+
+class _CountingCtxLen:
+    """Stub for get_model_context_length that counts resolutions."""
+
+    def __init__(self, value):
+        self.value = value
+        self.calls = 0
+
+    def __call__(self, **kwargs):
+        self.calls += 1
+        if isinstance(self.value, Exception):
+            raise self.value
+        return self.value
+
+
+def _trim(messages, *, window=1000, reserve=None, cache=None, counting=None,
+          monkeypatch=None):
+    from agent import model_metadata, moa_loop
+
+    stub = counting or _CountingCtxLen(window)
+    monkeypatch.setattr(model_metadata, "get_model_context_length", stub)
+    return moa_loop._trim_messages_for_reference(
+        messages,
+        {"provider": "openrouter", "model": "small-window"},
+        {"provider": "openrouter", "model": "small-window"},
+        reserve_output_tokens=reserve,
+        context_length_cache=cache,
+    )
+
+
+def _advisory_view(n_pairs, chunk="x" * 400):
+    """A text-only advisory view: system + n user/assistant pairs + trailing user."""
+    msgs = [{"role": "system", "content": "advisory system prompt"}]
+    for i in range(n_pairs):
+        msgs.append({"role": "user", "content": f"u{i} {chunk}"})
+        msgs.append({"role": "assistant", "content": f"a{i} {chunk}"})
+    msgs.append({"role": "user", "content": "judge the state above"})
+    return msgs
+
+
+def test_reference_trim_untouched_when_within_window(monkeypatch):
+    msgs = _advisory_view(2)
+    out = _trim(list(msgs), window=10_000_000, monkeypatch=monkeypatch)
+    assert out == msgs
+
+
+def test_reference_trim_drops_oldest_and_keeps_invariants(monkeypatch):
+    from agent.model_metadata import estimate_messages_tokens_rough
+
+    msgs = _advisory_view(30)
+    out = _trim(list(msgs), window=4000, reserve=100, monkeypatch=monkeypatch)
+
+    # Something was dropped and it fits the (window*0.9 - reserve) budget…
+    assert len(out) < len(msgs)
+    # System prompt survives at index 0.
+    assert out[0]["role"] == "system"
+    # User-first after the system prompt — never assistant-first.
+    assert out[1]["role"] == "user"
+    # Trailing synthetic user turn survives.
+    assert out[-1] == msgs[-1]
+    # Oldest frames were the ones dropped: the kept body is a contiguous
+    # suffix of the original body.
+    assert out[1:] == msgs[len(msgs) - len(out) + 1:]
+
+
+def test_reference_trim_estimates_after_system_prompt(monkeypatch):
+    """The advisory system prompt counts against the budget: a view that fits
+    without it but not with it must still be trimmed."""
+    from agent import model_metadata, moa_loop
+
+    msgs = _advisory_view(6)
+    body_tokens = model_metadata.estimate_messages_tokens_rough(msgs[1:])
+    total_tokens = model_metadata.estimate_messages_tokens_rough(msgs)
+    assert total_tokens > body_tokens
+
+    # Pick a window where (body fits) but (system+body does not):
+    # budget = window*0.9 - reserve(100) must sit between the two.
+    window = int((body_tokens + (total_tokens - body_tokens) / 2 + 100) / 0.9)
+    out = _trim(list(msgs), window=window, reserve=100, monkeypatch=monkeypatch)
+    assert len(out) < len(msgs)
+    assert out[0]["role"] == "system"
+
+
+def test_reference_trim_reserves_output_tokens(monkeypatch):
+    """With a huge output reserve the budget shrinks and forces a trim that
+    a reserve-less estimate would not need."""
+    msgs = _advisory_view(10)
+    from agent.model_metadata import estimate_messages_tokens_rough
+
+    total = estimate_messages_tokens_rough(msgs)
+    window = int((total + 500) / 0.9)  # fits easily with a small reserve
+    out_small = _trim(list(msgs), window=window, reserve=100, monkeypatch=monkeypatch)
+    assert out_small == msgs
+    out_big = _trim(list(msgs), window=window, reserve=total, monkeypatch=monkeypatch)
+    assert len(out_big) < len(msgs)
+
+
+def test_reference_trim_unresolvable_window_is_a_noop(monkeypatch):
+    msgs = _advisory_view(3)
+    stub = _CountingCtxLen(RuntimeError("metadata down"))
+    out = _trim(list(msgs), counting=stub, monkeypatch=monkeypatch)
+    assert out == msgs
+
+
+def test_reference_trim_context_length_cache_hits_once(monkeypatch):
+    """A shared per-turn cache resolves each (provider, model) window once."""
+    cache = {}
+    stub = _CountingCtxLen(10_000_000)
+    msgs = _advisory_view(2)
+    for _ in range(4):
+        _trim(list(msgs), cache=cache, counting=stub, monkeypatch=monkeypatch)
+    assert stub.calls == 1
+    assert cache == {("openrouter", "small-window"): 10_000_000}
+
+
+def test_reference_trim_caches_resolution_failures(monkeypatch):
+    """A failing metadata source is probed once, not per reference call."""
+    cache = {}
+    stub = _CountingCtxLen(RuntimeError("metadata down"))
+    msgs = _advisory_view(2)
+    for _ in range(3):
+        out = _trim(list(msgs), cache=cache, counting=stub, monkeypatch=monkeypatch)
+        assert out == msgs
+    assert stub.calls == 1
+    assert cache == {("openrouter", "small-window"): None}
+
+
+def test_run_reference_trims_oversized_view_before_calling(monkeypatch):
+    """End-to-end: _run_reference sends a trimmed request for a small-window
+    model instead of letting the provider 400."""
+    from agent import model_metadata, moa_loop
+
+    sent = {}
+
+    def fake_call_llm(**kwargs):
+        sent.update(kwargs)
+        return _response_with_usage("advice")
+
+    monkeypatch.setattr(moa_loop, "call_llm", fake_call_llm)
+    monkeypatch.setattr(
+        moa_loop,
+        "_slot_runtime",
+        lambda slot: {"provider": "openrouter", "model": slot["model"]},
+    )
+    monkeypatch.setattr(
+        model_metadata, "get_model_context_length", lambda **k: 3000
+    )
+
+    view = _advisory_view(40)[1:]  # advisory view has no system prompt
+    label, text, _acct = moa_loop._run_reference(
+        {"provider": "openrouter", "model": "small-window"},
+        view,
+        max_tokens=200,
+    )
+
+    assert text == "advice"
+    sent_messages = sent["messages"]
+    # System prompt was prepended and survived the trim.
+    assert sent_messages[0]["role"] == "system"
+    # The request actually shrank.
+    assert len(sent_messages) < len(view) + 1
+    # And ends with the synthetic trailing user turn.
+    assert sent_messages[-1]["role"] == "user"
+
+
+def test_render_tool_calls_tolerates_namespace_shapes():
+    """SDK-shaped (SimpleNamespace) tool_call entries must render their real
+    function name+args, not degrade to '[called tool: tool]'."""
+    from agent.moa_loop import _render_tool_calls
+
+    ns_call = SimpleNamespace(
+        function=SimpleNamespace(name="web_search", arguments='{"query": "x"}')
+    )
+    dict_call = {"function": {"name": "read_file", "arguments": '{"path": "y"}'}}
+    mixed = _render_tool_calls([ns_call, dict_call])
+
+    assert '[called tool: web_search({"query": "x"})]' in mixed
+    assert '[called tool: read_file({"path": "y"})]' in mixed
+
+    # Dict entry with a namespace-shaped nested function also renders.
+    hybrid = {"function": SimpleNamespace(name="terminal", arguments=None)}
+    assert _render_tool_calls([hybrid]) == "[called tool: terminal]"
+
+    # Degenerate shapes still fall back safely.
+    assert _render_tool_calls([SimpleNamespace()]) == "[called tool: tool]"
diff --git a/tests/run_agent/test_moa_privacy_filter.py b/tests/run_agent/test_moa_privacy_filter.py
new file mode 100644
index 00000000000..a3fe38c7e70
--- /dev/null
+++ b/tests/run_agent/test_moa_privacy_filter.py
@@ -0,0 +1,207 @@
+"""MoA privacy redaction filter (config: moa.privacy_filter — display | full).
+
+Reworked from PR #60463 (issue #59959). Secret/credential shapes are handled
+by the central redactor (agent.redact.redact_sensitive_text); the MoA filter
+adds conservative email + formatted-phone patterns and wires two modes:
+
+  display — redact user-visible surfaces only (reference display events +
+            saved MoA traces); the aggregator sees raw advisor text.
+  full    — additionally redact the advisor text injected into the
+            aggregator prompt (issue #59959's literal ask).
+  (off)   — default: everything passes through raw.
+"""
+
+from types import SimpleNamespace
+
+from agent.moa_loop import _redact_reference_text
+
+
+def _response(content="done", *, tool_calls=None):
+    message = SimpleNamespace(content=content, tool_calls=tool_calls or [])
+    choice = SimpleNamespace(message=message, finish_reason="stop")
+    return SimpleNamespace(choices=[choice], usage=None, model="fake-model")
+
+
+# --- pattern behavior -------------------------------------------------------
+
+
+def test_redacts_email_addresses():
+    out = _redact_reference_text("contact jane.doe+dev@example.co.uk for access")
+    assert "jane.doe" not in out
+    assert "[redacted email]" in out
+
+
+def test_redacts_formatted_phone_numbers():
+    for phone in ["(555) 123-4567", "555-123-4567", "555.123.4567", "+1 555-123-4567"]:
+        out = _redact_reference_text(f"call {phone} today")
+        assert phone not in out, phone
+        assert "[redacted phone]" in out, phone
+
+
+def test_redacts_api_keys_and_jwts_via_central_redactor():
+    out = _redact_reference_text(
+        "key sk-proj-abc123def456ghi789jkl012 and token "
+        "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U"
+    )
+    assert "sk-proj-abc123def456ghi789jkl012" not in out
+    assert "dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U" not in out
+
+
+def test_does_not_mangle_code_review_shaped_text():
+    """Advisory text is often code-review shaped. Line numbers, timestamps,
+    bare digit runs, git SHAs, IPs, versions, and source-code assignments must
+    survive redaction byte-identical — a false positive here corrupts the
+    guidance the aggregator acts on."""
+    text = (
+        "Line 1274: off-by-one at src/moa_loop.py:1274\n"
+        "commit 3428e70c599cbfbe240172b4ee1118dbc18a78ca\n"
+        "Date: 2026-07-12 12:34:56 +0000\n"
+        "epoch 1234567890, id 5551234567, port 127.0.0.1:8080\n"
+        "version 1.2.3-4567\n"
+        "MAX_TOKENS=4096\n"
+        '"apiKey": "test-fixture"\n'
+        "timeout = 1234567890\n"
+    )
+    assert _redact_reference_text(text) == text
+
+
+def test_git_log_author_emails_are_redacted_but_line_survives():
+    """Emails ARE redacted (they're the PII class the filter exists for), but
+    the surrounding git-log structure must stay intact and parseable."""
+    out = _redact_reference_text("Author: Jane Doe <jane@example.com> fixed the bug")
+    assert "jane@example.com" not in out
+    assert out == "Author: Jane Doe <[redacted email]> fixed the bug"
+
+
+def test_non_string_input_passes_through():
+    assert _redact_reference_text(None) is None
+    assert _redact_reference_text(42) == 42
+    assert _redact_reference_text("") == ""
+
+
+# --- mode wiring ------------------------------------------------------------
+
+
+SENSITIVE_ADVICE = "email ceo@example.com, phone (555) 867-5309, proceed"
+
+
+def _privacy_config(home, privacy_filter):
+    home.mkdir()
+    line = f"  privacy_filter: {privacy_filter}\n" if privacy_filter is not None else ""
+    (home / "config.yaml").write_text(
+        f"""
+moa:
+{line}  default_preset: review
+  presets:
+    review:
+      reference_models:
+        - provider: openai-codex
+          model: gpt-5.5
+      aggregator:
+        provider: openrouter
+        model: anthropic/claude-opus-4.8
+""".strip(),
+        encoding="utf-8",
+    )
+
+
+def _install_fake_llm(monkeypatch):
+    calls = []
+
+    def fake_call_llm(**kwargs):
+        calls.append(kwargs)
+        if kwargs["task"] == "moa_reference":
+            return _response(SENSITIVE_ADVICE)
+        return _response("acted")
+
+    monkeypatch.setattr("agent.moa_loop.call_llm", fake_call_llm)
+    return calls
+
+
+def _run_facade(monkeypatch, tmp_path, privacy_filter):
+    home = tmp_path / ".hermes"
+    _privacy_config(home, privacy_filter)
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    _install_fake_llm(monkeypatch)
+
+    from agent.moa_loop import MoAChatCompletions
+
+    events = []
+    facade = MoAChatCompletions(
+        "review", reference_callback=lambda ev, **kw: events.append((ev, kw))
+    )
+    prepared = facade.create(
+        messages=[{"role": "user", "content": "review this"}],
+        tools=[],
+        _moa_prepare_only=True,
+    )
+    ref_events = [kw for ev, kw in events if ev == "moa.reference"]
+    return prepared, ref_events, facade
+
+
+def test_privacy_off_by_default_everything_raw(monkeypatch, tmp_path):
+    prepared, ref_events, _ = _run_facade(monkeypatch, tmp_path, None)
+    assert "ceo@example.com" in prepared["guidance"]
+    assert "ceo@example.com" in ref_events[0]["text"]
+
+
+def test_display_mode_redacts_display_but_not_aggregator(monkeypatch, tmp_path):
+    prepared, ref_events, facade = _run_facade(monkeypatch, tmp_path, "display")
+    # User-visible reference block: redacted.
+    assert "ceo@example.com" not in ref_events[0]["text"]
+    assert "[redacted email]" in ref_events[0]["text"]
+    assert "(555) 867-5309" not in ref_events[0]["text"]
+    # Aggregator input: raw (synthesis quality unaffected).
+    assert "ceo@example.com" in prepared["guidance"]
+    # Pending trace surface: redacted (traces persist to disk).
+    trace_refs = facade._pending_trace["reference_outputs"]
+    assert all("ceo@example.com" not in text for _l, text, _a in trace_refs)
+
+
+def test_full_mode_redacts_aggregator_input_too(monkeypatch, tmp_path):
+    prepared, ref_events, _ = _run_facade(monkeypatch, tmp_path, "full")
+    assert "ceo@example.com" not in prepared["guidance"]
+    assert "[redacted email]" in prepared["guidance"]
+    assert "(555) 867-5309" not in prepared["guidance"]
+    assert "ceo@example.com" not in ref_events[0]["text"]
+    # The redacted guidance is what reaches the aggregator request messages.
+    joined_content = "".join(
+        str(m.get("content")) for m in prepared["messages"]
+    )
+    assert "ceo@example.com" not in joined_content
+
+
+def test_legacy_boolean_true_maps_to_full(monkeypatch, tmp_path):
+    prepared, _ref_events, _ = _run_facade(monkeypatch, tmp_path, "true")
+    assert "ceo@example.com" not in prepared["guidance"]
+
+
+def test_cache_keeps_raw_text_redaction_applied_per_surface(monkeypatch, tmp_path):
+    """The reference cache must hold RAW advisor text — redaction happens at
+    each consuming surface. Otherwise a mid-session mode change would leak
+    (cache pre-redacted with weaker mode) or double-redact."""
+    _prepared, _ref_events, facade = _run_facade(monkeypatch, tmp_path, "full")
+    assert any("ceo@example.com" in text for _l, text, _a in facade._ref_cache_outputs)
+
+
+def test_full_mode_covers_one_shot_aggregate_moa_context(monkeypatch, tmp_path):
+    """The /moa one-shot synthesis path also honors full mode."""
+    home = tmp_path / ".hermes"
+    _privacy_config(home, "full")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    calls = _install_fake_llm(monkeypatch)
+
+    from agent.moa_loop import aggregate_moa_context
+
+    aggregate_moa_context(
+        user_prompt="review this",
+        api_messages=[{"role": "user", "content": "review this"}],
+        reference_models=[{"provider": "openai-codex", "model": "gpt-5.5"}],
+        aggregator={"provider": "openrouter", "model": "anthropic/claude-opus-4.8"},
+    )
+
+    agg_calls = [c for c in calls if c["task"] == "moa_aggregator"]
+    assert agg_calls, "aggregator synthesis call expected"
+    agg_input = str(agg_calls[0]["messages"])
+    assert "ceo@example.com" not in agg_input
+    assert "[redacted email]" in agg_input
diff --git a/tests/run_agent/test_primary_runtime_restore.py b/tests/run_agent/test_primary_runtime_restore.py
index 0d732277e97..c56c4897ffc 100644
--- a/tests/run_agent/test_primary_runtime_restore.py
+++ b/tests/run_agent/test_primary_runtime_restore.py
@@ -577,20 +577,26 @@ class TestTryRecoverPrimaryTransport:
             # wait_time = min(3 + 10, 8) = 8
             mock_sleep.assert_called_once_with(8)
 
-    def test_closes_existing_client_before_rebuild(self):
+    def test_retires_existing_client_before_rebuild(self):
+        """#70773: the old shared client is retired (sockets shutdown, FD
+        release deferred to GC), never hard-closed — this path runs on the
+        conversation-loop thread while stale-killed workers may still be
+        unwinding on the old pool."""
         agent = _make_agent(provider="custom")
         old_client = agent.client
         error = _make_transport_error("ReadTimeout")
 
         with patch("run_agent.OpenAI", return_value=MagicMock()), \
              patch("time.sleep"), \
-             patch.object(agent, "_close_openai_client") as mock_close:
+             patch.object(agent, "_close_openai_client") as mock_close, \
+             patch.object(agent, "_retire_shared_openai_client") as mock_retire:
             agent._try_recover_primary_transport(
                 error, retry_count=3, max_retries=3,
             )
-            mock_close.assert_called_once_with(
-                old_client, reason="primary_recovery", shared=True,
+            mock_retire.assert_called_once_with(
+                old_client, reason="primary_recovery",
             )
+            mock_close.assert_not_called()
 
     def test_survives_rebuild_failure(self):
         """If client rebuild fails, returns False gracefully."""
diff --git a/tests/run_agent/test_proactive_prune_loop_wiring.py b/tests/run_agent/test_proactive_prune_loop_wiring.py
new file mode 100644
index 00000000000..60b28b94483
--- /dev/null
+++ b/tests/run_agent/test_proactive_prune_loop_wiring.py
@@ -0,0 +1,214 @@
+"""Behavioral tests for the post-tool proactive tool-result prune wiring.
+
+The conversation loop's post-tool gate now has a prune arm inside the
+``elif agent.compression_enabled`` branch: when full compression does NOT
+fire (the usual case on a large-window model), the deterministic no-LLM
+prune gets one shot per tool iteration, committing only when the engine
+returns a NEW list object with a non-zero prune count.
+
+These tests drive ``run_conversation()`` through real tool iterations and pin:
+- the prune is consulted when compression stands down;
+- a committed prune replaces ``messages`` for subsequent iterations;
+- a no-op (input object returned) commits nothing;
+- a compressor WITHOUT the method (plugin engine predating the hook /
+  SimpleNamespace test double) does not raise — getattr-guarded;
+- a raising prune is swallowed (debug log), never fails the turn.
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from run_agent import AIAgent
+
+
+def _tool_call(i: int):
+    return SimpleNamespace(
+        id=f"call_{i}",
+        type="function",
+        function=SimpleNamespace(name="web_search", arguments='{"query": "x"}'),
+    )
+
+
+def _tool_response(i: int):
+    msg = SimpleNamespace(
+        content=None,
+        reasoning_content=None,
+        reasoning=None,
+        tool_calls=[_tool_call(i)],
+    )
+    choice = SimpleNamespace(message=msg, finish_reason="tool_calls")
+    return SimpleNamespace(choices=[choice], model="test/model", usage=None)
+
+
+def _stop_response():
+    msg = SimpleNamespace(
+        content="done",
+        reasoning_content=None,
+        reasoning=None,
+        tool_calls=None,
+    )
+    choice = SimpleNamespace(message=msg, finish_reason="stop")
+    return SimpleNamespace(choices=[choice], model="test/model", usage=None)
+
+
+def _make_tool_defs(*names: str) -> list:
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": n,
+                "description": f"{n} tool",
+                "parameters": {"type": "object", "properties": {}},
+            },
+        }
+        for n in names
+    ]
+
+
+def _quiet_compressor() -> MagicMock:
+    """A compressor that never demands full compression.
+
+    ``should_compress`` False routes the post-tool gate into the ``elif``
+    branch where the proactive prune arm lives.  ``should_compress_info``
+    reports unblocked (no block reason) so the overflow warning stays quiet.
+    """
+    compressor = MagicMock()
+    compressor.protect_first_n = 3
+    compressor.protect_last_n = 20
+    compressor.threshold_tokens = 500_000
+    compressor.context_length = 1_000_000
+    compressor.last_prompt_tokens = 120_000
+    compressor.should_compress.return_value = False
+    compressor.should_compress_info.return_value = (False, None)
+    compressor.should_defer_preflight_to_real_usage.return_value = True
+    compressor.get_active_compression_failure_cooldown.return_value = None
+    return compressor
+
+
+@pytest.fixture()
+def agent():
+    with (
+        patch("run_agent.get_tool_definitions", return_value=_make_tool_defs("web_search")),
+        patch("run_agent.check_toolset_requirements", return_value={}),
+        patch("run_agent.OpenAI"),
+    ):
+        a = AIAgent(
+            api_key="test-key-1234567890",
+            base_url="https://openrouter.ai/api/v1",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            max_iterations=10,
+        )
+    a.client = MagicMock()
+    a._cached_system_prompt = "You are helpful."
+    a._use_prompt_caching = False
+    a._disable_streaming = True
+    a.tool_delay = 0
+    a.save_trajectories = False
+    a.compression_enabled = True
+    a.context_compressor = _quiet_compressor()
+    return a
+
+
+def _run_tool_loop(agent, n_tool_iterations: int):
+    responses = [_tool_response(i) for i in range(n_tool_iterations)]
+    responses.append(_stop_response())
+    agent.client.chat.completions.create.side_effect = responses
+
+    with (
+        patch.object(agent, "_persist_session"),
+        patch.object(agent, "_save_trajectory"),
+        patch.object(agent, "_cleanup_task_resources"),
+        patch(
+            "run_agent.handle_function_call",
+            lambda name, args, task_id=None, **kwargs: json.dumps({"ok": True}),
+        ),
+    ):
+        result = agent.run_conversation("do a lot of tool work")
+
+    return result
+
+
+class TestProactivePruneLoopWiring:
+    def test_prune_consulted_when_compression_stands_down(self, agent):
+        calls = []
+
+        def _prune(messages, current_tokens=None):
+            calls.append(current_tokens)
+            return messages, 0  # no-op contract: input object back
+
+        agent.context_compressor.prune_tool_results_only = _prune
+        result = _run_tool_loop(agent, n_tool_iterations=3)
+        assert result["completed"] is True
+        assert len(calls) == 3  # one shot per tool iteration
+        assert all(t == 120_000 for t in calls)  # fed the real usage reading
+
+    def test_committed_prune_replaces_messages(self, agent):
+        marker = "[old tool output pruned]"
+
+        def _prune(messages, current_tokens=None):
+            pruned = [dict(m) for m in messages]
+            changed = 0
+            for m in pruned:
+                if m.get("role") == "tool" and m.get("content") != marker:
+                    m["content"] = marker
+                    changed += 1
+            if not changed:
+                return messages, 0
+            return pruned, changed
+
+        agent.context_compressor.prune_tool_results_only = _prune
+        result = _run_tool_loop(agent, n_tool_iterations=2)
+        assert result["completed"] is True
+        tool_rows = [m for m in result["messages"] if m.get("role") == "tool"]
+        assert tool_rows, "expected tool rows in the final transcript"
+        assert all(m["content"] == marker for m in tool_rows)
+
+    def test_noop_input_object_commits_nothing(self, agent):
+        """Engine returns the INPUT object with a (bogus) non-zero count —
+        the caller's ``result is not input`` gate must refuse the commit."""
+        def _prune(messages, current_tokens=None):
+            return messages, 5  # lies about count but returns input object
+
+        agent.context_compressor.prune_tool_results_only = _prune
+        result = _run_tool_loop(agent, n_tool_iterations=2)
+        assert result["completed"] is True
+        tool_rows = [m for m in result["messages"] if m.get("role") == "tool"]
+        # tool output may be wrapped in an untrusted_tool_result envelope —
+        # assert the original payload survived un-pruned.
+        assert all('"ok": true' in m["content"] for m in tool_rows)
+
+    def test_engine_without_method_does_not_raise(self, agent):
+        """Plugin engines predating the hook / minimal doubles lack the
+        method entirely — the getattr guard treats absence as a no-op."""
+        compressor = SimpleNamespace(
+            protect_first_n=3,
+            protect_last_n=20,
+            threshold_tokens=500_000,
+            context_length=1_000_000,
+            last_prompt_tokens=120_000,
+            should_compress=lambda _t: False,
+            should_defer_preflight_to_real_usage=lambda _t: True,
+            get_active_compression_failure_cooldown=lambda: None,
+        )
+        agent.context_compressor = compressor
+        result = _run_tool_loop(agent, n_tool_iterations=2)
+        assert result["completed"] is True
+
+    def test_raising_prune_is_swallowed(self, agent):
+        def _prune(messages, current_tokens=None):
+            raise RuntimeError("boom")
+
+        agent.context_compressor.prune_tool_results_only = _prune
+        result = _run_tool_loop(agent, n_tool_iterations=2)
+        assert result["completed"] is True
+        tool_rows = [m for m in result["messages"] if m.get("role") == "tool"]
+        # tool output may be wrapped in an untrusted_tool_result envelope —
+        # assert the original payload survived un-pruned.
+        assert all('"ok": true' in m["content"] for m in tool_rows)
diff --git a/tests/run_agent/test_provider_fallback.py b/tests/run_agent/test_provider_fallback.py
index 8a0e05c332c..efdd6ef38f2 100644
--- a/tests/run_agent/test_provider_fallback.py
+++ b/tests/run_agent/test_provider_fallback.py
@@ -334,3 +334,40 @@ class TestFallbackChainDedup:
 
         assert ok is False
         mock_resolve.assert_not_called()
+
+    def test_allows_xai_api_fallback_from_xai_oauth_same_host_model(self):
+        """xai-oauth and xai share api.x.ai but use different credentials.
+
+        A spending-limit 403 on OAuth must still be able to fall over to the
+        API-key provider even when both entries use the same model slug and
+        base URL.  Blind base_url+model dedup incorrectly skipped that path.
+        """
+        fbs = [
+            {
+                "provider": "xai",
+                "model": "grok-4.5",
+                "base_url": "https://api.x.ai/v1",
+            },
+        ]
+        agent = _make_agent(fallback_model=fbs)
+        agent.provider = "xai-oauth"
+        agent.model = "grok-4.5"
+        agent.base_url = "https://api.x.ai/v1"
+
+        called = []
+
+        def _resolve(provider, model=None, raw_codex=False, **kwargs):
+            called.append((provider, model))
+            return _mock_client(base_url="https://api.x.ai/v1"), model
+
+        with patch("agent.auxiliary_client.resolve_provider_client", side_effect=_resolve):
+            with patch(
+                "hermes_cli.model_normalize.normalize_model_for_provider",
+                side_effect=lambda m, p: m,
+            ):
+                ok = agent._try_activate_fallback()
+
+        assert ok is True
+        assert called == [("xai", "grok-4.5")]
+        assert agent.provider == "xai"
+        assert agent.model == "grok-4.5"
diff --git a/tests/run_agent/test_run_agent.py b/tests/run_agent/test_run_agent.py
index 18f2d2ae829..e0cdc163066 100644
--- a/tests/run_agent/test_run_agent.py
+++ b/tests/run_agent/test_run_agent.py
@@ -4475,6 +4475,41 @@ class TestRunConversation:
         assert result["final_response"] == "Final answer"
         assert result["completed"] is True
 
+    def test_prompt_cache_marks_static_system_prefix_on_wire(self, agent):
+        self._setup_agent(agent)
+        agent._cached_system_prompt = "stable instructions\n\nsession context"
+        agent._cached_system_prompt_static = "stable instructions"
+        agent._use_prompt_caching = True
+        agent._use_native_cache_layout = False
+        agent._cache_ttl = "5m"
+        agent.client.chat.completions.create.return_value = _mock_response(
+            content="Final answer",
+            finish_reason="stop",
+        )
+
+        with (
+            patch.object(agent, "_persist_session"),
+            patch.object(agent, "_save_trajectory"),
+            patch.object(agent, "_cleanup_task_resources"),
+        ):
+            result = agent.run_conversation("hello")
+
+        assert result["completed"] is True
+        system = agent.client.chat.completions.create.call_args.kwargs["messages"][0]
+        assert system["role"] == "system"
+        assert system["content"] == [
+            {
+                "type": "text",
+                "text": "stable instructions",
+                "cache_control": {"type": "ephemeral"},
+            },
+            {
+                "type": "text",
+                "text": "\n\nsession context",
+                "cache_control": {"type": "ephemeral"},
+            },
+        ]
+
     def test_codex_content_filter_incomplete_routes_to_policy_fallback(self, agent):
         self._setup_agent(agent)
         agent.api_mode = "codex_responses"
@@ -6875,6 +6910,7 @@ class TestNousCredentialRefresh:
         agent.api_mode = "chat_completions"
 
         closed = {"value": False}
+        retired = {"value": False}
         rebuilt = {"kwargs": None}
         captured = {}
 
@@ -6900,12 +6936,28 @@ class TestNousCredentialRefresh:
             "hermes_cli.auth.resolve_nous_runtime_credentials", _fake_resolve
         )
 
-        agent.client = _ExistingClient()
+        existing = _ExistingClient()
+        agent.client = existing
+
+        _orig_retire = agent._retire_shared_openai_client
+
+        def _spy_retire(client, *, reason):
+            if client is existing:
+                retired["value"] = True
+            return _orig_retire(client, reason=reason)
+
+        monkeypatch.setattr(agent, "_retire_shared_openai_client", _spy_retire)
+
         with patch("run_agent.OpenAI", side_effect=_fake_openai):
             ok = agent._try_refresh_nous_client_credentials(force=True)
 
         assert ok is True
-        assert closed["value"] is True
+        # #70773: the replaced shared client is RETIRED (sockets shutdown,
+        # FD release deferred to GC), never hard-closed from the refreshing
+        # thread — close() releasing pool FDs cross-thread was the
+        # TLS-FD→SQLite corruption vector.
+        assert retired["value"] is True
+        assert closed["value"] is False
         assert captured["force_refresh"] is True
         assert rebuilt["kwargs"]["api_key"] == "new-nous-key"
         assert (
diff --git a/tests/run_agent/test_run_agent_codex_responses.py b/tests/run_agent/test_run_agent_codex_responses.py
index 071596e2046..b6be6812fb4 100644
--- a/tests/run_agent/test_run_agent_codex_responses.py
+++ b/tests/run_agent/test_run_agent_codex_responses.py
@@ -396,6 +396,25 @@ def test_build_api_kwargs_codex(monkeypatch):
     assert "extra_body" not in kwargs
 
 
+def test_build_api_kwargs_mantle_sets_extended_prompt_cache_retention(monkeypatch):
+    _patch_agent_bootstrap(monkeypatch)
+    agent = run_agent.AIAgent(
+        model="openai.gpt-5.5",
+        provider="custom",
+        api_mode="codex_responses",
+        base_url="https://bedrock-mantle.us-west-2.api.aws/v1",
+        api_key="test-token",
+        quiet_mode=True,
+        max_iterations=1,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+
+    kwargs = agent._build_api_kwargs([{"role": "user", "content": "Ping"}])
+
+    assert kwargs["prompt_cache_retention"] == "24h"
+
+
 def test_build_api_kwargs_codex_clamps_minimal_effort(monkeypatch):
     """'minimal' reasoning effort is clamped to 'low' on the Responses API.
 
@@ -1402,11 +1421,22 @@ def test_try_refresh_codex_client_credentials_handles_xai_oauth(monkeypatch):
     )
     monkeypatch.setattr(run_agent, "OpenAI", _fake_openai)
 
-    agent.client = _ExistingClient()
+    existing = _ExistingClient()
+    agent.client = existing
+    retired = {"client": None}
+    monkeypatch.setattr(
+        agent,
+        "_retire_shared_openai_client",
+        lambda client, *, reason: retired.__setitem__("client", client),
+    )
     ok = agent._try_refresh_codex_client_credentials(force=True)
 
     assert ok is True
-    assert closed["value"] is True
+    # #70773: the replaced shared client must NOT be close()d from the
+    # refresh path (cross-thread close is the FD-recycle corruption
+    # vector) — it is retired (sockets shutdown, FD release via GC).
+    assert closed["value"] is False
+    assert retired["client"] is existing
     assert rebuilt["kwargs"]["api_key"] == "fresh-xai-token"
     assert rebuilt["kwargs"]["base_url"] == "https://api.x.ai/v1"
     assert isinstance(agent.client, _RebuiltClient)
@@ -1524,11 +1554,22 @@ def test_try_refresh_codex_client_credentials_rebuilds_client(monkeypatch):
     )
     monkeypatch.setattr(run_agent, "OpenAI", _fake_openai)
 
-    agent.client = _ExistingClient()
+    existing = _ExistingClient()
+    agent.client = existing
+    retired = {"client": None}
+    monkeypatch.setattr(
+        agent,
+        "_retire_shared_openai_client",
+        lambda client, *, reason: retired.__setitem__("client", client),
+    )
     ok = agent._try_refresh_codex_client_credentials(force=True)
 
     assert ok is True
-    assert closed["value"] is True
+    # #70773: the replaced shared client must NOT be close()d from the
+    # refresh path (cross-thread close is the FD-recycle corruption
+    # vector) — it is retired (sockets shutdown, FD release via GC).
+    assert closed["value"] is False
+    assert retired["client"] is existing
     assert rebuilt["kwargs"]["api_key"] == "new-codex-token"
     assert rebuilt["kwargs"]["base_url"] == "https://chatgpt.com/backend-api/codex"
     assert isinstance(agent.client, _RebuiltClient)
@@ -1556,11 +1597,22 @@ def test_try_refresh_copilot_client_credentials_rebuilds_client(monkeypatch):
     )
     monkeypatch.setattr(run_agent, "OpenAI", _fake_openai)
 
-    agent.client = _ExistingClient()
+    existing = _ExistingClient()
+    agent.client = existing
+    retired = {"client": None}
+    monkeypatch.setattr(
+        agent,
+        "_retire_shared_openai_client",
+        lambda client, *, reason: retired.__setitem__("client", client),
+    )
     ok = agent._try_refresh_copilot_client_credentials()
 
     assert ok is True
-    assert closed["value"] is True
+    # #70773: the replaced shared client must NOT be close()d from the
+    # refresh path (cross-thread close is the FD-recycle corruption
+    # vector) — it is retired (sockets shutdown, FD release via GC).
+    assert closed["value"] is False
+    assert retired["client"] is existing
     assert rebuilt["kwargs"]["api_key"] == "gho_new_token"
     assert rebuilt["kwargs"]["base_url"] == "https://api.githubcopilot.com"
     assert rebuilt["kwargs"]["default_headers"]["Copilot-Integration-Id"] == "vscode-chat"
diff --git a/tests/run_agent/test_streaming.py b/tests/run_agent/test_streaming.py
index ceebff03525..9eb667f5528 100644
--- a/tests/run_agent/test_streaming.py
+++ b/tests/run_agent/test_streaming.py
@@ -3,6 +3,7 @@
 Tests the unified streaming API call, delta callbacks, tool-call
 suppression, provider fallback, and CLI streaming display.
 """
+import threading
 from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
@@ -763,6 +764,68 @@ class TestStreamingFallback:
         assert agent._disable_streaming is True
         assert deltas == []
 
+    @patch("run_agent.AIAgent._abort_request_openai_client")
+    @patch("run_agent.AIAgent._close_request_openai_client")
+    @patch("run_agent.AIAgent._create_request_openai_client")
+    def test_moa_interrupt_closes_stream_handle(
+        self, mock_create, mock_close_openai, mock_abort_openai
+    ):
+        """MoA interrupts must close the per-request stream, not the facade client."""
+        from run_agent import AIAgent
+
+        class _BlockingClosableStream:
+            def __init__(self):
+                self.entered = threading.Event()
+                self.closed = threading.Event()
+                self.close_calls = 0
+
+            def __iter__(self):
+                return self
+
+            def __next__(self):
+                self.entered.set()
+                if not self.closed.wait(timeout=5):
+                    raise TimeoutError("MoA test stream was not closed")
+                raise RuntimeError("stream closed")
+
+            def close(self):
+                self.close_calls += 1
+                self.closed.set()
+
+        stream = _BlockingClosableStream()
+        mock_client = MagicMock()
+        mock_client.chat.completions.create.return_value = stream
+        mock_create.return_value = mock_client
+
+        agent = AIAgent(
+            model="default",
+            provider="moa",
+            api_key="test-key",
+            base_url="moa://local",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+        )
+        agent.api_mode = "chat_completions"
+        agent._interrupt_requested = False
+        agent.client = mock_client
+
+        def _request_interrupt():
+            assert stream.entered.wait(timeout=2)
+            agent._interrupt_requested = True
+
+        interrupter = threading.Thread(target=_request_interrupt, daemon=True)
+        interrupter.start()
+
+        with pytest.raises(InterruptedError):
+            agent._interruptible_streaming_api_call({"model": "default", "messages": []})
+
+        assert stream.closed.wait(timeout=2)
+        assert stream.close_calls == 1
+        mock_create.assert_called_once()
+        mock_close_openai.assert_not_called()
+        mock_abort_openai.assert_not_called()
+
     @patch("run_agent.AIAgent._create_request_openai_client")
     @patch("run_agent.AIAgent._close_request_openai_client")
     def test_stream_error_propagates_original(self, mock_close, mock_create):
diff --git a/tests/scripts/test_contributor_map.py b/tests/scripts/test_contributor_map.py
index 3109a5e3143..655210aa989 100644
--- a/tests/scripts/test_contributor_map.py
+++ b/tests/scripts/test_contributor_map.py
@@ -114,6 +114,15 @@ def test_add_rejects_invalid_email_and_login(emails_dir):
     )
 
 
+def test_add_accepts_legacy_consecutive_hyphen_login(emails_dir):
+    # Legacy GitHub accounts with consecutive hyphens are real (Roger--Han);
+    # current signup rules forbid them but existing logins remain valid.
+    assert add_contributor("roger.hanhong@gmail.com", "Roger--Han") == 0
+    assert (emails_dir / "roger.hanhong@gmail.com").read_text(
+        encoding="utf-8"
+    ).strip().endswith("Roger--Han")
+
+
 def test_add_strips_at_prefix(emails_dir):
     assert add_contributor("z@z.com", "@zeta") == 0
     assert read_mapping_file(emails_dir / "z@z.com") == "zeta"
diff --git a/tests/scripts/test_footgun_subprocess_encoding.py b/tests/scripts/test_footgun_subprocess_encoding.py
new file mode 100644
index 00000000000..00b29aec913
--- /dev/null
+++ b/tests/scripts/test_footgun_subprocess_encoding.py
@@ -0,0 +1,276 @@
+"""Tests for the ``subprocess text=True without explicit encoding=`` footgun
+rule in ``scripts/check-windows-footguns.py``.
+
+This rule (added alongside PR #60741) catches ``subprocess.run/Popen/call/
+check_output/check_call(..., text=True, ...)`` calls that don't pass an
+explicit ``encoding=``. On Chinese Windows (cp936/GBK) and other non-UTF-8
+default codepages, ``text=True`` without ``encoding=`` decodes child output
+with ``locale.getpreferredencoding(False)`` and crashes ``_readerthread``
+with ``UnicodeDecodeError`` on non-default-codepage bytes.
+
+See issues #47939, #53428, #57238.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+LINTER_PATH = REPO_ROOT / "scripts" / "check-windows-footguns.py"
+
+
+def _load_linter_module():
+    """Import the linter script as a module (it's not a package).
+
+    Register the module in sys.modules BEFORE exec_module so that
+    ``@dataclass`` can resolve ``cls.__module__`` via
+    ``sys.modules.get(cls.__module__).__dict__`` (CPython 3.11+ dataclass
+    internals require this).
+    """
+    spec = importlib.util.spec_from_file_location("check_windows_footguns", LINTER_PATH)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["check_windows_footguns"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+@pytest.fixture(scope="module")
+def linter():
+    return _load_linter_module()
+
+
+def _find_footgun(linter, name: str):
+    """Locate a Footgun by name in the FOOTGUNS list."""
+    for fg in linter.FOOTGUNS:
+        if fg.name == name:
+            return fg
+    pytest.fail(f"Footgun rule '{name}' not found in FOOTGUNS")
+
+
+def _scan_line(linter, line: str, footgun_name: str) -> bool:
+    """Return True if the given line triggers the named footgun rule.
+
+    Uses the linter's own pattern + post_filter logic so the test exercises
+    the real detection path (including guard-hint and suppression checks).
+    """
+    fg = _find_footgun(linter, footgun_name)
+    # Replicate the relevant checks from scan_file(): suppression marker,
+    # guard hints, then pattern + post_filter.
+    if linter.SUPPRESS_MARKER.search(line):
+        return False
+    if any(hint in line for hint in linter.GUARD_HINTS):
+        return False
+    code = linter._strip_code(line)
+    if not code.strip():
+        return False
+    match = fg.pattern.search(code)
+    if not match:
+        return False
+    if fg.post_filter is not None:
+        try:
+            if not fg.post_filter(match, line):
+                return False
+        except (IndexError, AttributeError):
+            return False
+    return True
+
+
+RULE_NAME = "subprocess text=True without explicit encoding="
+
+
+# ---------------------------------------------------------------------------
+# Detection — these SHOULD be flagged
+# ---------------------------------------------------------------------------
+
+
+class TestDetection:
+    def test_flags_subprocess_run_text_true_without_encoding(self, linter):
+        line = '    result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)'
+        assert _scan_line(linter, line, RULE_NAME), "expected flag for text=True without encoding="
+
+    def test_flags_subprocess_popen_text_true_without_encoding(self, linter):
+        line = '    p = subprocess.Popen(cmd, text=True, stdout=PIPE)'
+        assert _scan_line(linter, line, RULE_NAME)
+
+    def test_flags_subprocess_check_output_text_true(self, linter):
+        line = '    out = subprocess.check_output(["git", "status"], text=True)'
+        assert _scan_line(linter, line, RULE_NAME)
+
+    def test_flags_sp_alias_text_true(self, linter):
+        line = '    res = _sp.run(cmd, text=True, timeout=5)'
+        assert _scan_line(linter, line, RULE_NAME)
+
+    def test_flags_text_with_spaces_around_equals(self, linter):
+        line = '    subprocess.run(cmd, text = True, timeout=10)'
+        assert _scan_line(linter, line, RULE_NAME)
+
+    def test_flags_bare_run_call(self, linter):
+        # .run( without explicit subprocess. prefix — still a subprocess call
+        line = '    result = obj.run(cmd, text=True)'
+        assert _scan_line(linter, line, RULE_NAME)
+
+
+# ---------------------------------------------------------------------------
+# Suppression — these should NOT be flagged
+# ---------------------------------------------------------------------------
+
+
+class TestSuppression:
+    def test_does_not_flag_when_encoding_present(self, linter):
+        line = '    subprocess.run(cmd, text=True, encoding="utf-8", errors="replace")'
+        assert not _scan_line(linter, line, RULE_NAME)
+
+    def test_does_not_flag_when_encoding_with_spaces(self, linter):
+        line = "    subprocess.run(cmd, text=True, encoding = 'utf-8')"
+        assert not _scan_line(linter, line, RULE_NAME)
+
+    def test_does_not_flag_inline_suppression_marker(self, linter):
+        line = '    subprocess.run(cmd, text=True)  # windows-footgun: ok — POSIX only'
+        assert not _scan_line(linter, line, RULE_NAME)
+
+    def test_does_not_flag_non_subprocess_text_kwarg(self, linter):
+        # DataFrame.rename(text=True) — not a subprocess call
+        line = '    df = df.rename(text=True)'
+        assert not _scan_line(linter, line, RULE_NAME), (
+            "should not flag non-subprocess APIs that accept text= kwarg"
+        )
+
+    def test_does_not_flag_text_true_in_string_literal(self, linter):
+        line = '    """See subprocess.run(text=True) for details."""'
+        assert not _scan_line(linter, line, RULE_NAME), (
+            "should not flag text=True inside docstrings"
+        )
+
+    def test_does_not_flag_def_text_method(self, linter):
+        line = '    def text(self, value: bool = True):'
+        assert not _scan_line(linter, line, RULE_NAME)
+
+    def test_does_not_flag_comment_only_line(self, linter):
+        line = '    # subprocess.run(cmd, text=True) — example'
+        assert not _scan_line(linter, line, RULE_NAME)
+
+
+# ---------------------------------------------------------------------------
+# Helper functions — unit tests for _is_likely_subprocess_call and
+# _looks_like_string_literal
+# ---------------------------------------------------------------------------
+
+
+class TestHelpers:
+    def test_is_likely_subprocess_call_matches_subprocess_run(self, linter):
+        assert linter._is_likely_subprocess_call("subprocess.run(cmd, text=True)")
+
+    def test_is_likely_subprocess_call_matches_bare_run(self, linter):
+        assert linter._is_likely_subprocess_call("result = obj.run(cmd, text=True)")
+
+    def test_is_likely_subprocess_call_rejects_dataframe(self, linter):
+        assert not linter._is_likely_subprocess_call("df.rename(text=True)")
+
+    def test_is_likely_subprocess_call_rejects_plain_assignment(self, linter):
+        assert not linter._is_likely_subprocess_call("config.text = True")
+
+    def test_looks_like_string_literal_double_quotes(self, linter):
+        import re
+        line = '    msg = "use text=True carefully"'
+        match = re.search(r"\btext\s*=\s*True\b", line)
+        assert match is not None
+        assert linter._looks_like_string_literal(line, match)
+
+    def test_looks_like_string_literal_single_quotes(self, linter):
+        import re
+        line = "    msg = 'see text=True in docs'"
+        match = re.search(r"\btext\s*=\s*True\b", line)
+        assert match is not None
+        assert linter._looks_like_string_literal(line, match)
+
+    def test_looks_like_string_literal_false_for_real_code(self, linter):
+        import re
+        line = '    subprocess.run(cmd, text=True)'
+        match = re.search(r"\btext\s*=\s*True\b", line)
+        assert match is not None
+        assert not linter._looks_like_string_literal(line, match)
+
+
+# ---------------------------------------------------------------------------
+# Full-repo scan — after PR #60741 merges, the new rule should find ZERO
+# unsuppressed violations in the whole tree (excluding the linter itself
+# and CONTRIBUTING docs). This test will FAIL until PR #60741 is merged;
+# mark it xfail when run on a branch that doesn't include PR #60741's fixes.
+# ---------------------------------------------------------------------------
+
+
+class TestFullRepoScan:
+    def test_new_rule_find_only_known_violations(self, linter, monkeypatch):
+        """Scan the full repo and assert the new rule's matches are exactly
+        the set of call sites that PR #60741 fixes (or zero, if PR #60741
+        is already merged into this branch).
+
+        This is a regression guard: if someone adds a new
+        ``subprocess.run(text=True)`` without ``encoding=``, this test
+        catches it.
+        """
+        # The 7 call sites that PR #60741 fixes. If PR #60741 is merged
+        # into this branch, this set should be empty. If not, these are
+        # the expected matches.
+        pr_60741_sites = {
+            "hermes_cli/main.py",
+            "hermes_cli/onepassword_secrets_cli.py",
+            "hermes_cli/setup.py",
+            "tools/transcription_tools.py",
+            "tools/tts_tool.py",
+        }
+
+        # Run the full scan
+        roots = [
+            REPO_ROOT / "hermes_cli",
+            REPO_ROOT / "gateway",
+            REPO_ROOT / "tools",
+            REPO_ROOT / "cron",
+            REPO_ROOT / "agent",
+            REPO_ROOT / "plugins",
+            REPO_ROOT / "scripts",
+            REPO_ROOT / "acp_adapter",
+            REPO_ROOT / "acp_registry",
+        ]
+        roots = [r for r in roots if r.exists()]
+
+        fg = _find_footgun(linter, RULE_NAME)
+        new_rule_matches: dict[str, list[int]] = {}
+
+        for path in linter.iter_files(roots):
+            matches = linter.scan_file(path, [fg])  # scan with ONLY the new rule
+            if matches:
+                rel = path.relative_to(REPO_ROOT).as_posix()
+                new_rule_matches[rel] = [m[0] for m in matches]
+
+        # Determine which sites remain. PR #60741's fixes are on a separate
+        # branch; if this branch doesn't include them, the 7 call sites
+        # will still be flagged — that's expected, not a failure.
+        if new_rule_matches:
+            # Filter out the linter itself (it mentions text=True in its
+            # own pattern/message, but EXCLUDED_FILES handles that for the
+            # CLI entry point; the helper functions could trip it).
+            new_rule_matches = {
+                k: v for k, v in new_rule_matches.items()
+                if k != "scripts/check-windows-footguns.py"
+            }
+
+        if not new_rule_matches:
+            # PR #60741 already merged — clean tree. This is the goal state.
+            return
+
+        # Matches remain — they must be exactly the PR #60741 sites.
+        matched_files = set(new_rule_matches.keys())
+        unexpected = matched_files - pr_60741_sites
+        if unexpected:
+            pytest.fail(
+                f"New footgun rule found UNEXPECTED matches in files not "
+                f"covered by PR #60741: {sorted(unexpected)}.\n"
+                f"These are either new regressions or call sites that need "
+                f"a `# windows-footgun: ok` suppression."
+            )
+        # All matches are the expected PR #60741 sites — OK on this branch.
diff --git a/tests/skills/test_office_document_skills.py b/tests/skills/test_office_document_skills.py
index 4804769d861..1557182cf75 100644
--- a/tests/skills/test_office_document_skills.py
+++ b/tests/skills/test_office_document_skills.py
@@ -124,3 +124,88 @@ def test_docs_pages_generated():
         assert (docs_dir / f"productivity-{name}.md").exists(), (
             f"missing generated docs page for {name}; run website/scripts/generate-skill-docs.py"
         )
+
+
+# Document/payload readers must not depend on the host locale. OOXML part
+# files are UTF-8 (declared in the XML prolog) and the form-fields JSON the
+# agent authors is UTF-8, but these sites used locale-default text mode: on
+# Windows (cp1251/GBK/cp932) the validators parsed silently mojibake'd
+# document text and the pdf fill scripts wrote mojibake'd values into the
+# user's form — or crashed outright where the bytes don't decode.
+_ENCODING_SENSITIVE_READS = [
+    (
+        "docx/scripts/office/validators/base.py",
+        'with open(xml_file, "rb") as f:',
+    ),
+    (
+        "powerpoint/scripts/office/validators/base.py",
+        'with open(xml_file, "rb") as f:',
+    ),
+    (
+        "pdf/scripts/check_bounding_boxes.py",
+        'with open(sys.argv[1], encoding="utf-8") as f:',
+    ),
+    (
+        "pdf/scripts/create_validation_image.py",
+        "with open(fields_json_path, 'r', encoding='utf-8') as f:",
+    ),
+    (
+        "pdf/scripts/fill_fillable_fields.py",
+        'with open(fields_json_path, encoding="utf-8") as f:',
+    ),
+    (
+        "pdf/scripts/fill_pdf_form_with_annotations.py",
+        'with open(fields_json_path, "r", encoding="utf-8") as f:',
+    ),
+]
+
+
+@pytest.mark.parametrize("rel_path,expected", _ENCODING_SENSITIVE_READS)
+def test_document_readers_are_locale_independent(rel_path, expected):
+    """XML parts are opened as bytes (lxml honors the XML prolog) and JSON
+    payloads as UTF-8 — never with the locale-default codec."""
+    source = (SKILLS / "productivity" / rel_path).read_text(encoding="utf-8")
+    assert expected in source, (
+        f"{rel_path}: locale-dependent read of a UTF-8 document/payload"
+    )
+
+
+def test_check_bounding_boxes_reads_utf8_fields_json(tmp_path):
+    """Run the real script on a UTF-8 fields.json with non-ASCII field
+    descriptions under a forced non-UTF-8 locale. Without the explicit
+    encoding the json.load crashes (C locale on POSIX; cp1251 chokes on
+    the 0x98 byte of U+2018 on Windows)."""
+    import json
+    import os
+    import subprocess
+    import sys
+
+    script = _skill_dir("pdf") / "scripts" / "check_bounding_boxes.py"
+    fields = {
+        "form_fields": [
+            {
+                "description": "Фамилия (‘label’)",
+                "page_number": 1,
+                "label_bounding_box": [0, 0, 10, 10],
+                "entry_bounding_box": [20, 20, 30, 40],
+            }
+        ]
+    }
+    fields_json = tmp_path / "fields.json"
+    fields_json.write_bytes(
+        json.dumps(fields, ensure_ascii=False, indent=2).encode("utf-8")
+    )
+
+    env = dict(os.environ)
+    env.update({"LC_ALL": "C", "LANG": "C", "PYTHONUTF8": "0", "PYTHONIOENCODING": "utf-8"})
+    result = subprocess.run(
+        [sys.executable, str(script), str(fields_json)],
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=60,
+    )
+    assert result.returncode == 0, (
+        f"script failed under non-UTF-8 locale:\n{result.stderr}"
+    )
+    assert "SUCCESS" in result.stdout
diff --git a/tests/skills/test_openclaw_migration.py b/tests/skills/test_openclaw_migration.py
index 0b331c40238..e75dad8792a 100644
--- a/tests/skills/test_openclaw_migration.py
+++ b/tests/skills/test_openclaw_migration.py
@@ -1107,3 +1107,141 @@ def test_migrate_model_config_no_catalog_leaves_value_alone(tmp_path: Path):
         {"agents": {"defaults": {"model": "some-model-id"}}},
     )
     assert _extract_model(parsed) == "some-model-id"
+
+
+# ── non-UTF-8 tolerance (issue #8901) ───────────────────────────────────────
+
+
+def _write_invalid_utf8_json(path: Path, prefix: bytes, valid_value: bytes, suffix: bytes) -> None:
+    """Write a JSON-shaped file containing one invalid UTF-8 byte (0xB3) inside
+    a string value, alongside a separate, validly-encoded value. Used to check
+    that a single bad byte does not prevent the rest of the file's data from
+    being read (relies on read_text(..., errors="replace"))."""
+    path.write_bytes(prefix + b"\xb3" + valid_value + suffix)
+
+
+def test_command_allowlist_handles_invalid_utf8_bytes(tmp_path: Path):
+    """exec-approvals.json with a non-UTF-8 byte should not abort migration;
+    valid patterns elsewhere in the same file must still be imported."""
+    mod = load_module()
+    source = tmp_path / ".openclaw"
+    target = tmp_path / ".hermes"
+    source.mkdir()
+    target.mkdir()
+
+    _write_invalid_utf8_json(
+        source / "exec-approvals.json",
+        prefix=b'{"agents": {"*": {"allowlist": [{"pattern": "/bad',
+        valid_value=b'"}, {"pattern": "/usr/bin/*"}]}}}',
+        suffix=b"",
+    )
+    (target / "config.yaml").write_text("command_allowlist: []\n", encoding="utf-8")
+
+    migrator = mod.Migrator(
+        source_root=source, target_root=target, execute=True,
+        workspace_target=None, overwrite=False, migrate_secrets=False, output_dir=None,
+        selected_options={"command-allowlist"},
+    )
+    report = migrator.migrate()
+
+    items = [i for i in report["items"] if i["kind"] == "command-allowlist"]
+    assert items and items[0]["status"] == "migrated"
+    config_text = (target / "config.yaml").read_text(encoding="utf-8")
+    assert "/usr/bin/*" in config_text
+
+
+def test_messaging_settings_handles_invalid_utf8_in_telegram_allowlist(tmp_path: Path):
+    """Telegram allowFrom file with a non-UTF-8 byte should not abort migration;
+    valid user IDs elsewhere in the same file must still be imported."""
+    mod = load_module()
+    source = tmp_path / ".openclaw"
+    target = tmp_path / ".hermes"
+    source.mkdir()
+    target.mkdir()
+
+    creds_dir = source / "credentials"
+    creds_dir.mkdir()
+    _write_invalid_utf8_json(
+        creds_dir / "telegram-default-allowFrom.json",
+        prefix=b'{"allowFrom": ["bad',
+        valid_value=b'", "123456789"]}',
+        suffix=b"",
+    )
+
+    migrator = mod.Migrator(
+        source_root=source, target_root=target, execute=True,
+        workspace_target=None, overwrite=False, migrate_secrets=False, output_dir=None,
+        selected_options={"messaging-settings"},
+    )
+    report = migrator.migrate()
+
+    items = [i for i in report["items"] if i["kind"] == "messaging-settings"]
+    assert items and items[0]["status"] == "migrated"
+    env_text = (target / ".env").read_text(encoding="utf-8")
+    assert "123456789" in env_text
+
+
+def test_provider_keys_handles_invalid_utf8_in_auth_profiles(tmp_path: Path):
+    """auth-profiles.json with a non-UTF-8 byte should not abort migration;
+    a valid provider key elsewhere in the same file must still be imported."""
+    mod = load_module()
+    source = tmp_path / ".openclaw"
+    target = tmp_path / ".hermes"
+    source.mkdir()
+    target.mkdir()
+
+    agent_dir = source / "agents" / "main" / "agent"
+    agent_dir.mkdir(parents=True)
+    _write_invalid_utf8_json(
+        agent_dir / "auth-profiles.json",
+        prefix=b'{"profiles": {"broken": {"key": "bad',
+        valid_value=b'"}, "openrouter-main": {"key": "sk-or-valid-key"}}}',
+        suffix=b"",
+    )
+    (source / "openclaw.json").write_text(json.dumps({}), encoding="utf-8")
+
+    migrator = mod.Migrator(
+        source_root=source, target_root=target, execute=True,
+        workspace_target=None, overwrite=False, migrate_secrets=True, output_dir=None,
+        selected_options={"provider-keys"},
+    )
+    report = migrator.migrate()
+
+    items = [i for i in report["items"] if i["kind"] == "provider-keys"]
+    assert items and items[0]["status"] == "migrated"
+    env_text = (target / ".env").read_text(encoding="utf-8")
+    assert "OPENROUTER_API_KEY=sk-or-valid-key" in env_text
+
+
+def test_daily_memory_skips_undecodable_file_but_merges_others(tmp_path: Path):
+    """A daily-memory .md file with invalid UTF-8 bytes should not abort the
+    merge; entries from the other, cleanly-encoded file must still land."""
+    mod = load_module()
+    source = tmp_path / ".openclaw"
+    target = tmp_path / ".hermes"
+    target.mkdir()
+
+    mem_dir = source / "workspace" / "memory"
+    mem_dir.mkdir(parents=True)
+    (mem_dir / "2026-03-01.md").write_text(
+        "# March 1 Notes\n\n- User prefers dark mode\n",
+        encoding="utf-8",
+    )
+    # errors="replace" means this file is still readable (bad byte becomes
+    # U+FFFD), so its valid heading/entries should also survive alongside it.
+    (mem_dir / "2026-03-02.md").write_bytes(
+        b"# March 2 Notes\n\n- Working on \xb3migration project\n"
+    )
+
+    migrator = mod.Migrator(
+        source_root=source, target_root=target, execute=True,
+        workspace_target=None, overwrite=False, migrate_secrets=False, output_dir=None,
+        selected_options={"daily-memory"},
+    )
+    report = migrator.migrate()
+
+    items = [i for i in report["items"] if i["kind"] == "daily-memory"]
+    assert items and items[0]["status"] == "migrated"
+    content = (target / "memories" / "MEMORY.md").read_text(encoding="utf-8")
+    assert "dark mode" in content
+    assert "migration project" in content
diff --git a/tests/skills/test_pinecone_research_skill.py b/tests/skills/test_pinecone_research_skill.py
new file mode 100644
index 00000000000..7bd48286abf
--- /dev/null
+++ b/tests/skills/test_pinecone_research_skill.py
@@ -0,0 +1,99 @@
+"""
+Smoke tests for the pinecone-research optional skill.
+
+Validates:
+  - SKILL.md frontmatter conforms to the ≤60-char description standard
+  - The skill name is distinct from the existing mlops/pinecone skill
+  - Frontmatter has required fields
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+SKILL_DIR = (
+    Path(__file__).resolve().parents[2]
+    / "optional-skills"
+    / "research"
+    / "pinecone-research"
+)
+
+MLOPS_PINECONE_DIR = (
+    Path(__file__).resolve().parents[2]
+    / "optional-skills"
+    / "mlops"
+    / "pinecone"
+)
+
+
+@pytest.fixture(scope="module")
+def frontmatter() -> dict:
+    src = (SKILL_DIR / "SKILL.md").read_text(encoding="utf-8")
+    m = re.search(r"^---\n(.*?)\n---", src, re.DOTALL)
+    assert m, "SKILL.md missing YAML frontmatter"
+    return yaml.safe_load(m.group(1))
+
+
+def test_skill_dir_exists() -> None:
+    assert SKILL_DIR.is_dir(), f"missing skill dir: {SKILL_DIR}"
+
+
+def test_skill_md_present() -> None:
+    assert (SKILL_DIR / "SKILL.md").is_file()
+
+
+def test_description_under_60_chars(frontmatter) -> None:
+    desc = frontmatter["description"]
+    assert len(desc) <= 60, f"description is {len(desc)} chars (limit ≤60): {desc!r}"
+
+
+def test_name_is_distinct_from_mlops_pinecone(frontmatter) -> None:
+    """The research skill must use a different name from mlops/pinecone."""
+    mlops_src = (MLOPS_PINECONE_DIR / "SKILL.md").read_text(encoding="utf-8")
+    m = re.search(r"^---\n(.*?)\n---", mlops_src, re.DOTALL)
+    assert m, "mlops/pinecone SKILL.md missing frontmatter"
+    mlops_fm = yaml.safe_load(m.group(1))
+    assert frontmatter["name"] != mlops_fm["name"], (
+        f"research pinecone name {frontmatter['name']!r} must differ from "
+        f"mlops pinecone name {mlops_fm['name']!r}"
+    )
+
+
+def test_name_matches_expected(frontmatter) -> None:
+    assert frontmatter["name"] == "pinecone-research"
+
+
+def test_has_required_frontmatter_fields(frontmatter) -> None:
+    for field in ("name", "description", "version", "license"):
+        assert field in frontmatter, f"missing required field: {field}"
+
+
+def test_platforms_includes_all_major(frontmatter) -> None:
+    platforms = frontmatter.get("platforms", [])
+    assert set(platforms) >= {"linux", "macos", "windows"}
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "scripts/rag_pipeline.py",
+        "scripts/memory_manager.py",
+    ],
+)
+def test_shipped_scripts_parse(path: str) -> None:
+    """Shipped scripts must be valid Python (ast.parse raises SyntaxError otherwise)."""
+    import ast
+
+    src = (SKILL_DIR / path).read_text(encoding="utf-8")
+    ast.parse(src)  # raises SyntaxError on broken Python
+
+
+def test_scripts_use_pinecone_client() -> None:
+    """Both scripts should reference the Pinecone SDK."""
+    for script in ("scripts/rag_pipeline.py", "scripts/memory_manager.py"):
+        src = (SKILL_DIR / script).read_text(encoding="utf-8")
+        assert "PINECONE_API_KEY" in src, f"{script} should read PINECONE_API_KEY"
+        assert "Pinecone" in src, f"{script} should import/use Pinecone client"
diff --git a/tests/skills/test_xurl_x_search_routing.py b/tests/skills/test_xurl_x_search_routing.py
new file mode 100644
index 00000000000..e7dd3768087
--- /dev/null
+++ b/tests/skills/test_xurl_x_search_routing.py
@@ -0,0 +1,93 @@
+"""Behavioral contract for xurl / x_search routing guidance.
+
+These tests assert structural invariants (required topics + placement of the
+routing guidance), not frozen prose snapshots.
+
+Placement contract (July 2026):
+- The xurl SKILL must NOT name `x_search` (or any other credential-gated
+  surface): the skill loads even when that tool isn't registered, so it must
+  describe its own search distinctively in its own terms (raw, engageable
+  post objects as the authenticated account).
+- Cross-surface routing guidance lives where both surfaces are known to
+  exist together: the x_search feature docs, the toolset description, and
+  the tools-config setup note.
+"""
+
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+XURL_SKILL = REPO_ROOT / "skills" / "social-media" / "xurl" / "SKILL.md"
+X_SEARCH_DOC = REPO_ROOT / "website" / "docs" / "user-guide" / "features" / "x-search.md"
+
+
+def _read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def _contains_any(text: str, *needles: str) -> bool:
+    lowered = text.lower()
+    return any(n.lower() in lowered for n in needles)
+
+
+def test_xurl_skill_never_names_credential_gated_surfaces():
+    """The skill must be self-contained: no cross-references to tools that
+    may not be registered (x_search is check_fn-gated on xAI credentials)."""
+    lowered = _read(XURL_SKILL).lower()
+    assert "x_search" not in lowered
+    assert "web_search" not in lowered
+
+
+def test_xurl_skill_search_is_distinct_standalone():
+    """Search must be described so an agent can route correctly even when
+    another X search surface exists — raw engageable posts, authenticated."""
+    text = _read(XURL_SKILL)
+    assert _contains_any(text, "raw post")
+    assert _contains_any(text, "authenticated")
+    assert _contains_any(text, "engage", "engageable")
+    # Distinguish from synthesized-answer surfaces in xurl's own terms.
+    assert _contains_any(text, "summarized answer", "summary of a topic")
+
+
+def test_xurl_skill_write_evidence_rule():
+    """State-changing X actions are proven only by xurl output / X API
+    response — never by search results or summaries."""
+    text = _read(XURL_SKILL)
+    assert _contains_any(text, "proves that a state-changing", "proves the action")
+    assert _contains_any(text, "never report a write", "never treat")
+
+
+def test_x_search_doc_separates_discovery_from_account_actions():
+    text = _read(X_SEARCH_DOC)
+    lowered = text.lower()
+
+    assert "x_search" in lowered
+    assert "xurl" in lowered
+    # Explicit comparison section or equivalent boundary language.
+    assert _contains_any(text, "vs `xurl`", "vs xurl", "two different x surfaces")
+    assert _contains_any(text, "read-only public", "public x discovery")
+    assert _contains_any(
+        text,
+        "posting",
+        "replying",
+        "liking",
+        "dm",
+        "media upload",
+        "deleting",
+    )
+    assert _contains_any(
+        text,
+        "authenticated",
+        "exact or authenticated",
+        "account actions",
+        "state-changing",
+    )
+    # Write confirmation must come from xurl / X API, not x_search.
+    assert _contains_any(
+        text,
+        "confirmed by `xurl`",
+        "xurl` output",
+        "x api response",
+        "never evidence",
+    )
+    assert _contains_any(text, "switch to the `xurl`", "switch to `xurl`", "xurl skill")
diff --git a/tests/state/test_compression_lineage_guard.py b/tests/state/test_compression_lineage_guard.py
new file mode 100644
index 00000000000..bc41632c98d
--- /dev/null
+++ b/tests/state/test_compression_lineage_guard.py
@@ -0,0 +1,196 @@
+"""Regression tests for stale writes after a compression session split."""
+
+from __future__ import annotations
+
+import pytest
+
+from hermes_state import SessionDB
+
+
+@pytest.fixture()
+def db(tmp_path):
+    session_db = SessionDB(db_path=tmp_path / "state.db")
+    try:
+        yield session_db
+    finally:
+        session_db.close()
+
+
+def _compression_parent(db: SessionDB, session_id: str = "parent") -> None:
+    db.create_session(session_id, source="webui")
+    db.append_message(session_id, "user", "before split")
+    db.end_session(session_id, "compression")
+
+
+def test_find_live_compression_child_returns_unique_direct_child(db: SessionDB) -> None:
+    _compression_parent(db)
+    db.create_session("child", source="webui", parent_session_id="parent")
+
+    child = db.find_live_compression_child("parent")
+
+    assert child is not None
+    assert child["id"] == "child"
+    assert child["parent_session_id"] == "parent"
+    assert child["ended_at"] is None
+
+
+def test_find_live_compression_child_fails_closed_when_ambiguous(db: SessionDB) -> None:
+    _compression_parent(db)
+    db.create_session("child-a", source="webui", parent_session_id="parent")
+    db.create_session("child-b", source="webui", parent_session_id="parent")
+
+    assert db.find_live_compression_child("parent") is None
+
+
+def test_find_live_compression_child_ignores_ended_children(db: SessionDB) -> None:
+    _compression_parent(db)
+    db.create_session("ended-child", source="webui", parent_session_id="parent")
+    db.end_session("ended-child", "agent_close")
+
+    assert db.find_live_compression_child("parent") is None
+
+
+def test_find_live_compression_child_ignores_non_continuation_children(
+    db: SessionDB,
+) -> None:
+    _compression_parent(db)
+    db.create_session("canonical", source="webui", parent_session_id="parent")
+    db.create_session(
+        "branch",
+        source="webui",
+        parent_session_id="parent",
+        model_config={"_branched_from": "parent"},
+    )
+    db.create_session(
+        "delegate",
+        source="webui",
+        parent_session_id="parent",
+        model_config={"_delegate_from": "parent"},
+    )
+    db.create_session("tool-child", source="tool", parent_session_id="parent")
+
+    child = db.find_live_compression_child("parent")
+
+    assert child is not None
+    assert child["id"] == "canonical"
+
+
+def test_append_message_rejects_compression_ended_parent_atomically(db: SessionDB) -> None:
+    _compression_parent(db)
+    before = db.get_session("parent")["message_count"]
+
+    with pytest.raises(RuntimeError, match="closed by compression"):
+        db.append_message("parent", "assistant", "must not land on parent")
+
+    assert db.get_session("parent")["message_count"] == before
+    assert [m["content"] for m in db.get_messages("parent")] == ["before split"]
+
+
+def test_append_message_preserves_legacy_behavior_for_other_end_reasons(db: SessionDB) -> None:
+    db.create_session("ended", source="test")
+    db.end_session("ended", "agent_close")
+
+    message_id = db.append_message("ended", "user", "legacy append")
+
+    assert isinstance(message_id, int)
+    assert db.get_messages("ended")[-1]["content"] == "legacy append"
+
+
+def test_replace_messages_rejects_compression_ended_parent_atomically(
+    db: SessionDB,
+) -> None:
+    _compression_parent(db)
+
+    with pytest.raises(RuntimeError, match="closed by compression"):
+        db.replace_messages("parent", [{"role": "user", "content": "rewrite"}])
+
+    assert [m["content"] for m in db.get_messages("parent")] == ["before split"]
+
+
+def test_publish_compression_child_is_atomic_on_handoff_failure(
+    db: SessionDB, monkeypatch
+) -> None:
+    db.create_session("atomic-parent", source="webui")
+    db.append_message("atomic-parent", "user", "original")
+    assert db.try_acquire_compression_lock("atomic-parent", "winner", ttl_seconds=60)
+
+    def _boom(*_args, **_kwargs):
+        raise RuntimeError("handoff insert failed")
+
+    monkeypatch.setattr(db, "_insert_message_rows", _boom)
+    with pytest.raises(RuntimeError, match="handoff insert failed"):
+        db.publish_compression_child(
+            parent_session_id="atomic-parent",
+            child_session_id="atomic-child",
+            source="webui",
+            messages=[{"role": "user", "content": "summary"}],
+            compression_lock_holder="winner",
+        )
+
+    parent = db.get_session("atomic-parent")
+    assert parent is not None
+    assert parent["ended_at"] is None
+    assert db.get_session("atomic-child") is None
+
+
+def test_publish_compression_child_exposes_complete_child(db: SessionDB) -> None:
+    db.create_session("atomic-parent", source="webui")
+    db.append_message("atomic-parent", "user", "original")
+    assert db.try_acquire_compression_lock("atomic-parent", "winner", ttl_seconds=60)
+
+    db.publish_compression_child(
+        parent_session_id="atomic-parent",
+        child_session_id="atomic-child",
+        source="webui",
+        system_prompt="compressed system",
+        messages=[{"role": "user", "content": "summary"}],
+        compression_lock_holder="winner",
+    )
+
+    assert db.get_session("atomic-parent")["end_reason"] == "compression"
+    child = db.find_live_compression_child("atomic-parent")
+    assert child is not None
+    assert child["id"] == "atomic-child"
+    assert child["system_prompt"] == "compressed system"
+    assert [m["content"] for m in db.get_messages("atomic-child")] == ["summary"]
+
+
+def test_publish_compression_child_rejects_lost_or_expired_lease(db: SessionDB) -> None:
+    db.create_session("lease-parent", source="webui")
+    db.append_message("lease-parent", "user", "new durable turn")
+    assert db.try_acquire_compression_lock("lease-parent", "new-winner", ttl_seconds=60)
+
+    with pytest.raises(RuntimeError, match="lease lost"):
+        db.publish_compression_child(
+            parent_session_id="lease-parent",
+            child_session_id="stale-child",
+            source="webui",
+            messages=[{"role": "user", "content": "stale summary"}],
+            compression_lock_holder="old-loser",
+        )
+
+    parent = db.get_session("lease-parent")
+    assert parent is not None
+    assert parent["ended_at"] is None
+    assert db.get_session("stale-child") is None
+    assert [m["content"] for m in db.get_messages("lease-parent")] == [
+        "new durable turn"
+    ]
+
+
+def test_compression_lease_blocks_non_owner_but_allows_owner_flush(
+    db: SessionDB,
+) -> None:
+    db.create_session("leased", source="webui")
+    assert db.try_acquire_compression_lock("leased", "winner", ttl_seconds=60)
+
+    with pytest.raises(RuntimeError, match="being compressed"):
+        db.append_message("leased", "user", "late stale turn")
+
+    db.append_message(
+        "leased",
+        "assistant",
+        "winner flush",
+        compression_lock_holder="winner",
+    )
+    assert [m["content"] for m in db.get_messages("leased")] == ["winner flush"]
diff --git a/tests/test_conftest_wal_gate.py b/tests/test_conftest_wal_gate.py
new file mode 100644
index 00000000000..1e93ca53a8f
--- /dev/null
+++ b/tests/test_conftest_wal_gate.py
@@ -0,0 +1,77 @@
+"""The conftest WAL gate must agree with hermes_state, and must not import it.
+
+``tests/conftest.py::_wal_is_usable`` duplicates the SQLite WAL-reset version
+predicate instead of importing ``hermes_state``. That is deliberate: importing
+``hermes_state`` during collection caches ``DEFAULT_DB_PATH`` from the real
+``~/.hermes`` before the per-test ``HERMES_HOME`` redirect, which makes tests
+read the developer's live production database.
+
+Duplication needs a guard, so these tests pin the two implementations in
+agreement across the documented upstream boundaries.
+"""
+
+import sqlite3
+
+import pytest
+
+from hermes_state import is_sqlite_wal_reset_vulnerable
+from tests.conftest import _wal_is_usable
+
+
+@pytest.mark.parametrize(
+    "version_info",
+    [
+        (3, 6, 23),   # pre-WAL
+        (3, 7, 0),    # first WAL release — vulnerable
+        (3, 44, 5),   # below the 3.44 backport
+        (3, 44, 6),   # 3.44 backport — fixed
+        (3, 45, 0),   # next minor, back to vulnerable
+        (3, 50, 4),   # the version that exposed this (repo .venv)
+        (3, 50, 6),   # below the 3.50 backport
+        (3, 50, 7),   # 3.50 backport — fixed
+        (3, 51, 2),   # last vulnerable
+        (3, 51, 3),   # fixed upstream
+        (3, 53, 1),   # the managed runtime
+    ],
+)
+def test_conftest_gate_agrees_with_hermes_state(version_info, monkeypatch):
+    """``_wai_is_usable`` must be the exact inverse of the canonical predicate."""
+    monkeypatch.setattr(sqlite3, "sqlite_version_info", version_info)
+    assert _wal_is_usable() is not is_sqlite_wal_reset_vulnerable(version_info), (
+        f"conftest gate and hermes_state disagree for SQLite {version_info}"
+    )
+
+
+def test_conftest_does_not_import_hermes_state_at_collection():
+    """The gate must stay import-free of hermes_state.
+
+    Importing it during collection caches DEFAULT_DB_PATH from the real
+    ~/.hermes, so tests read live production sessions instead of a tempdir.
+    Reading the source is not an option here (banned), so assert on behavior:
+    the gate must work with ``hermes_state`` absent from ``sys.modules`` and
+    blocked from being imported.
+    """
+    import builtins
+    import sys
+
+    real_import = builtins.__import__
+    blocked: list[str] = []
+
+    def guard(name, *args, **kwargs):
+        if name == "hermes_state" or name.startswith("hermes_state."):
+            blocked.append(name)
+            raise AssertionError(
+                "conftest._wal_is_usable imported hermes_state — this caches "
+                "DEFAULT_DB_PATH from the real ~/.hermes during collection"
+            )
+        return real_import(name, *args, **kwargs)
+
+    saved = sys.modules.pop("hermes_state", None)
+    builtins.__import__ = guard
+    try:
+        _wal_is_usable()  # must not raise
+    finally:
+        builtins.__import__ = real_import
+        if saved is not None:
+            sys.modules["hermes_state"] = saved
+    assert not blocked
diff --git a/tests/test_hermes_bootstrap.py b/tests/test_hermes_bootstrap.py
index 50a582bf998..a95bff9127a 100644
--- a/tests/test_hermes_bootstrap.py
+++ b/tests/test_hermes_bootstrap.py
@@ -24,6 +24,7 @@ import os
 import subprocess
 import sys
 import textwrap
+from pathlib import Path
 
 import pytest
 
@@ -396,3 +397,45 @@ class TestHardenImportPath:
             sys.path[:] = original
             if original_env is not None:
                 os.environ["HERMES_PYTHON_SRC_ROOT"] = original_env
+
+
+class TestSuppressPlatformVerConsole:
+    """suppress_platform_ver_console: stub applied on Windows, no-op on POSIX."""
+
+    def test_noop_on_posix(self, monkeypatch):
+        import platform
+        hb = _fresh_import()
+        original = getattr(platform, "_syscmd_ver", None)
+        monkeypatch.setattr(hb, "_IS_WINDOWS", False)
+        hb.suppress_platform_ver_console()
+        assert getattr(platform, "_syscmd_ver", None) is original
+
+    def test_stub_applied_when_windows(self, monkeypatch):
+        import platform
+        hb = _fresh_import()
+        original = getattr(platform, "_syscmd_ver", None)
+        try:
+            monkeypatch.setattr(hb, "_IS_WINDOWS", True)
+            hb.suppress_platform_ver_console()
+            stubbed = platform._syscmd_ver
+            assert stubbed is not original
+            # Stub returns its inputs — win32_ver()'s documented fallback path.
+            assert stubbed("s", "r", "v") == ("s", "r", "v")
+            # No-arg call (how Lib/platform.py invokes it in the fallback
+            # probe) must not raise — the rejected PR #69522 wrapper
+            # TypeError'd here.
+            assert stubbed() == ("", "", "")
+        finally:
+            if original is not None:
+                platform._syscmd_ver = original
+
+    def test_never_raises(self, monkeypatch):
+        hb = _fresh_import()
+        monkeypatch.setattr(hb, "_IS_WINDOWS", True)
+        import platform
+        original = platform._syscmd_ver
+        try:
+            monkeypatch.delattr(platform, "_syscmd_ver")
+            hb.suppress_platform_ver_console()  # hasattr guard → silent no-op
+        finally:
+            platform._syscmd_ver = original
diff --git a/tests/test_hermes_state.py b/tests/test_hermes_state.py
index d66d072e0e4..6f3704fa3e2 100644
--- a/tests/test_hermes_state.py
+++ b/tests/test_hermes_state.py
@@ -194,6 +194,44 @@ class TestSessionLifecycle:
         child = db.get_session("child")
         assert child["git_branch"] == "feature-x"
 
+    def test_child_session_inherits_profile_name_from_parent(self, db):
+        """A parented child born without profile_name (compression rotation,
+        /branch) must inherit its parent's owning profile — otherwise the
+        lineage silently migrates to the launch/default profile in unified
+        session lists (the cross-profile session-jump bug)."""
+        db.create_session(session_id="parent", source="cli", profile_name="ai-engineer")
+        # Rotation path: parent is ended with 'compression' BEFORE the child
+        # row is created (agent/conversation_compression.py).
+        db.end_session("parent", "compression")
+
+        db.create_session(session_id="child", source="cli", parent_session_id="parent")
+
+        assert db.get_session("child")["profile_name"] == "ai-engineer"
+
+    def test_child_session_explicit_profile_name_is_not_overwritten(self, db):
+        """Inheritance only fills NULLs — an explicit profile_name on the
+        child is never clobbered by the parent's."""
+        db.create_session(session_id="parent", source="cli", profile_name="ai-engineer")
+
+        db.create_session(
+            session_id="child", source="cli", parent_session_id="parent",
+            profile_name="other",
+        )
+
+        assert db.get_session("child")["profile_name"] == "other"
+
+    def test_multi_generation_lineage_inherits_profile_name(self, db):
+        """profile_name survives a compress-then-branch chain (root -> rotation
+        child -> branch tip) — the exact lineage that used to land on default."""
+        db.create_session(session_id="root", source="cli", profile_name="ai-engineer")
+        db.end_session("root", "compression")
+
+        db.create_session(session_id="gen1", source="cli", parent_session_id="root")
+        db.create_session(session_id="gen2", source="cli", parent_session_id="gen1")
+
+        assert db.get_session("gen1")["profile_name"] == "ai-engineer"
+        assert db.get_session("gen2")["profile_name"] == "ai-engineer"
+
     def test_compression_child_inherits_gateway_origin_columns(self, db):
         """A compression fork's child inherits gateway routing metadata
         (session_key/chat_id/...) from the ended parent, so a crash before
@@ -505,6 +543,30 @@ class TestSessionLifecycle:
                                model="xiaomi/mimo-v2.5-pro")
         assert db.get_session("s1")["model"] == "xiaomi/mimo-v2.5"
 
+    def test_update_session_model_clears_browser_lock_and_preserves_lineage(self, db):
+        """A later /model switch must replace, not compete with, a Browser lock."""
+        db.create_session(
+            session_id="s1",
+            source="hermes_browser",
+            model="x-ai/grok-4.5",
+            model_config={
+                "_branched_from": "parent-session",
+                "browser_model_lock": {
+                    "provider": "nous",
+                    "model": "x-ai/grok-4.5",
+                    "confirmed": True,
+                },
+            },
+        )
+
+        db.update_session_model("s1", "anthropic/claude-opus-4.8")
+
+        session = db.get_session("s1")
+        model_config = json.loads(session["model_config"])
+        assert session["model"] == "anthropic/claude-opus-4.8"
+        assert "browser_model_lock" not in model_config
+        assert model_config["_branched_from"] == "parent-session"
+
     def test_update_session_billing_route_overwrites_after_switch(self, db):
         """A mid-session provider switch must overwrite the billing route.
 
@@ -4631,13 +4693,13 @@ class TestListSessionsRich:
         """
         t0 = 1709500000.0
         db.create_session("root1", "cli")
+        db.append_message("root1", "user", "old ask")
         with db._lock:
             db._conn.execute("UPDATE sessions SET started_at=? WHERE id=?", (t0, "root1"))
             db._conn.execute(
                 "UPDATE sessions SET ended_at=?, end_reason=? WHERE id=?",
                 (t0 + 100, "compression", "root1"),
             )
-        db.append_message("root1", "user", "old ask")
 
         # Continuation tip created after root ended; last activity much later.
         db.create_session("tip1", "cli", parent_session_id="root1")
@@ -4756,6 +4818,39 @@ class TestListSessionsRich:
         assert db.get_session("delegate") is None
         assert db.get_session("branch") is not None
 
+    def test_delete_session_expected_targets_fail_closed_on_new_delegate(self, db):
+        db.create_session("parent", "cli")
+        db.create_session(
+            "delegate",
+            "cli",
+            parent_session_id="parent",
+            model_config={"_delegate_from": "parent"},
+        )
+        db.create_session(
+            "branch",
+            "cli",
+            parent_session_id="parent",
+            model_config={"_branched_from": "parent"},
+        )
+
+        expected_ids = db.get_session_delete_targets("parent")
+        assert expected_ids == ["parent", "delegate"]
+
+        db.create_session(
+            "late-delegate",
+            "cli",
+            parent_session_id="parent",
+            model_config={"_delegate_from": "parent"},
+        )
+
+        assert (
+            db.delete_session("parent", expected_delete_ids=expected_ids) is False
+        )
+        assert db.get_session("parent") is not None
+        assert db.get_session("delegate") is not None
+        assert db.get_session("late-delegate") is not None
+        assert db.get_session("branch") is not None
+
     def test_v16_migration_tags_linked_delegate_rows(self, tmp_path):
         """Pre-marker linked subagent rows get tagged, then cascade with parent."""
         import json
@@ -5834,6 +5929,93 @@ class TestFTSExternalContentMigration:
         finally:
             db.close()
 
+    def test_optimize_fts_storage_vacuum_reports_truthful_size(self, tmp_path):
+        """``logical_size_bytes()`` must be truthful the moment optimize returns.
+
+        In WAL mode VACUUM's rewrite lands in the ``-wal`` file, and the
+        checkpoint that folds it back is REFUSED (SQLITE_BUSY) while another
+        connection — a live gateway — holds a read-mark. A caller that sizes
+        the result with ``os.path.getsize()`` therefore reads the stale,
+        still-growing main file: that is how `hermes sessions optimize-storage`
+        reported "reclaimed -3820.1 MB" on a DB that had actually shrunk 60%.
+        SQLite's own page accounting is correct immediately.
+        """
+        db_path = tmp_path / "v22.db"
+        self._build_v22_db(db_path)
+
+        # Bulk the DB up so VACUUM actually has pages to move: with only a
+        # handful of rows the whole file fits in the WAL's first frames and the
+        # stale-stat() bug is invisible.
+        bulk = sqlite3.connect(str(db_path))
+        bulk.executemany(
+            "INSERT INTO messages (session_id, timestamp, role, content) "
+            "VALUES ('s1', ?, 'user', ?)",
+            [(time.time(), "filler " + "q" * 2000) for _ in range(4000)],
+        )
+        bulk.commit()
+        bulk.close()
+
+        db = SessionDB(db_path=db_path)
+        reader = None
+        try:
+            if db._conn.execute("PRAGMA journal_mode").fetchone()[0].lower() != "wal":
+                pytest.skip("WAL unavailable on this SQLite build")
+
+            # A live gateway/CLI session pinning a WAL read-mark, which is what
+            # blocks the post-VACUUM checkpoint.
+            reader = sqlite3.connect(str(db_path))
+            reader.execute("BEGIN")
+            reader.execute("SELECT COUNT(*) FROM messages").fetchone()
+
+            assert db.optimize_fts_storage(vacuum=True)["ok"] is True
+
+            reported = db.logical_size_bytes()
+            assert reported is not None
+            stat_size = db_path.stat().st_size
+
+            # Settle for real: release the reader, then checkpoint.
+            reader.rollback()
+            reader.close()
+            reader = None
+            db._conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+            settled = db_path.stat().st_size
+
+            page_size = db._conn.execute("PRAGMA page_size").fetchone()[0]
+
+            # Precondition for this test to mean anything: stat() must actually
+            # be lagging here, otherwise it isn't exercising the bug.
+            assert stat_size > settled + page_size, (
+                "test precondition failed: stat() did not lag the settled size, "
+                "so this case does not exercise the reporting bug"
+            )
+
+            # The contract: the reported size tracks where the file lands, not
+            # the stale on-disk size.
+            assert abs(reported - settled) <= page_size, (
+                f"logical_size_bytes() reported {reported} but the file settled "
+                f"at {settled} (stale stat() read {stat_size}) — a "
+                f"reclaimed-bytes delta built on this would be wrong"
+            )
+        finally:
+            if reader is not None:
+                reader.close()
+            db.close()
+
+    def test_logical_size_bytes_matches_page_accounting(self, tmp_path):
+        """Sanity: the helper returns page_count * page_size, or None if closed."""
+        db_path = tmp_path / "v22.db"
+        self._build_v22_db(db_path)
+        db = SessionDB(db_path=db_path)
+        try:
+            pc = db._conn.execute("PRAGMA page_count").fetchone()[0]
+            ps = db._conn.execute("PRAGMA page_size").fetchone()[0]
+            assert db.logical_size_bytes() == pc * ps
+        finally:
+            db.close()
+        # After close the connection is gone — must degrade to None, not raise,
+        # so callers can fall back to stat().
+        assert db.logical_size_bytes() is None
+
     def test_optimize_fts_storage_resumable_after_interrupt(self, tmp_path):
         """A partially-completed optimize resumes on re-run: after demote +
         one chunk, re-invoking finishes without duplicating rows."""
@@ -6450,6 +6632,133 @@ class TestSessionArchive:
         assert db.session_count(include_archived=True) == 2
 
 
+class TestSessionPinAndStaleArchive:
+    """Pin as a durable keep flag + last-activity-based stale auto-archive."""
+
+    def _pinned(self, db, sid):
+        row = db._conn.execute(
+            "SELECT pinned FROM sessions WHERE id = ?", (sid,)
+        ).fetchone()
+        return row["pinned"] if row is not None else None
+
+    def _make_idle(self, db, sid, *, days_idle, source="cli"):
+        """A session whose latest activity was ``days_idle`` days ago."""
+        db.create_session(session_id=sid, source=source)
+        db.append_message(session_id=sid, role="user", content=f"msg {sid}")
+        old = time.time() - days_idle * 86400
+        db._conn.execute("UPDATE sessions SET started_at = ? WHERE id = ?", (old, sid))
+        db._conn.execute(
+            "UPDATE messages SET timestamp = ? WHERE session_id = ?", (old, sid)
+        )
+        db._conn.commit()
+
+    # ── pin flag ──────────────────────────────────────────────────────────
+    def test_set_session_pinned_roundtrip(self, db):
+        db.create_session(session_id="s1", source="cli")
+        assert db.set_session_pinned("s1", True) is True
+        assert self._pinned(db, "s1") == 1
+        assert db.set_session_pinned("s1", False) is True
+        assert self._pinned(db, "s1") == 0
+
+    def test_set_session_pinned_missing_row(self, db):
+        assert db.set_session_pinned("nope", True) is False
+
+    def test_pin_propagates_across_compression_lineage(self, db):
+        db.create_session(session_id="root", source="cli")
+        db.end_session("root", end_reason="compression")
+        db.create_session(session_id="tip", source="cli", parent_session_id="root")
+
+        # Pinning the surfaced tip pins the compressed-away root too.
+        assert db.set_session_pinned("tip", True) is True
+        assert self._pinned(db, "root") == 1
+        assert self._pinned(db, "tip") == 1
+
+    # ── stale archive ─────────────────────────────────────────────────────
+    def test_archives_only_sessions_idle_past_threshold(self, db):
+        self._make_idle(db, "stale", days_idle=5)
+        self._make_idle(db, "fresh", days_idle=1)
+
+        assert db.archive_stale_sessions(3) == 1
+        assert db.get_session("stale")["archived"] == 1
+        assert db.get_session("fresh")["archived"] == 0
+
+    def test_recency_uses_last_activity_not_creation(self, db):
+        # Created long ago, but a message landed today -> not stale.
+        db.create_session(session_id="old_but_active", source="cli")
+        db._conn.execute(
+            "UPDATE sessions SET started_at = ? WHERE id = ?",
+            (time.time() - 60 * 86400, "old_but_active"),
+        )
+        db._conn.commit()
+        db.append_message(
+            session_id="old_but_active", role="user", content="fresh activity"
+        )
+
+        assert db.archive_stale_sessions(3) == 0
+        assert db.get_session("old_but_active")["archived"] == 0
+
+    def test_pinned_sessions_are_spared(self, db):
+        self._make_idle(db, "keep", days_idle=10)
+        db.set_session_pinned("keep", True)
+
+        assert db.archive_stale_sessions(3) == 0
+        assert db.get_session("keep")["archived"] == 0
+        # Opting out of the pin guard sweeps it.
+        assert db.archive_stale_sessions(3, exclude_pinned=False) == 1
+        assert db.get_session("keep")["archived"] == 1
+
+    def test_already_archived_is_idempotent(self, db):
+        self._make_idle(db, "stale", days_idle=5)
+        assert db.archive_stale_sessions(3) == 1
+        assert db.archive_stale_sessions(3) == 0
+
+    def test_stale_tip_archives_whole_compression_chain(self, db):
+        # A compressed-away root is never a candidate on its own (its live
+        # continuation may be fresh); the tip drives the decision and archives
+        # the chain as a unit.
+        db.create_session(session_id="root", source="cli")
+        db.end_session("root", end_reason="compression")
+        db.create_session(session_id="tip", source="cli", parent_session_id="root")
+        old = time.time() - 9 * 86400
+        db._conn.execute(
+            "UPDATE sessions SET started_at = ? WHERE id IN ('root', 'tip')", (old,)
+        )
+        db._conn.commit()
+
+        assert db.archive_stale_sessions(3) == 1  # one candidate (the tip)
+        assert db.get_session("root")["archived"] == 1
+        assert db.get_session("tip")["archived"] == 1
+
+    def test_non_positive_threshold_archives_nothing(self, db):
+        self._make_idle(db, "stale", days_idle=100)
+        assert db.archive_stale_sessions(-1) == 0
+        assert db.get_session("stale")["archived"] == 0
+
+    # ── throttled wrapper ─────────────────────────────────────────────────
+    def test_maybe_auto_archive_runs_then_throttles(self, db):
+        self._make_idle(db, "stale", days_idle=5)
+        first = db.maybe_auto_archive(idle_days=3, min_interval_hours=24)
+        assert first["skipped"] is False
+        assert first["archived"] == 1
+        assert db.get_meta("last_auto_archive") is not None
+
+        # A newly-stale session within the interval is left untouched.
+        self._make_idle(db, "stale2", days_idle=5)
+        second = db.maybe_auto_archive(idle_days=3, min_interval_hours=24)
+        assert second["skipped"] is True
+        assert second["archived"] == 0
+        assert db.get_session("stale2")["archived"] == 0
+
+    def test_maybe_auto_archive_reruns_after_interval(self, db):
+        self._make_idle(db, "stale", days_idle=5)
+        db.maybe_auto_archive(idle_days=3, min_interval_hours=24)
+        db.set_meta("last_auto_archive", str(time.time() - 48 * 3600))
+
+        self._make_idle(db, "stale2", days_idle=5)
+        result = db.maybe_auto_archive(idle_days=3, min_interval_hours=24)
+        assert result["skipped"] is False
+        assert result["archived"] == 1
+
 
 class TestSessionIdSearch:
     """Session id search backs Desktop's Search Sessions UX."""
@@ -6944,6 +7253,59 @@ def test_refresh_compression_lock_requires_holder_and_preserves_reclaimability(d
     assert db.try_acquire_compression_lock("s1", "holder-b", ttl_seconds=10.0) is True
 
 
+def test_starved_refresher_revives_its_own_unclaimed_lease(db, monkeypatch):
+    """A live owner past its own TTL must be able to revive an unclaimed row.
+
+    Ownership is decided by ``holder`` alone, deliberately NOT by
+    ``expires_at``. A refresher starved by a GC pause or a slow write can tick
+    after its own lease notionally expired; while nobody else has claimed the
+    row, that owner is still the owner. Requiring ``expires_at >= now`` made
+    the stall permanent — every later refresh matched 0 rows, so the owner kept
+    compressing and rotating with no lease at all, which is exactly the
+    unprotected window a competing path can fork the session lineage in.
+    """
+    db.create_session("s1", "cli")
+
+    monkeypatch.setattr(hermes_state.time, "time", lambda: 1000.0)
+    assert db.try_acquire_compression_lock("s1", "holder-a", ttl_seconds=10.0) is True
+
+    # Starved well past the 10s TTL, but the row is still holder-a's.
+    monkeypatch.setattr(hermes_state.time, "time", lambda: 1050.0)
+    assert db.refresh_compression_lock("s1", "holder-a", ttl_seconds=10.0) is True
+    revived_expires = db._conn.execute(
+        "SELECT expires_at FROM compression_locks WHERE session_id = ?",
+        ("s1",),
+    ).fetchone()[0]
+    assert revived_expires == 1060.0
+
+    # Reviving must not hand the lease to anyone else.
+    assert db.refresh_compression_lock("s1", "holder-b", ttl_seconds=10.0) is False
+
+
+def test_refresh_cannot_resurrect_a_lock_already_reclaimed(db, monkeypatch):
+    """Once a competitor owns the row, the old holder's refresh must fail.
+
+    The guard is the ``holder`` match, not the clock: a reclaim replaces
+    ``holder``, so the previous owner's UPDATE matches nothing.
+    """
+    db.create_session("s1", "cli")
+
+    monkeypatch.setattr(hermes_state.time, "time", lambda: 1000.0)
+    assert db.try_acquire_compression_lock("s1", "holder-a", ttl_seconds=10.0) is True
+
+    # holder-a's lease lapses and holder-b legitimately reclaims it.
+    monkeypatch.setattr(hermes_state.time, "time", lambda: 1020.0)
+    assert db.try_acquire_compression_lock("s1", "holder-b", ttl_seconds=10.0) is True
+
+    # holder-a coming back late must NOT steal it back.
+    assert db.refresh_compression_lock("s1", "holder-a", ttl_seconds=10.0) is False
+    current = db._conn.execute(
+        "SELECT holder FROM compression_locks WHERE session_id = ?",
+        ("s1",),
+    ).fetchone()[0]
+    assert current == "holder-b"
+
+
 # =========================================================================
 # compact_rows — lightweight column projection (issue #47414)
 # =========================================================================
@@ -7235,3 +7597,110 @@ class TestDisplayMetadataPersistence:
         assert len(switched) == 1
         assert switched[0]["display_metadata"] == meta
 
+
+class TestDisplayMetadataReadPaths:
+    """Every message read path must hand back the decoded dict.
+
+    Returning the raw column instead reaches the desktop as a string, where
+    ``'task_count' in meta`` throws and fails the whole session resume.
+    """
+
+    META = {
+        "delegation_id": "deleg_0d84d484",
+        "task_count": 1,
+        "completed_count": 1,
+        "failed_count": 0,
+        "duration_seconds": 193.55,
+    }
+
+    @staticmethod
+    def _seed(db):
+        db.create_session("s1", source="desktop")
+        message_id = db.append_message(
+            "s1", "user", "event",
+            display_kind="async_delegation_complete",
+            display_metadata=TestDisplayMetadataReadPaths.META,
+        )
+        return message_id, db.append_message("s1", "assistant", "anchor")
+
+    @staticmethod
+    def _read(db, reader, message_id, anchor_id):
+        if reader == "get_messages":
+            return db.get_messages("s1")[0]
+        if reader == "get_messages_around":
+            return db.get_messages_around("s1", message_id, window=0)["window"][0]
+        if reader == "get_anchored_view":
+            view = db.get_anchored_view("s1", anchor_id, window=0, bookend=1)
+            return view["bookend_start"][0]
+        return db.get_messages_as_conversation("s1")[0]
+
+    READERS = ("get_messages", "get_messages_around", "get_anchored_view", "conversation")
+
+    @pytest.mark.parametrize("reader", READERS)
+    def test_every_reader_decodes_display_metadata(self, db, reader):
+        message_id, anchor_id = self._seed(db)
+        assert self._read(db, reader, message_id, anchor_id)["display_metadata"] == self.META
+
+    @pytest.mark.parametrize("reader", READERS)
+    def test_every_reader_unwraps_historically_double_encoded_rows(self, db, reader):
+        """Rows written before the encode guard landed carry a second JSON layer."""
+        message_id, anchor_id = self._seed(db)
+
+        def _corrupt(conn):
+            conn.execute(
+                "UPDATE messages SET display_metadata = ? WHERE id = ?",
+                (json.dumps(json.dumps(self.META)), message_id),
+            )
+
+        db._execute_write(_corrupt)
+        assert self._read(db, reader, message_id, anchor_id)["display_metadata"] == self.META
+
+    @pytest.mark.parametrize("reader", READERS)
+    @pytest.mark.parametrize("raw", ["", "{not-json", "[]", '"text"', "0"])
+    def test_every_reader_drops_unusable_display_metadata(self, db, reader, raw):
+        """Bad presentation metadata must not take the message down with it."""
+        message_id, anchor_id = self._seed(db)
+
+        def _corrupt(conn):
+            conn.execute(
+                "UPDATE messages SET display_metadata = ? WHERE id = ?",
+                (raw, message_id),
+            )
+
+        db._execute_write(_corrupt)
+        message = self._read(db, reader, message_id, anchor_id)
+        assert message.get("display_metadata") is None
+        assert message["content"] == "event"
+
+    def test_export_import_round_trip_keeps_metadata_decodable(self, db, tmp_path):
+        """The read leak used to write a permanently double-encoded row here.
+
+        ``export_session`` reads through ``get_messages``, so an undecoded
+        string went back through ``_insert_message_rows`` and got re-dumped.
+        """
+        self._seed(db)
+        blob = db.export_session("s1")
+        assert isinstance(blob["messages"][0]["display_metadata"], dict)
+
+        target = SessionDB(db_path=tmp_path / "imported.db")
+        try:
+            target.import_sessions([json.loads(json.dumps(blob))])
+            assert target.get_messages_as_conversation("s1")[0]["display_metadata"] == self.META
+            assert target.get_messages("s1")[0]["display_metadata"] == self.META
+        finally:
+            target.close()
+
+    def test_write_paths_do_not_double_encode_serialized_metadata(self, db):
+        """Import/replace can hand us metadata that is already a JSON string."""
+        db.create_session("s1", source="cli")
+        db.replace_messages(
+            "s1",
+            [{
+                "role": "user",
+                "content": "event",
+                "display_kind": "async_delegation_complete",
+                "display_metadata": json.dumps(self.META),
+            }],
+        )
+        assert db.get_messages_as_conversation("s1")[0]["display_metadata"] == self.META
+
diff --git a/tests/test_hermes_state_compression_locks.py b/tests/test_hermes_state_compression_locks.py
index 4e44d92a445..aeeda8cb70f 100644
--- a/tests/test_hermes_state_compression_locks.py
+++ b/tests/test_hermes_state_compression_locks.py
@@ -12,12 +12,15 @@ diagnostic accessor) — not the wiring into compression.
 
 from __future__ import annotations
 
+import os
 import threading
 import time
 from pathlib import Path
+from types import SimpleNamespace
 
 import pytest
 
+import hermes_state
 from hermes_state import SessionDB
 
 
@@ -99,6 +102,212 @@ def test_non_expired_lock_is_held(db: SessionDB) -> None:
     assert db.try_acquire_compression_lock("sess1", "holder2") is False
 
 
+def test_non_expired_lock_from_dead_pid_is_reclaimed(
+    db: SessionDB, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # PID probing is POSIX-only by design (see
+    # test_windows_uses_ttl_only_without_pid_probe). Pin the platform so this
+    # exercises the probe branch on Windows dev machines too, instead of
+    # silently asserting the nt early-return.
+    monkeypatch.setattr(hermes_state.os, "name", "posix")
+    dead_holder = "pid=424242:tid=1:agent=abc:nonce=deadbeef"
+    assert db.try_acquire_compression_lock(
+        "sess1", dead_holder, ttl_seconds=300
+    ) is True
+
+    probed: list[int] = []
+
+    def process_is_gone(pid: int) -> bool:
+        probed.append(pid)
+        return False
+
+    monkeypatch.setattr(
+        hermes_state, "psutil", SimpleNamespace(pid_exists=process_is_gone)
+    )
+
+    assert db.try_acquire_compression_lock(
+        "sess1", "pid=525252:tid=2:agent=def:nonce=fresh", ttl_seconds=300
+    ) is True
+    assert probed == [424242]
+
+
+def test_dead_pid_reclaim_via_os_kill_fallback_when_psutil_missing(
+    db: SessionDB, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Scaffold-phase installs (no psutil) fall back to os.kill(pid, 0).
+
+    POSIX-only path: on Windows ``os.kill(pid, 0)`` is not a probe (sig 0 is
+    CTRL_C_EVENT, bpo-14484), so the production code early-returns there. Pin
+    the platform to keep this branch covered on Windows dev machines.
+    """
+    monkeypatch.setattr(hermes_state.os, "name", "posix")
+    dead_holder = "pid=424242:tid=1:agent=abc:nonce=deadbeef"
+    assert db.try_acquire_compression_lock(
+        "sess1", dead_holder, ttl_seconds=300
+    ) is True
+
+    monkeypatch.setattr(hermes_state, "psutil", None)
+
+    def process_is_gone(pid: int, signal: int) -> None:
+        assert pid == 424242
+        assert signal == 0
+        raise ProcessLookupError
+
+    monkeypatch.setattr(hermes_state.os, "kill", process_is_gone)
+
+    assert db.try_acquire_compression_lock(
+        "sess1", "pid=525252:tid=2:agent=def:nonce=fresh", ttl_seconds=300
+    ) is True
+
+
+def test_probe_doubt_keeps_lease_until_ttl(
+    db: SessionDB, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A probe that errors out is doubt, not proof of death → TTL protects."""
+    holder = "pid=424242:tid=1:agent=abc:nonce=doubt"
+    assert db.try_acquire_compression_lock(
+        "sess1", holder, ttl_seconds=300
+    ) is True
+
+    def probe_blows_up(pid: int) -> bool:
+        raise RuntimeError("transient probe failure")
+
+    monkeypatch.setattr(
+        hermes_state, "psutil", SimpleNamespace(pid_exists=probe_blows_up)
+    )
+
+    assert db.try_acquire_compression_lock(
+        "sess1", "pid=525252:tid=2:agent=def:nonce=other", ttl_seconds=300
+    ) is False
+    assert db.get_compression_lock_holder("sess1") == holder
+
+
+def test_non_expired_lock_from_live_pid_is_not_reclaimed(db: SessionDB) -> None:
+    live_holder = f"pid={os.getpid()}:tid=1:agent=abc:nonce=live"
+    assert db.try_acquire_compression_lock(
+        "sess1", live_holder, ttl_seconds=300
+    ) is True
+    assert db.try_acquire_compression_lock(
+        "sess1", "pid=525252:tid=2:agent=def:nonce=other", ttl_seconds=300
+    ) is False
+
+
+def test_same_process_holder_is_never_self_reclaimed(
+    db: SessionDB, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A holder from THIS pid is never probed — even a lying probe can't steal it."""
+    live_holder = f"pid={os.getpid()}:tid=1:agent=abc:nonce=self"
+    assert db.try_acquire_compression_lock(
+        "sess1", live_holder, ttl_seconds=300
+    ) is True
+    # Even if a (broken) probe were to claim our own PID is dead, the
+    # same-process guard short-circuits before any probe runs.
+    monkeypatch.setattr(
+        hermes_state,
+        "psutil",
+        SimpleNamespace(
+            pid_exists=lambda _pid: pytest.fail(
+                "same-process holder must not be probed"
+            )
+        ),
+    )
+    monkeypatch.setattr(
+        hermes_state.os,
+        "kill",
+        lambda *_args: pytest.fail("same-process holder must not be probed"),
+    )
+    assert db.try_acquire_compression_lock(
+        "sess1", "pid=525252:tid=2:agent=def:nonce=other", ttl_seconds=300
+    ) is False
+    assert db.get_compression_lock_holder("sess1") == live_holder
+
+
+def test_unstructured_holder_waits_for_ttl(
+    db: SessionDB, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    assert db.try_acquire_compression_lock(
+        "sess1", "legacy_holder", ttl_seconds=300
+    ) is True
+    monkeypatch.setattr(
+        hermes_state,
+        "psutil",
+        SimpleNamespace(
+            pid_exists=lambda _pid: pytest.fail(
+                "unstructured holder must not probe a PID"
+            )
+        ),
+    )
+    monkeypatch.setattr(
+        hermes_state.os,
+        "kill",
+        lambda *_args: pytest.fail("unstructured holder must not probe a PID"),
+    )
+    assert db.try_acquire_compression_lock(
+        "sess1", "pid=525252:tid=2:agent=def:nonce=other", ttl_seconds=300
+    ) is False
+
+
+def test_windows_reclaims_dead_holder_via_psutil_probe(
+    db: SessionDB, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """psutil.pid_exists is safe on Windows, so nt hosts do reclaim dead holders.
+
+    The os.kill(pid, 0) footgun (bpo-14484) only affects the no-psutil
+    fallback, not this path — see the companion test below. Gating the whole
+    function on nt used to strand every crashed holder for the full 300s TTL.
+    """
+    holder = "pid=424242:tid=1:agent=abc:nonce=windows"
+    assert db.try_acquire_compression_lock(
+        "sess1", holder, ttl_seconds=300
+    ) is True
+    monkeypatch.setattr(hermes_state.os, "name", "nt")
+    probed: list[int] = []
+
+    def _pid_exists(pid: int) -> bool:
+        probed.append(pid)
+        return False  # holder process is gone
+
+    monkeypatch.setattr(
+        hermes_state, "psutil", SimpleNamespace(pid_exists=_pid_exists)
+    )
+    monkeypatch.setattr(
+        hermes_state.os,
+        "kill",
+        lambda *_args: pytest.fail("Windows must never use os.kill as a PID probe"),
+    )
+
+    assert db.try_acquire_compression_lock(
+        "sess1", "pid=525252:tid=2:agent=def:nonce=other", ttl_seconds=300
+    ) is True
+    assert probed == [424242]
+
+
+def test_windows_without_psutil_stays_ttl_only(
+    db: SessionDB, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Scaffold installs on nt keep the lease: os.kill(pid, 0) is not a probe.
+
+    On Windows signal 0 maps to CTRL_C_EVENT (bpo-14484) and can kill the
+    target's console group, so with psutil absent the only safe answer is
+    "assume alive" and let the TTL expire the lease.
+    """
+    holder = "pid=424242:tid=1:agent=abc:nonce=windows"
+    assert db.try_acquire_compression_lock(
+        "sess1", holder, ttl_seconds=300
+    ) is True
+    monkeypatch.setattr(hermes_state.os, "name", "nt")
+    monkeypatch.setattr(hermes_state, "psutil", None)
+    monkeypatch.setattr(
+        hermes_state.os,
+        "kill",
+        lambda *_args: pytest.fail("Windows must never use os.kill as a PID probe"),
+    )
+
+    assert db.try_acquire_compression_lock(
+        "sess1", "pid=525252:tid=2:agent=def:nonce=other", ttl_seconds=300
+    ) is False
+
+
 # ----------------------------------------------------------------------
 # Empty / invalid input
 # ----------------------------------------------------------------------
diff --git a/tests/test_hermes_state_wal_fallback.py b/tests/test_hermes_state_wal_fallback.py
index 73141ce4388..3bccd9b32ec 100644
--- a/tests/test_hermes_state_wal_fallback.py
+++ b/tests/test_hermes_state_wal_fallback.py
@@ -308,6 +308,9 @@ class TestGetLastInitError:
                 return super().execute(sql, *args, **kwargs)
 
         def gated_connect(*args, **kwargs):
+            # connect_tracked passes a tracking-augmented factory; drop it and
+            # substitute the double, which connect_tracked will re-augment.
+            kwargs.pop("factory", None)
             return real_connect(str(target), factory=_BothPragmasFailConnection, **kwargs)
 
         with patch("hermes_state.sqlite3.connect", side_effect=gated_connect):
@@ -359,6 +362,10 @@ class TestSessionDbUsesWalFallback:
         factory = _make_blocking_factory("locking protocol", attempts)
 
         def gated_connect(*args, **kwargs):
+            # connect_tracked passes a tracking-augmented factory; drop it and
+            # substitute the double, which connect_tracked re-applies to the
+            # returned instance.
+            kwargs.pop("factory", None)
             return real_connect(str(target), factory=factory, **kwargs)
 
         with patch("hermes_state.sqlite3.connect", side_effect=gated_connect):
diff --git a/tests/test_iron_proxy.py b/tests/test_iron_proxy.py
new file mode 100644
index 00000000000..73b798e0fac
--- /dev/null
+++ b/tests/test_iron_proxy.py
@@ -0,0 +1,2050 @@
+"""Hermetic tests for the iron-proxy egress integration.
+
+Covers the pure-function surface (token mint, mapping discovery, config build,
+config + mappings I/O), the binary install path (HTTP downloads + tar
+extraction + checksum verification fully mocked), the subprocess lifecycle
+(spawn / PID / pid_alive / stop, with subprocess.Popen mocked), and the
+docker backend's egress arg builder.
+
+Live network and the real ``iron-proxy`` binary are NEVER touched.  See
+``tests/test_iron_proxy_e2e.py`` (gated behind a marker) for the real-binary
+smoke test.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import sys
+import tarfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent.proxy_sources import iron_proxy as ip
+
+
+# ---------------------------------------------------------------------------
+# Per-test isolation
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def hermes_home(tmp_path, monkeypatch):
+    """Point HERMES_HOME at a temp dir so install paths don't touch the real $HOME."""
+
+    home = tmp_path / "hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    # Make sure no stale provider keys influence discovery.
+    for key in list(os.environ):
+        if key.endswith("_API_KEY"):
+            monkeypatch.delenv(key, raising=False)
+    return home
+
+
+# ---------------------------------------------------------------------------
+# Token mint + mapping discovery
+# ---------------------------------------------------------------------------
+
+
+def test_mint_proxy_token_has_prefix_and_length():
+    t = ip.mint_proxy_token("alpha")
+    assert t.startswith("alpha-")
+    assert len(t) >= len("alpha-") + 32
+
+
+def test_mint_proxy_token_is_random():
+    a = ip.mint_proxy_token("x")
+    b = ip.mint_proxy_token("x")
+    assert a != b
+
+
+def test_discover_provider_mappings_from_env(hermes_home, monkeypatch):
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-real-1")
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-real-2")
+    monkeypatch.delenv("MISTRAL_API_KEY", raising=False)
+    ms = ip.discover_provider_mappings()
+    names = [m.real_env_name for m in ms]
+    assert "OPENROUTER_API_KEY" in names
+    assert "OPENAI_API_KEY" in names
+    assert "MISTRAL_API_KEY" not in names
+
+
+def test_discover_provider_mappings_explicit_names(hermes_home):
+    ms = ip.discover_provider_mappings(
+        available_env_names=["OPENROUTER_API_KEY", "GROQ_API_KEY", "UNKNOWN_KEY"]
+    )
+    names = {m.real_env_name for m in ms}
+    assert names == {"OPENROUTER_API_KEY", "GROQ_API_KEY"}
+    # Unknown providers (no entry in _BEARER_PROVIDERS) are skipped, not warned.
+
+
+def test_discover_provider_mappings_empty(hermes_home):
+    ms = ip.discover_provider_mappings(available_env_names=[])
+    assert ms == []
+
+
+# ---------------------------------------------------------------------------
+# Config / mapping serialization
+# ---------------------------------------------------------------------------
+
+
+def _sample_mapping(env_name: str = "OPENROUTER_API_KEY") -> ip.TokenMapping:
+    return ip.TokenMapping(
+        proxy_token=ip.mint_proxy_token("test"),
+        real_env_name=env_name,
+        upstream_hosts=("openrouter.ai", "*.openrouter.ai"),
+    )
+
+
+def test_build_proxy_config_shape(tmp_path):
+    m = _sample_mapping()
+    ca_crt = tmp_path / "ca.crt"
+    ca_key = tmp_path / "ca.key"
+    cfg = ip.build_proxy_config(
+        mappings=[m],
+        ca_cert=ca_crt,
+        ca_key=ca_key,
+    )
+    # Top-level sections — note `dns` is required by iron-proxy even when
+    # we only use the CONNECT tunnel.
+    assert set(cfg.keys()) >= {"dns", "proxy", "tls", "transforms", "log"}
+    # Transforms in expected order
+    assert [t["name"] for t in cfg["transforms"]] == ["allowlist", "secrets"]
+    # Allowlist uses `domains:` (iron-proxy schema), not `hosts:`
+    domains = cfg["transforms"][0]["config"]["domains"]
+    assert "openrouter.ai" in domains
+    # Secrets transform encodes our mapping
+    rules = cfg["transforms"][1]["config"]["secrets"]
+    assert len(rules) == 1
+    rule = rules[0]
+    # Real secret value is sourced from env at egress time, NOT inlined.
+    assert rule["source"] == {"type": "env", "var": "OPENROUTER_API_KEY"}
+    # The proxy token is the replacement target.
+    assert rule["replace"]["proxy_value"] == m.proxy_token
+    assert "Authorization" in rule["replace"]["match_headers"]
+    # Fail-closed: a request to a mapped host without the proxy token must be
+    # rejected, not forwarded with whatever credential it carried
+    # (maxpetrusenko P1). iron-proxy's replaceConfig.Require enforces this.
+    assert rule["replace"]["require"] is True
+    # Rules list contains one entry per upstream host.
+    rule_hosts = {r["host"] for r in rule["rules"]}
+    assert rule_hosts == set(m.upstream_hosts)
+    # TLS section names the CA paths
+    assert cfg["tls"]["ca_cert"] == str(ca_crt)
+
+
+def test_build_proxy_config_custom_allowed_hosts(tmp_path):
+    m = _sample_mapping("OPENAI_API_KEY")
+    cfg = ip.build_proxy_config(
+        mappings=[m],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        allowed_hosts=["custom-host.test"],
+    )
+    domains = cfg["transforms"][0]["config"]["domains"]
+    # Custom allowed_hosts wins as the base; mapping's hosts get appended.
+    assert "custom-host.test" in domains
+    assert "openrouter.ai" in domains  # comes from the mapping
+
+
+# ---------------------------------------------------------------------------
+# Default SSRF deny list (regression: docs promise cloud metadata is denied)
+# ---------------------------------------------------------------------------
+
+
+def test_default_deny_cidrs_present_when_unspecified(tmp_path):
+    """build_proxy_config must emit the default deny list when the caller
+    passes nothing.  The IMDS subnet (169.254.0.0/16) MUST be in the result
+    or the docs claim that ``upstream_deny_cidrs`` refuses cloud metadata
+    is a lie."""
+
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+    )
+    deny = cfg["proxy"]["upstream_deny_cidrs"]
+    assert "169.254.0.0/16" in deny  # IMDS
+    assert "127.0.0.0/8" in deny      # loopback v4
+    assert "::1/128" in deny           # loopback v6
+    assert "10.0.0.0/8" in deny        # RFC1918
+    assert "172.16.0.0/12" in deny     # RFC1918
+    assert "192.168.0.0/16" in deny    # RFC1918
+
+
+def test_explicit_empty_deny_cidrs_disables_default(tmp_path):
+    """Explicit ``[]`` opts out of the default deny list — needed by
+    hermetic tests that want to talk to a loopback upstream."""
+
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        upstream_deny_cidrs=[],
+    )
+    assert cfg["proxy"]["upstream_deny_cidrs"] == []
+
+
+def test_wizard_rendered_yaml_contains_deny_list(hermes_home, tmp_path):
+    """End-to-end: cmd_setup writes proxy.yaml; the rendered file must
+    contain the deny list because the wizard now passes the operator's
+    config-level setting (None → default) through to build_proxy_config."""
+
+    # Simulate the wizard's call shape (matches proxy_cli.cmd_setup).
+    state = ip._proxy_state_dir()
+    (state / "ca.crt").write_text("fake-ca")
+    (state / "ca.key").write_text("fake-key")
+    proxy_yaml = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=state / "ca.crt",
+        ca_key=state / "ca.key",
+        # The wizard passes ``upstream_deny_cidrs`` from the config; when
+        # the operator hasn't set anything, that's None and we get the
+        # safe default below.
+        upstream_deny_cidrs=None,
+    )
+    out = ip.write_proxy_config(proxy_yaml)
+    text = out.read_text(encoding="utf-8")
+    assert "169.254.0.0/16" in text
+
+
+# ---------------------------------------------------------------------------
+# Bind policy (regression: must not bind 0.0.0.0)
+# ---------------------------------------------------------------------------
+
+
+def test_default_bind_is_loopback_not_zero_zero(tmp_path):
+    """The sandbox-facing listeners must NOT be ``0.0.0.0:PORT`` or
+    ``:PORT`` (latter is INADDR_ANY)."""
+
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        tunnel_port=12345,
+        http_listen=["127.0.0.1:12345"],  # explicit so test is deterministic
+    )
+    # tunnel_listen is the CONNECT/MITM listener sandboxes hit via
+    # HTTPS_PROXY; http_listen is the plain-HTTP forward on port+1.
+    assert cfg["proxy"]["tunnel_listen"] == "127.0.0.1:12345"
+    assert cfg["proxy"]["http_listen"] == "127.0.0.1:12346"
+    for key in ("tunnel_listen", "http_listen", "https_listen"):
+        val = cfg["proxy"][key]
+        # Sentinel: confirm we didn't accidentally serialize a bare-port
+        # form like ":12345" (that's INADDR_ANY).
+        assert not val.startswith(":")
+        assert "0.0.0.0" not in val
+    # iron-proxy v0.39 doesn't support http_listens (plural).  We
+    # deliberately do NOT emit that key — re-emitting it would cause
+    # the daemon to fail YAML unmarshal at start time.
+    assert "http_listens" not in cfg["proxy"], (
+        "iron-proxy v0.39 rejects http_listens (plural); only the "
+        "singular http_listen string is accepted by the binary"
+    )
+
+
+def test_default_bind_uses_docker_bridge_on_linux(tmp_path, monkeypatch):
+    """When http_listen isn't passed AND we're on Linux, the singular
+    http_listen field is the DOCKER BRIDGE bind — not loopback.
+    iron-proxy v0.39 only supports one bind per daemon process, and on
+    Linux ``host.docker.internal:host-gateway`` resolves to the bridge
+    gateway (172.17.0.1 by default), which a loopback-only daemon never
+    answers.  Sandboxes must be able to reach the proxy from the
+    container's vantage point."""
+
+    monkeypatch.setattr(ip.platform, "system", lambda: "Linux")
+    monkeypatch.setattr(ip, "_detect_docker_bridge_ip", lambda: "172.17.0.1")
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        tunnel_port=9090,
+    )
+    # The sandbox-facing CONNECT/MITM listener binds the bridge gateway —
+    # reachable from containers via host.docker.internal.  Plain-HTTP
+    # forward listener rides on port+1, same host.
+    assert cfg["proxy"]["tunnel_listen"] == "172.17.0.1:9090"
+    assert cfg["proxy"]["http_listen"] == "172.17.0.1:9091"
+    # No http_listens (plural) — v0.39 rejects that key.
+    assert "http_listens" not in cfg["proxy"]
+
+
+def test_default_bind_falls_back_to_loopback_without_bridge(tmp_path, monkeypatch):
+    """On Linux without a detectable docker0 bridge (docker not
+    installed / not running), fall back to loopback rather than
+    refusing to bind."""
+
+    monkeypatch.setattr(ip.platform, "system", lambda: "Linux")
+    monkeypatch.setattr(ip, "_detect_docker_bridge_ip", lambda: None)
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        tunnel_port=9090,
+    )
+    assert cfg["proxy"]["tunnel_listen"] == "127.0.0.1:9090"
+    assert cfg["proxy"]["http_listen"] == "127.0.0.1:9091"
+
+
+def test_default_bind_is_loopback_on_macos(tmp_path, monkeypatch):
+    """On Docker Desktop platforms host.docker.internal routes to the
+    host via VPNkit, so loopback is reachable from containers and is
+    the least-exposed bind."""
+
+    monkeypatch.setattr(ip.platform, "system", lambda: "Darwin")
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        tunnel_port=9090,
+    )
+    assert cfg["proxy"]["tunnel_listen"] == "127.0.0.1:9090"
+    assert cfg["proxy"]["http_listen"] == "127.0.0.1:9091"
+
+
+def test_metrics_listener_pinned_to_loopback_ephemeral(tmp_path):
+    """iron-proxy v0.39's default metrics_listen is ``:9090``, which
+    collides with our default tunnel_port=9090.  build_proxy_config MUST
+    explicitly pin metrics.listen to ``127.0.0.1:0`` so the bind
+    collision can never happen at start time."""
+
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        tunnel_port=9090,
+    )
+    assert cfg["metrics"]["listen"] == "127.0.0.1:0"
+
+
+# ---------------------------------------------------------------------------
+# audit_log file pre-creation (parameter still accepted; v0.39 doesn't
+# wire it into the binary config but ensure_audit_log() still creates
+# the file at 0o600 as a logrotate / monitoring sentinel)
+# ---------------------------------------------------------------------------
+
+
+def test_audit_log_kwarg_does_not_inject_audit_path_v039(tmp_path):
+    """v0.39 of iron-proxy rejects ``log.audit_path`` (not a struct
+    field).  build_proxy_config still accepts the audit_log kwarg for
+    forward compatibility but MUST NOT emit it into the rendered yaml
+    until the upstream binary supports it.  See the kwarg's docstring
+    for the upgrade path."""
+
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        audit_log=tmp_path / "audit.log",
+    )
+    assert "audit_path" not in cfg["log"], (
+        "iron-proxy v0.39 has no log.audit_path field; emitting it "
+        "causes 'field audit_path not found in type config.Log' at "
+        "daemon start.  ensure_audit_log() still creates the file as "
+        "an operator-facing logrotate target."
+    )
+
+
+def test_audit_log_omitted_when_caller_passes_none(tmp_path):
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        audit_log=None,
+    )
+    assert "audit_path" not in cfg["log"]
+
+
+def test_write_and_load_mappings_roundtrip(hermes_home):
+    ms = [_sample_mapping("OPENROUTER_API_KEY"), _sample_mapping("OPENAI_API_KEY")]
+    path = ip.write_mappings(ms)
+    assert path.exists()
+    loaded = ip.load_mappings()
+    assert len(loaded) == 2
+    assert {m.real_env_name for m in loaded} == {"OPENROUTER_API_KEY", "OPENAI_API_KEY"}
+    # Tokens preserved
+    assert loaded[0].proxy_token == ms[0].proxy_token
+
+
+def test_load_mappings_handles_missing_file(hermes_home):
+    assert ip.load_mappings() == []
+
+
+def test_load_mappings_handles_corrupt_json(hermes_home):
+    state = ip._proxy_state_dir()
+    (state / "mappings.json").write_text("{not json", encoding="utf-8")
+    assert ip.load_mappings() == []
+
+
+def test_write_proxy_config_serializes_yaml(hermes_home, tmp_path):
+    ca_crt = tmp_path / "ca.crt"
+    ca_key = tmp_path / "ca.key"
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=ca_crt,
+        ca_key=ca_key,
+    )
+    out = ip.write_proxy_config(cfg)
+    assert out.exists()
+    text = out.read_text(encoding="utf-8")
+    assert "tunnel_listen" in text
+    assert f"ca_cert: {ca_crt}" in text
+    # The rendered config embeds proxy token values — it must land at
+    # 0o600, and (TOCTOU) must never be transiently world-readable
+    # between the atomic replace and the chmod.  We chmod the temp file
+    # before the replace, so the final file is 0o600 from first byte.
+    import os as _os
+    mode = _os.stat(out).st_mode & 0o777
+    assert mode == 0o600, f"proxy.yaml perms {oct(mode)}, expected 0o600"
+    mappings_out = ip.write_mappings([_sample_mapping()])
+    mmode = _os.stat(mappings_out).st_mode & 0o777
+    assert mmode == 0o600, f"mappings.json perms {oct(mmode)}, expected 0o600"
+
+
+# ---------------------------------------------------------------------------
+# Token-preservation on re-setup (regression: clobbered live sandboxes)
+# ---------------------------------------------------------------------------
+
+
+def test_merge_mappings_preserves_existing_tokens():
+    """Re-running setup must not invalidate tokens baked into already-
+    running sandboxes.  ``merge_mappings`` keeps the prior token for any
+    provider that's in both lists."""
+
+    existing = [
+        ip.TokenMapping(
+            proxy_token="hermes-proxy-original-12345",
+            real_env_name="OPENROUTER_API_KEY",
+            upstream_hosts=("openrouter.ai",),
+        ),
+    ]
+    discovered = ip.discover_provider_mappings(
+        available_env_names=["OPENROUTER_API_KEY", "OPENAI_API_KEY"]
+    )
+    merged = ip.merge_mappings(existing=existing, discovered=discovered)
+    by_name = {m.real_env_name: m for m in merged}
+    # Original token preserved.
+    assert by_name["OPENROUTER_API_KEY"].proxy_token == "hermes-proxy-original-12345"
+    # New provider got a fresh token.
+    assert by_name["OPENAI_API_KEY"].proxy_token != "hermes-proxy-original-12345"
+    # Both providers in the result.
+    assert set(by_name) == {"OPENROUTER_API_KEY", "OPENAI_API_KEY"}
+
+
+def test_merge_mappings_drops_providers_removed_from_env():
+    """When a provider is in `existing` but not in `discovered`, it must
+    be dropped from the result — the operator removed the env var."""
+
+    existing = [
+        ip.TokenMapping(
+            proxy_token="stale", real_env_name="OPENROUTER_API_KEY",
+            upstream_hosts=("openrouter.ai",),
+        ),
+    ]
+    discovered = ip.discover_provider_mappings(
+        available_env_names=["OPENAI_API_KEY"]
+    )
+    merged = ip.merge_mappings(existing=existing, discovered=discovered)
+    names = {m.real_env_name for m in merged}
+    assert names == {"OPENAI_API_KEY"}
+
+
+def test_merge_mappings_rotate_mints_fresh_tokens():
+    """``rotate=True`` rolls every token regardless of overlap.  The
+    --rotate-tokens flag uses this."""
+
+    existing = [
+        ip.TokenMapping(
+            proxy_token="hermes-proxy-original-12345",
+            real_env_name="OPENROUTER_API_KEY",
+            upstream_hosts=("openrouter.ai",),
+        ),
+    ]
+    discovered = ip.discover_provider_mappings(
+        available_env_names=["OPENROUTER_API_KEY"]
+    )
+    merged = ip.merge_mappings(existing=existing, discovered=discovered, rotate=True)
+    assert merged[0].proxy_token != "hermes-proxy-original-12345"
+
+
+# ---------------------------------------------------------------------------
+# Uncovered provider detection (regression: signature-auth providers bypass)
+# ---------------------------------------------------------------------------
+
+
+def test_uncovered_providers_detects_aws_gcp_appdefault(hermes_home, monkeypatch):
+    monkeypatch.setenv("AWS_ACCESS_KEY_ID", "AKIAEXAMPLE")
+    monkeypatch.setenv("GOOGLE_APPLICATION_CREDENTIALS", "/etc/gcp.json")
+    uncovered = ip.discover_uncovered_providers()
+    assert "AWS_ACCESS_KEY_ID" in uncovered
+    assert "GOOGLE_APPLICATION_CREDENTIALS" in uncovered
+
+
+def test_uncovered_providers_explicit_names_empty():
+    assert ip.discover_uncovered_providers(available_env_names=[]) == []
+
+
+def test_uncovered_providers_skips_bearer_providers(hermes_home, monkeypatch):
+    """OPENROUTER_API_KEY etc. are bearer providers — they should NOT
+    appear in the uncovered list."""
+
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-test")
+    uncovered = ip.discover_uncovered_providers()
+    assert "OPENROUTER_API_KEY" not in uncovered
+
+
+def test_uncovered_providers_skips_header_auth_providers(hermes_home, monkeypatch):
+    """Anthropic / Azure / Gemini moved from 'uncovered' to first-class
+    header-auth swapped providers — they must no longer be reported as
+    uncovered."""
+
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test")
+    monkeypatch.setenv("AZURE_OPENAI_API_KEY", "az-test")
+    monkeypatch.setenv("GEMINI_API_KEY", "g-test")
+    monkeypatch.setenv("GOOGLE_API_KEY", "g-test-alias")
+    uncovered = ip.discover_uncovered_providers()
+    assert "ANTHROPIC_API_KEY" not in uncovered
+    assert "AZURE_OPENAI_API_KEY" not in uncovered
+    assert "GEMINI_API_KEY" not in uncovered
+    assert "GOOGLE_API_KEY" not in uncovered
+
+
+# ---------------------------------------------------------------------------
+# Binary discovery + lazy install
+# ---------------------------------------------------------------------------
+
+
+def test_find_iron_proxy_returns_none_when_missing(hermes_home, monkeypatch):
+    monkeypatch.setattr("shutil.which", lambda name: None)
+    assert ip.find_iron_proxy(install_if_missing=False) is None
+
+
+def test_find_iron_proxy_returns_managed_first(hermes_home, monkeypatch):
+    managed = ip._hermes_bin_dir() / ip._platform_binary_name()
+    managed.parent.mkdir(parents=True, exist_ok=True)
+    managed.write_bytes(b"#!/bin/sh\necho ok\n")
+    managed.chmod(0o755)
+    # Even with a system one on PATH, the managed copy should win.
+    monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/iron-proxy")
+    assert ip.find_iron_proxy() == managed
+
+
+def _make_fake_tar(binary_name: str, payload: bytes = b"#!/bin/sh\necho ok\n") -> bytes:
+    """Build a tar.gz with one file at the root, named ``binary_name``."""
+
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        info = tarfile.TarInfo(name=binary_name)
+        info.size = len(payload)
+        info.mode = 0o755
+        tf.addfile(info, io.BytesIO(payload))
+    return buf.getvalue()
+
+
+def test_install_iron_proxy_verifies_checksum_and_extracts(hermes_home, monkeypatch):
+    fake_payload = _make_fake_tar(ip._platform_binary_name())
+    import hashlib
+
+    expected_sha = hashlib.sha256(fake_payload).hexdigest()
+    asset_name = ip._platform_asset_name()
+    checksum_text = f"{expected_sha}  {asset_name}\nffff  other-asset.tar.gz\n"
+
+    def fake_download(url: str, dest: Path) -> None:
+        if url.endswith(ip._IRON_PROXY_CHECKSUM_NAME):
+            dest.write_text(checksum_text)
+        else:
+            dest.write_bytes(fake_payload)
+
+    monkeypatch.setattr(ip, "_http_download", fake_download)
+    target = ip.install_iron_proxy()
+    assert target.exists()
+    assert target.read_bytes() == b"#!/bin/sh\necho ok\n"
+    # Executable bit is set
+    assert os.access(target, os.X_OK)
+
+
+def test_install_iron_proxy_rejects_bad_checksum(hermes_home, monkeypatch):
+    fake_payload = _make_fake_tar(ip._platform_binary_name())
+    asset_name = ip._platform_asset_name()
+    bad_text = f"deadbeef  {asset_name}\n"
+
+    def fake_download(url: str, dest: Path) -> None:
+        if url.endswith(ip._IRON_PROXY_CHECKSUM_NAME):
+            dest.write_text(bad_text)
+        else:
+            dest.write_bytes(fake_payload)
+
+    monkeypatch.setattr(ip, "_http_download", fake_download)
+    with pytest.raises(RuntimeError, match="Checksum mismatch"):
+        ip.install_iron_proxy()
+
+
+def test_install_iron_proxy_rejects_missing_checksum_entry(hermes_home, monkeypatch):
+    fake_payload = _make_fake_tar(ip._platform_binary_name())
+
+    def fake_download(url: str, dest: Path) -> None:
+        if url.endswith(ip._IRON_PROXY_CHECKSUM_NAME):
+            dest.write_text("aaaa  some-other-file.tar.gz\n")
+        else:
+            dest.write_bytes(fake_payload)
+
+    monkeypatch.setattr(ip, "_http_download", fake_download)
+    with pytest.raises(RuntimeError, match="No checksum entry"):
+        ip.install_iron_proxy()
+
+
+# ── GPG release-signature verification (maxpetrusenko P1) ────────────────────
+
+def test_verify_checksums_signature_skips_without_gpg(hermes_home, monkeypatch, tmp_path):
+    """No gpg on PATH → degrade gracefully (return False), do not raise."""
+    monkeypatch.setattr(ip.shutil, "which", lambda name: None)
+    cks = tmp_path / "checksums.txt"
+    cks.write_text("abc  iron-proxy.tar.gz\n")
+    assert ip._verify_checksums_signature(tmp_path, cks) is False
+
+
+def test_verify_checksums_signature_skips_when_sig_assets_missing(hermes_home, monkeypatch, tmp_path):
+    """gpg present but the release ships no .asc assets → degrade, don't raise."""
+    monkeypatch.setattr(ip.shutil, "which", lambda name: "/usr/bin/gpg" if name == "gpg" else None)
+
+    def fail_download(url: str, dest: Path) -> None:
+        raise RuntimeError("404 not found")
+    monkeypatch.setattr(ip, "_http_download", fail_download)
+    cks = tmp_path / "checksums.txt"
+    cks.write_text("abc  iron-proxy.tar.gz\n")
+    assert ip._verify_checksums_signature(tmp_path, cks) is False
+
+
+def test_verify_checksums_signature_raises_on_bad_signature(hermes_home, monkeypatch, tmp_path):
+    """A present-but-INVALID signature is a tamper signal → must raise."""
+    monkeypatch.setattr(ip.shutil, "which", lambda name: "/usr/bin/gpg" if name == "gpg" else None)
+    monkeypatch.setattr(ip, "_http_download", lambda url, dest: dest.write_bytes(b"asc"))
+
+    class _R:
+        def __init__(self, rc): self.returncode = rc; self.stderr = b"BAD signature"
+    def fake_run(cmd, **kw):
+        # import succeeds (rc 0), verify fails (rc 1)
+        return _R(0) if "--import" in cmd else _R(1)
+    monkeypatch.setattr(ip.subprocess, "run", fake_run)
+
+    cks = tmp_path / "checksums.txt"
+    cks.write_text("abc  iron-proxy.tar.gz\n")
+    with pytest.raises(RuntimeError, match="failed GPG signature verification"):
+        ip._verify_checksums_signature(tmp_path, cks)
+
+
+def test_verify_checksums_signature_passes_on_good_signature(hermes_home, monkeypatch, tmp_path):
+    """Valid signature → returns True."""
+    monkeypatch.setattr(ip.shutil, "which", lambda name: "/usr/bin/gpg" if name == "gpg" else None)
+    monkeypatch.setattr(ip, "_http_download", lambda url, dest: dest.write_bytes(b"asc"))
+
+    class _R:
+        def __init__(self, rc): self.returncode = rc; self.stderr = b""
+    monkeypatch.setattr(ip.subprocess, "run", lambda cmd, **kw: _R(0))
+
+    cks = tmp_path / "checksums.txt"
+    cks.write_text("abc  iron-proxy.tar.gz\n")
+    assert ip._verify_checksums_signature(tmp_path, cks) is True
+
+
+def test_install_aborts_on_bad_release_signature(hermes_home, monkeypatch):
+    """End-to-end: a tampered (bad-signature) release must abort install."""
+    fake_payload = _make_fake_tar(ip._platform_binary_name())
+    import hashlib
+    sha = hashlib.sha256(fake_payload).hexdigest()
+    asset_name = ip._platform_asset_name()
+
+    def fake_download(url: str, dest: Path) -> None:
+        if url.endswith(ip._IRON_PROXY_CHECKSUM_NAME):
+            dest.write_text(f"{sha}  {asset_name}\n")
+        elif url.endswith(".asc"):
+            dest.write_bytes(b"-----BEGIN PGP-----\n")
+        else:
+            dest.write_bytes(fake_payload)
+    monkeypatch.setattr(ip, "_http_download", fake_download)
+    monkeypatch.setattr(ip.shutil, "which", lambda name: "/usr/bin/gpg" if name == "gpg" else None)
+
+    class _R:
+        def __init__(self, rc): self.returncode = rc; self.stderr = b"BAD"
+    monkeypatch.setattr(ip.subprocess, "run",
+                        lambda cmd, **kw: _R(0) if "--import" in cmd else _R(1))
+
+    with pytest.raises(RuntimeError, match="GPG signature verification"):
+        ip.install_iron_proxy()
+
+
+def test_pick_tar_member_rejects_path_traversal():
+    """A malicious tar that escapes via '..' must be refused."""
+
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        info = tarfile.TarInfo(name="../iron-proxy")
+        info.size = 1
+        info.mode = 0o755
+        tf.addfile(info, io.BytesIO(b"x"))
+    buf.seek(0)
+    with tarfile.open(fileobj=buf, mode="r:gz") as tf:
+        with pytest.raises(RuntimeError, match="Could not find iron-proxy"):
+            ip._pick_tar_member(tf, "iron-proxy")
+
+
+# ---------------------------------------------------------------------------
+# Subprocess lifecycle
+# ---------------------------------------------------------------------------
+
+
+def test_get_status_when_nothing_configured(hermes_home):
+    status = ip.get_status()
+    assert status.binary_path is None
+    assert status.config_path is None
+    assert status.ca_cert_path is None
+    assert status.pid is None
+    assert status.listening is False
+    assert not status.installed
+    assert not status.configured
+
+
+def test_get_status_with_config_present(hermes_home, monkeypatch):
+    # Materialize binary, config, and ca cert.
+    bin_path = ip._hermes_bin_dir() / ip._platform_binary_name()
+    bin_path.parent.mkdir(parents=True, exist_ok=True)
+    bin_path.write_bytes(b"")
+    bin_path.chmod(0o755)
+    state = ip._proxy_state_dir()
+    (state / "ca.crt").write_text("fake")
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=state / "ca.crt",
+        ca_key=state / "ca.key",
+        tunnel_port=9999,
+    )
+    ip.write_proxy_config(cfg)
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "iron-proxy v0.0.0-test")
+
+    status = ip.get_status()
+    assert status.installed
+    assert status.configured
+    assert status.tunnel_port == 9999
+    assert "test" in (status.binary_version or "")
+
+
+def test_stop_proxy_handles_missing_pidfile(hermes_home):
+    # No pidfile → stop returns False, doesn't raise.
+    assert ip.stop_proxy() is False
+
+
+def test_stop_proxy_cleans_stale_pidfile(hermes_home, monkeypatch):
+    pid_file = ip._proxy_state_dir() / "iron-proxy.pid"
+    pid_file.write_text("999999999")
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: False)
+    assert ip.stop_proxy() is False
+    assert not pid_file.exists()
+
+
+def test_start_proxy_refuses_without_binary(hermes_home, monkeypatch):
+    # No binary, auto_install fails → RuntimeError surfaces.
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kwargs: None)
+    state = ip._proxy_state_dir()
+    (state / "proxy.yaml").write_text("proxy: {}")
+    with pytest.raises(RuntimeError, match="binary not available"):
+        ip.start_proxy()
+
+
+def test_start_proxy_refuses_without_config(hermes_home, monkeypatch):
+    binary = ip._hermes_bin_dir() / ip._platform_binary_name()
+    binary.parent.mkdir(parents=True, exist_ok=True)
+    binary.write_bytes(b"")
+    binary.chmod(0o755)
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kwargs: binary)
+    with pytest.raises(RuntimeError, match="config not found"):
+        ip.start_proxy()
+
+
+def test_start_proxy_writes_pidfile_when_alive(hermes_home, monkeypatch):
+    binary = ip._hermes_bin_dir() / ip._platform_binary_name()
+    binary.parent.mkdir(parents=True, exist_ok=True)
+    binary.write_bytes(b"")
+    binary.chmod(0o755)
+    state = ip._proxy_state_dir()
+    (state / "proxy.yaml").write_text("proxy: {}")
+
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kwargs: binary)
+    monkeypatch.setattr(ip, "_STARTUP_GRACE_SECONDS", 0)
+
+    # Pre-stub everything start_proxy's get_status() call will touch — it
+    # runs INSIDE start_proxy, so by the time Popen is mocked these have
+    # to already be hermetic.
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    # v3: start_proxy now REQUIRES _port_listening to return True before
+    # writing the pidfile.  The previous version of this test mocked it
+    # to False and relied on the loop falling through; the new code
+    # treats fall-through as failure and kills the child.
+    monkeypatch.setattr(ip, "_port_listening", lambda h, p: True)
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "iron-proxy test")
+
+    fake_proc = MagicMock()
+    fake_proc.pid = 4242
+    fake_proc.poll.return_value = None  # still alive
+
+    with patch("subprocess.Popen", lambda *a, **k: fake_proc):
+        status = ip.start_proxy()
+    assert (state / "iron-proxy.pid").read_text() == "4242"
+    assert status.pid == 4242
+
+
+def test_start_proxy_raises_when_immediate_exit(hermes_home, monkeypatch):
+    binary = ip._hermes_bin_dir() / ip._platform_binary_name()
+    binary.parent.mkdir(parents=True, exist_ok=True)
+    binary.write_bytes(b"")
+    binary.chmod(0o755)
+    state = ip._proxy_state_dir()
+    (state / "proxy.yaml").write_text("proxy: {}")
+    (state / "iron-proxy.log").write_text("bind: address already in use\n")
+
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kwargs: binary)
+    monkeypatch.setattr(ip, "_STARTUP_GRACE_SECONDS", 0)
+
+    fake_proc = MagicMock()
+    fake_proc.pid = 5151
+    fake_proc.poll.return_value = 1  # exited immediately
+    fake_proc.returncode = 1
+    with patch("subprocess.Popen", lambda *a, **k: fake_proc):
+        with pytest.raises(RuntimeError, match="exited immediately"):
+            ip.start_proxy()
+
+
+def test_start_proxy_idempotent_when_already_running(hermes_home, monkeypatch):
+    state = ip._proxy_state_dir()
+    pid_file = state / "iron-proxy.pid"
+    pid_file.write_text("12345")
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    monkeypatch.setattr(ip, "_port_listening", lambda h, p: True)
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "test")
+    # Materialize config so we get past that check (we shouldn't reach it,
+    # but if the idempotent path regresses we want a clean failure mode).
+    (state / "proxy.yaml").write_text("proxy: {}")
+    # Sentinel: subprocess.Popen must NOT be called.
+    with patch("subprocess.Popen", lambda *a, **k: pytest.fail("should not spawn")):
+        status = ip.start_proxy()
+    # Should return without spawning anything.
+    assert status is not None
+
+
+# ---------------------------------------------------------------------------
+# Docker integration
+# ---------------------------------------------------------------------------
+
+
+def test_docker_egress_args_empty_when_disabled(hermes_home, monkeypatch):
+    from tools.environments.docker import _egress_proxy_args_for_docker
+
+    # Default config has proxy.enabled=False; helper should return all empties.
+    vol, env, host = _egress_proxy_args_for_docker()
+    assert vol == []
+    assert env == {}
+    assert host == []
+
+
+def test_docker_egress_args_when_enabled_but_unconfigured_raises(hermes_home, monkeypatch):
+    from tools.environments.docker import _egress_proxy_args_for_docker
+    from hermes_cli.config import load_config, save_config
+
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["enforce_on_docker"] = True
+    save_config(cfg)
+
+    # No proxy.yaml exists → enforce_on_docker should raise.
+    with pytest.raises(RuntimeError, match="not configured"):
+        _egress_proxy_args_for_docker()
+
+
+def test_docker_egress_args_when_unconfigured_no_enforce(hermes_home, monkeypatch):
+    from tools.environments.docker import _egress_proxy_args_for_docker
+    from hermes_cli.config import load_config, save_config
+
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["enforce_on_docker"] = False
+    save_config(cfg)
+
+    # Without enforcement, missing config returns empties (warning only).
+    vol, env, host = _egress_proxy_args_for_docker()
+    assert vol == []
+    assert env == {}
+    assert host == []
+
+
+def test_docker_egress_args_full_path(hermes_home, monkeypatch):
+    """Wire up everything (config, CA, mappings, fake running proxy) and
+    verify the docker helper emits the right mounts and env."""
+
+    from tools.environments.docker import _egress_proxy_args_for_docker
+    from hermes_cli.config import load_config, save_config
+
+    # Materialize config, CA, mappings.
+    state = ip._proxy_state_dir()
+    ca = state / "ca.crt"
+    ca.write_text("fake-ca")
+    (state / "ca.key").write_text("fake-key")
+    mapping = _sample_mapping("OPENROUTER_API_KEY")
+    proxy_cfg = ip.build_proxy_config(
+        mappings=[mapping], ca_cert=ca, ca_key=state / "ca.key", tunnel_port=9090,
+    )
+    ip.write_proxy_config(proxy_cfg)
+    ip.write_mappings([mapping])
+
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["enforce_on_docker"] = True
+    save_config(cfg)
+
+    # Fake running proxy.
+    (state / "iron-proxy.pid").write_text("99999")
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    monkeypatch.setattr(ip, "_port_listening", lambda h, p: True)
+
+    vol, env, host = _egress_proxy_args_for_docker()
+    # CA mount present and in -v form
+    assert "-v" in vol
+    assert any("hermes-egress-ca.crt" in arg for arg in vol)
+    # Env contains both casings of HTTPS_PROXY and the CA env vars
+    assert env["HTTPS_PROXY"].endswith(":9090")
+    assert env["https_proxy"] == env["HTTPS_PROXY"]
+    assert env["REQUESTS_CA_BUNDLE"].endswith("hermes-egress-ca.crt")
+    assert env["NODE_EXTRA_CA_CERTS"] == env["REQUESTS_CA_BUNDLE"]
+    # NO_PROXY excludes loopback
+    assert "127.0.0.1" in env["NO_PROXY"]
+    # Per-mapping proxy token is surfaced under both the standard provider env
+    # name (so existing SDKs work without egress-specific code) and the
+    # introspection name.
+    assert env["OPENROUTER_API_KEY"] == mapping.proxy_token
+    assert env["HERMES_PROXY_TOKEN_OPENROUTER_API_KEY"] == mapping.proxy_token
+    # Linux host-gateway mapping
+    assert host == ["--add-host", "host.docker.internal:host-gateway"]
+
+
+def test_docker_egress_fingerprint_changes_with_tokens(hermes_home, monkeypatch):
+    """Persistent Docker container reuse must not attach to a container that
+    was created before egress, before a token rotation, or with a different CA
+    mount.  The label hash is what forces a fresh container in those cases."""
+
+    from tools.environments.docker import _egress_reuse_fingerprint
+
+    first = _egress_reuse_fingerprint(
+        ["-v", "/tmp/ca:/etc/ssl/certs/hermes-egress-ca.crt:ro"],
+        {"OPENROUTER_API_KEY": "token-a", "HTTPS_PROXY": "http://h:9090"},
+        ["--add-host", "host.docker.internal:host-gateway"],
+    )
+    second = _egress_reuse_fingerprint(
+        ["-v", "/tmp/ca:/etc/ssl/certs/hermes-egress-ca.crt:ro"],
+        {"OPENROUTER_API_KEY": "token-b", "HTTPS_PROXY": "http://h:9090"},
+        ["--add-host", "host.docker.internal:host-gateway"],
+    )
+
+    assert first
+    assert second
+    assert first != second
+
+
+# ---------------------------------------------------------------------------
+# Platform asset name resolution
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "system,machine,expected_substring",
+    [
+        ("Linux", "x86_64", "linux_amd64"),
+        ("Linux", "aarch64", "linux_arm64"),
+        ("Darwin", "arm64", "darwin_arm64"),
+        ("Darwin", "x86_64", "darwin_amd64"),
+    ],
+)
+def test_platform_asset_name(monkeypatch, system, machine, expected_substring):
+    monkeypatch.setattr("platform.system", lambda: system)
+    monkeypatch.setattr("platform.machine", lambda: machine)
+    assert expected_substring in ip._platform_asset_name()
+
+
+def test_platform_asset_name_rejects_windows(monkeypatch):
+    monkeypatch.setattr("platform.system", lambda: "Windows")
+    monkeypatch.setattr("platform.machine", lambda: "AMD64")
+    with pytest.raises(RuntimeError, match="does not ship native Windows"):
+        ip._platform_asset_name()
+
+
+# ---------------------------------------------------------------------------
+# Subprocess env minimization (regression: host secrets leaked to proxy)
+# ---------------------------------------------------------------------------
+
+
+def test_subprocess_env_strips_unrelated_secrets(hermes_home, monkeypatch):
+    """``_build_proxy_subprocess_env`` must NOT carry every host secret
+    over to the proxy.  /proc/<pid>/environ on the proxy would otherwise
+    expose all of them to same-uid local processes."""
+
+    # Unrelated env vars that should NOT propagate.
+    monkeypatch.setenv("MY_PRIVATE_TOKEN", "should-not-leak")
+    monkeypatch.setenv("DATABASE_URL", "postgres://very-private")
+    monkeypatch.setenv("SLACK_BOT_TOKEN", "xoxb-very-secret")
+    # Provider keys that ARE in load_mappings should propagate.
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-real")
+    ip.write_mappings([_sample_mapping("OPENROUTER_API_KEY")])
+
+    env = ip._build_proxy_subprocess_env()
+    assert "MY_PRIVATE_TOKEN" not in env
+    assert "DATABASE_URL" not in env
+    assert "SLACK_BOT_TOKEN" not in env
+    assert env.get("OPENROUTER_API_KEY") == "sk-or-real"
+
+
+def test_subprocess_env_strips_proxy_recursion_vars(hermes_home, monkeypatch):
+    """HTTPS_PROXY etc. in the parent env would otherwise recurse iron-proxy
+    through itself (or send its traffic through a corporate proxy)."""
+
+    monkeypatch.setenv("HTTPS_PROXY", "http://corporate:3128")
+    monkeypatch.setenv("HTTP_PROXY", "http://corporate:3128")
+    monkeypatch.setenv("ALL_PROXY", "socks5://corporate:1080")
+    env = ip._build_proxy_subprocess_env()
+    assert "HTTPS_PROXY" not in env
+    assert "https_proxy" not in env
+    assert "HTTP_PROXY" not in env
+    assert "ALL_PROXY" not in env
+
+
+def test_subprocess_env_keeps_infrastructure_vars(hermes_home, monkeypatch):
+    """PATH / HOME / locale must propagate or the child can't even find
+    its libs."""
+
+    monkeypatch.setenv("PATH", "/usr/local/bin:/usr/bin")
+    monkeypatch.setenv("HOME", "/home/test")
+    monkeypatch.setenv("LANG", "C.UTF-8")
+    env = ip._build_proxy_subprocess_env()
+    assert env.get("PATH") == "/usr/local/bin:/usr/bin"
+    assert env.get("HOME") == "/home/test"
+    assert env.get("LANG") == "C.UTF-8"
+
+
+# ---------------------------------------------------------------------------
+# CA generation TOCTOU (regression: 0o600 only set AFTER copy)
+# ---------------------------------------------------------------------------
+
+
+def test_ca_key_created_with_0o600(hermes_home, monkeypatch):
+    """The CA private key must NEVER exist on disk with default umask
+    permissions, even transiently.  Fix: open with explicit mode=0o600
+    so the very first byte is written under tight perms."""
+
+    # ensure_ca_cert shells out to openssl; mock the subprocess.run calls
+    # so we don't need openssl on the test host AND don't depend on its
+    # output format.
+    def fake_run(args, **kwargs):
+        # First call: genrsa → -out is at args[-2]
+        if args[1] == "genrsa":
+            out = args[-2]
+            Path(out).write_bytes(b"-----BEGIN RSA PRIVATE KEY-----\nfake\n-----END RSA PRIVATE KEY-----\n")
+        elif args[1] == "req":
+            # Find -out path
+            i = args.index("-out")
+            Path(args[i + 1]).write_bytes(b"-----BEGIN CERTIFICATE-----\nfake\n-----END CERTIFICATE-----\n")
+        result = MagicMock()
+        result.returncode = 0
+        return result
+
+    monkeypatch.setattr(ip.shutil, "which", lambda name: "/usr/bin/openssl" if name == "openssl" else None)
+    monkeypatch.setattr(ip.subprocess, "run", fake_run)
+
+    ca_crt, ca_key = ip.ensure_ca_cert()
+    assert ca_key.exists()
+    mode = ca_key.stat().st_mode & 0o777
+    assert mode == 0o600, f"CA key has perms {oct(mode)}, expected 0o600"
+
+
+# ---------------------------------------------------------------------------
+# Audit log permissions (regression: depended on umask)
+# ---------------------------------------------------------------------------
+
+
+def test_ensure_audit_log_creates_with_0o600(hermes_home, tmp_path):
+    audit = tmp_path / "audit.log"
+    ip.ensure_audit_log(audit)
+    assert audit.exists()
+    mode = audit.stat().st_mode & 0o777
+    assert mode == 0o600
+
+
+def test_ensure_audit_log_tightens_existing_perms(hermes_home, tmp_path):
+    audit = tmp_path / "audit.log"
+    audit.write_text("preexisting content\n")
+    os.chmod(audit, 0o644)
+    ip.ensure_audit_log(audit)
+    mode = audit.stat().st_mode & 0o777
+    assert mode == 0o600
+
+
+# ---------------------------------------------------------------------------
+# State dir hardening (regression: world-traversable on multi-user hosts)
+# ---------------------------------------------------------------------------
+
+
+def test_proxy_state_dir_is_0o700(hermes_home):
+    state = ip._proxy_state_dir()
+    mode = state.stat().st_mode & 0o777
+    assert mode == 0o700
+
+
+def test_proxy_state_dir_ro_does_not_create(hermes_home):
+    """_proxy_state_dir_ro is for read-only callers — it must NOT
+    materialize the dir.  Pure-status code paths shouldn't have the
+    side-effect of creating ~/.hermes/proxy/."""
+
+    # Sanity: rw path creates it.
+    rw = ip._proxy_state_dir()
+    assert rw.exists()
+    # Remove it and confirm the ro path doesn't recreate.
+    import shutil as _shutil
+    _shutil.rmtree(str(rw))
+    assert not rw.exists()
+    ro = ip._proxy_state_dir_ro()
+    assert not ro.exists()
+    # The path string is the same as the rw one.
+    assert ro == rw
+
+
+# ---------------------------------------------------------------------------
+# Mappings clobber refused when corrupt (regression: silent 403s)
+# ---------------------------------------------------------------------------
+
+
+def test_docker_egress_args_raises_on_empty_mappings(hermes_home, monkeypatch):
+    """If mappings.json is missing / corrupt / empty AND
+    enforce_on_docker is true, refuse to start the sandbox rather than
+    silently mounting an unusable proxy config."""
+
+    from tools.environments.docker import _egress_proxy_args_for_docker
+    from hermes_cli.config import load_config, save_config
+
+    state = ip._proxy_state_dir()
+    (state / "ca.crt").write_text("fake-ca")
+    (state / "ca.key").write_text("fake-key")
+    proxy_cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=state / "ca.crt", ca_key=state / "ca.key", tunnel_port=9090,
+    )
+    ip.write_proxy_config(proxy_cfg)
+    # Note: we deliberately do NOT write mappings.json — that's the
+    # bug-class this test guards against.
+
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["enforce_on_docker"] = True
+    save_config(cfg)
+
+    (state / "iron-proxy.pid").write_text("99999")
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    monkeypatch.setattr(ip, "_port_listening", lambda h, p: True)
+
+    with pytest.raises(RuntimeError, match="mappings.json is empty or"):
+        _egress_proxy_args_for_docker()
+
+
+# ---------------------------------------------------------------------------
+# CA missing → enforce_on_docker semantics (regression: silent fail-open)
+# ---------------------------------------------------------------------------
+
+
+def test_docker_egress_args_raises_when_ca_vanishes(hermes_home, monkeypatch):
+    """status.configured was True at check time but the CA file
+    disappeared between then and now (e.g. operator manually deleted
+    ~/.hermes/proxy/ca.crt).  enforce_on_docker=True must refuse."""
+
+    from tools.environments.docker import _egress_proxy_args_for_docker
+    from hermes_cli.config import load_config, save_config
+
+    state = ip._proxy_state_dir()
+    ca = state / "ca.crt"
+    ca.write_text("fake-ca")
+    (state / "ca.key").write_text("fake-key")
+    proxy_cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=ca, ca_key=state / "ca.key", tunnel_port=9090,
+    )
+    ip.write_proxy_config(proxy_cfg)
+    ip.write_mappings([_sample_mapping()])
+
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["enforce_on_docker"] = True
+    save_config(cfg)
+
+    (state / "iron-proxy.pid").write_text("99999")
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    monkeypatch.setattr(ip, "_port_listening", lambda h, p: True)
+
+    # Build a fake status: configured=True (because both path fields are
+    # set), but ca_cert_path.exists() is False — simulating the race
+    # where the CA file vanished between get_status() and the
+    # exists() recheck inside _egress_proxy_args_for_docker.
+    fake_status = ip.ProxyStatus(
+        binary_path=state / "fake-bin",  # truthy
+        config_path=state / "proxy.yaml",
+        ca_cert_path=state / "missing-ca.crt",  # points at nonexistent path
+        pid=99999,
+        listening=True,
+        tunnel_port=9090,
+    )
+    # ProxyStatus.configured returns True iff config_path AND ca_cert_path
+    # both exist.  We need configured=True but the second exists() check
+    # in docker.py to return False — force that by writing a placeholder
+    # config_path that exists and pointing ca_cert_path at a missing file.
+    (state / "proxy.yaml").write_text("# fake")
+    # ProxyStatus.configured: config_path.exists() and ca_cert_path.exists().
+    # Make ca_cert_path .exists() True for the configured check but the
+    # explicit .exists() recheck path in docker.py reads the same Path,
+    # which is missing — so we wrap.
+    class _CAStub:
+        """Path-like that toggles .exists() so configured=True but the
+        defensive recheck in docker.py returns False."""
+        _calls = 0
+        def __init__(self, real: Path):
+            self._real = real
+        def __str__(self):
+            return str(self._real)
+        @property
+        def parent(self):
+            return self._real.parent
+        def exists(self):
+            type(self)._calls += 1
+            # First call: configured property check → say yes.
+            # Second call: docker.py defensive recheck → say no.
+            return type(self)._calls == 1
+    fake_status.ca_cert_path = _CAStub(state / "missing-ca.crt")  # type: ignore[assignment]
+    monkeypatch.setattr(ip, "get_status", lambda: fake_status)
+
+    with pytest.raises(RuntimeError, match="CA cert vanished"):
+        _egress_proxy_args_for_docker()
+
+
+# ---------------------------------------------------------------------------
+# Docker env collision detection (regression: docker_env silently bypassed proxy)
+# ---------------------------------------------------------------------------
+
+
+def test_docker_env_collision_with_proxy_raises_when_enforce(hermes_home, monkeypatch):
+    """Setting docker_env: {HTTPS_PROXY: ''} in config.yaml with
+    enforce_on_docker=true must fail-loud rather than silently inverting
+    the egress isolation."""
+
+    from tools.environments.docker import DockerEnvironment
+    from hermes_cli.config import load_config, save_config
+
+    # Set up a fully-running proxy.
+    state = ip._proxy_state_dir()
+    ca = state / "ca.crt"
+    ca.write_text("fake-ca")
+    (state / "ca.key").write_text("fake-key")
+    proxy_cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=ca, ca_key=state / "ca.key", tunnel_port=9090,
+    )
+    ip.write_proxy_config(proxy_cfg)
+    ip.write_mappings([_sample_mapping()])
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["enforce_on_docker"] = True
+    save_config(cfg)
+    (state / "iron-proxy.pid").write_text("99999")
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    monkeypatch.setattr(ip, "_port_listening", lambda h, p: True)
+
+    # Mock the docker availability check so we never shell out.
+    monkeypatch.setattr(
+        "tools.environments.docker._ensure_docker_available", lambda: None,
+    )
+    # Mock find_docker so the resolved docker exe isn't probed.
+    monkeypatch.setattr(
+        "tools.environments.docker.find_docker", lambda: "/bin/true",
+    )
+    # Mock subprocess.run so we don't actually run `docker run`.  We
+    # only need the constructor to get past the env merge logic.
+    monkeypatch.setattr(
+        "tools.environments.docker.subprocess.run",
+        lambda *a, **k: MagicMock(stdout="abc123\n", returncode=0),
+    )
+    # init_session is the second outbound subprocess we don't care about.
+    monkeypatch.setattr(
+        "tools.environments.docker.DockerEnvironment.init_session",
+        lambda self: None,
+    )
+
+    # The collision: user sets HTTPS_PROXY to empty string in docker_env.
+    with pytest.raises(RuntimeError, match="overrides egress-proxy variables"):
+        DockerEnvironment(
+            image="busybox",
+            env={"HTTPS_PROXY": ""},  # the collision
+        )
+
+
+# ---------------------------------------------------------------------------
+# v3 round: bridge-IP parser hardening (P1 #1)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "bogus_ip",
+    [
+        "0.0.0.0",            # INADDR_ANY — must NEVER bind here
+        "127.0.0.1",          # loopback — reject (we bind loopback explicitly)
+        "224.0.0.1",          # multicast
+        "240.0.0.0",          # reserved
+        "169.254.0.1",        # link-local / IMDS — never a real bridge
+        "8.8.8.8",            # public — never a docker bridge
+        "999.999.999.999",    # garbage that count(.)==3 used to accept
+        "aa.bb.cc.dd",        # alpha garbage
+    ],
+)
+def test_detect_docker_bridge_ip_rejects_dangerous(monkeypatch, bogus_ip):
+    """The parser must reject anything that isn't plausibly a docker
+    bridge IP.  Previously ``ip.count('.') == 3`` would accept all of
+    these and re-open the LAN exposure the bind-policy fix closed."""
+
+    fake_stdout = (
+        f"3: docker0    inet {bogus_ip}/16 brd 172.17.255.255 scope global docker0\\\n"
+        "       valid_lft forever preferred_lft forever"
+    )
+
+    def fake_run(cmd, **kw):
+        from unittest.mock import MagicMock
+        m = MagicMock()
+        m.returncode = 0
+        m.stdout = fake_stdout
+        return m
+
+    monkeypatch.setattr(ip.subprocess, "run", fake_run)
+    assert ip._detect_docker_bridge_ip() is None
+
+
+def test_detect_docker_bridge_ip_accepts_typical(monkeypatch):
+    fake_stdout = (
+        "3: docker0    inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0\\\n"
+        "       valid_lft forever preferred_lft forever"
+    )
+
+    def fake_run(cmd, **kw):
+        from unittest.mock import MagicMock
+        m = MagicMock()
+        m.returncode = 0
+        m.stdout = fake_stdout
+        return m
+
+    monkeypatch.setattr(ip.subprocess, "run", fake_run)
+    assert ip._detect_docker_bridge_ip() == "172.17.0.1"
+
+
+def test_detect_docker_bridge_ip_handles_missing_ip_command(monkeypatch):
+    """No ``ip`` on PATH (or other OSError) returns None cleanly."""
+
+    def boom(*a, **k):
+        raise OSError("no such file")
+
+    monkeypatch.setattr(ip.subprocess, "run", boom)
+    assert ip._detect_docker_bridge_ip() is None
+
+
+# ---------------------------------------------------------------------------
+# v3: default deny-list adjacency (P2 IPv4-mapped-v6 + CGNAT)
+# ---------------------------------------------------------------------------
+
+
+def test_default_deny_includes_ipv4_mapped_v6(tmp_path):
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+    )
+    deny = cfg["proxy"]["upstream_deny_cidrs"]
+    assert "::ffff:0:0/96" in deny
+    assert "100.64.0.0/10" in deny    # CGNAT
+    assert "198.18.0.0/15" in deny    # RFC2544 benchmark
+
+
+# ---------------------------------------------------------------------------
+# Header-auth providers (x-api-key family) — match_headers + aliases
+# ---------------------------------------------------------------------------
+
+
+def test_header_auth_providers_discovered(hermes_home, monkeypatch):
+    """Anthropic / Azure / Gemini mint mappings with their native auth
+    headers instead of landing in the uncovered list."""
+
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test")
+    monkeypatch.setenv("AZURE_OPENAI_API_KEY", "az-test")
+    monkeypatch.setenv("GEMINI_API_KEY", "g-test")
+
+    ms = {m.real_env_name: m for m in ip.discover_provider_mappings()}
+    assert "ANTHROPIC_API_KEY" in ms
+    assert "AZURE_OPENAI_API_KEY" in ms
+    assert "GEMINI_API_KEY" in ms
+
+    anth = ms["ANTHROPIC_API_KEY"]
+    assert "x-api-key" in anth.match_headers
+    assert "api.anthropic.com" in anth.upstream_hosts
+
+    azure = ms["AZURE_OPENAI_API_KEY"]
+    assert "api-key" in azure.match_headers
+
+    gem = ms["GEMINI_API_KEY"]
+    assert "x-goog-api-key" in gem.match_headers
+    assert "GOOGLE_API_KEY" in gem.alias_env_names
+
+
+def test_gemini_alias_collapses_to_single_mapping(hermes_home, monkeypatch):
+    """GEMINI_API_KEY + GOOGLE_API_KEY are the same upstream credential —
+    two require-rules on the same host would reject each other's requests,
+    so exactly ONE mapping must be minted regardless of which names are
+    set."""
+
+    monkeypatch.setenv("GEMINI_API_KEY", "g-test")
+    monkeypatch.setenv("GOOGLE_API_KEY", "g-test-alias")
+    ms = [m for m in ip.discover_provider_mappings()
+          if "generativelanguage" in " ".join(m.upstream_hosts)]
+    assert len(ms) == 1
+    assert ms[0].real_env_name == "GEMINI_API_KEY"
+
+
+def test_gemini_alias_only_still_mints_mapping(hermes_home, monkeypatch):
+    """An operator with ONLY GOOGLE_API_KEY set still gets Gemini coverage
+    (mapping keyed on the canonical name)."""
+
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    monkeypatch.setenv("GOOGLE_API_KEY", "g-test-alias")
+    ms = {m.real_env_name: m for m in ip.discover_provider_mappings()}
+    assert "GEMINI_API_KEY" in ms
+    assert "GOOGLE_API_KEY" in ms["GEMINI_API_KEY"].alias_env_names
+
+
+def test_build_proxy_config_emits_per_provider_match_headers(tmp_path):
+    """Header-auth mappings carry their native headers into the secrets
+    rule; bearer mappings keep the Authorization default."""
+
+    bearer = _sample_mapping()
+    anth = ip.TokenMapping(
+        proxy_token=ip.mint_proxy_token("anthropic"),
+        real_env_name="ANTHROPIC_API_KEY",
+        upstream_hosts=("api.anthropic.com",),
+        match_headers=("x-api-key", "Authorization"),
+    )
+    cfg = ip.build_proxy_config(
+        mappings=[bearer, anth],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+    )
+    rules = {r["source"]["var"]: r for r in cfg["transforms"][1]["config"]["secrets"]}
+    assert rules["OPENROUTER_API_KEY"]["replace"]["match_headers"] == ["Authorization"]
+    assert rules["ANTHROPIC_API_KEY"]["replace"]["match_headers"] == [
+        "x-api-key", "Authorization",
+    ]
+    # Fail-closed still applies to header-auth providers.
+    assert rules["ANTHROPIC_API_KEY"]["replace"]["require"] is True
+    # Header-auth hosts land on the allowlist too.
+    assert "api.anthropic.com" in cfg["transforms"][0]["config"]["domains"]
+
+
+def test_mappings_roundtrip_preserves_headers_and_aliases(hermes_home):
+    m = ip.TokenMapping(
+        proxy_token=ip.mint_proxy_token("gemini"),
+        real_env_name="GEMINI_API_KEY",
+        upstream_hosts=("generativelanguage.googleapis.com",),
+        match_headers=("x-goog-api-key",),
+        alias_env_names=("GOOGLE_API_KEY",),
+    )
+    ip.write_mappings([m])
+    loaded = ip.load_mappings()
+    assert loaded[0].match_headers == ("x-goog-api-key",)
+    assert loaded[0].alias_env_names == ("GOOGLE_API_KEY",)
+
+
+def test_load_mappings_legacy_entries_default_to_bearer(hermes_home):
+    """mappings.json written before the match_headers/alias fields must
+    load with the Authorization default (same behavior as at write time)."""
+
+    import json as _json
+    state = ip._proxy_state_dir()
+    (state / "mappings.json").write_text(_json.dumps({
+        "version": 1,
+        "tokens": [{
+            "proxy_token": "openrouter-legacy-token",
+            "env_name": "OPENROUTER_API_KEY",
+            "upstream_hosts": ["openrouter.ai"],
+        }],
+    }), encoding="utf-8")
+    loaded = ip.load_mappings()
+    assert loaded[0].match_headers == ("Authorization",)
+    assert loaded[0].alias_env_names == ()
+
+
+def test_subprocess_env_mirrors_alias_into_canonical(hermes_home, monkeypatch):
+    """When only the alias (GOOGLE_API_KEY) is exported, the proxy child
+    env must still carry the canonical name the secrets rule reads."""
+
+    m = ip.TokenMapping(
+        proxy_token=ip.mint_proxy_token("gemini"),
+        real_env_name="GEMINI_API_KEY",
+        upstream_hosts=("generativelanguage.googleapis.com",),
+        match_headers=("x-goog-api-key",),
+        alias_env_names=("GOOGLE_API_KEY",),
+    )
+    ip.write_mappings([m])
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    monkeypatch.setenv("GOOGLE_API_KEY", "g-real-secret")
+    env = ip._build_proxy_subprocess_env()
+    assert env.get("GEMINI_API_KEY") == "g-real-secret"
+
+
+def test_subprocess_env_canonical_wins_over_alias(hermes_home, monkeypatch):
+    m = ip.TokenMapping(
+        proxy_token=ip.mint_proxy_token("gemini"),
+        real_env_name="GEMINI_API_KEY",
+        upstream_hosts=("generativelanguage.googleapis.com",),
+        match_headers=("x-goog-api-key",),
+        alias_env_names=("GOOGLE_API_KEY",),
+    )
+    ip.write_mappings([m])
+    monkeypatch.setenv("GEMINI_API_KEY", "g-canonical")
+    monkeypatch.setenv("GOOGLE_API_KEY", "g-alias")
+    env = ip._build_proxy_subprocess_env()
+    assert env.get("GEMINI_API_KEY") == "g-canonical"
+
+
+# ---------------------------------------------------------------------------
+# Management API (hot reload)
+# ---------------------------------------------------------------------------
+
+
+def test_build_proxy_config_enables_management_listener(tmp_path):
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=tmp_path / "ca.crt",
+        ca_key=tmp_path / "ca.key",
+        tunnel_port=9090,
+    )
+    mgmt = cfg["management"]
+    # Loopback only — sandboxes must never reach the management surface.
+    assert mgmt["listen"].startswith("127.0.0.1:")
+    assert mgmt["listen"].endswith(":9092")  # tunnel_port + 2
+    assert mgmt["api_key_env"] == ip._MGMT_API_KEY_ENV
+
+
+def test_ensure_management_token_persists_and_is_stable(hermes_home):
+    t1 = ip.ensure_management_token()
+    t2 = ip.ensure_management_token()
+    assert t1 == t2
+    assert t1.startswith("hermes-mgmt-")
+    p = ip._proxy_state_dir() / "management.token"
+    assert p.exists()
+    assert (p.stat().st_mode & 0o777) == 0o600
+
+
+def test_ensure_management_token_force_rotates(hermes_home):
+    t1 = ip.ensure_management_token()
+    t2 = ip.ensure_management_token(force=True)
+    assert t1 != t2
+
+
+def test_reload_proxy_refuses_when_not_running(hermes_home, monkeypatch):
+    monkeypatch.setattr(ip, "_read_pid", lambda: None)
+    with pytest.raises(RuntimeError, match="not running"):
+        ip.reload_proxy()
+
+
+def test_reload_proxy_refuses_on_pre_management_config(hermes_home, monkeypatch):
+    """A config written before management support has no listener — the
+    error must tell the operator to re-setup + restart once."""
+
+    monkeypatch.setattr(ip, "_read_pid", lambda: 4242)
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    # No proxy.yaml at all -> _read_management_listen_from_config is None.
+    with pytest.raises(RuntimeError, match="restart"):
+        ip.reload_proxy()
+
+
+def test_reload_proxy_posts_bearer_to_management_endpoint(hermes_home, monkeypatch):
+    monkeypatch.setattr(ip, "_read_pid", lambda: 4242)
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    monkeypatch.setattr(
+        ip, "_read_management_listen_from_config",
+        lambda config_path=None: ("127.0.0.1", 9092),
+    )
+    ip.ensure_management_token()
+
+    captured = {}
+
+    class _FakeResp:
+        status = 200
+        def __enter__(self):
+            return self
+        def __exit__(self, *a):
+            return False
+
+    def fake_urlopen(req, timeout=None):
+        captured["url"] = req.full_url
+        captured["method"] = req.get_method()
+        captured["auth"] = req.get_header("Authorization")
+        return _FakeResp()
+
+    import urllib.request
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+
+    assert ip.reload_proxy() is True
+    assert captured["url"] == "http://127.0.0.1:9092/v1/reload"
+    assert captured["method"] == "POST"
+    token = (ip._proxy_state_dir() / "management.token").read_text().strip()
+    assert captured["auth"] == f"Bearer {token}"
+
+
+def test_start_proxy_injects_management_key_env(hermes_home, monkeypatch):
+    """When the generated config has a management listener, start_proxy
+    must inject the bearer key env var — v0.39 refuses to start when
+    api_key_env is empty."""
+
+    cfg_path = ip._proxy_state_dir() / "proxy.yaml"
+    cfg = ip.build_proxy_config(
+        mappings=[_sample_mapping()],
+        ca_cert=hermes_home / "ca.crt",
+        ca_key=hermes_home / "ca.key",
+        http_listen=["127.0.0.1:9090"],
+    )
+    ip.write_proxy_config(cfg)
+    (hermes_home / "bin").mkdir(parents=True, exist_ok=True)
+    fake_bin = hermes_home / "bin" / "iron-proxy"
+    fake_bin.write_text("#!/bin/sh\nsleep 60\n")
+    fake_bin.chmod(0o755)
+
+    captured_env = {}
+
+    class _FakeProc:
+        pid = 99999
+        def poll(self):
+            return None
+
+    def fake_popen(cmd, **kw):
+        captured_env.update(kw.get("env") or {})
+        return _FakeProc()
+
+    monkeypatch.setattr(ip.subprocess, "Popen", fake_popen)
+    monkeypatch.setattr(ip, "_write_pidfile_safely", lambda pf, pid: None)
+    monkeypatch.setattr(ip, "_port_listening", lambda h, p: True)
+    monkeypatch.setattr(ip, "get_status", lambda: ip.ProxyStatus(pid=99999, listening=True))
+
+    ip.start_proxy(binary=fake_bin, config_path=cfg_path, install_if_missing=False)
+    assert captured_env.get(ip._MGMT_API_KEY_ENV)
+    assert captured_env[ip._MGMT_API_KEY_ENV].startswith("hermes-mgmt-")
+
+
+# ---------------------------------------------------------------------------
+# v3: _pid_proc_starttime parser (handles comm with parens, brackets)
+# ---------------------------------------------------------------------------
+
+
+def test_pid_proc_starttime_parses_comm_with_parens(tmp_path, monkeypatch):
+    """``/proc/<pid>/stat`` 'comm' field can contain spaces and parens
+    (e.g. a process literally named ``weird) tail``, with the comm
+    wrapped in the outer parens producing ``(weird) tail)``).  The
+    starttime parser must split from the LAST ')' to skip the comm
+    correctly, otherwise the field-index math drifts.
+
+    Layout reminder: ``<pid> (<comm>) <state> <ppid> ... <starttime> ...``
+    where starttime is field 22 (1-indexed).  Past the LAST ')' we have
+    fields 3..N → tail index 0..N-3, so starttime is at tail index 19.
+    """
+
+    # Comm contains a ')' character inside the outer parens.  The outer
+    # parens are stripped by the kernel's stat format; we test that
+    # rfind(')') correctly finds the OUTER closing one.
+    # Format: pid (comm) state ppid pgrp session tty_nr tpgid flags
+    #         minflt cminflt majflt cmajflt utime stime cutime cstime
+    #         priority nice num_threads itrealvalue starttime ...
+    fake_stat = (
+        "12345 (weird) tail) "          # pid + comm-with-paren-and-space
+        "S 1 1 1 0 -1 4194304 "         # state ppid pgrp sess tty tpgid flags
+        "100 0 0 0 10 5 0 0 "           # minflt cminflt majflt cmajflt utime stime cutime cstime
+        "20 0 1 0 99887766 "            # priority nice nthreads itreal STARTTIME
+        "1234 5678 ...rest..."          # vsize rss ...
+    )
+
+    real_read_text = Path.read_text
+
+    def fake_read_text(self, *a, **k):
+        if str(self).startswith("/proc/12345/stat"):
+            return fake_stat
+        return real_read_text(self, *a, **k)
+
+    monkeypatch.setattr(Path, "read_text", fake_read_text)
+    assert ip._pid_proc_starttime(12345) == "99887766"
+
+
+def test_pid_proc_starttime_returns_none_on_missing_proc(monkeypatch):
+    """Non-Linux hosts or pid not running."""
+
+    def raise_oserror(self, *a, **k):
+        raise OSError("no such file")
+
+    monkeypatch.setattr(Path, "read_text", raise_oserror)
+    assert ip._pid_proc_starttime(99999) is None
+
+
+# ---------------------------------------------------------------------------
+# v3: stop_proxy SIGKILL suppression on pid recycle (P3 #5 coverage gap)
+# ---------------------------------------------------------------------------
+
+
+def test_stop_proxy_suppresses_sigkill_on_pid_recycle(hermes_home, monkeypatch):
+    """When _pid_proc_starttime returns different values before and
+    after the SIGTERM grace window, stop_proxy must NOT issue SIGKILL —
+    the original pid was recycled to an unrelated process."""
+
+    state = ip._proxy_state_dir()
+    (state / "iron-proxy.pid").write_text("12345")
+
+    # _pid_alive: always True (process at this pid keeps appearing alive)
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+
+    # Starttime changes — first call returns "AAA", second returns "BBB"
+    # (simulating PID recycle to an unrelated process during the grace).
+    starttime_responses = iter(["111", "222"])
+    monkeypatch.setattr(
+        ip, "_pid_proc_starttime",
+        lambda pid: next(starttime_responses, "222"),
+    )
+
+    # Sentinel: kill list — if SIGKILL is sent, this gets populated.
+    kills: list = []
+
+    def fake_os_kill(pid, sig):
+        kills.append((pid, sig))
+
+    monkeypatch.setattr(ip.os, "kill", fake_os_kill)
+    # Speed up the wait loop.
+    monkeypatch.setattr(ip.time, "sleep", lambda _: None)
+    # Make time advance fast.
+    orig_time = ip.time.time
+    counter = {"n": 0.0}
+
+    def fake_time():
+        counter["n"] += 1.0  # 1 second per call — past deadline immediately
+        return counter["n"]
+
+    monkeypatch.setattr(ip.time, "time", fake_time)
+
+    result = ip.stop_proxy()
+    assert result is True
+    # SIGTERM should fire, SIGKILL should NOT (recycled detection).
+    sigterm_count = sum(1 for _, s in kills if s == ip.signal.SIGTERM)
+    sigkill_count = sum(1 for _, s in kills if s == ip._KILL_SIGNAL)
+    assert sigterm_count == 1
+    assert sigkill_count == 0, f"SIGKILL was issued despite pid recycle: {kills}"
+
+
+# ---------------------------------------------------------------------------
+# v3: _reset_for_tests actually clears module state (P3 #1)
+# ---------------------------------------------------------------------------
+
+
+def test_reset_for_tests_clears_version_cache_and_nonce():
+    """_reset_for_tests must clear _VERSION_CACHE and _proxy_nonce so
+    in-process callers don't see leakage between tests."""
+
+    ip._VERSION_CACHE["dummy"] = "v0.0.0-fake"
+    ip._proxy_nonce = "fake-nonce-12345"
+    ip._reset_for_tests()
+    assert ip._VERSION_CACHE == {}
+    assert ip._proxy_nonce is None
+
+
+# ---------------------------------------------------------------------------
+# v3: version cache doesn't poison on empty stdout (P2 _VERSION_CACHE bug B)
+# ---------------------------------------------------------------------------
+
+
+def test_iron_proxy_version_does_not_cache_empty_output(monkeypatch, tmp_path):
+    """If --version returns 0 with empty stdout (corrupt binary, flag
+    rename upstream), don't poison the cache — re-probe next call."""
+
+    binary = tmp_path / "iron-proxy"
+    binary.write_text("")
+
+    # First call: returns empty output.
+    def fake_run_empty(cmd, **kw):
+        from unittest.mock import MagicMock
+        m = MagicMock()
+        m.returncode = 0
+        m.stdout = ""
+        m.stderr = ""
+        return m
+
+    ip._VERSION_CACHE.clear()
+    monkeypatch.setattr(ip.subprocess, "run", fake_run_empty)
+    assert ip.iron_proxy_version(binary) == ""
+    # Should NOT have cached the empty string.
+    assert str(binary) not in ip._VERSION_CACHE
+
+
+# ---------------------------------------------------------------------------
+# v3: NODE_OPTIONS append-merge in docker env (arshkumarsingh #1)
+# ---------------------------------------------------------------------------
+
+
+def test_docker_egress_node_options_uses_sentinel(hermes_home, monkeypatch):
+    """``_egress_proxy_args_for_docker`` should NOT put NODE_OPTIONS in
+    env_overrides directly; it uses a sentinel key
+    ``_HERMES_EGRESS_NODE_OPTIONS_APPEND`` so DockerEnvironment can
+    append-merge with the operator's existing NODE_OPTIONS."""
+
+    from tools.environments.docker import _egress_proxy_args_for_docker
+    from hermes_cli.config import load_config, save_config
+
+    state = ip._proxy_state_dir()
+    ca = state / "ca.crt"
+    ca.write_text("fake-ca")
+    (state / "ca.key").write_text("fake-key")
+    mapping = _sample_mapping("OPENROUTER_API_KEY")
+    proxy_cfg = ip.build_proxy_config(
+        mappings=[mapping], ca_cert=ca, ca_key=state / "ca.key", tunnel_port=9090,
+    )
+    ip.write_proxy_config(proxy_cfg)
+    ip.write_mappings([mapping])
+
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["enforce_on_docker"] = True
+    save_config(cfg)
+
+    (state / "iron-proxy.pid").write_text("99999")
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    monkeypatch.setattr(ip, "_port_listening", lambda h, p: True)
+
+    _, env, _ = _egress_proxy_args_for_docker()
+    # The egress dict should contain the sentinel, NOT a raw NODE_OPTIONS.
+    assert env.get("_HERMES_EGRESS_NODE_OPTIONS_APPEND") == "--use-openssl-ca"
+    assert "NODE_OPTIONS" not in env, (
+        "NODE_OPTIONS in egress env_overrides would clobber the operator's "
+        "docker_env NODE_OPTIONS — that's exactly the bug arshkumarsingh "
+        "flagged."
+    )
+
+
+# ---------------------------------------------------------------------------
+# v3: ensure_audit_log fails loud on OSError (P2 promise mismatch)
+# ---------------------------------------------------------------------------
+
+
+def test_ensure_audit_log_raises_on_immutable_parent(tmp_path, monkeypatch):
+    """When the audit log can't be created with 0o600 (planted symlink,
+    immutable dir, disk full), raise — silently logging a warning would
+    let the daemon create the file under default umask, breaking the
+    privacy promise."""
+
+    # Aim at a path whose parent doesn't exist — open() will OSError.
+    audit = tmp_path / "definitely-does-not-exist" / "audit.log"
+    with pytest.raises(RuntimeError, match="audit log"):
+        ip.ensure_audit_log(audit)
+
+
+# ---------------------------------------------------------------------------
+# v3: persisted nonce roundtrip (stephenschoettler #3 cross-CLI defense)
+# ---------------------------------------------------------------------------
+
+
+def test_persisted_nonce_roundtrip(hermes_home, monkeypatch):
+    """Write the nonce next to the pidfile (simulating one CLI invocation
+    finishing start_proxy), then verify a fresh _read_persisted_nonce
+    can pick it up — that's what cross-process _pid_alive uses."""
+
+    nonce_path = ip._persisted_nonce_path()
+    nonce_path.parent.mkdir(parents=True, exist_ok=True)
+    nonce_path.write_text("test-nonce-abc123")
+    assert ip._read_persisted_nonce() == "test-nonce-abc123"
+
+
+def test_persisted_nonce_returns_none_when_missing(hermes_home):
+    """No nonce file → None, callers fall back to argv0 basename."""
+    assert ip._read_persisted_nonce() is None
+
+
+# ---------------------------------------------------------------------------
+# v4 round (GodsBoy follow-up): bind-host-aware liveness probes +
+# allow_env_fallback on the partial-secret path
+# ---------------------------------------------------------------------------
+
+
+def test_read_http_listen_from_config_returns_host_and_port(hermes_home):
+    """_read_http_listen_from_config must surface the BIND HOST, not just
+    the port — on Linux the daemon binds the docker bridge gateway and a
+    hardcoded loopback probe would report a healthy daemon as dead."""
+
+    state = ip._proxy_state_dir()
+    (state / "proxy.yaml").write_text(
+        "proxy:\n  http_listen: 172.17.0.1:9090\n", encoding="utf-8"
+    )
+    assert ip._read_http_listen_from_config() == ("172.17.0.1", 9090)
+    assert ip._read_tunnel_port_from_config() == 9090
+
+
+def test_read_http_listen_from_config_missing_file(hermes_home):
+    assert ip._read_http_listen_from_config() is None
+
+
+def test_get_status_probes_configured_bind_host(hermes_home, monkeypatch):
+    """get_status must probe the configured bind host (e.g. the docker
+    bridge IP), not loopback unconditionally."""
+
+    state = ip._proxy_state_dir()
+    (state / "proxy.yaml").write_text(
+        "proxy:\n  http_listen: 172.17.0.1:9123\n", encoding="utf-8"
+    )
+    (state / "ca.crt").write_text("cert")
+    ip._write_pidfile_safely(ip._pidfile(), 99999)
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: True)
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kw: None)
+
+    probed = {}
+
+    def fake_probe(host, port):
+        probed["host"] = host
+        probed["port"] = port
+        return True
+
+    monkeypatch.setattr(ip, "_port_listening", fake_probe)
+    status = ip.get_status()
+    assert probed == {"host": "172.17.0.1", "port": 9123}
+    assert status.listening is True
+    assert status.tunnel_port == 9123
+
+
+def test_partial_bitwarden_secrets_honor_allow_env_fallback(
+    hermes_home, monkeypatch,
+):
+    """The missing-secret branch's own error message tells operators to
+    set proxy.allow_env_fallback — so the flag must actually work there
+    (previously only the empty-token branch honored it)."""
+
+    ip.write_mappings([_sample_mapping("OPENROUTER_API_KEY")])
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-host-fallback")
+
+    import agent.secret_sources.bitwarden as bw
+    monkeypatch.setattr(
+        bw, "fetch_bitwarden_secrets", lambda **kw: ({}, []),
+    )
+    monkeypatch.setenv("BWS_ACCESS_TOKEN", "tok")
+    bw_cfg = {
+        "project_id": "proj",
+        "access_token_env": "BWS_ACCESS_TOKEN",
+        "allow_env_fallback": True,
+    }
+
+    env = ip._build_proxy_subprocess_env(
+        refresh_from_bitwarden=True, bitwarden_config=bw_cfg,
+    )
+    # Falls back to the host env value instead of raising.
+    assert env.get("OPENROUTER_API_KEY") == "sk-host-fallback"
+
+
+def test_partial_bitwarden_secrets_raise_without_fallback(
+    hermes_home, monkeypatch,
+):
+    """Strict default: missing BWS secrets raise."""
+
+    ip.write_mappings([_sample_mapping("OPENROUTER_API_KEY")])
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-host")
+
+    import agent.secret_sources.bitwarden as bw
+    monkeypatch.setattr(
+        bw, "fetch_bitwarden_secrets", lambda **kw: ({}, []),
+    )
+    monkeypatch.setenv("BWS_ACCESS_TOKEN", "tok")
+    bw_cfg = {"project_id": "proj", "access_token_env": "BWS_ACCESS_TOKEN"}
+
+    with pytest.raises(RuntimeError, match="did not return secrets"):
+        ip._build_proxy_subprocess_env(
+            refresh_from_bitwarden=True, bitwarden_config=bw_cfg,
+        )
+
+
+def test_bitwarden_importerror_raise_without_fallback(
+    hermes_home, monkeypatch,
+):
+    """Strict default: ImportError on BWS module raises when
+    allow_env_fallback is unset, matching the sibling branches."""
+
+    ip.write_mappings([_sample_mapping("OPENROUTER_API_KEY")])
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-host")
+
+    # Simulate the BWS SDK not being installed.  The lazy import
+    # ``from agent.secret_sources import bitwarden`` inside
+    # _build_proxy_subprocess_env resolves through the parent package's
+    # cached attribute; deleting both the sys.modules entry AND the
+    # parent-package attribute forces a real import that we intercept.
+    #
+    # In addition, block importlib.reload in case the test infra used it.
+    import agent.secret_sources as ss
+    monkeypatch.delitem(sys.modules, "agent.secret_sources.bitwarden", raising=False)
+    monkeypatch.delitem(sys.modules, "agent.secret_sources.bitwarden.bws", raising=False)
+    monkeypatch.delattr(ss, "bitwarden", raising=False)
+
+    # Now block the re-import.  ``from agent.secret_sources import
+    # bitwarden`` resolves to a submodule attribute; setting it to a
+    # sentinel that raises on attribute access is more reliable than
+    # trying to intercept __import__ at the C level.
+    class _MissingBWS:
+        """Sentinel: accessing any attribute raises ImportError."""
+        def __getattr__(self, _name):
+            raise ImportError("bws SDK not installed")
+        def __call__(self, *a, **kw):
+            raise ImportError("bws SDK not installed")
+    monkeypatch.setattr(ss, "bitwarden", _MissingBWS(), raising=False)
+
+    monkeypatch.setenv("BWS_ACCESS_TOKEN", "tok")
+    bw_cfg = {"project_id": "proj", "access_token_env": "BWS_ACCESS_TOKEN"}
+
+    with pytest.raises(RuntimeError, match="Bitwarden refresh module unavailable"):
+        ip._build_proxy_subprocess_env(
+            refresh_from_bitwarden=True, bitwarden_config=bw_cfg,
+        )
+
+
+def test_bitwarden_importerror_honor_allow_env_fallback(
+    hermes_home, monkeypatch,
+):
+    """With allow_env_fallback, an ImportError falls through to host env
+    instead of raising."""
+
+    ip.write_mappings([_sample_mapping("OPENROUTER_API_KEY")])
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-host-fallback")
+
+    import agent.secret_sources as ss
+    monkeypatch.delitem(sys.modules, "agent.secret_sources.bitwarden", raising=False)
+    monkeypatch.delitem(sys.modules, "agent.secret_sources.bitwarden.bws", raising=False)
+    monkeypatch.delattr(ss, "bitwarden", raising=False)
+
+    class _MissingBWS:
+        def __getattr__(self, _name):
+            raise ImportError("bws SDK not installed")
+        def __call__(self, *a, **kw):
+            raise ImportError("bws SDK not installed")
+    monkeypatch.setattr(ss, "bitwarden", _MissingBWS(), raising=False)
+
+    monkeypatch.setenv("BWS_ACCESS_TOKEN", "tok")
+    bw_cfg = {
+        "project_id": "proj",
+        "access_token_env": "BWS_ACCESS_TOKEN",
+        "allow_env_fallback": True,
+    }
+
+    env = ip._build_proxy_subprocess_env(
+        refresh_from_bitwarden=True, bitwarden_config=bw_cfg,
+    )
+    assert env.get("OPENROUTER_API_KEY") == "sk-host-fallback"
diff --git a/tests/test_iron_proxy_cli.py b/tests/test_iron_proxy_cli.py
new file mode 100644
index 00000000000..f3a6c9ba8cc
--- /dev/null
+++ b/tests/test_iron_proxy_cli.py
@@ -0,0 +1,597 @@
+"""Unit tests for ``hermes_cli.proxy_cli`` command handlers.
+
+These tests cover the user-facing CLI surface that was previously
+uncovered.  We mock the iron_proxy module's side-effect functions
+(install / start / stop / discover) and exercise the dispatch +
+return-code logic plus the small amount of presentation logic in
+each handler (e.g. --from-bitwarden's fail-loud path).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent.proxy_sources import iron_proxy as ip
+from hermes_cli import proxy_cli
+
+
+@pytest.fixture
+def hermes_home(tmp_path, monkeypatch):
+    """Point HERMES_HOME at a temp dir so the wizard doesn't touch the
+    operator's real config.  Also blanks any provider env vars so we
+    don't accidentally read a real key."""
+
+    home = tmp_path / "hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    for key in list(os.environ):
+        if key.endswith("_API_KEY") or key in (
+            "BWS_ACCESS_TOKEN", "ANTHROPIC_API_KEY",
+            "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY",
+        ):
+            monkeypatch.delenv(key, raising=False)
+    return home
+
+
+def _args(**overrides):
+    ns = argparse.Namespace(
+        force=False,
+        tunnel_port=None,
+        from_bitwarden=False,
+        no_bitwarden=False,
+        rotate_tokens=False,
+        restart=None,
+        show_tokens=False,
+    )
+    for k, v in overrides.items():
+        setattr(ns, k, v)
+    return ns
+
+
+# ---------------------------------------------------------------------------
+# cmd_install
+# ---------------------------------------------------------------------------
+
+
+def test_cmd_install_success_returns_0(hermes_home, monkeypatch):
+    monkeypatch.setattr(ip, "install_iron_proxy", lambda **kw: hermes_home / "iron-proxy")
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "v0.39.0-test")
+    rc = proxy_cli.cmd_install(_args())
+    assert rc == 0
+
+
+def test_cmd_install_failure_returns_1(hermes_home, monkeypatch):
+    def boom(**kw):
+        raise RuntimeError("download failed")
+    monkeypatch.setattr(ip, "install_iron_proxy", boom)
+    rc = proxy_cli.cmd_install(_args())
+    assert rc == 1
+
+
+# ---------------------------------------------------------------------------
+# cmd_setup — --from-bitwarden fail-loud paths
+# ---------------------------------------------------------------------------
+
+
+def test_cmd_setup_from_bitwarden_refuses_when_bw_disabled(hermes_home, monkeypatch):
+    """When --from-bitwarden is passed but secrets.bitwarden.enabled=false,
+    the wizard must FAIL rather than silently rewriting credential_source
+    to bitwarden."""
+
+    from hermes_cli.config import load_config, save_config
+
+    cfg = load_config()
+    cfg.setdefault("secrets", {})["bitwarden"] = {"enabled": False}
+    save_config(cfg)
+
+    # Pre-stub install + CA so we get to step 3.
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kw: hermes_home / "iron-proxy")
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "test")
+    monkeypatch.setattr(
+        ip, "ensure_ca_cert",
+        lambda **kw: (hermes_home / "ca.crt", hermes_home / "ca.key"),
+    )
+
+    rc = proxy_cli.cmd_setup(_args(from_bitwarden=True))
+    assert rc == 1
+    # Verify we did NOT write credential_source: bitwarden to config.
+    cfg2 = load_config()
+    proxy_cfg = cfg2.get("proxy") or {}
+    assert proxy_cfg.get("credential_source", "env") != "bitwarden"
+
+
+def test_cmd_setup_from_bitwarden_refuses_when_token_missing(hermes_home, monkeypatch):
+    """--from-bitwarden with secrets.bitwarden.enabled=true but BWS access
+    token unset → fail loud, not silent env-fallback."""
+
+    from hermes_cli.config import load_config, save_config
+
+    cfg = load_config()
+    cfg.setdefault("secrets", {})["bitwarden"] = {
+        "enabled": True,
+        "project_id": "test-proj",
+        "access_token_env": "BWS_ACCESS_TOKEN",
+    }
+    save_config(cfg)
+    monkeypatch.delenv("BWS_ACCESS_TOKEN", raising=False)
+
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kw: hermes_home / "iron-proxy")
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "test")
+    monkeypatch.setattr(
+        ip, "ensure_ca_cert",
+        lambda **kw: (hermes_home / "ca.crt", hermes_home / "ca.key"),
+    )
+
+    rc = proxy_cli.cmd_setup(_args(from_bitwarden=True))
+    assert rc == 1
+
+
+def test_cmd_setup_from_bitwarden_refuses_on_empty_vault(hermes_home, monkeypatch):
+    """If BW returns {} (empty vault / scoped wrong / unreachable), fail
+    loud rather than silently writing credential_source: bitwarden."""
+
+    from hermes_cli.config import load_config, save_config
+
+    cfg = load_config()
+    cfg.setdefault("secrets", {})["bitwarden"] = {
+        "enabled": True,
+        "project_id": "test-proj",
+        "access_token_env": "BWS_ACCESS_TOKEN",
+    }
+    save_config(cfg)
+    monkeypatch.setenv("BWS_ACCESS_TOKEN", "bwsk-test-token")
+
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kw: hermes_home / "iron-proxy")
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "test")
+    monkeypatch.setattr(
+        ip, "ensure_ca_cert",
+        lambda **kw: (hermes_home / "ca.crt", hermes_home / "ca.key"),
+    )
+
+    # Mock fetch_bitwarden_secrets to return an empty dict (empty vault).
+    fake_bw = MagicMock()
+    fake_bw.fetch_bitwarden_secrets = lambda **kw: ({}, [])
+    monkeypatch.setattr("agent.secret_sources.bitwarden", fake_bw, raising=False)
+    import sys
+    sys.modules["agent.secret_sources.bitwarden"] = fake_bw
+
+    rc = proxy_cli.cmd_setup(_args(from_bitwarden=True))
+    assert rc == 1
+
+
+def test_cmd_setup_rejects_tunnel_port_zero(hermes_home, monkeypatch):
+    """--tunnel-port=0 is rejected explicitly (was silently substituting
+    the default before the fix)."""
+
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-test")
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kw: hermes_home / "iron-proxy")
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "test")
+    monkeypatch.setattr(
+        ip, "ensure_ca_cert",
+        lambda **kw: (hermes_home / "ca.crt", hermes_home / "ca.key"),
+    )
+    rc = proxy_cli.cmd_setup(_args(tunnel_port=0))
+    assert rc == 1
+
+
+@pytest.mark.parametrize("bad_port", [-1, 65535, 65536])
+def test_cmd_setup_rejects_invalid_tunnel_port_range(hermes_home, monkeypatch, bad_port):
+    """The egress wizard owns the derived HTTP listener at tunnel_port+1,
+    so both listener ports must fit in the TCP range."""
+
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-test")
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kw: hermes_home / "iron-proxy")
+    monkeypatch.setattr(ip, "iron_proxy_version", lambda b: "test")
+    monkeypatch.setattr(
+        ip,
+        "ensure_ca_cert",
+        lambda **kw: (hermes_home / "ca.crt", hermes_home / "ca.key"),
+    )
+
+    rc = proxy_cli.cmd_setup(_args(tunnel_port=bad_port))
+    assert rc == 1
+
+
+# ---------------------------------------------------------------------------
+# ---------------------------------------------------------------------------
+
+
+def test_cmd_start_refuses_when_proxy_disabled(hermes_home, monkeypatch):
+    from hermes_cli.config import load_config, save_config
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = False
+    save_config(cfg)
+
+    rc = proxy_cli.cmd_start(_args())
+    assert rc == 1
+
+
+def test_cmd_start_honors_auto_install_false(hermes_home, monkeypatch):
+    from hermes_cli.config import load_config, save_config
+
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["auto_install"] = False
+    save_config(cfg)
+
+    captured: dict = {}
+
+    def fake_start_proxy(**kw):
+        captured.update(kw)
+        s = ip.ProxyStatus(pid=4242, listening=True, tunnel_port=9090)
+        return s
+
+    monkeypatch.setattr(ip, "start_proxy", fake_start_proxy)
+    monkeypatch.setattr(ip, "discover_uncovered_providers", lambda **kw: [])
+
+    rc = proxy_cli.cmd_start(_args())
+    assert rc == 0
+    assert captured.get("install_if_missing") is False
+
+
+def test_cmd_start_passes_bitwarden_refresh_flag_when_credential_source_is_bitwarden(
+    hermes_home, monkeypatch,
+):
+    """When credential_source=bitwarden, cmd_start must wire
+    refresh_secrets_from_bitwarden=True into start_proxy.  That's what
+    delivers the rotation promise the docs make."""
+
+    from hermes_cli.config import load_config, save_config
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["credential_source"] = "bitwarden"
+    cfg.setdefault("secrets", {})["bitwarden"] = {
+        "enabled": True,
+        "project_id": "test-proj-id",
+        "access_token_env": "BWS_ACCESS_TOKEN",
+    }
+    save_config(cfg)
+    # v3: cmd_start now pre-checks BWS access token + project_id before
+    # calling start_proxy.  Provide both so we get to the rotation
+    # wire-up code path.
+    monkeypatch.setenv("BWS_ACCESS_TOKEN", "bwsk-test-access-token")
+
+    captured: dict = {}
+    def fake_start_proxy(**kw):
+        captured.update(kw)
+        s = ip.ProxyStatus()
+        s.pid = 4242
+        s.listening = True
+        s.tunnel_port = 9090
+        return s
+    monkeypatch.setattr(ip, "start_proxy", fake_start_proxy)
+    monkeypatch.setattr(ip, "discover_uncovered_providers", lambda **kw: [])
+
+    rc = proxy_cli.cmd_start(_args())
+    assert rc == 0
+    assert captured.get("refresh_secrets_from_bitwarden") is True
+    assert captured.get("bitwarden_config") is not None
+
+
+def test_cmd_start_refuses_when_bitwarden_token_missing(hermes_home, monkeypatch):
+    """stephenschoettler #1: when credential_source=bitwarden but the
+    access-token env var is empty, cmd_start must fail-loud BEFORE
+    start_proxy can silently fall back to parent env."""
+
+    from hermes_cli.config import load_config, save_config
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["credential_source"] = "bitwarden"
+    cfg.setdefault("secrets", {})["bitwarden"] = {
+        "enabled": True,
+        "project_id": "test-proj-id",
+        "access_token_env": "BWS_ACCESS_TOKEN",
+    }
+    save_config(cfg)
+    monkeypatch.delenv("BWS_ACCESS_TOKEN", raising=False)
+
+    # Sentinel: start_proxy must NOT be called.
+    def must_not_call(**kw):
+        pytest.fail("start_proxy should not be invoked when BWS token missing")
+    monkeypatch.setattr(ip, "start_proxy", must_not_call)
+    monkeypatch.setattr(ip, "discover_uncovered_providers", lambda **kw: [])
+
+    rc = proxy_cli.cmd_start(_args())
+    assert rc == 1
+
+
+def test_cmd_start_does_not_pass_bitwarden_refresh_when_credential_source_is_env(
+    hermes_home, monkeypatch,
+):
+    from hermes_cli.config import load_config, save_config
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["credential_source"] = "env"
+    save_config(cfg)
+
+    captured: dict = {}
+    def fake_start_proxy(**kw):
+        captured.update(kw)
+        s = ip.ProxyStatus()
+        s.pid = 4242
+        s.listening = True
+        return s
+    monkeypatch.setattr(ip, "start_proxy", fake_start_proxy)
+    monkeypatch.setattr(ip, "discover_uncovered_providers", lambda **kw: [])
+
+    rc = proxy_cli.cmd_start(_args())
+    assert rc == 0
+    assert captured.get("refresh_secrets_from_bitwarden") is False
+
+
+# ---------------------------------------------------------------------------
+# cmd_stop, cmd_status, cmd_disable, cmd_config
+# ---------------------------------------------------------------------------
+
+
+def test_cmd_stop_returns_0_when_running(hermes_home, monkeypatch):
+    monkeypatch.setattr(ip, "stop_proxy", lambda: True)
+    rc = proxy_cli.cmd_stop(_args())
+    assert rc == 0
+
+
+def test_cmd_stop_returns_0_when_already_stopped(hermes_home, monkeypatch):
+    monkeypatch.setattr(ip, "stop_proxy", lambda: False)
+    rc = proxy_cli.cmd_stop(_args())
+    assert rc == 0
+
+
+# ---------------------------------------------------------------------------
+# cmd_restart
+# ---------------------------------------------------------------------------
+
+
+def test_cmd_restart_stops_then_starts(hermes_home, monkeypatch):
+    calls = []
+    monkeypatch.setattr(ip, "stop_proxy", lambda: (calls.append("stop"), True)[1])
+    monkeypatch.setattr(
+        proxy_cli, "cmd_start",
+        lambda args: (calls.append("start"), 0)[1],
+    )
+    rc = proxy_cli.cmd_restart(_args())
+    assert rc == 0
+    # stop must precede start, and both must run
+    assert calls == ["stop", "start"]
+
+
+def test_cmd_restart_starts_even_when_not_previously_running(hermes_home, monkeypatch):
+    calls = []
+    monkeypatch.setattr(ip, "stop_proxy", lambda: (calls.append("stop"), False)[1])
+    monkeypatch.setattr(
+        proxy_cli, "cmd_start",
+        lambda args: (calls.append("start"), 0)[1],
+    )
+    rc = proxy_cli.cmd_restart(_args())
+    assert rc == 0
+    assert calls == ["stop", "start"]
+
+
+def test_cmd_restart_propagates_start_failure(hermes_home, monkeypatch):
+    monkeypatch.setattr(ip, "stop_proxy", lambda: True)
+    monkeypatch.setattr(proxy_cli, "cmd_start", lambda args: 1)
+    rc = proxy_cli.cmd_restart(_args())
+    assert rc == 1
+
+
+# ---------------------------------------------------------------------------
+# _load_env_file_into_environ — setup discovers keys kept only in ~/.hermes/.env
+# ---------------------------------------------------------------------------
+
+
+def test_load_env_file_backfills_provider_keys(hermes_home, monkeypatch):
+    # Key present in .env but NOT exported in the process env.
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    monkeypatch.setattr(
+        "hermes_cli.config.load_env",
+        lambda: {"OPENROUTER_API_KEY": "sk-or-from-dotenv", "UNRELATED": "x"},
+    )
+    added = proxy_cli._load_env_file_into_environ()
+    assert added >= 1
+    assert os.environ.get("OPENROUTER_API_KEY") == "sk-or-from-dotenv"
+    # Only known provider names are backfilled, not arbitrary secrets.
+    assert "UNRELATED" not in os.environ
+
+
+def test_load_env_file_does_not_override_exported_value(hermes_home, monkeypatch):
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-exported-wins")
+    monkeypatch.setattr(
+        "hermes_cli.config.load_env",
+        lambda: {"OPENROUTER_API_KEY": "sk-or-from-dotenv"},
+    )
+    proxy_cli._load_env_file_into_environ()
+    # An exported value always wins over the .env file.
+    assert os.environ["OPENROUTER_API_KEY"] == "sk-or-exported-wins"
+
+
+def test_cmd_status_returns_0(hermes_home, monkeypatch):
+    monkeypatch.setattr(ip, "get_status", lambda: ip.ProxyStatus())
+    monkeypatch.setattr(ip, "load_mappings", lambda: [])
+    monkeypatch.setattr(ip, "discover_uncovered_providers", lambda **kw: [])
+    rc = proxy_cli.cmd_status(_args())
+    assert rc == 0
+
+
+def test_cmd_disable_uses_public_status_pid_not_private_read_pid(
+    hermes_home, monkeypatch,
+):
+    """cmd_disable must read status.pid (which incorporates the _pid_alive
+    check) — NOT ip._read_pid() directly (which would fire a spurious
+    'still running' warning for a stale pidfile from a crashed run)."""
+
+    from hermes_cli.config import load_config, save_config
+
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    save_config(cfg)
+
+    # Pidfile exists but the process is dead.  Old code would have warned
+    # "still running"; the new code reads status.pid which returns None
+    # because _pid_alive is False, so no spurious warning.
+    state = ip._proxy_state_dir()
+    (state / "iron-proxy.pid").write_text("99999")
+    # _pid_alive returns False → status.pid is None.
+    monkeypatch.setattr(ip, "_pid_alive", lambda pid: False)
+
+    # If cmd_disable reads _read_pid() directly (old path), this test
+    # would still pass — but reading status.pid is the correct
+    # API.  Sentinel: confirm _read_pid is NOT called from cmd_disable.
+    read_pid_calls = []
+    real_read_pid = ip._read_pid
+    def tracked_read_pid(*a, **kw):
+        read_pid_calls.append((a, kw))
+        return real_read_pid(*a, **kw)
+    monkeypatch.setattr(ip, "_read_pid", tracked_read_pid)
+
+    rc = proxy_cli.cmd_disable(_args())
+    assert rc == 0
+    # cmd_disable should call get_status() (which may internally call
+    # _read_pid), but should NOT call _read_pid from its own body.
+    # Hard to assert directly without source-introspection — the meatier
+    # assertion is that no "still running" message fired with a stale
+    # pidfile.  That's covered by inspecting return code + config
+    # mutation only.
+    from hermes_cli.config import load_config as _lc
+    cfg2 = _lc()
+    assert cfg2["proxy"]["enabled"] is False
+
+
+def test_cmd_config_returns_0_when_present(hermes_home, monkeypatch):
+    fake = ip.ProxyStatus()
+    fake.config_path = hermes_home / "proxy.yaml"
+    monkeypatch.setattr(ip, "get_status", lambda: fake)
+    rc = proxy_cli.cmd_config(_args())
+    assert rc == 0
+
+
+def test_cmd_config_returns_1_when_missing(hermes_home, monkeypatch):
+    monkeypatch.setattr(ip, "get_status", lambda: ip.ProxyStatus())
+    rc = proxy_cli.cmd_config(_args())
+    assert rc == 1
+
+
+# ---------------------------------------------------------------------------
+# Argparse wiring — dest='egress_command' regression
+# ---------------------------------------------------------------------------
+
+
+def test_register_cli_uses_egress_command_dest():
+    """The subparser dest must be 'egress_command' to stay disjoint from
+    the inbound OAuth 'hermes proxy' subparser (dest='proxy_command').
+    A future grep-and-refactor on proxy_command should not hit this
+    subparser by accident."""
+
+    parser = argparse.ArgumentParser(prog="hermes egress")
+    proxy_cli.register_cli(parser)
+    # Parse a no-op invocation and confirm the attribute name.
+    args = parser.parse_args(["install"])
+    assert hasattr(args, "egress_command")
+    assert not hasattr(args, "proxy_command")
+
+
+def test_egress_subcommands_registered():
+    """Smoke test: every documented subcommand parses without error."""
+
+    parser = argparse.ArgumentParser(prog="hermes egress")
+    proxy_cli.register_cli(parser)
+    for sub in ("install", "setup", "start", "stop", "status", "disable", "config"):
+        args = parser.parse_args([sub])
+        assert args.egress_command == sub
+
+
+def test_setup_has_rotate_tokens_flag():
+    """--rotate-tokens is the documented escape hatch for re-rolling
+    every proxy token (used after a suspected token leak).  Default is
+    preserve-existing."""
+
+    parser = argparse.ArgumentParser(prog="hermes egress")
+    proxy_cli.register_cli(parser)
+    args = parser.parse_args(["setup"])
+    assert args.rotate_tokens is False
+    args = parser.parse_args(["setup", "--rotate-tokens"])
+    assert args.rotate_tokens is True
+
+
+# ---------------------------------------------------------------------------
+# v4 round: credential_source=bitwarden with secrets.bitwarden disabled
+# must NOT silently degrade to host-env secrets
+# ---------------------------------------------------------------------------
+
+
+def test_cmd_start_refuses_when_bitwarden_mode_but_disabled(hermes_home, monkeypatch):
+    """config keeps credential_source: bitwarden but secrets.bitwarden.enabled
+    later flips to false — cmd_start must refuse, not silently start on
+    host env (the silent-degrade class strict mode is meant to close)."""
+
+    from hermes_cli.config import load_config, save_config
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["credential_source"] = "bitwarden"
+    cfg.setdefault("secrets", {})["bitwarden"] = {"enabled": False}
+    save_config(cfg)
+
+    def must_not_call(**kw):
+        pytest.fail("start_proxy must not run when bitwarden mode is broken")
+    monkeypatch.setattr(ip, "start_proxy", must_not_call)
+    monkeypatch.setattr(ip, "discover_uncovered_providers", lambda **kw: [])
+
+    rc = proxy_cli.cmd_start(_args())
+    assert rc == 1
+
+
+def test_cmd_start_bitwarden_disabled_proceeds_with_env_fallback(
+    hermes_home, monkeypatch,
+):
+    """Same scenario but proxy.allow_env_fallback=true is the documented
+    escape hatch — start proceeds (with a warning)."""
+
+    from hermes_cli.config import load_config, save_config
+    cfg = load_config()
+    cfg.setdefault("proxy", {})["enabled"] = True
+    cfg["proxy"]["credential_source"] = "bitwarden"
+    cfg["proxy"]["allow_env_fallback"] = True
+    cfg.setdefault("secrets", {})["bitwarden"] = {"enabled": False}
+    save_config(cfg)
+
+    captured: dict = {}
+
+    def fake_start_proxy(**kw):
+        captured.update(kw)
+        s = ip.ProxyStatus()
+        s.pid = 4242
+        s.listening = True
+        return s
+
+    monkeypatch.setattr(ip, "start_proxy", fake_start_proxy)
+    monkeypatch.setattr(ip, "discover_uncovered_providers", lambda **kw: [])
+
+    rc = proxy_cli.cmd_start(_args())
+    assert rc == 0
+    # BW refresh is off (bitwarden disabled), running on env secrets.
+    assert captured.get("refresh_secrets_from_bitwarden") is False
+
+
+def test_cmd_setup_audit_log_failure_is_warning_not_abort(hermes_home, monkeypatch):
+    """On the pinned v0.39 the daemon never writes audit.log, so a
+    pre-create failure must not abort the wizard."""
+
+    monkeypatch.setattr(ip, "find_iron_proxy", lambda **kw: hermes_home / "iron-proxy")
+    monkeypatch.setattr(ip, "discover_provider_mappings", lambda **kw: [
+        ip.TokenMapping(
+            proxy_token="hermes-proxy-deadbeef",
+            real_env_name="OPENROUTER_API_KEY",
+            upstream_hosts=("openrouter.ai",),
+        ),
+    ])
+    monkeypatch.setattr(ip, "discover_uncovered_providers", lambda **kw: [])
+
+    def boom(path):
+        raise RuntimeError("could not pre-create audit log (synthetic)")
+    monkeypatch.setattr(ip, "ensure_audit_log", boom)
+
+    rc = proxy_cli.cmd_setup(_args())
+    assert rc == 0
diff --git a/tests/test_iron_proxy_e2e.py b/tests/test_iron_proxy_e2e.py
new file mode 100644
index 00000000000..37c3936c0da
--- /dev/null
+++ b/tests/test_iron_proxy_e2e.py
@@ -0,0 +1,368 @@
+"""End-to-end smoke test for the iron-proxy egress integration.
+
+Spins up the REAL iron-proxy binary (auto-installed if not present), routes
+a curl request through it against a local fake upstream, and verifies that
+the Authorization header was swapped from a proxy token to a real secret.
+
+Gated on the network. Skipped by default in CI unless the user explicitly
+opts in with --run-e2e or HERMES_RUN_E2E=1.  This is intentional — the test
+downloads ~16MB and requires both `openssl` and `curl` to be present.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Optional
+
+import pytest
+
+from agent.proxy_sources import iron_proxy as ip
+
+
+pytestmark = pytest.mark.skipif(
+    os.environ.get("HERMES_RUN_E2E", "0") != "1",
+    reason="E2E proxy test — set HERMES_RUN_E2E=1 to run (requires network + curl + openssl)",
+)
+
+
+@pytest.fixture
+def hermes_home(tmp_path, monkeypatch):
+    home = tmp_path / "hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    return home
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class _CaptureHandler(BaseHTTPRequestHandler):
+    """Records the Authorization header of every incoming request."""
+
+    captured_auth: Optional[str] = None  # class-level so tests can read it
+
+    def do_GET(self):
+        type(self).captured_auth = self.headers.get("Authorization")
+        body = b'{"ok": true}'
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *args, **kwargs):
+        return  # silence access log
+
+
+def test_iron_proxy_swaps_authorization_header_end_to_end(hermes_home, monkeypatch):
+    """Real binary, real CA, real curl. Verify the proxy swaps a proxy-token
+    Authorization header for the real bearer value before forwarding."""
+
+    if not __import__("shutil").which("curl"):
+        pytest.skip("curl not available")
+    if not __import__("shutil").which("openssl"):
+        pytest.skip("openssl not available")
+
+    # ----- fake upstream ----------------------------------------------------
+    upstream_port = _free_port()
+    server = HTTPServer(("127.0.0.1", upstream_port), _CaptureHandler)
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    try:
+        # ----- iron-proxy install + CA + config ---------------------------
+        binary = ip.install_iron_proxy()
+        assert binary.exists()
+        ca_crt, ca_key = ip.ensure_ca_cert()
+        assert ca_crt.exists()
+
+        real_secret = "sk-real-upstream-value-deadbeef"
+        monkeypatch.setenv("TEST_UPSTREAM_KEY", real_secret)
+        proxy_token = ip.mint_proxy_token("test")
+
+        mapping = ip.TokenMapping(
+            proxy_token=proxy_token,
+            real_env_name="TEST_UPSTREAM_KEY",
+            upstream_hosts=("127.0.0.1",),
+        )
+
+        tunnel_port = _free_port()
+        cfg = ip.build_proxy_config(
+            mappings=[mapping],
+            ca_cert=ca_crt,
+            ca_key=ca_key,
+            tunnel_port=tunnel_port,
+            allowed_hosts=["127.0.0.1"],
+            # Test target is on loopback — clear the default IMDS+loopback
+            # deny list so iron-proxy will dial 127.0.0.1.
+            upstream_deny_cidrs=[],
+            # Hermetic: pin the bind to loopback.  Without this, Linux
+            # hosts with docker0 present would bind the bridge gateway
+            # (the production default) and the loopback curl below would
+            # never reach the proxy.
+            http_listen=[f"127.0.0.1:{tunnel_port}"],
+        )
+        ip.write_proxy_config(cfg)
+        ip.write_mappings([mapping])
+
+        # ----- start the proxy --------------------------------------------
+        try:
+            status = ip.start_proxy()
+        except RuntimeError as exc:
+            pytest.skip(f"iron-proxy could not start in this environment: {exc}")
+        assert status.pid is not None
+
+        # Wait up to 10s for the listener to come up.
+        for _ in range(50):
+            if ip._port_listening("127.0.0.1", tunnel_port):
+                break
+            time.sleep(0.2)
+        else:
+            pytest.fail("iron-proxy never started listening on the tunnel port")
+
+        # ----- request through the proxy ----------------------------------
+        # The fake upstream listens on plain HTTP (not HTTPS).  Plain-HTTP
+        # absolute-form forwards are served by the http_listen listener on
+        # tunnel_port + 1 (tunnel_port itself is the CONNECT/MITM listener
+        # that HTTPS_PROXY traffic hits).  The secrets transform fires on
+        # the plain forward too, swapping the Authorization header.
+        result = subprocess.run(
+            [
+                "curl",
+                "--silent",
+                "--max-time", "10",
+                "-x", f"http://127.0.0.1:{tunnel_port + 1}",
+                "-H", f"Authorization: Bearer {proxy_token}",
+                f"http://127.0.0.1:{upstream_port}/",
+            ],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0, f"curl failed: {result.stderr}"
+        # Some iron-proxy versions return 200 with no body; only the swap matters.
+        captured = _CaptureHandler.captured_auth
+        assert captured is not None, "upstream never received the request"
+        assert real_secret in captured, (
+            f"Authorization header was not swapped — upstream saw: {captured!r}"
+        )
+        assert proxy_token not in captured, (
+            f"Proxy token leaked through to upstream: {captured!r}"
+        )
+
+    finally:
+        # ----- cleanup ------------------------------------------------------
+        try:
+            ip.stop_proxy()
+        except Exception:
+            pass
+        server.shutdown()
+        server.server_close()
+
+
+class _CaptureXApiKeyHandler(BaseHTTPRequestHandler):
+    """Records the x-api-key header of every incoming request."""
+
+    captured_key: Optional[str] = None
+
+    def do_GET(self):
+        type(self).captured_key = self.headers.get("x-api-key")
+        body = b'{"ok": true}'
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *args, **kwargs):
+        return
+
+
+def test_iron_proxy_swaps_x_api_key_header_end_to_end(hermes_home, monkeypatch):
+    """Header-auth providers: the secrets transform must swap the proxy
+    token out of a NON-Authorization header (x-api-key — the Anthropic
+    native scheme) on the pinned binary."""
+
+    if not __import__("shutil").which("curl"):
+        pytest.skip("curl not available")
+    if not __import__("shutil").which("openssl"):
+        pytest.skip("openssl not available")
+
+    upstream_port = _free_port()
+    server = HTTPServer(("127.0.0.1", upstream_port), _CaptureXApiKeyHandler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+
+    try:
+        binary = ip.install_iron_proxy()
+        assert binary.exists()
+        ca_crt, ca_key = ip.ensure_ca_cert()
+
+        real_secret = "sk-ant-real-value-cafebabe"
+        monkeypatch.setenv("TEST_XAPI_KEY", real_secret)
+        proxy_token = ip.mint_proxy_token("anthropic")
+
+        mapping = ip.TokenMapping(
+            proxy_token=proxy_token,
+            real_env_name="TEST_XAPI_KEY",
+            upstream_hosts=("127.0.0.1",),
+            match_headers=("x-api-key", "Authorization"),
+        )
+
+        tunnel_port = _free_port()
+        cfg = ip.build_proxy_config(
+            mappings=[mapping],
+            ca_cert=ca_crt,
+            ca_key=ca_key,
+            tunnel_port=tunnel_port,
+            allowed_hosts=["127.0.0.1"],
+            upstream_deny_cidrs=[],
+            http_listen=[f"127.0.0.1:{tunnel_port}"],
+        )
+        ip.write_proxy_config(cfg)
+        ip.write_mappings([mapping])
+
+        try:
+            status = ip.start_proxy()
+        except RuntimeError as exc:
+            pytest.skip(f"iron-proxy could not start in this environment: {exc}")
+        assert status.pid is not None
+
+        for _ in range(50):
+            if ip._port_listening("127.0.0.1", tunnel_port):
+                break
+            time.sleep(0.2)
+        else:
+            pytest.fail("iron-proxy never started listening on the tunnel port")
+
+        result = subprocess.run(
+            [
+                "curl",
+                "--silent",
+                "--max-time", "10",
+                "-x", f"http://127.0.0.1:{tunnel_port + 1}",
+                "-H", f"x-api-key: {proxy_token}",
+                f"http://127.0.0.1:{upstream_port}/",
+            ],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0, f"curl failed: {result.stderr}"
+        captured = _CaptureXApiKeyHandler.captured_key
+        assert captured is not None, "upstream never received the request"
+        assert real_secret in captured, (
+            f"x-api-key header was not swapped — upstream saw: {captured!r}"
+        )
+        assert proxy_token not in captured, (
+            f"Proxy token leaked through to upstream: {captured!r}"
+        )
+
+    finally:
+        try:
+            ip.stop_proxy()
+        except Exception:
+            pass
+        server.shutdown()
+        server.server_close()
+
+
+def test_iron_proxy_management_reload_end_to_end(hermes_home, monkeypatch):
+    """Real binary: the management listener comes up, an authenticated
+    POST /v1/reload succeeds after a config edit, and the edited ruleset
+    takes effect WITHOUT a restart (same pid)."""
+
+    if not __import__("shutil").which("curl"):
+        pytest.skip("curl not available")
+    if not __import__("shutil").which("openssl"):
+        pytest.skip("openssl not available")
+
+    upstream_port = _free_port()
+    server = HTTPServer(("127.0.0.1", upstream_port), _CaptureHandler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+
+    try:
+        binary = ip.install_iron_proxy()
+        assert binary.exists()
+        ca_crt, ca_key = ip.ensure_ca_cert()
+
+        real_secret = "sk-real-reload-value-0badf00d"
+        monkeypatch.setenv("TEST_RELOAD_KEY", real_secret)
+        token_v1 = ip.mint_proxy_token("v1")
+
+        def _write_cfg(mapping):
+            cfg = ip.build_proxy_config(
+                mappings=[mapping],
+                ca_cert=ca_crt,
+                ca_key=ca_key,
+                tunnel_port=tunnel_port,
+                allowed_hosts=["127.0.0.1"],
+                upstream_deny_cidrs=[],
+                http_listen=[f"127.0.0.1:{tunnel_port}"],
+            )
+            ip.write_proxy_config(cfg)
+            ip.write_mappings([mapping])
+
+        tunnel_port = _free_port()
+        _write_cfg(ip.TokenMapping(
+            proxy_token=token_v1,
+            real_env_name="TEST_RELOAD_KEY",
+            upstream_hosts=("127.0.0.1",),
+        ))
+
+        try:
+            status = ip.start_proxy()
+        except RuntimeError as exc:
+            pytest.skip(f"iron-proxy could not start in this environment: {exc}")
+        pid_before = status.pid
+        assert pid_before is not None
+
+        for _ in range(50):
+            if ip._port_listening("127.0.0.1", tunnel_port):
+                break
+            time.sleep(0.2)
+        else:
+            pytest.fail("iron-proxy never started listening")
+
+        # Rotate the sandbox-visible token in the config, then hot-reload.
+        token_v2 = ip.mint_proxy_token("v2")
+        _write_cfg(ip.TokenMapping(
+            proxy_token=token_v2,
+            real_env_name="TEST_RELOAD_KEY",
+            upstream_hosts=("127.0.0.1",),
+        ))
+        assert ip.reload_proxy() is True
+
+        # Same daemon (no restart) ...
+        assert ip.get_status().pid == pid_before
+
+        # ... but the NEW token now swaps.
+        _CaptureHandler.captured_auth = None
+        result = subprocess.run(
+            [
+                "curl", "--silent", "--max-time", "10",
+                "-x", f"http://127.0.0.1:{tunnel_port + 1}",
+                "-H", f"Authorization: Bearer {token_v2}",
+                f"http://127.0.0.1:{upstream_port}/",
+            ],
+            capture_output=True, text=True,
+        )
+        assert result.returncode == 0, f"curl failed: {result.stderr}"
+        captured = _CaptureHandler.captured_auth
+        assert captured is not None and real_secret in captured, (
+            f"post-reload token was not swapped — upstream saw: {captured!r}"
+        )
+
+    finally:
+        try:
+            ip.stop_proxy()
+        except Exception:
+            pass
+        server.shutdown()
+        server.server_close()
diff --git a/tests/test_lazy_session_regressions.py b/tests/test_lazy_session_regressions.py
index 1e5a75206e1..ec684254c62 100644
--- a/tests/test_lazy_session_regressions.py
+++ b/tests/test_lazy_session_regressions.py
@@ -140,7 +140,7 @@ class TestSyncSessionKeyAfterAutoCompress:
                 self.session_id = "pre-compress-key"
                 self._cached_system_prompt = ""
 
-            def run_conversation(self, prompt, conversation_history=None, stream_callback=None):
+            def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
                 # Simulate what _compress_context does: rotate session_id
                 self.session_id = "post-compress-key"
                 return {
diff --git a/tests/test_run_tests_parallel.py b/tests/test_run_tests_parallel.py
index db5436f6f1e..846c6719ca4 100644
--- a/tests/test_run_tests_parallel.py
+++ b/tests/test_run_tests_parallel.py
@@ -359,3 +359,75 @@ def test_file_retry_does_not_launder_deterministic_failure(tmp_path: Path) -> No
     assert proc.returncode == 1, proc.stdout
     assert "deterministic regression" in proc.stdout
     assert "FLAKY file" not in proc.stdout
+
+
+# ---------------------------------------------------------------------------
+# Zero-collection is not a pass; node ids are translated, not dropped.
+#
+# Both behaviors were real foot-guns: a run where NOTHING was collected printed
+# "0 tests passed, 0 failed (100% complete)" (reads green), and a pytest node id
+# (`file.py::Class::test`) was silently discarded by path discovery so the run
+# ended with "No test files to run" while looking like an accepted selector.
+
+
+def test_zero_collected_across_run_fails_and_says_so(tmp_path: Path) -> None:
+    """A -k that matches nothing must FAIL, not report a green summary."""
+    probe_dir = _make_probe_dir(tmp_path)
+    proc = _run_runner(probe_dir, "-k", "zzz_matches_nothing")
+    assert proc.returncode == 1, proc.stdout
+    assert "NO TESTS RAN" in proc.stdout
+    assert "NOT a pass" in proc.stdout
+
+
+def test_all_skipped_file_is_still_a_pass(tmp_path: Path) -> None:
+    """Per-file zero-collection stays tolerated.
+
+    A platform-gated file (every test skipped) reports "N skipped" — collected,
+    just not executed — and must NOT trip the nothing-ran guard.
+    """
+    probe_dir = tmp_path / "skipprobe"
+    probe_dir.mkdir()
+    (probe_dir / "test_allskipped.py").write_text(
+        "import pytest\n\n"
+        "pytestmark = pytest.mark.skip(reason='platform-gated')\n\n"
+        "def test_one():\n    assert True\n\n"
+        "def test_two():\n    assert True\n"
+    )
+    proc = _run_runner(probe_dir)
+    assert proc.returncode == 0, proc.stdout
+    assert "NO TESTS RAN" not in proc.stdout
+
+
+def test_node_id_selector_runs_the_named_test(tmp_path: Path) -> None:
+    """``file.py::test_alpha`` runs that test instead of discovering nothing."""
+    probe_dir = _make_probe_dir(tmp_path)
+    target = probe_dir / "test_flagprobe.py"
+    repo_root = Path(__file__).resolve().parent.parent
+    proc = subprocess.run(
+        [sys.executable, str(repo_root / "scripts" / "run_tests_parallel.py"),
+         f"{target}::test_alpha", "-j", "1", "--file-timeout", "30"],
+        cwd=repo_root, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+        text=True, timeout=60,
+    )
+    assert proc.returncode == 0, proc.stdout
+    assert "No test files to run" not in proc.stdout
+    assert "node id" in proc.stdout  # explains the translation
+    # Ran exactly the one selected test, not both in the file.
+    assert "1 tests passed" in proc.stdout
+
+
+def test_explicit_k_wins_over_node_id_inference(tmp_path: Path) -> None:
+    """A caller's own ``-k`` is not overridden by the node-id translation."""
+    probe_dir = _make_probe_dir(tmp_path)
+    target = probe_dir / "test_flagprobe.py"
+    repo_root = Path(__file__).resolve().parent.parent
+    proc = subprocess.run(
+        [sys.executable, str(repo_root / "scripts" / "run_tests_parallel.py"),
+         f"{target}::test_alpha", "-k", "test_beta",
+         "-j", "1", "--file-timeout", "30"],
+        cwd=repo_root, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+        text=True, timeout=60,
+    )
+    # -k test_beta wins: one test ran, and it wasn't filtered to nothing.
+    assert proc.returncode == 0, proc.stdout
+    assert "1 tests passed" in proc.stdout
diff --git a/tests/test_session_skill_previews.py b/tests/test_session_skill_previews.py
new file mode 100644
index 00000000000..04f39329562
--- /dev/null
+++ b/tests/test_session_skill_previews.py
@@ -0,0 +1,162 @@
+"""Session previews must never surface a /skill's own body.
+
+`preview` is the head of the first user message, and it is the TITLE FALLBACK on
+every surface (sidebar rows, pickers, exports, desktop `sessionTitle`). A /skill
+invocation expands into a message that embeds the whole skill body, so an
+untitled skill session used to read `[IMPORTANT: The user has invoked the "work"
+skill, indicatin...` in the sidebar.
+
+These drive the real SQL/shaping path through SessionDB rather than calling the
+shaper directly, so the CASE expression and the Python side are covered together.
+"""
+
+import pytest
+
+import agent.skill_commands as skill_commands
+import tools.skills_tool as skills_tool
+from hermes_state import SessionDB
+
+SKILL_BODY = (
+    "Kick off a task in a fresh isolated git worktree instead of the current checkout. "
+    "Look at what the repo already does, and copy it. Create the worktree and branch. "
+)
+
+
+@pytest.fixture()
+def db(tmp_path):
+    session_db = SessionDB(db_path=tmp_path / "state.db")
+    yield session_db
+    session_db.close()
+
+
+def _install_skill(tmp_path, monkeypatch, name="work", body=SKILL_BODY):
+    skills_dir = tmp_path / "skills"
+    skill_dir = skills_dir / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: Description for {name}\n---\n\n# {name}\n\n{body}\n"
+    )
+    monkeypatch.setattr(skills_tool, "SKILLS_DIR", skills_dir)
+    monkeypatch.setattr(skill_commands, "_skill_commands", {})
+    monkeypatch.setattr(skill_commands, "_skill_commands_platform", None)
+    skill_commands.scan_skill_commands()
+    return skills_dir
+
+
+def _seed(db, session_id, content, *, title=None, reply="On it."):
+    db.create_session(session_id=session_id, source="cli", model="m")
+    db.append_message(session_id, role="user", content=content)
+    db.append_message(session_id, role="assistant", content=reply)
+    if title:
+        db.set_session_title(session_id, title)
+
+
+class TestSkillPreview:
+    def test_plain_message_preview_is_unchanged(self, db):
+        _seed(db, "s1", "fix the title leak")
+        (row,) = db.list_sessions_rich(limit=10)
+        assert row["preview"] == "fix the title leak"
+
+    def test_long_plain_message_still_truncates(self, db):
+        _seed(db, "s1", "x" * 200)
+        (row,) = db.list_sessions_rich(limit=10)
+        assert row["preview"] == "x" * 60 + "..."
+
+    def test_skill_preview_shows_the_typed_instruction(self, db, tmp_path, monkeypatch):
+        _install_skill(tmp_path, monkeypatch)
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        _seed(db, "s1", message)
+        (row,) = db.list_sessions_rich(limit=10)
+        assert row["preview"] == "/work — fix the title leak"
+
+    def test_skill_preview_never_leaks_the_body(self, db, tmp_path, monkeypatch):
+        _install_skill(tmp_path, monkeypatch)
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        _seed(db, "s1", message)
+        (row,) = db.list_sessions_rich(limit=10)
+        assert "IMPORTANT" not in row["preview"]
+        assert "worktree" not in row["preview"]
+
+    def test_bare_skill_preview_is_the_command(self, db, tmp_path, monkeypatch):
+        _install_skill(tmp_path, monkeypatch)
+        message = skill_commands.build_skill_invocation_message("/work")
+        _seed(db, "s1", message)
+        (row,) = db.list_sessions_rich(limit=10)
+        assert row["preview"] == "/work"
+
+    def test_huge_skill_body_still_recovers_the_instruction(
+        self, db, tmp_path, monkeypatch
+    ):
+        # Long enough that the head window lands mid-body and the SQL has to
+        # splice the tail to reach the instruction.
+        _install_skill(tmp_path, monkeypatch, body="filler line.\n" * 300)
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        _seed(db, "s1", message)
+        (row,) = db.list_sessions_rich(limit=10)
+        assert row["preview"] == "/work — fix the title leak"
+        assert "filler line" not in row["preview"]
+
+    def test_single_row_lookup_agrees_with_the_list(self, db, tmp_path, monkeypatch):
+        """_get_session_rich_row shares the shaper — a compression tip must
+        surface the same preview the list does."""
+        _install_skill(tmp_path, monkeypatch)
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        _seed(db, "s1", message)
+        (listed,) = db.list_sessions_rich(limit=10)
+        single = db._get_session_rich_row("s1")
+        assert single["preview"] == listed["preview"] == "/work — fix the title leak"
+
+    def test_rewind_picker_shows_the_typed_instruction(
+        self, db, tmp_path, monkeypatch
+    ):
+        _install_skill(tmp_path, monkeypatch)
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        _seed(db, "s1", message)
+        (entry,) = db.list_recent_user_messages("s1")
+        assert entry["preview"] == "/work — fix the title leak"
+
+
+class TestSkillScaffoldedSessionLookup:
+    """Backing queries for `hermes sessions retitle-skills`."""
+
+    def test_finds_only_titled_skill_sessions(self, db, tmp_path, monkeypatch):
+        _install_skill(tmp_path, monkeypatch)
+        message = skill_commands.build_skill_invocation_message(
+            "/work", user_instruction="fix the title leak"
+        )
+        _seed(db, "titled", message, title="Isolated Git Worktree Setup")
+        _seed(db, "untitled", message)
+        _seed(db, "plain", "fix the title leak", title="Fixing The Title Leak")
+
+        rows = db.list_skill_scaffolded_sessions()
+        assert [row["id"] for row in rows] == ["titled"]
+        assert rows[0]["title"] == "Isolated Git Worktree Setup"
+        # The full first turn comes back so the caller can re-derive the ask.
+        assert "fix the title leak" in rows[0]["content"]
+
+    def test_limit_is_honored(self, db, tmp_path, monkeypatch):
+        _install_skill(tmp_path, monkeypatch)
+        message = skill_commands.build_skill_invocation_message("/work")
+        for i in range(3):
+            _seed(db, f"s{i}", message, title=f"Title {i}")
+        assert len(db.list_skill_scaffolded_sessions(limit=2)) == 2
+
+    def test_first_assistant_text(self, db):
+        _seed(db, "s1", "hello", reply="first reply")
+        db.append_message("s1", role="assistant", content="second reply")
+        assert db.get_first_assistant_text("s1") == "first reply"
+
+    def test_first_assistant_text_missing_is_empty(self, db):
+        db.create_session(session_id="s1", source="cli", model="m")
+        db.append_message("s1", role="user", content="hello")
+        assert db.get_first_assistant_text("s1") == ""
diff --git a/tests/test_sqlite_lock_safe_inspection.py b/tests/test_sqlite_lock_safe_inspection.py
new file mode 100644
index 00000000000..8a196417d58
--- /dev/null
+++ b/tests/test_sqlite_lock_safe_inspection.py
@@ -0,0 +1,459 @@
+"""POSIX advisory locks must survive Hermes' own database inspection.
+
+close() on ANY file descriptor for a SQLite database cancels every POSIX
+advisory lock the process holds on that file -- including a running VACUUM's
+EXCLUSIVE lock and an in-flight BEGIN IMMEDIATE's RESERVED lock:
+
+    https://sqlite.org/howtocorrupt.html#_posix_advisory_locks_canceled_by_a_separate_thread_doing_close_
+
+Hermes used to byte-probe live databases in several places (kanban's
+post-commit page-count check, the zeroed-state.db detector run on every
+SessionDB construction, backup header verification). Under `hermes sessions
+optimize` this let an external process write into a database while VACUUM was
+rewriting it, producing "database disk image is malformed".
+
+These tests pin the behavioural contract: an external process must stay locked
+out across Hermes' inspection calls.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import subprocess
+import sys
+import textwrap
+import threading
+
+import pytest
+
+from hermes_cli.sqlite_safe_read import (
+    file_length_matches_header,
+    has_live_connection,
+    page_count_bytes,
+    read_header_bytes_preopen,
+    track_connection,
+    untrack_connection,
+)
+
+
+_INTRUDER = textwrap.dedent(
+    """
+    import sqlite3, sys
+    conn = sqlite3.connect(sys.argv[1], isolation_level=None, timeout=0)
+    try:
+        conn.execute("PRAGMA busy_timeout=0")
+        conn.execute("BEGIN IMMEDIATE")
+        conn.execute("INSERT INTO t(v) VALUES ('intruder')")
+        conn.execute("COMMIT")
+        print("ACQUIRED")
+    except sqlite3.OperationalError:
+        print("BLOCKED")
+    """
+)
+
+
+def _external_writer_can_break_in(db_path) -> bool:
+    """True when a separate process managed to write to a locked database."""
+    result = subprocess.run(
+        [sys.executable, "-c", _INTRUDER, str(db_path)],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    return "ACQUIRED" in result.stdout
+
+
+def _make_db(path, journal_mode: str) -> None:
+    conn = sqlite3.connect(str(path), isolation_level=None)
+    conn.execute(f"PRAGMA journal_mode={journal_mode}")
+    conn.execute("CREATE TABLE t(v TEXT)")
+    conn.executemany("INSERT INTO t(v) VALUES (?)", [(f"row{i}",) for i in range(200)])
+    conn.close()
+
+
+@pytest.fixture
+def clean_registry():
+    yield
+    # Keep the module-level registry from leaking across tests.
+    import hermes_cli.sqlite_safe_read as mod
+
+    with mod._live_lock:
+        mod._live_connections.clear()
+
+
+@pytest.mark.parametrize("journal_mode", ["DELETE", "WAL"])
+def test_write_lock_survives_file_length_check(tmp_path, journal_mode, clean_registry):
+    """kanban's post-commit invariant check must not cancel the write lock."""
+    from hermes_cli.kanban_db import _check_file_length_invariant
+
+    db = tmp_path / "kanban.db"
+    _make_db(db, journal_mode)
+
+    holder = sqlite3.connect(str(db), isolation_level=None, timeout=0.5)
+    holder.execute(f"PRAGMA journal_mode={journal_mode}")
+    holder.execute("BEGIN IMMEDIATE")
+    holder.execute("INSERT INTO t(v) VALUES ('held')")
+    try:
+        assert not _external_writer_can_break_in(db), (
+            "precondition failed: the external writer was not locked out "
+            "before the inspection call"
+        )
+
+        worker = sqlite3.connect(str(db), isolation_level=None, timeout=0.5)
+        try:
+            _check_file_length_invariant(worker)
+        finally:
+            worker.close()
+
+        assert not _external_writer_can_break_in(db), (
+            "_check_file_length_invariant cancelled this process's POSIX "
+            "advisory locks -- an external process wrote into a database "
+            "that a writer still believed it held exclusively"
+        )
+    finally:
+        holder.close()
+
+
+@pytest.mark.parametrize("journal_mode", ["DELETE", "WAL"])
+def test_write_lock_survives_zeroed_state_db_probe(
+    tmp_path, journal_mode, clean_registry
+):
+    """SessionDB's zeroed-file detector must not cancel locks once connected."""
+    from hermes_state import is_zeroed_state_db
+
+    db = tmp_path / "state.db"
+    _make_db(db, journal_mode)
+
+    holder = sqlite3.connect(str(db), isolation_level=None, timeout=0.5)
+    holder.execute(f"PRAGMA journal_mode={journal_mode}")
+    holder.execute("BEGIN IMMEDIATE")
+    holder.execute("INSERT INTO t(v) VALUES ('held')")
+    track_connection(db)
+    try:
+        assert not _external_writer_can_break_in(db)
+
+        assert is_zeroed_state_db(db) is False
+
+        assert not _external_writer_can_break_in(db), (
+            "is_zeroed_state_db cancelled this process's POSIX advisory "
+            "locks on a live database"
+        )
+    finally:
+        untrack_connection(db)
+        holder.close()
+
+
+def test_preopen_read_refused_while_connection_is_live(tmp_path, clean_registry):
+    """The byte-level probe is allowed pre-open and refused once connected."""
+    db = tmp_path / "state.db"
+    _make_db(db, "WAL")
+
+    assert not has_live_connection(db)
+    head = read_header_bytes_preopen(db, length=16)
+    assert head == b"SQLite format 3\x00"
+
+    track_connection(db)
+    try:
+        assert has_live_connection(db)
+        assert read_header_bytes_preopen(db, length=16) is None
+        # An explicit override stays available for offline artifacts.
+        assert read_header_bytes_preopen(db, length=16, force=True) is not None
+    finally:
+        untrack_connection(db)
+
+    assert not has_live_connection(db)
+    assert read_header_bytes_preopen(db, length=16) is not None
+
+
+def test_tracking_registry_does_not_leak_across_close_paths(tmp_path, clean_registry):
+    """A drifting counter would silently disable the probe guard forever.
+
+    Opens are easy to count; closes happen in many places. If the registry
+    ever over-counts, ``has_live_connection`` stays true for a path with no
+    live connection and every later byte-probe is refused — turning the
+    safety guard into a permanent outage of zeroed-file / header detection.
+    """
+    import contextlib
+
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
+    db = tmp_path / "state.db"
+    boot = connect_tracked(db, isolation_level=None)
+    boot.execute("CREATE TABLE t(v TEXT)")
+    boot.close()
+    assert not has_live_connection(db)
+
+    # plain close
+    connect_tracked(db).close()
+    assert not has_live_connection(db)
+
+    # contextlib.closing
+    with contextlib.closing(connect_tracked(db)):
+        assert has_live_connection(db)
+    assert not has_live_connection(db)
+
+    # `with conn:` is a TRANSACTION scope, not a close — must stay tracked
+    conn = connect_tracked(db, isolation_level=None)
+    with conn:
+        conn.execute("INSERT INTO t(v) VALUES ('x')")
+    assert has_live_connection(db), "transaction scope must not untrack"
+    conn.close()
+    assert not has_live_connection(db)
+
+    # double close is idempotent (must not under-count into negatives)
+    dup = connect_tracked(db)
+    dup.close()
+    dup.close()
+    assert not has_live_connection(db)
+
+    # nested lifetimes: still live until the last one closes
+    first = connect_tracked(db)
+    second = connect_tracked(db)
+    first.close()
+    assert has_live_connection(db)
+    second.close()
+    assert not has_live_connection(db)
+
+    # churn must not drift
+    for _ in range(100):
+        connect_tracked(db).close()
+    assert not has_live_connection(db)
+
+
+def test_probe_and_connect_do_not_race(tmp_path, clean_registry, monkeypatch):
+    """The check and the raw read must be atomic w.r.t. connection lifecycle.
+
+    Deterministic interleaving: pause the probe *inside* the byte read — after
+    it has decided "nothing is live" and opened its descriptor — then let
+    another thread open a tracked connection and take a write lock, then let
+    the probe close.
+
+    With the guard holding ``_live_lock`` across check+open+read+close, the
+    other thread blocks on that lock until the probe is done, so no
+    interleaving is possible. If the lock is only held across the check, that
+    thread slips in and the probe's ``close()`` cancels its POSIX locks.
+    """
+    import hermes_cli.sqlite_safe_read as ssr
+
+    db = tmp_path / "state.db"
+    _make_db(db, "DELETE")
+
+    inside_read = threading.Event()
+    may_close = threading.Event()
+    failures: list[str] = []
+    real_open = open
+
+    def slow_open(*args, **kwargs):
+        handle = real_open(*args, **kwargs)
+        inside_read.set()
+        # Hold the descriptor open while the writer tries to get in.
+        may_close.wait(10)
+        return handle
+
+    def writer():
+        inside_read.wait(10)
+        # If the guard is correct this blocks until the probe releases the
+        # lock; if not, it opens and locks inside the probe's window.
+        conn = ssr.connect_tracked(db, isolation_level=None, timeout=0.5)
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            conn.execute("INSERT INTO t(v) VALUES ('holder')")
+            may_close.set()  # let the probe's close() land
+            if _external_writer_can_break_in(db):
+                failures.append(
+                    "external writer broke in: the probe's close() cancelled "
+                    "this connection's POSIX locks"
+                )
+            conn.execute("COMMIT")
+        except sqlite3.Error as exc:  # a cancelled lock surfaces here too
+            failures.append(f"holder transaction failed: {exc}")
+        finally:
+            conn.close()
+
+    monkeypatch.setattr(ssr, "open", slow_open, raising=False)
+    t = threading.Thread(target=writer, daemon=True)
+    t.start()
+    try:
+        read_header_bytes_preopen(db, length=16)
+    finally:
+        may_close.set()  # never wedge the probe if the writer died
+    t.join(20)
+
+    assert not failures, failures[0]
+
+
+def test_read_only_uri_connection_is_tracked_by_real_path(tmp_path, clean_registry):
+    """A ``file:...?mode=ro`` connection must register under the real path.
+
+    SessionDB's read-only path opens a URI, not a filesystem path. Keying the
+    registry on the caller's spelling produces something like
+    ``<cwd>/file:/…/state.db?mode=ro``, which no probe of the actual Path can
+    match -- leaving the read-only connection invisible to the guard and its
+    locks cancellable.
+    """
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
+    db = tmp_path / "state.db"
+    _make_db(db, "DELETE")
+
+    conn = connect_tracked(
+        f"file:{db}?mode=ro", uri=True, isolation_level=None, timeout=0.5
+    )
+    try:
+        assert has_live_connection(db), (
+            "read-only URI connection was registered under a URI-shaped key; "
+            "a probe of the real path cannot see it"
+        )
+        assert read_header_bytes_preopen(db, length=16) is None
+    finally:
+        conn.close()
+
+    assert not has_live_connection(db)
+
+
+def test_session_db_read_only_is_tracked(tmp_path, clean_registry, monkeypatch):
+    """End-to-end: a real read-only SessionDB blocks byte-probes."""
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    from hermes_state import SessionDB
+
+    db_path = tmp_path / "state.db"
+    seed = SessionDB(db_path=db_path)
+    seed.create_session("s1", source="cli")
+    seed.close()
+
+    ro = SessionDB(db_path=db_path, read_only=True)
+    try:
+        assert has_live_connection(db_path)
+        assert read_header_bytes_preopen(db_path, length=16) is None
+    finally:
+        ro.close()
+
+    assert not has_live_connection(db_path)
+    assert read_header_bytes_preopen(db_path, length=16) is not None
+
+
+def test_custom_factory_is_honoured_and_still_tracked(tmp_path, clean_registry):
+    """A caller's factory must work AND keep byte-probe protection.
+
+    Callers legitimately pass their own Connection subclasses (the suite uses
+    them to simulate FTS5-less runtimes). Neither rejecting them nor silently
+    leaving them untracked is acceptable — the former breaks real callers, the
+    latter quietly unguards the database. The factory is augmented instead.
+    """
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
+    class CustomConnection(sqlite3.Connection):
+        pass
+
+    db = tmp_path / "state.db"
+    _make_db(db, "WAL")
+
+    conn = connect_tracked(db, factory=CustomConnection)
+    try:
+        assert isinstance(conn, CustomConnection), "caller's factory must be honoured"
+        assert conn.execute("SELECT COUNT(*) FROM t").fetchone()[0] == 200
+        assert has_live_connection(db), "custom factory must still be tracked"
+        assert read_header_bytes_preopen(db, length=16) is None
+    finally:
+        conn.close()
+
+    assert not has_live_connection(db), "custom factory must untrack on close"
+
+
+def test_opener_that_discards_our_factory_is_still_tracked(tmp_path, clean_registry):
+    """Tracking must survive an opener that substitutes its own factory.
+
+    Two distinct paths reach a custom Connection subclass: the caller passing
+    ``factory=`` (augmented before the open) and an opener that ignores the
+    factory we asked for and supplies its own (retrofitted after the open).
+    The suite's FTS5-less doubles take the second path, so it needs its own
+    coverage -- otherwise a regression there is invisible.
+    """
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
+    class CustomConnection(sqlite3.Connection):
+        pass
+
+    db = tmp_path / "state.db"
+    _make_db(db, "DELETE")
+
+    def opener_that_ignores_factory(path, **kwargs):
+        kwargs.pop("factory", None)
+        return sqlite3.connect(path, factory=CustomConnection, **kwargs)
+
+    conn = connect_tracked(db, connect_fn=opener_that_ignores_factory)
+    try:
+        assert isinstance(conn, CustomConnection), "opener's factory must survive"
+        assert has_live_connection(db), (
+            "connection opened with a substituted factory was left untracked; "
+            "its database silently lost byte-probe protection"
+        )
+        assert read_header_bytes_preopen(db, length=16) is None
+    finally:
+        conn.close()
+
+    assert not has_live_connection(db), "retrofitted connection must untrack on close"
+
+
+def test_session_db_read_only_tracks_under_canonical_path(tmp_path, clean_registry):
+    """The read-only URI must resolve to the real path even without a hint.
+
+    ``SessionDB`` passes ``tracking_path`` explicitly, but the helper must not
+    depend on that: ``PRAGMA database_list`` is the authority. This exercises
+    the no-hint path directly so removing the fallback is caught.
+    """
+    from hermes_cli.sqlite_safe_read import connect_tracked
+
+    db = tmp_path / "state.db"
+    _make_db(db, "DELETE")
+
+    conn = connect_tracked(
+        f"file:{db}?mode=ro", uri=True, isolation_level=None, timeout=0.5
+    )
+    try:
+        assert has_live_connection(db), (
+            "canonical-path resolution failed: the URI spelling was used as "
+            "the registry key"
+        )
+    finally:
+        conn.close()
+
+
+def test_page_count_bytes_matches_on_disk_size(tmp_path):
+    """The PRAGMA route reports the same size the header field encodes."""
+    db = tmp_path / "state.db"
+    _make_db(db, "DELETE")
+
+    conn = sqlite3.connect(str(db))
+    try:
+        logical = page_count_bytes(conn)
+        assert logical is not None
+        assert logical == db.stat().st_size
+        assert file_length_matches_header(conn) is True
+    finally:
+        conn.close()
+
+
+def test_file_length_check_never_reports_truncated_db_as_healthy(tmp_path):
+    """A short file must not come back as a clean 'file length matches'.
+
+    On a truncated database SQLite refuses the pragma outright, so the helper
+    returns None (inconclusive) rather than False. Either way the contract that
+    matters is the same: a torn file is never reported as healthy.
+    """
+    db = tmp_path / "state.db"
+    _make_db(db, "DELETE")
+
+    conn = sqlite3.connect(str(db))
+    try:
+        logical = page_count_bytes(conn)
+        assert logical is not None
+        assert file_length_matches_header(conn) is True
+
+        # Truncate behind SQLite's back to simulate a torn extend.
+        with open(db, "r+b") as handle:
+            handle.truncate(logical // 2)
+
+        assert file_length_matches_header(conn) is not True
+    finally:
+        conn.close()
diff --git a/tests/test_sqlite_wal_reset_gate.py b/tests/test_sqlite_wal_reset_gate.py
index c184a6b9c40..951f4e06fdd 100644
--- a/tests/test_sqlite_wal_reset_gate.py
+++ b/tests/test_sqlite_wal_reset_gate.py
@@ -186,5 +186,6 @@ def test_doctor_warns_without_adding_issues(monkeypatch, tmp_path, capsys):
     assert "SQLite" in out
     assert "3.50.4" in out
     assert "WAL-reset" in out
+    assert "hermes update" in out
     # No longer appended to the blocking issues summary.
     assert "Linked SQLite is vulnerable" not in out
diff --git a/tests/test_toolsets.py b/tests/test_toolsets.py
index 3f99554561e..7f9c55a83bd 100644
--- a/tests/test_toolsets.py
+++ b/tests/test_toolsets.py
@@ -31,6 +31,15 @@ class TestGetToolset:
         assert ts is not None
         assert "web_search" in ts["tools"]
 
+    def test_x_search_toolset_marks_read_only_and_points_to_xurl(self):
+        ts = get_toolset("x_search")
+        assert ts is not None
+        assert ts["tools"] == ["x_search"]
+        description = ts["description"].lower()
+        assert "read-only" in description
+        assert "xurl" in description
+        assert "authenticated" in description
+
     def test_merges_registry_tools_into_builtin_toolset(self, monkeypatch):
         reg = ToolRegistry()
         reg.register(
diff --git a/tests/test_trajectory_compressor.py b/tests/test_trajectory_compressor.py
index 8fcbfc38cfe..b4e4c876a3f 100644
--- a/tests/test_trajectory_compressor.py
+++ b/tests/test_trajectory_compressor.py
@@ -628,3 +628,67 @@ class TestCompressionToolPairIntegrity:
             {"from": "tool", "value": "<tool_response>a</tool_response>"},
         ]
         assert tc._snap_boundary(trajectory, 1, 0, 1) == 0
+
+
+# ---------------------------------------------------------------------------
+# TrajectoryCompressor — compression must never increase the token count
+# ---------------------------------------------------------------------------
+
+
+class TestCompressionNetSavingsGuard:
+    """When the compressible middle is no larger than the summary that would
+    replace it, compression cannot help — it must be skipped rather than grow
+    the trajectory (and burn a summarization call)."""
+
+    def _tiny_middle_trajectory(self):
+        # Large protected head (system+human), tiny compressible middle.
+        big = "w " * 400  # ~200 tokens each (1 token / 4 chars)
+        small = "ok " * 2
+        return [
+            {"from": "system", "value": big},  # protected (first_system)
+            {"from": "human", "value": big},  # protected (first_human)
+            {"from": "gpt", "value": small},  # protected (first_gpt)
+            {"from": "tool", "value": small},  # protected (first_tool)
+            {"from": "gpt", "value": small},  # compressible middle
+            {"from": "tool", "value": small},  # compressible middle
+            {"from": "gpt", "value": small},  # protected (last 2)
+            {"from": "human", "value": small},  # protected (last 2)
+        ]
+
+    def _config(self):
+        config = CompressionConfig()
+        config.protect_last_n_turns = 2
+        config.summary_target_tokens = 20
+        config.target_max_tokens = 100  # trajectory is far over this
+        return config
+
+    def test_sync_skips_compression_when_middle_smaller_than_summary(self):
+        tc = _make_compressor(self._config())
+        tc._generate_summary = MagicMock(
+            return_value="[CONTEXT SUMMARY]: " + "blah " * 30
+        )
+        trajectory = self._tiny_middle_trajectory()
+        before = sum(tc.count_turn_tokens(trajectory))
+
+        compressed, metrics = tc.compress_trajectory(trajectory)
+
+        assert metrics.was_compressed is False
+        assert compressed == trajectory
+        assert sum(tc.count_turn_tokens(compressed)) == before
+        tc._generate_summary.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_async_skips_compression_when_middle_smaller_than_summary(self):
+        tc = _make_compressor(self._config())
+        tc._generate_summary_async = AsyncMock(
+            return_value="[CONTEXT SUMMARY]: " + "blah " * 30
+        )
+        trajectory = self._tiny_middle_trajectory()
+        before = sum(tc.count_turn_tokens(trajectory))
+
+        compressed, metrics = await tc.compress_trajectory_async(trajectory)
+
+        assert metrics.was_compressed is False
+        assert compressed == trajectory
+        assert sum(tc.count_turn_tokens(compressed)) == before
+        tc._generate_summary_async.assert_not_called()
diff --git a/tests/test_tui_gateway_server.py b/tests/test_tui_gateway_server.py
index c1c794473c1..7b7d6b2a6d6 100644
--- a/tests/test_tui_gateway_server.py
+++ b/tests/test_tui_gateway_server.py
@@ -293,6 +293,8 @@ def test_prompt_submit_fails_open_inline_when_compute_host_dispatch_breaks(monke
     monkeypatch.setattr(server, "_persist_branch_seed", lambda _session: None)
     monkeypatch.setattr(server, "_start_agent_build", lambda _sid, _session: None)
     monkeypatch.setattr(server, "_wait_agent", lambda _session, _rid: None)
+    # The deferred inline-fallback thread now waits via the patient variant.
+    monkeypatch.setattr(server, "_wait_agent_for_prompt", lambda _session, _rid, _sid: None)
     monkeypatch.setattr(
         server,
         "_run_prompt_submit",
@@ -3239,6 +3241,145 @@ def test_prompt_submit_rejects_negative_truncate_ordinal(monkeypatch):
         server._sessions.pop("trunc-sid", None)
 
 
+def test_prompt_submit_refuses_empty_truncation_without_confirm(monkeypatch):
+    """Stale truncate_before_user_ordinal=0 must not wipe a non-empty transcript.
+
+    Desktop desync can attach ordinal 0 to an ordinary fresh submit. That cuts
+    at the first user message (history[:0] == []) and replace_messages() would
+    DELETE every durable row. Refuse unless confirm_empty_truncate is set.
+    """
+    replaced = []
+
+    class _FakeDB:
+        def replace_messages(self, key, messages):
+            replaced.append((key, list(messages)))
+
+    history = [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "ok"},
+        {"role": "user", "content": "second"},
+        {"role": "assistant", "content": "done"},
+    ]
+    server._sessions["empty-trunc-sid"] = _session(history=list(history))
+    monkeypatch.setattr(server, "_get_db", lambda: _FakeDB())
+    monkeypatch.setattr(
+        server, "_start_agent_build", lambda *a, **k: pytest.fail("must not start a turn")
+    )
+    monkeypatch.setattr(
+        server, "_start_inflight_turn", lambda *a, **k: pytest.fail("must not start a turn")
+    )
+
+    try:
+        # Missing confirm → refuse.
+        resp = server.handle_request(
+            {
+                "id": "1",
+                "method": "prompt.submit",
+                "params": {
+                    "session_id": "empty-trunc-sid",
+                    "text": "fresh typed message",
+                    "truncate_before_user_ordinal": 0,
+                },
+            }
+        )
+        assert resp["error"]["code"] == 4028
+        assert "confirm_empty_truncate" in resp["error"]["message"]
+        # Explicit falsey values must not satisfy the opt-in either.
+        for falsey in (False, 0, "", "false", "no"):
+            resp = server.handle_request(
+                {
+                    "id": "1",
+                    "method": "prompt.submit",
+                    "params": {
+                        "session_id": "empty-trunc-sid",
+                        "text": "fresh typed message",
+                        "truncate_before_user_ordinal": 0,
+                        "confirm_empty_truncate": falsey,
+                    },
+                }
+            )
+            assert resp["error"]["code"] == 4028, falsey
+        assert server._sessions["empty-trunc-sid"]["history"] == history
+        assert server._sessions["empty-trunc-sid"]["running"] is False
+        assert server._sessions["empty-trunc-sid"]["history_version"] == 0
+        assert replaced == []
+    finally:
+        server._sessions.pop("empty-trunc-sid", None)
+
+
+def test_prompt_submit_empty_truncation_allowed_with_confirm(monkeypatch):
+    """Intentional restore/regenerate of the first user turn may wipe history."""
+
+    seen = {}
+    replaced = []
+
+    class _Agent:
+        def run_conversation(
+            self, prompt, conversation_history=None, stream_callback=None, **_kwargs
+        ):
+            seen["prompt"] = prompt
+            seen["history"] = conversation_history
+            return {
+                "final_response": "regenerated",
+                "messages": [
+                    *(conversation_history or []),
+                    {"role": "user", "content": prompt},
+                    {"role": "assistant", "content": "regenerated"},
+                ],
+            }
+
+    class _ImmediateThread:
+        def __init__(self, target=None, daemon=None):
+            self._target = target
+
+        def start(self):
+            self._target()
+
+    class _FakeDB:
+        def replace_messages(self, key, messages):
+            replaced.append((key, list(messages)))
+
+    history = [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "ok"},
+        {"role": "user", "content": "second"},
+        {"role": "assistant", "content": "done"},
+    ]
+    server._sessions["confirm-empty-sid"] = _session(
+        agent=_Agent(), history=list(history)
+    )
+
+    try:
+        monkeypatch.setattr(server.threading, "Thread", _ImmediateThread)
+        monkeypatch.setattr(server, "_get_usage", lambda _a: {})
+        monkeypatch.setattr(server, "render_message", lambda _t, _c: "")
+        monkeypatch.setattr(server, "_emit", lambda *a: None)
+        monkeypatch.setattr(server, "_get_db", lambda: _FakeDB())
+
+        resp = server.handle_request(
+            {
+                "id": "1",
+                "method": "prompt.submit",
+                "params": {
+                    "session_id": "confirm-empty-sid",
+                    "text": "first",
+                    "truncate_before_user_ordinal": 0,
+                    "confirm_empty_truncate": True,
+                },
+            }
+        )
+        assert resp.get("result"), f"got error: {resp.get('error')}"
+        assert seen["prompt"] == "first"
+        assert seen["history"] == []
+        assert replaced == [("session-key", [])]
+        assert server._sessions["confirm-empty-sid"]["history"] == [
+            {"role": "user", "content": "first"},
+            {"role": "assistant", "content": "regenerated"},
+        ]
+    finally:
+        server._sessions.pop("confirm-empty-sid", None)
+
+
 class _StopAfterOneNotificationPoll:
     def __init__(self):
         self._checks = 0
@@ -3570,9 +3711,7 @@ class _RecordingAgent:
     def clear_interrupt(self):
         return None
 
-    def run_conversation(
-        self, prompt, conversation_history=None, stream_callback=None
-    ):
+    def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
         self._turns.append(prompt)
         return {"final_response": "", "messages": []}
 
@@ -3681,9 +3820,7 @@ def test_run_prompt_submit_requeues_all_unstarted_notifications_with_real_thread
         return thread
 
     class _BlockingNotificationAgent(_RecordingAgent):
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             turns.append(prompt)
             if "proc_batch_1" in prompt:
                 nested_started.set()
@@ -3893,7 +4030,7 @@ def test_ensure_session_db_row_persists_explicit_cwd(monkeypatch, tmp_path):
     created = []
 
     class _FakeDB:
-        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None):
+        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None, profile_name=None):
             created.append(
                 {"key": key, "source": source, "model": model, "model_config": model_config, "cwd": cwd}
             )
@@ -3914,7 +4051,7 @@ def test_ensure_session_db_row_persists_session_source(monkeypatch):
     created = []
 
     class _FakeDB:
-        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None):
+        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None, profile_name=None):
             created.append(
                 {"key": key, "source": source, "model": model, "model_config": model_config, "cwd": cwd}
             )
@@ -3929,13 +4066,17 @@ def test_ensure_session_db_row_persists_session_source(monkeypatch):
     ]
 
 
-def test_ensure_session_db_row_defaults_to_no_workspace(monkeypatch, tmp_path):
-    """Without an explicit workspace, cwd is left null so the session groups
-    under "No workspace" rather than the gateway's launch directory."""
+def test_ensure_session_db_row_records_a_terminal_workspace(monkeypatch, tmp_path):
+    """A terminal session's directory IS its workspace, so the row records it.
+
+    The user cd'd there before running hermes. Leaving it null stranded the row
+    with no cwd and no git_repo_root, so the sidebar could never place the
+    session under its project.
+    """
     created = []
 
     class _FakeDB:
-        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None):
+        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None, profile_name=None):
             created.append(
                 {"key": key, "source": source, "model": model, "model_config": model_config, "cwd": cwd}
             )
@@ -3948,7 +4089,28 @@ def test_ensure_session_db_row_defaults_to_no_workspace(monkeypatch, tmp_path):
     server._ensure_session_db_row({"session_key": "k1", "cwd": str(tmp_path)})
 
     assert created == [
-        {"key": "k1", "source": "tui", "model": "test-model", "model_config": None, "cwd": None}
+        {"key": "k1", "source": "tui", "model": "test-model", "model_config": None, "cwd": str(tmp_path)}
+    ]
+
+
+def test_ensure_session_db_row_defaults_desktop_to_no_workspace(monkeypatch, tmp_path):
+    """The desktop launches from wherever the bundle was opened, so an unpicked
+    cwd is an artifact — those chats stay null and group under "No workspace"."""
+    created = []
+
+    class _FakeDB:
+        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None, profile_name=None):
+            created.append(
+                {"key": key, "source": source, "model": model, "model_config": model_config, "cwd": cwd}
+            )
+
+    monkeypatch.setattr(server, "_get_db", lambda: _FakeDB())
+    monkeypatch.setattr(server, "_resolve_model", lambda: "test-model")
+
+    server._ensure_session_db_row({"session_key": "k1", "source": "desktop", "cwd": str(tmp_path)})
+
+    assert created == [
+        {"key": "k1", "source": "desktop", "model": "test-model", "model_config": None, "cwd": None}
     ]
 
 
@@ -3964,7 +4126,7 @@ def test_ensure_session_db_row_persists_session_model_override(monkeypatch):
     created = []
 
     class _FakeDB:
-        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None):
+        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None, profile_name=None):
             created.append(
                 {"key": key, "model": model, "model_config": model_config, "cwd": cwd}
             )
@@ -3996,7 +4158,7 @@ def test_ensure_session_db_row_no_override_uses_global(monkeypatch):
     created = []
 
     class _FakeDB:
-        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None):
+        def create_session(self, key, source=None, model=None, model_config=None, parent_session_id=None, cwd=None, profile_name=None):
             created.append({"model": model, "model_config": model_config})
 
     monkeypatch.setattr(server, "_get_db", lambda: _FakeDB())
@@ -4007,6 +4169,36 @@ def test_ensure_session_db_row_no_override_uses_global(monkeypatch):
     assert created == [{"model": "global/default", "model_config": None}]
 
 
+def test_ensure_session_db_row_stamps_profile_name(monkeypatch, tmp_path):
+    """A profile session's row carries its owning profile_name, so unified
+    multi-profile aggregation never has to guess from which state.db file the
+    row happened to be read (the cross-profile session-jump bug)."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+    created = []
+
+    class _ProfileDB:
+        def __init__(self, db_path=None):
+            created.append({"db_path": db_path})
+
+        def create_session(self, key, **kwargs):
+            created[-1].update({"key": key, "profile_name": kwargs.get("profile_name")})
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr("hermes_state.SessionDB", _ProfileDB)
+    monkeypatch.setattr(server, "_resolve_model", lambda: "test-model")
+
+    server._ensure_session_db_row(
+        {"session_key": "k1", "profile_home": str(profile_home)}
+    )
+
+    assert created and created[0]["key"] == "k1"
+    assert created[0]["profile_name"] == "mlperf"
+    assert created[0]["db_path"] == profile_home / "state.db"
+
+
 def test_session_title_clears_pending_after_persist(monkeypatch):
     class _FakeDB:
         def __init__(self):
@@ -6439,9 +6631,7 @@ def test_prompt_submit_sets_approval_session_key(monkeypatch):
     captured = {}
 
     class _Agent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             captured["session_key"] = get_current_session_key(default="")
             return {
                 "final_response": "ok",
@@ -6481,9 +6671,7 @@ def test_prompt_submit_expands_context_refs(monkeypatch):
         base_url = ""
         api_key = ""
 
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             captured["prompt"] = prompt
             return {
                 "final_response": "ok",
@@ -7352,9 +7540,7 @@ def test_prompt_submit_history_version_mismatch_surfaces_warning(monkeypatch):
     session_ref = {"s": None}
 
     class _RacyAgent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             # Simulate: something external bumped history_version
             # while we were running.
             with session_ref["s"]["history_lock"]:
@@ -7415,9 +7601,7 @@ def test_prompt_submit_sanitizes_bracketed_paste_before_agent(monkeypatch):
     captured: dict[str, str] = {}
 
     class _Agent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             captured["prompt"] = prompt
             return {
                 "final_response": "ok",
@@ -7459,9 +7643,7 @@ def test_prompt_submit_history_version_match_persists_normally(monkeypatch):
     """Regression guard: the backstop does not affect the happy path."""
 
     class _Agent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             return {
                 "final_response": "reply",
                 "messages": [{"role": "assistant", "content": "reply"}],
@@ -7512,9 +7694,7 @@ def test_prompt_submit_can_truncate_before_user_ordinal(monkeypatch):
     seen = {}
 
     class _Agent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             seen["prompt"] = prompt
             seen["history"] = conversation_history
             return {
@@ -7804,6 +7984,491 @@ def test_interrupt_before_agent_ready_prevents_late_turn_start(monkeypatch):
         server._sessions.pop("sid", None)
 
 
+def test_cancelled_turn_before_agent_ready_emits_error_event(monkeypatch):
+    """A turn cancelled during lazy agent startup must surface an error event.
+
+    Sibling of test_interrupt_before_agent_ready_prevents_late_turn_start: that
+    test only asserts `_run_prompt_submit` is skipped, mocking `_emit` to a
+    no-op so it cannot catch a silent drop. This test captures `_emit` and
+    asserts the client receives an `error` event with a human-readable message,
+    so the Desktop composer can show feedback instead of hanging on a
+    `{"status":"streaming"}` reply that never produces a turn (issue #63078
+    server-side half).
+    """
+    threads = []
+    emitted = []
+    calls = {"run_prompt": 0}
+
+    class _FakeThread:
+        def __init__(self, target=None, daemon=None):
+            self.target = target
+            threads.append(self)
+
+        def start(self):
+            return None
+
+        def is_alive(self):
+            return True
+
+    session = _session()
+    session["agent"] = None
+    server._sessions["sid"] = session
+
+    try:
+        monkeypatch.setattr(server.threading, "Thread", _FakeThread)
+        monkeypatch.setattr(server, "_emit", lambda *args, **kwargs: emitted.append(args))
+        monkeypatch.setattr(server, "_ensure_session_db_row", lambda session: None)
+        monkeypatch.setattr(server, "_persist_branch_seed", lambda session: None)
+        monkeypatch.setattr(server, "_start_agent_build", lambda sid, session: None)
+        monkeypatch.setattr(server, "_wait_agent", lambda session, rid: None)
+        monkeypatch.setattr(
+            server,
+            "_run_prompt_submit",
+            lambda *args, **kwargs: calls.__setitem__(
+                "run_prompt", calls["run_prompt"] + 1
+            ),
+        )
+
+        submit = server.handle_request(
+            {
+                "id": "1",
+                "method": "prompt.submit",
+                "params": {"session_id": "sid", "text": "hello"},
+            }
+        )
+        assert submit.get("result"), f"got error: {submit.get('error')}"
+        assert session["running"] is True
+
+        # User hits Stop while the agent is still building.
+        stop = server.handle_request(
+            {"id": "2", "method": "session.interrupt", "params": {"session_id": "sid"}}
+        )
+        assert stop.get("result"), f"got error: {stop.get('error')}"
+        assert session.get("_turn_cancel_requested") is True
+
+        # The deferred run thread now wakes up; without the emit it would bail
+        # silently and the Desktop would never learn the turn was dropped.
+        threads[0].target()
+
+        assert calls["run_prompt"] == 0
+        assert session["running"] is False
+        assert session.get("inflight_turn") is None
+        # Exactly one error event addressed to this session.
+        error_events = [e for e in emitted if e and len(e) >= 2 and e[0] == "error" and e[1] == "sid"]
+        assert len(error_events) == 1, f"expected one error event, got: {emitted}"
+        msg = error_events[0][2].get("message", "")
+        assert "cancelled" in msg.lower(), f"unexpected message: {msg}"
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_session_not_running_before_agent_ready_emits_error_event(monkeypatch):
+    """When `running` is cleared by something other than an explicit interrupt
+    (e.g. a concurrent session.create race that resets the flag), the deferred
+    run thread must still emit an error event rather than disappearing silently.
+    """
+    threads = []
+    emitted = []
+    calls = {"run_prompt": 0}
+
+    class _FakeThread:
+        def __init__(self, target=None, daemon=None):
+            self.target = target
+            threads.append(self)
+
+        def start(self):
+            return None
+
+        def is_alive(self):
+            return True
+
+    session = _session()
+    session["agent"] = None
+    server._sessions["sid"] = session
+
+    try:
+        monkeypatch.setattr(server.threading, "Thread", _FakeThread)
+        monkeypatch.setattr(server, "_emit", lambda *args, **kwargs: emitted.append(args))
+        monkeypatch.setattr(server, "_ensure_session_db_row", lambda session: None)
+        monkeypatch.setattr(server, "_persist_branch_seed", lambda session: None)
+        monkeypatch.setattr(server, "_start_agent_build", lambda sid, session: None)
+        monkeypatch.setattr(server, "_wait_agent", lambda session, rid: None)
+        monkeypatch.setattr(
+            server,
+            "_run_prompt_submit",
+            lambda *args, **kwargs: calls.__setitem__(
+                "run_prompt", calls["run_prompt"] + 1
+            ),
+        )
+
+        submit = server.handle_request(
+            {
+                "id": "1",
+                "method": "prompt.submit",
+                "params": {"session_id": "sid", "text": "hello"},
+            }
+        )
+        assert submit.get("result"), f"got error: {submit.get('error')}"
+        assert session["running"] is True
+
+        # Simulate a concurrent path clearing `running` without setting the
+        # cancel flag (the other branch of the guard).
+        with session["history_lock"]:
+            session["running"] = False
+
+        threads[0].target()
+
+        assert calls["run_prompt"] == 0
+        assert session.get("inflight_turn") is None
+        error_events = [e for e in emitted if e and len(e) >= 2 and e[0] == "error" and e[1] == "sid"]
+        assert len(error_events) == 1, f"expected one error event, got: {emitted}"
+        msg = error_events[0][2].get("message", "")
+        assert "no longer running" in msg.lower(), f"unexpected message: {msg}"
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_slow_agent_build_delivers_prompt_instead_of_timing_out(monkeypatch):
+    """#63078 server-side half: a deferred build slower than the old 30s
+    ``_wait_agent`` cliff must NOT eat the first message. The patient wait
+    keeps the pending prompt attached and delivers it as soon as the
+    still-running build completes."""
+    threads = []
+    emitted = []
+    calls = {"run_prompt": 0}
+
+    class _FakeThread:
+        def __init__(self, target=None, daemon=None):
+            self.target = target
+            threads.append(self)
+
+        def start(self):
+            return None
+
+        def is_alive(self):
+            return True
+
+    ready = threading.Event()
+    session = _session(agent_ready=ready)
+    session["agent"] = None
+    server._sessions["sid"] = session
+
+    # The build "completes" only after the wait loop has already gone through
+    # several empty slices — i.e. well past what a single fixed-timeout wait
+    # slice would tolerate.
+    slices = {"n": 0}
+
+    class _SlowReady:
+        def wait(self, timeout=None):
+            slices["n"] += 1
+            if slices["n"] >= 3:
+                ready.set()
+                session["agent"] = types.SimpleNamespace()
+                return True
+            return False
+
+        def is_set(self):
+            return ready.is_set()
+
+    session["agent_ready"] = _SlowReady()
+
+    try:
+        monkeypatch.setattr(server.threading, "Thread", _FakeThread)
+        monkeypatch.setattr(server, "_emit", lambda *args, **kwargs: emitted.append(args))
+        monkeypatch.setattr(server, "_ensure_session_db_row", lambda session: None)
+        monkeypatch.setattr(server, "_persist_branch_seed", lambda session: None)
+        monkeypatch.setattr(server, "_start_agent_build", lambda sid, session: None)
+        monkeypatch.setattr(
+            server,
+            "_run_prompt_submit",
+            lambda *args, **kwargs: calls.__setitem__(
+                "run_prompt", calls["run_prompt"] + 1
+            ),
+        )
+
+        submit = server.handle_request(
+            {
+                "id": "1",
+                "method": "prompt.submit",
+                "params": {"session_id": "sid", "text": "first message"},
+            }
+        )
+        assert submit.get("result"), f"got error: {submit.get('error')}"
+
+        threads[0].target()
+
+        # The message was DELIVERED, not dropped, and no error event fired.
+        assert calls["run_prompt"] == 1
+        error_events = [e for e in emitted if e and e[0] == "error"]
+        assert not error_events, f"unexpected error events: {error_events}"
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_slow_agent_build_emits_keyed_progress_notice(monkeypatch):
+    """Past the slow threshold the patient wait must tell the user once
+    (keyed notification.show) and clear the notice when the build lands —
+    a long wait is acceptable, a silent one is not."""
+    threads = []
+    emitted = []
+    calls = {"run_prompt": 0}
+
+    class _FakeThread:
+        def __init__(self, target=None, daemon=None):
+            self.target = target
+            threads.append(self)
+
+        def start(self):
+            return None
+
+        def is_alive(self):
+            return True
+
+    ready = threading.Event()
+    session = _session(agent_ready=ready)
+    session["agent"] = None
+    server._sessions["sid"] = session
+
+    slices = {"n": 0}
+
+    class _SlowReady:
+        def wait(self, timeout=None):
+            slices["n"] += 1
+            if slices["n"] >= 3:
+                ready.set()
+                session["agent"] = types.SimpleNamespace()
+                return True
+            return False
+
+        def is_set(self):
+            return ready.is_set()
+
+    session["agent_ready"] = _SlowReady()
+
+    try:
+        monkeypatch.setattr(server.threading, "Thread", _FakeThread)
+        # Every wait slice lands past the slow threshold.
+        monkeypatch.setattr(server, "_AGENT_BUILD_SLOW_NOTICE_AFTER", 0.0)
+        monkeypatch.setattr(server, "_emit", lambda *args, **kwargs: emitted.append(args))
+        monkeypatch.setattr(server, "_ensure_session_db_row", lambda session: None)
+        monkeypatch.setattr(server, "_persist_branch_seed", lambda session: None)
+        monkeypatch.setattr(server, "_start_agent_build", lambda sid, session: None)
+        monkeypatch.setattr(
+            server,
+            "_run_prompt_submit",
+            lambda *args, **kwargs: calls.__setitem__(
+                "run_prompt", calls["run_prompt"] + 1
+            ),
+        )
+
+        submit = server.handle_request(
+            {
+                "id": "1",
+                "method": "prompt.submit",
+                "params": {"session_id": "sid", "text": "first message"},
+            }
+        )
+        assert submit.get("result"), f"got error: {submit.get('error')}"
+
+        threads[0].target()
+
+        assert calls["run_prompt"] == 1
+        shows = [e for e in emitted if e and e[0] == "notification.show" and e[1] == "sid"]
+        clears = [e for e in emitted if e and e[0] == "notification.clear" and e[1] == "sid"]
+        # Exactly one keyed notice, replaced-in-place semantics, then cleared.
+        assert len(shows) == 1, f"expected one slow-build notice, got: {shows}"
+        assert shows[0][2].get("key") == server._AGENT_BUILD_SLOW_NOTICE_KEY
+        assert len(clears) == 1 and clears[0][2].get("key") == server._AGENT_BUILD_SLOW_NOTICE_KEY
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_agent_build_failure_surfaces_error_and_drops_turn(monkeypatch):
+    """When the build itself FAILS (agent_error set when ready fires), the
+    prompt must not run and the failure must reach the client as a visible
+    error event — never a silent drop."""
+    threads = []
+    emitted = []
+    calls = {"run_prompt": 0}
+
+    class _FakeThread:
+        def __init__(self, target=None, daemon=None):
+            self.target = target
+            threads.append(self)
+
+        def start(self):
+            return None
+
+        def is_alive(self):
+            return True
+
+    ready = threading.Event()
+    ready.set()  # build finished...
+    session = _session(agent_ready=ready)
+    session["agent"] = None
+    session["agent_error"] = "No LLM provider configured"  # ...but failed
+    server._sessions["sid"] = session
+
+    try:
+        monkeypatch.setattr(server.threading, "Thread", _FakeThread)
+        monkeypatch.setattr(server, "_emit", lambda *args, **kwargs: emitted.append(args))
+        monkeypatch.setattr(server, "_ensure_session_db_row", lambda session: None)
+        monkeypatch.setattr(server, "_persist_branch_seed", lambda session: None)
+        monkeypatch.setattr(server, "_start_agent_build", lambda sid, session: None)
+        monkeypatch.setattr(
+            server,
+            "_run_prompt_submit",
+            lambda *args, **kwargs: calls.__setitem__(
+                "run_prompt", calls["run_prompt"] + 1
+            ),
+        )
+
+        submit = server.handle_request(
+            {
+                "id": "1",
+                "method": "prompt.submit",
+                "params": {"session_id": "sid", "text": "first message"},
+            }
+        )
+        assert submit.get("result"), f"got error: {submit.get('error')}"
+
+        threads[0].target()
+
+        assert calls["run_prompt"] == 0
+        assert session["running"] is False
+        # #71184 upgraded failure delivery from a bare "error" event to a
+        # terminal message.complete frame (status=error, recoverable) so
+        # failed turns are retained as replayable inflight snapshots. The
+        # contract this test pins is unchanged: the build failure must reach
+        # the client VISIBLY — never a silent drop.
+        failure_frames = [
+            e
+            for e in emitted
+            if e
+            and e[0] in ("error", "message.complete")
+            and e[1] == "sid"
+            and (
+                "No LLM provider configured" in str(e[2].get("message", ""))
+                or "No LLM provider configured" in str(e[2].get("error", ""))
+                or "No LLM provider configured" in str(e[2].get("text", ""))
+            )
+        ]
+        assert len(failure_frames) == 1, f"expected one visible failure frame, got: {emitted}"
+        frame = failure_frames[0]
+        if frame[0] == "message.complete":
+            assert frame[2].get("status") == "error"
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_dead_build_thread_fails_fast_not_full_cap(monkeypatch):
+    """A build thread that died without setting agent_ready means the build
+    died hard — the waiter must fail promptly with a visible error instead of
+    sitting out the full wait cap on a corpse."""
+    emitted = []
+
+    class _DeadThread:
+        def is_alive(self):
+            return False
+
+    ready = threading.Event()  # never set
+    session = _session(agent_ready=ready)
+    session["agent"] = None
+    session["running"] = True
+    session["_agent_build_thread"] = _DeadThread()
+    session["agent_error"] = "agent init failed: boom"
+    server._sessions["sid"] = session
+
+    try:
+        monkeypatch.setattr(server, "_emit", lambda *args, **kwargs: emitted.append(args))
+        # Short slices so the test is fast; the dead-thread check fires on the
+        # first empty slice, far below the cap.
+        monkeypatch.setattr(server, "_AGENT_BUILD_WAIT_SLICE", 0.01)
+
+        start = time.monotonic()
+        err = server._wait_agent_for_prompt(session, "rid-1", "sid")
+        elapsed = time.monotonic() - start
+
+        assert err is not None
+        assert "boom" in (err.get("error") or {}).get("message", "")
+        assert elapsed < 5.0, f"dead-thread detection took {elapsed:.1f}s"
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_wait_agent_for_prompt_honors_cancel_mid_wait(monkeypatch):
+    """A cancel arriving during the patient wait must end it promptly and
+    return None (the caller's cancel branch owns the user-visible event)."""
+    ready = threading.Event()  # never set
+    session = _session(agent_ready=ready)
+    session["agent"] = None
+    session["running"] = True
+    server._sessions["sid"] = session
+
+    try:
+        monkeypatch.setattr(server, "_AGENT_BUILD_WAIT_SLICE", 0.01)
+
+        def cancel_soon():
+            time.sleep(0.05)
+            with session["history_lock"]:
+                session["_turn_cancel_requested"] = True
+
+        canceller = threading.Thread(target=cancel_soon)
+        canceller.start()
+        start = time.monotonic()
+        err = server._wait_agent_for_prompt(session, "rid-1", "sid")
+        elapsed = time.monotonic() - start
+        canceller.join()
+
+        assert err is None
+        assert elapsed < 5.0, f"cancel honored only after {elapsed:.1f}s"
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_agent_build_wait_cap_config_override(monkeypatch):
+    """agent.build_wait_timeout in config.yaml overrides the default cap;
+    invalid/absent values fall back to 600s."""
+    monkeypatch.setattr(server, "_load_cfg", lambda: {"agent": {"build_wait_timeout": 90}})
+    assert server._agent_build_wait_cap() == 90.0
+
+    monkeypatch.setattr(server, "_load_cfg", lambda: {"agent": {}})
+    assert server._agent_build_wait_cap() == 600.0
+
+    monkeypatch.setattr(server, "_load_cfg", lambda: {"agent": {"build_wait_timeout": 0}})
+    assert server._agent_build_wait_cap() == 600.0
+
+    monkeypatch.setattr(server, "_load_cfg", lambda: {"agent": {"build_wait_timeout": "nonsense"}})
+    assert server._agent_build_wait_cap() == 600.0
+
+
+def test_wait_agent_for_prompt_expires_at_cap(monkeypatch):
+    """A genuinely hung build (thread alive, never ready) still fails at the
+    bounded cap with a message that tells the user their text was not sent."""
+    class _AliveThread:
+        def is_alive(self):
+            return True
+
+    ready = threading.Event()  # never set
+    session = _session(agent_ready=ready)
+    session["agent"] = None
+    session["running"] = True
+    session["_agent_build_thread"] = _AliveThread()
+    server._sessions["sid"] = session
+
+    try:
+        monkeypatch.setattr(server, "_AGENT_BUILD_WAIT_SLICE", 0.01)
+        monkeypatch.setattr(server, "_agent_build_wait_cap", lambda: 0.05)
+
+        err = server._wait_agent_for_prompt(session, "rid-1", "sid")
+
+        assert err is not None
+        message = (err.get("error") or {}).get("message", "")
+        assert "timed out" in message and "was not sent" in message
+    finally:
+        server._sessions.pop("sid", None)
+
+
 def test_clear_pending_without_sid_clears_all():
     """_clear_pending(None) is the shutdown path — must still release
     every pending prompt regardless of owning session."""
@@ -8199,7 +8864,9 @@ def test_mirror_slash_compress_honors_here_argument(monkeypatch):
 
 # ---------------------------------------------------------------------------
 # session.create / session.close race: fast /new churn must not orphan the
-# slash_worker subprocess or the global approval-notify registration.
+# global approval-notify registration. (Slash workers are no longer pre-warmed
+# by the build thread — slash.exec spawns them on demand — so the build thread
+# must ALSO never construct one here.)
 # ---------------------------------------------------------------------------
 
 
@@ -8207,12 +8874,13 @@ def test_mirror_slash_compress_honors_here_argument(monkeypatch):
 def test_session_create_close_race_does_not_orphan_worker(monkeypatch):
     """Regression guard: if session.close runs while session.create's
     _build thread is still constructing the agent, the build thread
-    must detect the orphan and clean up the slash_worker + notify
-    registration it's about to install.  Without the cleanup those
-    resources leak — the subprocess stays alive until atexit and the
-    notify callback lingers in the global registry."""
+    must detect the orphan and unregister the notify registration it's
+    about to install.  It must also never pre-warm a slash worker (each
+    worker forks the full stdio MCP fleet; spawn is on-demand in
+    slash.exec) — a worker constructed here would be a regression."""
     import threading
 
+    created_workers: list[str] = []
     closed_workers: list[str] = []
     unregistered_keys: list[str] = []
 
@@ -8220,6 +8888,7 @@ def test_session_create_close_race_does_not_orphan_worker(monkeypatch):
         def __init__(self, key, model, profile_home=None):
             self.key = key
             self._closed = False
+            created_workers.append(key)
 
         def close(self):
             self._closed = True
@@ -8303,23 +8972,24 @@ def test_session_create_close_race_does_not_orphan_worker(monkeypatch):
     )
     assert close_resp.get("result", {}).get("closed") is True
 
-    # At this point session.close saw slash_worker=None (not yet
-    # installed) so it didn't close anything.  Release the build thread
-    # and let it finish — it should detect the orphan and clean up the
-    # worker it just allocated + unregister the notify.
+    # At this point session.close saw slash_worker=None (never eagerly
+    # installed) so it had nothing to close.  Release the build thread
+    # and let it finish — it should detect the orphan and unregister
+    # the notify, without ever having constructed a worker.
     release_build.set()
 
     # Give the build thread a moment to run through its finally.
     for _ in range(100):
-        if closed_workers:
+        if unregistered_keys:
             break
         import time
 
         time.sleep(0.02)
 
-    assert (
-        len(closed_workers) == 1
-    ), f"orphan worker was not cleaned up — closed_workers={closed_workers}"
+    assert created_workers == [], (
+        f"build thread pre-warmed a slash worker (spawn must stay on-demand "
+        f"in slash.exec) — created_workers={created_workers}"
+    )
     # Notify may be unregistered by both session.close (unconditional)
     # and the orphan-cleanup path; the key guarantee is that the build
     # thread does at least one unregister call (any prior close
@@ -8333,8 +9003,9 @@ def test_session_create_close_race_does_not_orphan_worker(monkeypatch):
 @pytest.mark.real_agent_prewarm
 def test_session_create_no_race_keeps_worker_alive(monkeypatch):
     """Regression guard: when session.close does NOT race, the build
-    thread must install the worker + notify normally and leave them
-    alone (no over-eager cleanup)."""
+    thread must install the notify normally and leave it alone (no
+    over-eager cleanup) — and must not pre-warm a slash worker (spawn
+    is on-demand in slash.exec)."""
     closed_workers: list[str] = []
     unregistered_keys: list[str] = []
 
@@ -8417,8 +9088,9 @@ def test_session_create_no_race_keeps_worker_alive(monkeypatch):
             own_unregistered == []
         ), f"build thread unregistered its own notify despite no race: {own_unregistered}"
 
-        # Session should have the live worker installed.
-        assert session.get("slash_worker") is not None
+        # No pre-warmed worker: slash.exec spawns on demand, so a fresh
+        # session that hasn't run a worker-routed command carries None.
+        assert session.get("slash_worker") is None
     finally:
         # Cleanup + restore sibling sessions we snapshotted.
         server._sessions.clear()
@@ -8672,6 +9344,536 @@ def test_session_delete_success_returns_deleted_id(monkeypatch):
     assert str(captured["sessions_dir"]).endswith("sessions")
 
 
+
+
+# --------------------------------------------------------------------------
+# session.* profile scoping (app-global remote mode) — #62503
+# --------------------------------------------------------------------------
+
+
+def test_session_list_honors_params_profile_opens_profile_db(monkeypatch, tmp_path):
+    """Issue #62503: session.list must read the profile's state.db, not launch."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+    (profile_home / "state.db").write_bytes(b"")
+    seen: dict = {}
+
+    class LaunchDB:
+        def list_sessions_rich(self, **kwargs):
+            seen["launch"] = True
+            return [{"id": "launch-1", "source": "tui", "title": "L"}]
+
+    class ProfileDB:
+        def __init__(self, db_path=None):
+            seen["db_path"] = db_path
+
+        def list_sessions_rich(self, **kwargs):
+            seen["profile"] = True
+            return [
+                {
+                    "id": "ml-1",
+                    "source": "tui",
+                    "title": "M",
+                    "preview": "",
+                    "started_at": 1,
+                    "message_count": 1,
+                }
+            ]
+
+        def close(self):
+            seen["closed"] = True
+
+    monkeypatch.setattr(server, "_profile_home", lambda p: profile_home if p == "mlperf" else None)
+    monkeypatch.setattr(server, "_get_db", lambda: LaunchDB())
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB)
+
+    resp = server.handle_request(
+        {
+            "id": "1",
+            "method": "session.list",
+            "params": {"profile": "mlperf", "limit": 5},
+        }
+    )
+    assert "result" in resp, resp
+    assert resp["result"]["sessions"][0]["id"] == "ml-1"
+    assert seen.get("profile") is True
+    assert seen.get("launch") is None
+    assert str(seen.get("db_path")).endswith("state.db")
+    assert seen.get("closed") is True
+
+
+def test_session_most_recent_honors_params_profile(monkeypatch, tmp_path):
+    """Issue #62503: session.most_recent must not return the launch profile tip."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+
+    class LaunchDB:
+        def list_sessions_rich(self, **kwargs):
+            return [{"id": "launch-tip", "source": "tui", "title": "L", "started_at": 9}]
+
+    class ProfileDB2:
+        def __init__(self, db_path=None):
+            self.db_path = db_path
+
+        def list_sessions_rich(self, **kwargs):
+            return [
+                {"id": "tool-noise", "source": "tool", "title": "t", "started_at": 9},
+                {"id": "ml-tip", "source": "desktop", "title": "M", "started_at": 3},
+            ]
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(server, "_profile_home", lambda p: profile_home if p == "mlperf" else None)
+    monkeypatch.setattr(server, "_get_db", lambda: LaunchDB())
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB2)
+
+    resp = server.handle_request(
+        {
+            "id": "1",
+            "method": "session.most_recent",
+            "params": {"profile": "mlperf"},
+        }
+    )
+    assert resp["result"]["session_id"] == "ml-tip"
+
+
+def test_session_create_reports_requested_profile_name(monkeypatch, tmp_path):
+    """Issue #62503: session.create info.profile_name must not always be launch."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+
+    def _clear():
+        for session in list(server._sessions.values()):
+            server._teardown_session(session)
+        server._sessions.clear()
+
+    monkeypatch.setattr(server, "_start_agent_build", lambda *a, **k: None)
+    monkeypatch.setattr(server, "_schedule_agent_build", lambda *a, **k: None)
+    monkeypatch.setattr(server, "_schedule_session_cap_enforcement", lambda *a, **k: None)
+    monkeypatch.setattr(server, "_completion_cwd", lambda params=None: str(tmp_path))
+    monkeypatch.setattr(server, "_profile_home", lambda p: profile_home if p == "mlperf" else None)
+    monkeypatch.setattr(server, "_current_profile_name", lambda: "default")
+    monkeypatch.setattr(server, "_claim_active_session_slot", lambda *a, **k: (None, None))
+    _clear()
+    try:
+        resp = server._methods["session.create"]("r1", {"profile": "mlperf", "cols": 80})
+        assert "result" in resp, resp
+        assert resp["result"]["info"]["profile_name"] == "mlperf"
+        sid = resp["result"]["session_id"]
+        assert server._sessions[sid]["profile_home"] == str(profile_home)
+    finally:
+        _clear()
+
+
+def test_session_delete_honors_params_profile_sessions_dir(monkeypatch, tmp_path):
+    """Issue #62503: delete must target the profile state.db + sessions dir."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    (profile_home / "sessions").mkdir(parents=True)
+    captured: dict = {}
+
+    class ProfileDB:
+        def __init__(self, db_path=None):
+            captured["db_path"] = db_path
+
+        def delete_session(self, sid, sessions_dir=None):
+            captured["sid"] = sid
+            captured["sessions_dir"] = sessions_dir
+            return True
+
+        def close(self):
+            captured["closed"] = True
+
+    monkeypatch.setattr(server, "_profile_home", lambda p: profile_home if p == "mlperf" else None)
+    monkeypatch.setattr(server, "_get_db", lambda: None)
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB)
+
+    resp = server.handle_request(
+        {
+            "id": "1",
+            "method": "session.delete",
+            "params": {"session_id": "old-ml", "profile": "mlperf"},
+        }
+    )
+    assert "result" in resp, resp
+    assert resp["result"] == {"deleted": "old-ml"}
+    assert str(captured["db_path"]).endswith("state.db")
+    assert Path(captured["sessions_dir"]) == profile_home / "sessions"
+    assert captured.get("closed") is True
+
+
+def test_session_title_uses_session_profile_db_not_launch(monkeypatch, tmp_path):
+    """session.title on a non-launch profile session must not touch launch DB."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+    seen: dict = {}
+
+    class LaunchDB:
+        def get_session_title(self, _key):
+            seen["launch_read"] = True
+            return "from-launch"
+
+        def set_session_title(self, _key, _title):
+            seen["launch_write"] = True
+            return True
+
+        def get_session(self, _key):
+            return {"id": _key, "title": "from-launch"}
+
+    class ProfileDB:
+        def __init__(self, db_path=None):
+            self.db_path = db_path
+            seen["db_path"] = db_path
+
+        def get_session_title(self, _key):
+            return seen.get("title")
+
+        def get_session(self, _key):
+            if "title" in seen:
+                return {"id": _key, "title": seen["title"]}
+            return None
+
+        def set_session_title(self, _key, title):
+            seen["title"] = title
+            seen["profile_write"] = True
+            return True
+
+        def close(self):
+            seen["closed"] = True
+
+    server._sessions["sid"] = {
+        "session_key": "ml-sess",
+        "history": [],
+        "history_lock": __import__("threading").Lock(),
+        "running": False,
+        "pending_title": None,
+        "profile_home": str(profile_home),
+        "agent": None,
+        "created_at": 1.0,
+        "last_active": 1.0,
+    }
+    monkeypatch.setattr(server, "_get_db", lambda: LaunchDB())
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB)
+    try:
+        set_resp = server.handle_request(
+            {
+                "id": "1",
+                "method": "session.title",
+                "params": {"session_id": "sid", "title": "profile-title"},
+            }
+        )
+        assert "result" in set_resp, set_resp
+        assert set_resp["result"]["title"] == "profile-title"
+        assert seen.get("profile_write") is True
+        assert seen.get("launch_write") is None
+        assert str(seen.get("db_path")).endswith("state.db")
+
+        get_resp = server.handle_request(
+            {"id": "2", "method": "session.title", "params": {"session_id": "sid"}}
+        )
+        assert get_resp["result"]["title"] == "profile-title"
+        assert seen.get("launch_read") is None
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_session_history_uses_session_profile_db(monkeypatch, tmp_path):
+    """session.history must read durable messages from the profile state.db."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+    seen: dict = {}
+
+    class LaunchDB:
+        def get_messages_as_conversation(self, _key, include_ancestors=True):
+            seen["launch"] = True
+            return [{"role": "user", "content": "launch"}]
+
+    class ProfileDB:
+        def __init__(self, db_path=None):
+            seen["db_path"] = db_path
+
+        def get_messages_as_conversation(self, _key, include_ancestors=True):
+            seen["profile"] = True
+            return [{"role": "user", "content": "from-profile"}]
+
+        def close(self):
+            seen["closed"] = True
+
+    server._sessions["sid"] = {
+        "session_key": "ml-sess",
+        "history": [{"role": "user", "content": "mem"}],
+        "history_lock": __import__("threading").Lock(),
+        "running": False,
+        "profile_home": str(profile_home),
+        "agent": None,
+        "created_at": 1.0,
+        "last_active": 1.0,
+    }
+    monkeypatch.setattr(server, "_get_db", lambda: LaunchDB())
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB)
+    try:
+        resp = server.handle_request(
+            {"id": "1", "method": "session.history", "params": {"session_id": "sid"}}
+        )
+        assert "result" in resp, resp
+        assert seen.get("profile") is True
+        assert seen.get("launch") is None
+        # Count comes from profile-backed conversation (1 msg), not bare mem list alone.
+        assert resp["result"]["count"] == 1
+        texts = []
+        for m in resp["result"]["messages"]:
+            texts.append(str(m))
+        assert any("from-profile" in t for t in texts) or resp["result"]["count"] == 1
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_session_status_uses_session_profile_db(monkeypatch, tmp_path):
+    """session.status must load meta from the session profile state.db."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+    seen: dict = {}
+
+    class LaunchDB:
+        def get_session(self, _key):
+            seen["launch"] = True
+            return {"id": _key, "title": "launch-title", "started_at": 1}
+
+    class ProfileDB:
+        def __init__(self, db_path=None):
+            seen["db_path"] = db_path
+
+        def get_session(self, _key):
+            seen["profile"] = True
+            return {"id": _key, "title": "profile-title", "started_at": 42}
+
+        def close(self):
+            seen["closed"] = True
+
+    server._sessions["sid"] = {
+        "session_key": "ml-sess",
+        "history": [],
+        "history_lock": __import__("threading").Lock(),
+        "running": False,
+        "profile_home": str(profile_home),
+        "agent": None,
+        "created_at": 1.0,
+        "last_active": 1.0,
+    }
+    monkeypatch.setattr(server, "_get_db", lambda: LaunchDB())
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB)
+    try:
+        resp = server.handle_request(
+            {"id": "1", "method": "session.status", "params": {"session_id": "sid"}}
+        )
+        assert "result" in resp, resp
+        assert "profile-title" in resp["result"]["output"]
+        assert seen.get("profile") is True
+        assert seen.get("launch") is None
+    finally:
+        server._sessions.pop("sid", None)
+
+
+def test_teardown_ends_session_in_profile_db(monkeypatch, tmp_path):
+    """_teardown_session must end_session on the profile store, not launch."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+    seen: dict = {}
+
+    class LaunchDB:
+        def get_session(self, _key):
+            seen["launch"] = True
+            return {"id": _key, "source": "tui"}
+
+        def end_session(self, _key, _reason):
+            seen["launch_end"] = True
+
+    class ProfileDB:
+        def __init__(self, db_path=None):
+            seen["db_path"] = db_path
+
+        def get_session(self, _key):
+            seen["profile"] = True
+            return {"id": _key, "source": "tui"}
+
+        def end_session(self, key, reason):
+            seen["ended"] = (key, reason)
+
+        def close(self):
+            seen["closed"] = True
+
+    monkeypatch.setattr(server, "_get_db", lambda: LaunchDB())
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB)
+    session = {
+        "session_key": "ml-sess",
+        "profile_home": str(profile_home),
+        "agent": None,
+        "history": [],
+        "source": "tui",
+    }
+    server._teardown_session(session, end_reason="closed")
+    assert seen.get("ended") == ("ml-sess", "closed")
+    assert seen.get("launch_end") is None
+    assert seen.get("launch") is None
+    assert str(seen.get("db_path")).endswith("state.db")
+
+
+def test_session_branch_writes_to_parent_profile_db(monkeypatch, tmp_path):
+    """session.branch must copy history into the parent's profile state.db."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+    seen: dict = {"msgs": []}
+
+    class LaunchDB:
+        def get_session_title(self, _key):
+            seen["launch"] = True
+            return "L"
+
+        def create_session(self, *a, **k):
+            seen["launch_create"] = True
+
+        def append_message(self, **k):
+            seen["launch_msg"] = True
+
+        def set_session_title(self, *a, **k):
+            return True
+
+    class ProfileDB:
+        def __init__(self, db_path=None):
+            seen["db_path"] = db_path
+            seen.setdefault("inits", 0)
+            seen["inits"] += 1
+
+        def get_session_title(self, _key):
+            return "parent"
+
+        def get_next_title_in_lineage(self, current):
+            return f"{current} (branch)"
+
+        def create_session(self, new_key, **kwargs):
+            seen["created"] = new_key
+            seen["parent"] = kwargs.get("parent_session_id")
+            seen["profile_name"] = kwargs.get("profile_name")
+
+        def append_message(self, **kwargs):
+            seen["msgs"].append(kwargs)
+
+        def set_session_title(self, key, title):
+            seen["title"] = (key, title)
+            return True
+
+        def get_session(self, key):
+            return {"id": key, "cwd": str(tmp_path)}
+
+        def update_session_cwd(self, *a, **k):
+            return None
+
+        def close(self):
+            seen["closed"] = True
+
+    class FakeAgent:
+        def __init__(self):
+            self.model = "test-model"
+            self.session_id = None
+
+    parent = {
+        "session_key": "parent-key",
+        "history": [{"role": "user", "content": "hi"}],
+        "history_lock": __import__("threading").Lock(),
+        "running": False,
+        "cols": 80,
+        "profile_home": str(profile_home),
+        "source": "tui",
+        "agent": FakeAgent(),
+        "created_at": 1.0,
+        "last_active": 1.0,
+        "cwd": str(tmp_path),
+    }
+    server._sessions["parent"] = parent
+    monkeypatch.setattr(server, "_get_db", lambda: LaunchDB())
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB)
+    monkeypatch.setattr(server, "_claim_active_session_slot", lambda *a, **k: (None, None))
+
+    def _fake_make_agent(*a, **k):
+        seen["agent_session_db"] = k.get("session_db")
+        return FakeAgent()
+
+    monkeypatch.setattr(server, "_make_agent", _fake_make_agent)
+    monkeypatch.setattr(server, "_set_session_context", lambda *a, **k: {})
+    monkeypatch.setattr(server, "_clear_session_context", lambda *a, **k: None)
+    monkeypatch.setattr(server, "_resolve_model", lambda: "test-model")
+    monkeypatch.setattr(server, "_session_cwd", lambda s: str(tmp_path))
+    monkeypatch.setattr(server, "_register_session_cwd", lambda *a, **k: None)
+    monkeypatch.setattr(server, "_attach_worker", lambda *a, **k: None)
+    try:
+        resp = server.handle_request(
+            {
+                "id": "1",
+                "method": "session.branch",
+                "params": {"session_id": "parent", "name": "forked"},
+            }
+        )
+        assert "result" in resp, resp
+        assert seen.get("created")
+        assert seen.get("parent") == "parent-key"
+        # The branch row is self-describing: stamped with the parent's owning
+        # profile, not left NULL for aggregators to mis-tag as "default".
+        assert seen.get("profile_name") == "mlperf"
+        assert seen.get("title") == (seen["created"], "forked")
+        assert len(seen["msgs"]) == 1
+        assert seen.get("launch") is None
+        assert seen.get("launch_create") is None
+        child_sid = resp["result"]["session_id"]
+        assert server._sessions[child_sid]["profile_home"] == str(profile_home)
+        # The branched AGENT must be bound to the parent profile's state.db —
+        # not just the row. Otherwise its own flushes (and a later compression
+        # rotation) land on the launch db, splitting the lineage again.
+        assert isinstance(seen.get("agent_session_db"), ProfileDB)
+    finally:
+        for k in list(server._sessions):
+            server._sessions.pop(k, None)
+
+
+def test_pending_title_finalizer_uses_session_profile_db(monkeypatch, tmp_path):
+    """Post-turn pending_title must land in the session profile store."""
+    profile_home = tmp_path / "profiles" / "mlperf"
+    profile_home.mkdir(parents=True)
+    seen: dict = {}
+
+    class LaunchDB:
+        def set_session_title(self, _key, _title):
+            seen["launch"] = True
+            return True
+
+    class ProfileDB:
+        def __init__(self, db_path=None):
+            seen["db_path"] = db_path
+
+        def set_session_title(self, key, title):
+            seen["set"] = (key, title)
+            return True
+
+        def close(self):
+            seen["closed"] = True
+
+    monkeypatch.setattr(server, "_get_db", lambda: LaunchDB())
+    monkeypatch.setattr("hermes_state.SessionDB", ProfileDB)
+    session = {
+        "session_key": "ml-sess",
+        "pending_title": "deferred-title",
+        "profile_home": str(profile_home),
+        "history": [],
+    }
+    # Exercise the same close pattern as the post-turn finalizer.
+    with server._session_db(session) as db:
+        assert db is not None
+        assert db.set_session_title(session["session_key"], session["pending_title"])
+        session["pending_title"] = None
+    assert seen.get("set") == ("ml-sess", "deferred-title")
+    assert seen.get("launch") is None
+    assert session["pending_title"] is None
+
+
 # --------------------------------------------------------------------------
 # model.options — curated-list parity with `hermes model` and classic /model
 # --------------------------------------------------------------------------
@@ -8862,6 +10064,7 @@ def test_model_options_preserves_canonical_custom_row_after_agent_init(monkeypat
     canonical.assert_called_once_with(
         base_url="http://127.0.0.1:11434/v1",
         config_provider="custom:local-ollama",
+        model="qwen3.6:35b-65k",
     )
 
 
@@ -8964,9 +10167,7 @@ def test_prompt_submit_auto_titles_session_on_complete(monkeypatch):
         api_key = object()
         api_mode = "codex_responses"
 
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             return {
                 "final_response": "Rome was founded in 753 BC.",
                 "messages": [
@@ -9009,9 +10210,7 @@ def test_prompt_submit_skips_auto_title_when_interrupted(monkeypatch):
     """maybe_auto_title must NOT be called when the agent was interrupted."""
 
     class _Agent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             return {
                 "final_response": "partial answer",
                 "interrupted": True,
@@ -9041,9 +10240,7 @@ def test_prompt_submit_skips_auto_title_when_response_empty(monkeypatch):
     """maybe_auto_title must NOT be called when the agent returns an empty reply."""
 
     class _Agent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             return {
                 "final_response": "",
                 "messages": [],
@@ -9074,9 +10271,7 @@ def test_prompt_submit_surfaces_backend_error_as_visible_text(monkeypatch):
     instead of emitting a blank message.complete turn."""
 
     class _Agent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             return {
                 "final_response": None,
                 "messages": [],
@@ -9121,9 +10316,7 @@ def test_prompt_submit_preserves_empty_response_without_error(monkeypatch):
     semantics owned by downstream handlers."""
 
     class _Agent:
-        def run_conversation(
-            self, prompt, conversation_history=None, stream_callback=None
-        ):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             return {
                 "final_response": None,
                 "messages": [],
@@ -9286,7 +10479,7 @@ def test_session_activate_returns_inflight_stream_before_completion(monkeypatch)
     class _Agent:
         model = "model-live"
 
-        def run_conversation(self, prompt, conversation_history=None, stream_callback=None):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             assert prompt == "write a long answer"
             assert conversation_history == []
             stream_callback("partial ")
@@ -10610,7 +11803,7 @@ def test_notification_poller_delivers_completion(monkeypatch):
     emitted = []
 
     class _Agent:
-        def run_conversation(self, prompt, conversation_history=None, stream_callback=None):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             turns.append(prompt)
             return {
                 "final_response": "ok",
@@ -10681,7 +11874,7 @@ def test_notification_poller_skips_consumed(monkeypatch):
     turns = []
 
     class _Agent:
-        def run_conversation(self, prompt, conversation_history=None, stream_callback=None):
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
             turns.append(prompt)
             return {"final_response": "ok", "messages": []}
 
@@ -11270,7 +12463,8 @@ def test_attach_worker_stores_worker_on_live_session():
 
 def test_restart_slash_worker_closes_orphan_when_session_reaped(monkeypatch):
     """Post-turn restart of a session reaped mid-flight (e.g. close_on_disconnect
-    fired while `running` flipped false) must close the fresh worker, not orphan it."""
+    fired while `running` flipped false) must close both the stale worker and
+    the fresh replacement, not orphan either."""
     closed = []
 
     class _FakeWorker:
@@ -11282,11 +12476,14 @@ def test_restart_slash_worker_closes_orphan_when_session_reaped(monkeypatch):
 
     monkeypatch.setattr(server, "_SlashWorker", _FakeWorker)
     server._sessions.pop("reaped", None)
-    reaped = {"session_key": "k"}  # not in _sessions -> torn down concurrently
+    # not in _sessions -> torn down concurrently; carries a live worker so the
+    # restart path actually runs (a workerless session is a restart no-op now)
+    reaped = {"session_key": "k", "slash_worker": _FakeWorker()}
     server._restart_slash_worker("reaped", reaped)
 
-    assert closed == [True]
-    assert reaped.get("slash_worker") is None
+    # stale worker closed by the restart, fresh worker closed by _attach_worker
+    # (sid no longer maps to this session)
+    assert closed == [True, True]
     assert "reaped" not in server._sessions
 
 
@@ -11299,15 +12496,95 @@ def test_restart_slash_worker_stores_on_live_session(monkeypatch):
             pass
 
     monkeypatch.setattr(server, "_SlashWorker", _FakeWorker)
-    live = {"session_key": "k", "slash_worker": None}
+    old_worker = _FakeWorker()
+    live = {"session_key": "k", "slash_worker": old_worker}
     server._sessions["live-restart"] = live
     try:
         server._restart_slash_worker("live-restart", live)
         assert isinstance(live["slash_worker"], _FakeWorker)
+        assert live["slash_worker"] is not old_worker
     finally:
         server._sessions.pop("live-restart", None)
 
 
+def test_restart_slash_worker_noop_without_worker(monkeypatch):
+    """A session that never spawned a worker (slash.exec not used yet) must
+    stay workerless across a restart — spawning here would fork the per-worker
+    stdio MCP fleet for sessions that never run worker-routed commands."""
+    spawned = []
+
+    class _FakeWorker:
+        def __init__(self, *a, **k):
+            spawned.append(True)
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(server, "_SlashWorker", _FakeWorker)
+    live = {"session_key": "k", "slash_worker": None}
+    server._sessions["lazy-noop"] = live
+    try:
+        server._restart_slash_worker("lazy-noop", live)
+        assert spawned == []
+        assert live["slash_worker"] is None
+    finally:
+        server._sessions.pop("lazy-noop", None)
+
+
+def test_slash_exec_concurrent_first_use_spawns_single_worker(monkeypatch):
+    """With eager pre-warm removed, slash.exec is the only spawn path — two
+    concurrent worker-routed commands on a fresh session must not each fork a
+    full MCP-fleet worker. The per-session spawn lock serializes first use."""
+    import time as _time
+
+    spawned = []
+    barrier = threading.Barrier(2, timeout=5)
+
+    class _SlowWorker:
+        def __init__(self, *a, **k):
+            spawned.append(self)
+            _time.sleep(0.05)  # widen the None-observation window
+
+        def run(self, cmd):
+            return f"ran {cmd}"
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(server, "_SlashWorker", _SlowWorker)
+    monkeypatch.setattr(server, "_mirror_slash_side_effects", lambda *a, **k: None)
+    session = _session(slash_worker=None)
+    server._sessions["race-spawn"] = session
+
+    results = []
+
+    def _exec(n):
+        barrier.wait()
+        resp = server.handle_request(
+            {
+                "id": str(n),
+                "method": "slash.exec",
+                "params": {"command": "/context", "session_id": "race-spawn"},
+            }
+        )
+        results.append(resp)
+
+    try:
+        threads = [threading.Thread(target=_exec, args=(i,)) for i in range(2)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+        assert len(spawned) == 1, (
+            f"concurrent slash.exec spawned {len(spawned)} workers — first-use "
+            f"spawn must be serialized per session"
+        )
+        assert session["slash_worker"] is spawned[0]
+        assert all("result" in r for r in results), results
+    finally:
+        server._sessions.pop("race-spawn", None)
+
+
 def test_session_close_rpc_claims_then_tears_down(monkeypatch):
     seen = []
     claimed = {"session_key": "k"}
@@ -12438,3 +13715,185 @@ def test_clarify_timeout_seconds_maps_non_positive_to_unlimited(monkeypatch, con
     monkeypatch.setattr("tools.clarify_gateway.get_clarify_timeout", lambda: configured)
 
     assert server._clarify_timeout_seconds() == expected
+
+
+def test_build_persist_message_with_image_refs_without_images_returns_text(monkeypatch):
+    """#70720: when no images are attached the persisted message is the raw
+    prompt — no @image directive prefix is introduced."""
+    assert server._build_persist_message_with_image_refs("what is this?", []) == "what is this?"
+    assert server._build_persist_message_with_image_refs("", []) == ""
+
+
+def test_build_persist_message_with_image_refs_appends_existing_paths(monkeypatch, tmp_path):
+    """Attached images that still exist on disk are persisted as trailing
+    ``@image:<path>`` directive lines so the desktop renders them after a
+    restart (instead of the vision-only enrichment that silently breaks)."""
+    img = tmp_path / "cat.png"
+    img.write_bytes(b"\x89PNG")
+
+    result = server._build_persist_message_with_image_refs("what is in this photo?", [str(img)])
+
+    assert result == f"what is in this photo?\n@image:{img}"
+
+
+def test_build_persist_message_keeps_the_caption_on_the_first_line(tmp_path):
+    """Session previews are the first 60 characters of the first user message,
+    so a leading directive would title the session with a truncated file path
+    in the sidebar, switcher, and command palette."""
+    img = tmp_path / "cat.png"
+    img.write_bytes(b"png")
+
+    result = server._build_persist_message_with_image_refs("what is in this photo?", [str(img)])
+
+    assert result.split("\n", 1)[0] == "what is in this photo?"
+
+
+def test_build_persist_message_with_image_refs_skips_missing_paths(monkeypatch, tmp_path):
+    """Only paths that still exist are persisted; a missing file must not
+    inject a dangling @image ref into the transcript."""
+    existing = tmp_path / "a.png"
+    existing.write_bytes(b"png")
+    missing = str(tmp_path / "gone.png")
+
+    result = server._build_persist_message_with_image_refs("compare them", [str(existing), missing])
+
+    assert result == f"compare them\n@image:{existing}"
+
+
+def test_build_persist_message_with_image_refs_without_text_is_refs_only(monkeypatch, tmp_path):
+    """A stand-alone attachment (no caption) persists as just the directive
+    line, so a bare image survives in history and is not dropped as empty."""
+    img = tmp_path / "only.png"
+    img.write_bytes(b"png")
+
+    assert server._build_persist_message_with_image_refs("", [str(img)]) == f"@image:{img}"
+
+
+def test_build_persist_message_quotes_paths_containing_spaces(tmp_path):
+    """The unquoted alternative in the directive pattern is ``\\S+``, so a path
+    with a space parses as a truncated ref with the tail left as loose text.
+    Desktop composer images live in the app's userData dir, which on macOS is
+    ``~/Library/Application Support/...`` — a space every time."""
+    img_dir = tmp_path / "Application Support" / "Hermes" / "composer-images"
+    img_dir.mkdir(parents=True)
+    img = img_dir / "cat.png"
+    img.write_bytes(b"png")
+
+    result = server._build_persist_message_with_image_refs("what is this?", [str(img)])
+
+    assert result == f"what is this?\n@image:`{img}`"
+
+
+def test_persist_user_message_mirrors_the_shape_sent_to_the_model(tmp_path):
+    """A native-vision turn sends ``content`` as a parts list, and the session
+    store ignores a plain-string override for a list payload. The override must
+    mirror the list shape (ref text + the original image parts) or it is
+    silently dropped and the attachment never reaches history."""
+    img = tmp_path / "cat.png"
+    img.write_bytes(b"png")
+    image_part = {"type": "image_url", "image_url": {"url": "data:image/png;base64,AAAA"}}
+    native_parts = [{"type": "text", "text": "api-only text"}, image_part]
+
+    override = server._build_persist_user_message("what is this?", [str(img)], native_parts)
+
+    assert override == [{"type": "text", "text": f"what is this?\n@image:{img}"}, image_part]
+
+
+def test_persist_user_message_stays_a_string_for_text_mode(tmp_path):
+    """Text-mode (vision-preprocessed) turns send a string, so the override
+    stays a string — the shape the session store rewrites directly."""
+    img = tmp_path / "cat.png"
+    img.write_bytes(b"png")
+
+    override = server._build_persist_user_message("what is this?", [str(img)], "enriched api-only text")
+
+    assert override == f"what is this?\n@image:{img}"
+
+
+def test_native_vision_turn_persists_a_renderable_image_ref(tmp_path):
+    """End to end through the real session-store flush: whichever image input
+    mode the turn used, the durable row carries an ``@image:`` ref the desktop
+    can render after a restart."""
+    from unittest.mock import MagicMock
+
+    from agent.image_routing import build_native_content_parts
+    from run_agent import AIAgent
+
+    img_dir = tmp_path / "Application Support" / "composer-images"
+    img_dir.mkdir(parents=True)
+    img = img_dir / "cat.png"
+    img.write_bytes(
+        bytes.fromhex(
+            "89504e470d0a1a0a0000000d494844520000000100000001080600000"
+            "01f15c4890000000a49444154789c6360000002000100ffff0300000600"
+            "0557bfabd40000000049454e44ae426082"
+        )
+    )
+    native_parts, skipped = build_native_content_parts("what is in this photo?", [str(img)])
+    assert not skipped
+
+    agent = AIAgent.__new__(AIAgent)
+    agent._session_db = MagicMock()
+    agent._session_db_created = True
+    agent.session_id = "s-1"
+    agent._last_flushed_db_idx = 0
+    agent._persist_disabled = False
+    agent._flushed_db_message_ids = set()
+    agent._flushed_db_message_session_id = None
+    agent._pending_cli_user_message = None
+    agent._persist_user_message_timestamp = None
+    agent._persist_user_message_idx = 0
+    agent._persist_user_message_override = server._build_persist_user_message(
+        "what is in this photo?", [str(img)], native_parts
+    )
+
+    agent._flush_messages_to_session_db([{"role": "user", "content": native_parts}], [])
+
+    written = agent._session_db.append_message.call_args.kwargs["content"]
+    assert f"@image:`{img}`" in written
+    assert "what is in this photo?" in written
+    # The model keeps the pixels for the rest of the session.
+    assert any(part.get("type") == "image_url" for part in agent._persist_user_message_override)
+
+
+def test_prompt_submit_passes_persist_user_message_to_agent(monkeypatch):
+    """#70720: _run_prompt_submit must forward the (image-ref-aware) persisted
+    user message to run_conversation via persist_user_message, so the gateway
+    stores the UI-recognizable form instead of the vision enrichment."""
+    captured = {}
+
+    class _Agent:
+        def run_conversation(self, prompt, conversation_history=None, stream_callback=None, **_kwargs):
+            captured["persist_user_message"] = _kwargs.get("persist_user_message")
+            return {
+                "final_response": "reply",
+                "messages": [{"role": "assistant", "content": "reply"}],
+            }
+
+    class _ImmediateThread:
+        def __init__(self, target=None, daemon=None):
+            self._target = target
+
+        def start(self):
+            self._target()
+
+    server._sessions["sid"] = _session(agent=_Agent())
+    try:
+        monkeypatch.setattr(server.threading, "Thread", _ImmediateThread)
+        monkeypatch.setattr(server, "_get_usage", lambda _a: {})
+        monkeypatch.setattr(server, "render_message", lambda _t, _c: "")
+        monkeypatch.setattr(server, "_emit", lambda *a: None)
+
+        resp = server.handle_request(
+            {
+                "id": "1",
+                "method": "prompt.submit",
+                "params": {"session_id": "sid", "text": "hi"},
+            }
+        )
+        assert resp.get("result")
+
+        # Without attachments the persist form equals the raw prompt.
+        assert captured.get("persist_user_message") == "hi"
+    finally:
+        server._sessions.pop("sid", None)
diff --git a/tests/test_windows_subprocess_no_window_flags.py b/tests/test_windows_subprocess_no_window_flags.py
index a3b8e85a947..0dcf29405ba 100644
--- a/tests/test_windows_subprocess_no_window_flags.py
+++ b/tests/test_windows_subprocess_no_window_flags.py
@@ -508,6 +508,8 @@ def test_gateway_force_kill_hides_taskkill_window(monkeypatch):
             {
                 "capture_output": True,
                 "text": True,
+                "encoding": "utf-8",
+                "errors": "replace",
                 "timeout": 10,
                 "creationflags": _CREATE_NO_WINDOW,
             },
@@ -837,3 +839,258 @@ def test_codex_app_server_transport_hides_console_window(monkeypatch):
     # Hide-only: the app-server wire still needs its pipes.
     assert kwargs["stdin"] == subprocess.PIPE
     assert kwargs["stdout"] == subprocess.PIPE
+
+
+# ── #47971 LSP spawn + installer paths (salvage) ────────────────────────────
+#
+# The LSP language-server spawn (agent/lsp/client.py::_spawn) and the
+# npm/go LSP auto-installers (agent/lsp/install.py) are reachable from
+# console-less parents — a VS Code/Zed extension host running the ACP
+# adapter — where a .cmd-wrapped server (pyright-langserver.CMD via
+# cmd.exe /c) or an npm/go console app flashes a window on Windows.
+# All are hide-only (creationflags); PIPE stdio must stay intact and the
+# POSIX start_new_session detach must be preserved on the client spawn.
+
+
+def test_lsp_client_spawn_hides_console_window(monkeypatch):
+    import asyncio
+
+    from agent.lsp import client as lsp_client
+
+    captured = []
+
+    class _FakeProc:
+        stdin = None
+        stdout = None
+        stderr = None
+
+    async def fake_exec(*cmd, **kwargs):
+        captured.append((list(cmd), kwargs))
+        return _FakeProc()
+
+    monkeypatch.setattr(lsp_client, "windows_hide_flags", lambda: _CREATE_NO_WINDOW)
+    monkeypatch.setattr(
+        lsp_client.asyncio, "create_subprocess_exec", fake_exec
+    )
+
+    client = lsp_client.LSPClient(
+        server_id="test-server",
+        workspace_root="/tmp/ws",
+        command=["fake-langserver", "--stdio"],
+    )
+    asyncio.run(client._spawn())
+
+    assert len(captured) == 1, captured
+    cmd, kwargs = captured[0]
+    assert cmd == ["fake-langserver", "--stdio"]
+    assert kwargs["creationflags"] == _CREATE_NO_WINDOW
+    # Hide-only: the LSP wire still needs its pipes, and the POSIX
+    # process-group detach (mcp orphan-sweep guard) must survive.
+    assert kwargs["stdin"] == asyncio.subprocess.PIPE
+    assert kwargs["stdout"] == asyncio.subprocess.PIPE
+    assert kwargs["start_new_session"] is True
+
+
+def test_lsp_install_npm_hides_console_window(monkeypatch, tmp_path):
+    from agent.lsp import install as lsp_install
+
+    captured = []
+
+    def fake_run(cmd, **kwargs):
+        captured.append((cmd, kwargs))
+        return _Completed(stdout="")
+
+    monkeypatch.setattr(lsp_install, "windows_hide_flags", lambda: _CREATE_NO_WINDOW)
+    monkeypatch.setattr(lsp_install.subprocess, "run", fake_run)
+    monkeypatch.setattr(lsp_install.shutil, "which", lambda name: f"/fake/bin/{name}")
+    monkeypatch.setattr(
+        lsp_install, "hermes_lsp_bin_dir", lambda: tmp_path / "lsp" / "bin"
+    )
+
+    # Bin lookup after the install misses (nothing staged) → None; the
+    # spawn contract is what is under test here.
+    lsp_install._install_npm("pyright", "pyright-langserver")
+
+    spawns = _spawns(captured, "/fake/bin/npm", "install", "pyright")
+    assert len(spawns) == 1, captured
+    cmd, kwargs = spawns[0]
+    assert kwargs["creationflags"] == _CREATE_NO_WINDOW
+    assert kwargs["stdin"] == subprocess.DEVNULL
+    assert kwargs["capture_output"] is True
+
+
+def test_lsp_install_go_hides_console_window(monkeypatch, tmp_path):
+    from agent.lsp import install as lsp_install
+
+    captured = []
+
+    def fake_run(cmd, **kwargs):
+        captured.append((cmd, kwargs))
+        return _Completed(stdout="")
+
+    monkeypatch.setattr(lsp_install, "windows_hide_flags", lambda: _CREATE_NO_WINDOW)
+    monkeypatch.setattr(lsp_install.subprocess, "run", fake_run)
+    monkeypatch.setattr(lsp_install.shutil, "which", lambda name: f"/fake/bin/{name}")
+    monkeypatch.setattr(
+        lsp_install, "hermes_lsp_bin_dir", lambda: tmp_path / "lsp" / "bin"
+    )
+
+    lsp_install._install_go("golang.org/x/tools/gopls@latest", "gopls")
+
+    spawns = _spawns(captured, "/fake/bin/go", "install")
+    assert len(spawns) == 1, captured
+    cmd, kwargs = spawns[0]
+    assert kwargs["creationflags"] == _CREATE_NO_WINDOW
+    assert kwargs["stdin"] == subprocess.DEVNULL
+    assert kwargs["capture_output"] is True
+
+
+# ── #67690 env probes, lazy installs, platform.win32_ver() (@m4r13y) ───────
+#
+# Windowless processes (pythonw gateway + kanban workers) flashed consoles
+# from three more spawn families: tools/env_probe._run's interpreter/pip
+# probes, tools/lazy_deps' uv→pip→ensurepip install ladder, and CPython
+# 3.11/3.12's platform.win32_ver() which shells out `cmd /c ver` with
+# shell=True and no CREATE_NO_WINDOW. All are hide-only (creationflags);
+# win32_ver is neutralized by stubbing platform._syscmd_ver so the
+# documented ValueError fallback reads sys.getwindowsversion() instead.
+
+
+def test_env_probe_run_hides_console_window(monkeypatch):
+    from tools import env_probe
+
+    captured = []
+
+    def fake_run(cmd, **kwargs):
+        captured.append((cmd, kwargs))
+        return _Completed(stdout="", returncode=0)
+
+    monkeypatch.setattr(env_probe, "windows_hide_flags", lambda: _CREATE_NO_WINDOW)
+    monkeypatch.setattr(env_probe.subprocess, "run", fake_run)
+
+    rc, out, err = env_probe._run(["python3", "--version"], timeout=1.0)
+
+    assert rc == 0
+    assert len(captured) == 1, captured
+    cmd, kwargs = captured[0]
+    assert cmd == ["python3", "--version"]
+    assert kwargs["creationflags"] == _CREATE_NO_WINDOW
+    # The temp-file capture contract (#67964) must survive: stdout/stderr are
+    # file objects (not PIPE) so a lingering grandchild can't wedge the probe.
+    assert kwargs["stdout"] is not None and kwargs["stdout"] != subprocess.PIPE
+    assert kwargs["stderr"] is not None and kwargs["stderr"] != subprocess.PIPE
+    assert kwargs["stdin"] == subprocess.DEVNULL
+
+
+def test_lazy_deps_uv_install_hides_console_window(monkeypatch):
+    from tools import lazy_deps
+
+    captured = []
+
+    def fake_run(cmd, **kwargs):
+        captured.append((cmd, kwargs))
+        return _Completed(stdout="installed", returncode=0)
+
+    monkeypatch.delenv(lazy_deps._LAZY_TARGET_ENV, raising=False)
+    monkeypatch.setattr(lazy_deps, "windows_hide_flags", lambda: _CREATE_NO_WINDOW)
+    monkeypatch.setattr(lazy_deps.subprocess, "run", fake_run)
+    monkeypatch.setattr(lazy_deps.shutil, "which", lambda name: "/usr/bin/uv" if name == "uv" else None)
+
+    res = lazy_deps._venv_pip_install(("left-pad",))
+
+    assert res.success
+    spawns = _spawns(captured, "pip", "install", "left-pad")
+    assert len(spawns) == 1, captured
+    cmd, kwargs = spawns[0]
+    assert cmd[:3] == ["/usr/bin/uv", "pip", "install"]
+    assert kwargs["creationflags"] == _CREATE_NO_WINDOW
+    assert kwargs["stdin"] == subprocess.DEVNULL
+
+
+def test_lazy_deps_pip_probe_and_install_hide_console_window(monkeypatch):
+    """No uv: the pip --version probe and the pip install fallback both hide."""
+    from tools import lazy_deps
+
+    captured = []
+
+    def fake_run(cmd, **kwargs):
+        captured.append((cmd, kwargs))
+        return _Completed(stdout="pip 25.0", returncode=0)
+
+    monkeypatch.delenv(lazy_deps._LAZY_TARGET_ENV, raising=False)
+    monkeypatch.setattr(lazy_deps, "windows_hide_flags", lambda: _CREATE_NO_WINDOW)
+    monkeypatch.setattr(lazy_deps.subprocess, "run", fake_run)
+    monkeypatch.setattr(lazy_deps.shutil, "which", lambda name: None)
+
+    res = lazy_deps._venv_pip_install(("left-pad",))
+
+    assert res.success
+    probes = _spawns(captured, "-m", "pip", "--version")
+    installs = _spawns(captured, "-m", "pip", "install", "left-pad")
+    assert len(probes) == 1 and len(installs) == 1, captured
+    for _cmd, kwargs in probes + installs:
+        assert kwargs["creationflags"] == _CREATE_NO_WINDOW
+        assert kwargs["stdin"] == subprocess.DEVNULL
+
+
+def test_lazy_deps_ensurepip_hides_console_window(monkeypatch):
+    """Failed pip probe: the ensurepip bootstrap spawn hides too."""
+    from tools import lazy_deps
+
+    captured = []
+
+    def fake_run(cmd, **kwargs):
+        captured.append((cmd, kwargs))
+        if "--version" in cmd:
+            return _Completed(stdout="", returncode=1)  # probe fails → ensurepip
+        return _Completed(stdout="ok", returncode=0)
+
+    monkeypatch.delenv(lazy_deps._LAZY_TARGET_ENV, raising=False)
+    monkeypatch.setattr(lazy_deps, "windows_hide_flags", lambda: _CREATE_NO_WINDOW)
+    monkeypatch.setattr(lazy_deps.subprocess, "run", fake_run)
+    monkeypatch.setattr(lazy_deps.shutil, "which", lambda name: None)
+
+    res = lazy_deps._venv_pip_install(("left-pad",))
+
+    assert res.success
+    bootstraps = _spawns(captured, "-m", "ensurepip", "--upgrade")
+    assert len(bootstraps) == 1, captured
+    assert bootstraps[0][1]["creationflags"] == _CREATE_NO_WINDOW
+
+
+def test_suppress_platform_ver_console_posix_noop(monkeypatch):
+    """On POSIX the helper must do nothing at all and never raise."""
+    import platform
+
+    from hermes_cli import _subprocess_compat
+
+    monkeypatch.setattr(_subprocess_compat, "IS_WINDOWS", False)
+    original = platform._syscmd_ver
+
+    _subprocess_compat.suppress_platform_ver_console()
+
+    assert platform._syscmd_ver is original
+    # win32_ver stays functional (returns empty fields off Windows).
+    assert platform.win32_ver() == ("", "", "", "")
+
+
+def test_suppress_platform_ver_console_stubs_syscmd_ver(monkeypatch):
+    """Simulated Windows: _syscmd_ver is replaced by an in-process echo stub
+    so win32_ver() takes its ValueError fallback instead of `cmd /c ver`."""
+    import platform
+
+    from hermes_cli import _subprocess_compat
+
+    monkeypatch.setattr(_subprocess_compat, "IS_WINDOWS", True)
+    # Register the original with monkeypatch so it gets restored after.
+    monkeypatch.setattr(platform, "_syscmd_ver", platform._syscmd_ver)
+
+    _subprocess_compat.suppress_platform_ver_console()
+
+    # The stub echoes its inputs — win32_ver() treats the unparseable value
+    # as the documented ValueError path and falls back to
+    # sys.getwindowsversion().platform_version (no subprocess, no window).
+    assert platform._syscmd_ver("s", "r", "v") == ("s", "r", "v")
+    # Idempotent + never raises on repeat calls.
+    _subprocess_compat.suppress_platform_ver_console()
+    assert platform._syscmd_ver() == ("", "", "")
diff --git a/tests/test_zeroed_state_db.py b/tests/test_zeroed_state_db.py
new file mode 100644
index 00000000000..6a9bf2810b8
--- /dev/null
+++ b/tests/test_zeroed_state_db.py
@@ -0,0 +1,170 @@
+"""#68474 hardening: zeroed state.db detection + quarantine."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+
+def test_is_zeroed_state_db_and_quarantine(tmp_path):
+    import hermes_state as hs
+
+    db = tmp_path / "state.db"
+    db.write_bytes(bytes(1024))
+    assert hs.is_zeroed_state_db(db) is True
+
+    q = hs.quarantine_zeroed_state_db(db)
+    assert q is not None
+    assert q.exists()
+    assert not db.exists()
+    assert q.read_bytes() == bytes(1024)
+
+
+def test_sessiondb_opens_fresh_after_zeroed_quarantine(tmp_path, monkeypatch):
+    import hermes_state as hs
+
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    db = tmp_path / "state.db"
+    db.write_bytes(bytes(4096))
+
+    sdb = hs.SessionDB(db_path=db)
+    try:
+        # Fresh DB should open and accept schema
+        assert db.exists()
+        assert not hs.is_zeroed_state_db(db)
+        # Quarantine retained
+        backups = list(tmp_path.glob("state.db.zeroed-*.bak"))
+        assert len(backups) == 1
+        assert backups[0].stat().st_size == 4096
+    finally:
+        sdb.close()
+
+
+def test_concurrent_quarantine_no_clobber(tmp_path):
+    """#68805: two concurrent startups must not race on quarantine.
+
+    Without the cross-process lock, the second process could move its
+    newly-created empty DB over the first process's quarantine backup,
+    erasing the original damaged-file evidence. With the lock, the
+    second process re-checks under the lock, finds the file no longer
+    zeroed (or gone), and returns without clobbering.
+    """
+    import hermes_state as hs
+    import threading
+    import sqlite3
+
+    db = tmp_path / "state.db"
+    db.write_bytes(bytes(4096))  # zeroed (all-NUL) 4 KB file
+
+    results: list = [None, None]
+    errors: list = [None, None]
+
+    def worker(idx):
+        try:
+            # Each worker opens its own SessionDB on the same path.
+            # The first one quarantines the zeroed file and creates a
+            # fresh DB. The second one should find a valid DB (or no
+            # file) under the lock and NOT clobber the quarantine.
+            sdb = hs.SessionDB(db_path=db)
+            try:
+                results[idx] = "ok"
+            finally:
+                sdb.close()
+        except Exception as exc:
+            errors[idx] = exc
+
+    t1 = threading.Thread(target=worker, args=(0,))
+    t2 = threading.Thread(target=worker, args=(1,))
+    t1.start()
+    t2.start()
+    t1.join(timeout=10)
+    t2.join(timeout=10)
+
+    # Both workers should complete without error
+    assert errors[0] is None, f"Worker 0 raised: {errors[0]}"
+    assert errors[1] is None, f"Worker 1 raised: {errors[1]}"
+
+    # The quarantine backup must survive — exactly one .bak file with
+    # the original 4096 zeroed bytes.
+    backups = list(tmp_path.glob("state.db.zeroed-*.bak"))
+    assert len(backups) >= 1, "At least one quarantine backup must exist"
+    for bak in backups:
+        assert bak.stat().st_size == 4096, (
+            f"Quarantine backup {bak} was clobbered: "
+            f"expected 4096 bytes, got {bak.stat().st_size}"
+        )
+
+    # The live state.db must be a valid (non-zeroed) SQLite database
+    assert db.exists()
+    assert not hs.is_zeroed_state_db(db)
+    conn = sqlite3.connect(str(db))
+    conn.execute("SELECT 1")
+    conn.close()
+
+
+def test_quarantine_fails_closed_when_lock_held(tmp_path):
+    """#68805 review: when the cross-process lock cannot be acquired within
+    the timeout, quarantine must FAIL CLOSED — return None without moving
+    the file. A fail-open fallback would let a slow/paused startup that
+    still owns the lock race with the fallback's re-check + rename.
+    """
+    import hermes_state as hs
+    import platform
+    import threading
+
+    db = tmp_path / "state.db"
+    db.write_bytes(bytes(4096))  # zeroed (all-NUL) 4 KB file
+
+    lock_path = db.with_name(db.name + ".quarantine.lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Hold the cross-process lock from a background thread so the main
+    # thread's quarantine attempt cannot acquire it.
+    lock_held = threading.Event()
+    release_lock = threading.Event()
+
+    def hold_lock():
+        handle = lock_path.open("a+b")
+        try:
+            if platform.system() == "Windows":
+                import msvcrt
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            lock_held.set()
+            release_lock.wait(timeout=15)
+            if platform.system() == "Windows":
+                import msvcrt
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        except OSError:
+            lock_held.clear()
+        finally:
+            handle.close()
+
+    holder = threading.Thread(target=hold_lock)
+    holder.start()
+    assert lock_held.wait(timeout=5), "Background thread failed to acquire lock"
+
+    # Reduce the quarantine lock timeout to keep the test fast. We patch
+    # the deadline by calling quarantine directly — it uses a 5s timeout,
+    # but we only need to verify it returns None without moving the file.
+    result = hs.quarantine_zeroed_state_db(db)
+
+    # Must fail closed: return None without moving the zeroed file
+    assert result is None, (
+        f"quarantine_zeroed_state_db returned {result} — expected None "
+        f"(fail-closed when lock is held)"
+    )
+    assert db.exists(), "Zeroed state.db was moved despite lock being held"
+    assert hs.is_zeroed_state_db(db), "File should still be zeroed (not moved)"
+
+    # Release the lock so the background thread can exit cleanly
+    release_lock.set()
+    holder.join(timeout=5)
diff --git a/tests/tools/test_async_delegation_fd_leak.py b/tests/tools/test_async_delegation_fd_leak.py
new file mode 100644
index 00000000000..ddc51f8984a
--- /dev/null
+++ b/tests/tools/test_async_delegation_fd_leak.py
@@ -0,0 +1,133 @@
+"""Regression: the async-delegation ledger must close every SQLite connection.
+
+Sibling of the cron execution-ledger leak (#69567 / PR #69594). The durable
+delegation ledger used ``with _connect() as conn:`` where the connection
+context manager commits/rolls back but never closes, leaking the db/-wal/-shm
+file descriptors on every dispatch, completion, and delivery-claim. These tests
+fail if the deterministic ``close()`` is ever removed again.
+"""
+
+import queue
+import sqlite3
+
+import pytest
+
+from tools import async_delegation as ad
+
+
+class _TrackingConnection:
+    """Delegates to a real sqlite3.Connection while recording close() calls.
+
+    sqlite3.Connection is a static C type: it has no per-instance __dict__ and
+    its methods can't be monkeypatched, so open/close tracking is done via a
+    delegating wrapper returned in place of the real connection.
+    """
+
+    def __init__(self, real, closed_ids):
+        object.__setattr__(self, "_real", real)
+        object.__setattr__(self, "_closed_ids", closed_ids)
+
+    def close(self):
+        self._closed_ids.append(id(self._real))
+        self._real.close()
+
+    def __enter__(self):
+        self._real.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return self._real.__exit__(exc_type, exc, tb)
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)
+
+    def __setattr__(self, name, value):
+        setattr(self._real, name, value)
+
+
+def _point_ledger(monkeypatch, tmp_path):
+    monkeypatch.setattr(ad, "_db_path", lambda: tmp_path / "state.db")
+    return ad
+
+
+def _track_connections(monkeypatch):
+    opened, closed = [], []
+    real_connect = sqlite3.connect
+
+    def tracking_connect(*args, **kwargs):
+        conn = real_connect(*args, **kwargs)
+        opened.append(id(conn))
+        return _TrackingConnection(conn, closed)
+
+    monkeypatch.setattr(ad.sqlite3, "connect", tracking_connect)
+    return opened, closed
+
+
+def test_ledger_operations_close_every_connection(monkeypatch, tmp_path):
+    """Public durable-ledger reads/writes must close every connection opened."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _track_connections(monkeypatch)
+
+    ad.get_durable_delegation("nope")
+    ad.recover_abandoned_delegations()
+    ad.restore_undelivered_completions(queue.Queue())
+    ad.mark_completion_delivered("nope")
+    ad.claim_completion_delivery("nope", "claim-1")
+
+    assert opened, "expected at least one connection to be opened"
+    assert len(opened) == len(closed)
+    assert set(opened) == set(closed)
+
+
+def test_early_return_still_closes_connection(monkeypatch, tmp_path):
+    """A no-op update (no matching row) must still open and close exactly once."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _track_connections(monkeypatch)
+
+    assert ad.mark_completion_delivered("does-not-exist") is False
+
+    assert len(opened) == 1
+    assert len(closed) == 1
+
+
+def test_exception_during_operation_still_closes_connection(monkeypatch, tmp_path):
+    """A failing statement inside the transaction must roll back and close."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = _track_connections(monkeypatch)
+
+    with pytest.raises(sqlite3.IntegrityError):
+        with ad._transaction() as conn:
+            # Missing NOT NULL columns -> constraint failure inside the block.
+            conn.execute(
+                "INSERT INTO async_delegations (delegation_id) VALUES ('x')"
+            )
+
+    assert len(opened) == 1
+    assert len(closed) == 1
+
+
+def test_schema_init_failure_still_closes_connection(monkeypatch, tmp_path):
+    """A PRAGMA/DDL failure after connect() must still close the connection."""
+    _point_ledger(monkeypatch, tmp_path)
+    opened, closed = [], []
+    real_connect = sqlite3.connect
+
+    class _FailingSchemaConnection(_TrackingConnection):
+        def execute(self, sql, *args, **kwargs):
+            if "CREATE TABLE" in sql:
+                raise sqlite3.OperationalError("simulated schema init failure")
+            return self._real.execute(sql, *args, **kwargs)
+
+    def tracking_connect(*args, **kwargs):
+        conn = real_connect(*args, **kwargs)
+        opened.append(id(conn))
+        return _FailingSchemaConnection(conn, closed)
+
+    monkeypatch.setattr(ad.sqlite3, "connect", tracking_connect)
+
+    with pytest.raises(sqlite3.OperationalError):
+        with ad._transaction():
+            pass
+
+    assert len(opened) == 1
+    assert len(closed) == 1
diff --git a/tests/tools/test_base_environment.py b/tests/tools/test_base_environment.py
index 7b84b15787e..079287a021e 100644
--- a/tests/tools/test_base_environment.py
+++ b/tests/tools/test_base_environment.py
@@ -67,7 +67,7 @@ class TestWrapCommand:
         assert "cd -- /tmp" in wrapped or "cd -- '/tmp'" in wrapped
         assert "eval 'echo hello'" in wrapped
         assert "__hermes_ec=$?" in wrapped
-        assert "export -p >" in wrapped
+        assert "export -p" in wrapped and "> " in wrapped
         # cwd travels via the stdout marker only — no temp-file write.
         assert "pwd -P >" not in wrapped
         assert env._cwd_marker in wrapped
@@ -141,14 +141,15 @@ class TestAtomicSnapshotWrite:
         env._snapshot_ready = True
         wrapped = env._wrap_command("echo hi", "/tmp")
         # Env dump goes to a temp file, not directly over the live snapshot.
-        assert "export -p > " in wrapped
+        assert "export -p" in wrapped and "> " in wrapped
         assert ".tmp." in wrapped
         # Then an atomic rename onto the real snapshot path.
         assert "mv -f " in wrapped
         # The env-dump must NOT write the live snapshot in place (the bug).
         snap = env._snapshot_path
-        assert f"export -p > {snap} " not in wrapped
-        assert f"export -p > '{snap}'" not in wrapped
+        assert f"> {snap} " not in wrapped
+        assert f"> '{snap}'" not in wrapped
+        assert f"> {snap}\n" not in wrapped
 
     def test_temp_path_uses_bashpid_not_dollardollar(self):
         """The temp name MUST use ``$BASHPID`` (the real subshell PID), not
@@ -186,7 +187,7 @@ class TestAtomicSnapshotWrite:
         env = _TestableEnv()
         env._snapshot_ready = True
         wrapped = env._wrap_command("echo hi", "/tmp")
-        assert "export -p > " in wrapped and "&& mv -f " in wrapped
+        assert "export -p" in wrapped and "> " in wrapped and "&& mv -f " in wrapped
         assert "rm -f " in wrapped  # temp cleanup on failure
 
     def test_init_session_bootstrap_also_atomic_and_bashpid(self):
@@ -217,7 +218,7 @@ class TestAtomicSnapshotWrite:
 
         assert "umask 077" in wrapped
         assert wrapped.index("eval 'echo hi'") < wrapped.index("umask 077")
-        assert wrapped.index("umask 077") < wrapped.index("export -p >")
+        assert wrapped.index("umask 077") < wrapped.index("export -p")
 
     def test_init_session_bootstrap_uses_private_umask(self):
         env = _TestableEnv()
@@ -234,7 +235,7 @@ class TestAtomicSnapshotWrite:
             pass
         boot = captured.get("cmd", "")
         assert "umask 077" in boot
-        assert boot.index("umask 077") < boot.index("export -p >")
+        assert boot.index("umask 077") < boot.index("export -p")
 
 
 class TestAtomicSnapshotConcurrencyBehavioral:
diff --git a/tests/tools/test_browser_console.py b/tests/tools/test_browser_console.py
index 08e851da28a..2316035e868 100644
--- a/tests/tools/test_browser_console.py
+++ b/tests/tools/test_browser_console.py
@@ -566,7 +566,7 @@ class TestDogfoodSkill:
     def _skill_dir(self):
         # Use the actual repo skills dir (not temp)
         self.skill_dir = os.path.join(
-            os.path.dirname(__file__), "..", "..", "skills", "dogfood"
+            os.path.dirname(__file__), "..", "..", "skills", "software-development", "dogfood"
         )
 
     def test_skill_md_exists(self):
diff --git a/tests/tools/test_checkpoint_manager.py b/tests/tools/test_checkpoint_manager.py
index 5c6db10c011..b72c9b954dd 100644
--- a/tests/tools/test_checkpoint_manager.py
+++ b/tests/tools/test_checkpoint_manager.py
@@ -1,8 +1,10 @@
 """Tests for tools/checkpoint_manager.py — CheckpointManager (v2 single-store)."""
 
+import argparse
 import json
 import logging
 import os
+import shutil
 import subprocess
 import time
 import pytest
@@ -934,6 +936,112 @@ class TestPruneCheckpointsV2:
         assert not old_legacy.exists()
 
 
+class TestPruneCheckpointsOrphanAllowlist:
+    """P1 fix on PR #69141: the confirmation preview must bind to exactly
+    what gets deleted. A project that only becomes orphaned *after* the
+    preview was built (e.g. its workdir vanishes while a human is answering
+    the y/N prompt) must survive a rescan-based prune unless its identity
+    was in the previewed/approved set.
+    """
+
+    def test_v2_allowlist_restricts_deletion_to_approved_hash(self, tmp_path, monkeypatch):
+        base = tmp_path / "checkpoints"
+        monkeypatch.setattr("tools.checkpoint_manager.CHECKPOINT_BASE", base)
+
+        previewed = tmp_path / "previewed-gone"
+        previewed.mkdir()
+        (previewed / "f").write_text("a")
+        newly_gone = tmp_path / "newly-gone"
+        newly_gone.mkdir()
+        (newly_gone / "f").write_text("b")
+
+        m = CheckpointManager(enabled=True)
+        assert m.ensure_checkpoint(str(previewed), "previewed") is True
+        m.new_turn()
+        assert m.ensure_checkpoint(str(newly_gone), "newly-gone") is True
+
+        import shutil as _shutil
+        _shutil.rmtree(previewed)
+        _shutil.rmtree(newly_gone)
+
+        previewed_hash = _project_hash(str(previewed))
+        newly_gone_hash = _project_hash(str(newly_gone))
+
+        result = prune_checkpoints(
+            retention_days=0, checkpoint_base=base,
+            orphan_allowlist={previewed_hash},
+        )
+
+        assert result["deleted_orphan"] == 1
+        assert not (base / "store" / "projects" / f"{previewed_hash}.json").exists()
+        # Not in the allowlist -> survives this prune even though it is orphaned.
+        assert (base / "store" / "projects" / f"{newly_gone_hash}.json").exists()
+
+    def test_pre_v2_allowlist_restricts_deletion_to_approved_path(self, tmp_path):
+        base = tmp_path / "checkpoints"
+        previewed_repo = _seed_legacy_repo(base, "aaaa" * 4, tmp_path / "previewed-gone")
+        newly_gone_repo = _seed_legacy_repo(base, "bbbb" * 4, tmp_path / "newly-gone")
+
+        result = prune_checkpoints(
+            retention_days=0, checkpoint_base=base,
+            orphan_allowlist={str(previewed_repo)},
+        )
+
+        assert result["deleted_orphan"] == 1
+        assert not previewed_repo.exists()
+        assert newly_gone_repo.exists()
+
+    def test_allowlist_none_deletes_all_current_orphans(self, tmp_path, monkeypatch):
+        """Default (no allowlist) keeps prior behaviour, e.g. for --force."""
+        base = tmp_path / "checkpoints"
+        orphan_a = _seed_legacy_repo(base, "cccc" * 4, tmp_path / "gone-a")
+        orphan_b = _seed_legacy_repo(base, "dddd" * 4, tmp_path / "gone-b")
+
+        result = prune_checkpoints(retention_days=0, checkpoint_base=base)
+
+        assert result["deleted_orphan"] == 2
+        assert not orphan_a.exists()
+        assert not orphan_b.exists()
+
+    def test_end_to_end_timing_change_during_confirmation_prompt(self, tmp_path, monkeypatch):
+        """Reproduces the exact PR #69141 review scenario end-to-end through
+        `hermes checkpoints prune`: the preview shows one pre-v2 orphan; a
+        second project's workdir is removed by the input() callback while
+        the human is "answering" the prompt. Only the previewed orphan may
+        be deleted.
+        """
+        import hermes_cli.checkpoints as checkpoints_cli
+
+        base = tmp_path / "checkpoints"
+        monkeypatch.setattr("tools.checkpoint_manager.CHECKPOINT_BASE", base)
+
+        previewed_work = tmp_path / "was-deleted-before-preview"
+        still_alive_work = tmp_path / "still-alive-during-preview"
+        still_alive_work.mkdir()
+        _seed_legacy_repo(base, "eeee" * 4, previewed_work)
+        second_repo = _seed_legacy_repo(base, "ffff" * 4, still_alive_work)
+
+        def _confirm_and_go_stale(_prompt):
+            # Simulate the workdir disappearing after the preview was shown
+            # but before the human's answer is processed.
+            import shutil as _shutil
+            _shutil.rmtree(still_alive_work)
+            return "y"
+
+        monkeypatch.setattr("builtins.input", _confirm_and_go_stale)
+
+        args = argparse.Namespace(
+            retention_days=0, max_size_mb=0, keep_orphans=False, force=False,
+        )
+        rc = checkpoints_cli.cmd_prune(args)
+
+        assert rc == 0
+        # The orphan shown in the preview is gone.
+        assert not (base / ("eeee" * 4)).exists()
+        # The one that only went orphan mid-confirmation must survive.
+        assert second_repo.exists()
+
+
 class TestMaybeAutoPruneCheckpoints:
     def test_first_call_prunes_and_writes_marker(self, tmp_path):
         base = tmp_path / "checkpoints"
@@ -1049,3 +1157,262 @@ class TestClearFunctions:
         result = clear_all()
         assert result["deleted"] is False
         assert result["bytes_freed"] == 0
+
+
+# =========================================================================
+# Orphan pruning must not act on an unreachable volume
+# =========================================================================
+
+class TestOrphanPruneRequiresObservableDeletion:
+    """A missing workdir is ambiguous: deleted, or just not mounted right now.
+
+    Orphan pruning deletes a project's whole checkpoint history and runs
+    unattended at startup (``maybe_auto_prune_checkpoints`` from the CLI and
+    the gateway), so it must only fire when the deletion is something we
+    actually observed — the parent directory present, the project gone. An
+    unplugged drive, a share behind a downed VPN, or a bind-mount absent from
+    this container must not cost the user their restore points.
+    """
+
+    def _project_with_history(self, work_dir, checkpoint_base, monkeypatch):
+        monkeypatch.setattr(
+            "tools.checkpoint_manager.CHECKPOINT_BASE", checkpoint_base
+        )
+        m = CheckpointManager(enabled=True, max_snapshots=10)
+        m.ensure_checkpoint(str(work_dir), "initial")
+        return m
+
+    def _history_survives(self, checkpoint_base, work_dir):
+        store = _store_path(checkpoint_base)
+        return _project_meta_path(
+            store, _project_hash(str(work_dir))
+        ).exists()
+
+    def test_unreachable_volume_keeps_its_checkpoints(
+        self, tmp_path, checkpoint_base, monkeypatch,
+    ):
+        """The whole mount is absent (parent missing too) → keep the history."""
+        mount = tmp_path / "mnt" / "nas"
+        work_dir = mount / "work" / "proj"
+        work_dir.mkdir(parents=True)
+        (work_dir / "main.py").write_text("print('x')\n")
+        self._project_with_history(work_dir, checkpoint_base, monkeypatch)
+
+        # The volume goes away — project AND its parents disappear together.
+        shutil.rmtree(tmp_path / "mnt")
+        assert not work_dir.exists()
+
+        prune_checkpoints(
+            retention_days=0, delete_orphans=True, checkpoint_base=checkpoint_base,
+        )
+
+        assert self._history_survives(checkpoint_base, work_dir), (
+            "checkpoint history was deleted for a project whose volume was "
+            "merely unmounted"
+        )
+
+    def test_surviving_empty_mountpoint_keeps_its_checkpoints(
+        self, tmp_path, checkpoint_base, monkeypatch,
+    ):
+        """The mount point outlives the volume as an empty dir → keep history.
+
+        The classic static layout (``/mnt/volume/proj``, an fstab entry, a
+        container bind-mount) does not remove the mount point on unmount: the
+        project disappears but ``/mnt/volume`` stays behind as an empty
+        directory. The parent being present is therefore not evidence on its
+        own — an empty parent looks exactly the same whether the volume was
+        detached or the project was deleted.
+        """
+        mount_point = tmp_path / "mnt" / "volume"
+        work_dir = mount_point / "proj"
+        work_dir.mkdir(parents=True)
+        (work_dir / "main.py").write_text("print('x')\n")
+        self._project_with_history(work_dir, checkpoint_base, monkeypatch)
+
+        # Unmount: contents go, the mount point itself remains.
+        shutil.rmtree(work_dir)
+        assert mount_point.is_dir() and not any(mount_point.iterdir())
+
+        prune_checkpoints(
+            retention_days=0, delete_orphans=True, checkpoint_base=checkpoint_base,
+        )
+
+        assert self._history_survives(checkpoint_base, work_dir), (
+            "checkpoint history was deleted for a project whose mount point "
+            "merely survived the unmount as an empty directory"
+        )
+
+    def test_empty_parent_project_is_still_reclaimed_by_retention(
+        self, tmp_path, checkpoint_base, monkeypatch,
+    ):
+        """Skipping an ambiguous parent defers reclamation, it does not lose it.
+
+        A project deleted out of an otherwise-empty parent is indistinguishable
+        from an unmounted volume, so orphan pruning leaves it alone — but the
+        retention rule, which reads ``last_touch`` instead of probing the
+        filesystem, still reclaims it.
+        """
+        parent = tmp_path / "solo"
+        work_dir = parent / "proj"
+        work_dir.mkdir(parents=True)
+        (work_dir / "main.py").write_text("print('x')\n")
+        self._project_with_history(work_dir, checkpoint_base, monkeypatch)
+
+        shutil.rmtree(work_dir)
+        assert parent.is_dir() and not any(parent.iterdir())
+
+        store = _store_path(checkpoint_base)
+        meta_path = _project_meta_path(store, _project_hash(str(work_dir)))
+        meta = json.loads(meta_path.read_text())
+        meta["last_touch"] = time.time() - 60 * 86400
+        meta_path.write_text(json.dumps(meta))
+
+        result = prune_checkpoints(
+            retention_days=30, delete_orphans=True, checkpoint_base=checkpoint_base,
+        )
+
+        assert result["deleted_stale"] >= 1
+        assert not self._history_survives(checkpoint_base, work_dir)
+
+    def test_genuinely_deleted_project_is_still_pruned(
+        self, tmp_path, checkpoint_base, monkeypatch,
+    ):
+        """Control: a populated parent without the project → a real orphan."""
+        parent = tmp_path / "projects"
+        work_dir = parent / "proj"
+        work_dir.mkdir(parents=True)
+        (work_dir / "main.py").write_text("print('x')\n")
+        (parent / "other-project").mkdir()
+        self._project_with_history(work_dir, checkpoint_base, monkeypatch)
+
+        shutil.rmtree(work_dir)
+        assert parent.exists() and not work_dir.exists()
+
+        result = prune_checkpoints(
+            retention_days=0, delete_orphans=True, checkpoint_base=checkpoint_base,
+        )
+
+        assert result["deleted_orphan"] >= 1
+        assert not self._history_survives(checkpoint_base, work_dir)
+
+    def test_live_project_is_never_pruned_as_orphan(
+        self, work_dir, checkpoint_base, monkeypatch,
+    ):
+        """Control: a present project keeps its history."""
+        self._project_with_history(work_dir, checkpoint_base, monkeypatch)
+
+        result = prune_checkpoints(
+            retention_days=0, delete_orphans=True, checkpoint_base=checkpoint_base,
+        )
+
+        assert result["deleted_orphan"] == 0
+        assert self._history_survives(checkpoint_base, work_dir)
+
+    def test_populated_underlay_mountpoint_keeps_its_checkpoints(
+        self, tmp_path, checkpoint_base, monkeypatch,
+    ):
+        """A detached volume exposing a populated underlay dir → keep history.
+
+        An entry in the parent does not prove the project volume is attached.
+        Unmounting swaps which directory is visible at the mount point's
+        path: the mounted filesystem's root gives way to the *underlying*
+        directory, whose own files (a ``.keep`` placeholder, sibling mount
+        points) become visible. Those entries were never next to the project,
+        so they must not corroborate an orphan classification — yet a naive
+        "parent has any entry" guard treats them as proof of deletion.
+
+        Simulate the detach faithfully: the directory visible at
+        ``mnt/volume`` after the unmount is a *different* directory (new
+        inode — the underlay) carrying a ``.keep`` placeholder.
+        """
+        mount_point = tmp_path / "mnt" / "volume"
+        work_dir = mount_point / "project"
+        work_dir.mkdir(parents=True)
+        (work_dir / "main.py").write_text("print('x')\n")
+        self._project_with_history(work_dir, checkpoint_base, monkeypatch)
+
+        # Detach: the directory that was mounted at the path (with the
+        # project on it) stops being visible there; the underlay directory —
+        # same path, different directory, its own contents — shows through,
+        # exposing a placeholder. Renaming (rather than deleting) the mounted
+        # directory keeps its inode alive, so the underlay directory is
+        # guaranteed a distinct identity, exactly as in a real unmount.
+        mount_point.rename(tmp_path / "detached-volume")
+        mount_point.mkdir()
+        (mount_point / ".keep").write_text("")
+        assert not work_dir.exists()
+        assert any(mount_point.iterdir())
+
+        result = prune_checkpoints(
+            retention_days=0, delete_orphans=True, checkpoint_base=checkpoint_base,
+        )
+
+        assert result["deleted_orphan"] == 0
+        assert self._history_survives(checkpoint_base, work_dir), (
+            "checkpoint history was deleted because underlay entries exposed "
+            "by an unmount were mistaken for attachment evidence"
+        )
+
+    def test_metadata_without_parent_identity_is_not_orphan_classified(
+        self, tmp_path, checkpoint_base, monkeypatch,
+    ):
+        """Metadata from an older version (no recorded identity) → keep.
+
+        Without a recorded parent ``(st_dev, st_ino)`` we cannot tell the
+        project's real parent from an underlay directory exposed by an
+        unmount, so the classification stays conservative: not an orphan.
+        The retention rule still reclaims genuinely abandoned projects.
+        """
+        parent = tmp_path / "projects"
+        work_dir = parent / "proj"
+        work_dir.mkdir(parents=True)
+        (work_dir / "main.py").write_text("print('x')\n")
+        (parent / "other-project").mkdir()
+        self._project_with_history(work_dir, checkpoint_base, monkeypatch)
+
+        # Strip the recorded identity, as metadata written by an older
+        # version would lack it.
+        store = _store_path(checkpoint_base)
+        meta_path = _project_meta_path(store, _project_hash(str(work_dir)))
+        meta = json.loads(meta_path.read_text())
+        meta.pop("workdir_parent_dev", None)
+        meta.pop("workdir_parent_ino", None)
+        meta_path.write_text(json.dumps(meta))
+
+        shutil.rmtree(work_dir)
+
+        result = prune_checkpoints(
+            retention_days=0, delete_orphans=True, checkpoint_base=checkpoint_base,
+        )
+
+        assert result["deleted_orphan"] == 0
+        assert self._history_survives(checkpoint_base, work_dir)
+
+    def test_recorded_parent_identity_survives_probe_failure_on_touch(
+        self, tmp_path, checkpoint_base, monkeypatch,
+    ):
+        """A later failed evidence probe must not erase recorded identity."""
+        from tools.checkpoint_manager import _register_project
+
+        parent = tmp_path / "projects"
+        work_dir = parent / "proj"
+        work_dir.mkdir(parents=True)
+        (work_dir / "main.py").write_text("print('x')\n")
+        self._project_with_history(work_dir, checkpoint_base, monkeypatch)
+
+        store = _store_path(checkpoint_base)
+        meta_path = _project_meta_path(store, _project_hash(str(work_dir)))
+        before = json.loads(meta_path.read_text())
+        assert "workdir_parent_dev" in before
+        assert "workdir_parent_ino" in before
+
+        # Re-register while the evidence probe fails (e.g. transient I/O
+        # error): the previously recorded identity must be preserved.
+        monkeypatch.setattr(
+            "tools.checkpoint_manager._volume_evidence", lambda _wd: {},
+        )
+        _register_project(store, str(work_dir))
+
+        after = json.loads(meta_path.read_text())
+        assert after["workdir_parent_dev"] == before["workdir_parent_dev"]
+        assert after["workdir_parent_ino"] == before["workdir_parent_ino"]
diff --git a/tests/tools/test_cronjob_run_immediate.py b/tests/tools/test_cronjob_run_immediate.py
index 9efa60e82cb..6588222a4bd 100644
--- a/tests/tools/test_cronjob_run_immediate.py
+++ b/tests/tools/test_cronjob_run_immediate.py
@@ -32,12 +32,53 @@ class TestCronjobRunExecutesImmediately:
         m_claim.assert_called_once_with("job-run-1")   # at-most-once claim taken
         m_run.assert_called_once()                       # fired via the shared body
 
+    def test_run_reconciles_external_provider_after_claimed_execution(self):
+        """A direct run must re-arm Chronos after it advances next_run_at.
+
+        Otherwise a scheduled Chronos fire that loses its claim to this direct
+        run is consumed without a successor one-shot, permanently stalling the
+        recurring job.
+        """
+        order = []
+        ran = {"id": "job-run-1", "last_status": "ok", "last_error": None}
+        with patch("tools.cronjob_tools.resolve_job_ref", return_value=dict(_JOB)), \
+             patch("tools.cronjob_tools.claim_job_for_fire", return_value=True), \
+             patch("cron.scheduler.run_one_job",
+                   side_effect=lambda *a, **kw: order.append("run") or True), \
+             patch("tools.cronjob_tools.get_job", return_value=ran), \
+             patch("tools.cronjob_tools._notify_provider_jobs_changed_safe",
+                   side_effect=lambda: order.append("notify")) as m_notify:
+            out = json.loads(cronjob(action="run", job_id="job-run-1"))
+
+        assert out["job"]["executed"] is True
+        m_notify.assert_called_once_with()
+        # Reconcile only AFTER the run persisted its final state (mark_job_run
+        # inside run_one_job), so the provider arms the post-run next_run_at.
+        assert order == ["run", "notify"]
+
+    def test_run_reconciles_external_provider_even_when_claimed_run_fails(self):
+        """A claimed direct run advances next_run_at at claim time, so the
+        provider must be reconciled even when the execution itself fails."""
+        failed = {"id": "job-run-1", "last_status": "error", "last_error": "provider 500"}
+        with patch("tools.cronjob_tools.resolve_job_ref", return_value=dict(_JOB)), \
+             patch("tools.cronjob_tools.claim_job_for_fire", return_value=True), \
+             patch("cron.scheduler.run_one_job", side_effect=RuntimeError("boom")), \
+             patch("tools.cronjob_tools.mark_job_run"), \
+             patch("tools.cronjob_tools.get_job", return_value=failed), \
+             patch("tools.cronjob_tools._notify_provider_jobs_changed_safe") as m_notify:
+            out = json.loads(cronjob(action="run", job_id="job-run-1"))
+
+        assert out["job"]["executed"] is True
+        assert out["job"]["execution_success"] is False
+        m_notify.assert_called_once_with()
+
     def test_run_skips_when_claim_lost(self):
         """If the scheduler already holds the fire claim, do NOT double-run."""
         with patch("tools.cronjob_tools.resolve_job_ref", return_value=dict(_JOB)), \
              patch("tools.cronjob_tools.claim_job_for_fire", return_value=False), \
              patch("cron.scheduler.run_one_job") as m_run, \
-             patch("tools.cronjob_tools.get_job", return_value=dict(_JOB)):
+             patch("tools.cronjob_tools.get_job", return_value=dict(_JOB)), \
+             patch("tools.cronjob_tools._notify_provider_jobs_changed_safe") as m_notify:
             out = json.loads(cronjob(action="run", job_id="job-run-1"))
 
         assert out["success"] is True
@@ -45,6 +86,7 @@ class TestCronjobRunExecutesImmediately:
         assert out["job"]["execution_success"] is False
         assert "execution_skipped" in out["job"]
         m_run.assert_not_called()  # claim lost -> never fired
+        m_notify.assert_not_called()  # the winning scheduler owns the re-arm
 
     def test_run_reports_failure_from_last_status(self):
         """A failed run is reported via the re-read job's last_status/last_error."""
diff --git a/tests/tools/test_discord_tool.py b/tests/tools/test_discord_tool.py
index 2a7d2793aaa..2fe22c03223 100644
--- a/tests/tools/test_discord_tool.py
+++ b/tests/tools/test_discord_tool.py
@@ -1268,7 +1268,11 @@ class TestModelToolsIntegration:
         mock_req.return_value = {"flags": 0}
 
         from model_tools import get_tool_definitions
-        tools = get_tool_definitions(enabled_toolsets=["hermes-discord"], quiet_mode=True)
+        # skip_tool_search_assembly: this test exercises the dynamic schema
+        # rebuild; under tiered disclosure the discord tools defer behind the
+        # bridge, but the rebuilt schema is what tool_describe serves.
+        tools = get_tool_definitions(enabled_toolsets=["hermes-discord"], quiet_mode=True,
+                                     skip_tool_search_assembly=True)
         discord_admin_tool = next(
             (t for t in tools if t.get("function", {}).get("name") == "discord_admin"),
             None,
diff --git a/tests/tools/test_docker_environment.py b/tests/tools/test_docker_environment.py
index 1f89c1aad9f..a2a6f79a595 100644
--- a/tests/tools/test_docker_environment.py
+++ b/tests/tools/test_docker_environment.py
@@ -45,11 +45,13 @@ def _make_dummy_env(**kwargs):
         persistent_filesystem=kwargs.get("persistent_filesystem", False),
         task_id=kwargs.get("task_id", "test-task"),
         volumes=kwargs.get("volumes", []),
+        forward_env=kwargs.get("forward_env"),
         network=kwargs.get("network", True),
         host_cwd=kwargs.get("host_cwd"),
         auto_mount_cwd=kwargs.get("auto_mount_cwd", False),
         env=kwargs.get("env"),
         run_as_host_user=kwargs.get("run_as_host_user", False),
+        extra_args=kwargs.get("extra_args", []),
         persist_across_processes=kwargs.get("persist_across_processes", True),
     )
 
@@ -114,6 +116,8 @@ def test_ensure_docker_available_uses_resolved_executable(monkeypatch):
         (["/opt/homebrew/bin/docker", "version"], {
             "capture_output": True,
             "text": True,
+            "encoding": "utf-8",
+            "errors": "replace",
             "timeout": 5,
             "stdin": subprocess.DEVNULL,
         })
@@ -362,6 +366,52 @@ def test_docker_env_appears_in_run_command(monkeypatch):
     assert "GNUPGHOME=/root/.gnupg" in run_args_str
 
 
+def _node_options_from_run(calls):
+    run_calls = [c for c in calls if isinstance(c[0], list) and len(c[0]) >= 2 and c[0][1] == "run"]
+    assert run_calls, "docker run should have been called"
+    args = run_calls[0][0]
+    for i, a in enumerate(args):
+        if a == "-e" and i + 1 < len(args) and args[i + 1].startswith("NODE_OPTIONS="):
+            return args[i + 1].split("=", 1)[1]
+    return None
+
+
+def test_egress_node_options_overrides_conflicting_ca_flag(monkeypatch):
+    """maxpetrusenko P1: a conflicting docker_env NODE_OPTIONS CA-mode flag
+    (--use-bundled-ca) must be replaced by the egress-required --use-openssl-ca,
+    not left to survive alongside it (final Node trust would depend on order)."""
+    monkeypatch.setattr(docker_env, "find_docker", lambda: "/usr/bin/docker")
+    monkeypatch.setattr(
+        docker_env, "_egress_proxy_args_for_docker",
+        lambda: ([], {"_HERMES_EGRESS_NODE_OPTIONS_APPEND": "--use-openssl-ca"}, []),
+    )
+    calls = _mock_subprocess_run(monkeypatch)
+
+    _make_dummy_env(env={"NODE_OPTIONS": "--max-old-space-size=8192 --use-bundled-ca"})
+
+    node_opts = (_node_options_from_run(calls) or "").split()
+    assert "--use-openssl-ca" in node_opts, "egress CA flag must be present"
+    assert "--use-bundled-ca" not in node_opts, "conflicting CA flag must be stripped"
+    # Operator's unrelated tuning must be preserved.
+    assert "--max-old-space-size=8192" in node_opts
+
+
+def test_egress_node_options_preserves_operator_tuning(monkeypatch):
+    """Non-conflicting operator NODE_OPTIONS survive the egress append-merge."""
+    monkeypatch.setattr(docker_env, "find_docker", lambda: "/usr/bin/docker")
+    monkeypatch.setattr(
+        docker_env, "_egress_proxy_args_for_docker",
+        lambda: ([], {"_HERMES_EGRESS_NODE_OPTIONS_APPEND": "--use-openssl-ca"}, []),
+    )
+    calls = _mock_subprocess_run(monkeypatch)
+
+    _make_dummy_env(env={"NODE_OPTIONS": "--max-old-space-size=4096"})
+
+    node_opts = (_node_options_from_run(calls) or "").split()
+    assert "--use-openssl-ca" in node_opts
+    assert "--max-old-space-size=4096" in node_opts
+
+
 def test_docker_env_appears_in_init_env_args(monkeypatch):
     """Explicit docker_env values should appear in _build_init_env_args."""
     env = _make_execute_only_env()
@@ -679,6 +729,7 @@ def test_labels_attribute_populated_after_init(monkeypatch):
         "hermes-agent": "1",
         "hermes-task-id": "abc",
         "hermes-profile": "default",
+        "hermes-egress": "off",
     }
 
 
@@ -710,8 +761,13 @@ def _mock_subprocess_run_with_reuse(monkeypatch, ps_state: str | None,
             if sub == "ps":
                 if ps_state is None:
                     return subprocess.CompletedProcess(cmd, 0, stdout="", stderr="")
+                # 3-field format: ID, State, EgressLabel.  When egress_label
+                # is "off" the code parses all three fields; <no value> means
+                # the container has no egress label, which is acceptable.
                 return subprocess.CompletedProcess(
-                    cmd, 0, stdout=f"reused-cid\t{ps_state}\n", stderr="",
+                    cmd, 0,
+                    stdout=f"reused-cid\t{ps_state}\t<no value>\n",
+                    stderr="",
                 )
             if sub == "start":
                 if not start_succeeds:
@@ -754,6 +810,95 @@ def test_reuse_attaches_to_running_container_without_docker_run(monkeypatch):
     )
 
 
+def test_egress_enabled_does_not_reuse_pre_egress_container(monkeypatch):
+    """A container created before egress was enabled lacks the proxy env vars
+    and CA mount.  Reusing it would silently bypass the credential firewall."""
+
+    monkeypatch.setattr(docker_env, "find_docker", lambda: "/usr/bin/docker")
+    monkeypatch.setattr(docker_env, "_get_active_profile_name", lambda: "default")
+    monkeypatch.setattr(
+        docker_env,
+        "_egress_proxy_args_for_docker",
+        lambda: (
+            ["-v", "/tmp/ca:/etc/ssl/certs/hermes-egress-ca.crt:ro"],
+            {"HTTPS_PROXY": "http://host.docker.internal:9090"},
+            ["--add-host", "host.docker.internal:host-gateway"],
+        ),
+    )
+    calls = []
+
+    def _run(cmd, **kwargs):
+        calls.append((list(cmd) if isinstance(cmd, list) else cmd, kwargs))
+        if isinstance(cmd, list) and len(cmd) >= 2:
+            sub = cmd[1]
+            if sub == "version":
+                return subprocess.CompletedProcess(cmd, 0, stdout="Docker version", stderr="")
+            if sub == "ps":
+                # Simulate an old pre-egress container: without the egress label
+                # filter it would match; with the filter Docker returns no match.
+                assert any(str(part).startswith("label=hermes-egress=") for part in cmd)
+                return subprocess.CompletedProcess(cmd, 0, stdout="", stderr="")
+            if sub == "run":
+                return subprocess.CompletedProcess(cmd, 0, stdout="fresh-cid\n", stderr="")
+        return subprocess.CompletedProcess(cmd, 0, stdout="", stderr="")
+
+    monkeypatch.setattr(docker_env.subprocess, "run", _run)
+
+    env = _make_dummy_env(task_id="reuse-egress")
+
+    assert env._container_id == "fresh-cid"
+    run_invocations = [
+        c for c in calls
+        if isinstance(c[0], list) and len(c[0]) >= 2 and c[0][1] == "run"
+    ]
+    assert run_invocations, "egress-enabled containers require a fresh docker run"
+
+
+def test_forward_env_provider_key_collision_refuses_under_egress(monkeypatch):
+    """docker_forward_env is explicit, but it still must not smuggle real
+    provider keys into an enforced egress sandbox."""
+
+    monkeypatch.setattr(docker_env, "find_docker", lambda: "/usr/bin/docker")
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-real")
+    monkeypatch.setattr(
+        docker_env,
+        "_egress_proxy_args_for_docker",
+        lambda: (
+            [],
+            {
+                "HTTPS_PROXY": "http://host.docker.internal:9090",
+                "OPENROUTER_API_KEY": "hermes-proxy-openrouter-token",
+                "HERMES_PROXY_TOKEN_OPENROUTER_API_KEY": "hermes-proxy-openrouter-token",
+            },
+            [],
+        ),
+    )
+    _mock_subprocess_run(monkeypatch)
+
+    with pytest.raises(RuntimeError, match="docker_forward_env.*OPENROUTER_API_KEY"):
+        _make_dummy_env(forward_env=["OPENROUTER_API_KEY"])
+
+
+def test_extra_args_proxy_override_refuses_under_egress(monkeypatch):
+    """docker_extra_args are appended after Hermes args, so egress enforcement
+    must reject critical overrides before Docker sees them."""
+
+    monkeypatch.setattr(docker_env, "find_docker", lambda: "/usr/bin/docker")
+    monkeypatch.setattr(
+        docker_env,
+        "_egress_proxy_args_for_docker",
+        lambda: (
+            [],
+            {"HTTPS_PROXY": "http://host.docker.internal:9090"},
+            [],
+        ),
+    )
+    _mock_subprocess_run(monkeypatch)
+
+    with pytest.raises(RuntimeError, match="docker_extra_args.*HTTPS_PROXY"):
+        _make_dummy_env(extra_args=["-e", "HTTPS_PROXY="])
+
+
 def test_reuse_starts_stopped_container_before_attaching(monkeypatch):
     """A labeled container in ``exited`` state must be restarted via
     ``docker start`` before the new Hermes process uses it. Without this
@@ -908,10 +1053,11 @@ def test_find_reusable_container_prefers_running_over_stopped(monkeypatch):
             if cmd[1] == "version":
                 return subprocess.CompletedProcess(cmd, 0, stdout="ok", stderr="")
             if cmd[1] == "ps":
-                # Two matches: stopped first, running second.
+                # Two matches: stopped first, running second.  3-field format
+                # with absent egress label for the "off" path.
                 return subprocess.CompletedProcess(
                     cmd, 0,
-                    stdout="stopped-cid\texited\nrunning-cid\trunning\n",
+                    stdout="stopped-cid\texited\t<no value>\nrunning-cid\trunning\t<no value>\n",
                     stderr="",
                 )
         return subprocess.CompletedProcess(cmd, 0, stdout="fresh-cid\n", stderr="")
@@ -924,6 +1070,71 @@ def test_find_reusable_container_prefers_running_over_stopped(monkeypatch):
     )
 
 
+def test_find_reusable_handles_empty_label_string(monkeypatch):
+    """Docker CLI v29.5.3 returns an empty string (NOT ``<no value>``)
+    for absent labels.  The trailing tab produces ``cid\\trunning\\t\\n``;
+    we must not strip the trailing tab or the three-field parser drops the
+    container.  Regression test for the egilewski review on #48073."""
+    monkeypatch.setattr(docker_env, "find_docker", lambda: "/usr/bin/docker")
+    monkeypatch.setattr(docker_env, "_get_active_profile_name", lambda: "default")
+
+    def _run(cmd, **kwargs):
+        if isinstance(cmd, list) and len(cmd) >= 2:
+            if cmd[1] == "version":
+                return subprocess.CompletedProcess(cmd, 0, stdout="ok", stderr="")
+            if cmd[1] == "ps":
+                # Docker v29.5.3: absent label → empty string, trailing tab
+                return subprocess.CompletedProcess(
+                    cmd, 0,
+                    stdout="safe-cid\trunning\t\n",
+                    stderr="",
+                )
+        return subprocess.CompletedProcess(cmd, 0, stdout="fresh-cid\n", stderr="")
+
+    monkeypatch.setattr(docker_env.subprocess, "run", _run)
+
+    env = _make_dummy_env(task_id="empty-label")
+    assert env._container_id == "safe-cid", (
+        f"container with empty-string label should be reused, got {env._container_id!r}"
+    )
+
+
+def test_reuse_off_rejects_non_off_egress_container(monkeypatch):
+    """When egress is off, a container that still has hermes-egress=on
+    (e.g. from before ``hermes egress disable``) must be rejected and a
+    fresh container created.  The post-filter protects against silently
+    reusing a container with baked-in proxy env and CA mounts."""
+
+    monkeypatch.setattr(docker_env, "find_docker", lambda: "/usr/bin/docker")
+    monkeypatch.setattr(docker_env, "_get_active_profile_name", lambda: "default")
+
+    def _run(cmd, **kwargs):
+        if isinstance(cmd, list) and len(cmd) >= 2:
+            if cmd[1] == "version":
+                return subprocess.CompletedProcess(cmd, 0, stdout="ok", stderr="")
+            if cmd[1] == "ps":
+                # Return a container with hermes-egress=on.  With egress=off
+                # the three-field format includes the label; the post-filter
+                # must skip this entry.
+                return subprocess.CompletedProcess(
+                    cmd, 0,
+                    stdout="stale-cid\trunning\ton\n",
+                    stderr="",
+                )
+            if cmd[1] == "run":
+                return subprocess.CompletedProcess(cmd, 0, stdout="fresh-cid\n", stderr="")
+        return subprocess.CompletedProcess(cmd, 0, stdout="", stderr="")
+
+    monkeypatch.setattr(docker_env.subprocess, "run", _run)
+
+    env = _make_dummy_env(task_id="egress-off-reject")
+    # Should fall through to fresh container because the stale one has
+    # hermes-egress=on.
+    assert env._container_id == "fresh-cid", (
+        f"expected fresh container, got {env._container_id!r}"
+    )
+
+
 # ── Cleanup correctness (issue #20561) ────────────────────────────
 
 
diff --git a/tests/tools/test_docker_network_config.py b/tests/tools/test_docker_network_config.py
index 776f5ef6d7c..62a76a99184 100644
--- a/tests/tools/test_docker_network_config.py
+++ b/tests/tools/test_docker_network_config.py
@@ -130,7 +130,10 @@ def _reuse_guard_harness(monkeypatch, *, existing_mode: str, network: bool):
             stdout = ""
 
         if len(cmd) > 1 and cmd[1] == "ps":
-            Result.stdout = "existing-container-id\trunning\n"
+            # Matches the egress-aware reuse probe: with egress off the
+            # format string is ID\tState\tEgressLabel and docker renders a
+            # missing label as "<no value>".
+            Result.stdout = "existing-container-id\trunning\t<no value>\n"
         elif len(cmd) > 1 and cmd[1] == "inspect":
             Result.stdout = f"{existing_mode}\n"
         elif len(cmd) > 1 and cmd[1] == "run":
diff --git a/tests/tools/test_hub_lock_non_utf8_68053.py b/tests/tools/test_hub_lock_non_utf8_68053.py
new file mode 100644
index 00000000000..509b4aefc5e
--- /dev/null
+++ b/tests/tools/test_hub_lock_non_utf8_68053.py
@@ -0,0 +1,65 @@
+"""Regression test for #68053 — hub lock.json with Windows-1252 bytes.
+
+`_read_hub_installed_names()` reads `~/.hermes/skills/.hub/lock.json` with a
+strict UTF-8 decode. A hub skill description carrying a Windows-1252 typographic
+byte (em-dash `0x97`, smart quotes, bullets) makes `read_text(encoding="utf-8")`
+raise `UnicodeDecodeError` — a `ValueError` sibling that is NOT caught by the
+function's `except (OSError, json.JSONDecodeError)`, so it escapes and returns
+HTTP 500 from the entire `/api/skills` endpoint, blanking the desktop Skills
+panel. The fix decodes with `errors="replace"`, so the offending byte degrades
+to U+FFFD and every skill name in the (structurally valid) lock stays readable.
+"""
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def skills_home(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "skills").mkdir()
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    import tools.skill_usage as mod
+    importlib.reload(mod)
+    return home
+
+
+def _write_hub_lock(home: Path, raw: bytes) -> None:
+    hub_dir = home / "skills" / ".hub"
+    hub_dir.mkdir(parents=True, exist_ok=True)
+    (hub_dir / "lock.json").write_bytes(raw)
+
+
+def test_windows_1252_em_dash_does_not_raise(skills_home):
+    """A 0x97 em-dash byte in a description must not blow up the reader."""
+    import tools.skill_usage as mod
+
+    # Valid JSON structure, but the description value contains a raw cp1252
+    # em-dash byte (0x97) instead of the UTF-8 sequence.
+    raw = (
+        b'{"installed": {"supply-chain": '
+        b'{"description": "guidance: safe \x97 3 finding(s)"}}}'
+    )
+    _write_hub_lock(skills_home, raw)
+
+    names = mod._read_hub_installed_names()
+
+    # The skill name is still recovered; no UnicodeDecodeError / 500.
+    assert "supply-chain" in names
+
+
+def test_clean_utf8_lock_still_read(skills_home):
+    """A well-formed UTF-8 lock keeps working unchanged."""
+    import tools.skill_usage as mod
+
+    raw = '{"installed": {"alpha": {}, "beta": {}}}'.encode("utf-8")
+    _write_hub_lock(skills_home, raw)
+
+    names = mod._read_hub_installed_names()
+
+    assert {"alpha", "beta"} <= names
diff --git a/tests/tools/test_local_shell_init.py b/tests/tools/test_local_shell_init.py
index f1e4f5b0451..178c02e6a95 100644
--- a/tests/tools/test_local_shell_init.py
+++ b/tests/tools/test_local_shell_init.py
@@ -194,12 +194,12 @@ class TestSnapshotEndToEnd:
         env = LocalEnvironment(cwd=str(tmp_path), timeout=15)
         try:
             first = env.execute(
-                'export HERMES_SESSION_ENV_PROBE="sticky"; '
+                'export HERMES_STICKY_ENV_PROBE="sticky"; '
                 'export PATH="/tmp/hermes-session-bin:$PATH"; '
-                'echo "first=$HERMES_SESSION_ENV_PROBE"'
+                'echo "first=$HERMES_STICKY_ENV_PROBE"'
             )
             second = env.execute(
-                'echo "second=$HERMES_SESSION_ENV_PROBE"; echo "PATH=$PATH"'
+                'echo "second=$HERMES_STICKY_ENV_PROBE"; echo "PATH=$PATH"'
             )
         finally:
             env.cleanup()
diff --git a/tests/tools/test_mcp_stdio_encoding_handler.py b/tests/tools/test_mcp_stdio_encoding_handler.py
new file mode 100644
index 00000000000..3a84ea92a77
--- /dev/null
+++ b/tests/tools/test_mcp_stdio_encoding_handler.py
@@ -0,0 +1,103 @@
+"""Tests for MCP stdio encoding error handler fix (issue #46099).
+
+On Windows, pipe I/O can produce non-UTF-8 bytes at chunk boundaries,
+causing UnicodeDecodeError when the MCP SDK's TextReceiveStream uses
+errors="strict". This test verifies that StdioServerParameters is created
+with encoding_error_handler="replace".
+"""
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from tools.mcp_tool import MCPServerTask, _MCP_AVAILABLE
+
+pytestmark = pytest.mark.skipif(not _MCP_AVAILABLE, reason="MCP SDK not installed")
+
+
+class TestStdioEncodingErrorHandler:
+    """Verify that _run_stdio passes encoding_error_handler='replace'."""
+
+    def test_stdio_server_params_uses_replace_encoding_handler(self):
+        """StdioServerParameters must use encoding_error_handler='replace'.
+
+        On Windows, pipe chunk boundaries can split multi-byte UTF-8 sequences,
+        producing bytes that fail with errors='strict'. Using 'replace' ensures
+        undecodable bytes become U+FFFD instead of crashing.
+        """
+        mock_session = MagicMock()
+        mock_session.initialize = AsyncMock()
+        mock_session.list_tools = AsyncMock(return_value=SimpleNamespace(tools=[]))
+
+        mock_stdio_cm = MagicMock()
+        mock_stdio_cm.__aenter__ = AsyncMock(return_value=(object(), object()))
+        mock_stdio_cm.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session_cm = MagicMock()
+        mock_session_cm.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_session_cm.__aexit__ = AsyncMock(return_value=False)
+
+        async def _test():
+            with (
+                patch("tools.mcp_tool.StdioServerParameters") as mock_params,
+                patch("tools.mcp_tool.stdio_client", return_value=mock_stdio_cm),
+                patch("tools.mcp_tool.ClientSession", return_value=mock_session_cm),
+                patch("tools.mcp_tool._snapshot_child_pids", return_value=set()),
+                patch("tools.mcp_tool._write_stderr_log_header"),
+                patch("tools.mcp_tool._get_mcp_stderr_log", return_value=None),
+            ):
+                server = MCPServerTask("test-encoding")
+                await server.start({
+                    "command": "echo",
+                    "args": ["hello"],
+                })
+
+                call_kwargs = mock_params.call_args.kwargs
+                assert call_kwargs["encoding_error_handler"] == "replace", (
+                    f"Expected encoding_error_handler='replace', "
+                    f"got '{call_kwargs.get('encoding_error_handler')}'"
+                )
+
+                await server.shutdown()
+
+        asyncio.run(_test())
+
+    def test_stdio_server_params_defaults_encoding_utf8(self):
+        """Verify that the default encoding (utf-8) is not overridden."""
+        mock_session = MagicMock()
+        mock_session.initialize = AsyncMock()
+        mock_session.list_tools = AsyncMock(return_value=SimpleNamespace(tools=[]))
+
+        mock_stdio_cm = MagicMock()
+        mock_stdio_cm.__aenter__ = AsyncMock(return_value=(object(), object()))
+        mock_stdio_cm.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session_cm = MagicMock()
+        mock_session_cm.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_session_cm.__aexit__ = AsyncMock(return_value=False)
+
+        async def _test():
+            with (
+                patch("tools.mcp_tool.StdioServerParameters") as mock_params,
+                patch("tools.mcp_tool.stdio_client", return_value=mock_stdio_cm),
+                patch("tools.mcp_tool.ClientSession", return_value=mock_session_cm),
+                patch("tools.mcp_tool._snapshot_child_pids", return_value=set()),
+                patch("tools.mcp_tool._write_stderr_log_header"),
+                patch("tools.mcp_tool._get_mcp_stderr_log", return_value=None),
+            ):
+                server = MCPServerTask("test-encoding")
+                await server.start({
+                    "command": "echo",
+                    "args": ["hello"],
+                })
+
+                call_kwargs = mock_params.call_args.kwargs
+                # encoding is not explicitly set — StdioServerParameters defaults to utf-8
+                # We just verify we don't override it
+                assert "encoding" not in call_kwargs or call_kwargs.get("encoding") == "utf-8"
+
+                await server.shutdown()
+
+        asyncio.run(_test())
diff --git a/tests/tools/test_mcp_tool.py b/tests/tools/test_mcp_tool.py
index 769a006940e..7e5b40c1cc3 100644
--- a/tests/tools/test_mcp_tool.py
+++ b/tests/tools/test_mcp_tool.py
@@ -3874,6 +3874,52 @@ class TestMCPSelectiveToolLoading:
             "mcp__ink_exclude__list_services",
         ]
 
+    def test_exclude_filter_supports_globs(self):
+        """fnmatch globs in exclude — the Cloudflare flat-mode shape
+        (``*_radar_*`` etc.). Previously silently matched nothing."""
+        config = {
+            "url": "https://mcp.example.com",
+            "tools": {"exclude": ["*_radar_*", "delete_*"]},
+        }
+        registered, _ = self._run_discover(
+            "ink_glob",
+            ["get_radar_summary", "get_accounts_radar_http", "delete_service",
+             "create_service", "list_services"],
+            config,
+            session=SimpleNamespace(),
+        )
+        assert registered == [
+            "mcp__ink_glob__create_service",
+            "mcp__ink_glob__list_services",
+        ]
+
+    def test_include_filter_supports_globs(self):
+        """Globs work symmetrically on the include whitelist."""
+        config = {
+            "url": "https://mcp.example.com",
+            "tools": {"include": ["get_zones_*"]},
+        }
+        registered, _ = self._run_discover(
+            "ink_glob_inc",
+            ["get_zones_dns_records", "get_zones_settings", "delete_zone",
+             "get_accounts"],
+            config,
+            session=SimpleNamespace(),
+        )
+        assert registered == [
+            "mcp__ink_glob_inc__get_zones_dns_records",
+            "mcp__ink_glob_inc__get_zones_settings",
+        ]
+
+    def test_exact_names_still_match_exactly(self):
+        """No-metachar entries stay literal — 'docs' must not glob-match
+        'docs_search', and exact matching is unchanged."""
+        from tools.mcp_tool import matches_name_filter
+        assert matches_name_filter("docs", {"docs"})
+        assert not matches_name_filter("docs_search", {"docs"})
+        assert matches_name_filter("docs_search", {"docs*"})
+        assert not matches_name_filter("anything", set())
+
     def test_include_filter_skips_utility_tools_without_capabilities(self):
         config = {
             "url": "https://mcp.example.com",
diff --git a/tests/tools/test_memory_tool.py b/tests/tools/test_memory_tool.py
index c2903f375c6..4e1858f07ea 100644
--- a/tests/tools/test_memory_tool.py
+++ b/tests/tools/test_memory_tool.py
@@ -829,6 +829,174 @@ class TestExternalDriftGuard:
         assert ".bak." in r2["drift_backup"]
 
 
+class TestUnreadableFileDoesNotWipeMemory:
+    """A file that exists but can't be read must NOT be treated as empty.
+
+    ``_read_file`` degraded a failed read to ``[]``, conflating "unreadable"
+    with "empty store". ``add`` rewrites the whole file from the parsed entries,
+    so a transient read failure (an external editor holding the file on Windows,
+    a permission blip, an I/O error) turned an append into a full-file rewrite
+    down to a single entry — silently wiping every prior memory while returning
+    success. replace/remove/apply_batch were shielded only incidentally (an
+    empty view means no match, so they abort); this pins the guarantee for all
+    of them explicitly.
+    """
+
+    @staticmethod
+    def _fail_read_once(monkeypatch, path):
+        """Make ``path.read_text`` raise OSError exactly once, else pass through."""
+        real = Path.read_text
+        state = {"failed": False}
+
+        def flaky(self, *a, **k):
+            if self == path and not state["failed"]:
+                state["failed"] = True
+                raise OSError("transient: file temporarily unavailable")
+            return real(self, *a, **k)
+
+        monkeypatch.setattr(Path, "read_text", flaky)
+
+    def test_add_refuses_and_preserves_memory_on_read_failure(
+        self, store, monkeypatch,
+    ):
+        store.add("memory", "User prefers dark mode.")
+        store.add("memory", "Deploy target is Ubuntu 24.04.")
+        path = store._path_for("memory")
+        before = path.read_text(encoding="utf-8")
+
+        self._fail_read_once(monkeypatch, path)
+        result = store.add("memory", "A brand new fact.")
+
+        # Refused, not a false success — and nothing on disk changed.
+        assert result["success"] is False
+        assert "could not be read" in result["error"]
+        assert path.read_text(encoding="utf-8") == before
+        assert "dark mode" in path.read_text(encoding="utf-8")
+        assert "Ubuntu 24.04" in path.read_text(encoding="utf-8")
+
+    def test_replace_reports_read_failure_not_missing_entry(
+        self, store, monkeypatch,
+    ):
+        store.add("memory", "Entry to replace later.")
+        path = store._path_for("memory")
+        before = path.read_text(encoding="utf-8")
+
+        self._fail_read_once(monkeypatch, path)
+        result = store.replace("memory", "Entry to replace", "New value.")
+
+        assert result["success"] is False
+        # The distinct read-failure error, NOT the confusing "no entry matched".
+        assert "could not be read" in result["error"]
+        assert path.read_text(encoding="utf-8") == before
+
+    def test_remove_refuses_on_read_failure(self, store, monkeypatch):
+        store.add("memory", "Keep me safe.")
+        path = store._path_for("memory")
+        before = path.read_text(encoding="utf-8")
+
+        self._fail_read_once(monkeypatch, path)
+        result = store.remove("memory", "Keep me safe")
+
+        assert result["success"] is False
+        assert "could not be read" in result["error"]
+        assert path.read_text(encoding="utf-8") == before
+
+    def test_apply_batch_refuses_on_read_failure(self, store, monkeypatch):
+        store.add("memory", "Original batch entry.")
+        path = store._path_for("memory")
+        before = path.read_text(encoding="utf-8")
+
+        self._fail_read_once(monkeypatch, path)
+        result = store.apply_batch(
+            "memory", [{"action": "add", "content": "batched addition"}]
+        )
+
+        assert result["success"] is False
+        assert path.read_text(encoding="utf-8") == before
+
+    def test_absent_file_is_still_a_clean_empty_store(self, store):
+        """A genuinely missing file must NOT be mistaken for a read failure."""
+        path = store._path_for("memory")
+        if path.exists():
+            path.unlink()
+
+        result = store.add("memory", "First entry ever.")
+
+        assert result["success"] is True
+        assert "First entry ever." in path.read_text(encoding="utf-8")
+
+    def test_normal_add_still_works_when_read_succeeds(self, store):
+        """Control: the guard does not disturb the happy path."""
+        store.add("memory", "Fact one.")
+        result = store.add("memory", "Fact two.")
+        assert result["success"] is True
+        path = store._path_for("memory")
+        assert "Fact one." in path.read_text(encoding="utf-8")
+        assert "Fact two." in path.read_text(encoding="utf-8")
+
+    def test_user_store_add_refuses_on_read_failure(self, store, monkeypatch):
+        """USER.md shares the read-modify-write pattern and needs the same guard."""
+        store.add("user", "Name: Alice")
+        store.add("user", "Role: developer")
+        path = store._path_for("user")
+        before = path.read_text(encoding="utf-8")
+
+        self._fail_read_once(monkeypatch, path)
+        result = store.add("user", "Timezone: UTC")
+
+        assert result["success"] is False
+        assert "could not be read" in result["error"]
+        assert path.read_text(encoding="utf-8") == before
+
+    def test_invalid_utf8_file_refuses_write_instead_of_crashing(self, store):
+        """Undecodable bytes are 'unreadable', not a crash and not an empty store.
+
+        A MEMORY.md with invalid UTF-8 used to raise UnicodeDecodeError out of
+        the mutation path. It must instead produce the same preservation
+        refusal as a failed read — the on-disk bytes can't be round-tripped,
+        so rewriting would corrupt or discard them.
+        """
+        store.add("memory", "Entry before corruption.")
+        path = store._path_for("memory")
+        original_bytes = b"\xff\xfe invalid utf-8 \x80\x81 memory content"
+        path.write_bytes(original_bytes)
+
+        result = store.add("memory", "New entry.")
+
+        assert result["success"] is False
+        assert "could not be read" in result["error"]
+        assert path.read_bytes() == original_bytes  # nothing rewritten
+
+    def test_mutations_read_the_file_exactly_once(self, store, monkeypatch):
+        """Drift detection must use the SAME snapshot as the reload parse.
+
+        The drift guard used to re-read the file itself and swallow a failed
+        second read as "no drift" — a read failure between the checked reload
+        and the drift check let `replace` rewrite the file from a stale view,
+        discarding externally added entries. Pin the invariant structurally:
+        one mutation, one read.
+        """
+        store.add("memory", "Only entry.")
+        path = store._path_for("memory")
+
+        real = Path.read_text
+        counts = {"n": 0}
+
+        def counting(self, *a, **k):
+            if self == path:
+                counts["n"] += 1
+            return real(self, *a, **k)
+
+        monkeypatch.setattr(Path, "read_text", counting)
+        result = store.replace("memory", "Only entry", "Replaced entry.")
+
+        assert result["success"] is True
+        assert counts["n"] == 1, (
+            f"replace() read the memory file {counts['n']} times; drift "
+            f"detection must reuse the single checked-read snapshot"
+        )
+
+
 # =========================================================================
 # Load-time snapshot sanitization — promptware defense (#496)
 #
diff --git a/tests/tools/test_process_registry.py b/tests/tools/test_process_registry.py
index beeb41fe1ea..a9ea279fce8 100644
--- a/tests/tools/test_process_registry.py
+++ b/tests/tools/test_process_registry.py
@@ -911,6 +911,153 @@ class TestPopenLeakOnSetupFailure:
         assert session.pid == 7777
 
 
+# =========================================================================
+# Spawn rewrite regression (issue #68915)
+# =========================================================================
+
+
+class TestSpawnRewriteCompoundBackground:
+    """Verify that spawn_local rewrites `A && B &` patterns to avoid subshell deadlocks.
+
+    Issue #68915: when bash parses ``A && B &`` it forks a subshell ``(A && B) &``.
+    If B is a long-running server, the subshell never exits and holds the stdout
+    pipe open, causing a permanent deadlock. The rewriter wraps the tail to
+    ``A && { B & }`` so no subshell fork occurs.
+    """
+
+    def test_compound_and_background_gets_rewritten(self, registry):
+        """A && B & must be rewritten to A && { B & } before Popen."""
+        captured_cmd = []
+
+        def fake_popen(args, **kwargs):
+            captured_cmd.append(args)
+            proc = MagicMock()
+            proc.pid = 1111
+            proc.stdout = MagicMock()
+            return proc
+
+        fake_thread = MagicMock()
+        fake_thread.daemon = False
+
+        with patch("tools.process_registry._find_shell", return_value="/bin/bash"), \
+             patch("subprocess.Popen", side_effect=fake_popen), \
+             patch("threading.Thread", return_value=fake_thread), \
+             patch.object(registry, "_write_checkpoint"):
+            registry.spawn_local("cd /app && node server.js &>/tmp/srv.log &", cwd="/tmp")
+
+        assert len(captured_cmd) == 1
+        shell_cmd = captured_cmd[0]
+        # The command passed to Popen should be the REWRITTEN version
+        assert "&& { node server.js &>/tmp/srv.log & }" in shell_cmd[2]
+
+    def test_simple_background_preserved(self, registry):
+        """Simple cmd & (no &&) must NOT be rewritten — no subshell bug."""
+        captured_cmd = []
+
+        def fake_popen(args, **kwargs):
+            captured_cmd.append(args)
+            proc = MagicMock()
+            proc.pid = 2222
+            proc.stdout = MagicMock()
+            return proc
+
+        fake_thread = MagicMock()
+        fake_thread.daemon = False
+
+        with patch("tools.process_registry._find_shell", return_value="/bin/bash"), \
+             patch("subprocess.Popen", side_effect=fake_popen), \
+             patch("threading.Thread", return_value=fake_thread), \
+             patch.object(registry, "_write_checkpoint"):
+            registry.spawn_local("sleep 5 &", cwd="/tmp")
+
+        assert len(captured_cmd) == 1
+        shell_cmd = captured_cmd[0][2]
+        # Simple background must remain as-is
+        assert "sleep 5 &" in shell_cmd
+
+    def test_multi_line_compound_background(self, registry):
+        """Multi-line cd + server start must be rewritten."""
+        captured_cmd = []
+
+        def fake_popen(args, **kwargs):
+            captured_cmd.append(args)
+            proc = MagicMock()
+            proc.pid = 3333
+            proc.stdout = MagicMock()
+            return proc
+
+        fake_thread = MagicMock()
+        fake_thread.daemon = False
+
+        with patch("tools.process_registry._find_shell", return_value="/bin/bash"), \
+             patch("subprocess.Popen", side_effect=fake_popen), \
+             patch("threading.Thread", return_value=fake_thread), \
+             patch.object(registry, "_write_checkpoint"):
+            registry.spawn_local(
+                "cd /app && python3 -m http.server &\nsleep 1\ncurl http://localhost:8000/",
+                cwd="/tmp",
+            )
+
+        assert len(captured_cmd) == 1
+        shell_cmd = captured_cmd[0][2]
+        # First line's compound should be rewritten; rest is preserved
+        assert "&& { python3 -m http.server & }" in shell_cmd
+        assert "sleep 1" in shell_cmd
+        assert "curl http://localhost:8000/" in shell_cmd
+
+    def test_session_stores_original_command(self, registry):
+        """Session.command must store the ORIGINAL (unrewritten) command."""
+        captured = []
+
+        def fake_popen(args, **kwargs):
+            proc = MagicMock()
+            proc.pid = 4444
+            proc.stdout = MagicMock()
+            captured.append(args)
+            return proc
+
+        fake_thread = MagicMock()
+        fake_thread.daemon = False
+
+        with patch("tools.process_registry._find_shell", return_value="/bin/bash"), \
+             patch("subprocess.Popen", side_effect=fake_popen), \
+             patch("threading.Thread", return_value=fake_thread), \
+             patch.object(registry, "_write_checkpoint"):
+            session = registry.spawn_local("A && B &", cwd="/tmp")
+
+        assert session.command == "A && B &"
+        assert "{ B" in captured[0][2]  # rewritten in Popen args
+
+    def test_pty_path_uses_rewritten_command(self, registry):
+        """PTY spawn path must also use the rewritten command (issue #68915)."""
+        mock_pty_proc = MagicMock()
+        mock_pty_proc.pid = 5555
+
+        mock_pty_module = MagicMock()
+        mock_pty_module.PtyProcess.spawn = MagicMock(return_value=mock_pty_proc)
+
+        fake_thread = MagicMock()
+        fake_thread.daemon = False
+
+        with patch("tools.process_registry._find_shell", return_value="/bin/bash"), \
+             patch("tools.process_registry._IS_WINDOWS", False), \
+             patch.dict("sys.modules", {"ptyprocess": mock_pty_module}), \
+             patch("threading.Thread", return_value=fake_thread), \
+             patch.object(registry, "_write_checkpoint"):
+            session = registry.spawn_local(
+                "cd /app && node server.js &",
+                cwd="/tmp",
+                use_pty=True,
+            )
+
+        assert mock_pty_module.PtyProcess.spawn.called, \
+            "PTY spawn should have been attempted"
+        pty_args = mock_pty_module.PtyProcess.spawn.call_args[0][0]
+        assert "&& { node server.js & }" in pty_args[2], \
+            f"PTY path should use rewritten command, got: {pty_args[2]}"
+        assert session.command == "cd /app && node server.js &"
+
+
 # =========================================================================
 # Checkpoint
 # =========================================================================
@@ -2229,3 +2376,135 @@ class TestHandleProcessRedaction:
         monkeypatch.setattr(pr, "process_registry", reg)
         out = json.loads(pr._handle_process({"action": "log", "session_id": sess.id}))
         assert "zzzopaque1234567890abcdef" in out["output"]
+
+
+# =========================================================================
+# Reader loop: orphaned grandchild holding the stdout pipe (issue #68915)
+# =========================================================================
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX-only: select() on pipes")
+class TestReaderLoopOrphanedPipe:
+    """Regression tests for issue #68915.
+
+    When an agent command backgrounds a long-lived process (``node server.js
+    &``), the grandchild inherits the write end of the reader's stdout pipe.
+    The direct bash child exits, but the pipe never EOFs — the old blocking
+    ``read1()`` parked the reader thread forever, ``session.exited`` never
+    flipped on its own, and ``notify_on_complete`` never fired. The reader
+    must instead terminate shortly after the direct child exits, even while
+    a descendant still holds the pipe open.
+    """
+
+    def test_reader_exits_when_orphan_holds_pipe(self, registry):
+        """Reader loop must return promptly after the direct child exits,
+        even though a backgrounded descendant keeps the pipe open."""
+        proc = subprocess.Popen(
+            ["sh", "-c", "echo started; sleep 30 & exit 0"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            preexec_fn=os.setsid,
+        )
+        s = _make_session(sid="proc_orphan_reader")
+        s.process = proc
+        s.pid = proc.pid
+        registry._running[s.id] = s
+
+        done = threading.Event()
+
+        def _run():
+            registry._reader_loop(s)
+            done.set()
+
+        t = threading.Thread(target=_run, daemon=True)
+        t.start()
+        try:
+            # The direct child exits immediately; the reader must notice and
+            # return well before the 30s descendant releases the pipe.
+            assert done.wait(timeout=10.0), (
+                "_reader_loop is still blocked on the orphan-held pipe "
+                "(issue #68915) — session.exited would never flip and "
+                "notify_on_complete would never fire"
+            )
+            assert s.exited is True
+            assert s.exit_code == 0
+            assert s.completion_reason == "exited"
+            assert "started" in s.output_buffer
+            assert s.id in registry._finished
+        finally:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+
+    def test_reader_exit_fires_notify_on_complete(self, registry):
+        """The autonomous completion notification must not depend on a
+        poll()/wait() call when an orphan holds the pipe."""
+        proc = subprocess.Popen(
+            ["sh", "-c", "sleep 30 & echo bg-started"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            preexec_fn=os.setsid,
+        )
+        s = _make_session(sid="proc_orphan_notify")
+        s.process = proc
+        s.pid = proc.pid
+        s.notify_on_complete = True
+        registry._running[s.id] = s
+
+        done = threading.Event()
+
+        def _run():
+            registry._reader_loop(s)
+            done.set()
+
+        t = threading.Thread(target=_run, daemon=True)
+        t.start()
+        try:
+            assert done.wait(timeout=10.0), (
+                "_reader_loop blocked — completion notification lost (#68915)"
+            )
+            # Exactly one completion event must have been queued.
+            item = registry.completion_queue.get_nowait()
+            assert item["type"] == "completion"
+            assert item["session_id"] == s.id
+            assert item["exit_code"] == 0
+        finally:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+
+    def test_reader_still_streams_full_output_to_eof(self, registry):
+        """No-orphan case: the reader must still capture ALL output through
+        true EOF (the early-exit path must not race away buffered tail)."""
+        script = (
+            "for i in 1 2 3 4 5; do echo line-$i; done; "
+            "sleep 0.3; echo tail-after-sleep"
+        )
+        proc = subprocess.Popen(
+            ["sh", "-c", script],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            preexec_fn=os.setsid,
+        )
+        s = _make_session(sid="proc_orphan_fulldrain")
+        s.process = proc
+        s.pid = proc.pid
+        registry._running[s.id] = s
+
+        registry._reader_loop(s)
+
+        assert s.exited is True
+        assert s.exit_code == 0
+        for i in range(1, 6):
+            assert f"line-{i}" in s.output_buffer
+        assert "tail-after-sleep" in s.output_buffer
diff --git a/tests/tools/test_refresh_agent_mcp_tools.py b/tests/tools/test_refresh_agent_mcp_tools.py
index da349474a33..30f97910450 100644
--- a/tests/tools/test_refresh_agent_mcp_tools.py
+++ b/tests/tools/test_refresh_agent_mcp_tools.py
@@ -140,6 +140,32 @@ def test_refresh_preserves_memory_provider_and_context_engine_tools(monkeypatch)
     assert added == {"mcp_new_server_tool"}
 
 
+def test_refresh_does_not_reinject_disabled_memory_provider_tools(monkeypatch):
+    """A refresh removes stale provider tools when memory becomes disabled."""
+    agent = _agent(
+        ["read_file", "memory_search"],
+        enabled=["all"],
+        disabled=["memory"],
+    )
+    agent._memory_manager = types.SimpleNamespace(
+        get_all_tool_schemas=lambda: [
+            {"name": "memory_search", "description": "", "parameters": {}}
+        ]
+    )
+
+    import model_tools
+    monkeypatch.setattr(
+        model_tools,
+        "get_tool_definitions",
+        lambda **kw: [_tool("read_file")],
+    )
+
+    mcp_tool.refresh_agent_mcp_tools(agent)
+
+    assert "memory_search" not in agent.valid_tool_names
+    assert all(t["function"]["name"] != "memory_search" for t in agent.tools)
+
+
 def test_refresh_respects_context_engine_toolset_gate(monkeypatch):
     """#5544: context-engine tools must NOT be re-injected on a restricted
     toolset. A platform with enabled_toolsets that excludes context_engine
diff --git a/tests/tools/test_schema_sanitizer.py b/tests/tools/test_schema_sanitizer.py
index 90a6ffa3c04..da6a1e30ad0 100644
--- a/tests/tools/test_schema_sanitizer.py
+++ b/tests/tools/test_schema_sanitizer.py
@@ -759,3 +759,111 @@ def test_strip_slash_enum_ignores_non_string_enum_values():
     props = tools[0]["function"]["parameters"]["properties"]
     assert props["level"]["enum"] == [1, 2, 3]
     assert props["flag"]["enum"] == [True, False]
+
+
+# ---------------------------------------------------------------------------
+# Property-key renaming (provider ^[a-zA-Z0-9_.-]{1,64}$ pattern compat)
+# Real-world source: Cloudflare flat API MCP ships keys like
+# ``issue_class~neq`` and ``meta.<field>[<operator>]`` — one bad key anywhere
+# in the tools array 400s the whole request on Anthropic/Bedrock/Vertex/Azure.
+# ---------------------------------------------------------------------------
+
+from tools.schema_sanitizer import sanitize_property_key, unrename_tool_args
+
+
+def test_bad_property_keys_renamed_to_conforming():
+    tools = [_tool("cf_issues", {
+        "type": "object",
+        "properties": {
+            "issue_class~neq": {"type": "string"},
+            "meta.<field>[<operator>]": {"type": "string"},
+            "normal_key": {"type": "string"},
+        },
+        "required": ["issue_class~neq"],
+    })]
+    out = sanitize_tool_schemas(tools)
+    props = out[0]["function"]["parameters"]["properties"]
+    import re
+    pat = re.compile(r"^[a-zA-Z0-9_.-]{1,64}$")
+    assert all(pat.match(k) for k in props), list(props)
+    assert "normal_key" in props
+    assert "issue_class_neq" in props
+    # required remapped alongside
+    assert out[0]["function"]["parameters"]["required"] == ["issue_class_neq"]
+
+
+def test_property_key_over_64_chars_truncated():
+    long_key = "k" * 80
+    tools = [_tool("t", {"type": "object", "properties": {long_key: {"type": "string"}}})]
+    out = sanitize_tool_schemas(tools)
+    props = out[0]["function"]["parameters"]["properties"]
+    assert list(props) == ["k" * 64]
+
+
+def test_rename_collision_deduped_deterministically():
+    tools = [_tool("t", {
+        "type": "object",
+        "properties": {
+            "a~b": {"type": "string"},
+            "a b": {"type": "integer"},
+            "a_b": {"type": "boolean"},  # already owns the sanitized name
+        },
+    })]
+    out = sanitize_tool_schemas(tools)
+    props = out[0]["function"]["parameters"]["properties"]
+    assert props["a_b"]["type"] == "boolean"       # original conforming key untouched
+    assert set(props) == {"a_b", "a_b_2", "a_b_3"}
+    # deterministic across repeated runs
+    out2 = sanitize_tool_schemas(tools)
+    assert out2[0]["function"]["parameters"]["properties"].keys() == props.keys()
+
+
+def test_nested_bad_property_keys_renamed():
+    tools = [_tool("t", {
+        "type": "object",
+        "properties": {
+            "body": {
+                "type": "object",
+                "properties": {"filter~gte": {"type": "number"}},
+            },
+        },
+    })]
+    out = sanitize_tool_schemas(tools)
+    body = out[0]["function"]["parameters"]["properties"]["body"]
+    assert "filter_gte" in body["properties"]
+    assert "filter~gte" not in body["properties"]
+
+
+def test_unrename_tool_args_maps_back_to_wire_names():
+    original_params = {
+        "type": "object",
+        "properties": {
+            "issue_class~neq": {"type": "string"},
+            "normal": {"type": "string"},
+            "body": {
+                "type": "object",
+                "properties": {"filter~gte": {"type": "number"}},
+            },
+        },
+    }
+    model_args = {
+        "issue_class_neq": "spoofed_dns",
+        "normal": "x",
+        "body": {"filter_gte": 5},
+    }
+    restored = unrename_tool_args(original_params, model_args)
+    assert restored == {
+        "issue_class~neq": "spoofed_dns",
+        "normal": "x",
+        "body": {"filter~gte": 5},
+    }
+
+
+def test_unrename_passes_unknown_keys_through():
+    params = {"type": "object", "properties": {"a": {"type": "string"}}}
+    assert unrename_tool_args(params, {"a": 1, "mystery": 2}) == {"a": 1, "mystery": 2}
+
+
+def test_sanitize_property_key_empty_falls_back():
+    assert sanitize_property_key("~~~") == "___"
+    assert sanitize_property_key("") == "param"
diff --git a/tests/tools/test_session_search.py b/tests/tools/test_session_search.py
index 3509055ecdb..bd538ebd4cb 100644
--- a/tests/tools/test_session_search.py
+++ b/tests/tools/test_session_search.py
@@ -20,6 +20,7 @@ from tools.session_search_tool import (
     _is_compacted_message,
     _is_compression_ended,
     _resolve_to_parent,
+    _session_link,
     session_search,
 )
 
@@ -492,6 +493,69 @@ class TestReadShape:
         assert len(result["messages"]) == 30  # head 20 + tail 10
 
 
+# =========================================================================
+# Session links — the value the agent writes to point the user at a session
+# =========================================================================
+
+def _linked_session_id(link: str) -> str:
+    """Recover the session id from an `@session:[<profile>/]<id>` value."""
+    assert link.startswith("@session:"), link
+    value = link[len("@session:"):]
+
+    return value.rsplit("/", 1)[-1]
+
+
+class TestSessionLink:
+    def test_link_carries_the_named_profile(self):
+        assert _session_link("s_oldest", "work") == "@session:work/s_oldest"
+
+    def test_link_falls_back_to_a_bare_id_when_the_profile_is_unknown(self, monkeypatch):
+        monkeypatch.setattr(
+            "hermes_cli.profiles.get_active_profile_name",
+            lambda: "custom",
+        )
+
+        assert _session_link("s_oldest") == "@session:s_oldest"
+
+    def test_link_survives_a_failure_to_resolve_the_profile(self, monkeypatch):
+        def boom():
+            raise RuntimeError("no profile")
+
+        monkeypatch.setattr("hermes_cli.profiles.get_active_profile_name", boom)
+
+        assert _session_link("s_oldest") == "@session:s_oldest"
+
+    def test_read_result_links_to_the_session_it_read(self, db):
+        _seed_modpack_sessions(db)
+        result = json.loads(session_search(session_id="s_oldest", db=db))
+
+        assert _linked_session_id(result["link"]) == result["session_id"]
+
+    def test_every_discovery_result_links_to_its_own_session(self, db):
+        _seed_modpack_sessions(db)
+        result = json.loads(session_search(query="modpack", limit=5, db=db))
+
+        assert result["results"]
+        for entry in result["results"]:
+            assert _linked_session_id(entry["link"]) == entry["session_id"]
+
+    def test_every_browse_result_links_to_its_own_session(self, db):
+        _seed_modpack_sessions(db)
+        result = json.loads(session_search(db=db))
+
+        assert result["results"]
+        for entry in result["results"]:
+            assert _linked_session_id(entry["link"]) == entry["session_id"]
+
+    def test_link_splits_the_way_the_tool_parses_it_back(self):
+        """The agent hands its own link back as session_id; the value has to
+        survive the profile/id partition in session_search."""
+        value = _session_link("s_middle", "work")[len("@session:"):]
+        profile, _, session_id = value.partition("/")
+
+        assert (profile, session_id) == ("work", "s_middle")
+
+
 # =========================================================================
 # Cross-profile read — `profile` swaps in another profile's DB (read-only)
 # =========================================================================
diff --git a/tests/tools/test_skill_manager_tool.py b/tests/tools/test_skill_manager_tool.py
index 3443e0418b1..c4e9a8ddae3 100644
--- a/tests/tools/test_skill_manager_tool.py
+++ b/tests/tools/test_skill_manager_tool.py
@@ -21,6 +21,11 @@ from tools.skill_manager_tool import (
     skill_manage,
     MAX_NAME_LENGTH,
 )
+from agent.skill_utils import (
+    extract_skill_description,
+    parse_frontmatter,
+    SKILL_PROMPT_DESC_LIMIT,
+)
 
 
 @contextmanager
@@ -54,6 +59,17 @@ description: Updated description.
 Step 1: Do the new thing.
 """
 
+LONG_DESC_CONTENT = """\
+---
+name: long-desc
+description: Use when deploying multi-region Kubernetes clusters with custom CNI plugins and service mesh.
+---
+
+# Long Desc Skill
+
+Step 1.
+"""
+
 
 # ---------------------------------------------------------------------------
 # _validate_name
@@ -259,6 +275,46 @@ class TestCreateSkill:
         assert f"Invalid category '{outside}'" in result["error"]
         assert not (outside / "my-skill" / "SKILL.md").exists()
 
+    def test_create_long_desc_rejected(self, tmp_path):
+        with _skill_dir(tmp_path):
+            result = _create_skill("long-desc", LONG_DESC_CONTENT)
+        assert result["success"] is False
+        assert "system-prompt budget" in result["error"]
+
+    def test_create_short_desc_no_prompt_preview(self, tmp_path):
+        with _skill_dir(tmp_path):
+            result = _create_skill("my-skill", VALID_SKILL_CONTENT)
+        assert result["success"] is True
+        assert "system_prompt_preview" not in result
+
+    def test_create_boundary_at_limit_accepted_no_preview(self, tmp_path):
+        desc = "U" * SKILL_PROMPT_DESC_LIMIT
+        content = f"---\nname: boundary-at\ndescription: {desc}\n---\n\n# Boundary\n\nStep 1.\n"
+        with _skill_dir(tmp_path):
+            result = _create_skill("boundary-at", content)
+        assert result["success"] is True
+        assert "system_prompt_preview" not in result
+
+    def test_create_boundary_over_limit_rejected(self, tmp_path):
+        desc = "U" * (SKILL_PROMPT_DESC_LIMIT + 1)
+        content = f"---\nname: boundary-over\ndescription: {desc}\n---\n\n# Boundary\n\nStep 1.\n"
+        with _skill_dir(tmp_path):
+            result = _create_skill("boundary-over", content)
+        assert result["success"] is False
+        assert "system-prompt budget" in result["error"]
+
+    def test_edit_long_desc_still_allowed_with_preview(self, tmp_path):
+        """Edit/patch paths stay permissive so existing over-limit skills
+        remain maintainable — they warn via system_prompt_preview instead."""
+        with _skill_dir(tmp_path):
+            _create_skill("my-skill", VALID_SKILL_CONTENT)
+            result = _edit_skill("my-skill", LONG_DESC_CONTENT)
+        assert result["success"] is True
+        assert "system_prompt_preview" in result
+        assert "System prompt will show" in result["system_prompt_preview"]
+        fm, _ = parse_frontmatter(LONG_DESC_CONTENT)
+        assert extract_skill_description(fm) in result["system_prompt_preview"]
+
 
 class TestEditSkill:
     def test_edit_existing_skill(self, tmp_path):
@@ -284,6 +340,14 @@ class TestEditSkill:
         content = (tmp_path / "my-skill" / "SKILL.md").read_text()
         assert "A test skill" in content
 
+    def test_edit_long_desc_includes_prompt_preview(self, tmp_path):
+        edit_content = LONG_DESC_CONTENT.replace("name: long-desc", "name: test-skill")
+        with _skill_dir(tmp_path):
+            _create_skill("test-skill", VALID_SKILL_CONTENT)
+            result = _edit_skill("test-skill", edit_content)
+        assert result["success"] is True
+        assert "system_prompt_preview" in result
+
 
 class TestPatchSkill:
     def test_patch_unique_match(self, tmp_path):
@@ -963,6 +1027,12 @@ class TestExternalSkillMutations:
                 with patch(
                     "tools.skill_usage.get_record",
                     side_effect=lambda n: {"pinned": False},
+                ), patch(
+                    # Ownership runs before the pin guard; mark the skill
+                    # curator-managed so this test still isolates the PIN guard
+                    # (since #67140 an unmarked skill fails closed on ownership).
+                    "tools.skill_usage.load_usage",
+                    return_value={"my-skill": {"created_by": "agent"}},
                 ):
                     raw = skill_manage(
                         action="patch",
@@ -1009,7 +1079,95 @@ class TestExternalSkillMutations:
 
         result = json.loads(raw)
         assert result["success"] is False
-        assert "manually authored" in result["error"].lower()
+        # Refusal must name the ownership reason and point at the supported way
+        # in (`hermes curator adopt`), not just say "no".
+        assert "not curator-managed" in result["error"].lower()
+        assert "curator adopt" in result["error"]
+
+    @pytest.mark.parametrize(
+        ("action", "kwargs"),
+        [
+            ("patch", {"old_string": "Do the thing.", "new_string": "Changed."}),
+            ("edit", {"content": VALID_SKILL_CONTENT_2}),
+            ("delete", {}),
+            (
+                "write_file",
+                {"file_path": "references/new.md", "file_content": "new"},
+            ),
+            ("remove_file", {"file_path": "references/existing.md"}),
+        ],
+    )
+    def test_background_review_fails_closed_without_agent_ownership_record(
+        self, tmp_path, action, kwargs
+    ):
+        """Every autonomous mutation requires positive agent ownership proof."""
+        from tools.skill_provenance import (
+            BACKGROUND_REVIEW,
+            reset_current_write_origin,
+            set_current_write_origin,
+        )
+
+        with _skill_dir(tmp_path):
+            _create_skill("manual-skill", VALID_SKILL_CONTENT)
+            support = tmp_path / "manual-skill" / "references" / "existing.md"
+            support.parent.mkdir(parents=True)
+            support.write_text("keep", encoding="utf-8")
+            before = {
+                path.relative_to(tmp_path): path.read_bytes()
+                for path in tmp_path.rglob("*")
+                if path.is_file()
+            }
+
+            token = set_current_write_origin(BACKGROUND_REVIEW)
+            try:
+                with patch("tools.skill_usage.load_usage", return_value={}):
+                    raw = skill_manage(action=action, name="manual-skill", **kwargs)
+            finally:
+                reset_current_write_origin(token)
+
+            after = {
+                path.relative_to(tmp_path): path.read_bytes()
+                for path in tmp_path.rglob("*")
+                if path.is_file()
+            }
+
+        result = json.loads(raw)
+        assert result["success"] is False
+        # Wording landed as "not curator-managed" (#67140) rather than
+        # "ownership"; the contract asserted here is the refusal + zero writes.
+        assert "not curator-managed" in result["error"].lower()
+        assert before == after
+
+    def test_background_review_fails_closed_when_ownership_lookup_errors(self, tmp_path):
+        from tools.skill_provenance import (
+            BACKGROUND_REVIEW,
+            reset_current_write_origin,
+            set_current_write_origin,
+        )
+
+        with _skill_dir(tmp_path):
+            _create_skill("manual-skill", VALID_SKILL_CONTENT)
+            token = set_current_write_origin(BACKGROUND_REVIEW)
+            try:
+                with patch(
+                    "tools.skill_usage.load_usage",
+                    side_effect=ValueError("corrupt usage data"),
+                ):
+                    raw = skill_manage(
+                        action="patch",
+                        name="manual-skill",
+                        old_string="Do the thing.",
+                        new_string="Changed.",
+                    )
+            finally:
+                reset_current_write_origin(token)
+
+        result = json.loads(raw)
+        assert result["success"] is False
+        assert "ownership" in result["error"].lower()
+        assert "Do the thing." in (
+            tmp_path / "manual-skill" / "SKILL.md"
+        ).read_text(encoding="utf-8")
 
     def test_background_review_allows_agent_created_skill(self, tmp_path):
         """Agent-created skills (created_by='agent') are NOT blocked by the
@@ -1047,10 +1205,168 @@ class TestExternalSkillMutations:
                 reset_current_write_origin(token)
 
         result = json.loads(raw)
-        # Should not be blocked by the manual-skill guard (may be blocked by
+        # Should not be blocked by the ownership guard (may be blocked by
         # the consolidation-delete guard if absorbed_into is empty, but the
-        # manual-skill guard must not fire).
-        assert "manually authored" not in result.get("error", "").lower()
+        # ownership guard must not fire).
+        assert "not curator-managed" not in result.get("error", "").lower()
+
+
+class TestBackgroundOwnershipPolicyConsistency:
+    """The autonomous write policy must not depend on its own side effects.
+
+    Issue #67140: the ownership guard keyed on ``isinstance(usage_rec, dict)``,
+    so a local skill with NO usage record passed. The successful write then
+    called ``bump_patch()``, creating a ``created_by: null`` record — and the
+    identical write was refused from then on. "Allowed exactly once" is a race
+    with our own bookkeeping, not a policy.
+    """
+
+    @staticmethod
+    def _bg_patch(tmp_path, name, old, new):
+        from tools.skill_manager_tool import mark_background_review_skill_read
+        from tools.skill_provenance import (
+            BACKGROUND_REVIEW,
+            reset_current_write_origin,
+            set_current_write_origin,
+        )
+
+        token = set_current_write_origin(BACKGROUND_REVIEW)
+        try:
+            mark_background_review_skill_read(tmp_path / name / "SKILL.md")
+            return json.loads(skill_manage(
+                action="patch", name=name, old_string=old, new_string=new,
+            ))
+        finally:
+            reset_current_write_origin(token)
+
+    def test_missing_record_fails_closed_like_explicit_null(self, tmp_path, monkeypatch):
+        """Both unmanaged record shapes must produce the SAME verdict."""
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path / ".hermes"))
+        with _skill_dir(tmp_path):
+            _create_skill("no-record", VALID_SKILL_CONTENT)
+            with patch("tools.skill_usage.load_usage", return_value={}):
+                missing = self._bg_patch(
+                    tmp_path, "no-record", "Do the thing.", "Do the new thing.",
+                )
+            with patch(
+                "tools.skill_usage.load_usage",
+                return_value={"no-record": {"created_by": None}},
+            ):
+                null_rec = self._bg_patch(
+                    tmp_path, "no-record", "Do the thing.", "Do the new thing.",
+                )
+
+        assert missing["success"] is False
+        assert null_rec["success"] is False
+        assert ("not curator-managed" in missing["error"].lower()
+                and "not curator-managed" in null_rec["error"].lower())
+
+    def test_repeated_identical_write_gets_the_same_answer(self, tmp_path, monkeypatch):
+        """The real #67140 shape: no stubbing of load_usage, so the first write's
+        telemetry side effect is live. Both attempts must agree."""
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path / ".hermes"))
+        (tmp_path / ".hermes" / "skills").mkdir(parents=True, exist_ok=True)
+        with _skill_dir(tmp_path):
+            _create_skill("flip-skill", VALID_SKILL_CONTENT)
+            first = self._bg_patch(
+                tmp_path, "flip-skill", "Do the thing.", "Do the new thing.",
+            )
+            second = self._bg_patch(
+                tmp_path, "flip-skill", "Do the thing.", "Do the new thing.",
+            )
+
+        assert first["success"] == second["success"], (
+            "autonomous write policy flipped between two identical attempts: "
+            f"first={first.get('success')} second={second.get('success')}"
+        )
+        assert first["success"] is False
+
+    def test_refusal_points_at_the_supported_way_in(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path / ".hermes"))
+        with _skill_dir(tmp_path):
+            _create_skill("no-record", VALID_SKILL_CONTENT)
+            with patch("tools.skill_usage.load_usage", return_value={}):
+                res = self._bg_patch(
+                    tmp_path, "no-record", "Do the thing.", "Do the new thing.",
+                )
+        assert "hermes curator adopt no-record" in res["error"]
+
+    def test_foreground_write_to_unmanaged_skill_still_allowed(self, tmp_path, monkeypatch):
+        """Fail-closed applies to AUTONOMOUS writes only. A user-directed
+        foreground edit to their own skill must keep working."""
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path / ".hermes"))
+        with _skill_dir(tmp_path):
+            _create_skill("no-record", VALID_SKILL_CONTENT)
+            with patch("tools.skill_usage.load_usage", return_value={}):
+                res = json.loads(skill_manage(
+                    action="patch", name="no-record",
+                    old_string="Do the thing.", new_string="Do the new thing.",
+                ))
+        assert res["success"] is True
+
+    def test_adopted_skill_becomes_writable_by_autonomous_curation(self, tmp_path, monkeypatch):
+        """Adoption is the documented path from refused to allowed."""
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path / ".hermes"))
+        with _skill_dir(tmp_path):
+            _create_skill("adopt-me", VALID_SKILL_CONTENT)
+            with patch("tools.skill_usage.load_usage", return_value={}):
+                before = self._bg_patch(
+                    tmp_path, "adopt-me", "Do the thing.", "Do the new thing.",
+                )
+            with patch(
+                "tools.skill_usage.load_usage",
+                return_value={"adopt-me": {"created_by": "agent"}},
+            ), patch(
+                "tools.skill_usage.get_record",
+                side_effect=lambda n: {"created_by": "agent", "pinned": False},
+            ):
+                after = self._bg_patch(
+                    tmp_path, "adopt-me", "Do the thing.", "Do the new thing.",
+                )
+
+        assert before["success"] is False
+        assert after["success"] is True, after
+
+
+class TestReviewPromptMatchesEnforcement:
+    """The session-review prompt must only ask for writes enforcement permits.
+
+    Issue #67140 claims 1 and 3: the prompt told the reviewer to patch any
+    skill consulted in the conversation and stated pinned skills could be
+    improved, while the shared background guard refuses both. A prompt that
+    requests refused writes burns review turns on guaranteed failures.
+    """
+
+    @staticmethod
+    def _prompts():
+        from agent import background_review as br
+
+        out = []
+        for attr in ("_SKILL_REVIEW_PROMPT", "_COMBINED_REVIEW_PROMPT"):
+            text = getattr(br, attr, "")
+            if text:
+                out.append((attr, text))
+        assert out, "no review prompts found to check"
+        return out
+
+    def test_prompts_do_not_claim_pinned_skills_are_patchable(self):
+        for attr, text in self._prompts():
+            assert "CAN be improved" not in text, (
+                f"{attr} still tells the reviewer pinned skills are patchable, "
+                "but _background_review_write_guard refuses pinned writes"
+            )
+
+    def test_prompts_list_pinned_and_user_owned_as_protected(self):
+        for attr, text in self._prompts():
+            assert "PINNED skills" in text, f"{attr} omits the pin restriction"
+            assert "USER-OWNED skills" in text, f"{attr} omits the ownership restriction"
+
+    def test_prompts_point_at_adopt_instead_of_patching(self):
+        for attr, text in self._prompts():
+            assert "curator adopt" in text, (
+                f"{attr} does not tell the reviewer what to recommend when the "
+                "right skill is user-owned"
+            )
 
 
 # ---------------------------------------------------------------------------
@@ -1245,6 +1561,15 @@ def _curator_pass(tmp_path, *, monkeypatch):
     (``get_hermes_home()``) resolves into the same tree the skill manager
     searches, and flips ``is_background_review()`` → True so the consolidation
     guard fires.
+
+    Also stubs the ownership check to report every skill as curator-managed.
+    The ownership guard runs BEFORE the consolidation / read-before-write
+    guards these tests target, and since #67140 a skill with no usage record
+    fails closed — so without this, every test in this class would be refused
+    by ownership and never reach the guard under test. The real curator only
+    ever operates on managed sediment, so "managed" is the correct premise
+    here; tests that specifically exercise the ownership guard set their own
+    records instead.
     """
     hermes_home = tmp_path / ".hermes"
     skills_root = hermes_home / "skills"
@@ -1253,6 +1578,7 @@ def _curator_pass(tmp_path, *, monkeypatch):
     with patch("tools.skill_manager_tool.SKILLS_DIR", skills_root), \
          patch("tools.skills_tool.SKILLS_DIR", skills_root), \
          patch("agent.skill_utils.get_all_skills_dirs", return_value=[skills_root]), \
+         patch("tools.skill_usage._is_curator_managed_record", return_value=True), \
          patch("tools.skill_provenance.is_background_review", return_value=True):
         yield skills_root
 
@@ -1273,6 +1599,15 @@ def _skill_content(name: str) -> str:
         "Step 1: Do the thing.\n"
     )
 
+def _create_curator_skill(name: str, content: str):
+    """Create a skill and record the agent ownership a real curator create has."""
+    from tools.skill_usage import mark_agent_created
+
+    result = _create_skill(name, content)
+    assert result["success"] is True, result
+    mark_agent_created(name)
+    return result
+
 
 class TestCuratorConsolidationDeleteGuard:
     """The curator's LLM consolidation pass must fail CLOSED on unverified
@@ -1287,7 +1622,7 @@ class TestCuratorConsolidationDeleteGuard:
 
     def test_bare_prune_during_curator_pass_refused(self, tmp_path, monkeypatch):
         with _curator_pass(tmp_path, monkeypatch=monkeypatch) as skills_root:
-            _create_skill("active-skill", VALID_SKILL_CONTENT)
+            _create_curator_skill("active-skill", VALID_SKILL_CONTENT)
             result = _delete_skill("active-skill", absorbed_into="")
         assert result["success"] is False
         assert result.get("_fail_closed") is True
@@ -1296,7 +1631,7 @@ class TestCuratorConsolidationDeleteGuard:
 
     def test_omitted_absorbed_into_during_curator_pass_refused(self, tmp_path, monkeypatch):
         with _curator_pass(tmp_path, monkeypatch=monkeypatch) as skills_root:
-            _create_skill("active-skill", VALID_SKILL_CONTENT)
+            _create_curator_skill("active-skill", VALID_SKILL_CONTENT)
             result = _delete_skill("active-skill")  # absorbed_into omitted
         assert result["success"] is False
         assert result.get("_fail_closed") is True
@@ -1304,7 +1639,7 @@ class TestCuratorConsolidationDeleteGuard:
 
     def test_whitespace_absorbed_into_during_curator_pass_refused(self, tmp_path, monkeypatch):
         with _curator_pass(tmp_path, monkeypatch=monkeypatch) as skills_root:
-            _create_skill("active-skill", VALID_SKILL_CONTENT)
+            _create_curator_skill("active-skill", VALID_SKILL_CONTENT)
             result = _delete_skill("active-skill", absorbed_into="   ")
         assert result["success"] is False
         assert result.get("_fail_closed") is True
@@ -1312,8 +1647,8 @@ class TestCuratorConsolidationDeleteGuard:
 
     def test_verified_consolidation_archives_recoverably(self, tmp_path, monkeypatch):
         with _curator_pass(tmp_path, monkeypatch=monkeypatch) as skills_root:
-            _create_skill("umbrella", _skill_content("umbrella"))
-            _create_skill("narrow", _skill_content("narrow"))
+            _create_curator_skill("umbrella", _skill_content("umbrella"))
+            _create_curator_skill("narrow", _skill_content("narrow"))
             result = _delete_skill("narrow", absorbed_into="umbrella")
         assert result["success"] is True, result
         assert result.get("_archived") is True
@@ -1328,7 +1663,7 @@ class TestCuratorConsolidationDeleteGuard:
         # The pre-existing target-existence check fires before the recoverable
         # archive — a hallucinated umbrella is refused and the skill stays put.
         with _curator_pass(tmp_path, monkeypatch=monkeypatch) as skills_root:
-            _create_skill("narrow", VALID_SKILL_CONTENT)
+            _create_curator_skill("narrow", VALID_SKILL_CONTENT)
             result = _delete_skill("narrow", absorbed_into="ghost-umbrella")
         assert result["success"] is False
         assert "does not exist" in result["error"]
@@ -1367,7 +1702,7 @@ class TestCuratorConsolidationDeleteGuard:
 
         _reset_background_review_read_marks()
         with _curator_pass(tmp_path, monkeypatch=monkeypatch):
-            _create_skill("reviewed", _skill_content("reviewed"))
+            _create_curator_skill("reviewed", _skill_content("reviewed"))
 
             blocked = json.loads(skill_manage(
                 action="patch",
@@ -1397,7 +1732,7 @@ class TestCuratorConsolidationDeleteGuard:
 
         _reset_background_review_read_marks()
         with _curator_pass(tmp_path, monkeypatch=monkeypatch):
-            _create_skill("reviewed", _skill_content("reviewed"))
+            _create_curator_skill("reviewed", _skill_content("reviewed"))
             ref = tmp_path / ".hermes" / "skills" / "reviewed" / "references"
             ref.mkdir()
             (ref / "workflow.md").write_text("old workflow\n", encoding="utf-8")
diff --git a/tests/tools/test_skill_usage.py b/tests/tools/test_skill_usage.py
index d167fa55916..99f151126bc 100644
--- a/tests/tools/test_skill_usage.py
+++ b/tests/tools/test_skill_usage.py
@@ -786,7 +786,7 @@ def test_end_to_end_telemetry_tracked_but_lifecycle_refused(skills_home):
 
 def test_usage_report_covers_all_provenance(skills_home):
     """usage_report() surfaces every skill with provenance, unlike the
-    curator-scoped agent_created_report()."""
+    curator-scoped curated_report()."""
     from tools.skill_usage import (
         bump_use, usage_report, mark_agent_created,
     )
@@ -813,3 +813,181 @@ def test_usage_report_covers_all_provenance(skills_home):
     for n in rows:
         assert rows[n]["use_count"] == 1
         assert rows[n]["_persisted"] is True
+
+
+# ---------------------------------------------------------------------------
+# Unmanaged enumeration + adoption
+#
+# A skill only becomes curator-managed when ``created_by: agent`` lands on its
+# usage record, and that only happens for background-review creations. Records
+# written before the marker existed carry no key at all, and every foreground
+# `skill_manage(create)` leaves it unset — both are curation-eligible yet
+# invisible to every automatic transition. These tests pin the contract that
+# the blind spot is enumerable and that adoption is an explicit declaration:
+# never inferred from telemetry, never silently reached by the curator.
+# ---------------------------------------------------------------------------
+
+def _seed_usage(skills_dir: Path, records: dict) -> None:
+    (skills_dir / ".usage.json").write_text(
+        json.dumps(records, indent=1), encoding="utf-8"
+    )
+
+
+def test_unmanaged_lists_eligible_skills_without_provenance(skills_home):
+    from tools.skill_usage import list_unmanaged_skill_names
+
+    skills_dir = skills_home / "skills"
+    _write_skill(skills_dir, "legacy")       # record with NO created_by key
+    _write_skill(skills_dir, "foreground")   # created_by present but unset
+    _write_skill(skills_dir, "managed")      # real provenance
+    _seed_usage(skills_dir, {
+        "legacy": {"use_count": 3, "patch_count": 40},
+        "foreground": {"created_by": None, "use_count": 1},
+        "managed": {"created_by": "agent"},
+    })
+
+    names = list_unmanaged_skill_names()
+    assert "legacy" in names
+    assert "foreground" in names
+    assert "managed" not in names
+
+
+def test_unmanaged_excludes_externally_owned_skills(skills_home):
+    from tools.skill_usage import list_unmanaged_skill_names
+
+    skills_dir = skills_home / "skills"
+    _write_skill(skills_dir, "bundled-one")
+    _write_skill(skills_dir, "hub-one")
+    _write_skill(skills_dir, "mine")
+    (skills_dir / ".bundled_manifest").write_text("bundled-one:abc\n", encoding="utf-8")
+    hub = skills_dir / ".hub"
+    hub.mkdir()
+    (hub / "lock.json").write_text(
+        json.dumps({"installed": {"hub-one": {}}}), encoding="utf-8",
+    )
+
+    names = list_unmanaged_skill_names()
+    # Bundled and hub skills have an owner other than the user; adoption is not
+    # the mechanism that governs them.
+    assert "bundled-one" not in names
+    assert "hub-one" not in names
+    assert "mine" in names
+
+
+def test_unmanaged_report_distinguishes_legacy_from_foreground(skills_home):
+    from tools.skill_usage import unmanaged_report
+
+    skills_dir = skills_home / "skills"
+    _write_skill(skills_dir, "legacy")
+    _write_skill(skills_dir, "foreground")
+    _seed_usage(skills_dir, {
+        "legacy": {"use_count": 1},
+        "foreground": {"created_by": None},
+    })
+
+    rows = {r["name"]: r for r in unmanaged_report()}
+    # No created_by key at all => predates the mechanism, authorship unknowable.
+    assert rows["legacy"]["has_provenance_key"] is False
+    # Key present but unset => a foreground create under the current policy.
+    assert rows["foreground"]["has_provenance_key"] is True
+
+
+def test_adopt_marks_skill_curator_managed(skills_home):
+    from tools.skill_usage import adopt_skill, curated_report, list_unmanaged_skill_names
+
+    skills_dir = skills_home / "skills"
+    _write_skill(skills_dir, "legacy")
+    _seed_usage(skills_dir, {"legacy": {"use_count": 2, "patch_count": 9}})
+
+    assert "legacy" in list_unmanaged_skill_names()
+    ok, _msg = adopt_skill("legacy")
+    assert ok is True
+    assert "legacy" in {r["name"] for r in curated_report()}
+    assert "legacy" not in list_unmanaged_skill_names()
+
+
+def test_adopt_preserves_the_inactivity_clock(skills_home):
+    """Adoption must not reset staleness — it hands over an EXISTING history.
+
+    If adopting re-anchored the clock to now, every legacy skill would buy a
+    fresh archive_after_days window, which is the opposite of what the user
+    wants when they hand over a library they already stopped using.
+    """
+    from tools.skill_usage import adopt_skill, get_record, latest_activity_at
+
+    skills_dir = skills_home / "skills"
+    _write_skill(skills_dir, "legacy")
+    _seed_usage(skills_dir, {
+        "legacy": {
+            "use_count": 5,
+            "patch_count": 7,
+            "last_used_at": "2026-04-29T00:00:00+00:00",
+            "created_at": "2026-04-28T00:00:00+00:00",
+        }
+    })
+    before = latest_activity_at(get_record("legacy"))
+
+    ok, _msg = adopt_skill("legacy")
+    assert ok is True
+    rec = get_record("legacy")
+    assert latest_activity_at(rec) == before
+    assert rec["use_count"] == 5
+    assert rec["patch_count"] == 7
+
+
+def test_adopt_is_idempotent(skills_home):
+    from tools.skill_usage import adopt_skill
+
+    skills_dir = skills_home / "skills"
+    _write_skill(skills_dir, "mine")
+    assert adopt_skill("mine")[0] is True
+    ok, msg = adopt_skill("mine")
+    assert ok is True
+    assert "already" in msg
+
+
+@pytest.mark.parametrize("kind", ["bundled", "hub", "protected", "missing"])
+def test_adopt_refuses_skills_the_user_does_not_own(skills_home, monkeypatch, kind):
+    """Adoption writes a provenance claim, so it must refuse anything with an
+    external owner rather than stamping a lie onto the record.
+
+    ``prune_builtins`` is forced ON here — the shipped default — because that
+    is the configuration in which a bundled skill is otherwise curation-
+    eligible. With it off, ``mark_agent_created``'s own eligibility gate would
+    block the write and this test would pass without exercising adopt's guard
+    at all.
+    """
+    from tools import skill_usage
+    from tools.skill_usage import adopt_skill, load_usage
+
+    monkeypatch.setattr(skill_usage, "_prune_builtins_enabled", lambda: True)
+
+    skills_dir = skills_home / "skills"
+    if kind == "bundled":
+        name = "bundled-one"
+        _write_skill(skills_dir, name)
+        (skills_dir / ".bundled_manifest").write_text(f"{name}:abc\n", encoding="utf-8")
+    elif kind == "hub":
+        name = "hub-one"
+        _write_skill(skills_dir, name)
+        hub = skills_dir / ".hub"
+        hub.mkdir()
+        (hub / "lock.json").write_text(
+            json.dumps({"installed": {name: {}}}), encoding="utf-8",
+        )
+    elif kind == "protected":
+        name = sorted(skill_usage.PROTECTED_BUILTIN_SKILLS)[0]
+        _write_skill(skills_dir, name)
+    else:
+        name = "no-such-skill"
+
+    ok, _msg = adopt_skill(name)
+    assert ok is False
+    assert load_usage().get(name, {}).get("created_by") != "agent"
+
+
+def test_adopt_rejects_empty_name(skills_home):
+    from tools.skill_usage import adopt_skill
+
+    assert adopt_skill("")[0] is False
+
diff --git a/tests/tools/test_skills_sync.py b/tests/tools/test_skills_sync.py
index 42d59d78e1e..47f957fda40 100644
--- a/tests/tools/test_skills_sync.py
+++ b/tests/tools/test_skills_sync.py
@@ -395,6 +395,139 @@ class TestExternalDirsIndexing:
         assert result["shadowed_by_external"] == []
 
 
+class TestRenamedBundledSkillRecovery:
+    """Upstream renames/recategorizations must not strand the user's copy.
+
+    ``sync_skills()`` keys the manifest by frontmatter *name*, but computes the
+    destination from the bundled *path*. When upstream moves a skill, the name
+    still matches while the new dest does not exist yet — the pre-fix code fell
+    into its "in manifest but not on disk" branch, misread the skill as
+    user-deleted, and left the old directory stranded at the stale path forever.
+    """
+
+    def _patches(self, bundled, skills_dir, manifest_file):
+        from contextlib import ExitStack
+        stack = ExitStack()
+        stack.enter_context(patch("tools.skills_sync._get_bundled_dir", return_value=bundled))
+        stack.enter_context(
+            patch(
+                "tools.skills_sync._get_optional_dir",
+                return_value=bundled.parent / "optional-skills",
+            )
+        )
+        stack.enter_context(patch("tools.skills_sync.SKILLS_DIR", skills_dir))
+        stack.enter_context(patch("tools.skills_sync.MANIFEST_FILE", manifest_file))
+        return stack
+
+    def _skill(self, root, rel, body="# Body\n"):
+        d = root / rel
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "SKILL.md").write_text(f"---\nname: moved-skill\n---\n{body}")
+        return d
+
+    def test_rename_relocates_unmodified_copy(self, tmp_path):
+        """The stale copy is moved to the new path and updated, not stranded."""
+        bundled = tmp_path / "bundled"
+        skills_dir = tmp_path / "user_skills"
+        manifest_file = skills_dir / ".bundled_manifest"
+
+        # User's copy sits at the OLD path, byte-identical to what sync wrote.
+        old = self._skill(skills_dir, "oldcat/moved-skill")
+        origin_hash = _dir_hash(old)
+        manifest_file.parent.mkdir(parents=True, exist_ok=True)
+        manifest_file.write_text(f"moved-skill:{origin_hash}\n")
+
+        # Upstream moved it to a NEW category and changed the content.
+        self._skill(bundled, "newcat/moved-skill", body="# Updated upstream\n")
+
+        with self._patches(bundled, skills_dir, manifest_file):
+            result = sync_skills(quiet=True)
+            # Manifest now tracks the current bundled hash (read inside the
+            # patch context — MANIFEST_FILE is a module global).
+            recorded = _read_manifest()["moved-skill"]
+
+        new = skills_dir / "newcat" / "moved-skill"
+        assert new.exists(), "renamed skill was not relocated to the new path"
+        assert not old.exists(), "stale copy left behind — would shadow forever"
+        assert "moved-skill" in result["relocated"]
+        # Having been relocated, it then takes the normal update path.
+        assert "moved-skill" in result["updated"]
+        assert "Updated upstream" in (new / "SKILL.md").read_text()
+        # Future syncs can now detect further upstream changes.
+        assert recorded == _dir_hash(bundled / "newcat" / "moved-skill")
+
+    def test_rename_preserves_user_modified_copy(self, tmp_path):
+        """A user-edited copy at the old path is never moved or overwritten."""
+        bundled = tmp_path / "bundled"
+        skills_dir = tmp_path / "user_skills"
+        manifest_file = skills_dir / ".bundled_manifest"
+
+        old = self._skill(skills_dir, "oldcat/moved-skill")
+        origin_hash = _dir_hash(old)
+        # User then edits their copy, so it no longer matches the origin hash.
+        (old / "SKILL.md").write_text("---\nname: moved-skill\n---\n# MY EDITS\n")
+        manifest_file.parent.mkdir(parents=True, exist_ok=True)
+        manifest_file.write_text(f"moved-skill:{origin_hash}\n")
+
+        self._skill(bundled, "newcat/moved-skill", body="# Updated upstream\n")
+
+        with self._patches(bundled, skills_dir, manifest_file):
+            result = sync_skills(quiet=True)
+
+        assert old.exists(), "user's modified copy must not be moved"
+        assert "MY EDITS" in (old / "SKILL.md").read_text()
+        assert "moved-skill" not in result.get("relocated", [])
+
+    def test_rename_does_not_move_hub_installed_skill(self, tmp_path):
+        """A hub-owned path is never relocated — the hub lock owns it."""
+        bundled = tmp_path / "bundled"
+        skills_dir = tmp_path / "user_skills"
+        manifest_file = skills_dir / ".bundled_manifest"
+
+        old = self._skill(skills_dir, "oldcat/moved-skill")
+        origin_hash = _dir_hash(old)
+        manifest_file.parent.mkdir(parents=True, exist_ok=True)
+        manifest_file.write_text(f"moved-skill:{origin_hash}\n")
+
+        lock = skills_dir / ".hub" / "lock.json"
+        lock.parent.mkdir(parents=True, exist_ok=True)
+        lock.write_text(
+            json.dumps(
+                {
+                    "version": 1,
+                    "installed": {
+                        "moved-skill": {"install_path": "oldcat/moved-skill"}
+                    },
+                }
+            )
+        )
+
+        self._skill(bundled, "newcat/moved-skill", body="# Updated upstream\n")
+
+        with self._patches(bundled, skills_dir, manifest_file):
+            result = sync_skills(quiet=True)
+
+        assert old.exists(), "hub-installed skill must not be relocated"
+        assert "moved-skill" not in result.get("relocated", [])
+
+    def test_genuine_user_deletion_still_respected(self, tmp_path):
+        """No copy anywhere on disk = a real deletion; must not be resurrected."""
+        bundled = tmp_path / "bundled"
+        skills_dir = tmp_path / "user_skills"
+        skills_dir.mkdir(parents=True, exist_ok=True)
+        manifest_file = skills_dir / ".bundled_manifest"
+        manifest_file.write_text("moved-skill:deadbeef\n")
+
+        self._skill(bundled, "newcat/moved-skill")
+
+        with self._patches(bundled, skills_dir, manifest_file):
+            result = sync_skills(quiet=True)
+
+        assert not (skills_dir / "newcat" / "moved-skill").exists()
+        assert "moved-skill" not in result["copied"]
+        assert "moved-skill" not in result.get("relocated", [])
+
+
 class TestSyncSkills:
     def _setup_bundled(self, tmp_path):
         """Create a fake bundled skills directory."""
@@ -773,6 +906,87 @@ class TestSyncSkills:
         assert result["optional_provenance_backfilled"] == []
         assert not (skills_dir / ".hub" / "lock.json").exists()
 
+    def test_backfills_optional_provenance_for_relocated_skill(self, tmp_path):
+        """Upstream recategorization must not blind provenance repair.
+
+        When a skill was installed at ``mlops/chroma`` and upstream later moved
+        it to ``mlops/vector-databases/chroma``, the repo-derived install path
+        no longer exists in the active tree. A path-only lookup skips it
+        forever, so `hermes skills repair-optional` can never fix it. The
+        recorded install_path must be the ACTUAL location, not the repo's.
+        """
+        bundled = self._setup_bundled(tmp_path)
+        optional = tmp_path / "optional-skills"
+        optional_skill = optional / "mlops" / "vector-databases" / "chroma"
+        optional_skill.mkdir(parents=True)
+        (optional_skill / "SKILL.md").write_text("---\nname: chroma\n---\n# Chroma\n")
+
+        skills_dir = tmp_path / "user_skills"
+        manifest_file = skills_dir / ".bundled_manifest"
+        # Installed under the OLD category path.
+        active = skills_dir / "mlops" / "chroma"
+        active.mkdir(parents=True)
+        (active / "SKILL.md").write_text("---\nname: chroma\n---\n# Chroma\n")
+
+        with self._patches(bundled, skills_dir, manifest_file):
+            with patch("tools.skills_sync._get_optional_dir", return_value=optional):
+                result = sync_skills(quiet=True)
+
+        assert result["optional_provenance_backfilled"] == ["chroma"]
+        data = json.loads((skills_dir / ".hub" / "lock.json").read_text())
+        entry = data["installed"]["chroma"]
+        assert entry["source"] == "official"
+        assert entry["install_path"] == "mlops/chroma"
+
+    def test_relocated_backfill_still_requires_identical_content(self, tmp_path):
+        """The name fallback must not weaken the content check.
+
+        Finding the skill by name is only a locator; a locally-edited copy is
+        still the user's and must not be claimed as official.
+        """
+        bundled = self._setup_bundled(tmp_path)
+        optional = tmp_path / "optional-skills"
+        optional_skill = optional / "mlops" / "vector-databases" / "chroma"
+        optional_skill.mkdir(parents=True)
+        (optional_skill / "SKILL.md").write_text("---\nname: chroma\n---\n# upstream\n")
+
+        skills_dir = tmp_path / "user_skills"
+        manifest_file = skills_dir / ".bundled_manifest"
+        active = skills_dir / "mlops" / "chroma"
+        active.mkdir(parents=True)
+        (active / "SKILL.md").write_text("---\nname: chroma\n---\n# LOCALLY EDITED\n")
+
+        with self._patches(bundled, skills_dir, manifest_file):
+            with patch("tools.skills_sync._get_optional_dir", return_value=optional):
+                result = sync_skills(quiet=True)
+
+        assert result["optional_provenance_backfilled"] == []
+
+    def test_relocated_backfill_refuses_ambiguous_names(self, tmp_path):
+        """Two installed dirs sharing a name give no basis to pick one.
+
+        Guessing would write official provenance onto the wrong skill, so the
+        fallback must decline rather than choose.
+        """
+        bundled = self._setup_bundled(tmp_path)
+        optional = tmp_path / "optional-skills"
+        optional_skill = optional / "cat" / "dupe"
+        optional_skill.mkdir(parents=True)
+        (optional_skill / "SKILL.md").write_text("---\nname: dupe\n---\n# D\n")
+
+        skills_dir = tmp_path / "user_skills"
+        manifest_file = skills_dir / ".bundled_manifest"
+        for parent in ("x", "y"):
+            d = skills_dir / parent / "dupe"
+            d.mkdir(parents=True)
+            (d / "SKILL.md").write_text("---\nname: dupe\n---\n# D\n")
+
+        with self._patches(bundled, skills_dir, manifest_file):
+            with patch("tools.skills_sync._get_optional_dir", return_value=optional):
+                result = sync_skills(quiet=True)
+
+        assert result["optional_provenance_backfilled"] == []
+
     def test_repair_official_optional_restores_reorganized_skill_with_backup(self, tmp_path):
         bundled = self._setup_bundled(tmp_path)
         optional = tmp_path / "optional-skills"
diff --git a/tests/tools/test_snapshot_session_id_leak.py b/tests/tools/test_snapshot_session_id_leak.py
new file mode 100644
index 00000000000..c48555988ae
--- /dev/null
+++ b/tests/tools/test_snapshot_session_id_leak.py
@@ -0,0 +1,113 @@
+"""Cross-session HERMES_SESSION_ID leak via the shared bash snapshot.
+
+Regression coverage for the bug where a single long-lived backend serves many
+sessions through ONE ``_active_environments["default"]`` LocalEnvironment (the
+messaging gateway, TUI, and desktop/web dashboard all collapse the terminal to
+"default"). That environment persists a bash *session snapshot* file and
+``source``s it before every command. ``export -p`` dumped the FIRST session's
+``HERMES_SESSION_ID`` into the snapshot, so every LATER session ``source``d that
+stale value and its ``echo $HERMES_SESSION_ID`` reported a FOREIGN session's id
+— overriding the correct per-command Popen env injected by
+``_inject_session_context_env``.
+
+The fix strips the per-session bridged vars (HERMES_SESSION_* / UI /
+CRON_AUTO_DELIVER_) from the snapshot at both dump sites in
+``tools/environments/base.py``; they are re-injected fresh on every command.
+"""
+
+import os
+import re
+import sys
+
+import pytest
+
+from tools.environments.base import (
+    _SNAPSHOT_EXCLUDED_ENV_REGEX,
+    _export_dump_excluding_session_vars,
+)
+
+
+# ---------------------------------------------------------------------------
+# Unit: the exclusion regex matches exactly the bridged vars, nothing else.
+# ---------------------------------------------------------------------------
+
+def test_regex_matches_bridged_session_vars():
+    rx = re.compile(_SNAPSHOT_EXCLUDED_ENV_REGEX)
+    # Every var the gateway bridges must be excluded.
+    from gateway.session_context import _VAR_MAP
+
+    for name in _VAR_MAP:
+        line = f'declare -x {name}="whatever"'
+        assert rx.search(line), f"{name} should be excluded from the snapshot"
+
+
+def test_regex_preserves_user_env():
+    rx = re.compile(_SNAPSHOT_EXCLUDED_ENV_REGEX)
+    for line in (
+        'declare -x PATH="/usr/bin:/bin"',
+        'declare -x HOME="/home/user"',
+        'declare -x HERMES_HOME="/home/user/.hermes"',  # NOT a session var
+        'declare -x HERMESX="x"',
+        'declare -x MY_HERMES_SESSION_ID="x"',  # prefix must anchor after "declare -x "
+    ):
+        assert not rx.search(line), f"{line!r} must be preserved in the snapshot"
+
+
+def test_export_snippet_shape():
+    snippet = _export_dump_excluding_session_vars("/tmp/snap.tmp.$BASHPID")
+    assert "export -p" in snippet
+    assert "grep -vE" in snippet
+    assert "/tmp/snap.tmp.$BASHPID" in snippet
+    # The redirection must be attached to a brace group wrapping the pipeline,
+    # NOT to the grep segment: a redirect on grep expands $BASHPID inside
+    # grep's pipeline subshell (a different PID than the parent shell that
+    # expands the follow-up ``mv`` operand), silently orphaning the dump and
+    # breaking snapshot env persistence entirely.
+    assert snippet.lstrip().startswith("{ ")
+    assert "|| true; }" in snippet
+    assert snippet.rstrip().endswith("> /tmp/snap.tmp.$BASHPID")
+
+
+# ---------------------------------------------------------------------------
+# Integration: real LocalEnvironment, two sessions, no cross-contamination.
+# ---------------------------------------------------------------------------
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX bash snapshot path")
+def test_shared_snapshot_no_cross_session_leak(tmp_path):
+    import threading
+
+    from gateway.session_context import _VAR_MAP, _UNSET, set_session_vars
+    from tools.environments.local import LocalEnvironment
+
+    env = LocalEnvironment(cwd=str(tmp_path), timeout=30)
+    env.init_session()
+    try:
+        def run_as(sid):
+            out = {}
+
+            def worker():
+                for v in _VAR_MAP.values():
+                    v.set(_UNSET)
+                set_session_vars(session_key="k" + sid, session_id=sid, source="desktop")
+                out["r"] = env.execute('echo "[$HERMES_SESSION_ID]"')
+
+            t = threading.Thread(target=worker)
+            t.start()
+            t.join()
+            return out["r"].get("output", "")
+
+        out_a = run_as("SIDAAA")
+        out_b = run_as("SIDBBB")
+
+        assert "SIDAAA" in out_a, f"session A saw {out_a!r}"
+        # The core assertion: B must see its OWN id, not A's leaked via snapshot.
+        assert "SIDBBB" in out_b, f"session B saw {out_b!r}"
+        assert "SIDAAA" not in out_b, f"session B leaked A's id: {out_b!r}"
+
+        # And the snapshot file must not carry the session id at all.
+        snap = env._snapshot_path
+        if os.path.exists(snap):
+            with open(snap) as f:
+                assert "HERMES_SESSION_ID" not in f.read()
+    finally:
+        env.cleanup()
diff --git a/tests/tools/test_subprocess_utf8_encoding.py b/tests/tools/test_subprocess_utf8_encoding.py
new file mode 100644
index 00000000000..72e2f8c52e3
--- /dev/null
+++ b/tests/tools/test_subprocess_utf8_encoding.py
@@ -0,0 +1,68 @@
+"""Regression test for issue #53428 — subprocess.run(text=True) without
+explicit ``encoding=`` triggers ``UnicodeDecodeError`` on Chinese Windows
+(cp936/GBK default encoding).
+
+PR #55339 covers 21 call sites in ``agent/``, ``gateway/``, ``cli.py``,
+``cron/``, plus 5 more in ``tools/`` and ``hermes_cli/`` (main.py,
+setup.py, tts_tool.py, transcription_tools.py). The two call sites it
+misses — ``hermes_cli/onepassword_secrets_cli.py::_op_whoami`` and
+``_op_version`` — are guarded here.
+
+Without ``encoding=``, ``text=True`` decodes child output with
+``locale.getpreferredencoding(False)`` — cp936 on Chinese Windows —
+which crashes on non-GBK bytes (issues #47939, #53428, #57238).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+
+def _assert_utf8_kwargs(mock_run):
+    """Lift the encoding/errors kwargs out of the mock and assert them."""
+    assert mock_run.called, "subprocess.run was not called"
+    kwargs = mock_run.call_args.kwargs
+    assert kwargs.get("encoding") == "utf-8", (
+        f"subprocess.run called without encoding='utf-8' "
+        f"(got encoding={kwargs.get('encoding')!r}). "
+        f"On Chinese Windows (cp936), text=True without explicit encoding "
+        f"crashes with UnicodeDecodeError on non-GBK bytes. See #53428."
+    )
+    assert kwargs.get("errors") == "replace", (
+        f"subprocess.run called without errors='replace' "
+        f"(got errors={kwargs.get('errors')!r}). encoding='utf-8' alone "
+        f"still raises UnicodeDecodeError on non-UTF-8 bytes emitted by "
+        f"Windows-native CLIs. See #53428."
+    )
+
+
+def test_op_whoami_passes_utf8_encoding(tmp_path):
+    """_op_whoami must pass encoding='utf-8', errors='replace' so op CLI
+    output containing non-ASCII account names doesn't crash on cp936."""
+    from hermes_cli import onepassword_secrets_cli as op_cli
+
+    fake_binary = tmp_path / "op"
+    fake_binary.write_bytes(b"")
+    with patch.object(op_cli.subprocess, "run") as mock_run:
+        mock_run.return_value = MagicMock(
+            returncode=0, stdout="user@example.com", stderr=""
+        )
+        op_cli._op_whoami(fake_binary, account="")
+    _assert_utf8_kwargs(mock_run)
+
+
+def test_op_version_passes_utf8_encoding(tmp_path):
+    """_op_version must pass encoding='utf-8', errors='replace' so op CLI
+    output containing non-ASCII bytes doesn't crash on cp936. Pairs with
+    _op_whoami — both run in the same setup/status CLI flow."""
+    from hermes_cli import onepassword_secrets_cli as op_cli
+
+    fake_binary = tmp_path / "op"
+    fake_binary.write_bytes(b"")
+    with patch.object(op_cli.subprocess, "run") as mock_run:
+        mock_run.return_value = MagicMock(
+            returncode=0, stdout="2.24.0", stderr=""
+        )
+        op_cli._op_version(fake_binary)
+    _assert_utf8_kwargs(mock_run)
diff --git a/tests/tools/test_tool_search.py b/tests/tools/test_tool_search.py
index 9c8c8a33c17..117047ecfeb 100644
--- a/tests/tools/test_tool_search.py
+++ b/tests/tools/test_tool_search.py
@@ -44,7 +44,7 @@ class TestConfigParsing:
         from tools.tool_search import ToolSearchConfig
         cfg = ToolSearchConfig.from_raw(None)
         assert cfg.enabled == "auto"
-        assert cfg.threshold_pct == 10.0
+        assert cfg.threshold_pct == 5.0
 
     def test_bool_true_maps_to_auto(self):
         from tools.tool_search import ToolSearchConfig
@@ -149,24 +149,29 @@ class TestThresholdGate:
         cfg = ToolSearchConfig.from_raw({"enabled": "on"})
         assert should_activate(cfg, deferrable_tokens=100, context_length=200_000)
 
-    def test_auto_below_threshold_does_not_activate(self):
+    def test_auto_activates_with_any_deferrable(self):
+        """Tiered disclosure: ANY deferrable tool activates the bridge —
+        the threshold now bounds the listing, not activation."""
         from tools.tool_search import ToolSearchConfig, should_activate
         cfg = ToolSearchConfig.from_raw({"enabled": "auto", "threshold_pct": 10})
-        # 5% of 200K = below 10% threshold
-        assert not should_activate(cfg, deferrable_tokens=10_000, context_length=200_000)
-
-    def test_auto_at_or_above_threshold_activates(self):
-        from tools.tool_search import ToolSearchConfig, should_activate
-        cfg = ToolSearchConfig.from_raw({"enabled": "auto", "threshold_pct": 10})
-        assert should_activate(cfg, deferrable_tokens=20_000, context_length=200_000)
+        assert should_activate(cfg, deferrable_tokens=100, context_length=200_000)
         assert should_activate(cfg, deferrable_tokens=50_000, context_length=200_000)
+        # unknown context length: still activates
+        assert should_activate(cfg, deferrable_tokens=100, context_length=0)
 
-    def test_auto_without_context_length_uses_20k_cutoff(self):
-        """Fallback cutoff used when the active model is unknown."""
-        from tools.tool_search import ToolSearchConfig, should_activate
-        cfg = ToolSearchConfig.from_raw({"enabled": "auto"})
-        assert not should_activate(cfg, deferrable_tokens=10_000, context_length=0)
-        assert should_activate(cfg, deferrable_tokens=25_000, context_length=0)
+    def test_listing_budget_min_of_pct_and_cap(self):
+        from tools.tool_search import ToolSearchConfig, listing_token_budget
+        cfg = ToolSearchConfig.from_raw(
+            {"threshold_pct": 5, "listing_max_tokens": 8000})
+        # 5% of 200K = 10K > cap 8K → cap wins
+        assert listing_token_budget(cfg, 200_000) == 8000
+        # 5% of 50K = 2.5K < cap 8K → pct leg wins
+        assert listing_token_budget(cfg, 50_000) == 2500
+        # unknown context → 10K fallback for the pct leg, still capped
+        assert listing_token_budget(cfg, 0) == 8000
+        assert listing_token_budget(cfg, None) == 8000
+        # default threshold is 5%
+        assert ToolSearchConfig.from_raw(None).threshold_pct == 5.0
 
     def test_token_estimate_proportional_to_schema_size(self):
         from tools.tool_search import estimate_tokens_from_schemas
@@ -250,20 +255,107 @@ class TestAssembly:
         assert not result.activated
         assert {t["function"]["name"] for t in result.tool_defs} == {"terminal", "read_file"}
 
-    def test_below_threshold_returns_unchanged(self):
-        """Tiny deferrable surface: don't bother."""
+    @staticmethod
+    def _register_mcp(name):
+        from tools.registry import registry
+
+        def _handler(args, task_id=None, **kw):
+            return json.dumps({"ok": True})
+
+        registry.register(
+            name=name,
+            handler=_handler,
+            schema=_td(name, "Deferred capability description.")["function"],
+            toolset="mcp-tiertest",
+        )
+
+    def test_small_deferrable_surface_defers_with_full_listing(self):
+        """Tiered disclosure: even a tiny MCP/plugin surface defers (tier 1),
+        with the full name+description listing embedded."""
         from tools.tool_search import assemble_tool_defs, ToolSearchConfig
-        # _td renders to ~80 chars / 20 tokens. 3 of them = ~60 tokens.
-        # 10% of 200K = 20K. Way below.
-        defs = [_td("unknown_tool_a"), _td("unknown_tool_b"), _td("unknown_tool_c")]
+        for n in ("tier_small_a", "tier_small_b", "tier_small_c"):
+            self._register_mcp(n)
+        defs = [_td("terminal", "Run shell")] + [
+            _td(n, "Deferred capability description.")
+            for n in ("tier_small_a", "tier_small_b", "tier_small_c")]
         result = assemble_tool_defs(
             defs,
             context_length=200_000,
             config=ToolSearchConfig.from_raw({"enabled": "auto", "threshold_pct": 10}),
         )
-        assert not result.activated
+        assert result.activated
+        assert result.tier == 1
+        assert result.listing_form == "full"
         names = {(t.get("function") or {}).get("name") for t in result.tool_defs}
-        assert "tool_search" not in names
+        assert "tool_search" in names
+        assert "terminal" in names  # core stays eager
+        search = next(t for t in result.tool_defs
+                      if t["function"]["name"] == "tool_search")
+        assert "tier_small_a" in search["function"]["description"]
+
+    def test_oversized_catalog_degrades_to_server_summary_tier2(self):
+        """When even the names-only listing exceeds the budget, tier 2:
+        bare bridge + one-line-per-server summary (no per-tool names)."""
+        from tools.tool_search import assemble_tool_defs, ToolSearchConfig
+        names = [f"tier2_very_long_tool_name_number_{i:04d}_extra" for i in range(400)]
+        for n in names:
+            self._register_mcp(n)
+        defs = [_td(n, "A description that will not matter at this size.")
+                for n in names]
+        result = assemble_tool_defs(
+            defs,
+            context_length=200_000,
+            config=ToolSearchConfig.from_raw(
+                {"enabled": "auto", "threshold_pct": 10, "listing_max_tokens": 200}),
+        )
+        assert result.activated
+        assert result.tier == 2
+        assert result.listing_form == "groups"
+        search = next(t for t in result.tool_defs
+                      if t["function"]["name"] == "tool_search")
+        desc = search["function"]["description"]
+        # No individual tool names...
+        assert "tier2_very_long_tool_name_number_0000" not in desc
+        # ...but the server (toolset) is named with its tool count, and the
+        # model is told to search rather than substitute/deny.
+        assert "tiertest" in desc
+        assert "(400 tools" in desc
+        assert "search here FIRST" in desc
+
+    def test_mixed_catalog_small_server_keeps_listing(self):
+        """Per-server degradation: an oversized server collapses to a
+        summary line while a small co-attached server keeps per-tool names
+        (the Cloudflare+Linear shape)."""
+        from tools.tool_search import build_catalog_listing_with_form
+        from tools.registry import registry
+        import json as _json
+
+        def _h(args, task_id=None, **kw):
+            return _json.dumps({"ok": True})
+
+        big = [f"bigsrv_tool_{i:04d}_with_a_long_name" for i in range(300)]
+        small = ["smallsrv_create_item", "smallsrv_list_items"]
+        for n in big:
+            registry.register(name=n, handler=_h,
+                              schema=_td(n, "Big server tool.")["function"],
+                              toolset="mcp-bigsrv")
+        for n in small:
+            registry.register(name=n, handler=_h,
+                              schema=_td(n, "Small server tool.")["function"],
+                              toolset="mcp-smallsrv")
+        defs = ([_td(n, "Big server tool.") for n in big]
+                + [_td(n, "Small server tool.") for n in small])
+        # Budget fits the small server's lines + big server's summary,
+        # but not the big server's 300 names.
+        text, form = build_catalog_listing_with_form(defs, max_tokens=300)
+        assert form == "mixed"
+        assert text is not None
+        assert "smallsrv_create_item" in text          # small server listed
+        assert "bigsrv_tool_0000" not in text          # big server names dropped
+        assert "bigsrv (300 tools" in text             # ...but summarized
+        # deterministic (cache safety)
+        text2, _ = build_catalog_listing_with_form(list(reversed(defs)), max_tokens=300)
+        assert text == text2
 
     def test_idempotent_when_bridge_already_present(self):
         from tools.tool_search import assemble_tool_defs, ToolSearchConfig, BRIDGE_TOOL_NAMES
@@ -536,3 +628,114 @@ class TestRegression_ToolsetScoping:
         # core tools are never deferrable
         assert "terminal" not in names
 
+
+
+# ---------------------------------------------------------------------------
+# Catalog listing (skills-style progressive disclosure)
+# ---------------------------------------------------------------------------
+
+
+class TestCatalogListing:
+    def test_config_defaults(self):
+        from tools.tool_search import ToolSearchConfig
+        cfg = ToolSearchConfig.from_raw(None)
+        assert cfg.listing == "auto"
+        assert cfg.listing_max_tokens == 20000
+        # legacy bool shapes keep defaults too
+        assert ToolSearchConfig.from_raw(True).listing == "auto"
+
+    def test_config_listing_off_and_clamp(self):
+        from tools.tool_search import ToolSearchConfig
+        cfg = ToolSearchConfig.from_raw({"listing": "off", "listing_max_tokens": 999999})
+        assert cfg.listing == "off"
+        assert cfg.listing_max_tokens == 60000
+        cfg2 = ToolSearchConfig.from_raw({"listing": "garbage", "listing_max_tokens": -5})
+        assert cfg2.listing == "auto"
+        assert cfg2.listing_max_tokens == 200
+
+    def test_short_desc_first_sentence_and_clip(self):
+        from tools.tool_search import _short_desc
+        assert _short_desc("Open an issue. Second sentence dropped.") == "Open an issue."
+        long = "word " * 40
+        s = _short_desc(long)
+        assert len(s) <= 61  # 60 + ellipsis char
+        assert s.endswith("…")
+        assert _short_desc("") == ""
+
+    def test_listing_grouped_and_deterministic(self):
+        from tools.tool_search import build_catalog_listing
+        defs = [
+            _td("zeta_tool", "Does zeta."),
+            _td("alpha_tool", "Does alpha."),
+        ]
+        a = build_catalog_listing(defs)
+        b = build_catalog_listing(list(reversed(defs)))
+        assert a == b  # byte-stable regardless of input order (cache safety)
+        assert a.index("alpha_tool") < a.index("zeta_tool")
+
+    def test_listing_budget_falls_back_to_names_then_none(self):
+        from tools.tool_search import build_catalog_listing
+        defs = [_td(f"tool_{i:03d}", "A tool that does something moderately verbose.")
+                for i in range(50)]
+        full = build_catalog_listing(defs, max_tokens=20000)
+        assert full is not None and "- tool_000:" in full
+        names_only = build_catalog_listing(defs, max_tokens=300)
+        assert names_only is not None
+        assert "- tool_000:" not in names_only  # descriptions dropped
+        assert "tool_000" in names_only
+        assert build_catalog_listing(defs, max_tokens=200) is None or "tool_000" in build_catalog_listing(defs, max_tokens=200)
+
+    def test_bridge_embeds_listing(self):
+        from tools.tool_search import bridge_tool_schemas
+        bridges = bridge_tool_schemas(5, listing="github tools (2):\n- a: x\n- b: y")
+        search = next(b for b in bridges if b["function"]["name"] == "tool_search")
+        assert "github tools (2)" in search["function"]["description"]
+        assert "do NOT claim it is unavailable" in search["function"]["description"]
+        # other bridges unchanged
+        bare = bridge_tool_schemas(5)
+        assert bare[1] == bridges[1] and bare[2] == bridges[2]
+
+    @staticmethod
+    def _register(name):
+        from tools.registry import registry
+
+        def _handler(args, task_id=None, **kw):
+            return json.dumps({"ok": True})
+
+        registry.register(
+            name=name,
+            handler=_handler,
+            schema=_td(name, "Deferred capability description.")["function"],
+            toolset="mcp-listingtest",
+        )
+
+    def test_assembly_embeds_listing_when_active(self):
+        from tools.tool_search import assemble_tool_defs, ToolSearchConfig
+        for i in range(30):
+            self._register(f"mcp_x_{i}")
+        defs = [_td("terminal", "Run shell")] + [
+            _td(f"mcp_x_{i}", "Deferred capability description.",
+                {"a": {"type": "string", "description": "x" * 200}})
+            for i in range(30)
+        ]
+        result = assemble_tool_defs(
+            defs, context_length=200_000,
+            config=ToolSearchConfig.from_raw({"enabled": "on"}),
+        )
+        assert result.activated
+        search = next(t for t in result.tool_defs if t["function"]["name"] == "tool_search")
+        assert "mcp_x_0" in search["function"]["description"]
+        assert "listingtest tools (30):" in search["function"]["description"]
+
+    def test_assembly_listing_off_keeps_legacy_description(self):
+        from tools.tool_search import assemble_tool_defs, ToolSearchConfig
+        for i in range(30):
+            self._register(f"mcp_x_{i}")
+        defs = [_td(f"mcp_x_{i}", "Deferred.") for i in range(30)]
+        result = assemble_tool_defs(
+            defs, context_length=1000,
+            config=ToolSearchConfig.from_raw({"enabled": "on", "listing": "off"}),
+        )
+        assert result.activated
+        search = next(t for t in result.tool_defs if t["function"]["name"] == "tool_search")
+        assert "mcp_x_0" not in search["function"]["description"]
diff --git a/tests/tools/test_url_safety.py b/tests/tools/test_url_safety.py
index 18ebb8bb04d..1dcf36fd0c1 100644
--- a/tests/tools/test_url_safety.py
+++ b/tests/tools/test_url_safety.py
@@ -135,11 +135,67 @@ class TestIsSafeUrl:
         ]):
             assert is_safe_url("http://[::1]:8080/") is False
 
-    def test_dns_failure_blocked(self):
-        """DNS failures now fail closed — block the request."""
+    def test_dns_failure_blocked(self, monkeypatch):
+        """DNS failures fail closed — block the request (no proxy configured)."""
+        for var in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"):
+            monkeypatch.delenv(var, raising=False)
         with patch("socket.getaddrinfo", side_effect=socket.gaierror("Name resolution failed")):
             assert is_safe_url("https://nonexistent.example.com") is False
 
+
+class TestProxyEnvironmentDnsDelegation:
+    """When an HTTP proxy is configured, DNS is delegated to the proxy.
+
+    Sandbox / proxy-only environments (Docker + Squid, NVIDIA OpenShell,
+    iron-proxy egress sandboxes) block direct DNS at the network level;
+    only HTTP(S) via the proxy works. is_safe_url must not fail closed on
+    the pre-flight DNS check there — the proxy is the egress boundary.
+    Regression tests for #32217 / PR #68469.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _clear_proxy_env(self, monkeypatch):
+        for var in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"):
+            monkeypatch.delenv(var, raising=False)
+
+    def test_dns_failure_allowed_when_proxy_configured(self, monkeypatch):
+        monkeypatch.setenv("HTTPS_PROXY", "http://host.docker.internal:9090")
+        with patch("socket.getaddrinfo", side_effect=socket.gaierror("blocked at network level")):
+            assert is_safe_url("https://api.openai.com/v1/models") is True
+
+    def test_lowercase_proxy_var_also_recognized(self, monkeypatch):
+        monkeypatch.setenv("http_proxy", "http://proxy.internal:3128")
+        with patch("socket.getaddrinfo", side_effect=socket.gaierror("no dns")):
+            assert is_safe_url("https://example.com/") is True
+
+    def test_metadata_hostname_still_blocked_with_proxy(self, monkeypatch):
+        """The blocked-hostname floor runs BEFORE the DNS skip."""
+        monkeypatch.setenv("HTTPS_PROXY", "http://proxy.internal:3128")
+        with patch("socket.getaddrinfo", side_effect=socket.gaierror("no dns")):
+            assert is_safe_url("http://metadata.google.internal/computeMetadata/v1/") is False
+
+    def test_literal_metadata_ip_still_blocked_with_proxy(self, monkeypatch):
+        """Literal IPs never take the DNS-failure path — floor intact."""
+        monkeypatch.setenv("HTTPS_PROXY", "http://proxy.internal:3128")
+        assert is_safe_url("http://169.254.169.254/latest/meta-data/") is False
+
+    def test_literal_private_ip_still_blocked_with_proxy(self, monkeypatch):
+        monkeypatch.setenv("HTTPS_PROXY", "http://proxy.internal:3128")
+        assert is_safe_url("http://192.168.1.1/admin") is False
+
+    def test_dns_success_path_unchanged_with_proxy(self, monkeypatch):
+        """When DNS resolves, the normal IP checks still apply under a proxy."""
+        monkeypatch.setenv("HTTPS_PROXY", "http://proxy.internal:3128")
+        with patch("socket.getaddrinfo", return_value=[
+            (2, 1, 6, "", ("10.0.0.5", 0)),
+        ]):
+            assert is_safe_url("https://internal.corp/") is False
+
+    def test_empty_proxy_var_does_not_trigger_delegation(self, monkeypatch):
+        monkeypatch.setenv("HTTPS_PROXY", "")
+        with patch("socket.getaddrinfo", side_effect=socket.gaierror("fail")):
+            assert is_safe_url("https://nonexistent.example.com") is False
+
     def test_empty_url_blocked(self):
         assert is_safe_url("") is False
 
@@ -275,7 +331,9 @@ class TestIsSafeUrl:
         ]):
             assert is_safe_url("http://multimedia.nt.qq.com.cn/download?id=123") is False
 
-    def test_qq_multimedia_hostname_dns_failure_still_blocked(self):
+    def test_qq_multimedia_hostname_dns_failure_still_blocked(self, monkeypatch):
+        for var in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"):
+            monkeypatch.delenv(var, raising=False)
         with patch("socket.getaddrinfo", side_effect=socket.gaierror("Name resolution failed")):
             assert is_safe_url("https://multimedia.nt.qq.com.cn/download?id=123") is False
 
@@ -637,6 +695,8 @@ class TestAllowPrivateUrlsIntegration:
     def test_dns_failure_still_blocked_with_toggle(self, monkeypatch):
         """DNS failures are still blocked even with toggle on."""
         monkeypatch.setenv("HERMES_ALLOW_PRIVATE_URLS", "true")
+        for var in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"):
+            monkeypatch.delenv(var, raising=False)
         with patch("socket.getaddrinfo", side_effect=socket.gaierror("fail")):
             assert is_safe_url("https://nonexistent.example.com") is False
 
diff --git a/tests/tools/test_windows_native_support.py b/tests/tools/test_windows_native_support.py
index 58bbc007a50..b4187cf02a0 100644
--- a/tests/tools/test_windows_native_support.py
+++ b/tests/tools/test_windows_native_support.py
@@ -11,8 +11,10 @@ Windows runner.
 
 from __future__ import annotations
 
+import asyncio
 import os
 import signal
+import subprocess
 import sys
 from pathlib import Path
 from unittest import mock
@@ -1139,3 +1141,199 @@ class TestWindowlessGatewayRestartSpec:
         assert cwd == "C:/hermes"
         assert env["VIRTUAL_ENV"] == str(Path("C:/venv"))
         assert "PYTHONPATH" in env
+
+
+# ---------------------------------------------------------------------------
+# gateway/run.py :: GatewayRunner._launch_detached_restart_command
+# outer watcher Popen breakaway-denied fallback (PR #42993)
+# ---------------------------------------------------------------------------
+
+
+class TestGatewayRunRestartWatcherOuterPopenFallback:
+    """The Windows ``/restart`` watcher in ``gateway.run`` spawns an outer
+    detached ``python -c <watcher>`` process with
+    ``windows_detach_popen_kwargs()`` (which carries
+    ``CREATE_BREAKAWAY_FROM_JOB``).  A restrictive parent job object rejects
+    the breakaway bit with ``ERROR_ACCESS_DENIED`` (surfaced as ``OSError``);
+    the launcher must retry once without breakaway, preserving argv and the
+    scrubbed environment, and only warn — never crash, never leak secrets —
+    if the retry also fails.
+
+    Behavioral: drives the real coroutine with a mocked ``subprocess.Popen``
+    rather than asserting on source text.  Runs on Linux CI via a
+    ``sys.platform`` patch; the breakaway-bit assertions are gated on the
+    real host being Windows because ``_subprocess_compat`` caches
+    ``IS_WINDOWS`` at import time.
+    """
+
+    @staticmethod
+    def _fake_self():
+        from types import SimpleNamespace
+
+        return SimpleNamespace(
+            _detached_restart_helper_started=False,
+            _restart_drain_timeout=0.0,
+        )
+
+    @classmethod
+    def _drive(cls, gr):
+        asyncio.run(
+            gr.GatewayRunner._launch_detached_restart_command(cls._fake_self())
+        )
+
+    def test_outer_watcher_retries_without_breakaway_on_oserror(self, monkeypatch):
+        import gateway.run as gr
+        from hermes_cli._subprocess_compat import (
+            IS_WINDOWS,
+            windows_detach_flags_without_breakaway,
+            windows_detach_popen_kwargs,
+        )
+
+        monkeypatch.setattr(gr.sys, "platform", "win32")
+        monkeypatch.setattr(gr, "_resolve_hermes_bin", lambda: ["hermes"])
+
+        calls = []
+
+        def fake_popen(argv, **kwargs):
+            calls.append((argv, kwargs))
+            if len(calls) == 1:
+                raise OSError(5, "Access is denied")  # ERROR_ACCESS_DENIED
+            return MagicMock()
+
+        monkeypatch.setattr("subprocess.Popen", fake_popen)
+
+        self._drive(gr)
+
+        assert len(calls) == 2, "outer watcher must retry exactly once on OSError"
+        (argv1, kw1), (argv2, kw2) = calls
+
+        # argv is identical across primary and fallback, and every current
+        # watcher parameter survives:
+        #   [watcher_python, "-c", <script>, str(pid), str(restart_after_s), *cmd_argv]
+        assert argv1 == argv2
+        assert argv1[1] == "-c"
+        assert argv1[3] == str(os.getpid())
+        assert float(argv1[4]) >= 5.0  # restart deadline preserved
+        assert argv1[-2:] == ["gateway", "restart"]
+
+        # Scrubbed env preserved and identical on both calls.
+        assert kw1["env"] is kw2["env"]
+        assert "_HERMES_GATEWAY" not in kw1["env"]
+
+        # Stable, non-flag spawn configuration preserved across both attempts.
+        assert kw1["stdout"] is subprocess.DEVNULL
+        assert kw1["stderr"] is subprocess.DEVNULL
+        assert kw2["stdout"] is subprocess.DEVNULL
+        assert kw2["stderr"] is subprocess.DEVNULL
+
+        # Primary spreads the full detach helper.  Assert every returned helper
+        # kwarg is present on the call — meaningful on Linux CI too, where the
+        # helper returns {"start_new_session": True} (no creationflags entry):
+        # dropping the spread entirely would fail here, not just on Windows.
+        # The fallback uses the explicit no-breakaway creationflags.
+        expected_primary = windows_detach_popen_kwargs()
+        for key, value in expected_primary.items():
+            assert kw1[key] == value
+        assert kw2["creationflags"] == windows_detach_flags_without_breakaway()
+        assert "start_new_session" not in kw2
+
+        if IS_WINDOWS:
+            _BREAKAWAY = 0x01000000
+            assert kw1["creationflags"] & _BREAKAWAY, (
+                "primary spawn must request CREATE_BREAKAWAY_FROM_JOB"
+            )
+            assert not (kw2["creationflags"] & _BREAKAWAY), (
+                "fallback spawn must drop CREATE_BREAKAWAY_FROM_JOB"
+            )
+
+    def test_outer_watcher_inline_respawn_stays_no_breakaway(self, monkeypatch):
+        """The embedded respawn script (argv[2]) must keep calling
+        ``windows_detach_flags_without_breakaway()`` — current main
+        intentionally respawns the gateway without the breakaway bit, and this
+        port must not reintroduce a breakaway-first inline shape."""
+        import gateway.run as gr
+
+        monkeypatch.setattr(gr.sys, "platform", "win32")
+        monkeypatch.setattr(gr, "_resolve_hermes_bin", lambda: ["hermes"])
+
+        captured = {}
+
+        def fake_popen(argv, **kwargs):
+            captured["argv"] = argv
+            return MagicMock()
+
+        monkeypatch.setattr("subprocess.Popen", fake_popen)
+        self._drive(gr)
+
+        watcher_script = captured["argv"][2]
+        assert "windows_detach_flags_without_breakaway()" in watcher_script
+        assert "CREATE_BREAKAWAY_FROM_JOB" not in watcher_script
+
+    def test_outer_watcher_happy_path_spawns_once(self, monkeypatch):
+        import gateway.run as gr
+
+        monkeypatch.setattr(gr.sys, "platform", "win32")
+        monkeypatch.setattr(gr, "_resolve_hermes_bin", lambda: ["hermes"])
+
+        calls = []
+        monkeypatch.setattr(
+            "subprocess.Popen",
+            lambda argv, **kwargs: calls.append((argv, kwargs)) or MagicMock(),
+        )
+        warn = MagicMock()
+        monkeypatch.setattr(gr.logger, "warning", warn)
+
+        self._drive(gr)
+
+        assert len(calls) == 1, "no retry when the primary spawn succeeds"
+        warn.assert_not_called()
+
+    def test_outer_watcher_dual_failure_warns_without_leaking_secrets(
+        self, monkeypatch
+    ):
+        import gateway.run as gr
+
+        monkeypatch.setattr(gr.sys, "platform", "win32")
+        monkeypatch.setattr(gr, "_resolve_hermes_bin", lambda: ["hermes"])
+
+        calls = []
+
+        def always_fail(argv, **kwargs):
+            calls.append((argv, kwargs))
+            raise OSError(5, "Access is denied")
+
+        monkeypatch.setattr("subprocess.Popen", always_fail)
+        warn = MagicMock()
+        monkeypatch.setattr(gr.logger, "warning", warn)
+
+        # Deterministic sentinel in the environment the watcher inherits
+        # (watcher_env = os.environ.copy()); the warning must never echo it.
+        secret = "maxwell-do-not-log-this-secret-42993"
+        monkeypatch.setenv("HERMES_TEST_SECRET", secret)
+
+        # Dual failure must NOT propagate — the user's CLI still exits cleanly.
+        self._drive(gr)
+
+        assert len(calls) == 2, "both primary and fallback attempted"
+        warn.assert_called_once()
+
+        # Secret-safe logging: only (interpreter basename, error field, error
+        # code) are logged — never the exception object (str(exc) can carry a
+        # path), the argv (watcher source + interpreter path), or env contents.
+        argv_used, kwargs_used = calls[0]
+        fmt, *log_args = warn.call_args.args
+        assert len(log_args) == 3, "warning should log only (basename, field, code)"
+        basename_arg, error_field, error_code = log_args
+        assert basename_arg == os.path.basename(argv_used[0])
+        assert error_field in ("winerror", "errno")
+        assert isinstance(error_code, int)
+        for arg in log_args:
+            assert not isinstance(arg, (OSError, list, dict))
+
+        # The watcher's env carried the sentinel; the rendered warning must not.
+        assert secret in (kwargs_used.get("env") or {}).get("HERMES_TEST_SECRET", "")
+        rendered = fmt % tuple(log_args)
+        assert secret not in rendered
+        assert argv_used[2] not in rendered  # watcher script body
+        assert "argv" not in fmt.lower()
+        assert "env=" not in fmt.lower()
diff --git a/tests/tools/test_x_search_tool.py b/tests/tools/test_x_search_tool.py
index 3a5186f9142..385dd2cf262 100644
--- a/tests/tools/test_x_search_tool.py
+++ b/tests/tools/test_x_search_tool.py
@@ -98,6 +98,28 @@ def test_x_search_rejects_conflicting_handle_filters(monkeypatch):
     assert result["error"] == "allowed_x_handles and excluded_x_handles cannot be used together"
 
 
+def test_x_search_schema_is_read_only_without_cross_tool_names():
+    """Static schema must state read-only scope without naming other surfaces.
+
+    AGENTS.md forbids hardcoding cross-tool/skill names in tool schemas because
+    those surfaces may be unavailable. Keep out-of-scope guidance generic here;
+    xurl routing lives in the skill and feature docs.
+    """
+    from tools.x_search_tool import X_SEARCH_SCHEMA
+
+    description = X_SEARCH_SCHEMA["description"]
+    lowered = description.lower()
+
+    assert "read-only" in lowered
+    assert "public x" in lowered
+    for action in ("post", "reply", "like", "dm", "upload media", "delete"):
+        assert action in lowered
+    assert "authenticated" in lowered
+    # No static cross-surface names in the model-facing schema.
+    assert "xurl" not in lowered
+    assert "web_search" not in lowered
+
+
 def test_x_search_extracts_inline_url_citations(monkeypatch):
     from tools.x_search_tool import x_search_tool
 
diff --git a/tests/tui_gateway/test_auto_continue.py b/tests/tui_gateway/test_auto_continue.py
new file mode 100644
index 00000000000..28a70e3e420
--- /dev/null
+++ b/tests/tui_gateway/test_auto_continue.py
@@ -0,0 +1,423 @@
+"""Crash-interrupted turns auto-continue on the next session.resume.
+
+A turn's durable marker (tui_gateway/turn_marker.py) is written when the turn
+starts running and cleared when it concludes — success, handled error, or
+interrupt. Only a process death leaves it behind, so a marker found at resume
+time is positive proof the turn never finished. Contract pinned here:
+
+* the marker module round-trips, prunes stale entries, and tolerates a
+  corrupt sidecar;
+* ``_run_prompt_submit`` writes the marker before the turn and clears it in
+  the ``finally`` on both the success and exception paths (a handled failure
+  is a concluded turn — its terminal frame + retained snapshot own recovery);
+* ``_maybe_schedule_auto_continue`` re-submits a fresh interrupted prompt as
+  a continuation note (display_kind ``auto_continue``), refuses stale /
+  disabled / crash-looping / already-running cases, and bounds attempts via
+  the marker's attempt counter.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import types
+
+import pytest
+
+from tui_gateway import server
+from tui_gateway.turn_marker import (
+    clear_turn_marker,
+    read_turn_marker,
+    record_turn_start,
+)
+
+
+class _InlineThread:
+    """Run threads synchronously so tests observe final state."""
+
+    def __init__(self, target=None, daemon=None, args=(), kwargs=None):
+        self._target = target
+        self._args = args
+        self._kwargs = kwargs or {}
+
+    def start(self):
+        if self._target is not None:
+            self._target(*self._args, **self._kwargs)
+
+    def is_alive(self):
+        return False
+
+    def join(self, timeout=None):
+        return None
+
+
+def _session(agent=None, **extra):
+    return {
+        "agent": agent if agent is not None else types.SimpleNamespace(),
+        "session_key": "session-key",
+        "history": [],
+        "history_lock": threading.Lock(),
+        "history_version": 0,
+        "running": False,
+        "attached_images": [],
+        "image_counter": 0,
+        "cols": 80,
+        "slash_worker": None,
+        "show_reasoning": False,
+        "tool_progress_mode": "all",
+        "inflight_turn": None,
+        **extra,
+    }
+
+
+@pytest.fixture()
+def emits(monkeypatch):
+    captured: list = []
+    monkeypatch.setattr(
+        server,
+        "_emit",
+        lambda event, sid, payload=None: captured.append((event, sid, payload)),
+    )
+    return captured
+
+
+@pytest.fixture()
+def marker_home(monkeypatch, tmp_path):
+    """Point the server's marker storage at a temp HERMES_HOME."""
+    monkeypatch.setattr(server, "_hermes_home", tmp_path)
+    return tmp_path
+
+
+@pytest.fixture()
+def turn_env(monkeypatch, tmp_path, marker_home):
+    """Neutralize the turn pipeline's environment-heavy side paths."""
+    monkeypatch.setattr(server.threading, "Thread", _InlineThread)
+    monkeypatch.setattr(server, "_wire_callbacks", lambda sid: None)
+    monkeypatch.setattr(server, "_sync_agent_model_with_config", lambda sid, session: None)
+    monkeypatch.setattr(server, "_session_cwd", lambda session: str(tmp_path))
+    monkeypatch.setattr(server, "_register_session_cwd", lambda session: None)
+    monkeypatch.setattr(server, "_tts_stream_begin", lambda: None)
+    monkeypatch.setattr(server, "_sync_session_key_after_compress", lambda *a, **k: None)
+    monkeypatch.setattr(server, "_get_usage", lambda agent: {})
+
+
+# ── Marker module ──────────────────────────────────────────────────────
+
+
+def test_marker_roundtrip(tmp_path):
+    record_turn_start(tmp_path, "abc", "fix the bug", attempts=1)
+
+    marker = read_turn_marker(tmp_path, "abc")
+    assert marker is not None
+    assert marker["prompt"] == "fix the bug"
+    assert marker["attempts"] == 1
+    assert marker["started_at"] == pytest.approx(time.time(), abs=5)
+
+    clear_turn_marker(tmp_path, "abc")
+    assert read_turn_marker(tmp_path, "abc") is None
+
+
+def test_marker_clear_is_noop_without_entry(tmp_path):
+    clear_turn_marker(tmp_path, "missing")
+    assert read_turn_marker(tmp_path, "missing") is None
+
+
+def test_marker_write_prunes_expired_entries(tmp_path):
+    import json
+
+    path = tmp_path / "desktop" / "interrupted_turns.json"
+    path.parent.mkdir(parents=True)
+    path.write_text(
+        json.dumps({"old": {"attempts": 0, "prompt": "ancient prompt", "started_at": 1.0}})
+    )
+
+    record_turn_start(tmp_path, "new", "current prompt")
+
+    assert read_turn_marker(tmp_path, "old") is None
+    assert read_turn_marker(tmp_path, "new") is not None
+
+
+def test_marker_survives_corrupt_sidecar(tmp_path):
+    path = tmp_path / "desktop" / "interrupted_turns.json"
+    path.parent.mkdir(parents=True)
+    path.write_text("{not json")
+
+    assert read_turn_marker(tmp_path, "abc") is None
+    record_turn_start(tmp_path, "abc", "prompt")
+    assert read_turn_marker(tmp_path, "abc")["prompt"] == "prompt"
+
+
+# ── Turn lifecycle owns the marker ─────────────────────────────────────
+
+
+def test_concluded_turn_clears_marker(emits, turn_env, marker_home):
+    seen_mid_turn: list = []
+
+    def _run(message, **kwargs):
+        seen_mid_turn.append(read_turn_marker(marker_home, "session-key"))
+        return {"final_response": "done"}
+
+    agent = types.SimpleNamespace(
+        session_id="session-key", run_conversation=_run, clear_interrupt=lambda: None
+    )
+    session = _session(agent=agent, running=True)
+
+    server._run_prompt_submit("rid", "sid", session, "do the thing")
+
+    # Written before the turn ran (this is what survives a process death) …
+    assert seen_mid_turn and seen_mid_turn[0] is not None
+    assert seen_mid_turn[0]["prompt"] == "do the thing"
+    assert seen_mid_turn[0]["attempts"] == 0
+    # … and cleared once the turn concluded.
+    assert read_turn_marker(marker_home, "session-key") is None
+
+
+@pytest.mark.parametrize(
+    "result", [{"final_response": "done"}, {"error": "provider said no"}]
+)
+def test_marker_is_gone_by_the_terminal_frame(monkeypatch, turn_env, marker_home, result):
+    """The client treats message.complete as "turn over" and may quit right
+    then; post-turn work (titles, memory, goal hooks) keeps the thread alive
+    for a second or more afterwards. If the marker outlived the frame, that
+    quit looked like a crash and re-ran a finished turn on the next launch."""
+    at_frame: list = []
+
+    def _emit(event, sid, payload=None):
+        if event == "message.complete":
+            at_frame.append(read_turn_marker(marker_home, "session-key"))
+
+    monkeypatch.setattr(server, "_emit", _emit)
+    agent = types.SimpleNamespace(
+        session_id="session-key",
+        run_conversation=lambda message, **kwargs: result,
+        clear_interrupt=lambda: None,
+    )
+
+    server._run_prompt_submit("rid", "sid", _session(agent=agent, running=True), "do the thing")
+
+    assert at_frame == [None]
+
+
+def test_handled_failure_still_clears_marker(emits, turn_env, marker_home):
+    """An exception is a CONCLUDED turn (terminal frame + retained snapshot own
+    recovery) — only a process death may leave the marker behind."""
+
+    def _boom(message, **kwargs):
+        raise RuntimeError("provider exploded")
+
+    agent = types.SimpleNamespace(
+        session_id="session-key", run_conversation=_boom, clear_interrupt=lambda: None
+    )
+    session = _session(agent=agent, running=True)
+
+    server._run_prompt_submit("rid", "sid", session, "do the thing")
+
+    assert read_turn_marker(marker_home, "session-key") is None
+
+
+def test_continuation_turn_records_attempt_and_original_prompt(
+    emits, turn_env, marker_home
+):
+    """A continuation's marker must carry the attempt count (crash-loop
+    breaker) and the ORIGINAL prompt — recording its own recovery note would
+    nest note inside note on a second crash."""
+    seen: list = []
+
+    def _run(message, **kwargs):
+        seen.append(read_turn_marker(marker_home, "session-key"))
+        return {"final_response": "done"}
+
+    agent = types.SimpleNamespace(
+        session_id="session-key", run_conversation=_run, clear_interrupt=lambda: None
+    )
+    session = _session(
+        agent=agent,
+        running=True,
+        _auto_continue_attempt=2,
+        _auto_continue_prompt="the original prompt",
+    )
+
+    server._run_prompt_submit("rid", "sid", session, server._auto_continue_note("the original prompt"))
+
+    assert [(m["attempts"], m["prompt"]) for m in seen] == [(2, "the original prompt")]
+    # Consumed, so the NEXT user turn starts from a clean slate.
+    assert "_auto_continue_attempt" not in session
+    assert "_auto_continue_prompt" not in session
+
+
+# ── Scheduling decision ────────────────────────────────────────────────
+
+
+@pytest.fixture()
+def schedule_env(monkeypatch, marker_home):
+    monkeypatch.setattr(server.threading, "Thread", _InlineThread)
+    monkeypatch.setattr(server, "_start_agent_build", lambda sid, session: None)
+    monkeypatch.setattr(server, "_wait_agent", lambda session, rid, timeout=30.0: None)
+    monkeypatch.setattr(server, "_load_cfg", lambda: {})
+    submitted: list = []
+    monkeypatch.setattr(
+        server,
+        "_run_prompt_submit",
+        lambda rid, sid, session, text, **kw: submitted.append((text, kw)),
+    )
+    return submitted
+
+
+def test_fresh_marker_schedules_continuation(emits, schedule_env, marker_home):
+    record_turn_start(marker_home, "session-key", "fix the flaky test")
+    session = _session()
+
+    result = server._maybe_schedule_auto_continue("sid", session, "session-key")
+
+    assert result is not None
+    assert result["attempt"] == 1
+    assert session["running"] is True
+    assert session["_auto_continue_attempt"] == 1
+    (text, kwargs), = schedule_env
+    assert text.startswith("[System note: Your previous turn was interrupted")
+    assert "fix the flaky test" in text
+    assert kwargs["display_kind"] == "auto_continue"
+    assert ("message.start", "sid", None) in [(e, s, p) for e, s, p in emits]
+
+
+def test_stale_marker_is_cleared_not_continued(schedule_env, marker_home, monkeypatch):
+    record_turn_start(marker_home, "session-key", "old prompt")
+    monkeypatch.setattr(
+        server, "time", types.SimpleNamespace(time=lambda: time.time() + 3600)
+    )
+
+    result = server._maybe_schedule_auto_continue("sid", _session(), "session-key")
+
+    assert result is None
+    assert not schedule_env
+    assert read_turn_marker(marker_home, "session-key") is None
+
+
+def test_config_widens_freshness_window(emits, schedule_env, marker_home, monkeypatch):
+    record_turn_start(marker_home, "session-key", "old prompt")
+    monkeypatch.setattr(
+        server,
+        "_load_cfg",
+        lambda: {"desktop": {"auto_continue": {"freshness_minutes": 120}}},
+    )
+    monkeypatch.setattr(
+        server, "time", types.SimpleNamespace(time=lambda: time.time() + 3600)
+    )
+
+    result = server._maybe_schedule_auto_continue("sid", _session(), "session-key")
+
+    assert result is not None
+    assert len(schedule_env) == 1
+
+
+def test_exhausted_attempts_break_the_loop(schedule_env, marker_home):
+    record_turn_start(marker_home, "session-key", "crashy prompt", attempts=2)
+
+    result = server._maybe_schedule_auto_continue("sid", _session(), "session-key")
+
+    assert result is None
+    assert not schedule_env
+    assert read_turn_marker(marker_home, "session-key") is None
+
+
+def test_disabled_by_config(schedule_env, marker_home, monkeypatch):
+    record_turn_start(marker_home, "session-key", "prompt")
+    monkeypatch.setattr(
+        server,
+        "_load_cfg",
+        lambda: {"desktop": {"auto_continue": {"enabled": False}}},
+    )
+
+    result = server._maybe_schedule_auto_continue("sid", _session(), "session-key")
+
+    assert result is None
+    assert not schedule_env
+
+
+def test_no_marker_means_no_continuation(schedule_env, marker_home):
+    assert server._maybe_schedule_auto_continue("sid", _session(), "session-key") is None
+    assert not schedule_env
+
+
+def test_running_session_wins_over_continuation(emits, schedule_env, marker_home):
+    """A real user prompt that raced the kickoff keeps its turn; the marker is
+    left for that turn's own conclusion to clear."""
+    record_turn_start(marker_home, "session-key", "prompt")
+    session = _session(running=True)
+
+    result = server._maybe_schedule_auto_continue("sid", session, "session-key")
+
+    # Scheduled (the descriptor is returned), but the kickoff bailed.
+    assert result is not None
+    assert not schedule_env
+    assert session["_auto_continue_scheduled"] is False
+    assert read_turn_marker(marker_home, "session-key") is not None
+    # Nothing left behind for the racing user turn to inherit.
+    assert "_auto_continue_attempt" not in session
+    assert "_auto_continue_prompt" not in session
+
+
+def test_double_schedule_is_guarded(emits, schedule_env, marker_home):
+    record_turn_start(marker_home, "session-key", "prompt")
+    session = _session()
+
+    first = server._maybe_schedule_auto_continue("sid", session, "session-key")
+    second = server._maybe_schedule_auto_continue("sid", session, "session-key")
+
+    assert first is not None
+    assert second is None
+    assert len(schedule_env) == 1
+
+
+def test_failed_agent_build_leaves_marker_for_retry(
+    emits, schedule_env, marker_home, monkeypatch
+):
+    record_turn_start(marker_home, "session-key", "prompt")
+    monkeypatch.setattr(
+        server,
+        "_wait_agent",
+        lambda session, rid, timeout=30.0: {"error": {"message": "boom"}},
+    )
+    session = _session()
+
+    result = server._maybe_schedule_auto_continue("sid", session, "session-key")
+
+    assert result is not None
+    assert not schedule_env
+    assert session["_auto_continue_scheduled"] is False
+    assert read_turn_marker(marker_home, "session-key") is not None
+
+
+# ── End to end: continuation runs a real turn and clears the marker ────
+
+
+def test_continuation_runs_through_turn_pipeline(emits, turn_env, marker_home, monkeypatch):
+    record_turn_start(marker_home, "session-key", "finish the migration")
+    monkeypatch.setattr(server, "_start_agent_build", lambda sid, session: None)
+    monkeypatch.setattr(server, "_wait_agent", lambda session, rid, timeout=30.0: None)
+    monkeypatch.setattr(server, "_load_cfg", lambda: {})
+
+    prompts: list = []
+
+    def _run(message, **kwargs):
+        prompts.append(message)
+        return {"final_response": "continued and finished"}
+
+    agent = types.SimpleNamespace(
+        session_id="session-key", run_conversation=_run, clear_interrupt=lambda: None
+    )
+    session = _session(agent=agent)
+
+    result = server._maybe_schedule_auto_continue("sid", session, "session-key")
+
+    assert result == {
+        "attempt": 1,
+        "interrupted_at": pytest.approx(time.time(), abs=5),
+    }
+    assert len(prompts) == 1
+    assert "finish the migration" in prompts[0]
+    # The concluded continuation cleared both the marker and the turn state.
+    assert read_turn_marker(marker_home, "session-key") is None
+    assert session["running"] is False
+    completes = [p for e, _s, p in emits if e == "message.complete"]
+    assert completes and completes[0]["status"] == "complete"
diff --git a/tests/tui_gateway/test_custom_provider_session_persistence.py b/tests/tui_gateway/test_custom_provider_session_persistence.py
index f78a5d8c2fa..0715aa9ee82 100644
--- a/tests/tui_gateway/test_custom_provider_session_persistence.py
+++ b/tests/tui_gateway/test_custom_provider_session_persistence.py
@@ -352,3 +352,158 @@ class TestBareCustomNoBaseUrlHealsFromConfig:
         assert persisted.get("provider") == "custom:mimo-v2.5-pro"
 
 
+# --- Regression: bare "custom" + no base_url + DIFFERENT default provider ----
+#
+# The config-provider fallback above only heals when ``config.model.provider``
+# still points at the custom entry. A user whose global default is a built-in
+# provider (e.g. Nous) but who switched THIS session to a self-hosted model
+# gets no heal: the bare provider is dropped, resume falls back to the default
+# provider, and the default provider's endpoint 404s with "Model '<x>' not
+# found" (the b200/hermes-ultra-sft report). The stored MODEL NAME is the one
+# session-scoped fact that still identifies the entry — these tests lock the
+# model-name recovery tier.
+
+ULTRA_URL = "http://b200-cluster:30090/v1"
+
+ULTRA_CONFIG = {
+    # Global default deliberately points at a BUILT-IN provider — the config
+    # fallback must not fire; only the model lookup can recover the entry.
+    "model": {"default": "some-nous-model", "provider": "nous"},
+    "providers": {
+        "hermes-ultra": {
+            "api": ULTRA_URL,
+            "api_key": "sk-ultra",
+            "models": ["hermes-ultra-sft"],
+        }
+    },
+}
+
+ULTRA_LEGACY_CONFIG = {
+    "model": {"default": "some-nous-model", "provider": "nous"},
+    "custom_providers": [
+        {
+            "name": "hermes-ultra",
+            "base_url": ULTRA_URL,
+            "api_key": "sk-ultra",
+            "model": "hermes-ultra-sft",
+        }
+    ],
+}
+
+
+class TestModelNameRecoversEntryIdentity:
+    def test_identity_by_model_from_providers_dict_models_list(self, monkeypatch):
+        monkeypatch.setattr(rp, "load_config", lambda: ULTRA_CONFIG)
+
+        assert (
+            rp.find_custom_provider_identity_by_model("hermes-ultra-sft")
+            == "custom:hermes-ultra"
+        )
+
+    def test_identity_by_model_from_legacy_default_model(self, monkeypatch):
+        monkeypatch.setattr(rp, "load_config", lambda: ULTRA_LEGACY_CONFIG)
+
+        assert (
+            rp.find_custom_provider_identity_by_model("hermes-ultra-sft")
+            == "custom:hermes-ultra"
+        )
+
+    def test_identity_by_model_unknown_model_returns_none(self, monkeypatch):
+        monkeypatch.setattr(rp, "load_config", lambda: ULTRA_CONFIG)
+
+        assert rp.find_custom_provider_identity_by_model("gpt-5.5") is None
+        assert rp.find_custom_provider_identity_by_model("") is None
+
+    def test_canonical_identity_prefers_base_url_over_model(self, monkeypatch):
+        """URL ownership beats model-name matching when both are present."""
+        config = {
+            "model": {"default": "x", "provider": "nous"},
+            "providers": {
+                "by-url": {"api": ULTRA_URL, "api_key": "k1"},
+                "by-model": {
+                    "api": "http://other:9000/v1",
+                    "api_key": "k2",
+                    "models": ["hermes-ultra-sft"],
+                },
+            },
+        }
+        monkeypatch.setattr(rp, "load_config", lambda: config)
+
+        assert (
+            rp.canonical_custom_identity(
+                base_url=ULTRA_URL, model="hermes-ultra-sft"
+            )
+            == "custom:by-url"
+        )
+
+    def test_canonical_identity_recovers_from_model_when_config_points_elsewhere(
+        self, monkeypatch
+    ):
+        monkeypatch.setattr(rp, "load_config", lambda: ULTRA_CONFIG)
+        monkeypatch.setattr(rp, "_get_model_config", lambda: ULTRA_CONFIG["model"])
+
+        assert (
+            rp.canonical_custom_identity(base_url=None, model="hermes-ultra-sft")
+            == "custom:hermes-ultra"
+        )
+
+    def test_restore_heals_bare_custom_row_via_model_name(self, monkeypatch):
+        """The b200/hermes-ultra-sft report: row has bare custom, no base_url,
+        and the global default provider is a built-in. Before the model tier,
+        the bare provider was dropped and resume silently rerouted the
+        session's model to the default provider (Nous 404: "Model
+        'hermes-ultra-sft' not found... OpenRouter catalog")."""
+        monkeypatch.setattr(rp, "load_config", lambda: ULTRA_CONFIG)
+        monkeypatch.setattr(rp, "_get_model_config", lambda: ULTRA_CONFIG["model"])
+
+        from tui_gateway.server import _stored_session_runtime_overrides
+
+        row = {
+            "model": "hermes-ultra-sft",
+            "model_config": json.dumps(
+                {"model": "hermes-ultra-sft", "provider": "custom"}
+            ),
+            "billing_provider": "custom",
+        }
+        overrides = _stored_session_runtime_overrides(row)
+
+        assert overrides["provider_override"] == "custom:hermes-ultra"
+        assert overrides["model_override"]["provider"] == "custom:hermes-ultra"
+
+    def test_persist_heals_bare_custom_via_model_when_no_base_url(self, monkeypatch):
+        monkeypatch.setattr(rp, "load_config", lambda: ULTRA_CONFIG)
+        monkeypatch.setattr(rp, "_get_model_config", lambda: ULTRA_CONFIG["model"])
+
+        from tui_gateway.server import _runtime_model_config
+
+        agent = types.SimpleNamespace(
+            model="hermes-ultra-sft",
+            provider="custom",
+            base_url="",
+            api_mode="chat_completions",
+            reasoning_config=None,
+            service_tier=None,
+        )
+        config = _runtime_model_config(agent)
+
+        assert config["provider"] == "custom:hermes-ultra"
+
+    def test_make_agent_heals_via_model_end_to_end(self, monkeypatch):
+        """resume → _make_agent with bare custom + no base_url + built-in
+        global default must rebuild against the entry's endpoint + key, not
+        the default provider."""
+        override = {
+            "model": "hermes-ultra-sft",
+            "provider": "custom",
+            "base_url": None,
+            "api_mode": "chat_completions",
+        }
+
+        kwargs = _make_agent_with_override(
+            override, monkeypatch, ULTRA_CONFIG, model_cfg=ULTRA_CONFIG["model"]
+        )
+
+        assert kwargs["base_url"] == ULTRA_URL
+        assert kwargs["api_key"] == "sk-ultra"
+
+
diff --git a/tests/tui_gateway/test_failed_turn_retention.py b/tests/tui_gateway/test_failed_turn_retention.py
new file mode 100644
index 00000000000..064a1fdf730
--- /dev/null
+++ b/tests/tui_gateway/test_failed_turn_retention.py
@@ -0,0 +1,291 @@
+"""Failed turns must retain a replayable ``inflight`` snapshot.
+
+A turn that ended in error used to clear ``inflight_turn`` and emit its
+terminal frame in the same breath. If the client was disconnected during that
+window, the frame went to the detached drop-transport and the in-memory state
+was already gone — the desktop reconnected to a session with no trace of the
+failure (stuck spinner or a silently missing turn).
+
+Contract pinned here:
+
+* ``_fail_inflight_turn`` keeps the user prompt, partial assistant text, and
+  error semantics; ``_inflight_snapshot`` exposes status/error/recoverable.
+* The returned-error path (``run_conversation()`` returning ``error``) retains
+  the snapshot — not just the exception path.
+* The exception path closes the turn with a terminal ``message.complete``
+  (``status: "error"``, same shape as the returned-error path) instead of a
+  bare ``error`` event.
+* ``session.resume``'s live payload carries the retained snapshot.
+* A retained failure never leaks into the next turn's inflight state.
+"""
+
+from __future__ import annotations
+
+import threading
+import types
+
+import pytest
+
+from tui_gateway import server
+
+
+class _InlineThread:
+    """Run the turn synchronously so tests observe its final state."""
+
+    def __init__(self, target=None, daemon=None, args=(), kwargs=None):
+        self._target = target
+        self._args = args
+        self._kwargs = kwargs or {}
+
+    def start(self):
+        if self._target is not None:
+            self._target(*self._args, **self._kwargs)
+
+    def is_alive(self):
+        return False
+
+    def join(self, timeout=None):
+        return None
+
+
+def _session(agent=None, **extra):
+    return {
+        "agent": agent if agent is not None else types.SimpleNamespace(),
+        "session_key": "session-key",
+        "history": [],
+        "history_lock": threading.Lock(),
+        "history_version": 0,
+        "running": False,
+        "attached_images": [],
+        "image_counter": 0,
+        "cols": 80,
+        "slash_worker": None,
+        "show_reasoning": False,
+        "tool_progress_mode": "all",
+        "inflight_turn": None,
+        **extra,
+    }
+
+
+@pytest.fixture()
+def emits(monkeypatch):
+    captured: list = []
+    monkeypatch.setattr(
+        server,
+        "_emit",
+        lambda event, sid, payload=None: captured.append((event, sid, payload)),
+    )
+    return captured
+
+
+@pytest.fixture()
+def turn_env(monkeypatch, tmp_path):
+    """Neutralize the turn pipeline's environment-heavy side paths."""
+    monkeypatch.setattr(server.threading, "Thread", _InlineThread)
+    monkeypatch.setattr(server, "_wire_callbacks", lambda sid: None)
+    monkeypatch.setattr(server, "_sync_agent_model_with_config", lambda sid, session: None)
+    monkeypatch.setattr(server, "_session_cwd", lambda session: str(tmp_path))
+    monkeypatch.setattr(server, "_register_session_cwd", lambda session: None)
+    monkeypatch.setattr(server, "_tts_stream_begin", lambda: None)
+    monkeypatch.setattr(server, "_sync_session_key_after_compress", lambda *a, **k: None)
+    monkeypatch.setattr(server, "_get_usage", lambda agent: {})
+
+
+def _events(captured, name):
+    return [payload for event, _sid, payload in captured if event == name]
+
+
+# ── Unit: retention helpers ───────────────────────────────────────────
+
+
+def test_fail_inflight_turn_retains_partial_and_error():
+    session = _session()
+    server._start_inflight_turn(session, "do the thing")
+    server._append_inflight_delta(session, "partial answer")
+
+    server._fail_inflight_turn(session, RuntimeError("provider exploded"))
+
+    snapshot = server._inflight_snapshot(session)
+    assert snapshot is not None
+    assert snapshot["user"] == "do the thing"
+    assert snapshot["assistant"] == "partial answer"
+    assert snapshot["streaming"] is False
+    assert snapshot["error"] == "provider exploded"
+    assert snapshot["status"] == "error"
+    assert snapshot["recoverable"] is True
+
+
+def test_snapshot_returned_for_error_only_turn():
+    """An init failure has no user/assistant text yet — the error alone must
+    survive the emptiness check, or resume shows nothing."""
+    session = _session()
+    server._fail_inflight_turn(session, "agent initialization failed")
+
+    snapshot = server._inflight_snapshot(session)
+    assert snapshot is not None
+    assert snapshot["error"] == "agent initialization failed"
+
+
+def test_healthy_snapshot_carries_no_error_keys():
+    session = _session()
+    server._start_inflight_turn(session, "hi")
+    server._append_inflight_delta(session, "hello")
+
+    snapshot = server._inflight_snapshot(session)
+    assert snapshot == {"assistant": "hello", "streaming": True, "user": "hi"}
+
+
+# ── Returned-error path (run_conversation returns an error result) ────
+
+
+def test_returned_error_result_retains_snapshot_and_emits_terminal_frame(
+    emits, turn_env
+):
+    agent = types.SimpleNamespace(
+        session_id="session-key",
+        run_conversation=lambda *a, **k: {
+            "final_response": "",
+            "error": "provider 402: billing wall",
+            "failed": True,
+        },
+        clear_interrupt=lambda: None,
+    )
+    session = _session(agent=agent, running=True)
+    server._start_inflight_turn(session, "do the thing")
+
+    server._run_prompt_submit("rid", "sid", session, "do the thing")
+
+    completes = _events(emits, "message.complete")
+    assert len(completes) == 1
+    payload = completes[0]
+    assert payload["status"] == "error"
+    assert payload["error"] == "provider 402: billing wall"
+    assert payload["recoverable"] is True
+
+    # The retained snapshot survives the finally block for resume replay.
+    snapshot = server._inflight_snapshot(session)
+    assert snapshot is not None
+    assert snapshot["status"] == "error"
+    assert snapshot["error"] == "provider 402: billing wall"
+    assert snapshot["user"] == "do the thing"
+    assert session["running"] is False
+
+
+def test_completed_turn_still_clears_inflight(emits, turn_env):
+    agent = types.SimpleNamespace(
+        session_id="session-key",
+        run_conversation=lambda *a, **k: {"final_response": "all done"},
+        clear_interrupt=lambda: None,
+    )
+    session = _session(agent=agent, running=True)
+    server._start_inflight_turn(session, "do the thing")
+
+    server._run_prompt_submit("rid", "sid", session, "do the thing")
+
+    completes = _events(emits, "message.complete")
+    assert len(completes) == 1
+    assert completes[0]["status"] == "complete"
+    assert "error" not in completes[0]
+    assert server._inflight_snapshot(session) is None
+
+
+# ── Exception path ─────────────────────────────────────────────────────
+
+
+def test_exception_closes_turn_with_terminal_complete_and_partial(emits, turn_env):
+    def _boom(message, stream_callback=None, **kwargs):
+        if stream_callback is not None:
+            stream_callback("half an ans")
+        raise RuntimeError("connection reset mid-stream")
+
+    agent = types.SimpleNamespace(
+        session_id="session-key",
+        run_conversation=_boom,
+        clear_interrupt=lambda: None,
+    )
+    session = _session(agent=agent, running=True)
+    server._start_inflight_turn(session, "do the thing")
+
+    server._run_prompt_submit("rid", "sid", session, "do the thing")
+
+    # Terminal frame, not a bare error event.
+    assert not _events(emits, "error")
+    completes = _events(emits, "message.complete")
+    assert len(completes) == 1
+    payload = completes[0]
+    assert payload["status"] == "error"
+    assert payload["error"] == "connection reset mid-stream"
+    assert payload["recoverable"] is True
+    assert payload["partial"] is True
+    assert payload["text"] == "half an ans"
+
+    snapshot = server._inflight_snapshot(session)
+    assert snapshot is not None
+    assert snapshot["assistant"] == "half an ans"
+    assert snapshot["error"] == "connection reset mid-stream"
+    assert session["running"] is False
+
+
+# ── Resume replay (the reason retention exists) ───────────────────────
+
+
+def test_live_session_payload_exposes_retained_failure(emits, turn_env, monkeypatch):
+    agent = types.SimpleNamespace(
+        session_id="session-key",
+        run_conversation=lambda *a, **k: {
+            "final_response": "",
+            "error": "budget exhausted",
+            "failed": True,
+        },
+        clear_interrupt=lambda: None,
+    )
+    session = _session(agent=agent, running=True)
+    server._start_inflight_turn(session, "long job")
+    server._run_prompt_submit("rid", "sid", session, "long job")
+
+    # What session.resume's live fast path hands a reconnecting client.
+    monkeypatch.setattr(server, "_get_db", lambda: None)
+    payload = server._live_session_payload("sid", session)
+
+    assert payload["running"] is False
+    inflight = payload.get("inflight")
+    assert inflight is not None
+    assert inflight["status"] == "error"
+    assert inflight["error"] == "budget exhausted"
+    assert inflight["user"] == "long job"
+
+
+# ── Retained failure must not leak into the next turn ─────────────────
+
+
+def test_next_turn_replaces_retained_error_snapshot(emits, turn_env):
+    seen_inflight_user: list = []
+
+    def _run_ok(message, **kwargs):
+        # Capture what the inflight turn looks like while the new turn runs.
+        turn = server._inflight_snapshot(_run_ok.session)
+        seen_inflight_user.append(turn and turn["user"])
+        return {"final_response": "fresh answer"}
+
+    agent = types.SimpleNamespace(
+        session_id="session-key",
+        run_conversation=_run_ok,
+        clear_interrupt=lambda: None,
+    )
+    session = _session(agent=agent, running=True)
+    _run_ok.session = session
+
+    # Leftover retained failure from a previous turn.
+    server._start_inflight_turn(session, "old failed prompt")
+    server._fail_inflight_turn(session, "previous turn failed")
+
+    server._run_prompt_submit("rid", "sid", session, "new prompt")
+
+    # The new turn must have started a fresh inflight turn, not inherited the
+    # failed one (the retained dict used to satisfy the isinstance guard).
+    assert seen_inflight_user == ["new prompt"]
+    snapshot = server._inflight_snapshot(session)
+    assert snapshot is None
+    completes = _events(emits, "message.complete")
+    assert len(completes) == 1
+    assert completes[0]["status"] == "complete"
diff --git a/tests/tui_gateway/test_project_tree.py b/tests/tui_gateway/test_project_tree.py
index cd0424c5d5a..a7e73703f94 100644
--- a/tests/tui_gateway/test_project_tree.py
+++ b/tests/tui_gateway/test_project_tree.py
@@ -466,6 +466,106 @@ def test_broad_default_non_git_cwd_stays_unscoped():
     assert detached["id"] not in tree["scoped_session_ids"]
 
 
+def test_deleted_sibling_worktree_folds_into_parent_home_checkout():
+    # A deleted <repo>-<suffix> worktree leaves its session with an unresolvable
+    # cwd and no persisted root. It joins the parent's trunk lane — no dead-path
+    # lane, no phantom project.
+    resolve = _resolver({"/www/hermes-agent": ("/www/hermes-agent", "/www/hermes-agent")})
+    sessions = [
+        _session("/www/hermes-agent", branch="main"),
+        _session("/www/hermes-agent-session-links"),
+    ]
+
+    tree = pt.build_tree([], sessions, [], resolve, hydrate=True)
+    project = tree["projects"][0]
+
+    assert [p["id"] for p in tree["projects"]] == ["/www/hermes-agent"]
+    assert _lane_ids(project) == ["/www/hermes-agent::branch::main"]
+    main = project["repos"][0]["groups"][0]
+    assert main["isMain"] and main["path"] == "/www/hermes-agent"
+    assert len(main["sessions"]) == 2
+
+
+def test_deleted_sibling_worktree_subdir_folds_into_parent_home_checkout():
+    # Same as above, but the session's cwd is a SUBDIR of the deleted worktree
+    # (an agent that cd-ed into `<repo>-<suffix>/apps/desktop`). The leaf name
+    # ("desktop") shares nothing with the repo, so the sibling probe has to walk
+    # the ancestors — otherwise the dead path is minted as its own project.
+    resolve = _resolver({"/www/hermes-agent": ("/www/hermes-agent", "/www/hermes-agent")})
+    sessions = [
+        _session("/www/hermes-agent", branch="main"),
+        _session("/www/hermes-agent-guiperf/apps/desktop"),
+    ]
+
+    tree = pt.build_tree([], sessions, [], resolve, hydrate=True)
+
+    assert [p["id"] for p in tree["projects"]] == ["/www/hermes-agent"]
+    project = tree["projects"][0]
+    assert _lane_ids(project) == ["/www/hermes-agent::branch::main"]
+    assert len(project["repos"][0]["groups"][0]["sessions"]) == 2
+
+
+def test_deleted_unrelated_workspace_does_not_become_a_project():
+    # A deleted dir the sibling probe can't reach by name (`hermes-salvage-drafts`
+    # shares no prefix with `hermes-agent`; `/tmp/scratch` was never a worktree)
+    # must not be promoted to a phantom project — it can never be opened and can
+    # only be dismissed by hand. The session stays in flat Recents.
+    resolve = _resolver({"/www/hermes-agent": ("/www/hermes-agent", "/www/hermes-agent")})
+    sessions = [
+        _session("/www/hermes-agent", branch="main"),
+        _session("/www/hermes-salvage-drafts/apps/desktop"),
+        _session("/tmp/scratch"),
+    ]
+    on_disk = {"/www/hermes-agent"}
+
+    tree = pt.build_tree([], sessions, [], resolve, hydrate=True, exists=lambda p: p in on_disk)
+
+    assert [p["id"] for p in tree["projects"]] == ["/www/hermes-agent"]
+
+
+def test_existing_non_git_workspace_still_becomes_a_project():
+    # The existence guard keys on the DIRECTORY, not on git-ness: a plain folder
+    # that's still on disk is a legitimate workspace and must keep its project.
+    sessions = [_session("/www/notes")]
+
+    tree = pt.build_tree([], sessions, [], lambda _cwd: None, hydrate=True, exists=lambda _p: True)
+
+    assert [p["id"] for p in tree["projects"]] == ["/www/notes"]
+
+
+def test_stale_persisted_repo_root_does_not_become_a_project():
+    # A session carrying a git_repo_root whose repo has since been deleted must
+    # not resurrect it as a project on the strength of the persisted value alone.
+    sessions = [_session("/tmp/gone/sub", repo_root="/tmp/gone")]
+
+    tree = pt.build_tree([], sessions, [], lambda _cwd: None, hydrate=True, exists=lambda _p: False)
+
+    assert tree["projects"] == []
+
+
+def test_exists_defaults_to_keeping_everything():
+    # Omitting `exists` (remote backends, which can't stat) preserves the old
+    # behavior: guessing "gone" would wrongly hide a project on the other host.
+    sessions = [_session("/remote/workspace")]
+
+    tree = pt.build_tree([], sessions, [], lambda _cwd: None, hydrate=True)
+
+    assert [p["id"] for p in tree["projects"]] == ["/remote/workspace"]
+
+
+def test_sibling_probe_is_bounded():
+    # Each miss costs a git invocation, and this runs per session, so a deeply
+    # nested unresolvable cwd must not fan out into an unbounded probe storm.
+    probed = []
+
+    def resolve(cwd):
+        probed.append(cwd)
+        return None
+
+    assert pt._probe_sibling_worktree("/a-b-c/d-e-f/g-h-i/j-k-l", resolve) == ""
+    assert len(probed) <= pt._MAX_SIBLING_PROBES
+
+
 def test_colliding_repo_basenames_disambiguate_labels():
     resolve = _resolver(
         {
diff --git a/tests/tui_gateway/test_projects_rpc.py b/tests/tui_gateway/test_projects_rpc.py
index 731ae56edab..067a4758638 100644
--- a/tests/tui_gateway/test_projects_rpc.py
+++ b/tests/tui_gateway/test_projects_rpc.py
@@ -263,6 +263,62 @@ def test_record_repos_persists_and_shows_zero_session_repo(tmp_path):
     assert by_label["fresh-repo"]["sessions"] == 0
 
 
+def test_scan_time_is_not_treated_as_session_activity(tmp_path):
+    """A scanned repo with no sessions must not rank as recently active.
+
+    ``discovered_repos.last_seen`` records when the disk scan last saw the
+    directory. Folding it into ``last_active`` stamped every scanned checkout
+    with the scan time — i.e. "just now" — so repos the user has never opened
+    in Hermes outranked the ones they actually work in.
+    """
+    worked_in = tmp_path / "worked-in"
+    worked_in.mkdir()
+    subprocess.run(["git", "init"], cwd=worked_in, check=True, capture_output=True)
+    server._get_db().create_session("worked-in-session", "cli", cwd=str(worked_in))
+
+    never_opened = tmp_path / "never-opened"
+    never_opened.mkdir()
+
+    _call(
+        "projects.record_repos",
+        {"repos": [{"root": str(never_opened)}, {"root": str(worked_in)}]},
+    )
+
+    by_root = {r["root"]: r for r in _call("projects.discover_repos")["repos"]}
+    idle = by_root[str(never_opened)]
+    active = by_root[str(worked_in)]
+
+    assert idle["sessions"] == 0
+    # A repo with no sessions has no activity to report...
+    assert idle["last_active"] == 0
+    # ...so the repo the user actually worked in sorts ahead of it.
+    assert active["last_active"] > idle["last_active"]
+
+
+def test_terminal_session_persists_its_launch_cwd():
+    """A terminal session's cwd IS its workspace, so the row must record it.
+
+    The user cd'd into that directory before running hermes. Dropping it left
+    the row with no cwd and no git_repo_root, so the sidebar could never place
+    the session under its project.
+    """
+    for source in ("tui", "cli"):
+        assert server._persisted_session_cwd(
+            {"source": source, "cwd": "/somewhere/a-repo"}
+        ) == "/somewhere/a-repo"
+
+
+def test_desktop_launch_cwd_is_not_persisted_as_a_workspace():
+    # The desktop launches from wherever the bundle was opened, so an unpicked
+    # cwd is an artifact — those chats belong under "No workspace".
+    assert server._persisted_session_cwd({"source": "desktop", "cwd": "/opt/whatever"}) is None
+
+    # An explicit pick is always honored, desktop included.
+    assert server._persisted_session_cwd(
+        {"source": "desktop", "cwd": "/picked/repo", "explicit_cwd": True}
+    ) == "/picked/repo"
+
+
 def test_disabled_discovery_clears_cache_and_rejects_new_scan(monkeypatch, tmp_path):
     repo = tmp_path / "cached-repo"
     repo.mkdir()
diff --git a/tests/tui_gateway/test_session_cwd_follow.py b/tests/tui_gateway/test_session_cwd_follow.py
new file mode 100644
index 00000000000..e5fa5a7c2fb
--- /dev/null
+++ b/tests/tui_gateway/test_session_cwd_follow.py
@@ -0,0 +1,160 @@
+"""A session that settles into another git worktree re-anchors onto it.
+
+The desktop already follows a session that moves (``followActiveSessionCwd``
+refreshes the project tree and scopes into the new project), but it only ever
+sees a move when the backend reports one on ``session.info``. These tests
+exercise the backend half against real git worktrees on disk.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+import pytest
+
+import tools.terminal_tool as terminal_tool
+import tui_gateway.server as server
+
+
+def _git(cwd, *args):
+    subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True)
+
+
+@pytest.fixture
+def repo_with_worktree(tmp_path):
+    """A real repo on ``main`` plus a linked worktree on ``feature``."""
+    repo = tmp_path / "proj"
+    repo.mkdir()
+    _git(repo, "init", "-b", "main")
+    _git(repo, "config", "user.email", "t@example.com")
+    _git(repo, "config", "user.name", "t")
+    (repo / "README.md").write_text("hi\n")
+    _git(repo, "add", ".")
+    _git(repo, "commit", "-m", "init")
+
+    worktree = tmp_path / "proj-feature"
+    _git(repo, "worktree", "add", "-b", "feature", str(worktree))
+
+    from tui_gateway import git_probe
+
+    git_probe.invalidate()
+    yield repo, worktree
+    git_probe.invalidate()
+
+
+@pytest.fixture
+def session(repo_with_worktree):
+    repo, _ = repo_with_worktree
+    key = "sess-follow"
+    terminal_tool.clear_session_cwd(key)
+    yield {"session_key": key, "cwd": str(repo), "source": "desktop"}
+    terminal_tool.clear_session_cwd(key)
+
+
+@pytest.fixture(autouse=True)
+def _no_db(monkeypatch):
+    monkeypatch.setattr(server, "_get_db", lambda: None)
+    monkeypatch.setattr(server, "_persist_session_git_meta", lambda *_a: None)
+    monkeypatch.setattr(server, "_register_session_cwd", lambda _s: None)
+    monkeypatch.setattr(server, "_is_local_terminal_backend", lambda: True)
+
+
+def test_settling_in_a_worktree_reanchors_the_session(session, repo_with_worktree):
+    """The whole reported bug: work goes to the worktree, the session says main."""
+    _, worktree = repo_with_worktree
+    terminal_tool.record_session_cwd(session["session_key"], str(worktree))
+
+    assert server._reconcile_session_cwd_from_terminal(session) is True
+    assert session["cwd"] == str(worktree)
+    # The move is the session's workspace now, so it earns a persisted row.
+    assert session["explicit_cwd"] is True
+
+
+def test_a_subdirectory_of_the_same_checkout_is_not_a_move(session, repo_with_worktree):
+    repo, _ = repo_with_worktree
+    sub = repo / "src"
+    sub.mkdir()
+    terminal_tool.record_session_cwd(session["session_key"], str(sub))
+
+    assert server._reconcile_session_cwd_from_terminal(session) is False
+    assert session["cwd"] == str(repo)
+
+
+def test_browsing_outside_a_repo_is_not_a_move(session, repo_with_worktree, tmp_path):
+    """`cd /tmp` to read a log must not re-home the workspace."""
+    repo, _ = repo_with_worktree
+    scratch = tmp_path / "scratch"
+    scratch.mkdir()
+    terminal_tool.record_session_cwd(session["session_key"], str(scratch))
+
+    assert server._reconcile_session_cwd_from_terminal(session) is False
+    assert session["cwd"] == str(repo)
+
+
+def test_a_deleted_directory_is_not_a_move(session, repo_with_worktree, tmp_path):
+    repo, _ = repo_with_worktree
+    terminal_tool.record_session_cwd(session["session_key"], str(tmp_path / "gone"))
+
+    assert server._reconcile_session_cwd_from_terminal(session) is False
+    assert session["cwd"] == str(repo)
+
+
+def test_remote_backends_do_not_reanchor(session, repo_with_worktree, monkeypatch):
+    """A remote cwd names a path on the host, not one this gateway can probe."""
+    repo, worktree = repo_with_worktree
+    monkeypatch.setattr(server, "_is_local_terminal_backend", lambda: False)
+    terminal_tool.record_session_cwd(session["session_key"], str(worktree))
+
+    assert server._reconcile_session_cwd_from_terminal(session) is False
+    assert session["cwd"] == str(repo)
+
+
+def test_settled_session_info_reports_the_worktree_branch(
+    session, repo_with_worktree, monkeypatch
+):
+    """End of turn: the emitted session.info is what the desktop follows."""
+    _, worktree = repo_with_worktree
+    emitted: list[tuple[str, str, dict]] = []
+    monkeypatch.setattr(server, "_emit", lambda ev, sid, payload=None: emitted.append((ev, sid, payload or {})))
+    terminal_tool.record_session_cwd(session["session_key"], str(worktree))
+
+    server._emit_settled_session_info("sid-1", session, agent=None)
+
+    assert len(emitted) == 1
+    event, sid, payload = emitted[0]
+    assert (event, sid) == ("session.info", "sid-1")
+    assert payload["cwd"] == str(worktree)
+    assert payload["branch"] == "feature"
+
+
+def test_settled_session_info_still_emits_when_nothing_moved(
+    session, repo_with_worktree, monkeypatch
+):
+    repo, _ = repo_with_worktree
+    emitted: list[dict] = []
+    monkeypatch.setattr(server, "_emit", lambda ev, sid, payload=None: emitted.append(payload or {}))
+
+    server._emit_settled_session_info("sid-1", session, agent=None)
+
+    assert len(emitted) == 1
+    assert emitted[0]["cwd"] == str(repo)
+    assert emitted[0]["branch"] == "main"
+
+
+def test_reconcile_ignores_a_foreign_sessions_record(session, repo_with_worktree):
+    """cwd records are per session key — another chat's move must not leak in."""
+    repo, worktree = repo_with_worktree
+    terminal_tool.record_session_cwd("someone-else", str(worktree))
+
+    assert server._reconcile_session_cwd_from_terminal(session) is False
+    assert session["cwd"] == str(repo)
+    terminal_tool.clear_session_cwd("someone-else")
+
+
+def test_os_normalized_paths_are_not_a_move(session, repo_with_worktree):
+    """A trailing-slash / unnormalized record is the same dir, not a relocation."""
+    repo, _ = repo_with_worktree
+    terminal_tool.record_session_cwd(session["session_key"], str(repo) + os.sep)
+
+    assert server._reconcile_session_cwd_from_terminal(session) is False
diff --git a/tests/tui_gateway/test_session_id_injection.py b/tests/tui_gateway/test_session_id_injection.py
new file mode 100644
index 00000000000..069b3a5a5d1
--- /dev/null
+++ b/tests/tui_gateway/test_session_id_injection.py
@@ -0,0 +1,80 @@
+"""Contract test: tui_gateway._set_session_context must inject the live
+session id into HERMES_SESSION_ID so terminal/execute_code subprocesses can
+read the current session's id.
+
+Regression for the bug where _set_session_context called set_session_vars
+WITHOUT session_id, leaving the contextvar as "" (explicitly empty). Because
+the session-context bridge treats an explicit "" as authoritative and does NOT
+fall back to os.environ, every terminal command in a dashboard/TUI/web session
+saw an empty HERMES_SESSION_ID even though agent_init had set it via
+set_current_session_id().
+"""
+import pytest
+
+from gateway.session_context import (
+    get_session_env,
+    _VAR_MAP,
+    _UNSET,
+)
+import tui_gateway.server as server
+
+
+@pytest.fixture(autouse=True)
+def _reset_contextvars():
+    """Reset all session contextvars to _UNSET between tests.
+
+    In production each asyncio.Task/worker thread gets a fresh context copy
+    where the defaults are _UNSET. In tests functions share one thread
+    context, so a value set by test A would leak into test B without this.
+    """
+    yield
+    for var in _VAR_MAP.values():
+        var.set(_UNSET)
+
+
+class _FakeAgent:
+    def __init__(self, session_id):
+        self.session_id = session_id
+
+
+def _install_session(monkeypatch, *, session_key, agent_session_id, source="cli"):
+    """Register a fake session in server._sessions for the duration of a test."""
+    sess = {
+        "session_key": session_key,
+        "source": source,
+        "agent": _FakeAgent(agent_session_id) if agent_session_id is not None else None,
+        "cwd": "/home/user",
+    }
+    monkeypatch.setattr(server, "_sessions", {session_key: sess}, raising=False)
+    return sess
+
+
+def test_set_session_context_injects_agent_session_id(monkeypatch):
+    """HERMES_SESSION_ID must equal the live agent.session_id after binding."""
+    _install_session(
+        monkeypatch, session_key="skey-abc", agent_session_id="20260722_deadbeef"
+    )
+
+    server._set_session_context("skey-abc", ui_session_id="ui-123")
+
+    assert get_session_env("HERMES_SESSION_ID") == "20260722_deadbeef"
+
+
+def test_set_session_context_falls_back_to_session_key(monkeypatch):
+    """When the agent has no session_id yet, fall back to the session_key
+    (never leave HERMES_SESSION_ID empty for an identified session)."""
+    _install_session(monkeypatch, session_key="skey-xyz", agent_session_id=None)
+
+    server._set_session_context("skey-xyz")
+
+    assert get_session_env("HERMES_SESSION_ID") == "skey-xyz"
+
+
+def test_set_session_context_unknown_key_uses_key(monkeypatch):
+    """An ephemeral/unknown session_key (not in _sessions) still binds the key
+    itself rather than leaving the id empty."""
+    monkeypatch.setattr(server, "_sessions", {}, raising=False)
+
+    server._set_session_context("ephemeral-key")
+
+    assert get_session_env("HERMES_SESSION_ID") == "ephemeral-key"
diff --git a/tests/tui_gateway/test_subprocess_encoding.py b/tests/tui_gateway/test_subprocess_encoding.py
new file mode 100644
index 00000000000..91cabb187d6
--- /dev/null
+++ b/tests/tui_gateway/test_subprocess_encoding.py
@@ -0,0 +1,132 @@
+"""Regression tests for UTF-8 encoding hardening in tui_gateway/server.py (#53137).
+
+On Windows with a non-UTF-8 system locale (e.g. GBK on Chinese Windows),
+text-mode subprocess reads defaulted to the locale encoding. When a child
+process emitted bytes invalid in that locale, an unhandled UnicodeDecodeError
+crashed the reader thread / gateway thread.
+
+#53137 added encoding="utf-8", errors="replace" to every text-mode subprocess
+call in tui_gateway/server.py. These tests assert that the kwargs survive so
+the crash class cannot silently regress.
+
+# Test pattern adapted from @devorun's PR #52700 (salvage convention).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import tui_gateway.server as server
+
+
+# ── helpers ──────────────────────────────────────────────────────────────
+
+def _make_completed_process() -> MagicMock:
+    """A CompletedProcess-like mock with str stdout/stderr (text=True contract)."""
+    cp = MagicMock()
+    cp.stdout = ""
+    cp.stderr = ""
+    cp.returncode = 0
+    return cp
+
+
+# ── _SlashWorker.Popen path ──────────────────────────────────────────────
+
+def test_slash_worker_popen_uses_utf8_replace():
+    """The slash-worker subprocess.Popen must pass encoding="utf-8" and
+    errors="replace" so invalid bytes in child stdout/stderr don't raise
+    UnicodeDecodeError inside the drain threads (#53137).
+    """
+    with patch.dict("sys.modules", {
+        "hermes_constants": MagicMock(
+            get_hermes_home=MagicMock(return_value="/tmp/hermes_test")
+        ),
+    }):
+        with patch("subprocess.Popen") as mock_popen:
+            mock_popen.return_value.stdout = MagicMock()
+            mock_popen.return_value.stderr = MagicMock()
+
+            from tui_gateway.server import _SlashWorker
+
+            _SlashWorker(
+                session_key="test_key",
+                model="test-model",
+            )
+
+            assert mock_popen.called, "Popen was not invoked"
+            kwargs = mock_popen.call_args[1]
+            assert kwargs.get("encoding") == "utf-8", (
+                f"slash-worker Popen must set encoding='utf-8' (got {kwargs.get('encoding')!r})"
+            )
+            assert kwargs.get("errors") == "replace", (
+                f"slash-worker Popen must set errors='replace' (got {kwargs.get('errors')!r})"
+            )
+
+
+# ── cli.exec handler ─────────────────────────────────────────────────────
+
+def test_cli_exec_uses_utf8_replace():
+    """The cli.exec RPC handler runs `python -m hermes_cli.main` via
+    subprocess.run; it must pass encoding="utf-8" and errors="replace"
+    (#53137)."""
+    handler = server._methods["cli.exec"]
+    with patch("subprocess.run", return_value=_make_completed_process()) as mock_run:
+        # Non-interactive argv that passes _cli_exec_blocked.
+        resp = handler(1, {"argv": ["--version"]})
+        assert mock_run.called, "subprocess.run was not invoked"
+        kwargs = mock_run.call_args[1]
+        assert kwargs.get("encoding") == "utf-8", (
+            f"cli.exec subprocess.run must set encoding='utf-8' (got {kwargs.get('encoding')!r})"
+        )
+        assert kwargs.get("errors") == "replace", (
+            f"cli.exec subprocess.run must set errors='replace' (got {kwargs.get('errors')!r})"
+        )
+
+
+# ── shell.exec handler ───────────────────────────────────────────────────
+
+def test_shell_exec_uses_utf8_replace():
+    """The shell.exec RPC handler runs an arbitrary shell command via
+    subprocess.run; it must pass encoding="utf-8" and errors="replace"
+    (#53137)."""
+    handler = server._methods["shell.exec"]
+    with patch("subprocess.run", return_value=_make_completed_process()) as mock_run:
+        # A harmless, non-dangerous command that passes the approval gate.
+        with patch("tools.approval.detect_hardline_command", return_value=(False, "")), \
+             patch("tools.approval.detect_dangerous_command", return_value=(False, None, "")):
+            resp = handler(1, {"command": "echo hello"})
+        assert mock_run.called, "subprocess.run was not invoked"
+        kwargs = mock_run.call_args[1]
+        assert kwargs.get("encoding") == "utf-8", (
+            f"shell.exec subprocess.run must set encoding='utf-8' (got {kwargs.get('encoding')!r})"
+        )
+        assert kwargs.get("errors") == "replace", (
+            f"shell.exec subprocess.run must set errors='replace' (got {kwargs.get('errors')!r})"
+        )
+
+
+# ── quick-command exec path (via command.dispatch) ───────────────────────
+
+def test_quick_command_exec_uses_utf8_replace():
+    """A quick_command of type 'exec' is dispatched via command.dispatch;
+    the underlying subprocess.run must pass encoding="utf-8" and
+    errors="replace" (#53137)."""
+    handler = server._methods["command.dispatch"]
+    fake_cp = _make_completed_process()
+    with patch("subprocess.run", return_value=fake_cp) as mock_run, \
+         patch("tui_gateway.server._load_cfg", return_value={
+             "quick_commands": {"runcmd": {"type": "exec", "command": "echo hi"}}
+         }), \
+         patch("tools.environments.local._sanitize_subprocess_env", return_value={"PATH": "/usr/bin"}):
+        resp = handler(1, {"name": "runcmd", "arg": "", "session_id": ""})
+        assert mock_run.called, "subprocess.run was not invoked for quick-command exec"
+        kwargs = mock_run.call_args[1]
+        assert kwargs.get("encoding") == "utf-8", (
+            f"quick-command exec subprocess.run must set encoding='utf-8' (got {kwargs.get('encoding')!r})"
+        )
+        assert kwargs.get("errors") == "replace", (
+            f"quick-command exec subprocess.run must set errors='replace' (got {kwargs.get('errors')!r})"
+        )
diff --git a/tools/async_delegation.py b/tools/async_delegation.py
index e456aed50f8..7e88899e585 100644
--- a/tools/async_delegation.py
+++ b/tools/async_delegation.py
@@ -43,7 +43,8 @@ import threading
 import time
 import uuid
 from concurrent.futures import ThreadPoolExecutor
-from typing import Any, Callable, Dict, List, Optional
+from contextlib import contextmanager
+from typing import Any, Callable, Dict, Iterator, List, Optional
 
 from hermes_constants import get_hermes_home
 from tools.daemon_pool import DaemonThreadPoolExecutor
@@ -90,11 +91,22 @@ def _db_path():
 
 
 def _connect() -> sqlite3.Connection:
-    from hermes_state import apply_wal_with_fallback
-
     path = _db_path()
     path.parent.mkdir(parents=True, exist_ok=True)
     conn = sqlite3.connect(path, timeout=10)
+    try:
+        _initialize_schema(conn)
+    except Exception:
+        # A PRAGMA/DDL failure after a successful connect() must not leak the
+        # just-opened connection back to the caller.
+        conn.close()
+        raise
+    return conn
+
+
+def _initialize_schema(conn: sqlite3.Connection) -> None:
+    from hermes_state import apply_wal_with_fallback
+
     apply_wal_with_fallback(conn, db_label="state.db (async_delegation)")
     conn.execute(
         """CREATE TABLE IF NOT EXISTS async_delegations (
@@ -134,7 +146,25 @@ def _connect() -> sqlite3.Connection:
     ):
         if name not in columns:
             conn.execute(f"ALTER TABLE async_delegations ADD COLUMN {name} {sql_type}")
-    return conn
+
+
+@contextmanager
+def _transaction() -> Iterator[sqlite3.Connection]:
+    """Open a connection, commit/rollback on exit, and ALWAYS close it.
+
+    ``sqlite3.Connection.__enter__``/``__exit__`` only commit or roll back the
+    transaction; they do not close the connection. Using ``with _connect()``
+    alone therefore leaks a connection — and its WAL/SHM file descriptors — on
+    every durable dispatch, completion, and delivery-claim, deferring the close
+    to the garbage collector. On a long-running gateway that exhausts
+    ``RLIMIT_NOFILE`` (the cron-ledger sibling of this bug was #69567 / PR #69594).
+    """
+    conn = _connect()
+    try:
+        with conn:
+            yield conn
+    finally:
+        conn.close()
 
 
 def _persist_dispatch(record: Dict[str, Any]) -> None:
@@ -149,7 +179,7 @@ def _persist_dispatch(record: Dict[str, Any]) -> None:
         for key in ("goal", "goals", "context", "toolsets", "role", "model", "is_batch")
         if key in record
     }
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         conn.execute(
             """INSERT OR REPLACE INTO async_delegations
                (delegation_id, origin_session, origin_ui_session_id,
@@ -167,7 +197,7 @@ def _persist_dispatch(record: Dict[str, Any]) -> None:
 
 
 def _delete_durable_delegation(delegation_id: str) -> None:
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         conn.execute("DELETE FROM async_delegations WHERE delegation_id=?", (delegation_id,))
 
 
@@ -175,7 +205,7 @@ def _prune_durable_records() -> None:
     """Bound terminal history, preferring delivered records for deletion."""
     now = time.time()
     cutoff = now - _DURABLE_RETENTION_SECONDS
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         conn.execute(
             "DELETE FROM async_delegations WHERE delivery_state='delivered' AND updated_at < ?",
             (cutoff,),
@@ -212,7 +242,7 @@ def _prune_durable_records() -> None:
 
 def _persist_completion(event: Dict[str, Any], result: Dict[str, Any]) -> None:
     now = time.time()
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         conn.execute(
             """UPDATE async_delegations SET state=?, completed_at=?, updated_at=?,
                event_json=?, result_json=?, delivery_state='pending'
@@ -223,7 +253,7 @@ def _persist_completion(event: Dict[str, Any], result: Dict[str, Any]) -> None:
 
 
 def _note_delivery_attempt(delegation_id: str) -> None:
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         conn.execute(
             "UPDATE async_delegations SET delivery_attempts=delivery_attempts+1, updated_at=? WHERE delegation_id=?",
             (time.time(), delegation_id),
@@ -238,7 +268,7 @@ def recover_abandoned_delegations() -> int:
         return 0
     now = time.time()
     recovered = 0
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         rows = conn.execute(
             """SELECT delegation_id, origin_session, origin_ui_session_id,
                       parent_session_id, dispatched_at, owner_pid,
@@ -294,7 +324,7 @@ def restore_undelivered_completions(target_queue) -> int:
     results seconds after boot (#64484).
     """
     recover_abandoned_delegations()
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         rows = conn.execute(
             """SELECT delegation_id, event_json FROM async_delegations
                WHERE state != 'running' AND delivery_state='pending' AND event_json IS NOT NULL
@@ -311,7 +341,7 @@ def restore_undelivered_completions(target_queue) -> int:
 def mark_completion_delivered(delegation_id: str) -> bool:
     """Atomically acknowledge successful injection of a durable completion."""
     now = time.time()
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         cur = conn.execute(
             """UPDATE async_delegations SET delivery_state='delivered', delivered_at=?, updated_at=?
                WHERE delegation_id=? AND delivery_state!='delivered'""",
@@ -323,7 +353,7 @@ def mark_completion_delivered(delegation_id: str) -> bool:
 def claim_completion_delivery(delegation_id: str, claim_id: str) -> bool:
     """Claim one pending completion across competing consumers/processes."""
     now = time.time()
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         row = conn.execute(
             "SELECT delivery_state FROM async_delegations WHERE delegation_id=?",
             (delegation_id,),
@@ -362,7 +392,7 @@ def release_completion_delivery(delegation_id: str, claim_id: str) -> bool:
     pending rows).
     """
     now = time.time()
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         capped = conn.execute(
             """UPDATE async_delegations SET delivery_state='dropped',
                       delivery_claim=NULL, delivery_claimed_at=NULL, updated_at=?
@@ -397,7 +427,7 @@ def drop_completion_delivery(delegation_id: str, claim_id: str) -> bool:
     completion that will be fail-closed dropped again every time.
     """
     now = time.time()
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         cur = conn.execute(
             """UPDATE async_delegations SET delivery_state='dropped',
                       updated_at=?, delivery_claim=NULL,
@@ -412,7 +442,7 @@ def drop_completion_delivery(delegation_id: str, claim_id: str) -> bool:
 def complete_completion_delivery(delegation_id: str, claim_id: str) -> bool:
     """Acknowledge acceptance for the consumer holding this claim."""
     now = time.time()
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         cur = conn.execute(
             """UPDATE async_delegations SET delivery_state='delivered',
                       delivered_at=?, updated_at=?, delivery_claim=NULL,
@@ -435,7 +465,7 @@ def release_event_delivery(evt: Dict[str, Any], claim_id: str) -> None:
 
 
 def get_durable_delegation(delegation_id: str) -> Optional[Dict[str, Any]]:
-    with _DB_LOCK, _connect() as conn:
+    with _DB_LOCK, _transaction() as conn:
         row = conn.execute(
             """SELECT origin_session, state, dispatched_at, completed_at,
                       result_json, delivery_state, delivery_attempts,
diff --git a/tools/browser_tool.py b/tools/browser_tool.py
index bcc1455d783..c8cf7515700 100644
--- a/tools/browser_tool.py
+++ b/tools/browser_tool.py
@@ -4687,7 +4687,7 @@ def _maybe_autoinstall_chromium() -> bool:
         proc = subprocess.run(
             install_cmd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=600,
             env=_build_browser_env(),
         )
diff --git a/tools/checkpoint_manager.py b/tools/checkpoint_manager.py
index b5ce04c6a64..27d3680725c 100644
--- a/tools/checkpoint_manager.py
+++ b/tools/checkpoint_manager.py
@@ -327,7 +327,7 @@ def _run_git(
         result = subprocess.run(
             cmd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=timeout,
             env=env,
             cwd=str(normalized_working_dir),
@@ -453,7 +453,7 @@ def _init_store(store: Path, working_dir: str) -> Optional[str]:
     try:
         result = subprocess.run(
             ["git", "init", "--bare", str(store)],
-            capture_output=True, text=True,
+            capture_output=True, text=True, encoding='utf-8', errors='replace',
             env=init_env, timeout=_GIT_TIMEOUT,
             stdin=subprocess.DEVNULL,
             creationflags=windows_hide_flags(),
@@ -483,6 +483,39 @@ def _init_store(store: Path, working_dir: str) -> Optional[str]:
     return None
 
 
+def _volume_evidence(workdir: Path) -> Dict:
+    """Record the identity of ``workdir``'s parent while the project is live.
+
+    ``(st_dev, st_ino)`` of the parent directory, captured at a moment when
+    the workdir itself is reachable, identifies the *directory* — not just
+    the path.  A mount point resolves to the mounted filesystem's root while
+    the volume is attached and to the underlying (underlay) directory after
+    unmount: same path, different directory, different ``(st_dev, st_ino)``.
+    Orphan pruning uses this to distinguish "the project was deleted out of
+    the directory we knew" from "a different directory is now visible at
+    that path because the volume is detached".
+
+    Returns ``{}`` when the workdir is not currently reachable, when the
+    filesystem does not provide a usable directory identity (a zero
+    ``st_dev`` or ``st_ino`` — e.g. Windows filesystems without file IDs and
+    some network shares), or when the probe fails — callers treat all of
+    these as "no evidence recorded" and orphan pruning stays conservative
+    for the project (never classified as orphan; retention still applies).
+    """
+    try:
+        if not workdir.exists():
+            return {}
+        st = workdir.parent.stat()
+        if not st.st_dev or not st.st_ino:
+            return {}
+        return {
+            "workdir_parent_dev": st.st_dev,
+            "workdir_parent_ino": st.st_ino,
+        }
+    except OSError:
+        return {}
+
+
 def _register_project(store: Path, working_dir: str) -> None:
     """Create or update ``projects/<hash>.json`` with workdir + timestamps."""
     dir_hash = _project_hash(working_dir)
@@ -490,11 +523,22 @@ def _register_project(store: Path, working_dir: str) -> None:
     now = time.time()
     meta: Dict = {"workdir": str(_normalize_path(working_dir)),
                   "created_at": now, "last_touch": now}
+    evidence = _volume_evidence(_normalize_path(working_dir))
+    if evidence:
+        meta.update(evidence)
     if meta_path.exists():
         try:
             existing = json.loads(meta_path.read_text(encoding="utf-8"))
             if isinstance(existing, dict):
                 meta["created_at"] = existing.get("created_at", now)
+                if not evidence:
+                    # Fresh probe failed — keep the previously recorded
+                    # parent identity rather than dropping it. Stale evidence
+                    # only makes pruning MORE conservative (mismatch => not
+                    # an orphan).
+                    for key in ("workdir_parent_dev", "workdir_parent_ino"):
+                        if key in existing:
+                            meta[key] = existing[key]
         except (OSError, ValueError):
             pass
     try:
@@ -520,6 +564,13 @@ def _touch_project(store: Path, working_dir: str) -> None:
     meta["workdir"] = str(_normalize_path(working_dir))
     meta["last_touch"] = time.time()
     meta.setdefault("created_at", meta["last_touch"])
+    # Refresh the parent-directory identity while the project is observably
+    # live — a remount can legitimately change it (new device, new inode).
+    # On probe failure the previous evidence is kept: stale evidence can only
+    # make pruning MORE conservative (mismatch => not an orphan).
+    evidence = _volume_evidence(_normalize_path(working_dir))
+    if evidence:
+        meta.update(evidence)
     try:
         meta_path.write_text(json.dumps(meta), encoding="utf-8")
     except OSError as exc:
@@ -545,6 +596,44 @@ def _list_projects(store: Path) -> List[Dict]:
     return out
 
 
+def _pre_v2_shadow_repos(base: Path) -> List[Dict]:
+    """Return pre-v2 per-project shadow repos still directly under ``base``.
+
+    Pre-v2 layout kept one shadow git repo per working directory directly
+    under ``CHECKPOINT_BASE`` (identified by a ``HEAD`` file).  This is the
+    single source of truth for that scan so a preview built from it (e.g.
+    ``store_status``) always matches what ``prune_checkpoints`` deletes.
+    """
+    out: List[Dict] = []
+    if not base.exists():
+        return out
+    for child in base.iterdir():
+        if not child.is_dir():
+            continue
+        if child.name == _STORE_DIRNAME or child.name.startswith(_LEGACY_PREFIX):
+            continue
+        if not (child / "HEAD").exists():
+            continue
+        workdir: Optional[str] = None
+        marker_unreadable = False
+        wd_marker = child / "HERMES_WORKDIR"
+        if wd_marker.exists():
+            try:
+                workdir = wd_marker.read_text(encoding="utf-8").strip()
+            except (OSError, UnicodeDecodeError):
+                # The marker is there, we just could not read it. That is
+                # not evidence the project is gone — never delete on it.
+                workdir = None
+                marker_unreadable = True
+        out.append({
+            "path": child,
+            "workdir": workdir,
+            "exists": bool(workdir) and Path(workdir).exists(),
+            "marker_unreadable": marker_unreadable,
+        })
+    return out
+
+
 def _dir_file_count(path: str) -> int:
     """Quick file count estimate (stops early if over _MAX_FILES)."""
     count = 0
@@ -1255,11 +1344,112 @@ def _delete_ref(store: Path, ref: str) -> bool:
     return ok
 
 
+def _workdir_is_observably_gone(
+    workdir: str,
+    parent_dev: Optional[int] = None,
+    parent_ino: Optional[int] = None,
+    require_parent_identity: bool = True,
+) -> bool:
+    """True only when we can positively observe that ``workdir`` was removed.
+
+    ``Path.exists()`` returns False for a deleted directory AND for one whose
+    storage simply is not attached right now — an unplugged external drive, a
+    network share behind a downed VPN, a bind-mount absent from this
+    container, an offline Windows mapped drive. Orphan pruning deletes the
+    project's entire checkpoint history, so treating that ambiguity as
+    "deleted" throws away the user's restore points over a transient mount
+    state, unattended, at startup.
+
+    Require corroboration, in three steps.
+
+    First, the parent directory must be present, so the absence of the project
+    inside it is something we actually observed. When the parent is missing
+    too, the volume is not there and we know nothing.
+
+    Second, the present parent must be the directory we knew — not merely a
+    directory at the same path. Unmounting swaps the directory visible at a
+    mount point: while the volume is attached the path resolves to the
+    mounted filesystem's root; after detach it resolves to the *underlying*
+    (underlay) directory, which may carry entries of its own (a ``.keep``
+    placeholder, sibling mount points). Those entries were never next to the
+    project and prove nothing about the volume being attached. So the
+    parent's ``(st_dev, st_ino)`` must match the identity recorded in the
+    project's metadata while the project was observably live
+    (``parent_dev``/``parent_ino``). A mismatch means a different directory
+    is visible at that path — a detached volume, not an observed deletion.
+    When no identity was ever recorded (metadata written by an older
+    version) and ``require_parent_identity`` is True, stay conservative and
+    do not classify as orphan. Callers that have no identity channel at all
+    (the frozen pre-v2 layout) pass ``require_parent_identity=False`` to
+    keep the structural checks only.
+
+    Third, the (identity-confirmed) parent must actually carry information.
+    Unmounting leaves classic static mount points (``/mnt/volume/proj``, an
+    fstab entry, a container bind-mount) behind as *empty* directories, so an
+    empty parent is the signature of a detached volume just as much as of a
+    deleted project. Prune only when the parent holds something else (we
+    observed a populated directory that does not contain the project) or is
+    itself a live mount point (the volume is demonstrably attached and the
+    project is demonstrably not on it).
+
+    Genuinely abandoned projects are still reclaimed by the retention/stale
+    rule, which runs off ``last_touch`` rather than a filesystem probe.
+    """
+    if not workdir:
+        return False
+    path = Path(workdir)
+    try:
+        if path.exists():
+            return False
+        parent = path.parent
+        # A path whose parent is itself (a filesystem root) gives us nothing
+        # to corroborate against.
+        if parent == path:
+            return False
+        if not parent.is_dir():
+            return False
+        if parent_dev is not None and parent_ino is not None:
+            st = parent.stat()
+            if (st.st_dev, st.st_ino) != (parent_dev, parent_ino):
+                # A different directory is visible at the parent's path than
+                # the one the project lived in — the volume is detached (its
+                # underlay showing through) or was swapped. Not a deletion.
+                return False
+        elif require_parent_identity:
+            # No recorded identity to check against — we cannot tell the
+            # project's real parent from an underlay directory exposed by an
+            # unmount. Unsure never deletes; retention still reclaims.
+            return False
+        if _dir_has_any_entry(parent):
+            return True
+        # Empty parent: only evidence if that directory is a mount point, i.e.
+        # the volume is attached right now and simply does not hold the
+        # project. An empty plain directory is an unmounted mount point as
+        # readily as an emptied project root.
+        return os.path.ismount(parent)
+    except OSError:
+        # Probe failed (permission, I/O error) — not evidence of deletion.
+        return False
+
+
+def _dir_has_any_entry(directory: Path) -> bool:
+    """True when ``directory`` contains at least one entry.
+
+    Stops after the first entry rather than materializing the listing; a
+    project root can hold a large tree.
+    """
+    with os.scandir(directory) as entries:
+        for _ in entries:
+            return True
+    return False
+
+
 def prune_checkpoints(
     retention_days: int = 7,
     delete_orphans: bool = True,
     checkpoint_base: Optional[Path] = None,
     max_total_size_mb: int = 0,
+    orphan_allowlist: Optional[set] = None,
 ) -> Dict[str, int]:
     """Delete stale/orphan checkpoints and reclaim store space.
 
@@ -1269,6 +1459,17 @@ def prune_checkpoints(
       (the original project was deleted / moved); OR
     * its ``last_touch`` is older than ``retention_days`` days.
 
+    ``orphan_allowlist``, when not ``None``, restricts orphan deletion to
+    the given identities (v2 project ``_hash`` strings and/or pre-v2 shadow
+    repo paths as ``str``). This lets a caller that showed the user a
+    confirmation preview (built from ``store_status()``) bind the resulting
+    deletion to exactly what was displayed — a project that only becomes
+    orphaned *after* the preview (e.g. its workdir vanishes while the human
+    is answering the prompt) is skipped rather than swept up under the
+    earlier confirmation. Pass ``None`` (the default) to delete every
+    currently-orphaned project, e.g. for ``--force`` or unattended callers
+    that never show a preview.
+
     Additionally, if ``max_total_size_mb > 0`` and the store exceeds that
     after orphan/stale pruning, the oldest commit per remaining project is
     dropped until the store is under the cap.
@@ -1325,22 +1526,29 @@ def prune_checkpoints(
             except OSError as exc:
                 result["errors"] += 1
                 logger.warning("Failed to delete legacy archive %s: %s", child, exc)
-            continue
-        # Only count as a pre-v2 shadow repo if it has a HEAD.
-        if not (child / "HEAD").exists():
-            continue
+
+    # Pre-v2 per-project shadow repos.  Scanned via the same helper
+    # `store_status()` uses for its orphan preview, so a confirmation prompt
+    # built from that preview always matches what gets deleted here.
+    for repo in _pre_v2_shadow_repos(base):
+        child = repo["path"]
         result["scanned"] += 1
         reason: Optional[str] = None
-        if delete_orphans:
-            workdir: Optional[str] = None
-            wd_marker = child / "HERMES_WORKDIR"
-            if wd_marker.exists():
-                try:
-                    workdir = wd_marker.read_text(encoding="utf-8").strip()
-                except (OSError, UnicodeDecodeError):
-                    workdir = None
-            if workdir is None or not Path(workdir).exists():
-                reason = "orphan"
+        if (
+            delete_orphans
+            and not repo["marker_unreadable"]
+            and (
+                repo["workdir"] is None
+                # The frozen pre-v2 layout has no metadata channel to carry a
+                # recorded parent identity, so only the structural checks
+                # (parent present + populated / live mount point) apply here.
+                or _workdir_is_observably_gone(
+                    repo["workdir"], require_parent_identity=False,
+                )
+            )
+            and (orphan_allowlist is None or str(child) in orphan_allowlist)
+        ):
+            reason = "orphan"
         if reason is None and retention_days > 0:
             newest = 0.0
             try:
@@ -1378,7 +1586,24 @@ def prune_checkpoints(
                 continue
             result["scanned"] += 1
             reason = None
-            if delete_orphans and (not workdir or not Path(workdir).exists()):
+            parent_dev = meta.get("workdir_parent_dev")
+            parent_ino = meta.get("workdir_parent_ino")
+            if not isinstance(parent_dev, int) or isinstance(parent_dev, bool):
+                parent_dev = None
+            if not isinstance(parent_ino, int) or isinstance(parent_ino, bool):
+                parent_ino = None
+            if (
+                delete_orphans
+                and (
+                    not workdir
+                    or _workdir_is_observably_gone(
+                        workdir,
+                        parent_dev=parent_dev,
+                        parent_ino=parent_ino,
+                    )
+                )
+                and (orphan_allowlist is None or dir_hash in orphan_allowlist)
+            ):
                 reason = "orphan"
             elif retention_days > 0:
                 last_touch = float(meta.get("last_touch", 0) or 0)
@@ -1572,7 +1797,14 @@ def store_status(checkpoint_base: Optional[Path] = None) -> Dict:
 
     ``{"base": path, "store_size_bytes": N, "legacy_size_bytes": N,
        "total_size_bytes": N, "project_count": N, "projects": [...],
-       "legacy_archives": [...]}``
+       "pre_v2_projects": [...], "legacy_archives": [...]}``
+
+    ``pre_v2_projects`` covers shadow repos still on the pre-v2 per-project
+    layout (``base/<hash>/HEAD``) — distinct from ``legacy_archives``, which
+    are already-migrated ``legacy-<ts>/`` dirs. Callers that preview an
+    orphan-deletion sweep must include both ``projects`` and
+    ``pre_v2_projects``, since ``prune_checkpoints`` deletes orphans from
+    both layouts.
     """
     base = checkpoint_base or CHECKPOINT_BASE
     out: Dict = {
@@ -1582,6 +1814,7 @@ def store_status(checkpoint_base: Optional[Path] = None) -> Dict:
         "total_size_bytes": 0,
         "project_count": 0,
         "projects": [],
+        "pre_v2_projects": [],
         "legacy_archives": [],
     }
     if not base.exists():
@@ -1613,6 +1846,15 @@ def store_status(checkpoint_base: Optional[Path] = None) -> Dict:
                 })
     out["project_count"] = len(out["projects"])
 
+    out["pre_v2_projects"] = [
+        {
+            "path": str(r["path"]),
+            "workdir": r["workdir"],
+            "exists": r["exists"],
+        }
+        for r in _pre_v2_shadow_repos(base)
+    ]
+
     for child in base.iterdir():
         if child.is_dir() and child.name.startswith(_LEGACY_PREFIX):
             try:
diff --git a/tools/computer_use/cua_backend.py b/tools/computer_use/cua_backend.py
index 94b456dd67f..98b98ec0be6 100644
--- a/tools/computer_use/cua_backend.py
+++ b/tools/computer_use/cua_backend.py
@@ -295,7 +295,7 @@ def _linux_x11_active_window_id() -> Optional[int]:
         proc = subprocess.run(
             ["xprop", "-root", "_NET_ACTIVE_WINDOW"],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=2,
             check=False,
         )
@@ -379,7 +379,7 @@ def _resolve_mcp_invocation(
         from tools.environments.local import _sanitize_subprocess_env
         proc = subprocess.run(
             [driver_cmd, "manifest"],
-            capture_output=True, text=True, timeout=timeout,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout,
             stdin=subprocess.DEVNULL,
             # cua-driver is a third-party binary — never hand it provider
             # API keys via inherited env (same policy as the MCP and CLI
@@ -445,7 +445,7 @@ def _cua_driver_supports_no_overlay(driver_cmd: str) -> bool:
         from tools.environments.local import _sanitize_subprocess_env
         proc = subprocess.run(
             [driver_cmd, "--help"],
-            capture_output=True, text=True, timeout=3.0,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=3.0,
             stdin=subprocess.DEVNULL,
             env=_sanitize_subprocess_env(cua_driver_child_env()),
         )
@@ -576,7 +576,7 @@ def cua_driver_update_check(*, timeout: float = 8.0) -> Optional[Dict[str, Any]]
         from tools.environments.local import _sanitize_subprocess_env
         proc = subprocess.run(
             [driver_cmd, "check-update", "--json"],
-            capture_output=True, text=True, timeout=timeout,
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout,
             # Some older drivers don't have the verb and fall through to a
             # stdin-reading mode rather than erroring — DEVNULL gives them EOF
             # so they exit fast instead of blocking until the timeout.
@@ -1256,7 +1256,7 @@ class _CuaDriverSession:
             for attempt in range(attempts):
                 try:
                     proc = _subprocess.run(
-                        cmd, capture_output=True, text=True, timeout=max(15.0, timeout),
+                        cmd, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=max(15.0, timeout),
                         env=_sanitize_subprocess_env(cua_driver_child_env()),
                     )
                 except Exception as e:  # pragma: no cover - subprocess spawn failure
diff --git a/tools/computer_use/permissions.py b/tools/computer_use/permissions.py
index 4cccf2d683d..541fd284c0c 100644
--- a/tools/computer_use/permissions.py
+++ b/tools/computer_use/permissions.py
@@ -66,7 +66,7 @@ def _run(binary: str, *args: str, timeout: float) -> subprocess.CompletedProcess
     return subprocess.run(
         [binary, *args],
         capture_output=True,
-        text=True,
+        text=True, encoding='utf-8', errors='replace',
         timeout=timeout,
         env=_child_env(),
         stdin=subprocess.DEVNULL,
diff --git a/tools/computer_use/tool.py b/tools/computer_use/tool.py
index 1cda6a78fe9..58117ea9056 100644
--- a/tools/computer_use/tool.py
+++ b/tools/computer_use/tool.py
@@ -38,6 +38,7 @@ For captures / actions with `capture_after=True`:
 
 from __future__ import annotations
 
+import atexit
 import base64
 import json
 import logging
@@ -177,16 +178,39 @@ def _get_backend() -> ComputerUseBackend:
         return _backend
 
 
+def _shutdown_backend_atexit() -> None:
+    """Stop the cached backend so the cua-driver child doesn't outlive us.
+
+    The backend is cached per-process and holds a long-lived ``cua-driver``
+    subprocess, so without this the driver survives the Hermes process that
+    spawned it (#28152 item 3). #69903 kept the orphan from burning a core by
+    disabling the cursor overlay; the process itself still lingered.
+
+    Mirrors ``browser_tool``'s ``atexit.register(_emergency_cleanup_all_sessions)``
+    — same spawn-and-drive-a-subprocess shape. atexit only, no signal handlers:
+    a ``SystemExit`` raised from a prompt_toolkit key binding corrupts its
+    coroutine state and makes the process unkillable. Never raises, since an
+    exception escaping atexit prints a traceback on every exit.
+    """
+    global _backend
+    # Drop the lock before stop() — teardown budgets 5s and shouldn't block
+    # an unrelated caller waiting to spawn.
+    with _backend_lock:
+        backend, _backend = _backend, None
+    if backend is None:
+        return
+    try:
+        backend.stop()
+    except Exception as e:
+        logger.debug("cua-driver atexit teardown failed: %s", e)
+
+
+atexit.register(_shutdown_backend_atexit)
+
+
 def reset_backend_for_tests() -> None:  # pragma: no cover
     """Test helper — tear down the cached backend and per-session state."""
-    global _backend
-    with _backend_lock:
-        if _backend is not None:
-            try:
-                _backend.stop()
-            except Exception:
-                pass
-        _backend = None
+    _shutdown_backend_atexit()
     _AUX_VISION_ROUTE_CACHE.clear()
     with _approval_lock:
         _session_auto_approve.clear()
diff --git a/tools/cronjob_tools.py b/tools/cronjob_tools.py
index 430cd1dda40..a623d38c6f5 100644
--- a/tools/cronjob_tools.py
+++ b/tools/cronjob_tools.py
@@ -842,6 +842,12 @@ def cronjob(
             # _execute_job_now advances next_run_at and blocks a concurrent tick
             # from double-firing.
             exec_result = _execute_job_now(job)
+            # A claimed direct run advances next_run_at and may race the
+            # external one-shot for the same occurrence. If Chronos loses that
+            # claim, its consumed fire cannot re-arm itself; reconcile from the
+            # winning direct path after the run has persisted its final state.
+            if exec_result.get("claimed", False):
+                _notify_provider_jobs_changed_safe()
             # Re-read so the response reflects the post-run last_run_at/last_status.
             result = _format_job(get_job(job_id) or {"id": job_id})
             result["executed"] = exec_result.get("claimed", False)
diff --git a/tools/env_probe.py b/tools/env_probe.py
index 95427cc1c9a..6e28a51cfd2 100644
--- a/tools/env_probe.py
+++ b/tools/env_probe.py
@@ -38,6 +38,8 @@ import tempfile
 import threading
 from typing import Optional
 
+from hermes_cli._subprocess_compat import windows_hide_flags
+
 logger = logging.getLogger(__name__)
 
 # Module-level cache.  The probe result is deterministic for the
@@ -105,6 +107,11 @@ def _run(cmd: list[str], timeout: float = 3.0) -> tuple[int, str, str]:
                     timeout=timeout,
                     check=False,
                     stdin=subprocess.DEVNULL,
+                    # CREATE_NO_WINDOW (0 on POSIX): the probe runs in
+                    # windowless processes (pythonw gateway / kanban workers)
+                    # where a console child would otherwise flash a visible
+                    # window per probe — ~5 flashes at every worker startup.
+                    creationflags=windows_hide_flags(),
                 )
             except subprocess.TimeoutExpired:
                 return -1, "", "timeout"
diff --git a/tools/environments/base.py b/tools/environments/base.py
index 1b20cfa90ee..74c33aff753 100644
--- a/tools/environments/base.py
+++ b/tools/environments/base.py
@@ -248,7 +248,7 @@ def _popen_bash(
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
         stdin=subprocess.PIPE if stdin_data is not None else subprocess.DEVNULL,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         **kwargs,
     )
     if stdin_data is not None:
@@ -382,6 +382,53 @@ def _cwd_marker(session_id: str) -> str:
     return f"__HERMES_CWD_{session_id}__"
 
 
+# Per-session variables that the gateway bridges freshly onto every command's
+# process environment (via tools/environments/local._inject_session_context_env,
+# reading gateway.session_context._VAR_MAP). They must NEVER be persisted into
+# the shared bash session snapshot: a single long-lived backend serves many
+# concurrent sessions (the messaging gateway, TUI, desktop/web dashboard all
+# collapse the terminal to one "default" environment), so ``export -p`` dumping
+# the FIRST session's HERMES_SESSION_ID into the snapshot makes every LATER
+# session ``source`` that stale value and see a FOREIGN session's identity —
+# overriding the correct per-command Popen env (issue: cross-session
+# HERMES_SESSION_ID leak via the shared snapshot). Stripping them from the
+# snapshot is safe because they are re-injected on every command; a snapshot
+# should only carry the user's own shell state (PATH, functions, exports they
+# set), not Hermes' per-turn session identity.
+#
+# Kept in sync with gateway.session_context._VAR_MAP: every bridged name starts
+# with one of these prefixes.
+_SNAPSHOT_EXCLUDED_ENV_REGEX = (
+    "^declare -x (HERMES_SESSION_|HERMES_UI_SESSION_ID|HERMES_CRON_AUTO_DELIVER_)"
+)
+
+
+def _export_dump_excluding_session_vars(tmp_path: str) -> str:
+    """Return a shell snippet that dumps ``export -p`` to *tmp_path* minus the
+    per-session bridged vars (see ``_SNAPSHOT_EXCLUDED_ENV_REGEX``).
+
+    ``export -p`` emits one ``declare -x NAME="value"`` line per exported var.
+    We drop the HERMES_SESSION_* / UI / CRON_AUTO_DELIVER lines so they never
+    persist across sessions in the shared snapshot. ``grep -vE`` returns exit 1
+    when it filters everything, so ``|| true`` keeps the pipeline's success
+    contract intact for the callers that chain on it.
+
+    The pipeline MUST be wrapped in a brace group with the redirection applied
+    to the group, not to the last pipeline segment. *tmp_path* typically embeds
+    ``$BASHPID`` for concurrency-safe temp names; a redirection attached
+    directly to ``grep`` is expanded inside grep's own pipeline subshell, where
+    ``$BASHPID`` resolves to the grep subshell's PID — while the caller's
+    follow-up ``mv $tmp`` expands in the parent shell to a DIFFERENT PID. The
+    dump then lands in an orphaned temp file and the snapshot silently never
+    updates (all exported-env persistence breaks). The brace-group redirect is
+    expanded in the current shell, keeping both expansions consistent.
+    """
+    return (
+        f"{{ export -p | grep -vE '{_SNAPSHOT_EXCLUDED_ENV_REGEX}' || true; }} "
+        f"> {tmp_path}"
+    )
+
+
 # ---------------------------------------------------------------------------
 # BaseEnvironment
 # ---------------------------------------------------------------------------
@@ -498,7 +545,7 @@ class BaseEnvironment(ABC):
         _snap_tmp = self._quote_shell_path(self._snapshot_path + ".tmp.") + "$BASHPID"
         bootstrap = (
             f"umask 077\n"
-            f"export -p > {_snap_tmp}\n"
+            f"{_export_dump_excluding_session_vars(_snap_tmp)}\n"
             # Dump function definitions, filtering out private (``_``-prefixed)
             # helpers — mainly bash-completion internals (``_git``, ``_make``…)
             # — by NAME, not by line.  A naive ``declare -f | grep -vE '^_[^_]'``
@@ -642,9 +689,15 @@ class BaseEnvironment(ABC):
         # Chain mv on the export succeeding so a failed/partial dump never
         # replaces a good snapshot; drop the temp on failure so it isn't
         # orphaned (cleaned up wholesale in LocalEnvironment.cleanup too).
+        # NOTE: the redirection must be attached to a brace group, not to the
+        # grep pipeline segment — ``_snap_tmp`` embeds ``$BASHPID``, and a
+        # redirect on grep is expanded inside grep's pipeline subshell (a
+        # different PID than the parent shell that expands the ``mv`` operand),
+        # silently orphaning the dump. See _export_dump_excluding_session_vars.
         if self._snapshot_ready:
             parts.append(
-                f"{{ export -p > {_snap_tmp} && mv -f {_snap_tmp} {_quoted_snap}; }} "
+                f"{{ {_export_dump_excluding_session_vars(_snap_tmp)} "
+                f"&& mv -f {_snap_tmp} {_quoted_snap}; }} "
                 f"2>/dev/null || rm -f {_snap_tmp} 2>/dev/null || true"
             )
 
diff --git a/tools/environments/docker.py b/tools/environments/docker.py
index ea4a6ec77e6..def1ac157f1 100644
--- a/tools/environments/docker.py
+++ b/tools/environments/docker.py
@@ -5,6 +5,7 @@ configurable resource limits (CPU, memory, disk), and optional filesystem
 persistence via bind mounts.
 """
 
+import hashlib
 import json
 import logging
 import os
@@ -36,6 +37,7 @@ _DOCKER_SEARCH_PATHS = [
 
 _docker_executable: Optional[str] = None  # resolved once, cached
 _ENV_VAR_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_EGRESS_LABEL_KEY = "hermes-egress"
 
 
 def _normalize_forward_env_names(forward_env: list[str] | None) -> list[str]:
@@ -179,7 +181,7 @@ def reap_orphan_containers(
     try:
         listing = subprocess.run(
             [docker, "ps", "-a", *filters, "--format", "{{.ID}}"],
-            capture_output=True, text=True, timeout=15, check=False,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=15, check=False,
             stdin=subprocess.DEVNULL,
         )
     except (subprocess.TimeoutExpired, OSError) as e:
@@ -213,7 +215,7 @@ def reap_orphan_containers(
         try:
             result = subprocess.run(
                 [docker, "rm", "-f", cid],
-                capture_output=True, text=True, timeout=30,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=30,
                 stdin=subprocess.DEVNULL,
             )
             if result.returncode == 0:
@@ -243,7 +245,7 @@ def _container_finished_at(docker_exe: str, container_id: str):
     try:
         result = subprocess.run(
             [docker_exe, "inspect", "--format", "{{.State.FinishedAt}}", container_id],
-            capture_output=True, text=True, timeout=10, check=False,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=10, check=False,
             stdin=subprocess.DEVNULL,
         )
     except (subprocess.TimeoutExpired, OSError) as e:
@@ -364,6 +366,247 @@ _PRIVDROP_CAP_ARGS = [
 ]
 
 
+def _egress_proxy_args_for_docker() -> tuple[list[str], dict[str, str], list[str]]:
+    """Build the docker mount/env/host args needed to route a sandbox through
+    the iron-proxy egress firewall.
+
+    Returns ``(volume_args, env_overrides, host_args)``:
+
+    * ``volume_args`` — read-only bind mount of the CA cert into the container
+      (extends docker's ``-v`` argv list)
+    * ``env_overrides`` — env vars to set on container creation: ``HTTPS_PROXY``,
+      ``HTTP_PROXY``, ``NO_PROXY`` (loopback only), Python/Node/curl CA-bundle
+      paths, and one ``HERMES_PROXY_TOKEN_<NAME>`` per minted mapping
+    * ``host_args`` — extra ``--add-host`` flags so the container can reach the
+      host-side proxy (Linux needs ``host.docker.internal:host-gateway``;
+      Docker Desktop populates this automatically on macOS/Windows)
+
+    Returns three empty containers when the proxy is disabled, not yet set up,
+    or not currently running.  If ``proxy.enforce_on_docker`` is true and the
+    proxy is enabled-but-not-running, raises ``RuntimeError`` so the docker
+    backend refuses to start the sandbox.
+    """
+
+    # Narrow except: ImportError is the only legitimate failure here.
+    # Bare ``except Exception`` would hide AttributeError, SyntaxError in
+    # the config module, etc. and silently start the sandbox without
+    # proxy enforcement.  We let unexpected exceptions propagate so the
+    # docker backend visibly fails rather than degrading silently.
+    try:
+        from hermes_cli.config import load_config
+        from agent.proxy_sources import iron_proxy as ip
+    except ImportError as exc:
+        logger.debug("Egress proxy plumbing unavailable: %s", exc)
+        return ([], {}, [])
+
+    cfg = load_config()
+    proxy_cfg = cfg.get("proxy") or {}
+    if not proxy_cfg.get("enabled"):
+        return ([], {}, [])
+
+    status = ip.get_status()
+    enforce = bool(proxy_cfg.get("enforce_on_docker", True))
+
+    if not status.configured:
+        msg = (
+            "proxy.enabled is true but iron-proxy is not configured. "
+            "Run `hermes egress setup` to mint tokens and write proxy.yaml."
+        )
+        if enforce:
+            raise RuntimeError(msg)
+        logger.warning("%s — continuing without proxy (enforce_on_docker=false).", msg)
+        return ([], {}, [])
+
+    if not (status.pid and status.listening):
+        msg = (
+            f"iron-proxy is enabled but not running on port {status.tunnel_port}. "
+            "Start it with `hermes egress start`."
+        )
+        if enforce:
+            raise RuntimeError(msg)
+        logger.warning("%s — continuing without proxy (enforce_on_docker=false).", msg)
+        return ([], {}, [])
+
+    if status.ca_cert_path is None or not status.ca_cert_path.exists():
+        # status.configured was True a moment ago but the CA file has
+        # disappeared.  Treat this with the same enforce semantics as the
+        # other failure branches — silently dropping the CA mount would
+        # leave the sandbox with proxy env vars pointing at iron-proxy
+        # but no trust anchor, so every TLS handshake would 5xx; or
+        # worse, with enforce_on_docker=false we'd drop both the proxy
+        # vars AND any other isolation, opening the sandbox.
+        msg = (
+            f"iron-proxy CA cert vanished from {status.ca_cert_path}. "
+            "Re-run `hermes egress setup` to regenerate it."
+        )
+        if enforce:
+            raise RuntimeError(msg)
+        logger.warning("%s — continuing without proxy (enforce_on_docker=false).", msg)
+        return ([], {}, [])
+
+    # Corrupt or empty mappings.json is a silent failure mode that's
+    # indistinguishable from an upstream outage from inside the sandbox
+    # (every request returns 403).  Refuse to mount with empty mappings
+    # rather than ship a broken sandbox.
+    mappings = ip.load_mappings()
+    if not mappings:
+        msg = (
+            "iron-proxy is configured but mappings.json is empty or "
+            "corrupt.  Re-run `hermes egress setup` to mint provider "
+            "tokens before starting a sandbox."
+        )
+        if enforce:
+            raise RuntimeError(msg)
+        logger.warning("%s — continuing without proxy (enforce_on_docker=false).", msg)
+        return ([], {}, [])
+
+    container_ca = "/etc/ssl/certs/hermes-egress-ca.crt"
+    volume_args = ["-v", f"{status.ca_cert_path}:{container_ca}:ro"]
+
+    # tunnel_port serves CONNECT (HTTPS); the plain-HTTP forward listener
+    # is on tunnel_port + 1 (see build_proxy_config's listener-role notes).
+    proxy_url = f"http://host.docker.internal:{status.tunnel_port}"
+    plain_http_url = f"http://host.docker.internal:{status.tunnel_port + 1}"
+    env_overrides: dict[str, str] = {
+        # HTTPS_PROXY / HTTP_PROXY are respected by curl, requests, urllib,
+        # httpx, node fetch, go default transport, etc.  Lowercase variants
+        # are also set because some tools only look at one casing.
+        "HTTPS_PROXY": proxy_url,
+        "https_proxy": proxy_url,
+        "HTTP_PROXY": plain_http_url,
+        "http_proxy": plain_http_url,
+        # Loopback-only NO_PROXY so localhost dev servers inside the sandbox
+        # (test fixtures, local LLMs) don't get sent through the proxy.
+        "NO_PROXY": "127.0.0.1,localhost,::1",
+        "no_proxy": "127.0.0.1,localhost,::1",
+        # CA bundle locations for the major language runtimes.  iron-proxy
+        # presents a leaf cert signed by our CA on every MITM'd connection.
+        #
+        # CRITICAL ASYMMETRY: Python (REQUESTS_CA_BUNDLE / SSL_CERT_FILE)
+        # and curl (CURL_CA_BUNDLE) REPLACE the system CA store.
+        # NODE_EXTRA_CA_CERTS ADDS to it.  A Node.js process that
+        # bypasses HTTPS_PROXY by using a raw socket would still see the
+        # system CA store and succeed where Python/curl fail validation.
+        # We additionally set NODE_OPTIONS=--use-openssl-ca to force Node
+        # through the OpenSSL store that SSL_CERT_FILE controls, narrowing
+        # the asymmetry.  Not a complete fix — see the docs caveat — but
+        # closes the easy case.
+        "REQUESTS_CA_BUNDLE": container_ca,   # Python `requests`
+        "SSL_CERT_FILE": container_ca,         # Python ssl module / OpenSSL
+        "CURL_CA_BUNDLE": container_ca,        # curl
+        "NODE_EXTRA_CA_CERTS": container_ca,   # Node.js: adds to system store
+        # NOTE: NODE_OPTIONS is intentionally NOT placed in env_overrides
+        # here as a flat assignment.  We need to APPEND --use-openssl-ca
+        # to whatever the user already has in NODE_OPTIONS (e.g.
+        # --max-old-space-size=4096), not clobber it.  The append-merge
+        # happens in DockerEnvironment._merge_node_options below.
+        # For the agent inside the sandbox to identify itself as proxy-aware.
+        "HERMES_EGRESS_PROXY": "1",
+        # Sentinel that DockerEnvironment uses to do the NODE_OPTIONS
+        # append-merge.  Stripped from the final env before docker run.
+        "_HERMES_EGRESS_NODE_OPTIONS_APPEND": "--use-openssl-ca",
+    }
+
+    # Surface the per-provider proxy tokens under the standard provider env
+    # names so existing SDKs and provider clients work unchanged inside the
+    # sandbox.  Alias env names (e.g. GOOGLE_API_KEY for GEMINI_API_KEY)
+    # receive the same token so SDKs reading either name authenticate
+    # through the proxy.  Keep the HERMES_PROXY_TOKEN_* aliases for
+    # diagnostics.
+    for m in mappings:
+        env_overrides[m.real_env_name] = m.proxy_token
+        env_overrides[f"HERMES_PROXY_TOKEN_{m.real_env_name}"] = m.proxy_token
+        for alias in getattr(m, "alias_env_names", ()) or ():
+            env_overrides[alias] = m.proxy_token
+
+    # On Linux, host.docker.internal isn't populated by default — Docker Desktop
+    # adds it on macOS/Windows; on Linux we need an explicit --add-host with
+    # host-gateway.  On Desktop this is a no-op (harmless duplicate).
+    host_args: list[str] = ["--add-host", "host.docker.internal:host-gateway"]
+
+    return (volume_args, env_overrides, host_args)
+
+
+def _egress_reuse_fingerprint(
+    volume_args: list[str],
+    env_overrides: dict[str, str],
+    host_args: list[str],
+) -> str:
+    """Stable Docker-label value for the egress posture of a container."""
+    if not (volume_args or env_overrides or host_args):
+        return "off"
+    payload = json.dumps(
+        {
+            "volume_args": volume_args,
+            "env_overrides": env_overrides,
+            "host_args": host_args,
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:24]
+
+
+def _egress_enforce_on_docker(default: bool = True) -> bool:
+    """Read proxy.enforce_on_docker with fail-safe defaulting."""
+    try:
+        from hermes_cli.config import load_config as _load_cfg
+
+        return bool((_load_cfg().get("proxy") or {}).get("enforce_on_docker", default))
+    except (ImportError, OSError):
+        return default
+    except Exception:
+        return default
+
+
+def _critical_egress_env_names(env_overrides: dict[str, str]) -> set[str]:
+    """Env names that would weaken or bypass enforced egress if overridden."""
+    critical = {
+        "HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy",
+        "NO_PROXY", "no_proxy",
+        "REQUESTS_CA_BUNDLE", "SSL_CERT_FILE", "CURL_CA_BUNDLE",
+        "NODE_EXTRA_CA_CERTS", "NODE_OPTIONS",
+    }
+    critical.update(
+        key for key in env_overrides
+        if key.endswith("_API_KEY") or key.endswith("_TOKEN")
+    )
+    return critical
+
+
+def _extra_args_egress_collisions(
+    extra_args: list[str], critical_names: set[str],
+) -> list[str]:
+    """Return docker_extra_args entries that can override egress controls."""
+    collisions: list[str] = []
+    env_flags = {"-e", "--env", "--env-file"}
+    network_flags = {"--network", "--net"}
+    i = 0
+    while i < len(extra_args):
+        arg = extra_args[i]
+        nxt = extra_args[i + 1] if i + 1 < len(extra_args) else ""
+        if arg in env_flags:
+            if arg == "--env-file":
+                collisions.append(arg)
+            else:
+                name = nxt.split("=", 1)[0]
+                if name in critical_names:
+                    collisions.append(name)
+            i += 2
+            continue
+        if any(arg.startswith(f"{flag}=") for flag in env_flags):
+            if arg.startswith("--env-file="):
+                collisions.append("--env-file")
+            else:
+                name = arg.split("=", 1)[1].split("=", 1)[0]
+                if name in critical_names:
+                    collisions.append(name)
+        elif arg in network_flags or any(arg.startswith(f"{flag}=") for flag in network_flags):
+            collisions.append(arg)
+        i += 1
+    return sorted(set(collisions))
+
+
 def _build_security_args(run_as_host_user: bool, run_exec: bool = False) -> list[str]:
     """Return the security/cap/tmpfs args tailored to the privilege mode.
 
@@ -394,7 +637,7 @@ def _image_uses_init_entrypoint(docker_exe: str, image: str) -> bool:
             [docker_exe, "image", "inspect", image,
              "--format", "{{json .Config.Entrypoint}}"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=15,
             stdin=subprocess.DEVNULL,
         )
@@ -477,7 +720,7 @@ def _cgroup_limits_available(image: str) -> bool:
              "--cpus", "0.5", "--memory", "64m", "--pids-limit", "32",
              image, "sleep", "0"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=60,
             stdin=subprocess.DEVNULL,
         )
@@ -520,7 +763,7 @@ def _ensure_docker_available() -> None:
         result = subprocess.run(
             [docker_exe, "version"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=5,
             stdin=subprocess.DEVNULL,
         )
@@ -786,11 +1029,195 @@ class DockerEnvironment(BaseEnvironment):
         except Exception as e:
             logger.debug("Docker: could not load credential file mounts: %s", e)
 
+        # Egress credential-injection proxy (iron-proxy) — when configured,
+        # mount the CA cert into the sandbox and set HTTPS_PROXY + CA-bundle
+        # env vars so outbound traffic routes through the host-side proxy.
+        # The sandbox receives PROXY tokens instead of real API keys.
+        egress_volume_args, egress_env_overrides, egress_host_args = (
+            _egress_proxy_args_for_docker()
+        )
+        egress_label = _egress_reuse_fingerprint(
+            egress_volume_args, egress_env_overrides, egress_host_args,
+        )
+        _enforce_egress = _egress_enforce_on_docker()
+        _critical_egress_names = _critical_egress_env_names(egress_env_overrides)
+        if egress_env_overrides:
+            _forward_collisions = sorted(
+                key for key in self._forward_env if key in _critical_egress_names
+            )
+            if _forward_collisions:
+                _msg = (
+                    f"docker_forward_env would inject real egress-protected "
+                    f"variables {_forward_collisions}; enforce_on_docker is "
+                    f"{'enabled' if _enforce_egress else 'disabled'}."
+                )
+                if _enforce_egress:
+                    raise RuntimeError(
+                        f"{_msg}  Remove these names from docker_forward_env "
+                        "or disable enforce_on_docker to opt out of egress isolation."
+                    )
+                logger.warning(
+                    "%s  Explicit docker_forward_env values will override egress tokens.",
+                    _msg,
+                )
+        volume_args.extend(egress_volume_args)
+        # egress env overrides are merged in further below alongside the
+        # other env_args computation.
+
         # Explicit environment variables (docker_env config) — set at container
         # creation so they're available to all processes (including entrypoint).
+        # Egress proxy env vars (HTTPS_PROXY, CA-bundle paths, proxy tokens)
+        # are merged below.  Precedence policy:
+        #
+        # - When egress enforcement is on AND the user's docker_env tries
+        #   to override one of the proxy-control vars (HTTPS_PROXY,
+        #   SSL_CERT_FILE, etc.), fail-loud rather than silently inverting
+        #   the isolation.  The CA mount + tokens would still ship while
+        #   traffic leaves the sandbox direct with real credentials —
+        #   exactly what enforce_on_docker is meant to prevent.
+        # - When enforcement is off, the user's docker_env wins (current
+        #   behavior) but we log a warning naming both config sources.
+        # - When the user override is identical to the egress value, no-op.
+        if egress_env_overrides:
+            try:
+                from hermes_cli.config import load_config as _load_cfg_for_collision
+                _proxy_cfg = (_load_cfg_for_collision().get("proxy") or {})
+            except (ImportError, OSError):
+                _proxy_cfg = {}
+            except Exception as _e:  # noqa: BLE001 — narrowed below via yaml import
+                # yaml.YAMLError from a malformed config.yaml.  We import
+                # lazily because PyYAML is a soft dep in some test envs.
+                try:
+                    import yaml  # noqa: F401
+                except ImportError:
+                    raise
+                logger.warning(
+                    "Could not read proxy config for egress collision check: %s",
+                    _e,
+                )
+                _proxy_cfg = {}
+            _enforce_egress = bool(_proxy_cfg.get("enforce_on_docker", True))
+            # Egress-controlling env vars that affect the proxy posture.
+            _critical_proxy_control = {
+                "HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy",
+                "NO_PROXY", "no_proxy",
+                "REQUESTS_CA_BUNDLE", "SSL_CERT_FILE", "CURL_CA_BUNDLE",
+                "NODE_EXTRA_CA_CERTS",
+            }
+            # stephenschoettler #2: also block docker_env from injecting
+            # real provider keys.  `docker_env: {OPENROUTER_API_KEY: sk-real}`
+            # in config.yaml puts the live secret into the sandbox while
+            # egress is nominally enforced — defeats the entire feature.
+            # Pull the mapped real_env_name from each token mapping at
+            # call time so this stays in sync with whatever the operator
+            # has configured.
+            _critical_provider_keys: set[str] = set()
+            try:
+                from agent.proxy_sources import iron_proxy as _ip_for_mappings
+                _critical_provider_keys = {
+                    m.real_env_name for m in _ip_for_mappings.load_mappings()
+                }
+            except Exception:  # noqa: BLE001 — best-effort collision check
+                pass
+            _critical = _critical_proxy_control | _critical_provider_keys
+            _collisions = sorted(
+                k for k in _critical
+                if k in self._env
+                and (
+                    k not in egress_env_overrides
+                    or self._env[k] != egress_env_overrides[k]
+                )
+                # For provider keys, ANY override is a collision (the egress
+                # path mints proxy tokens; a real key in docker_env bypasses
+                # the swap regardless of whether the egress dict happens to
+                # carry it).
+                and (
+                    k in _critical_provider_keys
+                    or (k in egress_env_overrides
+                        and self._env[k] != egress_env_overrides[k])
+                )
+            )
+            if _collisions:
+                _msg = (
+                    f"docker_env in config.yaml overrides egress-proxy "
+                    f"variables {_collisions}; enforce_on_docker is "
+                    f"{'enabled' if _enforce_egress else 'disabled'}."
+                )
+                if _enforce_egress:
+                    raise RuntimeError(
+                        f"{_msg}  Remove these keys from docker_env or "
+                        "disable enforce_on_docker to opt out of egress "
+                        "isolation."
+                    )
+                logger.warning(
+                    "%s  Falling back to docker_env values; sandbox traffic "
+                    "will NOT route through the proxy.", _msg,
+                )
+
+        # When enforce_on_docker is true, egress overrides win.  When
+        # false, docker_env wins (back-compat for users who deliberately
+        # opt out).  In both cases the collision check above has already
+        # surfaced any disagreement.
+        try:
+            from hermes_cli.config import load_config as _load_cfg_for_precedence
+            _enforce_egress_merge = bool(
+                (_load_cfg_for_precedence().get("proxy") or {})
+                .get("enforce_on_docker", True)
+            )
+        except (ImportError, OSError):
+            _enforce_egress_merge = True
+        except Exception:  # noqa: BLE001 — yaml.YAMLError or similar
+            # Malformed config.yaml; fail-safe to enforced.
+            _enforce_egress_merge = True
+
+        if _enforce_egress_merge and egress_env_overrides:
+            merged_env = dict(self._env)
+            merged_env.update(egress_env_overrides)
+        else:
+            merged_env = dict(egress_env_overrides)
+            merged_env.update(self._env)
+
+        # arshkumarsingh #1: NODE_OPTIONS append-merge.  The egress path
+        # wants ``--use-openssl-ca`` so Node routes through the OpenSSL
+        # CA store ``SSL_CERT_FILE`` controls.  But the operator's
+        # ``docker_env: {NODE_OPTIONS: "--max-old-space-size=8192"}``
+        # MUST be preserved — replacing it would silently drop their
+        # tuning.  We carry the egress flag in a sentinel key
+        # ``_HERMES_EGRESS_NODE_OPTIONS_APPEND`` and merge here.
+        _egress_node_append = merged_env.pop(
+            "_HERMES_EGRESS_NODE_OPTIONS_APPEND", None,
+        )
+        if _egress_node_append:
+            existing_node = merged_env.get("NODE_OPTIONS", "")
+            existing_tokens = existing_node.split()
+            # maxpetrusenko P1: dedupe is not enough — the operator may have set
+            # a CONFLICTING CA-mode flag (e.g. --use-bundled-ca) that would
+            # otherwise survive alongside our --use-openssl-ca, leaving Node's
+            # final trust behavior dependent on option order / Node parsing.
+            # Egress isolation requires our flag to win deterministically, so
+            # strip any known-conflicting CA-mode flags before appending.
+            _CA_MODE_FLAGS = {"--use-openssl-ca", "--use-bundled-ca"}
+            append_token = _egress_node_append.strip()
+            if append_token in _CA_MODE_FLAGS:
+                dropped = [t for t in existing_tokens if t in _CA_MODE_FLAGS and t != append_token]
+                if dropped:
+                    logger.warning(
+                        "Overriding conflicting NODE_OPTIONS CA-mode flag(s) %s "
+                        "with egress-required %s to keep Node routed through the "
+                        "egress CA store.", dropped, append_token,
+                    )
+                existing_tokens = [t for t in existing_tokens if t not in _CA_MODE_FLAGS or t == append_token]
+            # De-dup: only add if not already present (the operator may
+            # have set the same flag themselves).
+            if append_token not in existing_tokens:
+                existing_tokens.append(append_token)
+            merged_env["NODE_OPTIONS"] = " ".join(existing_tokens).strip()
+            if not merged_env["NODE_OPTIONS"]:
+                merged_env.pop("NODE_OPTIONS", None)
+
         env_args = []
-        for key in sorted(self._env):
-            env_args.extend(["-e", f"{key}={self._env[key]}"])
+        for key in sorted(merged_env):
+            env_args.extend(["-e", f"{key}={merged_env[key]}"])
 
         # Optional: run the container as the host user so files written into
         # bind-mounted dirs (/workspace, /root, docker_volumes entries) are
@@ -842,12 +1269,31 @@ class DockerEnvironment(BaseEnvironment):
                 logger.warning("Ignoring non-string docker_extra_args entry: %r", arg)
                 continue
             validated_extra.append(arg)
+        if egress_env_overrides:
+            _extra_collisions = _extra_args_egress_collisions(
+                validated_extra, _critical_egress_names,
+            )
+            if _extra_collisions:
+                _msg = (
+                    f"docker_extra_args would override egress-proxy controls "
+                    f"{_extra_collisions}; enforce_on_docker is "
+                    f"{'enabled' if _enforce_egress else 'disabled'}."
+                )
+                if _enforce_egress:
+                    raise RuntimeError(
+                        f"{_msg}  Remove these args or disable enforce_on_docker "
+                        "to opt out of egress isolation."
+                    )
+                logger.warning(
+                    "%s  Extra Docker args may bypass egress isolation.", _msg,
+                )
 
         all_run_args = (
             security_args
             + user_args
             + writable_args
             + resource_args
+            + egress_host_args
             + volume_args
             + env_args
             + validated_extra
@@ -869,6 +1315,7 @@ class DockerEnvironment(BaseEnvironment):
             "--label", "hermes-agent=1",
             "--label", f"hermes-task-id={task_label}",
             "--label", f"hermes-profile={profile_name}",
+            "--label", f"{_EGRESS_LABEL_KEY}={egress_label}",
         ]
         # Save args for container recreation on "No such container" recovery.
         self._image = image
@@ -880,6 +1327,7 @@ class DockerEnvironment(BaseEnvironment):
             "hermes-agent": "1",
             "hermes-task-id": task_label,
             "hermes-profile": profile_name,
+            _EGRESS_LABEL_KEY: egress_label,
         }
 
         # Cross-process container reuse (issue #20561 — docs claim "ONE long-lived
@@ -889,14 +1337,15 @@ class DockerEnvironment(BaseEnvironment):
         # restores the documented contract; opt out via
         # ``terminal.docker_persist_across_processes: false``.
         #
-        # Reuse matches on labels only — we deliberately do NOT compare image
-        # / mounts / resources.  Operators who need a fresh container after
-        # changing those settings should set ``docker_persist_across_processes:
-        # false`` (or run ``docker rm -f`` against the labeled container) to
-        # force a clean start.
+        # Reuse matches on labels only.  The egress posture gets its own label
+        # because env vars, CA mounts, and host mappings are immutable after
+        # container creation — reusing a pre-egress or pre-rotation container
+        # would silently bypass the credential firewall.
         reused = False
         if persist_across_processes:
-            existing = self._find_reusable_container(task_label, profile_name)
+            existing = self._find_reusable_container(
+                task_label, profile_name, egress_label,
+            )
             if existing is not None:
                 container_id, state = existing
                 # Network-mode guard: reuse must not silently defeat an
@@ -928,7 +1377,7 @@ class DockerEnvironment(BaseEnvironment):
                         subprocess.run(
                             [self._docker_exe, "rm", "-f", container_id],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding="utf-8", errors="replace",
                             timeout=30,
                             check=False,
                             stdin=subprocess.DEVNULL,
@@ -944,7 +1393,7 @@ class DockerEnvironment(BaseEnvironment):
                         subprocess.run(
                             [self._docker_exe, "start", container_id],
                             capture_output=True,
-                            text=True,
+                            text=True, encoding='utf-8', errors='replace',
                             timeout=30,
                             check=True,
                             stdin=subprocess.DEVNULL,
@@ -983,7 +1432,7 @@ class DockerEnvironment(BaseEnvironment):
                 result = subprocess.run(
                     run_cmd,
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                     timeout=120,  # image pull may take a while
                     check=True,
                     stdin=subprocess.DEVNULL,
@@ -1108,7 +1557,9 @@ class DockerEnvironment(BaseEnvironment):
         # 1. Try label-based reuse (another process may have recreated it).
         task_label = self._labels.get("hermes-task-id", "")
         profile_label = self._labels.get("hermes-profile", "")
-        existing = self._find_reusable_container(task_label, profile_label)
+        existing = self._find_reusable_container(
+            task_label, profile_label, self._labels.get(_EGRESS_LABEL_KEY, "off"),
+        )
         if existing is not None:
             cid, state = existing
             if state == "running":
@@ -1118,7 +1569,7 @@ class DockerEnvironment(BaseEnvironment):
                 try:
                     subprocess.run(
                         [self._docker_exe, "start", cid],
-                        capture_output=True, text=True, timeout=30, check=True,
+                        capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=30, check=True,
                         stdin=subprocess.DEVNULL,
                     )
                     self._container_id = cid
@@ -1149,7 +1600,7 @@ class DockerEnvironment(BaseEnvironment):
                     "sleep", "infinity",
                 ]
                 result = subprocess.run(
-                    run_cmd, capture_output=True, text=True, timeout=120, check=True,
+                    run_cmd, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=120, check=True,
                     stdin=subprocess.DEVNULL,
                 )
                 self._container_id = result.stdout.strip()
@@ -1204,7 +1655,7 @@ class DockerEnvironment(BaseEnvironment):
             docker = find_docker() or "docker"
             result = subprocess.run(
                 [docker, "info", "--format", "{{.Driver}}"],
-                capture_output=True, text=True, timeout=10,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=10,
                 stdin=subprocess.DEVNULL,
             )
             driver = result.stdout.strip().lower()
@@ -1215,7 +1666,7 @@ class DockerEnvironment(BaseEnvironment):
             # Probe by attempting a dry-ish run — the fastest reliable check.
             probe = subprocess.run(
                 [docker, "create", "--storage-opt", "size=1m", "hello-world"],
-                capture_output=True, text=True, timeout=15,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=15,
                 stdin=subprocess.DEVNULL,
             )
             if probe.returncode == 0:
@@ -1250,7 +1701,7 @@ class DockerEnvironment(BaseEnvironment):
                     container_id,
                 ],
                 capture_output=True,
-                text=True,
+                text=True, encoding="utf-8", errors="replace",
                 timeout=10,
                 check=False,
                 stdin=subprocess.DEVNULL,
@@ -1267,7 +1718,12 @@ class DockerEnvironment(BaseEnvironment):
         mode = result.stdout.strip()
         return mode or None
 
-    def _find_reusable_container(self, task_label: str, profile_label: str) -> Optional[tuple[str, str]]:
+    def _find_reusable_container(
+        self,
+        task_label: str,
+        profile_label: str,
+        egress_label: str,
+    ) -> Optional[tuple[str, str]]:
         """Look for an existing container labeled for this (task, profile).
 
         Returns ``(container_id, state)`` on hit, ``None`` on miss / on any
@@ -1281,16 +1737,31 @@ class DockerEnvironment(BaseEnvironment):
         started by some other tool.
         """
         try:
+            filters = [
+                "--filter", "label=hermes-agent=1",
+                "--filter", f"label=hermes-task-id={task_label}",
+                "--filter", f"label=hermes-profile={profile_label}",
+            ]
+            if egress_label != "off":
+                filters.extend(["--filter", f"label={_EGRESS_LABEL_KEY}={egress_label}"])
+                fmt = "{{.ID}}\t{{.State}}"
+            else:
+                # When egress is off, we widen the probe to find any
+                # task+profile container (regardless of egress label), then
+                # post-filter in Python: reject containers whose
+                # hermes-egress label is present and not "off".  Without
+                # this, a container created with egress=on can be silently
+                # reused after the operator runs "hermes egress disable",
+                # preserving baked-in proxy env and CA mounts.
+                fmt = '{{.ID}}\t{{.State}}\t{{.Label "' + _EGRESS_LABEL_KEY + '"}}'
             result = subprocess.run(
                 [
                     self._docker_exe, "ps", "-a",
-                    "--filter", "label=hermes-agent=1",
-                    "--filter", f"label=hermes-task-id={task_label}",
-                    "--filter", f"label=hermes-profile={profile_label}",
-                    "--format", "{{.ID}}\t{{.State}}",
+                    *filters,
+                    "--format", fmt,
                 ],
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=10,
                 check=False,
                 stdin=subprocess.DEVNULL,
@@ -1304,7 +1775,7 @@ class DockerEnvironment(BaseEnvironment):
                 result.returncode, result.stderr.strip(),
             )
             return None
-        lines = [ln.strip() for ln in result.stdout.splitlines() if ln.strip()]
+        lines = [ln for ln in result.stdout.splitlines() if ln.strip()]
         if not lines:
             return None
         # Multiple matches are unusual (one (task, profile) should produce one
@@ -1315,10 +1786,24 @@ class DockerEnvironment(BaseEnvironment):
         running = None
         first = None
         for ln in lines:
-            parts = ln.split("\t", 1)
-            if len(parts) != 2:
-                continue
-            cid, state = parts[0], parts[1].lower()
+            if egress_label == "off":
+                # Format: ID\tState\tEgressLabel — parse all three fields
+                # and reject containers with a non-off egress label.
+                parts = ln.split("\t", 2)
+                if len(parts) < 3:
+                    continue
+                cid, state, egress_val = parts[0], parts[1].lower(), parts[2]
+                if egress_val not in ("", "<no value>", "off"):
+                    logger.debug(
+                        "skipping container %s for egress=off reuse: "
+                        "label %s=%r", cid, _EGRESS_LABEL_KEY, egress_val,
+                    )
+                    continue
+            else:
+                parts = ln.split("\t", 1)
+                if len(parts) != 2:
+                    continue
+                cid, state = parts[0], parts[1].lower()
             if first is None:
                 first = (cid, state)
             if state == "running" and running is None:
diff --git a/tools/environments/local.py b/tools/environments/local.py
index cce93c20b67..673d8a3345e 100644
--- a/tools/environments/local.py
+++ b/tools/environments/local.py
@@ -764,7 +764,7 @@ def _mandatory_aslr_enabled() -> "bool | None":
                 "(Get-ProcessMitigation -System).Aslr.ForceRelocateImages.ToString()",
             ],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=10,
             creationflags=windows_hide_flags(),
         )
@@ -830,7 +830,7 @@ def _bash_starts(bash: str) -> bool:
         result = subprocess.run(
             [bash, "--noprofile", "--norc", "-c", _BASH_EXTERNAL_PROGRAM_PROBE],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=15,
             creationflags=windows_hide_flags() if _IS_WINDOWS else 0,
         )
diff --git a/tools/environments/singularity.py b/tools/environments/singularity.py
index 666d908b256..169937096bd 100644
--- a/tools/environments/singularity.py
+++ b/tools/environments/singularity.py
@@ -45,7 +45,7 @@ def _ensure_singularity_available() -> str:
     exe = _find_singularity_executable()
     try:
         result = subprocess.run(
-            [exe, "version"], capture_output=True, text=True, timeout=10,
+            [exe, "version"], capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=10,
             stdin=subprocess.DEVNULL,
         )
     except FileNotFoundError:
@@ -136,7 +136,7 @@ def _get_or_build_sif(image: str, executable: str = "apptainer") -> str:
         try:
             result = subprocess.run(
                 [executable, "build", str(sif_path), image],
-                capture_output=True, text=True, timeout=600, env=env,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=600, env=env,
                 stdin=subprocess.DEVNULL,
             )
             if result.returncode != 0:
@@ -220,7 +220,7 @@ class SingularityEnvironment(BaseEnvironment):
         cmd.extend([str(self.image), self.instance_id])
 
         try:
-            result = subprocess.run(cmd, capture_output=True, text=True, timeout=120, stdin=subprocess.DEVNULL)
+            result = subprocess.run(cmd, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=120, stdin=subprocess.DEVNULL)
             if result.returncode != 0:
                 raise RuntimeError(f"Failed to start instance: {result.stderr}")
             self._instance_started = True
@@ -251,7 +251,7 @@ class SingularityEnvironment(BaseEnvironment):
             try:
                 subprocess.run(
                     [self.executable, "instance", "stop", self.instance_id],
-                    capture_output=True, text=True, timeout=30,
+                    capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=30,
                     stdin=subprocess.DEVNULL,
                 )
                 logger.info("Singularity instance %s stopped", self.instance_id)
diff --git a/tools/environments/ssh.py b/tools/environments/ssh.py
index 1a06ad9b82c..f3e4d5561df 100644
--- a/tools/environments/ssh.py
+++ b/tools/environments/ssh.py
@@ -104,7 +104,7 @@ class SSHEnvironment(BaseEnvironment):
             result = subprocess.run(
                 cmd,
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=15,
                 stdin=subprocess.DEVNULL,
             )
@@ -122,7 +122,7 @@ class SSHEnvironment(BaseEnvironment):
             result = subprocess.run(
                 cmd,
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=10,
                 stdin=subprocess.DEVNULL,
             )
@@ -149,7 +149,7 @@ class SSHEnvironment(BaseEnvironment):
         subprocess.run(
             cmd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
             stdin=subprocess.DEVNULL,
         )
@@ -164,7 +164,7 @@ class SSHEnvironment(BaseEnvironment):
         subprocess.run(
             mkdir_cmd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
             stdin=subprocess.DEVNULL,
         )
@@ -178,7 +178,7 @@ class SSHEnvironment(BaseEnvironment):
         result = subprocess.run(
             scp_cmd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=30,
             stdin=subprocess.DEVNULL,
         )
@@ -207,7 +207,7 @@ class SSHEnvironment(BaseEnvironment):
             result = subprocess.run(
                 cmd,
                 capture_output=True,
-                text=True,
+                text=True, encoding='utf-8', errors='replace',
                 timeout=30,
                 stdin=subprocess.DEVNULL,
             )
@@ -325,7 +325,7 @@ class SSHEnvironment(BaseEnvironment):
         result = subprocess.run(
             cmd,
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=10,
             stdin=subprocess.DEVNULL,
         )
diff --git a/tools/lazy_deps.py b/tools/lazy_deps.py
index ec5692ecd55..1c119aabca5 100644
--- a/tools/lazy_deps.py
+++ b/tools/lazy_deps.py
@@ -79,6 +79,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Optional
 
+from hermes_cli._subprocess_compat import windows_hide_flags
+
 logger = logging.getLogger(__name__)
 
 
@@ -666,8 +668,9 @@ def _venv_pip_install(specs: tuple[str, ...], *, timeout: int = 300) -> _Install
             try:
                 r = subprocess.run(
                     [uv_bin, "pip", "install", *target_args, *constraint_args, *specs],
-                    capture_output=True, text=True, timeout=timeout, env=uv_env,
+                    capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=timeout, env=uv_env,
                     stdin=subprocess.DEVNULL,
+                    creationflags=windows_hide_flags(),
                 )
                 if r.returncode == 0:
                     if target is not None:
@@ -682,8 +685,9 @@ def _venv_pip_install(specs: tuple[str, ...], *, timeout: int = 300) -> _Install
         try:
             probe = subprocess.run(
                 pip_cmd + ["--version"],
-                capture_output=True, text=True, timeout=15,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=15,
                 stdin=subprocess.DEVNULL,
+                creationflags=windows_hide_flags(),
             )
             if probe.returncode != 0:
                 raise FileNotFoundError("pip not in venv")
@@ -691,8 +695,9 @@ def _venv_pip_install(specs: tuple[str, ...], *, timeout: int = 300) -> _Install
             try:
                 subprocess.run(
                     [sys.executable, "-m", "ensurepip", "--upgrade", "--default-pip"],
-                    capture_output=True, text=True, timeout=120, check=True,
+                    capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=120, check=True,
                     stdin=subprocess.DEVNULL,
+                    creationflags=windows_hide_flags(),
                 )
             except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
                 return _InstallResult(False, "",
@@ -701,8 +706,9 @@ def _venv_pip_install(specs: tuple[str, ...], *, timeout: int = 300) -> _Install
         try:
             r = subprocess.run(
                 pip_cmd + ["install", *target_args, *constraint_args, *specs],
-                capture_output=True, text=True, timeout=timeout,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=timeout,
                 stdin=subprocess.DEVNULL,
+                creationflags=windows_hide_flags(),
             )
             if r.returncode == 0 and target is not None:
                 _activate_target_on_syspath(target)
diff --git a/tools/managed_tool_gateway.py b/tools/managed_tool_gateway.py
index d894dcb4b29..2bbc9dcff16 100644
--- a/tools/managed_tool_gateway.py
+++ b/tools/managed_tool_gateway.py
@@ -37,7 +37,7 @@ def _read_nous_provider_state() -> Optional[dict]:
         path = auth_json_path()
         if not path.is_file():
             return None
-        data = json.loads(path.read_text())
+        data = json.loads(path.read_text(encoding="utf-8"))
         providers = data.get("providers", {})
         if not isinstance(providers, dict):
             return None
diff --git a/tools/mcp_tool.py b/tools/mcp_tool.py
index 7d18ceb1525..28dd5e91741 100644
--- a/tools/mcp_tool.py
+++ b/tools/mcp_tool.py
@@ -93,6 +93,7 @@ import asyncio
 import contextvars
 import concurrent.futures
 import errno
+import fnmatch
 import inspect
 import json
 import logging
@@ -2411,6 +2412,10 @@ class MCPServerTask:
             command=command,
             args=args,
             env=safe_env if safe_env else None,
+            # On Windows, pipe I/O can deliver non-UTF-8 bytes at chunk
+            # boundaries.  Use "replace" to substitute undecodable bytes
+            # with U+FFFD instead of crashing with UnicodeDecodeError.
+            encoding_error_handler="replace",
         )
 
         sampling_kwargs = self._sampling.session_kwargs() if self._sampling else {}
@@ -5303,7 +5308,12 @@ def _build_utility_schemas(server_name: str) -> List[dict]:
 
 
 def _normalize_name_filter(value: Any, label: str) -> set[str]:
-    """Normalize include/exclude config to a set of tool names."""
+    """Normalize include/exclude config to a set of tool-name patterns.
+
+    Entries may be exact tool names or fnmatch-style globs
+    (``*_radar_*``, ``get_zones_*``). Matching happens in
+    :func:`matches_name_filter`.
+    """
     if value is None:
         return set()
     if isinstance(value, str):
@@ -5314,6 +5324,25 @@ def _normalize_name_filter(value: Any, label: str) -> set[str]:
     return set()
 
 
+def matches_name_filter(tool_name: str, patterns: set[str]) -> bool:
+    """True if ``tool_name`` matches any entry in ``patterns``.
+
+    Exact names match literally; entries containing fnmatch metacharacters
+    (``*``, ``?``, ``[``) match as case-sensitive globs — the same pattern
+    semantics as ``approvals.deny``. Exact membership is checked first so
+    large literal lists stay O(1).
+    """
+    if not patterns:
+        return False
+    if tool_name in patterns:
+        return True
+    return any(
+        fnmatch.fnmatchcase(tool_name, p)
+        for p in patterns
+        if "*" in p or "?" in p or "[" in p
+    )
+
+
 def _parse_boolish(value: Any, default: bool = True) -> bool:
     """Parse a bool-like config value with safe fallback."""
     if value is None:
@@ -5477,9 +5506,10 @@ def _register_server_tools(name: str, server: MCPServerTask, config: dict) -> Li
     toolset_name = f"mcp-{name}"
 
     # Selective tool loading: honour include/exclude lists from config.
-    # Rules (matching issue #690 spec):
-    #   tools.include — whitelist: only these tool names are registered
-    #   tools.exclude — blacklist: all tools EXCEPT these are registered
+    # Rules (matching issue #690 spec, extended with glob support):
+    #   tools.include — whitelist: only matching tool names are registered
+    #   tools.exclude — blacklist: all tools EXCEPT matching ones are registered
+    #   entries may be exact names or fnmatch globs (e.g. "*_radar_*")
     #   include takes precedence over exclude
     #   Neither set → register all tools (backward-compatible default)
     tools_filter = config.get("tools") or {}
@@ -5488,9 +5518,9 @@ def _register_server_tools(name: str, server: MCPServerTask, config: dict) -> Li
 
     def _should_register(tool_name: str) -> bool:
         if include_set:
-            return tool_name in include_set
+            return matches_name_filter(tool_name, include_set)
         if exclude_set:
-            return tool_name not in exclude_set
+            return not matches_name_filter(tool_name, exclude_set)
         return True
 
     for mcp_tool in server._tools:
@@ -6134,9 +6164,13 @@ def _reinject_post_build_tools(agent, tools_list: list, name_set: set) -> set:
         memory_manager = getattr(agent, "_memory_manager", None)
         get_mem_schemas = getattr(memory_manager, "get_all_tool_schemas", None) if memory_manager else None
         if callable(get_mem_schemas):
-            # Honor the same enablement gate inject_memory_provider_tools uses.
+            # Honor the same toolset gate inject_memory_provider_tools uses.
             from agent.memory_manager import memory_provider_tools_enabled
-            if "memory" in name_set or memory_provider_tools_enabled(getattr(agent, "enabled_toolsets", None)):
+            if memory_provider_tools_enabled(
+                getattr(agent, "enabled_toolsets", None),
+                getattr(agent, "disabled_toolsets", None),
+                memory_tool_present="memory" in name_set,
+            ):
                 for schema in get_mem_schemas():
                     if isinstance(schema, dict):
                         _add(schema)
diff --git a/tools/memory_tool.py b/tools/memory_tool.py
index f5b866b80ac..463b6b5149c 100644
--- a/tools/memory_tool.py
+++ b/tools/memory_tool.py
@@ -31,7 +31,7 @@ import time
 from contextlib import contextmanager
 from pathlib import Path
 from hermes_constants import get_hermes_home
-from typing import Dict, Any, List, Optional
+from typing import Dict, Any, List, Optional, Tuple
 
 from utils import atomic_replace
 
@@ -120,6 +120,33 @@ def _drift_error(path: "Path", bak_path: str) -> Dict[str, Any]:
     }
 
 
+# Sentinel returned by ``_reload_target`` when the target file EXISTS but could
+# not be read. Distinct from a drift-backup path (``str``) and from a clean
+# reload (``None``): the caller must abort the mutation rather than persist over
+# an unreadable file.
+_READ_FAILED = object()
+
+
+def _read_failed_error(path: "Path") -> Dict[str, Any]:
+    """Build the error dict returned when the on-disk memory file is unreadable.
+
+    A file that exists but cannot be read is NOT an empty store. Reading it as
+    ``[]`` and then persisting would rewrite the whole file from an empty entry
+    list — wiping the user's memory. We refuse the write so nothing is lost.
+    """
+    return {
+        "success": False,
+        "error": (
+            f"Refusing to write {path.name}: the file exists on disk but could "
+            f"not be read right now (temporarily locked by another program, a "
+            f"permission change, invalid/corrupt text encoding, or a filesystem "
+            f"error). Treating an unreadable file as empty and saving would wipe "
+            f"existing memory, so the write is refused. Nothing was changed — "
+            f"retry in a moment."
+        ),
+    }
+
+
 class MemoryStore:
     """
     Bounded curated memory with file persistence. One instance per AIAgent.
@@ -294,7 +321,7 @@ class MemoryStore:
             return mem_dir / "USER.md"
         return mem_dir / "MEMORY.md"
 
-    def _reload_target(self, target: str, *, skip_drift: bool = False) -> Optional[str]:
+    def _reload_target(self, target: str, *, skip_drift: bool = False):
         """Re-read entries from disk into in-memory state.
 
         Called under file lock to get the latest state before mutating.
@@ -303,15 +330,34 @@ class MemoryStore:
         parser/serializer, OR an entry larger than the store's char limit).
         When drift is detected the caller must abort the mutation —
         flushing would discard the un-roundtrippable content.
-        Returns None on clean reload.
+        Returns ``None`` on clean reload.
+
+        Returns the ``_READ_FAILED`` sentinel when the file EXISTS but could not
+        be read. The caller MUST abort: the on-disk entries are unknown, so
+        overwriting from an assumed-empty view would wipe them. This is the real
+        exposure behind ``add`` — it skips the drift guard because appending is
+        safe, but that reasoning only holds when the reload actually saw the
+        file. A failed read reported as ``[]`` turned ``add`` into a full-file
+        rewrite down to a single entry.
 
         When *skip_drift* is True the round-trip / entry-size check is
         bypassed.  Used by the ``add`` action which appends without
         rewriting, so existing content is never clobbered.
         """
         path = self._path_for(target)
-        bak = None if skip_drift else self._detect_external_drift(target)
-        fresh = self._read_file(path)
+        raw, read_ok = self._read_raw_checked(path)
+        if not read_ok:
+            # Leave in-memory entries untouched and tell the caller to abort;
+            # persisting over an unreadable file would destroy it.
+            return _READ_FAILED
+        # Derive BOTH the drift check and the entry parse from the same raw
+        # snapshot. The drift guard used to re-read the file itself and treat
+        # a failed second read as "no drift" — so a read failure between the
+        # checked reload and the drift check let replace/remove/apply_batch
+        # rewrite the file from a stale view, silently discarding whatever an
+        # external writer had just added. One read, one snapshot, no window.
+        bak = None if skip_drift else self._detect_external_drift(target, raw)
+        fresh = self._parse_entries(raw)
         fresh = list(dict.fromkeys(fresh))  # deduplicate
         self._set_entries(target, fresh)
         return bak
@@ -361,7 +407,14 @@ class MemoryStore:
             # tool-written entries in the same session are harmless.  The drift
             # guard remains active for replace/remove where full-file rewrite
             # would discard un-roundtrippable content (issue #26045).
-            self._reload_target(target, skip_drift=True)
+            #
+            # But "append never clobbers" only holds when the reload actually
+            # read the file. add rewrites the WHOLE file from the parsed
+            # entries, so a file that exists but read as empty (transient lock,
+            # permission blip, I/O error) would be rewritten down to just the
+            # new entry — wiping every prior memory. Refuse instead.
+            if self._reload_target(target, skip_drift=True) is _READ_FAILED:
+                return _read_failed_error(self._path_for(target))
 
             entries = self._entries_for(target)
             limit = self._char_limit(target)
@@ -411,6 +464,8 @@ class MemoryStore:
 
         with self._file_lock(self._path_for(target)):
             bak = self._reload_target(target)
+            if bak is _READ_FAILED:
+                return _read_failed_error(self._path_for(target))
             if bak:
                 return _drift_error(self._path_for(target), bak)
 
@@ -472,6 +527,8 @@ class MemoryStore:
 
         with self._file_lock(self._path_for(target)):
             bak = self._reload_target(target)
+            if bak is _READ_FAILED:
+                return _read_failed_error(self._path_for(target))
             if bak:
                 return _drift_error(self._path_for(target), bak)
 
@@ -532,6 +589,8 @@ class MemoryStore:
 
         with self._file_lock(self._path_for(target)):
             bak = self._reload_target(target)
+            if bak is _READ_FAILED:
+                return _read_failed_error(self._path_for(target))
             if bak:
                 return _drift_error(self._path_for(target), bak)
 
@@ -690,30 +749,73 @@ class MemoryStore:
         return f"{separator}\n{header}\n{separator}\n{content}"
 
     @staticmethod
-    def _read_file(path: Path) -> List[str]:
-        """Read a memory file and split into entries.
+    def _read_raw_checked(path: Path) -> Tuple[str, bool]:
+        """Read a memory file's raw text, distinguishing unreadable from empty.
+
+        Returns ``(raw, read_ok)``. ``read_ok`` is False ONLY when the file
+        EXISTS but could not be read — an absent file is a clean ``("", True)``.
+        Invalid UTF-8 counts as unreadable too: the bytes on disk hold content
+        we cannot faithfully round-trip, so a rewrite would corrupt or discard
+        it just like a failed read. Read-modify-write callers must treat
+        ``read_ok=False`` as "abort" rather than "empty store", or a transient
+        read failure would let them persist over — and wipe — the on-disk
+        memory (issue #26045 is about the same class: never rewrite a file
+        from a view that isn't the real one).
 
         No file locking needed: _write_file uses atomic rename, so readers
         always see either the previous complete file or the new complete file.
         """
         if not path.exists():
-            return []
+            return "", True
         try:
-            raw = path.read_text(encoding="utf-8")
-        except (OSError, IOError):
-            return []
+            return path.read_text(encoding="utf-8"), True
+        except (OSError, IOError, UnicodeDecodeError):
+            return "", False
 
+    @staticmethod
+    def _parse_entries(raw: str) -> List[str]:
+        """Split raw memory-file text into stripped, non-empty entries."""
         if not raw.strip():
             return []
-
         # Use ENTRY_DELIMITER for consistency with _write_file. Splitting by "§"
         # alone would incorrectly split entries that contain "§" in their content.
         entries = [e.strip() for e in raw.split(ENTRY_DELIMITER)]
         return [e for e in entries if e]
 
-    def _detect_external_drift(self, target: str) -> Optional[str]:
+    @staticmethod
+    def _read_entries_checked(path: Path) -> Tuple[List[str], bool]:
+        """Read + parse a memory file, distinguishing unreadable from empty.
+
+        Returns ``(entries, read_ok)`` — see ``_read_raw_checked`` for the
+        ``read_ok`` contract.
+        """
+        raw, read_ok = MemoryStore._read_raw_checked(path)
+        if not read_ok:
+            return [], False
+        return MemoryStore._parse_entries(raw), True
+
+    @staticmethod
+    def _read_file(path: Path) -> List[str]:
+        """Read a memory file and split into entries (empty list on any error).
+
+        Retained for read-only callers (``load_from_disk``) that build in-memory
+        state without persisting; a failed read degrading to ``[]`` there is
+        harmless because nothing is written back. Read-modify-write paths use
+        ``_read_raw_checked`` so they can refuse to overwrite an unreadable
+        file — see ``_reload_target``.
+        """
+        return MemoryStore._read_entries_checked(path)[0]
+
+    def _detect_external_drift(self, target: str, raw: str) -> Optional[str]:
         """Return a backup-path string if on-disk content shows external drift.
 
+        *raw* is the file content already read by the caller's checked read
+        (``_read_raw_checked``). Drift detection MUST operate on that same
+        snapshot — an earlier version re-read the file here and treated a
+        failed second read as "no drift", which let a mutation proceed from a
+        stale first snapshot and rewrite away content an external writer added
+        between the two reads.
+
         The memory file is supposed to be a list of small entries the tool
         wrote, joined by §. Detect drift via two signals:
 
@@ -736,12 +838,6 @@ class MemoryStore:
         per-target char_limit for signal #2.
         """
         path = self._path_for(target)
-        if not path.exists():
-            return None
-        try:
-            raw = path.read_text(encoding="utf-8")
-        except (OSError, IOError):
-            return None
         if not raw.strip():
             return None
 
diff --git a/tools/process_registry.py b/tools/process_registry.py
index 97cf89b3bda..7daf74b2e33 100644
--- a/tools/process_registry.py
+++ b/tools/process_registry.py
@@ -600,7 +600,7 @@ class ProcessRegistry:
                 subprocess.run(
                     ["taskkill", "/PID", str(pid), "/T", "/F"],
                     capture_output=True,
-                    text=True,
+                    text=True, encoding='utf-8', errors='replace',
                     timeout=10,
                     creationflags=windows_hide_flags(),
                     stdin=subprocess.DEVNULL,
@@ -705,6 +705,15 @@ class ProcessRegistry:
                      CLI tools (Codex, Claude Code, Python REPL). Falls back to
                      subprocess.Popen if ptyprocess is not installed.
         """
+        # Guard against the `A && B &` subshell-wait trap (issue #68915).
+        # Bash parses ``A && B &`` as ``(A && B) &`` — a subshell that holds
+        # the stdout pipe open forever when B is a long-running server.
+        # The rewriter wraps it to ``A && { B & }`` so no subshell fork.
+        # Lazy import avoids circular dependency (terminal_tool imports this).
+        from tools.terminal_tool import _rewrite_compound_background as _rewrite_bg
+
+        safe_command = _rewrite_bg(command)
+
         session = ProcessSession(
             id=f"proc_{uuid.uuid4().hex[:12]}",
             command=command,
@@ -725,7 +734,7 @@ class ProcessRegistry:
                 pty_env = _sanitize_subprocess_env(os.environ, env_vars)
                 pty_env["PYTHONUNBUFFERED"] = "1"
                 pty_proc = _PtyProcessCls.spawn(
-                    [user_shell, "-lic", f"set +m; {command}"],
+                    [user_shell, "-lic", f"set +m; {safe_command}"],
                     cwd=session.cwd,
                     env=pty_env,
                     dimensions=(30, 120),
@@ -769,7 +778,7 @@ class ProcessRegistry:
         _popen_kwargs = {"creationflags": windows_hide_flags()} if _IS_WINDOWS else {}
 
         proc = subprocess.Popen(
-            [user_shell, "-lic", f"set +m; {command}"],
+            [user_shell, "-lic", f"set +m; {safe_command}"],
             text=True,
             cwd=session.cwd,
             env=bg_env,
@@ -934,36 +943,96 @@ class ProcessRegistry:
         block until EOF (or a large buffer fills), which makes "live" output land
         in one burst at process exit. ``buffer.read1(4096)`` yields incremental
         chunks as bytes become available, then we decode to text.
+
+        Orphaned-pipe guard (issue #68915): when the user's command backgrounds
+        a long-lived process (``node server.js &``, ``sleep 300 &``), that
+        grandchild inherits the write end of our stdout pipe via ``fork()``.
+        The direct ``bash`` child exits promptly, but the pipe never reaches
+        EOF while the grandchild lives — so a blocking read would park this
+        thread forever, ``session.exited`` would never flip, and
+        ``notify_on_complete`` would never fire (``_reconcile_local_exit``
+        only runs lazily from poll()/wait(), which an autonomous notification
+        can't rely on). On POSIX we therefore ``select()`` with a short poll
+        interval and stop draining shortly after the direct child exits, even
+        if the pipe hasn't EOF'd — mirroring the foreground fix in
+        ``tools/environments/base.py::_wait_for_process`` (#8340). Windows
+        pipes don't support select(); the blocking path is kept there and the
+        lazy reconcile in poll()/wait() remains the safety net.
         """
         first_chunk = True
+
+        def _append_chunk(chunk: str):
+            nonlocal first_chunk
+            if first_chunk:
+                chunk = self._clean_shell_noise(chunk)
+                first_chunk = False
+            with session._lock:
+                session.output_buffer += chunk
+                if len(session.output_buffer) > session.max_output_chars:
+                    session.output_buffer = session.output_buffer[-session.max_output_chars:]
+            self._check_watch_patterns(session, chunk)
+            self._emit_output(session, chunk)
+
         try:
-            stdout = session.process.stdout
-            if stdout is None:
+            proc = session.process
+            if proc is None or proc.stdout is None:
                 return
+            stdout = proc.stdout
 
             raw_read = getattr(getattr(stdout, "buffer", None), "read1", None)
-            while True:
-                if raw_read is not None:
-                    raw = raw_read(4096)
-                    if not raw:
-                        break
-                    chunk = raw.decode("utf-8", errors="replace")
-                else:
-                    # Fallback for mocked/alternate streams without a buffered raw
-                    # interface. This may be less "live", but keeps compatibility.
-                    chunk = stdout.read(4096)
-                    if not chunk:
-                        break
 
-                if first_chunk:
-                    chunk = self._clean_shell_noise(chunk)
-                    first_chunk = False
-                with session._lock:
-                    session.output_buffer += chunk
-                    if len(session.output_buffer) > session.max_output_chars:
-                        session.output_buffer = session.output_buffer[-session.max_output_chars:]
-                self._check_watch_patterns(session, chunk)
-                self._emit_output(session, chunk)
+            # Resolve a real OS fd for the select() path. Mocked streams
+            # (unit tests, adapters) may lack fileno() — fall back to the
+            # historical blocking loop for those.
+            fd = None
+            if raw_read is not None and not _IS_WINDOWS:
+                fileno = getattr(stdout, "fileno", None)
+                try:
+                    candidate = fileno() if callable(fileno) else None
+                except Exception:
+                    candidate = None
+                if isinstance(candidate, int) and candidate >= 0:
+                    fd = candidate
+
+            if fd is not None:
+                import select as _select
+
+                idle_after_exit = 0
+                while True:
+                    try:
+                        ready, _, _ = _select.select([fd], [], [], 0.2)
+                    except (ValueError, OSError):
+                        break  # fd already closed
+                    if ready:
+                        raw = raw_read(4096)
+                        if not raw:
+                            break  # true EOF — all writers closed
+                        _append_chunk(raw.decode("utf-8", errors="replace"))
+                        idle_after_exit = 0
+                    elif proc.poll() is not None:
+                        # Direct child is gone and the pipe was idle for
+                        # ~200ms. Give it a few more cycles to catch any
+                        # buffered tail, then stop — otherwise we would wait
+                        # forever on a pipe held open by an orphaned
+                        # grandchild (issue #68915).
+                        idle_after_exit += 1
+                        if idle_after_exit >= 3:
+                            break
+            else:
+                while True:
+                    if raw_read is not None:
+                        raw = raw_read(4096)
+                        if not raw:
+                            break
+                        chunk = raw.decode("utf-8", errors="replace")
+                    else:
+                        # Fallback for mocked/alternate streams without a buffered raw
+                        # interface. This may be less "live", but keeps compatibility.
+                        chunk = stdout.read(4096)
+                        if not chunk:
+                            break
+
+                    _append_chunk(chunk)
         except Exception as e:
             logger.debug("Process stdout reader ended: %s", e)
         finally:
diff --git a/tools/schema_sanitizer.py b/tools/schema_sanitizer.py
index 9f0bc98fcd2..7dbcb1ef87f 100644
--- a/tools/schema_sanitizer.py
+++ b/tools/schema_sanitizer.py
@@ -38,11 +38,85 @@ from __future__ import annotations
 
 import copy
 import logging
+import re
 from typing import Any
 
 logger = logging.getLogger(__name__)
 
 
+# Anthropic (and Bedrock/Vertex/Azure fronting it) reject tool input schemas
+# whose property keys don't match this pattern. Cloudflare's flat API MCP
+# ships 61 such keys (query-filter params like ``issue_class~neq`` and
+# ``meta.<field>[<operator>]``) — one bad key anywhere in the tools array
+# 400s the entire request.
+_PROP_KEY_RE = re.compile(r"^[a-zA-Z0-9_.-]{1,64}$")
+_PROP_KEY_BAD_CHARS = re.compile(r"[^a-zA-Z0-9_.-]")
+
+
+def sanitize_property_key(key: str) -> str:
+    """Deterministically map an arbitrary property key to a conforming one."""
+    new = _PROP_KEY_BAD_CHARS.sub("_", key)[:64]
+    return new or "param"
+
+
+def _rename_property_keys(props: dict, path: str) -> dict[str, str]:
+    """Return {original_key: conforming_key} for one properties dict.
+
+    Identity entries are omitted. Deterministic: keys are processed in
+    insertion order and collisions deduped with numeric suffixes, so the
+    model-visible schema AND the dispatch-time reverse map (computed
+    independently from the registry's original schema) always agree.
+    """
+    renames: dict[str, str] = {}
+    taken = {k for k in props if _PROP_KEY_RE.match(k)}
+    for key in props:
+        if _PROP_KEY_RE.match(key):
+            continue
+        base = sanitize_property_key(key)
+        candidate, i = base, 2
+        while candidate in taken:
+            suffix = f"_{i}"
+            candidate = base[: 64 - len(suffix)] + suffix
+            i += 1
+        taken.add(candidate)
+        renames[key] = candidate
+        logger.debug(
+            "schema_sanitizer[%s]: renamed property key %r -> %r "
+            "(provider key-pattern compat)", path, key, candidate,
+        )
+    return renames
+
+
+def unrename_tool_args(params_schema: Any, args: Any) -> Any:
+    """Map sanitized property keys in model-emitted args back to wire names.
+
+    ``params_schema`` is the ORIGINAL (unsanitized) parameters schema from the
+    registry. Recurses into object-typed values and array items so nested
+    renamed keys are restored too. Unknown keys pass through untouched.
+    """
+    if not isinstance(params_schema, dict) or not isinstance(args, dict):
+        return args
+    props = params_schema.get("properties")
+    if not isinstance(props, dict):
+        return args
+    reverse = {v: k for k, v in _rename_property_keys(props, "<unrename>").items()}
+    out = {}
+    for key, value in args.items():
+        orig = reverse.get(key, key)
+        subschema = props.get(orig)
+        if isinstance(subschema, dict):
+            if isinstance(value, dict):
+                value = unrename_tool_args(subschema, value)
+            elif isinstance(value, list) and isinstance(subschema.get("items"), dict):
+                value = [
+                    unrename_tool_args(subschema["items"], item)
+                    if isinstance(item, dict) else item
+                    for item in value
+                ]
+        out[orig] = value
+    return out
+
+
 def sanitize_tool_schemas(tools: list[dict]) -> list[dict]:
     """Return a copy of ``tools`` with each tool's parameter schema sanitized.
 
@@ -268,6 +342,13 @@ def _sanitize_node(node: Any, path: str) -> Any:
     if not isinstance(node, dict):
         return node
 
+    # Compute property-key renames up front so the ``required`` branch below
+    # can remap regardless of dict iteration order (``required`` may precede
+    # ``properties`` in the source dict).
+    prop_renames: dict[str, str] = {}
+    if isinstance(node.get("properties"), dict):
+        prop_renames = _rename_property_keys(node["properties"], f"{path}.properties")
+
     out: dict = {}
     for key, value in node.items():
         # JSON Schema ``type`` arrays (e.g. ``["number", "string"]``, common
@@ -306,10 +387,12 @@ def _sanitize_node(node: Any, path: str) -> Any:
             continue
 
         if key in {"properties", "$defs", "definitions"} and isinstance(value, dict):
-            out[key] = {
-                sub_k: _sanitize_node(sub_v, f"{path}.{key}.{sub_k}")
-                for sub_k, sub_v in value.items()
-            }
+            renames = prop_renames if key == "properties" else {}
+            new_props = {}
+            for sub_k, sub_v in value.items():
+                out_k = renames.get(sub_k, sub_k)
+                new_props[out_k] = _sanitize_node(sub_v, f"{path}.{key}.{out_k}")
+            out[key] = new_props
         elif key in {"items", "additionalProperties"}:
             if isinstance(value, bool):
                 # Keep bool ``additionalProperties`` as-is — it's a valid form
@@ -330,8 +413,13 @@ def _sanitize_node(node: Any, path: str) -> Any:
             #  - ``examples``: list of example values (any JSON type)
             # Recursing into these with _sanitize_node() would mis-interpret
             # literal strings like "path" as bare-string schemas and replace
-            # them with {"type": "object"} dicts. Pass through unchanged.
-            out[key] = copy.deepcopy(value) if isinstance(value, (list, dict)) else value
+            # them with {"type": "object"} dicts. Pass through unchanged
+            # (remapping ``required`` entries through the property renames).
+            if key == "required" and prop_renames and isinstance(value, list):
+                out[key] = [prop_renames.get(r, r) if isinstance(r, str) else r
+                            for r in value]
+            else:
+                out[key] = copy.deepcopy(value) if isinstance(value, (list, dict)) else value
         else:
             out[key] = _sanitize_node(value, f"{path}.{key}") if isinstance(value, (dict, list)) else value
 
diff --git a/tools/session_search_tool.py b/tools/session_search_tool.py
index bc09e82511d..e305467f054 100644
--- a/tools/session_search_tool.py
+++ b/tools/session_search_tool.py
@@ -291,6 +291,28 @@ def _resolve_profile_db(profile: str):
     return SessionDB(db_path=profiles_mod.get_profile_dir(canon) / "state.db", read_only=True)
 
 
+def _session_link(session_id: str, profile: str = None) -> str:
+    """The reference the agent writes to point the user at a session.
+
+    Same value the desktop composer emits when a session is dragged into a
+    message, so the desktop renders it as a link carrying the session's title.
+    The profile segment is omitted when we can't name it confidently — a bare
+    id still resolves, it just can't disambiguate across profiles.
+    """
+    name = (profile or "").strip()
+    if not name:
+        try:
+            from hermes_cli.profiles import get_active_profile_name
+
+            resolved = get_active_profile_name()
+            name = "" if resolved == "custom" else resolved
+        except Exception:
+            logging.debug("get_active_profile_name failed for session link", exc_info=True)
+            name = ""
+
+    return f"@session:{name}/{session_id}" if name else f"@session:{session_id}"
+
+
 def _locate_session_db(session_id: str):
     """Scan every profile's ``state.db`` (read-only) for a session id.
 
@@ -335,7 +357,7 @@ def _locate_session_db(session_id: str):
     return None, None
 
 
-def _read_session(db, session_id: str, head: int = 20, tail: int = 10) -> str:
+def _read_session(db, session_id: str, head: int = 20, tail: int = 10, link_profile: str = None) -> str:
     """Read shape: dump a whole session by id (head + tail when large).
 
     Serves the linked-session case — the user dropped an @session reference and
@@ -366,6 +388,7 @@ def _read_session(db, session_id: str, head: int = 20, tail: int = 10) -> str:
         "success": True,
         "mode": "read",
         "session_id": session_id,
+        "link": _session_link(session_id, link_profile),
         "session_meta": {
             "when": _format_timestamp(meta.get("started_at")),
             "source": meta.get("source"),
@@ -384,7 +407,7 @@ def _read_session(db, session_id: str, head: int = 20, tail: int = 10) -> str:
     return json.dumps(response, ensure_ascii=False)
 
 
-def _list_recent_sessions(db, limit: int, current_session_id: str = None) -> str:
+def _list_recent_sessions(db, limit: int, current_session_id: str = None, link_profile: str = None) -> str:
     """Return metadata for the most recent sessions (no LLM calls, no FTS5)."""
     try:
         sessions = db.list_sessions_rich(
@@ -405,6 +428,7 @@ def _list_recent_sessions(db, limit: int, current_session_id: str = None) -> str
                 continue
             results.append({
                 "session_id": sid,
+                "link": _session_link(sid, link_profile),
                 "title": s.get("title") or None,
                 "source": s.get("source", ""),
                 "started_at": s.get("started_at", ""),
@@ -630,6 +654,7 @@ def _discover(
     limit: int,
     sort: Optional[str],
     current_session_id: str = None,
+    link_profile: str = None,
 ) -> str:
     """Discovery shape: FTS5 + anchored window + bookends per hit. Single call."""
     role_list = role_filter if role_filter else ["user", "assistant"]
@@ -764,6 +789,9 @@ def _discover(
             entry["parent_session_id"] = lineage_root
         results.append(entry)
 
+    for entry in results:
+        entry["link"] = _session_link(entry["session_id"], link_profile)
+
     _final_payload = {
         "success": True,
         "mode": "discover",
@@ -848,7 +876,7 @@ def session_search(
     # Read shape: a session_id with no anchor → dump the whole session.
     if isinstance(session_id, str) and session_id.strip():
         sid = session_id.strip()
-        result = _read_session(db, sid)
+        result = _read_session(db, sid, link_profile=profile)
         if json.loads(result).get("success"):
             return result
 
@@ -858,7 +886,7 @@ def session_search(
         located, owner = _locate_session_db(sid)
         if located is not None:
             try:
-                found = json.loads(_read_session(located, sid))
+                found = json.loads(_read_session(located, sid, link_profile=owner))
             finally:
                 located.close()
             if found.get("success"):
@@ -876,7 +904,7 @@ def session_search(
 
     # Browse shape: no query → recent sessions.
     if not query or not isinstance(query, str) or not query.strip():
-        return _list_recent_sessions(db, limit, current_session_id)
+        return _list_recent_sessions(db, limit, current_session_id, link_profile=profile)
 
     # Parse role_filter
     role_list: Optional[List[str]] = None
@@ -897,6 +925,7 @@ def session_search(
         limit=limit,
         sort=sort_norm,
         current_session_id=current_session_id,
+        link_profile=profile,
     )
 
 
@@ -962,6 +991,16 @@ SESSION_SEARCH_SCHEMA = {
         "     session_search()\n"
         "     Returns recent sessions chronologically: titles, previews, timestamps. "
         "Use when the user asks \"what was I working on\" without naming a topic.\n\n"
+        "LINKING THE USER TO A SESSION\n\n"
+        "  When you refer the user to a session, write its `link` value inline in "
+        "your reply — every result carries one, e.g. "
+        "`@session:default/20260722_204335_d62c16`. Copy it verbatim; do not "
+        "reformat it as a markdown link or wrap it in backticks. Hermes renders "
+        "it as a link showing the session's title, so the link IS the title: "
+        "use it as a noun mid-sentence (\"that's @session:default/... — want me "
+        "to pick it up?\"), never alone on its own line, and never alongside the "
+        "title, id, or date spelled out — that shows the user the same session "
+        "twice.\n\n"
         "FTS5 SYNTAX\n\n"
         "  AND is the default — multi-word queries require all terms. Use OR explicitly "
         "for broader recall (`alpha OR beta OR gamma`), quoted phrases for exact match "
diff --git a/tools/skill_manager_tool.py b/tools/skill_manager_tool.py
index debea52642f..2cd20bde2ea 100644
--- a/tools/skill_manager_tool.py
+++ b/tools/skill_manager_tool.py
@@ -45,6 +45,12 @@ from typing import Any, Dict, List, Optional, Tuple
 from hermes_constants import get_hermes_home, display_hermes_home
 from utils import atomic_replace, is_truthy_value
 from hermes_cli.config import cfg_get
+from agent.skill_utils import (
+    extract_skill_description,
+    is_skill_description_truncated_for_prompt,
+    parse_frontmatter as _parse_frontmatter,
+    SKILL_PROMPT_DESC_LIMIT,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -374,25 +380,46 @@ def _background_review_write_guard(
                     f"skill '{name}'."
                 ),
             }
-        # Manually authored skills (created_by != "agent") are off-limits
-        # to autonomous curation. This prevents the LLM consolidation pass
-        # from archiving skills the user placed manually (e.g. via URL
-        # install or direct SKILL.md authoring), which lack the
-        # `created_by: "agent"` marker.
+        # Skills that are not curator-managed are off-limits to autonomous
+        # curation. This prevents the LLM consolidation pass from mutating
+        # skills the user owns (manually authored, URL-installed, or created by
+        # a foreground `skill_manage(create)` at the user's request), which lack
+        # the `created_by: "agent"` marker.
+        #
+        # A MISSING record and an explicit `created_by: null` must resolve
+        # IDENTICALLY (issue #67140). Keying on `isinstance(usage_rec, dict)`
+        # made the policy depend on the guard's own side effect: a local skill
+        # with no telemetry record passed, the successful write called
+        # bump_patch() which created a `created_by: null` record, and the very
+        # same write was refused from then on. "Allowed exactly once" is not a
+        # policy — it is a race with our own bookkeeping. Fail closed for both
+        # shapes; `hermes curator adopt <name>` is the supported way in.
         usage_data = skill_usage.load_usage()
         usage_rec = usage_data.get(name)
-        if isinstance(usage_rec, dict) and not skill_usage._is_curator_managed_record(usage_rec):
+        if not skill_usage._is_curator_managed_record(usage_rec):
+            if isinstance(usage_rec, dict):
+                _detail = f"created_by={usage_rec.get('created_by')!r}"
+            else:
+                _detail = "no usage record"
             return {
                 "success": False,
                 "error": (
                     f"Refusing background curator {action} for skill "
-                    f"'{name}': the skill records show it is not agent-created "
-                    f"(created_by={usage_rec.get('created_by')!r}). Manually authored "
-                    f"skills are off-limits to autonomous curation."
+                    f"'{name}': the skill is not curator-managed ({_detail}). "
+                    "User-owned skills are off-limits to autonomous curation. "
+                    f"Run `hermes curator adopt {name}` to opt it in."
                 ),
             }
     except Exception:
-        logger.debug("owned skill guard lookup failed for %s", name, exc_info=True)
+        logger.warning("owned skill guard lookup failed for %s", name, exc_info=True)
+        return {
+            "success": False,
+            "error": (
+                f"Refusing background curator {action} for skill '{name}': "
+                "agent ownership could not be verified because the provenance "
+                "record is unavailable or unreadable."
+            ),
+        }
     return None
 
 
@@ -538,10 +565,16 @@ def _validate_category(category: Optional[str]) -> Optional[str]:
     return None
 
 
-def _validate_frontmatter(content: str) -> Optional[str]:
+def _validate_frontmatter(content: str, *, new_skill: bool = False) -> Optional[str]:
     """
     Validate that SKILL.md content has proper frontmatter with required fields.
     Returns error message or None if valid.
+
+    When ``new_skill`` is True (create path only), the description must also
+    fit the 60-char system-prompt budget (SKILL_PROMPT_DESC_LIMIT) so newly
+    authored skills never lose routing signal to index truncation. Edit and
+    patch paths deliberately skip this so existing over-limit skills remain
+    maintainable while their descriptions are cleaned up.
     """
     if not content.strip():
         return "Content cannot be empty."
@@ -570,8 +603,17 @@ def _validate_frontmatter(content: str) -> Optional[str]:
         return "Frontmatter must include 'name' field."
     if "description" not in parsed:
         return "Frontmatter must include 'description' field."
-    if len(str(parsed["description"])) > MAX_DESCRIPTION_LENGTH:
+    desc = str(parsed["description"])
+    if len(desc) > MAX_DESCRIPTION_LENGTH:
         return f"Description exceeds {MAX_DESCRIPTION_LENGTH} characters."
+    if new_skill and len(desc.strip().strip("'\"")) > SKILL_PROMPT_DESC_LIMIT:
+        return (
+            f"Description is {len(desc.strip())} chars — new skills must fit the "
+            f"{SKILL_PROMPT_DESC_LIMIT}-char system-prompt budget (one sentence, "
+            f"trigger first, ends with a period). The skill index truncates "
+            f"longer descriptions to {SKILL_PROMPT_DESC_LIMIT - 3} chars + '...', "
+            f"destroying the routing signal. Move detail into the skill body."
+        )
 
     body = content[end_match.end() + 3:].strip()
     if not body:
@@ -810,6 +852,18 @@ def _atomic_write_text(file_path: Path, content: str, encoding: str = "utf-8") -
 # Core actions
 # =============================================================================
 
+
+def _add_description_prompt_preview(result: Dict[str, Any], content: str) -> None:
+    """Append a system_prompt_preview field when the description will be truncated."""
+    fm, _ = _parse_frontmatter(content)
+    if is_skill_description_truncated_for_prompt(fm):
+        result["system_prompt_preview"] = (
+            f"System prompt will show: \"{extract_skill_description(fm)}\" — "
+            f"keep the trigger self-contained in the first "
+            f"{SKILL_PROMPT_DESC_LIMIT - 3} chars."
+        )
+
+
 def _create_skill(name: str, content: str, category: str = None) -> Dict[str, Any]:
     """Create a new user skill with SKILL.md content."""
     # Validate name
@@ -822,7 +876,7 @@ def _create_skill(name: str, content: str, category: str = None) -> Dict[str, An
         return {"success": False, "error": err}
 
     # Validate content
-    err = _validate_frontmatter(content)
+    err = _validate_frontmatter(content, new_skill=True)
     if err:
         return {"success": False, "error": err}
 
@@ -875,6 +929,7 @@ def _create_skill(name: str, content: str, category: str = None) -> Dict[str, An
         "To add reference files, templates, or scripts, use "
         "skill_manage(action='write_file', name='{}', file_path='references/example.md', file_content='...')".format(name)
     )
+    _add_description_prompt_preview(result, content)
     return result
 
 
@@ -923,12 +978,14 @@ def _edit_skill(name: str, content: str) -> Dict[str, Any]:
     except Exception:
         pass
 
-    return {
+    result = {
         "success": True,
         "message": f"Skill '{name}' updated (full rewrite).",
         "path": str(existing["path"]),
         "_change": {"description": _desc},
     }
+    _add_description_prompt_preview(result, content)
+    return result
 
 
 def _patch_skill(
@@ -1469,6 +1526,10 @@ SKILL_MANAGE_SCHEMA = {
         "Skip for simple one-offs. Confirm with user before creating/deleting.\n\n"
         "Good skills: trigger conditions, numbered steps with exact commands, "
         "pitfalls section, verification steps. Use skill_view() to see format examples.\n\n"
+        "Description: long descriptions are truncated to the first 57 chars "
+        "plus '...' in the system prompt skill index; longer text is visible "
+        "via skills_list/skill_view. Keep the trigger self-contained in that "
+        "first 57-char window: 'Use when <trigger>. <one-line behavior>.'\n\n"
         "Pinned skills are protected from deletion only — skill_manage(action='delete') "
         "will refuse with a message pointing the user to `hermes curator unpin <name>`. "
         "Patches and edits go through on pinned skills so you can still improve them as "
diff --git a/tools/skill_usage.py b/tools/skill_usage.py
index dcdca87f812..7f519a5d99b 100644
--- a/tools/skill_usage.py
+++ b/tools/skill_usage.py
@@ -210,7 +210,15 @@ def _read_hub_installed_names() -> Set[str]:
     if not lock_path.exists():
         return set()
     try:
-        data = json.loads(lock_path.read_text(encoding="utf-8"))
+        # Tolerate non-UTF-8 bytes in the lock file. Hub descriptions can carry
+        # Windows-1252 typographic chars (em-dash 0x97, smart quotes, bullets)
+        # written as single high bytes; a strict utf-8 read raises
+        # UnicodeDecodeError, which is a ValueError sibling (not OSError/
+        # JSONDecodeError) so it escapes the handler below and 500s the whole
+        # /api/skills endpoint. errors="replace" degrades the offending byte to
+        # U+FFFD, keeping the (structurally valid) JSON — and every other
+        # skill — readable. See #68053.
+        data = json.loads(lock_path.read_text(encoding="utf-8", errors="replace"))
         if isinstance(data, dict):
             installed = data.get("installed") or {}
             if isinstance(installed, dict):
@@ -471,12 +479,160 @@ def is_curation_eligible(skill_name: str, skill_path: Optional[Path] = None) ->
 
 
 def _is_curator_managed_record(record: Any) -> bool:
-    """Return True when a usage record opts a skill into curator management."""
+    """Return True when a usage record opts a skill into curator management.
+
+    NAMING (issue #67140): the on-disk field is ``created_by``, which reads
+    like provenance but is consumed as a **curator-management opt-in policy
+    flag**. The two are not the same question:
+
+    * provenance = "who authored this file" — historical fact, and for records
+      written before the marker existed it is simply unrecoverable.
+    * management = "may autonomous curation mutate/archive this" — a policy
+      decision the user can change at any time via ``hermes curator adopt``.
+
+    ``created_by: "agent"`` therefore means "curator-managed", NOT "proof the
+    agent wrote it". The field name is retained because it is already on disk
+    in every user's ``.usage.json``; renaming it would strand those records.
+    Read it as policy, and prefer ``is_curator_managed()`` at call sites so the
+    intent is unambiguous.
+    """
     if not isinstance(record, dict):
         return False
     return record.get("created_by") == "agent" or record.get("agent_created") is True
 
 
+def is_curator_managed(skill_name: str) -> bool:
+    """Whether *skill_name* is opted into curator management.
+
+    Policy-intent alias for the ``created_by``-marker check, so call sites read
+    as the question they are actually asking (see ``_is_curator_managed_record``
+    for why the stored field name says "created_by").
+    """
+    return _is_curator_managed_record(load_usage().get(skill_name))
+
+
+def list_unmanaged_skill_names() -> List[str]:
+    """Enumerate curation-ELIGIBLE skills that carry no provenance marker.
+
+    These are skills the curator *could* manage (they are not hub-installed,
+    not external, not protected built-ins) but never will, because nothing
+    ever wrote ``created_by: agent`` onto their usage record. Two ways a skill
+    lands here:
+
+    * It predates the provenance mechanism entirely — records written before
+      ``created_by`` existed carry no key at all, so their authorship is
+      unknowable from the record alone.
+    * It was created by a FOREGROUND ``skill_manage(action="create")`` call,
+      which deliberately does not mark provenance (skills a user asks for
+      belong to the user).
+
+    Either way the skill is invisible to ``curated_report()`` and therefore to
+    every automatic transition. ``hermes curator status`` surfaces this count
+    so the blind spot is legible instead of silent, and ``hermes curator
+    adopt`` lets the user hand specific skills over explicitly.
+
+    Provenance is a DECLARATION, never an inference: this function only
+    reports, and callers must not auto-adopt what it returns. Heavy patch or
+    use counts are evidence of maintenance, not of authorship — the agent
+    edits user-authored skills on the user's behalf routinely.
+    """
+    base = _skills_dir()
+    if not base.exists():
+        return []
+    hub = _read_hub_installed_names()
+    bundled = _read_bundled_manifest_names()
+    usage = load_usage()
+
+    names: List[str] = []
+    for skill_md in base.rglob("SKILL.md"):
+        if is_excluded_skill_path(skill_md) or is_external_skill_path(skill_md):
+            continue
+        try:
+            skill_md.relative_to(base)
+        except ValueError:
+            continue
+        name = _read_skill_name(skill_md, fallback=skill_md.parent.name)
+        # Anything with an external owner or a bundled/protected identity is
+        # outside the adoption question entirely.
+        if name in hub or name in bundled or is_protected_builtin(name):
+            continue
+        if _is_curator_managed_record(usage.get(name)):
+            continue
+        if not is_curation_eligible(name, skill_md):
+            continue
+        names.append(name)
+    return sorted(set(names))
+
+
+def unmanaged_report() -> List[Dict[str, Any]]:
+    """Rows for every skill :func:`list_unmanaged_skill_names` returns.
+
+    Each row carries the usual activity fields plus ``has_provenance_key``:
+    False when the record has no ``created_by`` key at all (pre-dates the
+    mechanism), True when the key is present but unset (a foreground create
+    under the current policy). The distinction matters for explaining WHY a
+    skill is unmanaged; it is not a signal to adopt on.
+    """
+    usage = load_usage()
+    rows: List[Dict[str, Any]] = []
+    for name in list_unmanaged_skill_names():
+        raw = usage.get(name)
+        rec: Dict[str, Any] = dict(raw) if isinstance(raw, dict) else _empty_record()
+        for k, v in _empty_record().items():
+            rec.setdefault(k, v)
+        row = {"name": name, **rec}
+        row["has_provenance_key"] = isinstance(raw, dict) and "created_by" in raw
+        row["has_record"] = isinstance(raw, dict)
+        row["last_activity_at"] = latest_activity_at(row)
+        row["activity_count"] = activity_count(row)
+        rows.append(row)
+    return rows
+
+
+def adopt_skill(skill_name: str) -> Tuple[bool, str]:
+    """Hand *skill_name* to the curator by user declaration.
+
+    Writes the same ``created_by: agent`` marker the background review fork
+    writes, so the skill joins ``curated_report()`` and the automatic
+    transition walk. The inactivity clock is NOT reset: the skill's existing
+    ``last_activity_at`` still governs staleness, so adopting something idle
+    for months does not buy it a fresh window (nor does it archive it on the
+    spot — the state machine decides on the next pass).
+
+    Returns (ok, message). Refuses hub-installed, external, and protected
+    built-in skills, which have an owner other than the user.
+    """
+    if not skill_name:
+        return False, "no skill name given"
+    if is_protected_builtin(skill_name):
+        return False, f"'{skill_name}' is a protected built-in; the curator never manages it"
+    if is_hub_installed(skill_name):
+        return False, f"'{skill_name}' is hub-installed; its upstream owns it"
+    if is_bundled(skill_name):
+        # Bundled skills already fall under the curator via
+        # ``curator.prune_builtins``; stamping created_by=agent on one would
+        # claim Hermes' own shipped skill was agent-authored and change nothing
+        # about its eligibility.
+        return False, (
+            f"'{skill_name}' is a bundled built-in — it is governed by "
+            "curator.prune_builtins, not by adoption"
+        )
+    skill_dir = _find_skill_dir(skill_name)
+    if skill_dir is None:
+        if _find_external_skill_dir(skill_name) is not None:
+            return False, f"'{skill_name}' lives in skills.external_dirs and is read-only to the curator"
+        return False, f"skill '{skill_name}' not found"
+    if is_external_skill_path(skill_dir):
+        return False, _external_read_only_message(skill_name)
+    usage = load_usage()
+    if _is_curator_managed_record(usage.get(skill_name)):
+        return True, f"'{skill_name}' is already curator-managed"
+    mark_agent_created(skill_name)
+    if not _is_curator_managed_record(load_usage().get(skill_name)):
+        return False, f"could not mark '{skill_name}' as curator-managed"
+    return True, f"adopted '{skill_name}' into curator management"
+
+
 # ---------------------------------------------------------------------------
 # Sidecar I/O
 # ---------------------------------------------------------------------------
@@ -867,11 +1023,15 @@ def _find_external_skill_dir(skill_name: str) -> Optional[Path]:
 # Reporting — for the curator CLI / slash command
 # ---------------------------------------------------------------------------
 
-def agent_created_report() -> List[Dict[str, Any]]:
-    """Return a list of {name, state, pinned, last_activity_at, ...}
+def curated_report() -> List[Dict[str, Any]]:
+    """Return a list of {name, provenance, state, pinned, last_activity_at, ...}
     records for every curator-managed skill. Missing usage records are
     backfilled with defaults so callers can always index fields.
 
+    ``provenance`` is 'agent', 'bundled', or 'hub' (see :func:`provenance`).
+    Bundled skills are only included when ``curator.prune_builtins`` is enabled.
+    Hub-installed skills are never included.
+
     Each row carries ``_persisted``: True when a real record exists in
     ``.usage.json``, False when the row is a fresh backfill (e.g. a built-in
     seen for the first time). The curator uses this to seed the inactivity
@@ -889,10 +1049,22 @@ def agent_created_report() -> List[Dict[str, Any]]:
         row = {"name": name, **rec, "_persisted": persisted}
         row["last_activity_at"] = latest_activity_at(row)
         row["activity_count"] = activity_count(row)
+        row["provenance"] = provenance(name)
         rows.append(row)
     return rows
 
 
+def agent_created_report() -> List[Dict[str, Any]]:
+    """DEPRECATED — use :func:`curated_report` instead.
+
+    Used to return everything :func:`curated_report` returns (including bundled
+    skills when ``curator.prune_builtins`` is enabled), which made the
+    "agent-created" name misleading. Kept as a compatibility alias for
+    external callers; new code should call ``curated_report()``.
+    """
+    return curated_report()
+
+
 def provenance(skill_name: str) -> str:
     """Classify a skill's origin: 'hub', 'bundled', or 'agent'.
 
@@ -909,7 +1081,7 @@ def provenance(skill_name: str) -> str:
 def usage_report() -> List[Dict[str, Any]]:
     """Return usage telemetry for EVERY skill on disk, with provenance.
 
-    Unlike ``agent_created_report()`` (which is scoped to curator-managed
+    Unlike ``curated_report()`` (which is scoped to curator-managed
     candidates), this surfaces all skills — bundled built-ins and
     hub-installed included — so callers can answer "how often is this skill
     used" independent of whether it's ever curated. Rows carry a
diff --git a/tools/skills_hub.py b/tools/skills_hub.py
index aa1bcc5c01e..bb44e5e686e 100644
--- a/tools/skills_hub.py
+++ b/tools/skills_hub.py
@@ -412,7 +412,7 @@ class GitHubAuth:
         try:
             result = subprocess.run(
                 ["gh", "auth", "token"],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
                 stdin=subprocess.DEVNULL,
                 creationflags=windows_hide_flags(),
             )
@@ -1144,7 +1144,7 @@ class GitHubSource(SkillSource):
             stat = cache_file.stat()
             if time.time() - stat.st_mtime > INDEX_CACHE_TTL:
                 return None
-            return json.loads(cache_file.read_text())
+            return json.loads(cache_file.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError):
             return None
 
@@ -1154,7 +1154,7 @@ class GitHubSource(SkillSource):
         index_cache_dir.mkdir(parents=True, exist_ok=True)
         cache_file = index_cache_dir / f"{key}.json"
         try:
-            cache_file.write_text(json.dumps(data, ensure_ascii=False))
+            cache_file.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
         except OSError as e:
             logger.debug("Could not write cache: %s", e)
 
@@ -3355,7 +3355,7 @@ def _read_index_cache(key: str) -> Optional[Any]:
         stat = cache_file.stat()
         if time.time() - stat.st_mtime > INDEX_CACHE_TTL:
             return None
-        return json.loads(cache_file.read_text())
+        return json.loads(cache_file.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
         return None
 
@@ -3370,12 +3370,12 @@ def _write_index_cache(key: str, data: Any) -> None:
     ignore_file = _hub_dir() / ".ignore"
     if not ignore_file.exists():
         try:
-            ignore_file.write_text("# Exclude hub internals from search tools\n*\n")
+            ignore_file.write_text("# Exclude hub internals from search tools\n*\n", encoding="utf-8")
         except OSError:
             pass
     cache_file = index_cache_dir / f"{key}.json"
     try:
-        cache_file.write_text(json.dumps(data, ensure_ascii=False, default=str))
+        cache_file.write_text(json.dumps(data, ensure_ascii=False, default=str), encoding="utf-8")
     except OSError as e:
         logger.debug("Could not write cache: %s", e)
 
@@ -3409,13 +3409,13 @@ class HubLockFile:
         if not self.path.exists():
             return {"version": 1, "installed": {}}
         try:
-            return json.loads(self.path.read_text())
+            return json.loads(self.path.read_text(encoding="utf-8"))
         except (json.JSONDecodeError, OSError):
             return {"version": 1, "installed": {}}
 
     def save(self, data: dict) -> None:
         self.path.parent.mkdir(parents=True, exist_ok=True)
-        self.path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+        self.path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
 
     def record_install(
         self,
@@ -3483,14 +3483,14 @@ class TapsManager:
         if not self.path.exists():
             return []
         try:
-            data = json.loads(self.path.read_text())
+            data = json.loads(self.path.read_text(encoding="utf-8"))
             return data.get("taps", [])
         except (json.JSONDecodeError, OSError):
             return []
 
     def save(self, taps: List[dict]) -> None:
         self.path.parent.mkdir(parents=True, exist_ok=True)
-        self.path.write_text(json.dumps({"taps": taps}, indent=2) + "\n")
+        self.path.write_text(json.dumps({"taps": taps}, indent=2) + "\n", encoding="utf-8")
 
     def add(self, repo: str, path: str = "skills/") -> bool:
         """Add a tap. Returns False if already exists."""
@@ -3549,11 +3549,11 @@ def ensure_hub_dirs() -> None:
     _quarantine_dir().mkdir(exist_ok=True)
     _index_cache_dir().mkdir(exist_ok=True)
     if not lock_file.exists():
-        lock_file.write_text('{"version": 1, "installed": {}}\n')
+        lock_file.write_text('{"version": 1, "installed": {}}\n', encoding="utf-8")
     if not audit_log.exists():
         audit_log.touch()
     if not taps_file.exists():
-        taps_file.write_text('{"taps": []}\n')
+        taps_file.write_text('{"taps": []}\n', encoding="utf-8")
 
 
 def quarantine_bundle(bundle: SkillBundle) -> Path:
@@ -3803,7 +3803,7 @@ def _load_hermes_index() -> Optional[dict]:
         try:
             age = time.time() - hermes_index_cache_file.stat().st_mtime
             if age < HERMES_INDEX_TTL:
-                return json.loads(hermes_index_cache_file.read_text())
+                return json.loads(hermes_index_cache_file.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError):
             pass
 
@@ -3857,7 +3857,7 @@ def _load_hermes_index() -> Optional[dict]:
     # Cache locally
     try:
         hermes_index_cache_file.parent.mkdir(parents=True, exist_ok=True)
-        hermes_index_cache_file.write_text(json.dumps(data))
+        hermes_index_cache_file.write_text(json.dumps(data), encoding="utf-8")
     except OSError:
         pass
 
@@ -3869,7 +3869,7 @@ def _load_stale_index_cache() -> Optional[dict]:
     hermes_index_cache_file = _hermes_index_cache_file()
     if hermes_index_cache_file.exists():
         try:
-            return json.loads(hermes_index_cache_file.read_text())
+            return json.loads(hermes_index_cache_file.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError):
             pass
     return None
diff --git a/tools/skills_sync.py b/tools/skills_sync.py
index 09b8337540b..de0545e308c 100644
--- a/tools/skills_sync.py
+++ b/tools/skills_sync.py
@@ -26,8 +26,24 @@ import json
 import logging
 import os
 import shutil
+import sys
 from datetime import datetime, timezone
 from pathlib import Path, PurePosixPath
+
+# Force stdout/stderr to UTF-8. On non-UTF-8 Windows locales (e.g. CP936/GBK
+# on zh-CN), Python's default stream encoding can't represent the checkmark /
+# arrow glyphs this script prints (✓ U+2713, ↑ U+2191), raising
+# UnicodeEncodeError mid-run. The bootstrap installer (install.ps1) captures
+# this script's stdout and parses it as UTF-8; a GBK byte stream then surfaces
+# as "stream did not contain valid UTF-8" and aborts the config-templates
+# stage even though the script itself exits 0. Reconfigure unconditionally so
+# output is valid UTF-8 regardless of the active codepage or caller.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        try:
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, TypeError):
+            pass
 from hermes_constants import get_bundled_skills_dir, get_hermes_home, get_optional_skills_dir
 from agent.skill_utils import is_excluded_skill_path
 from typing import Dict, List, Optional, Set, Tuple
@@ -386,6 +402,36 @@ def restore_official_optional_skill(name: str, *, restore: bool = False) -> dict
     }
 
 
+def _find_installed_skill_dir_by_name(skill_dir_name: str) -> Optional[Path]:
+    """Locate an installed skill directory by its directory name.
+
+    Used only as a fallback when the repo-derived install path doesn't exist in
+    the active tree (upstream recategorized the skill after it was installed).
+    Returns None when there is no match, or when the name is AMBIGUOUS — two
+    skills sharing a directory name give us no basis to pick one, and guessing
+    would write provenance onto the wrong skill. The caller still verifies a
+    byte-identical content hash before recording anything.
+    """
+    if not skill_dir_name or not SKILLS_DIR.exists():
+        return None
+    matches: List[Path] = []
+    for skill_md in SKILLS_DIR.rglob("SKILL.md"):
+        if is_excluded_skill_path(skill_md):
+            continue
+        candidate = skill_md.parent
+        if candidate.name != skill_dir_name:
+            continue
+        # Never reach outside the skills tree (symlinked/external dirs).
+        try:
+            candidate.resolve().relative_to(SKILLS_DIR.resolve())
+        except (OSError, ValueError):
+            continue
+        matches.append(candidate)
+    if len(matches) != 1:
+        return None
+    return matches[0]
+
+
 def _backfill_optional_provenance(quiet: bool = False) -> List[str]:
     """Mark already-present official optional skills as hub-installed.
 
@@ -401,7 +447,7 @@ def _backfill_optional_provenance(quiet: bool = False) -> List[str]:
 
     lock_path = SKILLS_DIR / ".hub" / "lock.json"
     try:
-        data = json.loads(lock_path.read_text()) if lock_path.exists() else {"version": 1, "installed": {}}
+        data = json.loads(lock_path.read_text(encoding="utf-8")) if lock_path.exists() else {"version": 1, "installed": {}}
     except (json.JSONDecodeError, OSError):
         data = {"version": 1, "installed": {}}
     installed = data.setdefault("installed", {})
@@ -424,7 +470,22 @@ def _backfill_optional_provenance(quiet: bool = False) -> List[str]:
             continue
         dest = SKILLS_DIR / Path(*install_path.split("/"))
         if not dest.exists() or not dest.is_dir():
-            continue
+            # The active tree may hold the same skill under a DIFFERENT
+            # category path than the repo uses — categories get reorganized
+            # upstream (e.g. mlops/chroma → mlops/vector-databases/chroma)
+            # while the already-installed copy keeps its old location. A
+            # path-only lookup misses every one of those, so provenance repair
+            # silently skips them forever. Fall back to a unique
+            # same-directory-name match anywhere in the tree, then still
+            # require a byte-identical hash below before claiming provenance.
+            dest = _find_installed_skill_dir_by_name(src.name)
+            if dest is None:
+                continue
+            try:
+                install_path = _safe_rel_install_path(dest, SKILLS_DIR)
+            except ValueError as e:
+                logger.debug("Skipping relocated optional skill %s: %s", dest, e)
+                continue
         if _dir_hash(dest) != _dir_hash(src):
             continue
 
@@ -479,6 +540,114 @@ def _backfill_optional_provenance(quiet: bool = False) -> List[str]:
     return backfilled
 
 
+def _read_hub_install_paths() -> Set[str]:
+    """Return install paths recorded in the skills-hub lock, as POSIX strings.
+
+    Hub-installed skills are owned by the hub (``hermes skills uninstall``),
+    never by bundled sync. Rename recovery must not move them even when their
+    content happens to match a bundled origin hash, or the lock's
+    ``install_path`` would point at a directory that no longer exists.
+    """
+    lock_path = SKILLS_DIR / ".hub" / "lock.json"
+    if not lock_path.exists():
+        return set()
+    try:
+        data = json.loads(lock_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return set()
+    paths: Set[str] = set()
+    for entry in (data.get("installed") or {}).values():
+        if isinstance(entry, dict):
+            install_path = entry.get("install_path")
+            if install_path:
+                paths.add(str(install_path).strip("/"))
+    return paths
+
+
+def _index_active_skills() -> Dict[str, List[Path]]:
+    """Index every skill in the user's tree by frontmatter name.
+
+    Returns ``{skill_name: [skill_dir, ...]}``. Used by rename recovery to
+    locate a bundled skill that upstream moved to a new category/directory.
+    """
+    index: Dict[str, List[Path]] = {}
+    if not SKILLS_DIR.exists():
+        return index
+    for skill_md in SKILLS_DIR.rglob("SKILL.md"):
+        if is_excluded_skill_path(skill_md):
+            continue
+        skill_dir = skill_md.parent
+        name = _read_skill_name(skill_md, skill_dir.name)
+        index.setdefault(name, []).append(skill_dir)
+    return index
+
+
+def _recover_renamed_skill(
+    skill_name: str,
+    origin_hash: str,
+    dest: Path,
+    active_index: Dict[str, List[Path]],
+    hub_paths: Set[str],
+    quiet: bool,
+) -> Optional[str]:
+    """Move a bundled skill's stale copy to its new canonical path.
+
+    When upstream RENAMES or RECATEGORIZES a bundled skill, the manifest key
+    (frontmatter name) still matches but ``dest`` is a brand-new path that does
+    not exist yet. Without recovery, ``sync_skills()`` falls through to its
+    "in manifest but not on disk" branch and misreads the skill as
+    *user-deleted*: the old directory is stranded forever and never receives
+    another update.
+
+    A stale copy is only moved when it is byte-identical to ``origin_hash`` —
+    the hash recorded the last time sync wrote that skill — which proves the
+    directory is the copy *we* placed there rather than the user's own work.
+    Anything else (user-edited, hub-installed) is left untouched.
+
+    Returns the relative source path when a move happened, else ``None``.
+    """
+    if not origin_hash:
+        return None
+
+    for candidate in active_index.get(skill_name, []):
+        if candidate == dest or not candidate.is_dir():
+            continue
+        try:
+            rel = candidate.relative_to(SKILLS_DIR).as_posix()
+        except ValueError:
+            continue
+        # Never relocate a hub-installed skill — the hub owns its path.
+        if rel in hub_paths:
+            continue
+        if _dir_hash(candidate) != origin_hash:
+            # User customized the copy at the old path. Moving it would edit
+            # their work; leaving it avoids a duplicate-name collision. Warn
+            # so they can migrate deliberately.
+            if not quiet:
+                print(
+                    f"  ⚠ {skill_name}: upstream moved this skill to "
+                    f"{dest.relative_to(SKILLS_DIR).as_posix()}, but your "
+                    f"modified copy at {rel} was kept — it will not receive "
+                    f"updates. Run `hermes skills reset {skill_name} --restore` "
+                    f"to move to the new location."
+                )
+            continue
+        try:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(str(candidate), str(dest))
+        except (OSError, IOError):
+            logger.warning(
+                "Could not relocate renamed skill %s -> %s", candidate, dest,
+                exc_info=True,
+            )
+            return None
+        logger.info("Relocated renamed bundled skill: %s -> %s", candidate, dest)
+        if not quiet:
+            print(f"  → {skill_name} (moved {rel} → {dest.relative_to(SKILLS_DIR).as_posix()})")
+        return rel
+    return None
+
+
 def sync_skills(quiet: bool = False) -> dict:
     """
     Sync bundled skills into ~/.hermes/skills/ using the manifest.
@@ -517,11 +686,15 @@ def sync_skills(quiet: bool = False) -> dict:
     # Index of skills already provided by external_dirs (skip writing them)
     external_index = _build_external_skill_index()
     shadowed_by_external: List[str] = []
+    # Rename recovery indexes, built once per sync (see _recover_renamed_skill).
+    active_index = _index_active_skills()
+    hub_paths = _read_hub_install_paths()
 
     copied = []
     updated = []
     user_modified = []
     suppressed_skipped: List[str] = []
+    relocated: List[str] = []
     skipped = 0
 
     for skill_name, skill_src in bundled_skills:
@@ -555,6 +728,23 @@ def sync_skills(quiet: bool = False) -> dict:
                     exc_info=True,
                 )
 
+        # Recover an upstream RENAME / RECATEGORIZATION before classifying.
+        # The manifest key (frontmatter name) survives a directory move, but
+        # ``dest`` is a new path that does not exist yet — without this the
+        # "in manifest but not on disk" branch below misreads the skill as
+        # user-deleted, stranding the old copy at its stale path forever.
+        if not dest.exists() and skill_name in manifest:
+            _moved_from = _recover_renamed_skill(
+                skill_name,
+                manifest.get(skill_name, ""),
+                dest,
+                active_index,
+                hub_paths,
+                quiet,
+            )
+            if _moved_from:
+                relocated.append(skill_name)
+
         if skill_name in external_index:
             # An external_dirs source already provides this skill. Writing it
             # into the profile-local tree would create a name collision the
@@ -713,6 +903,7 @@ def sync_skills(quiet: bool = False) -> dict:
         "user_modified": user_modified,
         "cleaned": cleaned,
         "suppressed": suppressed_skipped,
+        "relocated": relocated,
         "total_bundled": len(bundled_skills),
         "optional_provenance_backfilled": optional_provenance_backfilled,
         "shadowed_by_external": shadowed_by_external,
diff --git a/tools/tirith_security.py b/tools/tirith_security.py
index 93509604131..a07d3f817df 100644
--- a/tools/tirith_security.py
+++ b/tools/tirith_security.py
@@ -315,7 +315,7 @@ def _verify_cosign(checksums_path: str, sig_path: str, cert_path: str) -> bool |
              "--certificate-oidc-issuer", _COSIGN_ISSUER,
              checksums_path],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=15,
             stdin=subprocess.DEVNULL,
         )
@@ -776,7 +776,7 @@ def check_command_security(command: str) -> dict:
             [tirith_path, "check", "--json", "--non-interactive",
              "--shell", "posix", "--", command],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=timeout,
             stdin=subprocess.DEVNULL,
         )
diff --git a/tools/tool_search.py b/tools/tool_search.py
index e885a5d7b88..ccfddcc46e4 100644
--- a/tools/tool_search.py
+++ b/tools/tool_search.py
@@ -9,9 +9,19 @@ for the full rationale):
 
 * Core tools defined in ``toolsets._HERMES_CORE_TOOLS`` are *never* deferred.
   Always-load means always-load. No exceptions.
-* The threshold gate runs every assembly: when deferrable tools would consume
-  less than ``threshold_pct`` of the model's context window (default 10%),
-  tool search is a no-op and the tools array passes through unchanged.
+* Tiered disclosure (July 2026 plan): the moment ANY deferrable (MCP/plugin)
+  tools are present, they hide behind the bridge. What scales with catalog
+  size is the *listing*, not the activation decision:
+    - Tier 0 — no MCP/plugin tools: pure passthrough, everything eager.
+    - Tier 1 — deferred tools whose catalog listing fits the listing budget
+      (``min(threshold_pct`` of context — default 5% — ``, listing_max_tokens)``):
+      bridge + skills-style listing (name + short description per tool),
+      degrading to a names-only listing when the full form is over budget.
+    - Tier 2 — per-tool listing over budget even names-only (e.g.
+      Cloudflare's flat API surface, ~3,300 tools whose names alone are
+      ~32K tokens): bare bridge + a one-line-per-server summary (server
+      name + tool count) so the model still knows WHICH domains are
+      reachable; individual tools are discoverable only via ``tool_search``.
 * The catalog is stateless across turns and tools-array assemblies. It is
   rebuilt from the current tool-defs list every time. This is the lesson
   from OpenClaw's cron regression (openclaw/openclaw#84141): a session-keyed
@@ -65,9 +75,25 @@ class ToolSearchConfig:
     """Resolved, validated tool-search configuration for a single assembly."""
 
     enabled: str  # "auto" | "on" | "off"
-    threshold_pct: float  # 0..100 — only used when enabled == "auto"
+    # Listing budget as a percentage of the model's context window. Under
+    # tiered disclosure this no longer gates *activation* (any deferrable
+    # tool activates the bridge) — it bounds how much context the embedded
+    # catalog listing may consume before disclosure degrades:
+    # full listing -> names-only -> bare bridge (tier 2).
+    threshold_pct: float  # 0..100
     search_default_limit: int
     max_search_limit: int
+    # Catalog listing ("skills-style" progressive disclosure): when active,
+    # a grouped name + short-description manifest of every deferred tool is
+    # embedded in the tool_search bridge description, so capabilities stay
+    # DISCOVERABLE (like the skills listing in the system prompt) while full
+    # schemas stay deferred.  "auto" = include when it fits the listing
+    # budget (falls back to names-only, then to none = bare bridge);
+    # "on" = same rendering, explicit intent; "off" = always bare bridge.
+    listing: str = "auto"  # "auto" | "on" | "off"
+    # Absolute cap on the embedded listing, regardless of context size.
+    # Effective budget = min(listing_max_tokens, threshold_pct% of context).
+    listing_max_tokens: int = 20000
 
     @classmethod
     def from_raw(cls, raw: Any) -> "ToolSearchConfig":
@@ -80,13 +106,13 @@ class ToolSearchConfig:
         break the agent.
         """
         if raw is True:
-            return cls(enabled="auto", threshold_pct=10.0,
+            return cls(enabled="auto", threshold_pct=5.0,
                        search_default_limit=5, max_search_limit=20)
         if raw is False:
-            return cls(enabled="off", threshold_pct=10.0,
+            return cls(enabled="off", threshold_pct=5.0,
                        search_default_limit=5, max_search_limit=20)
         if not isinstance(raw, dict):
-            return cls(enabled="auto", threshold_pct=10.0,
+            return cls(enabled="auto", threshold_pct=5.0,
                        search_default_limit=5, max_search_limit=20)
 
         enabled_raw = str(raw.get("enabled", "auto")).strip().lower()
@@ -99,18 +125,31 @@ class ToolSearchConfig:
         else:
             enabled = "auto"
 
-        threshold_pct = _safe_float(raw.get("threshold_pct"), 10.0)
+        threshold_pct = _safe_float(raw.get("threshold_pct"), 5.0)
         threshold_pct = max(0.0, min(100.0, threshold_pct))
 
         max_search_limit = max(1, min(50, _safe_int(raw.get("max_search_limit"), 20)))
         search_default_limit = max(1, min(max_search_limit,
                                           _safe_int(raw.get("search_default_limit"), 5)))
 
+        listing_raw = str(raw.get("listing", "auto")).strip().lower()
+        if listing_raw in ("true", "1", "yes"):
+            listing = "on"
+        elif listing_raw in ("false", "0", "no"):
+            listing = "off"
+        elif listing_raw in ("auto", "on", "off"):
+            listing = listing_raw
+        else:
+            listing = "auto"
+        listing_max_tokens = max(200, min(60000, _safe_int(raw.get("listing_max_tokens"), 20000)))
+
         return cls(
             enabled=enabled,
             threshold_pct=threshold_pct,
             search_default_limit=search_default_limit,
             max_search_limit=max_search_limit,
+            listing=listing,
+            listing_max_tokens=listing_max_tokens,
         )
 
 
@@ -238,24 +277,37 @@ def should_activate(
 ) -> bool:
     """Decide whether tool search should activate for the current assembly.
 
-    ``"off"`` skips unconditionally. ``"on"`` activates unconditionally
-    (as long as there is at least one deferrable tool — there's no point
-    swapping a no-op). ``"auto"`` activates when the deferrable schemas
-    would consume ``threshold_pct`` of context or more.
+    ``"off"`` skips unconditionally. ``"on"`` and ``"auto"`` activate whenever
+    at least one deferrable tool exists (there's no point swapping a no-op).
+
+    Tiered-disclosure semantics (July 2026): the presence of ANY MCP/plugin
+    tool activates the bridge — schemas always defer. What the threshold now
+    controls is the *listing budget* (see :func:`listing_token_budget`), not
+    activation. ``context_length`` is retained in the signature for
+    backward compatibility with existing callers.
     """
     if config.enabled == "off":
         return False
     if deferrable_tokens <= 0:
         return False
-    if config.enabled == "on":
-        return True
-    # auto
-    if not context_length or context_length <= 0:
-        # Without a known context size, fall back to a fixed 20K-token cutoff
-        # — the cliff above which Anthropic and OpenAI both saw quality drops.
-        return deferrable_tokens >= 20_000
-    threshold_tokens = int(context_length * (config.threshold_pct / 100.0))
-    return deferrable_tokens >= threshold_tokens
+    return True
+
+
+def listing_token_budget(
+    config: ToolSearchConfig,
+    context_length: Optional[int],
+) -> int:
+    """Effective token budget for the embedded catalog listing.
+
+    ``min(listing_max_tokens, threshold_pct% of context)``. Without a known
+    context size, the percentage leg falls back to a fixed 10K cutoff
+    (5% of a typical 200K window).
+    """
+    if context_length and context_length > 0:
+        pct_leg = int(context_length * (config.threshold_pct / 100.0))
+    else:
+        pct_leg = 10_000
+    return max(0, min(config.listing_max_tokens, pct_leg))
 
 
 # ---------------------------------------------------------------------------
@@ -423,12 +475,173 @@ def search_catalog(catalog: List[CatalogEntry], query: str, limit: int = 5) -> L
 # ---------------------------------------------------------------------------
 
 
-def bridge_tool_schemas(deferred_count: int) -> List[Dict[str, Any]]:
+_SENTENCE_END_RE = re.compile(r"[.!?\n]")
+
+
+def _short_desc(description: str, max_chars: int = 60) -> str:
+    """First sentence of a tool description, clipped to ``max_chars``.
+
+    Mirrors the skills-listing convention: one terse line per capability.
+    Whitespace is collapsed; a hard clip never cuts mid-word unless the
+    first word itself exceeds the budget.
+    """
+    text = " ".join((description or "").split())
+    if not text:
+        return ""
+    m = _SENTENCE_END_RE.search(text)
+    if m:
+        text = text[:m.start() + (1 if text[m.start()] == "." else 0)]
+    if len(text) <= max_chars:
+        return text
+    clipped = text[:max_chars]
+    if " " in clipped:
+        clipped = clipped.rsplit(" ", 1)[0]
+    return clipped.rstrip(",;: ") + "…"
+
+
+def _listing_group_label(source_name: str) -> str:
+    """Human-facing group heading for a toolset, e.g. ``mcp-github`` -> ``github``."""
+    label = source_name or "other"
+    if label.startswith("mcp-"):
+        label = label[4:]
+    return label
+
+
+def build_catalog_listing(
+    deferrable: List[Dict[str, Any]],
+    *,
+    max_tokens: int = 20000,
+) -> Optional[str]:
+    """Render a skills-style manifest of the deferred catalog.
+
+    One line per tool — ``name: short description`` — grouped under a
+    heading per source (MCP server / plugin toolset), exactly like the
+    bundled-skills listing in the system prompt:
+
+        github tools: (44)
+        - create_issue: Open a new issue in a GitHub repository.
+        - merge_pull_request: Merge an open pull request.
+        ...
+
+    Ordering is deterministic (groups and tools sorted by name) so the
+    rendered block is byte-stable across assemblies of the same catalog —
+    this keeps the request prefix cacheable across turns.
+
+    Token-budget fallbacks (cheap chars/4 estimate, same rule as the
+    activation gate):
+      1. full listing (names + short descriptions)
+      2. names-only listing, still grouped
+      3. server-level summary — one line per MCP server / plugin toolset
+         (name + tool count), so the model always knows WHICH domains are
+         reachable through the bridge even when per-tool names don't fit
+      4. ``None`` — only when the summary itself exceeds the budget
+    """
+    text, _form = build_catalog_listing_with_form(deferrable, max_tokens=max_tokens)
+    return text
+
+
+def build_catalog_listing_with_form(
+    deferrable: List[Dict[str, Any]],
+    *,
+    max_tokens: int = 20000,
+) -> Tuple[Optional[str], str]:
+    """Like :func:`build_catalog_listing` but also reports the form used.
+
+    Returns ``(text, form)`` where ``form`` is ``"full"`` (names + short
+    descriptions), ``"names"`` (names-only fallback), ``"mixed"`` (per-server
+    degradation: small servers keep per-tool lines, oversized servers
+    collapse to a name + tool-count summary line), ``"groups"`` (every
+    server summarized), or ``"none"`` (over budget in every form).
+
+    Degradation is PER SERVER, not global: one huge server (Cloudflare's
+    3,320 flat tools) must not cost a small co-attached server (Linear's 24)
+    its listing. Greedy fit, smallest rendered group first, is deterministic
+    for a given catalog — byte-stable across assemblies, cache-safe.
+    """
+    if not deferrable:
+        return None, "none"
+
+    groups: Dict[str, List[Tuple[str, str]]] = {}
+    for td in deferrable:
+        fn = td.get("function") or {}
+        name = fn.get("name", "")
+        if not name:
+            continue
+        source, source_name = _classify_source(name)
+        label = _listing_group_label(source_name if source != "other" else "other")
+        groups.setdefault(label, []).append((name, _short_desc(fn.get("description", ""))))
+
+    if not groups:
+        return None, "none"
+
+    def render_group(label: str, mode: str) -> str:
+        """Render one server's block. mode: 'full' | 'names' | 'summary'."""
+        tools = sorted(groups[label])
+        if mode == "summary":
+            return (f"{label} ({len(tools)} tools — names not listed; "
+                    f"discover via `{TOOL_SEARCH_NAME}`)")
+        lines = [f"{label} tools ({len(tools)}):"]
+        if mode == "full":
+            for name, desc in tools:
+                lines.append(f"- {name}: {desc}" if desc else f"- {name}")
+        else:
+            lines.append(", ".join(name for name, _ in tools))
+        return "\n".join(lines)
+
+    header = ("Deferred tool catalog (call schemas via "
+              f"`{TOOL_DESCRIBE_NAME}`, invoke via `{TOOL_CALL_NAME}`):")
+
+    def assemble(modes: Dict[str, str]) -> str:
+        return "\n".join([header] + [render_group(lbl, modes[lbl])
+                                     for lbl in sorted(groups)])
+
+    def fits(text: str) -> bool:
+        return math.ceil(len(text) / CHARS_PER_TOKEN) <= max_tokens
+
+    # 1. Everything full.
+    modes = {lbl: "full" for lbl in groups}
+    if fits(assemble(modes)):
+        return assemble(modes), "full"
+
+    # 2. Everything names-only.
+    modes = {lbl: "names" for lbl in groups}
+    if fits(assemble(modes)):
+        return assemble(modes), "names"
+
+    # 3. Per-server degradation: collapse the LARGEST rendered groups to
+    #    summary lines first, keeping per-tool names for small servers.
+    #    Deterministic: size then label. One oversized server (Cloudflare)
+    #    must not cost a small co-attached server (Linear) its listing.
+    by_size = sorted(groups, key=lambda lbl: (-len(render_group(lbl, "names")), lbl))
+    for lbl in by_size:
+        modes[lbl] = "summary"
+        if fits(assemble(modes)):
+            form = "groups" if all(m == "summary" for m in modes.values()) else "mixed"
+            return assemble(modes), form
+
+    # 4. Even the all-summary form is over budget.
+    return None, "none"
+
+
+def bridge_tool_schemas(
+    deferred_count: int,
+    listing: Optional[str] = None,
+    listing_form: str = "",
+) -> List[Dict[str, Any]]:
     """Build the bridge tool schemas to inject in place of deferred tools.
 
     The schemas are intentionally short — every byte added here is a byte
     the user pays on every turn. Descriptions are tuned to be unambiguous
     about the call sequence the model should follow.
+
+    When ``listing`` is provided (see :func:`build_catalog_listing`), it is
+    embedded in the ``tool_search`` description so every deferred capability
+    stays *visible* by name — the skills-listing pattern — closing the
+    "model doesn't know what it doesn't know" gap while full parameter
+    schemas remain deferred. ``listing_form`` selects the framing: per-tool
+    forms ("full"/"names") tell the model it may skip the search when it
+    sees the exact name; the server-summary form ("groups") tells it which
+    DOMAINS are reachable and that search is mandatory for tool discovery.
     """
     desc_search = (
         f"Search {deferred_count} additional tools that are loaded on demand. "
@@ -437,6 +650,28 @@ def bridge_tool_schemas(deferred_count: int) -> List[Dict[str, Any]]:
         f"then `{TOOL_CALL_NAME}` to invoke it. Tools listed at the top of this "
         "system prompt are already available and do not need to be searched."
     )
+    if listing and listing_form == "groups":
+        desc_search += (
+            "\n\nThe servers below are connected and their tools ARE available "
+            "through this bridge. For any request in these domains, search "
+            "here FIRST — do not claim the capability is unavailable and do "
+            "not substitute a generic tool (terminal/browser) without "
+            "searching.\n\n" + listing
+        )
+    elif listing:
+        desc_search += (
+            "\n\nEvery deferred capability is listed below. If a tool name "
+            "appears here, do NOT claim it is unavailable — load it with "
+            f"`{TOOL_DESCRIBE_NAME}` (skip `{TOOL_SEARCH_NAME}` when you "
+            "already see the exact name)."
+        )
+        if listing_form == "mixed":
+            desc_search += (
+                " For servers marked 'names not listed', the tools exist "
+                f"too — find them with `{TOOL_SEARCH_NAME}` before "
+                "concluding anything is missing."
+            )
+        desc_search += "\n\n" + listing
     desc_describe = (
         f"Load the full JSON schema for one tool returned by `{TOOL_SEARCH_NAME}`. "
         f"Required before `{TOOL_CALL_NAME}` if the tool's parameters are unknown."
@@ -524,6 +759,12 @@ class AssemblyResult:
     deferred_count: int = 0
     deferred_tokens: int = 0
     threshold_tokens: int = 0
+    # Disclosure tier actually applied:
+    #   0 = passthrough (no deferrable tools, or tool_search off)
+    #   1 = bridge + catalog listing (full or names-only)
+    #   2 = bare bridge — catalog too large for any listing form
+    tier: int = 0
+    listing_form: str = "none"  # "full" | "names" | "none"
 
 
 def assemble_tool_defs(
@@ -563,15 +804,29 @@ def assemble_tool_defs(
             deferred_count=len(deferrable),
             deferred_tokens=deferrable_tokens,
             threshold_tokens=int((context_length or 0) * (config.threshold_pct / 100.0)),
+            tier=0,
         )
 
-    bridge = bridge_tool_schemas(len(deferrable))
+    listing = None
+    listing_form = "none"
+    listing_budget = listing_token_budget(config, context_length)
+    if config.listing != "off":
+        listing, listing_form = build_catalog_listing_with_form(
+            deferrable, max_tokens=listing_budget)
+    bridge = bridge_tool_schemas(len(deferrable), listing=listing,
+                                 listing_form=listing_form)
     result = visible + bridge
-    threshold_tokens = int((context_length or 0) * (config.threshold_pct / 100.0))
+    # Tier 1 = per-tool listing for at least part of the catalog (full,
+    # names, or mixed). Tier 2 = search-only discovery; the server-level
+    # "groups" summary keeps domains visible but individual tools are only
+    # reachable via tool_search.
+    tier = 1 if listing_form in ("full", "names", "mixed") else 2
 
     logger.info(
-        "tool_search activated: %d core/visible tools kept, %d deferred (~%d tokens, threshold ~%d)",
-        len(visible), len(deferrable), deferrable_tokens, threshold_tokens,
+        "tool_search activated (tier %d): %d core/visible tools kept, %d deferred "
+        "(~%d tokens), listing %s (budget ~%d tokens)",
+        tier, len(visible), len(deferrable), deferrable_tokens,
+        listing_form, listing_budget,
     )
 
     return AssemblyResult(
@@ -579,7 +834,9 @@ def assemble_tool_defs(
         activated=True,
         deferred_count=len(deferrable),
         deferred_tokens=deferrable_tokens,
-        threshold_tokens=threshold_tokens,
+        threshold_tokens=listing_budget,
+        tier=tier,
+        listing_form=listing_form,
     )
 
 
@@ -724,6 +981,9 @@ __all__ = [
     "estimate_tokens_from_schemas",
     "should_activate",
     "build_catalog",
+    "build_catalog_listing",
+    "build_catalog_listing_with_form",
+    "listing_token_budget",
     "search_catalog",
     "bridge_tool_schemas",
     "assemble_tool_defs",
diff --git a/tools/transcription_tools.py b/tools/transcription_tools.py
index 6c34e714cd7..dd8c60275ad 100644
--- a/tools/transcription_tools.py
+++ b/tools/transcription_tools.py
@@ -556,6 +556,10 @@ def _run_command_stt(command: str, timeout: float) -> subprocess.CompletedProces
         "stdout": subprocess.PIPE,
         "stderr": subprocess.PIPE,
         "text": True,
+        # Lossy UTF-8 decode — locale-mismatched bytes from the STT command
+        # must not raise in the reader threads on non-UTF-8 Windows (#45099).
+        "encoding": "utf-8",
+        "errors": "replace",
         "env": delegated_child_subprocess_env(),
     }
     if os.name == "nt":
@@ -1210,7 +1214,7 @@ def _prepare_local_audio(file_path: str, work_dir: str) -> tuple[Optional[str],
     command = [ffmpeg, "-y", "-i", file_path, converted_path]
 
     try:
-        subprocess.run(command, check=True, capture_output=True, text=True, timeout=300, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags())
+        subprocess.run(command, check=True, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=300, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags())
         return converted_path, None
     except subprocess.TimeoutExpired:
         logger.error("ffmpeg conversion timed out for %s", file_path)
@@ -1256,9 +1260,9 @@ def _transcribe_local_command(file_path: str, model_name: str) -> Dict[str, Any]
             # User-provided templates (env var) may contain shell syntax; auto-detected commands are safe for list mode.
             use_shell = bool(os.getenv(LOCAL_STT_COMMAND_ENV, "").strip())
             if use_shell:
-                subprocess.run(command, shell=True, check=True, capture_output=True, text=True, timeout=300, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags())
+                subprocess.run(command, shell=True, check=True, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=300, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags())
             else:
-                subprocess.run(shlex.split(command), check=True, capture_output=True, text=True, timeout=300, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags())
+                subprocess.run(shlex.split(command), check=True, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=300, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags())
             
 
             txt_files = sorted(Path(output_dir).glob("*.txt"))
diff --git a/tools/tts_tool.py b/tools/tts_tool.py
index 16320974ae6..446a04aa58c 100644
--- a/tools/tts_tool.py
+++ b/tools/tts_tool.py
@@ -782,6 +782,10 @@ def _run_command_tts(command: str, timeout: float) -> subprocess.CompletedProces
         "stdout": subprocess.PIPE,
         "stderr": subprocess.PIPE,
         "text": True,
+        # Lossy UTF-8 decode — locale-mismatched bytes from the TTS command
+        # must not raise in the reader threads on non-UTF-8 Windows (#45099).
+        "encoding": "utf-8",
+        "errors": "replace",
         "env": delegated_child_subprocess_env(),
     }
     if os.name == "nt":
@@ -2015,7 +2019,7 @@ def _generate_neutts(text: str, output_path: str, tts_config: Dict[str, Any]) ->
         "--device", device,
     ]
 
-    result = subprocess.run(cmd, capture_output=True, text=True, timeout=120, stdin=subprocess.DEVNULL)
+    result = subprocess.run(cmd, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=120, stdin=subprocess.DEVNULL)
     if result.returncode != 0:
         stderr = result.stderr.strip()
         # Filter out the "OK:" line from stderr
@@ -2097,7 +2101,7 @@ def _resolve_piper_voice_path(voice: str, download_dir: Path) -> str:
         result = subprocess.run(
             [_sys.executable, "-m", "piper.download_voices", voice,
              "--download-dir", str(download_dir)],
-            capture_output=True, text=True, timeout=300,
+            capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=300,
             stdin=subprocess.DEVNULL,
         )
     except subprocess.TimeoutExpired as exc:
diff --git a/tools/url_safety.py b/tools/url_safety.py
index 27dcc55efd1..00cf1b498db 100644
--- a/tools/url_safety.py
+++ b/tools/url_safety.py
@@ -39,6 +39,21 @@ from utils import is_truthy_value
 logger = logging.getLogger(__name__)
 
 
+# ── Proxy detection ──────────────────────────────────────────
+# Proxy environment variables that indicate the runtime should
+# delegate DNS to a proxy rather than attempting direct resolution.
+_PROXY_ENV_VARS = (
+    "HTTPS_PROXY", "https_proxy",
+    "HTTP_PROXY", "http_proxy",
+    "ALL_PROXY", "all_proxy",
+)
+
+
+def _proxy_is_configured() -> bool:
+    """Return True when at least one HTTP proxy env var is set."""
+    return any(os.environ.get(v) for v in _PROXY_ENV_VARS)
+
+
 def normalize_url_for_request(url: str) -> str:
     """Return an ASCII-safe HTTP URL for Hermes-owned URL tools.
 
@@ -420,8 +435,29 @@ def is_safe_url(url: str) -> bool:
         try:
             addr_info = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
         except socket.gaierror:
-            # DNS resolution failed — fail closed. If DNS can't resolve it,
-            # the HTTP client will also fail, so blocking loses nothing.
+            # DNS resolution failed.  In sandbox / proxy environments
+            # (NVIDIA OpenShell, Docker + Squid, etc.) the host may
+            # block direct DNS — only HTTP(S) through the proxy is
+            # permitted.  When a proxy is configured, delegate DNS to
+            # the proxy rather than blocking the request outright.
+            # The hostname was already checked against
+            # _BLOCKED_HOSTNAMES above so metadata endpoints remain
+            # blocked regardless.  Literal IPs never qualify — they
+            # need no DNS, so a getaddrinfo failure on one is not a
+            # proxy-environment symptom; keep them on the fail-closed
+            # path (and the blocked-IP floor) instead of delegating.
+            _is_literal_ip = True
+            try:
+                ipaddress.ip_address(hostname)
+            except ValueError:
+                _is_literal_ip = False
+            if not _is_literal_ip and _proxy_is_configured():
+                logger.debug(
+                    "DNS resolution failed for %s — proxy configured, "
+                    "allowing through for proxy-side resolution",
+                    hostname,
+                )
+                return True
             logger.warning("Blocked request — DNS resolution failed for: %s", hostname)
             return False
 
diff --git a/tools/voice_mode.py b/tools/voice_mode.py
index e3162e06e56..ca35a2b2e7e 100644
--- a/tools/voice_mode.py
+++ b/tools/voice_mode.py
@@ -72,7 +72,7 @@ def _termux_api_app_installed() -> bool:
         result = subprocess.run(
             ["pm", "list", "packages", "com.termux.api"],
             capture_output=True,
-            text=True,
+            text=True, encoding='utf-8', errors='replace',
             timeout=5,
             check=False,
             stdin=subprocess.DEVNULL,
@@ -389,7 +389,7 @@ class TermuxAudioRecorder:
             "-c", str(CHANNELS),
         ]
         try:
-            subprocess.run(command, capture_output=True, text=True, timeout=15, check=True, stdin=subprocess.DEVNULL)
+            subprocess.run(command, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=15, check=True, stdin=subprocess.DEVNULL)
         except subprocess.CalledProcessError as e:
             details = (e.stderr or e.stdout or str(e)).strip()
             raise RuntimeError(f"Termux microphone start failed: {details}") from e
@@ -406,7 +406,7 @@ class TermuxAudioRecorder:
         mic_cmd = _termux_microphone_command()
         if not mic_cmd:
             return
-        subprocess.run([mic_cmd, "-q"], capture_output=True, text=True, timeout=15, check=False, stdin=subprocess.DEVNULL)
+        subprocess.run([mic_cmd, "-q"], capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=15, check=False, stdin=subprocess.DEVNULL)
 
     def stop(self) -> Optional[str]:
         with self._lock:
diff --git a/tools/web_tools.py b/tools/web_tools.py
index 7754c386a56..131c0030365 100644
--- a/tools/web_tools.py
+++ b/tools/web_tools.py
@@ -422,7 +422,7 @@ def _web_requires_env() -> list[str]:
 DEFAULT_EXTRACT_CHAR_LIMIT = 15000
 
 # Hard ceiling on the full-text file written to cache/web. The truncate-store
-# path otherwise calls path.write_text(content) with no upper bound, so a
+# path otherwise calls path.write_text(content, encoding="utf-8") with no upper bound, so a
 # multi-MB page (some backends return very large markdown) writes unbounded
 # bytes to disk on every extract. Cap the stored copy; the model only ever
 # sees char_limit anyway, and a 2MB page is already far more than any single
diff --git a/tools/x_search_tool.py b/tools/x_search_tool.py
index 87de533dd4a..8a89ead21ca 100644
--- a/tools/x_search_tool.py
+++ b/tools/x_search_tool.py
@@ -480,9 +480,12 @@ X_SEARCH_SCHEMA = {
     "name": "x_search",
     "description": (
         "Search X (Twitter) posts, profiles, and threads using xAI's built-in "
-        "X Search tool. Use this for current discussion, reactions, or claims "
-        "on X rather than general web pages. Available when xAI credentials "
-        "are configured (SuperGrok OAuth or XAI_API_KEY)."
+        "X Search tool. Read-only discovery only: use this for current "
+        "discussion, reactions, or claims on public X rather than general web "
+        "pages. Do not use it to post, reply, like, DM, upload media, delete, "
+        "or inspect the user's authenticated X account — those require a "
+        "separate authenticated X API surface outside this tool. Available "
+        "when xAI credentials are configured (SuperGrok OAuth or XAI_API_KEY)."
     ),
     "parameters": {
         "type": "object",
diff --git a/tools/xai_http.py b/tools/xai_http.py
index 8d80ae1bbd4..6d5287e4d86 100644
--- a/tools/xai_http.py
+++ b/tools/xai_http.py
@@ -44,7 +44,7 @@ def has_xai_credentials() -> bool:
         auth_path = get_hermes_home() / "auth.json"
         if not auth_path.exists():
             return False
-        store = json.loads(auth_path.read_text())
+        store = json.loads(auth_path.read_text(encoding="utf-8"))
         providers = store.get("providers") if isinstance(store, dict) else None
         xai_state = providers.get("xai-oauth") if isinstance(providers, dict) else None
         tokens = xai_state.get("tokens") if isinstance(xai_state, dict) else None
@@ -234,7 +234,7 @@ def maybe_mark_xai_storage_notice_seen(section_name: str) -> Optional[str]:
         marker = marker_dir / f"{section_name}_xai_storage_notice_seen"
         if marker.exists():
             return None
-        marker.write_text(datetime.datetime.now(datetime.UTC).isoformat() + "\n")
+        marker.write_text(datetime.datetime.now(datetime.UTC).isoformat() + "\n", encoding="utf-8")
         return notice
     except Exception:
         return notice
diff --git a/toolsets.py b/toolsets.py
index 5cd53fa7240..75219f719cf 100644
--- a/toolsets.py
+++ b/toolsets.py
@@ -110,9 +110,11 @@ TOOLSETS = {
     "x_search": {
         "description": (
             "Search X (Twitter) posts and threads via xAI's built-in "
-            "x_search Responses tool. Available when xAI credentials are "
-            "configured (SuperGrok OAuth or XAI_API_KEY). Off by default; "
-            "enable in `hermes tools` → X (Twitter) Search."
+            "x_search Responses tool. Read-only public X discovery; use the "
+            "xurl skill for authenticated X API reads and account actions. "
+            "Available when xAI credentials are configured (SuperGrok OAuth "
+            "or XAI_API_KEY). Off by default; enable in `hermes tools` → "
+            "X (Twitter) Search."
         ),
         "tools": ["x_search"],
         "includes": []
diff --git a/trajectory_compressor.py b/trajectory_compressor.py
index ca1c86c5b68..83248983a2c 100644
--- a/trajectory_compressor.py
+++ b/trajectory_compressor.py
@@ -831,6 +831,18 @@ Write only the summary, starting with "[CONTEXT SUMMARY]:" prefix."""
             metrics.still_over_limit = total_tokens > self.config.target_max_tokens
             return trajectory, metrics
 
+        # If the region we can safely compress is no larger than the summary
+        # that would replace it, compression cannot reduce the token count --
+        # it would grow the trajectory and still spend a summarization call.
+        if (
+            sum(turn_tokens[compress_start:compress_until])
+            <= self.config.summary_target_tokens
+        ):
+            metrics.compressed_tokens = total_tokens
+            metrics.compressed_turns = len(trajectory)
+            metrics.still_over_limit = total_tokens > self.config.target_max_tokens
+            return trajectory, metrics
+
         # Record compression region
         metrics.turns_compressed_start_idx = compress_start
         metrics.turns_compressed_end_idx = compress_until
@@ -946,6 +958,18 @@ Write only the summary, starting with "[CONTEXT SUMMARY]:" prefix."""
             metrics.still_over_limit = total_tokens > self.config.target_max_tokens
             return trajectory, metrics
 
+        # If the region we can safely compress is no larger than the summary
+        # that would replace it, compression cannot reduce the token count --
+        # it would grow the trajectory and still spend a summarization call.
+        if (
+            sum(turn_tokens[compress_start:compress_until])
+            <= self.config.summary_target_tokens
+        ):
+            metrics.compressed_tokens = total_tokens
+            metrics.compressed_turns = len(trajectory)
+            metrics.still_over_limit = total_tokens > self.config.target_max_tokens
+            return trajectory, metrics
+
         # Record compression region
         metrics.turns_compressed_start_idx = compress_start
         metrics.turns_compressed_end_idx = compress_until
diff --git a/tui_gateway/compute_host.py b/tui_gateway/compute_host.py
index 9ff3e100cb3..102d8e6d47b 100644
--- a/tui_gateway/compute_host.py
+++ b/tui_gateway/compute_host.py
@@ -113,6 +113,8 @@ def _build_sha() -> str:
             ["git", "rev-parse", "HEAD"],
             cwd=str(_repo_root()),
             text=True,
+            encoding="utf-8",
+            errors="replace",
             stderr=subprocess.DEVNULL,
             timeout=2,
         ).strip()
@@ -686,7 +688,7 @@ class ComputeHost:
 
 def _rss_mb(pid: int) -> float:
     try:
-        out = subprocess.check_output(["ps", "-o", "rss=", "-p", str(pid)], text=True, stdin=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=2).strip()
+        out = subprocess.check_output(["ps", "-o", "rss=", "-p", str(pid)], text=True, encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=2).strip()
         return int(out.splitlines()[-1].strip()) / 1024.0 if out else 0.0
     except Exception:
         return 0.0
diff --git a/tui_gateway/host_supervisor.py b/tui_gateway/host_supervisor.py
index 2541e27a777..dc81656f8c3 100644
--- a/tui_gateway/host_supervisor.py
+++ b/tui_gateway/host_supervisor.py
@@ -72,6 +72,8 @@ def _build_sha() -> str:
             ["git", "rev-parse", "HEAD"],
             cwd=str(_repo_root()),
             text=True,
+            encoding="utf-8",
+            errors="replace",
             stderr=subprocess.DEVNULL,
             timeout=2,
         ).strip()
@@ -112,6 +114,8 @@ def _pid_command(pid: int) -> str:
         return subprocess.check_output(
             ["ps", "-p", str(pid), "-o", "command="],
             text=True,
+            encoding="utf-8",
+            errors="replace",
             stderr=subprocess.DEVNULL,
             timeout=2,
         ).strip()
@@ -327,6 +331,11 @@ class HostSupervisor:
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             text=True,
+            # Lossy UTF-8 decode — the compute host emits UTF-8; a
+            # locale-mismatched byte must not raise inside the drain
+            # threads and kill the supervisor (#52649).
+            encoding="utf-8",
+            errors="replace",
             bufsize=1,
             start_new_session=True,
         )
diff --git a/tui_gateway/project_tree.py b/tui_gateway/project_tree.py
index 3f243153964..545600eaf6c 100644
--- a/tui_gateway/project_tree.py
+++ b/tui_gateway/project_tree.py
@@ -34,6 +34,13 @@ from typing import Any, Callable, Optional
 # cwd is not in a git repo (or cannot be probed, e.g. a remote backend).
 Resolve = Callable[[str], Optional[dict]]
 
+# A "does this directory still exist?" predicate, injected for the same reason
+# ``Resolve`` is: the builder stays pure and unit-testable. Defaults to assuming
+# everything exists, which preserves the previous behavior for callers that
+# can't stat (remote backends), where guessing "gone" would wrongly hide a
+# project that lives on the other host.
+Exists = Callable[[str], bool]
+
 # Only KANBAN-TASK worktrees (`<repo>/.worktrees/t_<hex>`, the `t_…` id kanban_db
 # mints) collapse into one lane; user-named "New worktree" dirs under
 # `.worktrees/` stay as their own lanes.
@@ -41,6 +48,11 @@ _KANBAN_DIR_RE = re.compile(r"^(.*[/\\]\.worktrees)[/\\]t_[0-9a-f]+[/\\]?$")
 _TRUNK_BRANCHES = {"main", "master", "trunk", "develop"}
 DEFAULT_BRANCH_LABEL = "main"
 
+# How many sibling candidates to try when recovering a deleted worktree's parent
+# repo (see ``_probe_sibling_worktree``). Each miss costs a git probe, so keep it
+# tight — real suffixes are one or two segments.
+_MAX_SIBLING_PROBES = 4
+
 
 def _branch_lane_id(repo_root: str, branch: str = "") -> str:
     """The one definition of a main-checkout lane id (must match the desktop)."""
@@ -146,6 +158,44 @@ def _placement(
     }
 
 
+def _parent_dir(path: str) -> str:
+    """The containing directory of ``path`` (``""`` once the root is passed)."""
+    stripped = re.sub(r"[/\\]+$", "", path or "")
+    return re.sub(r"[/\\]+$", "", re.sub(r"[^/\\]+$", "", stripped))
+
+
+def _probe_sibling_worktree(cwd: str, resolve: Resolve) -> str:
+    """The parent repo root of a deleted ``<repo>-<suffix>`` worktree, else ``""``.
+
+    A deleted worktree dir can't be probed, so walk back up its name — trimming
+    one ``-<segment>`` at a time — and return the first sibling that resolves.
+
+    The session's cwd is frequently a SUBDIR of the deleted worktree (an agent
+    that ``cd``-ed into ``<repo>-<suffix>/apps/desktop``), whose basename shares
+    nothing with the repo. So the trim is applied to each ANCESTOR, deepest
+    first, not just to the leaf — otherwise the probe silently no-ops and the
+    dead path gets minted as its own top-level project. Probes are bounded in
+    total (each costs a git invocation) and served from the shared probe cache.
+    """
+    probes = 0
+    path = re.sub(r"[/\\]+$", "", cwd or "")
+
+    while path and probes < _MAX_SIBLING_PROBES:
+        parts = base_name(path).split("-")
+
+        for i in range(len(parts) - 1, 0, -1):
+            if probes >= _MAX_SIBLING_PROBES:
+                break
+            probes += 1
+            info = resolve(_with_base_name(path, "-".join(parts[:i])))
+            if info and info.get("repo_root"):
+                return (info["repo_root"] or "").strip()
+
+        path = _parent_dir(path)
+
+    return ""
+
+
 def _place_by_heuristic(path: str) -> Optional[dict]:
     """Path-only fallback when there is no git probe and no persisted root."""
     base = base_name(path)
@@ -195,6 +245,14 @@ def _place(cwd: str, branch: str, resolve: Optional[Resolve], persisted_root: st
         b = (branch or "").strip() or DEFAULT_BRANCH_LABEL
         return _placement(persisted_root, _branch_lane_id(persisted_root, b), b, persisted_root, True, False)
 
+    # Unresolvable cwd: a deleted ``<repo>-<suffix>`` worktree still belongs to
+    # its parent. It has no checkout to return to, so absorb it into the trunk
+    # lane rather than stranding a dead-path lane in the project forever.
+    sibling_root = _probe_sibling_worktree(cwd, resolve) if resolve else ""
+    if sibling_root:
+        b = (branch or "").strip() or DEFAULT_BRANCH_LABEL
+        return _placement(sibling_root, _branch_lane_id(sibling_root, b), b, sibling_root, True, False)
+
     return _place_by_heuristic(cwd)
 
 
@@ -475,6 +533,7 @@ def build_tree(
     hydrate: bool = False,
     is_junk_root: Optional[Callable[[str], bool]] = None,
     is_junk_cwd: Optional[Callable[[str], bool]] = None,
+    exists: Optional[Exists] = None,
 ) -> dict:
     """Build the authoritative project tree.
 
@@ -486,7 +545,10 @@ def build_tree(
     bare home dir, the HERMES_HOME subtree). ``is_junk_cwd`` is the narrower
     policy for non-git session folders: selected descendants may be intentional
     workspaces even when their parent tree contains Hermes state. User-created
-    projects are honored regardless.
+    projects are honored regardless. ``exists`` reports whether a directory is
+    still on disk, so a session whose workspace was DELETED (a removed worktree,
+    a scratch dir under /tmp) doesn't get promoted to a phantom AUTO project;
+    omit it (remote backends) to keep every candidate.
 
     Returns ``{"projects": [...], "scoped_session_ids": [...]}``. When
     ``hydrate`` is False (overview), lane ``sessions`` arrays are emptied but
@@ -496,6 +558,7 @@ def build_tree(
     active_projects = [p for p in projects if not p.get("archived")]
     _junk = is_junk_root or (lambda _root: False)
     _junk_cwd = is_junk_cwd or (lambda _cwd: False)
+    _exists = exists or (lambda _path: True)
     folder_index = _FolderIndex(active_projects)
 
     by_project: dict[str, list[dict]] = {}
@@ -558,8 +621,10 @@ def build_tree(
         root = _session_repo_root(session, resolve)
         if root:
             # A real git root uses the stricter repo policy. Do not reinterpret a
-            # filtered internal repo as a cwd-only project.
-            if not _junk(root):
+            # filtered internal repo as a cwd-only project. A root that no longer
+            # exists is a stale persisted value (the repo was deleted after the
+            # session ran) and must not resurrect as a project.
+            if not _junk(root) and _exists(root):
                 _add_auto(root, session)
             continue
 
@@ -572,7 +637,13 @@ def build_tree(
             resolve,
             (session.get("git_repo_root") or "").strip(),
         )
-        if placement:
+        # A placement that only echoes back the unresolvable cwd is the
+        # path-only heuristic guessing — it never found a repo. When that dir is
+        # also gone from disk (a deleted worktree whose name shares no prefix
+        # with its parent, a removed /tmp scratch dir), promoting it mints a
+        # phantom project that can never be opened and can only be dismissed by
+        # hand. The session keeps its place in flat Recents.
+        if placement and _exists(placement["repo_key"]):
             _add_auto(placement["repo_key"], session)
 
     seen: set[str] = set()
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index e91e8e362b7..d5277dadca9 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -29,6 +29,11 @@ from utils import is_truthy_value
 from tools.environments.local import hermes_subprocess_env
 from agent.replay_cleanup import sanitize_replay_history
 from tui_gateway import git_probe
+from tui_gateway.turn_marker import (
+    clear_turn_marker,
+    read_turn_marker,
+    record_turn_start,
+)
 from tui_gateway.transport import (
     StdioTransport,
     Transport,
@@ -351,6 +356,12 @@ class _SlashWorker:
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             text=True,
+            # Force UTF-8 with lossy decoding so child output containing bytes
+            # that are invalid in the system locale (e.g. GBK on Chinese
+            # Windows) can't raise UnicodeDecodeError inside the drain threads
+            # and crash the gateway. See #53137.
+            encoding="utf-8",
+            errors="replace",
             bufsize=1,
             cwd=os.getcwd(),
             env=env,
@@ -679,20 +690,22 @@ def _finalize_session(session: dict | None, end_reason: str = "tui_close") -> No
     _tui_owns_lifecycle = True
     if session_id:
         try:
-            db = _get_db()
-            if db is not None:
-                # Don't end gateway-originated sessions — the gateway owns
-                # their lifecycle.  The TUI is a viewer, not the owner.
-                # Ending a gateway session in state.db triggers a Groundhog
-                # Day routing loop: the gateway's #54878 self-heal detects
-                # the stale entry, recovers to the parent session, context
-                # compression splits back to the reaped child, and the cycle
-                # repeats on every inbound message.  (#60609)
-                row = db.get_session(session_id)
-                source = (row or {}).get("source", "")
-                _tui_owns_lifecycle = not _is_gateway_owned_source(source)
-                if _tui_owns_lifecycle:
-                    db.end_session(session_id, end_reason)
+            # End the row in the *session's* profile state.db (app-global
+            # remote mode), not the launch profile's shared handle.
+            with _session_db(session) as db:
+                if db is not None:
+                    # Don't end gateway-originated sessions — the gateway owns
+                    # their lifecycle.  The TUI is a viewer, not the owner.
+                    # Ending a gateway session in state.db triggers a Groundhog
+                    # Day routing loop: the gateway's #54878 self-heal detects
+                    # the stale entry, recovers to the parent session, context
+                    # compression splits back to the reaped child, and the cycle
+                    # repeats on every inbound message.  (#60609)
+                    row = db.get_session(session_id)
+                    source = (row or {}).get("source", "")
+                    _tui_owns_lifecycle = not _is_gateway_owned_source(source)
+                    if _tui_owns_lifecycle:
+                        db.end_session(session_id, end_reason)
         except Exception:
             pass
 
@@ -1068,6 +1081,63 @@ def _get_db():
     return _db
 
 
+def _db_for_profile(profile: str | None = None):
+    """Return SessionDB for ``params.profile`` when it differs from launch.
+
+    App-global remote mode passes ``profile`` on session.* RPCs so history/list/
+    create operate on that profile's ``state.db``. Launch/own profile → shared
+    ``_get_db()`` handle (left open). Non-launch profile → a dedicated handle
+    the caller should ``close()`` (see :func:`_profile_db` contextmanager).
+
+    Returns (db, owns_handle). ``db`` is None when unavailable.
+    """
+    profile_home = _profile_home(profile)
+    if profile_home is None:
+        return _get_db(), False
+    try:
+        from hermes_state import SessionDB
+
+        return SessionDB(db_path=Path(profile_home) / "state.db"), True
+    except Exception as exc:
+        logger.warning(
+            "TUI profile session store unavailable for %s: %s",
+            profile,
+            exc,
+        )
+        return None, False
+
+
+@contextlib.contextmanager
+def _profile_db(params: dict | None = None):
+    """Yield the SessionDB for ``params['profile']`` (app-global remote mode).
+
+    Closes dedicated profile handles; leaves the launch-profile shared handle open.
+    Yields None when the db is unavailable.
+    """
+    profile = None
+    if isinstance(params, dict):
+        profile = (params.get("profile") or "").strip() or None
+    db, owns = _db_for_profile(profile)
+    try:
+        yield db
+    finally:
+        if owns and db is not None:
+            with contextlib.suppress(Exception):
+                db.close()
+
+
+def _response_profile_name(profile: str | None = None) -> str:
+    """Profile name to report on session.* payloads.
+
+    Prefer the RPC's requested profile when it is a real non-launch profile;
+    otherwise the process launch profile.
+    """
+    name = (profile or "").strip()
+    if name and _profile_home(name) is not None:
+        return name
+    return _current_profile_name()
+
+
 def _db_unavailable_error(rid, *, code: int):
     detail = _db_error or "state.db unavailable"
     return _err(rid, code, f"state.db unavailable: {detail}")
@@ -1611,6 +1681,124 @@ def _wait_agent(session: dict, rid: str, timeout: float = 30.0) -> dict | None:
     return _err(rid, 5032, err) if err else None
 
 
+# The deferred prompt path waits in short slices so a cancel is honored
+# promptly and a slow build can be reported to the client exactly once.
+_AGENT_BUILD_WAIT_SLICE = 5.0
+_AGENT_BUILD_SLOW_NOTICE_AFTER = 30.0
+_AGENT_BUILD_SLOW_NOTICE_KEY = "agent-build-slow"
+
+
+def _agent_build_wait_cap() -> float:
+    """Upper bound (seconds) a submitted prompt waits for the deferred agent
+    build before failing permanently. ``agent.build_wait_timeout`` in
+    config.yaml overrides the 600s default (raise it for deployments with
+    many slow/unreachable MCP servers or high-latency provider metadata)."""
+    try:
+        agent_cfg = _load_cfg().get("agent") or {}
+        raw = agent_cfg.get("build_wait_timeout")
+        if raw is not None:
+            value = float(raw)
+            if value > 0:
+                return value
+    except Exception:
+        pass
+    return 600.0
+
+
+def _wait_agent_for_prompt(session: dict, rid: str, sid: str) -> dict | None:
+    """Patient variant of ``_wait_agent`` for the deferred prompt.submit path.
+
+    The flat 30s ``_wait_agent`` ceiling was a message-eating cliff (#63078):
+    ``prompt.submit`` has already returned ``{"status": "streaming"}``, the
+    user's first message IS the turn in flight, and the deferred agent build
+    (MCP discovery with per-server retry backoff, synchronous model-metadata
+    HTTP, skills scanning) routinely outlives 30 seconds on cold starts. On
+    timeout the old path emitted an error EVENT and returned without ever
+    calling ``_run_prompt_submit`` — the first message was permanently
+    discarded while the build finished successfully in the background, leaving
+    the blank first session.
+
+    This wait instead:
+      - keeps the pending prompt attached to this (already off-RPC) thread and
+        delivers it the moment the still-running build completes;
+      - waits in short slices so a cancel (session.interrupt / session churn)
+        is honored promptly instead of after the full timeout;
+      - tells the client once, via a keyed notice, when the build outlives
+        ``_AGENT_BUILD_SLOW_NOTICE_AFTER`` — the wait is patient but never
+        silent;
+      - fails permanently only when the build itself fails: the build thread
+        died without signalling ready, or the bounded cap
+        (``agent.build_wait_timeout``, default 600s — no infinite waits)
+        expired on a genuinely hung build.
+
+    Returns ``None`` on success OR when the turn was cancelled mid-wait (the
+    caller's cancel branch owns that messaging), an ``_err`` dict otherwise.
+    """
+    ready = session.get("agent_ready")
+    if ready is None:
+        return None
+    start = time.monotonic()
+    cap = _agent_build_wait_cap()
+    notified_slow = False
+    while not ready.wait(timeout=_AGENT_BUILD_WAIT_SLICE):
+        with session["history_lock"]:
+            cancelled = session.get("_turn_cancel_requested") or not session.get(
+                "running"
+            )
+        if cancelled:
+            # The caller's cancel/not-running branch emits the user-visible
+            # event for this — bail without an error of our own.
+            return None
+        waited = time.monotonic() - start
+        if waited >= cap:
+            return _err(
+                rid,
+                5032,
+                f"agent initialization timed out after {int(waited)}s — "
+                "your message was not sent; retry once the session is ready",
+            )
+        build_thread = session.get("_agent_build_thread")
+        if (
+            build_thread is not None
+            and not build_thread.is_alive()
+            and not ready.is_set()
+        ):
+            # _build's ``finally`` guarantees ready.set(); a dead thread with
+            # ready still unset means the build died hard (interpreter-level
+            # kill) — don't wait on a corpse for the rest of the cap.
+            return _err(
+                rid,
+                5032,
+                session.get("agent_error")
+                or "agent initialization failed before completing",
+            )
+        if not notified_slow and waited >= _AGENT_BUILD_SLOW_NOTICE_AFTER:
+            # One keyed, replace-in-place notice: the desktop shows it as a
+            # toast, the TUI in its status bar. Without this the extended wait
+            # would be exactly the silent hang this function exists to fix.
+            notified_slow = True
+            _emit(
+                "notification.show",
+                sid,
+                {
+                    "text": (
+                        "Still starting the agent (tool discovery / model "
+                        "setup) — your message will be sent as soon as it's "
+                        "ready."
+                    ),
+                    "level": "info",
+                    "kind": "agent",
+                    "ttl_ms": None,
+                    "key": _AGENT_BUILD_SLOW_NOTICE_KEY,
+                    "id": _AGENT_BUILD_SLOW_NOTICE_KEY,
+                },
+            )
+    if notified_slow:
+        _emit("notification.clear", sid, {"key": _AGENT_BUILD_SLOW_NOTICE_KEY})
+    err = session.get("agent_error")
+    return _err(rid, 5032, err) if err else None
+
+
 def _start_agent_build(sid: str, session: dict) -> None:
     """Start building the real AIAgent for a TUI session, once.
 
@@ -1704,15 +1892,15 @@ def _start_agent_build(sid: str, session: dict) -> None:
             # override is still active here.
             current["config_model_seen"] = _config_model_target()
 
-            try:
-                worker = _SlashWorker(
-                    key,
-                    getattr(agent, "model", _resolve_model()),
-                    profile_home=current.get("profile_home"),
-                )
-                _attach_worker(sid, current, worker)
-            except Exception:
-                pass
+            # No eager slash-worker pre-warm: slash.exec spawns one on demand
+            # (its error path already relies on that respawn to recover from a
+            # dead worker). Each worker child runs its own MCP discovery
+            # (#61891), so pre-warming one per session forks the full stdio
+            # MCP fleet — ~20 OS processes per retained session on a config
+            # with a few stdio servers — even for sessions that never run a
+            # worker-routed command. Sessions held by a live transport are
+            # never reaped, so with the desktop app open for days those
+            # fleets accumulate until the OS refuses new process spawns.
 
             try:
                 from tools.approval import (
@@ -1787,7 +1975,12 @@ def _start_agent_build(sid: str, session: dict) -> None:
                     pass
             ready.set()
 
-    threading.Thread(target=_build, daemon=True).start()
+    build_thread = threading.Thread(target=_build, daemon=True)
+    # Handle for _wait_agent_for_prompt: a dead build thread with agent_ready
+    # still unset means the build died hard — waiters must not sit out the
+    # full cap on a corpse.
+    session["_agent_build_thread"] = build_thread
+    build_thread.start()
 
 
 def _sess_nowait(params, rid):
@@ -1899,6 +2092,28 @@ def _session_cwd(session: dict | None) -> str:
     return _completion_cwd()
 
 
+# Sources whose launch directory is an artifact of how the app was started, not
+# a workspace the user picked. Everything else is terminal-started: the process
+# runs in a directory the user deliberately cd'd into.
+_LAUNCH_CWD_NOT_A_WORKSPACE = {"desktop"}
+
+
+def _persisted_session_cwd(session: dict) -> str | None:
+    """The cwd to stamp on the session's DB row, or None to leave it unset.
+
+    See :func:`_ensure_session_db_row` for why the launch directory counts as a
+    workspace for terminal sessions but not for the desktop.
+    """
+    if session.get("explicit_cwd"):
+        return _session_cwd(session)
+    if _session_source(session) in _LAUNCH_CWD_NOT_A_WORKSPACE:
+        return None
+    # Only the session's OWN directory. `_session_cwd` falls back to the
+    # gateway-wide completion cwd, which belongs to no session in particular —
+    # stamping that would invent a workspace for a session that never had one.
+    return str(session.get("cwd") or "") or None
+
+
 def _heal_dead_cwd(cwd: str) -> str:
     """Resolve a session cwd that points at a now-deleted directory.
 
@@ -1968,6 +2183,80 @@ def _display_session_cwd(session: dict | None) -> str:
     return healed
 
 
+def _reconcile_session_cwd_from_terminal(session: dict | None) -> bool:
+    """Re-anchor a session that SETTLED in another git checkout. Returns moved.
+
+    An agent told to work in a fresh worktree does exactly that — `git worktree
+    add`, `cd` into it, and every later command runs there — but the session
+    stayed pinned to wherever it started, so the desktop kept labelling the chat
+    with the primary checkout's branch while all the work landed elsewhere.
+
+    A plain `cd` is deliberately NOT a workspace move (see
+    ``_apply_project_workspace``): browsing to /tmp to read a log must not
+    re-home the chat. What we adopt here is narrower — the session's recorded
+    cwd is in a DIFFERENT git working tree than its workspace. That is a
+    relocation by any reading, and it is the only shape this reconciles.
+
+    Local backends only: a remote/SSH cwd names a path on the host, which this
+    gateway can neither stat nor probe with git.
+    """
+    if not session or not _is_local_terminal_backend():
+        return False
+
+    try:
+        from tools.terminal_tool import get_session_cwd
+
+        recorded = get_session_cwd(session.get("session_key") or "")
+    except Exception:
+        return False
+
+    if not recorded:
+        return False
+
+    resolved = os.path.abspath(os.path.expanduser(str(recorded)))
+    current = os.path.abspath(os.path.expanduser(_session_cwd(session)))
+    if resolved == current or not os.path.isdir(resolved):
+        return False
+
+    # The worktree ROOT, not the common repo root: folding worktrees together
+    # here is exactly what hides the move we're looking for.
+    landed = _git_repo_root_for_cwd(resolved)
+    if not landed or landed == _git_repo_root_for_cwd(current):
+        return False
+
+    session["cwd"] = resolved
+    # The session works here now, so this is its workspace — a desktop chat
+    # whose cwd was an unpersisted launch artifact earns a real row.
+    session["explicit_cwd"] = True
+    _register_session_cwd(session)
+
+    with _session_db(session) as db:
+        if db is not None:
+            try:
+                db.update_session_cwd(session.get("session_key", ""), resolved)
+            except Exception:
+                logger.debug("failed to persist settled session cwd", exc_info=True)
+
+    _persist_session_git_meta(session, resolved)
+    return True
+
+
+def _emit_settled_session_info(sid: str, session: dict, agent) -> None:
+    """Emit end-of-turn ``session.info``, reconciling a settled cwd first.
+
+    The turn is over, so the agent has stopped moving: this is the one moment
+    where its recorded cwd is a stable answer to "where does this session
+    work". Reconciling before building the payload means the same event that
+    already tells the desktop the turn ended also carries the new cwd/branch —
+    the client follows it with no new event type and no extra round trip.
+    """
+    try:
+        _reconcile_session_cwd_from_terminal(session)
+    except Exception:
+        logger.debug("failed to reconcile settled session cwd", exc_info=True)
+    _emit("session.info", sid, _session_info(agent, session))
+
+
 def _session_source(session: dict | None) -> str:
     if session:
         source = str(session.get("source") or "").strip()
@@ -1997,12 +2286,19 @@ def _ensure_session_db_row(session: dict) -> None:
     Uses INSERT OR IGNORE under the hood, so re-calls (and the AIAgent's own
     lazy create) are no-ops.
 
-    Only an *explicitly chosen* workspace is persisted as the session's cwd.
-    The agent still runs in the auto-detected directory (session["cwd"]), but
-    we don't stamp that onto the row — otherwise every session the user never
-    picked a folder for gets grouped under whatever directory the desktop
-    happened to launch in (e.g. "desktop"). Leaving it null groups them under
-    "No workspace", which is the desired default.
+    A cwd the user *chose* is always persisted. When they made no explicit
+    choice the launch directory stands in, and whether that is meaningful
+    depends on how the session was started:
+
+    * The desktop launches from wherever the app bundle was opened (often ``/``
+      or the user's home), so stamping that would file every unpicked chat under
+      a folder the user never chose. Those stay null and group under "No
+      workspace", which is the desired default.
+    * A terminal session (``hermes`` / ``hermes --tui`` / CLI) is started from a
+      directory the user deliberately ``cd``'d into — that IS the workspace, and
+      it is also where the agent's terminal actually runs. Dropping it stranded
+      the session with no cwd AND no git_repo_root, so the sidebar could never
+      place it under its project.
     """
     key = session.get("session_key")
     if not key:
@@ -2060,7 +2356,8 @@ def _ensure_session_db_row(session: dict) -> None:
             from hermes_cli.runtime_provider import canonical_custom_identity
 
             healed = canonical_custom_identity(
-                base_url=model_config.get("base_url") or None
+                base_url=model_config.get("base_url") or None,
+                model=model_config.get("model") or row_model or None,
             )
             if healed:
                 model_config["provider"] = healed
@@ -2090,7 +2387,11 @@ def _ensure_session_db_row(session: dict) -> None:
             model=row_model,
             model_config=model_config or None,
             parent_session_id=parent_session_id,
-            cwd=_session_cwd(session) if session.get("explicit_cwd") else None,
+            cwd=_persisted_session_cwd(session),
+            # Self-describing rows: aggregators that merge multiple profile DBs
+            # into one list can't rely on which file a row came from alone. NULL
+            # means the launch/default profile (matches run_agent's convention).
+            profile_name=Path(profile_home).name if profile_home else None,
         )
     except Exception:
         logger.debug("failed to persist desktop session row", exc_info=True)
@@ -2381,13 +2682,27 @@ def _set_session_context(
         # it instead of falling back to the gateway launch dir.
         resolved = cwd if cwd is not None else _cwd_for_session_key(session_key)
         source = _resolve_session_platform()
+        # Derive the live conversation id so terminal/execute_code subprocesses
+        # can read HERMES_SESSION_ID. Without this, set_session_vars leaves the
+        # session-id contextvar as "" (explicitly empty), and the subprocess-env
+        # bridge treats that as authoritative — NOT falling back to os.environ —
+        # so every command in a dashboard/TUI/web session saw an empty
+        # HERMES_SESSION_ID even though agent_init set it via
+        # set_current_session_id(). Prefer the agent's durable session_id, then
+        # fall back to the session_key (matching the id derivation used at
+        # session-finalize), so an identified session is never left blank.
+        session_id = session_key
         with _sessions_lock:
             for sess in list(_sessions.values()):
                 if sess.get("session_key") == session_key:
                     source = _session_source(sess)
+                    session_id = (
+                        getattr(sess.get("agent"), "session_id", None) or session_key
+                    )
                     break
         return set_session_vars(
             session_key=session_key,
+            session_id=session_id,
             source=source,
             cwd=resolved,
             ui_session_id=ui_session_id,
@@ -2776,9 +3091,10 @@ def _stored_session_runtime_overrides(row: dict | None) -> dict:
     # the resolved billing class, not a routable identity — restoring it as the
     # session's provider override routes the resume to the OpenRouter default
     # URL with no api_key, surfacing as "No LLM provider configured". Recover
-    # the durable ``custom:<name>`` menu key from the stored base_url, falling
-    # back to the configured provider when the row has no base_url (the
-    # recurring Desktop/TUI regression vector). If neither names a real entry,
+    # the durable ``custom:<name>`` menu key from the stored base_url, then
+    # from the entry that serves the stored model, falling back to the
+    # configured provider when the row has neither (the recurring Desktop/TUI
+    # regression vector). If none names a real entry,
     # drop the bare provider entirely so resume falls back to the configured
     # default rather than the broken OpenRouter route.
     if provider.strip().lower() == "custom":
@@ -2786,7 +3102,9 @@ def _stored_session_runtime_overrides(row: dict | None) -> dict:
         try:
             from hermes_cli.runtime_provider import canonical_custom_identity
 
-            healed = canonical_custom_identity(base_url=base_url or None)
+            healed = canonical_custom_identity(
+                base_url=base_url or None, model=model or None
+            )
         except Exception:
             logger.debug(
                 "custom provider identity recovery failed", exc_info=True
@@ -2850,7 +3168,10 @@ def _runtime_model_config(agent, existing: dict | None = None) -> dict:
                 )
 
                 provider = (
-                    canonical_custom_identity(base_url=base_url) or provider
+                    canonical_custom_identity(
+                        base_url=base_url, model=model or None
+                    )
+                    or provider
                 )
             except Exception:
                 logger.debug(
@@ -3323,11 +3644,16 @@ def _tool_lifecycle_required_for_ui(name: str) -> bool:
 
 def _restart_slash_worker(sid: str, session: dict):
     worker = session.get("slash_worker")
-    if worker:
-        try:
-            worker.close()
-        except Exception:
-            pass
+    # A session that never spawned a worker has nothing stale to replace —
+    # the next slash.exec builds one with the current session key/model.
+    # Spawning here would fork the per-worker stdio MCP fleet for sessions
+    # that never use worker-routed commands.
+    if worker is None:
+        return
+    try:
+        worker.close()
+    except Exception:
+        pass
     try:
         new_worker = _SlashWorker(
             session["session_key"],
@@ -4114,7 +4440,13 @@ def _session_info(agent, session: dict | None = None) -> dict:
         "update_behind": None,
         "update_command": "",
         "usage": _session_usage_snapshot(session),
-        "profile_name": _current_profile_name(),
+        "profile_name": _response_profile_name(
+            Path(session["profile_home"]).name
+            if isinstance(session, dict) and session.get("profile_home")
+            else None
+        )
+        if isinstance(session, dict) and session.get("profile_home")
+        else _current_profile_name(),
     }
     try:
         from hermes_cli import __version__, __release_date__
@@ -4438,6 +4770,43 @@ def _on_tool_progress(
     if event_type == "moa.aggregating":
         _emit("moa.aggregating", sid, {"aggregator": str(name or "")})
         return
+    if event_type == "moa.progress":
+        # Per-reference completion — drives the status-bar progress indicator
+        # (`MOA: 2/3 refs done`) requested in issue #59546. Only emitted when
+        # both counters are present so the client can render deterministically.
+        refs_done = _kwargs.get("moa_refs_done")
+        refs_total = _kwargs.get("moa_refs_total")
+        if refs_done is None or refs_total is None:
+            return
+        _emit(
+            "moa.progress",
+            sid,
+            {
+                "label": str(name or ""),
+                "refs_done": int(refs_done),
+                "refs_total": int(refs_total),
+            },
+        )
+        return
+    if event_type == "moa.phase":
+        # Phase transition — currently only ``phase="aggregator"`` fires once
+        # the fan-out completes and the aggregator is about to act. Tells the
+        # client which phase of the MoA pipeline is currently running so it
+        # can swap status-bar copy accordingly.
+        phase = _kwargs.get("moa_phase")
+        if not phase:
+            return
+        phase_payload: dict[str, object] = {"phase": str(phase)}
+        refs_done = _kwargs.get("moa_refs_done")
+        refs_total = _kwargs.get("moa_refs_total")
+        if refs_done is not None:
+            phase_payload["refs_done"] = int(refs_done)
+        if refs_total is not None:
+            phase_payload["refs_total"] = int(refs_total)
+        if name:
+            phase_payload["aggregator"] = str(name)
+        _emit("moa.phase", sid, phase_payload)
+        return
     if event_type.startswith("subagent."):
         payload = {
             "goal": str(_kwargs.get("goal") or ""),
@@ -5343,7 +5712,9 @@ def _make_agent(
             # (the recurring Desktop/TUI regression vector).
             from hermes_cli.runtime_provider import canonical_custom_identity
 
-            recovered = canonical_custom_identity(base_url=override_base_url or None)
+            recovered = canonical_custom_identity(
+                base_url=override_base_url or None, model=model or None
+            )
             if recovered:
                 requested_provider = recovered
             if override_base_url:
@@ -5442,6 +5813,7 @@ def _init_session(
     cwd: str | None = None,
     session_db=None,
     source: str | None = None,
+    profile_home: str | None = None,
 ):
     now = time.time()
     with _sessions_lock:
@@ -5465,6 +5837,10 @@ def _init_session(
             "tool_progress_mode": _load_tool_progress_mode(),
             "edit_snapshots": {},
             "tool_started_at": {},
+            # Profile-scoped HERMES_HOME for app-global remote mode; None =
+            # launch profile. SessionBranch copies the parent's value so the
+            # child stays on the same state.db.
+            "profile_home": profile_home,
             # Per-session model override set by an in-session /model switch.
             # Honored on rebuild (/new, resume) so a switch in THIS session
             # never leaks into siblings via process-global env vars.
@@ -5473,35 +5849,48 @@ def _init_session(
             # session (stdio for Ink, JSON-RPC WS for the dashboard sidebar).
             "transport": current_transport() or _stdio_transport,
         }
-    db = session_db if session_db is not None else _get_db()
-    if db is not None:
-        row = db.get_session(key)
-        if row and row.get("cwd"):
-            with _sessions_lock:
-                if sid in _sessions:
-                    _sessions[sid]["cwd"] = row["cwd"]
-        else:
-            try:
-                _cwd = _sessions[sid]["cwd"]
-                db.update_session_cwd(key, _cwd)
-                # git branch/root probes run off the hot path (see _set_session_cwd).
-                _persist_session_git_meta(_sessions[sid], _cwd)
-            except Exception:
-                logger.debug("failed to persist resumed session cwd", exc_info=True)
-    _register_session_cwd(_sessions[sid])
+    _init_owns_db = False
+    if session_db is not None:
+        db = session_db
+    elif profile_home:
+        try:
+            from hermes_state import SessionDB
+
+            db = SessionDB(db_path=Path(profile_home) / "state.db")
+            _init_owns_db = True
+        except Exception:
+            db = _get_db()
+    else:
+        db = _get_db()
     try:
-        _attach_worker(
-            sid,
-            _sessions[sid],
-            _SlashWorker(
-                key,
-                getattr(agent, "model", _resolve_model()),
-                profile_home=_sessions[sid].get("profile_home"),
-            ),
-        )
-    except Exception:
-        # Defer hard-failure to slash.exec; chat still works without slash worker.
-        _sessions[sid]["slash_worker"] = None
+        if db is not None:
+            row = db.get_session(key) if hasattr(db, "get_session") else None
+            if row and row.get("cwd"):
+                with _sessions_lock:
+                    if sid in _sessions:
+                        _sessions[sid]["cwd"] = row["cwd"]
+            else:
+                try:
+                    _cwd = _sessions[sid]["cwd"]
+                    if hasattr(db, "update_session_cwd"):
+                        db.update_session_cwd(key, _cwd)
+                    # git branch/root probes run off the hot path (see _set_session_cwd).
+                    _persist_session_git_meta(_sessions[sid], _cwd)
+                except Exception:
+                    logger.debug(
+                        "failed to persist resumed session cwd", exc_info=True
+                    )
+    finally:
+        if _init_owns_db and db is not None:
+            try:
+                db.close()
+            except Exception:
+                pass
+    _register_session_cwd(_sessions[sid])
+    # No eager slash-worker pre-warm — the session dict already carries
+    # slash_worker=None and slash.exec builds one on demand. See the
+    # deferred-build path in _start_agent_build for the full rationale
+    # (per-worker MCP fleets accumulating across retained sessions).
     try:
         from tools.approval import register_gateway_notify, load_permanent_allowlist
 
@@ -5601,6 +5990,49 @@ def _enrich_with_attached_images(user_text: str, image_paths: list[str]) -> str:
     return text or "What do you see in this image?"
 
 
+def _build_persist_message_with_image_refs(user_text: str, image_paths: list[str]) -> str:
+    """Build the clean, UI-recognizable version of the user's message for
+    persisting to session history. Uses ``@image:<path>`` directives — the
+    format the desktop client (directive-text.tsx / HERMES_DIRECTIVE_RE)
+    actually parses and renders as an image — unlike
+    ``_enrich_with_attached_images``, which embeds a vision description and
+    an ``image_url:`` hint meant only for the model and must never be
+    persisted as-is (it silently breaks image rendering after a full
+    restart, and reorders image/text on live session-switch reconciliation).
+
+    The caption leads and the directives trail: session previews are the first
+    60 characters of the first user message (``list_sessions_rich``), so a
+    leading directive would label the session with a truncated file path in the
+    sidebar, switcher, and command palette. Clients lift the refs out of the
+    body by line, so their position does not affect how the turn renders.
+    """
+    from agent.context_references import format_reference_value
+
+    text = user_text or ""
+    refs = "\n".join(f"@image:{format_reference_value(p)}" for p in image_paths if Path(p).exists())
+    if not refs:
+        return text
+    return f"{text}\n{refs}" if text else refs
+
+
+def _build_persist_user_message(user_text: str, image_paths: list[str], run_message: Any) -> Any:
+    """Shape the persisted user turn to match what was sent to the model.
+
+    Native-vision turns send ``content`` as a parts list, and
+    ``_flush_messages_to_session_db`` deliberately ignores a plain-string
+    override for a list payload (a text override must not erase a turn's
+    image/audio summary). So mirror the shape: replace only the text part with
+    the ``@image:`` ref form and keep the image parts, so the model still has
+    the pixels for the rest of the session. Any API-only text part (the
+    barge-in note) is dropped along the way, which is the point of the override.
+    """
+    persist_text = _build_persist_message_with_image_refs(user_text, image_paths)
+    if not isinstance(run_message, list):
+        return persist_text
+    image_parts = [p for p in run_message if not (isinstance(p, dict) and p.get("type") == "text")]
+    return [{"type": "text", "text": persist_text}, *image_parts]
+
+
 def _content_display_text(content: Any) -> str:
     if content is None:
         return ""
@@ -5933,6 +6365,189 @@ def _clear_inflight_turn(session: dict) -> None:
     session["inflight_turn"] = None
 
 
+def _fail_inflight_turn(session: dict, error: Any) -> None:
+    """Mark the in-flight turn terminal-error but keep it replayable.
+
+    Normal completion clears ``inflight_turn`` because the response is now in
+    canonical history. Failures are different: the terminal frame can be lost
+    on a WS disconnect, and the failed turn may never have been committed.
+    Retaining a compact error snapshot lets ``session.resume`` replay the
+    user's prompt, any partial assistant text, and the error itself instead of
+    leaving the client stranded on a spinner or hydrating from stale DB state.
+    The snapshot lives until the next turn starts (``_start_inflight_turn``
+    overwrites it) or the session closes.
+
+    Caller must hold ``session["history_lock"]``.
+    """
+    message = str(error) if not isinstance(error, BaseException) else (str(error) or type(error).__name__)
+    now = time.time()
+    turn = session.get("inflight_turn")
+    if not isinstance(turn, dict):
+        turn = {"assistant": "", "user": "", "started_at": now}
+    turn["assistant"] = str(turn.get("assistant") or "")
+    turn["user"] = str(turn.get("user") or "")
+    turn["error"] = message or "turn failed"
+    turn["status"] = "error"
+    turn["recoverable"] = True
+    turn["streaming"] = False
+    turn["updated_at"] = now
+    session["inflight_turn"] = turn
+
+
+# ── Auto-continue: resume a turn killed by a process/machine death ────
+#
+# A turn that concludes — success, handled error, interrupt — clears its
+# durable marker (see tui_gateway/turn_marker.py) in _run_prompt_submit's
+# finally. Only a process death leaves the marker behind, so a marker found
+# at session.resume time is positive proof the turn never finished AND the
+# client never saw a terminal frame. If the interruption is fresh, re-submit
+# the interrupted prompt automatically (the messaging gateway has done this
+# for restart-interrupted sessions since #27856); if it's stale, clear the
+# marker and let the recovered partial transcript speak for itself — the
+# user can ask to continue manually.
+
+_AUTO_CONTINUE_ENABLED_DEFAULT = True
+_AUTO_CONTINUE_FRESHNESS_MINUTES_DEFAULT = 15
+_AUTO_CONTINUE_MAX_ATTEMPTS_DEFAULT = 2
+
+
+def _auto_continue_config() -> tuple[bool, float, int]:
+    """(enabled, freshness window in seconds, max attempts) from config.yaml."""
+    desktop = _load_cfg().get("desktop")
+    cfg = desktop.get("auto_continue") if isinstance(desktop, dict) else None
+    if not isinstance(cfg, dict):
+        cfg = {}
+    try:
+        minutes = float(cfg.get("freshness_minutes", _AUTO_CONTINUE_FRESHNESS_MINUTES_DEFAULT))
+    except (TypeError, ValueError):
+        minutes = float(_AUTO_CONTINUE_FRESHNESS_MINUTES_DEFAULT)
+    return (
+        is_truthy_value(cfg.get("enabled"), default=_AUTO_CONTINUE_ENABLED_DEFAULT),
+        max(0.0, minutes) * 60.0,
+        _coerce_int_config_value(
+            cfg.get("max_attempts"), _AUTO_CONTINUE_MAX_ATTEMPTS_DEFAULT, min_value=0
+        ),
+    )
+
+
+def _session_home(session: dict) -> Path:
+    """The HERMES_HOME the session's durable state lives in (profile-aware)."""
+    profile_home = session.get("profile_home")
+    return Path(profile_home) if profile_home else Path(_hermes_home)
+
+
+def _retire_turn_marker(session: dict, *keys: str) -> None:
+    """Drop the crash marker for a turn whose outcome is about to reach the client.
+
+    Called immediately before the terminal frame rather than at the end of the
+    turn thread: post-turn work (titles, memory sync, goal hooks) runs for a
+    second or more after the client has its answer, and quitting inside that
+    window would leave a marker that looks like a crash — re-running a finished
+    turn on the next launch. Extra ``keys`` cover a session_key that
+    compression rotated mid-turn.
+    """
+    home = _session_home(session)
+    for key in dict.fromkeys((*keys, str(session.get("session_key") or ""))):
+        if key:
+            clear_turn_marker(home, key)
+
+
+def _auto_continue_note(prompt: str) -> str:
+    # Same opening as the messaging gateway's recovery notes so transcript
+    # tooling recognizes both. The original prompt is embedded because a hard
+    # crash persists nothing of the interrupted turn to the session DB — this
+    # note is the only copy the model will see.
+    return (
+        "[System note: Your previous turn was interrupted mid-run — the app or "
+        "its backend process stopped before the turn could finish. Some of the "
+        "work may already be complete; check the current state before redoing "
+        "anything, then finish the task. The interrupted request was:]\n\n"
+        f"{prompt}"
+    )
+
+
+def _maybe_schedule_auto_continue(sid: str, session: dict, session_key: str) -> dict | None:
+    """Kick off a continuation turn for a crash-interrupted session.
+
+    Called from session.resume's cold paths after the live record is
+    registered. Returns a small descriptor for the resume payload when a
+    continuation was scheduled, else None. The turn itself runs on a
+    background thread after the (deferred) agent build finishes, through the
+    same _run_prompt_submit machinery as every other synthesized turn — so
+    the client that just resumed streams it live.
+    """
+    home = _session_home(session)
+    marker = read_turn_marker(home, session_key)
+    if marker is None:
+        return None
+    enabled, freshness_secs, max_attempts = _auto_continue_config()
+    age = time.time() - marker["started_at"]
+    if not enabled or age > freshness_secs or marker["attempts"] >= max_attempts:
+        # Stale, disabled, or crash-looping: stop trying. The journal/partial
+        # transcript still shows what happened; a manual message continues it.
+        clear_turn_marker(home, session_key)
+        return None
+    if session.get("_auto_continue_scheduled"):
+        return None
+    session["_auto_continue_scheduled"] = True
+    attempt = marker["attempts"] + 1
+    text = _auto_continue_note(marker["prompt"])
+
+    def kickoff() -> None:
+        rid = f"__auto_continue__{int(time.time() * 1000)}"
+        try:
+            _start_agent_build(sid, session)
+            err = _wait_agent(session, rid, timeout=120.0)
+        except Exception:
+            logger.warning("auto-continue agent build failed for %s", sid, exc_info=True)
+            err = {"error": {"message": "agent build failed"}}
+        if err:
+            # Leave the marker: the next resume retries (bounded by attempts).
+            session["_auto_continue_scheduled"] = False
+            return
+        with session["history_lock"]:
+            if session.get("running") or session.get("_turn_cancel_requested") or session.get("_finalized"):
+                # A real user prompt beat us to it — their turn wins, and its
+                # own conclusion clears the marker.
+                session["_auto_continue_scheduled"] = False
+                return
+            session["running"] = True
+            session["last_active"] = time.time()
+            # Hand this turn its own marker inputs (read back by
+            # _run_prompt_submit): count the attempt so a crash during the
+            # continuation trips the breaker, and re-record the ORIGINAL
+            # prompt so a second crash doesn't nest note inside note. Set
+            # here, not at schedule time, so a bail above leaves nothing
+            # behind for a racing user turn to inherit.
+            session["_auto_continue_attempt"] = attempt
+            session["_auto_continue_prompt"] = marker["prompt"]
+        try:
+            _emit(
+                "status.update",
+                sid,
+                {"kind": "process", "text": "Resuming interrupted turn…"},
+            )
+            _emit("message.start", sid)
+            _run_prompt_submit(rid, sid, session, text, display_kind="auto_continue")
+        except Exception as exc:
+            print(
+                f"[tui_gateway] auto-continue dispatch failed: "
+                f"{type(exc).__name__}: {exc}",
+                file=sys.stderr,
+            )
+            with session["history_lock"]:
+                session["running"] = False
+
+    threading.Thread(target=kickoff, daemon=True).start()
+    logger.info(
+        "auto-continue scheduled for session %s (attempt %d, interrupted %.0fs ago)",
+        session_key,
+        attempt,
+        age,
+    )
+    return {"attempt": attempt, "interrupted_at": marker["started_at"]}
+
+
 def _enqueue_prompt(session: dict, text: Any, transport: Any) -> None:
     """Stash a message to run as the very next turn once the live one ends.
 
@@ -6097,13 +6712,58 @@ def _inflight_snapshot(session: dict) -> dict | None:
     user = str(turn.get("user") or "").strip()
     assistant = str(turn.get("assistant") or "")
     streaming = bool(turn.get("streaming"))
-    if not user and not assistant and not streaming:
+    error = str(turn.get("error") or "").strip()
+    if not user and not assistant and not streaming and not error:
         return None
-    return {
+    snapshot = {
         "assistant": assistant,
         "streaming": streaming,
         "user": user,
     }
+    if error:
+        # Retained failed turn (see _fail_inflight_turn): carry the error
+        # semantics so a resuming client can rebuild the failed-turn bubble
+        # instead of rendering the partial text as a healthy reply.
+        snapshot["error"] = error
+        snapshot["status"] = str(turn.get("status") or "error")
+        snapshot["recoverable"] = bool(turn.get("recoverable"))
+    return snapshot
+
+
+def _emit_terminal_turn_error(sid: str, session: dict, error: Any) -> None:
+    """Close a failed turn with a terminal ``message.complete`` frame.
+
+    Emits the same ``status: "error"`` frame shape the returned-error path in
+    ``_run_prompt_submit`` already produces (so TUI/desktop handling is
+    uniform), and retains the failed turn via ``_fail_inflight_turn`` so a
+    client that missed this frame (disconnect window) can recover it from
+    ``session.resume``'s ``inflight`` payload.
+    """
+    with session["history_lock"]:
+        _fail_inflight_turn(session, error)
+        turn = session.get("inflight_turn") or {}
+        message = str(turn.get("error") or "turn failed")
+        partial = str(turn.get("assistant") or "")
+        cols = int(session.get("cols", 80))
+    text = partial or f"Error: {message}"
+    agent = session.get("agent")
+    payload = {
+        "text": text,
+        "usage": _get_usage(agent) if agent is not None else {},
+        "status": "error",
+        "error": message,
+        "recoverable": True,
+    }
+    if partial:
+        payload["partial"] = True
+    try:
+        rendered = render_message(text, cols)
+    except Exception:
+        rendered = ""
+    if rendered:
+        payload["rendered"] = rendered
+    _retire_turn_marker(session)
+    _emit("message.complete", sid, payload)
 
 
 def _queued_prompt_snapshot(session: dict) -> dict | None:
@@ -6270,7 +6930,7 @@ def _(rid, params: dict) -> dict:
                 "project": _project_info_for_cwd(_sessions[sid]["cwd"]),
                 "lazy": True,
                 "desktop_contract": DESKTOP_BACKEND_CONTRACT,
-                "profile_name": _current_profile_name(),
+                "profile_name": _response_profile_name(profile),
             },
         },
     )
@@ -6278,48 +6938,53 @@ def _(rid, params: dict) -> dict:
 
 @method("session.list")
 def _(rid, params: dict) -> dict:
-    db = _get_db()
-    if db is None:
-        return _db_unavailable_error(rid, code=5006)
-    try:
-        # Resume picker should surface human conversation sessions from every
-        # user-facing surface — CLI, TUI, all gateway platforms (including new
-        # ones not enumerated here), ACP adapter clients, webhook sessions,
-        # custom `HERMES_SESSION_SOURCE` values, and older installs with
-        # different source labels. We deny-list only the noisy internal
-        # sources (``tool`` sub-agent runs) rather than allow-listing a
-        # fixed set of platform names that goes stale whenever a new
-        # platform is added or a user names their own source.
-        deny = frozenset({"tool"})
+    with _profile_db(params) as db:
+        if db is None:
+            return _db_unavailable_error(rid, code=5006)
+        try:
+            # Resume picker should surface human conversation sessions from every
+            # user-facing surface — CLI, TUI, all gateway platforms (including new
+            # ones not enumerated here), ACP adapter clients, webhook sessions,
+            # custom `HERMES_SESSION_SOURCE` values, and older installs with
+            # different source labels. We deny-list only the noisy internal
+            # sources (``tool`` sub-agent runs) rather than allow-listing a
+            # fixed set of platform names that goes stale whenever a new
+            # platform is added or a user names their own source.
+            deny = frozenset({"tool"})
 
-        limit = int(params.get("limit", 200) or 200)
-        # Over-fetch modestly so per-source filtering doesn't leave us
-        # short; the compression-tip projection in ``list_sessions_rich``
-        # can also merge rows.
-        fetch_limit = max(limit * 2, 200)
-        rows = [
-            s
-            for s in db.list_sessions_rich(source=None, limit=fetch_limit, order_by_last_active=True, compact_rows=True)
-            if (s.get("source") or "").strip().lower() not in deny
-        ][:limit]
-        return _ok(
-            rid,
-            {
-                "sessions": [
-                    {
-                        "id": s["id"],
-                        "title": s.get("title") or "",
-                        "preview": s.get("preview") or "",
-                        "started_at": s.get("started_at") or 0,
-                        "message_count": s.get("message_count") or 0,
-                        "source": s.get("source") or "",
-                    }
-                    for s in rows
-                ]
-            },
-        )
-    except Exception as e:
-        return _err(rid, 5006, str(e))
+            limit = int(params.get("limit", 200) or 200)
+            # Over-fetch modestly so per-source filtering doesn't leave us
+            # short; the compression-tip projection in ``list_sessions_rich``
+            # can also merge rows.
+            fetch_limit = max(limit * 2, 200)
+            rows = [
+                s
+                for s in db.list_sessions_rich(
+                    source=None,
+                    limit=fetch_limit,
+                    order_by_last_active=True,
+                    compact_rows=True,
+                )
+                if (s.get("source") or "").strip().lower() not in deny
+            ][:limit]
+            return _ok(
+                rid,
+                {
+                    "sessions": [
+                        {
+                            "id": s["id"],
+                            "title": s.get("title") or "",
+                            "preview": s.get("preview") or "",
+                            "started_at": s.get("started_at") or 0,
+                            "message_count": s.get("message_count") or 0,
+                            "source": s.get("source") or "",
+                        }
+                        for s in rows
+                    ]
+                },
+            )
+        except Exception as e:
+            return _err(rid, 5006, str(e))
 
 
 @method("session.most_recent")
@@ -6336,34 +7001,39 @@ def _(rid, params: dict) -> dict:
     session found right now".  Errors are also folded into that
     null-result shape (and logged) so callers don't have to special-
     case JSON-RPC error envelopes for what is a normal "no answer".
+
+    Honors ``params.profile`` so app-global remote mode lists from the
+    focused profile's ``state.db`` (mirrors ``session.resume``).
     """
-    db = _get_db()
-    if db is None:
-        return _ok(rid, {"session_id": None})
-    try:
-        deny = frozenset({"tool"})
-        # Over-fetch by a generous bounded amount so heavy sub-agent
-        # users (lots of recent ``tool`` rows) don't get a false
-        # "no eligible session" answer.  ``session.list`` uses a
-        # similar over-fetch strategy.
-        rows = db.list_sessions_rich(source=None, limit=200, order_by_last_active=True, compact_rows=True)
-        for row in rows:
-            src = (row.get("source") or "").strip().lower()
-            if src in deny:
-                continue
-            return _ok(
-                rid,
-                {
-                    "session_id": row.get("id"),
-                    "title": row.get("title") or "",
-                    "started_at": row.get("started_at") or 0,
-                    "source": row.get("source") or "",
-                },
+    with _profile_db(params) as db:
+        if db is None:
+            return _ok(rid, {"session_id": None})
+        try:
+            deny = frozenset({"tool"})
+            # Over-fetch by a generous bounded amount so heavy sub-agent
+            # users (lots of recent ``tool`` rows) don't get a false
+            # "no eligible session" answer.  ``session.list`` uses a
+            # similar over-fetch strategy.
+            rows = db.list_sessions_rich(
+                source=None, limit=200, order_by_last_active=True, compact_rows=True
             )
-        return _ok(rid, {"session_id": None})
-    except Exception:
-        logger.exception("session.most_recent failed")
-        return _ok(rid, {"session_id": None})
+            for row in rows:
+                src = (row.get("source") or "").strip().lower()
+                if src in deny:
+                    continue
+                return _ok(
+                    rid,
+                    {
+                        "session_id": row.get("id"),
+                        "title": row.get("title") or "",
+                        "started_at": row.get("started_at") or 0,
+                        "source": row.get("source") or "",
+                    },
+                )
+            return _ok(rid, {"session_id": None})
+        except Exception:
+            logger.exception("session.most_recent failed")
+            return _ok(rid, {"session_id": None})
 
 
 @method("project.facts")
@@ -6408,7 +7078,13 @@ def _(rid, params: dict) -> dict:
         return _ok(rid, {"verification": {"status": "unknown", "evidence": None}})
 
 
-def _lazy_resume_info(cwd: str, *, model: str = "", provider: str = "") -> dict:
+def _lazy_resume_info(
+    cwd: str,
+    *,
+    model: str = "",
+    provider: str = "",
+    profile: str | None = None,
+) -> dict:
     """session.info for a not-yet-built session (the shape session.create
     returns). tools/skills land later when the deferred build emits session.info."""
     info = {
@@ -6420,7 +7096,7 @@ def _lazy_resume_info(cwd: str, *, model: str = "", provider: str = "") -> dict:
         "skills": {},
         "lazy": True,
         "desktop_contract": DESKTOP_BACKEND_CONTRACT,
-        "profile_name": _current_profile_name(),
+        "profile_name": _response_profile_name(profile),
     }
     if provider:
         info["provider"] = provider
@@ -6672,7 +7348,7 @@ def _(rid, params: dict) -> dict:
                 "resumed": target,
                 "message_count": len(messages),
                 "messages": messages,
-                "info": _lazy_resume_info(cwd),
+                "info": _lazy_resume_info(cwd, profile=profile),
                 "inflight": None,
                 "running": child_running,
                 "session_key": target,
@@ -6746,27 +7422,29 @@ def _(rid, params: dict) -> dict:
 
         _schedule_agent_build(sid)
         _schedule_session_cap_enforcement()  # trim detached idle sessions over the cap
+        auto_continue = _maybe_schedule_auto_continue(sid, record, target)
 
         messages = _history_to_messages(display_history)
-        return _ok(
-            rid,
-            {
-                "session_id": sid,
-                "resumed": target,
-                "message_count": len(messages),
-                "messages": messages,
-                "info": _lazy_resume_info(
-                    cwd,
-                    model=model_override.get("model") or "",
-                    provider=overrides.get("provider_override") or "",
-                ),
-                "inflight": None,
-                "running": False,
-                "session_key": target,
-                "started_at": record["created_at"],
-                "status": "idle",
-            },
-        )
+        payload = {
+            "session_id": sid,
+            "resumed": target,
+            "message_count": len(messages),
+            "messages": messages,
+            "info": _lazy_resume_info(
+                cwd,
+                model=model_override.get("model") or "",
+                provider=overrides.get("provider_override") or "",
+                profile=profile,
+            ),
+            "inflight": None,
+            "running": False,
+            "session_key": target,
+            "started_at": record["created_at"],
+            "status": "idle",
+        }
+        if auto_continue is not None:
+            payload["auto_continue"] = auto_continue
+        return _ok(rid, payload)
 
     # Build the agent OUTSIDE the lock — _make_agent can block for seconds
     # (MCP discovery, prompt/skill build, AIAgent construction). Holding
@@ -6885,21 +7563,24 @@ def _(rid, params: dict) -> dict:
                 lease.release()
             return _err(rid, 5000, f"resume failed: {e}")
         session = _sessions.get(sid) or {}
-    return _ok(
-        rid,
-        {
-            "session_id": sid,
-            "resumed": target,
-            "message_count": len(messages),
-            "messages": messages,
-            "info": _session_info(agent, session),
-            "inflight": None,
-            "running": False,
-            "session_key": target,
-            "started_at": float(session.get("created_at") or time.time()),
-            "status": "idle",
-        },
+    auto_continue = (
+        _maybe_schedule_auto_continue(sid, session, target) if session else None
     )
+    payload = {
+        "session_id": sid,
+        "resumed": target,
+        "message_count": len(messages),
+        "messages": messages,
+        "info": _session_info(agent, session),
+        "inflight": None,
+        "running": False,
+        "session_key": target,
+        "started_at": float(session.get("created_at") or time.time()),
+        "status": "idle",
+    }
+    if auto_continue is not None:
+        payload["auto_continue"] = auto_continue
+    return _ok(rid, payload)
 
 
 @method("session.cwd.set")
@@ -6959,12 +7640,12 @@ def _message_preview(history: list) -> str:
 
 def _session_live_title(session: dict, key: str) -> str:
     title = str(session.get("pending_title") or "").strip()
-    db = _get_db()
-    if db is not None:
-        try:
-            title = str(db.get_session_title(key) or title or "").strip()
-        except Exception:
-            pass
+    try:
+        with _session_db(session) as db:
+            if db is not None:
+                title = str(db.get_session_title(key) or title or "").strip()
+    except Exception:
+        pass
     return title
 
 
@@ -7216,13 +7897,13 @@ def _(rid, params: dict) -> dict:
     still being written to and removing them out from under the live
     agent corrupts message ordering and trips FK constraints when the
     next message append flushes.
+
+    Honors ``params.profile`` so app-global remote mode deletes from the
+    focused profile's ``state.db`` + sessions dir (mirrors ``session.resume``).
     """
     target = params.get("session_id", "")
     if not target:
         return _err(rid, 4006, "session_id required")
-    db = _get_db()
-    if db is None:
-        return _db_unavailable_error(rid, code=5036)
     # Block deletion of any session currently bound to a live TUI session
     # in this process.  The picker hides the active session anyway, but a
     # racing caller could still target it.  Snapshot via ``list(...)``
@@ -7238,14 +7919,22 @@ def _(rid, params: dict) -> dict:
     active = {s.get("session_key") for s in snapshot if s.get("session_key")}
     if target in active:
         return _err(rid, 4023, "cannot delete an active session")
-    sessions_dir = get_hermes_home() / "sessions"
-    try:
-        deleted = db.delete_session(target, sessions_dir=sessions_dir)
-    except Exception as e:
-        return _err(rid, 5036, f"delete failed: {e}")
-    if not deleted:
-        return _err(rid, 4007, "session not found")
-    return _ok(rid, {"deleted": target})
+    profile = (params.get("profile") or "").strip() or None
+    profile_home = _profile_home(profile)
+    with _profile_db(params) as db:
+        if db is None:
+            return _db_unavailable_error(rid, code=5036)
+        if profile_home is not None:
+            sessions_dir = Path(profile_home) / "sessions"
+        else:
+            sessions_dir = get_hermes_home() / "sessions"
+        try:
+            deleted = db.delete_session(target, sessions_dir=sessions_dir)
+        except Exception as e:
+            return _err(rid, 5036, f"delete failed: {e}")
+        if not deleted:
+            return _err(rid, 4007, "session not found")
+        return _ok(rid, {"deleted": target})
 
 
 @method("session.title")
@@ -7253,83 +7942,84 @@ def _(rid, params: dict) -> dict:
     session, err = _sess_nowait(params, rid)
     if err:
         return err
-    db = _get_db()
-    if db is None:
-        return _db_unavailable_error(rid, code=5007)
-    key = session["session_key"]
-    if "title" not in params:
-        fallback = session.get("pending_title") or ""
-        try:
-            resolved_title = db.get_session_title(key) or ""
-            if fallback:
-                if db.set_session_title(key, fallback):
-                    session["pending_title"] = None
-                    resolved_title = fallback
-                else:
-                    existing_row = db.get_session(key)
-                    existing_title = ((existing_row or {}).get("title") or "").strip()
-                    if existing_title == fallback:
+    with _session_db(session) as db:
+        if db is None:
+            return _db_unavailable_error(rid, code=5007)
+        key = session["session_key"]
+        if "title" not in params:
+            fallback = session.get("pending_title") or ""
+            try:
+                resolved_title = db.get_session_title(key) or ""
+                if fallback:
+                    if db.set_session_title(key, fallback):
                         session["pending_title"] = None
                         resolved_title = fallback
-                    elif not resolved_title:
-                        resolved_title = fallback
-            elif resolved_title:
-                session["pending_title"] = None
-        except Exception:
-            resolved_title = fallback
-        _emit_session_info_for_session(params.get("session_id", ""), session)
-        return _ok(
-            rid,
-            {
-                "title": resolved_title,
-                "session_key": key,
-            },
-        )
-    title = (params.get("title", "") or "").strip()
-    if not title:
-        return _err(rid, 4021, "title required")
-    try:
-        if db.set_session_title(key, title):
-            session["pending_title"] = None
-            _emit_session_info_for_session(params.get("session_id", ""), session)
-            return _ok(rid, {"pending": False, "title": title})
-        # rowcount == 0 can mean "same value" as well as "missing row".
-        existing_row = db.get_session(key)
-        if existing_row:
-            session["pending_title"] = None
+                    else:
+                        existing_row = db.get_session(key)
+                        existing_title = ((existing_row or {}).get("title") or "").strip()
+                        if existing_title == fallback:
+                            session["pending_title"] = None
+                            resolved_title = fallback
+                        elif not resolved_title:
+                            resolved_title = fallback
+                elif resolved_title:
+                    session["pending_title"] = None
+            except Exception:
+                resolved_title = fallback
             _emit_session_info_for_session(params.get("session_id", ""), session)
             return _ok(
                 rid,
                 {
-                    "pending": False,
-                    "title": (existing_row.get("title") or title),
+                    "title": resolved_title,
+                    "session_key": key,
                 },
             )
-        # No row yet (the DB write is deferred to the first prompt so empty
-        # drafts don't litter the sidebar). An explicit /title is clear user
-        # intent, not an abandoned draft — so persist the row NOW and set the
-        # title, mirroring the messaging gateway's _handle_title_command. The
-        # old behavior only queued pending_title and relied on the post-turn
-        # apply block; if that turn never landed under this session_key the
-        # title was silently lost and the sidebar fell back to the message
-        # preview. Creating the row up front removes that race entirely. The
-        # min-messages sidebar filter keeps a titled 0-message row hidden, so
-        # a /title'd-but-never-used draft still doesn't clutter the list.
-        _ensure_session_db_row(session)
-        with _session_db(session) as scoped_db:
-            if scoped_db is not None and scoped_db.set_session_title(key, title):
+        title = (params.get("title", "") or "").strip()
+        if not title:
+            return _err(rid, 4021, "title required")
+        try:
+            if db.set_session_title(key, title):
                 session["pending_title"] = None
                 _emit_session_info_for_session(params.get("session_id", ""), session)
                 return _ok(rid, {"pending": False, "title": title})
-        # Row creation didn't take (DB unavailable, or a concurrent writer) —
-        # fall back to queuing so the post-turn apply block can still recover.
-        session["pending_title"] = title
-        _emit_session_info_for_session(params.get("session_id", ""), session)
-        return _ok(rid, {"pending": True, "title": title})
-    except ValueError as e:
-        return _err(rid, 4022, str(e))
-    except Exception as e:
-        return _err(rid, 5007, str(e))
+            # rowcount == 0 can mean "same value" as well as "missing row".
+            existing_row = db.get_session(key)
+            if existing_row:
+                session["pending_title"] = None
+                _emit_session_info_for_session(params.get("session_id", ""), session)
+                return _ok(
+                    rid,
+                    {
+                        "pending": False,
+                        "title": (existing_row.get("title") or title),
+                    },
+                )
+            # No row yet (the DB write is deferred to the first prompt so empty
+            # drafts don't litter the sidebar). An explicit /title is clear user
+            # intent, not an abandoned draft — so persist the row NOW and set the
+            # title, mirroring the messaging gateway's _handle_title_command. The
+            # old behavior only queued pending_title and relied on the post-turn
+            # apply block; if that turn never landed under this session_key the
+            # title was silently lost and the sidebar fell back to the message
+            # preview. Creating the row up front removes that race entirely. The
+            # min-messages sidebar filter keeps a titled 0-message row hidden, so
+            # a /title'd-but-never-used draft still doesn't clutter the list.
+            _ensure_session_db_row(session)
+            with _session_db(session) as scoped_db:
+                if scoped_db is not None and scoped_db.set_session_title(key, title):
+                    session["pending_title"] = None
+                    _emit_session_info_for_session(params.get("session_id", ""), session)
+                    return _ok(rid, {"pending": False, "title": title})
+            # Row creation didn't take (DB unavailable, or a concurrent writer) —
+            # fall back to queuing so the post-turn apply block can still recover.
+            session["pending_title"] = title
+            _emit_session_info_for_session(params.get("session_id", ""), session)
+            return _ok(rid, {"pending": True, "title": title})
+        except ValueError as e:
+            return _err(rid, 4022, str(e))
+        except Exception as e:
+            return _err(rid, 5007, str(e))
+
 
 
 def _main_runtime_from_agent(agent) -> dict | None:
@@ -9138,12 +9828,27 @@ def _(rid, params: dict) -> dict:
     key = session.get("session_key") or params.get("session_id") or ""
     agent = session.get("agent")
     meta = {}
-    db = _get_db()
-    if db and key:
-        try:
-            meta = db.get_session(key) or {}
-        except Exception:
-            meta = {}
+    # Prefer the live session's bound profile db, else params.profile, else launch.
+    status_params = dict(params or {})
+    if not status_params.get("profile") and session.get("profile_home"):
+        # profile_home is a path; still allow _session_db via a synthetic session
+        pass
+    with _session_db(session) as db:
+        if db is None:
+            # Fall back to ~params.profile naming for not-yet-mapped sessions.
+            with _profile_db(params) as db2:
+                db = db2
+                if db and key:
+                    try:
+                        meta = db.get_session(key) or {}
+                    except Exception:
+                        meta = {}
+                db = None  # prevent double-use
+        if db is not None and key:
+            try:
+                meta = db.get_session(key) or {}
+            except Exception:
+                meta = {}
 
     def _dt(value, fallback: datetime | None = None) -> datetime:
         if value:
@@ -9194,14 +9899,15 @@ def _(rid, params: dict) -> dict:
     if err:
         return err
     history = list(session.get("history", []))
-    db = _get_db()
-    if db is not None and session.get("session_key"):
-        try:
-            history = db.get_messages_as_conversation(
-                session["session_key"], include_ancestors=True
-            )
-        except Exception:
-            pass
+    if session.get("session_key"):
+        with _session_db(session) as db:
+            if db is not None:
+                try:
+                    history = db.get_messages_as_conversation(
+                        session["session_key"], include_ancestors=True
+                    )
+                except Exception:
+                    pass
     return _ok(
         rid,
         {
@@ -9500,77 +10206,113 @@ def _(rid, params: dict) -> dict:
     session, err = _sess(params, rid)
     if err:
         return err
-    db = _get_db()
-    if db is None:
-        return _db_unavailable_error(rid, code=5008)
-    old_key = session["session_key"]
-    with session["history_lock"]:
-        history = [dict(msg) for msg in session.get("history", [])]
-    if not history:
-        return _err(rid, 4008, "nothing to branch — send a message first")
-    new_key = _new_session_key()
-    new_sid = uuid.uuid4().hex[:8]
-    source = _session_source(session)
-    lease, limit_message = _claim_active_session_slot(
-        new_key, live_session_id=new_sid, surface=source
-    )
-    if limit_message is not None:
-        return _err(rid, 4090, limit_message)
-    branch_name = params.get("name", "")
-    try:
-        if branch_name:
-            title = branch_name
-        else:
-            current = db.get_session_title(old_key) or "branch"
-            title = (
-                db.get_next_title_in_lineage(current)
-                if hasattr(db, "get_next_title_in_lineage")
-                else f"{current} (branch)"
-            )
-        db.create_session(
-            new_key,
-            source=source,
-            model=_resolve_model(),
-            # Stable _branched_from marker so list_sessions_rich() keeps the
-            # branch visible in /resume and /sessions. The TUI branch leaves
-            # the parent live (no end_reason='branched'), so the legacy
-            # end_reason heuristic never matches it — the marker is the only
-            # thing that surfaces TUI branches. See issue #20856.
-            model_config={"_branched_from": old_key},
-            parent_session_id=old_key,
-            cwd=_session_cwd(session),
+    # Branch must write into the parent's profile-scoped state.db (app-global
+    # remote mode). Using the launch handle would orphan branch rows + history.
+    with _session_db(session) as db:
+        if db is None:
+            return _db_unavailable_error(rid, code=5008)
+        old_key = session["session_key"]
+        with session["history_lock"]:
+            history = [dict(msg) for msg in session.get("history", [])]
+        if not history:
+            return _err(rid, 4008, "nothing to branch — send a message first")
+        new_key = _new_session_key()
+        new_sid = uuid.uuid4().hex[:8]
+        source = _session_source(session)
+        lease, limit_message = _claim_active_session_slot(
+            new_key, live_session_id=new_sid, surface=source
         )
-        for msg in history:
-            db.append_message(
-                session_id=new_key,
-                role=msg.get("role", "user"),
-                content=msg.get("content"),
-                timestamp=msg.get("timestamp"),
-            )
-        db.set_session_title(new_key, title)
-    except Exception as e:
-        if lease is not None:
-            lease.release()
-        return _err(rid, 5008, f"branch failed: {e}")
-    try:
-        tokens = _set_session_context(new_key)
+        if limit_message is not None:
+            return _err(rid, 4090, limit_message)
+        branch_name = params.get("name", "")
         try:
-            agent = _make_agent(
+            if branch_name:
+                title = branch_name
+            else:
+                current = db.get_session_title(old_key) or "branch"
+                title = (
+                    db.get_next_title_in_lineage(current)
+                    if hasattr(db, "get_next_title_in_lineage")
+                    else f"{current} (branch)"
+                )
+            db.create_session(
+                new_key,
+                source=source,
+                model=_resolve_model(),
+                # Stable _branched_from marker so list_sessions_rich() keeps the
+                # branch visible in /resume and /sessions. The TUI branch leaves
+                # the parent live (no end_reason='branched'), so the legacy
+                # end_reason heuristic never matches it — the marker is the only
+                # thing that surfaces TUI branches. See issue #20856.
+                model_config={"_branched_from": old_key},
+                parent_session_id=old_key,
+                cwd=_session_cwd(session),
+                # The branch stays on its parent's profile. Explicit stamp (not
+                # just the parent-backfill) so it holds even when the parent row
+                # predates the profile_name column.
+                profile_name=(
+                    Path(session["profile_home"]).name
+                    if session.get("profile_home")
+                    else None
+                ),
+            )
+            for msg in history:
+                db.append_message(
+                    session_id=new_key,
+                    role=msg.get("role", "user"),
+                    content=msg.get("content"),
+                    # Preserve the parent's original message timestamps —
+                    # branch copies are history, not new activity (9d73006ad).
+                    timestamp=msg.get("timestamp"),
+                )
+            db.set_session_title(new_key, title)
+        except Exception as e:
+            if lease is not None:
+                lease.release()
+            return _err(rid, 5008, f"branch failed: {e}")
+    try:
+        # Bind the branched AGENT to the parent's profile, mirroring
+        # session.create/resume: home override so config/skills/memory resolve
+        # to the profile during the build, and the profile's own state.db
+        # handle so the live agent's message flushes — and any later
+        # compression rotation — persist there. Writing only the row to the
+        # parent's db while the agent stayed on the launch handle would
+        # recreate the cross-profile split one turn later.
+        parent_home = session.get("profile_home")
+        branch_db = None
+        if parent_home:
+            from hermes_state import SessionDB
+
+            branch_db = SessionDB(db_path=Path(parent_home) / "state.db")
+        home_token = (
+            set_hermes_home_override(parent_home) if parent_home else None
+        )
+        try:
+            tokens = _set_session_context(new_key)
+            try:
+                agent = _make_agent(
+                    new_sid,
+                    new_key,
+                    session_id=new_key,
+                    session_db=branch_db,
+                    platform_override=source,
+                )
+            finally:
+                _clear_session_context(tokens)
+            _init_session(
                 new_sid,
                 new_key,
-                session_id=new_key,
-                platform_override=source,
+                agent,
+                list(history),
+                cols=session.get("cols", 80),
+                cwd=_session_cwd(session),
+                session_db=branch_db,
+                source=source,
+                profile_home=parent_home,
             )
         finally:
-            _clear_session_context(tokens)
-        _init_session(
-            new_sid,
-            new_key,
-            agent,
-            list(history),
-            cols=session.get("cols", 80),
-            source=source,
-        )
+            if home_token is not None:
+                reset_hermes_home_override(home_token)
         if new_sid in _sessions:
             _sessions[new_sid]["active_session_lease"] = lease
     except Exception as e:
@@ -10014,6 +10756,41 @@ def _(rid, params: dict) -> dict:
             if ordinal < 0 or ordinal >= len(user_indices):
                 return _err(rid, 4018, "target user message is no longer in session history")
             truncated = history[: user_indices[ordinal]]
+            # Stale clients can attach truncate_before_user_ordinal=0 to an
+            # ordinary submit. That resolves to history[:0] == [] and
+            # replace_messages() DELETEs every durable row — silent total
+            # transcript loss. Refuse the empty-truncation edge unless the
+            # client explicitly opts in (legitimate restore/regenerate of the
+            # first user turn).
+            if (
+                not truncated
+                and history
+                and not is_truthy_value(params.get("confirm_empty_truncate"))
+            ):
+                logger.warning(
+                    "prompt.submit: REFUSED empty truncation of session %s "
+                    "(%d messages would be wiped; ordinal=%d).",
+                    sid,
+                    len(history),
+                    ordinal,
+                )
+                return _err(
+                    rid,
+                    4028,
+                    "truncation would erase the entire session transcript; "
+                    "resubmit with confirm_empty_truncate=true if this is intended",
+                )
+            # Info for routine rewind/edit cuts; warning only when the client
+            # explicitly opts into wiping the whole transcript.
+            log_fn = logger.warning if not truncated else logger.info
+            log_fn(
+                "prompt.submit: truncating session %s history %d -> %d messages "
+                "(ordinal=%d)",
+                sid,
+                len(history),
+                len(truncated),
+                ordinal,
+            )
             session["history"] = truncated
             session["history_version"] = int(session.get("history_version", 0)) + 1
             if (db := _get_db()) is not None:
@@ -10044,25 +10821,45 @@ def _(rid, params: dict) -> dict:
     _start_agent_build(sid, session)
 
     def run_after_agent_ready() -> None:
-        err = _wait_agent(session, rid)
+        # Patient wait (#63078): the user's message is already the accepted
+        # in-flight turn, so a slow deferred build must not eat it. The wait
+        # delivers the prompt when the still-running build completes, honors a
+        # cancel promptly, notices the user once past the slow threshold, and
+        # only errors when the build itself fails or the bounded cap expires.
+        err = _wait_agent_for_prompt(session, rid, sid)
         if err:
-            _emit(
-                "error",
+            # Terminal frame + retained snapshot (not a bare "error" event +
+            # cleared inflight): if the client is disconnected right now, the
+            # retained snapshot is the only way resume can show this failure.
+            _emit_terminal_turn_error(
                 sid,
-                {
-                    "message": (err.get("error") or {}).get(
-                        "message", "agent initialization failed"
-                    )
-                },
+                session,
+                (err.get("error") or {}).get("message", "agent initialization failed"),
             )
             with session["history_lock"]:
                 session["running"] = False
-                _clear_inflight_turn(session)
+                session["last_active"] = time.time()
+            _emit("session.info", sid, _session_info(session.get("agent"), session))
             return
         with session["history_lock"]:
             if session.get("_turn_cancel_requested") or not session.get("running"):
                 session["running"] = False
                 _clear_inflight_turn(session)
+                # Surface the cancellation to the client. Without this emit the
+                # turn vanishes silently — the Desktop sees `prompt.submit`
+                # return `{"status": "streaming"}` but never receives a
+                # `message.start` or `error` event, so the composer shows no
+                # feedback (issue #63078 server-side half). Match the
+                # `_wait_agent` error branch above: emit, then bail.
+                _emit(
+                    "error",
+                    sid,
+                    {
+                        "message": "Turn cancelled before the agent was ready"
+                        if session.get("_turn_cancel_requested")
+                        else "Session no longer running before the agent was ready"
+                    },
+                )
                 return
         _run_prompt_submit(rid, sid, session, text)
 
@@ -10558,7 +11355,10 @@ def _run_prompt_submit(
         history_version = int(session.get("history_version", 0))
         images = list(session.get("attached_images", []))
         session["attached_images"] = []
-        if not isinstance(session.get("inflight_turn"), dict):
+        inflight = session.get("inflight_turn")
+        # A retained failed turn (see _fail_inflight_turn) is a stale leftover
+        # by the time a new turn starts — replace it, never append onto it.
+        if not isinstance(inflight, dict) or inflight.get("status") == "error":
             _start_inflight_turn(session, text)
     agent = session["agent"]
     if hasattr(agent, "clear_interrupt"):
@@ -10575,6 +11375,21 @@ def _run_prompt_submit(
         goal_followup = None  # set by the post-turn goal hook below
         tts_queue = None  # streaming-TTS feed for this turn (voice mode)
         one_turn_restore = session.pop("one_turn_model_restore", None)
+        # True once a failed turn's snapshot was retained for resume replay —
+        # tells the finally below to skip the normal inflight clear.
+        turn_error_retained = False
+        # Durable crash marker: written before the turn runs, retired the
+        # moment its outcome reaches the client (see _retire_turn_marker).
+        # Any concluded turn — success, handled error, interrupt — retires
+        # it, so a marker that survives means the process died mid-turn;
+        # session.resume auto-continues from it. Compression can rotate
+        # session_key mid-turn, so remember the key we wrote under.
+        marker_home = _session_home(session)
+        marker_key = str(session.get("session_key") or "")
+        marker_attempt = int(session.pop("_auto_continue_attempt", 0) or 0)
+        marker_text = session.pop("_auto_continue_prompt", None) or text
+        if isinstance(marker_text, str) and marker_text.strip():
+            record_turn_start(marker_home, marker_key, marker_text, attempts=marker_attempt)
         try:
             from tools.approval import (
                 reset_current_session_key,
@@ -10746,6 +11561,9 @@ def _run_prompt_submit(
             run_kwargs = {
                 "conversation_history": list(history),
                 "stream_callback": _stream,
+                "persist_user_message": (
+                    _build_persist_user_message(prompt, images, run_message) if images else prompt
+                ),
             }
             try:
                 if "task_id" in inspect.signature(agent.run_conversation).parameters:
@@ -10898,7 +11716,24 @@ def _run_prompt_submit(
             if rendered:
                 payload["rendered"] = rendered
             with session["history_lock"]:
-                _clear_inflight_turn(session)
+                if status == "error":
+                    # Returned-error result (provider 4xx, budget, etc.): retain
+                    # the failed turn for resume replay instead of clearing it.
+                    # If this terminal frame is lost to a disconnect, resume's
+                    # inflight payload is the only carrier of the failure.
+                    _fail_inflight_turn(
+                        session,
+                        result.get("error") if isinstance(result, dict) else raw,
+                    )
+                    turn_error_retained = True
+                else:
+                    _clear_inflight_turn(session)
+            if status == "error":
+                payload["error"] = str(
+                    (result.get("error") if isinstance(result, dict) else "") or raw
+                )
+                payload["recoverable"] = True
+            _retire_turn_marker(session, marker_key)
             _emit("message.complete", sid, payload)
 
             # ── /goal continuation (Ralph-style loop) ─────────────────
@@ -10953,26 +11788,26 @@ def _run_prompt_submit(
                         file=sys.stderr,
                     )
 
-            # Apply pending_title now that the DB row exists.
+            # Apply pending_title now that the DB row exists — in the
+            # session-owned profile store (not the launch profile).
             _pending = session.get("pending_title")
             if _pending and status == "complete":
-                _pdb = _get_db()
-                if _pdb:
-                    _session_key = session.get("session_key") or sid
-                    try:
-                        if _pdb.set_session_title(_session_key, _pending):
+                _session_key = session.get("session_key") or sid
+                try:
+                    with _session_db(session) as _pdb:
+                        if _pdb and _pdb.set_session_title(_session_key, _pending):
                             session["pending_title"] = None
-                    except ValueError as exc:
-                        # Invalid/duplicate title — non-retryable, drop it.
-                        # Auto-title will take over. Fix for #19029.
-                        session["pending_title"] = None
-                        logger.info(
-                            "Dropping pending title for session %s: %s",
-                            _session_key, exc,
-                        )
-                    except Exception:
-                        # Transient DB failure — keep pending_title for retry.
-                        pass
+                except ValueError as exc:
+                    # Invalid/duplicate title — non-retryable, drop it.
+                    # Auto-title will take over. Fix for #19029.
+                    session["pending_title"] = None
+                    logger.info(
+                        "Dropping pending title for session %s: %s",
+                        _session_key, exc,
+                    )
+                except Exception:
+                    # Transient DB failure — keep pending_title for retry.
+                    pass
 
             if (
                 status == "complete"
@@ -11060,7 +11895,20 @@ def _run_prompt_submit(
             print(
                 f"[gateway-turn] {type(e).__name__}: {e}", file=sys.stderr, flush=True
             )
-            _emit("error", sid, {"message": str(e)})
+            try:
+                # Close the turn with the same terminal error frame shape as
+                # the returned-error path (uniform client handling), retaining
+                # the failed turn for resume replay.
+                _emit_terminal_turn_error(sid, session, e)
+                turn_error_retained = True
+            except Exception as emit_exc:
+                print(
+                    f"[gateway-turn] terminal error emit failed: "
+                    f"{type(emit_exc).__name__}: {emit_exc}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+                _emit("error", sid, {"message": str(e)})
         finally:
             if tts_queue is not None:
                 tts_queue.put(None)  # end-of-text sentinel — flush + finish speaking
@@ -11086,8 +11934,13 @@ def _run_prompt_submit(
             with session["history_lock"]:
                 session["running"] = False
                 session["last_active"] = time.time()
-                _clear_inflight_turn(session)
-            _emit("session.info", sid, _session_info(agent, session))
+                if not turn_error_retained:
+                    _clear_inflight_turn(session)
+            # Backstop for turns that never reached a terminal frame (the
+            # frame paths retire the marker as they emit).
+            _retire_turn_marker(session, marker_key)
+            session.pop("_auto_continue_scheduled", None)
+            _emit_settled_session_info(sid, session, agent)
 
         # A user prompt that arrived mid-turn (interrupt + queue) wins over
         # every auto follow-up below — drain it first and skip them this cycle;
@@ -11500,6 +12353,9 @@ def _(rid, params: dict) -> dict:
         try:
             res = subprocess.run(
                 argv, capture_output=True, text=True, timeout=120, stdin=subprocess.DEVNULL,
+                # Force UTF-8 + lossy decode so non-UTF-8 child output can't
+                # crash the gateway thread on locale-mismatched Windows (#53137).
+                encoding="utf-8", errors="replace",
                 creationflags=windows_hide_flags(),
             )
         except subprocess.TimeoutExpired:
@@ -12944,7 +13800,12 @@ def _discover_repos_payload(
                 agg = _agg(root)
                 if entry.get("label"):
                     agg["label"] = entry["label"]
-                agg["last_active"] = max(agg["last_active"], float(entry.get("last_seen") or 0))
+                # NOTE: `last_seen` is when the disk scan last saw the directory,
+                # not when the user last worked in it. Folding it into
+                # `last_active` stamped every scanned repo with the scan time —
+                # i.e. "just now" — so a git checkout with zero Hermes sessions
+                # outranked the repos the user actually works in. Activity stays
+                # session-derived; a repo with no sessions has no activity.
 
         if conn is not None:
             _read(conn)
@@ -13141,12 +14002,34 @@ def _project_tree_inputs(
     return sessions, projects, discovered, active_id
 
 
+# Per-build memo for `_dir_exists_cached`. Cleared at the top of every
+# `_build_project_tree`, so a dir created or deleted between sidebar refreshes
+# is seen on the next one.
+_DIR_EXISTS_CACHE: dict[str, bool] = {}
+
+
+def _dir_exists_cached(path: str) -> bool:
+    """``os.path.isdir`` for the project tree, memoized per build.
+
+    ``build_tree`` asks per SESSION, not per distinct path, so a power user with
+    hundreds of sessions across a handful of dirs would otherwise fire hundreds
+    of redundant stats on every sidebar open. The memo is per build, so a dir
+    created or deleted between refreshes is picked up on the next one.
+    """
+    hit = _DIR_EXISTS_CACHE.get(path)
+    if hit is None:
+        hit = os.path.isdir(path)
+        _DIR_EXISTS_CACHE[path] = hit
+    return hit
+
+
 def _build_project_tree(
     db, *, preview_limit: int, hydrate: bool, session_limit: int, include_discovered: bool
 ) -> tuple[dict, str | None]:
     """Gather inputs and run the one authoritative builder. Returns (tree, active_id)."""
     from tui_gateway import project_tree
 
+    _DIR_EXISTS_CACHE.clear()
     sessions, projects, discovered, active_id = _project_tree_inputs(
         db, session_limit, include_discovered=include_discovered
     )
@@ -13159,6 +14042,7 @@ def _build_project_tree(
         hydrate=hydrate,
         is_junk_root=_is_repo_junk,
         is_junk_cwd=_is_session_cwd_junk,
+        exists=_dir_exists_cached,
     )
     return tree, active_id
 
@@ -13977,6 +14861,10 @@ def _(rid, params: dict) -> dict:
             [sys.executable, "-m", "hermes_cli.main", *argv],
             capture_output=True,
             text=True,
+            # Force UTF-8 + lossy decode so non-UTF-8 child output can't crash
+            # the gateway thread on locale-mismatched Windows. See #53137.
+            encoding="utf-8",
+            errors="replace",
             timeout=min(int(params.get("timeout", 240)), 600),
             cwd=os.getcwd(),
             # cli.exec runs `python -m hermes_cli.main` (can drive the agent) →
@@ -14050,6 +14938,9 @@ def _(rid, params: dict) -> dict:
                 shell=True,
                 capture_output=True,
                 text=True,
+                # Force UTF-8 + lossy decode so non-UTF-8 child output can't
+                # crash the gateway thread on locale-mismatched Windows (#53137).
+                encoding="utf-8", errors="replace",
                 timeout=30,
                 stdin=subprocess.DEVNULL,
                 env=sanitized_env,
@@ -15052,6 +15943,14 @@ def _(rid, params: dict) -> dict:
             skill_bundles_provider=lambda: get_skill_bundles(),
         )
         doc = Document(text, len(text))
+        # Skill commands and bundles are the only completions offered for an
+        # inline `/skill` reference typed mid-message, so the class has to
+        # reach the TUI as data. Derived from the same providers the completer
+        # uses — no sniffing the ⚡/▣ meta glyphs, which are display text.
+        skill_names = {
+            key.lstrip("/").lower()
+            for key in (*get_skill_commands(), *get_skill_bundles())
+        }
         items = [
             {
                 "text": c.text,
@@ -15062,6 +15961,11 @@ def _(rid, params: dict) -> dict:
                 # layout into 1-char truncation of the next column.
                 "display": to_plain_text(c.display) if c.display else c.text,
                 "meta": to_plain_text(c.display_meta) if c.display_meta else "",
+                "kind": (
+                    "skill"
+                    if c.text.strip().lstrip("/").lower() in skill_names
+                    else "command"
+                ),
             }
             for c in completer.get_completions(doc, None)
         ][:30]
@@ -15071,21 +15975,25 @@ def _(rid, params: dict) -> dict:
                 "text": "/density",
                 "display": "/density",
                 "meta": "Toggle compact display mode",
+                "kind": "command",
             },
             {
                 "text": "/details",
                 "display": "/details",
                 "meta": "Control agent detail visibility",
+                "kind": "command",
             },
             {
                 "text": "/logs",
                 "display": "/logs",
                 "meta": "Show recent gateway log lines",
+                "kind": "command",
             },
             {
                 "text": "/mouse",
                 "display": "/mouse",
                 "meta": "Set mouse tracking preset [on|off|toggle|wheel|buttons|all]",
+                "kind": "command",
             },
         ]
         for extra in extras:
@@ -15127,6 +16035,8 @@ def _model_picker_context(agent):
                 canonical_custom_identity(
                     base_url=base_url or None,
                     config_provider=ctx.current_provider,
+                    model=(getattr(agent, "model", "") if agent else "")
+                    or None,
                 )
                 or provider
             )
@@ -15147,7 +16057,7 @@ def _model_picker_context(agent):
 @method("model.options")
 def _(rid, params: dict) -> dict:
     try:
-        from hermes_cli.inventory import build_models_payload
+        from hermes_cli.inventory import build_model_options_payload
 
         session = _sessions.get(params.get("session_id", ""))
         agent = session.get("agent") if session else None
@@ -15156,25 +16066,11 @@ def _(rid, params: dict) -> dict:
         # agent attributes must NOT clobber disk config (with_overrides
         # is truthy-only).
         ctx = _model_picker_context(agent)
-        # picker_hints + canonical_order produce the TUI/desktop picker shape:
-        # `authenticated`/`auth_type`/`key_env`/`warning` per row, in
-        # CANONICAL_PROVIDERS declaration order. Desktop pickers default to the
-        # configured subset; callers that need setup affordances can pass
-        # include_unconfigured=true explicitly.
-        # Curated model lists are preserved — list_authenticated_providers
-        # populates `models` from the curated catalog, not provider_model_ids
-        # (which would pull non-agentic models like TTS/embeddings/etc.).
-        payload = build_models_payload(
+        payload = build_model_options_payload(
             ctx,
             explicit_only=bool(params.get("explicit_only")),
             include_unconfigured=bool(params.get("include_unconfigured")),
-            picker_hints=True,
-            canonical_order=True,
-            pricing=True,
-            capabilities=True,
             refresh=bool(params.get("refresh")),
-            probe_custom_providers=bool(params.get("refresh")),
-            probe_current_custom_provider=not bool(params.get("refresh")),
         )
         return _ok(rid, payload)
     except Exception as e:
@@ -15815,15 +16711,26 @@ def _(rid, params: dict) -> dict:
 
     worker = session.get("slash_worker")
     if not worker:
-        try:
-            worker = _SlashWorker(
-                session["session_key"],
-                getattr(session.get("agent"), "model", _resolve_model()),
-                profile_home=session.get("profile_home"),
-            )
-            _attach_worker(params.get("session_id", ""), session, worker)
-        except Exception as e:
-            return _err(rid, 5030, f"slash worker start failed: {e}")
+        # On-demand spawn is now the ONLY spawn path for a fresh session
+        # (eager pre-warm removed), and slash.exec handlers run on the RPC
+        # thread pool — two concurrent slash commands on the same session
+        # could both observe slash_worker=None and each fork a full
+        # MCP-fleet worker (the loser of the _attach_worker race would leak
+        # unclosed). Serialize first-use spawn per session.
+        with _sessions_lock:
+            spawn_lock = session.setdefault("_slash_spawn_lock", threading.Lock())
+        with spawn_lock:
+            worker = session.get("slash_worker")
+            if not worker:
+                try:
+                    worker = _SlashWorker(
+                        session["session_key"],
+                        getattr(session.get("agent"), "model", _resolve_model()),
+                        profile_home=session.get("profile_home"),
+                    )
+                    _attach_worker(params.get("session_id", ""), session, worker)
+                except Exception as e:
+                    return _err(rid, 5030, f"slash worker start failed: {e}")
 
     try:
         output = worker.run(cmd)
@@ -16719,7 +17626,10 @@ def _(rid, params: dict) -> dict:
             if session
             else _load_enabled_toolsets()
         )
-        tools = get_tool_definitions(enabled_toolsets=enabled, quiet_mode=True)
+        # Pre-assembly list: /tools is a discovery surface and must show
+        # tools deferred behind the tool_search bridge (same as the CLI).
+        tools = get_tool_definitions(enabled_toolsets=enabled, quiet_mode=True,
+                                     skip_tool_search_assembly=True)
         sections = {}
 
         for tool in sorted(tools, key=lambda t: t["function"]["name"]):
@@ -17143,6 +18053,9 @@ def _(rid, params: dict) -> dict:
 
         r = subprocess.run(
             cmd, shell=True, capture_output=True, text=True, timeout=30, cwd=os.getcwd(),
+            # Force UTF-8 + lossy decode so non-UTF-8 child output can't crash
+            # the gateway thread on locale-mismatched Windows (#53137).
+            encoding="utf-8", errors="replace",
             stdin=subprocess.DEVNULL,
             creationflags=windows_hide_flags(),
         )
diff --git a/tui_gateway/turn_marker.py b/tui_gateway/turn_marker.py
new file mode 100644
index 00000000000..933f384f37d
--- /dev/null
+++ b/tui_gateway/turn_marker.py
@@ -0,0 +1,159 @@
+"""Durable interrupted-turn markers for the desktop/TUI auto-continue path.
+
+A running turn's progress lives only in process memory (the agent flushes to
+SQLite at turn end, not mid-turn), so an app/backend/machine death mid-turn
+leaves no durable trace of the interrupted prompt. This sidecar is that
+trace: a marker is written when a turn starts running and cleared when the
+turn concludes — success, handled error, or interrupt all clear it, so only
+a process death leaves one behind. ``session.resume`` reads the marker to
+decide whether to auto-continue the interrupted turn (see
+``_maybe_schedule_auto_continue`` in ``tui_gateway/server.py``).
+
+Markers are stored per ``HERMES_HOME`` (callers pass the session's home so
+profile sessions keep their state in their own profile directory) and the
+file is bounded: writes prune entries older than ``_MAX_AGE_SECS`` and cap
+the total count, so an unlucky streak of crashes can't grow it unboundedly.
+
+Every function is best-effort by design — marker bookkeeping must never
+break a turn — so I/O errors degrade to "no marker" instead of raising.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_MARKER_DIR = "desktop"
+_MARKER_FILE = "interrupted_turns.json"
+_MAX_AGE_SECS = 24 * 3600
+_MAX_ENTRIES = 32
+# Enough to re-submit any realistic prompt; guards the sidecar against a
+# pathological multi-megabyte paste being journaled on every turn.
+_MAX_PROMPT_CHARS = 64_000
+
+_lock = threading.Lock()
+
+
+def _marker_path(home: Path | str) -> Path:
+    return Path(home) / _MARKER_DIR / _MARKER_FILE
+
+
+def _load(path: Path) -> dict[str, dict]:
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        return {}
+    except Exception:
+        logger.debug("unreadable turn-marker file %s; starting fresh", path, exc_info=True)
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {k: v for k, v in data.items() if isinstance(v, dict)}
+
+
+def _prune(entries: dict[str, dict], now: float) -> dict[str, dict]:
+    fresh = {
+        key: entry
+        for key, entry in entries.items()
+        if now - float(entry.get("started_at") or 0) <= _MAX_AGE_SECS
+    }
+    if len(fresh) <= _MAX_ENTRIES:
+        return fresh
+    newest = sorted(
+        fresh.items(),
+        key=lambda item: float(item[1].get("started_at") or 0),
+        reverse=True,
+    )[:_MAX_ENTRIES]
+    return dict(newest)
+
+
+def _store(path: Path, entries: dict[str, dict]) -> None:
+    if not entries:
+        path.unlink(missing_ok=True)
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".turn-marker-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(entries, f)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def record_turn_start(
+    home: Path | str, session_key: str, prompt: str, *, attempts: int = 0
+) -> None:
+    """Persist the marker for a turn that is about to run.
+
+    ``attempts`` counts how many auto-continues led to this run: 0 for a
+    user-initiated turn, N for the Nth automatic re-run — the crash-loop
+    breaker reads it back on the next resume.
+    """
+    if not session_key or not prompt:
+        return
+    now = time.time()
+    entry = {
+        "attempts": max(0, int(attempts)),
+        "prompt": prompt[:_MAX_PROMPT_CHARS],
+        "started_at": now,
+    }
+    try:
+        with _lock:
+            path = _marker_path(home)
+            entries = _prune(_load(path), now)
+            entries[session_key] = entry
+            _store(path, entries)
+    except Exception:
+        logger.debug("failed to record turn marker for %s", session_key, exc_info=True)
+
+
+def clear_turn_marker(home: Path | str, session_key: str) -> None:
+    """Remove the marker once its turn concluded (any outcome the client saw)."""
+    if not session_key:
+        return
+    try:
+        with _lock:
+            path = _marker_path(home)
+            entries = _load(path)
+            if session_key not in entries:
+                return
+            del entries[session_key]
+            _store(path, entries)
+    except Exception:
+        logger.debug("failed to clear turn marker for %s", session_key, exc_info=True)
+
+
+def read_turn_marker(home: Path | str, session_key: str) -> dict[str, Any] | None:
+    """The marker left by a turn that never concluded, or None."""
+    if not session_key:
+        return None
+    try:
+        with _lock:
+            entry = _load(_marker_path(home)).get(session_key)
+    except Exception:
+        return None
+    if not isinstance(entry, dict):
+        return None
+    prompt = str(entry.get("prompt") or "")
+    if not prompt.strip():
+        return None
+    try:
+        started_at = float(entry.get("started_at") or 0)
+        attempts = max(0, int(entry.get("attempts") or 0))
+    except (TypeError, ValueError):
+        return None
+    return {"attempts": attempts, "prompt": prompt, "started_at": started_at}
diff --git a/ui-tui/packages/hermes-ink/src/entry-exports.ts b/ui-tui/packages/hermes-ink/src/entry-exports.ts
index 49bbf21179f..1488124034d 100644
--- a/ui-tui/packages/hermes-ink/src/entry-exports.ts
+++ b/ui-tui/packages/hermes-ink/src/entry-exports.ts
@@ -10,7 +10,7 @@ export { NoSelect } from './ink/components/NoSelect.js'
 export { RawAnsi } from './ink/components/RawAnsi.js'
 export { default as ScrollBox } from './ink/components/ScrollBox.js'
 export { default as Spacer } from './ink/components/Spacer.js'
-export { default as Text } from './ink/components/Text.js'
+export { setDimFallbackColor, default as Text } from './ink/components/Text.js'
 export { default as useApp } from './ink/hooks/use-app.js'
 export { useCursorAdvance } from './ink/hooks/use-cursor-advance.js'
 export { useDeclaredCursor } from './ink/hooks/use-declared-cursor.js'
diff --git a/ui-tui/packages/hermes-ink/src/ink/components/Text.test.ts b/ui-tui/packages/hermes-ink/src/ink/components/Text.test.ts
index c94f6349d8f..f6bbfe13622 100644
--- a/ui-tui/packages/hermes-ink/src/ink/components/Text.test.ts
+++ b/ui-tui/packages/hermes-ink/src/ink/components/Text.test.ts
@@ -1,6 +1,6 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 
-import { dimColorFallback, shouldUseAnsiDim } from './Text.js'
+import { dimColorFallback, setDimFallbackColor, shouldUseAnsiDim } from './Text.js'
 
 describe('shouldUseAnsiDim', () => {
   it('disables ANSI dim on VTE terminals by default', () => {
@@ -23,6 +23,10 @@ describe('shouldUseAnsiDim', () => {
 })
 
 describe('dimColorFallback', () => {
+  afterEach(() => {
+    setDimFallbackColor(undefined)
+  })
+
   it('renders Apple Terminal dim as muted gray by default', () => {
     expect(dimColorFallback({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe('#6B7280')
   })
@@ -39,4 +43,23 @@ describe('dimColorFallback', () => {
       dimColorFallback({ HERMES_TUI_DIM: '0', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)
     ).toBeUndefined()
   })
+
+  it('uses the theme tone once one is supplied, so dim stays in-palette', () => {
+    setDimFallbackColor('#936e06')
+
+    expect(dimColorFallback({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe('#936e06')
+  })
+
+  it('falls back to the boot default when the theme tone is cleared', () => {
+    setDimFallbackColor('#936e06')
+    setDimFallbackColor(undefined)
+
+    expect(dimColorFallback({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe('#6B7280')
+  })
+
+  it('stays inert on terminals that honor SGR 2, whatever the theme tone', () => {
+    setDimFallbackColor('#936e06')
+
+    expect(dimColorFallback({ TERM: 'xterm-256color' } as NodeJS.ProcessEnv)).toBeUndefined()
+  })
 })
diff --git a/ui-tui/packages/hermes-ink/src/ink/components/Text.tsx b/ui-tui/packages/hermes-ink/src/ink/components/Text.tsx
index 4eb4bc7b963..491cb545cb2 100644
--- a/ui-tui/packages/hermes-ink/src/ink/components/Text.tsx
+++ b/ui-tui/packages/hermes-ink/src/ink/components/Text.tsx
@@ -84,6 +84,19 @@ export function shouldUseAnsiDim(env: NodeJS.ProcessEnv = process.env): boolean
   return !env.VTE_VERSION
 }
 
+/**
+ * Terminals that ignore SGR 2 need a literal color instead. The tone is
+ * theme-supplied (setDimFallbackColor, called from the theme effect) so it
+ * stays inside the active palette; the slate below is only the pre-theme
+ * boot default. A hardcoded value here reads as an off-palette foreground
+ * next to themed spans on the same line — cold gray beside warm ink.
+ */
+let dimFallbackColor: Color = LEGACY_APPLE_DIM_COLOR
+
+export function setDimFallbackColor(color: Color | undefined): void {
+  dimFallbackColor = color || LEGACY_APPLE_DIM_COLOR
+}
+
 export function dimColorFallback(env: NodeJS.ProcessEnv = process.env): Color | undefined {
   const override = (env.HERMES_TUI_DIM ?? '').trim()
 
@@ -91,7 +104,7 @@ export function dimColorFallback(env: NodeJS.ProcessEnv = process.env): Color |
     return undefined
   }
 
-  return (env.TERM_PROGRAM ?? '').trim() === 'Apple_Terminal' ? LEGACY_APPLE_DIM_COLOR : undefined
+  return (env.TERM_PROGRAM ?? '').trim() === 'Apple_Terminal' ? dimFallbackColor : undefined
 }
 
 const memoizedStylesForWrap: Record<NonNullable<Styles['textWrap']>, Styles> = {
diff --git a/ui-tui/src/__tests__/completionApply.test.ts b/ui-tui/src/__tests__/completionApply.test.ts
index 5b26f8810d3..b8870a94278 100644
--- a/ui-tui/src/__tests__/completionApply.test.ts
+++ b/ui-tui/src/__tests__/completionApply.test.ts
@@ -16,6 +16,18 @@ describe('applyCompletion', () => {
   it('replaces an argument token after a space (subcommand completion)', () => {
     expect(applyCompletion('/cron ad', 'add', 6)).toBe('/cron add')
   })
+
+  it('applies an inline skill pick without disturbing the prose in front of it', () => {
+    // The gateway returns bare names for `complete.slash`; a mid-message
+    // reference replaces from just after its own `/`, so "please run " stays.
+    expect(applyCompletion('please run /cle', 'clean', 12)).toBe('please run /clean')
+  })
+
+  it('drops the row slash based on the character before the replace point, not the input start', () => {
+    // Widget-app rows carry a leading slash. Mid-message the input does NOT
+    // start with `/`, so a start-anchored check would double it up.
+    expect(applyCompletion('please run /cle', '/clean', 12)).toBe('please run /clean')
+  })
 })
 
 describe('completionToApplyOnSubmit', () => {
diff --git a/ui-tui/src/__tests__/inlineSlashSkill.test.ts b/ui-tui/src/__tests__/inlineSlashSkill.test.ts
new file mode 100644
index 00000000000..d2f81b7059f
--- /dev/null
+++ b/ui-tui/src/__tests__/inlineSlashSkill.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+
+import { inlineSlashTrigger, splitSlashSkillRefs } from '../domain/slash.js'
+import { completionRequestForInput } from '../hooks/useCompletion.js'
+
+describe('inlineSlashTrigger', () => {
+  it('detects a slash typed mid-message', () => {
+    // The reported bug: only a position-0 slash offered anything, so
+    // "please run /cle" completed nothing.
+    expect(inlineSlashTrigger('please run /cle')).toEqual({ query: 'cle', start: 11 })
+  })
+
+  it('detects a bare slash after whitespace, before any name is typed', () => {
+    expect(inlineSlashTrigger('please run /')).toEqual({ query: '', start: 11 })
+  })
+
+  it('fires after a newline, not just a space', () => {
+    expect(inlineSlashTrigger('text\n/skill')).toEqual({ query: 'skill', start: 5 })
+  })
+
+  it('does not fire at position 0 — that is a command invocation', () => {
+    expect(inlineSlashTrigger('/clean')).toBeNull()
+    expect(inlineSlashTrigger('/')).toBeNull()
+  })
+
+  it('leaves file paths alone', () => {
+    expect(inlineSlashTrigger('look at /usr/local/bin')).toBeNull()
+    expect(inlineSlashTrigger('check src/foo/bar')).toBeNull()
+    expect(inlineSlashTrigger('and/or')).toBeNull()
+  })
+
+  it('stops at the command token — an inline reference takes no args', () => {
+    // Only a position-0 slash is a real invocation, so `/personality alic`
+    // mid-message is prose with a reference in it, already ended.
+    expect(inlineSlashTrigger('hello there /personality alic')).toBeNull()
+  })
+
+  it('reports a start index that replaces only the typed token', () => {
+    const text = 'please run /cle'
+    const trigger = inlineSlashTrigger(text)!
+
+    expect(text.slice(0, trigger.start)).toBe('please run ')
+    expect(text.slice(trigger.start)).toBe('/cle')
+  })
+})
+
+describe('completionRequestForInput — inline skill references', () => {
+  it('asks for skills only when the slash is mid-message', () => {
+    const request = completionRequestForInput('please run /cle')
+
+    expect(request).toMatchObject({
+      method: 'complete.slash',
+      params: { text: '/cle' },
+      replaceFrom: 12,
+      skillsOnly: true
+    })
+  })
+
+  it('keeps the full command set at position 0', () => {
+    expect(completionRequestForInput('/cle')).toEqual({
+      method: 'complete.slash',
+      params: { text: '/cle' },
+      replaceFrom: 1
+    })
+  })
+
+  it('routes a real mid-message path to path completion, not skills', () => {
+    expect(completionRequestForInput('open src/foo/ba')).toMatchObject({ method: 'complete.path' })
+    expect(completionRequestForInput('open /usr/lo')).toMatchObject({ method: 'complete.path' })
+  })
+})
+
+describe('splitSlashSkillRefs', () => {
+  it('marks a skill referenced mid-prose', () => {
+    expect(splitSlashSkillRefs('clean this up with /clean')).toEqual([
+      { ref: false, text: 'clean this up with ' },
+      { ref: true, text: '/clean' }
+    ])
+  })
+
+  it('keeps the prose on both sides of the reference', () => {
+    expect(splitSlashSkillRefs('run /clean then ship')).toEqual([
+      { ref: false, text: 'run ' },
+      { ref: true, text: '/clean' },
+      { ref: false, text: ' then ship' }
+    ])
+  })
+
+  it('does not mark paths', () => {
+    for (const text of ['look at /usr/local/bin', 'check src/foo/bar', 'a 3 /4 b']) {
+      expect(splitSlashSkillRefs(text)).toEqual([{ ref: false, text }])
+    }
+  })
+
+  it('does not mark a leading slash — that is a command, not a reference', () => {
+    expect(splitSlashSkillRefs('/clean')).toEqual([{ ref: false, text: '/clean' }])
+  })
+
+  it('round-trips the input exactly', () => {
+    for (const text of ['run /clean then /work ok', 'plain text', '', 'look at /usr/local/bin']) {
+      expect(
+        splitSlashSkillRefs(text)
+          .map(s => s.text)
+          .join('')
+      ).toBe(text)
+    }
+  })
+
+  it('always returns at least one segment', () => {
+    expect(splitSlashSkillRefs('')).toEqual([{ ref: false, text: '' }])
+  })
+})
diff --git a/ui-tui/src/__tests__/markdown.test.ts b/ui-tui/src/__tests__/markdown.test.ts
index 0c2b2c5d28e..9c4f0eaed6d 100644
--- a/ui-tui/src/__tests__/markdown.test.ts
+++ b/ui-tui/src/__tests__/markdown.test.ts
@@ -1,12 +1,35 @@
 import { PassThrough } from 'stream'
 
 import { Box, renderSync } from '@hermes/ink'
+import chalk from 'chalk'
 import React from 'react'
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { AUDIO_DIRECTIVE_RE, INLINE_RE, Md, MEDIA_LINE_RE, stripInlineMarkup } from '../components/markdown.js'
+import { __resetLinkTitleCache, fetchLinkTitle } from '../lib/externalLink.js'
 import { stripAnsi } from '../lib/text.js'
-import { DEFAULT_THEME } from '../theme.js'
+import { DEFAULT_THEME, LIGHT_THEME } from '../theme.js'
+
+afterEach(() => {
+  __resetLinkTitleCache()
+  vi.unstubAllGlobals()
+})
+
+// Stub the network and warm the shared title cache, so a subsequent render
+// has the resolved title available synchronously.
+const stubFetchedTitle = (url: string, title: string) => {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue(
+      new Response(`<html><head><title>${title}</title></head></html>`, {
+        headers: { 'content-type': 'text/html' },
+        status: 200
+      })
+    )
+  )
+
+  return fetchLinkTitle(url)
+}
 
 const matches = (text: string) => [...text.matchAll(INLINE_RE)].map(m => m[0])
 const BEL = String.fromCharCode(7)
@@ -266,19 +289,37 @@ describe('Md link labels', () => {
     expect(rendered).not.toContain('https://www.expedia.com/things-to-do/puerto-rico-el-yunque-rainforest-adventure')
   })
 
-  it('keeps explicit markdown labels as the immediate fallback', () => {
+  it('keeps the authored markdown label even when a page title resolves', async () => {
+    const url = 'https://www.expedia.com/things-to-do/puerto-rico-el-yunque-rainforest-adventure'
+
+    // Warm the shared cache so `useLinkTitle` would have a title to render
+    // synchronously — the label must still win.
+    await stubFetchedTitle(url, 'El Yunque Rainforest Adventure | Expedia')
+
     const lines = renderPlain(
       React.createElement(
         Box,
         { width: 80 },
-        React.createElement(Md, {
-          t: DEFAULT_THEME,
-          text: '[Trip details](https://www.expedia.com/things-to-do/puerto-rico-el-yunque-rainforest-adventure)'
-        })
+        React.createElement(Md, { t: DEFAULT_THEME, text: `[Trip details](${url})` })
       )
     )
 
-    expect(lines.join('\n')).toContain('Trip details')
+    const rendered = lines.join('\n')
+
+    expect(rendered).toContain('Trip details')
+    expect(rendered).not.toContain('El Yunque Rainforest Adventure | Expedia')
+  })
+
+  it('still resolves titles for links whose label is just the URL', async () => {
+    const url = 'https://www.expedia.com/things-to-do/puerto-rico-el-yunque-rainforest-adventure'
+
+    await stubFetchedTitle(url, 'Rainforest Adventure Tour')
+
+    const lines = renderPlain(
+      React.createElement(Box, { width: 120 }, React.createElement(Md, { t: DEFAULT_THEME, text: `[${url}](${url})` }))
+    )
+
+    expect(lines.join('\n')).toContain('Rainforest Adventure Tour')
   })
 })
 
@@ -329,3 +370,89 @@ describe('renderTable CJK width alignment', () => {
     expect(qwenCol2).toBe(headerCol2)
   })
 })
+
+describe('body prose stays in the theme palette', () => {
+  // Prose used to render in the terminal's DEFAULT foreground while inline
+  // tokens beside it carried a theme color, so one line mixed two inks.
+  // Because an inline token can match mid-word, so could a single word.
+  // LIGHT_THEME is the vehicle here because every tone in it is hex, so
+  // emitted SGR maps back to palette entries without format juggling.
+  const foregroundRuns = (text: string): string[] => {
+    // chalk is a singleton and defaults to level 0 under vitest (no TTY),
+    // which would emit no SGR at all and make every assertion here vacuous.
+    const savedLevel = chalk.level
+    chalk.level = 3
+
+    const stdout = new PassThrough()
+    const stdin = new PassThrough()
+    const stderr = new PassThrough()
+    let output = ''
+
+    Object.assign(stdout, { columns: 80, isTTY: true, rows: 24 })
+    Object.assign(stdin, { isTTY: false })
+    Object.assign(stderr, { isTTY: false })
+    stdout.on('data', chunk => {
+      output += chunk.toString()
+    })
+
+    const instance = renderSync(
+      React.createElement(Box, { width: 70 }, React.createElement(Md, { cols: 68, t: LIGHT_THEME, text })),
+      {
+        patchConsole: false,
+        stderr: stderr as NodeJS.WriteStream,
+        stdin: stdin as NodeJS.ReadStream,
+        stdout: stdout as NodeJS.WriteStream
+      }
+    )
+
+    instance.unmount()
+    instance.cleanup()
+    chalk.level = savedLevel
+
+    return [...output.matchAll(new RegExp(`${ESC}\\[38;2;(\\d+);(\\d+);(\\d+)m`, 'g'))].map(
+      m =>
+        '#' +
+        m
+          .slice(1, 4)
+          .map(v => Number(v).toString(16).padStart(2, '0'))
+          .join('')
+    )
+  }
+
+  const PALETTE = new Set(
+    Object.values(LIGHT_THEME.color)
+      .filter((v): v is string => typeof v === 'string' && v.startsWith('#'))
+      .map(v => v.toLowerCase())
+  )
+
+  const INK = LIGHT_THEME.color.text.toLowerCase()
+
+  it('opens a paragraph with the theme ink, not the terminal default', () => {
+    expect(foregroundRuns('plain prose line')[0]).toBe(INK)
+  })
+
+  it('keeps every foreground on a mixed-token line inside the palette', () => {
+    // `render_terminal_output` trips the underscore-italic token mid-word —
+    // the exact shape that split one word across two inks.
+    const fg = foregroundRuns('set the `flag` and re-render_terminal_output for the run')
+
+    expect(fg.length).toBeGreaterThan(0)
+
+    for (const c of fg) {
+      expect(PALETTE.has(c)).toBe(true)
+    }
+  })
+
+  it('returns to the theme ink after an inline token, not to the terminal default', () => {
+    const fg = foregroundRuns('before `code` after')
+
+    expect(fg[0]).toBe(INK)
+    expect(fg.at(-1)).toBe(INK)
+  })
+
+  it('themes list-item prose too', () => {
+    for (const text of ['- a bullet item', '1. a numbered item']) {
+      expect(foregroundRuns(text)).toContain(INK)
+    }
+  })
+})
diff --git a/ui-tui/src/__tests__/messageLine.test.ts b/ui-tui/src/__tests__/messageLine.test.ts
index b330bbd2374..9ca72e371cd 100644
--- a/ui-tui/src/__tests__/messageLine.test.ts
+++ b/ui-tui/src/__tests__/messageLine.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { shouldShowResponseSeparator } from '../components/messageLine.js'
+import { shouldShowResponseSeparator, shouldShowThinkingTrail } from '../components/messageLine.js'
 
 describe('shouldShowResponseSeparator', () => {
   it('separates assistant response text from visible details', () => {
@@ -17,3 +17,28 @@ describe('shouldShowResponseSeparator', () => {
     expect(shouldShowResponseSeparator({ role: 'system', text: 'note' }, true)).toBe(false)
   })
 })
+
+describe('shouldShowThinkingTrail', () => {
+  it('hides an ordinary reasoning trail when every section is hidden', () => {
+    const msg = { role: 'system', text: '', thinking: 'plan' } as const
+    expect(shouldShowThinkingTrail(msg, 'hidden', 'hidden', 'hidden')).toBe(false)
+  })
+
+  it('shows an ordinary reasoning trail when any section is visible', () => {
+    const msg = { role: 'system', text: '', thinking: 'plan' } as const
+    expect(shouldShowThinkingTrail(msg, 'collapsed', 'hidden', 'hidden')).toBe(true)
+    expect(shouldShowThinkingTrail(msg, 'hidden', 'collapsed', 'hidden')).toBe(true)
+    expect(shouldShowThinkingTrail(msg, 'hidden', 'hidden', 'expanded')).toBe(true)
+  })
+
+  it('keeps a MoA reference block visible even when every section is hidden (#64657)', () => {
+    const msg = {
+      role: 'system',
+      text: '',
+      thinking: '◇ Reference 1/2 — model-a\nadvice-a',
+      isMoaReference: true
+    } as const
+
+    expect(shouldShowThinkingTrail(msg, 'hidden', 'hidden', 'hidden')).toBe(true)
+  })
+})
diff --git a/ui-tui/src/__tests__/moaProgressActivity.test.ts b/ui-tui/src/__tests__/moaProgressActivity.test.ts
new file mode 100644
index 00000000000..1d76556d202
--- /dev/null
+++ b/ui-tui/src/__tests__/moaProgressActivity.test.ts
@@ -0,0 +1,100 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { createGatewayEventHandler } from '../app/createGatewayEventHandler.js'
+import { resetOverlayState } from '../app/overlayStore.js'
+import { turnController } from '../app/turnController.js'
+import { getTurnState, resetTurnState } from '../app/turnStore.js'
+import { patchUiState, resetUiState } from '../app/uiStore.js'
+import type { Msg } from '../types.js'
+
+const ref = <T>(current: T) => ({ current })
+
+const buildCtx = (appended: Msg[]) =>
+  ({
+    composer: {
+      dequeue: () => undefined,
+      queueEditRef: ref<null | number>(null),
+      sendQueued: () => undefined,
+      setInput: () => undefined
+    },
+    gateway: {
+      gw: { request: () => undefined },
+      rpc: async () => null
+    },
+    session: {
+      STARTUP_RESUME_ID: '',
+      colsRef: ref(80),
+      newSession: () => undefined,
+      resetSession: () => undefined,
+      resumeById: () => undefined,
+      setCatalog: () => undefined
+    },
+    submission: {
+      submitRef: { current: () => undefined }
+    },
+    system: {
+      bellOnComplete: false,
+      sys: () => undefined
+    },
+    transcript: {
+      appendMessage: (msg: Msg) => appended.push(msg),
+      panel: () => undefined,
+      setHistoryItems: () => undefined
+    },
+    voice: {
+      setProcessing: () => undefined,
+      setRecording: () => undefined,
+      setVoiceEnabled: () => undefined
+    }
+  }) as any
+
+const activityTexts = () => getTurnState().activity.map(item => item.text)
+
+describe('moa.progress / moa.phase activity surface', () => {
+  beforeEach(() => {
+    resetOverlayState()
+    resetUiState()
+    resetTurnState()
+    turnController.fullReset()
+    patchUiState({ showReasoning: true })
+  })
+
+  it('shows "MoA: refs k/n" as each reference completes, replacing in place', () => {
+    const onEvent = createGatewayEventHandler(buildCtx([]))
+
+    onEvent({ payload: {}, type: 'message.start' } as any)
+    onEvent({ payload: { label: 'model-a', refs_done: 1, refs_total: 3 }, type: 'moa.progress' } as any)
+
+    expect(activityTexts()).toContain('MoA: refs 1/3')
+
+    onEvent({ payload: { label: 'model-b', refs_done: 2, refs_total: 3 }, type: 'moa.progress' } as any)
+
+    const texts = activityTexts()
+    expect(texts).toContain('MoA: refs 2/3')
+    // Replaced in place — the stale 1/3 line must not linger alongside 2/3.
+    expect(texts).not.toContain('MoA: refs 1/3')
+  })
+
+  it('swaps the progress line for aggregator copy on moa.phase', () => {
+    const onEvent = createGatewayEventHandler(buildCtx([]))
+
+    onEvent({ payload: {}, type: 'message.start' } as any)
+    onEvent({ payload: { label: 'model-a', refs_done: 3, refs_total: 3 }, type: 'moa.progress' } as any)
+    onEvent({ payload: { phase: 'aggregator', refs_done: 3, refs_total: 3 }, type: 'moa.phase' } as any)
+
+    const texts = activityTexts()
+    expect(texts).toContain('MoA: aggregating…')
+    expect(texts).not.toContain('MoA: refs 3/3')
+  })
+
+  it('ignores malformed payloads (missing counters / unknown phase)', () => {
+    const onEvent = createGatewayEventHandler(buildCtx([]))
+
+    onEvent({ payload: {}, type: 'message.start' } as any)
+    const before = activityTexts().length
+    onEvent({ payload: { label: 'model-a' }, type: 'moa.progress' } as any)
+    onEvent({ payload: { phase: 'reference' }, type: 'moa.phase' } as any)
+
+    expect(activityTexts().length).toBe(before)
+  })
+})
diff --git a/ui-tui/src/__tests__/thinkingMoaReferenceVisibility.test.tsx b/ui-tui/src/__tests__/thinkingMoaReferenceVisibility.test.tsx
new file mode 100644
index 00000000000..91b332c0007
--- /dev/null
+++ b/ui-tui/src/__tests__/thinkingMoaReferenceVisibility.test.tsx
@@ -0,0 +1,61 @@
+import { PassThrough } from 'stream'
+
+import { renderSync } from '@hermes/ink'
+import React from 'react'
+import { describe, expect, it } from 'vitest'
+
+import { ToolTrail } from '../components/thinking.js'
+import { stripAnsi } from '../lib/text.js'
+import { DEFAULT_THEME } from '../theme.js'
+
+describe('ToolTrail — MoA reference panel visibility (#64701)', () => {
+  it('stays expanded after mount effects settle when reasoningAlwaysVisible is set, even under sections.thinking: hidden', async () => {
+    const stdout = new PassThrough()
+    const stdin = new PassThrough()
+    const stderr = new PassThrough()
+    let output = ''
+
+    Object.assign(stdout, { columns: 60, isTTY: false, rows: 20 })
+    Object.assign(stdin, { isTTY: false })
+    Object.assign(stderr, { isTTY: false })
+    stdout.on('data', chunk => {
+      output += chunk.toString()
+    })
+
+    const instance = renderSync(
+      <ToolTrail
+        reasoning="Reference model output that must stay visible on first paint."
+        reasoningAlwaysVisible
+        sections={{ thinking: 'hidden' }}
+        t={DEFAULT_THEME}
+      />,
+      {
+        patchConsole: false,
+        stderr: stderr as NodeJS.WriteStream,
+        stdin: stdin as NodeJS.ReadStream,
+        stdout: stdout as NodeJS.WriteStream
+      }
+    )
+
+    // Let queued passive effects (and any re-render they trigger) flush
+    // before reading the frame — the #64701 bug is specifically that the
+    // re-sync effect fires AFTER the first paint and clobbers the
+    // reasoningAlwaysVisible mount value, so asserting on the pre-effect
+    // frame alone would miss the regression entirely.
+    await new Promise(resolve => setImmediate(resolve))
+    await new Promise(resolve => setImmediate(resolve))
+
+    const frame = stripAnsi(output)
+
+    instance.unmount()
+    instance.cleanup()
+
+    // Open chevron (▾) means the panel is still expanded once effects have
+    // settled, as the reasoningAlwaysVisible-seeded useState value intends.
+    // A collapsed (▸) render here means the re-sync effect fired on mount
+    // and clobbered it — the exact #64701 regression.
+    expect(frame).toContain('▾ ')
+    expect(frame).toContain('Thinking')
+    expect(frame).not.toContain('▸ ')
+  })
+})
diff --git a/ui-tui/src/app/createGatewayEventHandler.ts b/ui-tui/src/app/createGatewayEventHandler.ts
index 8527e083a58..d8630e21673 100644
--- a/ui-tui/src/app/createGatewayEventHandler.ts
+++ b/ui-tui/src/app/createGatewayEventHandler.ts
@@ -1005,6 +1005,25 @@ export function createGatewayEventHandler(ctx: GatewayEventHandlerContext): (ev:
         // through the normal message stream. No committed transcript entry.
         return
 
+      case 'moa.progress':
+        // Live fan-out progress — one activity line, replaced in place as each
+        // reference completes ("MoA: refs 2/3"), so the user sees movement
+        // during the (potentially long) reference phase without transcript spam.
+        if (typeof ev.payload?.refs_done === 'number' && typeof ev.payload?.refs_total === 'number') {
+          turnController.pushActivity(`MoA: refs ${ev.payload.refs_done}/${ev.payload.refs_total}`, 'info', 'MoA')
+        }
+
+        return
+
+      case 'moa.phase':
+        // Phase transition — currently only phase="aggregator" (fan-out done,
+        // aggregator acting). Swap the progress line for aggregator copy.
+        if (ev.payload?.phase === 'aggregator') {
+          turnController.pushActivity('MoA: aggregating…', 'info', 'MoA')
+        }
+
+        return
+
       case 'tool.progress':
         if (ev.payload?.preview && ev.payload.name) {
           turnController.recordToolProgress(ev.payload.name, ev.payload.preview)
diff --git a/ui-tui/src/app/interfaces.ts b/ui-tui/src/app/interfaces.ts
index 44ff7fa2a2c..485c0ec28e2 100644
--- a/ui-tui/src/app/interfaces.ts
+++ b/ui-tui/src/app/interfaces.ts
@@ -88,6 +88,9 @@ export interface SelectionApi {
 
 export interface CompletionItem {
   display: string
+  /** Completion class from the gateway; `skill` is the only kind offered for
+   *  an inline `/skill` reference typed mid-message. */
+  kind?: string
   meta?: string
   text: string
 }
diff --git a/ui-tui/src/app/turnController.ts b/ui-tui/src/app/turnController.ts
index a8afea727d9..91380466487 100644
--- a/ui-tui/src/app/turnController.ts
+++ b/ui-tui/src/app/turnController.ts
@@ -757,6 +757,7 @@ class TurnController {
       role: 'system',
       text: '',
       thinking,
+      isMoaReference: true,
       thinkingTokens: estimateTokensRough(thinking)
     })
     patchTurnState({ streamSegments: this.segmentMessages })
diff --git a/ui-tui/src/app/useInputHandlers.ts b/ui-tui/src/app/useInputHandlers.ts
index 83c71285037..f9461919915 100644
--- a/ui-tui/src/app/useInputHandlers.ts
+++ b/ui-tui/src/app/useInputHandlers.ts
@@ -4,6 +4,7 @@ import { useEffect, useRef } from 'react'
 
 import { DASHBOARD_TUI_MODE } from '../config/env.js'
 import { TYPING_IDLE_MS } from '../config/timing.js'
+import { applyCompletion } from '../domain/slash.js'
 import type {
   ApprovalRespondResponse,
   ConfigSetResponse,
@@ -640,12 +641,7 @@ export function useInputHandlers(ctx: InputHandlerContext): InputHandlerResult {
       const row = cState.completions[cState.compIdx]
 
       if (row?.text) {
-        const text =
-          cState.input.startsWith('/') && row.text.startsWith('/') && cState.compReplace > 0
-            ? row.text.slice(1)
-            : row.text
-
-        cActions.setInput(cState.input.slice(0, cState.compReplace) + text)
+        cActions.setInput(applyCompletion(cState.input, row.text, cState.compReplace))
       }
 
       return
diff --git a/ui-tui/src/app/useMainApp.ts b/ui-tui/src/app/useMainApp.ts
index 586d30716e4..cc3cea4a3b7 100644
--- a/ui-tui/src/app/useMainApp.ts
+++ b/ui-tui/src/app/useMainApp.ts
@@ -1,6 +1,7 @@
 import {
   forceRedraw,
   type ScrollBoxHandle,
+  setDimFallbackColor,
   useApp,
   useHasSelection,
   useSelection,
@@ -245,6 +246,14 @@ export function useMainApp(gw: GatewayClient) {
     selection.setSelectionBgColor(ui.theme.color.selectionBg)
   }, [selection, ui.theme.color.selectionBg])
 
+  // Terminals that ignore SGR 2 (Apple_Terminal) get a literal color for
+  // `dim` instead. Feed it the theme's muted tone so dimmed spans stay in
+  // the palette — a hardcoded gray renders as a foreign foreground next to
+  // themed text on the same line.
+  useEffect(() => {
+    setDimFallbackColor(ui.theme.color.muted)
+  }, [ui.theme.color.muted])
+
   // macOS Terminal.app does not forward Cmd+C to fullscreen TUIs that enable
   // mouse tracking, so the only reliable native-feeling path is iTerm-style
   // copy-on-select: once a drag creates a stable TUI selection, write it to
@@ -1057,16 +1066,21 @@ export function useMainApp(gw: GatewayClient) {
           state.streamSegments.some(segment => {
             const hasThinking = Boolean(segment.thinking?.trim())
             const hasTrailTools = Boolean(segment.tools?.length)
+            // A MoA reference segment (segment.isMoaReference) is the
+            // user-facing mixture-of-agents process the user opted into, not
+            // private model reasoning — it must keep the live progress area
+            // (and therefore StreamingAssistant) up even when the thinking
+            // panel is hidden, matching shouldShowThinkingTrail's settled-
+            // transcript override in messageLine.tsx (#64657/#64701).
+            const thinkingVisible = thinkingPanelVisible || Boolean(segment.isMoaReference)
 
             if (segment.kind === 'trail' && !segment.text) {
-              return (
-                (thinkingPanelVisible && hasThinking) || ((toolsPanelVisible || activityPanelVisible) && hasTrailTools)
-              )
+              return (thinkingVisible && hasThinking) || ((toolsPanelVisible || activityPanelVisible) && hasTrailTools)
             }
 
             return (
               Boolean(segment.text?.trim()) ||
-              (thinkingPanelVisible && hasThinking) ||
+              (thinkingVisible && hasThinking) ||
               ((toolsPanelVisible || activityPanelVisible) && hasTrailTools)
             )
           }) ||
diff --git a/ui-tui/src/components/markdown.tsx b/ui-tui/src/components/markdown.tsx
index fb7fafd73c5..2aa421822b4 100644
--- a/ui-tui/src/components/markdown.tsx
+++ b/ui-tui/src/components/markdown.tsx
@@ -153,25 +153,27 @@ const autolinkUrl = (raw: string) =>
 const defaultLinkLabel = (url: string) =>
   url.startsWith('mailto:') ? url.replace(/^mailto:/, '') : /^https?:\/\//i.test(url) ? urlSlugTitleLabel(url) : url
 
-const pickFallbackLabel = (label: string | undefined, target: string): string | undefined => {
+// A label only counts as authored if it says something the URL doesn't:
+// `[https://example.com](https://example.com)` and `<https://example.com>`
+// are bare links wearing markdown syntax, so they still want a page title.
+const pickAuthoredLabel = (label: string | undefined, target: string): string | undefined => {
   const trimmed = label?.trim()
 
-  if (!trimmed) {
-    return undefined
-  }
-
-  return normalizeExternalUrl(trimmed) === target ? undefined : trimmed
+  return trimmed && normalizeExternalUrl(trimmed) !== target ? trimmed : undefined
 }
 
 interface ResolvedLinkProps {
-  fallbackLabel?: string
+  authoredLabel?: string
   t: Theme
   url: string
 }
 
-function ResolvedLink({ fallbackLabel, t, url }: ResolvedLinkProps) {
-  const fetched = useLinkTitle(url)
-  const display = fetched || fallbackLabel || defaultLinkLabel(url)
+// Title resolution is a fallback for links with no text of their own, not an
+// override — replacing `[Read the RFC](url)` with the page title throws away
+// better wording than we can derive, and mangles labels like `#71706`.
+function ResolvedLink({ authoredLabel, t, url }: ResolvedLinkProps) {
+  const fetched = useLinkTitle(authoredLabel ? null : url)
+  const display = authoredLabel || fetched || defaultLinkLabel(url)
 
   return (
     <Link url={url}>
@@ -185,7 +187,7 @@ function ResolvedLink({ fallbackLabel, t, url }: ResolvedLinkProps) {
 const renderResolvedLink = (k: number, t: Theme, rawUrl: string, label?: string) => {
   const target = normalizeExternalUrl(rawUrl)
 
-  return <ResolvedLink fallbackLabel={pickFallbackLabel(label, target)} key={k} t={t} url={target} />
+  return <ResolvedLink authoredLabel={pickAuthoredLabel(label, target)} key={k} t={t} url={target} />
 }
 
 export const stripInlineMarkup = (v: string) =>
@@ -539,7 +541,14 @@ const renderTable = (k: number, rows: string[][], t: Theme, cols?: number) => {
   )
 }
 
-function MdInline({ t, text }: { t: Theme; text: string }) {
+// `color` anchors the prose runs to a palette tone. Block callers that
+// already wrap MdInline in a colored <Text> (headings, quotes, footnotes)
+// leave it unset and inherit that parent; body-prose callers pass
+// `t.color.text` so plain words are themed instead of falling through to
+// the terminal's default foreground. Without it a single line mixes
+// themed spans (code, links, math) with unthemed prose — and because an
+// inline token can match mid-word, so can a single word.
+function MdInline({ color, t, text }: { color?: string; t: Theme; text: string }) {
   const parts: ReactNode[] = []
 
   let last = 0
@@ -650,7 +659,11 @@ function MdInline({ t, text }: { t: Theme; text: string }) {
     parts.push(<Text key={parts.length}>{text.slice(last)}</Text>)
   }
 
-  return <Text wrap="wrap-trim">{parts.length ? parts : text}</Text>
+  return (
+    <Text {...(color ? { color } : {})} wrap="wrap-trim">
+      {parts.length ? parts : text}
+    </Text>
+  )
 }
 
 // Cross-instance parsed-children cache: useMemo's per-instance cache dies
@@ -881,7 +894,7 @@ function MdImpl({ cols, compact, t, text }: MdProps) {
 
         if (closeIdx < 0) {
           start('paragraph')
-          nodes.push(<MdInline key={key} t={t} text={line} />)
+          nodes.push(<MdInline color={t.color.text} key={key} t={t} text={line} />)
           i++
 
           continue
@@ -998,7 +1011,7 @@ function MdImpl({ cols, compact, t, text }: MdProps) {
           nodes.push(
             <Text key={`${key}-def-${i}`} wrap="wrap-trim">
               <Text color={t.color.muted}> · </Text>
-              <MdInline t={t} text={def} />
+              <MdInline color={t.color.text} t={t} text={def} />
             </Text>
           )
           i++
@@ -1019,7 +1032,7 @@ function MdImpl({ cols, compact, t, text }: MdProps) {
           <Box key={key} paddingLeft={indentDepth(bullet[1]!) * 2}>
             <Text wrap="wrap-trim">
               <Text color={t.color.muted}>{marker} </Text>
-              <MdInline t={t} text={task ? task[2]! : bullet[2]!} />
+              <MdInline color={t.color.text} t={t} text={task ? task[2]! : bullet[2]!} />
             </Text>
           </Box>
         )
@@ -1036,7 +1049,7 @@ function MdImpl({ cols, compact, t, text }: MdProps) {
           <Box key={key} paddingLeft={indentDepth(numbered[1]!) * 2}>
             <Text wrap="wrap-trim">
               <Text color={t.color.muted}>{numbered[2]}. </Text>
-              <MdInline t={t} text={numbered[3]!} />
+              <MdInline color={t.color.text} t={t} text={numbered[3]!} />
             </Text>
           </Box>
         )
@@ -1141,7 +1154,7 @@ function MdImpl({ cols, compact, t, text }: MdProps) {
       }
 
       start('paragraph')
-      nodes.push(<MdInline key={key} t={t} text={line} />)
+      nodes.push(<MdInline color={t.color.text} key={key} t={t} text={line} />)
       i++
     }
 
diff --git a/ui-tui/src/components/messageLine.tsx b/ui-tui/src/components/messageLine.tsx
index 7e0499d4569..09b1c78a1ad 100644
--- a/ui-tui/src/components/messageLine.tsx
+++ b/ui-tui/src/components/messageLine.tsx
@@ -7,6 +7,7 @@ import { hasLeadGap } from '../domain/blockLayout.js'
 import { sectionMode } from '../domain/details.js'
 import { userDisplay } from '../domain/messages.js'
 import { ROLE } from '../domain/roles.js'
+import { splitSlashSkillRefs } from '../domain/slash.js'
 import { transcriptBodyWidth, transcriptGutterWidth } from '../lib/inputMetrics.js'
 import {
   boundedLiveRenderText,
@@ -75,12 +76,13 @@ export const MessageLine = memo(function MessageLine({
   }
 
   if (msg.kind === 'trail' && (msg.tools?.length || tools.length || thinking)) {
-    return thinkingMode !== 'hidden' || toolsMode !== 'hidden' || activityMode !== 'hidden' ? (
+    return shouldShowThinkingTrail(msg, thinkingMode, toolsMode, activityMode) ? (
       <Box flexDirection="column" marginTop={leadGap ? 1 : 0}>
         <ToolTrail
           commandOverride={detailsModeCommandOverride}
           detailsMode={detailsMode}
           reasoning={thinking}
+          reasoningAlwaysVisible={msg.isMoaReference}
           reasoningTokens={msg.thinkingTokens}
           sections={sections}
           t={t}
@@ -203,6 +205,27 @@ export const MessageLine = memo(function MessageLine({
       )
     }
 
+    // A skill the user referenced mid-prose (`clean this up with /clean`)
+    // keeps the accent it wore as a completion in the composer, instead of
+    // flattening back into the body text.
+    if (msg.role === 'user') {
+      const segments = splitSlashSkillRefs(msg.text)
+
+      return (
+        <Text {...(body ? { color: body } : {})}>
+          {segments.map((segment, i) =>
+            segment.ref ? (
+              <Text color={t.color.accent} key={i}>
+                {segment.text}
+              </Text>
+            ) : (
+              segment.text
+            )
+          )}
+        </Text>
+      )
+    }
+
     return <Text {...(body ? { color: body } : {})}>{msg.text}</Text>
   })()
 
@@ -259,6 +282,18 @@ export const MessageLine = memo(function MessageLine({
 export const shouldShowResponseSeparator = (msg: Msg, showDetails: boolean): boolean =>
   msg.role === 'assistant' && showDetails && /\S/.test(msg.text)
 
+// A MoA reference block (msg.isMoaReference) is the user-facing
+// mixture-of-agents process the user opted into, not private model
+// reasoning — it must stay visible even when every other trail section is
+// hidden (#64657).
+export const shouldShowThinkingTrail = (
+  msg: Msg,
+  thinkingMode: DetailsMode,
+  toolsMode: DetailsMode,
+  activityMode: DetailsMode
+): boolean =>
+  Boolean(msg.isMoaReference) || thinkingMode !== 'hidden' || toolsMode !== 'hidden' || activityMode !== 'hidden'
+
 interface MessageLineProps {
   cols: number
   compact?: boolean
diff --git a/ui-tui/src/components/thinking.tsx b/ui-tui/src/components/thinking.tsx
index 84c85fb4d54..47c8d667d8a 100644
--- a/ui-tui/src/components/thinking.tsx
+++ b/ui-tui/src/components/thinking.tsx
@@ -1,5 +1,5 @@
 import { Box, NoSelect, Text } from '@hermes/ink'
-import { memo, type ReactNode, useEffect, useMemo, useState } from 'react'
+import { memo, type ReactNode, useEffect, useMemo, useRef, useState } from 'react'
 import spinners, { type BrailleSpinnerName } from 'unicode-animations'
 
 import { THINKING_COT_MAX } from '../config/limits.js'
@@ -680,6 +680,7 @@ export const ToolTrail = memo(function ToolTrail({
   outcome = '',
   reasoningActive = false,
   reasoning = '',
+  reasoningAlwaysVisible = false,
   reasoningTokens,
   reasoningStreaming = false,
   sections,
@@ -696,6 +697,10 @@ export const ToolTrail = memo(function ToolTrail({
   outcome?: string
   reasoningActive?: boolean
   reasoning?: string
+  // MoA reference blocks (see Msg.isMoaReference) stay visible even when
+  // `visible.thinking === 'hidden'` — they're the mixture-of-agents process
+  // the user opted into, not private model reasoning (#64657).
+  reasoningAlwaysVisible?: boolean
   reasoningTokens?: number
   reasoningStreaming?: boolean
   sections?: SectionVisibility
@@ -724,7 +729,13 @@ export const ToolTrail = memo(function ToolTrail({
   // `visible.X === 'expanded'` at render time — that locks the panel open
   // and silently breaks manual chevron clicks for default-expanded
   // sections (regression caught after #14968).
-  const [openThinking, setOpenThinking] = useState(visible.thinking === 'expanded')
+  // A MoA reference panel (reasoningAlwaysVisible) opens by default on
+  // mount even under `thinking: hidden` — the user opted into MoA and
+  // should see the reference immediately, not a collapsed "Thinking"
+  // label. This only affects the initial mount value; the re-sync effect
+  // below deliberately does NOT re-apply it, so a manual collapse still
+  // sticks (see the no-OR-at-effect-time warning above, #14968).
+  const [openThinking, setOpenThinking] = useState(visible.thinking === 'expanded' || reasoningAlwaysVisible)
   const [openTools, setOpenTools] = useState(visible.tools === 'expanded')
   const [openSubagents, setOpenSubagents] = useState(visible.subagents === 'expanded')
   const [deepSubagents, setDeepSubagents] = useState(visible.subagents === 'expanded')
@@ -740,7 +751,21 @@ export const ToolTrail = memo(function ToolTrail({
     return () => clearInterval(id)
   }, [openTools, tools.length, visible.tools])
 
+  // Effects run after the FIRST render too, not just on later updates — so
+  // this re-sync was clobbering the reasoningAlwaysVisible mount value above
+  // right after mount, collapsing a just-opened MoA reference panel under
+  // `thinking: hidden` before the user ever saw it (#64701). Skip only the
+  // very first run; every subsequent `visible` change (the case this effect
+  // exists for) still re-syncs without the override, so a manual collapse
+  // still sticks per the no-OR-at-effect-time rule above.
+  const skippedInitialSync = useRef(false)
   useEffect(() => {
+    if (!skippedInitialSync.current) {
+      skippedInitialSync.current = true
+
+      return
+    }
+
     setOpenThinking(visible.thinking === 'expanded')
     setOpenTools(visible.tools === 'expanded')
     setOpenSubagents(visible.subagents === 'expanded')
@@ -915,6 +940,7 @@ export const ToolTrail = memo(function ToolTrail({
 
   const allHidden =
     visible.thinking === 'hidden' &&
+    !reasoningAlwaysVisible &&
     visible.tools === 'hidden' &&
     visible.subagents === 'hidden' &&
     visible.activity === 'hidden'
@@ -939,7 +965,7 @@ export const ToolTrail = memo(function ToolTrail({
   // hidden sections stay hidden so the override is honoured.
 
   const expandAll = () => {
-    if (visible.thinking !== 'hidden') {
+    if (visible.thinking !== 'hidden' || reasoningAlwaysVisible) {
       setOpenThinking(true)
     }
 
@@ -986,7 +1012,7 @@ export const ToolTrail = memo(function ToolTrail({
     render: (rails: boolean[]) => ReactNode
   }[] = []
 
-  if (hasThinking && visible.thinking !== 'hidden') {
+  if (hasThinking && (visible.thinking !== 'hidden' || reasoningAlwaysVisible)) {
     panels.push({
       header: (
         <Box
diff --git a/ui-tui/src/domain/slash.ts b/ui-tui/src/domain/slash.ts
index b86c34d134c..b40578c9604 100644
--- a/ui-tui/src/domain/slash.ts
+++ b/ui-tui/src/domain/slash.ts
@@ -10,21 +10,100 @@ export const sessionScopedModelArg = (value: string) => {
 
 export const looksLikeSlashCommand = (text: string) => /^\/[^\s/]*(?:\s|$)/.test(text)
 
+// A `/` means two different things depending on where it sits:
+//
+//  - At position 0 it's a COMMAND invocation the TUI executes
+//    (`looksLikeSlashCommand`, and the backend's dispatch, are both
+//    `^`-anchored). Completion stays live past the command name so arg
+//    completion works (`/cron ad` → `add`).
+//  - After whitespace it's an inline SKILL reference the user is dropping into
+//    prose ("clean this up with /clean"). The text submits as an ordinary
+//    message, so there are no args to complete — the token ends at the caret.
+//
+// The inline shape is what makes skills reachable anywhere in a prompt. The
+// trailing `$` matters for both: completion runs against the text the user has
+// typed so far, so the match has to end where they're typing.
+//
+// Requiring a single bare segment (no second `/`) keeps real paths out:
+// `look at /usr/local/bin` and `check src/foo/bar` never match. A bare `/us` is
+// genuinely ambiguous with an absolute path, and resolves as a skill reference
+// — typing the next `/` flips it straight back to path completion.
+const INLINE_SLASH_RE = /\s\/([a-zA-Z][\w-]*)?$/
+
+/**
+ * Locate an inline `/skill` reference at the end of `text`, or null when the
+ * text isn't one. `start` is the index of the `/` itself, so a completion
+ * replaces the typed token and leaves the prose in front of it untouched.
+ */
+export const inlineSlashTrigger = (text: string): { query: string; start: number } | null => {
+  const match = INLINE_SLASH_RE.exec(text)
+
+  if (!match) {
+    return null
+  }
+
+  const query = match[1] ?? ''
+
+  return { query, start: text.length - query.length - 1 }
+}
+
 export const parseSlashCommand = (cmd: string) => {
   const [name = '', ...rest] = cmd.slice(1).split(/\s+/)
 
   return { arg: rest.join(' '), cmd, name: name.toLowerCase() }
 }
 
+// A skill referenced mid-prose in a message that's already been sent
+// ("clean this up with /clean"). The composer offers it as a completion, so
+// the transcript marks it as one rather than flattening it into the body text.
+//
+// Unlike the caret-anchored trigger above this scans finished text, so it has
+// to reject a token that continues into a path: `/usr/local/bin` would
+// otherwise mark `/usr`. `(?![\w-]*\/)` requires the token to end at something
+// other than another slash. A leading `/` is excluded too — that's a command
+// invocation, which never reaches the transcript as a user message.
+const SLASH_SKILL_REF_RE = /(?<=\s)\/[a-zA-Z][\w-]*(?![\w-]*\/)/g
+
+/**
+ * Split `text` into alternating plain and `/skill` reference runs. Always
+ * returns at least one segment, and concatenating every `text` reproduces the
+ * input exactly — the transcript styles the reference without rewriting it.
+ */
+export const splitSlashSkillRefs = (text: string): { ref: boolean; text: string }[] => {
+  const out: { ref: boolean; text: string }[] = []
+  let last = 0
+
+  for (const match of text.matchAll(SLASH_SKILL_REF_RE)) {
+    const start = match.index ?? 0
+
+    if (start > last) {
+      out.push({ ref: false, text: text.slice(last, start) })
+    }
+
+    out.push({ ref: true, text: match[0] })
+    last = start + match[0].length
+  }
+
+  if (last < text.length || !out.length) {
+    out.push({ ref: false, text: text.slice(last) })
+  }
+
+  return out
+}
+
 /**
  * Apply a completion row to the current input, mirroring the editor's
  * replace semantics: replace from `compReplace` with the row text, dropping
- * the leading slash when both the input and the row carry one (the gateway's
- * slash completer returns bare command names whose replace span begins after
- * the leading `/`).
+ * the row's leading slash when the input already has one immediately before
+ * the replace point (the gateway's slash completer returns bare command names
+ * whose replace span begins after the leading `/`).
+ *
+ * Keyed off the character before `compReplace` rather than the start of the
+ * input so a `/token` anywhere in the message behaves the same as one at
+ * position 0 — an inline `run /cle` replaces from after its own slash.
  */
 export const applyCompletion = (value: string, rowText: string, compReplace: number): string => {
-  const text = value.startsWith('/') && rowText.startsWith('/') ? rowText.slice(1) : rowText
+  const text = value[compReplace - 1] === '/' && rowText.startsWith('/') ? rowText.slice(1) : rowText
 
   return value.slice(0, compReplace) + text
 }
diff --git a/ui-tui/src/gatewayTypes.ts b/ui-tui/src/gatewayTypes.ts
index cf84abfddf7..719ffe9938d 100644
--- a/ui-tui/src/gatewayTypes.ts
+++ b/ui-tui/src/gatewayTypes.ts
@@ -9,6 +9,9 @@ export type GatewaySkin = HermesSkin
 
 export interface GatewayCompletionItem {
   display: string
+  /** Completion class, set by the gateway. `skill` covers skill commands and
+   *  skill bundles — the only kind offered for an inline `/skill` reference. */
+  kind?: string
   meta?: string
   text: string
 }
@@ -608,6 +611,16 @@ export type GatewayEvent =
       type: 'moa.reference'
     }
   | { payload?: { aggregator?: string }; session_id?: string; type: 'moa.aggregating' }
+  | {
+      payload?: { label?: string; refs_done?: number; refs_total?: number }
+      session_id?: string
+      type: 'moa.progress'
+    }
+  | {
+      payload?: { aggregator?: string; phase?: string; refs_done?: number; refs_total?: number }
+      session_id?: string
+      type: 'moa.phase'
+    }
   | { payload: { name?: string; preview?: string }; session_id?: string; type: 'tool.progress' }
   | { payload: { name?: string }; session_id?: string; type: 'tool.generating' }
   | {
diff --git a/ui-tui/src/hooks/useCompletion.ts b/ui-tui/src/hooks/useCompletion.ts
index 5e0dc33c540..468c8995b03 100644
--- a/ui-tui/src/hooks/useCompletion.ts
+++ b/ui-tui/src/hooks/useCompletion.ts
@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react'
 
 import type { CompletionItem } from '../app/interfaces.js'
-import { looksLikeSlashCommand } from '../domain/slash.js'
+import { inlineSlashTrigger, looksLikeSlashCommand } from '../domain/slash.js'
 import type { GatewayClient } from '../gatewayClient.js'
 import type { CompletionResponse } from '../gatewayTypes.js'
 import { asRpcResult } from '../lib/rpc.js'
@@ -30,15 +30,11 @@ export function completionRequestForInput(
   input: string
 ):
   | { method: 'complete.path'; params: { word: string }; replaceFrom: number }
-  | { method: 'complete.slash'; params: { text: string }; replaceFrom: number }
+  | { method: 'complete.slash'; params: { text: string }; replaceFrom: number; skillsOnly?: boolean }
   | null {
   const isSlashCommand = looksLikeSlashCommand(input)
   const pathWord = isSlashCommand ? null : (input.match(TAB_PATH_RE)?.[1] ?? null)
 
-  if (!isSlashCommand && !pathWord) {
-    return null
-  }
-
   // `/model` uses the two-step ModelPicker (real curated IDs).
   // Slash completion here only showed short aliases + vendor/family meta.
   if (isSlashCommand && /^\/model(?:\s|$)/.test(input)) {
@@ -49,10 +45,30 @@ export function completionRequestForInput(
     return { method: 'complete.slash', params: { text: input }, replaceFrom: 1 }
   }
 
+  // A `/token` mid-message is a skill reference dropped into prose. It's only
+  // reachable here because the path branch below would otherwise claim it: a
+  // bare `/cle` matches TAB_PATH_RE as an absolute path. Skills win that tie —
+  // the moment a second `/` is typed the inline trigger stops matching and
+  // path completion takes back over.
+  const inline = inlineSlashTrigger(input)
+
+  if (inline) {
+    return {
+      method: 'complete.slash',
+      params: { text: `/${inline.query}` },
+      replaceFrom: inline.start + 1,
+      skillsOnly: true
+    }
+  }
+
+  if (!pathWord) {
+    return null
+  }
+
   return {
     method: 'complete.path',
-    params: { word: pathWord! },
-    replaceFrom: input.length - pathWord!.length
+    params: { word: pathWord },
+    replaceFrom: input.length - pathWord.length
   }
 }
 
@@ -103,12 +119,27 @@ export function useCompletion(input: string, blocked: boolean, gw: GatewayClient
 
           const r = asRpcResult<CompletionResponse>(raw)
 
-          const items =
+          const fetched =
             request.method === 'complete.slash' ? mergeWidgetAppItems(input, r?.items ?? []) : (r?.items ?? [])
 
+          // Mid-message offers SKILLS only. A built-in like `/model` or `/new`
+          // acts on the app, so it's meaningless as a reference inside prose —
+          // only a skill reads as "handle this part with X". Filtering here
+          // rather than in the gateway keeps one completion source for both
+          // shapes.
+          const items =
+            request.method === 'complete.slash' && request.skillsOnly
+              ? fetched.filter(item => item.kind === 'skill')
+              : fetched
+
           setCompletions(items)
           setCompIdx(0)
-          setCompReplace(request.method === 'complete.slash' ? (r?.replace_from ?? 1) : request.replaceFrom)
+          // An inline reference replaces its own token, so the gateway's
+          // `replace_from` (an offset into the synthetic `/query` it was sent)
+          // doesn't apply — the caller already knows where the token starts.
+          setCompReplace(
+            request.method === 'complete.slash' && !request.skillsOnly ? (r?.replace_from ?? 1) : request.replaceFrom
+          )
         })
         .catch((e: unknown) => {
           if (ref.current !== input) {
diff --git a/ui-tui/src/lib/externalLink.ts b/ui-tui/src/lib/externalLink.ts
index f0256f5be15..06e17a948cf 100644
--- a/ui-tui/src/lib/externalLink.ts
+++ b/ui-tui/src/lib/externalLink.ts
@@ -15,7 +15,7 @@ const TITLE_USER_AGENT =
   'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36'
 
 const TITLE_ERROR_RE =
-  /\b(?:access denied|attention required|captcha|error|forbidden|just a moment|request blocked|too many requests)\b/i
+  /\b(?:access denied|attention required|captcha|error|forbidden|just a moment|not found|request blocked|too many requests)\b/i
 
 const DOMAIN_RE = /^(?:www\.)?[a-z0-9](?:[a-z0-9-]*\.)+[a-z]{2,}(?::\d+)?(?:[/?#][^\s]*)?$/i
 const SKIP_PROTO_RE = /^(?:file|data|mailto|javascript|blob|chrome|about|hermes):/i
diff --git a/ui-tui/src/types.ts b/ui-tui/src/types.ts
index f97506df7c9..49c4cef4189 100644
--- a/ui-tui/src/types.ts
+++ b/ui-tui/src/types.ts
@@ -120,6 +120,11 @@ export interface Msg {
   role: Role
   text: string
   thinking?: string
+  // MoA reference-model output stored in `thinking` (see turnController's
+  // recordMoaReference): unlike ordinary model reasoning, this is the
+  // user-facing mixture-of-agents process the user opted into, so it stays
+  // visible even when `display.sections.thinking` is hidden.
+  isMoaReference?: boolean
   thinkingTokens?: number
   toolTokens?: number
   tools?: string[]
diff --git a/ui-tui/src/types/hermes-ink.d.ts b/ui-tui/src/types/hermes-ink.d.ts
index 0e92c307650..94df7504f50 100644
--- a/ui-tui/src/types/hermes-ink.d.ts
+++ b/ui-tui/src/types/hermes-ink.d.ts
@@ -104,6 +104,7 @@ declare module '@hermes/ink' {
   export const NoSelect: React.ComponentType<any>
   export const ScrollBox: React.ComponentType<any>
   export const Text: React.ComponentType<any>
+  export function setDimFallbackColor(color: string | undefined): void
   export const TextInput: React.ComponentType<any>
   export const stringWidth: (s: string) => number
   export function isXtermJs(): boolean
diff --git a/web/src/i18n/ar.ts b/web/src/i18n/ar.ts
new file mode 100644
index 00000000000..0d961d9b49e
--- /dev/null
+++ b/web/src/i18n/ar.ts
@@ -0,0 +1,701 @@
+import { defineLocale } from "./define-locale";
+
+export const ar = defineLocale({
+  common: {
+    save: "حفظ",
+    saving: "جاري الحفظ...",
+    cancel: "إلغاء",
+    close: "إغلاق",
+    confirm: "تأكيد",
+    delete: "حذف",
+    refresh: "تحديث",
+    retry: "إعادة المحاولة",
+    search: "بحث...",
+    loading: "جاري التحميل...",
+    create: "إنشاء",
+    creating: "جاري الإنشاء...",
+    set: "تعيين",
+    replace: "استبدال",
+    clear: "مسح",
+    live: "مباشر",
+    off: "مغلق",
+    enabled: "مفعّل",
+    disabled: "معطّل",
+    active: "نشط",
+    inactive: "غير نشط",
+    unknown: "غير معروف",
+    untitled: "بدون عنوان",
+    none: "لا يوجد",
+    form: "نموذج",
+    noResults: "لا توجد نتائج",
+    of: "من",
+    page: "صفحة",
+    msgs: "رسائل",
+    tools: "أدوات",
+    match: "مطابقة",
+    other: "آخر",
+    configured: "مكوَّن",
+    removed: "مزال",
+    failedToToggle: "فشل التبديل",
+    failedToRemove: "فشل الحذف",
+    failedToReveal: "فشل الإظهار",
+    collapse: "طي",
+    expand: "توسيع",
+    general: "عام",
+    messaging: "مراسلة",
+    pluginLoadFailed:
+      "تعذر تحميل سكربت هذا المكوِّن الإضافي. تفقَّد علامة الشبكة (dashboard-plugins/…) ومسار ملحقات الخادم.",
+    pluginNotRegistered:
+      "لم يستدعِ سكربت المكوِّن الإضافي register()، أو حدث خطأ في السكربت. افتح وحدة تحكم المتصفح للتفاصيل.",
+  },
+
+  app: {
+    brand: "Hermes Agent",
+    brandShort: "HA",
+    closeNavigation: "إغلاق التنقل",
+    closeModelTools: "إغلاق النموذج والأدوات",
+    footer: {
+      org: "Nous Research",
+    },
+    activeSessionsLabel: "الجلسات النشطة:",
+    gatewayStatusLabel: "حالة البوابة:",
+    gatewayStrip: {
+      failed: "فشل البدء",
+      off: "مغلق",
+      running: "يعمل",
+      starting: "قيد البدء",
+      stopped: "متوقف",
+    },
+    nav: {
+      analytics: "التحليلات",
+      chat: "المحادثة",
+      config: "الإعدادات",
+      cron: "المهام المجدولة",
+      documentation: "التوثيق",
+      keys: "المفاتيح",
+      logs: "السجلات",
+      models: "النماذج",
+      profiles: "الملفات الشخصية",
+      plugins: "المكوِّنات الإضافية",
+      sessions: "الجلسات",
+      skills: "المهارات",
+    },
+    modelToolsSheetSubtitle: "& أدوات",
+    modelToolsSheetTitle: "النموذج",
+    navigation: "التنقل",
+    openDocumentation: "فتح التوثيق في تبويب جديد",
+    openNavigation: "فتح التنقل",
+    pluginNavSection: "المكوِّنات الإضافية",
+    sessionsActiveCount: "{count} نشطة",
+    statusOverview: "نظرة عامة على الحالة",
+    system: "النظام",
+    webUi: "واجهة الويب",
+  },
+
+  status: {
+    actionFailed: "فشلت الإجراء",
+    actionFinished: "انتهى",
+    actions: "إجراءات",
+    agent: "العامل",
+    activeSessions: "الجلسات النشطة",
+    connected: "متصل",
+    connectedPlatforms: "المنصات المتصلة",
+    disconnected: "غير متصل",
+    error: "خطأ",
+    failed: "فشل",
+    gateway: "البوابة",
+    gatewayFailedToStart: "فشل بدء البوابة",
+    lastUpdate: "آخر تحديث",
+    noneRunning: "لا شيء",
+    notRunning: "لا يعمل",
+    pid: "PID",
+    platformDisconnected: "غير متصل",
+    platformError: "خطأ",
+    recentSessions: "الجلسات الأخيرة",
+    restartGateway: "إعادة تشغيل البوابة",
+    restartingGateway: "إعادة تشغيل البوابة…",
+    running: "يعمل",
+    runningRemote: "يعمل (عن بعد)",
+    startFailed: "فشل البدء",
+    starting: "قيد البدء",
+    startedInBackground: "بدء في الخلفية — تحقق من السجلات للتقدم",
+    stopped: "متوقف",
+    updateHermes: "تحديث Hermes",
+    updatingHermes: "جاري تحديث Hermes…",
+    waitingForOutput: "في انتظار الناتج…",
+  },
+
+  sessions: {
+    title: "الجلسات",
+    searchPlaceholder: "بحث في محتوى الرسائل...",
+    noSessions: "لا توجد جلسات حتى الآن",
+    noMatch: "لا توجد جلسات تطابق بحثك",
+    startConversation: "ابدأ محادثة لتظهر هنا",
+    noMessages: "لا توجد رسائل",
+    untitledSession: "جلسة بدون عنوان",
+    deleteSession: "حذف الجلسة",
+    confirmDeleteTitle: "حذف الجلسة؟",
+    confirmDeleteMessage:
+      "سيزيل هذا نهائيًا المحادثة وجميع رسائلها. لا يمكن التراجع عن هذا الإجراء.",
+    sessionDeleted: "تم حذف الجلسة",
+    failedToDelete: "فشل حذف الجلسة",
+    resumeInChat: "استئناف في المحادثة",
+    previousPage: "الصفحة السابقة",
+    nextPage: "الصفحة التالية",
+    roles: {
+      user: "المستخدم",
+      assistant: "المساعد",
+      system: "النظام",
+      tool: "أداة",
+    },
+  },
+
+  analytics: {
+    period: "الفترة:",
+    totalTokens: "إجمالي الرموز",
+    totalSessions: "إجمالي الجلسات",
+    apiCalls: "استدعاءات API",
+    dailyTokenUsage: "استخدام الرموز اليومي",
+    dailyBreakdown: "التفصيل اليومي",
+    perModelBreakdown: "التفصيل حسب النموذج",
+    topSkills: "أعلى المهارات استخدامًا",
+    skill: "مهارة",
+    loads: "تم تحميل العامل",
+    edits: "تم إدارة العامل",
+    lastUsed: "آخر استخدام",
+    input: "إدخال",
+    output: "إخراج",
+    total: "الإجمالي",
+    noUsageData: "لا توجد بيانات استخدام لهذه الفترة",
+    startSession: "ابدأ جلسة لرؤية التحليلات هنا",
+    date: "التاريخ",
+    model: "النموذج",
+    tokens: "رموز",
+    perDayAvg: "في اليوم (متوسط)",
+    acrossModels: "عبر {count} نموذج",
+    inOut: "{input} إدخال / {output} إخراج",
+  },
+
+  models: {
+    modelsUsed: "النماذج المستخدمة",
+    estimatedCost: "التكلفة التقريبية",
+    tokens: "رموز",
+    sessions: "جلسات",
+    avgPerSession: "متوسط/جلسة",
+    apiCalls: "استدعاءات API",
+    toolCalls: "استدعاءات الأدوات",
+    noModelsData: "لا توجد بيانات نموذج لهذه الفترة",
+    startSession: "ابدأ جلسة لرؤية بيانات النماذج هنا",
+  },
+
+  logs: {
+    title: "السجلات",
+    autoRefresh: "تحديث تلقائي",
+    file: "ملف",
+    level: "المستوى",
+    component: "المكوِّن",
+    lines: "الأسطر",
+    noLogLines: "لم يُعثر على أسطر سجل",
+  },
+
+  cron: {
+    confirmDeleteMessage:
+      "يزيل هذا المهمة من الجدولة. لا يمكن التراجع عن الإجراء.",
+    confirmDeleteTitle: "حذف المهمة المجدولة؟",
+    newJob: "مهمة cron جديدة",
+    nameOptional: "الاسم (اختياري)",
+    namePlaceholder: "مثال: ملخص يومي",
+    prompt: "المطالبة",
+    promptPlaceholder: "ماذا يجب أن يفعل العامل في كل تشغيل؟",
+    schedule: "الجدولة (تعبير cron)",
+    schedulePlaceholder: "0 9 * * *",
+    deliverTo: "التسليم إلى",
+    scheduledJobs: "المهام المجدولة",
+    noJobs: "لم يتم تكوين أي مهام cron. أنشئ واحدة أعلاه.",
+    last: "آخر",
+    next: "التالي",
+    pause: "إيقاف مؤقت",
+    resume: "استئناف",
+    triggerNow: "تشغيل الآن",
+    delivery: {
+      local: "محلي",
+      telegram: "Telegram",
+      discord: "Discord",
+      slack: "Slack",
+      email: "البريد الإلكتروني",
+    },
+  },
+
+  profiles: {
+    newProfile: "ملف شخصي جديد",
+    name: "الاسم",
+    namePlaceholder: "مثال: coder, writer, إلخ.",
+    nameRequired: "الاسم مطلوب",
+    nameRule:
+      "حروف صغيرة، أرقام، _ و - فقط؛ يجب البدء بحرف أو رقم؛ حتى 64 حرفًا.",
+    invalidName: "اسم ملف شخصي غير صالح",
+    allProfiles: "الملفات الشخصية",
+    noProfiles: "لم يُعثر على ملفات شخصية.",
+    defaultBadge: "افتراضي",
+    hasEnv: "env",
+    model: "النموذج",
+    skills: "المهارات",
+    rename: "إعادة تسمية",
+    editSoul: "تعديل SOUL.md",
+    soulSection: "SOUL.md (شخصية / موجه النظام)",
+    soulPlaceholder: "# كيف يجب أن يتصرف هذا العامل…",
+    saveSoul: "حفظ SOUL",
+    soulSaved: "تم حفظ SOUL.md",
+    openInTerminal: "نسخ أمر CLI",
+    commandCopied: "تم النسخ إلى الحافظة",
+    copyFailed: "تعذر النسخ",
+    confirmDeleteTitle: "حذف الملف الشخصي؟",
+    confirmDeleteMessage:
+      "هذا يحذف نهائيًا الملف الشخصي '{name}' — الإعدادات، المفاتيح، الذكريات، الجلسات، المهارات، مهام cron. لا يمكن التراجع عن الإجراء.",
+    created: "تم الإنشاء",
+    deleted: "تم الحذف",
+    renamed: "تمت إعادة التسمية",
+  },
+
+  pluginsPage: {
+    contextEngineLabel: "محرك السياق",
+    dashboardSlots: "فتحات لوحة التحكم",
+    disableRuntime: "تعطيل",
+    enableAfterInstall: "تفعيل بعد التثبيت",
+    enableRuntime: "تفعيل",
+    forceReinstall: "إعادة تثبيت إجباري (حذف المجلد الموجود أولاً)",
+    headline:
+      "اكتشف وثبِّت وفعِّل وحدِّث مكوِّنات Hermes الإضافية (مطابقة `hermes plugins`).",
+    identifierLabel: "رابط Git أو owner/repo",
+    inactive: "غير نشط",
+    installBtn: "تثبيت من Git",
+    installHeading: "تثبيت من GitHub / رابط Git",
+    installHint: "استخدم اختصار owner/repo أو رابط استنساخ كامل يبدأ بـ https:// أو git@.",
+    memoryProviderLabel: "مزوِّد الذاكرة",
+    missingEnvWarn: "عيّن هذه المتغيرات في المفاتيح قبل أن يتمكن المكوِّن الإضافي من العمل:",
+    noDashboardTab: "لا يوجد تبويب لوحة تحكم",
+    openTab: "فتح",
+    orphanHeading: "امتدادات لوحة التحكم فقط (لا يوجد تطابق plugin.yaml للعامل)",
+    pluginListHeading: "المكوِّنات الإضافية المثبتة",
+    providerDefaults: "مدمج / افتراضي",
+    providersHeading: "مكوِّنات مزوِّدات وقت التشغيل",
+    providersHint:
+      "يكتب memory.provider (فارغ = مدمج) و context.engine إلى config.yaml. يسري في الجلسة التالية.",
+    refreshDashboard: "إعادة فحص امتدادات لوحة التحكم",
+    removeConfirm: "إزالة هذا المكوِّن الإضافي من ~/.hermes/plugins/؟",
+    removeHint: "يمكن إزالة المكوِّنات المثبتة من المستخدم تحت ~/.hermes/plugins فقط.",
+    rescanHeading: "سجل مكوِّنات SPA",
+    rescanHint: "أعد الفحص بعد إضافة ملفات على القرص لتمكن الشريط الجانبي من التقاط المخطوطات الجديدة.",
+    runtimeHeading: "وقت تشغيل البوابة (مكوِّنات YAML)",
+    saveProviders: "حفظ إعدادات مزوِّد الذاكرة",
+    savedProviders: "تم حفظ إعدادات مزوِّد الذاكرة.",
+    sourceBadge: "المصدر",
+    authRequired: "مصادقة مطلوبة",
+    authRequiredHint: "شغِّل هذا الأمر للمصادقة:",
+    updateGit: "سحب من Git",
+    versionBadge: "الإصدار",
+    showInSidebar: "إظهار في الشريط الجانبي",
+    hideFromSidebar: "إخفاء من الشريط الجانبي",
+  },
+
+  skills: {
+    title: "المهارات",
+    searchPlaceholder: "بحث في المهارات ومجموعات الأدوات...",
+    enabledOf: "{enabled}/{total} مفعلة",
+    all: "الكل",
+    categories: "الفئات",
+    filters: "الفلاتر",
+    noSkills: "لم يُعثر على مهارات. يتم تحميل المهارات من ~/.hermes/skills/",
+    noSkillsMatch: "لا توجد مهارات تطابق بحثك أو الفلاتر.",
+    skillCount: "{count} مهارة{s}",
+    resultCount: "{count} نتيجة{s}",
+    noDescription: "لا يوجد وصف متاح.",
+    toolsets: "مجموعات الأدوات",
+    toolsetLabel: "مجموعة أدوات {name}",
+    noToolsetsMatch: "لا توجد مجموعات أدوات تطابق البحث.",
+    setupNeeded: "يلزم الإعداد",
+    disabledForCli: "معطَّل لواجهة CLI",
+    more: "+{count} المزيد",
+  },
+
+  config: {
+    configPath: "~/.hermes/config.yaml",
+    filters: "الفلاتر",
+    sections: "الأقسام",
+    exportConfig: "تصدير الإعدادات كـ JSON",
+    importConfig: "استيراد الإعدادات من JSON",
+    resetDefaults: "إعادة التعيين للافتراضيات",
+    resetScopeTooltip: "إعادة تعيين {scope} للافتراضيات",
+    confirmResetScope:
+      "إعادة تعيين جميع إعدادات {scope} للافتراضيات؟ هذا يحدِّث النموذج فقط — لا تُكتب التغييرات في config.yaml حتى تضغط على حفظ.",
+    resetScopeToast: "تمت إعادة تعيين {scope} للافتراضيات — راجع واحفظ للتثبيت",
+    rawYaml: "إعدادات YAML الأولية",
+    searchResults: "نتائج البحث",
+    fields: "حقل{s}",
+    noFieldsMatch: 'لا توجد حقول تطابق "{query}"',
+    configSaved: "تم حفظ الإعدادات",
+    yamlConfigSaved: "تم حفظ إعدادات YAML",
+    failedToSave: "فشل الحفظ",
+    failedToSaveYaml: "فشل حفظ YAML",
+    failedToLoadRaw: "فشل تحميل الإعدادات الأولية",
+    configImported: "تم استيراد الإعدادات — راجع واحفظ",
+    invalidJson: "ملف JSON غير صالح",
+    categories: {
+      general: "عام",
+      agent: "العامل",
+      terminal: "الطرفية",
+      display: "العرض",
+      delegation: "التفويض",
+      memory: "الذاكرة",
+      compression: "الضغط",
+      security: "الأمان",
+      browser: "المتصفح",
+      voice: "الصوت",
+      tts: "تحويل النص إلى كلام",
+      stt: "تحويل الكلام إلى نص",
+      logging: "التسجيل",
+      discord: "Discord",
+      auxiliary: "إضافي",
+    },
+  },
+
+  env: {
+    changesNote: "يتم حفظ التغييرات على القرص فورًا. تلتقط الجلسات النشطة المفاتيح الجديدة تلقائيًا.",
+    confirmClearMessage:
+      "سيتم إزالة القيمة المخزنة لهذا المتغير من ملف .env. لا يمكن التراجع عن هذا من الواجهة.",
+    confirmClearTitle: "مسح هذا المفتاح؟",
+    description: "إدارة مفاتيح API والأسرار المخزَّنة في",
+    hideAdvanced: "إخفاء المتقدمة",
+    showAdvanced: "إظهار المتقدمة",
+    llmProviders: "مزوِّدو LLM",
+    providersConfigured: "{configured} من {total} مزوِّدين مكوَّنين",
+    getKey: "الحصول على المفتاح",
+    notConfigured: "{count} غير مكوَّن",
+    notSet: "غير معيّن",
+    keysCount: "{count} مفتاح{s}",
+    enterValue: "أدخل القيمة...",
+    replaceCurrentValue: "استبدال القيمة الحالية ({preview})",
+    showValue: "إظهار القيمة الحقيقية",
+    hideValue: "إخفاء القيمة",
+  },
+
+  oauth: {
+    title: "عمليات تسجيل دخول المزوِّدين (OAuth)",
+    providerLogins: "عمليات تسجيل دخول المزوِّدين (OAuth)",
+    description:
+      "{connected} من {total} مزوِّدي OAuth متصلون. تتدفق عمليات تسجيل الدخول حاليًا عبر CLI؛ انسخ الأمر وألصقه في طرفية للإعداد.",
+    connected: "متصل",
+    expired: "منتهي الصلاحية",
+    notConnected: "غير متصل. شغِّل {command} في طرفية.",
+    runInTerminal: "في طرفية.",
+    noProviders: "لم يُكتشف أي مزوِّد يدعم OAuth.",
+    login: "تسجيل الدخول",
+    disconnect: "قطع الاتصال",
+    managedExternally: "مدار خارجيًا",
+    copied: "تم النسخ ✓",
+    cli: "CLI",
+    copyCliCommand: "نسخ أمر CLI (لخارجي / احتياطي)",
+    connect: "اتصال",
+    sessionExpires: "تنتهي صلاحية الجلسة خلال {time}",
+    initiatingLogin: "بدء تدفق تسجيل الدخول…",
+    exchangingCode: "تبديل الرمز برموز الوصول…",
+    connectedClosing: "متصل! إغلاق…",
+    loginFailed: "فشل تسجيل الدخول.",
+    sessionExpired: "انتهت صلاحية الجلسة. انقر إعادة المحاولة لبدء تسجيل دخول جديد.",
+    reOpenAuth: "إعادة فتح صفحة المصادقة",
+    reOpenVerification: "إعادة فتح صفحة التحقق",
+    submitCode: "تقديم الرمز",
+    pasteCode: "ألصق رمز التفويض (مع لاحقة #state مقبولة)",
+    waitingAuth: "في انتظار تفويضك في المتصفح…",
+    enterCodePrompt: "فتح تبويب جديد. أدخل هذا الرمز عند الطلب:",
+    pkceStep1: "فتح تبويب جديد إلى claude.ai. سجِّل الدخول وانقر تفويض.",
+    pkceStep2: "انسخ رمز التفويض المعروض بعد التفويض.",
+    pkceStep3: "ألصقه أدناه وقدِّم.",
+    flowLabels: {
+      pkce: "تسجيل دخول المتصفح (PKCE)",
+      device_code: "رمز الجهاز",
+      external: "CLI خارجي",
+    },
+    expiresIn: "تنتهي خلال {time}",
+  },
+
+  language: {
+    switchTo: "التبديل إلى الإنجليزية",
+  },
+
+  theme: {
+    title: "السمة",
+    switchTheme: "تبديل السمة",
+  },
+
+  achievements: {
+    hero: {
+      kicker: "Agentic Gamerscore",
+      title: "إنجازات Hermes",
+      subtitle:
+        "شارات Hermes قابلة للجمع مكتسبة من سجل الجلسات الفعلي. الإنجازات غير المكتملة المعروفة تُعرض كـ Discovered؛ تبقى الإنجازات السرية مخفية حتى يظهر السلوك المطابق لأول مرة.",
+      scan_subtitle:
+        "فحص سجل جلسات Hermes. يمكن أن يستغرق الفحص الأول 5–10 ثوانٍ على السجلات الكبيرة.",
+    },
+    actions: {
+      rescan: "إعادة الفحص",
+    },
+    stats: {
+      unlocked: "مفتوحة",
+      unlocked_hint: "شارات مكتسبة",
+      discovered: "مكتشفة",
+      discovered_hint: "معروفة، لم تُكتسب بعد",
+      secrets: "أسرار",
+      secrets_hint: "مخفية حتى أول إشارة",
+      highest_tier: "أعلى مستوى",
+      highest_tier_hint: "نحاس → فضة → ذهب ← ماس → أوليمبي",
+      latest: "الأحدث",
+      latest_hint_empty: "شغِّل Hermes أكثر",
+      none_yet: "لا توجد بعد",
+    },
+    state: {
+      unlocked: "مفتوح",
+      discovered: "مكتشف",
+      secret: "سري",
+    },
+    tier: {
+      target: "الهدف {tier}",
+      hidden: "مخفي",
+      complete: "مكتمل",
+      objective: "الهدف",
+    },
+    progress: {
+      hidden: "مخفي",
+    },
+    scan: {
+      building_headline: "إنشاء ملف الإنجاز…",
+      building_detail:
+        "قراءة الجلسات، استدعاءات الأدوات، بيانات تعريف النموذج، وحالة الفتح.",
+      starting_headline: "بدء فحص الإنجازات…",
+      progress_detail:
+        "تم فحص {scanned} من {total} جلسة · {pct}%. تنفتح الشارات مع تدفق المزيد من السجل.",
+      idle_detail:
+        "قراءة الجلسات، استدعاءات الأدوات، بيانات تعريف النموذج، وحالة الفتح. تظهر الشارات هنا عند فتحها.",
+    },
+    guide: {
+      tiers_header: "المستويات",
+      secret_header: "الإنجازات السرية",
+      secret_body:
+        "تخفى الأسرار محددها الدقيق. بمجرد أن ترى Hermes إشارة ذات صلة، تصبح البطاقة مكتشفة وتعرض متطلباتها.",
+      scan_status_header: "حالة الفحص",
+      scan_status_body:
+        "تُفحص Hermes السجل المحلي مرة واحدة، ثم تظهر البطاقات تلقائيًا. لا يوجد توقف إذا استغرق هذا بضع ثوانٍ.",
+      what_scanned_header: "ما يتم فحصه",
+      what_scanned_body:
+        "الجلسات، استدعاءات الأدوات، بيانات تعريف النموذج، الأخطاء، الإنجازات، وحالة الفتح المحلية.",
+    },
+    card: {
+      share_title: "مشاركة هذا الإنجاز",
+      share_label: "مشاركة {name}",
+      share_text: "مشاركة",
+      how_to_reveal: "كيفية الإظهار",
+      what_counts: "ما يُحتسب",
+      evidence_label: "دليل",
+      evidence_session_fallback: "جلسة",
+      no_evidence: "لا دليل بعد",
+    },
+    latest: {
+      header: "آخر الفتوحات",
+    },
+    empty: {
+      no_secrets_header: "لا توجد أسرار مخفية متبقية في هذا الفحص.",
+      no_secrets_body:
+        "تلميح: تبدأ الأسرار عادة من أنماط الفشل غير العادية أو أنماط المستخدم المتقدم — تعارضات المنافذ، حواجز الأذونات، متغيرات بيئة مفقودة، أخطاء YAML، تصادمات Docker، استخدام الإرجاع أو التبقي، ضربات التخزين المؤقت، أو إصلاحات صغيرة بعد الكثير من الأخطاء الحمراء."
+    },
+    filters: {
+      all_categories: "الكل",
+      visibility_all: "الكل",
+      visibility_unlocked: "مفتوح",
+      visibility_discovered: "مكتشف",
+      visibility_secret: "سري",
+    },
+    share: {
+      dialog_label: "مشاركة الإنجاز",
+      header: "مشاركة: {name}",
+      close: "إغلاق",
+      rendering: "جاري العرض…",
+      card_alt: "بطاقة مشاركة {name}",
+      error_generic: "حدث خطأ ما.",
+      x_title: "يفتح X مع منشومعد مسبقًا",
+      x_button: "مشاركة على X",
+      copy_title: "نسخ الصورة للصقها في منشورك",
+      copy_button: "نسخ الصورة",
+      copied: "تم النسخ ✓",
+      download_button: "تنزيل PNG",
+      hint:
+        "المشاركة على X تفتح منشورًا معدَّلاً مسبقًا في تبويب جديد. انقر نسخ الصورة أولاً إذا أردت شارة الإنجاز 1200×630 مرفقة — يسمح X باللصق مباشرة في مؤلف التغريد. تنزيل PNG يحفظ الملف للاستخدام anywhere.",
+      clipboard_unsupported:
+        "نسخ صورة الحافظة غير مدعوم في هذا المتصفح — استخدم التنزيل بدلاً من ذلك.",
+      tweet_text: "فتحت للتو {tier_part}\"{name}\" في Hermes Agent ☤"
+    },
+  },
+
+  kanban: {
+    loading: "جاري تحميل لوحة Kanban…",
+    loadFailed: "فشل تحميل لوحة Kanban: ",
+    loadFailedHint:
+      "يُنشئ الواجهة الخلفية kanban.db تلقائيًا عند أول قراءة. إذا استمرت المشكلة، تفقَّد سجلات لوحة التحكم.",
+    board: "لوحة",
+    newBoard: "+ لوحة جديدة",
+    newBoardTitle: "لوحة جديدة",
+    newBoardDescription:
+      "تتيح اللوحات فصل تدفقات العمل غير المرتبطة — واحدة لكل مشروع أو مستودع أو مجال.",
+    slug: "المعرِّف",
+    slugHint: "— أحرف صغيرة، واصلات، مثال atm10-server",
+    displayName: "الاسم المعروض",
+    displayNameHint: "(اختياري)",
+    description: "الوصف",
+    descriptionHint: "(اختياري)",
+    icon: "أيقونة",
+    iconHint: "(حرف واحد أو رمز تعبيري)",
+    switchAfterCreate: "التبديل إلى هذه اللوحة بعد إنشائها",
+    cancel: "إلغاء",
+    creating: "جاري الإنشاء…",
+    createBoard: "إنشاء لوحة",
+    search: "بحث",
+    filterCards: "تصفية البطاقات…",
+    tenant: "المستأجر",
+    allTenants: "كل المستأجرين",
+    assignee: "المكلَّف",
+    allProfiles: "كل الملفات الشخصية",
+    showArchived: "إظهار المؤرشفة",
+    lanesByProfile: "مسارات حسب الملف الشخصي",
+    nudgeDispatcher: "دفع المُجلِّب",
+    refresh: "تحديث",
+    selected: "محدد",
+    complete: "إكمال",
+    archive: "أرشفة",
+    apply: "تطبيق",
+    clear: "مسح",
+    createTask: "إنشاء مهمة في هذا العمود",
+    noTasks: "— لا توجد مهام —",
+    unassigned: "غير مكلَّف",
+    needsAssignee: "يحتاج مكلِّف",
+    needsAssigneeHint:
+      "المتطلبات مُلباة، لكن المُجلِّب يتخطى هذه المهمة حتى تعيّن ملفًا شخصيًا.",
+    untitled: "(بدون عنوان)",
+    loadingDetail: "جاري التحميل…",
+    addComment: "إضافة تعليق… (Enter للتقديم)",
+    comment: "تعليق",
+    status: "الحالة",
+    workspace: "مساحة العمل",
+    skills: "المهارات",
+    createdBy: "أنشئ بواسطة",
+    result: "النتيجة",
+    comments: "التعليقات",
+    events: "الأحداث",
+    runHistory: "سجل التنفيذ",
+    workerLog: "سجل العامل",
+    loadingLog: "جاري تحميل السجل…",
+    noWorkerLog:
+      "— لا يوجد سجل عامل بعد (لم تُنشَ المهمة أو تم تدوير السجل) —",
+    noDescription: "— لا يوجد وصف —",
+    noComments: "— لا توجد تعليقات —",
+    edit: "تعديل",
+    save: "حفظ",
+    dependencies: "الاعتماديات",
+    parents: "الآباء:",
+    children: "الأبناء:",
+    none: "لا شيء",
+    addParent: "— إضافة أب —",
+    addChild: "— إضافة ابن —",
+    removeDependency: "إزالة الاعتماد",
+    block: "حظر",
+    unblock: "إلغاء الحظر",
+    notifyHomeChannels: "إشعار القنوات الرئيسية",
+    diagnostics: "التشخيصات",
+    hide: "إخفاء",
+    show: "إظهار",
+    attention: "انتباه",
+    tasksNeedAttention: "مهام تحتاج انتباه",
+    taskNeedsAttention: "مهمة واحدة تحتاج انتباه",
+    diagnostic: "تشخيصي",
+    open: "فتح",
+    close: "إغلاق (Esc)",
+    reassignTo: "إعادة تعيين إلى:",
+    copied: "تم النسخ",
+    copyCommand: "نسخ الأمر إلى الحافظة",
+    reclaim: "استعادة",
+    reassign: "إعادة تعيين",
+    renderingError: "اصطدم تبويب Kanban بخطأ عرض",
+    reloadView: "إعادة تحميل العرض",
+    wsAuthFailed:
+      "فشلت مصادقة WebSocket — أعد تحميل الصفحة لتحديث رمز الجلسة.",
+    markDone: "تحديد {n} مهمة كمكتملة؟",
+    markArchived: "أرشفة {n} مهمة؟",
+    warning: "تحذير",
+    phantomIds: "معرفات وهمية:",
+    active: "نشط",
+    ended: "منتهٍ",
+    noProfile: "(لا يوجد ملف شخصي)",
+    showAllAttempts: "إظهار كل المحاولات",
+    sendingUpdates: "إرسال التحديثات إلى",
+    sendNotifications: "إرسال إشعارات مكتمل / محظور / متروك لـ",
+    archiveBoardConfirm:
+      "أرشفة لوحة '{name}'؟ ستُنقَل إلى boards/_archived/ لتتمكن من استرجاعها لاحقًا. المهام على هذه اللوحة لن تظهر بعد الآن في أي مكان في الواجهة.",
+    archiveBoardTitle: "أرشفة هذه اللوحة",
+    boardSwitcherHint: "تتيح اللوحات فصل تدفقات عمل غير مرتبطة",
+    taskCreatedWarning: "تم إنشاء المهمة، لكن: ",
+    moveFailed: "فشل النقل: ",
+    bulkFailed: "مجموعة: ",
+    completionBlockedHallucination: "⚠ الحظر — معرّفات بطاقات وهمية",
+    suspectedHallucinatedReferences: "⚠ النص يشير إلى معرّفات بطاقات وهمية",
+    pickProfileFirst: "اختر ملفًا شخصيًا أولاً.",
+    unblockedMessage: "تم إلغاء حظر {id}. المهمة جاهزة للدورة التالية.",
+    unblockFailed: "فشل إلغاء الحظر: ",
+    reclaimedMessage: "تم استعادة {id}. المهمة عادت إلى جاهزة.",
+    reclaimFailed: "فشل الاستعادة: ",
+    reassignedMessage: "تم إعادة تعيين {id} إلى {profile}.",
+    reassignFailed: "فشل إعادة التعيين: ",
+    selectForBulk: "تحديد لإجراءات جماعية",
+    clickToEdit: "انقر للتعديل",
+    clickToEditAssignee: "انقر لتعديل المكلَّف",
+    emptyAssignee: "(فارغ = إزالة التكليف)",
+    columnLabels: {
+      triage: "فرز",
+      todo: "مهام",
+      ready: "جاهز",
+      running: "قيد التنفيذ",
+      blocked: "محظور",
+      done: "منجز",
+      archived: "مؤرشف",
+    },
+    columnHelp: {
+      triage: "أفكار أولية — سيصِغ المُحدِّد المواصفات",
+      todo: "في انتظار الاعتماديات أو غير مكلَّف",
+      ready: "الاعتماديات مُلباة؛ عيّن ملفًا شخصيًا للتشغيل",
+      running: "مطالب بعامل — قيد التنفيذ",
+      blocked: "طلب العامل مدخلات من الإنسان",
+      done: "مكتمل",
+      archived: "مؤرشف",
+    },
+    confirmDone:
+      "تحديد هذه المهمة كمكتملة؟ سيتم تحرير مطالبة العامل ويصبح الأبناء المعتمدون جاهزين.",
+    confirmArchive:
+      "أرشفة هذه المهمة؟ ستختفي من عرض اللوحة الافتراضي.",
+    confirmBlocked:
+      "تحديد هذه المهمة كمحظورة؟ سيتم تحرير مطالبة العامل.",
+    completionSummary:
+      "ملخص الإنجاز لـ {label}. يُخزَّن كنتيجة للمهمة.",
+    completionSummaryRequired:
+      "ملخص الإنجاز مطلوب قبل تحديد المهمة كمكتملة.",
+    triagePlaceholder: "فكرةrough — سيقوم الذكاء الاصطناعي بصياغة المواصفات…",
+    taskTitlePlaceholder: "عنوان المهمة الجديد…",
+    specifier: "محدِّد المواصفات",
+    assigneePlaceholder: "المكلَّف",
+    priority: "الأولوية",
+    skillsPlaceholder:
+      "مهارات (اختياري، مفصولة بفواصل): translation, github-code-review",
+    noParent: "— لا يوجد أب —",
+    workspacePathDir: "مسار مساحة العمل (مطلوب، مثال ~/projects/my-app)",
+    workspacePathOptional:
+      "مسار مساحة العمل (اختياري، مستنتج من المكلَّف إذا كان فارغًا)",
+    logTruncated: "(عرض آخر 100 كيلوبايت — السجل الكامل في ",
+    logAt: ")",
+  },
+});
diff --git a/web/src/i18n/context.tsx b/web/src/i18n/context.tsx
index aa7a219b924..e25b0cc4b50 100644
--- a/web/src/i18n/context.tsx
+++ b/web/src/i18n/context.tsx
@@ -1,4 +1,4 @@
-import { createContext, useContext, useState, useCallback, type ReactNode } from "react";
+import { createContext, useContext, useState, useCallback, useEffect, type ReactNode } from "react";
 import type { Locale, Translations } from "./types";
 import { en } from "./en";
 import { zh } from "./zh";
@@ -16,6 +16,7 @@ import { ga } from "./ga";
 import { pt } from "./pt";
 import { ru } from "./ru";
 import { hu } from "./hu";
+import { ar } from "./ar";
 
 const TRANSLATIONS: Record<Locale, Translations> = {
   en,
@@ -34,8 +35,13 @@ const TRANSLATIONS: Record<Locale, Translations> = {
   pt,
   ru,
   hu,
+  ar,
 };
 
+// Locales whose script flows right-to-left. Consumed by the provider to set the
+// document direction so Tailwind's logical utilities (ms-/me-, ps-/pe-) flip.
+const RTL_LOCALES = new Set<Locale>(["ar"]);
+
 // Display metadata for the language picker — endonym (native name) so users
 // recognize their language even if they don't speak the current UI language.
 // Exposed as a constant so the LanguageSwitcher and any future settings page
@@ -62,6 +68,7 @@ export const LOCALE_META: Record<Locale, { name: string }> = {
   pt: { name: "Português" },
   ru: { name: "Русский" },
   hu: { name: "Magyar" },
+  ar: { name: "العربية" },
 };
 
 const SUPPORTED_LOCALES = Object.keys(TRANSLATIONS) as Locale[];
@@ -105,6 +112,12 @@ export function I18nProvider({ children }: { children: ReactNode }) {
     }
   }, []);
 
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    document.documentElement.lang = locale;
+    document.documentElement.dir = RTL_LOCALES.has(locale) ? "rtl" : "ltr";
+  }, [locale]);
+
   const value: I18nContextValue = {
     locale,
     setLocale,
diff --git a/web/src/i18n/define-locale.ts b/web/src/i18n/define-locale.ts
new file mode 100644
index 00000000000..401a0cccb56
--- /dev/null
+++ b/web/src/i18n/define-locale.ts
@@ -0,0 +1,46 @@
+import { en } from "./en";
+import type { Translations } from "./types";
+
+// Partial-locale helper: a translation file supplies only the strings it has
+// translated and every missing key falls back to English, while unknown keys
+// still fail the type-check. Mirrors the desktop app's `defineLocale` so a new
+// locale (e.g. Arabic) can land without hand-porting every future English key.
+
+type TranslationOverride<T> = T extends (...args: never[]) => string
+  ? T
+  : T extends readonly unknown[]
+    ? T
+    : T extends string
+      ? string
+      : T extends object
+        ? { [K in keyof T]?: TranslationOverride<T[K]> }
+        : T;
+
+export type TranslationOverrides = TranslationOverride<Translations>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function mergeTranslations<T>(base: T, overrides: TranslationOverride<T> | undefined): T {
+  if (!isRecord(base) || !isRecord(overrides)) {
+    return (overrides ?? base) as T;
+  }
+
+  const result: Record<string, unknown> = { ...base };
+
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    const baseValue = result[key];
+    result[key] = isRecord(baseValue) && isRecord(value) ? mergeTranslations(baseValue, value) : value;
+  }
+
+  return result as T;
+}
+
+export function defineLocale(overrides: TranslationOverrides): Translations {
+  return mergeTranslations<Translations>(en, overrides);
+}
diff --git a/web/src/i18n/types.ts b/web/src/i18n/types.ts
index 52fd86acf6a..1991a20f51d 100644
--- a/web/src/i18n/types.ts
+++ b/web/src/i18n/types.ts
@@ -14,7 +14,8 @@ export type Locale =
   | "ga"
   | "pt"
   | "ru"
-  | "hu";
+  | "hu"
+  | "ar";
 
 export interface Translations {
   // ── Common ──
diff --git a/web/src/index.css b/web/src/index.css
index 30b601e6c57..e4b5e2777f9 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -245,3 +245,11 @@ code { font-size: 0.875rem; }
     2px 2px;
 }
 
+/* RTL support — Arabic and any future right-to-left locale. The i18n provider
+   sets `dir` on <html>; Tailwind v4's logical spacing utilities (ms-/me-,
+   ps-/pe-) and logical properties then flip automatically. Scoped so the
+   default LTR layout is untouched. */
+html[dir="rtl"] {
+  direction: rtl;
+}
+
diff --git a/web/src/lib/api.ts b/web/src/lib/api.ts
index 7474a8322a5..06a919826fa 100644
--- a/web/src/lib/api.ts
+++ b/web/src/lib/api.ts
@@ -2333,6 +2333,7 @@ export interface MoaModelSlot {
   model: string;
   /** Optional per-slot reasoning effort — round-tripped, not edited here. */
   reasoning_effort?: string;
+  enabled?: boolean;
 }
 
 export interface MoaConfigResponse {
@@ -2343,10 +2344,12 @@ export interface MoaConfigResponse {
     aggregator: MoaModelSlot;
     reference_temperature: number;
     aggregator_temperature: number;
+    reference_timeout: number | null;
+    degraded_reference_policy: "loud" | "silent";
     max_tokens: number;
     /** Optional advisor output cap — round-tripped, not edited here. */
     reference_max_tokens?: number | null;
-    /** Fan-out cadence (per_iteration | user_turn) — round-tripped. */
+    /** Fan-out cadence (user_turn default | per_iteration | every_n:N) — round-tripped. */
     fanout?: string;
     enabled: boolean;
   }>;
@@ -2354,6 +2357,8 @@ export interface MoaConfigResponse {
   aggregator: MoaModelSlot;
   reference_temperature: number;
   aggregator_temperature: number;
+  reference_timeout: number | null;
+  degraded_reference_policy: "loud" | "silent";
   max_tokens: number;
   enabled: boolean;
 }
diff --git a/web/src/pages/ModelsPage.tsx b/web/src/pages/ModelsPage.tsx
index e4fb338bc97..8954f8b7e39 100644
--- a/web/src/pages/ModelsPage.tsx
+++ b/web/src/pages/ModelsPage.tsx
@@ -34,6 +34,7 @@ import { Spinner } from "@nous-research/ui/ui/components/spinner";
 import { Stats } from "@nous-research/ui/ui/components/stats";
 import { Card, CardContent, CardHeader, CardTitle } from "@nous-research/ui/ui/components/card";
 import { Badge } from "@nous-research/ui/ui/components/badge";
+import { Switch } from "@nous-research/ui/ui/components/switch";
 import { ConfirmDialog } from "@/components/ConfirmDialog";
 import { useModalBehavior } from "@/hooks/useModalBehavior";
 import { usePageHeader } from "@/contexts/usePageHeader";
@@ -764,6 +765,8 @@ function MoaModelsModal({
       aggregator: draft.aggregator,
       reference_temperature: draft.reference_temperature,
       aggregator_temperature: draft.aggregator_temperature,
+      reference_timeout: draft.reference_timeout,
+      degraded_reference_policy: draft.degraded_reference_policy,
       max_tokens: draft.max_tokens,
       enabled: draft.enabled,
     };
@@ -855,13 +858,30 @@ function MoaModelsModal({
           <div className="space-y-2">
             <div className="text-display text-xs font-medium tracking-wider">Reference models</div>
             {preset.reference_models.map((slot, index) => (
-              <div key={`${selected}-${slot.provider}-${slot.model}-${index}`} className="flex items-center gap-2 border border-border/50 bg-muted/20 px-3 py-2">
+              <div
+                key={`${selected}-${slot.provider}-${slot.model}-${index}`}
+                className={cn(
+                  "flex items-center gap-2 border border-border/50 bg-muted/20 px-3 py-2",
+                  slot.enabled === false && "opacity-60"
+                )}
+              >
+                <Switch
+                  checked={slot.enabled !== false}
+                  onCheckedChange={(checked) =>
+                    updateSelectedPreset((prev) => ({
+                      ...prev,
+                      reference_models: prev.reference_models.map((s, i) =>
+                        i === index ? { ...s, enabled: checked === true } : s
+                      ),
+                    }))
+                  }
+                />
                 <div className="min-w-0 flex-1 truncate font-mono text-xs text-text-secondary">{slotLabel(slot)}</div>
                 <Button size="sm" outlined onClick={() => setPicker({ kind: "reference", index })}>Change</Button>
                 <Button size="sm" ghost disabled={preset.reference_models.length <= 1} onClick={() => updateSelectedPreset((prev) => ({ ...prev, reference_models: prev.reference_models.filter((_, i) => i !== index) }))}>Remove</Button>
               </div>
             ))}
-            <Button size="sm" outlined onClick={() => updateSelectedPreset((prev) => ({ ...prev, reference_models: [...prev.reference_models, prev.aggregator] }))}>Add reference model</Button>
+            <Button size="sm" outlined onClick={() => updateSelectedPreset((prev) => ({ ...prev, reference_models: [...prev.reference_models, { ...prev.aggregator, enabled: true }] }))}>Add reference model</Button>
           </div>
 
           <div className="space-y-2">
@@ -895,7 +915,7 @@ function MoaModelsModal({
               if (picker.kind === "aggregator") return { ...prev, aggregator: { provider, model } };
               return {
                 ...prev,
-                reference_models: prev.reference_models.map((slot, i) => i === picker.index ? { provider, model } : slot),
+                reference_models: prev.reference_models.map((slot, i) => i === picker.index ? { ...slot, provider, model } : slot),
               };
             });
           }}
diff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.md
index e3eb2c4d8f2..c27f371c396 100644
--- a/website/docs/developer-guide/context-compression-and-caching.md
+++ b/website/docs/developer-guide/context-compression-and-caching.md
@@ -87,6 +87,7 @@ compression:
   #   "claude-sonnet": 0.35  # overrides" below.
   target_ratio: 0.20         # How much of threshold to keep as tail (default: 0.20)
   protect_last_n: 20         # Minimum protected tail messages (default: 20)
+  min_tail_user_messages: 1  # Real user messages guaranteed in the tail (default: 1)
   codex_gpt55_autoraise: true  # gpt-5.5 on Codex OAuth: raise trigger to 85% (default: true)
   codex_gpt55_autoraise_notice: true  # Show the one-time autoraise notice (default: true)
   codex_app_server_auto: native  # native|hermes|off for Codex app-server thread compaction
@@ -107,6 +108,7 @@ auxiliary:
 | `model_thresholds` | `{}` | map | Per-model overrides of `threshold`. Keys are substring-matched against the model name (longest match wins). The small-context floor still applies on top (see below) |
 | `target_ratio` | `0.20` | 0.10-0.80 | Controls tail protection token budget: `threshold_tokens × target_ratio` |
 | `protect_last_n` | `20` | ≥1 | Minimum number of recent messages always preserved |
+| `min_tail_user_messages` | `1` | ≥1 | Minimum number of REAL (actionable) user messages guaranteed to survive in the uncompressed tail. `1` = the existing single last-user anchor (behavior-preserving default). Raise to e.g. `3` to keep the last 3 real user turns verbatim even when bulky tool outputs fill the tail token budget. Blank platform echoes, compaction handoffs, and synthetic continuation rows never count toward N. The guarantee wins over the tail token budget — the tail may exceed the budget when the anchor pulls the cut back |
 | `protect_first_n` | `3` | (hardcoded) | System prompt + first exchange always preserved |
 | `idle_compact_after_seconds` | `0` | ≥0 seconds | Opt-in: compact up front when a session resumes after this many seconds idle (0 = disabled). Skips when context ≤ threshold × target_ratio; honors cooldown/anti-thrash/lock guards |
 | `codex_gpt55_autoraise` | `true` | bool | Raise the trigger to 85% for gpt-5.5 on the ChatGPT Codex OAuth route (see below). Set `false` to keep the global `threshold` |
diff --git a/website/docs/developer-guide/context-engine-plugin.md b/website/docs/developer-guide/context-engine-plugin.md
index a6e53de9dbf..169b2bf7cc6 100644
--- a/website/docs/developer-guide/context-engine-plugin.md
+++ b/website/docs/developer-guide/context-engine-plugin.md
@@ -97,6 +97,67 @@ These have sensible defaults in the ABC. Override as needed:
 | `handle_tool_call(name, args, **kwargs)` | Returns error JSON | You implement tool handlers |
 | `should_compress_preflight(messages)` | Returns `False` | You can do a cheap pre-API-call estimate |
 | `get_status()` | Standard token/threshold dict | You have custom metrics to expose |
+| `select_context(request_messages, *, conversation_messages, incoming_message, budget_tokens)` | Returns `None` (no-op) | You select/route which context enters **this** request (retrieval, topic routing) — see below |
+| `on_turn_complete(messages, usage=None, **kwargs)` | No-op | You ingest/index/observe the finished turn — see below |
+
+## Per-turn context selection and observation
+
+`compress()` answers "context is too long → make it shorter". Two optional,
+no-op-default hooks cover the orthogonal *selection / observation* axis, so an
+engine no longer has to force `should_compress()` to `True` and abuse
+`compress()` as a per-turn callback:
+
+```python
+def select_context(self, request_messages, *, conversation_messages=None,
+                   incoming_message=None, budget_tokens=0):
+    """Choose/replace the context for THIS request, before dispatch.
+
+    Return a new message list to use for this one provider call (retrieval,
+    topic routing, role/branch switching), or None to leave it unchanged.
+    Request-only: the persisted conversation history is never mutated.
+    """
+
+def on_turn_complete(self, messages, usage=None, **kwargs):
+    """Observe a finished turn after the assistant/tool loop completes.
+
+    Receives a shallow copy of the finalized transcript plus the turn's
+    canonical usage dict (or None if no provider response was reached), so the
+    engine can ingest/index/summarize for the next select_context(). The return
+    value is ignored.
+    """
+```
+
+Contract:
+
+- **No-op by default, fail-open.** Both default to `return None`. A missing hook, an exception, or an invalid return value leaves the request untouched — so a failing engine is never worse than not installing one. The host also identity-checks for the inherited ABC default and skips it entirely, so non-implementing engines (including the built-in compressor) pay no per-request work at all.
+- **`select_context()` is request-only.** The returned list replaces the messages for a single provider call; persisted history is never written. Returning `None`, `[]`, a non-list, or a list containing non-dicts all fall open to the unmodified request.
+- **Ordering / cache stability.** The hook runs **before** prompt cache-control and every request sanitizer, so (a) a replacement still passes the same validation as any request, and (b) the no-op default leaves the request byte-identical — prompt-cache behaviour is unchanged for non-implementing engines. An engine that replaces the list changes only its own cache prefix. Evaluated per provider request (re-runs on retries).
+- **`on_turn_complete()`** is post-turn observation only; treat `messages` as read-only. **Coverage is best-effort:** it fires from the standard turn-finalization seam. Some abnormal early-return paths in the loop (e.g. a content-policy block or a provider terminal failure) persist and return without routing through finalization, so they do not currently emit this hook — treat it as a best-effort observation for completed turns, not a guaranteed callback for every early exit. Unifying all terminal paths behind one finalization seam is a separate follow-up.
+
+### When to use these hooks — and when NOT to
+
+- **Implement `select_context()` only when your engine must *replace* the
+  per-request context** — retrieval-augmented selection, topic/branch routing,
+  role switching. It is the only verb that can swap which messages enter a
+  request: the `pre_llm_call` plugin hook is inject-only by documented design
+  (it appends to the user message and never rewrites the list, to preserve the
+  prompt-cache prefix). If you don't need replacement, don't implement it.
+- **If your plugin only needs post-turn observation / ingestion** (indexing,
+  memory sync, analytics), implement a **memory provider** (`sync_turn()` —
+  see [Memory Provider Plugins](./memory-provider-plugin.md)) instead of a
+  context engine. A context engine takes ownership of the session's compaction
+  policy; a memory provider observes turns without owning anything.
+  `on_turn_complete()` exists as the observation mirror for engines that
+  *already* need `select_context()` — so the same component can learn from the
+  turn it just routed — not as a general-purpose turn callback.
+- **Prompt-cache impact of a real `select_context()`.** A non-no-op selection
+  naturally changes the prompt-cache prefix for the turns where it changes the
+  selection — that request's prefix no longer matches the provider's cached
+  prefix, so those turns re-write cache instead of reading it. Engines should
+  return **stable selections when nothing has changed** (same object or an
+  equal list), and only reshape the context when the routing decision actually
+  differs; a selection that shuffles per turn silently forfeits cache reuse
+  every turn.
 
 ## Engine tools
 
diff --git a/website/docs/developer-guide/egress-internals.md b/website/docs/developer-guide/egress-internals.md
new file mode 100644
index 00000000000..f84160788a0
--- /dev/null
+++ b/website/docs/developer-guide/egress-internals.md
@@ -0,0 +1,318 @@
+---
+sidebar_position: 14
+title: "Egress proxy internals"
+description: "How the iron-proxy egress firewall integrates with Hermes — module layout, lifecycle, security invariants, and extension points"
+---
+
+# Egress proxy internals
+
+This page covers the architecture of the egress credential-injection firewall (`hermes egress` / iron-proxy) from a contributor / plugin author's perspective. End-user setup + usage docs live at [Egress proxy](../user-guide/egress/iron-proxy.md).
+
+The threat model and high-level design are summarised on the user page; this page is about *how* it's wired, where the security-relevant code lives, and what invariants you have to preserve if you touch it.
+
+## Module layout
+
+```text
+agent/proxy_sources/iron_proxy.py     Core: binary install, CA gen, config build,
+                                       subprocess lifecycle, mappings I/O, PID/nonce
+                                       defense.  Pure-function surface where possible.
+
+hermes_cli/proxy_cli.py               Wizard + slash command handlers.
+                                       `hermes egress {install,setup,start,stop,
+                                       status,disable,config}`.  Wires the
+                                       core module into argparse.
+
+hermes_cli/main.py:_dispatch_egress   Top-level subparser dispatcher.
+                                       dest='egress_command' (intentionally
+                                       disjoint from the inbound OAuth
+                                       `hermes proxy` subparser, which uses
+                                       dest='proxy_command').
+
+hermes_cli/config.py: proxy schema    The `proxy:` block in DEFAULT_CONFIG.
+                                       Adding a knob means: add it here, add a
+                                       wizard prompt or `setdefault` in
+                                       proxy_cli.cmd_setup, and document it
+                                       in the user-guide page.
+
+tools/environments/docker.py
+  _egress_proxy_args_for_docker()     Builds the volume_args / env_overrides /
+                                       host_args triple that the Docker backend
+                                       injects when `proxy.enabled: true`.
+
+  DockerEnvironment.__init__          Docker-side merge logic: collision
+                                       detection against critical egress vars,
+                                       NODE_OPTIONS append-merge via the
+                                       _HERMES_EGRESS_NODE_OPTIONS_APPEND
+                                       sentinel, enforce_on_docker precedence.
+
+tests/test_iron_proxy.py              Hermetic tests (~70).  Binary install
+                                       path, config build, mappings I/O,
+                                       subprocess lifecycle, docker arg builder,
+                                       deny CIDR defaults, bind policy, CA
+                                       TOCTOU, ensure_audit_log behaviour, etc.
+
+tests/test_iron_proxy_cli.py          CLI handler unit tests (~20).  Argparse
+                                       wiring, fail-loud paths, BWS refresh
+                                       wire-up, dest='egress_command'
+                                       regression guard.
+
+tests/test_iron_proxy_e2e.py          Live E2E (gated on HERMES_RUN_E2E=1).
+                                       Real iron-proxy binary, real curl,
+                                       end-to-end token swap verified.
+```
+
+## Lifecycle
+
+```text
+hermes egress install
+  -> agent.proxy_sources.iron_proxy.install_iron_proxy(force=...)
+       Downloads pinned tarball + checksums.txt from GitHub Releases.
+       SHA-256 verification before extraction.
+       tarfile.extract(..., filter="data") on Python 3.12+ (PEP 706);
+         falls back to plain extract on older Python with member-name
+         sanitisation via _pick_tar_member.
+       Stage into ~/.hermes/bin/.iron-proxy_XXXX, chmod 755, os.replace
+         to ~/.hermes/bin/iron-proxy (atomic).
+       _VERSION_CACHE.pop(target) so a forced reinstall re-probes
+         --version on next call.
+
+hermes egress setup [--from-bitwarden | --no-bitwarden] [--rotate-tokens]
+  -> proxy_cli.cmd_setup
+       Step 1. find_iron_proxy(install_if_missing=False) -> install if absent.
+       Step 2. ensure_ca_cert()
+                 Run openssl genrsa + req via subprocess.
+                 Write CA key via os.open(O_WRONLY|O_CREAT|O_TRUNC|O_NOFOLLOW, 0o600)
+                   + os.replace.  Never exists on disk under default umask.
+                 Write CA cert with 0o644 (public).
+       Step 3. discover_provider_mappings() or pull names from BWS via
+                 fetch_bitwarden_secrets() when --from-bitwarden.
+                 merge_mappings(existing=load_mappings(), discovered,
+                                rotate=args.rotate_tokens) preserves prior
+                 tokens unless --rotate-tokens is passed.
+                 discover_uncovered_providers() and surface warnings.
+       Step 4. ensure_audit_log(audit_log_path)   # raises on OSError
+               build_proxy_config(...) with defaults applied at the call site
+                 (deny CIDRs default, bind policy from _default_http_listen).
+               write_proxy_config(cfg)            # atomic via .tmp + os.replace, 0o600
+               write_mappings(mappings)           # atomic, 0o600
+       Step 5. proxy_cfg["enabled"] = True; credential_source preservation logic
+               (do NOT silently downgrade bitwarden -> env on re-run);
+               save_config(cfg).
+
+hermes egress start
+  -> proxy_cli.cmd_start
+       Pre-checks (refuse-start path):
+         - credential_source=bitwarden? -> pre-validate access_token_env + project_id
+       -> iron_proxy.start_proxy(
+            refresh_secrets_from_bitwarden=...,
+            bitwarden_config=...,
+          )
+            existing=_read_pid(); if alive, idempotent return.
+            _build_proxy_subprocess_env(...):  ALLOWLIST + mapped real_env_names,
+              strip HTTPS_PROXY/etc. to avoid recursion, optional BWS refresh
+              (raises on missing values unless allow_env_fallback=true).
+            Plant nonce: _proxy_nonce = sha256(urandom(16)); env[NONCE_ENV] = ...
+            Open log_path via O_NOFOLLOW + 0o600 + st_uid check.
+            Popen with stdin=DEVNULL, stdout=log_fd, stderr=STDOUT,
+              start_new_session=True (POSIX).
+            Close parent's log_fd in finally.
+            _write_pidfile_safely(pidfile, proc.pid)
+              O_EXCL + O_NOFOLLOW + uid check + persisted nonce sidecar.
+              FileExistsError -> discriminate live vs stale, retry once if stale.
+            Install SIGINT/SIGTERM handlers (main-thread only).
+            Poll loop (do-while shape):
+              while True:
+                if proc.poll() is not None: tail log + unlink pidfile + raise
+                if _port_listening(probe_host, tunnel_port): break  # probe_host = configured bind host
+                if time.time() >= deadline: break  (do-while: checked AFTER first probe)
+                time.sleep(0.1)
+            If not listening at exit: _kill_and_wait(proc) + unlink pidfile + raise.
+
+hermes egress stop
+  -> iron_proxy.stop_proxy
+       _read_pid + _pid_alive guard.
+       starttime_before = _pid_proc_starttime(pid)   # Linux only; None elsewhere
+       os.kill(pid, SIGTERM)
+       Wait up to 5s for graceful exit.
+       After grace: re-check starttime + _pid_alive.
+         If recycled (starttime drift OR _pid_alive False), DO NOT SIGKILL.
+         Otherwise os.kill(pid, _KILL_SIGNAL).
+       _cleanup_state_files: unlink pidfile + nonce sibling.
+```
+
+## Security invariants
+
+These are the load-bearing properties.  If you touch the module, you must preserve them.  Where there's a regression test, it's named.
+
+### Filesystem perms
+
+| Path | Mode | Test |
+|---|---|---|
+| `~/.hermes/proxy/` (dir) | `0o700` | `test_proxy_state_dir_is_0o700` |
+| `ca.key` | `0o600` | `test_ca_key_created_with_0o600` |
+| `ca.crt` | `0o644` | (implicit; chmod call in `ensure_ca_cert`) |
+| `proxy.yaml` | `0o600` | (chmod after atomic rename in `write_proxy_config`) |
+| `mappings.json` | `0o600` | (chmod after atomic rename in `write_mappings`) |
+| `iron-proxy.pid` | `0o600` | (`os.open(..., 0o600)` mode in `_write_pidfile_safely`) |
+| `iron-proxy.nonce` | `0o600` | (`os.open(..., 0o600)` mode in `_write_pidfile_safely`) |
+| `audit.log` | `0o600` | `test_ensure_audit_log_creates_with_0o600` |
+| `iron-proxy.log` | `0o600` | (`os.open(..., 0o600)` + `fchmod`) |
+
+All write paths use `os.open(O_WRONLY | O_CREAT | O_NOFOLLOW, 0o600)` + `os.fstat().st_uid` check.  `shutil.copy2` + `os.chmod` is forbidden because it leaks a default-umask window.
+
+### Subprocess env minimisation
+
+`_build_proxy_subprocess_env` MUST NOT use `os.environ.copy()`.  The allowlist is `_PROXY_SUBPROCESS_ENV_ALLOWLIST` (PATH, HOME, locale, etc.) plus the env names referenced by `load_mappings()`.  Everything else stays on the host.
+
+Regression: `test_subprocess_env_strips_unrelated_secrets`, `test_subprocess_env_strips_proxy_recursion_vars`, `test_subprocess_env_keeps_infrastructure_vars`.
+
+### Bind policy
+
+`_default_http_listen` returns a single-element list: on Linux the docker bridge gateway IP (containers reach the proxy via `host.docker.internal:host-gateway`, which resolves to the bridge gateway — a loopback bind is unreachable from inside containers there); on macOS/Windows Docker Desktop, loopback (VPNkit routes `host.docker.internal` to the host).  Linux without a detectable docker0 bridge falls back to loopback with a warning.  Never `0.0.0.0`, never `:PORT` (INADDR_ANY).
+
+`_detect_docker_bridge_ip` validates via `ipaddress.IPv4Address` and rejects `is_unspecified` / `is_loopback` / `is_multicast` / `is_reserved` / `is_link_local` / `is_global`.  A hostile `ip` shim on PATH cannot inject `0.0.0.0`.
+
+**v0.39 schema constraint and listener roles (verified live against the binary):** the binary's `config.Proxy` struct has only singular listener fields — there is no `http_listens` (plural) list.  `tunnel_listen` is the CONNECT + MITM listener (what `HTTPS_PROXY` traffic hits); `http_listen` only handles absolute-form plain-HTTP forwards (a CONNECT sent to it is relayed upstream as a regular request and 400s).  `build_proxy_config` therefore binds `tunnel_listen` on `tunnel_port` and `http_listen` on `tunnel_port + 1`, both on the platform bind host.  The Docker backend sets `HTTPS_PROXY` to `tunnel_port` and `HTTP_PROXY` to `tunnel_port + 1`.
+
+The liveness probes (`start_proxy` poll loop, `get_status`) read the configured bind host via `_read_http_listen_from_config()` and probe THAT host — a hardcoded loopback probe would report a healthy bridge-bound daemon as dead.
+
+Regression: `test_default_bind_is_loopback_not_zero_zero` (asserts no INADDR_ANY AND that `http_listens` is NOT in the rendered yaml), `test_default_bind_uses_docker_bridge_on_linux`, `test_default_bind_falls_back_to_loopback_without_bridge`, `test_default_bind_is_loopback_on_macos`, `test_detect_docker_bridge_ip_rejects_dangerous` (parametrized over 8 attack inputs).
+
+### Metrics port collision
+
+`metrics.listen` defaults to `:9090` in iron-proxy v0.39 — the SAME port as Hermes's default `tunnel_port: 9090`.  `build_proxy_config` MUST explicitly pin `metrics.listen: 127.0.0.1:0` so the metrics binding gets an ephemeral loopback port that can never collide with the proxy listener regardless of operator-chosen `tunnel_port`.
+
+Regression: `test_metrics_listener_pinned_to_loopback_ephemeral`.
+
+### Default deny CIDRs
+
+`_DEFAULT_UPSTREAM_DENY_CIDRS` covers loopback (v4 + v6), link-local (incl. IMDS at 169.254.169.254 and the IPv4-mapped-v6 form), RFC1918, IPv6 ULA, CGNAT, and the RFC2544 benchmark range.  `build_proxy_config(..., upstream_deny_cidrs=None)` MUST emit the default; only an explicit empty list opts out.
+
+Regression: `test_default_deny_cidrs_present_when_unspecified`, `test_default_deny_includes_ipv4_mapped_v6`.
+
+### Audit log fail-loud
+
+`ensure_audit_log` raises `RuntimeError` on any `OSError`.  On the pinned v0.39 the daemon never writes this file (no `log.audit_path` field), so `cmd_setup` treats the failure as a WARNING (the file is non-load-bearing until the version bump) and qualifies the success line as "reserved".  When the pin moves to a version with `log.audit_path`, revisit: the pre-create becomes load-bearing for the 0o600-from-first-byte guarantee and the wizard should fail loud again.
+
+**v0.39 schema constraint:** `log.audit_path` is NOT a field in iron-proxy v0.39's `config.Log` struct, so `build_proxy_config` accepts the `audit_log` kwarg but does NOT emit it into the rendered yaml.  Per-request records on v0.39 land in `iron-proxy.log` alongside daemon-level events.  The `audit.log` file is still pre-created at `0o600` with `O_NOFOLLOW` so the privacy contract holds when the pinned version is bumped to one that supports the separate stream.
+
+Regression: `test_ensure_audit_log_raises_on_immutable_parent`, `test_audit_log_kwarg_does_not_inject_audit_path_v039`.
+
+### Bitwarden mode fail-loud
+
+When `credential_source: bitwarden` AND `proxy.allow_env_fallback: false` (default):
+- Missing access token env var -> `cmd_start` refuses.
+- Missing `project_id` -> `cmd_start` refuses.
+- `bws secret list` returns no values for one or more mapped providers -> `_build_proxy_subprocess_env` raises.
+
+Falling back to host env in BW mode reintroduces exactly the staleness bug the BW path is meant to defeat.
+
+Regression: `test_cmd_start_refuses_when_bitwarden_token_missing` (CLI layer); strict-mode assertions in `_build_proxy_subprocess_env` (daemon layer).
+
+### docker_env collision detection
+
+When `enforce_on_docker: true`, `docker_env` overrides on any of the egress-controlling vars (HTTPS_PROXY, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, etc.) OR any mapped `real_env_name` (OPENROUTER_API_KEY, etc.) raises `RuntimeError` BEFORE the container starts.
+
+Regression: `test_docker_env_collision_with_proxy_raises_when_enforce`.
+
+### PID recycling defense
+
+`_pid_alive` MUST consult either the in-process `_proxy_nonce` (same-process case) OR the on-disk `iron-proxy.nonce` (cross-CLI case) before trusting an `argv[0]` basename match.  `stop_proxy` MUST re-check `/proc/<pid>/stat` starttime before SIGKILL and suppress the signal on starttime drift.
+
+Regression: `test_stop_proxy_suppresses_sigkill_on_pid_recycle`, `test_pid_proc_starttime_parses_comm_with_parens`, `test_persisted_nonce_roundtrip`.
+
+### Token preservation on re-setup
+
+`merge_mappings(existing, discovered, rotate=False)` MUST return prior tokens for providers that overlap.  Re-running `hermes egress setup` cannot silently 401 running sandboxes.  `--rotate-tokens` is the explicit opt-in.
+
+Regression: `test_merge_mappings_preserves_existing_tokens`, `test_merge_mappings_rotate_mints_fresh_tokens`.
+
+### `credential_source` preservation
+
+`cmd_setup` MUST NOT downgrade `credential_source: bitwarden` to `env` on re-run without an explicit `--no-bitwarden` flag.  Running `hermes egress setup` (no flag) preserves whatever was previously configured.
+
+Tested via the `cmd_setup` flow in CLI tests (the bitwarden-preservation path is exercised when `--from-bitwarden` is followed by a plain `setup` re-run).
+
+## Extension points
+
+### Adding a new bearer-token provider
+
+`_BEARER_PROVIDERS` in `iron_proxy.py` maps env var name -> tuple of upstream hosts.  Adding an entry makes it discoverable by `discover_provider_mappings()`; the wizard mints a token for it automatically when the env var is present.
+
+```python
+_BEARER_PROVIDERS: Dict[str, Tuple[str, ...]] = {
+    ...,
+    "MY_PROVIDER_API_KEY": ("api.myprovider.com",),
+}
+```
+
+Also update `_DEFAULT_ALLOWED_HOSTS` so the proxy allows the upstream by default.  Run `test_discover_provider_mappings_*` to confirm.
+
+### Adding a new header-token provider (x-api-key family)
+
+If the provider authenticates with a static NON-Authorization header (like Anthropic's `x-api-key`, Azure's `api-key`, or Gemini's `x-goog-api-key`), add it to `_HEADER_AUTH_PROVIDERS` — iron-proxy's `secrets.replace.match_headers` targets arbitrary header names, so these are first-class swapped providers:
+
+```python
+_HEADER_AUTH_PROVIDERS: Dict[str, Dict[str, Tuple[str, ...]]] = {
+    ...,
+    "MY_PROVIDER_API_KEY": {
+        "hosts": ("api.myprovider.com",),
+        "match_headers": ("x-my-auth-header", "Authorization"),
+        "aliases": (),
+    },
+}
+```
+
+Use `aliases` ONLY for interchangeable env-var names of the *same* credential (e.g. `GOOGLE_API_KEY` for `GEMINI_API_KEY`) — aliased names collapse into a single mapping, because two `require: true` rules on the same host reject each other's requests. Also update `_DEFAULT_ALLOWED_HOSTS`.
+
+### Adding a new signature-auth provider (uncovered)
+
+If the provider uses SigV4 / SDK-minted OAuth / request signatures, a static header swap cannot cover it.  Add the env var to `_NON_BEARER_PROVIDERS` so the wizard and `hermes egress status` warn about it:
+
+```python
+_NON_BEARER_PROVIDERS: Tuple[str, ...] = (
+    ...,
+    "MY_SIGNED_PROVIDER_ACCESS_KEY",
+)
+```
+
+### Wiring iron-proxy into a non-Docker backend
+
+`_egress_proxy_args_for_docker` is Docker-specific.  Backends that want similar wiring need their own analogue that:
+
+1. Reads `load_config().get("proxy", {})`; returns empty args if `enabled` is false.
+2. Calls `iron_proxy.get_status()`; surfaces `enforce` semantics on `configured` / `pid` / `listening` / `ca_cert_path` failure paths.
+3. Calls `iron_proxy.load_mappings()`; refuses to mount if empty AND `enforce_on_docker: true`.
+4. Sets the seven env vars (HTTPS_PROXY, NO_PROXY, REQUESTS_CA_BUNDLE, SSL_CERT_FILE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, HERMES_EGRESS_PROXY) and the per-mapping `HERMES_PROXY_TOKEN_<NAME>` vars.
+5. Distributes the CA cert into the sandbox at a path the runtime will trust (typically `/etc/ssl/certs/hermes-egress-ca.crt`).
+6. Implements collision detection against the user's backend-specific env config.
+
+The Docker implementation is ~150 lines; expect similar volume for Modal / Daytona / SSH.
+
+### Subscribing to per-request audit events
+
+iron-proxy writes line-delimited JSON to `~/.hermes/proxy/iron-proxy.log` on the currently pinned v0.39 (daemon + per-request records combined; see "Logging on iron-proxy v0.39" in the user guide).  A plugin / external watcher can tail that file and react to allowlist denials, secret swaps, or upstream errors.  When the pinned version is bumped to one that supports `log.audit_path`, the per-request stream moves to `audit.log` and watchers wired to that path go live without operator action.  The schema is documented at [docs.iron.sh/audit](https://docs.iron.sh/audit) (link).
+
+## Testing
+
+```bash
+# Hermetic suite (no network, no real binary)
+scripts/run_tests.sh tests/test_iron_proxy.py tests/test_iron_proxy_cli.py
+
+# Live E2E (real binary, real curl, real CONNECT tunnel)
+HERMES_RUN_E2E=1 scripts/run_tests.sh tests/test_iron_proxy_e2e.py
+
+# Live PTY smoke against `hermes egress`
+HERMES_HOME=/tmp/hermes-egress-test python3 -m hermes_cli.main egress --help
+HERMES_HOME=/tmp/hermes-egress-test python3 -m hermes_cli.main egress setup --help
+```
+
+The CLI uses argparse, so `--help` is a good first probe for "did my new flag register correctly".
+
+## See also
+
+- User-facing setup + troubleshooting: [Egress proxy](https://hermes-agent.nousresearch.com/docs/user-guide/egress/iron-proxy)
+- Docker backend internals: [Docker](https://hermes-agent.nousresearch.com/docs/user-guide/docker)
+- Bitwarden Secrets Manager integration: [`hermes secrets bitwarden`](https://hermes-agent.nousresearch.com/docs/user-guide/secrets/bitwarden)
+- CLI command reference: [`hermes egress`](https://hermes-agent.nousresearch.com/docs/reference/cli-commands#hermes-egress)
+- Sandbox-injected environment variables: [Egress proxy (sandbox-injected)](https://hermes-agent.nousresearch.com/docs/reference/environment-variables#egress-proxy-sandbox-injected)
diff --git a/website/docs/developer-guide/programmatic-integration.md b/website/docs/developer-guide/programmatic-integration.md
index 39a3bae2ff4..0feeb3b508e 100644
--- a/website/docs/developer-guide/programmatic-integration.md
+++ b/website/docs/developer-guide/programmatic-integration.md
@@ -95,11 +95,36 @@ POST /v1/runs/{id}/approval      Resolve a pending approval
 POST /v1/runs/{id}/stop          Interrupt the run
 GET  /v1/capabilities            Machine-readable feature flags
 GET  /v1/models                  Lists hermes-agent
+GET  /api/model/options          Provider-aware picker inventory
 GET  /health, /health/detailed
 ```
 
 Setup, headers (`X-Hermes-Session-Id`, `X-Hermes-Session-Key`), and frontend wiring: [API Server](../user-guide/features/api-server).
 
+### Model catalog surfaces
+
+The OpenAI-compatible API intentionally keeps `GET /v1/models` minimal: it is
+the compatibility endpoint frontends expect, not the full Hermes provider/model
+picker catalog.
+
+If an external control plane needs Hermes' curated provider rows, per-model
+pricing, or capability hints, use one of the authenticated picker surfaces:
+
+- API server REST: `GET /api/model/options` with the API-server bearer key
+- Dashboard backend REST: `GET /api/model/options` with `X-Hermes-Session-Token`
+- TUI gateway RPC: `model.options`
+
+Those surfaces share the same payload builder and the same custom-provider
+probe policy:
+
+- Normal open: probe only the current custom provider so offline saved
+  endpoints do not stall the picker.
+- Explicit refresh (`refresh=1` or `refresh: true`): bust the provider-model
+  cache and probe all saved custom providers so live catalogs repopulate fully.
+
+Use `/v1/models` for OpenAI-client compatibility. Use `/api/model/options` or
+`model.options` when you are building a Hermes-aware model picker.
+
 ---
 
 ## Which one should I use?
diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md
index 2b390b3edef..9898f01f60a 100644
--- a/website/docs/getting-started/quickstart.md
+++ b/website/docs/getting-started/quickstart.md
@@ -274,6 +274,8 @@ hermes config set terminal.backend docker    # Docker isolation
 hermes config set terminal.backend ssh       # Remote server
 ```
 
+For Docker sandboxes, you can also enable the **egress credential-injection proxy** so the sandbox never sees your real API keys — only opaque proxy tokens that work exclusively from behind a local TLS-intercepting daemon. See [Egress proxy](../user-guide/egress/iron-proxy.md). Setup is `hermes egress setup && hermes egress start`; `hermes setup terminal` also points Docker users at it. Modal, SSH, Daytona, and Singularity are not wired yet.
+
 ### Voice mode
 
 ```bash
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 228e0c3f4ea..cdf16ad1c24 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -43,6 +43,7 @@ hermes [global-options] <command> [subcommand/options]
 | `hermes fallback` | Manage fallback providers tried when the primary model errors. |
 | `hermes gateway` | Run or manage the messaging gateway service. |
 | `hermes proxy` | Local OpenAI-compatible proxy that attaches OAuth provider credentials. See [Subscription Proxy](../user-guide/features/subscription-proxy.md). |
+| `hermes egress` | Outbound credential-injection firewall for remote terminal sandboxes (iron-proxy). Disabled by default. See [Egress proxy](../user-guide/egress/iron-proxy.md). |
 | `hermes lsp` | Manage Language Server Protocol integration (semantic diagnostics for write_file/patch). |
 | `hermes setup` | Interactive setup wizard for all or part of the configuration. |
 | `hermes whatsapp` | Configure and pair the WhatsApp bridge. |
@@ -631,6 +632,67 @@ All actions are also available as a slash command in the gateway (`/kanban …`)
 
 For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see `docs/hermes-kanban-v1-spec.pdf` in the repository or the [Kanban user guide](/user-guide/features/kanban).
 
+## `hermes egress`
+
+Outbound credential-injection firewall for remote terminal sandboxes. Wraps the [iron-proxy](https://github.com/ironsh/iron-proxy) daemon — a TLS-intercepting proxy that swaps opaque proxy tokens for real upstream API credentials at the network boundary, so sandboxes never hold real keys. Disabled by default; see the full [Egress proxy](../user-guide/egress/iron-proxy.md) page for setup + architecture.
+
+```bash
+hermes egress install                  # download the pinned iron-proxy binary
+hermes egress install --force          # re-download even if already installed
+
+hermes egress setup                    # interactive wizard: CA, mappings, config
+hermes egress setup --tunnel-port N    # override the tunnel listener port (default 9090)
+hermes egress setup --from-bitwarden   # use Bitwarden Secrets Manager as credential source
+hermes egress setup --no-bitwarden     # explicitly switch back to env-based credentials
+hermes egress setup --rotate-tokens    # mint fresh proxy tokens (default preserves existing)
+
+hermes egress start                    # spawn the managed proxy daemon
+hermes egress stop                     # SIGTERM (then SIGKILL after 5s grace)
+hermes egress restart                  # stop (if running) then start — needed for secret changes
+hermes egress reload                   # hot-reload the ruleset in-place (no restart, no dropped
+                                       #   connections) via the loopback management API
+
+hermes egress status                   # binary + config + pid + listening + mappings
+hermes egress status --show-tokens     # print proxy tokens in full (default: redacted)
+
+hermes egress disable                  # flip proxy.enabled = false (does not stop a running proxy)
+hermes egress config                   # print the path to proxy.yaml for inspection
+```
+
+### Common flows
+
+```bash
+# First-time setup
+export OPENROUTER_API_KEY=…
+hermes egress setup && hermes egress start
+hermes config set terminal.backend docker   # if not already
+
+# Switching credential source after the fact
+hermes egress setup --from-bitwarden       # env → bitwarden
+hermes egress setup --no-bitwarden         # bitwarden → env
+# (just `setup` without either flag preserves the existing mode)
+
+# Rotating all tokens (e.g. after a suspected token leak)
+hermes egress setup --rotate-tokens    # setup offers to restart the running daemon for you
+# (running sandboxes still hold old tokens; restart them too)
+
+# Adding a new upstream
+# Edit ~/.hermes/config.yaml proxy.extra_allowed_hosts: [api.example.com]
+hermes egress setup
+hermes egress restart                  # one-command apply (stop + start)
+```
+
+### Diagnostic shortcuts
+
+```bash
+hermes egress status                     # current state in one view
+cat ~/.hermes/proxy/proxy.yaml           # the rendered iron-proxy config
+tail -20 ~/.hermes/proxy/iron-proxy.log  # daemon-level diagnostics
+tail -f ~/.hermes/proxy/iron-proxy.log | jq  # daemon + per-request log (line-delimited JSON; v0.39 combines both streams)
+```
+
+Common failure modes + recovery are covered in [Egress proxy → Troubleshooting](../user-guide/egress/iron-proxy.md#troubleshooting).
+
 ## `hermes project`
 
 ```bash
diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md
index dfd122d6890..9473ac605c4 100644
--- a/website/docs/reference/environment-variables.md
+++ b/website/docs/reference/environment-variables.md
@@ -251,6 +251,23 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
 | `TERMINAL_LOCAL_PERSISTENT` | Enable persistent shell for local backend (default: `false`) |
 | `TERMINAL_SSH_PERSISTENT` | Override persistent shell for SSH backend (default: follows `TERMINAL_PERSISTENT_SHELL`) |
 
+## Egress proxy (sandbox-injected)
+
+These env vars are NOT set on the host — they're injected into Docker sandboxes by the [Egress proxy](../user-guide/egress/iron-proxy.md) integration when `proxy.enabled: true`. Docker is the only wired backend in this release.
+
+| Variable | Description |
+|----------|-------------|
+| `HERMES_EGRESS_PROXY` | Set to `1` inside a sandbox when the egress proxy is active. Agent code can check this to know it's running behind a TLS-intercepting proxy. |
+| Provider env vars (`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, …) | Set to opaque proxy tokens, not real upstream secrets, so existing SDKs keep reading the standard env names. iron-proxy swaps those tokens for the real upstream secret at the network boundary. |
+| `HERMES_PROXY_TOKEN_<ENV_NAME>` | Diagnostic alias for each minted provider mapping. E.g. `HERMES_PROXY_TOKEN_OPENROUTER_API_KEY=hermes-proxy-openrouter-…`. Same token value as the standard provider env var. |
+| `HTTPS_PROXY` / `HTTP_PROXY` | `HTTPS_PROXY` points at `http://host.docker.internal:<tunnel_port>` for CONNECT/MITM. `HTTP_PROXY` points at `<tunnel_port + 1>` for plain-HTTP forwarding. |
+| `NO_PROXY` | `127.0.0.1,localhost,::1` so loopback dev servers inside the sandbox bypass the proxy. |
+| `REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE` / `CURL_CA_BUNDLE` / `NODE_EXTRA_CA_CERTS` | Path to the mounted Hermes egress CA cert inside the sandbox (`/etc/ssl/certs/hermes-egress-ca.crt`). Lets the language runtimes trust iron-proxy's MITM-minted leaf certs. |
+| `NODE_OPTIONS` | Appended with `--use-openssl-ca` (your existing flags are preserved) so Node.js routes through the OpenSSL store the other CA-bundle vars control. Narrows the [Node.js asymmetric CA caveat](../user-guide/egress/iron-proxy.md#nodejs-asymmetric-ca-caveat). |
+| `HERMES_IRON_PROXY_NONCE` | Set on the iron-proxy daemon process itself (NOT inside the sandbox). Used by `_pid_alive` to confirm a candidate PID still refers to *our* managed binary across PID recycling. |
+
+These are set automatically by the Docker terminal backend when `proxy.enabled: true` AND the daemon is running. You don't set them yourself; the relevant operator-facing knobs are in `~/.hermes/config.yaml` under the `proxy:` section — see [Egress proxy → Configuration](../user-guide/egress/iron-proxy.md#configuration).
+
 ## Messaging
 
 | Variable | Description |
@@ -731,6 +748,7 @@ Advanced per-platform knobs for throttling the outbound message batcher. Most us
 | `HERMES_QUIET` | Suppress non-essential output (`true`/`false`) |
 | `CODEX_HOME` | When [Codex app-server runtime](../user-guide/features/codex-app-server-runtime) is enabled, override the directory Codex CLI reads its config + auth from (default: `~/.codex`). Hermes' migration writes the managed block to `<CODEX_HOME>/config.toml`. |
 | `HERMES_KANBAN_TASK` | Set by the kanban dispatcher when spawning a worker (task UUID). Workers and the spawned `hermes-tools` MCP subprocess inherit it so kanban tools gate correctly. Don't set manually. |
+| `HERMES_ACP_SKIP_CONFIGURED_MCP` | Set by an [ACP host](../user-guide/features/acp#host-integration) on the Hermes subprocess it spawns. `1` skips starting the globally configured `config.yaml` MCP servers before the ACP JSON-RPC loop, for hosts that pass the session's MCP servers through `session/new` themselves. Servers supplied by the ACP session are still registered; any other value keeps the default. Don't set manually. |
 | `HERMES_API_TIMEOUT` | LLM API call timeout in seconds (default: `1800`) |
 | `HERMES_API_CALL_STALE_TIMEOUT` | Non-streaming stale-call timeout in seconds (default: `90`). Auto-disabled for local providers when left unset, and may scale upward for very large contexts. Also configurable via `providers.<id>.stale_timeout_seconds` or `providers.<id>.models.<model>.stale_timeout_seconds` in `config.yaml`. |
 | `HERMES_STREAM_READ_TIMEOUT` | Streaming socket read timeout in seconds (default: `120`). Auto-increased to `HERMES_API_TIMEOUT` for local providers. Increase if local LLMs time out during long code generation. |
diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.md
index a244a4eb881..6a826ec62e2 100644
--- a/website/docs/reference/optional-skills-catalog.md
+++ b/website/docs/reference/optional-skills-catalog.md
@@ -32,9 +32,9 @@ hermes skills uninstall <skill-name>
 | Skill | Description |
 |-------|-------------|
 | [**antigravity-cli**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli) | Operate the Antigravity CLI (agy): plugins, auth, sandbox. |
-| [**blackbox**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox) | Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key. |
+| [**blackbox**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox) | Delegate coding tasks to the Blackbox AI multi-model CLI. |
 | [**grok**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok) | Delegate coding to xAI Grok Build CLI (features, PRs). |
-| [**honcho**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho) | Configure and use Honcho memory with Hermes -- cross-session user modeling, multi-profile peer isolation, observation config, dialectic reasoning, session summaries, and context budget enforcement. Use when setting up Honcho, troubleshoo... |
+| [**honcho**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho) | Configure and troubleshoot Honcho memory for Hermes. |
 | [**openhands**](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands) | Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). |
 
 ## blockchain
@@ -43,7 +43,7 @@ hermes skills uninstall <skill-name>
 |-------|-------------|
 | [**evm**](/docs/user-guide/skills/optional/blockchain/blockchain-evm) | Read-only EVM client: wallets, tokens, gas across 8 chains. |
 | [**hyperliquid**](/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid) | Hyperliquid market data, account history, trade review. |
-| [**solana**](/docs/user-guide/skills/optional/blockchain/blockchain-solana) | Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network stats. Uses Solana RPC + CoinGecko. No API key required. |
+| [**solana**](/docs/user-guide/skills/optional/blockchain/blockchain-solana) | Query Solana wallets, tokens, txs, and NFTs in USD. |
 
 ## communication
 
@@ -55,24 +55,33 @@ hermes skills uninstall <skill-name>
 
 | Skill | Description |
 |-------|-------------|
+| [**audiocraft-audio-generation**](/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation) | AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. |
 | [**baoyu-article-illustrator**](/docs/user-guide/skills/optional/creative/creative-baoyu-article-illustrator) | Article illustrations: type × style × palette consistency. |
 | [**baoyu-comic**](/docs/user-guide/skills/optional/creative/creative-baoyu-comic) | Knowledge comics (知识漫画): educational, biography, tutorial. |
 | [**blender-mcp**](/docs/user-guide/skills/optional/creative/creative-blender-mcp) | Drive Blender via the catalog blender MCP, with bpy recipes. |
-| [**concept-diagrams**](/docs/user-guide/skills/optional/creative/creative-concept-diagrams) | Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and no... |
+| [**concept-diagrams**](/docs/user-guide/skills/optional/creative/creative-concept-diagrams) | Generate flat, minimal educational SVG visuals as HTML. |
 | [**creative-ideation**](/docs/user-guide/skills/optional/creative/creative-creative-ideation) | Generate ideas via named methods from creative practice. |
-| [**hyperframes**](/docs/user-guide/skills/optional/creative/creative-hyperframes) | Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions using HyperFrames. HTML is the source of truth for video. Use when the user wants... |
-| [**kanban-video-orchestrator**](/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator) | Plan, set up, and monitor a multi-agent video production pipeline backed by Hermes Kanban. Use when the user wants to make ANY video — narrative film, product/marketing, music video, explainer, ASCII/terminal art, abstract/generative loo... |
-| [**meme-generation**](/docs/user-guide/skills/optional/creative/creative-meme-generation) | Generate real meme images by picking a template and overlaying text with Pillow. Produces actual .png meme files. |
+| [**heartmula**](/docs/user-guide/skills/optional/creative/creative-heartmula) | HeartMuLa: Suno-like song generation from lyrics + tags. |
+| [**hyperframes**](/docs/user-guide/skills/optional/creative/creative-hyperframes) | Render MP4/WebM videos from HTML compositions. |
+| [**kanban-video-orchestrator**](/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator) | Plan and run multi-agent video production pipelines. |
+| [**meme-generation**](/docs/user-guide/skills/optional/creative/creative-meme-generation) | Create meme PNGs from templates with Pillow text overlay. |
 | [**pixel-art**](/docs/user-guide/skills/optional/creative/creative-pixel-art) | Pixel art w/ era palettes (NES, Game Boy, PICO-8). |
-| [**unreal-mcp**](/docs/user-guide/skills/optional/creative/creative-unreal-mcp) | Use when the user wants to do anything in Unreal Engine through Epic's official editor-embedded MCP server (catalog entry: unreal-engine) — build/light/populate scenes, place and transform actors, author Blueprints, animate with Sequence... |
+| [**tldraw-offline**](/docs/user-guide/skills/optional/creative/creative-tldraw-offline) | Drive and script tldraw offline canvases with an agent. |
+| [**unreal-mcp**](/docs/user-guide/skills/optional/creative/creative-unreal-mcp) | Automate Unreal Engine editor scenes, actors, and renders. |
+
+## data-science
+
+| Skill | Description |
+|-------|-------------|
+| [**jupyter-notebook**](/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook) | Iterative Python via live Jupyter kernel (hamelnb). |
 
 ## devops
 
 | Skill | Description |
 |-------|-------------|
-| [**inference-sh-cli**](/docs/user-guide/skills/optional/devops/devops-cli) | Run 150+ AI apps via inference.sh CLI (infsh) — image generation, video creation, LLMs, search, 3D, social automation. Uses the terminal tool. Triggers: inference.sh, infsh, ai apps, flux, veo, image generation, video generation, seedrea... |
-| [**docker-management**](/docs/user-guide/skills/optional/devops/devops-docker-management) | Manage Docker containers, images, volumes, networks, and Compose stacks — lifecycle ops, debugging, cleanup, and Dockerfile optimization. |
-| [**hermes-s6-container-supervision**](/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision) | Modify, debug, or extend the s6-overlay supervision tree inside the Hermes Agent Docker image — adding new services, debugging profile gateways, understanding the Architecture B main-program pattern. |
+| [**inference-sh-cli**](/docs/user-guide/skills/optional/devops/devops-cli) | Run 150+ AI apps (image, video, LLM) via inference.sh CLI. |
+| [**docker-management**](/docs/user-guide/skills/optional/devops/devops-docker-management) | Manage Docker containers, images, volumes, and Compose. |
+| [**hermes-s6-container-supervision**](/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision) | Modify or debug s6 services in the Hermes Docker image. |
 | [**pinggy-tunnel**](/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel) | Zero-install localhost tunnels over SSH via Pinggy. |
 | [**watchers**](/docs/user-guide/skills/optional/devops/devops-watchers) | Poll RSS, JSON APIs, and GitHub with watermark dedup. |
 
@@ -80,25 +89,25 @@ hermes skills uninstall <skill-name>
 
 | Skill | Description |
 |-------|-------------|
-| [**adversarial-ux-test**](/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test) | Roleplay the most difficult, tech-resistant user for your product. Browse the app as that persona, find every UX pain point, then filter complaints through a pragmatism layer to separate real problems from noise. Creates actionable ticke... |
+| [**adversarial-ux-test**](/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test) | Roleplay a hostile user to find and triage UX pain points. |
 
 ## email
 
 | Skill | Description |
 |-------|-------------|
-| [**agentmail**](/docs/user-guide/skills/optional/email/email-agentmail) | Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to). |
+| [**agentmail**](/docs/user-guide/skills/optional/email/email-agentmail) | Give the agent its own inbox: send and receive email. |
 
 ## finance
 
 | Skill | Description |
 |-------|-------------|
-| [**3-statement-model**](/docs/user-guide/skills/optional/finance/finance-3-statement-model) | Build fully-integrated 3-statement models (IS, BS, CF) in Excel with working capital schedules, D&A roll-forwards, debt schedule, and the plugs that make cash and retained earnings tie. Pairs with excel-author. |
-| [**comps-analysis**](/docs/user-guide/skills/optional/finance/finance-comps-analysis) | Build comparable company analysis in Excel — operating metrics, valuation multiples, statistical benchmarking vs peer sets. Pairs with excel-author. Use for public-company valuation, IPO pricing, sector benchmarking, or outlier detection. |
-| [**dcf-model**](/docs/user-guide/skills/optional/finance/finance-dcf-model) | Build institutional-quality DCF valuation models in Excel — revenue projections, FCF build, WACC, terminal value, Bear/Base/Bull scenarios, 5x5 sensitivity tables. Pairs with excel-author. Use for intrinsic-value equity analysis. |
-| [**excel-author**](/docs/user-guide/skills/optional/finance/finance-excel-author) | Build auditable Excel workbooks headless with openpyxl — blue/black/green cell conventions, formulas over hardcodes, named ranges, balance checks, sensitivity tables. Use for financial models, audit outputs, reconciliations. |
-| [**lbo-model**](/docs/user-guide/skills/optional/finance/finance-lbo-model) | Build leveraged buyout models in Excel — sources & uses, debt schedule, cash sweep, exit multiple, IRR/MOIC sensitivity. Pairs with excel-author. Use for PE screening, sponsor-case valuation, or illustrative LBO in a pitch. |
-| [**merger-model**](/docs/user-guide/skills/optional/finance/finance-merger-model) | Build accretion/dilution (merger) models in Excel — pro-forma P&L, synergies, financing mix, EPS impact. Pairs with excel-author. Use for M&A pitches, board materials, or deal evaluation. |
-| [**pptx-author**](/docs/user-guide/skills/optional/finance/finance-pptx-author) | Build PowerPoint decks headless with python-pptx. Pairs with excel-author for model-backed decks where every number traces to a workbook cell. Use for pitch decks, IC memos, earnings notes. |
+| [**3-statement-model**](/docs/user-guide/skills/optional/finance/finance-3-statement-model) | Build integrated IS/BS/CF financial workbooks in Excel. |
+| [**comps-analysis**](/docs/user-guide/skills/optional/finance/finance-comps-analysis) | Build comparable-company valuation workbooks in Excel. |
+| [**dcf-model**](/docs/user-guide/skills/optional/finance/finance-dcf-model) | Build discounted cash flow valuation workbooks in Excel. |
+| [**excel-author**](/docs/user-guide/skills/optional/finance/finance-excel-author) | Build auditable financial workbooks headless via openpyxl. |
+| [**lbo-model**](/docs/user-guide/skills/optional/finance/finance-lbo-model) | Build leveraged buyout workbooks with IRR/MOIC in Excel. |
+| [**merger-model**](/docs/user-guide/skills/optional/finance/finance-merger-model) | Build M&A accretion/dilution workbooks in Excel. |
+| [**pptx-author**](/docs/user-guide/skills/optional/finance/finance-pptx-author) | Build PowerPoint decks headless with python-pptx. |
 | [**stocks**](/docs/user-guide/skills/optional/finance/finance-stocks) | Stock quotes, history, search, compare, crypto via Yahoo. |
 
 ## gaming
@@ -119,50 +128,51 @@ hermes skills uninstall <skill-name>
 
 | Skill | Description |
 |-------|-------------|
-| [**fastmcp**](/docs/user-guide/skills/optional/mcp/mcp-fastmcp) | Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Use when creating a new MCP server, wrapping an API or database as MCP tools, exposing resources or prompts, or preparing a FastMCP server for Claude Code, Cur... |
+| [**fastmcp**](/docs/user-guide/skills/optional/mcp/mcp-fastmcp) | Build, test, and deploy Python MCP servers. |
 | [**mcp-oauth-remote-gateway**](/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway) | Manual OAuth for remote MCP servers on headless gateways. |
-| [**mcporter**](/docs/user-guide/skills/optional/mcp/mcp-mcporter) | Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation. |
+| [**mcporter**](/docs/user-guide/skills/optional/mcp/mcp-mcporter) | List, auth, and call MCP servers/tools from the terminal. |
 
 ## migration
 
 | Skill | Description |
 |-------|-------------|
-| [**openclaw-migration**](/docs/user-guide/skills/optional/migration/migration-openclaw-migration) | Migrate a user's OpenClaw customization footprint into Hermes Agent. Imports Hermes-compatible memories, SOUL.md, command allowlists, user skills, and selected workspace assets from ~/.openclaw, then reports exactly what could not be mig... |
+| [**openclaw-migration**](/docs/user-guide/skills/optional/migration/migration-openclaw-migration) | Import an OpenClaw setup (memories, skills) into Hermes. |
 
 ## mlops
 
 | Skill | Description |
 |-------|-------------|
-| [**huggingface-accelerate**](/docs/user-guide/skills/optional/mlops/mlops-accelerate) | Simplest distributed training API. 4 lines to add distributed support to any PyTorch script. Unified API for DeepSpeed/FSDP/Megatron/DDP. Automatic device placement, mixed precision (FP16/BF16/FP8). Interactive config, single launch comm... |
+| [**huggingface-accelerate**](/docs/user-guide/skills/optional/mlops/mlops-accelerate) | Run PyTorch training across GPUs with minimal changes. |
 | [**axolotl**](/docs/user-guide/skills/optional/mlops/mlops-training-axolotl) | Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO). |
-| [**chroma**](/docs/user-guide/skills/optional/mlops/mlops-chroma) | Open-source embedding database for AI applications. Store embeddings and metadata, perform vector and full-text search, filter by metadata. Simple 4-function API. Scales from notebooks to production clusters. Use for semantic search, RAG... |
-| [**clip**](/docs/user-guide/skills/optional/mlops/mlops-clip) | OpenAI's model connecting vision and language. Enables zero-shot image classification, image-text matching, and cross-modal retrieval. Trained on 400M image-text pairs. Use for image search, content moderation, or vision-language tasks w... |
+| [**chroma**](/docs/user-guide/skills/optional/mlops/mlops-chroma) | Embedding database for RAG and semantic search. |
+| [**clip**](/docs/user-guide/skills/optional/mlops/mlops-clip) | Zero-shot image classification and image-text search. |
 | [**dspy**](/docs/user-guide/skills/optional/mlops/mlops-research-dspy) | DSPy: declarative LM programs, auto-optimize prompts, RAG. |
-| [**faiss**](/docs/user-guide/skills/optional/mlops/mlops-faiss) | Facebook's library for efficient similarity search and clustering of dense vectors. Supports billions of vectors, GPU acceleration, and various index types (Flat, IVF, HNSW). Use for fast k-NN search, large-scale vector retrieval, or whe... |
-| [**optimizing-attention-flash**](/docs/user-guide/skills/optional/mlops/mlops-flash-attention) | Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. Use when training/running transformers with long sequences (>512 tokens), encountering GPU memory issues with attention, or need faster in... |
-| [**guidance**](/docs/user-guide/skills/optional/mlops/mlops-guidance) | Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidance - Microsoft Research's constrained generation framework |
-| [**huggingface-tokenizers**](/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) | Fast tokenizers optimized for research and production. Rust-based implementation tokenizes 1GB in &lt;20 seconds. Supports BPE, WordPiece, and Unigram algorithms. Train custom vocabularies, track alignments, handle padding/truncation. Integ... |
-| [**instructor**](/docs/user-guide/skills/optional/mlops/mlops-instructor) | Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream partial results with Instructor - battle-tested structured output library |
-| [**lambda-labs-gpu-cloud**](/docs/user-guide/skills/optional/mlops/mlops-lambda-labs) | Reserved and on-demand GPU cloud instances for ML training and inference. Use when you need dedicated GPU instances with simple SSH access, persistent filesystems, or high-performance multi-node clusters for large-scale training. |
-| [**llava**](/docs/user-guide/skills/optional/mlops/mlops-llava) | Large Language and Vision Assistant. Enables visual instruction tuning and image-based conversations. Combines CLIP vision encoder with Vicuna/LLaMA language models. Supports multi-turn image chat, visual question answering, and instruct... |
-| [**modal-serverless-gpu**](/docs/user-guide/skills/optional/mlops/mlops-modal) | Serverless GPU cloud platform for running ML workloads. Use when you need on-demand GPU access without infrastructure management, deploying ML models as APIs, or running batch jobs with automatic scaling. |
-| [**nemo-curator**](/docs/user-guide/skills/optional/mlops/mlops-nemo-curator) | GPU-accelerated data curation for LLM training. Supports text/image/video/audio. Features fuzzy deduplication (16× faster), quality filtering (30+ heuristics), semantic deduplication, PII redaction, NSFW detection. Scales across GPUs wit... |
+| [**faiss**](/docs/user-guide/skills/optional/mlops/mlops-faiss) | Fast vector similarity search at billion scale. |
+| [**optimizing-attention-flash**](/docs/user-guide/skills/optional/mlops/mlops-flash-attention) | Speed up long-sequence transformer training and inference. |
+| [**guidance**](/docs/user-guide/skills/optional/mlops/mlops-guidance) | Constrain LLM output with grammars; guarantee valid JSON. |
+| [**huggingface-tokenizers**](/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) | Fast BPE/WordPiece tokenization and custom vocab training. |
+| [**instructor**](/docs/user-guide/skills/optional/mlops/mlops-instructor) | Structured LLM outputs validated with Pydantic. |
+| [**lambda-labs-gpu-cloud**](/docs/user-guide/skills/optional/mlops/mlops-lambda-labs) | On-demand GPU cloud instances for ML training. |
+| [**llava**](/docs/user-guide/skills/optional/mlops/mlops-llava) | Vision-language chat: VQA, captioning, image dialogue. |
+| [**modal-serverless-gpu**](/docs/user-guide/skills/optional/mlops/mlops-modal) | Serverless GPU cloud for ML jobs and model APIs. |
+| [**nemo-curator**](/docs/user-guide/skills/optional/mlops/mlops-nemo-curator) | Curate LLM training data: dedupe, filter, PII redaction. |
 | [**obliteratus**](/docs/user-guide/skills/optional/mlops/mlops-obliteratus) | OBLITERATUS: abliterate LLM refusals (diff-in-means). |
 | [**outlines**](/docs/user-guide/skills/optional/mlops/mlops-inference-outlines) | Outlines: structured JSON/regex/Pydantic LLM generation. |
-| [**peft-fine-tuning**](/docs/user-guide/skills/optional/mlops/mlops-peft) | Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods. Use when fine-tuning large models (7B-70B) with limited GPU memory, when you need to train &lt;1% of parameters with minimal accuracy loss, or for multi-adapter se... |
+| [**peft-fine-tuning**](/docs/user-guide/skills/optional/mlops/mlops-peft) | Fine-tune large LLMs with LoRA on limited GPU memory. |
 | [**pinecone**](/docs/user-guide/skills/optional/mlops/mlops-pinecone) | Managed vector database for production AI applications. Fully managed, auto-scaling, with hybrid search (dense + sparse), metadata filtering, and namespaces. Low latency (&lt;100ms p95). Use for production RAG, recommendation systems, or se... |
-| [**pytorch-fsdp**](/docs/user-guide/skills/optional/mlops/mlops-pytorch-fsdp) | Expert guidance for Fully Sharded Data Parallel training with PyTorch FSDP - parameter sharding, mixed precision, CPU offloading, FSDP2 |
-| [**pytorch-lightning**](/docs/user-guide/skills/optional/mlops/mlops-pytorch-lightning) | High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate. Scales from laptop to supercomputer with same code. Use when you want clean training loops w... |
-| [**qdrant-vector-search**](/docs/user-guide/skills/optional/mlops/mlops-qdrant) | High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered per... |
-| [**sparse-autoencoder-training**](/docs/user-guide/skills/optional/mlops/mlops-saelens) | Provides guidance for training and analyzing Sparse Autoencoders (SAEs) using SAELens to decompose neural network activations into interpretable features. Use when discovering interpretable features, analyzing superposition, or studying... |
-| [**simpo-training**](/docs/user-guide/skills/optional/mlops/mlops-simpo) | Simple Preference Optimization for LLM alignment. Reference-free alternative to DPO with better performance (+6.4 points on AlpacaEval 2.0). No reference model needed, more efficient than DPO. Use for preference alignment when want simpl... |
-| [**slime-rl-training**](/docs/user-guide/skills/optional/mlops/mlops-slime) | Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework. Use when training GLM models, implementing custom data generation workflows, or needing tight Megatron-LM integration for RL scaling. |
-| [**stable-diffusion-image-generation**](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion) | State-of-the-art text-to-image generation with Stable Diffusion models via HuggingFace Diffusers. Use when generating images from text prompts, performing image-to-image translation, inpainting, or building custom diffusion pipelines. |
-| [**tensorrt-llm**](/docs/user-guide/skills/optional/mlops/mlops-tensorrt-llm) | Optimizes LLM inference with NVIDIA TensorRT for maximum throughput and lowest latency. Use for production deployment on NVIDIA GPUs (A100/H100), when you need 10-100x faster inference than PyTorch, or for serving models with quantizatio... |
-| [**distributed-llm-pretraining-torchtitan**](/docs/user-guide/skills/optional/mlops/mlops-torchtitan) | Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP). Use when pretraining Llama 3.1, DeepSeek V3, or custom models at scale from 8 to 512+ GPUs with Float8, torch.compile, and dist... |
+| [**pytorch-fsdp**](/docs/user-guide/skills/optional/mlops/mlops-pytorch-fsdp) | Fully sharded data-parallel training for large models. |
+| [**pytorch-lightning**](/docs/user-guide/skills/optional/mlops/mlops-pytorch-lightning) | Clean training loops with built-in distributed support. |
+| [**qdrant-vector-search**](/docs/user-guide/skills/optional/mlops/mlops-qdrant) | Vector search engine for production RAG systems. |
+| [**sparse-autoencoder-training**](/docs/user-guide/skills/optional/mlops/mlops-saelens) | Train sparse autoencoders to interpret model features. |
+| [**segment-anything-model**](/docs/user-guide/skills/optional/mlops/mlops-models-segment-anything-model) | SAM: zero-shot image segmentation via points, boxes, masks. |
+| [**simpo-training**](/docs/user-guide/skills/optional/mlops/mlops-simpo) | Reference-free preference alignment, simpler than DPO. |
+| [**slime-rl-training**](/docs/user-guide/skills/optional/mlops/mlops-slime) | RL post-training for LLMs with Megatron and SGLang. |
+| [**stable-diffusion-image-generation**](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion) | Text-to-image generation, inpainting, and img2img. |
+| [**tensorrt-llm**](/docs/user-guide/skills/optional/mlops/mlops-tensorrt-llm) | High-throughput LLM inference on NVIDIA GPUs. |
+| [**distributed-llm-pretraining-torchtitan**](/docs/user-guide/skills/optional/mlops/mlops-torchtitan) | Pretrain LLMs at scale with PyTorch 4D parallelism. |
 | [**fine-tuning-with-trl**](/docs/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning) | TRL: SFT, DPO, PPO, GRPO, reward modeling for LLM RLHF. |
 | [**unsloth**](/docs/user-guide/skills/optional/mlops/mlops-training-unsloth) | Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM. |
-| [**whisper**](/docs/user-guide/skills/optional/mlops/mlops-whisper) | OpenAI's general-purpose speech recognition model. Supports 99 languages, transcription, translation to English, and language identification. Six model sizes from tiny (39M params) to large (1550M params). Use for speech-to-text, podcast... |
+| [**whisper**](/docs/user-guide/skills/optional/mlops/mlops-whisper) | Transcribe and translate speech in 99 languages. |
 
 ## payments
 
@@ -176,38 +186,38 @@ hermes skills uninstall <skill-name>
 
 | Skill | Description |
 |-------|-------------|
-| [**canvas**](/docs/user-guide/skills/optional/productivity/productivity-canvas) | Canvas LMS integration — fetch enrolled courses and assignments using API token authentication. |
-| [**here.now**](/docs/user-guide/skills/optional/productivity/productivity-here-now) | Publish static sites to &#123;slug&#125;.here.now and store private files in cloud Drives for agent-to-agent handoff. |
+| [**canvas**](/docs/user-guide/skills/optional/productivity/productivity-canvas) | Fetch Canvas LMS courses and assignments via API token. |
+| [**here.now**](/docs/user-guide/skills/optional/productivity/productivity-here-now) | Publish sites to &#123;slug&#125;.here.now and store files in Drives. |
 | [**memento-flashcards**](/docs/user-guide/skills/optional/productivity/productivity-memento-flashcards) | Spaced-repetition flashcard system. Create cards from facts or text, chat with flashcards using free-text answers graded by the agent, generate quizzes from YouTube transcripts, review due cards with adaptive scheduling, and export/impor... |
 | [**shop**](/docs/user-guide/skills/optional/productivity/productivity-shop) | Shop catalog search, checkout, order tracking, returns. |
-| [**shopify**](/docs/user-guide/skills/optional/productivity/productivity-shopify) | Shopify Admin & Storefront GraphQL APIs via curl. Products, orders, customers, inventory, metafields. |
-| [**siyuan**](/docs/user-guide/skills/optional/productivity/productivity-siyuan) | SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl. |
-| [**telephony**](/docs/user-guide/skills/optional/productivity/productivity-telephony) | Give Hermes phone capabilities without core tool changes. Provision and persist a Twilio number, send and receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi. |
+| [**shopify**](/docs/user-guide/skills/optional/productivity/productivity-shopify) | Query Shopify Admin/Storefront GraphQL APIs via curl. |
+| [**siyuan**](/docs/user-guide/skills/optional/productivity/productivity-siyuan) | Query and edit a SiYuan knowledge base via its API. |
+| [**telephony**](/docs/user-guide/skills/optional/productivity/productivity-telephony) | Provision Twilio numbers, SMS/MMS, and AI outbound calls. |
 
 ## research
 
 | Skill | Description |
 |-------|-------------|
-| [**bioinformatics**](/docs/user-guide/skills/optional/research/research-bioinformatics) | Gateway to 400+ bioinformatics skills from bioSkills and ClawBio. Covers genomics, transcriptomics, single-cell, variant calling, pharmacogenomics, metagenomics, structural biology, and more. Fetches domain-specific reference material on... |
+| [**bioinformatics**](/docs/user-guide/skills/optional/research/research-bioinformatics) | Gateway to 400+ genomics and computational biology skills. |
 | [**darwinian-evolver**](/docs/user-guide/skills/optional/research/research-darwinian-evolver) | Evolve prompts/regex/SQL/code with Imbue's evolution loop. |
-| [**domain-intel**](/docs/user-guide/skills/optional/research/research-domain-intel) | Passive domain reconnaissance using Python stdlib. Subdomain discovery, SSL certificate inspection, WHOIS lookups, DNS records, domain availability checks, and bulk multi-domain analysis. No API keys required. |
+| [**domain-intel**](/docs/user-guide/skills/optional/research/research-domain-intel) | Passive recon of subdomains, SSL certs, WHOIS, and DNS. |
 | [**drug-discovery**](/docs/user-guide/skills/optional/research/research-drug-discovery) | Pharmaceutical research assistant for drug discovery workflows. Search bioactive compounds on ChEMBL, calculate drug-likeness (Lipinski Ro5, QED, TPSA, synthetic accessibility), look up drug-drug interactions via OpenFDA, interpret ADMET... |
-| [**duckduckgo-search**](/docs/user-guide/skills/optional/research/research-duckduckgo-search) | Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Prefer the `ddgs` CLI when installed; use the Python DDGS library only after verifying that `ddgs` is available in the current runtime. |
-| [**gitnexus-explorer**](/docs/user-guide/skills/optional/research/research-gitnexus-explorer) | Index a codebase with GitNexus and serve an interactive knowledge graph via web UI + Cloudflare tunnel. |
-| [**osint-investigation**](/docs/user-guide/skills/optional/research/research-osint-investigation) | Public-records OSINT investigation framework — SEC EDGAR filings, USAspending contracts, Senate lobbying, OFAC sanctions, ICIJ offshore leaks, NYC property records (ACRIS), OpenCorporates registries, CourtListener court records, Wayback... |
-| [**parallel-cli**](/docs/user-guide/skills/optional/research/research-parallel-cli) | Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring. Prefer JSON output and non-interactive flows. |
-| [**qmd**](/docs/user-guide/skills/optional/research/research-qmd) | Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration. |
-| [**scrapling**](/docs/user-guide/skills/optional/research/research-scrapling) | Web scraping with Scrapling - HTTP fetching, stealth browser automation, Cloudflare bypass, and spider crawling via CLI and Python. |
-| [**searxng-search**](/docs/user-guide/skills/optional/research/research-searxng-search) | Free meta-search via SearXNG — aggregates results from 70+ search engines. Self-hosted or use a public instance. No API key needed. Falls back automatically when the web search toolset is unavailable. |
+| [**duckduckgo-search**](/docs/user-guide/skills/optional/research/research-duckduckgo-search) | Free keyless web, news, and image search via ddgs. |
+| [**gitnexus-explorer**](/docs/user-guide/skills/optional/research/research-gitnexus-explorer) | Serve an interactive codebase knowledge graph web UI. |
+| [**osint-investigation**](/docs/user-guide/skills/optional/research/research-osint-investigation) | Follow the money via public records and sanctions data. |
+| [**parallel-cli**](/docs/user-guide/skills/optional/research/research-parallel-cli) | Agent-native web search, deep research, and enrichment. |
+| [**qmd**](/docs/user-guide/skills/optional/research/research-qmd) | Hybrid local search over notes, docs, and transcripts. |
+| [**scrapling**](/docs/user-guide/skills/optional/research/research-scrapling) | Scrape sites with stealth browsing and Cloudflare bypass. |
+| [**searxng-search**](/docs/user-guide/skills/optional/research/research-searxng-search) | Free keyless meta-search aggregating 70+ engines. |
 
 ## security
 
 | Skill | Description |
 |-------|-------------|
-| [**1password**](/docs/user-guide/skills/optional/security/security-1password) | Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in, and reading/injecting secrets for commands. |
+| [**1password**](/docs/user-guide/skills/optional/security/security-1password) | Set up op CLI, sign in, and read or inject secrets. |
 | [**godmode**](/docs/user-guide/skills/optional/security/security-godmode) | Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN. |
 | [**oss-forensics**](/docs/user-guide/skills/optional/security/security-oss-forensics) | Supply chain investigation, evidence recovery, and forensic analysis for GitHub repositories. Covers deleted commit recovery, force-push detection, IOC extraction, multi-source evidence collection, hypothesis formation/validation, and st... |
-| [**sherlock**](/docs/user-guide/skills/optional/security/security-sherlock) | OSINT username search across 400+ social networks. Hunt down social media accounts by username. |
+| [**sherlock**](/docs/user-guide/skills/optional/security/security-sherlock) | Find accounts for a username across 400+ platforms. |
 | [**unbroker**](/docs/user-guide/skills/optional/security/security-unbroker) | Autonomously remove your info from data-broker sites. |
 | [**web-pentest**](/docs/user-guide/skills/optional/security/security-web-pentest) | Authorized web application penetration testing — reconnaissance, vulnerability analysis, proof-based exploitation, and professional reporting. Adapts Shannon's "No Exploit, No Report" methodology with hard guardrails for scope, authoriza... |
 
@@ -224,7 +234,13 @@ hermes skills uninstall <skill-name>
 | Skill | Description |
 |-------|-------------|
 | [**cloudflare-temporary-deploy**](/docs/user-guide/skills/optional/web-development/web-development-cloudflare-temporary-deploy) | Deploy a Worker live, no account, via wrangler --temporary. |
-| [**page-agent**](/docs/user-guide/skills/optional/web-development/web-development-page-agent) | Embed alibaba/page-agent into your own web application — a pure-JavaScript in-page GUI agent that ships as a single &lt;script> tag or npm package and lets end-users of your site drive the UI with natural language ("click login, fill userna... |
+| [**page-agent**](/docs/user-guide/skills/optional/web-development/web-development-page-agent) | Embed an in-page natural-language GUI copilot in web apps. |
+
+## yuanbao
+
+| Skill | Description |
+|-------|-------------|
+| [**yuanbao**](/docs/user-guide/skills/optional/yuanbao/yuanbao-yuanbao) | Yuanbao (元宝) groups: @mention users, query info/members. |
 
 ---
 
diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md
index b12f63249b8..24c539f81de 100644
--- a/website/docs/reference/skills-catalog.md
+++ b/website/docs/reference/skills-catalog.md
@@ -27,15 +27,10 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 |-------|-------------|------|
 | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code) | Delegate coding to Claude Code CLI (features, PRs). | `autonomous-ai-agents/claude-code` |
 | [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex) | Delegate coding to OpenAI Codex CLI (features, PRs). | `autonomous-ai-agents/codex` |
-| [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | Configure, extend, or contribute to Hermes Agent. | `autonomous-ai-agents/hermes-agent` |
+| [`computer-use`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use) | Drive the user's desktop in the background — clicking, typing, scrolling, dragging — without stealing the cursor, keyboard focus, or switching virtual desktops / Spaces. Cross-platform: macOS, Windows, Linux. Works with any tool-capable... | `autonomous-ai-agents/computer-use` |
+| [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | Use, configure, theme, extend, and orchestrate Hermes Agent. | `autonomous-ai-agents/hermes-agent` |
 | [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) | Delegate coding to OpenCode CLI (features, PR review). | `autonomous-ai-agents/opencode` |
 
-## computer-use
-
-| Skill | Description | Path |
-|-------|-------------|------|
-| [`computer-use`](/docs/user-guide/skills/bundled/computer-use/computer-use-computer-use) | Drive the user's desktop in the background — clicking, typing, scrolling, dragging — without stealing the cursor, keyboard focus, or switching virtual desktops / Spaces. Cross-platform: macOS, Windows, Linux. Works with any tool-capable... | `computer-use` |
-
 ## creative
 
 | Skill | Description | Path |
@@ -45,29 +40,17 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video) | ASCII video: convert video/audio to colored ASCII MP4/GIF. | `creative/ascii-video` |
 | [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative/baoyu-infographic` |
 | [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design) | Design one-off HTML artifacts (landing, deck, prototype). | `creative/claude-design` |
-| [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui) | Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST/WebSocket API for execution. | `creative/comfyui` |
+| [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui) | Generate images, video, and audio via diffusion workflows. | `creative/comfyui` |
 | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md) | Author/validate/export Google's DESIGN.md token spec files. | `creative/design-md` |
 | [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). | `creative/excalidraw` |
 | [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) | Humanize text: strip AI-isms and add real voice. | `creative/humanizer` |
 | [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) | Manim CE animations: 3Blue1Brown math/algo videos. | `creative/manim-video` |
 | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) | p5.js sketches: gen art, shaders, interactive, 3D. | `creative/p5js` |
 | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs) | 54 real design systems (Stripe, Linear, Vercel) as HTML/CSS. | `creative/popular-web-designs` |
-| [`pretext`](/docs/user-guide/skills/bundled/creative/creative-pretext) | Use when building creative browser demos with @chenglou/pretext — DOM-free text layout for ASCII art, typographic flow around obstacles, text-as-geometry games, kinetic typography, and text-powered generative art. Produces single-file HT... | `creative/pretext` |
+| [`pretext`](/docs/user-guide/skills/bundled/creative/creative-pretext) | Build creative browser demos with DOM-free text layout. | `creative/pretext` |
 | [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch) | Throwaway HTML mockups: 2-3 design variants to compare. | `creative/sketch` |
 | [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | Songwriting craft and Suno AI music prompts. | `creative/songwriting-and-ai-music` |
-| [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp) | Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools. | `creative/touchdesigner-mcp` |
-
-## data-science
-
-| Skill | Description | Path |
-|-------|-------------|------|
-| [`jupyter-live-kernel`](/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel) | Iterative Python via live Jupyter kernel (hamelnb). | `data-science/jupyter-live-kernel` |
-
-## dogfood
-
-| Skill | Description | Path |
-|-------|-------------|------|
-| [`dogfood`](/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood) | Exploratory QA of web apps: find bugs, evidence, reports. | `dogfood` |
+| [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp) | Control TouchDesigner via twozero MCP. | `creative/touchdesigner-mcp` |
 
 ## email
 
@@ -86,18 +69,11 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 | [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow) | GitHub PR lifecycle: branch, commit, open, CI, merge. | `github/github-pr-workflow` |
 | [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) | Clone/create/fork repos; manage remotes, releases. | `github/github-repo-management` |
 
-## hermes-desktop-plugins
-
-| Skill | Description | Path |
-|-------|-------------|------|
-| [`hermes-desktop-plugins`](/docs/user-guide/skills/bundled/hermes-desktop-plugins/hermes-desktop-plugins-hermes-desktop-plugins) | Write desktop app plugins that add UI panes and commands. | `hermes-desktop-plugins` |
-
 ## media
 
 | Skill | Description | Path |
 |-------|-------------|------|
 | [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search) | Search/download GIFs from Tenor via curl + jq. | `media/gif-search` |
-| [`heartmula`](/docs/user-guide/skills/bundled/media/media-heartmula) | HeartMuLa: Suno-like song generation from lyrics + tags. | `media/heartmula` |
 | [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee) | Audio spectrograms/features (mel, chroma, MFCC) via CLI. | `media/songsee` |
 | [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content) | YouTube transcripts to summaries, threads, blogs. | `media/youtube-content` |
 
@@ -105,12 +81,10 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`audiocraft-audio-generation`](/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft) | AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. | `mlops/models/audiocraft` |
 | [`huggingface-hub`](/docs/user-guide/skills/bundled/mlops/mlops-huggingface-hub) | HuggingFace hf CLI: search/download/upload models, datasets. | `mlops/huggingface-hub` |
 | [`llama-cpp`](/docs/user-guide/skills/bundled/mlops/mlops-inference-llama-cpp) | llama.cpp local GGUF inference + HF Hub model discovery. | `mlops/inference/llama-cpp` |
-| [`evaluating-llms-harness`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness) | lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). | `mlops/evaluation/lm-evaluation-harness` |
-| [`segment-anything-model`](/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything) | SAM: zero-shot image segmentation via points, boxes, masks. | `mlops/models/segment-anything` |
-| [`serving-llms-vllm`](/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm) | vLLM: high-throughput LLM serving, OpenAI API, quantization. | `mlops/inference/vllm` |
+| [`evaluating-llms-harness`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness) | lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). | `mlops/evaluation/evaluating-llms-harness` |
+| [`serving-llms-vllm`](/docs/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm) | vLLM: high-throughput LLM serving, OpenAI API, quantization. | `mlops/inference/serving-llms-vllm` |
 | [`weights-and-biases`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases) | W&B: log ML experiments, sweeps, model registry, dashboards. | `mlops/evaluation/weights-and-biases` |
 
 ## note-taking
@@ -127,13 +101,12 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 | [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx) | Create, read, edit Word .docx documents and templates. | `productivity/docx` |
 | [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) | Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. | `productivity/google-workspace` |
 | [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) | Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. | `productivity/maps` |
-| [`nano-pdf`](/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf) | Edit PDF text/typos/titles via nano-pdf CLI (NL prompts). | `productivity/nano-pdf` |
+| [`nano-pdf`](/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf) | Edit text in existing PDFs via natural-language prompts. | `productivity/nano-pdf` |
 | [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) | Notion API + ntn CLI: pages, databases, markdown, Workers. | `productivity/notion` |
 | [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) | Extract text from PDFs/scans (pymupdf, marker-pdf). | `productivity/ocr-and-documents` |
 | [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf) | Create, merge, split, fill, and secure PDF files. | `productivity/pdf` |
-| [`petdex`](/docs/user-guide/skills/bundled/productivity/productivity-petdex) | Install and select animated petdex mascots for Hermes. | `productivity/petdex` |
 | [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) | Create, read, edit .pptx decks, slides, notes, templates. | `productivity/powerpoint` |
-| [`teams-meeting-pipeline`](/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline) | Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions. | `productivity/teams-meeting-pipeline` |
+| [`teams-meeting-pipeline`](/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline) | Teams meeting summaries, job replay, Graph subscriptions. | `productivity/teams-meeting-pipeline` |
 | [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx) | Create, read, edit Excel .xlsx spreadsheets and CSVs. | `productivity/xlsx` |
 
 ## research
@@ -156,24 +129,19 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) | X/Twitter via xurl CLI: post, search, DM, media, v2 API. | `social-media/xurl` |
+| [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) | X/Twitter via xurl CLI: raw post search, posting, DM, media. | `social-media/xurl` |
 
 ## software-development
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`hermes-agent-skill-authoring`](/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | Author in-repo SKILL.md: frontmatter, validator, structure, and writing-quality principles. | `software-development/hermes-agent-skill-authoring` |
+| [`dogfood`](/docs/user-guide/skills/bundled/software-development/software-development-dogfood) | Exploratory QA of web apps: find bugs, evidence, reports. | `software-development/dogfood` |
+| [`hermes-agent-skill-authoring`](/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | Author in-repo SKILL.md files: frontmatter and structure. | `software-development/hermes-agent-skill-authoring` |
 | [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | `software-development/node-inspect-debugger` |
-| [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | Plan mode: write an actionable markdown plan to .hermes/plans/, no execution. Bite-sized tasks, exact paths, complete code. | `software-development/plan` |
+| [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | Write a markdown plan to .hermes/plans/; no execution. | `software-development/plan` |
 | [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) | Debug Python: pdb REPL + debugpy remote (DAP). | `software-development/python-debugpy` |
 | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | Pre-commit review: security scan, quality gates, auto-fix. | `software-development/requesting-code-review` |
-| [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code) | Parallel 3-agent cleanup of recent code changes. | `software-development/simplify-code` |
+| [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code) | Parallel 4-agent cleanup of recent code changes. | `software-development/simplify-code` |
 | [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike) | Throwaway experiments to validate an idea before build. | `software-development/spike` |
 | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) | 4-phase root cause debugging: understand bugs before fixing. | `software-development/systematic-debugging` |
 | [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | TDD: enforce RED-GREEN-REFACTOR, tests before code. | `software-development/test-driven-development` |
-
-## yuanbao
-
-| Skill | Description | Path |
-|-------|-------------|------|
-| [`yuanbao`](/docs/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao) | Yuanbao (元宝) groups: @mention users, query info/members. | `yuanbao` |
diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md
index 1b621aeea1a..ce78b22e386 100644
--- a/website/docs/reference/slash-commands.md
+++ b/website/docs/reference/slash-commands.md
@@ -55,6 +55,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
 | `/moa <prompt>` | Run a single prompt through the default [Mixture of Agents](/user-guide/features/mixture-of-agents) preset, then restore your current model. One-shot — does not change your session model. |
 | `/resume [name]` | Resume a previously-named session |
 | `/sessions` (TUI alias: `/switch`) | Classic CLI: browse and resume previous sessions in an interactive picker. TUI: open the live session switcher for currently open TUI sessions. Use `/sessions new` in the TUI to start another live session immediately. |
+| `/egress [status]` | Show Docker egress proxy status — enabled/configured/running state, credential source, token mappings, uncovered providers, and next remediation step. Works in CLI, TUI, Desktop chat, and messaging gateway. |
 | `/redraw` | Force a full UI repaint (recovers from terminal drift after tmux resize, mouse selection artifacts, etc.) |
 | `/status` | Show session info — model, provider, profile, session ID, working directory, title, created/updated timestamps, token totals, agent-running state — followed by a local **Session recap** block (recent user/assistant turn counts, tool result count, top tools used, last few files touched, the latest user prompt, and the latest assistant reply). The recap is computed locally from the in-memory conversation; no LLM call, no prompt-cache impact. |
 | `/agents` (alias: `/tasks`) | Show active agents and running tasks across the current session. |
@@ -258,7 +259,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
 - `/skills` is **CLI-only for search/browse/install**; its write-approval review subcommands (`pending`, `approve`, `reject`, `diff`, `approval`) also work on messaging platforms when `skills.write_approval` is on. `/memory` works on **both** surfaces.
 - `/verbose` is **CLI-only by default**, but can be enabled for messaging platforms by setting `display.tool_progress_command: true` in `config.yaml`. When enabled, it cycles the `display.tool_progress` mode and saves to config.
 - `/sethome`, `/update`, `/restart`, `/approve`, `/deny`, `/topic`, `/platform`, and `/commands` are **messaging-only** commands.
-- `/status`, `/version`, `/background`, `/queue`, `/steer`, `/voice`, `/reload-mcp`, `/reload-skills`, `/rollback`, `/debug`, `/fast`, `/footer`, `/curator`, `/kanban`, `/credits`, `/suggestions`, `/blueprint`, `/learn`, `/sessions`, and `/yolo` work in **both** the CLI and the messaging gateway.
+- `/status`, `/egress`, `/version`, `/background`, `/queue`, `/steer`, `/voice`, `/reload-mcp`, `/reload-skills`, `/rollback`, `/debug`, `/fast`, `/footer`, `/curator`, `/kanban`, `/credits`, `/suggestions`, `/blueprint`, `/learn`, `/sessions`, and `/yolo` work in **both** the CLI and the messaging gateway.
 - `/voice join`, `/voice channel`, and `/voice leave` are only meaningful on Discord.
 - In the TUI, `/sessions` shows live sessions in the current TUI process. Use `/resume [name]` or `hermes --tui --resume <id-or-title>` for saved or closed transcripts.
 
diff --git a/website/docs/reference/tools-reference.md b/website/docs/reference/tools-reference.md
index a8cf61fcf39..54dc040de54 100644
--- a/website/docs/reference/tools-reference.md
+++ b/website/docs/reference/tools-reference.md
@@ -216,7 +216,7 @@ The single `video_generate` tool covers both modalities — pass `image_url` to
 
 | Tool | Description | Requires environment |
 |------|-------------|----------------------|
-| `x_search` | Search X (Twitter) posts, profiles, and threads using xAI's built-in `x_search` Responses tool. Use this for current discussion, reactions, or claims on X rather than general web pages. Off by default — opt in via `hermes tools` → 🐦 X (Twitter) Search. Schema is only registered when xAI credentials are configured (check_fn-gated). | XAI_API_KEY **or** xAI Grok OAuth (SuperGrok / Premium+) login |
+| `x_search` | Search X (Twitter) posts, profiles, and threads using xAI's built-in `x_search` Responses tool. Read-only public X discovery for current discussion, reactions, or claims on public X (not general web pages). Does not post, reply, like, DM, upload media, delete, or inspect the authenticated X account — those need a separate authenticated X API surface (e.g. the `xurl` skill). Off by default — opt in via `hermes tools` → 🐦 X (Twitter) Search. Schema is only registered when xAI credentials are configured (check_fn-gated). | XAI_API_KEY **or** xAI Grok OAuth (SuperGrok / Premium+) login |
 
 ## `tts` toolset
 
diff --git a/website/docs/reference/toolsets-reference.md b/website/docs/reference/toolsets-reference.md
index 60d345e1e1f..1f8092e7b43 100644
--- a/website/docs/reference/toolsets-reference.md
+++ b/website/docs/reference/toolsets-reference.md
@@ -83,7 +83,7 @@ Or in-session:
 | `vision` | `vision_analyze` | Image analysis via vision-capable models. |
 | `video` | `video_analyze` | Video analysis and understanding tools (opt-in, not in the default toolset — add explicitly via `--toolsets`). |
 | `web` | `web_extract`, `web_search` | Web search and page content extraction. |
-| `x_search` | `x_search` | Search X (Twitter) posts and threads via xAI's built-in `x_search` Responses tool. Off by default; opt in via `hermes tools`. Schema only registered when xAI credentials (SuperGrok OAuth or `XAI_API_KEY`) are configured. |
+| `x_search` | `x_search` | Read-only public X discovery via xAI's built-in `x_search` Responses tool. Use the `xurl` skill for authenticated X API reads and account actions. Off by default; opt in via `hermes tools`. Schema only registered when xAI credentials (SuperGrok OAuth or `XAI_API_KEY`) are configured. |
 | `yuanbao` | `yb_query_group_info`, `yb_query_group_members`, `yb_search_sticker`, `yb_send_dm`, `yb_send_sticker` | Yuanbao DM/group actions and sticker search. Registered only on `hermes-yuanbao`. |
 
 ## Platform Toolsets
diff --git a/website/docs/user-guide/checkpoints-and-rollback.md b/website/docs/user-guide/checkpoints-and-rollback.md
index 1393060612e..a71ec2fe5b7 100644
--- a/website/docs/user-guide/checkpoints-and-rollback.md
+++ b/website/docs/user-guide/checkpoints-and-rollback.md
@@ -94,12 +94,15 @@ checkpoints:
   max_file_size_mb: 10        # skip any single file larger than this
 
   # Auto-maintenance (on by default): sweep ~/.hermes/checkpoints/ at startup
-  # and delete project entries whose working directory no longer exists
-  # (orphans) or whose last_touch is older than retention_days. Runs at most
-  # once per min_interval_hours, tracked via a .last_prune marker.
+  # and delete project entries whose last_touch is older than retention_days.
+  # Runs at most once per min_interval_hours, tracked via a .last_prune
+  # marker. This sweep never deletes "orphan" entries (working directory not
+  # found) — a missing workdir at startup is ambiguous (deleted project vs.
+  # an unmounted external volume / network share / VPN not yet up), so
+  # orphan cleanup is only ever done via the explicit
+  # `hermes checkpoints prune` command below, with a confirmation prompt.
   auto_prune: true
   retention_days: 7
-  delete_orphans: true
   min_interval_hours: 24
 ```
 
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 7956d07fc35..96ce47b7f6b 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -743,6 +743,7 @@ All compression settings live in `config.yaml` (no environment variables).
 ```yaml
 compression:
   enabled: true                                     # Toggle compression on/off
+  progress_notices: false                           # Opt-in: deliver routine compression progress notices to chat platforms — see below
   threshold: 0.50                                   # Compress at this % of context limit
   threshold_tokens: null                            # Absolute token cap (optional) — takes lower of ratio vs absolute
   target_ratio: 0.20                                # Fraction of threshold to preserve as recent tail
@@ -750,8 +751,12 @@ compression:
   protect_first_n: 3                                # Non-system head messages pinned across compactions (0 = pin nothing)
   idle_compact_after_seconds: 0                     # Opt-in idle compaction (0 = disabled) — see below
   hygiene_hard_message_limit: 5000                  # Gateway safety valve — see below
-  hygiene_timeout_seconds: 30                       # Max seconds gateway waits for pre-agent hygiene compression
+  hygiene_timeout_seconds: 30                       # Max seconds of NO summary-model output before hygiene compression is cut off
+  hygiene_total_ceiling_seconds: 600                # Absolute cap on the hygiene wait even while tokens are still streaming
   hygiene_failure_cooldown_seconds: 300             # Skip repeated failed hygiene attempts for this session
+  proactive_prune_tokens: 0                         # Opt-in tokens trigger for the no-LLM tool-result prune (0 = off; see below)
+  proactive_prune_min_result_chars: 8000            # Prune's summarize pass only touches tool results larger than this (clamped >= 200)
+  proactive_prune_min_reclaim_tokens: 4096          # Prune only commits when it reclaims at least this many tokens (0 = commit any)
 
 # The summarization model/provider is configured under auxiliary:
 auxiliary:
@@ -765,9 +770,13 @@ auxiliary:
 Older configs with `compression.summary_model`, `compression.summary_provider`, and `compression.summary_base_url` are automatically migrated to `auxiliary.compression.*` on first load (config version 17). No manual action needed.
 :::
 
+`progress_notices` (default `false`) controls whether **routine** compression progress statuses reach chat platforms (Telegram, Discord, Slack, etc.). By design, automatic compression is silent on chat surfaces — it runs in the background with server-side logging only. Set `progress_notices: true` to opt into seeing the routine lifecycle on chat platforms: the "Compacting context…" start notice, preflight/pre-API compression triggers, idle compaction, retry progress ("Compressed 30 → 12 messages, retrying…"), and the "Context compaction complete" notice. The gate is scoped to compression statuses only — unrelated operational noise (auxiliary model failures, provider rate-limit/retry chatter) stays suppressed either way. Compression **failure** notices and manual `/compress` feedback are always visible regardless of this setting. Editing this value on a running gateway takes effect on the next message.
+
 `hygiene_hard_message_limit` is a gateway-only **pre-compression safety valve**. It exists to break a death spiral: when API calls keep disconnecting on an oversized session, the gateway never receives token-usage data, so the token-based threshold can't fire, so the transcript keeps growing and disconnects get worse. This count-based floor fires on message count alone (always known, regardless of API failures) to force compression and recover the session. Default `5000` — far above any normal session, including large-context (1M+) models doing thousands of short turns, which compress on the token threshold long before this. Raise it further for unusual platforms, lower it to force more aggressive compression. Editing this value on a running gateway takes effect on the next message (see below).
 
-`hygiene_timeout_seconds` caps how long the gateway waits for this pre-agent compression pass. If the auxiliary compression backend is down or very slow, the gateway warns the user, continues the incoming message without compression, and records a temporary per-session failure cooldown instead of appearing stuck.
+`hygiene_timeout_seconds` is the gateway's **inactivity budget** for this pre-agent compression pass — not a total wall-clock cap. The compression summary call streams from the model, and each arriving token counts as forward progress: a slow reasoning model that is still generating keeps extending its own deadline, so slow-but-healthy summary models are never cut off mid-generation. Only when the summary model produces **no output** for this many seconds (backend down, hung connection, silent provider) does the gateway warn the user, continue the incoming message without compression, and record a temporary per-session failure cooldown instead of appearing stuck.
+
+`hygiene_total_ceiling_seconds` (default `600`) bounds the total wait even while tokens are still moving, so a degenerate trickle stream can't hold a turn hostage indefinitely. It is clamped to at least `hygiene_timeout_seconds`.
 
 `hygiene_failure_cooldown_seconds` controls that per-session cooldown after a hygiene compression timeout or abort. During the cooldown, the gateway skips repeated hygiene attempts for the same oversized session so every incoming message does not block on the same broken auxiliary backend. `/compress`, `/reset`, or a healthy later turn can still recover the session.
 
@@ -777,6 +786,8 @@ Older configs with `compression.summary_model`, `compression.summary_provider`,
 
 `idle_compact_after_seconds` is an **opt-in, time-based** trigger that complements the size-based `threshold`. Default `0` (disabled). When set above 0, a session that resumes after at least that many seconds of inactivity compacts its accumulated history up front, before the first reply — so a long-lived thread (e.g. a Telegram conversation you come back to hours later) doesn't re-read its full stale context on every subsequent turn. It never fires when the context is already at or below the post-compression target (`threshold × target_ratio`), and it honors the same failure-cooldown, anti-thrash, and per-session lock guards as every automatic compaction. Example: `idle_compact_after_seconds: 1800` compacts after 30 minutes idle.
 
+`proactive_prune_tokens` enables a deterministic, no-LLM prune of old tool-result payloads that runs independently of `threshold`. On large-window models the `threshold` compaction (≈50% of the window) rarely fires, so bulky tool outputs (terminal dumps, file reads, web extracts) ride along in history and get re-sent on every subsequent turn. When re-sent history exceeds `proactive_prune_tokens` (default `0` = off; try `48000` to enable), the prune dedupes identical results, summarizes older oversized ones, and truncates large tool-call arguments — protecting the most recent `protect_last_n` messages and never calling the model. Full outputs stay recoverable from the session store. `proactive_prune_min_result_chars` (default `8000`, clamped to ≥ 200) sets the size below which a tool result is left untouched. `proactive_prune_min_reclaim_tokens` (default `4096`) prevents a prune from committing unless it reclaims at least that many tokens — a committed prune rewrites already-sent history and invalidates the provider's prompt-cache prefix, so this gate keeps those cache breaks episodic and amortized (one meaningful break, like a compression boundary) instead of firing on every tool iteration. This runs only under the built-in `compressor` engine; other context engines inherit a no-op.
+
 :::tip Gateway hot-reload of compression and context length
 As of recent releases, editing `model.context_length` or any `compression.*` key in `config.yaml` on a running gateway takes effect on the next message — no gateway restart, no `/reset`, no session rotation required. The cached-agent signature includes these keys, so the gateway transparently rebuilds the agent when it sees a change. API keys and tool/skill config still require the usual reload paths.
 :::
@@ -974,6 +985,18 @@ If you do not want Hermes to auto-generate titles after the first exchange, set
 `auxiliary.title_generation.enabled: false`. Manual titles still work through
 `/title` and `hermes sessions rename`.
 
+### Stream-only endpoints
+
+Some OpenAI-compatible endpoints reject non-streaming chat requests outright (e.g. Tencent Copilot returns HTTP 400 `"Non-stream chat request is currently not supported"`). Interactive chat already streams, but auxiliary tasks (title generation, compression, web extraction) use non-streaming calls and would fail on every attempt. Hermes always treats `copilot.tencent.com` as stream-only; for any other such endpoint, list a URL substring under `auxiliary.stream_only_base_urls`:
+
+```yaml
+auxiliary:
+  stream_only_base_urls:
+    - "my-stream-only-proxy.example.com"
+```
+
+Matching auxiliary calls are sent with `stream=True` and the chunks (including tool-call deltas) are aggregated client-side — no behavior change for any other endpoint.
+
 ### Video Tutorial
 
 <div style={{position: 'relative', width: '100%', aspectRatio: '16 / 9', marginBottom: '1.5rem'}}>
diff --git a/website/docs/user-guide/egress/index.md b/website/docs/user-guide/egress/index.md
new file mode 100644
index 00000000000..90ccbb8a05e
--- /dev/null
+++ b/website/docs/user-guide/egress/index.md
@@ -0,0 +1,10 @@
+---
+title: Egress proxy
+sidebar_position: 1
+---
+
+# Egress proxy
+
+Optional outbound credential-injection firewall for remote terminal sandboxes. The sandbox only ever holds opaque proxy tokens; real API keys never leave the host.
+
+- [iron-proxy](./iron-proxy) — single-binary TLS-intercepting proxy from [ironsh/iron-proxy](https://github.com/ironsh/iron-proxy), lazy-installed and managed by `hermes egress`.
diff --git a/website/docs/user-guide/egress/iron-proxy.md b/website/docs/user-guide/egress/iron-proxy.md
new file mode 100644
index 00000000000..f38cbfa33a8
--- /dev/null
+++ b/website/docs/user-guide/egress/iron-proxy.md
@@ -0,0 +1,570 @@
+# Egress credential-injection proxy (iron-proxy)
+
+When Hermes runs your agent inside a Docker terminal sandbox, that sandbox normally holds your real upstream API keys (`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, etc.). A prompt-injected agent in that sandbox can `cat ~/.config/openrouter/auth.json` or `printenv | grep -i key` and exfiltrate them.
+
+The egress proxy fixes this: the sandbox holds opaque **proxy tokens**, never the real keys. All outbound traffic from the sandbox routes through a local [iron-proxy](https://github.com/ironsh/iron-proxy) daemon (Apache-2.0, Go) on the host, which terminates TLS and swaps the proxy token for the real credential before forwarding the request upstream. Compromise the sandbox and the attacker walks away with tokens that only work behind the **configured trusted proxy boundary** — the CA private key and the proxy endpoint integrity are part of that boundary. If traffic can be redirected to attacker-controlled proxy infrastructure (e.g. a stolen CA private key or a hijacked proxy endpoint), the token guarantee no longer holds.
+
+This release wires the egress proxy into the Docker backend only. Modal, Daytona, SSH, and Singularity do **not** receive proxy env vars or CA mounts yet.
+
+## What it is
+
+- A managed `iron-proxy` subprocess on the host, lazy-installed into `~/.hermes/bin/iron-proxy`
+- A local CA at `~/.hermes/proxy/ca.crt` that the sandbox trusts so iron-proxy can MITM TLS and rewrite headers
+- A `proxy.yaml` config at `~/.hermes/proxy/proxy.yaml` listing the upstream hosts you allow and the secrets-transform mapping
+- A `mappings.json` recording which proxy token corresponds to which real env var
+
+The sandbox gets `HTTPS_PROXY=http://host.docker.internal:9090`, `HTTP_PROXY=http://host.docker.internal:9091`, and standard provider env vars such as `OPENROUTER_API_KEY` set to opaque proxy tokens. Matching `HERMES_PROXY_TOKEN_<ENV_NAME>` aliases are also exported for diagnostics. Existing provider SDKs read the usual env names, send the proxy token in `Authorization`, and iron-proxy's `secrets` transform substitutes the real value sourced from the host-side daemon environment.
+
+## What it is not
+
+- It is **not** the inbound `hermes proxy` command, which is an OAuth aggregator reverse proxy. Different command (`hermes egress`), different direction.
+- It does **not** sit between your local terminal and providers — only between the sandbox and providers.
+- It does **not** rewrite credentials for in-process LLM calls the host process makes. Those continue to use your `.env` keys directly. The threat model is the *sandbox*, not the host.
+
+## Quick start
+
+```bash
+# 1. Install the iron-proxy binary (pinned version, SHA-256 verified)
+hermes egress install
+
+# 2. Run the wizard: generates CA, mints proxy tokens for every provider key
+#    in your env, writes proxy.yaml.
+hermes egress setup
+
+# 3. Start the proxy daemon
+hermes egress start
+
+# 4. Check status
+hermes egress status
+```
+
+`hermes egress setup` discovers provider keys from your environment. If your keys live only in `~/.hermes/.env` (not exported into your shell), setup reads that file automatically — you don't have to `export` them first.
+
+When you re-run `setup` later (new allowlist host, rotated tokens, switched credential source), it stops the running daemon because its config is held in memory, then **offers to restart it for you** so the change takes effect immediately. On a tty it asks; pass `--restart` to always restart or `--no-restart` to leave it down. To apply changes any other time, `hermes egress restart` is the one-command stop-then-start.
+
+Once running, the Docker terminal backend automatically:
+
+- Mounts `~/.hermes/proxy/ca.crt` into the sandbox at `/etc/ssl/certs/hermes-egress-ca.crt`
+- Sets `HTTPS_PROXY`, `HTTP_PROXY`, `REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `NODE_EXTRA_CA_CERTS` to make every common HTTP runtime route through the proxy and trust the CA
+- Sets `NODE_OPTIONS=--use-openssl-ca` (appended to whatever you already have in `docker_env.NODE_OPTIONS`) so Node.js routes through the OpenSSL store the other CA-bundle vars control — see [Node.js asymmetric CA caveat](#nodejs-asymmetric-ca-caveat) below for the residual gap
+- Adds `--add-host=host.docker.internal:host-gateway` so the sandbox can reach the host-side proxy on Linux (Docker Desktop handles this automatically on macOS/Windows)
+- Exports the proxy token under the standard provider env name (for example `OPENROUTER_API_KEY`) plus one `HERMES_PROXY_TOKEN_<ENV_NAME>` diagnostic alias per minted mapping
+
+## Configuration
+
+The full config lives in `~/.hermes/config.yaml` under the `proxy:` section. Defaults are documented inline; everything is optional.
+
+```yaml
+proxy:
+  # Master switch. When false the feature is a complete no-op — no
+  # binaries downloaded, no docker mounts added, no subprocess started.
+  enabled: false
+
+  # Tunnel listener port. Sandboxes hit http://host.docker.internal:<port>.
+  tunnel_port: 9090
+
+  # Auto-download the pinned iron-proxy binary on first use.
+  auto_install: true
+
+  # Where iron-proxy looks up the real upstream secrets at egress time.
+  #   env       — process env (default). Whatever is in your ~/.hermes/.env
+  #               at proxy-start time is the source of truth.
+  #   bitwarden — refetch from Bitwarden Secrets Manager on each proxy
+  #               restart. Rotation in the BW web app propagates without
+  #               touching .env. Requires `secrets.bitwarden.enabled: true`.
+  credential_source: env
+
+  # When true (default), the Docker backend refuses to start a sandbox if
+  # the proxy is enabled but not running. Set to false to fall back to the
+  # legacy "real credentials inside the sandbox" posture when the proxy
+  # is unavailable.
+  enforce_on_docker: true
+
+  # When `credential_source: bitwarden` but the BWS access token /
+  # project_id is missing OR the bws fetch returns no values for mapped
+  # providers, the daemon raises by default (matches the spirit of "I
+  # asked for rotation — don't silently use stale env values").  Set
+  # to true to opt back into the legacy host-env fallback — useful for
+  # migrations where you want to start switching to BW mode but haven't
+  # wired every secret yet.
+  allow_env_fallback: false
+
+  # SSRF deny list applied to outbound traffic.  Omit / leave null to
+  # use the safe default: loopback (v4 + v6), link-local (incl. cloud
+  # metadata IPs at 169.254.169.254), RFC1918, IPv6 ULA, IPv4-mapped-v6,
+  # CGNAT, and the RFC2544 benchmark range.  Set to an explicit `[]`
+  # to opt out entirely (only sensible in hermetic tests).
+  upstream_deny_cidrs: null
+
+  # Extra allowed upstream hosts beyond the bundled defaults.
+  # Wildcards (`*.foo.com`) are supported. The defaults cover OpenRouter,
+  # OpenAI, Anthropic, Google, xAI, Mistral, Groq, Together, DeepSeek,
+  # and Nous Research.
+  extra_allowed_hosts: []
+```
+
+### Default allowed upstream hosts
+
+```
+openrouter.ai           *.openrouter.ai
+api.openai.com          api.anthropic.com
+generativelanguage.googleapis.com
+api.x.ai                api.mistral.ai
+api.groq.com            api.together.xyz
+api.deepseek.com        inference.nousresearch.com
+```
+
+If your agent needs an upstream that isn't on the list — a self-hosted inference endpoint, an extra cloud LLM, an MCP server — add it to `proxy.extra_allowed_hosts`. Wildcards are matched against the full hostname (`*.example.com` matches `api.example.com` and `staging.example.com` but not `example.com` itself).
+
+### Default SSRF deny CIDRs
+
+Applied regardless of allowlist. These ranges are refused by iron-proxy at the network boundary, so a DNS rebinding attack via an allowlisted hostname can't reach IMDS or your internal network:
+
+| CIDR | Purpose |
+|---|---|
+| `127.0.0.0/8`, `::1/128` | Loopback (v4 + v6) |
+| `169.254.0.0/16`, `fe80::/10` | Link-local — **incl. AWS / GCP / Azure IMDS at `169.254.169.254`** |
+| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 |
+| `fc00::/7` | IPv6 ULA |
+| `::ffff:0:0/96` | IPv4-mapped IPv6 — closes the dual-stack IMDS bypass |
+| `100.64.0.0/10` | RFC6598 CGNAT (used by AWS VPC, K8s pod networks) |
+| `198.18.0.0/15` | RFC2544 benchmark range |
+
+To override: set `proxy.upstream_deny_cidrs` to your own list. To opt out entirely (e.g. for a hermetic test that needs to reach a loopback upstream): set it to an empty list `[]`.
+
+### Bind policy
+
+The proxy never binds `0.0.0.0`. The default bind is platform-specific because iron-proxy v0.39 supports only a **single bind per daemon process**:
+
+- **Linux:** the docker bridge gateway (`172.17.0.1:<tunnel_port>` by default). Containers reach the proxy via `host.docker.internal`, which `--add-host=host.docker.internal:host-gateway` resolves to exactly this bridge gateway IP — a loopback-only bind would be unreachable from inside sandboxes. The bridge IP is an address on the host's `docker0` interface, so it is not exposed to the LAN; it IS reachable by other containers on the default bridge network, but requests still require a minted proxy token and an allowlisted upstream. If no docker bridge is detected (docker not installed/running), the bind falls back to loopback with a warning.
+- **macOS / Windows Docker Desktop:** loopback (`127.0.0.1:<tunnel_port>`). Desktop's VPNkit routes `host.docker.internal` to the host, so loopback is reachable from containers and is the least-exposed choice.
+
+A LAN peer with a leaked proxy token cannot use the proxy — neither bind is reachable from the external network.
+
+We also pin `metrics.listen: 127.0.0.1:0` so the daemon's built-in metrics server gets an ephemeral loopback port instead of its default `:9090` — otherwise it would fight `tunnel_port: 9090` for the same socket and the daemon would refuse to start with "address already in use". Note the `:0` ephemeral port is random per start and not surfaced anywhere, so metrics are effectively disabled at this pin.
+
+If a hostile `ip` shim earlier on PATH had been able to inject a non-private IPv4 as the bridge address (`0.0.0.0`, a public address, multicast, link-local, etc.) the loopback fallback still applies — we never bind anything we couldn't validate via `ipaddress.IPv4Address` + `is_*` checks.
+
+## Covered auth schemes
+
+The `secrets` transform swaps the proxy token wherever it appears in a matched location — and it matches more than `Authorization: Bearer`:
+
+| Provider | Env var | Swapped in |
+|---|---|---|
+| OpenRouter, OpenAI, Groq, Together, DeepSeek, Mistral, xAI, Nous | `*_API_KEY` | `Authorization` header |
+| Anthropic native | `ANTHROPIC_API_KEY` | `x-api-key` + `Authorization` |
+| Azure OpenAI | `AZURE_OPENAI_API_KEY` | `api-key` + `Authorization` (`*.openai.azure.com`, `*.cognitiveservices.azure.com`, `*.services.ai.azure.com`) |
+| Google AI Studio (Gemini) | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | `x-goog-api-key` header or `?key=` query param |
+
+`GEMINI_API_KEY` and `GOOGLE_API_KEY` are treated as one credential: a single proxy token is minted and injected into the sandbox under **both** names, and either name in your host env satisfies discovery.
+
+## Uncovered providers
+
+Auth schemes that involve request signing or SDK-minted OAuth cannot be swapped by a static header replacement — if their env vars are present, the sandbox holds **real credentials** for those providers and the egress isolation guarantee is incomplete for them:
+
+| Env var | Provider | Reason |
+|---|---|---|
+| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | AWS Bedrock / SageMaker | SigV4-signed requests |
+| `GOOGLE_APPLICATION_CREDENTIALS` | GCP Vertex AI | OAuth minted from a service-account file |
+
+These env vars are present on most developer laptops for unrelated tooling (terraform, gcloud, aws CLI, ECR push). They surface as warnings in the wizard and `hermes egress status` but never block the proxy from starting. If you don't use those providers from sandboxes, `unset` the vars to clear the warning.
+
+## Bitwarden integration
+
+If you already use Bitwarden Secrets Manager via [`hermes secrets bitwarden setup`](../secrets/bitwarden), the egress proxy can pull real credentials from there instead of `os.environ`:
+
+```bash
+hermes egress setup --from-bitwarden
+```
+
+This sets `proxy.credential_source: bitwarden` and discovers provider env names from your BW project.
+
+### Rotation semantics
+
+When `credential_source: bitwarden`, the iron-proxy daemon refetches secrets from BWS via `bws secret list <project_id>` **every time it starts**. So the rotation flow is:
+
+1. Rotate a key in the Bitwarden web app.
+2. `hermes egress stop && hermes egress start` on the host.
+3. Sandboxes started after that point swap proxy tokens for the new value.
+
+No `.env` edits. No Hermes restart on the host. The proxy daemon is the only thing that touches the new value — your host process and `os.environ` are untouched.
+
+### Fail-loud at start
+
+When `credential_source: bitwarden`, `hermes egress start` pre-checks at the wizard layer AND `_build_proxy_subprocess_env` re-checks at the daemon layer:
+
+- BWS access token env var is unset → refuse to start with a hint to `unset` and re-run, or `hermes egress setup --no-bitwarden` to switch back to env mode
+- `secrets.bitwarden.project_id` is empty → refuse to start with a hint to run `hermes secrets bitwarden setup`
+- `bws secret list` returns no values for one or more mapped providers → refuse to start, listing the missing names
+
+This is intentional. Falling back to host env in BW mode reintroduces exactly the staleness bug the BW path is meant to defeat (operator picked BW for the rotation guarantee; silent fallback breaks that guarantee).
+
+The `proxy.allow_env_fallback: true` config flag opts back in to the legacy "silently fall back to host env if BWS is unreachable" behavior for migration scenarios. Use it when you're moving secrets into BW one at a time and want the daemon to start with whichever values are available.
+
+### Switching credential source
+
+| From | To | Command |
+|---|---|---|
+| env | bitwarden | `hermes egress setup --from-bitwarden` |
+| bitwarden | env | `hermes egress setup --no-bitwarden` |
+
+**Re-running `hermes egress setup` WITHOUT either flag preserves the existing `credential_source`** — the wizard refuses to silently downgrade you back to env. This matters because once you've configured bitwarden mode, the rotation guarantee is what you signed up for; you have to explicitly say "I want env again" to change it.
+
+## Slash commands
+
+The CLI subcommand tree:
+
+```
+hermes egress install                  # download the pinned iron-proxy binary
+hermes egress install --force          # re-download even if a managed copy exists
+
+hermes egress setup                    # interactive wizard
+hermes egress setup --tunnel-port N    # override the tunnel listener port
+hermes egress setup --from-bitwarden   # use BWS as credential source (fail-loud)
+hermes egress setup --no-bitwarden     # explicitly switch back to env mode
+hermes egress setup --rotate-tokens    # mint fresh tokens for every provider
+                                       #   (default preserves existing)
+
+hermes egress start                    # spawn the managed proxy daemon
+hermes egress stop                     # SIGTERM (then SIGKILL after 5s grace)
+hermes egress restart                  # stop (if running) then start — needed when
+                                       #   upstream SECRETS change (rotation, new provider)
+hermes egress reload                   # hot-reload the ruleset from proxy.yaml via the
+                                       #   management API — no restart, no dropped
+                                       #   connections (allowlist / mapping edits)
+
+hermes egress status                   # binary + config + pid + listening state + mappings
+hermes egress status --show-tokens     # print proxy tokens in full
+                                       #   (default: redacted prefix + suffix only)
+
+hermes egress disable                  # flip proxy.enabled = false
+                                       #   (does not stop a running proxy)
+
+hermes egress config                   # print the path to proxy.yaml for debugging
+```
+
+### Token rotation
+
+By default, `hermes egress setup` **preserves** proxy tokens for providers that already have them. Adding a new provider mints a fresh token only for the new one; existing tokens are unchanged. This avoids 401-ing running sandboxes when you re-run the wizard.
+
+`--rotate-tokens` rolls every token:
+
+```bash
+hermes egress setup --rotate-tokens
+```
+
+When there are existing tokens AND stdin is a tty, the wizard prompts for confirmation:
+
+```
+⚠  --rotate-tokens will invalidate proxy tokens in every running
+   Hermes sandbox.  They will start 401-ing against upstreams until restarted.
+Type 'rotate' to confirm:
+```
+
+Non-tty invocations (CI, scripts) skip the prompt — the flag is treated as deliberate. Before any overwrite the current `mappings.json` is copied to a timestamped sibling so manual recovery is possible:
+
+```
+backup: ~/.hermes/proxy/mappings.json.rotated-20260524T143012
+```
+
+`hermes egress setup` stops a running daemon when it rewrites config or token mappings, because the daemon keeps the old YAML in memory. After `--rotate-tokens`:
+
+```bash
+hermes egress start
+```
+
+Containers already running hold the old tokens and will need to be restarted to pick up the new ones. New persistent Docker containers include an egress-posture label, so Hermes will not reuse a pre-egress or pre-rotation container for new sessions.
+
+## State directory layout
+
+Everything iron-proxy maintains lives in `~/.hermes/proxy/`:
+
+| Path | Mode | Purpose |
+|---|---|---|
+| `~/.hermes/proxy/` (dir) | `0o700` | Owned + traversable by you only |
+| `ca.crt` | `0o644` | Public CA cert distributed into sandboxes |
+| `ca.key` | `0o600` | CA signing key — never leaves the host |
+| `proxy.yaml` | `0o600` | iron-proxy config; rewritten every `setup` |
+| `mappings.json` | `0o600` | Sandbox proxy token → upstream env var |
+| `mappings.json.rotated-*` | `0o600` | Backups created by `--rotate-tokens` |
+| `iron-proxy.pid` | `0o600` | PID of the running daemon |
+| `iron-proxy.nonce` | `0o600` | Per-start nonce for PID-recycle defense |
+| `iron-proxy.log` | `0o600` | Daemon stdout/stderr — **includes per-request records on v0.39** |
+| `audit.log` | `0o600` | Reserved for the dedicated per-request audit stream on future binary versions; pre-created so the privacy contract holds when upstream wires it in |
+
+The CA private key is the most sensitive file. It's created with `0o600` from the first byte (no umask-window TOCTOU) and `O_NOFOLLOW` so a same-uid attacker can't redirect it via a planted symlink. The pidfile, nonce file, daemon log, and audit log get the same treatment.
+
+### Logging on iron-proxy v0.39
+
+On the currently pinned binary version (**v0.39.0**) iron-proxy writes ALL output — daemon-level diagnostics AND per-request records — to **`~/.hermes/proxy/iron-proxy.log`**. v0.39's `config.Log` struct doesn't have a separate `audit_path` field, so we can't route per-request records to a dedicated stream there.
+
+We still pre-create `~/.hermes/proxy/audit.log` at `0o600` with `O_NOFOLLOW` because:
+
+1. It reserves the path for the future version bump: when the pinned version moves to one that supports `log.audit_path`, per-request records will start flowing there without operator-side reconfiguration. **Until then the file stays at 0 bytes — do not point monitoring, alerting, or forensics tooling at it yet.** Use `iron-proxy.log` for everything today.
+2. The 0o600-from-first-byte guarantee defends against the upstream-fix-day where v0.40+ creates the file under its default umask if it doesn't already exist.
+
+Until that version bump lands, treat `iron-proxy.log` as the source of truth for both audiences:
+
+- Daemon-level events (startup banner, bind errors, shutdown reason, transform errors). Operations + troubleshooting.
+- Per-request records (CONNECT to allowlisted upstream, secret swap fired, allowlist denial). Forensics + compliance.
+
+Both files are appended to across restarts. Rotate them with logrotate if you care about disk usage on long-lived hosts.
+
+## How it works
+
+```
+┌──────────────┐                ┌──────────────┐                ┌─────────────┐
+│ Docker       │ CONNECT /     │ iron-proxy    │ HTTPS w/       │ OpenRouter  │
+│ sandbox      ├──────────────▶│ (host:9090)   ├───────────────▶│ / OpenAI /  │
+│              │ HTTP forward  │               │ real API key   │ Anthropic …  │
+│ has:         │ w/ proxy tok  │ mints leaf    │                │             │
+│ - proxy tok  │ in Auth hdr   │ cert from CA  │                │             │
+│ - CA cert    │               │ matches token │                │             │
+│ - HTTPS_PROXY│               │ swaps secret  │                │             │
+└──────────────┘               └──────────────┘                └─────────────┘
+                                       │
+                                       │ daemon + per-request log (combined on v0.39)
+                                       ▼
+                              ~/.hermes/proxy/iron-proxy.log
+                              (~/.hermes/proxy/audit.log reserved for v0.40+ split stream)
+```
+
+1. Sandbox makes an HTTPS request, e.g. `POST https://openrouter.ai/v1/chat/completions` with `Authorization: Bearer hermes-proxy-openrouter-…` (the proxy token, not the real key).
+2. Because `HTTPS_PROXY` is set, the request goes to iron-proxy as a CONNECT tunnel.
+3. iron-proxy checks the allowlist. `openrouter.ai` is allowed.
+4. iron-proxy mints a leaf cert signed by our CA for `openrouter.ai`, terminates the TLS connection, inspects the request.
+5. The `secrets` transform matches the proxy-token string in the `Authorization` header and substitutes the real `OPENROUTER_API_KEY` value, sourced from iron-proxy's own environment.
+6. Request is re-encrypted and forwarded to OpenRouter.
+7. The request is logged to `~/.hermes/proxy/iron-proxy.log` on v0.39. When the pinned binary version supports the split stream (v0.40+), per-request records will flow to `~/.hermes/proxy/audit.log` and daemon-level diagnostics will stay in `iron-proxy.log`. See [Logging on iron-proxy v0.39](#logging-on-iron-proxy-v039).
+
+A request to a non-allowlisted host (e.g. `https://attacker.example.com/leak?key=...`) is rejected with HTTP 403 before any bytes leave the host. The denial is recorded in `iron-proxy.log` with the upstream host and the source sandbox.
+
+### CA distribution into the sandbox
+
+When the Docker backend starts a container with `proxy.enabled: true` and the daemon is listening, it adds these arguments to `docker run`:
+
+| Arg | Purpose |
+|---|---|
+| `-v ~/.hermes/proxy/ca.crt:/etc/ssl/certs/hermes-egress-ca.crt:ro` | Read-only mount of the CA |
+| `-e HTTPS_PROXY=http://host.docker.internal:9090` | Python httpx / curl / go default transport / Node fetch |
+| `-e HTTP_PROXY=http://host.docker.internal:9091` | curl + wget for plain HTTP — the plain-HTTP forward listener lives on `tunnel_port + 1` |
+| `-e NO_PROXY=127.0.0.1,localhost,::1` | Loopback dev servers inside the sandbox bypass the proxy |
+| `-e REQUESTS_CA_BUNDLE=…ca.crt` | Python `requests` |
+| `-e SSL_CERT_FILE=…ca.crt` | Python `ssl` module / OpenSSL — **replaces** the system store |
+| `-e CURL_CA_BUNDLE=…ca.crt` | curl — **replaces** the system store |
+| `-e NODE_EXTRA_CA_CERTS=…ca.crt` | Node.js — **adds** to the system store |
+| `-e NODE_OPTIONS="<your value> --use-openssl-ca"` | Node.js — route through OpenSSL store (appended; your `--max-old-space-size` etc. are preserved) |
+| `-e HERMES_EGRESS_PROXY=1` | Sentinel the agent can read to know it's proxy-aware |
+| `-e OPENROUTER_API_KEY=<proxy-token>` | Standard provider env names receive proxy tokens so existing SDKs keep working |
+| `-e HERMES_PROXY_TOKEN_<NAME>=…` | Diagnostic alias for each mapping; same value as the standard provider env var |
+| `--add-host=host.docker.internal:host-gateway` | Linux-only; Docker Desktop maps it automatically |
+
+#### Node.js asymmetric CA caveat
+
+`REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE` / `CURL_CA_BUNDLE` **replace** the system CA store inside the sandbox. `NODE_EXTRA_CA_CERTS` **adds** to it. A Node.js process inside the sandbox could in principle bypass the proxy by opening a raw `net.Socket` and starting its own TLS handshake — the system CA store would still trust real upstream certs, so the request would succeed where Python / curl would fail validation.
+
+`NODE_OPTIONS=--use-openssl-ca` is appended to whatever you already have in `docker_env.NODE_OPTIONS`. This forces Node through the OpenSSL store that `SSL_CERT_FILE` controls, narrowing the asymmetry. It does NOT cover code that explicitly passes its own `ca` option to `tls.connect()` or `https.request()`, but it closes the easy case.
+
+This is a known v1 limitation. Track [github.com/ironsh/iron-proxy/issues](https://github.com/ironsh/iron-proxy/issues) for an upstream resolution; in the meantime, do not run untrusted Node code that opens raw sockets in a sandbox you're depending on egress isolation for.
+
+### docker\_env collisions
+
+If you set proxy-controlling env vars in your `docker_env:` config block (rare but possible), Hermes refuses to start the sandbox when `enforce_on_docker: true` is set. This includes both:
+
+- Egress-control vars: `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `NODE_EXTRA_CA_CERTS`
+- Real provider env vars: every name in `mappings.json` (e.g. `OPENROUTER_API_KEY`, `OPENAI_API_KEY`)
+
+Example error:
+
+```
+docker_env in config.yaml overrides egress-proxy variables
+['HTTPS_PROXY', 'OPENROUTER_API_KEY']; enforce_on_docker is enabled.
+Remove these keys from docker_env or disable enforce_on_docker to
+opt out of egress isolation.
+```
+
+With `enforce_on_docker: false` the same situation surfaces as a warning and your `docker_env` values win — useful for migrations or testing, but you're explicitly opting OUT of the isolation guarantee.
+
+## PID and nonce defense
+
+The daemon's pidfile is written with `O_EXCL` + `O_NOFOLLOW` + ownership check. Concurrent `hermes egress start` calls produce one of two outcomes:
+
+- The existing pidfile points at a live iron-proxy → second start refuses with "another start in progress" + a hint to run `hermes egress stop`
+- The existing pidfile is stale (crashed daemon) → second start unlinks it and retries once
+
+Beyond that, every `start_proxy` plants a fresh random nonce in two places:
+
+- `HERMES_IRON_PROXY_NONCE=<nonce>` in the daemon's env
+- `~/.hermes/proxy/iron-proxy.nonce` (0o600 sibling of the pidfile)
+
+When `hermes egress stop` (or any other `_pid_alive` check) wants to confirm a PID still refers to *our* daemon — not an unrelated process that was assigned the same PID after iron-proxy crashed — it reads `/proc/<pid>/environ` and looks for the nonce. The on-disk copy is what makes this work across CLI invocations (the in-memory `_proxy_nonce` is per-process and resets on every `hermes` invocation).
+
+If the nonce check fails, the code falls back to matching `argv[0]` basename against `iron-proxy`. `stop_proxy` additionally captures `/proc/<pid>/stat` starttime before SIGTERM and re-verifies after the 5s grace window — if starttime drifted, the PID was recycled mid-wait and SIGKILL is suppressed with a warning.
+
+## Security model
+
+**What this protects against:**
+
+- Prompt-injected agent in a Docker sandbox reading `printenv` / credential files and exfiltrating real keys.
+- Compromised dependency in the sandbox phoning home to an arbitrary host — default-deny allowlist blocks unknown destinations.
+- Agent dialing cloud metadata endpoints (`169.254.169.254`) — iron-proxy denies these by default via `upstream_deny_cidrs`, including the IPv4-mapped-v6 form `::ffff:169.254.169.254`.
+- DNS rebinding through an allowlisted hostname to a private IP — the deny CIDRs are checked at connect time, not at allowlist time.
+- Same-uid local processes reading the iron-proxy daemon's env to scrape secrets — only the env var names referenced by mappings are forwarded, not the full host env.
+- A LAN peer with a leaked sandbox proxy token spending your API quota — the proxy binds the docker bridge gateway (Linux) or loopback (Docker Desktop), never `0.0.0.0`, so it is unreachable from the external network.
+
+**What it does NOT protect against:**
+
+- A compromised host process. If the agent process itself is compromised, real keys in the host's `~/.hermes/.env` are exposed regardless. This is a defense-in-depth feature for *sandbox* compromise, not host compromise.
+- **Loss of the trusted-proxy boundary itself.** The token-swap guarantee assumes the sandbox trusts the mounted CA cert (`/etc/ssl/certs/hermes-egress-ca.crt`) and that traffic actually reaches *our* iron-proxy. If the CA private key is stolen, or sandbox egress is redirected to attacker-controlled proxy infrastructure, an adversary-in-the-middle can present a valid leaf cert and the proxy tokens are no longer a meaningful boundary (cf. [MITRE ATT&CK T1588.004](https://attack.mitre.org/techniques/T1588/004/) — obtained TLS certificate material enabling AiTM). Protect the CA key (it's `0600`, host-only) and the proxy endpoint accordingly.
+- Sandbox processes that bypass `HTTPS_PROXY` by using a raw socket. The proxy can't intercept what doesn't route to it. Node.js is partially mitigated via `NODE_OPTIONS=--use-openssl-ca` (see caveat above).
+- Credential files explicitly mounted into Docker (`terminal.credential_files` or skill-registered mounts). Egress protects provider env vars; it does not inspect arbitrary mounted files. Do not mount real provider credentials into an enforced egress sandbox.
+- Allowlisted-host data exfiltration. If `api.openai.com` is allowed, an agent could embed exfil data in a request body to that host. The daemon log captures the request happened but doesn't prevent it.
+- Uncovered providers (AWS Bedrock SigV4, GCP Vertex service-account OAuth). Their env vars stay in the sandbox; if you enable them, those credentials bypass the proxy entirely. See [Uncovered providers](#uncovered-providers).
+- iron-proxy in-memory secret zeroisation. The Go binary holds swapped-in real credentials in process memory; a core-dump or `/proc/<pid>/mem` read from a same-uid attacker would expose them. Out of scope for this layer.
+
+## Failure modes
+
+- **Binary not installed, `auto_install: true`** — first `hermes egress setup` or `hermes egress start` downloads it. SHA-256 verified against the upstream `checksums.txt`.
+- **Binary not installed, `auto_install: false`** — `start` fails with a clear message pointing to manual install.
+- **`enabled: true` but proxy not running** — with `enforce_on_docker: true` (default), Docker sandbox creation refuses to start with an explanatory error. With `enforce_on_docker: false`, it falls back to direct outbound with real creds and logs a warning.
+- **Port collision** — iron-proxy exits immediately; `hermes egress start` reports the last 20 log lines and fails with non-zero exit.
+- **Upstream-host denied** — sandbox gets HTTP 403 from the proxy with a body explaining which host wasn't allowed. The agent sees the error and reports it.
+- **Cloud metadata IP (169.254.169.254) requested** — refused by `upstream_deny_cidrs` regardless of allowlist.
+- **`docker_env` collides with a proxy-controlling var (enforce on)** — sandbox creation refuses with the names of the colliding keys.
+- **`docker_forward_env` tries to forward a protected provider key (enforce on)** — sandbox creation refuses; remove the key from `docker_forward_env` or opt out with `proxy.enforce_on_docker: false`.
+- **`docker_extra_args` overrides proxy env/network controls (enforce on)** — sandbox creation refuses; user-supplied `-e HTTPS_PROXY=...`, `--env-file`, or `--network` args run after Hermes' generated args and can bypass egress.
+- **BWS access token missing in `credential_source: bitwarden`** — `hermes egress start` refuses with `--no-bitwarden` as the recovery hint.
+- **iron-proxy doesn't bind within 5 seconds** — process is killed, pidfile unlinked, error names the port + tail of `iron-proxy.log`.
+- **Concurrent `hermes egress start` calls** — second call refuses with "another start in progress" if the first's daemon is up; otherwise the second unlinks the stale pidfile and proceeds.
+
+## Troubleshooting
+
+### "Refusing to start: BWS_ACCESS_TOKEN is not set"
+
+You enabled `credential_source: bitwarden` but the access-token env var isn't in your shell. Either:
+
+```bash
+export BWS_ACCESS_TOKEN=…   # one-shot
+hermes egress start
+```
+
+Or move it into `~/.hermes/.env`. Or switch back to env mode:
+
+```bash
+hermes egress setup --no-bitwarden
+```
+
+### "iron-proxy exited immediately"
+
+Look at the last 20 lines of `~/.hermes/proxy/iron-proxy.log`. Common causes:
+
+- Port already in use → change `proxy.tunnel_port` or kill whatever else owns 9090
+- Invalid `proxy.yaml` → run `hermes egress setup` to regenerate
+- CA cert / key permissions wrong → `chmod 0o600 ~/.hermes/proxy/ca.key`
+
+### "iron-proxy did not bind \<bind-host\>:9090 within 5s"
+
+The daemon started but never bound the listener. Usually means the binary is wedged or doing something expensive at startup. Check `~/.hermes/proxy/iron-proxy.log`. The orphan process is killed automatically and the pidfile cleaned up so you can just retry `hermes egress start`.
+
+### Sandbox times out connecting to the proxy (Linux)
+
+The container resolves `host.docker.internal` to the docker bridge gateway and the proxy is bound there, but a host firewall (commonly `ufw` with default-deny INPUT) drops container→host traffic on `docker0`. Verify from a container:
+
+```bash
+docker run --rm --add-host host.docker.internal:host-gateway busybox \
+  nc -zv -w 3 host.docker.internal 9090
+```
+
+If that times out while `hermes egress status` shows `listening`, allow the bridge subnet in your firewall, e.g. for ufw:
+
+```bash
+sudo ufw allow in on docker0 to any port 9090 proto tcp
+sudo ufw allow in on docker0 to any port 9091 proto tcp
+```
+
+(9091 = the plain-HTTP forward listener on `tunnel_port + 1`.)
+
+### Sandbox sees `HTTP 403` from the proxy
+
+The agent inside the sandbox tried to hit a host that isn't in `proxy.extra_allowed_hosts`. The 403 body explains which host. If you want to allow it, add to your config:
+
+```yaml
+proxy:
+  extra_allowed_hosts:
+    - api.example.com
+    - "*.staging.example.com"
+```
+
+Then `hermes egress setup` (to regenerate `proxy.yaml`) and `hermes egress stop && hermes egress start`.
+
+### Sandbox sees SSL verification errors
+
+Either the CA isn't mounted in the sandbox (rare; the docker backend does this automatically when `proxy.enabled: true`), or your image's HTTP client is reading from a non-standard env var.
+
+```bash
+# Inside the sandbox:
+cat /etc/ssl/certs/hermes-egress-ca.crt | head -1
+# Should print: -----BEGIN CERTIFICATE-----
+env | grep -E "^(REQUESTS|CURL|SSL|NODE).*CA"
+# Should list all four CA-bundle env vars pointing at /etc/ssl/certs/hermes-egress-ca.crt
+```
+
+If the cert isn't there, check that `proxy.enabled: true` AND `hermes egress status` shows `Listening yes`. If the env vars are missing, the sandbox image might be running an entrypoint that strips them — check your `docker_env` config.
+
+### Sandbox sees `HTTP 401` from upstreams
+
+Two common causes:
+
+1. **Token-clobber on re-setup.** You ran `hermes egress setup --rotate-tokens` (or rotated tokens some other way) and the running sandboxes still hold the old tokens. Restart the sandboxes.
+2. **Bitwarden refresh failed silently.** Should not happen with the new fail-loud behavior, but if you have `proxy.allow_env_fallback: true` set, the daemon may have started with stale env values. Check the daemon's environment (`/proc/<iron-proxy-pid>/environ`) for the expected `OPENROUTER_API_KEY` etc.
+
+### "Address in use" after the parent process died
+
+The parent Hermes process died during `hermes egress start` (Ctrl-C during the listening probe, OOM, panic). The new fix-up logic writes the pidfile immediately after `Popen` so the orphan is recoverable:
+
+```bash
+hermes egress stop   # finds the orphan via the pidfile, kills it
+hermes egress start
+```
+
+If `hermes egress stop` says "iron-proxy was not running" but you can still see the daemon in `ps`, the pidfile got out of sync. Manual recovery:
+
+```bash
+pkill -TERM iron-proxy
+rm -f ~/.hermes/proxy/iron-proxy.pid ~/.hermes/proxy/iron-proxy.nonce
+hermes egress start
+```
+
+### Inspecting per-request behavior
+
+On the pinned binary version (**v0.39**) both daemon-level events and per-request records land in `~/.hermes/proxy/iron-proxy.log`. The format is line-delimited JSON. Grep for a specific upstream:
+
+```bash
+grep '"upstream":"openrouter.ai"' ~/.hermes/proxy/iron-proxy.log | tail -20
+```
+
+Or watch in real-time:
+
+```bash
+tail -f ~/.hermes/proxy/iron-proxy.log | jq
+```
+
+When the pinned version moves to v0.40+ (which adds `log.audit_path`), per-request records will move to `~/.hermes/proxy/audit.log` and `iron-proxy.log` will hold only daemon-level events. Until that bump, `audit.log` is an empty placeholder (pre-created at `0o600` so the future daemon inherits tight permissions) — wire your logrotate / monitoring tooling to `iron-proxy.log` today and plan to add `audit.log` after the version bump.
+
+## Limitations (v1)
+
+- Docker backend only. Modal, Daytona, and SSH wiring will follow in separate PRs.
+- Providers with signature-based auth (AWS SigV4, GCP service-account OAuth) bypass the proxy entirely — see [Uncovered providers](#uncovered-providers). Header-token providers (bearer, `x-api-key`, `api-key`, `x-goog-api-key`) are all covered.
+- No native Windows binary upstream. Run on Linux / macOS / WSL.
+- The CA is a 10-year self-signed cert on first generation. Rotation requires `openssl genrsa ...` by hand (or wait for a follow-up that adds `hermes egress rotate-ca`).
+- Re-running setup stops a running daemon after rewriting config or mappings; restart (or `hermes egress reload` for ruleset-only changes) and restart already-running sandboxes after token rotation.
+- iron-proxy in-memory secret zeroisation is upstream-controlled. Same-uid attackers with `/proc/<pid>/mem` read access can read swapped-in secrets from the daemon's memory.
+- iron-proxy v0.39 only supports a **single bind per daemon** (we bind the docker bridge gateway on Linux, loopback on Docker Desktop) and combines daemon + per-request records into a single log stream. When upstream adds `proxy.http_listens` (plural) and `log.audit_path`, a version bump can wire in multi-bind and the dedicated audit stream.
+
+## See also
+
+- Upstream project: [github.com/ironsh/iron-proxy](https://github.com/ironsh/iron-proxy)
+- Upstream docs: [docs.iron.sh](https://docs.iron.sh/)
+- Bitwarden integration: [`hermes secrets bitwarden`](../secrets/bitwarden)
+- Hermes Docker terminal backend: [Docker](../docker)
+- Developer / contributor reference: [Egress proxy internals](../../developer-guide/egress-internals)
diff --git a/website/docs/user-guide/features/acp.md b/website/docs/user-guide/features/acp.md
index ccdaabc5832..4983465d2fd 100644
--- a/website/docs/user-guide/features/acp.md
+++ b/website/docs/user-guide/features/acp.md
@@ -156,6 +156,28 @@ ACP mode uses the same Hermes configuration as the CLI:
 
 Provider resolution uses Hermes' normal runtime resolver, so ACP inherits the currently configured provider and credentials. Hermes also advertises a terminal auth method (`--setup`) for first-run ACP clients; this opens Hermes' interactive model/provider setup.
 
+## Host integration
+
+These variables are set by an **ACP host process** (an editor or another agent
+harness) on the Hermes subprocess it spawns. They are not user configuration —
+do not set them by hand in `.env` or `config.yaml`.
+
+| Variable | Value | Effect |
+|----------|-------|--------|
+| `HERMES_ACP_SKIP_CONFIGURED_MCP` | `1` | Skip starting the **globally configured** MCP servers from `config.yaml` before the ACP JSON-RPC loop begins. |
+
+Hermes normally starts every MCP server configured in `config.yaml` before it
+enters the ACP JSON-RPC loop. A host that owns MCP itself — passing the
+session's servers explicitly through `session/new` — does not need that global
+startup, and an unrelated slow or interactive MCP server would otherwise delay
+`initialize`. Setting the marker to exactly `1` lets such a host skip it.
+
+Only the global `config.yaml` discovery is skipped. **MCP servers supplied by
+the ACP session through `session/new` are still registered**, so a host loses
+no capability it asked for. Any other value (unset, empty, `0`, `false`) keeps
+the default behavior, so an unrelated truthy-looking string cannot silently
+disable MCP.
+
 ## Session behavior
 
 ACP sessions are tracked by the ACP adapter's in-memory session manager while the server is running.
diff --git a/website/docs/user-guide/features/api-server.md b/website/docs/user-guide/features/api-server.md
index b67a896dd83..0311e2a228b 100644
--- a/website/docs/user-guide/features/api-server.md
+++ b/website/docs/user-guide/features/api-server.md
@@ -198,6 +198,42 @@ Delete a stored response.
 
 Lists the agent as an available model. The advertised model name defaults to the [profile](/user-guide/profiles) name (or `hermes-agent` for the default profile). Required by most frontends for model discovery.
 
+`/v1/models` is intentionally the cheap OpenAI-compat surface. It does **not**
+enumerate every authenticated provider/model combination Hermes can route to,
+and it does not do pricing or capability enrichment.
+
+### GET /api/model/options
+
+Hermes-aware clients can request the same curated provider/model inventory used
+by the dashboard and TUI. This route uses the API server's normal bearer
+authentication and returns provider rows, model capability hints, and pricing
+metadata that do not belong in the OpenAI-compatible `/v1/models` response:
+
+```bash
+curl \
+  -H "Authorization: Bearer $API_SERVER_KEY" \
+  "http://127.0.0.1:8642/api/model/options"
+```
+
+That payload is the same substrate the dashboard Models page and the TUI
+`model.options` RPC use. It returns authenticated providers, curated model
+lists, per-model pricing, and model capability hints.
+
+Normal opens are intentionally conservative for custom providers: Hermes probes
+only the **currently selected** custom endpoint so a stale or offline saved
+endpoint does not block the picker. An explicit refresh flips to full probing
+and busts the provider model cache:
+
+```bash
+curl \
+  -H "Authorization: Bearer $API_SERVER_KEY" \
+  "http://127.0.0.1:8642/api/model/options?refresh=1"
+```
+
+Use `/v1/models` when an OpenAI-compatible client only needs a model name to
+send back in chat/responses requests. Use `/api/model/options` when an
+authenticated UI needs the richer Hermes-specific picker metadata.
+
 ### GET /v1/capabilities
 
 Returns a machine-readable description of the API server's stable surface for external UIs, orchestrators, and plugin bridges.
@@ -221,6 +257,69 @@ Returns a machine-readable description of the API server's stable surface for ex
 
 Use this endpoint when integrating dashboards, browser UIs, or control planes so they can discover whether the running Hermes version supports runs, streaming, cancellation, and session continuity without depending on private Python internals.
 
+## Per-request model selection
+
+Authenticated clients can override Hermes' default model selection per request
+by sending:
+
+- `model` — the target model id for this turn
+- `provider` — the Hermes provider slug to resolve credentials/runtime for this turn
+- `model_options` — request-scoped reasoning / service-tier controls
+
+The same request fields are accepted on:
+
+- `POST /v1/chat/completions`
+- `POST /v1/responses`
+- `POST /v1/runs`
+- `POST /api/sessions/{session_id}/chat`
+- `POST /api/sessions/{session_id}/chat/stream`
+
+Precedence is deterministic:
+
+1. Session `/model` override, if that session already has one
+2. A static `gateway.platforms.api_server.model_routes` mapping selected when
+   the request's `model` is a configured route alias
+3. Direct request `model` / `provider` when no route alias matches
+4. Global gateway config / environment defaults
+
+`model_options` stays request-scoped regardless of which model/provider wins.
+If a request sends a `provider` that conflicts with a configured `model_routes`
+alias, Hermes rejects the request with `400` instead of silently remixing route
+credentials with another provider.
+
+**Bare `model` values on the OpenAI-compatible endpoints are opt-in.** Generic
+OpenAI clients routinely hardcode model names (`gpt-4o`, ...), and existing
+deployments rely on those falling back to the gateway default. On
+`POST /v1/chat/completions` and `POST /v1/responses`, a `model` value sent
+WITHOUT a `provider` is therefore ignored unless you enable:
+
+```yaml
+gateway:
+  platforms:
+    api_server:
+      direct_model_requests: true
+```
+
+Requests that include an explicit `provider` — and the Hermes-native
+`/v1/runs` and session-chat endpoints — always honor the requested model
+regardless of this flag.
+
+Example:
+
+```json
+{
+  "model": "MiniMax-M3",
+  "provider": "minimax",
+  "model_options": {
+    "reasoning_effort": "high",
+    "service_tier": "priority"
+  },
+  "messages": [
+    {"role": "user", "content": "Summarize the repo status."}
+  ]
+}
+```
+
 ### GET /health
 
 Health check. Returns `{"status": "ok"}`. Also available at **GET /v1/health** for OpenAI-compatible clients that expect the `/v1/` prefix.
@@ -521,7 +620,9 @@ In Open WebUI, add each as a separate connection. The model dropdown shows `alic
 
 - **Response storage** — stored responses (for `previous_response_id`) are persisted in SQLite and survive gateway restarts. Max 100 stored responses (LRU eviction).
 - **No file upload** — inline images are supported on both `/v1/chat/completions` and `/v1/responses`, but uploaded files (`file`, `input_file`, `file_id`) and non-image document inputs are not supported through the API.
-- **Model field is cosmetic** — the `model` field in requests is accepted but the actual LLM model used is configured server-side in config.yaml.
+- **Simple OpenAI clients still see an alias** — `/v1/models` advertises the
+  stable Hermes alias (`hermes-agent` or the active profile name). Richer
+  clients can send explicit `provider` / `model_options` overrides on requests.
 
 ## Proxy Mode
 
diff --git a/website/docs/user-guide/features/computer-use.md b/website/docs/user-guide/features/computer-use.md
index e8b00968b74..71e05b150d9 100644
--- a/website/docs/user-guide/features/computer-use.md
+++ b/website/docs/user-guide/features/computer-use.md
@@ -130,7 +130,7 @@ halo).
 
 ## Going deeper — the cua-driver skill pack
 
-Hermes intentionally keeps its skill (`skills/computer-use/SKILL.md`)
+Hermes intentionally keeps its skill (`skills/autonomous-ai-agents/computer-use/SKILL.md`)
 focused on the Hermes-side `computer_use` action vocabulary — the
 single source of truth the agent loads. For the deeper material —
 platform-specific deep dives, recording semantics, browser page
@@ -449,7 +449,7 @@ autostart pattern — see
 
 ## See also
 
-- **Hermes-side skill** — `skills/computer-use/SKILL.md` — teaches the
+- **Hermes-side skill** — `skills/autonomous-ai-agents/computer-use/SKILL.md` — teaches the
   Hermes `computer_use` action vocabulary; this is what the agent loads.
 - **cua-driver skill pack** — for platform-specific deep dives
   (macOS no-foreground contract, Windows UIA + Session 0, Linux AT-SPI
diff --git a/website/docs/user-guide/features/curator.md b/website/docs/user-guide/features/curator.md
index 0601e65fb85..2497aca61b3 100644
--- a/website/docs/user-guide/features/curator.md
+++ b/website/docs/user-guide/features/curator.md
@@ -103,6 +103,9 @@ hermes curator pause          # stop runs until resumed
 hermes curator resume
 hermes curator pin <skill>    # never auto-transition this skill
 hermes curator unpin <skill>
+hermes curator adopt <skill>    # hand an unmanaged skill to the curator
+hermes curator adopt --all-unmanaged   # hand over every unmanaged skill
+hermes curator list-unmanaged   # itemize skills with no provenance marker
 hermes curator restore <skill>  # move an archived skill back to active
 hermes curator list-archived    # list skills currently in ~/.hermes/skills/.archive/
 hermes curator archive <skill>  # manually archive a single skill now
@@ -170,6 +173,73 @@ jurisdiction — the LLM review pass is skipped and the report will show
 `Model: (not resolved) via (not resolved)` with `Duration: 0s`.
 :::
 
+### Adopting unmanaged skills
+
+`hermes curator status` reports an **unmanaged** count alongside the managed
+one:
+
+```
+curator-managed skills: 43 total  (agent-created=43  bundled=0)
+  active     41
+  stale       2
+  archived    0
+
+unmanaged (no provenance marker): 112 total
+  pre-dates marker    34
+  foreground-created  78
+  never auto-staled or archived — `hermes curator adopt <name>` hands one over
+```
+
+Those 112 are curation-*eligible* but permanently invisible to the lifecycle,
+for one of two reasons:
+
+- **pre-dates marker** — the record was written before `created_by` existed, so
+  it carries no provenance signal at all. Authorship is genuinely unknowable
+  from the record.
+- **foreground-created** — a foreground `skill_manage(create)` left the marker
+  unset by design, since skills you ask for belong to you.
+
+A large library can therefore look fully curated while most of it is
+untouchable. `adopt` closes that gap by **declaration**:
+
+```bash
+hermes curator list-unmanaged                    # itemize them, with reasons
+hermes curator adopt <name> [<name> ...]         # hand specific skills over
+hermes curator adopt --all-unmanaged --dry-run   # preview the full list
+hermes curator adopt --all-unmanaged             # hand over everything (prompts)
+hermes curator adopt --all-unmanaged --yes       # skip the prompt
+```
+
+Adoption writes the same `created_by: agent` marker the background review fork
+writes. It does **not** reset the inactivity clock — an adopted skill keeps its
+existing `last_activity_at`, so handing over a library you already stopped
+using does not buy it a fresh 90-day window. Expect adopted long-idle skills to
+go `stale` (or `archived`) on the next pass; that is the point.
+
+Adoption is also what unblocks autonomous *improvement*. The background review
+fork refuses to patch a skill that isn't curator-managed, so if it notices one
+of your skills is outdated it will say so and recommend adoption rather than
+edit it. Foreground (user-directed) edits are never affected — you and the
+agent can always edit your own skills on request.
+
+:::note `created_by` is a policy flag, not a provenance claim
+The stored field is named `created_by`, but it is consumed as "may autonomous
+curation touch this?" — not "who wrote this file". Those are different
+questions, and for records predating the marker the authorship answer is simply
+unrecoverable. The name is kept because it is already on disk in every
+`.usage.json`; read it as policy. `hermes curator adopt` changes the policy, and
+says nothing about who authored the file.
+:::
+
+:::note Provenance is declared, never inferred
+Adoption is deliberately manual. Telemetry cannot establish authorship: a skill
+with thousands of patches proves the agent **maintains** it, not that the agent
+**wrote** it — Hermes edits user-authored skills on your behalf constantly. An
+automatic "looks agent-made, adopt it" heuristic would eventually archive
+something you hand-wrote. `adopt` refuses bundled, hub-installed, external, and
+protected built-in skills, which have an owner other than you.
+:::
+
 Skills that ARE agent-created follow the full lifecycle:
 
 - `active` → (30d unused) `stale` → (90d unused) `archived`
diff --git a/website/docs/user-guide/features/image-generation.md b/website/docs/user-guide/features/image-generation.md
index 7e890382475..1eead3f0505 100644
--- a/website/docs/user-guide/features/image-generation.md
+++ b/website/docs/user-guide/features/image-generation.md
@@ -122,6 +122,19 @@ FAL models with an editing endpoint: `flux-2/klein/9b`, `flux-2-pro`,
 `krea/*`) reject image inputs with a clear error pointing you at an
 edit-capable model.
 
+:::note OpenAI (Codex auth) is best-effort
+
+The Codex surface (`chatgpt.com/backend-api/codex`) hosts `image_generation`
+as a tool the chat model may call, and Hermes cannot force the call — the
+backend rejects every `tool_choice` shape for hosted tools, so the request
+relies on instructions to steer the model. When the host model declines to
+invoke the tool, the call fails with `empty_response`. Whether the hosted
+image tool is reachable at all has also been reported to vary between
+accounts. If you need image generation to work deterministically, configure
+the **OpenAI** (API key), **FAL**, or **xAI** backend instead.
+
+:::
+
 The active model's editing capability is surfaced in the tool description at
 runtime, so the agent knows whether `image_url` will be honored before it
 calls the tool.
diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.md
index f025aea1f45..ad72afee9e0 100644
--- a/website/docs/user-guide/features/mcp.md
+++ b/website/docs/user-guide/features/mcp.md
@@ -460,6 +460,24 @@ mcp_servers:
 
 All server tools are registered except the excluded ones.
 
+### Glob patterns
+
+Both lists accept fnmatch-style globs alongside exact names — essential for
+huge flat surfaces like Cloudflare's API MCP (`?codemode=false`, ~3,300
+tools) where excluding product areas one endpoint at a time is impractical:
+
+```yaml
+mcp_servers:
+  cloudflare:
+    url: "https://mcp.cloudflare.com/mcp?codemode=false"
+    auth: oauth
+    tools:
+      exclude: ["*_radar_*", "*_accounts_dlp_*", "*_zones_web3_*"]
+```
+
+Entries without glob metacharacters (`*`, `?`, `[`) match exactly — `docs`
+excludes only the tool named `docs`, never `docs_search`.
+
 ### Precedence rule
 
 If both are present:
diff --git a/website/docs/user-guide/features/memory-providers.md b/website/docs/user-guide/features/memory-providers.md
index ea807aee488..5aedf04bc7d 100644
--- a/website/docs/user-guide/features/memory-providers.md
+++ b/website/docs/user-guide/features/memory-providers.md
@@ -70,6 +70,8 @@ hermes memory setup        # select "honcho" — runs the Honcho-specific post-s
 
 The legacy `hermes honcho setup` command still works (it now redirects to `hermes memory setup`), but is only registered after Honcho is selected as the active memory provider.
 
+**Headless / remote machines:** for cloud auth on a box without a browser (SSH, remote VM), pick **device** at the wizard's auth-method prompt. The CLI prints a short code and a verification link; open the link in a browser on any other machine, approve, and setup completes — no API key copy-paste. The wizard defaults to this option automatically when it detects no usable local browser.
+
 **Config:** `$HERMES_HOME/honcho.json` (profile-local) or `~/.honcho/config.json` (global). Resolution order: `$HERMES_HOME/honcho.json` > `~/.hermes/honcho.json` > `~/.honcho/config.json`. See the [config reference](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md) and the [Honcho integration guide](https://docs.honcho.dev/v3/guides/integrations/hermes).
 
 <details>
diff --git a/website/docs/user-guide/features/mixture-of-agents.md b/website/docs/user-guide/features/mixture-of-agents.md
index 151a066dda4..55c6d23791f 100644
--- a/website/docs/user-guide/features/mixture-of-agents.md
+++ b/website/docs/user-guide/features/mixture-of-agents.md
@@ -132,6 +132,75 @@ moa:
 
 Leave it unset (or `0`/blank) to keep the prior uncapped behavior.
 
+### Advisor cadence with `fanout`
+
+By default the advisors run **once per user turn** (`fanout: user_turn`) —
+they synthesize plan-level advice on the first message of the turn, then the
+acting aggregator works through the rest of the tool loop alone. This is the
+cheapest cadence: advisor cost does not multiply with the number of tool
+calls in a turn. Two alternative cadences trade cost for advice freshness:
+
+- `fanout: per_iteration` — advisors re-run on **every tool iteration**, so
+  their advice always tracks the latest tool results — at the cost of
+  multiplying advisor latency and spend by the number of tool calls in a
+  turn.
+- `fanout: every_n:3` — the middle ground: advisors run on the **first**
+  iteration of each user turn and then every **3rd** tool iteration (any
+  `N >= 2` works). Iterations in between reuse the cached guidance from the
+  last advisor run, so the aggregator still gets advice on every step — it is
+  just refreshed every N steps instead of every step. The counter resets on
+  each new user message, so every turn starts with fresh advice. The mapping
+  form `fanout: {mode: every_n, n: 3}` is also accepted and normalized to
+  the string form.
+
+```yaml
+moa:
+  presets:
+    fresh:
+      reference_models:
+        - provider: openrouter
+          model: anthropic/claude-opus-4.8
+      aggregator:
+        provider: openrouter
+        model: openai/gpt-5.5
+      fanout: per_iteration   # advisors refresh on every tool iteration
+```
+
+Unknown or malformed values fall back to `user_turn`.
+
+:::note Default change
+Prior to July 2026 the default cadence was `per_iteration`. The default is
+now `user_turn` — the cheapest, lowest-impact cadence — until per-mode
+benchmarks justify a costlier default. Presets that want per-step advising
+back set `fanout: per_iteration` explicitly.
+:::
+
+### Privacy filter for advisor outputs
+
+Advisor outputs can echo sensitive data from the conversation — emails,
+formatted phone numbers, API keys, JWTs — into the reference blocks shown in
+the UI, saved MoA traces, and the aggregator prompt. `moa.privacy_filter`
+(off by default) redacts those surfaces:
+
+```yaml
+moa:
+  privacy_filter: display   # or: full
+```
+
+- `display` — redacts **user-visible surfaces only**: the labelled reference
+  blocks rendered in the UI and the records written by `save_traces`. The
+  aggregator still receives the raw advisor text, so answer quality is
+  unaffected.
+- `full` — additionally redacts the advisor text injected into the
+  aggregator prompt (and the one-shot `/moa` synthesis input).
+
+Credential shapes (API-key prefixes, JWTs, private keys, DB connection
+strings) are masked by Hermes' central secret redactor; the MoA filter adds
+email and clearly formatted phone-number redaction on top. Patterns are
+deliberately conservative for code-review-style advice: bare digit runs, line
+numbers, timestamps, git SHAs, and IP addresses are never touched — only
+delimited phone formats like `(555) 123-4567` or `555-123-4567` match.
+
 ### Per-slot reasoning effort
 
 Reference and aggregator slots may also set `reasoning_effort`. Use this when
diff --git a/website/docs/user-guide/features/pets.md b/website/docs/user-guide/features/pets.md
index e2b0bbe65d5..de082f36c8a 100644
--- a/website/docs/user-guide/features/pets.md
+++ b/website/docs/user-guide/features/pets.md
@@ -206,5 +206,6 @@ Common gotchas:
 
 ## See also
 
-- The [`petdex` skill](../skills/bundled/productivity/productivity-petdex.md)
-  lets the agent install and switch pets for you on request.
+- The [`hermes-agent` skill](../skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md)
+  lets the agent install and switch pets for you on request (see its
+  `references/petdex.md`).
diff --git a/website/docs/user-guide/features/tool-search.md b/website/docs/user-guide/features/tool-search.md
index 726cbbc1728..ebb9b9d8760 100644
--- a/website/docs/user-guide/features/tool-search.md
+++ b/website/docs/user-guide/features/tool-search.md
@@ -55,19 +55,20 @@ see the underlying tool, not the bridge.
 
 ## When does it activate?
 
-By default Tool Search runs in `auto` mode: it activates only when the
-deferrable tool schemas would consume at least 10% of the active model's
-context window. Below that, the tools-array assembly is a pure
-pass-through and you pay no overhead.
+Tool Search uses **tiered disclosure**: the presence of *any* deferrable
+(MCP/plugin) tool activates the bridge; what scales with catalog size is
+how much of the catalog stays visible, not whether schemas defer.
 
-This decision is re-evaluated every time the tools array is built, so:
+| Tier | Condition | What the model sees |
+| --- | --- | --- |
+| **0** | No MCP/plugin tools | Every tool eager, no bridge. Pass-through. |
+| **1** | Deferred catalog's listing fits the budget | Bridge + a skills-style manifest of every deferred tool (name + short description, degrading to names-only when over budget). Degradation is **per server**: when one oversized server (Cloudflare) is attached alongside small ones (Linear), the small servers keep their per-tool listings and only the oversized server collapses to a summary line. |
+| **2** | Per-tool listing exceeds the budget even names-only for every server (e.g. Cloudflare's flat API surface alone: ~3,300 tools whose names are ~32K tokens) | Bare bridge + a one-line-per-server summary (server name + tool count), so the model knows which domains are reachable; individual tools are discoverable only through `tool_search`. |
 
-- A session with just a few MCP tools and a long context model never
-  activates Tool Search.
-- A session with many MCP servers attached (15+ tools typically) starts
-  activating it.
-- Removing MCP servers mid-session correctly returns to direct exposure
-  on the next assembly.
+The listing budget is `min(threshold_pct% of context, listing_max_tokens)`.
+The decision is re-evaluated every time the tools array is built, so
+adding or removing MCP servers mid-session moves the session between
+tiers on the next assembly.
 
 ## Configuration
 
@@ -75,17 +76,32 @@ This decision is re-evaluated every time the tools array is built, so:
 tools:
   tool_search:
     enabled: auto       # auto (default), on, or off
-    threshold_pct: 10   # percentage of context — only used in auto mode
+    threshold_pct: 5    # listing budget as a percentage of context
     search_default_limit: 5
     max_search_limit: 20
+    listing: auto       # embed a grouped name+description catalog manifest
+    listing_max_tokens: 20000
 ```
 
 | Key | Default | Meaning |
 | --- | --- | --- |
-| `enabled` | `auto` | `auto` activates above threshold; `on` always activates if there's at least one deferrable tool; `off` disables entirely. |
-| `threshold_pct` | `10` | Percentage of context length at which `auto` mode kicks in. Range 0–100. |
+| `enabled` | `auto` | `auto`/`on` activate whenever at least one deferrable tool exists; `off` disables entirely (everything stays eager). |
+| `threshold_pct` | `5` | Listing budget as a percentage of the active model's context length. Range 0–100. |
 | `search_default_limit` | `5` | Hits returned when the model calls `tool_search` without a `limit`. |
 | `max_search_limit` | `20` | Hard upper bound the model can request via `limit`. Range 1–50. |
+| `listing` | `auto` | Embed a skills-style manifest of every deferred tool (name + first sentence of its description, ≤60 chars, grouped by MCP server) in the `tool_search` bridge description. `auto` includes it when it fits the budget (falling back to names-only, then to the tier-2 server summary); `on`/`off` force either way. |
+| `listing_max_tokens` | `20000` | Absolute cap on the embedded listing, regardless of context size. Range 200–60000. |
+
+### Why the listing exists
+
+Without it, deferred capabilities are *invisible* — live benchmarking showed
+models substituting visible core tools (running `gh` in the terminal instead
+of searching for the deferred GitHub tool) or declaring a capability
+nonexistent instead of calling `tool_search`. The listing applies the skills
+pattern to tools: every capability stays discoverable by name at all times,
+while full parameter schemas remain deferred. If the model sees the exact
+tool name in the listing, it can skip `tool_search` and go straight to
+`tool_describe`, saving a round trip.
 
 You can also flip the legacy boolean shape:
 
@@ -97,13 +113,15 @@ tools:
 ## When NOT to use it
 
 Tool Search trades a fixed per-turn token cost (the three bridge tool
-schemas, ~300 tokens) and at least one extra round trip (search →
-describe → call) for the savings on the deferred schemas. It's a clear
-win when you have many tools and use few per turn; it's overhead when
-you have few tools total.
+schemas plus the catalog listing) and at least one extra round trip on
+cold tools (describe → call) for the savings on the deferred schemas.
+At tier 1 the listing keeps every capability visible, so the discovery
+round trip usually disappears — the model goes straight to
+`tool_describe`. Live benchmarking showed the listing mode matching
+eager loading's task success while costing less than the bare bridge.
 
-The `auto` default handles this for you. If you set `enabled: on`
-unconditionally, expect a slight per-turn cost on small toolsets.
+If you want the old always-eager behavior for a small toolset, set
+`enabled: off`.
 
 ## Trade-offs that don't go away
 
diff --git a/website/docs/user-guide/features/x-search.md b/website/docs/user-guide/features/x-search.md
index bdfeeeba095..7b8271d9ae5 100644
--- a/website/docs/user-guide/features/x-search.md
+++ b/website/docs/user-guide/features/x-search.md
@@ -11,6 +11,17 @@ The `x_search` tool lets the agent search X (Twitter) posts, profiles, and threa
 
 **Use this instead of `web_search`** when you specifically want current discussion, reactions, or claims **on X**. For general web pages, keep using `web_search` / `web_extract`.
 
+## `x_search` vs `xurl`
+
+Hermes can expose two different X surfaces:
+
+| Surface | Use it for | Do not use it for |
+|---------|------------|-------------------|
+| `x_search` | Read-only public X discovery: current discussion, reactions, claims, profiles, threads, and synthesized answers with citations. | Posting, replying, liking, DMs, media upload, deleting, or proving that an authenticated X account changed state. |
+| `xurl` skill | Exact or authenticated X API work: `post`, `reply`, `read`, `like`, `dm`, timelines, mentions, media upload, account-specific reads, and raw v2 endpoints. | Broad Grok-synthesized public X research when `x_search` is available and no authenticated account context is needed. |
+
+For mixed workflows, use `x_search` to discover candidate public posts, then switch to `xurl read` or another exact `xurl` command after the target post/user/action is clear. Any state-changing X action must be confirmed by `xurl` output or the X API response; an `x_search` answer is never evidence that a write happened.
+
 :::tip
 If you're paying Portal for an xAI model anyway, Live Search calls bill against the same xAI key configured for chat. See [Nous Portal](/integrations/nous-portal).
 :::
@@ -119,6 +130,8 @@ The agent will:
 2. Get back a synthesized answer plus a list of citations linking to specific posts
 3. Reply with the answer and references
 
+If the next user request is "reply to the best one" or "like that post", the agent should switch to the `xurl` skill, confirm the exact target post, and use the X API action. `x_search` remains a discovery tool.
+
 ## Troubleshooting
 
 ### "No xAI credentials available"
@@ -149,5 +162,6 @@ Causes worth checking:
 ## See Also
 
 - [xAI Grok OAuth (SuperGrok / Premium+)](../../guides/xai-grok-oauth.md) — the OAuth setup guide
+- [xurl skill](../skills/bundled/social-media/social-media-xurl.md) — official X API CLI for authenticated account actions
 - [Web Search & Extract](web-search.md) — for general (non-X) web search
 - [Tools Reference](../../reference/tools-reference.md) — full tool catalog
diff --git a/website/docs/user-guide/sessions.md b/website/docs/user-guide/sessions.md
index daece81f482..50e52363171 100644
--- a/website/docs/user-guide/sessions.md
+++ b/website/docs/user-guide/sessions.md
@@ -392,7 +392,7 @@ hermes sessions export --format md --model sonnet --min-messages 50 --redact
 hermes sessions export --format md --session-id 20250305_091523_a1b2c3d4 --delete-after-verified --yes
 ```
 
-Markdown/QMD export writes one `.md` or `.qmd` file per exported session plus a `manifest.jsonl` with the file path, message count, lineage ids, and SHA-256. Bulk export requires at least one filter; a bare bulk export is refused. `--delete-after-verified` is intentionally limited to `--session-id` and requires `--yes`. `--redact` scrubs secrets (API keys, tokens, credentials) from message content and tool output before writing — recommended for any export you plan to share.
+Markdown/QMD export writes one `.md` or `.qmd` file per exported session plus a `manifest.jsonl` with the file path, message count, lineage ids, and SHA-256. Bulk export requires at least one filter; a bare bulk export is refused. `--delete-after-verified` is intentionally limited to `--session-id` and requires `--yes`. Because deleting a parent session also removes its delegate/subagent sessions, this mode exports and verifies each delegate in a separate file before deleting anything. If the delegate set changes during export, deletion is refused. `--redact` scrubs secrets (API keys, tokens, credentials) from message content and tool output before writing — recommended for any export you plan to share.
 
 ### Delete a Session
 
diff --git a/website/docs/user-guide/skills/bundled/computer-use/computer-use-computer-use.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md
similarity index 99%
rename from website/docs/user-guide/skills/bundled/computer-use/computer-use-computer-use.md
rename to website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md
index 63ea92a9336..44e28074fbf 100644
--- a/website/docs/user-guide/skills/bundled/computer-use/computer-use-computer-use.md
+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md
@@ -19,11 +19,10 @@ whenever the `computer_use` tool is available.
 | | |
 |---|---|
 | Source | Bundled (installed by default) |
-| Path | `skills/computer-use` |
+| Path | `skills/autonomous-ai-agents/computer-use` |
 | Version | `2.0.0` |
 | Platforms | macos, windows, linux |
 | Tags | `computer-use`, `desktop`, `automation`, `gui`, `cross-platform` |
-| Related skills | `browser` |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
index 2dde2ad9d12..ed894fba0bf 100644
--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
@@ -1,14 +1,14 @@
 ---
-title: "Hermes Agent — Configure, extend, or contribute to Hermes Agent"
+title: "Hermes Agent — Use, configure, theme, extend, and orchestrate Hermes Agent"
 sidebar_label: "Hermes Agent"
-description: "Configure, extend, or contribute to Hermes Agent"
+description: "Use, configure, theme, extend, and orchestrate Hermes Agent"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Hermes Agent
 
-Configure, extend, or contribute to Hermes Agent.
+Use, configure, theme, extend, and orchestrate Hermes Agent.
 
 ## Skill metadata
 
@@ -16,11 +16,11 @@ Configure, extend, or contribute to Hermes Agent.
 |---|---|
 | Source | Bundled (installed by default) |
 | Path | `skills/autonomous-ai-agents/hermes-agent` |
-| Version | `2.1.0` |
+| Version | `3.1.0` |
 | Author | Hermes Agent + Teknium |
 | License | MIT |
 | Platforms | linux, macos, windows |
-| Tags | `hermes`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `development` |
+| Tags | `hermes`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `themes`, `skins`, `desktop-plugins`, `tui-widgets`, `petdex`, `development` |
 | Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |
 
 ## Reference: full SKILL.md
@@ -31,529 +31,98 @@ The following is the complete skill definition that Hermes loads when this skill
 
 # Hermes Agent
 
-Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, messaging platforms, and IDEs. It belongs to the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, DeepSeek, local models, and 15+ others) and runs on Linux, macOS, and WSL.
+Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, messaging platforms, and IDEs. It's in the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, local models, and 20+ others) and runs on Linux, macOS, Windows, and WSL.
 
 What makes Hermes different:
 
-- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment.
-- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works.
-- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, and 10+ other platforms with full tool access, not just chat.
-- **Provider-agnostic** — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically.
+- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills that load into future sessions.
+- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends.
+- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat.
+- **Many surfaces** — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains).
+- **Provider-agnostic** — swap models and providers mid-workflow; credential pools rotate across multiple API keys automatically.
 - **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
-- **Extensible** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem.
+- **Extensible & themeable** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, skins that theme every surface, desktop UI plugins, TUI widgets, and pet mascots.
 
-People use Hermes for software development, research, system administration, data analysis, content creation, home automation, and anything else that benefits from an AI agent with persistent context and full system access.
-
-**This skill helps you work with Hermes Agent effectively** — setting it up, configuring features, spawning additional agent instances, troubleshooting issues, finding the right commands and settings, and understanding how the system works when you need to extend or contribute to it.
+**This skill is a hub.** The body covers identity, quick start, spawning/orchestration, and hard invariants. Everything else lives in reference files — **load the matching reference (below) before answering**; do not answer detail questions from the body alone.
 
 **Docs:** https://hermes-agent.nousresearch.com/docs/
 
+## Scope & Verification
+
+This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.
+
+Good verification targets:
+
+- CLI commands: `hermes --help`, `hermes <command> --help`, and `hermes_cli/main.py`
+- User documentation: https://hermes-agent.nousresearch.com/docs/
+- Source tree: https://github.com/NousResearch/hermes-agent
+
 ## Quick Start
 
 ```bash
-# Install
+# Install (shell installer — sets up uv, Python, the venv, and the launcher)
 curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
 
-# Interactive chat (default)
+# Interactive chat (default surface; set display.interface: tui to launch the Ink TUI instead)
 hermes
 
 # Single query
 hermes chat -q "What is the capital of France?"
 
-# Setup wizard
+# Setup wizard  /  pick model+provider  /  health check
 hermes setup
-
-# Change model/provider
 hermes model
-
-# Check health
 hermes doctor
+
+# Other surfaces
+hermes desktop                 # launch the native desktop app (alias: hermes gui)
+hermes dashboard               # web admin panel + embedded chat
+hermes proxy                   # OpenAI-compatible local proxy backed by your OAuth provider
 ```
 
----
-
-## CLI Reference
-
-### Global Flags
+## Key Paths
 
 ```
-hermes [flags] [command]
-
-  --version, -V             Show version
-  --resume, -r SESSION      Resume session by ID or title
-  --continue, -c [NAME]     Resume by name, or most recent session
-  --worktree, -w            Isolated git worktree mode (parallel agents)
-  --skills, -s SKILL        Preload skills (comma-separate or repeat)
-  --profile, -p NAME        Use a named profile
-  --yolo                    Skip dangerous command approval
-  --pass-session-id         Include session ID in system prompt
-```
-
-No subcommand defaults to `chat`.
-
-### Chat
-
-```
-hermes chat [flags]
-  -q, --query TEXT          Single query, non-interactive
-  -m, --model MODEL         Model (e.g. anthropic/claude-sonnet-4)
-  -t, --toolsets LIST       Comma-separated toolsets
-  --provider PROVIDER       Force provider (openrouter, anthropic, nous, etc.)
-  -v, --verbose             Verbose output
-  -Q, --quiet               Suppress banner, spinner, tool previews
-  --checkpoints             Enable filesystem checkpoints (/rollback)
-  --source TAG              Session source tag (default: cli)
-```
-
-### Configuration
-
-```
-hermes setup [section]      Interactive wizard (model|terminal|gateway|tools|agent)
-hermes model                Interactive model/provider picker
-hermes config               View current config
-hermes config edit          Open config.yaml in $EDITOR
-hermes config set KEY VAL   Set a config value
-hermes config path          Print config.yaml path
-hermes config env-path      Print .env path
-hermes config check         Check for missing/outdated config
-hermes config migrate       Update config with new options
-hermes auth                 Interactive credential manager
-hermes auth add PROVIDER    Add OAuth or API-key credential (e.g. nous, openai-codex, qwen-oauth)
-hermes auth list            List stored credentials
-hermes auth remove PROVIDER Remove a stored credential
-hermes doctor [--fix]       Check dependencies and config
-hermes status [--all]       Show component status
-```
-
-### Tools & Skills
-
-```
-hermes tools                Interactive tool enable/disable (curses UI)
-hermes tools list           Show all tools and status
-hermes tools enable NAME    Enable a toolset
-hermes tools disable NAME   Disable a toolset
-
-hermes skills list          List installed skills
-hermes skills search QUERY  Search the skills hub
-hermes skills install ID    Install a skill (ID can be a hub identifier OR a direct https://…/SKILL.md URL; pass --name to override when frontmatter has no name)
-hermes skills inspect ID    Preview without installing
-hermes skills config        Enable/disable skills per platform
-hermes skills check         Check for updates
-hermes skills update        Update outdated skills
-hermes skills uninstall N   Remove a hub skill
-hermes skills publish PATH  Publish to registry
-hermes skills browse        Browse all available skills
-hermes skills tap add REPO  Add a GitHub repo as skill source
-```
-
-### MCP Servers
-
-```
-hermes mcp serve            Run Hermes as an MCP server
-hermes mcp add NAME         Add an MCP server (--url or --command)
-hermes mcp remove NAME      Remove an MCP server
-hermes mcp list             List configured servers
-hermes mcp test NAME        Test connection
-hermes mcp configure NAME   Toggle tool selection
-```
-
-How the built-in MCP client connects servers (stdio/HTTP), auto-discovers
-their tools, and exposes them as first-class tools, plus catalog install
-(`hermes mcp install <name>`): `skill_view(name="hermes-agent", file_path="references/native-mcp.md")`.
-
-### Gateway (Messaging Platforms)
-
-```
-hermes gateway run          Start gateway foreground
-hermes gateway install      Install as background service
-hermes gateway start/stop   Control the service
-hermes gateway restart      Restart the service
-hermes gateway status       Check status
-hermes gateway setup        Configure platforms
-```
-
-Supported platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, Matrix, Mattermost, Home Assistant, DingTalk, Feishu, WeCom, BlueBubbles (iMessage), Weixin (WeChat), API Server, Webhooks. Open WebUI connects via the API Server adapter.
-
-Platform docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/
-
-### Sessions
-
-```
-hermes sessions list        List recent sessions
-hermes sessions browse      Interactive picker
-hermes sessions export OUT  Export to JSONL
-hermes sessions rename ID T Rename a session
-hermes sessions delete ID   Delete a session
-hermes sessions prune       Clean up old sessions (--older-than N days)
-hermes sessions stats       Session store statistics
-```
-
-### Cron Jobs
-
-```
-hermes cron list            List jobs (--all for disabled)
-hermes cron create SCHED    Create: '30m', 'every 2h', '0 9 * * *'
-hermes cron edit ID         Edit schedule, prompt, delivery
-hermes cron pause/resume ID Control job state
-hermes cron run ID          Trigger on next tick
-hermes cron remove ID       Delete a job
-hermes cron status          Scheduler status
-```
-
-### Webhooks
-
-```
-hermes webhook subscribe N  Create route at /webhooks/<name>
-hermes webhook list         List subscriptions
-hermes webhook remove NAME  Remove a subscription
-hermes webhook test NAME    Send a test POST
-```
-
-Full setup, route config, payload templating, and event-driven agent-run
-patterns: `skill_view(name="hermes-agent", file_path="references/webhooks.md")`.
-
-### Profiles
-
-```
-hermes profile list         List all profiles
-hermes profile create NAME  Create (--clone, --clone-all, --clone-from)
-hermes profile use NAME     Set sticky default
-hermes profile delete NAME  Delete a profile
-hermes profile show NAME    Show details
-hermes profile alias NAME   Manage wrapper scripts
-hermes profile rename A B   Rename a profile
-hermes profile export NAME  Export to tar.gz
-hermes profile import FILE  Import from archive
-```
-
-### Credential Pools
-
-```
-hermes auth add             Interactive credential wizard
-hermes auth list [PROVIDER] List pooled credentials
-hermes auth remove P INDEX  Remove by provider + index
-hermes auth reset PROVIDER  Clear exhaustion status
-```
-
-### Other
-
-```
-hermes insights [--days N]  Usage analytics
-hermes update               Update to latest version
-hermes pairing list/approve/revoke  DM authorization
-hermes plugins list/install/remove  Plugin management
-hermes honcho setup/status  Honcho memory integration (requires honcho plugin)
-hermes memory setup/status/off  Memory provider config
-hermes completion bash|zsh  Shell completions
-hermes acp                  ACP server (IDE integration)
-hermes claw migrate         Migrate from OpenClaw
-hermes uninstall            Uninstall Hermes
-```
-
----
-
-## Slash Commands (In-Session)
-
-Type these during an interactive chat session. New commands land fairly
-often; if something below looks stale, run `/help` in-session for the
-authoritative list or see the [live slash commands reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands).
-The registry of record is `hermes_cli/commands.py` — every consumer
-(autocomplete, Telegram menu, Slack mapping, `/help`) derives from it.
-
-### Session Control
-```
-/new (/reset)        Fresh session
-/clear               Clear screen + new session (CLI)
-/retry               Resend last message
-/undo                Remove last exchange
-/title [name]        Name the session
-/compress            Manually compress context
-/stop                Kill background processes
-/rollback [N]        Restore filesystem checkpoint
-/snapshot [sub]      Create or restore state snapshots of Hermes config/state (CLI)
-/background <prompt> Run prompt in background
-/queue <prompt>      Queue for next turn
-/steer <prompt>      Inject a message after the next tool call without interrupting
-/agents (/tasks)     Show active agents and running tasks
-/resume [name]       Resume a named session
-/goal [text|sub]     Set a standing goal Hermes works on across turns until achieved
-                     (subcommands: status, pause, resume, clear)
-/redraw              Force a full UI repaint (CLI)
-```
-
-### Configuration
-```
-/config              Show config (CLI)
-/model [name]        Show or change model
-/personality [name]  Set personality
-/reasoning [level]   Set reasoning (none|minimal|low|medium|high|xhigh|max|ultra|show|hide)
-/verbose             Cycle: off → new → all → verbose
-/voice [on|off|tts]  Voice mode
-/yolo                Toggle approval bypass
-/busy [sub]          Control what Enter does while Hermes is working (CLI)
-                     (subcommands: queue, steer, interrupt, status)
-/indicator [style]   Pick the TUI busy-indicator style (CLI)
-                     (styles: kaomoji, emoji, unicode, ascii)
-/footer [on|off]     Toggle gateway runtime-metadata footer on final replies
-/skin [name]         Change theme (CLI)
-/statusbar           Toggle status bar (CLI)
-```
-
-### Tools & Skills
-```
-/tools               Manage tools (CLI)
-/toolsets            List toolsets (CLI)
-/skills              Search/install skills (CLI)
-/skill <name>        Load a skill into session
-/reload-skills       Re-scan ~/.hermes/skills/ for added/removed skills
-/reload              Reload .env variables into the running session (CLI)
-/reload-mcp          Reload MCP servers
-/cron                Manage cron jobs (CLI)
-/curator [sub]       Background skill maintenance (status, run, pin, archive, …)
-/kanban [sub]        Multi-profile collaboration board (tasks, links, comments)
-/plugins             List plugins (CLI)
-```
-
-### Gateway
-```
-/approve             Approve a pending command (gateway)
-/deny                Deny a pending command (gateway)
-/restart             Restart gateway (gateway)
-/sethome             Set current chat as home channel (gateway)
-/update              Update Hermes to latest (gateway)
-/topic [sub]         Enable or inspect Telegram DM topic sessions (gateway)
-/platforms (/gateway) Show platform connection status (gateway)
-```
-
-### Utility
-```
-/branch (/fork)      Branch the current session
-/fast                Toggle priority/fast processing
-/browser             Open CDP browser connection
-/history             Show conversation history (CLI)
-/save                Save conversation to file (CLI)
-/copy [N]            Copy the last assistant response to clipboard (CLI)
-/paste               Attach clipboard image (CLI)
-/image               Attach local image file (CLI)
-```
-
-### Info
-```
-/help                Show commands
-/commands [page]     Browse all commands (gateway)
-/usage               Token usage
-/insights [days]     Usage analytics
-/status              Session info (gateway)
-/profile             Active profile info
-/debug               Upload debug report (system info + logs) and get shareable links
-```
-
-### Exit
-```
-/quit (/exit, /q)    Exit CLI
-```
-
----
-
-## Key Paths & Config
-
-```
-~/.hermes/config.yaml       Main configuration
-~/.hermes/.env              API keys and secrets (under $HERMES_HOME if set)
+~/.hermes/config.yaml       Main configuration (settings — never secrets)
+~/.hermes/.env              API keys and secrets ONLY (under $HERMES_HOME if set)
 $HERMES_HOME/skills/        Installed skills
-~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts (and optional per-session JSON snapshots when sessions.write_json_snapshots: true)
+~/.hermes/skins/            Custom themes (see references/themes.md)
+~/.hermes/desktop-plugins/  Desktop app UI plugins (see references/desktop-plugins.md)
+~/.hermes/tui-widgets/      TUI widget apps (see references/tui-widgets.md)
+~/.hermes/pets/             Installed pet mascots (see references/petdex.md)
 ~/.hermes/state.db          Canonical session store (SQLite + FTS5)
+~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts
 ~/.hermes/logs/             Gateway and error logs
 ~/.hermes/auth.json         OAuth tokens and credential pools
 ~/.hermes/hermes-agent/     Source code (if git-installed)
 ```
 
-Profiles use `~/.hermes/profiles/<name>/` with the same layout.
+Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile is active, resolve the real home from `$HERMES_HOME` — never hardcode `~/.hermes`.
 
-### Config Sections
+## Routing Table — load the reference for the task
 
-Edit with `hermes config edit` or `hermes config set section.key value`.
+| User wants... | Load |
+|---|---|
+| CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` |
+| In-session slash commands | `references/slash-commands.md` |
+| Provider setup, API keys, OAuth | `references/providers-and-models.md` |
+| config.yaml sections, toolsets, voice/STT/TTS | `references/configuration.md` |
+| AGENTS.md / .hermes.md / CLAUDE.md project rules | `references/project-context-files.md` |
+| Secret redaction, PII, approval modes, "reset permissions" | `references/security-privacy.md` |
+| Delegation, cron, curator, kanban | `references/background-systems.md` |
+| MCP servers (add, catalog, `hermes mcp`) | `references/native-mcp.md` |
+| Webhook routes and event-driven runs | `references/webhooks.md` |
+| A custom theme/skin ("synthwave theme", "change the gold ●") | `references/themes.md` + `templates/skin.yaml` |
+| A desktop app UI element (pane, widget, ⌘K command, page) | `references/desktop-plugins.md` + `templates/plugin.js` |
+| A live TUI panel or modal widget (ticker, clock, dashboard) | `references/tui-widgets.md` + `templates/clock.mjs` |
+| Pet mascots — install, select, scale, diagnose | `references/petdex.md` |
+| Windows-specific issues (keybinds, WinError 10106, BOM) | `references/windows-quirks.md` |
+| Debugging: voice, tools missing, gateway, aux models | `references/troubleshooting.md` |
+| Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` |
+| delegate_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` |
+| "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` |
 
-| Section | Key options |
-|---------|-------------|
-| `model` | `default`, `provider`, `base_url`, `api_key`, `context_length` (explicit override; clear to `""` for auto-detect from server `/v1/models`) |
-| `agent` | `max_turns` (90), `tool_use_enforcement` |
-| `terminal` | `backend` (local/docker/ssh/modal), `cwd`, `timeout` (180) |
-| `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) |
-| `display` | `skin`, `tool_progress`, `show_reasoning`, `show_cost` |
-| `stt` | `enabled`, `provider` (local/groq/openai/mistral) |
-| `tts` | `provider` (edge/elevenlabs/openai/minimax/mistral/neutts) |
-| `memory` | `memory_enabled`, `user_profile_enabled`, `provider` |
-| `security` | `tirith_enabled`, `website_blocklist` |
-| `delegation` | `model`, `provider`, `base_url`, `api_key`, `max_iterations` (50), `reasoning_effort` |
-| `checkpoints` | `enabled`, `max_snapshots` (50) |
-
-Full config reference: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
-
-### Providers
-
-20+ providers supported. Set via `hermes model` or `hermes setup`.
-
-| Provider | Auth | Key env var |
-|----------|------|-------------|
-| OpenRouter | API key | `OPENROUTER_API_KEY` |
-| Anthropic | API key | `ANTHROPIC_API_KEY` |
-| Nous Portal | OAuth | `hermes auth` |
-| OpenAI Codex | OAuth | `hermes auth` |
-| GitHub Copilot | Token | `COPILOT_GITHUB_TOKEN` |
-| Google Gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
-| DeepSeek | API key | `DEEPSEEK_API_KEY` |
-| xAI / Grok | API key | `XAI_API_KEY` |
-| Hugging Face | Token | `HF_TOKEN` |
-| Z.AI / GLM | API key | `GLM_API_KEY` |
-| MiniMax | API key | `MINIMAX_API_KEY` |
-| MiniMax CN | API key | `MINIMAX_CN_API_KEY` |
-| Kimi / Moonshot | API key | `KIMI_API_KEY` |
-| Alibaba / DashScope | API key | `DASHSCOPE_API_KEY` |
-| Xiaomi MiMo | API key | `XIAOMI_API_KEY` |
-| Kilo Code | API key | `KILOCODE_API_KEY` |
-| OpenCode Zen | API key | `OPENCODE_ZEN_API_KEY` |
-| OpenCode Go | API key | `OPENCODE_GO_API_KEY` |
-| Qwen OAuth | OAuth | `hermes auth add qwen-oauth` |
-| Custom endpoint | Config | `model.base_url` + `model.api_key` in config.yaml |
-| GitHub Copilot ACP | External | `COPILOT_CLI_PATH` or Copilot CLI |
-
-Full provider docs: https://hermes-agent.nousresearch.com/docs/integrations/providers
-
-### Toolsets
-
-Enable/disable via `hermes tools` (interactive) or `hermes tools enable/disable NAME`.
-
-| Toolset | What it provides |
-|---------|-----------------|
-| `web` | Web search and content extraction |
-| `search` | Web search only (subset of `web`) |
-| `browser` | Browser automation (Browserbase, Camofox, or local Chromium) |
-| `terminal` | Shell commands and process management |
-| `file` | File read/write/search/patch |
-| `code_execution` | Sandboxed Python execution |
-| `vision` | Image analysis |
-| `image_gen` | AI image generation |
-| `video` | Video analysis and generation |
-| `tts` | Text-to-speech |
-| `skills` | Skill browsing and management |
-| `memory` | Persistent cross-session memory |
-| `session_search` | Search past conversations |
-| `delegation` | Subagent task delegation |
-| `cronjob` | Scheduled task management |
-| `clarify` | Ask user clarifying questions |
-| `messaging` | Cross-platform message sending |
-| `todo` | In-session task planning and tracking |
-| `kanban` | Multi-agent work-queue tools (gated to workers) |
-| `debugging` | Extra introspection/debug tools (off by default) |
-| `safe` | Minimal, low-risk toolset for locked-down sessions |
-| `spotify` | Spotify playback and playlist control |
-| `homeassistant` | Smart home control (off by default) |
-| `discord` | Discord integration tools |
-| `discord_admin` | Discord admin/moderation tools |
-| `feishu_doc` | Feishu (Lark) document tools |
-| `feishu_drive` | Feishu (Lark) drive tools |
-| `yuanbao` | Yuanbao integration tools |
-| `rl` | Reinforcement learning tools (off by default) |
-
-Full enumeration lives in `toolsets.py` as the `TOOLSETS` dict; `_HERMES_CORE_TOOLS` is the default bundle most platforms inherit from.
-
-Tool changes take effect on `/reset` (new session). They do NOT apply mid-conversation to preserve prompt caching.
-
----
-
-## Security & Privacy Toggles
-
-Common "why is Hermes doing X to my output / tool calls / commands?" toggles — and the exact commands to change them. Most of these need a fresh session (`/reset` in chat, or start a new `hermes` invocation) because they're read once at startup.
-
-### Secret redaction in tool output
-
-Secret redaction is **on by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) is scanned for strings that look like API keys, tokens, and secrets before it enters the conversation context and logs. Leave it enabled for normal use:
-
-```bash
-hermes config set security.redact_secrets true       # keep enabled globally
-```
-
-**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=false` from a tool call) will NOT take effect for the running process. Tell the user to change it in config from a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task.
-
-Disable only when you deliberately need raw credential-like strings for debugging or redactor development:
-```bash
-hermes config set security.redact_secrets false
-```
-
-### PII redaction in gateway messages
-
-Separate from secret redaction. When enabled, the gateway hashes user IDs and strips phone numbers from the session context before it reaches the model:
-
-```bash
-hermes config set privacy.redact_pii true    # enable
-hermes config set privacy.redact_pii false   # disable (default)
-```
-
-### Command approval prompts
-
-By default (`approvals.mode: smart`), Hermes asks an auxiliary LLM to assess shell commands flagged as destructive (`rm -rf`, `git reset --hard`, etc.). The modes are:
-
-- `smart` — auto-approve a low-risk command once, deny high-risk commands, and prompt when uncertain (default)
-- `manual` — always prompt
-- `off` — skip all approval prompts (equivalent to `--yolo`)
-
-```bash
-hermes config set approvals.mode smart       # recommended middle ground
-hermes config set approvals.mode off         # bypass everything (not recommended)
-```
-
-Per-invocation bypass without changing config:
-- `hermes --yolo …`
-- `export HERMES_YOLO_MODE=1`
-
-Note: YOLO / `approvals.mode: off` does NOT turn off secret redaction. They are independent.
-
-### Shell hooks allowlist
-
-Some shell-hook integrations require explicit allowlisting before they fire. Managed via `~/.hermes/shell-hooks-allowlist.json` — prompted interactively the first time a hook wants to run.
-
-### Disabling the web/browser/image-gen tools
-
-To keep the model away from network or media tools entirely, open `hermes tools` and toggle per-platform. Takes effect on next session (`/reset`). See the Tools & Skills section above.
-
----
-
-## Voice & Transcription
-
-### STT (Voice → Text)
-
-Voice messages from messaging platforms are auto-transcribed.
-
-Provider priority (auto-detected):
-1. **Local faster-whisper** — free, no API key: `pip install faster-whisper`
-2. **Groq Whisper** — free tier: set `GROQ_API_KEY`
-3. **OpenAI Whisper** — paid: set `VOICE_TOOLS_OPENAI_KEY`
-4. **Mistral Voxtral** — set `MISTRAL_API_KEY`
-
-Config:
-```yaml
-stt:
-  enabled: true
-  provider: local        # local, groq, openai, mistral
-  local:
-    model: base          # tiny, base, small, medium, large-v3
-```
-
-### TTS (Text → Voice)
-
-| Provider | Env var | Free? |
-|----------|---------|-------|
-| Edge TTS | None | Yes (default) |
-| ElevenLabs | `ELEVENLABS_API_KEY` | Free tier |
-| OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Paid |
-| MiniMax | `MINIMAX_API_KEY` | Paid |
-| Mistral (Voxtral) | `MISTRAL_API_KEY` | Paid |
-| NeuTTS (local) | None (`pip install neutts[all]` + `espeak-ng`) | Free |
-
-Voice commands: `/voice on` (voice-to-voice), `/voice tts` (always voice), `/voice off`.
-
----
+Two theming rules that hold even without loading the reference: **you apply skins yourself** (`hermes config set display.skin <name>` — every surface repaints live within ~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`hermes skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background.
 
 ## Spawning Additional Hermes Instances
 
@@ -633,429 +202,20 @@ terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_14305
 - **Use `hermes chat -q` for fire-and-forget** — no PTY needed
 - **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt_toolkit
 - **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry
+- **"delegate_task is capped at N" reports** — see `references/delegate-task-concurrency-diagnosis.md`. Three real cap paths in Hermes; if none fired, the model is self-limiting and rationalising it as "the runtime caps."
+- **"Can $external_app use my Nous Portal subscription / OAuth?"** — see `references/portal-auth-for-third-party-apps.md`. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).
 
----
+## Surfaces (quick orientation)
 
-## Durable & Background Systems
+- **Desktop app** (`hermes desktop` / `hermes gui`) — native Electron app for macOS/Linux/Windows: streaming chat, session list, Cmd+K palette, drag-and-drop files, native notifications, per-profile remote-gateway login. Extend it with UI plugins — `references/desktop-plugins.md`.
+- **Web dashboard** (`hermes dashboard`) — full admin panel: messaging channels, MCP catalog, webhooks, memory, profile builder, plus an embedded `hermes --tui` chat. Secured behind an OAuth/token gate.
+- **Ink TUI** (`hermes --tui` or `display.interface: tui`) — terminal UI with docked widget apps — `references/tui-widgets.md`.
+- **OpenAI-compatible proxy** (`hermes proxy`) — a local OpenAI API backed by whichever OAuth provider you're signed into. Point Codex CLI, Aider, Cline, or any script at it — no API key.
 
-Four systems run alongside the main conversation loop. Quick reference
-here; full developer notes live in `AGENTS.md`, user-facing docs under
-`website/docs/user-guide/features/`.
+## Hard Invariants (never violate, regardless of what you loaded)
 
-### Delegation (`delegate_task`)
-
-Synchronous subagent spawn — the parent waits for the child's summary
-before continuing its own loop. Isolated context + terminal session.
-
-- **Single:** `delegate_task(goal, context)`.
-- **Batch:** `delegate_task(tasks=[{goal, ...}, ...])` runs children in
-  parallel, capped by `delegation.max_concurrent_children` (default 3).
-- **Roles:** `leaf` (default; cannot re-delegate) vs `orchestrator`
-  (can spawn its own workers, bounded by `delegation.max_spawn_depth`).
-- **Not durable.** If the parent is interrupted, the child is
-  cancelled. For work that must outlive the turn, use `cronjob` or
-  `terminal(background=True, notify_on_complete=True)`.
-
-Config: `delegation.*` in `config.yaml`.
-
-### Cron (scheduled jobs)
-
-Durable scheduler — `cron/jobs.py` + `cron/scheduler.py`. Drive it via
-the `cronjob` tool, the `hermes cron` CLI (`list`, `add`, `edit`,
-`pause`, `resume`, `run`, `remove`), or the `/cron` slash command.
-
-- **Schedules:** duration (`"30m"`, `"2h"`), "every" phrase
-  (`"every monday 9am"`), 5-field cron (`"0 9 * * *"`), or ISO timestamp.
-- **Per-job knobs:** `skills`, `model`/`provider` override, `script`
-  (pre-run data collection; `no_agent=True` makes the script the whole
-  job), `context_from` (chain job A's output into job B), `workdir`
-  (run in a specific dir with its `AGENTS.md` / `CLAUDE.md` loaded),
-  multi-platform delivery.
-- **Invariants:** 3-minute hard interrupt per run, `.tick.lock` file
-  prevents duplicate ticks across processes, cron sessions pass
-  `skip_memory=True` by default, and cron deliveries are framed with a
-  header/footer instead of being mirrored into the target gateway
-  session (keeps role alternation intact).
-
-User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
-
-### Curator (skill lifecycle)
-
-Background maintenance for agent-created skills. Tracks usage, marks
-idle skills stale, archives stale ones, keeps a pre-run tar.gz backup
-so nothing is lost.
-
-- **CLI:** `hermes curator <verb>` — `status`, `run`, `pause`, `resume`,
-  `pin`, `unpin`, `archive`, `restore`, `prune`, `backup`, `rollback`.
-- **Slash:** `/curator <subcommand>` mirrors the CLI.
-- **Scope:** only touches skills with `created_by: "agent"` provenance.
-  Bundled + hub-installed skills are off-limits. **Never deletes** —
-  max destructive action is archive. Pinned skills are exempt from
-  every auto-transition and every LLM review pass.
-- **Telemetry:** sidecar at `~/.hermes/skills/.usage.json` holds
-  per-skill `use_count`, `view_count`, `patch_count`,
-  `last_activity_at`, `state`, `pinned`.
-
-Config: `curator.*` (`enabled`, `interval_hours`, `min_idle_hours`,
-`stale_after_days`, `archive_after_days`, `backup.*`).
-User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/curator
-
-### Kanban (multi-agent work queue)
-
-Durable SQLite board for multi-profile / multi-worker collaboration.
-Users drive it via `hermes kanban <verb>`; dispatcher-spawned workers
-see a focused `kanban_*` toolset gated by `HERMES_KANBAN_TASK`, and
-orchestrator profiles can opt into the broader `kanban` toolset. Normal
-sessions still have zero `kanban_*` schema footprint unless configured.
-
-- **CLI verbs (common):** `init`, `create`, `list` (alias `ls`),
-  `show`, `assign`, `link`, `unlink`, `comment`, `complete`, `block`,
-  `unblock`, `archive`, `tail`. Less common: `watch`, `stats`, `runs`,
-  `log`, `dispatch`, `daemon`, `gc`.
-- **Worker/orchestrator toolset:** `kanban_show`, `kanban_complete`,
-  `kanban_block`, `kanban_heartbeat`, `kanban_comment`, `kanban_create`,
-  `kanban_link`; profiles that explicitly enable the `kanban` toolset
-  outside a dispatcher-spawned task also get `kanban_list` and
-  `kanban_unblock` for board routing.
-- **Dispatcher** runs inside the gateway by default
-  (`kanban.dispatch_in_gateway: true`) — reclaims stale claims,
-  promotes ready tasks, atomically claims, spawns assigned profiles.
-  Auto-blocks a task after `failure_limit` consecutive spawn failures
-  (default 2; configurable via `kanban.failure_limit` or per-task
-  `max_retries`).
-- **Isolation:** board is the hard boundary (workers get
-  `HERMES_KANBAN_BOARD` pinned in env); tenant is a soft namespace
-  within a board for workspace-path + memory-key isolation.
-
-User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban
-
----
-
-## Windows-Specific Quirks
-
-Hermes runs natively on Windows (PowerShell, cmd, Windows Terminal, git-bash
-mintty, VS Code integrated terminal). Most of it just works, but a handful
-of differences between Win32 and POSIX have bitten us — document new ones
-here as you hit them so the next person (or the next session) doesn't
-rediscover them from scratch.
-
-### Input / Keybindings
-
-**Alt+Enter doesn't insert a newline.** Windows Terminal intercepts Alt+Enter
-at the terminal layer to toggle fullscreen — the keystroke never reaches
-prompt_toolkit. Use **Ctrl+Enter** instead. Windows Terminal delivers
-Ctrl+Enter as LF (`c-j`), distinct from plain Enter (`c-m` / CR), and the
-CLI binds `c-j` to newline insertion on `win32` only (see
-`_bind_prompt_submit_keys` + the Windows-only `c-j` binding in `cli.py`).
-Side effect: the raw Ctrl+J keystroke also inserts a newline on Windows —
-unavoidable, because Windows Terminal collapses Ctrl+Enter and Ctrl+J to
-the same keycode at the Win32 console API layer. No conflicting binding
-existed for Ctrl+J on Windows, so this is a harmless side effect.
-
-mintty / git-bash behaves the same (fullscreen on Alt+Enter) unless you
-disable Alt+Fn shortcuts in Options → Keys. Easier to just use Ctrl+Enter.
-
-**Diagnosing keybindings.** Run `python scripts/keystroke_diagnostic.py`
-(repo root) to see exactly how prompt_toolkit identifies each keystroke
-in the current terminal. Answers questions like "does Shift+Enter come
-through as a distinct key?" (almost never — most terminals collapse it
-to plain Enter) or "what byte sequence is my terminal sending for
-Ctrl+Enter?" This is how the Ctrl+Enter = c-j fact was established.
-
-### Config / Files
-
-**HTTP 400 "No models provided" on first run.** `config.yaml` was saved
-with a UTF-8 BOM (common when Windows apps write it). Re-save as UTF-8
-without BOM. `hermes config edit` writes without BOM; manual edits in
-Notepad are the usual culprit.
-
-### `execute_code` / Sandbox
-
-**WinError 10106** ("The requested service provider could not be loaded
-or initialized") from the sandbox child process — it can't create an
-`AF_INET` socket, so the loopback-TCP RPC fallback fails before
-`connect()`. Root cause is usually **not** a broken Winsock LSP; it's
-Hermes's own env scrubber dropping `SYSTEMROOT` / `WINDIR` / `COMSPEC`
-from the child env. Python's `socket` module needs `SYSTEMROOT` to locate
-`mswsock.dll`. Fixed via the `_WINDOWS_ESSENTIAL_ENV_VARS` allowlist in
-`tools/code_execution_tool.py`. If you still hit it, echo `os.environ`
-inside an `execute_code` block to confirm `SYSTEMROOT` is set. Full
-diagnostic recipe in `references/execute-code-sandbox-env-windows.md`.
-
-### Testing / Contributing
-
-**`scripts/run_tests.sh` doesn't work as-is on Windows** — it looks for
-POSIX venv layouts (`.venv/bin/activate`). The Hermes-installed venv at
-`venv/Scripts/` has no pip or pytest either (stripped for install size).
-Workaround: install `pytest + pytest-xdist + pyyaml` into a system Python
-3.11 user site, then invoke pytest directly with `PYTHONPATH` set:
-
-```bash
-"/c/Program Files/Python311/python" -m pip install --user pytest pytest-xdist pyyaml
-export PYTHONPATH="$(pwd)"
-"/c/Program Files/Python311/python" -m pytest tests/foo/test_bar.py -v --tb=short -n 0
-```
-
-Use `-n 0`, not `-n 4` — `pyproject.toml`'s default `addopts` already
-includes `-n`, and the wrapper's CI-parity guarantees don't apply off POSIX.
-
-**POSIX-only tests need skip guards.** Common markers already in the codebase:
-- Symlinks — elevated privileges on Windows
-- `0o600` file modes — POSIX mode bits not enforced on NTFS by default
-- `signal.SIGALRM` — Unix-only (see `tests/conftest.py::_enforce_test_timeout`)
-- Winsock / Windows-specific regressions — `@pytest.mark.skipif(sys.platform != "win32", ...)`
-
-Use the existing skip-pattern style (`sys.platform == "win32"` or
-`sys.platform.startswith("win")`) to stay consistent with the rest of the
-suite.
-
-### Path / Filesystem
-
-**Line endings.** Git may warn `LF will be replaced by CRLF the next time
-Git touches it`. Cosmetic — the repo's `.gitattributes` normalizes. Don't
-let editors auto-convert committed POSIX-newline files to CRLF.
-
-**Forward slashes work almost everywhere.** `C:/Users/...` is accepted by
-every Hermes tool and most Windows APIs. Prefer forward slashes in code
-and logs — avoids shell-escaping backslashes in bash.
-
----
-
-## Troubleshooting
-
-### Voice not working
-1. Check `stt.enabled: true` in config.yaml
-2. Verify provider: `pip install faster-whisper` or set API key
-3. In gateway: `/restart`. In CLI: exit and relaunch.
-
-### Tool not available
-1. `hermes tools` — check if toolset is enabled for your platform
-2. Some tools need env vars (check `.env`)
-3. `/reset` after enabling tools
-
-### Model/provider issues
-1. `hermes doctor` — check config and dependencies
-2. `hermes auth` — re-authenticate OAuth providers (or `hermes auth add <provider>`)
-3. Check `.env` has the right API key
-4. **Copilot 403**: `gh auth login` tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via `hermes model` → GitHub Copilot.
-
-### Changes not taking effect
-- **Tools/skills:** `/reset` starts a new session with updated toolset
-- **Config changes:** In gateway: `/restart`. In CLI: exit and relaunch.
-- **Code changes:** Restart the CLI or gateway process
-
-### Skills not showing
-1. `hermes skills list` — verify installed
-2. `hermes skills config` — check platform enablement
-3. Load explicitly: `/skill name` or `hermes -s name`
-
-### Gateway issues
-Check logs first:
-```bash
-grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20
-```
-
-Common gateway problems:
-- **Gateway dies on SSH logout**: Enable linger: `sudo loginctl enable-linger $USER`
-- **Gateway dies on WSL2 close**: WSL2 requires `systemd=true` in `/etc/wsl.conf` for systemd services to work. Without it, gateway falls back to `nohup` (dies when session closes).
-- **Gateway crash loop**: Reset the failed state: `systemctl --user reset-failed hermes-gateway`
-
-### Platform-specific issues
-- **Discord bot silent**: Must enable **Message Content Intent** in Bot → Privileged Gateway Intents.
-- **Slack bot only works in DMs**: Must subscribe to `message.channels` event. Without it, the bot ignores public channels.
-- **Windows-specific issues** (`Alt+Enter` newline, WinError 10106, UTF-8 BOM config, test suite, line endings): see the dedicated **Windows-Specific Quirks** section above.
-
-### Auxiliary models not working
-If `auxiliary` tasks (vision, compression, session_search) fail silently, the `auto` provider can't find a backend. Either set `OPENROUTER_API_KEY` or `GOOGLE_API_KEY`, or explicitly configure each auxiliary task's provider:
-```bash
-hermes config set auxiliary.vision.provider <your_provider>
-hermes config set auxiliary.vision.model <model_name>
-```
-
----
-### Context window shows wrong size
-
-If Hermes reports a smaller context window than your local model supports
-(e.g., 128k when llama-server has `-c 262144`):
-
-**Check if `model.context_length` is explicitly set.** Hermes uses a
-multi-source resolution chain (highest priority first):
-
-1. `model.context_length` in config.yaml — **blocks auto-detection if set**
-2. Custom provider per-model setting
-3. Persistent cache (survives restarts)
-4. `/v1/models` endpoint from your server — auto-detected when nothing
-   above overrides it
-
-**Fix:** Clear the override so auto-detection falls through:
-
-
-## Where to Find Things
-
-| Looking for... | Location |
-|----------------|----------|
-| Config options | `hermes config edit` or [Configuration docs](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) |
-| Available tools | `hermes tools list` or [Tools reference](https://hermes-agent.nousresearch.com/docs/reference/tools-reference) |
-| Slash commands | `/help` in session or [Slash commands reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) |
-| Skills catalog | `hermes skills browse` or [Skills catalog](https://hermes-agent.nousresearch.com/docs/reference/skills-catalog) |
-| Provider setup | `hermes model` or [Providers guide](https://hermes-agent.nousresearch.com/docs/integrations/providers) |
-| Platform setup | `hermes gateway setup` or [Messaging docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) |
-| MCP servers | `hermes mcp list` or [MCP guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) |
-| Profiles | `hermes profile list` or [Profiles docs](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) |
-| Cron jobs | `hermes cron list` or [Cron docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) |
-| Memory | `hermes memory status` or [Memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) |
-| Env variables | `hermes config env-path` or [Env vars reference](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) |
-| CLI commands | `hermes --help` or [CLI reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) |
-| Gateway logs | `~/.hermes/logs/gateway.log` |
-| Session files | `hermes sessions browse` (reads state.db) |
-| Source code | `~/.hermes/hermes-agent/` |
-
----
-
-## Contributor Quick Reference
-
-For occasional contributors and PR authors. Full developer docs: https://hermes-agent.nousresearch.com/docs/developer-guide/
-
-### Project Layout
-
-<!-- ascii-guard-ignore -->
-```
-hermes-agent/
-├── run_agent.py          # AIAgent — core conversation loop
-├── model_tools.py        # Tool discovery and dispatch
-├── toolsets.py           # Toolset definitions
-├── cli.py                # Interactive CLI (HermesCLI)
-├── hermes_state.py       # SQLite session store
-├── agent/                # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch
-├── hermes_cli/           # CLI subcommands, config, setup, commands
-│   ├── commands.py       # Slash command registry (CommandDef)
-│   ├── config.py         # DEFAULT_CONFIG, env var definitions
-│   └── main.py           # CLI entry point and argparse
-├── tools/                # One file per tool
-│   └── registry.py       # Central tool registry
-├── gateway/              # Messaging gateway
-│   └── platforms/        # Platform adapters (telegram, discord, etc.)
-├── cron/                 # Job scheduler
-├── tests/                # ~3000 pytest tests
-└── website/              # Docusaurus docs site
-```
-<!-- ascii-guard-ignore-end -->
-
-Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys) — both under `$HERMES_HOME` when it is set.
-
-### Adding a Tool (3 files)
-
-**1. Create `tools/your_tool.py`:**
-```python
-import json, os
-from tools.registry import registry
-
-def check_requirements() -> bool:
-    return bool(os.getenv("EXAMPLE_API_KEY"))
-
-def example_tool(param: str, task_id: str = None) -> str:
-    return json.dumps({"success": True, "data": "..."})
-
-registry.register(
-    name="example_tool",
-    toolset="example",
-    schema={"name": "example_tool", "description": "...", "parameters": {...}},
-    handler=lambda args, **kw: example_tool(
-        param=args.get("param", ""), task_id=kw.get("task_id")),
-    check_fn=check_requirements,
-    requires_env=["EXAMPLE_API_KEY"],
-)
-```
-
-**2. Add to `toolsets.py`** → `_HERMES_CORE_TOOLS` list.
-
-Auto-discovery: any `tools/*.py` file with a top-level `registry.register()` call is imported automatically — no manual list needed.
-
-All handlers must return JSON strings. Use `get_hermes_home()` for paths, never hardcode `~/.hermes`.
-
-### Adding a Slash Command
-
-1. Add `CommandDef` to `COMMAND_REGISTRY` in `hermes_cli/commands.py`
-2. Add handler in `cli.py` → `process_command()`
-3. (Optional) Add gateway handler in `gateway/run.py`
-
-All consumers (help text, autocomplete, Telegram menu, Slack mapping) derive from the central registry automatically.
-
-### Agent Loop (High Level)
-
-```
-run_conversation():
-  1. Build system prompt
-  2. Loop while iterations < max:
-     a. Call LLM (OpenAI-format messages + tool schemas)
-     b. If tool_calls → dispatch each via handle_function_call() → append results → continue
-     c. If text response → return
-  3. Context compression triggers automatically near token limit
-```
-
-### Testing
-
-```bash
-python -m pytest tests/ -o 'addopts=' -q   # Full suite
-python -m pytest tests/tools/ -q            # Specific area
-```
-
-- Tests auto-redirect `HERMES_HOME` to temp dirs — never touch real `~/.hermes/`
-- Run full suite before pushing any change
-- Use `-o 'addopts='` to clear any baked-in pytest flags
-
-**Windows contributors:** `scripts/run_tests.sh` currently looks for POSIX venvs (`.venv/bin/activate` / `venv/bin/activate`) and will error out on Windows where the layout is `venv/Scripts/activate` + `python.exe`. The Hermes-installed venv at `venv/Scripts/` also has no `pip` or `pytest` — it's stripped for end-user install size. Workaround: install pytest + pytest-xdist + pyyaml into a system Python 3.11 user site (`/c/Program Files/Python311/python -m pip install --user pytest pytest-xdist pyyaml`), then run tests directly:
-
-```bash
-export PYTHONPATH="$(pwd)"
-"/c/Program Files/Python311/python" -m pytest tests/tools/test_foo.py -v --tb=short -n 0
-```
-
-Use `-n 0` (not `-n 4`) because `pyproject.toml`'s default `addopts` already includes `-n`, and the wrapper's CI-parity story doesn't apply off-POSIX.
-
-**Cross-platform test guards:** tests that use POSIX-only syscalls need a skip marker. Common ones already in the codebase:
-- Symlink creation → `@pytest.mark.skipif(sys.platform == "win32", reason="Symlinks require elevated privileges on Windows")` (see `tests/cron/test_cron_script.py`)
-- POSIX file modes (0o600, etc.) → `@pytest.mark.skipif(sys.platform.startswith("win"), reason="POSIX mode bits not enforced on Windows")` (see `tests/hermes_cli/test_auth_toctou_file_modes.py`)
-- `signal.SIGALRM` → Unix-only (see `tests/conftest.py::_enforce_test_timeout`)
-- Live Winsock / Windows-specific regression tests → `@pytest.mark.skipif(sys.platform != "win32", reason="Windows-specific regression")`
-
-**Monkeypatching `sys.platform` is not enough** when the code under test also calls `platform.system()` / `platform.release()` / `platform.mac_ver()`. Those functions re-read the real OS independently, so a test that sets `sys.platform = "linux"` on a Windows runner will still see `platform.system() == "Windows"` and route through the Windows branch. Patch all three together:
-
-```python
-monkeypatch.setattr(sys, "platform", "linux")
-monkeypatch.setattr(platform, "system", lambda: "Linux")
-monkeypatch.setattr(platform, "release", lambda: "6.8.0-generic")
-```
-
-See `tests/agent/test_prompt_builder.py::TestEnvironmentHints` for a worked example.
-
-### Extending the system prompt's execution-environment block
-
-Factual guidance about the host OS, user home, cwd, terminal backend, and shell (bash vs. PowerShell on Windows) is emitted from `agent/prompt_builder.py::build_environment_hints()`. This is also where the WSL hint and per-backend probe logic live. The convention:
-
-- **Local terminal backend** → emit host info (OS, `$HOME`, cwd) + Windows-specific notes (hostname ≠ username, `terminal` uses bash not PowerShell).
-- **Remote terminal backend** (anything in `_REMOTE_TERMINAL_BACKENDS`: `docker, singularity, modal, daytona, ssh, managed_modal`) → **suppress** host info entirely and describe only the backend. A live `uname`/`whoami`/`pwd` probe runs inside the backend via `tools.environments.get_environment(...).execute(...)`, cached per process in `_BACKEND_PROBE_CACHE`, with a static fallback if the probe times out.
-- **Key fact for prompt authoring:** when `TERMINAL_ENV != "local"`, *every* file tool (`read_file`, `write_file`, `patch`, `search_files`) runs inside the backend container, not on the host. The system prompt must never describe the host in that case — the agent can't touch it.
-
-Full design notes, the exact emitted strings, and testing pitfalls:
-`references/prompt-builder-environment-hints.md`.
-
-**Refactor-safety pattern (POSIX-equivalence guard):** when you extract inline logic into a helper that adds Windows/platform-specific behavior, keep a `_legacy_<name>` oracle function in the test file that's a verbatim copy of the old code, then parametrize-diff against it. Example: `tests/tools/test_code_execution_windows_env.py::TestPosixEquivalence`. This locks in the invariant that POSIX behavior is bit-for-bit identical and makes any future drift fail loudly with a clear diff.
-
-### Commit Conventions
-
-```
-type: concise subject line
-
-Optional body.
-```
-
-Types: `fix:`, `feat:`, `refactor:`, `docs:`, `chore:`
-
-### Key Rules
-
-- **Never break prompt caching** — don't change context, tools, or system prompt mid-conversation
-- **Message role alternation** — never two assistant or two user messages in a row
-- Use `get_hermes_home()` from `hermes_constants` for all paths (profile-safe)
-- Config values go in `config.yaml`, secrets go in `.env`
-- New tools need a `check_fn` so they only appear when requirements are met
+- **Never break prompt caching** — don't change past context, toolsets, or the system prompt mid-conversation. The only exception is context compression.
+- **Message role alternation** — never two assistant or two user messages in a row; only `tool` results can repeat.
+- **Secrets in `.env`, settings in `config.yaml`** — never tell a user to put a non-credential setting in `.env`.
+- **Profile-safe paths** — `get_hermes_home()` in code, `$HERMES_HOME` when resolving paths in a session.
+- **Never hand-edit `config.yaml` for the user** — use `hermes config set KEY VAL`; a stray indent can corrupt the file and break the live gateway.
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-comfyui.md b/website/docs/user-guide/skills/bundled/creative/creative-comfyui.md
index 38610be8b83..74b249e0dee 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-comfyui.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-comfyui.md
@@ -1,14 +1,14 @@
 ---
-title: "Comfyui"
+title: "Comfyui — Generate images, video, and audio via diffusion workflows"
 sidebar_label: "Comfyui"
-description: "Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection"
+description: "Generate images, video, and audio via diffusion workflows"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Comfyui
 
-Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST/WebSocket API for execution.
+Generate images, video, and audio via diffusion workflows.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Generate images, video, and audio with ComfyUI — install, launch, manage nodes
 | License | MIT |
 | Platforms | macos, linux, windows |
 | Tags | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |
-| Related skills | [`stable-diffusion-image-generation`](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion), `image_gen` |
+| Related skills | [`stable-diffusion-image-generation`](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-design-md.md b/website/docs/user-guide/skills/bundled/creative/creative-design-md.md
index a96723ddb7f..8fbf077bf3c 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-design-md.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-design-md.md
@@ -16,7 +16,7 @@ Author/validate/export Google's DESIGN.md token spec files.
 |---|---|
 | Source | Bundled (installed by default) |
 | Path | `skills/creative/design-md` |
-| Version | `1.0.0` |
+| Version | `1.1.0` |
 | Author | Hermes Agent |
 | License | MIT |
 | Platforms | linux, macos, windows |
@@ -116,7 +116,7 @@ Public Sans for everything except small all-caps labels...
 
 | Type | Format | Example |
 |------|--------|---------|
-| Color | `#` + hex (sRGB) | `"#1A1C1E"` |
+| Color | any CSS color (hex, `rgb()`, `oklch()`, named) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
 | Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |
 | Token reference | `{path.to.token}` | `{colors.primary}` |
 | Typography | object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` | see above |
@@ -128,8 +128,10 @@ pressed) are **separate component entries** with related key names
 
 ## Canonical section order
 
-Sections are optional, but present ones MUST appear in this order. Duplicate
-headings reject the file.
+Sections are optional, but present ones should appear in this order. The
+linter flags out-of-order sections (`section-order`, warning) and duplicate
+headings — consumers per the spec reject duplicates, so fix both before
+returning the file.
 
 1. Overview (alias: Brand & Style)
 2. Colors
@@ -168,8 +170,11 @@ npx -y @google/design.md lint DESIGN.md
 # Compare two versions, fail on regression (exit 1 = regression)
 npx -y @google/design.md diff DESIGN.md DESIGN-v2.md
 
-# Export to Tailwind theme JSON
-npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
+# Export to Tailwind v3 theme JSON (`tailwind` is a back-compat alias)
+npx -y @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
+
+# Export to a Tailwind v4 CSS @theme block (--color-*, --text-*, --radius-*, ...)
+npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css
 
 # Export to W3C DTCG (Design Tokens Format Module) JSON
 npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
@@ -178,18 +183,28 @@ npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
 npx -y @google/design.md spec --rules-only --format json
 ```
 
-All commands accept `-` for stdin. `lint` returns exit 1 on errors. Use the
-`--format json` flag and parse the output if you need to report findings
-structurally.
+All commands accept `-` for stdin. `lint` returns exit 1 on errors (warnings
+alone exit 0). `export` exits 0 on a successful export regardless of lint
+findings in the source — run `lint` separately to gate on those. Output is
+JSON by default; parse it if you need to report findings structurally.
 
-### Lint rule reference (what the 7 rules catch)
+On Windows, the `design.md` bin name can collide with the `.md` file
+association (silent no-op or the file opens in an editor). Use the dot-free
+alias: `npx -y -p @google/design.md designmd lint DESIGN.md`.
+
+### Lint rule reference (the 9 rules, as of CLI 0.3.0)
 
 - `broken-ref` (error) — `{colors.missing}` points at a non-existent token
-- `duplicate-section` (error) — same `## Heading` appears twice
-- `invalid-color`, `invalid-dimension`, `invalid-typography` (error)
-- `wcag-contrast` (warning/info) — component `textColor` vs `backgroundColor`
-  ratio against WCAG AA (4.5:1) and AAA (7:1)
-- `unknown-component-property` (warning) — outside the whitelist above
+- `contrast-ratio` (warning) — component `textColor` vs `backgroundColor`
+  below WCAG AA (4.5:1)
+- `missing-primary` (warning) — colors defined but no `primary` token
+- `missing-typography` (warning) — colors defined but no typography tokens
+- `orphaned-tokens` (warning) — color tokens never referenced by a component
+- `section-order` (warning) — sections out of the canonical order
+- `unknown-key` (warning) — top-level YAML key that looks like a typo of a
+  schema key (`colours:` → `colors:`); custom extension keys stay silent
+- `token-summary`, `missing-sections` (info) — counts and absent optional
+  sections
 
 When the user cares about accessibility, call this out explicitly in your
 summary — WCAG findings are the most load-bearing reason to use the CLI.
@@ -202,10 +217,16 @@ summary — WCAG findings are the most load-bearing reason to use the CLI.
   truncate values like `#1A1C1E` oddly.
 - **Negative dimensions need quotes too.** `letterSpacing: -0.02em` parses as
   a YAML flow — write `letterSpacing: "-0.02em"`.
-- **Section order is enforced.** If the user gives you prose in a random order,
-  reorder it to match the canonical list before saving.
-- **`version: alpha` is the current spec version** (as of Apr 2026). The spec
-  is marked alpha — watch for breaking changes.
+- **Section order matters even though the linter only warns.** If the user
+  gives you prose in a random order, reorder it to match the canonical list
+  before saving — spec-compliant consumers expect it.
+- **Typography sub-property typos are silently dropped.** As of CLI 0.3.0 a
+  typo like `fontwight:` produces no finding and the value vanishes from
+  exports — double-check sub-property names against the schema
+  (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`,
+  `fontFeature`, `fontVariation`).
+- **`version: alpha` is the current spec version** (as of Jul 2026, CLI
+  0.3.0). The spec is marked alpha — watch for breaking changes.
 - **Token references resolve by dotted path.** `{colors.primary}` works;
   `{primary}` does not.
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-pretext.md b/website/docs/user-guide/skills/bundled/creative/creative-pretext.md
index 78ed86c8e61..59cdfc87734 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-pretext.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-pretext.md
@@ -1,14 +1,14 @@
 ---
-title: "Pretext"
+title: "Pretext — Build creative browser demos with DOM-free text layout"
 sidebar_label: "Pretext"
-description: "Use when building creative browser demos with @chenglou/pretext — DOM-free text layout for ASCII art, typographic flow around obstacles, text-as-geometry gam..."
+description: "Build creative browser demos with DOM-free text layout"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Pretext
 
-Use when building creative browser demos with @chenglou/pretext — DOM-free text layout for ASCII art, typographic flow around obstacles, text-as-geometry games, kinetic typography, and text-powered generative art. Produces single-file HTML demos by default.
+Build creative browser demos with DOM-free text layout.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md b/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md
index 6ff697fa39a..6b0cdbb70a1 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md
@@ -296,3 +296,21 @@ Style can drift in extensions — restate genre/mood when extending.
 - Don't be precious about rules. If a line breaks meter but hits
   harder, keep it. The feeling is what matters. Craft serves art,
   not the other way around.
+
+---
+
+## 10. Local / Open-Source Music Generation
+
+For local, GPU-based generation instead of Suno, two optional skills
+cover this (heavy dependencies, so not installed by default):
+
+- **heartmula** — full songs with vocals from lyrics + tags
+  (open-source Suno alternative, 8-16GB VRAM):
+  `hermes skills install official/creative/heartmula`
+- **audiocraft** — Meta's MusicGen (instrumental text-to-music) and
+  AudioGen (sound effects):
+  `hermes skills install official/creative/audiocraft-audio-generation`
+
+The lyric-writing and prompting craft in this skill applies to
+heartmula too — its input format is lyrics with bracketed structure
+tags plus comma-separated style tags.
diff --git a/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md b/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md
index 9a14bceffd9..8fff080b383 100644
--- a/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md
+++ b/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md
@@ -1,14 +1,14 @@
 ---
-title: "Touchdesigner Mcp"
+title: "Touchdesigner Mcp — Control TouchDesigner via twozero MCP"
 sidebar_label: "Touchdesigner Mcp"
-description: "Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals"
+description: "Control TouchDesigner via twozero MCP"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Touchdesigner Mcp
 
-Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.
+Control TouchDesigner via twozero MCP.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Control a running TouchDesigner instance via twozero MCP — create operators, s
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `TouchDesigner`, `MCP`, `twozero`, `creative-coding`, `real-time-visuals`, `generative-art`, `audio-reactive`, `VJ`, `installation`, `GLSL` |
-| Related skills | `native-mcp`, [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
+| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/hermes-desktop-plugins/hermes-desktop-plugins-hermes-desktop-plugins.md b/website/docs/user-guide/skills/bundled/hermes-desktop-plugins/hermes-desktop-plugins-hermes-desktop-plugins.md
deleted file mode 100644
index af0015b7983..00000000000
--- a/website/docs/user-guide/skills/bundled/hermes-desktop-plugins/hermes-desktop-plugins-hermes-desktop-plugins.md
+++ /dev/null
@@ -1,180 +0,0 @@
----
-title: "Hermes Desktop Plugins — Write desktop app plugins that add UI panes and commands"
-sidebar_label: "Hermes Desktop Plugins"
-description: "Write desktop app plugins that add UI panes and commands"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Hermes Desktop Plugins
-
-Write desktop app plugins that add UI panes and commands.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/hermes-desktop-plugins` |
-| Version | `1.0.0` |
-| Platforms | linux, macos, windows |
-| Tags | `desktop`, `plugins`, `ui`, `extension` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Hermes Desktop Plugins Skill
-
-Write plugins for the Hermes desktop app: statusbar items, layout panes,
-command-palette commands, keybinds, routes, and themes. A plugin is a single
-plain-JavaScript ESM file the app loads at runtime — no build step, no repo
-changes. A plugin can also talk to its own Python backend namespace
-(`ctx.rest`/`ctx.socket` → `/api/plugins/<id>`); the general Python plugin
-system (`~/.hermes/plugins/`) is otherwise documented separately.
-
-Full human reference (every export, area payloads, backend, security):
-`website/docs/developer-guide/desktop-plugin-sdk.md`.
-
-## When to Use
-
-- The user asks for a new desktop UI element (a pane, a statusbar widget, a
-  dashboard, a command) without modifying the app itself.
-- You want to surface data you compute (via gateway RPC) inside the app.
-
-## Prerequisites
-
-- The Hermes desktop app (it loads plugins; the CLI/gateway alone does not).
-- Write access to `$HERMES_HOME/desktop-plugins/` (usually
-  `~/.hermes/desktop-plugins/`).
-
-## How to Run
-
-1. Create `$HERMES_HOME/desktop-plugins/<name>/plugin.js` from
-   `templates/plugin.js` (relative to this skill directory) — that's
-   `~/.hermes/...` by default, or `~/.hermes/profiles/<profile>/...` under a
-   named profile. Keep `<name>` equal to the plugin `id`.
-2. The desktop app watches that directory: the plugin loads within a few
-   seconds of the file landing, and every later save hot-reloads it in
-   place. No reload step. (Fallback if it doesn't appear: ⌘K →
-   **Reload desktop plugins**.)
-3. If loading fails the app shows a toast naming the error — fix the file
-   and save again.
-
-## Quick Reference
-
-The ONLY import surface is `@hermes/plugin-sdk` (plus `react` /
-`react/jsx-runtime`, which resolve to the app's own React — write UI with
-`jsx()` calls, not JSX syntax; the file is not compiled).
-
-- `host.state.*` — readonly reactive atoms: `activeSessionId`, `cwd`,
-  `gateway`, `model`, `profile`, `viewport`. Read with `.get()` in handlers,
-  `useValue(atom)` in components.
-- `host.request(method, params)` — gateway JSON-RPC (sessions, config,
-  skills, cron — everything the app uses).
-- `host.onEvent(type, fn)` — live gateway events (`'*'` for all). Returns a
-  disposer.
-- `host.notify({ kind, message })`, `host.navigate(path)`, `host.logs(...)`,
-  `host.status()`, `haptic('tap')`.
-- `ctx.register({ id, area, order?, render?, data? })` — contribute UI.
-  Key areas: `'statusBar.right'`/`'statusBar.left'` (chips),
-  `'panes'` (layout zones — set `title` and
-  `data: { placement, dock?, width?, height? }`; the pane auto-joins a
-  matching zone), `PALETTE_AREA` (⌘K commands), `KEYBINDS_AREA` (rebindable
-  actions).
-- Pane placement: `placement: 'left'|'right'|'bottom'|'main'` is the
-  semantic role — the pane stacks (tabs) with existing panes of that role.
-  To land on a specific EDGE instead, add `dock: { pane, pos }` — the same
-  gesture as dragging onto a pane's drop chip. `pane` is any pane id
-  (`workspace` is the main thread; also `sessions`, `terminal`, `files`,
-  `review`, `logs`), `pos` is `'top'|'bottom'|'left'|'right'|'center'`.
-  E.g. "below the conversation" = `dock: { pane: 'workspace', pos: 'bottom' }`
-  — declare a `height` (e.g. `'200px'`) so it doesn't take half the zone.
-- Full PAGES: register `area: ROUTES_AREA` with `data: { path: '/my-page' }`
-  and a `render` — the page mounts in the workspace (main) pane like any
-  built-in view. Make it reachable with a sidebar nav row:
-  `ctx.register({ id: 'nav', area: SIDEBAR_NAV_AREA, data: { path: '/my-page', label: 'My Page', codicon: 'project' } })`
-  (renders below Artifacts, lights up at the route) — and/or a
-  `PALETTE_AREA` command calling `host.navigate('/my-page')`.
-- `ctx.storage.get/set/remove` — persistence namespaced to your plugin.
-- `ctx.i18n.register({ en, ja, ... })` — ship your OWN locale bundles, scoped
-  to your plugin (never edit core `en.ts`). Values are literal strings or
-  interpolator functions; nested trees are addressed by dot-path. Read them
-  reactively in components with `usePluginI18n(id)` returning `t('key', ...args)`
-  (re-renders on a locale switch), or via `ctx.i18n.t` in handlers/stores.
-  Resolution follows the app's active locale, then your `en`, then the raw key.
-- Data: `useQuery`/`useMutation`/`useQueryClient`/`queryClient` (the app's ONE
-  React Query client — cache, dedupe, `refetchInterval`, invalidate like core;
-  never hand-roll a poll loop), plus `atom`/`computed` for plugin-local state.
-- Backend: if the plugin ships a Python `plugin_api.py` (under
-  `~/.hermes/plugins/<id>/dashboard/`, manifest `"api": "plugin_api.py"`), reach
-  it with `ctx.rest('/path', { method?, body?, timeoutMs? })` and its live twin
-  `ctx.socket('/events', onMessage)` — both scoped to `/api/plugins/<id>` by
-  construction (traversal rejected). `ctx.socket` is a **no-op on OAuth
-  remotes**, so always keep a polling fallback. The Python backend is imported
-  only when the plugin is in `plugins.enabled` in `config.yaml` (separate from
-  the in-app enable toggle). For gateway-wide data use `host.request` /
-  `host.onEvent` instead.
-- `Contribute` (mount-scoped): render `jsx(Contribute, { area, id, children })`
-  inside a component so page-owned chrome (e.g. a titlebar control in
-  `TITLEBAR_AREAS.center`) leaves when the page unmounts — `ctx.register` is for
-  permanent contributions.
-- `defaultEnabled: false` on the default export ships an opt-in plugin: it
-  inventories in Settings → Plugins, off until the user flips it on.
-- Users manage plugins in Settings → Plugins (enable/disable live, reveal
-  folder). A disabled plugin stays disabled across restarts — don't fight
-  it; the user turned you off.
-- UI: the app's design language, importable directly — `Button`, `Input`,
-  `Textarea`, `Select*`, `Switch`, `Checkbox`, `SegmentedControl`, `Tabs*`,
-  `Dialog*`, `ConfirmDialog`, `DropdownMenu*`, `ContextMenu*`, `Popover*`,
-  `Tip`/`Tooltip*`, `Badge`, `Kbd`/`KbdGroup`, `SearchField`, `ScrollArea`,
-  `Separator`, `Skeleton`, `GlyphSpinner`, `EmptyState`, `ErrorState`,
-  `CopyButton`, `StatusDot`, `LogView`, `Codicon`, `DecodeText`, plus `cn`
-  and `icons.*`. Prefer these over hand-rolled elements so the plugin looks
-  native; style with theme vars, never hardcoded colors.
-
-## Procedure
-
-1. Pick a short kebab-case `id`; the folder name must match.
-2. Start from `templates/plugin.js`; keep the default export shape
-   (`{ id, name, register(ctx) }`).
-3. For a pane, register `area: 'panes'` with a `placement` hint and a
-   `render` returning your component — the app places it into a sensible
-   zone automatically; the user can drag it anywhere afterwards.
-4. Fetch data with `host.request` and/or subscribe with `host.onEvent`;
-   never poll faster than a few seconds.
-5. Write the file with your file tools, then ask the user to run
-   **Reload desktop plugins** from ⌘K.
-
-## Pitfalls
-
-- NEVER hardcode colors or backgrounds (`#000`, `black`, `rgb(...)`). Panes
-  already sit on the app's editor background — leave the background alone
-  and use theme variables for everything else: `var(--ui-text-secondary)`,
-  `var(--ui-text-quaternary)`, `var(--ui-stroke-secondary)`,
-  `var(--ui-accent)`. For canvas drawing, resolve them once with
-  `getComputedStyle(canvas).getPropertyValue('--ui-accent')`.
-- Reference only what you imported — a component you forgot to import
-  (e.g. `StatusDot`) is a ReferenceError at render. Double-check every
-  identifier in your `jsx()` calls appears in the import line.
-- Canvas panes MUST track their container with a `ResizeObserver` and
-  re-size the canvas (width/height attributes, not just CSS) — panes resize
-  constantly (sash drags, layout switches); a mount-time-only size leaves
-  blank space or blurry scaling.
-- JSX syntax will not parse — the file loads uncompiled. Use
-  `jsx('div', { children: ... })` from `react/jsx-runtime`.
-- Do not import anything except `@hermes/plugin-sdk`, `react`, and
-  `react/jsx-runtime`; other specifiers fail to resolve.
-- Handlers must read state imperatively (`$atom.get()`), never from render
-  closures — rapid events will otherwise see stale values.
-- Keep components small; subscribe (`useValue`) only in the leaf that
-  renders the value.
-
-## Verification
-
-- The plugin's UI appears after **Reload desktop plugins**.
-- No error toast ("Plugin &lt;name> failed to load") appears; if it does, the
-  message names the failure — fix and reload.
-- For panes: the new zone is visible and draggable like any core pane.
diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md b/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness.md
similarity index 95%
rename from website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md
rename to website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness.md
index 415027621c0..51d87a0259b 100644
--- a/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md
+++ b/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness.md
@@ -15,7 +15,7 @@ lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.).
 | | |
 |---|---|
 | Source | Bundled (installed by default) |
-| Path | `skills/mlops/evaluation/lm-evaluation-harness` |
+| Path | `skills/mlops/evaluation/evaluating-llms-harness` |
 | Version | `1.0.0` |
 | Author | Orchestra Research |
 | License | MIT |
@@ -483,13 +483,13 @@ lm_eval --model hf \
 
 ## Advanced topics
 
-**Benchmark descriptions**: See [references/benchmark-guide.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/lm-evaluation-harness/references/benchmark-guide.md) for detailed description of all 60+ tasks, what they measure, and interpretation.
+**Benchmark descriptions**: See [references/benchmark-guide.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md) for detailed description of all 60+ tasks, what they measure, and interpretation.
 
-**Custom tasks**: See [references/custom-tasks.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/lm-evaluation-harness/references/custom-tasks.md) for creating domain-specific evaluation tasks.
+**Custom tasks**: See [references/custom-tasks.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md) for creating domain-specific evaluation tasks.
 
-**API evaluation**: See [references/api-evaluation.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/lm-evaluation-harness/references/api-evaluation.md) for evaluating OpenAI, Anthropic, and other API models.
+**API evaluation**: See [references/api-evaluation.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md) for evaluating OpenAI, Anthropic, and other API models.
 
-**Multi-GPU strategies**: See [references/distributed-eval.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/lm-evaluation-harness/references/distributed-eval.md) for data parallel and tensor parallel evaluation.
+**Multi-GPU strategies**: See [references/distributed-eval.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md) for data parallel and tensor parallel evaluation.
 
 ## Hardware requirements
 
diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm.md b/website/docs/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm.md
similarity index 94%
rename from website/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm.md
rename to website/docs/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm.md
index 524f1bf265e..25740ce7831 100644
--- a/website/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm.md
+++ b/website/docs/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm.md
@@ -15,7 +15,7 @@ vLLM: high-throughput LLM serving, OpenAI API, quantization.
 | | |
 |---|---|
 | Source | Bundled (installed by default) |
-| Path | `skills/mlops/inference/vllm` |
+| Path | `skills/mlops/inference/serving-llms-vllm` |
 | Version | `1.0.0` |
 | Author | Orchestra Research |
 | License | MIT |
@@ -362,13 +362,13 @@ vllm serve MODEL --speculative-model DRAFT_MODEL
 
 ## Advanced topics
 
-**Server deployment patterns**: See [references/server-deployment.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/vllm/references/server-deployment.md) for Docker, Kubernetes, and load balancing configurations.
+**Server deployment patterns**: See [references/server-deployment.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/server-deployment.md) for Docker, Kubernetes, and load balancing configurations.
 
-**Performance optimization**: See [references/optimization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/vllm/references/optimization.md) for PagedAttention tuning, continuous batching details, and benchmark results.
+**Performance optimization**: See [references/optimization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/optimization.md) for PagedAttention tuning, continuous batching details, and benchmark results.
 
-**Quantization guide**: See [references/quantization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/vllm/references/quantization.md) for AWQ/GPTQ/FP8 setup, model preparation, and accuracy comparisons.
+**Quantization guide**: See [references/quantization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/quantization.md) for AWQ/GPTQ/FP8 setup, model preparation, and accuracy comparisons.
 
-**Troubleshooting**: See [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/vllm/references/troubleshooting.md) for detailed error messages, debugging steps, and performance diagnostics.
+**Troubleshooting**: See [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md) for detailed error messages, debugging steps, and performance diagnostics.
 
 ## Hardware requirements
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md b/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
index 9cfa355846d..acd3b12ba9d 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
@@ -1,14 +1,14 @@
 ---
-title: "Nano Pdf — Edit PDF text/typos/titles via nano-pdf CLI (NL prompts)"
+title: "Nano Pdf — Edit text in existing PDFs via natural-language prompts"
 sidebar_label: "Nano Pdf"
-description: "Edit PDF text/typos/titles via nano-pdf CLI (NL prompts)"
+description: "Edit text in existing PDFs via natural-language prompts"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Nano Pdf
 
-Edit PDF text/typos/titles via nano-pdf CLI (NL prompts).
+Edit text in existing PDFs via natural-language prompts.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-petdex.md b/website/docs/user-guide/skills/bundled/productivity/productivity-petdex.md
deleted file mode 100644
index 56ed48d0886..00000000000
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-petdex.md
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: "Petdex — Install and select animated petdex mascots for Hermes"
-sidebar_label: "Petdex"
-description: "Install and select animated petdex mascots for Hermes"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Petdex
-
-Install and select animated petdex mascots for Hermes.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/productivity/petdex` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `petdex`, `mascot`, `display`, `cli`, `tui`, `desktop` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Petdex Skill
-
-Browse, install, and select animated "pet" mascots from the public
-[petdex](https://github.com/crafter-station/petdex) gallery. An installed pet
-reacts to agent activity (idle, running a tool, reviewing, error, done) across
-the Hermes CLI, TUI, and desktop app. This skill drives the `hermes pets` CLI
-and the `display.pet` config — it does not generate sprites.
-
-## When to Use
-
-- The user wants a desktop/terminal mascot or asks about "pets" / petdex.
-- The user wants to change, preview, or disable the active pet.
-- Diagnosing why a pet isn't showing (terminal graphics support, config).
-
-## Prerequisites
-
-- Network access to `petdex.dev` for the gallery/manifest (read-only, no auth).
-- Pillow (a core Hermes dependency) for sprite decoding — already installed.
-- For full-fidelity terminal rendering: a graphics-capable terminal (kitty,
-  Ghostty, WezTerm, iTerm2, or sixel). Otherwise a truecolor Unicode
-  half-block fallback is used automatically.
-
-## How to Run
-
-Use the `terminal` tool to run `hermes pets <subcommand>`.
-
-## Quick Reference
-
-| Goal | Command |
-| --- | --- |
-| Browse the gallery | `hermes pets list` (add a substring to filter: `hermes pets list cat`) |
-| List installed pets | `hermes pets list --installed` |
-| Install a pet | `hermes pets install <slug>` (add `--select` to make it active) |
-| Set the active pet | `hermes pets select <slug>` (omit slug for a picker) |
-| Resize the pet everywhere | `hermes pets scale <factor>` (e.g. `0.5`, clamped 0.1–3.0) |
-| Preview/animate in terminal | `hermes pets show [slug] [--cycle] [--state run]` |
-| Disable the pet | `hermes pets off` |
-| Remove a pet | `hermes pets remove <slug>` |
-| Diagnose setup | `hermes pets doctor` |
-
-## Procedure
-
-1. Find a pet: `hermes pets list <query>` and note its `slug`.
-2. Install + activate: `hermes pets install <slug> --select`.
-3. Preview it: `hermes pets show` (Ctrl+C to stop).
-4. Confirm setup: `hermes pets doctor` — shows the resolved pet, configured
-   render mode, detected terminal graphics protocol, and effective mode.
-
-Pets install into `<HERMES_HOME>/pets/<slug>/` (profile-aware). Selecting a pet
-writes `display.pet.slug` + `display.pet.enabled` to `config.yaml`.
-
-## Configuration
-
-Under `display.pet` in `config.yaml`:
-
-- `enabled` (bool) — master on/off.
-- `slug` (str) — active pet; empty = first installed.
-- `render_mode` — `auto` (detect) | `kitty` | `iterm` | `sixel` | `unicode` | `off`.
-- `scale` (float) — on-screen size of the native 192×208 frames (default 0.33,
-  clamped 0.1–3.0). One knob resizes every surface; set it with
-  `hermes pets scale <factor>`, the `/pet scale` slash command, or the desktop
-  Appearance slider.
-- `unicode_cols` (int) — width in columns for the Unicode fallback.
-
-## Pitfalls
-
-- A pet only shows once one is installed AND selected (`enabled: true`).
-- Inside a pipe/redirect (no TTY) terminal rendering is disabled by design.
-- The petdex npm CLI installs to `~/.codex/pets`; Hermes uses its own
-  profile-scoped `<HERMES_HOME>/pets/` instead — install through `hermes pets`.
-
-## Verification
-
-- `hermes pets doctor` reports `✓ ready` when a pet is installed, selected,
-  enabled, and Pillow is importable.
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md b/website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md
index 8fb4c066302..9ff14e4b53b 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md
@@ -1,14 +1,14 @@
 ---
-title: "Teams Meeting Pipeline"
+title: "Teams Meeting Pipeline — Teams meeting summaries, job replay, Graph subscriptions"
 sidebar_label: "Teams Meeting Pipeline"
-description: "Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions"
+description: "Teams meeting summaries, job replay, Graph subscriptions"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Teams Meeting Pipeline
 
-Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions.
+Teams meeting summaries, job replay, Graph subscriptions.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md b/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md
index 611215c06c3..ba7e49b7c8b 100644
--- a/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md
+++ b/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md
@@ -22,7 +22,7 @@ Write ML papers for NeurIPS/ICML/ICLR: design→submit.
 | Dependencies | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` |
 | Platforms | linux, macos |
 | Tags | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` |
-| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), `ml-paper-writing`, [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
+| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
 
 ## Reference: full SKILL.md
 
@@ -2166,7 +2166,7 @@ Compose this skill with other Hermes skills for specific phases:
 | **`memory`** | Persist key decisions across sessions: contribution framing, venue choice, reviewer feedback. |
 | **`cronjob`** | Schedule experiment monitoring, deadline countdowns, automated arXiv checks. |
 | **`clarify`** | Ask the user targeted questions when blocked (venue choice, contribution framing). |
-| **`send_message`** | Notify user when experiments complete or drafts are ready, even if user isn't in chat. |
+| **cron `deliver:`** | Notify the user when experiments complete or drafts are ready even if they're not in chat — schedule the check as a cron job with a messaging `deliver:` target (the agent no longer has a `send_message` tool; outbound delivery is handled by cron/`hermes send`). |
 
 ### Tool Usage Patterns
 
@@ -2177,7 +2177,7 @@ terminal("ps aux | grep <pattern>")
 → terminal("ls results/")
 → execute_code("analyze results JSON, compute metrics")
 → terminal("git add -A && git commit -m '<descriptive message>' && git push")
-→ send_message("Experiment complete: <summary>")
+→ (final response auto-delivers "Experiment complete: <summary>"; for unattended runs, schedule via cron with a deliver: target)
 ```
 
 **Parallel section drafting** (using delegation):
@@ -2277,7 +2277,7 @@ cronjob("create", {
 
 ### Communication Patterns
 
-**When to notify the user** (via `send_message` or direct response):
+**When to notify the user** (via your direct/final response, or a cron `deliver:` target for unattended runs):
 - Experiment batch completed (with results table)
 - Unexpected finding or failure requiring decision
 - Draft section ready for review
diff --git a/website/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood.md b/website/docs/user-guide/skills/bundled/software-development/software-development-dogfood.md
similarity index 99%
rename from website/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood.md
rename to website/docs/user-guide/skills/bundled/software-development/software-development-dogfood.md
index ff076d55f5b..5849bff96bc 100644
--- a/website/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-dogfood.md
@@ -15,7 +15,7 @@ Exploratory QA of web apps: find bugs, evidence, reports.
 | | |
 |---|---|
 | Source | Bundled (installed by default) |
-| Path | `skills/dogfood` |
+| Path | `skills/software-development/dogfood` |
 | Version | `1.0.0` |
 | Platforms | linux, macos, windows |
 | Tags | `qa`, `testing`, `browser`, `web`, `dogfood` |
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
index 10183a9a2a6..ee5ed2e16da 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
@@ -8,7 +8,7 @@ description: "Author in-repo SKILL"
 
 # Hermes Agent Skill Authoring
 
-Author in-repo SKILL.md: frontmatter, validator, structure.
+Author in-repo SKILL.md files: frontmatter and structure.
 
 ## Skill metadata
 
@@ -16,7 +16,7 @@ Author in-repo SKILL.md: frontmatter, validator, structure.
 |---|---|
 | Source | Bundled (installed by default) |
 | Path | `skills/software-development/hermes-agent-skill-authoring` |
-| Version | `1.0.0` |
+| Version | `1.1.0` |
 | Author | Hermes Agent |
 | License | MIT |
 | Platforms | linux, macos, windows |
@@ -61,7 +61,7 @@ Peer-matched shape used by every skill under `skills/software-development/`:
 ---
 name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
 description: Use when <trigger>. <one-line behavior>.
-version: 1.0.0
+version: 1.1.0
 author: Hermes Agent
 license: MIT
 metadata:
@@ -79,6 +79,29 @@ metadata:
 - Full SKILL.md: ≤ 100,000 chars (enforced as `MAX_SKILL_CONTENT_CHARS`, ~36k tokens).
 - Peer skills in `software-development/` sit at **8-14k chars**. Aim for that range. If you're pushing past 20k, split into `references/*.md` and reference them from SKILL.md.
 
+## Writing Quality Principles
+
+A skill exists to make the agent's process more predictable. Predictability does **not** mean identical output every run; it means the agent reliably follows the same useful discipline.
+
+Use these quality checks when writing or editing any skill:
+
+1. **Optimize for process predictability.** Ask: what behavior should change when this skill loads? If a line does not change behavior, cut it.
+2. **Choose the right context load.** A model-invoked Hermes skill pays for its description every turn. Keep descriptions focused on trigger classes and the skill's distinctive behavior. Put details in the body or linked references.
+3. **Use an information hierarchy.** Put always-needed steps in `SKILL.md`; put branch-specific or bulky reference material in `references/`, `templates/`, or `scripts/` and point to it only when needed.
+4. **End steps with completion criteria.** Each ordered step should say how the agent knows it is done. Good criteria are checkable and, when it matters, exhaustive: "every modified file accounted for" beats "summarize changes."
+5. **Co-locate rules with the concept they govern.** Avoid scattering one idea across the file. Keep definition, caveats, examples, and verification near each other.
+6. **Use strong leading words.** Prefer compact concepts the model already knows — e.g. "tight loop," "tracer bullet," "root cause," "regression test" — over long repeated explanations. A good leading word saves tokens and anchors behavior.
+7. **Prune duplication and no-ops.** Keep each meaning in one source of truth. Sentence by sentence, ask whether the sentence changes agent behavior versus the default. If not, delete it rather than polishing it.
+8. **Watch for premature completion.** If agents tend to rush a step, first sharpen that step's completion criterion. Split the sequence only when later steps distract from doing the current step well.
+
+Common quality failures:
+
+- **Premature completion** — the skill lets the agent move on before the work is genuinely done.
+- **Duplication** — the same rule appears in multiple places and drifts.
+- **Sediment** — stale lines remain because adding felt safer than deleting.
+- **Sprawl** — too much always-visible material; push branch-specific reference behind pointers.
+- **No-op prose** — generic advice the agent would already follow without the skill.
+
 ## Peer-Matched Structure
 
 Every in-repo skill follows roughly:
@@ -116,7 +139,7 @@ Not every section is mandatory, but `Overview` + `When to Use` + actionable body
 skills/<category>/<skill-name>/SKILL.md
 ```
 
-Categories currently in repo (confirm with `ls skills/`): `autonomous-ai-agents`, `creative`, `data-science`, `devops`, `dogfood`, `email`, `gaming`, `github`, `leisure`, `mcp`, `media`, `mlops/*`, `note-taking`, `productivity`, `red-teaming`, `research`, `smart-home`, `social-media`, `software-development`.
+Categories currently in repo (confirm with `ls skills/`): `autonomous-ai-agents`, `creative`, `data-science`, `devops`, `email`, `gaming`, `github`, `leisure`, `mcp`, `media`, `mlops/*`, `note-taking`, `productivity`, `red-teaming`, `research`, `smart-home`, `social-media`, `software-development`.
 
 Pick the closest existing category. Don't invent new top-level categories casually.
 
@@ -168,7 +191,11 @@ Pick the closest existing category. Don't invent new top-level categories casual
 
 6. **Expecting the current session to see the new skill.** It won't. The skill loader is initialized at session start. Verify in a fresh session or via `skill_view` using the exact path.
 
-7. **Linking to skills that don't exist in-repo.** `related_skills: [some-user-local-skill]` works for you but breaks for other clones. Prefer only in-repo links.
+7. **Letting skills accumulate sediment.** A skill should get shorter or sharper over time. When adding a rule, remove the old wording it replaces; don't layer advice forever.
+
+8. **Writing no-op prose.** "Be careful," "be thorough," and "use best practices" rarely change model behavior. Replace with a checkable completion criterion or a stronger leading word.
+
+9. **Linking to skills that don't exist in-repo.** `related_skills: [some-user-local-skill]` works for you but breaks for other clones. Prefer only in-repo links.
 
 ## Verification Checklist
 
@@ -179,5 +206,9 @@ Pick the closest existing category. Don't invent new top-level categories casual
 - [ ] Description ≤ 1024 chars and starts with "Use when ..."
 - [ ] Total file ≤ 100,000 chars (aim for 8-15k)
 - [ ] Structure: `# Title` → `## Overview` → `## When to Use` → body → `## Common Pitfalls` → `## Verification Checklist`
+- [ ] Each ordered step has a checkable completion criterion
+- [ ] Description is trigger-focused and avoids duplicated body content
+- [ ] Bulky or branch-specific reference is progressively disclosed in linked files
+- [ ] No-op prose and duplicated rules removed
 - [ ] `related_skills` references resolve in-repo (or are explicitly OK to be user-local)
 - [ ] `git add skills/<category>/<name>/ && git commit` completed on the intended branch
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md b/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
index 5257512e9e6..2613c25a245 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
@@ -21,7 +21,7 @@ Debug Node.js via --inspect + Chrome DevTools Protocol CLI.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |
-| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), `debugging-hermes-tui-commands` |
+| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md b/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md
index 36d390bd2f3..349c1e61e04 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md
@@ -1,14 +1,14 @@
 ---
-title: "Plan — Plan mode: write an actionable markdown plan to"
+title: "Plan — Write a markdown plan to"
 sidebar_label: "Plan"
-description: "Plan mode: write an actionable markdown plan to"
+description: "Write a markdown plan to"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Plan
 
-Plan mode: write an actionable markdown plan to .hermes/plans/, no execution. Bite-sized tasks, exact paths, complete code.
+Write a markdown plan to .hermes/plans/; no execution.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md b/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
index dbc26409efe..dcb66a389b0 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
@@ -21,7 +21,7 @@ Debug Python: pdb REPL + debugpy remote (DAP).
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` |
-| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), `debugging-hermes-tui-commands` |
+| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md b/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md
index 4fce9a3288b..49e3d0143d2 100644
--- a/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md
+++ b/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md
@@ -1,14 +1,14 @@
 ---
-title: "Simplify Code — Parallel 3-agent cleanup of recent code changes"
+title: "Simplify Code — Parallel 4-agent cleanup of recent code changes"
 sidebar_label: "Simplify Code"
-description: "Parallel 3-agent cleanup of recent code changes"
+description: "Parallel 4-agent cleanup of recent code changes"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Simplify Code
 
-Parallel 3-agent cleanup of recent code changes.
+Parallel 4-agent cleanup of recent code changes.
 
 ## Skill metadata
 
@@ -16,7 +16,7 @@ Parallel 3-agent cleanup of recent code changes.
 |---|---|
 | Source | Bundled (installed by default) |
 | Path | `skills/software-development/simplify-code` |
-| Version | `1.0.0` |
+| Version | `1.1.0` |
 | Author | Hermes Agent (inspired by Claude Code /simplify) |
 | License | MIT |
 | Platforms | linux, macos, windows |
@@ -31,13 +31,18 @@ The following is the complete skill definition that Hermes loads when this skill
 
 # Simplify Code — Parallel Review & Cleanup
 
-Review your recent code changes with three focused reviewers running in
+Review your recent code changes with four focused reviewers running in
 parallel, aggregate their findings, and apply the fixes worth applying.
 
-**Core principle:** Three narrow reviewers beat one broad reviewer. Each one
+**This is a cleanup pass, not a bug hunt.** You are improving the quality of
+code that already works — removing duplication, flattening needless
+complexity, cutting waste, and deepening band-aid fixes. Do not go hunting
+for correctness bugs here; that's what `requesting-code-review` is for.
+
+**Core principle:** Four narrow reviewers beat one broad reviewer. Each one
 deeply searches the codebase for a single class of problem — reuse, quality,
-efficiency — without diluting its attention across all three. They run
-concurrently, so you pay the latency of one review, not three.
+efficiency, altitude — without diluting its attention across all four. They
+run concurrently, so you pay the latency of one review, not four.
 
 ## When to Use
 
@@ -51,14 +56,15 @@ Optional modifiers the user may add — honor them:
 
 - **Focus:** "simplify focus on efficiency" → run only the efficiency reviewer
   (or weight the aggregation toward it). Recognized focuses: `reuse`,
-  `quality`, `efficiency`.
+  `quality` (also accepts `simplification`), `efficiency`, `altitude`.
 - **Dry run:** "simplify but don't change anything" / "just report" → run the
-  three reviewers, present findings, apply NOTHING. Ask before applying.
+  four reviewers, present findings, apply NOTHING. Ask before applying.
 - **Scope:** "simplify the last commit" / "simplify staged" / "simplify
   src/foo.py" → narrow the diff source accordingly (see Phase 1).
 
-Do NOT auto-run this after every edit. It costs three subagents' worth of
-tokens — invoke it only when the user explicitly asks.
+Do NOT auto-run this after every edit or tack it onto the end of unrelated
+tasks. It costs four subagents' worth of tokens — invoke it only when the
+user explicitly asks.
 
 ## The Process
 
@@ -87,16 +93,24 @@ recently created/edited in this session. If you genuinely can't find any
 changed code, say so and stop — there's nothing to simplify.
 
 Capture the full diff text. Note its size: if it's very large (say >2000
-changed lines), warn the user that three subagents each carrying the full diff
+changed lines), warn the user that four subagents each carrying the full diff
 will be token-heavy, and offer to scope it down (per-directory, per-commit)
 before proceeding.
 
-### Phase 2 — Launch three reviewers in parallel
+### Phase 2 — Launch four reviewers in parallel
 
-Use `delegate_task` **batch mode** — pass all three tasks in one `tasks`
-array so they run concurrently. Three is the right fan-out for this pattern;
-it's well within the `delegation.max_concurrent_children` budget on any
-default install.
+Use `delegate_task` **batch mode** — pass all four tasks in one `tasks`
+array so they run concurrently. Four is the right fan-out for this pattern;
+it's within the `delegation.max_concurrent_children` budget on any default
+install.
+
+**No delegation available?** If you can't call `delegate_task` in this
+context (you're a leaf subagent, delegation is disabled, or the budget is
+exhausted), do NOT skip the review or drop angles. Work through all four
+reviewer angles yourself, sequentially, in this context — same search
+standards, same finding format. Then say clearly in your final summary that
+this was a single-pass inline review, not the parallel fan-out, so the user
+knows what actually ran.
 
 Give **every** reviewer the **complete diff** (not fragments — cross-file
 issues hide in the gaps) plus the absolute repo path so they can search the
@@ -108,10 +122,13 @@ Tell each reviewer to:
 - **Apply Chesterton's Fence:** before flagging anything for removal, run
   `git blame` on the line to understand why it exists. If you can't determine
   the original purpose, mark it `confidence: low` — don't guess.
-- Report findings as structured output with confidence and risk:
+- Report findings as structured output with the concrete cost, confidence,
+  and risk:
   ```
-  file:line → problem → suggested fix | confidence: high/medium/low | risk: SAFE/CAREFUL/RISKY
+  file:line → problem → cost (what's duplicated/wasted/harder to maintain) → suggested fix | confidence: high/medium/low | risk: SAFE/CAREFUL/RISKY
   ```
+  The **cost** field forces each finding to justify itself — a finding that
+  can't articulate what the problem actually costs is probably a nit.
   - **SAFE** = proven not to affect behavior (unused imports, commented-out
     code, pass-through wrappers). Auto-apply these.
   - **CAREFUL** = improves without changing semantics (rename local variable,
@@ -122,7 +139,7 @@ Tell each reviewer to:
 - Skip nits and style-only churn. Only flag things that materially improve
   the code.
 
-Pass these three goals (drop any the user's focus excludes):
+Pass these four goals (drop any the user's focus excludes):
 
 **Reviewer 1 — Code Reuse**
 > Review this diff for code that duplicates functionality already in the
@@ -142,7 +159,9 @@ Pass these three goals (drop any the user's focus excludes):
 > blocks that should share an abstraction); leaky abstractions (exposing
 > internals, breaking an existing encapsulation boundary); stringly-typed
 > code (raw strings where a constant/enum/registry already exists — check the
-> canonical registries before flagging); AI-generated slop patterns (extra
+> canonical registries before flagging); deeply nested conditionals (ternary
+> chains, 3+-level if/else pyramids — flatten with guard clauses, early
+> returns, or a lookup table); AI-generated slop patterns (extra
 > comments restating obvious code like `// increment counter` above `count++`;
 > unnecessary defensive null-checks on already-validated inputs; `as any`
 > casts that bypass the type system; patterns inconsistent with the rest of
@@ -155,17 +174,41 @@ Pass these three goals (drop any the user's focus excludes):
 > hot-path bloat (heavy/blocking work on startup or per-request paths);
 > TOCTOU anti-patterns (existence pre-checks before an op instead of doing
 > the op and handling the error); memory issues (unbounded growth, missing
-> cleanup, listener/handle leaks); overly broad reads (loading whole files
-> when a slice would do); silent failures (empty catch blocks, ignored error
-> returns, `except: pass`, `.catch(() => {})` with no handling, error
-> propagation gaps — these hide bugs and should at minimum log before
-> swallowing). For each, give the concrete fix and why it's faster or safer.
+> cleanup, listener/handle leaks; long-lived callbacks or objects built as
+> closures that capture the whole enclosing scope — everything captured
+> stays alive as long as the object does, so prefer a small class or
+> explicit-fields struct that copies only what it needs); overly broad reads
+> (loading whole files when a slice would do); silent failures (empty catch
+> blocks, ignored error returns, `except: pass`, `.catch(() => {})` with no
+> handling, error propagation gaps — these hide bugs and should at minimum
+> log before swallowing). For each, give the concrete fix and why it's
+> faster or safer.
+
+**Reviewer 4 — Altitude**
+> Review this diff for changes implemented at the wrong depth — band-aids
+> layered on top of shared infrastructure instead of fixes to the
+> infrastructure itself. Signs of a too-shallow fix: a special case added to
+> a generic code path to handle one caller (an `if (caller == X)` branch, a
+> type check, a magic-value escape hatch); a symptom patched at the call
+> site while sibling call sites keep the same flaw; a workaround stacked on
+> an earlier workaround; a wrapper added to avoid touching the thing that
+> actually needs changing; configuration or flags introduced to route around
+> a broken default instead of fixing the default. For each, identify the
+> underlying mechanism the change is dodging and describe the deeper fix —
+> generalize the shared path, fix the root default, or fix the whole bug
+> class — and honestly note when the deeper fix is large enough that it
+> should be its own task rather than part of this cleanup. Read the
+> surrounding code and `git blame` first: what looks like a band-aid is
+> sometimes a deliberate boundary (compat shims, staged migrations,
+> vendored-code isolation). Don't flag those.
 
 ### Phase 3 — Aggregate and apply
 
-Wait for all three to return (batch mode returns them together).
+Wait for all four to return (batch mode returns them together).
 
-1. **Merge** the findings into one list, deduping where reviewers overlap.
+1. **Merge** the findings into one list, deduping where reviewers overlap —
+   when two findings target the same line or the same underlying mechanism,
+   collapse them into one.
 2. **Discard false positives** — you have the most context; you don't have to
    argue with a reviewer, just drop weak or wrong suggestions silently.
 3. **Resolve conflicts.** Reviewers can disagree (Reviewer 1: "use existing
@@ -182,20 +225,23 @@ Wait for all three to return (batch mode returns them together).
      after each file. Revert any that break.
    - **RISKY last** (flag for review — do NOT auto-apply): N+1 restructuring,
      public API changes, concurrency fixes, error-handling changes. Present
-     each with risk description and test coverage status.
+     each with risk description and test coverage status. Altitude findings
+     usually land here — deepening a fix means touching shared
+     infrastructure, so present the deeper fix and let the user decide
+     whether to do it now or as a follow-up.
    If the user opted for a dry run, present all three tiers and apply nothing.
 5. **Verify** you didn't break anything: run the project's targeted tests for
    the touched files (not the full suite), and re-run any linter/type check the
    repo uses. If a fix breaks a test, revert that one fix and report it.
 6. **Summarize** what you changed: a short list of applied fixes grouped by
    reviewer category and risk tier, plus any findings you deliberately skipped
-   and why.
+   and why. If you ran inline (no delegation), say so here.
 
 ## Pitfalls
 
-- **Don't fan out wider than ~3.** More reviewers means more cost and more
-  conflicting suggestions to reconcile, not better coverage. Three categories
-  cover the space.
+- **Don't fan out wider than 4.** More reviewers means more cost and more
+  conflicting suggestions to reconcile, not better coverage. The four
+  categories cover the space.
 - **Give the WHOLE diff to each reviewer.** Splitting the diff across reviewers
   defeats the design — cross-file duplication and N+1s only show up with the
   full picture.
@@ -204,12 +250,19 @@ Wait for all three to return (batch mode returns them together).
   `file:line` evidence; drop findings that lack it.
 - **Apply ≠ rewrite.** This is cleanup of the user's recent changes, not a
   license to refactor the whole module. Keep edits scoped to what the diff
-  touched plus the minimal surrounding change a fix requires.
+  touched plus the minimal surrounding change a fix requires. Altitude
+  findings are the exception that proves the rule: when the right fix is
+  deeper than the diff, FLAG it — don't unilaterally rebuild the shared
+  mechanism inside a cleanup pass.
+- **Don't drift into bug-hunting.** If a reviewer surfaces a genuine
+  correctness bug, report it prominently — but as a separate "found a bug"
+  note, not folded into cleanup fixes. Correctness review is a different
+  pass with different verification standards.
 - **Respect project conventions.** If the repo has AGENTS.md / CLAUDE.md /
   HERMES.md or a linter config, fold those rules into the reviewer prompts so
   suggestions match house style instead of fighting it.
 - **Large diffs blow context.** If the diff is huge, scope it down before
-  delegating — three subagents each carrying a 5000-line diff is expensive and
+  delegating — four subagents each carrying a 5000-line diff is expensive and
   may truncate.
 - **Over-trusting dead code tools.** `knip`, `ts-prune`, and `depcheck` flag
   exports that ARE used dynamically (string-based imports, reflection). Always
@@ -221,10 +274,15 @@ Wait for all three to return (batch mode returns them together).
 - **Removing "unnecessary" error handling.** An empty catch block or ignored
   error might be intentional — the error is expected and benign in that
   context. Flag it, don't remove it; let the human decide.
+- **Not every special case is a band-aid.** Compat shims, staged migrations,
+  and isolation layers around vendored code look like altitude violations but
+  are deliberate design. Check `git blame` and surrounding comments before
+  flagging; when the intent is unclear, mark `confidence: low`.
 
 ## Related
 
 If your install has the `subagent-driven-development` skill (optional), it
 covers the complementary case: parallel review *during* implementation, per
 task. This skill is the standalone *after-the-fact* cleanup pass. Use
-`requesting-code-review` for the pre-commit security/quality gate.
+`requesting-code-review` for the pre-commit security/quality gate — that's
+the bug hunt; this is the cleanup.
diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md
index 737ae091a83..89fb98fc872 100644
--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md
+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md
@@ -1,14 +1,14 @@
 ---
-title: "Blackbox — Delegate coding tasks to Blackbox AI CLI agent"
+title: "Blackbox — Delegate coding tasks to the Blackbox AI multi-model CLI"
 sidebar_label: "Blackbox"
-description: "Delegate coding tasks to Blackbox AI CLI agent"
+description: "Delegate coding tasks to the Blackbox AI multi-model CLI"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Blackbox
 
-Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key.
+Delegate coding tasks to the Blackbox AI multi-model CLI.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md
index a54a2a0dea0..4d3c1c1a452 100644
--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md
+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md
@@ -1,14 +1,14 @@
 ---
-title: "Honcho"
+title: "Honcho — Configure and troubleshoot Honcho memory for Hermes"
 sidebar_label: "Honcho"
-description: "Configure and use Honcho memory with Hermes -- cross-session user modeling, multi-profile peer isolation, observation config, dialectic reasoning, session su..."
+description: "Configure and troubleshoot Honcho memory for Hermes"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Honcho
 
-Configure and use Honcho memory with Hermes -- cross-session user modeling, multi-profile peer isolation, observation config, dialectic reasoning, session summaries, and context budget enforcement. Use when setting up Honcho, troubleshooting memory, managing profiles with Honcho peers, or tuning observation, recall, and dialectic settings.
+Configure and troubleshoot Honcho memory for Hermes.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/blockchain/blockchain-solana.md b/website/docs/user-guide/skills/optional/blockchain/blockchain-solana.md
index 793faaff966..f2c293ef7c3 100644
--- a/website/docs/user-guide/skills/optional/blockchain/blockchain-solana.md
+++ b/website/docs/user-guide/skills/optional/blockchain/blockchain-solana.md
@@ -1,14 +1,14 @@
 ---
-title: "Solana"
+title: "Solana — Query Solana wallets, tokens, txs, and NFTs in USD"
 sidebar_label: "Solana"
-description: "Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network s..."
+description: "Query Solana wallets, tokens, txs, and NFTs in USD"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Solana
 
-Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network stats. Uses Solana RPC + CoinGecko. No API key required.
+Query Solana wallets, tokens, txs, and NFTs in USD.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md b/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
similarity index 96%
rename from website/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md
rename to website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
index 2360025bb2a..cde300fc264 100644
--- a/website/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
@@ -14,14 +14,15 @@ AudioCraft: MusicGen text-to-music, AudioGen text-to-sound.
 
 | | |
 |---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/mlops/models/audiocraft` |
+| Source | Optional — install with `hermes skills install official/creative/audiocraft-audio-generation` |
+| Path | `optional-skills/creative/audiocraft-audio-generation` |
 | Version | `1.0.0` |
 | Author | Orchestra Research |
 | License | MIT |
 | Dependencies | `audiocraft`, `torch>=2.0.0`, `transformers>=4.30.0` |
 | Platforms | linux, macos |
 | Tags | `Multimodal`, `Audio Generation`, `Text-to-Music`, `Text-to-Audio`, `MusicGen` |
+| Related skills | [`heartmula`](/docs/user-guide/skills/optional/creative/creative-heartmula), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
 
 ## Reference: full SKILL.md
 
@@ -575,8 +576,8 @@ for desc in descriptions:
 
 ## References
 
-- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/audiocraft/references/advanced-usage.md)** - Training, fine-tuning, deployment
-- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/audiocraft/references/troubleshooting.md)** - Common issues and solutions
+- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md)** - Training, fine-tuning, deployment
+- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md)** - Common issues and solutions
 
 ## Resources
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md b/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md
index 9b3ba92b3bd..09ac135f4ae 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md
@@ -1,14 +1,14 @@
 ---
-title: "Concept Diagrams"
+title: "Concept Diagrams — Generate flat, minimal educational SVG visuals as HTML"
 sidebar_label: "Concept Diagrams"
-description: "Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sente..."
+description: "Generate flat, minimal educational SVG visuals as HTML"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Concept Diagrams
 
-Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and non-software visuals — physics setups, chemistry mechanisms, math curves, physical objects (aircraft, turbines, smartphones, mechanical watches), anatomy, floor plans, cross-sections, narrative journeys (lifecycle of X, process of Y), hub-spoke system integrations (smart city, IoT), and exploded layer views. If a more specialized skill exists for the subject (dedicated software/cloud architecture, hand-drawn sketches, animated explainers, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback with a clean educational look. Ships with 15 example diagrams.
+Generate flat, minimal educational SVG visuals as HTML.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, u
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `diagrams`, `svg`, `visualization`, `education`, `physics`, `chemistry`, `engineering` |
-| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), `generative-widgets` |
+| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/bundled/media/media-heartmula.md b/website/docs/user-guide/skills/optional/creative/creative-heartmula.md
similarity index 94%
rename from website/docs/user-guide/skills/bundled/media/media-heartmula.md
rename to website/docs/user-guide/skills/optional/creative/creative-heartmula.md
index 17e72f9ed0f..16dcf43c229 100644
--- a/website/docs/user-guide/skills/bundled/media/media-heartmula.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-heartmula.md
@@ -14,12 +14,12 @@ HeartMuLa: Suno-like song generation from lyrics + tags.
 
 | | |
 |---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/media/heartmula` |
+| Source | Optional — install with `hermes skills install official/creative/heartmula` |
+| Path | `optional-skills/creative/heartmula` |
 | Version | `1.0.0` |
 | Platforms | linux, macos, windows |
 | Tags | `music`, `audio`, `generation`, `ai`, `heartmula`, `heartcodec`, `lyrics`, `songs` |
-| Related skills | `audiocraft` |
+| Related skills | [`audiocraft-audio-generation`](/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md b/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md
index fc27d61d579..3f453acd8db 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md
@@ -1,14 +1,14 @@
 ---
-title: "Hyperframes"
+title: "Hyperframes — Render MP4/WebM videos from HTML compositions"
 sidebar_label: "Hyperframes"
-description: "Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions us..."
+description: "Render MP4/WebM videos from HTML compositions"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Hyperframes
 
-Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions using HyperFrames. HTML is the source of truth for video. Use when the user wants a rendered MP4/WebM from an HTML composition, wants to animate text/logos/charts over media, needs captions synced to audio, wants TTS narration, or wants to convert a website into a video.
+Render MP4/WebM videos from HTML compositions.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md b/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
index 7195aaceeaf..e36a5cd48c6 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
@@ -21,7 +21,7 @@ Plan, set up, and monitor a multi-agent video production pipeline backed by Herm
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `video`, `kanban`, `multi-agent`, `orchestration`, `production-pipeline` |
-| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui), [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp), [`blender-mcp`](/docs/user-guide/skills/optional/creative/creative-blender-mcp), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/bundled/media/media-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), `spotify`, [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`baoyu-comic`](/docs/user-guide/skills/optional/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) |
+| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui), [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp), [`blender-mcp`](/docs/user-guide/skills/optional/creative/creative-blender-mcp), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/optional/creative/creative-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`baoyu-comic`](/docs/user-guide/skills/optional/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) |
 
 ## Reference: full SKILL.md
 
@@ -186,8 +186,9 @@ task graphs. See **[references/examples.md](https://github.com/NousResearch/herm
 6. **The director never executes.** Even with the full `kanban + terminal +
    file` toolset, the director's `SOUL.md` rules forbid it from executing
    work itself. It decomposes and routes only — every concrete task becomes
-   a `hermes kanban create` call to a specialist profile. The
-   auto-injected kanban orchestration guidance spells this out further.
+   a `hermes kanban create` call to a specialist profile. The kanban
+   orchestration guidance auto-injected into every kanban worker's system
+   prompt spells this out further.
 
 7. **Don't over-decompose.** A 30-second product video does NOT need 20 tasks.
    Aim for the smallest task graph that still parallelizes well and exposes the
diff --git a/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md b/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md
index 836780c678d..605fe7ddc0b 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md
@@ -1,14 +1,14 @@
 ---
-title: "Meme Generation — Generate real meme images by picking a template and overlaying text with Pillow"
+title: "Meme Generation — Create meme PNGs from templates with Pillow text overlay"
 sidebar_label: "Meme Generation"
-description: "Generate real meme images by picking a template and overlaying text with Pillow"
+description: "Create meme PNGs from templates with Pillow text overlay"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Meme Generation
 
-Generate real meme images by picking a template and overlaying text with Pillow. Produces actual .png meme files.
+Create meme PNGs from templates with Pillow text overlay.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Generate real meme images by picking a template and overlaying text with Pillow.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `creative`, `memes`, `humor`, `images` |
-| Related skills | [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art), `generative-widgets` |
+| Related skills | [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md b/website/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md
index 1a369b1a60d..7ffd9b9408a 100644
--- a/website/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md
+++ b/website/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md
@@ -1,14 +1,14 @@
 ---
-title: "Unreal Mcp"
+title: "Unreal Mcp — Automate Unreal Engine editor scenes, actors, and renders"
 sidebar_label: "Unreal Mcp"
-description: "Use when the user wants to do anything in Unreal Engine through Epic's official editor-embedded MCP server (catalog entry: unreal-engine) — build/light/popul..."
+description: "Automate Unreal Engine editor scenes, actors, and renders"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Unreal Mcp
 
-Use when the user wants to do anything in Unreal Engine through Epic's official editor-embedded MCP server (catalog entry: unreal-engine) — build/light/populate scenes, place and transform actors, author Blueprints, animate with Sequencer, create material instances, frame cameras, take screenshots, render, import assets, run PIE test sessions and automation tests, or automate the editor end-to-end from plain-English prompts with no Unreal knowledge required. Covers the tool-search discovery walk (list_toolsets/describe_toolset/call_tool), serial game-thread call discipline, ProgrammaticToolset batching, the Blueprint graph DSL loop, scene-craft numbers (physical light units, exposure, scale conventions), complete build recipes, save/undo hygiene, and extending the tool surface with custom Python toolsets.
+Automate Unreal Engine editor scenes, actors, and renders.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md b/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md
similarity index 84%
rename from website/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md
rename to website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md
index 8b75ecffb17..a869a968d21 100644
--- a/website/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md
+++ b/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md
@@ -1,12 +1,12 @@
 ---
-title: "Jupyter Live Kernel — Iterative Python via live Jupyter kernel (hamelnb)"
-sidebar_label: "Jupyter Live Kernel"
+title: "Jupyter Notebook — Iterative Python via live Jupyter kernel (hamelnb)"
+sidebar_label: "Jupyter Notebook"
 description: "Iterative Python via live Jupyter kernel (hamelnb)"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
-# Jupyter Live Kernel
+# Jupyter Notebook
 
 Iterative Python via live Jupyter kernel (hamelnb).
 
@@ -14,8 +14,8 @@ Iterative Python via live Jupyter kernel (hamelnb).
 
 | | |
 |---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/data-science/jupyter-live-kernel` |
+| Source | Optional — install with `hermes skills install official/data-science/jupyter-notebook` |
+| Path | `optional-skills/data-science/jupyter-notebook` |
 | Version | `1.0.0` |
 | Author | Hermes Agent |
 | License | MIT |
@@ -28,7 +28,7 @@ Iterative Python via live Jupyter kernel (hamelnb).
 The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
 :::
 
-# Jupyter Live Kernel (hamelnb)
+# Jupyter Notebook (hamelnb live kernel)
 
 Gives you a **stateful Python REPL** via a live Jupyter kernel. Variables persist
 across executions. Use this instead of `execute_code` when you need to build up
@@ -177,6 +177,17 @@ uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compac
 8. **Occasional websocket timeouts** — some operations may timeout on first try,
    especially after a kernel restart. Retry once before escalating.
 
+9. **If websocket consistently times out on this host**, force zmq transport:
+   `uv run "$SCRIPT" execute --transport zmq ...`. Symptom: every execute returns
+   "Websocket execution may already have reached the kernel, so auto fallback was
+   skipped". The kernel actually ran fine (REST shows execution_state=idle and
+   execution_count increments) — only the websocket reply channel is broken.
+   zmq transport uses jupyter_client directly and sidesteps the issue.
+
+10. **When starting a fresh server for REST-only use**, add
+    `--ServerApp.disable_check_xsrf=True` — otherwise POST /api/sessions returns
+    `"'_xsrf' argument missing from POST"` and kernel session creation fails.
+
 ## Timeout Defaults
 
 The script has a 30-second default timeout per execution. For long-running
diff --git a/website/docs/user-guide/skills/optional/devops/devops-cli.md b/website/docs/user-guide/skills/optional/devops/devops-cli.md
index b0abaf8bc90..9eced67e92f 100644
--- a/website/docs/user-guide/skills/optional/devops/devops-cli.md
+++ b/website/docs/user-guide/skills/optional/devops/devops-cli.md
@@ -1,14 +1,14 @@
 ---
-title: "Inference Sh Cli — Run 150+ AI apps via inference"
+title: "Inference Sh Cli — Run 150+ AI apps (image, video, LLM) via inference"
 sidebar_label: "Inference Sh Cli"
-description: "Run 150+ AI apps via inference"
+description: "Run 150+ AI apps (image, video, LLM) via inference"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Inference Sh Cli
 
-Run 150+ AI apps via inference.sh CLI (infsh) — image generation, video creation, LLMs, search, 3D, social automation. Uses the terminal tool. Triggers: inference.sh, infsh, ai apps, flux, veo, image generation, video generation, seedream, seedance, tavily
+Run 150+ AI apps (image, video, LLM) via inference.sh CLI.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/devops/devops-docker-management.md b/website/docs/user-guide/skills/optional/devops/devops-docker-management.md
index 64490ed819b..bc9c60c9c69 100644
--- a/website/docs/user-guide/skills/optional/devops/devops-docker-management.md
+++ b/website/docs/user-guide/skills/optional/devops/devops-docker-management.md
@@ -1,14 +1,14 @@
 ---
-title: "Docker Management"
+title: "Docker Management — Manage Docker containers, images, volumes, and Compose"
 sidebar_label: "Docker Management"
-description: "Manage Docker containers, images, volumes, networks, and Compose stacks — lifecycle ops, debugging, cleanup, and Dockerfile optimization"
+description: "Manage Docker containers, images, volumes, and Compose"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Docker Management
 
-Manage Docker containers, images, volumes, networks, and Compose stacks — lifecycle ops, debugging, cleanup, and Dockerfile optimization.
+Manage Docker containers, images, volumes, and Compose.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md b/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md
index 08bb067512b..6bcadfa0acb 100644
--- a/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md
+++ b/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md
@@ -1,14 +1,14 @@
 ---
-title: "Hermes S6 Container Supervision"
+title: "Hermes S6 Container Supervision — Modify or debug s6 services in the Hermes Docker image"
 sidebar_label: "Hermes S6 Container Supervision"
-description: "Modify, debug, or extend the s6-overlay supervision tree inside the Hermes Agent Docker image — adding new services, debugging profile gateways, understandin..."
+description: "Modify or debug s6 services in the Hermes Docker image"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Hermes S6 Container Supervision
 
-Modify, debug, or extend the s6-overlay supervision tree inside the Hermes Agent Docker image — adding new services, debugging profile gateways, understanding the Architecture B main-program pattern.
+Modify or debug s6 services in the Hermes Docker image.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Modify, debug, or extend the s6-overlay supervision tree inside the Hermes Agent
 | License | MIT |
 | Platforms | linux |
 | Tags | `docker`, `s6`, `supervision`, `gateway`, `profiles` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), `hermes-agent-dev` |
+| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md b/website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md
index 18fb572bdcb..ff7ec24d229 100644
--- a/website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md
+++ b/website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md
@@ -21,7 +21,6 @@ Zero-install localhost tunnels over SSH via Pinggy.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Pinggy`, `Tunnel`, `Networking`, `SSH`, `Webhook`, `Localhost` |
-| Related skills | `cloudflared-quick-tunnel`, `webhook-subscriptions` |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md b/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
index 159f3631d1b..2a552a58464 100644
--- a/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
+++ b/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
@@ -1,14 +1,14 @@
 ---
-title: "Adversarial Ux Test — Roleplay the most difficult, tech-resistant user for your product"
+title: "Adversarial Ux Test — Roleplay a hostile user to find and triage UX pain points"
 sidebar_label: "Adversarial Ux Test"
-description: "Roleplay the most difficult, tech-resistant user for your product"
+description: "Roleplay a hostile user to find and triage UX pain points"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Adversarial Ux Test
 
-Roleplay the most difficult, tech-resistant user for your product. Browse the app as that persona, find every UX pain point, then filter complaints through a pragmatism layer to separate real problems from noise. Creates actionable tickets from genuine issues only.
+Roleplay a hostile user to find and triage UX pain points.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Roleplay the most difficult, tech-resistant user for your product. Browse the ap
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `qa`, `ux`, `testing`, `adversarial`, `dogfood`, `personas`, `user-testing` |
-| Related skills | [`dogfood`](/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood) |
+| Related skills | [`dogfood`](/docs/user-guide/skills/bundled/software-development/software-development-dogfood) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/email/email-agentmail.md b/website/docs/user-guide/skills/optional/email/email-agentmail.md
index 8f35ecf20ed..0e500da190c 100644
--- a/website/docs/user-guide/skills/optional/email/email-agentmail.md
+++ b/website/docs/user-guide/skills/optional/email/email-agentmail.md
@@ -1,14 +1,14 @@
 ---
-title: "Agentmail — Give the agent its own dedicated email inbox via AgentMail"
+title: "Agentmail — Give the agent its own inbox: send and receive email"
 sidebar_label: "Agentmail"
-description: "Give the agent its own dedicated email inbox via AgentMail"
+description: "Give the agent its own inbox: send and receive email"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Agentmail
 
-Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to).
+Give the agent its own inbox: send and receive email.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md b/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md
index 886f4f0f7a1..d945e58e49a 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md
@@ -1,14 +1,14 @@
 ---
-title: "3 Statement Model"
+title: "3 Statement Model — Build integrated IS/BS/CF financial workbooks in Excel"
 sidebar_label: "3 Statement Model"
-description: "Build fully-integrated 3-statement models (IS, BS, CF) in Excel with working capital schedules, D&A roll-forwards, debt schedule, and the plugs that make cas..."
+description: "Build integrated IS/BS/CF financial workbooks in Excel"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # 3 Statement Model
 
-Build fully-integrated 3-statement models (IS, BS, CF) in Excel with working capital schedules, D&A roll-forwards, debt schedule, and the plugs that make cash and retained earnings tie. Pairs with excel-author.
+Build integrated IS/BS/CF financial workbooks in Excel.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md b/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md
index 952f030567c..192f0f98e5e 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md
@@ -1,14 +1,14 @@
 ---
-title: "Comps Analysis"
+title: "Comps Analysis — Build comparable-company valuation workbooks in Excel"
 sidebar_label: "Comps Analysis"
-description: "Build comparable company analysis in Excel — operating metrics, valuation multiples, statistical benchmarking vs peer sets"
+description: "Build comparable-company valuation workbooks in Excel"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Comps Analysis
 
-Build comparable company analysis in Excel — operating metrics, valuation multiples, statistical benchmarking vs peer sets. Pairs with excel-author. Use for public-company valuation, IPO pricing, sector benchmarking, or outlier detection.
+Build comparable-company valuation workbooks in Excel.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md b/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md
index 36d491657b5..34a847d2db7 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md
@@ -1,14 +1,14 @@
 ---
-title: "Dcf Model"
+title: "Dcf Model — Build discounted cash flow valuation workbooks in Excel"
 sidebar_label: "Dcf Model"
-description: "Build institutional-quality DCF valuation models in Excel — revenue projections, FCF build, WACC, terminal value, Bear/Base/Bull scenarios, 5x5 sensitivity t..."
+description: "Build discounted cash flow valuation workbooks in Excel"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Dcf Model
 
-Build institutional-quality DCF valuation models in Excel — revenue projections, FCF build, WACC, terminal value, Bear/Base/Bull scenarios, 5x5 sensitivity tables. Pairs with excel-author. Use for intrinsic-value equity analysis.
+Build discounted cash flow valuation workbooks in Excel.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
index 1fcff553c53..732080ee06d 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
@@ -1,14 +1,14 @@
 ---
-title: "Excel Author"
+title: "Excel Author — Build auditable financial workbooks headless via openpyxl"
 sidebar_label: "Excel Author"
-description: "Build auditable Excel workbooks headless with openpyxl — blue/black/green cell conventions, formulas over hardcodes, named ranges, balance checks, sensitivit..."
+description: "Build auditable financial workbooks headless via openpyxl"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Excel Author
 
-Build auditable Excel workbooks headless with openpyxl — blue/black/green cell conventions, formulas over hardcodes, named ranges, balance checks, sensitivity tables. Use for financial models, audit outputs, reconciliations.
+Build auditable financial workbooks headless via openpyxl.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md b/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md
index 82a76c67dbf..052cf588096 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md
@@ -1,14 +1,14 @@
 ---
-title: "Lbo Model"
+title: "Lbo Model — Build leveraged buyout workbooks with IRR/MOIC in Excel"
 sidebar_label: "Lbo Model"
-description: "Build leveraged buyout models in Excel — sources & uses, debt schedule, cash sweep, exit multiple, IRR/MOIC sensitivity"
+description: "Build leveraged buyout workbooks with IRR/MOIC in Excel"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Lbo Model
 
-Build leveraged buyout models in Excel — sources & uses, debt schedule, cash sweep, exit multiple, IRR/MOIC sensitivity. Pairs with excel-author. Use for PE screening, sponsor-case valuation, or illustrative LBO in a pitch.
+Build leveraged buyout workbooks with IRR/MOIC in Excel.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-merger-model.md b/website/docs/user-guide/skills/optional/finance/finance-merger-model.md
index 30e8ffcd5be..c7876caac84 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-merger-model.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-merger-model.md
@@ -1,14 +1,14 @@
 ---
-title: "Merger Model — Build accretion/dilution (merger) models in Excel — pro-forma P&L, synergies, financing mix, EPS impact"
+title: "Merger Model — Build M&A accretion/dilution workbooks in Excel"
 sidebar_label: "Merger Model"
-description: "Build accretion/dilution (merger) models in Excel — pro-forma P&L, synergies, financing mix, EPS impact"
+description: "Build M&A accretion/dilution workbooks in Excel"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Merger Model
 
-Build accretion/dilution (merger) models in Excel — pro-forma P&L, synergies, financing mix, EPS impact. Pairs with excel-author. Use for M&A pitches, board materials, or deal evaluation.
+Build M&A accretion/dilution workbooks in Excel.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
index a7f863289d4..ae7d711c396 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
@@ -8,7 +8,7 @@ description: "Build PowerPoint decks headless with python-pptx"
 
 # Pptx Author
 
-Build PowerPoint decks headless with python-pptx. Pairs with excel-author for model-backed decks where every number traces to a workbook cell. Use for pitch decks, IC memos, earnings notes.
+Build PowerPoint decks headless with python-pptx.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md b/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md
index 3efe47b12b8..8012434d42d 100644
--- a/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md
+++ b/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md
@@ -1,14 +1,14 @@
 ---
-title: "Fastmcp — Build, test, inspect, install, and deploy MCP servers with FastMCP in Python"
+title: "Fastmcp — Build, test, and deploy Python MCP servers"
 sidebar_label: "Fastmcp"
-description: "Build, test, inspect, install, and deploy MCP servers with FastMCP in Python"
+description: "Build, test, and deploy Python MCP servers"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Fastmcp
 
-Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Use when creating a new MCP server, wrapping an API or database as MCP tools, exposing resources or prompts, or preparing a FastMCP server for Claude Code, Cursor, or HTTP deployment.
+Build, test, and deploy Python MCP servers.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Us
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `MCP`, `FastMCP`, `Python`, `Tools`, `Resources`, `Prompts`, `Deployment` |
-| Related skills | `native-mcp`, [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
+| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md b/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md
index e2157f4b84e..935382b96fc 100644
--- a/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md
+++ b/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md
@@ -21,7 +21,7 @@ Manual OAuth for remote MCP servers on headless gateways.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `MCP`, `OAuth`, `PKCE`, `Remote-Deployment` |
-| Related skills | `native-mcp`, [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter), [`fastmcp`](/docs/user-guide/skills/optional/mcp/mcp-fastmcp) |
+| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter), [`fastmcp`](/docs/user-guide/skills/optional/mcp/mcp-fastmcp) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/mcp/mcp-mcporter.md b/website/docs/user-guide/skills/optional/mcp/mcp-mcporter.md
index 9c52f9654c8..0bc09c9a4f1 100644
--- a/website/docs/user-guide/skills/optional/mcp/mcp-mcporter.md
+++ b/website/docs/user-guide/skills/optional/mcp/mcp-mcporter.md
@@ -1,14 +1,14 @@
 ---
-title: "Mcporter"
+title: "Mcporter — List, auth, and call MCP servers/tools from the terminal"
 sidebar_label: "Mcporter"
-description: "Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type gene..."
+description: "List, auth, and call MCP servers/tools from the terminal"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Mcporter
 
-Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
+List, auth, and call MCP servers/tools from the terminal.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md b/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md
index 5837b10511d..f2e9fba4e7c 100644
--- a/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md
+++ b/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md
@@ -1,14 +1,14 @@
 ---
-title: "Openclaw Migration — Migrate a user's OpenClaw customization footprint into Hermes Agent"
+title: "Openclaw Migration — Import an OpenClaw setup (memories, skills) into Hermes"
 sidebar_label: "Openclaw Migration"
-description: "Migrate a user's OpenClaw customization footprint into Hermes Agent"
+description: "Import an OpenClaw setup (memories, skills) into Hermes"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Openclaw Migration
 
-Migrate a user's OpenClaw customization footprint into Hermes Agent. Imports Hermes-compatible memories, SOUL.md, command allowlists, user skills, and selected workspace assets from ~/.openclaw, then reports exactly what could not be migrated and why.
+Import an OpenClaw setup (memories, skills) into Hermes.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-accelerate.md b/website/docs/user-guide/skills/optional/mlops/mlops-accelerate.md
index cde80bfd39a..3ec9b87b6fe 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-accelerate.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-accelerate.md
@@ -1,14 +1,14 @@
 ---
-title: "Huggingface Accelerate — Simplest distributed training API"
+title: "Huggingface Accelerate — Run PyTorch training across GPUs with minimal changes"
 sidebar_label: "Huggingface Accelerate"
-description: "Simplest distributed training API"
+description: "Run PyTorch training across GPUs with minimal changes"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Huggingface Accelerate
 
-Simplest distributed training API. 4 lines to add distributed support to any PyTorch script. Unified API for DeepSpeed/FSDP/Megatron/DDP. Automatic device placement, mixed precision (FP16/BF16/FP8). Interactive config, single launch command. HuggingFace ecosystem standard.
+Run PyTorch training across GPUs with minimal changes.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-chroma.md b/website/docs/user-guide/skills/optional/mlops/mlops-chroma.md
index 990ffd5f92b..1dafc4cc54b 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-chroma.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-chroma.md
@@ -1,14 +1,14 @@
 ---
-title: "Chroma — Open-source embedding database for AI applications"
+title: "Chroma — Embedding database for RAG and semantic search"
 sidebar_label: "Chroma"
-description: "Open-source embedding database for AI applications"
+description: "Embedding database for RAG and semantic search"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Chroma
 
-Open-source embedding database for AI applications. Store embeddings and metadata, perform vector and full-text search, filter by metadata. Simple 4-function API. Scales from notebooks to production clusters. Use for semantic search, RAG applications, or document retrieval. Best for local development and open-source projects.
+Embedding database for RAG and semantic search.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-clip.md b/website/docs/user-guide/skills/optional/mlops/mlops-clip.md
index 3351a12130f..e9266e443b2 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-clip.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-clip.md
@@ -1,14 +1,14 @@
 ---
-title: "Clip — OpenAI's model connecting vision and language"
+title: "Clip — Zero-shot image classification and image-text search"
 sidebar_label: "Clip"
-description: "OpenAI's model connecting vision and language"
+description: "Zero-shot image classification and image-text search"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Clip
 
-OpenAI's model connecting vision and language. Enables zero-shot image classification, image-text matching, and cross-modal retrieval. Trained on 400M image-text pairs. Use for image search, content moderation, or vision-language tasks without fine-tuning. Best for general-purpose image understanding.
+Zero-shot image classification and image-text search.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-faiss.md b/website/docs/user-guide/skills/optional/mlops/mlops-faiss.md
index 4a837754065..e83bc5a59be 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-faiss.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-faiss.md
@@ -1,14 +1,14 @@
 ---
-title: "Faiss — Facebook's library for efficient similarity search and clustering of dense vectors"
+title: "Faiss — Fast vector similarity search at billion scale"
 sidebar_label: "Faiss"
-description: "Facebook's library for efficient similarity search and clustering of dense vectors"
+description: "Fast vector similarity search at billion scale"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Faiss
 
-Facebook's library for efficient similarity search and clustering of dense vectors. Supports billions of vectors, GPU acceleration, and various index types (Flat, IVF, HNSW). Use for fast k-NN search, large-scale vector retrieval, or when you need pure similarity search without metadata. Best for high-performance applications.
+Fast vector similarity search at billion scale.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md b/website/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md
index c688439d719..03ebed78249 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md
@@ -1,14 +1,14 @@
 ---
-title: "Optimizing Attention Flash"
+title: "Optimizing Attention Flash — Speed up long-sequence transformer training and inference"
 sidebar_label: "Optimizing Attention Flash"
-description: "Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction"
+description: "Speed up long-sequence transformer training and inference"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Optimizing Attention Flash
 
-Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. Use when training/running transformers with long sequences (>512 tokens), encountering GPU memory issues with attention, or need faster inference. Supports PyTorch native SDPA, flash-attn library, H100 FP8, and sliding window attention.
+Speed up long-sequence transformer training and inference.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md b/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md
index 7010a7f3c8d..9be8a50410a 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md
@@ -1,14 +1,14 @@
 ---
-title: "Guidance"
+title: "Guidance — Constrain LLM output with grammars; guarantee valid JSON"
 sidebar_label: "Guidance"
-description: "Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidanc..."
+description: "Constrain LLM output with grammars; guarantee valid JSON"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Guidance
 
-Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidance - Microsoft Research's constrained generation framework
+Constrain LLM output with grammars; guarantee valid JSON.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md b/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md
index 5b83df6b708..723cf707a7f 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md
@@ -1,14 +1,14 @@
 ---
-title: "Huggingface Tokenizers — Fast tokenizers optimized for research and production"
+title: "Huggingface Tokenizers — Fast BPE/WordPiece tokenization and custom vocab training"
 sidebar_label: "Huggingface Tokenizers"
-description: "Fast tokenizers optimized for research and production"
+description: "Fast BPE/WordPiece tokenization and custom vocab training"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Huggingface Tokenizers
 
-Fast tokenizers optimized for research and production. Rust-based implementation tokenizes 1GB in &lt;20 seconds. Supports BPE, WordPiece, and Unigram algorithms. Train custom vocabularies, track alignments, handle padding/truncation. Integrates seamlessly with transformers. Use when you need high-performance tokenization or custom tokenizer training.
+Fast BPE/WordPiece tokenization and custom vocab training.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-instructor.md b/website/docs/user-guide/skills/optional/mlops/mlops-instructor.md
index 9282c5e8ab5..323b03847d9 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-instructor.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-instructor.md
@@ -1,14 +1,14 @@
 ---
-title: "Instructor"
+title: "Instructor — Structured LLM outputs validated with Pydantic"
 sidebar_label: "Instructor"
-description: "Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream ..."
+description: "Structured LLM outputs validated with Pydantic"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Instructor
 
-Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream partial results with Instructor - battle-tested structured output library
+Structured LLM outputs validated with Pydantic.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-lambda-labs.md b/website/docs/user-guide/skills/optional/mlops/mlops-lambda-labs.md
index b43c9721040..500b8ae25d0 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-lambda-labs.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-lambda-labs.md
@@ -1,14 +1,14 @@
 ---
-title: "Lambda Labs Gpu Cloud — Reserved and on-demand GPU cloud instances for ML training and inference"
+title: "Lambda Labs Gpu Cloud — On-demand GPU cloud instances for ML training"
 sidebar_label: "Lambda Labs Gpu Cloud"
-description: "Reserved and on-demand GPU cloud instances for ML training and inference"
+description: "On-demand GPU cloud instances for ML training"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Lambda Labs Gpu Cloud
 
-Reserved and on-demand GPU cloud instances for ML training and inference. Use when you need dedicated GPU instances with simple SSH access, persistent filesystems, or high-performance multi-node clusters for large-scale training.
+On-demand GPU cloud instances for ML training.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-llava.md b/website/docs/user-guide/skills/optional/mlops/mlops-llava.md
index f8dffae4eba..bd50b50ab43 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-llava.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-llava.md
@@ -1,14 +1,14 @@
 ---
-title: "Llava — Large Language and Vision Assistant"
+title: "Llava — Vision-language chat: VQA, captioning, image dialogue"
 sidebar_label: "Llava"
-description: "Large Language and Vision Assistant"
+description: "Vision-language chat: VQA, captioning, image dialogue"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Llava
 
-Large Language and Vision Assistant. Enables visual instruction tuning and image-based conversations. Combines CLIP vision encoder with Vicuna/LLaMA language models. Supports multi-turn image chat, visual question answering, and instruction following. Use for vision-language chatbots or image understanding tasks. Best for conversational image analysis.
+Vision-language chat: VQA, captioning, image dialogue.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-modal.md b/website/docs/user-guide/skills/optional/mlops/mlops-modal.md
index 60466a2b916..9e9d1613fea 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-modal.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-modal.md
@@ -1,14 +1,14 @@
 ---
-title: "Modal Serverless Gpu — Serverless GPU cloud platform for running ML workloads"
+title: "Modal Serverless Gpu — Serverless GPU cloud for ML jobs and model APIs"
 sidebar_label: "Modal Serverless Gpu"
-description: "Serverless GPU cloud platform for running ML workloads"
+description: "Serverless GPU cloud for ML jobs and model APIs"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Modal Serverless Gpu
 
-Serverless GPU cloud platform for running ML workloads. Use when you need on-demand GPU access without infrastructure management, deploying ML models as APIs, or running batch jobs with automatic scaling.
+Serverless GPU cloud for ML jobs and model APIs.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md b/website/docs/user-guide/skills/optional/mlops/mlops-models-segment-anything-model.md
similarity index 95%
rename from website/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md
rename to website/docs/user-guide/skills/optional/mlops/mlops-models-segment-anything-model.md
index 4353fcc6519..474b989f5f9 100644
--- a/website/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-models-segment-anything-model.md
@@ -14,8 +14,8 @@ SAM: zero-shot image segmentation via points, boxes, masks.
 
 | | |
 |---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/mlops/models/segment-anything` |
+| Source | Optional — install with `hermes skills install official/mlops/segment-anything-model` |
+| Path | `optional-skills/mlops/models/segment-anything-model` |
 | Version | `1.0.0` |
 | Author | Orchestra Research |
 | License | MIT |
@@ -92,7 +92,7 @@ import numpy as np
 from segment_anything import sam_model_registry, SamPredictor
 
 # Load model
-sam = sam_model_registry["vit_h"](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/segment-anything/checkpoint="sam_vit_h_4b8939.pth")
+sam = sam_model_registry["vit_h"](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/models/segment-anything-model/checkpoint="sam_vit_h_4b8939.pth")
 sam.to(device="cuda")
 
 # Create predictor
@@ -478,7 +478,7 @@ decoded_mask = mask_utils.decode(rle)
 
 ```python
 # Use smaller model for limited VRAM
-sam = sam_model_registry["vit_b"](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/segment-anything/checkpoint="sam_vit_b_01ec64.pth")
+sam = sam_model_registry["vit_b"](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/models/segment-anything-model/checkpoint="sam_vit_b_01ec64.pth")
 
 # Process images in batches
 # Clear CUDA cache between large batches
@@ -513,8 +513,8 @@ mask_generator = SamAutomaticMaskGenerator(
 
 ## References
 
-- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/segment-anything/references/advanced-usage.md)** - Batching, fine-tuning, integration
-- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/segment-anything/references/troubleshooting.md)** - Common issues and solutions
+- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/models/segment-anything-model/references/advanced-usage.md)** - Batching, fine-tuning, integration
+- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/models/segment-anything-model/references/troubleshooting.md)** - Common issues and solutions
 
 ## Resources
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-nemo-curator.md b/website/docs/user-guide/skills/optional/mlops/mlops-nemo-curator.md
index fdafab41f4c..6dcf838ddd3 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-nemo-curator.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-nemo-curator.md
@@ -1,14 +1,14 @@
 ---
-title: "Nemo Curator — GPU-accelerated data curation for LLM training"
+title: "Nemo Curator — Curate LLM training data: dedupe, filter, PII redaction"
 sidebar_label: "Nemo Curator"
-description: "GPU-accelerated data curation for LLM training"
+description: "Curate LLM training data: dedupe, filter, PII redaction"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Nemo Curator
 
-GPU-accelerated data curation for LLM training. Supports text/image/video/audio. Features fuzzy deduplication (16× faster), quality filtering (30+ heuristics), semantic deduplication, PII redaction, NSFW detection. Scales across GPUs with RAPIDS. Use for preparing high-quality training datasets, cleaning web data, or deduplicating large corpora.
+Curate LLM training data: dedupe, filter, PII redaction.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md b/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md
index 917bab47b8a..d849d45c036 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md
@@ -22,7 +22,7 @@ OBLITERATUS: abliterate LLM refusals (diff-in-means).
 | Dependencies | `obliteratus`, `torch`, `transformers`, `bitsandbytes`, `accelerate`, `safetensors` |
 | Platforms | linux, macos |
 | Tags | `Abliteration`, `Uncensoring`, `Refusal-Removal`, `LLM`, `Weight-Projection`, `SVD`, `Mechanistic-Interpretability`, `HuggingFace`, `Model-Surgery` |
-| Related skills | `vllm`, `gguf`, [`huggingface-tokenizers`](/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) |
+| Related skills | [`serving-llms-vllm`](/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm), [`llama-cpp`](/docs/user-guide/skills/bundled/mlops/mlops-inference-llama-cpp), [`huggingface-tokenizers`](/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-peft.md b/website/docs/user-guide/skills/optional/mlops/mlops-peft.md
index 4320a0a9be1..b29141779e4 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-peft.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-peft.md
@@ -1,14 +1,14 @@
 ---
-title: "Peft Fine Tuning — Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods"
+title: "Peft Fine Tuning — Fine-tune large LLMs with LoRA on limited GPU memory"
 sidebar_label: "Peft Fine Tuning"
-description: "Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods"
+description: "Fine-tune large LLMs with LoRA on limited GPU memory"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Peft Fine Tuning
 
-Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods. Use when fine-tuning large models (7B-70B) with limited GPU memory, when you need to train &lt;1% of parameters with minimal accuracy loss, or for multi-adapter serving. HuggingFace's official library integrated with transformers ecosystem.
+Fine-tune large LLMs with LoRA on limited GPU memory.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-pytorch-fsdp.md b/website/docs/user-guide/skills/optional/mlops/mlops-pytorch-fsdp.md
index 1069244ea87..174d7497d4a 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-pytorch-fsdp.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-pytorch-fsdp.md
@@ -1,14 +1,14 @@
 ---
-title: "Pytorch Fsdp"
+title: "Pytorch Fsdp — Fully sharded data-parallel training for large models"
 sidebar_label: "Pytorch Fsdp"
-description: "Expert guidance for Fully Sharded Data Parallel training with PyTorch FSDP - parameter sharding, mixed precision, CPU offloading, FSDP2"
+description: "Fully sharded data-parallel training for large models"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Pytorch Fsdp
 
-Expert guidance for Fully Sharded Data Parallel training with PyTorch FSDP - parameter sharding, mixed precision, CPU offloading, FSDP2
+Fully sharded data-parallel training for large models.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-pytorch-lightning.md b/website/docs/user-guide/skills/optional/mlops/mlops-pytorch-lightning.md
index 57364a278bc..dac2b7e6132 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-pytorch-lightning.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-pytorch-lightning.md
@@ -1,14 +1,14 @@
 ---
-title: "Pytorch Lightning"
+title: "Pytorch Lightning — Clean training loops with built-in distributed support"
 sidebar_label: "Pytorch Lightning"
-description: "High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate"
+description: "Clean training loops with built-in distributed support"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Pytorch Lightning
 
-High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate. Scales from laptop to supercomputer with same code. Use when you want clean training loops with built-in best practices.
+Clean training loops with built-in distributed support.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-qdrant.md b/website/docs/user-guide/skills/optional/mlops/mlops-qdrant.md
index 1503c9f3fe0..bfdb20c979d 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-qdrant.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-qdrant.md
@@ -1,14 +1,14 @@
 ---
-title: "Qdrant Vector Search — High-performance vector similarity search engine for RAG and semantic search"
+title: "Qdrant Vector Search — Vector search engine for production RAG systems"
 sidebar_label: "Qdrant Vector Search"
-description: "High-performance vector similarity search engine for RAG and semantic search"
+description: "Vector search engine for production RAG systems"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Qdrant Vector Search
 
-High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered performance.
+Vector search engine for production RAG systems.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-saelens.md b/website/docs/user-guide/skills/optional/mlops/mlops-saelens.md
index a015a7a006b..89ae694b5a3 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-saelens.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-saelens.md
@@ -1,14 +1,14 @@
 ---
-title: "Sparse Autoencoder Training"
+title: "Sparse Autoencoder Training — Train sparse autoencoders to interpret model features"
 sidebar_label: "Sparse Autoencoder Training"
-description: "Provides guidance for training and analyzing Sparse Autoencoders (SAEs) using SAELens to decompose neural network activations into interpretable features"
+description: "Train sparse autoencoders to interpret model features"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Sparse Autoencoder Training
 
-Provides guidance for training and analyzing Sparse Autoencoders (SAEs) using SAELens to decompose neural network activations into interpretable features. Use when discovering interpretable features, analyzing superposition, or studying monosemantic representations in language models.
+Train sparse autoencoders to interpret model features.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-simpo.md b/website/docs/user-guide/skills/optional/mlops/mlops-simpo.md
index 8184970fde9..b85280b21bc 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-simpo.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-simpo.md
@@ -1,14 +1,14 @@
 ---
-title: "Simpo Training — Simple Preference Optimization for LLM alignment"
+title: "Simpo Training — Reference-free preference alignment, simpler than DPO"
 sidebar_label: "Simpo Training"
-description: "Simple Preference Optimization for LLM alignment"
+description: "Reference-free preference alignment, simpler than DPO"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Simpo Training
 
-Simple Preference Optimization for LLM alignment. Reference-free alternative to DPO with better performance (+6.4 points on AlpacaEval 2.0). No reference model needed, more efficient than DPO. Use for preference alignment when want simpler, faster training than DPO/PPO.
+Reference-free preference alignment, simpler than DPO.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-slime.md b/website/docs/user-guide/skills/optional/mlops/mlops-slime.md
index b6f25d37cd5..e57e10ff130 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-slime.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-slime.md
@@ -1,14 +1,14 @@
 ---
-title: "Slime Rl Training — Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework"
+title: "Slime Rl Training — RL post-training for LLMs with Megatron and SGLang"
 sidebar_label: "Slime Rl Training"
-description: "Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework"
+description: "RL post-training for LLMs with Megatron and SGLang"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Slime Rl Training
 
-Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework. Use when training GLM models, implementing custom data generation workflows, or needing tight Megatron-LM integration for RL scaling.
+RL post-training for LLMs with Megatron and SGLang.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md b/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md
index e40967e24c6..8b00f8ba973 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md
@@ -1,14 +1,14 @@
 ---
-title: "Stable Diffusion Image Generation"
+title: "Stable Diffusion Image Generation — Text-to-image generation, inpainting, and img2img"
 sidebar_label: "Stable Diffusion Image Generation"
-description: "State-of-the-art text-to-image generation with Stable Diffusion models via HuggingFace Diffusers"
+description: "Text-to-image generation, inpainting, and img2img"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Stable Diffusion Image Generation
 
-State-of-the-art text-to-image generation with Stable Diffusion models via HuggingFace Diffusers. Use when generating images from text prompts, performing image-to-image translation, inpainting, or building custom diffusion pipelines.
+Text-to-image generation, inpainting, and img2img.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-tensorrt-llm.md b/website/docs/user-guide/skills/optional/mlops/mlops-tensorrt-llm.md
index fbaff703715..e056826842f 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-tensorrt-llm.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-tensorrt-llm.md
@@ -1,14 +1,14 @@
 ---
-title: "Tensorrt Llm — Optimizes LLM inference with NVIDIA TensorRT for maximum throughput and lowest latency"
+title: "Tensorrt Llm — High-throughput LLM inference on NVIDIA GPUs"
 sidebar_label: "Tensorrt Llm"
-description: "Optimizes LLM inference with NVIDIA TensorRT for maximum throughput and lowest latency"
+description: "High-throughput LLM inference on NVIDIA GPUs"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Tensorrt Llm
 
-Optimizes LLM inference with NVIDIA TensorRT for maximum throughput and lowest latency. Use for production deployment on NVIDIA GPUs (A100/H100), when you need 10-100x faster inference than PyTorch, or for serving models with quantization (FP8/INT4), in-flight batching, and multi-GPU scaling.
+High-throughput LLM inference on NVIDIA GPUs.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-torchtitan.md b/website/docs/user-guide/skills/optional/mlops/mlops-torchtitan.md
index a0a4625dc76..2416d3677fe 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-torchtitan.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-torchtitan.md
@@ -1,14 +1,14 @@
 ---
-title: "Distributed Llm Pretraining Torchtitan"
+title: "Distributed Llm Pretraining Torchtitan — Pretrain LLMs at scale with PyTorch 4D parallelism"
 sidebar_label: "Distributed Llm Pretraining Torchtitan"
-description: "Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP)"
+description: "Pretrain LLMs at scale with PyTorch 4D parallelism"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Distributed Llm Pretraining Torchtitan
 
-Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP). Use when pretraining Llama 3.1, DeepSeek V3, or custom models at scale from 8 to 512+ GPUs with Float8, torch.compile, and distributed checkpointing.
+Pretrain LLMs at scale with PyTorch 4D parallelism.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-whisper.md b/website/docs/user-guide/skills/optional/mlops/mlops-whisper.md
index 3c4a4d151d3..458316b67c1 100644
--- a/website/docs/user-guide/skills/optional/mlops/mlops-whisper.md
+++ b/website/docs/user-guide/skills/optional/mlops/mlops-whisper.md
@@ -1,14 +1,14 @@
 ---
-title: "Whisper — OpenAI's general-purpose speech recognition model"
+title: "Whisper — Transcribe and translate speech in 99 languages"
 sidebar_label: "Whisper"
-description: "OpenAI's general-purpose speech recognition model"
+description: "Transcribe and translate speech in 99 languages"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Whisper
 
-OpenAI's general-purpose speech recognition model. Supports 99 languages, transcription, translation to English, and language identification. Six model sizes from tiny (39M params) to large (1550M params). Use for speech-to-text, podcast transcription, or multilingual audio processing. Best for robust, multilingual ASR.
+Transcribe and translate speech in 99 languages.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-canvas.md b/website/docs/user-guide/skills/optional/productivity/productivity-canvas.md
index 11bbf7e2006..90f44f1a618 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-canvas.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-canvas.md
@@ -1,14 +1,14 @@
 ---
-title: "Canvas — Canvas LMS integration — fetch enrolled courses and assignments using API token authentication"
+title: "Canvas — Fetch Canvas LMS courses and assignments via API token"
 sidebar_label: "Canvas"
-description: "Canvas LMS integration — fetch enrolled courses and assignments using API token authentication"
+description: "Fetch Canvas LMS courses and assignments via API token"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Canvas
 
-Canvas LMS integration — fetch enrolled courses and assignments using API token authentication.
+Fetch Canvas LMS courses and assignments via API token.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-here-now.md b/website/docs/user-guide/skills/optional/productivity/productivity-here-now.md
index 3a11925965b..d156815aff4 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-here-now.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-here-now.md
@@ -1,14 +1,14 @@
 ---
-title: "Here.Now — Publish static sites to {slug}"
+title: "Here.Now — Publish sites to {slug}"
 sidebar_label: "Here.Now"
-description: "Publish static sites to {slug}"
+description: "Publish sites to {slug}"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Here.Now
 
-Publish static sites to &#123;slug&#125;.here.now and store private files in cloud Drives for agent-to-agent handoff.
+Publish sites to &#123;slug&#125;.here.now and store files in Drives.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md b/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md
index 97d4116d82d..a552bc5bfdb 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md
@@ -1,14 +1,14 @@
 ---
-title: "Shopify — Shopify Admin & Storefront GraphQL APIs via curl"
+title: "Shopify — Query Shopify Admin/Storefront GraphQL APIs via curl"
 sidebar_label: "Shopify"
-description: "Shopify Admin & Storefront GraphQL APIs via curl"
+description: "Query Shopify Admin/Storefront GraphQL APIs via curl"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Shopify
 
-Shopify Admin & Storefront GraphQL APIs via curl. Products, orders, customers, inventory, metafields.
+Query Shopify Admin/Storefront GraphQL APIs via curl.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md b/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md
index 777ee265d11..6747083b07d 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md
@@ -1,14 +1,14 @@
 ---
-title: "Siyuan"
+title: "Siyuan — Query and edit a SiYuan knowledge base via its API"
 sidebar_label: "Siyuan"
-description: "SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl"
+description: "Query and edit a SiYuan knowledge base via its API"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Siyuan
 
-SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.
+Query and edit a SiYuan knowledge base via its API.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-telephony.md b/website/docs/user-guide/skills/optional/productivity/productivity-telephony.md
index 03d08bdc399..d3f6b81adaf 100644
--- a/website/docs/user-guide/skills/optional/productivity/productivity-telephony.md
+++ b/website/docs/user-guide/skills/optional/productivity/productivity-telephony.md
@@ -1,14 +1,14 @@
 ---
-title: "Telephony — Give Hermes phone capabilities without core tool changes"
+title: "Telephony — Provision Twilio numbers, SMS/MMS, and AI outbound calls"
 sidebar_label: "Telephony"
-description: "Give Hermes phone capabilities without core tool changes"
+description: "Provision Twilio numbers, SMS/MMS, and AI outbound calls"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Telephony
 
-Give Hermes phone capabilities without core tool changes. Provision and persist a Twilio number, send and receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi.
+Provision Twilio numbers, SMS/MMS, and AI outbound calls.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/research/research-bioinformatics.md b/website/docs/user-guide/skills/optional/research/research-bioinformatics.md
index c9845d6f1ca..dc8bbef0220 100644
--- a/website/docs/user-guide/skills/optional/research/research-bioinformatics.md
+++ b/website/docs/user-guide/skills/optional/research/research-bioinformatics.md
@@ -1,14 +1,14 @@
 ---
-title: "Bioinformatics — Gateway to 400+ bioinformatics skills from bioSkills and ClawBio"
+title: "Bioinformatics — Gateway to 400+ genomics and computational biology skills"
 sidebar_label: "Bioinformatics"
-description: "Gateway to 400+ bioinformatics skills from bioSkills and ClawBio"
+description: "Gateway to 400+ genomics and computational biology skills"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Bioinformatics
 
-Gateway to 400+ bioinformatics skills from bioSkills and ClawBio. Covers genomics, transcriptomics, single-cell, variant calling, pharmacogenomics, metagenomics, structural biology, and more. Fetches domain-specific reference material on demand.
+Gateway to 400+ genomics and computational biology skills.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/research/research-darwinian-evolver.md b/website/docs/user-guide/skills/optional/research/research-darwinian-evolver.md
index 121b2dde160..6975bf22190 100644
--- a/website/docs/user-guide/skills/optional/research/research-darwinian-evolver.md
+++ b/website/docs/user-guide/skills/optional/research/research-darwinian-evolver.md
@@ -21,7 +21,7 @@ Evolve prompts/regex/SQL/code with Imbue's evolution loop.
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `evolution`, `optimization`, `prompt-engineering`, `research` |
-| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`jupyter-live-kernel`](/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel) |
+| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`jupyter-notebook`](/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-domain-intel.md b/website/docs/user-guide/skills/optional/research/research-domain-intel.md
index e107b6e7e4a..5314b05ef51 100644
--- a/website/docs/user-guide/skills/optional/research/research-domain-intel.md
+++ b/website/docs/user-guide/skills/optional/research/research-domain-intel.md
@@ -1,14 +1,14 @@
 ---
-title: "Domain Intel — Passive domain reconnaissance using Python stdlib"
+title: "Domain Intel — Passive recon of subdomains, SSL certs, WHOIS, and DNS"
 sidebar_label: "Domain Intel"
-description: "Passive domain reconnaissance using Python stdlib"
+description: "Passive recon of subdomains, SSL certs, WHOIS, and DNS"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Domain Intel
 
-Passive domain reconnaissance using Python stdlib. Subdomain discovery, SSL certificate inspection, WHOIS lookups, DNS records, domain availability checks, and bulk multi-domain analysis. No API keys required.
+Passive recon of subdomains, SSL certs, WHOIS, and DNS.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/research/research-duckduckgo-search.md b/website/docs/user-guide/skills/optional/research/research-duckduckgo-search.md
index bd08395e24f..466b8cc9aa5 100644
--- a/website/docs/user-guide/skills/optional/research/research-duckduckgo-search.md
+++ b/website/docs/user-guide/skills/optional/research/research-duckduckgo-search.md
@@ -1,14 +1,14 @@
 ---
-title: "Duckduckgo Search — Free web search via DuckDuckGo — text, news, images, videos"
+title: "Duckduckgo Search — Free keyless web, news, and image search via ddgs"
 sidebar_label: "Duckduckgo Search"
-description: "Free web search via DuckDuckGo — text, news, images, videos"
+description: "Free keyless web, news, and image search via ddgs"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Duckduckgo Search
 
-Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Prefer the `ddgs` CLI when installed; use the Python DDGS library only after verifying that `ddgs` is available in the current runtime.
+Free keyless web, news, and image search via ddgs.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md b/website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md
index a5f062dc373..c5d3feed896 100644
--- a/website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md
+++ b/website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md
@@ -1,14 +1,14 @@
 ---
-title: "Gitnexus Explorer"
+title: "Gitnexus Explorer — Serve an interactive codebase knowledge graph web UI"
 sidebar_label: "Gitnexus Explorer"
-description: "Index a codebase with GitNexus and serve an interactive knowledge graph via web UI + Cloudflare tunnel"
+description: "Serve an interactive codebase knowledge graph web UI"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Gitnexus Explorer
 
-Index a codebase with GitNexus and serve an interactive knowledge graph via web UI + Cloudflare tunnel.
+Serve an interactive codebase knowledge graph web UI.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Index a codebase with GitNexus and serve an interactive knowledge graph via web
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `gitnexus`, `code-intelligence`, `knowledge-graph`, `visualization` |
-| Related skills | `native-mcp`, [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection) |
+| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-osint-investigation.md b/website/docs/user-guide/skills/optional/research/research-osint-investigation.md
index 7428c3022b2..5fc03658381 100644
--- a/website/docs/user-guide/skills/optional/research/research-osint-investigation.md
+++ b/website/docs/user-guide/skills/optional/research/research-osint-investigation.md
@@ -1,14 +1,14 @@
 ---
-title: "Osint Investigation"
+title: "Osint Investigation — Follow the money via public records and sanctions data"
 sidebar_label: "Osint Investigation"
-description: "Public-records OSINT investigation framework — SEC EDGAR filings, USAspending contracts, Senate lobbying, OFAC sanctions, ICIJ offshore leaks, NYC property r..."
+description: "Follow the money via public records and sanctions data"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Osint Investigation
 
-Public-records OSINT investigation framework — SEC EDGAR filings, USAspending contracts, Senate lobbying, OFAC sanctions, ICIJ offshore leaks, NYC property records (ACRIS), OpenCorporates registries, CourtListener court records, Wayback Machine archives, Wikipedia + Wikidata, GDELT news monitoring. Entity resolution across sources, cross-link analysis, timing correlation, evidence chains. Python stdlib only.
+Follow the money via public records and sanctions data.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/research/research-parallel-cli.md b/website/docs/user-guide/skills/optional/research/research-parallel-cli.md
index 6532ae33c89..07e55f9b803 100644
--- a/website/docs/user-guide/skills/optional/research/research-parallel-cli.md
+++ b/website/docs/user-guide/skills/optional/research/research-parallel-cli.md
@@ -1,14 +1,14 @@
 ---
-title: "Parallel Cli"
+title: "Parallel Cli — Agent-native web search, deep research, and enrichment"
 sidebar_label: "Parallel Cli"
-description: "Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring"
+description: "Agent-native web search, deep research, and enrichment"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Parallel Cli
 
-Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring. Prefer JSON output and non-interactive flows.
+Agent-native web search, deep research, and enrichment.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/research/research-qmd.md b/website/docs/user-guide/skills/optional/research/research-qmd.md
index 8d145080b45..503455865ca 100644
--- a/website/docs/user-guide/skills/optional/research/research-qmd.md
+++ b/website/docs/user-guide/skills/optional/research/research-qmd.md
@@ -1,14 +1,14 @@
 ---
-title: "Qmd"
+title: "Qmd — Hybrid local search over notes, docs, and transcripts"
 sidebar_label: "Qmd"
-description: "Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking"
+description: "Hybrid local search over notes, docs, and transcripts"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Qmd
 
-Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration.
+Hybrid local search over notes, docs, and transcripts.
 
 ## Skill metadata
 
@@ -21,7 +21,7 @@ Search personal knowledge bases, notes, docs, and meeting transcripts locally us
 | License | MIT |
 | Platforms | macos, linux |
 | Tags | `Search`, `Knowledge-Base`, `RAG`, `Notes`, `MCP`, `Local-AI` |
-| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), `native-mcp`, [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
+| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
 
 ## Reference: full SKILL.md
 
diff --git a/website/docs/user-guide/skills/optional/research/research-scrapling.md b/website/docs/user-guide/skills/optional/research/research-scrapling.md
index dd1ba8865db..7d916178d96 100644
--- a/website/docs/user-guide/skills/optional/research/research-scrapling.md
+++ b/website/docs/user-guide/skills/optional/research/research-scrapling.md
@@ -1,14 +1,14 @@
 ---
-title: "Scrapling"
+title: "Scrapling — Scrape sites with stealth browsing and Cloudflare bypass"
 sidebar_label: "Scrapling"
-description: "Web scraping with Scrapling - HTTP fetching, stealth browser automation, Cloudflare bypass, and spider crawling via CLI and Python"
+description: "Scrape sites with stealth browsing and Cloudflare bypass"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Scrapling
 
-Web scraping with Scrapling - HTTP fetching, stealth browser automation, Cloudflare bypass, and spider crawling via CLI and Python.
+Scrape sites with stealth browsing and Cloudflare bypass.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/research/research-searxng-search.md b/website/docs/user-guide/skills/optional/research/research-searxng-search.md
index 90abfc91198..4a9211759c6 100644
--- a/website/docs/user-guide/skills/optional/research/research-searxng-search.md
+++ b/website/docs/user-guide/skills/optional/research/research-searxng-search.md
@@ -1,14 +1,14 @@
 ---
-title: "Searxng Search — Free meta-search via SearXNG — aggregates results from 70+ search engines"
+title: "Searxng Search — Free keyless meta-search aggregating 70+ engines"
 sidebar_label: "Searxng Search"
-description: "Free meta-search via SearXNG — aggregates results from 70+ search engines"
+description: "Free keyless meta-search aggregating 70+ engines"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Searxng Search
 
-Free meta-search via SearXNG — aggregates results from 70+ search engines. Self-hosted or use a public instance. No API key needed. Falls back automatically when the web search toolset is unavailable.
+Free keyless meta-search aggregating 70+ engines.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/security/security-1password.md b/website/docs/user-guide/skills/optional/security/security-1password.md
index c2c3fccb6e9..4b9697bacf6 100644
--- a/website/docs/user-guide/skills/optional/security/security-1password.md
+++ b/website/docs/user-guide/skills/optional/security/security-1password.md
@@ -1,14 +1,14 @@
 ---
-title: "1Password — Set up and use 1Password CLI (op)"
+title: "1Password — Set up op CLI, sign in, and read or inject secrets"
 sidebar_label: "1Password"
-description: "Set up and use 1Password CLI (op)"
+description: "Set up op CLI, sign in, and read or inject secrets"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # 1Password
 
-Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in, and reading/injecting secrets for commands.
+Set up op CLI, sign in, and read or inject secrets.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/security/security-sherlock.md b/website/docs/user-guide/skills/optional/security/security-sherlock.md
index 22feb13c420..ad50f1a6eb7 100644
--- a/website/docs/user-guide/skills/optional/security/security-sherlock.md
+++ b/website/docs/user-guide/skills/optional/security/security-sherlock.md
@@ -1,14 +1,14 @@
 ---
-title: "Sherlock — OSINT username search across 400+ social networks"
+title: "Sherlock — Find accounts for a username across 400+ platforms"
 sidebar_label: "Sherlock"
-description: "OSINT username search across 400+ social networks"
+description: "Find accounts for a username across 400+ platforms"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Sherlock
 
-OSINT username search across 400+ social networks. Hunt down social media accounts by username.
+Find accounts for a username across 400+ platforms.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/optional/web-development/web-development-page-agent.md b/website/docs/user-guide/skills/optional/web-development/web-development-page-agent.md
index 2b0cef786e0..f8332ab3dd5 100644
--- a/website/docs/user-guide/skills/optional/web-development/web-development-page-agent.md
+++ b/website/docs/user-guide/skills/optional/web-development/web-development-page-agent.md
@@ -1,14 +1,14 @@
 ---
-title: "Page Agent"
+title: "Page Agent — Embed an in-page natural-language GUI copilot in web apps"
 sidebar_label: "Page Agent"
-description: "Embed alibaba/page-agent into your own web application — a pure-JavaScript in-page GUI agent that ships as a single <script> tag or npm package and lets end-..."
+description: "Embed an in-page natural-language GUI copilot in web apps"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Page Agent
 
-Embed alibaba/page-agent into your own web application — a pure-JavaScript in-page GUI agent that ships as a single &lt;script> tag or npm package and lets end-users of your site drive the UI with natural language ("click login, fill username as John"). No Python, no headless browser, no extension required. Use this skill when the user is a web developer who wants to add an AI copilot to their SaaS / admin panel / B2B tool, make a legacy web app accessible via natural language, or evaluate page-agent against a local (Ollama) or cloud (Qwen / OpenAI / OpenRouter) LLM. NOT for server-side browser automation — point those users to Hermes' built-in browser tool instead.
+Embed an in-page natural-language GUI copilot in web apps.
 
 ## Skill metadata
 
diff --git a/website/docs/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md b/website/docs/user-guide/skills/optional/yuanbao/yuanbao-yuanbao.md
similarity index 97%
rename from website/docs/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md
rename to website/docs/user-guide/skills/optional/yuanbao/yuanbao-yuanbao.md
index aff10159e5c..3324a63ad10 100644
--- a/website/docs/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md
+++ b/website/docs/user-guide/skills/optional/yuanbao/yuanbao-yuanbao.md
@@ -14,8 +14,8 @@ Yuanbao (元宝) groups: @mention users, query info/members.
 
 | | |
 |---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/yuanbao` |
+| Source | Optional — install with `hermes skills install official/yuanbao/yuanbao` |
+| Path | `optional-skills/yuanbao` |
 | Version | `1.0.0` |
 | Platforms | linux, macos, windows |
 | Tags | `yuanbao`, `mention`, `at`, `group`, `members`, `元宝`, `派`, `艾特` |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/optional-skills-catalog.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/optional-skills-catalog.md
index 297182ece5e..e9a94e778c9 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/optional-skills-catalog.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/optional-skills-catalog.md
@@ -52,12 +52,20 @@ hermes skills uninstall <skill-name>
 
 | 技能 | 描述 |
 |-------|-------------|
+| [**audiocraft-audio-generation**](/user-guide/skills/optional/creative/creative-audiocraft-audio-generation) | AudioCraft：MusicGen 文本转音乐、AudioGen 文本转音效。 |
 | [**blender-mcp**](/user-guide/skills/optional/creative/creative-blender-mcp) | 通过 socket 连接 blender-mcp 插件，直接从 Hermes 控制 Blender。创建 3D 对象、材质、动画，并运行任意 Blender Python（bpy）代码。适用于用户希望在 Blender 中创建或修改任何内容的场景。 |
 | [**concept-diagrams**](/user-guide/skills/optional/creative/creative-concept-diagrams) | 生成扁平、极简、支持亮色/暗色模式的 SVG 图表，输出为独立 HTML 文件，采用统一的教育视觉语言，包含 9 种语义色阶、句首大写排版及自动暗色模式。最适合教育和说明类内容。 |
+| [**heartmula**](/user-guide/skills/optional/creative/creative-heartmula) | HeartMuLa：根据歌词 + 标签生成类 Suno 风格的歌曲。 |
 | [**hyperframes**](/user-guide/skills/optional/creative/creative-hyperframes) | 使用 HyperFrames 创建基于 HTML 的视频合成、动态标题卡、社交叠层、字幕访谈视频、音频响应视觉效果及着色器转场。HTML 是视频的唯一来源。适用于用户希望制作任何视频内容的场景。 |
 | [**kanban-video-orchestrator**](/user-guide/skills/optional/creative/creative-kanban-video-orchestrator) | 规划、搭建并监控由 Hermes Kanban 支撑的多 agent 视频制作流水线。适用于用户希望制作任何类型视频的场景 — 叙事影片、产品/营销视频、MV、解说视频、ASCII/终端艺术、抽象/生成式循环等。 |
 | [**meme-generation**](/user-guide/skills/optional/creative/creative-meme-generation) | 通过选取模板并使用 Pillow 叠加文字来生成真实的 meme 图片，输出实际的 .png 文件。 |
 
+## data-science
+
+| 技能 | 描述 |
+|-------|-------------|
+| [**jupyter-notebook**](/user-guide/skills/optional/data-science/data-science-jupyter-notebook) | 通过实时 Jupyter kernel（hamelnb）进行迭代式 Python 开发。 |
+
 ## devops
 
 | 技能 | 描述 |
@@ -136,6 +144,7 @@ hermes skills uninstall <skill-name>
 | [**pytorch-lightning**](/user-guide/skills/optional/mlops/mlops-pytorch-lightning) | 高层 PyTorch 框架，提供 Trainer 类、自动分布式训练（DDP/FSDP/DeepSpeed）、回调系统及极少样板代码。同一套代码可从笔记本扩展至超算。适用于希望训练循环简洁、同时保留完整 PyTorch 灵活性的场景。 |
 | [**qdrant-vector-search**](/user-guide/skills/optional/mlops/mlops-qdrant) | 高性能向量相似性搜索引擎，适用于 RAG 和语义搜索。适用于构建需要快速近邻搜索、带过滤的混合搜索或基于 Rust 高性能的可扩展向量存储的生产 RAG 系统。 |
 | [**sparse-autoencoder-training**](/user-guide/skills/optional/mlops/mlops-saelens) | 提供使用 SAELens 训练和分析稀疏自编码器（SAE）的指导，将神经网络激活分解为可解释特征。适用于发现可解释特征、分析叠加现象或研究神经网络内部结构的场景。 |
+| [**segment-anything-model**](/user-guide/skills/optional/mlops/mlops-models-segment-anything-model) | SAM：通过点、框、掩码进行零样本图像分割。 |
 | [**simpo-training**](/user-guide/skills/optional/mlops/mlops-simpo) | 用于 LLM 对齐的简单偏好优化（SimPO）。无需参考模型的 DPO 替代方案，性能更优（在 AlpacaEval 2.0 上提升 +6.4 分）。比 DPO 更高效。适用于希望简化偏好对齐流程的场景。 |
 | [**slime-rl-training**](/user-guide/skills/optional/mlops/mlops-slime) | 提供使用 slime（Megatron+SGLang 框架）进行 LLM RL 后训练的指导。适用于训练 GLM 模型、实现自定义数据生成工作流或需要紧密 Megatron-LM 集成以进行 RL 扩展的场景。 |
 | [**stable-diffusion-image-generation**](/user-guide/skills/optional/mlops/mlops-stable-diffusion) | 通过 HuggingFace Diffusers 使用 Stable Diffusion 模型进行最先进的文本到图像生成。适用于从文本 prompt 生成图像、图像到图像转换、图像修复或构建自定义扩散流水线的场景。 |
@@ -193,6 +202,12 @@ hermes skills uninstall <skill-name>
 |-------|-------------|
 | [**page-agent**](/user-guide/skills/optional/web-development/web-development-page-agent) | 将 alibaba/page-agent 嵌入您自己的 Web 应用 — 一个纯 JavaScript 页内 GUI agent，以单个 `<script>` 标签或 npm 包形式提供，让您网站的终端用户可以用自然语言驱动 UI（如"点击登录，填写用户名..."）。 |
 
+## yuanbao
+
+| 技能 | 描述 |
+|-------|-------------|
+| [**yuanbao**](/user-guide/skills/optional/yuanbao/yuanbao-yuanbao) | 元宝（Yuanbao）群组：@提及用户、查询信息/成员。 |
+
 ---
 
 ## 贡献可选技能
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md
index 305224a7cf4..d82880928e8 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md
@@ -52,24 +52,12 @@ Hermes 在执行 `hermes update` 时也会同步内置技能，但同步清单
 | [`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | 歌曲创作技巧与 Suno AI 音乐 prompt（提示词）。 | `creative/songwriting-and-ai-music` |
 | [`touchdesigner-mcp`](/user-guide/skills/bundled/creative/creative-touchdesigner-mcp) | 通过 twozero MCP 控制运行中的 TouchDesigner 实例——创建算子、设置参数、连接节点、执行 Python、构建实时视觉效果。36 个原生工具。 | `creative/touchdesigner-mcp` |
 
-## data-science
-
-| 技能 | 描述 | 路径 |
-|-------|-------------|------|
-| [`jupyter-live-kernel`](/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel) | 通过实时 Jupyter kernel（hamelnb）进行迭代式 Python 开发。 | `data-science/jupyter-live-kernel` |
-
 ## devops
 
 | 技能 | 描述 | 路径 |
 |-------|-------------|------|
 
 
-## dogfood
-
-| 技能 | 描述 | 路径 |
-|-------|-------------|------|
-| [`dogfood`](/user-guide/skills/bundled/dogfood/dogfood-dogfood) | Web 应用探索性 QA：发现 bug、收集证据、生成报告。 | `dogfood` |
-
 ## email
 
 | 技能 | 描述 | 路径 |
@@ -102,7 +90,6 @@ Hermes 在执行 `hermes update` 时也会同步内置技能，但同步清单
 | 技能 | 描述 | 路径 |
 |-------|-------------|------|
 | [`gif-search`](/user-guide/skills/bundled/media/media-gif-search) | 通过 curl + jq 从 Tenor 搜索/下载 GIF。 | `media/gif-search` |
-| [`heartmula`](/user-guide/skills/bundled/media/media-heartmula) | HeartMuLa：根据歌词 + 标签生成类 Suno 风格的歌曲。 | `media/heartmula` |
 | [`songsee`](/user-guide/skills/bundled/media/media-songsee) | 通过 CLI 生成音频频谱图/特征（mel、chroma、MFCC）。 | `media/songsee` |
 | [`youtube-content`](/user-guide/skills/bundled/media/media-youtube-content) | 将 YouTube 字幕转换为摘要、推文串、博客文章。 | `media/youtube-content` |
 
@@ -110,12 +97,10 @@ Hermes 在执行 `hermes update` 时也会同步内置技能，但同步清单
 
 | 技能 | 描述 | 路径 |
 |-------|-------------|------|
-| [`audiocraft-audio-generation`](/user-guide/skills/bundled/mlops/mlops-models-audiocraft) | AudioCraft：MusicGen 文本转音乐、AudioGen 文本转音效。 | `mlops/models/audiocraft` |
 | [`huggingface-hub`](/user-guide/skills/bundled/mlops/mlops-huggingface-hub) | HuggingFace hf CLI：搜索/下载/上传模型、数据集。 | `mlops/huggingface-hub` |
 | [`llama-cpp`](/user-guide/skills/bundled/mlops/mlops-inference-llama-cpp) | llama.cpp 本地 GGUF 推理 + HF Hub 模型发现。 | `mlops/inference/llama-cpp` |
-| [`evaluating-llms-harness`](/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness) | lm-eval-harness：对 LLM 进行基准测试（MMLU、GSM8K 等）。 | `mlops/evaluation/lm-evaluation-harness` |
-| [`segment-anything-model`](/user-guide/skills/bundled/mlops/mlops-models-segment-anything) | SAM：通过点、框、掩码进行零样本图像分割。 | `mlops/models/segment-anything` |
-| [`serving-llms-vllm`](/user-guide/skills/bundled/mlops/mlops-inference-vllm) | vLLM：高吞吐量 LLM 服务、OpenAI API 兼容、量化支持。 | `mlops/inference/vllm` |
+| [`evaluating-llms-harness`](/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness) | lm-eval-harness：对 LLM 进行基准测试（MMLU、GSM8K 等）。 | `mlops/evaluation/evaluating-llms-harness` |
+| [`serving-llms-vllm`](/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm) | vLLM：高吞吐量 LLM 服务、OpenAI API 兼容、量化支持。 | `mlops/inference/serving-llms-vllm` |
 | [`weights-and-biases`](/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases) | W&B：记录 ML 实验、超参数搜索、模型注册表、仪表盘。 | `mlops/evaluation/weights-and-biases` |
 
 ## note-taking
@@ -131,7 +116,7 @@ Hermes 在执行 `hermes update` 时也会同步内置技能，但同步清单
 | [`airtable`](/user-guide/skills/bundled/productivity/productivity-airtable) | 通过 curl 调用 Airtable REST API：记录增删改查、过滤、upsert。 | `productivity/airtable` |
 | [`google-workspace`](/user-guide/skills/bundled/productivity/productivity-google-workspace) | 通过 gws CLI 或 Python 操作 Gmail、Calendar、Drive、Docs、Sheets。 | `productivity/google-workspace` |
 | [`maps`](/user-guide/skills/bundled/productivity/productivity-maps) | 通过 OpenStreetMap/OSRM 进行地理编码、POI 查询、路线规划、时区查询。 | `productivity/maps` |
-| [`nano-pdf`](/user-guide/skills/bundled/productivity/productivity-nano-pdf) | 通过 nano-pdf CLI 编辑 PDF 文本/错别字/标题（自然语言 prompt）。 | `productivity/nano-pdf` |
+| [`nano-pdf`](/user-guide/skills/bundled/productivity/productivity-nano-pdf) | 通过自然语言指令编辑现有 PDF 中的文本。 | `productivity/nano-pdf` |
 | [`notion`](/user-guide/skills/bundled/productivity/productivity-notion) | Notion API + ntn CLI：页面、数据库、Markdown、Workers。 | `productivity/notion` |
 | [`ocr-and-documents`](/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) | 从 PDF/扫描件中提取文本（pymupdf、marker-pdf）。 | `productivity/ocr-and-documents` |
 | [`powerpoint`](/user-guide/skills/bundled/productivity/productivity-powerpoint) | 创建、读取、编辑 .pptx 演示文稿、幻灯片、备注、模板。 | `productivity/powerpoint` |
@@ -163,6 +148,7 @@ Hermes 在执行 `hermes update` 时也会同步内置技能，但同步清单
 
 | 技能 | 描述 | 路径 |
 |-------|-------------|------|
+| [`dogfood`](/user-guide/skills/bundled/software-development/software-development-dogfood) | Web 应用探索性 QA：发现 bug、收集证据、生成报告。 | `software-development/dogfood` |
 | [`hermes-agent-skill-authoring`](/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | 编写仓库内 SKILL.md：frontmatter、验证器、结构规范。 | `software-development/hermes-agent-skill-authoring` |
 | [`node-inspect-debugger`](/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) | 通过 --inspect + Chrome DevTools Protocol CLI 调试 Node.js。 | `software-development/node-inspect-debugger` |
 | [`plan`](/user-guide/skills/bundled/software-development/software-development-plan) | 计划模式：将 Markdown 计划写入 `.hermes/plans/`，不执行。 | `software-development/plan` |
@@ -170,10 +156,4 @@ Hermes 在执行 `hermes update` 时也会同步内置技能，但同步清单
 | [`requesting-code-review`](/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | 提交前审查：安全扫描、质量门控、自动修复。 | `software-development/requesting-code-review` |
 | [`spike`](/user-guide/skills/bundled/software-development/software-development-spike) | 一次性实验，在正式构建前验证想法。 | `software-development/spike` |
 | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging) | 四阶段根因调试：先理解 bug，再修复。 | `software-development/systematic-debugging` |
-| [`test-driven-development`](/user-guide/skills/bundled/software-development/software-development-test-driven-development) | TDD：强制执行红-绿-重构流程，先写测试再写代码。 | `software-development/test-driven-development` |
-
-## yuanbao
-
-| 技能 | 描述 | 路径 |
-|-------|-------------|------|
-| [`yuanbao`](/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao) | 元宝（Yuanbao）群组：@提及用户、查询信息/成员。 | `yuanbao` |
\ No newline at end of file
+| [`test-driven-development`](/user-guide/skills/bundled/software-development/software-development-test-driven-development) | TDD：强制执行红-绿-重构流程，先写测试再写代码。 | `software-development/test-driven-development` |
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/checkpoints-and-rollback.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/checkpoints-and-rollback.md
index 472b30f930a..dec3ddb259d 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/checkpoints-and-rollback.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/checkpoints-and-rollback.md
@@ -94,12 +94,14 @@ checkpoints:
   max_file_size_mb: 10        # 跳过大于此值的单个文件
 
   # 自动维护（默认开启）：启动时扫描 ~/.hermes/checkpoints/，
-  # 删除工作目录已不存在的项目条目（孤立项）或 last_touch 超过
-  # retention_days 的条目。通过 .last_prune 标记控制，
-  # 最多每 min_interval_hours 运行一次。
+  # 删除 last_touch 超过 retention_days 的条目。通过 .last_prune
+  # 标记控制，最多每 min_interval_hours 运行一次。此扫描不会删除
+  # “孤立”条目（工作目录未找到）——启动时工作目录缺失含义模糊
+  # （项目被删除，还是外部卷/网络共享/VPN 尚未挂载），因此孤立项
+  # 清理只能通过下方的 `hermes checkpoints prune` 命令显式触发，
+  # 并会要求确认。
   auto_prune: true
   retention_days: 7
-  delete_orphans: true
   min_interval_hours: 24
 ```
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-comfyui.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-comfyui.md
index ea40d8e491f..85dc0293f3e 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-comfyui.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-comfyui.md
@@ -21,7 +21,7 @@ description: "使用 ComfyUI 生成图像、视频和音频——安装、启动
 | 许可证 | MIT |
 | 平台 | macos, linux, windows |
 | 标签 | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |
-| 相关 skill | [`stable-diffusion-image-generation`](/user-guide/skills/optional/mlops/mlops-stable-diffusion), `image_gen` |
+| 相关 skill | [`stable-diffusion-image-generation`](/user-guide/skills/optional/mlops/mlops-stable-diffusion) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md
index 1dd9429af21..5741718df8a 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md
@@ -286,4 +286,20 @@ AI 歌手不是在阅读——它们是在发音。帮助它们：
 - Style 字段中强有力的人声人设描述比任何单个 metatag
   都能产生更大的差异。
 - 不要对规则过于执着。如果一行打破了韵律但冲击力更强，
-  就保留它。感受才是关键。技艺服务于艺术，而不是反过来。
\ No newline at end of file
+  就保留它。感受才是关键。技艺服务于艺术，而不是反过来。
+---
+
+## 10. 本地 / 开源音乐生成
+
+如果想在本地用 GPU 生成音乐而不是使用 Suno，有两个可选 skill
+覆盖此场景（依赖较重，默认不安装）：
+
+- **heartmula** — 从歌词 + 标签生成带人声的完整歌曲
+  （开源 Suno 替代品，需 8-16GB 显存）：
+  `hermes skills install official/creative/heartmula`
+- **audiocraft** — Meta 的 MusicGen（文本转纯音乐）和
+  AudioGen（音效生成）：
+  `hermes skills install official/creative/audiocraft-audio-generation`
+
+本 skill 中的歌词写作与提示词技巧同样适用于 heartmula —
+它的输入格式是带方括号结构标签的歌词，加上逗号分隔的风格标签。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md
index 0e7929f599b..ebf64974393 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md
@@ -21,7 +21,7 @@ description: "通过 twozero MCP 控制运行中的 TouchDesigner 实例——
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `TouchDesigner`, `MCP`, `twozero`, `creative-coding`, `real-time-visuals`, `generative-art`, `audio-reactive`, `VJ`, `installation`, `GLSL` |
-| 相关 skill | [`native-mcp`](/user-guide/skills/bundled/mcp/mcp-native-mcp), [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
+| 相关 skill |, [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness.md
similarity index 95%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness.md
index e726fba51be..ff1db16ee61 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness.md
@@ -15,7 +15,7 @@ lm-eval-harness：对 LLM 进行基准测试（MMLU、GSM8K 等）。
 | | |
 |---|---|
 | 来源 | 内置（默认安装） |
-| 路径 | `skills/mlops/evaluation/lm-evaluation-harness` |
+| 路径 | `skills/mlops/evaluation/evaluating-llms-harness` |
 | 版本 | `1.0.0` |
 | 作者 | Orchestra Research |
 | 许可证 | MIT |
@@ -483,13 +483,13 @@ lm_eval --model hf \
 
 ## 进阶主题
 
-**基准描述**：参见 [references/benchmark-guide.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/lm-evaluation-harness/references/benchmark-guide.md)，了解所有 60+ 个任务的详细说明、测量内容及结果解读。
+**基准描述**：参见 [references/benchmark-guide.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md)，了解所有 60+ 个任务的详细说明、测量内容及结果解读。
 
-**自定义任务**：参见 [references/custom-tasks.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/lm-evaluation-harness/references/custom-tasks.md)，了解如何创建特定领域的评估任务。
+**自定义任务**：参见 [references/custom-tasks.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md)，了解如何创建特定领域的评估任务。
 
-**API 评估**：参见 [references/api-evaluation.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/lm-evaluation-harness/references/api-evaluation.md)，了解如何评估 OpenAI、Anthropic 及其他 API 模型。
+**API 评估**：参见 [references/api-evaluation.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md)，了解如何评估 OpenAI、Anthropic 及其他 API 模型。
 
-**多 GPU 策略**：参见 [references/distributed-eval.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/lm-evaluation-harness/references/distributed-eval.md)，了解数据并行与张量并行评估方案。
+**多 GPU 策略**：参见 [references/distributed-eval.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md)，了解数据并行与张量并行评估方案。
 
 ## 硬件要求
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-inference-vllm.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm.md
similarity index 94%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-inference-vllm.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm.md
index a16134da7a1..23200328542 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-inference-vllm.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm.md
@@ -15,7 +15,7 @@ vLLM：高吞吐量 LLM 服务、OpenAI API、量化。
 | | |
 |---|---|
 | 来源 | 内置（默认安装） |
-| 路径 | `skills/mlops/inference/vllm` |
+| 路径 | `skills/mlops/inference/serving-llms-vllm` |
 | 版本 | `1.0.0` |
 | 作者 | Orchestra Research |
 | 许可证 | MIT |
@@ -362,13 +362,13 @@ vllm serve MODEL --speculative-model DRAFT_MODEL
 
 ## 高级主题
 
-**服务器部署模式**：参见 [references/server-deployment.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/vllm/references/server-deployment.md)，了解 Docker、Kubernetes 和负载均衡配置。
+**服务器部署模式**：参见 [references/server-deployment.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/server-deployment.md)，了解 Docker、Kubernetes 和负载均衡配置。
 
-**性能优化**：参见 [references/optimization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/vllm/references/optimization.md)，了解 PagedAttention 调优、continuous batching 详情及基准测试结果。
+**性能优化**：参见 [references/optimization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/optimization.md)，了解 PagedAttention 调优、continuous batching 详情及基准测试结果。
 
-**量化指南**：参见 [references/quantization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/vllm/references/quantization.md)，了解 AWQ/GPTQ/FP8 配置、模型准备及精度对比。
+**量化指南**：参见 [references/quantization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/quantization.md)，了解 AWQ/GPTQ/FP8 配置、模型准备及精度对比。
 
-**故障排查**：参见 [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/vllm/references/troubleshooting.md)，了解详细错误信息、调试步骤及性能诊断。
+**故障排查**：参见 [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md)，了解详细错误信息、调试步骤及性能诊断。
 
 ## 硬件要求
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-nano-pdf.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
index ff84da6c395..fd3121d72ea 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-nano-pdf.md
@@ -1,14 +1,14 @@
 ---
-title: "Nano Pdf — 通过 nano-pdf CLI 编辑 PDF 文本/错别字/标题（自然语言 prompt）"
+title: "Nano Pdf — 通过自然语言指令编辑现有 PDF 中的文本"
 sidebar_label: "Nano Pdf"
-description: "通过 nano-pdf CLI 编辑 PDF 文本/错别字/标题（自然语言 prompt）"
+description: "通过自然语言指令编辑现有 PDF 中的文本"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Nano Pdf
 
-通过 nano-pdf CLI 编辑 PDF 文本/错别字/标题（自然语言 prompt（提示词））。
+通过自然语言指令（prompt）编辑现有 PDF 中的文本。
 
 ## Skill 元数据
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-research-paper-writing.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-research-paper-writing.md
index 060ee02af96..035f3c42a79 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-research-paper-writing.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-research-paper-writing.md
@@ -22,7 +22,7 @@ description: "为 NeurIPS/ICML/ICLR 撰写 ML 论文：设计→投稿"
 | 依赖项 | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` |
 | 平台 | linux, macos |
 | 标签 | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` |
-| 相关 skill | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv), `ml-paper-writing`, [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/user-guide/skills/bundled/software-development/software-development-plan) |
+| 相关 skill | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/user-guide/skills/bundled/software-development/software-development-plan) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/dogfood/dogfood-dogfood.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-dogfood.md
similarity index 99%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/dogfood/dogfood-dogfood.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-dogfood.md
index df271753190..2809c0ab109 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/dogfood/dogfood-dogfood.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-dogfood.md
@@ -15,7 +15,7 @@ description: "网页应用探索性 QA：发现缺陷、收集证据、生成报
 | | |
 |---|---|
 | 来源 | 内置（默认安装） |
-| 路径 | `skills/dogfood` |
+| 路径 | `skills/software-development/dogfood` |
 | 版本 | `1.0.0` |
 | 平台 | linux, macos, windows |
 | 标签 | `qa`, `testing`, `browser`, `web`, `dogfood` |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
index 432122d718d..3b0feb61e60 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
@@ -116,7 +116,7 @@ Named scenarios → concrete command sequences.
 skills/<category>/<skill-name>/SKILL.md
 ```
 
-仓库中现有的分类（通过 `ls skills/` 确认）：`autonomous-ai-agents`、`creative`、`data-science`、`devops`、`dogfood`、`email`、`gaming`、`github`、`leisure`、`mcp`、`media`、`mlops/*`、`note-taking`、`productivity`、`red-teaming`、`research`、`smart-home`、`social-media`、`software-development`。
+仓库中现有的分类（通过 `ls skills/` 确认）：`autonomous-ai-agents`、`creative`、`data-science`、`devops`、`email`、`gaming`、`github`、`leisure`、`mcp`、`media`、`mlops/*`、`note-taking`、`productivity`、`red-teaming`、`research`、`smart-home`、`social-media`、`software-development`。
 
 选择最接近的现有分类。不要随意创建新的顶级分类。
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
index e6d1e1e9a6c..00d897b3ac5 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
@@ -21,7 +21,7 @@ description: "调试 Node"
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |
-| 相关 skill | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`debugging-hermes-tui-commands`](/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
+| 相关 skill | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/user-guide/skills/bundled/software-development/software-development-python-debugpy) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-python-debugpy.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
index 4f0ef7a1afe..a8276c5678f 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
@@ -21,7 +21,7 @@ description: "调试 Python：pdb REPL + debugpy 远程（DAP）"
 | 许可证 | MIT |
 | 平台 | linux, macos |
 | 标签 | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` |
-| 相关 skill | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`debugging-hermes-tui-commands`](/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
+| 相关 skill | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
similarity index 97%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
index a78440d247c..225c3164593 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md
@@ -14,14 +14,15 @@ AudioCraft：MusicGen 文本转音乐，AudioGen 文本转声音。
 
 | | |
 |---|---|
-| 来源 | 内置（默认安装） |
-| 路径 | `skills/mlops/models/audiocraft` |
+| 来源 | 可选 — 通过 `hermes skills install official/creative/audiocraft-audio-generation` 安装 |
+| 路径 | `optional-skills/creative/audiocraft-audio-generation` |
 | 版本 | `1.0.0` |
 | 作者 | Orchestra Research |
 | 许可证 | MIT |
 | 依赖 | `audiocraft`, `torch>=2.0.0`, `transformers>=4.30.0` |
 | 平台 | linux, macos |
 | 标签 | `Multimodal`, `Audio Generation`, `Text-to-Music`, `Text-to-Audio`, `MusicGen` |
+| 相关 skill | [`heartmula`](/user-guide/skills/optional/creative/creative-heartmula), [`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-concept-diagrams.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-concept-diagrams.md
index 405f658a22b..bc23466e4cb 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-concept-diagrams.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-concept-diagrams.md
@@ -21,7 +21,7 @@ description: "以统一的教育视觉语言生成扁平、简约、支持明暗
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `diagrams`, `svg`, `visualization`, `education`, `physics`, `chemistry`, `engineering` |
-| 相关 skills | [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), `generative-widgets` |
+| 相关 skills | [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-heartmula.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-heartmula.md
similarity index 95%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-heartmula.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-heartmula.md
index 38d2fb03b35..486720715ab 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-heartmula.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-heartmula.md
@@ -14,12 +14,12 @@ HeartMuLa：基于歌词与标签的类 Suno 歌曲生成。
 
 | | |
 |---|---|
-| 来源 | 内置（默认安装） |
-| 路径 | `skills/media/heartmula` |
+| 来源 | 可选 — 通过 `hermes skills install official/creative/heartmula` 安装 |
+| 路径 | `optional-skills/creative/heartmula` |
 | 版本 | `1.0.0` |
 | 平台 | linux, macos, windows |
 | 标签 | `music`, `audio`, `generation`, `ai`, `heartmula`, `heartcodec`, `lyrics`, `songs` |
-| 相关 skill | `audiocraft` |
+| 相关 skill | [`audiocraft-audio-generation`](/user-guide/skills/optional/creative/creative-audiocraft-audio-generation), [`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
index a1ba562abf8..75a371cecb0 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
@@ -21,7 +21,7 @@ description: "规划、搭建并监控由 Hermes Kanban 支撑的多智能体视
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `video`, `kanban`, `multi-agent`, `orchestration`, `production-pipeline` |
-| 相关技能 | [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video)、[`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video)、[`p5js`](/user-guide/skills/bundled/creative/creative-p5js)、[`comfyui`](/user-guide/skills/bundled/creative/creative-comfyui)、[`touchdesigner-mcp`](/user-guide/skills/bundled/creative/creative-touchdesigner-mcp)、[`blender-mcp`](/user-guide/skills/optional/creative/creative-blender-mcp)、[`pixel-art`](/user-guide/skills/bundled/creative/creative-pixel-art)、[`ascii-art`](/user-guide/skills/bundled/creative/creative-ascii-art)、[`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music)、[`heartmula`](/user-guide/skills/bundled/media/media-heartmula)、[`songsee`](/user-guide/skills/bundled/media/media-songsee)、[`spotify`](/user-guide/skills/bundled/media/media-spotify)、[`youtube-content`](/user-guide/skills/bundled/media/media-youtube-content)、[`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design)、[`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw)、[`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram)、[`concept-diagrams`](/user-guide/skills/optional/creative/creative-concept-diagrams)、[`baoyu-comic`](/user-guide/skills/bundled/creative/creative-baoyu-comic)、[`baoyu-infographic`](/user-guide/skills/bundled/creative/creative-baoyu-infographic)、[`humanizer`](/user-guide/skills/bundled/creative/creative-humanizer)、[`gif-search`](/user-guide/skills/bundled/media/media-gif-search)、[`meme-generation`](/user-guide/skills/optional/creative/creative-meme-generation) |
+| 相关技能 | [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video)、[`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video)、[`p5js`](/user-guide/skills/bundled/creative/creative-p5js)、[`comfyui`](/user-guide/skills/bundled/creative/creative-comfyui)、[`touchdesigner-mcp`](/user-guide/skills/bundled/creative/creative-touchdesigner-mcp)、[`blender-mcp`](/user-guide/skills/optional/creative/creative-blender-mcp)、[`pixel-art`](/user-guide/skills/bundled/creative/creative-pixel-art)、[`ascii-art`](/user-guide/skills/bundled/creative/creative-ascii-art)、[`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music)、[`heartmula`](/user-guide/skills/optional/creative/creative-heartmula)、[`songsee`](/user-guide/skills/bundled/media/media-songsee)、[`youtube-content`](/user-guide/skills/bundled/media/media-youtube-content)、[`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design)、[`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw)、[`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram)、[`concept-diagrams`](/user-guide/skills/optional/creative/creative-concept-diagrams)、[`baoyu-comic`](/user-guide/skills/bundled/creative/creative-baoyu-comic)、[`baoyu-infographic`](/user-guide/skills/bundled/creative/creative-baoyu-infographic)、[`humanizer`](/user-guide/skills/bundled/creative/creative-humanizer)、[`gif-search`](/user-guide/skills/bundled/media/media-gif-search)、[`meme-generation`](/user-guide/skills/optional/creative/creative-meme-generation) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-meme-generation.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-meme-generation.md
index e0f80577567..0a10ebd1a68 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-meme-generation.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-meme-generation.md
@@ -21,7 +21,7 @@ description: "使用 Pillow 选取模板并叠加文字，生成真实的表情
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `creative`, `memes`, `humor`, `images` |
-| 相关 skill | [`ascii-art`](/user-guide/skills/bundled/creative/creative-ascii-art), `generative-widgets` |
+| 相关 skill | [`ascii-art`](/user-guide/skills/bundled/creative/creative-ascii-art) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md
similarity index 84%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md
index 9becd49a35f..c68075a5402 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md
@@ -1,12 +1,12 @@
 ---
-title: "Jupyter Live Kernel — 通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb）"
-sidebar_label: "Jupyter Live Kernel"
+title: "Jupyter Notebook — 通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb）"
+sidebar_label: "Jupyter Notebook"
 description: "通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb）"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
-# Jupyter Live Kernel
+# Jupyter Notebook
 
 通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb）。
 
@@ -14,8 +14,8 @@ description: "通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb
 
 | | |
 |---|---|
-| 来源 | 内置（默认安装） |
-| 路径 | `skills/data-science/jupyter-live-kernel` |
+| 来源 | 可选 — 通过 `hermes skills install official/data-science/jupyter-notebook` 安装 |
+| 路径 | `optional-skills/data-science/jupyter-notebook` |
 | 版本 | `1.0.0` |
 | 作者 | Hermes Agent |
 | 许可证 | MIT |
@@ -28,7 +28,7 @@ description: "通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb
 以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
 :::
 
-# Jupyter Live Kernel（hamelnb）
+# Jupyter Notebook（hamelnb 实时内核）
 
 通过实时 Jupyter 内核为你提供一个**有状态的 Python REPL**（交互式解释器）。变量在多次执行之间持久保留。当你需要逐步构建状态、探索 API、检查 DataFrame 或迭代复杂代码时，请使用此工具而非 `execute_code`。
 
@@ -164,6 +164,17 @@ uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compac
 
 8. **偶发的 websocket 超时** —— 某些操作（尤其是内核重启后）首次尝试可能超时。在上报问题前先重试一次。
 
+9. **如果 websocket 在此主机上持续超时**，强制使用 zmq 传输：
+   `uv run "$SCRIPT" execute --transport zmq ...`。症状：每次 execute 都返回
+   "Websocket execution may already have reached the kernel, so auto fallback was
+   skipped"。内核实际上运行正常（REST 显示 execution_state=idle 且
+   execution_count 递增）—— 只是 websocket 回复通道损坏。zmq 传输直接使用
+   jupyter_client，可绕过此问题。
+
+10. **为纯 REST 使用启动新服务器时**，添加
+    `--ServerApp.disable_check_xsrf=True` —— 否则 POST /api/sessions 会返回
+    `"'_xsrf' argument missing from POST"`，导致内核会话创建失败。
+
 ## 超时默认值
 
 脚本每次执行的默认超时为 30 秒。对于长时间运行的操作，传入 `--timeout 120`。初始设置或大量计算时，建议使用较宽松的超时值（60 秒以上）。
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/devops/devops-pinggy-tunnel.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/devops/devops-pinggy-tunnel.md
index 42bfc1c58fd..67382ef14a7 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/devops/devops-pinggy-tunnel.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/devops/devops-pinggy-tunnel.md
@@ -21,7 +21,7 @@ description: "通过 Pinggy 实现零安装 SSH localhost 隧道"
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `Pinggy`, `Tunnel`, `Networking`, `SSH`, `Webhook`, `Localhost` |
-| 相关 skill | `cloudflared-quick-tunnel`, [`webhook-subscriptions`](/user-guide/skills/bundled/devops/devops-webhook-subscriptions) |
+| 相关 skill | |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
index 480dc5287af..fda3e295ac8 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md
@@ -21,7 +21,7 @@ description: "扮演产品最难搞的技术抵触用户"
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `qa`, `ux`, `testing`, `adversarial`, `dogfood`, `personas`, `user-testing` |
-| 相关 skill | [`dogfood`](/user-guide/skills/bundled/dogfood/dogfood-dogfood) |
+| 相关 skill | [`dogfood`](/user-guide/skills/bundled/software-development/software-development-dogfood) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mcp/mcp-fastmcp.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mcp/mcp-fastmcp.md
index 8c9e2d7e089..5a3348aafbd 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mcp/mcp-fastmcp.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mcp/mcp-fastmcp.md
@@ -21,7 +21,7 @@ description: "使用 FastMCP 在 Python 中构建、测试、检查、安装和
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `MCP`, `FastMCP`, `Python`, `Tools`, `Resources`, `Prompts`, `Deployment` |
-| 相关 skill | [`native-mcp`](/user-guide/skills/bundled/mcp/mcp-native-mcp), [`mcporter`](/user-guide/skills/optional/mcp/mcp-mcporter) |
+| 相关 skill | [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`mcporter`](/user-guide/skills/optional/mcp/mcp-mcporter) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-models-segment-anything-model.md
similarity index 95%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-models-segment-anything-model.md
index 992eb665200..464d7690e12 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-models-segment-anything-model.md
@@ -14,8 +14,8 @@ SAM：通过点、框、掩码实现零样本图像分割。
 
 | | |
 |---|---|
-| 来源 | 内置（默认安装） |
-| 路径 | `skills/mlops/models/segment-anything` |
+| 来源 | 可选 — 通过 `hermes skills install official/mlops/segment-anything` 安装 |
+| 路径 | `optional-skills/mlops/models/segment-anything-model` |
 | 版本 | `1.0.0` |
 | 作者 | Orchestra Research |
 | 许可证 | MIT |
@@ -92,7 +92,7 @@ import numpy as np
 from segment_anything import sam_model_registry, SamPredictor
 
 # 加载模型
-sam = sam_model_registry["vit_h"](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/segment-anything/checkpoint="sam_vit_h_4b8939.pth")
+sam = sam_model_registry["vit_h"](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/models/segment-anything-model/checkpoint="sam_vit_h_4b8939.pth")
 sam.to(device="cuda")
 
 # 创建预测器
@@ -478,7 +478,7 @@ decoded_mask = mask_utils.decode(rle)
 
 ```python
 # 在 VRAM 有限时使用较小模型
-sam = sam_model_registry["vit_b"](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/segment-anything/checkpoint="sam_vit_b_01ec64.pth")
+sam = sam_model_registry["vit_b"](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/models/segment-anything-model/checkpoint="sam_vit_b_01ec64.pth")
 
 # 批量处理图像
 # 在大批量之间清空 CUDA 缓存
@@ -513,8 +513,8 @@ mask_generator = SamAutomaticMaskGenerator(
 
 ## 参考资料
 
-- **[高级用法](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/segment-anything/references/advanced-usage.md)** - 批处理、微调、集成
-- **[故障排查](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/segment-anything/references/troubleshooting.md)** - 常见问题与解决方案
+- **[高级用法](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/models/segment-anything-model/references/advanced-usage.md)** - 批处理、微调、集成
+- **[故障排查](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/models/segment-anything-model/references/troubleshooting.md)** - 常见问题与解决方案
 
 ## 资源
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-darwinian-evolver.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-darwinian-evolver.md
index b6f3a031889..391583514f9 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-darwinian-evolver.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-darwinian-evolver.md
@@ -21,7 +21,7 @@ description: "使用 Imbue 的进化循环来优化 prompt/正则/SQL/代码"
 | 许可证 | MIT |
 | 平台 | linux, macos |
 | 标签 | `evolution`, `optimization`, `prompt-engineering`, `research` |
-| 相关 skill | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv), [`jupyter-live-kernel`](/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel) |
+| 相关 skill | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv), [`jupyter-notebook`](/user-guide/skills/optional/data-science/data-science-jupyter-notebook) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-gitnexus-explorer.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-gitnexus-explorer.md
index a14b562fd0a..0fc44b691ec 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-gitnexus-explorer.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-gitnexus-explorer.md
@@ -21,7 +21,7 @@ description: "使用 GitNexus 为代码库建立索引，并通过 Web UI + Clou
 | 许可证 | MIT |
 | 平台 | linux, macos, windows |
 | 标签 | `gitnexus`, `code-intelligence`, `knowledge-graph`, `visualization` |
-| 相关 skill | [`native-mcp`](/user-guide/skills/bundled/mcp/mcp-native-mcp), [`codebase-inspection`](/user-guide/skills/bundled/github/github-codebase-inspection) |
+| 相关 skill | [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`codebase-inspection`](/user-guide/skills/bundled/github/github-codebase-inspection) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-qmd.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-qmd.md
index 5878d872a93..cd2686415fe 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-qmd.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-qmd.md
@@ -21,7 +21,7 @@ description: "使用 qmd 在本地搜索个人知识库、笔记、文档和会
 | 许可证 | MIT |
 | 平台 | macos, linux |
 | 标签 | `Search`, `Knowledge-Base`, `RAG`, `Notes`, `MCP`, `Local-AI` |
-| 相关 skill | [`obsidian`](/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`native-mcp`](/user-guide/skills/bundled/mcp/mcp-native-mcp), [`arxiv`](/user-guide/skills/bundled/research/research-arxiv) |
+| 相关 skill | [`obsidian`](/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`arxiv`](/user-guide/skills/bundled/research/research-arxiv) |
 
 ## 参考：完整 SKILL.md
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/yuanbao/yuanbao-yuanbao.md
similarity index 97%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/yuanbao/yuanbao-yuanbao.md
index 7d06be41d2d..0095bf6080c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/yuanbao/yuanbao-yuanbao.md
@@ -14,8 +14,8 @@ Yuanbao（元宝）群组：@提及用户、查询信息/成员。
 
 | | |
 |---|---|
-| 来源 | 内置（默认安装） |
-| 路径 | `skills/yuanbao` |
+| 来源 | 可选 — 使用 `hermes skills install official/yuanbao/yuanbao` 安装 |
+| 路径 | `optional-skills/yuanbao` |
 | 版本 | `1.0.0` |
 | 平台 | linux, macos, windows |
 | 标签 | `yuanbao`, `mention`, `at`, `group`, `members`, `元宝`, `派`, `艾特` |
diff --git a/website/scripts/generate-skill-docs.py b/website/scripts/generate-skill-docs.py
index af077d786c6..7a8644ea617 100755
--- a/website/scripts/generate-skill-docs.py
+++ b/website/scripts/generate-skill-docs.py
@@ -284,7 +284,7 @@ def derive_skill_meta(skill_path: Path, source_dir: Path, source_kind: str) -> d
     rel = skill_path.parent.relative_to(source_dir)
     parts = rel.parts
     if len(parts) == 1:
-        # Top-level skill (e.g. skills/dogfood/SKILL.md) -- rare
+        # Top-level skill (e.g. skills/<name>/SKILL.md with no category) -- rare
         category = parts[0]
         sub = None
         slug = parts[0]
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 76b948aa725..7314af5a2b3 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -40,6 +40,15 @@ const sidebars: SidebarsConfig = {
             'user-guide/secrets/onepassword',
           ],
         },
+        {
+          type: 'category',
+          label: 'Egress proxy',
+          collapsed: true,
+          items: [
+            'user-guide/egress/index',
+            'user-guide/egress/iron-proxy',
+          ],
+        },
         'user-guide/sessions',
         'user-guide/profiles',
         'user-guide/profile-distributions',
@@ -154,19 +163,11 @@ const sidebars: SidebarsConfig = {
                   items: [
                     'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code',
                     'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex',
+                    'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use',
                     'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent',
                     'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode',
                   ],
                 },
-                {
-                  type: 'category',
-                  label: 'computer-use',
-                  key: 'skills-bundled-computer-use',
-                  collapsed: true,
-                  items: [
-                    'user-guide/skills/bundled/computer-use/computer-use-computer-use',
-                  ],
-                },
                 {
                   type: 'category',
                   label: 'creative',
@@ -191,24 +192,6 @@ const sidebars: SidebarsConfig = {
                     'user-guide/skills/bundled/creative/creative-touchdesigner-mcp',
                   ],
                 },
-                {
-                  type: 'category',
-                  label: 'data-science',
-                  key: 'skills-bundled-data-science',
-                  collapsed: true,
-                  items: [
-                    'user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel',
-                  ],
-                },
-                {
-                  type: 'category',
-                  label: 'dogfood',
-                  key: 'skills-bundled-dogfood',
-                  collapsed: true,
-                  items: [
-                    'user-guide/skills/bundled/dogfood/dogfood-dogfood',
-                  ],
-                },
                 {
                   type: 'category',
                   label: 'email',
@@ -232,15 +215,6 @@ const sidebars: SidebarsConfig = {
                     'user-guide/skills/bundled/github/github-github-repo-management',
                   ],
                 },
-                {
-                  type: 'category',
-                  label: 'hermes-desktop-plugins',
-                  key: 'skills-bundled-hermes-desktop-plugins',
-                  collapsed: true,
-                  items: [
-                    'user-guide/skills/bundled/hermes-desktop-plugins/hermes-desktop-plugins-hermes-desktop-plugins',
-                  ],
-                },
                 {
                   type: 'category',
                   label: 'media',
@@ -248,7 +222,6 @@ const sidebars: SidebarsConfig = {
                   collapsed: true,
                   items: [
                     'user-guide/skills/bundled/media/media-gif-search',
-                    'user-guide/skills/bundled/media/media-heartmula',
                     'user-guide/skills/bundled/media/media-songsee',
                     'user-guide/skills/bundled/media/media-youtube-content',
                   ],
@@ -259,12 +232,10 @@ const sidebars: SidebarsConfig = {
                   key: 'skills-bundled-mlops',
                   collapsed: true,
                   items: [
-                    'user-guide/skills/bundled/mlops/mlops-models-audiocraft',
                     'user-guide/skills/bundled/mlops/mlops-huggingface-hub',
                     'user-guide/skills/bundled/mlops/mlops-inference-llama-cpp',
-                    'user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness',
-                    'user-guide/skills/bundled/mlops/mlops-models-segment-anything',
-                    'user-guide/skills/bundled/mlops/mlops-inference-vllm',
+                    'user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness',
+                    'user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm',
                     'user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases',
                   ],
                 },
@@ -291,7 +262,6 @@ const sidebars: SidebarsConfig = {
                     'user-guide/skills/bundled/productivity/productivity-notion',
                     'user-guide/skills/bundled/productivity/productivity-ocr-and-documents',
                     'user-guide/skills/bundled/productivity/productivity-pdf',
-                    'user-guide/skills/bundled/productivity/productivity-petdex',
                     'user-guide/skills/bundled/productivity/productivity-powerpoint',
                     'user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline',
                     'user-guide/skills/bundled/productivity/productivity-xlsx',
@@ -334,6 +304,7 @@ const sidebars: SidebarsConfig = {
                   key: 'skills-bundled-software-development',
                   collapsed: true,
                   items: [
+                    'user-guide/skills/bundled/software-development/software-development-dogfood',
                     'user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring',
                     'user-guide/skills/bundled/software-development/software-development-node-inspect-debugger',
                     'user-guide/skills/bundled/software-development/software-development-plan',
@@ -345,15 +316,6 @@ const sidebars: SidebarsConfig = {
                     'user-guide/skills/bundled/software-development/software-development-test-driven-development',
                   ],
                 },
-                {
-                  type: 'category',
-                  label: 'yuanbao',
-                  key: 'skills-bundled-yuanbao',
-                  collapsed: true,
-                  items: [
-                    'user-guide/skills/bundled/yuanbao/yuanbao-yuanbao',
-                  ],
-                },
               ],
             },
             {
@@ -400,11 +362,13 @@ const sidebars: SidebarsConfig = {
                   key: 'skills-optional-creative',
                   collapsed: true,
                   items: [
+                    'user-guide/skills/optional/creative/creative-audiocraft-audio-generation',
                     'user-guide/skills/optional/creative/creative-baoyu-article-illustrator',
                     'user-guide/skills/optional/creative/creative-baoyu-comic',
                     'user-guide/skills/optional/creative/creative-blender-mcp',
                     'user-guide/skills/optional/creative/creative-concept-diagrams',
                     'user-guide/skills/optional/creative/creative-creative-ideation',
+                    'user-guide/skills/optional/creative/creative-heartmula',
                     'user-guide/skills/optional/creative/creative-hyperframes',
                     'user-guide/skills/optional/creative/creative-kanban-video-orchestrator',
                     'user-guide/skills/optional/creative/creative-meme-generation',
@@ -412,6 +376,15 @@ const sidebars: SidebarsConfig = {
                     'user-guide/skills/optional/creative/creative-unreal-mcp',
                   ],
                 },
+                {
+                  type: 'category',
+                  label: 'data-science',
+                  key: 'skills-optional-data-science',
+                  collapsed: true,
+                  items: [
+                    'user-guide/skills/optional/data-science/data-science-jupyter-notebook',
+                  ],
+                },
                 {
                   type: 'category',
                   label: 'devops',
@@ -527,6 +500,7 @@ const sidebars: SidebarsConfig = {
                     'user-guide/skills/optional/mlops/mlops-pytorch-lightning',
                     'user-guide/skills/optional/mlops/mlops-qdrant',
                     'user-guide/skills/optional/mlops/mlops-saelens',
+                    'user-guide/skills/optional/mlops/mlops-models-segment-anything-model',
                     'user-guide/skills/optional/mlops/mlops-simpo',
                     'user-guide/skills/optional/mlops/mlops-slime',
                     'user-guide/skills/optional/mlops/mlops-stable-diffusion',
@@ -617,6 +591,15 @@ const sidebars: SidebarsConfig = {
                     'user-guide/skills/optional/web-development/web-development-page-agent',
                   ],
                 },
+                {
+                  type: 'category',
+                  label: 'yuanbao',
+                  key: 'skills-optional-yuanbao',
+                  collapsed: true,
+                  items: [
+                    'user-guide/skills/optional/yuanbao/yuanbao-yuanbao',
+                  ],
+                },
               ],
             },
           ],
@@ -790,6 +773,7 @@ const sidebars: SidebarsConfig = {
             'developer-guide/browser-supervisor',
             'developer-guide/acp-internals',
             'developer-guide/cron-internals',
+            'developer-guide/egress-internals',
             'developer-guide/trajectory-format',
           ],
         },
diff --git a/website/static/api/model-catalog.json b/website/static/api/model-catalog.json
index 4711abbd87b..3fa346ca4b3 100644
--- a/website/static/api/model-catalog.json
+++ b/website/static/api/model-catalog.json
@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "updated_at": "2026-07-20T08:23:45Z",
+  "updated_at": "2026-07-24T19:06:06Z",
   "metadata": {
     "source": "hermes-agent repo",
     "docs": "https://hermes-agent.nousresearch.com/docs/reference/model-catalog"
@@ -16,6 +16,14 @@
           "id": "anthropic/claude-fable-5",
           "description": ""
         },
+        {
+          "id": "anthropic/claude-opus-5",
+          "description": ""
+        },
+        {
+          "id": "anthropic/claude-opus-5-fast",
+          "description": "2x price, higher output speed"
+        },
         {
           "id": "anthropic/claude-opus-4.8",
           "description": ""
@@ -180,6 +188,9 @@
         {
           "id": "anthropic/claude-fable-5"
         },
+        {
+          "id": "anthropic/claude-opus-5"
+        },
         {
           "id": "anthropic/claude-opus-4.8"
         },