feat(skills): wake-word-training — teach Hermes to train custom wake words

Adds an optional skill so Hermes can build a custom openWakeWord model for a
phrase other than the bundled "hey hermes" (defaults to "hey <profile>"). The
skill drives openWakeWord's own trainer via the terminal tool — no heavy
training stack ships in core, and the existing resolver already loads the
resulting .onnx by path, so there are zero changes to the wake runtime.

- SKILL.md: end-to-end procedure (synthetic positives, augmentation/negatives,
  train, export into the profile's ~/.hermes/wakewords/, wire config, restart).
- scripts/generate_positives.py: OpenAI-TTS positives (default when
  OPENAI_API_KEY is set) with import-lazy synthesis; pure planning helpers.
- scripts/make_training_config.py: emits the openWakeWord training YAML.
- references/platforms.md: Colab fast path + macOS caveats + dataset sources.
- tests: frontmatter contract + pure helper logic, stdlib-only, no network.
- docs: point the wake-word "different phrase" section at the skill.

.github/workflows/js-tests.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     outputs:
-      packages: ${{ steps.set-matrix.outputs.packages }}
+      checks: ${{ steps.set-matrix.outputs.checks }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
@@ -22,21 +22,40 @@ jobs:
           command: npm ci --ignore-scripts
       - id: set-matrix
         run: |
-          PACKAGES=$(npm query .workspace | jq -c '[.[].location]')
-          if [ "$PACKAGES" = "[]" ] || [ -z "$PACKAGES" ]; then
-            echo "::error::Workspace discovery produced an empty package list — refusing to emit a zero-length matrix (would skip all JS/TS checks silently)."
-            exit 1
-          fi
-          echo "packages=$PACKAGES" >> "$GITHUB_OUTPUT"
+          node -e '
+          const { execSync } = require("child_process");
+          const pkgs = JSON.parse(execSync("npm query .workspace", { encoding: "utf-8" }));
+          if (pkgs.length === 0) {
+            console.error("::error::Workspace discovery produced an empty package list — refusing to emit a zero-length matrix (would skip all JS/TS checks silently).");
+            process.exit(1);
+          }
+          const checks = [];
+          for (const pkg of pkgs) {
+            const scripts = pkg.scripts || {};
+            const subs = Object.keys(scripts).filter(s => /^check:.+$/.test(s));
+            if (subs.length > 0) {
+              for (const script of subs) {
+                checks.push({ package: pkg.location, script });
+              }
+            } else if (scripts.check) {
+              checks.push({ package: pkg.location, script: "check" });
+            }
+          }
+          if (checks.length === 0) {
+            console.error("::error::No check scripts found in any workspace package.");
+            process.exit(1);
+          }
+          process.stdout.write("checks=" + JSON.stringify(checks) + "\n");
+          ' >> "$GITHUB_OUTPUT"
 
   check:
-    name: Typecheck & Test
+    name: ${{ matrix.package }} / ${{ matrix.script }}
     needs: workspaces
     runs-on: ubuntu-latest
     timeout-minutes: 20
     strategy:
       matrix:
-        package: ${{ fromJson(needs.workspaces.outputs.packages) }}
+        include: ${{ fromJson(needs.workspaces.outputs.checks) }}
       fail-fast: false # report all failures, not just the first one
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -47,5 +66,4 @@ jobs:
       - uses: ./.github/actions/retry
         with:
           command: npm ci
-      - run: npm run --prefix ${{ matrix.package }} check
-      - run: npm run --prefix ${{ matrix.package }} fix
+      - run: npm run --prefix ${{ matrix.package }} ${{ matrix.script }}

acp_adapter/server.py

@@ -1936,8 +1936,8 @@ class HermesACPAgent(acp.Agent):
                 return "No tools available."
             lines = [f"Available tools ({len(tools)}):"]
             for t in tools:
-                name = t.get("function", {}).get("name", "?")
-                desc = t.get("function", {}).get("description", "")
+                name = (t.get("function") or {}).get("name", "?")
+                desc = (t.get("function") or {}).get("description", "")
                 # Truncate long descriptions
                 if len(desc) > 80:
                     desc = desc[:77] + "..."

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)
@@ -480,6 +517,7 @@ def init_agent(
     checkpoint_max_total_size_mb: int = 500,
     checkpoint_max_file_size_mb: int = 10,
     pass_session_id: bool = False,
+    requested_provider: str = None,
 ):
     """
     Initialize the AI Agent.
@@ -488,6 +526,7 @@ def init_agent(
         base_url (str): Base URL for the model API (optional)
         api_key (str): API key for authentication (optional, uses env var if not provided)
         provider (str): Provider identifier (optional; used for telemetry/routing hints)
+        requested_provider (str): Original provider identity before runtime canonicalization
         api_mode (str): API mode override: "chat_completions" or "codex_responses"
         model (str): Model name to use (default: "anthropic/claude-opus-4.6")
         max_iterations (int): Maximum number of tool calling iterations (default: 90)
@@ -568,6 +607,11 @@ def init_agent(
     agent.base_url = base_url or ""
     provider_name = provider.strip().lower() if isinstance(provider, str) and provider.strip() else None
     agent.provider = provider_name or ""
+    agent.requested_provider = (
+        requested_provider.strip().lower()
+        if isinstance(requested_provider, str) and requested_provider.strip()
+        else agent.provider
+    )
     agent._credential_pool = credential_pool
     agent.acp_command = acp_command or command
     agent.acp_args = list(acp_args or args or [])
@@ -1018,49 +1062,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"
@@ -1803,6 +1818,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
@@ -1831,6 +1868,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
@@ -2305,6 +2375,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):
@@ -2569,6 +2643,7 @@ def init_agent(
     agent._primary_runtime = {
         "model": agent.model,
         "provider": agent.provider,
+        "requested_provider": agent.requested_provider,
         "base_url": agent.base_url,
         "api_mode": agent.api_mode,
         "api_key": getattr(agent, "api_key", ""),

agent/agent_runtime_helpers.py

@@ -922,12 +922,17 @@ def recover_with_credential_pool(
             )
             return False, has_retried_429
 
-    # Capture the current API key before any rotation — needed to
-    # identify which credential actually failed when
-    # mark_exhausted_and_rotate is called.  Without this hint the
-    # pool falls back to current() or _select_unlocked(), which may
-    # return the NEXT (healthy) entry after a prior rotation, marking
-    # the wrong credential as exhausted (#43747).
+    # Attribute the failure to the API key the agent actually dispatched the
+    # request with, not to pool.current(). The current() pointer is shared,
+    # mutable state — round-robin select() advances it on every call, and
+    # concurrent turns or a second process (gateway/dashboard) reloading the
+    # pool reset it to None — so by the time recovery runs it routinely points
+    # at a DIFFERENT, healthy entry. Marking that entry exhausted copies this
+    # request's error/reset time onto it and can take the whole pool offline
+    # from a single rate-limited key (#43747). ``_swap_credential`` keeps
+    # ``agent.api_key`` in sync with the entry in use, so it identifies the
+    # 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
     if not _api_key_hint:
         _cur = pool.current()
@@ -987,7 +992,16 @@ def recover_with_credential_pool(
         # rotate immediately. This prevents the "cancel-between-429s" trap
         # where has_retried_429 (a local var) gets reset on each new prompt,
         # causing the pool to retry the same exhausted credential forever.
-        current_entry = pool.current()
+        # 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:
+            current_entry = next(
+                (e for e in pool.entries() if e.runtime_api_key == _api_key_hint),
+                None,
+            )
+        if current_entry is None:
+            current_entry = pool.current()
         current_last_status = getattr(current_entry, "last_status", None) if current_entry else None
         if current_last_status == STATUS_EXHAUSTED:
             _ra().logger.info(
@@ -995,7 +1009,11 @@ 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 = pool.mark_exhausted_and_rotate(
+                status_code=rotate_status,
+                error_context=error_context,
+                api_key_hint=_api_key_hint,
+            )
             if next_entry is not None:
                 _ra().logger.info(
                     "Credential %s (rate limit, pre-exhausted) — rotated to pool entry %s",
@@ -1019,7 +1037,11 @@ 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 = pool.mark_exhausted_and_rotate(
+            status_code=rotate_status,
+            error_context=error_context,
+            api_key_hint=_api_key_hint,
+        )
         if next_entry is not None:
             _ra().logger.info(
                 "Credential %s (rate limit) — rotated to pool entry %s",
@@ -1034,7 +1056,7 @@ def recover_with_credential_pool(
         # Subscription/entitlement 403s look like auth failures on the wire
         # but refresh cannot fix them — the OAuth token is already valid,
         # the account simply lacks the entitlement.  Without this guard,
-        # ``try_refresh_current()`` keeps minting fresh tokens against the
+        # the refresh path keeps minting fresh tokens against the
         # same unsubscribed account and the main agent loop spins re-issuing
         # the same 403 until the user Ctrl+C's.
         #
@@ -1087,9 +1109,13 @@ def recover_with_credential_pool(
                 agent.provider or "provider",
             )
             return False, has_retried_429
-        refreshed = pool.try_refresh_current()
+        # Refresh the entry that supplied the failing key, not current():
+        # 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)
         if refreshed is not None:
-            # ``try_refresh_current()`` re-mints a fresh OAuth token and reports
+            # ``try_refresh_matching()`` re-mints a fresh OAuth token and reports
             # success even when the upstream keeps rejecting it — a single-entry
             # pool (common for OAuth/Max subscribers) has nothing to rotate to,
             # so a bare "refreshed → retry" loop spins forever on the same dead
@@ -1117,9 +1143,13 @@ def recover_with_credential_pool(
             agent._swap_credential(refreshed)
             return True, has_retried_429
         # Refresh failed — rotate to next credential instead of giving up.
-        # The failed entry is already marked exhausted by try_refresh_current().
+        # 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 = pool.mark_exhausted_and_rotate(
+            status_code=rotate_status,
+            error_context=error_context,
+            api_key_hint=_api_key_hint,
+        )
         if next_entry is not None:
             _ra().logger.info(
                 "Credential %s (auth refresh failed) — rotated to pool entry %s",
@@ -1178,6 +1208,7 @@ def try_recover_primary_transport(
         agent._client_kwargs = dict(rt["client_kwargs"])
         agent.model = rt["model"]
         agent.provider = rt["provider"]
+        agent.requested_provider = rt.get("requested_provider", agent.provider)
         agent.base_url = rt["base_url"]
         agent.api_mode = rt["api_mode"]
         if hasattr(agent, "_transport_cache"):
@@ -1194,6 +1225,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"]),
@@ -1341,6 +1380,7 @@ def restore_primary_runtime(agent) -> bool:
         # ── Core runtime state ──
         agent.model = rt["model"]
         agent.provider = rt["provider"]
+        agent.requested_provider = rt.get("requested_provider", agent.provider)
         agent.base_url = rt["base_url"]           # setter updates _base_url_lower
         agent.api_mode = rt["api_mode"]
         if hasattr(agent, "_transport_cache"):
@@ -1356,7 +1396,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"]
@@ -2005,6 +2056,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
         for name in (
             "model",
             "provider",
+            "requested_provider",
             "base_url",
             "api_mode",
             "api_key",
@@ -2033,6 +2085,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
         # ── Swap core runtime fields ──
         agent.model = new_model
         agent.provider = new_provider
+        agent.requested_provider = new_provider
         # Use the new base_url when provided. When it's empty AND the
         # provider is actually changing, do NOT fall back to the current
         # (old provider's) URL — that silently pairs the new provider label
@@ -2090,7 +2143,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
 
         # ── 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
@@ -2107,7 +2160,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,
@@ -2282,6 +2335,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
     agent._primary_runtime = {
         "model": agent.model,
         "provider": agent.provider,
+        "requested_provider": agent.requested_provider,
         "base_url": agent.base_url,
         "api_mode": agent.api_mode,
         "api_key": getattr(agent, "api_key", ""),

agent/anthropic_adapter.py

@@ -1881,6 +1881,28 @@ def _content_parts_to_anthropic_blocks(parts: Any) -> List[Dict[str, Any]]:
     return out
 
 
+_EMPTY_TEXT_PLACEHOLDER = "(empty)"
+
+
+def _safe_text(text: Any) -> str:
+    """Return ``text`` if it's non-whitespace, else a non-whitespace placeholder.
+
+    The Anthropic Messages API rejects requests where a text content block is
+    empty or whitespace-only (HTTP 400 "text content blocks must contain
+    non-whitespace text"). When such a block gets stored in session history —
+    e.g. produced by context compression — it is replayed verbatim on every
+    subsequent turn, permanently wedging the session. Coercing to a
+    non-whitespace placeholder is self-healing: the next API call recovers.
+
+    Mirrors ``bedrock_adapter._safe_text`` (#9486); ref #69512.
+    """
+    if text is None:
+        return _EMPTY_TEXT_PLACEHOLDER
+    if not isinstance(text, str):
+        text = str(text)
+    return text if text.strip() else _EMPTY_TEXT_PLACEHOLDER
+
+
 def _sanitize_replay_block(b: Dict[str, Any]) -> Optional[Dict[str, Any]]:
     """Strip output-only fields from a stored Anthropic content block so it is
     valid as REQUEST input on replay.
@@ -1898,7 +1920,10 @@ def _sanitize_replay_block(b: Dict[str, Any]) -> Optional[Dict[str, Any]]:
         return None
     btype = b.get("type")
     if btype == "text":
-        out: Dict[str, Any] = {"type": "text", "text": b.get("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", ""))}
         # 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")
@@ -2058,7 +2083,16 @@ def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
     # Anthropic rejects empty assistant content
     effective = blocks or content
     if not effective or effective == "":
-        effective = [{"type": "text", "text": "(empty)"}]
+        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", ""))
     return {"role": "assistant", "content": effective}
 
 

agent/auxiliary_client.py

@@ -2303,6 +2303,62 @@ def _read_main_base_url() -> str:
     return ""
 
 
+def _resolve_moa_aggregator(preset_name: Optional[str]) -> Tuple[Optional[str], Optional[str]]:
+    """Resolve a MoA preset to its aggregator (provider, model) pair.
+
+    "moa" is a virtual provider — the acting model of a preset is its
+    aggregator slot, and there is no real "moa" HTTP endpoint. Auxiliary
+    tasks (title generation, compression, vision, commit messages, …) don't
+    need the reference fan-out, so every aux resolution layer maps
+    provider="moa"/model=<preset> to the aggregator's real provider+model
+    through this single helper (shared by ``_resolve_auto``,
+    ``_resolve_task_provider_model``, and ``resolve_provider_client`` so the
+    preset lookup and validation cannot drift between paths).
+
+    Args:
+        preset_name: The MoA preset name (usually carried in the "model"
+            field), or None/"" to resolve the user's default preset.
+
+    Returns:
+        (aggregator_provider, aggregator_model), or (None, None) when the
+        preset cannot be resolved (missing config, renamed/deleted preset,
+        or a malformed aggregator slot).
+    """
+    try:
+        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 {}, preset_name or None)
+        agg = preset.get("aggregator") or {}
+        agg_provider = str(agg.get("provider") or "").strip()
+        agg_model = str(agg.get("model") or "").strip()
+        if agg_provider and agg_model and agg_provider.lower() != "moa":
+            return agg_provider, agg_model
+    except Exception:
+        logger.debug(
+            "MoA aggregator resolution failed for preset %r", preset_name, exc_info=True
+        )
+    return None, None
+
+
+def _read_main_model_for_aux() -> str:
+    """Main model with MoA presets unwrapped to the aggregator's model.
+
+    When the main provider is ``moa``, ``_read_main_model()`` returns a MoA
+    *preset name* (e.g. "opus-gpt") — never a valid wire model id on any
+    provider. Auxiliary fallback chains that pre-fill a missing model from
+    the main model must use this reader instead, so unset aux models default
+    to the preset's acting (aggregator) model. Returns "" when the main
+    provider is moa but the preset cannot be resolved — sending nothing is
+    strictly better than sending a preset name that 400s.
+    """
+    model = _read_main_model()
+    if (_read_main_provider() or "").strip().lower() == "moa":
+        _, agg_model = _resolve_moa_aggregator(model)
+        return agg_model or ""
+    return model
+
+
 def _read_main_api_key_if_same_host(aux_base_url: str) -> str:
     """Return the main api_key only when *aux_base_url* points at the same
     host as the main model's base_url.
@@ -2378,6 +2434,7 @@ def set_runtime_main(
     provider: str,
     model: str,
     *,
+    requested_provider: str = "",
     base_url: str = "",
     api_key: Any = "",
     api_mode: str = "",
@@ -2393,6 +2450,7 @@ def set_runtime_main(
     global _RUNTIME_MAIN_AUTH_MODE, _RUNTIME_MAIN_COMPAT_SNAPSHOT
     runtime = {
         "provider": (provider or "").strip().lower(),
+        "requested_provider": (requested_provider or "").strip().lower(),
         "model": (model or "").strip(),
         "base_url": (base_url or "").strip(),
         "api_key": (
@@ -2573,7 +2631,7 @@ def _try_custom_endpoint() -> Tuple[Optional[Any], Optional[str]]:
         return None, None
     if custom_base.lower().startswith(_CODEX_AUX_BASE_URL.lower()):
         return None, None
-    model = _read_main_model() or "gpt-4o-mini"
+    model = _read_main_model_for_aux() or "gpt-4o-mini"
     logger.debug("Auxiliary client: custom endpoint (%s, api_mode=%s)", model, custom_mode or "chat_completions")
     _clean_base, _dq = _extract_url_query_params(custom_base)
     _extra = {"default_query": _dq} if _dq else {}
@@ -2865,6 +2923,7 @@ _AUTO_PROVIDER_LABELS = {
 }
 
 _MAIN_RUNTIME_FIELDS = ("provider", "model", "base_url", "api_key", "api_mode", "auth_mode")
+_MAIN_RUNTIME_CONTEXT_FIELDS = _MAIN_RUNTIME_FIELDS + ("requested_provider",)
 
 
 def _normalize_main_runtime(main_runtime: Optional[Dict[str, Any]]) -> Dict[str, Any]:
@@ -2887,7 +2946,7 @@ def _normalize_main_runtime(main_runtime: Optional[Dict[str, Any]]) -> Dict[str,
     if not isinstance(main_runtime, dict):
         return {}
     normalized: Dict[str, Any] = {}
-    for field in _MAIN_RUNTIME_FIELDS:
+    for field in _MAIN_RUNTIME_CONTEXT_FIELDS:
         value = main_runtime.get(field)
         # Preserve a callable api_key (Entra ID bearer provider) unchanged.
         if field == "api_key" and callable(value) and not isinstance(value, str):
@@ -2895,9 +2954,10 @@ def _normalize_main_runtime(main_runtime: Optional[Dict[str, Any]]) -> Dict[str,
             continue
         if isinstance(value, str) and value.strip():
             normalized[field] = value.strip()
-    provider = normalized.get("provider")
-    if isinstance(provider, str):
-        normalized["provider"] = provider.lower()
+    for identity_field in ("provider", "requested_provider"):
+        identity = normalized.get(identity_field)
+        if isinstance(identity, str):
+            normalized[identity_field] = identity.lower()
     return normalized
 
 
@@ -3588,6 +3648,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(
@@ -3623,7 +3684,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(
@@ -3647,6 +3714,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(
@@ -3682,7 +3750,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(
@@ -3757,6 +3830,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
@@ -3870,7 +3961,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(
             fb_client.chat.completions.create(**fb_kwargs), task)
@@ -3887,7 +3978,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(
                         retry_client.chat.completions.create(**retry_kwargs), task)
@@ -3936,7 +4027,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 fb_client.chat.completions.create(**fb_kwargs), task)
@@ -3954,7 +4045,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 retry_client.chat.completions.create(**retry_kwargs), task)
@@ -4041,6 +4132,13 @@ def _try_main_agent_model_fallback(
     """
     main_provider = (_read_main_provider() or "").strip()
     main_model = (_read_main_model() or "").strip()
+    if main_provider.lower() == "moa":
+        # MoA virtual provider: fall back to the preset's aggregator — the
+        # acting model — instead of the unreachable "moa"/<preset-name> pair.
+        _agg_provider, _agg_model = _resolve_moa_aggregator(main_model)
+        if not _agg_provider or not _agg_model:
+            return None, None, ""
+        main_provider, main_model = _agg_provider, _agg_model
     if not main_provider or not main_model or main_provider.lower() in {"auto", ""}:
         return None, None, ""
 
@@ -4441,26 +4539,17 @@ def _resolve_auto(
     # model. Resolve the MoA preset to its aggregator slot and continue Step 1
     # with that real provider+model. Mirrors the MoA context-length resolution.
     if main_provider == "moa":
-        try:
-            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 {}, main_model)
-            _agg = _preset.get("aggregator") or {}
-            _agg_provider = str(_agg.get("provider") or "").strip()
-            _agg_model = str(_agg.get("model") or "").strip()
-            if _agg_provider and _agg_model and _agg_provider.lower() != "moa":
-                main_provider = _agg_provider
-                main_model = _agg_model
-                # The MoA virtual runtime carries a non-HTTP base_url
-                # ("moa://local") and a placeholder api_key; they belong to the
-                # facade, not the aggregator's real provider. Drop them so the
-                # aggregator resolves through its own provider credentials.
-                runtime_base_url = ""
-                runtime_api_key = ""
-                runtime_api_mode = ""
-        except Exception:
-            logger.debug("MoA aux resolution to aggregator failed", exc_info=True)
+        _agg_provider, _agg_model = _resolve_moa_aggregator(main_model)
+        if _agg_provider and _agg_model:
+            main_provider = _agg_provider
+            main_model = _agg_model
+            # The MoA virtual runtime carries a non-HTTP base_url
+            # ("moa://local") and a placeholder api_key; they belong to the
+            # facade, not the aggregator's real provider. Drop them so the
+            # aggregator resolves through its own provider credentials.
+            runtime_base_url = ""
+            runtime_api_key = ""
+            runtime_api_mode = ""
 
     if (main_provider and main_model
             and main_provider not in {"auto", ""}):
@@ -4715,6 +4804,27 @@ def resolve_provider_client(
     # Normalise aliases
     provider = _normalize_aux_provider(provider)
 
+    # MoA virtual provider chokepoint: "moa" is not a real HTTP provider —
+    # its acting model is the preset's aggregator slot. The two resolver
+    # layers above (_resolve_auto, _resolve_task_provider_model) already
+    # unwrap their own paths, but callers that route here directly (vision
+    # auto-detect, _try_main_agent_model_fallback, get_available_vision_backends,
+    # plugin code) would otherwise dead-end in the unknown-provider branch.
+    # ``model`` carries the preset name for moa calls; when the preset can't
+    # be resolved we leave the call untouched and let the normal
+    # missing-provider handling produce its diagnostic.
+    if provider == "moa":
+        _agg_provider, _agg_model = _resolve_moa_aggregator(model)
+        if _agg_provider and _agg_model:
+            original_provider = _agg_provider.strip().lower()
+            provider = _normalize_aux_provider(_agg_provider)
+            model = _agg_model
+            # The moa:// facade endpoint and placeholder key belong to the
+            # virtual runtime, not the aggregator's real provider.
+            if explicit_base_url and str(explicit_base_url).lower().startswith("moa://"):
+                explicit_base_url = None
+                explicit_api_key = None
+
     # Universal model-resolution fallback for concrete providers. ``auto`` is
     # intentionally excluded: `_resolve_auto(main_runtime=...)` returns the
     # model paired with the provider it actually selected. Pre-filling an auto
@@ -4735,6 +4845,10 @@ def resolve_provider_client(
     #      the load-bearing step for OAuth providers: an xai-oauth user
     #      with grok-4.3 configured gets grok-4.3 for title generation
     #      instead of silently dropping to whatever Step-2 fallback (#31845).
+    #      When the main provider is MoA, ``_read_main_model_for_aux()``
+    #      substitutes the preset's aggregator model — the preset NAME is
+    #      never a valid wire model id, so unset aux models default to the
+    #      preset's acting model instead.
     #
     # Each provider branch below sees a non-empty ``model`` whenever the
     # user has *anything* configured — no provider-specific empty-model
@@ -4751,7 +4865,7 @@ def resolve_provider_client(
     # return the actual current runtime model when the caller did not explicitly
     # request one. (# compression-current-model)
     if not model and provider != "auto":
-        model = _get_aux_model_for_provider(provider) or _read_main_model() or model
+        model = _get_aux_model_for_provider(provider) or _read_main_model_for_aux() or model
 
     def _needs_codex_wrap(client_obj, base_url_str: str, model_str: str) -> bool:
         """Decide if a plain OpenAI client should be wrapped for Responses API.
@@ -5025,7 +5139,7 @@ def resolve_provider_client(
                     model
                     or custom_entry.get("model")
                     or (main_runtime.get("model") if main_runtime else None)
-                    or _read_main_model()
+                    or _read_main_model_for_aux()
                     or "gpt-4o-mini",
                     provider,
                 )
@@ -5260,7 +5374,7 @@ def resolve_provider_client(
         final_model = _normalize_resolved_model(
             model
             or (main_runtime.get("model") if main_runtime else None)
-            or _read_main_model(),
+            or _read_main_model_for_aux(),
             provider,
         )
         if provider == "copilot-acp":
@@ -5628,7 +5742,24 @@ def resolve_vision_provider_client(
         #   5. Stop
         main_provider = str(runtime.get("provider") or _read_main_provider())
         main_model = str(runtime.get("model") or _read_main_model())
-        if main_provider and main_provider not in {"auto", ""}:
+        if main_provider.strip().lower() == "moa":
+            # MoA virtual provider: main_model is a preset NAME, and every
+            # capability probe below (_PROVIDERS_WITHOUT_VISION,
+            # _main_model_supports_vision, _resolve_provider_vision_default)
+            # would run against a provider/model pair that doesn't exist on
+            # any wire. Unwrap to the preset's aggregator slot first so the
+            # checks and the eventual client target the real acting model.
+            _agg_provider, _agg_model = _resolve_moa_aggregator(main_model)
+            if _agg_provider and _agg_model:
+                main_provider, main_model = _agg_provider, _agg_model
+                # Drop the moa:// facade endpoint from the runtime view used
+                # below — it belongs to the virtual provider, not the
+                # aggregator's real provider.
+                runtime = dict(runtime)
+                runtime["base_url"] = ""
+                runtime["api_key"] = ""
+                runtime["api_mode"] = ""
+        if main_provider and main_provider not in {"auto", "", "moa"}:
             # A provider-specific vision default wins over the user's chat model:
             # static overrides (xiaomi/zai) and catalog-backed discovery (the
             # DeepInfra profile hook) both yield a *known* vision-capable model,
@@ -6225,8 +6356,8 @@ def _resolve_task_provider_model(
     task: str = None,
     provider: str = None,
     model: str = None,
-    base_url: str = None,
-    api_key: str = None,
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
 ) -> Tuple[str, Optional[str], Optional[str], Optional[str], Optional[str]]:
     """Determine provider + model for a call.
 
@@ -6269,12 +6400,57 @@ def _resolve_task_provider_model(
     # which downstream consumers like ContextCompressor accept as the task output.
     # The provider-side 'auto' is handled in _resolve_auto() via main_runtime
     # fallback, so dropping cfg_model to None here lets that path do its job.
+    #
+    # The explicit `model` kwarg needs the identical normalization: MoA slots
+    # (agent/moa_loop.py's _slot_runtime) forward a preset's `model:` field as
+    # this explicit argument rather than through auxiliary.<task> config, so a
+    # user-configured `model: auto` on a MoA reference/aggregator slot reaches
+    # this function here, not as cfg_model. Only normalizing cfg_model let that
+    # literal "auto" slip through via `model or cfg_model` below.
+    if model and model.lower() == "auto":
+        model = None
     if cfg_model and cfg_model.lower() == "auto":
         cfg_model = None
 
     resolved_model = model or cfg_model
     resolved_api_mode = cfg_api_mode
 
+    # MoA virtual provider: an *explicit* `provider: moa` override (either the
+    # caller-passed `provider` arg or `auxiliary.<task>.provider` in
+    # config.yaml) reaches this function directly — it never goes through
+    # _resolve_auto(), which only unwraps the *implicit* "main provider is
+    # moa" case (#53827). Left as-is, "moa" is returned verbatim and
+    # resolve_provider_client() looks it up in PROVIDER_REGISTRY (which has
+    # no "moa" entry — it's not a real HTTP provider), falls to the
+    # unknown-provider dead end, and call_llm surfaces a nonsensical
+    # "MOA_API_KEY environment variable" error for a provider that was never
+    # meant to be reached over the wire. Auxiliary tasks don't need the
+    # reference fan-out — resolve to the preset's aggregator slot instead,
+    # exactly like the implicit path does (shared helper: _resolve_moa_aggregator).
+    def _unwrap_moa_provider(prov: str, mdl: Optional[str]) -> Tuple[str, Optional[str]]:
+        if prov.strip().lower() != "moa":
+            return prov, mdl
+        agg_provider, agg_model = _resolve_moa_aggregator(mdl)
+        if agg_provider and agg_model:
+            return agg_provider, agg_model
+        return prov, mdl
+
+    if provider and str(provider).strip().lower() == "moa":
+        provider, resolved_model = _unwrap_moa_provider(provider, resolved_model)
+        # The moa:// virtual endpoint (if any explicit base_url/api_key was
+        # passed alongside provider="moa") belongs to the facade, not the
+        # aggregator's real provider — drop it so the aggregator resolves
+        # through its own provider credentials, mirroring _resolve_auto().
+        if provider and provider.lower() != "moa":
+            base_url = None
+            api_key = None
+    elif cfg_provider and str(cfg_provider).strip().lower() == "moa":
+        cfg_provider, cfg_model = _unwrap_moa_provider(cfg_provider, resolved_model)
+        if cfg_provider and cfg_provider.lower() != "moa":
+            resolved_model = cfg_model
+            cfg_base_url = None
+            cfg_api_key = None
+
     # Convenience aliases for direct API-key endpoints that aren't first-class
     # providers (e.g. ``provider: openai`` → custom + api.openai.com/v1).
     # Applied to both explicit args and config-derived values. When the user
@@ -6631,6 +6807,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] = {
@@ -6685,11 +6862,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
@@ -6921,6 +7119,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,
@@ -6946,6 +7145,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
@@ -7058,7 +7260,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 "")
@@ -7312,6 +7516,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 ─────────────────────
@@ -7355,6 +7560,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
@@ -7674,7 +7880,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):

agent/bedrock_adapter.py

@@ -433,6 +433,29 @@ def _model_supports_tool_use(model_id: str) -> bool:
     return not any(pattern in model_lower for pattern in _NON_TOOL_CALLING_PATTERNS)
 
 
+# ---------------------------------------------------------------------------
+# Prompt-cache capability detection (Converse API cachePoint)
+# ---------------------------------------------------------------------------
+# Claude on Bedrock already gets prompt caching through the AnthropicBedrock
+# SDK path (see is_anthropic_bedrock_model / runtime_provider.py's dual-path
+# routing) — it never reaches build_converse_kwargs unless bearer-token auth
+# forces the Converse path (#28156). This allowlist covers the Converse API
+# itself: sending an unsupported model a cachePoint block raises a
+# ValidationException, so — like _model_supports_tool_use but inverted —
+# unknown models default to NOT receiving cache markers until confirmed.
+# Ref: https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
+_CACHE_POINT_PATTERNS = [
+    "anthropic.claude",  # bearer-token fallback path
+    "amazon.nova",
+]
+
+
+def _model_supports_prompt_cache(model_id: str) -> bool:
+    """Return True if the model accepts a Converse API cachePoint block."""
+    model_lower = model_id.lower()
+    return any(pattern in model_lower for pattern in _CACHE_POINT_PATTERNS)
+
+
 def is_anthropic_bedrock_model(model_id: str) -> bool:
     """Return True if the model is an Anthropic Claude model on Bedrock.
 
@@ -764,14 +787,22 @@ def normalize_converse_response(response: Dict) -> SimpleNamespace:
         reasoning_content="\n\n".join(reasoning_parts) if reasoning_parts else None,
     )
 
-    # Build usage stats
+    # Build usage stats. Converse's inputTokens excludes cache read/write
+    # tokens (unlike OpenAI's prompt_tokens, which includes them) — restore
+    # the OpenAI-style "total includes cache" convention here so downstream
+    # normalize_usage() can subtract them back out consistently, and surface
+    # the Anthropic-named fields it already falls back to for cache reads.
     usage_data = response.get("usage", {})
+    input_tokens = usage_data.get("inputTokens", 0)
+    cache_read_tokens = usage_data.get("cacheReadInputTokens", 0)
+    cache_write_tokens = usage_data.get("cacheWriteInputTokens", 0)
+    output_tokens = usage_data.get("outputTokens", 0)
     usage = SimpleNamespace(
-        prompt_tokens=usage_data.get("inputTokens", 0),
-        completion_tokens=usage_data.get("outputTokens", 0),
-        total_tokens=(
-            usage_data.get("inputTokens", 0) + usage_data.get("outputTokens", 0)
-        ),
+        prompt_tokens=input_tokens + cache_read_tokens + cache_write_tokens,
+        completion_tokens=output_tokens,
+        total_tokens=input_tokens + cache_read_tokens + cache_write_tokens + output_tokens,
+        cache_read_input_tokens=cache_read_tokens,
+        cache_creation_input_tokens=cache_write_tokens,
     )
 
     finish_reason = _converse_stop_reason_to_openai(stop_reason)
@@ -936,6 +967,8 @@ def stream_converse_with_callbacks(
             usage_data = {
                 "inputTokens": meta_usage.get("inputTokens", 0),
                 "outputTokens": meta_usage.get("outputTokens", 0),
+                "cacheReadInputTokens": meta_usage.get("cacheReadInputTokens", 0),
+                "cacheWriteInputTokens": meta_usage.get("cacheWriteInputTokens", 0),
             }
 
     # Flush remaining text
@@ -949,12 +982,16 @@ def stream_converse_with_callbacks(
         reasoning_content="\n\n".join(reasoning_parts) if reasoning_parts else None,
     )
 
+    input_tokens = usage_data.get("inputTokens", 0)
+    cache_read_tokens = usage_data.get("cacheReadInputTokens", 0)
+    cache_write_tokens = usage_data.get("cacheWriteInputTokens", 0)
+    output_tokens = usage_data.get("outputTokens", 0)
     usage = SimpleNamespace(
-        prompt_tokens=usage_data.get("inputTokens", 0),
-        completion_tokens=usage_data.get("outputTokens", 0),
-        total_tokens=(
-            usage_data.get("inputTokens", 0) + usage_data.get("outputTokens", 0)
-        ),
+        prompt_tokens=input_tokens + cache_read_tokens + cache_write_tokens,
+        completion_tokens=output_tokens,
+        total_tokens=input_tokens + cache_read_tokens + cache_write_tokens + output_tokens,
+        cache_read_input_tokens=cache_read_tokens,
+        cache_creation_input_tokens=cache_write_tokens,
     )
 
     finish_reason = _converse_stop_reason_to_openai(stop_reason)
@@ -993,6 +1030,7 @@ def build_converse_kwargs(
     Converts OpenAI-format inputs to Converse API parameters.
     """
     system_prompt, converse_messages = convert_messages_to_converse(messages)
+    cache_enabled = _model_supports_prompt_cache(model)
 
     kwargs: Dict[str, Any] = {
         "modelId": model,
@@ -1003,6 +1041,8 @@ def build_converse_kwargs(
     }
 
     if system_prompt:
+        if cache_enabled:
+            system_prompt = system_prompt + [{"cachePoint": {"type": "default"}}]
         kwargs["system"] = system_prompt
 
     from agent.anthropic_adapter import _forbids_sampling_params
@@ -1026,6 +1066,8 @@ def build_converse_kwargs(
             # Strip tools for known non-tool-calling models and warn the user.
             # Ref: PR #7920 feedback from @ptlally, pattern from PR #4346.
             if _model_supports_tool_use(model):
+                if cache_enabled:
+                    converse_tools = converse_tools + [{"cachePoint": {"type": "default"}}]
                 kwargs["toolConfig"] = {"tools": converse_tools}
             else:
                 logger.warning(
@@ -1033,6 +1075,14 @@ def build_converse_kwargs(
                     "The agent will operate in text-only mode.", model
                 )
 
+    if cache_enabled and len(converse_messages) >= 2:
+        # Checkpoint everything up to (not including) the newest turn, so the
+        # marker survives unchanged across requests as only the tail grows —
+        # mirroring the Anthropic system_and_3 strategy in prompt_caching.py.
+        content = converse_messages[-2].get("content")
+        if isinstance(content, list) and content:
+            content.append({"cachePoint": {"type": "default"}})
+
     if guardrail_config:
         kwargs["guardrailConfig"] = guardrail_config
 

agent/chat_completion_helpers.py

@@ -1712,6 +1712,7 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None) -> bool
         agent._config_context_length = None
         agent.model = fb_model
         agent.provider = fb_provider
+        agent.requested_provider = fb_provider
         agent.base_url = fb_base_url
         agent.api_mode = fb_api_mode
         if hasattr(agent, "_transport_cache"):
@@ -1945,7 +1946,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 ""
@@ -2462,7 +2473,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
@@ -2482,6 +2497,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)
@@ -2489,9 +2542,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()
             )
@@ -2500,8 +2559,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:
@@ -2680,6 +2740,11 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
         _diag = agent._stream_diag_init()
         request_client_holder["diag"] = _diag
         stream = request_client.chat.completions.create(**stream_kwargs)
+        if agent.provider == "moa":
+            # The MoA facade is a shared singleton — abort/close of the
+            # registered client is a no-op, so register the stream handle
+            # itself for interrupt teardown (#57354).
+            stream = _set_request_stream_handle(stream)
         # Claim the delta sink for THIS attempt (#65991). If a prior attempt's
         # stream is somehow still alive (a stale-stream reconnect whose socket
         # abort raced), this claim supersedes it so its late chunks are fenced

agent/context_engine.py

@@ -53,6 +53,39 @@ def sanitize_memory_context(memory_context: str) -> str:
     )
 
 
+def automatic_compaction_status_message(
+    engine: Any,
+    *,
+    phase: str,
+    default_message: str,
+    **context: Any,
+) -> str | None:
+    """Resolve host-visible status for an automatic compaction event.
+
+    Engines can suppress routine automatic status with
+    ``emit_automatic_compaction_status = False`` or customize it by defining
+    ``get_automatic_compaction_status_message(...)``. Empty strings and
+    ``None`` mean "do not emit a lifecycle status".
+    """
+    if not getattr(engine, "emit_automatic_compaction_status", True):
+        return None
+
+    formatter = getattr(engine, "get_automatic_compaction_status_message", None)
+    if callable(formatter):
+        message = formatter(
+            phase=phase,
+            default_message=default_message,
+            **context,
+        )
+    else:
+        message = default_message
+
+    if message is None:
+        return None
+    message = str(message).strip()
+    return message or None
+
+
 class ContextEngine(ABC):
     """Base class all context engines must implement."""
 
@@ -89,6 +122,12 @@ class ContextEngine(ABC):
     protect_first_n: int = 3
     protect_last_n: int = 6
 
+    # User-visible lifecycle status for automatic host-triggered compaction.
+    # Alternative engines that treat compaction as routine background
+    # maintenance can set this false to keep successful automatic passes silent;
+    # warnings, errors, and explicit manual commands should still surface.
+    emit_automatic_compaction_status: bool = True
+
     # -- Core interface ----------------------------------------------------
 
     @abstractmethod
@@ -107,6 +146,19 @@ class ContextEngine(ABC):
     def should_compress(self, prompt_tokens: int = None) -> bool:
         """Return True if compaction should fire this turn."""
 
+    def should_compress_info(self, prompt_tokens: int = None) -> "tuple[bool, str | None]":
+        """Return ``(should_compress, reason)``.
+
+        The base implementation is backward-compatible: engines that only
+        implement ``should_compress`` get ``(should_compress(prompt_tokens),
+        None)``. Concrete engines with richer block reasons (e.g. a
+        summary-LLM cooldown or an anti-thrashing guard) override this to
+        surface a human-readable reason so callers can warn the user instead
+        of silently skipping compression. Added for the silent-overflow
+        warning fix (#62625) so plugin engines don't raise AttributeError.
+        """
+        return self.should_compress(prompt_tokens), None
+
     @abstractmethod
     def compress(
         self,
@@ -137,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:
@@ -156,6 +346,27 @@ class ContextEngine(ABC):
         """
         return False
 
+    def get_automatic_compaction_status_message(
+        self,
+        *,
+        phase: str,
+        default_message: str,
+        **context: Any,
+    ) -> str | None:
+        """Return user-visible status for automatic host-triggered compaction.
+
+        Return ``None`` to suppress successful automatic lifecycle status for
+        this compaction event. ``phase`` identifies the host call site (for
+        example ``"preflight"`` or ``"compress"``). ``context`` contains
+        best-effort fields such as ``approx_tokens`` and ``threshold_tokens``.
+
+        This hook does not control warning/error messages or explicit manual
+        commands such as ``/compress``.
+        """
+        if not self.emit_automatic_compaction_status:
+            return None
+        return default_message
+
     # -- Optional: manual /compress preflight ------------------------------
 
     def has_content_to_compress(self, messages: List[Dict[str, Any]]) -> bool:

agent/conversation_compression.py

@@ -42,7 +42,10 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Optional, Tuple
 
-from agent.context_engine import sanitize_memory_context
+from agent.context_engine import (
+    automatic_compaction_status_message,
+    sanitize_memory_context,
+)
 from agent.model_metadata import estimate_request_tokens_rough
 
 logger = logging.getLogger(__name__)
@@ -106,6 +109,22 @@ COMPRESSION_RETRY_CONTEXT_REDUCED_STATUS_TEMPLATE = (
     "🗜️ Context reduced to {new_ctx:,} tokens (was {old_ctx:,}), retrying..."
 )
 
+# FAILURE-CLASS notice — a deliberate carve-out from routine-compression
+# silence (#16775 class): the context is over the compression threshold but
+# compression is blocked (summary-LLM cooldown / anti-thrash breaker), so the
+# session will keep growing until the hard provider token limit kills it.
+# This MUST stay visible on chat gateways. Do NOT add it to
+# ROUTINE_COMPRESSION_STATUS_SAMPLES or the gateway noise regex
+# (_TELEGRAM_NOISY_STATUS_RE); it is pinned un-swallowed in
+# tests/gateway/test_telegram_noise_filter.py::VISIBLE_COMPRESSION_MESSAGES.
+CONTEXT_OVERFLOW_BLOCKED_WARNING_TEMPLATE = (
+    "⚠ Context is over the compression threshold "
+    "(~{tokens:,} tokens >= {threshold:,}) "
+    "but compression is currently blocked ({reason}). "
+    "The model may stop responding. Run /new to start a fresh "
+    "session or /compress to retry immediately."
+)
+
 # Sample-formatted instances of every routine compression status line, for
 # behavioral tests that iterate the ACTUAL emitted wording (formatted from the
 # same constants the emission sites use) through the gateway noise filter.
@@ -188,6 +207,64 @@ def _cached_prompt_reflects_builtin_memory(agent: Any, cached_prompt: str) -> bo
     return True
 
 
+class CompressionCommitFence:
+    """Fence timeout cancellation against post-summary session mutation.
+
+    Compression itself is synchronous and may be running in an executor thread.
+    A caller can stop waiting for the summary, but it cannot kill that thread.
+    This fence makes the commit boundary deterministic: cancellation either wins
+    before session mutation starts, or waits until an already-started commit is
+    fully complete before the caller proceeds.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._cancelled = False
+        self._commit_started = False
+
+    def cancel_before_commit(self) -> bool:
+        """Cancel a pending commit, or wait for an active commit to finish.
+
+        Returns ``True`` when cancellation won before the commit boundary.
+        Returns ``False`` when the worker had already entered the boundary; in
+        that case acquiring this lock waits until all session mutation finishes.
+        """
+        with self._lock:
+            if self._commit_started:
+                return False
+            self._cancelled = True
+            return True
+
+    def try_cancel_before_commit(self) -> Optional[bool]:
+        """Non-blocking form of :meth:`cancel_before_commit`.
+
+        Returns ``None`` while an active commit owns the fence, allowing an
+        async caller to yield instead of blocking its event loop.
+        """
+        if not self._lock.acquire(blocking=False):
+            return None
+        try:
+            if self._commit_started:
+                return False
+            self._cancelled = True
+            return True
+        finally:
+            self._lock.release()
+
+    def begin_commit(self) -> bool:
+        """Enter the commit boundary unless cancellation already won."""
+        self._lock.acquire()
+        if self._cancelled:
+            self._lock.release()
+            return False
+        self._commit_started = True
+        return True
+
+    def finish_commit(self) -> None:
+        """Leave a commit boundary entered by :meth:`begin_commit`."""
+        self._lock.release()
+
+
 def _lock_api_is_absent_on_session_db(lock_db: Any) -> bool:
     """Whether the live in-memory SessionDB class structurally predates locks.
 
@@ -216,6 +293,7 @@ def _refresh_persisted_compression_guards(compressor: Any) -> None:
     method_calls = (
         ("get_active_compression_failure_cooldown", {"refresh": True}),
         ("_load_fallback_compression_streak", {}),
+        ("_load_ineffective_compression_count", {}),
     )
     for method_name, kwargs in method_calls:
         method = getattr(type(compressor), method_name, None)
@@ -277,6 +355,24 @@ 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 _compression_lock_holder(agent: Any) -> str:
     """Build a unique holder id for the lock: pid:tid:agent-instance:uuid.
 
@@ -730,7 +826,11 @@ def replay_compression_warning(agent: Any) -> None:
             pass
 
 
-def conversation_history_after_compression(agent: Any, messages: list) -> Optional[list]:
+def conversation_history_after_compression(
+    agent: Any,
+    messages: list,
+    previous_history: Optional[list] = None,
+) -> Optional[list]:
     """Return the correct flush baseline after a compression boundary.
 
     Legacy compression rotates to a fresh child session. That child has not
@@ -747,7 +847,19 @@ def conversation_history_after_compression(agent: Any, messages: list) -> Option
 
     A shallow copy is intentional: it captures the current compacted dict
     identities as history while allowing later same-turn appends to remain new.
+
+    An aborted or no-op attempt after an earlier in-place compaction must retain
+    the pre-attempt baseline.  Treating all current messages as persisted would
+    drop any later, unflushed turns on restart; clearing the baseline would
+    append the already-persisted compacted rows a second time.
     """
+    if bool(getattr(agent, "_last_compression_attempt_recorded", False)):
+        attempt_in_place = getattr(agent, "_last_compression_attempt_in_place", None)
+        if attempt_in_place is True:
+            return list(messages)
+        if attempt_in_place is False:
+            return None
+        return previous_history
     if bool(getattr(agent, "_last_compaction_in_place", False)):
         return list(messages)
     return None
@@ -806,6 +918,37 @@ def _is_real_user_message(message: Any) -> bool:
     return not ContextCompressor._is_synthetic_compression_user_turn(message)
 
 
+def _strip_stale_todo_snapshot(content: Any) -> Any:
+    """Remove a previously merged todo-snapshot block from message content.
+
+    Snapshot merges (see the injection site in ``compress_context``) always
+    append the block at the end of the trailing user turn, so a surviving
+    header marks stale todo state from an earlier compaction boundary.
+    Stripping before re-injection keeps repeated boundaries from
+    accumulating outdated snapshots (#26981).
+    """
+    from tools.todo_tool import TODO_INJECTION_HEADER
+
+    if isinstance(content, str):
+        idx = content.find(TODO_INJECTION_HEADER)
+        if idx == -1:
+            return content
+        return content[:idx].rstrip()
+    if isinstance(content, list):
+        return [
+            part
+            for part in content
+            if not (
+                isinstance(part, dict)
+                and part.get("type") == "text"
+                and str(part.get("text") or "")
+                .lstrip()
+                .startswith(TODO_INJECTION_HEADER)
+            )
+        ]
+    return content
+
+
 def _merge_anchor_into_user_message(target: dict, anchor: dict) -> None:
     """Fold the human anchor into an existing user-role scaffolding turn.
 
@@ -975,6 +1118,7 @@ def compress_context(
     focus_topic: Optional[str] = None,
     force: bool = False,
     defer_context_engine_notification: bool = False,
+    commit_fence: Optional[CompressionCommitFence] = None,
 ) -> Tuple[list, str]:
     """Compress conversation context and split the session in SQLite.
 
@@ -994,6 +1138,9 @@ def compress_context(
             callers use the default ``False``.
         defer_context_engine_notification: Delay the existing context-engine
             hook until a manual host commits its outer history transaction.
+        commit_fence: Optional cooperative fence for executor callers that
+            may time out. It prevents a late worker from mutating session state
+            after its caller has moved on.
 
     Returns:
         ``(compressed_messages, new_system_prompt)`` tuple.  When
@@ -1008,6 +1155,21 @@ def compress_context(
     ):
         raise RuntimeError("a compression notification is already pending")
 
+    # ``conversation_history_after_compression()`` needs the latest attempt's
+    # outcome, while ``_last_compaction_in_place`` remains the run-level signal
+    # read by gateway callers. ``None`` means this attempt aborted or made no
+    # 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
     _trigger_source = "manual" if force else "auto"
@@ -1030,14 +1192,26 @@ def compress_context(
     # the app server does not expose its native summary prompt, so there is no
     # truthful injection point for ``on_pre_compress()`` return text here.
     if getattr(agent, "api_mode", None) == "codex_app_server":
-        return _compress_context_via_codex_app_server(
-            agent,
-            messages,
-            system_message,
-            approx_tokens=approx_tokens,
-            task_id=task_id,
-            force=force,
-        )
+        _codex_fence_entered = False
+        if commit_fence is not None:
+            _codex_fence_entered = commit_fence.begin_commit()
+            if not _codex_fence_entered:
+                existing_prompt = getattr(agent, "_cached_system_prompt", None)
+                if not existing_prompt:
+                    existing_prompt = agent._build_system_prompt(system_message)
+                return messages, existing_prompt
+        try:
+            return _compress_context_via_codex_app_server(
+                agent,
+                messages,
+                system_message,
+                approx_tokens=approx_tokens,
+                task_id=task_id,
+                force=force,
+            )
+        finally:
+            if _codex_fence_entered:
+                commit_fence.finish_commit()
 
     # Every automatic entrypoint must honor compressor-owned cooldown and
     # breaker state. Gateway hygiene constructs a fresh AIAgent, so the
@@ -1089,7 +1263,20 @@ def compress_context(
         f"{approx_tokens:,}" if approx_tokens else "unknown", agent.model,
         focus_topic,
     )
-    agent._emit_status(COMPACTION_STATUS)
+    _compaction_status = COMPACTION_STATUS
+    if not force:
+        _compaction_status = automatic_compaction_status_message(
+            agent.context_compressor,
+            phase="compress",
+            default_message=_compaction_status,
+            approx_tokens=approx_tokens,
+            message_count=_pre_msg_count,
+            model=agent.model,
+            focus_topic=focus_topic,
+        )
+    _compaction_status_emitted = bool(_compaction_status)
+    if _compaction_status:
+        agent._emit_status(_compaction_status)
     _compaction_done_emitted = False
 
     def _complete_compaction_lifecycle() -> None:
@@ -1097,7 +1284,11 @@ def compress_context(
         if _compaction_done_emitted:
             return
         _compaction_done_emitted = True
-        _emit_compaction_done(agent)
+        # A suppressed start (quiet context engine) opened no visible
+        # compaction phase — emit no terminal edge either. Failure warnings
+        # go through agent._emit_warning and are never suppressed here.
+        if _compaction_status_emitted:
+            _emit_compaction_done(agent)
 
     # ── Compression lock ────────────────────────────────────────────────
     # Atomic, state.db-backed lock per session_id.  Without this, two
@@ -1134,6 +1325,12 @@ def compress_context(
     _try_acquire_lock = None
     _lock_lookup_error: Optional[Exception] = None
     _legacy_session_db_without_lock_api = False
+    # Clear any stale lock-skip signal from a prior call so this call's
+    # outcome alone determines what callers see.  Without this an
+    # auto-compress lock-skip followed by a successful manual /compress
+    # would falsely report "Compression already in progress" and discard
+    # the compression results.
+    agent._compression_skipped_due_to_lock = None
     if _lock_db is not None:
         try:
             _legacy_session_db_without_lock_api = _lock_api_is_absent_on_session_db(
@@ -1221,6 +1418,11 @@ def compress_context(
                 _lock_sid, existing,
             )
             _lock_holder = None  # don't release a lock we don't own
+            # Signal to callers that this no-op is due to a concurrent lock,
+            # not a genuine "nothing to compress" or aux-model failure.
+            # Manual /compress callers can surface a clear status message
+            # instead of the misleading "No changes from compression" text.
+            agent._compression_skipped_due_to_lock = existing or True
             # Surface to the user once — quiet for downstream auto-compress loops
             if getattr(agent, "_last_compression_lock_warning_sid", None) != _lock_sid:
                 agent._last_compression_lock_warning_sid = _lock_sid
@@ -1394,6 +1596,7 @@ def compress_context(
         if _activity_heartbeat is not None:
             _activity_heartbeat.stop("context compression completed")
 
+    _commit_fence_entered = False
     try:
         # Capture boundary quality before session-rotation callbacks run. Built-in
         # and plugin lifecycle hooks may reset per-session compressor fields while
@@ -1481,6 +1684,28 @@ def compress_context(
             _release_lock()
             return messages, _existing_sp
 
+        if commit_fence is not None:
+            _commit_fence_entered = commit_fence.begin_commit()
+            if not _commit_fence_entered:
+                logger.info(
+                    "Compression commit cancelled before session mutation "
+                    "(session=%s).",
+                    agent.session_id or "none",
+                )
+                agent._last_compaction_in_place = False
+                _existing_sp = getattr(agent, "_cached_system_prompt", None)
+                if not _existing_sp:
+                    _existing_sp = agent._build_system_prompt(system_message)
+                _emit_compression_attempt_telemetry(
+                    agent,
+                    started_at=_attempt_started_at,
+                    commit_status="aborted",
+                    split_status="aborted",
+                    failure_class="commit_fence_cancelled",
+                )
+                _release_lock()
+                return messages, _existing_sp
+
         summary_error = getattr(agent.context_compressor, "_last_summary_error", None)
         if summary_error:
             if getattr(agent, "_last_compression_summary_warning", None) != summary_error:
@@ -1509,11 +1734,54 @@ def compress_context(
 
         todo_snapshot = agent._todo_store.format_for_injection()
         if todo_snapshot:
-            compressed.append({
-                "role": "user",
-                "content": todo_snapshot,
-                "_todo_snapshot_synthetic": True,
-            })
+            # Fold the snapshot into a trailing REAL user message so
+            # compression never introduces a synthetic user/user pair. Any
+            # snapshot merged at an earlier boundary is stripped first so
+            # repeated compactions refresh rather than accumulate todo state
+            # (#26981). Scaffolding tails (continuation marker, summary
+            # handoff, a bare stale snapshot row) must never absorb the
+            # snapshot: merging would upgrade them to "real user" evidence
+            # and break zero-user provenance (#69292), so those keep the
+            # flagged standalone append and the real-user preservation pass
+            # continues to see todo scaffolding, not human intent.
+            from agent.context_compressor import _append_text_to_content
+
+            merged = False
+            _tail = (
+                compressed[-1]
+                if compressed and isinstance(compressed[-1], dict)
+                else None
+            )
+            if _tail is not None and _tail.get("role") == "user":
+                _stripped = _strip_stale_todo_snapshot(_tail.get("content"))
+                _probe = {
+                    key: value for key, value in _tail.items() if key != "content"
+                }
+                _probe["content"] = _stripped
+                if _is_real_user_message(_probe):
+                    _snapshot_text = (
+                        f"\n\n{todo_snapshot}"
+                        if isinstance(_stripped, str) and _stripped
+                        else todo_snapshot
+                    )
+                    _tail["content"] = _append_text_to_content(
+                        _stripped, _snapshot_text
+                    )
+                    merged = True
+                elif _stripped != _tail.get("content") and not _message_text(
+                    {"role": "user", "content": _stripped}
+                ).strip():
+                    # The tail was nothing but an earlier snapshot row —
+                    # refresh it in place instead of stacking a duplicate.
+                    _tail["content"] = todo_snapshot
+                    _tail["_todo_snapshot_synthetic"] = True
+                    merged = True
+            if not merged:
+                compressed.append({
+                    "role": "user",
+                    "content": todo_snapshot,
+                    "_todo_snapshot_synthetic": True,
+                })
         _ensure_compressed_has_user_turn(messages, compressed)
 
         cached_system_prompt = agent._cached_system_prompt
@@ -1823,6 +2091,7 @@ def compress_context(
         # via a rotation-independent flag. The gateway uses this — NOT an
         # id-change diff — to re-baseline transcript handling (history_offset=0 +
         # rewrite on the same id) when compaction happened in place. See #38763.
+        agent._last_compression_attempt_in_place = compacted_in_place
         agent._last_compaction_in_place = compacted_in_place
 
         # Keep the post-compression rough estimate for diagnostics, but do not
@@ -1888,7 +2157,11 @@ def compress_context(
         # file dedup) ran. A concurrent path that wakes up the moment we
         # release will see the NEW session_id in state.db / SessionEntry and
         # acquire on that — no race against our just-finished work.
-        _release_lock()
+        try:
+            _release_lock()
+        finally:
+            if _commit_fence_entered:
+                commit_fence.finish_commit()
 
 
 def _compress_context_via_codex_app_server(

agent/conversation_loop.py

@@ -34,8 +34,10 @@ 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
 from agent.display import KawaiiSpinner
 from agent.error_classifier import FailoverReason, classify_api_error
 from agent.iteration_budget import IterationBudget
@@ -639,6 +641,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.
 
@@ -665,6 +716,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,
@@ -710,6 +891,13 @@ def run_conversation(
         except Exception:
             pass
 
+    # The gateway caches agents across user turns.  Compression state is
+    # per-turn: carrying a prior in-place boundary forward would make a later
+    # uncompressed result look like a compacted transcript to gateway writers.
+    agent._last_compaction_in_place = False
+    agent._last_compression_attempt_recorded = False
+    agent._last_compression_attempt_in_place = None
+
     # ── Per-turn setup (the prologue) ──
     # All once-per-turn setup — stdio guarding, retry-counter resets, user
     # message sanitization, todo/nudge hydration, system-prompt restore-or-
@@ -797,6 +985,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.
@@ -981,6 +1176,13 @@ def run_conversation(
             # outgoing copy.
             _api_content = api_msg.pop("api_content", None)
 
+            # Display-only timeline metadata. Never a provider field — strip
+            # from every outgoing copy so strict OpenAI-compatible backends
+            # don't reject the request after a model switch or resumed typed
+            # event row enters the live history.
+            api_msg.pop("display_kind", None)
+            api_msg.pop("display_metadata", None)
+
             # Inject ephemeral context into the current turn's user message.
             # Sources: memory manager prefetch + plugin pre_llm_call hooks
             # with target="user_message" (the default).  Both are
@@ -1038,7 +1240,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)
@@ -1084,7 +1307,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):
@@ -1111,6 +1345,26 @@ def run_conversation(
             for idx, pfm in enumerate(agent.prefill_messages):
                 api_messages.insert(sys_offset + idx, pfm.copy())
 
+        # 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,
+        )
+
         # 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,
@@ -1300,6 +1554,15 @@ def run_conversation(
             if _moa_prepared_request is not None:
                 pending_moa_prepared_request = _moa_prepared_request
             compression_attempts += 1
+            # Compression is actually running (block cleared / was never
+            # blocked) — reset the blocked-overflow warning dedup so a future
+            # blocked-over-threshold turn can warn again. Mirrors the
+            # turn-context preflight reset (silent-overflow fix #62625).
+            # getattr guard: test doubles built via object.__new__ lack the
+            # method (gateway test-double pitfall) — treat absence as no-op.
+            _clear_warn = getattr(agent, "_clear_context_overflow_warn", None)
+            if callable(_clear_warn):
+                _clear_warn()
             logger.info(
                 "Pre-API compression: ~%s request tokens >= %s threshold "
                 "(context=%s, attempt=%s/%s)",
@@ -1310,42 +1573,98 @@ def run_conversation(
                 compression_attempts,
                 max_compression_attempts,
             )
-            agent._emit_status(
-                PRE_API_COMPRESSION_STATUS_TEMPLATE.format(
+            _pre_api_status = automatic_compaction_status_message(
+                _compressor,
+                phase="pre_api",
+                default_message=PRE_API_COMPRESSION_STATUS_TEMPLATE.format(
                     tokens=request_pressure_tokens
-                )
+                ),
+                approx_tokens=request_pressure_tokens,
+                threshold_tokens=int(
+                    getattr(_compressor, "threshold_tokens", 0) or 0
+                ),
+                context_length=int(
+                    getattr(_compressor, "context_length", 0) or 0
+                ),
+                model=agent.model,
+                attempt=compression_attempts,
+                max_attempts=max_compression_attempts,
             )
+            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
-            )
-            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
+            and compression_attempts < max_compression_attempts
+            and not _defer_preflight(request_pressure_tokens)
+            and _compression_cooldown
+        ):
+            # Blocked by the summary-LLM cooldown. Surface a deduped warning
+            # (only when actually over threshold — should_compress_info
+            # returns a None reason below threshold) so the user isn't left
+            # with a silently growing context. Mirrors the turn-context
+            # preflight and the loop-compaction guards (silent-overflow fix
+            # #62625).
+            _block_reason = None
+            try:
+                _block_reason = _compressor.should_compress_info(
+                    request_pressure_tokens
+                )[1]
+            except Exception:
+                _block_reason = None
+            if _block_reason:
+                agent._warn_context_overflow_blocked(
+                    _block_reason,
+                    request_pressure_tokens,
+                    int(getattr(_compressor, "threshold_tokens", 0) or 0),
+                )
         
         # Thinking spinner for quiet mode (animated during API call)
         thinking_spinner = None
@@ -1935,6 +2254,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)
@@ -2343,13 +2664,17 @@ def run_conversation(
                                     force=True,
                                 )
                             agent._cleanup_task_resources(effective_task_id)
-                            agent._persist_session(messages, conversation_history)
                             _final_response = (
                                 "Stream repeatedly dropped mid tool-call (network); "
                                 "the tool was not executed"
                                 if _is_stub_stall
                                 else "Response truncated due to output length limit"
                             )
+                            # Prior successful tool batches (or injected tool
+                            # errors) can leave a tool-result tail; this path
+                            # never reaches finalize_turn (#48879 class).
+                            close_interrupted_tool_sequence(messages, _final_response)
+                            agent._persist_session(messages, conversation_history)
                             return {
                                 "final_response": _final_response,
                                 "messages": messages,
@@ -2452,6 +2777,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",
@@ -3523,7 +3856,7 @@ def run_conversation(
                             task_id=effective_task_id,
                         )
                         conversation_history = conversation_history_after_compression(
-                            agent, messages
+                            agent, messages, conversation_history
                         )
                         if len(messages) < original_len or old_ctx > _reduced_ctx:
                             agent._buffer_status(
@@ -3773,12 +4106,25 @@ 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
+                        agent, messages, conversation_history
                     )
 
                     # Re-estimate tokens after compression.  Same-message-count
@@ -4014,12 +4360,25 @@ 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
+                        agent, messages, conversation_history
                     )
 
                     # Re-estimate tokens after compression.  Same-message-count
@@ -5022,8 +5381,13 @@ def run_conversation(
                         agent._flush_status_buffer()
                         agent._vprint(f"{agent.log_prefix}❌ Max retries (3) for invalid tool calls exceeded. Stopping as partial.", force=True)
                         agent._invalid_tool_retries = 0
-                        agent._persist_session(messages, conversation_history)
                         _final_response = f"Model generated invalid tool call: {invalid_preview}"
+                        # Prior <3 retries (or an earlier successful tool batch)
+                        # leave a tool-result tail. Closing it here matches
+                        # interrupt aborts (#48879 / #52592) so the next user
+                        # turn is not tool→user for strict providers.
+                        close_interrupted_tool_sequence(messages, _final_response)
+                        agent._persist_session(messages, conversation_history)
                         return {
                             "final_response": _final_response,
                             "messages": messages,
@@ -5103,14 +5467,18 @@ def run_conversation(
                         )
                         agent._invalid_json_retries = 0
                         agent._cleanup_task_resources(effective_task_id)
+                        _final_response = "Response truncated due to output length limit"
+                        # Same tool-tail close as interrupt / invalid-tool
+                        # exhaustion — this path never reaches finalize_turn.
+                        close_interrupted_tool_sequence(messages, _final_response)
                         agent._persist_session(messages, conversation_history)
                         return {
-                            "final_response": "Response truncated due to output length limit",
+                            "final_response": _final_response,
                             "messages": messages,
                             "api_calls": api_call_count,
                             "completed": False,
                             "partial": True,
-                            "error": "Response truncated due to output length limit",
+                            "error": _final_response,
                         }
 
                     # Track retries for invalid JSON arguments
@@ -5401,15 +5769,98 @@ def run_conversation(
                     and _compressor.should_compress(_real_tokens)
                 ):
                     compression_attempts += 1
+                    # Compression is actually running (block cleared / was
+                    # never blocked) — reset the blocked-overflow warning
+                    # dedup so a future blocked-over-threshold turn can warn
+                    # again (silent-overflow fix #62625).
+                    # getattr guard: test doubles built via object.__new__ lack the
+                    # method (gateway test-double pitfall) — treat absence as no-op.
+                    _clear_warn = getattr(agent, "_clear_context_overflow_warn", None)
+                    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
-                    )
+                    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
+                    # the user isn't left with a silently growing context that
+                    # eventually hits the hard provider limit. Mirrors the
+                    # turn-context preflight guard (silent-overflow fix #62625).
+                    _block_reason = None
+                    _info = getattr(_compressor, "should_compress_info", None)
+                    if _info is not None:
+                        try:
+                            _block_reason = _info(_real_tokens)[1]
+                        except Exception:
+                            _block_reason = None
+                    if _block_reason:
+                        agent._warn_context_overflow_blocked(
+                            _block_reason,
+                            _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

agent/copilot_acp_client.py

@@ -503,6 +503,10 @@ class CopilotACPClient:
 
     def _run_prompt(self, prompt_text: str, *, timeout_seconds: float) -> tuple[str, str]:
         try:
+            # Hide the console the CLI child would otherwise flash on Windows
+            # (#56747). Hide-only — stdio pipes stay intact for the ACP wire.
+            from hermes_cli._subprocess_compat import windows_hide_flags
+
             proc = subprocess.Popen(
                 [self._acp_command] + self._acp_args,
                 stdin=subprocess.PIPE,
@@ -512,6 +516,7 @@ class CopilotACPClient:
                 bufsize=1,
                 cwd=self._acp_cwd,
                 env=_build_subprocess_env(),
+                creationflags=windows_hide_flags(),
             )
         except FileNotFoundError as exc:
             raise RuntimeError(

agent/credential_pool.py

@@ -596,20 +596,32 @@ class CredentialPool:
         self._last_no_entries_log_at: Optional[float] = None
 
     def has_credentials(self) -> bool:
-        return bool(self._entries)
+        with self._lock:
+            return bool(self._entries)
 
     def has_available(self) -> bool:
         """True if at least one entry is not currently in exhaustion cooldown."""
-        return bool(self._available_entries())
+        # ``_available_entries`` is not read-only: it prunes aged-out DEAD
+        # manual entries (rebinding ``self._entries``) and persists.  It must
+        # run under ``self._lock`` like every other caller (``select`` etc.),
+        # otherwise a status probe here can race a concurrent ``select`` /
+        # rotation and tear ``self._entries`` or double-write auth.json.
+        with self._lock:
+            return bool(self._available_entries())
 
     def entries(self) -> List[PooledCredential]:
-        return list(self._entries)
+        with self._lock:
+            return list(self._entries)
 
-    def current(self) -> Optional[PooledCredential]:
+    def _current_unlocked(self) -> Optional[PooledCredential]:
         if not self._current_id:
             return None
         return next((entry for entry in self._entries if entry.id == self._current_id), None)
 
+    def current(self) -> Optional[PooledCredential]:
+        with self._lock:
+            return self._current_unlocked()
+
     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):
@@ -652,6 +664,8 @@ class CredentialPool:
         entry: PooledCredential,
         status_code: Optional[int],
         error_context: Optional[Dict[str, Any]] = None,
+        *,
+        persist: bool = True,
     ) -> PooledCredential:
         normalized_error = _normalize_error_context(error_context)
         # Permanent OAuth failures (token_invalidated, token_revoked, etc.)
@@ -675,7 +689,8 @@ class CredentialPool:
             last_error_reset_at=normalized_error.get("reset_at"),
         )
         self._replace_entry(entry, updated)
-        self._persist()
+        if persist:
+            self._persist()
         return updated
 
     def _sync_anthropic_entry_from_credentials_file(self, entry: PooledCredential) -> PooledCredential:
@@ -1726,18 +1741,21 @@ class CredentialPool:
             self._entries = [replace(candidate, priority=idx) for idx, candidate in enumerate(rotated)]
             self._persist()
             self._current_id = entry.id
-            return self.current() or entry
+            return self._current_unlocked() or entry
 
         entry = available[0]
         self._current_id = entry.id
         return entry
 
     def peek(self) -> Optional[PooledCredential]:
-        current = self.current()
-        if current is not None:
-            return current
-        available = self._available_entries()
-        return available[0] if available else None
+        # Single lock acquisition for the whole read; call the unlocked
+        # helpers so we don't re-enter the non-reentrant ``self._lock``.
+        with self._lock:
+            current = self._current_unlocked()
+            if current is not None:
+                return current
+            available = self._available_entries()
+            return available[0] if available else None
 
     def mark_exhausted_and_rotate(
         self,
@@ -1757,12 +1775,49 @@ 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",
+                        self.provider,
+                    )
+                    self._current_id = None
+                    return self._select_unlocked()
             if entry is None:
-                entry = self.current() or self._select_unlocked()
+                entry = self._current_unlocked() or self._select_unlocked()
             if entry is None:
                 return None
             _label = entry.label or entry.id[:8]
             self._mark_exhausted(entry, status_code, error_context)
+            # A 402/429/401 is an API-key–level failure: the account is out of
+            # balance, rate-limited, or its key is rejected.  The same key can
+            # back more than one pool entry (e.g. an explicit pool entry plus a
+            # ``model_config`` entry auto-seeded from ``model.api_key`` — both
+            # carry the identical ``runtime_api_key``).  Marking only the first
+            # match leaves the sibling entries OK, so ``_select_unlocked()``
+            # keeps handing back the same depleted key and rotation never
+            # converges — the caller ``continue``s forever until the client
+            # 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:
+                siblings_marked = False
+                for sibling in self._entries:
+                    if sibling.id == entry.id:
+                        continue
+                    if sibling.runtime_api_key == api_key_hint:
+                        self._mark_exhausted(
+                            sibling, status_code, error_context, persist=False
+                        )
+                        siblings_marked = True
+                if siblings_marked:
+                    self._persist()
             # Re-read the updated entry to log the correct terminal state.
             updated_entry = next(
                 (e for e in self._entries if e.id == entry.id), entry,
@@ -1852,14 +1907,14 @@ class CredentialPool:
                     None,
                 )
             else:
-                entry = self.current() or self._select_unlocked(refresh=False)
+                entry = self._current_unlocked() or self._select_unlocked(refresh=False)
             if entry is None:
                 return None
             self._current_id = entry.id
             return self._try_refresh_current_unlocked()
 
     def _try_refresh_current_unlocked(self) -> Optional[PooledCredential]:
-        entry = self.current()
+        entry = self._current_unlocked()
         if entry is None:
             return None
         refreshed = self._refresh_entry(entry, force=True)
@@ -1868,76 +1923,80 @@ class CredentialPool:
         return refreshed
 
     def reset_statuses(self) -> int:
-        count = 0
-        new_entries = []
-        for entry in self._entries:
-            if entry.last_status or entry.last_status_at or entry.last_error_code:
-                new_entries.append(
-                    replace(
-                        entry,
-                        last_status=None,
-                        last_status_at=None,
-                        last_error_code=None,
-                        last_error_reason=None,
-                        last_error_message=None,
-                        last_error_reset_at=None,
+        with self._lock:
+            count = 0
+            new_entries = []
+            for entry in self._entries:
+                if entry.last_status or entry.last_status_at or entry.last_error_code:
+                    new_entries.append(
+                        replace(
+                            entry,
+                            last_status=None,
+                            last_status_at=None,
+                            last_error_code=None,
+                            last_error_reason=None,
+                            last_error_message=None,
+                            last_error_reset_at=None,
+                        )
                     )
-                )
-                count += 1
-            else:
-                new_entries.append(entry)
-        if count:
-            self._entries = new_entries
-            self._persist()
-        return count
+                    count += 1
+                else:
+                    new_entries.append(entry)
+            if count:
+                self._entries = new_entries
+                self._persist()
+            return count
 
     def remove_index(self, index: int) -> Optional[PooledCredential]:
-        if index < 1 or index > len(self._entries):
-            return None
-        removed = self._entries.pop(index - 1)
-        self._entries = [
-            replace(entry, priority=new_priority)
-            for new_priority, entry in enumerate(self._entries)
-        ]
-        write_credential_pool(
-            self.provider,
-            [entry.to_dict() for entry in self._entries],
-            removed_ids=[removed.id],
-        )
-        if self._current_id == removed.id:
-            self._current_id = None
-        return removed
+        with self._lock:
+            if index < 1 or index > len(self._entries):
+                return None
+            removed = self._entries.pop(index - 1)
+            self._entries = [
+                replace(entry, priority=new_priority)
+                for new_priority, entry in enumerate(self._entries)
+            ]
+            write_credential_pool(
+                self.provider,
+                [entry.to_dict() for entry in self._entries],
+                removed_ids=[removed.id],
+            )
+            if self._current_id == removed.id:
+                self._current_id = None
+            return removed
 
     def resolve_target(self, target: Any) -> Tuple[Optional[int], Optional[PooledCredential], Optional[str]]:
         raw = str(target or "").strip()
         if not raw:
             return None, None, "No credential target provided."
 
-        for idx, entry in enumerate(self._entries, start=1):
-            if entry.id == raw:
-                return idx, entry, None
+        with self._lock:
+            for idx, entry in enumerate(self._entries, start=1):
+                if entry.id == raw:
+                    return idx, entry, None
 
-        label_matches = [
-            (idx, entry)
-            for idx, entry in enumerate(self._entries, start=1)
-            if entry.label.strip().lower() == raw.lower()
-        ]
-        if len(label_matches) == 1:
-            return label_matches[0][0], label_matches[0][1], None
-        if len(label_matches) > 1:
-            return None, None, f'Ambiguous credential label "{raw}". Use the numeric index or entry id instead.'
-        if raw.isdigit():
-            index = int(raw)
-            if 1 <= index <= len(self._entries):
-                return index, self._entries[index - 1], None
-            return None, None, f"No credential #{index}."
-        return None, None, f'No credential matching "{raw}".'
+            label_matches = [
+                (idx, entry)
+                for idx, entry in enumerate(self._entries, start=1)
+                if entry.label.strip().lower() == raw.lower()
+            ]
+            if len(label_matches) == 1:
+                return label_matches[0][0], label_matches[0][1], None
+            if len(label_matches) > 1:
+                return None, None, f'Ambiguous credential label "{raw}". Use the numeric index or entry id instead.'
+            if raw.isdigit():
+                index = int(raw)
+                if 1 <= index <= len(self._entries):
+                    return index, self._entries[index - 1], None
+                return None, None, f"No credential #{index}."
+            return None, None, f'No credential matching "{raw}".'
 
     def add_entry(self, entry: PooledCredential) -> PooledCredential:
-        entry = replace(entry, priority=_next_priority(self._entries))
-        self._entries.append(entry)
-        self._persist()
-        return entry
+        with self._lock:
+            entry = replace(entry, priority=_next_priority(self._entries))
+            self._entries.append(entry)
+            self._persist()
+            return entry
 
 
 def _upsert_entry(entries: List[PooledCredential], provider: str, source: str, payload: Dict[str, Any]) -> bool:

agent/curator.py

@@ -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 "

agent/delegation_context.py

@@ -0,0 +1,85 @@
+"""Context-local state for delegate_task child execution.
+
+The parent Hermes process may itself be a Kanban dispatcher worker with
+HERMES_KANBAN_* variables in process env. delegate_task children run inside the
+same Python process, but they are not dispatcher-owned Kanban workers. This
+module lets code paths that resolve tool schemas or spawn subprocesses fail
+closed for delegated children without mutating global os.environ for the parent.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Iterator, Mapping, MutableMapping
+
+_DELEGATED_CHILD_CONTEXT: ContextVar[bool] = ContextVar(
+    "hermes_delegated_child_context",
+    default=False,
+)
+
+DELEGATED_CHILD_ENV_MARKER = "HERMES_DELEGATED_CHILD_CONTEXT"
+
+KANBAN_ENV_KEYS: tuple[str, ...] = (
+    "HERMES_KANBAN_TASK",
+    "HERMES_KANBAN_RUN_ID",
+    "HERMES_KANBAN_WORKSPACE",
+    "HERMES_KANBAN_WORKSPACES_ROOT",
+    "HERMES_KANBAN_CLAIM_LOCK",
+    "HERMES_KANBAN_BOARD",
+    "HERMES_KANBAN_DB",
+)
+
+
+@contextmanager
+def delegated_child_context() -> Iterator[None]:
+    """Mark the current execution context as a delegate_task child."""
+    token = _DELEGATED_CHILD_CONTEXT.set(True)
+    try:
+        yield
+    finally:
+        _DELEGATED_CHILD_CONTEXT.reset(token)
+
+
+def is_delegated_child_context() -> bool:
+    """Return True while code is running for a delegate_task child."""
+    return bool(_DELEGATED_CHILD_CONTEXT.get())
+
+
+def is_delegated_child_process_context() -> bool:
+    """Return True in this process or a subprocess spawned by a child."""
+    import os
+
+    return bool(_DELEGATED_CHILD_CONTEXT.get()) or bool(
+        os.environ.get(DELEGATED_CHILD_ENV_MARKER)
+    )
+
+
+def scrub_kanban_env(env: Mapping[str, str] | MutableMapping[str, str]) -> dict[str, str]:
+    """Return *env* with dispatcher-only Kanban variables removed."""
+    cleaned = dict(env)
+    for key in KANBAN_ENV_KEYS:
+        cleaned.pop(key, None)
+    cleaned[DELEGATED_CHILD_ENV_MARKER] = "1"
+    return cleaned
+
+
+def delegated_child_subprocess_env(
+    env: Mapping[str, str] | MutableMapping[str, str] | None = None,
+) -> dict[str, str] | None:
+    """Return an env override only when delegated-child lineage must cross fork.
+
+    Most subprocess call sites historically used ``env=None`` to inherit the
+    process environment.  In a ``delegate_task`` child, inheriting as-is leaks
+    parent dispatcher ``HERMES_KANBAN_*`` vars while losing the ContextVar in
+    the new process.  This helper preserves normal ``env=None`` semantics for
+    non-delegated calls, and only materializes a scrubbed env when the lineage
+    marker must be propagated across a child-process boundary.
+    """
+    if not is_delegated_child_process_context():
+        return None if env is None else dict(env)
+
+    if env is None:
+        import os
+
+        env = os.environ
+    return scrub_kanban_env(env)

agent/error_classifier.py

@@ -413,6 +413,7 @@ _CONTENT_POLICY_BLOCKED_PATTERNS = [
 _AUTH_PATTERNS = [
     "invalid api key",
     "invalid_api_key",
+    "gateway_auth_failed",
     "authentication",
     "unauthorized",
     "forbidden",

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
 
 

agent/image_routing.py

@@ -181,6 +181,8 @@ def _supports_vision_override(
     cfg: Optional[Dict[str, Any]],
     provider: str,
     model: str,
+    *,
+    requested_provider: str = "",
 ) -> Optional[bool]:
     """Resolve user-declared vision capability from config.yaml.
 
@@ -188,9 +190,14 @@ def _supports_vision_override(
       1. ``model.supports_vision`` (top-level shortcut for the active model)
       2. ``providers.<provider>.models.<model>.supports_vision``
          (named custom providers — ``provider`` may be the runtime-resolved
-         value ``"custom"`` and/or the user-declared name under
-         ``model.provider``; both are tried. For ``custom:<name>`` syntax,
-         the stripped ``<name>`` is also tried as a provider key.)
+         value ``"custom"``, the runtime's originally requested provider,
+         and/or the user-declared name under ``model.provider``; all are
+         tried. For ``custom:<name>`` syntax, the stripped ``<name>`` is also
+         tried as a provider key.)
+      2b. ``custom_providers`` (legacy list form) ``.models.<model>``
+
+    Under (2) and (2b), the per-model capability key may be written as
+    either ``supports_vision`` or the shorter ``vision`` alias; both work.
 
     Returns None when no override is set, so the caller falls through to
     models.dev. Returns False explicitly only when the user wrote a
@@ -214,7 +221,7 @@ def _supports_vision_override(
     # "custom:<name>" form while providers: is keyed by bare <name>.
     config_provider = str(model_cfg.get("provider") or "").strip()
     provider_candidates: List[str] = []
-    for candidate in (provider, config_provider):
+    for candidate in (requested_provider, provider, config_provider):
         if not candidate:
             continue
         provider_candidates.append(candidate)
@@ -231,7 +238,9 @@ def _supports_vision_override(
         models_cfg: Dict[str, Any] = models_raw if isinstance(models_raw, dict) else {}
         per_model_raw = models_cfg.get(model)
         per_model: Dict[str, Any] = per_model_raw if isinstance(per_model_raw, dict) else {}
-        coerced = _coerce_capability_bool(per_model.get("supports_vision"))
+        coerced = _coerce_capability_bool(
+            per_model.get("supports_vision", per_model.get("vision"))
+        )
         if coerced is not None:
             return coerced
 
@@ -240,28 +249,26 @@ def _supports_vision_override(
     # may appear as the raw name or "custom:<name>" at runtime).
     custom_providers = cfg.get("custom_providers")
     if isinstance(custom_providers, list):
-        # Build candidate names: the provider value and the config provider
-        # value, both raw and with "custom:" prefix stripped/added.
-        candidate_names: set = set()
-        for p in filter(None, (provider, config_provider)):
-            candidate_names.add(p)
-            if p.startswith("custom:"):
-                candidate_names.add(p[len("custom:"):])
-            else:
-                candidate_names.add(f"custom:{p}")
-        for entry_raw in custom_providers:
-            if not isinstance(entry_raw, dict):
-                continue
-            entry_name = str(entry_raw.get("name") or "").strip()
-            if entry_name not in candidate_names:
-                continue
-            models_raw = entry_raw.get("models")
-            models_cfg = models_raw if isinstance(models_raw, dict) else {}
-            per_model_raw = models_cfg.get(model)
-            per_model = per_model_raw if isinstance(per_model_raw, dict) else {}
-            coerced = _coerce_capability_bool(per_model.get("supports_vision"))
-            if coerced is not None:
-                return coerced
+        # Candidate priority matters when the CLI-selected provider differs
+        # from model.provider. Walk identities first, then config entries, so
+        # list order cannot let the persisted default shadow the live route.
+        for candidate in dict.fromkeys(provider_candidates):
+            candidate_name = candidate.strip().lower()
+            for entry_raw in custom_providers:
+                if not isinstance(entry_raw, dict):
+                    continue
+                entry_name = str(entry_raw.get("name") or "").strip().lower()
+                if entry_name != candidate_name:
+                    continue
+                models_raw = entry_raw.get("models")
+                models_cfg = models_raw if isinstance(models_raw, dict) else {}
+                per_model_raw = models_cfg.get(model)
+                per_model = per_model_raw if isinstance(per_model_raw, dict) else {}
+                coerced = _coerce_capability_bool(
+                    per_model.get("supports_vision", per_model.get("vision"))
+                )
+                if coerced is not None:
+                    return coerced
 
     return None
 
@@ -381,6 +388,8 @@ def _lookup_supports_vision(
     provider: str,
     model: str,
     cfg: Optional[Dict[str, Any]] = None,
+    *,
+    requested_provider: str = "",
 ) -> Optional[bool]:
     """Return True/False if we can resolve caps, None if unknown.
 
@@ -388,7 +397,34 @@ def _lookup_supports_vision(
     (so custom/local models declared as vision-capable don't fall through to
     text routing in ``auto`` mode), then falls back to models.dev.
     """
-    override = _supports_vision_override(cfg, provider, model)
+    # Named custom providers are canonicalized to ``provider="custom"`` by
+    # runtime resolution.  The original CLI/config name is carried in the
+    # context-local main runtime so capability lookup can still select the
+    # exact custom_providers entry.  Require an exact provider+model match:
+    # background/auxiliary lookups must never borrow another turn's identity.
+    if not requested_provider:
+        try:
+            from agent.auxiliary_client import _runtime_main_value
+
+            runtime_provider = str(
+                _runtime_main_value("provider") or ""
+            ).strip().lower()
+            runtime_model = str(_runtime_main_value("model") or "").strip()
+            lookup_provider = str(provider or "").strip().lower()
+            lookup_model = str(model or "").strip()
+            if runtime_provider == lookup_provider and runtime_model == lookup_model:
+                requested_provider = str(
+                    _runtime_main_value("requested_provider") or ""
+                ).strip()
+        except Exception:
+            pass
+
+    override = _supports_vision_override(
+        cfg,
+        provider,
+        model,
+        requested_provider=requested_provider,
+    )
     if override is not None:
         return override
     if not provider or not model:
@@ -426,6 +462,8 @@ def decide_image_input_mode(
     provider: str,
     model: str,
     cfg: Optional[Dict[str, Any]],
+    *,
+    requested_provider: str = "",
 ) -> str:
     """Return ``"native"`` or ``"text"`` for the given turn.
 
@@ -433,6 +471,7 @@ def decide_image_input_mode(
       provider: active inference provider ID (e.g. ``"anthropic"``, ``"openrouter"``).
       model:    active model slug as it would be sent to the provider.
       cfg:      loaded config.yaml dict, or None. When None, behaves as auto.
+      requested_provider: provider identity before runtime canonicalization.
     """
     mode_cfg = "auto"
     if isinstance(cfg, dict):
@@ -449,7 +488,17 @@ def decide_image_input_mode(
     # explicit auxiliary.vision config acts as a *fallback* for text-only
     # main models — it should not preempt native vision on a model that
     # can natively inspect the pixels (issue #29135).
-    supports = _lookup_supports_vision(provider, model, cfg)
+    if requested_provider:
+        supports = _lookup_supports_vision(
+            provider,
+            model,
+            cfg,
+            requested_provider=requested_provider,
+        )
+    else:
+        # Keep the long-standing three-argument call contract for callers and
+        # tests that replace the capability lookup hook.
+        supports = _lookup_supports_vision(provider, model, cfg)
     if supports is True:
         return "native"
     if _explicit_aux_vision_override(cfg):

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(

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
@@ -268,6 +270,7 @@ def _install_npm(
             text=True,
             timeout=300,
             stdin=subprocess.DEVNULL,
+            creationflags=windows_hide_flags(),
         )
         if proc.returncode != 0:
             logger.warning(
@@ -317,6 +320,7 @@ def _install_go(pkg: str, bin_name: str) -> Optional[str]:
             timeout=600,
             env=env,
             stdin=subprocess.DEVNULL,
+            creationflags=windows_hide_flags(),
         )
         if proc.returncode != 0:
             logger.warning(

agent/manual_compression_feedback.py

@@ -7,6 +7,36 @@ from typing import Any, Sequence
 from agent.redact import redact_sensitive_text
 
 
+def describe_compression_lock_skip(lock_signal: Any) -> str:
+    """User-facing text for a manual /compress skipped by the compression lock.
+
+    ``lock_signal`` is ``agent._compression_skipped_due_to_lock`` (or the
+    ``holder`` carried by the TUI's ``CompressionLockHeld``): a descriptive
+    holder string when another compressor CONFIRMED holds the lock, or
+    ``True``/``None`` when acquisition failed without a confirmed holder
+    (``hermes_state.try_acquire_compression_lock`` catches ``sqlite3.Error``
+    internally and returns ``False``, so a failed acquire is NOT proof that
+    another compression is running). The two cases must be worded
+    differently: claiming "already in progress" on an unconfirmed failure
+    misdirects the user when the real problem is a broken lock subsystem.
+    """
+    holder = (
+        lock_signal
+        if isinstance(lock_signal, str) and lock_signal.strip()
+        else None
+    )
+    if holder:
+        return (
+            f"⏳ Compression already in progress for this session "
+            f"(holder: {holder}). Please wait for it to finish."
+        )
+    return (
+        "⏳ Compression skipped: could not acquire this session's "
+        "compression lock. Another compression may still be running, or "
+        "the lock check failed — try again shortly."
+    )
+
+
 def summarize_manual_compression(
     before_messages: Sequence[dict[str, Any]],
     after_messages: Sequence[dict[str, Any]],

agent/model_metadata.py

@@ -2201,11 +2201,18 @@ def get_model_context_length(
     # acting context, so they're ignored here.
     if (provider or "").strip().lower() == "moa":
         try:
-            from hermes_cli.config import load_config
+            from hermes_cli.config import (
+                get_compatible_custom_providers,
+                load_config,
+            )
             from hermes_cli.moa_config import resolve_moa_preset
             from hermes_cli.runtime_provider import resolve_runtime_provider
 
-            preset = resolve_moa_preset(load_config().get("moa") or {}, model)
+            config = load_config()
+            effective_custom_providers = custom_providers
+            if effective_custom_providers is None:
+                effective_custom_providers = get_compatible_custom_providers(config)
+            preset = resolve_moa_preset(config.get("moa") or {}, model)
             agg = preset.get("aggregator") or {}
             agg_provider = str(agg.get("provider") or "").strip()
             agg_model = str(agg.get("model") or "").strip()
@@ -2215,7 +2222,8 @@ def get_model_context_length(
                     agg_model,
                     base_url=rt.get("base_url", "") or "",
                     api_key=rt.get("api_key", "") or "",
-                    provider=agg_provider,
+                    provider=rt.get("provider") or agg_provider,
+                    custom_providers=effective_custom_providers,
                 )
         except Exception:
             logger.debug("MoA aggregator context-length resolution failed", exc_info=True)

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 = (
@@ -884,7 +890,14 @@ PLATFORM_HINTS = {
         "You're responding through an API server. The rendering layer is unknown — "
         "assume plain text. No markdown formatting (no asterisks, bullets, headers, "
         "code fences). Treat this like a conversation, not a document. Keep responses "
-        "brief and natural."
+        "brief and natural. "
+        "File/media delivery: images referenced as MEDIA:/absolute/path tags "
+        "(.png/.jpg/.jpeg/.gif/.webp/.bmp, up to 5MB) are inlined as base64 data "
+        "URLs in responses on the chat, completions, and responses endpoints. "
+        "Non-image files are NOT intercepted anywhere, and the runs endpoint "
+        "intercepts nothing — a MEDIA: tag there renders as literal text exposing "
+        "a raw host filesystem path. For those cases, state the plain file path "
+        "in your response text instead of a MEDIA: tag."
     ),
     "webui": (
         "You are in the Hermes WebUI, a browser-based chat interface. "

agent/skill_commands.py

@@ -453,8 +453,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

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

agent/transports/codex_app_server.py

@@ -127,6 +127,10 @@ class CodexAppServerClient:
         # Codex emits tracing to stderr; default WARN keeps it quiet for users.
         spawn_env.setdefault("RUST_LOG", "warn")
 
+        # Hide the console the codex child would otherwise flash on Windows
+        # (#56747). Hide-only — stdio pipes stay intact for the app-server wire.
+        from hermes_cli._subprocess_compat import windows_hide_flags
+
         self._proc = subprocess.Popen(
             cmd,
             stdin=subprocess.PIPE,
@@ -134,6 +138,7 @@ class CodexAppServerClient:
             stderr=subprocess.PIPE,
             bufsize=0,
             env=spawn_env,
+            creationflags=windows_hide_flags(),
         )
         self._next_id = 1
         self._pending: dict[int, _Pending] = {}

agent/turn_context.py

@@ -34,8 +34,10 @@ 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,
 )
+from agent.context_engine import automatic_compaction_status_message
 from agent.iteration_budget import IterationBudget
 from agent.memory_manager import build_memory_context_block
 from agent.model_metadata import (
@@ -375,6 +377,7 @@ def build_turn_context(
         set_runtime_main(
             getattr(agent, "provider", "") or "",
             getattr(agent, "model", "") or "",
+            requested_provider=getattr(agent, "requested_provider", "") or "",
             base_url=getattr(agent, "base_url", "") or "",
             api_key=getattr(agent, "api_key", "") or "",
             api_mode=getattr(agent, "api_mode", "") or "",
@@ -662,11 +665,18 @@ def build_turn_context(
                     f"{_idle_floor:,}",
                     agent.session_id or "none",
                 )
-                agent._emit_status(
-                    IDLE_COMPACTION_STATUS_TEMPLATE.format(
+                _idle_status = automatic_compaction_status_message(
+                    _compressor,
+                    phase="idle",
+                    default_message=IDLE_COMPACTION_STATUS_TEMPLATE.format(
                         idle_seconds=int(_idle_gap), tokens=_idle_tokens
-                    )
+                    ),
+                    approx_tokens=_idle_tokens,
+                    idle_seconds=int(_idle_gap),
+                    model=agent.model,
                 )
+                if _idle_status:
+                    agent._emit_status(_idle_status)
                 _idle_input = messages
                 messages, active_system_prompt = agent._compress_context(
                     messages, system_message, approx_tokens=_idle_tokens,
@@ -680,7 +690,7 @@ def build_turn_context(
                 # untouched.
                 if messages is not _idle_input:
                     conversation_history = conversation_history_after_compression(
-                        agent, messages
+                        agent, messages, conversation_history
                     )
                     # Compaction rebuilt the list, so the index of this turn's
                     # just-appended user message is stale — re-anchor it the
@@ -696,6 +706,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,
@@ -708,6 +720,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",
@@ -741,6 +768,8 @@ def build_turn_context(
             lambda: None,
         )()
 
+        _should_compress_now = False
+        _compress_block_reason = None
         if _preflight_deferred:
             logger.info(
                 "Skipping preflight compression: rough estimate ~%s >= %s, "
@@ -756,14 +785,42 @@ def build_turn_context(
                 int(_compression_cooldown.get("remaining_seconds", 0.0)),
                 agent.session_id or "none",
             )
+            if _preflight_tokens >= _compressor.threshold_tokens:
+                # Context is over threshold but compression is blocked by the
+                # summary-LLM cooldown — surface a warning (see block below).
+                _cooldown_secs = _compression_cooldown.get("remaining_seconds", 0.0)
+                _compress_block_reason = f"cooldown:{_cooldown_secs:.0f}"
         elif _codex_native_auto:
             logger.info(
                 "Skipping Hermes preflight compression for codex app-server "
                 "(mode=%s); Hermes will not start thread compaction here.",
                 getattr(agent, "codex_app_server_auto_compaction", "native"),
             )
-        elif _compressor.should_compress(_preflight_tokens):
+        else:
+            _should_compress_now = _compressor.should_compress(_preflight_tokens)
+            if not _should_compress_now:
+                # Context is over threshold but compression is blocked
+                # (summary-LLM cooldown or anti-thrashing). Ask should_compress_info
+                # for the human-readable reason so we can surface a warning below.
+                # getattr guard: minimal compressor doubles (SimpleNamespace in
+                # the engine-preflight tests) and older plugin engines lack the
+                # method — absence means no block reason, no warning.
+                _info = getattr(_compressor, "should_compress_info", None)
+                if callable(_info):
+                    try:
+                        _compress_block_reason = _info(_preflight_tokens)[1]
+                    except Exception:
+                        _compress_block_reason = None
+        if _should_compress_now:
             _preflight_compressed = True
+            # Compression is actually running (block cleared / was never
+            # blocked) — reset the dedup so a future blocked-over-threshold
+            # turn can warn again. Real session boundary.
+            # getattr guard: test doubles built via object.__new__ lack the
+            # method (gateway test-double pitfall) — treat absence as no-op.
+            _clear_warn = getattr(agent, "_clear_context_overflow_warn", None)
+            if callable(_clear_warn):
+                _clear_warn()
             logger.info(
                 "Preflight compression: ~%s tokens >= %s threshold (model %s, ctx %s)",
                 f"{_preflight_tokens:,}",
@@ -771,12 +828,20 @@ def build_turn_context(
                 agent.model,
                 f"{_compressor.context_length:,}",
             )
-            agent._emit_status(
-                PREFLIGHT_COMPRESSION_STATUS_TEMPLATE.format(
+            _preflight_status = automatic_compaction_status_message(
+                _compressor,
+                phase="preflight",
+                default_message=PREFLIGHT_COMPRESSION_STATUS_TEMPLATE.format(
                     tokens=_preflight_tokens,
                     threshold=_compressor.threshold_tokens,
-                )
+                ),
+                approx_tokens=_preflight_tokens,
+                threshold_tokens=_compressor.threshold_tokens,
+                context_length=_compressor.context_length,
+                model=agent.model,
             )
+            if _preflight_status:
+                agent._emit_status(_preflight_status)
             # Preflight passes honor the same configured per-turn cap
             # (compression.max_attempts) as the loop's compression sites;
             # default 3 preserves the prior hardcoded behavior.
@@ -786,10 +851,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
@@ -805,7 +889,7 @@ def build_turn_context(
                     _preflight_compression_blocked = True
                     break  # Cannot compress further: neither rows nor tokens moved
                 conversation_history = conversation_history_after_compression(
-                    agent, messages
+                    agent, messages, conversation_history
                 )
                 agent._empty_content_retries = 0
                 agent._thinking_prefill_retries = 0
@@ -827,6 +911,100 @@ def build_turn_context(
                         f"{_preflight_tokens:,}",
                     )
                     break
+        elif _compress_block_reason:
+            # Context is already over the compression threshold, but compression
+            # is blocked (summary LLM cooldown or anti-thrashing). Without a
+            # signal the session keeps growing until the model silently stops
+            # answering — the conversation hits the hard provider token limit
+            # with no explanation. Surface a deduped warning so the user can
+            # take action (/new or /compress) instead of hitting a silent hang.
+            agent._warn_context_overflow_blocked(
+                _compress_block_reason,
+                _preflight_tokens,
+                _compressor.threshold_tokens,
+            )
+        else:
+            # Sub-threshold and unblocked — allow the overflow warning to fire
+            # again next time the context is over threshold but blocked.
+            # getattr guard: test doubles built via object.__new__ lack the
+            # method (gateway test-double pitfall) — treat absence as no-op.
+            _clear_warn = getattr(agent, "_clear_context_overflow_warn", None)
+            if callable(_clear_warn):
+                _clear_warn()
+            # Engine maintenance only when NO skip-branch fired: a failure
+            # cooldown, deferred estimate, or codex-native route must keep
+            # the engine hook un-consulted (#20316 contract — the cooldown
+            # exists precisely because compression recently failed).
+            if _compression_cooldown or _preflight_deferred or _codex_native_auto:
+                _engine_preflight = None
+            else:
+                _engine_preflight = getattr(
+                    _compressor, "should_compress_preflight", None
+                )
+            # ── Engine-driven sub-threshold preflight maintenance (#20316) ──
+            # None of the threshold-path branches fired (not deferred, no
+            # failure cooldown, not codex-native, and should_compress() said
+            # the request is under pressure). Context engines that override
+            # ``should_compress_preflight()`` (e.g. LCM-style incremental
+            # leaf-chunk compaction) can still request deferred maintenance
+            # below the token threshold. The default
+            # ``ContextEngine.should_compress_preflight()`` returns False, so
+            # the built-in ``ContextCompressor`` path is byte-identical.
+            #
+            # Attempt-cap integration: the engine gets exactly ONE
+            # ``compress()`` pass per turn. It is mutually exclusive with the
+            # threshold multi-pass loop above (if/elif), so turn-start
+            # preflight passes stay bounded by the resolved
+            # ``compression.max_attempts`` cap (floor 1) in every case.
+            #
+            # No-op-blocking integration: a sub-threshold engine pass that
+            # no-ops says nothing about over-threshold compressibility, so it
+            # must neither set nor clear ``_preflight_compression_blocked``
+            # (#64382) — and being in the ``else`` arm it can never run after
+            # the threshold loop has proven a retry ineffective.
+            # (resolved above, gated on no skip-branch having fired)
+            _wants_engine_preflight = False
+            if callable(_engine_preflight):
+                try:
+                    _wants_engine_preflight = bool(_engine_preflight(messages))
+                except Exception as _preflight_exc:
+                    # A buggy engine must never break an otherwise-healthy
+                    # turn: swallow at debug level and skip maintenance.
+                    logger.debug(
+                        "should_compress_preflight raised %s; skipping "
+                        "engine-driven preflight maintenance",
+                        _preflight_exc,
+                    )
+                    _wants_engine_preflight = False
+            if _wants_engine_preflight:
+                logger.info(
+                    "Engine-driven preflight maintenance: %s requested "
+                    "compress() at ~%s tokens (below %s threshold)",
+                    getattr(_compressor, "name", type(_compressor).__name__),
+                    f"{_preflight_tokens:,}",
+                    f"{getattr(_compressor, 'threshold_tokens', 0):,}",
+                )
+                _engine_input = messages
+                messages, active_system_prompt = agent._compress_context(
+                    messages, system_message, approx_tokens=_preflight_tokens,
+                    task_id=effective_task_id,
+                )
+                # ``_compress_context`` returns the INPUT list object on every
+                # skip path (per-session lock held elsewhere, cooldown,
+                # anti-thrash breaker, codex-native routing) and an engine may
+                # legitimately no-op. Only re-baseline the flush history and
+                # re-anchor the user row after a REAL compaction — a skip must
+                # leave the turn's bookkeeping untouched.
+                if messages is not _engine_input:
+                    _preflight_compressed = True
+                    conversation_history = conversation_history_after_compression(
+                        agent, messages
+                    )
+                    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
 
     if _preflight_compressed:
         # Compression rebuilt the list (tail messages are fresh compaction

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
@@ -625,4 +683,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

agent/verification_evidence.py

@@ -60,10 +60,12 @@ def _db_path() -> 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)
-    conn.execute("PRAGMA journal_mode=WAL")
+    apply_wal_with_fallback(conn, db_label="verification_evidence.db")
     conn.execute("PRAGMA busy_timeout=5000")
     conn.row_factory = sqlite3.Row
     _ensure_schema(conn)

apps/bootstrap-installer/package.json

@@ -13,7 +13,7 @@
     "tauri:build": "tauri build",
     "tauri:build:debug": "tauri build --debug",
     "typecheck": "tsc -p . --noEmit",
-    "check": "npm run typecheck",
+    "check": "npm run typecheck && npm run lint",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "fix": "npm run lint:fix"

apps/desktop/e2e/hidden-history-messages.spec.ts

@@ -0,0 +1,147 @@
+/**
+ * E2E regression: desktop resume must hide agent-only transcript rows.
+ *
+ * Compaction handoffs are active user rows because the model needs them for
+ * context continuity. They are not authored chat content, so the desktop
+ * transcript must never display them after a real compressor-generated resume.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import { expect, test } from './test'
+
+import {
+  type MockBackendFixture,
+  buildAppEnv,
+  createSandbox,
+  launchDesktop,
+  waitForAppReady,
+  writeEnvFile,
+  writeMockProviderConfig,
+} from './fixtures'
+import {
+  MOCK_REPLY,
+  startMockServer,
+  VERIFICATION_STOP_TEXT,
+  VERIFICATION_STOP_TRIGGER,
+} from './mock-server'
+import { RealSessionBuilder } from './real-session-builder'
+
+const SESSION_TITLE = 'E2E Hidden History Messages'
+const VISIBLE_USER_TEXT = 'E2E_VISIBLE_USER_HISTORY'
+const VISIBLE_POST_COMPACTION_TEXT = 'E2E_VISIBLE_POST_COMPACTION_HISTORY'
+const COMPACTION_TRIGGER_PADDING = ' force real context compression'.repeat(600)
+
+async function setupSeededMockBackend(): Promise<MockBackendFixture> {
+  const mock = await startMockServer()
+  const sandbox = createSandbox('hidden-history')
+  writeMockProviderConfig(sandbox.hermesHome, mock.url)
+  fs.appendFileSync(
+    path.join(sandbox.hermesHome, 'config.yaml'),
+    '\ncompression:\n  threshold_tokens: 1\n',
+    'utf8',
+  )
+  writeEnvFile(sandbox.hermesHome)
+  const builder = await RealSessionBuilder.start(sandbox.hermesHome)
+  try {
+    await builder.createSession({
+      title: SESSION_TITLE,
+      turns: [
+        `${VISIBLE_USER_TEXT}${COMPACTION_TRIGGER_PADDING}`,
+        VISIBLE_POST_COMPACTION_TEXT,
+      ],
+    })
+  } finally {
+    await builder.close()
+  }
+
+  const { app, page } = await launchDesktop(buildAppEnv(sandbox))
+
+  return {
+    app,
+    page,
+    mock,
+    mockUrl: mock.url,
+    sandbox,
+    cleanup: async () => {
+      await app.close().catch(() => undefined)
+      await mock.close()
+      sandbox.cleanup()
+    },
+  }
+}
+
+test('resume hides real context-compaction handoffs', async ({}, testInfo) => {
+  const fixture = await setupSeededMockBackend()
+
+  try {
+    const { page } = fixture
+    await waitForAppReady(fixture, 120_000)
+
+    const sessionRow = page
+      .locator('[data-slot="sidebar"] button')
+      .filter({ hasText: SESSION_TITLE })
+      .first()
+    await sessionRow.click()
+
+    const transcript = page.locator('[data-slot="aui_thread-viewport"]')
+    await expect(transcript).toContainText(VISIBLE_USER_TEXT)
+    await expect(transcript).toContainText(VISIBLE_POST_COMPACTION_TEXT)
+    await expect(transcript).toContainText(MOCK_REPLY)
+    await expect(transcript).not.toContainText('[CONTEXT COMPACTION — REFERENCE ONLY]')
+    await page.screenshot({ path: testInfo.outputPath('hidden-history-resume.png') })
+  } finally {
+    await fixture.cleanup()
+  }
+})
+
+test('live verify-on-stop continuations stay out of the transcript', async ({}, testInfo) => {
+  const sandbox = createSandbox('live-verification-nudge')
+  const projectRoot = path.join(sandbox.root, 'project')
+  const changedFile = path.join(projectRoot, 'e2e-verification-target.py')
+  fs.mkdirSync(projectRoot)
+  fs.writeFileSync(
+    path.join(projectRoot, 'pyproject.toml'),
+    '[project]\nname = "e2e-verification-project"\nversion = "0.0.0"\n',
+    'utf8',
+  )
+
+  const mock = await startMockServer({ verificationWritePath: changedFile })
+  writeMockProviderConfig(sandbox.hermesHome, mock.url)
+  fs.appendFileSync(path.join(sandbox.hermesHome, 'config.yaml'), '\nagent:\n  verify_on_stop: true\n', 'utf8')
+  writeEnvFile(sandbox.hermesHome)
+  const { app, page } = await launchDesktop(buildAppEnv(sandbox))
+  const fixture: MockBackendFixture = {
+    app,
+    page,
+    mock,
+    mockUrl: mock.url,
+    sandbox,
+    cleanup: async () => {
+      await app.close().catch(() => undefined)
+      await mock.close()
+      sandbox.cleanup()
+    },
+  }
+
+  try {
+    await waitForAppReady(fixture, 120_000)
+    const composer = page.locator('[contenteditable="true"]').first()
+    await composer.click()
+    await composer.type(VERIFICATION_STOP_TRIGGER)
+    await page.keyboard.press('Enter')
+
+    const transcript = page.locator('[data-slot="aui_thread-viewport"]')
+    await expect(transcript).toContainText(VERIFICATION_STOP_TEXT, { timeout: 60_000 })
+    await expect.poll(
+      () => mock.receivedPrompts.some(prompt => prompt.includes('[System: You edited code in this turn')),
+      { timeout: 30_000 },
+    ).toBe(true)
+    expect(fs.existsSync(changedFile), 'The scripted write_file call should edit only the sandbox project').toBe(true)
+    await expect(transcript).not.toContainText('[System: You edited code in this turn')
+    await page.screenshot({ path: testInfo.outputPath('live-verification-nudge.png') })
+  } finally {
+    await fixture.cleanup()
+  }
+})

apps/desktop/e2e/large-session-resume.spec.ts

@@ -1,4 +1,3 @@
-import { spawnSync } from 'node:child_process'
 import * as path from 'node:path'
 
 import { type TestInfo } from '@playwright/test'
@@ -15,13 +14,16 @@ import {
   writeMockProviderConfig,
 } from './fixtures'
 import { MOCK_REPLY, startMockServer, type MockServer, type MockServerOptions } from './mock-server'
+import { RealSessionBuilder } from './real-session-builder'
 
 const DESKTOP_ROOT = path.resolve(import.meta.dirname, '..')
-const REPO_ROOT = path.resolve(DESKTOP_ROOT, '..', '..')
-const SEED_SCRIPT = path.resolve(import.meta.dirname, 'scripts', 'seed_large_session.py')
 const SESSION_TITLE = 'E2E large persisted session'
 const EXPECTED_TEXT = 'E2E persisted user message 52'
 const BACKGROUND_PROMPT = 'E2E background inference must remain attached across resume'
+const HISTORY_TURNS = Array.from(
+  { length: 27 },
+  (_, index) => `E2E persisted user message ${index * 2}: audit the compatibility matrix`,
+)
 
 interface SeededFixture {
   app: ElectronApplication
@@ -43,13 +45,11 @@ async function setupSeededDesktop(mockServer?: MockServerOptions): Promise<Seede
   writeMockProviderConfig(sandbox.hermesHome, mock.url)
   writeEnvFile(sandbox.hermesHome)
 
-  const seeded = spawnSync('python3', [SEED_SCRIPT, path.join(sandbox.hermesHome, 'state.db')], {
-    cwd: REPO_ROOT,
-    encoding: 'utf8',
-    env: { ...process.env, PYTHONPATH: REPO_ROOT },
-  })
-  if (seeded.status !== 0) {
-    throw new Error(`large-session seed failed:\n${seeded.stdout}\n${seeded.stderr}`)
+  const builder = await RealSessionBuilder.start(sandbox.hermesHome)
+  try {
+    await builder.createSession({ title: SESSION_TITLE, turns: HISTORY_TURNS })
+  } finally {
+    await builder.close()
   }
 
   const { app, page } = await launchDesktop(buildAppEnv(sandbox))
@@ -210,6 +210,7 @@ test.describe('large session resume', () => {
       await waitForAppReady(fixture, 120_000)
 
       await openSeededSession(fixture.page)
+      const initialMockReplyCount = await textNodeOccurrences(fixture.page, MOCK_REPLY)
       await submitPrompt(fixture.page, BACKGROUND_PROMPT)
       await fixture.mock.waitForHeldStream()
       await openNewSession(fixture.page)
@@ -229,7 +230,10 @@ test.describe('large session resume', () => {
       await fixture.page.screenshot({ path: testInfo.outputPath(`${resumeKind}-background-inference-resume.png`), fullPage: false })
 
       expect(await textNodeOccurrences(fixture.page, BACKGROUND_PROMPT), 'the running user prompt should appear once').toBe(1)
-      expect(await textNodeOccurrences(fixture.page, MOCK_REPLY), 'the completed assistant reply should appear once').toBe(1)
+      expect(
+        await textNodeOccurrences(fixture.page, MOCK_REPLY),
+        'the completed assistant reply should add exactly one transcript row',
+      ).toBe(initialMockReplyCount + 1)
     })
   }
 })

apps/desktop/e2e/mock-server.ts

@@ -23,8 +23,10 @@ export const MOCK_REPLY = 'Hello from the mock inference server! The full boot c
 export interface MockServerOptions {
   /** Pause the matching stream after its first token for session-switch E2E coverage. */
   holdFirstStreamForPrompt?: string
-  /** Pause the first completion whose request JSON contains this text. */
-  holdFirstCompletionContaining?: string
+/** Pause the first completion whose request JSON contains this text. */
+holdFirstCompletionContaining?: string
+/** Absolute sandbox path written by the verify-on-stop scripted tool call. */
+verificationWritePath?: string
 }
 
 export interface MockServer {
@@ -104,6 +106,9 @@ let _queueStopIndex = 0
 /** Per-server counter for the correction/session-switch script. */
 let _correctionSwitchIndex = 0
 
+/** Per-server counter for the verify-on-stop script. */
+let _verificationStopIndex = 0
+
 /** User messages received by the mock, for E2E assertions on real submits. */
 const _receivedUserTexts: string[] = []
 
@@ -114,6 +119,7 @@ function resetScriptIndex(): void {
   _sidebarCrossIndex = 0
   _queueStopIndex = 0
   _correctionSwitchIndex = 0
+  _verificationStopIndex = 0
   _receivedUserTexts.length = 0
 }
 
@@ -214,6 +220,32 @@ const CORRECTION_SWITCH_SCRIPT: ScriptedTurn[] = [
 
 export const CORRECTION_SWITCH_TRIGGER = 'E2E_CORRECTION_SWITCH_TRIGGER'
 
+/**
+ * Drives a real code edit followed by two finish attempts. Hermes should add
+ * its synthetic verify-on-stop continuation after each finish attempt until
+ * the bounded verifier gives up. The mock's request capture proves the nudge
+ * reached the model; desktop must never render it as chat content.
+ */
+function verificationStopScript(writePath: string): ScriptedTurn[] {
+  return [
+  {
+    text: 'I will make the requested code change.',
+    toolCalls: [{
+      name: 'write_file',
+      args: {
+        path: writePath,
+        content: 'def changed_by_e2e():\n    return "changed"\n',
+      },
+    }],
+  },
+  { text: 'The code edit is complete.' },
+  { text: 'I cannot provide fresh verification evidence for that edit.' },
+  ]
+}
+
+export const VERIFICATION_STOP_TRIGGER = 'E2E_VERIFY_ON_STOP_TRIGGER'
+export const VERIFICATION_STOP_TEXT = 'I cannot provide fresh verification evidence for that edit.'
+
 /**
  * A marker that makes the mock emit a real blocking clarify tool call. Tests
  * use it to hold a turn open while exercising busy-composer interactions.
@@ -340,6 +372,9 @@ export function startMockServer(options: MockServerOptions = {}): Promise<MockSe
           const isSidebarTrigger = userText.includes('E2E_SIDEBAR_TRIGGER')
           const isSidebarCrossTrigger = userText.includes('E2E_SIDEBAR_CROSS')
           const isQueueStopTrigger = userText.includes('E2E_QUEUE_STOP_TRIGGER')
+          const isVerificationStopTrigger = messages.some(
+            message => typeof message?.content === 'string' && message.content.includes(VERIFICATION_STOP_TRIGGER),
+          )
           const isCorrectionSwitchTrigger = messages.some(
             message => typeof message?.content === 'string' && message.content.includes(CORRECTION_SWITCH_TRIGGER),
           )
@@ -364,6 +399,18 @@ export function startMockServer(options: MockServerOptions = {}): Promise<MockSe
             return
           }
 
+          if (isVerificationStopTrigger) {
+            const script = verificationStopScript(options.verificationWritePath ?? 'e2e-verification-target.py')
+            const turn = script[_verificationStopIndex] ?? script[script.length - 1]
+            _verificationStopIndex++
+            if (stream) {
+              streamScriptedTurn(res, model, turn)
+            } else {
+              nonStreamingScriptedTurn(res, model, turn)
+            }
+            return
+          }
+
           if (isCorrectionSwitchTrigger) {
             const turn = CORRECTION_SWITCH_SCRIPT[_correctionSwitchIndex] ?? CORRECTION_SWITCH_SCRIPT[CORRECTION_SWITCH_SCRIPT.length - 1]
             _correctionSwitchIndex++

apps/desktop/e2e/real-session-builder.ts

@@ -0,0 +1,226 @@
+import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process'
+import * as path from 'node:path'
+import { createInterface } from 'node:readline'
+
+const DESKTOP_ROOT = path.resolve(import.meta.dirname, '..')
+const REPO_ROOT = path.resolve(DESKTOP_ROOT, '..', '..')
+const DEFAULT_TIMEOUT_MS = 60_000
+
+interface JsonRpcError {
+  code?: number
+  message?: string
+}
+
+interface JsonRpcFrame {
+  error?: JsonRpcError
+  id?: number
+  method?: string
+  params?: {
+    payload?: unknown
+    session_id?: string
+    type?: string
+  }
+  result?: unknown
+}
+
+interface CreatedSession {
+  session_id: string
+  stored_session_id: string
+}
+
+export interface RealSessionSpec {
+  /** Human-visible sidebar title, persisted by the first completed turn. */
+  title: string
+  /** Each item becomes one real user prompt followed by the mock provider's reply. */
+  turns: readonly string[]
+}
+
+export interface RealSession {
+  /** Runtime-only TUI session id, valid only while the builder process is alive. */
+  runtimeId: string
+  /** Durable SessionDB id that desktop resumes after the builder exits. */
+  sessionId: string
+}
+
+/**
+ * Creates durable desktop session history through the real TUI gateway and
+ * AIAgent loop, using the E2E mock provider configured in `hermesHome`.
+ *
+ * This intentionally uses the shipped stdio JSON-RPC transport instead of
+ * importing SessionDB or launching Electron. The desktop's WebSocket backend
+ * dispatches the same `tui_gateway.server` methods.
+ */
+export class RealSessionBuilder {
+  private readonly child: ChildProcessWithoutNullStreams
+  private nextRequestId = 0
+  private readonly pending = new Map<number, { reject: (reason: Error) => void; resolve: (value: unknown) => void }>()
+  private readonly events: JsonRpcFrame[] = []
+  private readonly eventWaiters: Array<{
+    predicate: (frame: JsonRpcFrame) => boolean
+    reject: (reason: Error) => void
+    resolve: (frame: JsonRpcFrame) => void
+  }> = []
+  private readonly stderr: string[] = []
+  private closed = false
+
+  private constructor(hermesHome: string) {
+    this.child = spawn('uv', ['run', '--active', '--no-sync', 'python', '-m', 'tui_gateway.entry'], {
+      cwd: REPO_ROOT,
+      env: {
+        ...process.env,
+        HERMES_HOME: hermesHome,
+        PYTHONPATH: REPO_ROOT,
+      },
+      stdio: 'pipe',
+    })
+
+    createInterface({ input: this.child.stdout }).on('line', line => this.handleLine(line))
+    createInterface({ input: this.child.stderr }).on('line', line => {
+      this.stderr.push(line)
+      if (this.stderr.length > 80) this.stderr.shift()
+    })
+    this.child.once('error', error => this.failAll(new Error(`real-session gateway failed to start: ${error.message}`)))
+    this.child.once('exit', (code, signal) => {
+      if (!this.closed) {
+        this.failAll(new Error(`real-session gateway exited unexpectedly (${signal ?? code ?? 'unknown'}):\n${this.stderr.join('\n')}`))
+      }
+    })
+  }
+
+  static async start(hermesHome: string): Promise<RealSessionBuilder> {
+    const builder = new RealSessionBuilder(hermesHome)
+    await builder.waitForEvent(frame => frame.params?.type === 'gateway.ready')
+    return builder
+  }
+
+  async createSession(spec: RealSessionSpec): Promise<RealSession> {
+    if (spec.turns.length === 0) {
+      throw new Error('RealSessionBuilder requires at least one turn so the real agent creates a durable session row')
+    }
+
+    const created = await this.request<CreatedSession>('session.create', {
+      cols: 120,
+      cwd: REPO_ROOT,
+      source: 'desktop',
+      title: spec.title,
+    })
+    const runtimeId = requireString(created, 'session_id')
+    const sessionId = requireString(created, 'stored_session_id')
+
+    for (const text of spec.turns) {
+      const completion = this.waitForEvent(
+        frame => frame.params?.type === 'message.complete' && frame.params.session_id === runtimeId,
+      )
+      await this.request('prompt.submit', { session_id: runtimeId, text })
+      const frame = await completion
+      const status = readString(frame.params?.payload, 'status')
+      if (status !== 'complete') {
+        throw new Error(`real session turn failed with status ${status ?? 'unknown'}: ${JSON.stringify(frame.params?.payload)}`)
+      }
+    }
+
+    await this.request('session.close', { session_id: runtimeId })
+    return { runtimeId, sessionId }
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return
+    this.closed = true
+    this.child.stdin.end()
+    await new Promise<void>(resolve => {
+      const timeout = setTimeout(() => {
+        this.child.kill('SIGTERM')
+        resolve()
+      }, 5_000)
+      this.child.once('exit', () => {
+        clearTimeout(timeout)
+        resolve()
+      })
+    })
+  }
+
+  private request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T> {
+    const id = ++this.nextRequestId
+    return this.withTimeout(new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { resolve: value => resolve(value as T), reject })
+      this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`, error => {
+        if (error) {
+          this.pending.delete(id)
+          reject(error)
+        }
+      })
+    }), `request ${method}`)
+  }
+
+  private waitForEvent(predicate: (frame: JsonRpcFrame) => boolean): Promise<JsonRpcFrame> {
+    const index = this.events.findIndex(predicate)
+    if (index >= 0) {
+      return Promise.resolve(this.events.splice(index, 1)[0])
+    }
+    return this.withTimeout(new Promise<JsonRpcFrame>((resolve, reject) => {
+      this.eventWaiters.push({ predicate, resolve, reject })
+    }), 'gateway event')
+  }
+
+  private handleLine(line: string): void {
+    let frame: JsonRpcFrame
+    try {
+      frame = JSON.parse(line) as JsonRpcFrame
+    } catch {
+      return
+    }
+
+    if (typeof frame.id === 'number') {
+      const pending = this.pending.get(frame.id)
+      if (!pending) return
+      this.pending.delete(frame.id)
+      if (frame.error) {
+        pending.reject(new Error(`JSON-RPC error ${frame.error.code ?? 'unknown'}: ${frame.error.message ?? 'unknown error'}`))
+      } else {
+        pending.resolve(frame.result)
+      }
+      return
+    }
+
+    if (frame.method !== 'event') return
+    const waiter = this.eventWaiters.find(candidate => candidate.predicate(frame))
+    if (!waiter) {
+      this.events.push(frame)
+      return
+    }
+    this.eventWaiters.splice(this.eventWaiters.indexOf(waiter), 1)
+    waiter.resolve(frame)
+  }
+
+  private withTimeout<T>(promise: Promise<T>, operation: string): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`Timed out after ${DEFAULT_TIMEOUT_MS / 1000}s waiting for ${operation}:\n${this.stderr.join('\n')}`)), DEFAULT_TIMEOUT_MS)
+      promise.then(value => {
+        clearTimeout(timer)
+        resolve(value)
+      }, error => {
+        clearTimeout(timer)
+        reject(error)
+      })
+    })
+  }
+
+  private failAll(error: Error): void {
+    for (const pending of this.pending.values()) pending.reject(error)
+    this.pending.clear()
+    for (const waiter of this.eventWaiters) waiter.reject(error)
+    this.eventWaiters.length = 0
+  }
+}
+
+function readString(value: unknown, key: string): string | undefined {
+  if (!value || typeof value !== 'object') return undefined
+  const candidate = (value as Record<string, unknown>)[key]
+  return typeof candidate === 'string' ? candidate : undefined
+}
+
+function requireString(value: unknown, key: string): string {
+  const candidate = readString(value, key)
+  if (!candidate) throw new Error(`Gateway response omitted required ${key}: ${JSON.stringify(value)}`)
+  return candidate
+}

apps/desktop/e2e/scripts/seed_large_session.py

@@ -1,52 +0,0 @@
-#!/usr/bin/env python3
-"""Seed a deterministic, tool-free large session into an isolated state.db."""
-
-import sys
-from pathlib import Path
-
-repo_root = Path(__file__).resolve().parents[3]
-sys.path.insert(0, str(repo_root))
-
-from hermes_state import SessionDB  # noqa: E402
-
-SESSION_ID = "e2e-large-session"
-SESSION_TITLE = "E2E large persisted session"
-
-
-def main() -> None:
-    if len(sys.argv) != 2:
-        raise SystemExit(f"usage: {sys.argv[0]} <state.db>")
-
-    messages = []
-    for index in range(53):
-        role = "user" if index % 2 == 0 else "assistant"
-        content = (
-            f"E2E persisted user message {index}: audit the compatibility matrix"
-            if role == "user"
-            else f"E2E persisted assistant reply {index}: recorded the audit result"
-        )
-        messages.append({"role": role, "content": content, "timestamp": 1_700_000_000 + index})
-
-    database = SessionDB(db_path=Path(sys.argv[1]))
-    result = database.import_sessions(
-        [
-            {
-                "id": SESSION_ID,
-                "source": "desktop",
-                "model": "mock-model",
-                "started_at": 1_700_000_000,
-                "title": SESSION_TITLE,
-                "cwd": str(repo_root),
-                "system_prompt": "",
-                "messages": messages,
-            }
-        ]
-    )
-    database.close()
-
-    if not result.get("ok") or result.get("imported") != 1:
-        raise SystemExit(f"failed to seed large session: {result}")
-
-
-if __name__ == "__main__":
-    main()

apps/desktop/e2e/scripts/seed_session_db.py

@@ -1,56 +0,0 @@
-#!/usr/bin/env python3
-"""Seed a Hermes state.db with a session exported from a real conversation.
-
-Usage: seed_session_db.py <state_db_path> <fixture_json_path>
-
-Creates the database with the full SessionDB schema (if it doesn't exist)
-and imports the session from the JSON fixture. Uses the real
-SessionDB.import_sessions() so the data shape matches what the desktop
-backend expects.
-"""
-import json
-import sys
-from pathlib import Path
-
-# Add the repo root to sys.path so we can import hermes_state.
-# The script is invoked from apps/desktop/e2e/ — repo root is ../../..
-repo_root = Path(__file__).resolve().parents[3]
-sys.path.insert(0, str(repo_root))
-
-from hermes_state import SessionDB  # noqa: E402
-
-
-def main():
-    if len(sys.argv) != 3:
-        print(f"Usage: {sys.argv[0]} <state_db_path> <fixture_json_path>", file=sys.stderr)
-        sys.exit(1)
-
-    db_path = Path(sys.argv[1])
-    fixture_path = Path(sys.argv[2])
-
-    db_path.parent.mkdir(parents=True, exist_ok=True)
-
-    with open(fixture_path, "r", encoding="utf-8") as f:
-        session_data = json.load(f)
-
-    db = SessionDB(db_path=db_path)
-    result = db.import_sessions([session_data])
-
-    if not result.get("ok"):
-        print(f"Import failed: {result}", file=sys.stderr)
-        sys.exit(1)
-
-    imported = result.get("imported", 0)
-    skipped = result.get("skipped", 0)
-    errors = result.get("errors", [])
-
-    if errors:
-        print(f"Import had errors: {errors}", file=sys.stderr)
-        sys.exit(1)
-
-    print(f"Seeded {imported} session(s), skipped {skipped} → {db_path}")
-    db.close()
-
-
-if __name__ == "__main__":
-    main()

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()
 

apps/desktop/e2e/warm-resume-jitter.spec.ts

@@ -28,11 +28,6 @@
  * Prerequisite: `npm run build` must have been run so dist/ exists.
  */
 
-import { spawnSync } from 'node:child_process'
-import * as fs from 'node:fs'
-import * as os from 'node:os'
-import * as path from 'node:path'
-
 import { expect, test } from './test'
 
 import {
@@ -45,12 +40,9 @@ import {
   launchDesktop,
 } from './fixtures'
 import { startMockServer } from './mock-server'
+import { RealSessionBuilder } from './real-session-builder'
 
-const DESKTOP_ROOT = path.resolve(import.meta.dirname, '..')
-const REPO_ROOT = path.resolve(DESKTOP_ROOT, '..', '..')
-const SEED_SCRIPT = path.join(DESKTOP_ROOT, 'e2e', 'scripts', 'seed_session_db.py')
 const SESSION_TITLE = 'E2E Warm Resume Jitter Test'
-const SESSION_ID = 'e2e-warm-resume-session'
 /** 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. */
@@ -82,54 +74,27 @@ function gibberish(rng: () => number): string {
 const FIRST_USER_MSG = gibberish(mulberry32(RNG_SEED))
 
 /**
- * Generate a session fixture with MESSAGE_COUNT messages (user/assistant
- * pairs) of seeded gibberish — just role + content, enough for SessionDB
- * to import and the transcript to render. Written to a temp file for the
- * seed script.
+ * Generate the user turns for a real session. The mock provider produces the
+ * assistant side of each pair through the normal AIAgent persistence path.
  */
-function generateSessionFixture(fixturePath: string): void {
+function generateSessionTurns(): string[] {
   const rng = mulberry32(RNG_SEED)
-  const messages: Array<{ role: string; content: string }> = []
+  const turns: string[] = []
 
   for (let i = 0; i < MESSAGE_COUNT / 2; i++) {
-    messages.push({ role: 'user', content: gibberish(rng) })
-    messages.push({ role: 'assistant', content: gibberish(rng) })
+    turns.push(gibberish(rng))
+    gibberish(rng)
   }
 
-  const session = {
-    id: SESSION_ID,
-    source: 'cli',
-    model: 'mock-model',
-    system_prompt: '',
-    started_at: 1721692800.0,
-    message_count: MESSAGE_COUNT,
-    title: SESSION_TITLE,
-    cwd: '/tmp',
-    archived: 0,
-    rewind_count: 0,
-    compression_fallback_streak: 0,
-    messages,
-  }
-
-  fs.writeFileSync(fixturePath, JSON.stringify(session), 'utf8')
-}
-
-/** Resolve the python binary from the nix devshell (falls back to python3). */
-function findPython(): string {
-  const result = spawnSync('which', ['python'], { encoding: 'utf8' })
-  if (result.status === 0 && result.stdout.trim()) {
-    return result.stdout.trim()
-  }
-  return 'python3'
+  return turns
 }
 
 /**
- * Set up a mock-backend sandbox with a pre-seeded session in state.db.
+ * Set up a mock-backend sandbox with a real persisted session in state.db.
  *
- * Unlike the shared `setupMockBackend()`, this variant seeds the DB
- * BEFORE launching the app so the session appears in the sidebar on first
- * load — exercising the real `resumeSession()` cold path without needing
- * to send a message first.
+ * Unlike the shared `setupMockBackend()`, this variant creates the session
+ * through the real stdio gateway before launching desktop so the session is
+ * visible in the sidebar on first load.
  */
 async function setupSeededMockBackend(): Promise<MockBackendFixture> {
   // 1. Start mock server
@@ -140,28 +105,13 @@ async function setupSeededMockBackend(): Promise<MockBackendFixture> {
   writeMockProviderConfig(sandbox.hermesHome, mock.url)
   writeEnvFile(sandbox.hermesHome)
 
-  // 3. Pre-seed state.db: generate a fixture JSON to a temp file, then
-  //    run the seed script to import it into state.db BEFORE launching.
-  const stateDbPath = path.join(sandbox.hermesHome, 'state.db')
-  const fixturePath = path.join(os.tmpdir(), `hermes-e2e-warm-resume-${Date.now()}.json`)
-  generateSessionFixture(fixturePath)
-  const python = findPython()
-  const seedResult = spawnSync(
-    python,
-    [SEED_SCRIPT, stateDbPath, fixturePath],
-    {
-      cwd: REPO_ROOT,
-      env: { ...process.env, PYTHONPATH: REPO_ROOT },
-      encoding: 'utf8',
-      timeout: 30_000,
-    },
-  )
-  fs.unlinkSync(fixturePath)
-
-  if (seedResult.status !== 0) {
-    throw new Error(
-      `Failed to seed state.db:\nstdout: ${seedResult.stdout}\nstderr: ${seedResult.stderr}`,
-    )
+  // 3. Produce all 16 user/assistant pairs through the real TUI gateway,
+  // AIAgent, mock provider, and SessionDB persistence path before desktop starts.
+  const builder = await RealSessionBuilder.start(sandbox.hermesHome)
+  try {
+    await builder.createSession({ title: SESSION_TITLE, turns: generateSessionTurns() })
+  } finally {
+    await builder.close()
   }
 
   // 4. Build env + launch

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')
+})

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
+}

apps/desktop/electron/main.ts

@@ -78,6 +78,7 @@ import {
 } from './desktop-uninstall'
 import { installEmbedReferer } from './embed-referer'
 import { createEventDeduper } from './event-dedupe'
+import { findGitBash as _findGitBash } from './find-git-bash'
 import { readDirForIpc } from './fs-read-dir'
 import { probeGatewayWebSocket } from './gateway-ws-probe'
 import { scanGitRepos } from './git-repo-scan'
@@ -1915,48 +1916,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) {

apps/desktop/package.json

@@ -54,7 +54,11 @@
     "test:desktop:platforms": "vitest run --project electron",
     "test": "vitest run",
     "preview": "node scripts/assert-root-install.mjs && vite preview --host 127.0.0.1 --port 4174",
-    "check": "npm run typecheck && npm run test && npm run test:desktop:all",
+    "check:test:desktop:platforms": "npm run test:desktop:platforms",
+    "check:test:ui": "npm run test:ui",
+    "check:test:desktop:all": "npm run test:desktop:all",
+    "check:lint": "npm run typecheck && npm run lint",
+    "check": "npm run check:lint && npm run check:test:ui && npm run test:desktop:platforms && npm run test:desktop:all",
     "test:e2e": "npm run build && playwright test e2e/",
     "test:e2e:visual": "npm run build && WLR_BACKENDS=headless WLR_NO_HARDWARE_CURSORS=1 cage -- npx playwright test e2e/ --reporter=list",
     "test:e2e:update-snapshots": "npm run build && WLR_BACKENDS=headless WLR_NO_HARDWARE_CURSORS=1 cage -- npx playwright test e2e/ --reporter=list --update-snapshots"

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

@@ -55,6 +55,7 @@ export function useComposerVoice({
   const { t } = useI18n()
   const [voiceConversationActive, setVoiceConversationActive] = useState(false)
   const lastSpokenIdRef = useRef<string | null>(null)
+  const voiceStartRequest = useStore($voiceConversationStartRequest)
 
   const { dictate, voiceActivityState, voiceStatus } = useVoiceRecorder({
     focusInput,
@@ -143,54 +144,37 @@ export function useComposerVoice({
     [target, toggleVoiceConversation]
   )
 
-  // "Hey Hermes" wake word: a latched start request (nanostore) the composer
-  // claims once it's mounted and the gateway is ready. Survives the fresh-session
-  // remount the wake handler triggers, and waits out a transient `disabled`.
-  const voiceStartReq = useStore($voiceConversationStartRequest)
   useEffect(() => {
-    if (disabled) {
-      return // not ready — re-runs when `disabled` flips false
-    }
-
-    if (!takeVoiceConversationStart(voiceStartReq)) {
-      return
-    }
-
-    if (!voiceConversationActive) {
+    if (target === 'main' && !disabled && takeVoiceConversationStart(voiceStartRequest) && !voiceConversationActive) {
       setVoiceConversationActive(true)
     }
-  }, [voiceStartReq, disabled, voiceConversationActive])
+  }, [disabled, target, voiceConversationActive, voiceStartRequest])
 
-  // Hand the mic between the server-side wake detector and the browser's voice
-  // loop: pause the detector while a conversation is live, resume it after
-  // (no-ops server-side when the wake word isn't armed). wakePausedRef tracks
-  // whether WE paused, so resume always runs once — including on unmount, where
-  // ending voice can tear the composer down before the `false` render lands and
-  // would otherwise leave the detector paused forever.
   const wakePausedRef = useRef(false)
 
-  const wakeRpc = useCallback(
-    (method: string) => void $gateway.get()?.request(method, {}).catch(() => undefined),
-    []
-  )
-
   const resumeWakeIfPaused = useCallback(() => {
     if (!wakePausedRef.current) {
       return
     }
 
     wakePausedRef.current = false
-    wakeRpc('wake.resume')
-  }, [wakeRpc])
+    void $gateway
+      .get()
+      ?.request('wake.resume', {})
+      .catch(() => undefined)
+  }, [])
 
   useEffect(() => {
     if (voiceConversationActive) {
       wakePausedRef.current = true
-      wakeRpc('wake.pause')
+      void $gateway
+        .get()
+        ?.request('wake.pause', {})
+        .catch(() => undefined)
     } else {
       resumeWakeIfPaused()
     }
-  }, [voiceConversationActive, wakeRpc, resumeWakeIfPaused])
+  }, [resumeWakeIfPaused, voiceConversationActive])
 
   useEffect(() => resumeWakeIfPaused, [resumeWakeIfPaused])
 

apps/desktop/src/app/contrib/wiring.tsx

@@ -647,9 +647,6 @@ export function ContribWiring({ children }: { children: ReactNode }) {
     (event: Parameters<typeof handleDesktopGatewayEvent>[0]) => {
       emitGatewayEvent(event)
 
-      // "Hey Hermes": handle the wake event on the canonical onEvent pipeline —
-      // open a fresh session (unless the config keeps the current one) and begin
-      // back-and-forth voice via the composer's latched start request.
       if (event.type === 'wake.detected') {
         const payload = event.payload as { start_new_session?: boolean } | undefined
 
@@ -685,15 +682,10 @@ export function ContribWiring({ children }: { children: ReactNode }) {
     refreshSessions
   })
 
-  // "Hey Hermes" wake word: arm the server-side detector for this surface
-  // (gated on config server-side). Detection arrives as a wake.detected event
-  // handled in handleGatewayEventWithPlugins. Idempotent, so reconnects are safe.
   useEffect(() => {
-    if (gatewayState !== 'open') {
-      return
+    if (gatewayState === 'open') {
+      void requestGateway('wake.start', { surface: 'gui' }).catch(() => undefined)
     }
-
-    void requestGateway('wake.start', { surface: 'gui' }).catch(() => undefined)
   }, [gatewayState, requestGateway])
 
   // Only the open messaging transcript needs its own poll — local chats are

apps/desktop/src/app/gateway/hooks/gateway-hmr-survivor.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import {
+  type GatewaySurvivor,
+  stashGatewaySurvivor,
+  survivorIsStale,
+  takeGatewaySurvivor
+} from './gateway-hmr-survivor'
+
+// A minimal stand-in for HermesGateway: the survivor cache only reads
+// `connectionState`. Cast through unknown so we don't drag the whole class in.
+function fakeGateway(state: 'idle' | 'connecting' | 'open' | 'closed' | 'error') {
+  return { connectionState: state } as unknown as GatewaySurvivor['gateway']
+}
+
+function makeSurvivor(state: Parameters<typeof fakeGateway>[0]): GatewaySurvivor {
+  return { gateway: fakeGateway(state), profile: 'default', connection: null }
+}
+
+afterEach(() => {
+  // Drain any survivor a test parked but didn't take, so cases don't leak across
+  // the shared globalThis slot.
+  takeGatewaySurvivor()
+})
+
+describe('gateway HMR survivor cache', () => {
+  it('returns null when nothing is parked', () => {
+    expect(takeGatewaySurvivor()).toBeNull()
+  })
+
+  it('round-trips a parked survivor', () => {
+    const survivor = makeSurvivor('open')
+    stashGatewaySurvivor(survivor)
+    expect(takeGatewaySurvivor()).toBe(survivor)
+  })
+
+  it('is single-shot — a second take returns null', () => {
+    stashGatewaySurvivor(makeSurvivor('open'))
+    expect(takeGatewaySurvivor()).not.toBeNull()
+    expect(takeGatewaySurvivor()).toBeNull()
+  })
+
+  it('persists across re-imports via the globalThis slot', async () => {
+    const survivor = makeSurvivor('open')
+    stashGatewaySurvivor(survivor)
+
+    // A fresh import of the module (simulating an HMR module swap) must resolve
+    // the same underlying store, not a reset one.
+    const reimported = await import('./gateway-hmr-survivor')
+    expect(reimported.takeGatewaySurvivor()).toBe(survivor)
+  })
+
+  it('treats open / connecting sockets as adoptable', () => {
+    expect(survivorIsStale(makeSurvivor('open'))).toBe(false)
+    expect(survivorIsStale(makeSurvivor('connecting'))).toBe(false)
+  })
+
+  it('treats closed / error / idle sockets as stale', () => {
+    expect(survivorIsStale(makeSurvivor('closed'))).toBe(true)
+    expect(survivorIsStale(makeSurvivor('error'))).toBe(true)
+    expect(survivorIsStale(makeSurvivor('idle'))).toBe(true)
+  })
+
+  it('returns a stale survivor from take() so the caller can close it', () => {
+    const dead = makeSurvivor('closed')
+    stashGatewaySurvivor(dead)
+    const taken = takeGatewaySurvivor()
+    expect(taken).toBe(dead)
+    expect(taken && survivorIsStale(taken)).toBe(true)
+  })
+})

apps/desktop/src/app/gateway/hooks/gateway-hmr-survivor.ts

@@ -0,0 +1,56 @@
+// Keep the live primary gateway socket alive across Vite HMR so editing UI never
+// drops the agent session. Stash on dispose, re-adopt on remount. globalThis +
+// self-accept so this module's own reload doesn't reset the cache. Prod strips
+// import.meta.hot → byte-for-byte unchanged live unmount.
+
+import type { HermesConnection } from '@/global'
+import type { HermesGateway } from '@/hermes'
+
+export interface GatewaySurvivor {
+  gateway: HermesGateway
+  profile: string
+  connection: HermesConnection | null
+}
+
+// One slot on globalThis, keyed by a process-stable Symbol so repeated imports
+// (across hot reloads) resolve the exact same store.
+const SURVIVOR_KEY = Symbol.for('hermes.desktop.gatewaySurvivor')
+
+interface SurvivorGlobal {
+  [SURVIVOR_KEY]?: GatewaySurvivor | null
+}
+
+function slot(): SurvivorGlobal {
+  return globalThis as unknown as SurvivorGlobal
+}
+
+/** Park the live gateway so the next module instance can re-adopt it. */
+export function stashGatewaySurvivor(survivor: GatewaySurvivor): void {
+  slot()[SURVIVOR_KEY] = survivor
+}
+
+/**
+ * Take the parked gateway, if any. Single-shot: the slot is cleared on read.
+ * The caller decides whether to adopt or discard it via `survivorIsStale` — a
+ * socket that died while parked (e.g. backend restart between edits) is still
+ * returned so the caller can close it and boot fresh.
+ */
+export function takeGatewaySurvivor(): GatewaySurvivor | null {
+  const store = slot()
+  const survivor = store[SURVIVOR_KEY] ?? null
+  store[SURVIVOR_KEY] = null
+
+  return survivor
+}
+
+/** A parked survivor whose socket is no longer open — caller should discard it. */
+export function survivorIsStale(survivor: GatewaySurvivor): boolean {
+  const state = survivor.gateway.connectionState
+
+  return state !== 'open' && state !== 'connecting'
+}
+
+// Self-accept so editing THIS module doesn't blow away the cache it manages.
+if (import.meta.hot) {
+  import.meta.hot.accept()
+}

apps/desktop/src/app/gateway/hooks/use-gateway-boot.test.tsx

@@ -4,6 +4,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { $desktopBoot } from '@/store/boot'
 import { $gatewayState } from '@/store/session'
 
+import { takeGatewaySurvivor } from './gateway-hmr-survivor'
 import { useGatewayBoot } from './use-gateway-boot'
 
 // End-to-end-ish repro of the "remote VPS → stuck on CONNECTING, no Settings"
@@ -131,6 +132,17 @@ function Harness({
 const originalWebSocket = globalThis.WebSocket
 
 beforeEach(() => {
+  // Drop any parked gateway left by a prior file/case (globalThis slot).
+  const leftover = takeGatewaySurvivor()
+
+  if (leftover) {
+    try {
+      leftover.gateway.close()
+    } catch {
+      // ignore
+    }
+  }
+
   vi.useFakeTimers()
   FakeWebSocket.mode = 'open'
   FakeWebSocket.instances = []
@@ -152,6 +164,19 @@ beforeEach(() => {
 
 afterEach(() => {
   cleanup()
+  // Vitest keeps import.meta.hot truthy, so the boot effect's cleanup parks an
+  // open gateway instead of tearing it down (the real HMR path). Drain + close
+  // that survivor so the next test boots a fresh socket instead of adoptBoot().
+  const survivor = takeGatewaySurvivor()
+
+  if (survivor) {
+    try {
+      survivor.gateway.close()
+    } catch {
+      // ignore
+    }
+  }
+
   vi.useRealTimers()
   ;(globalThis as { WebSocket: unknown }).WebSocket = originalWebSocket
   delete (window as { hermesDesktop?: unknown }).hermesDesktop

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

@@ -40,6 +40,8 @@ import {
 import { $attentionSessionIds, $workingSessionIds, resetTileRuntimeBindings } from '@/store/session-states'
 import type { RpcEvent } from '@/types/hermes'
 
+import { stashGatewaySurvivor, survivorIsStale, takeGatewaySurvivor } from './gateway-hmr-survivor'
+
 // After this many consecutive failed reconnects (≈45s with the 1→15s backoff)
 // raise a recoverable boot error. Otherwise a dropped remote gateway loops the
 // backoff forever behind the fullscreen CONNECTING overlay with no way to reach
@@ -337,9 +339,28 @@ export function useGatewayBoot({
       progress: 6
     })
 
-    const gateway = new HermesGateway()
+    // HMR adoption: in a dev hot update, the previous effect instance parked its
+    // still-open socket instead of closing it (see the cleanup below). Re-adopt
+    // it so an edit doesn't drop the live agent session. A stale (closed) parked
+    // socket is discarded and we boot fresh. No-op in production: import.meta.hot
+    // is undefined there, so this folds to `null` and the whole survivor module
+    // dead-code-eliminates out of the bundle.
+    const survivor = import.meta.hot ? takeGatewaySurvivor() : null
+    const adoptedFromHmr = Boolean(survivor && !survivorIsStale(survivor))
+
+    if (survivor && !adoptedFromHmr) {
+      // Parked socket died between edits (e.g. backend restart) — release it.
+      try {
+        survivor.gateway.close()
+      } catch {
+        // ignore
+      }
+    }
+
+    const gateway = adoptedFromHmr ? survivor!.gateway : new HermesGateway()
+
     callbacksRef.current.onGatewayReady(gateway)
-    setPrimaryGateway(gateway, normalizeProfileKey($activeGatewayProfile.get()))
+    setPrimaryGateway(gateway, survivor?.profile ?? normalizeProfileKey($activeGatewayProfile.get()))
     // Secondary (background-profile) sockets funnel into the same handler.
     configureGatewayRegistry({ onEvent: event => callbacksRef.current.handleGatewayEvent(event) })
 
@@ -513,7 +534,42 @@ export function useGatewayBoot({
       }
     }
 
-    void boot()
+    // Adopt the parked socket without re-running the full boot handshake: the
+    // socket is already open, the backend session is untouched, and we already
+    // know the profile. We only re-publish the connection, re-sync config +
+    // sessions (cheap, and the backend may have moved on between edits), and
+    // dismiss any boot overlay. This is what keeps a live, mid-stream session
+    // intact across an HMR update.
+    async function adoptBoot() {
+      bootCompleted = true
+      completeDesktopBoot()
+
+      if (survivor?.connection) {
+        publish(survivor.connection)
+      }
+
+      const profile = survivor?.profile ?? $activeGatewayProfile.get()
+      $activeGatewayProfile.set(profile)
+      void ensureGatewayForProfile(profile)
+
+      // Mirror the current (already-open) socket state into the composer so the
+      // input doesn't sit disabled after the swap.
+      reportPrimaryGatewayState(gateway.connectionState)
+
+      await callbacksRef.current.refreshHermesConfig().catch(() => undefined)
+
+      if (cancelled) {
+        return
+      }
+
+      await callbacksRef.current.refreshSessions().catch(() => undefined)
+    }
+
+    if (adoptedFromHmr) {
+      void adoptBoot()
+    } else {
+      void boot()
+    }
 
     return () => {
       cancelled = true
@@ -532,6 +588,24 @@ export function useGatewayBoot({
       offExit()
       offWindowState?.()
       offBootProgress()
+
+      // HMR teardown vs. real unmount. On a hot update we must NOT close the
+      // socket — that's the whole bug. Detach this instance's listeners (their
+      // closures capture the disposed module), park the still-open gateway, and
+      // let the freshly loaded effect re-adopt it. Secondaries are owned by the
+      // gateway store (HMR-stable module state), so they survive untouched.
+      // Production: import.meta.hot is undefined, so this branch never runs and
+      // the original destructive teardown below is byte-for-byte preserved.
+      if (import.meta.hot && gateway.connectionState === 'open') {
+        stashGatewaySurvivor({
+          gateway,
+          profile: survivor?.profile ?? $activeGatewayProfile.get(),
+          connection: $connection.get()
+        })
+
+        return
+      }
+
       closeSecondaryGateways()
       gateway.close()
       publish(null)

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',
@@ -524,7 +526,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 +554,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 })
         }

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

@@ -501,27 +501,36 @@ export function useMessageStream({
             const existing = prev[index]
             const existingText = chatMessageText(existing).trim()
 
+            // The last assistant row is a sealed interim (a tool-call turn or a
+            // verify-on-stop candidate — `message.interim` fires for BOTH, see
+            // tui_gateway `_load_interim_assistant_messages`). When the final
+            // completion is the SAME turn's reply, settle it onto that interim
+            // instead of appending a second bubble. Continuity, not exact
+            // equality: streaming can drop characters and the final may add a
+            // trailing delta, so treat prefix-either-way as the same message.
+            // (mergeFinalAssistantText, via completeMessage, does the real
+            // text merge — replaces the interim's text with the full final.)
+            const finalContinuesInterim = Boolean(
+              existing.interim &&
+              finalText &&
+              existingText &&
+              (finalText === existingText || finalText.startsWith(existingText) || existingText.startsWith(finalText))
+            )
+
             if (existing.pending || (!interimBoundaryPending && finalText && existingText === finalText)) {
               nextMessages = prev.map((message, messageIndex) =>
                 messageIndex === index ? completeMessage(message) : message
               )
-            } else if (
-              interimBoundaryPending &&
-              responsePreviewed &&
-              finalText &&
-              existingText &&
-              finalText.startsWith(existingText)
-            ) {
-              // The verification candidate was published provisionally as an
-              // interim message and then reused as the terminal response
-              // (continuation-budget fallback). Settle the interim in place
-              // instead of creating a duplicate — the DB has one row, so the
-              // live UI must agree. (#65919 review: duplicate-message blocker)
-              //
-              // Prefix match (not exact equality): the final response may be
-              // the streamed text plus a trailing delta.  mergeFinalAssistantText
-              // (called via completeMessage) handles the actual merge — it
-              // strips the old text parts and appends the full final text.
+            } else if (interimBoundaryPending && (responsePreviewed || finalContinuesInterim)) {
+              // Settle the interim in place instead of creating a duplicate —
+              // the DB has one row, so the live UI must agree. Previously this
+              // was gated on `responsePreviewed` alone, so a NON-previewed
+              // tool-call turn whose final matched its sealed interim appended a
+              // second bubble (the "renders twice: partial first copy + clean
+              // final" bug, #63679). `finalContinuesInterim` closes that gap
+              // for ordinary tool-call turns while `responsePreviewed` still
+              // covers the verify-on-stop continuation-budget case even when the
+              // final text was rewritten and no longer shares a prefix.
               nextMessages = prev.map((message, messageIndex) =>
                 messageIndex === index ? completeMessage(message) : message
               )

apps/desktop/src/app/session/hooks/use-message-stream/interim-sealing.test.tsx

@@ -186,18 +186,51 @@ describe('useMessageStream interim text sealing', () => {
     expect(getState().interimBoundaryPending).toBe(true)
   })
 
-  it('keeps an identical final completion distinct from an interim reply without response_previewed', async () => {
+  it('settles an identical final onto a non-previewed interim (tool-call turn) instead of duplicating (#63679)', async () => {
     await mountStream()
     await start()
 
+    // A plain tool-call turn: the streamed text is sealed as an interim at the
+    // tool boundary (no response_previewed — that flag is only for verify-on-
+    // stop). The final completion is the SAME turn's reply. It must settle onto
+    // the interim, not append a second bubble — the DB has one row. This is the
+    // "renders twice" bug: partial streamed copy + clean final copy side by side.
     await interim('same reply')
     await complete('same reply')
 
-    // Without response_previewed, the interim and terminal replies are
-    // distinct messages — the gateway didn't signal that the final reuses
-    // the provisional candidate.
     const texts = assistantMessages()
-    expect(texts.filter(t => t === 'same reply')).toHaveLength(2)
+    expect(texts.filter(t => t === 'same reply')).toHaveLength(1)
+  })
+
+  it('settles a prefix-extended final onto a non-previewed interim (streamed + trailing delta)', async () => {
+    await mountStream()
+    await start()
+
+    // The stream dropped/settled early at the tool boundary; the final adds a
+    // trailing delta. Same turn — one bubble with the full final text.
+    await delta('partial')
+    await interim('partial')
+    await complete('partial answer continued')
+
+    const texts = assistantMessages()
+    expect(texts.filter(t => t.includes('partial'))).toHaveLength(1)
+    expect(texts[0]).toBe('partial answer continued')
+  })
+
+  it('appends a genuinely different final as its own bubble (two real assistant segments)', async () => {
+    await mountStream()
+    await start()
+
+    // The interim is one segment (pre-tool commentary); the final is different
+    // content, not a continuation of it. These are two real messages and must
+    // both render — the fix must not over-collapse distinct replies.
+    await interim('let me check the files')
+    await complete('the answer is 42')
+
+    const texts = assistantMessages()
+    expect(texts).toContain('let me check the files')
+    expect(texts).toContain('the answer is 42')
+    expect(texts).toHaveLength(2)
   })
 
   it('settles an identical final completion onto the interim when response_previewed', async () => {

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')
+  })
+})

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)
+  })
+})

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()
+    }
+  })
 })

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

@@ -993,6 +993,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 +1078,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 +1161,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 +1174,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"

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',

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

@@ -16,6 +16,7 @@ describe('MarkdownTextContent remote images', () => {
 
     throw new Error(`unexpected path ${path}`)
   })
+
   let originalDesktop: typeof window.hermesDesktop
 
   beforeEach(() => {

apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts

@@ -130,9 +130,7 @@ function readFileDisplayTarget(args: Record<string, unknown>, result: Record<str
 
 function shellCommand(args: Record<string, unknown>): string {
   return (
-    firstStringField(args, ['context', 'preview']) ||
-    firstStringField(args, ['command', 'code']) ||
-    contextValue(args)
+    firstStringField(args, ['context', 'preview']) || firstStringField(args, ['command', 'code']) || contextValue(args)
   )
 }
 
@@ -1389,8 +1387,11 @@ export function buildToolView(part: ToolPart, inlineDiff: string): ToolView {
 
   const searchHits =
     part.toolName === 'web_search' && status !== 'error' ? extractSearchResults(part.result) : undefined
+
   const searchQuery =
-    part.toolName === 'web_search' ? firstStringField(argsRecord, ['search_term', 'query']) || contextValue(argsRecord) : ''
+    part.toolName === 'web_search'
+      ? firstStringField(argsRecord, ['search_term', 'query']) || contextValue(argsRecord)
+      : ''
 
   const resultCount = status === 'error' ? null : toolResultCount(part, argsRecord, resultRecord)
 

apps/desktop/src/components/assistant-ui/tool/fallback.tsx

@@ -391,14 +391,14 @@ function ToolEntry({ part }: ToolEntryProps) {
 
   const hasExpandableContent = Boolean(
     view.imageUrl ||
-      view.inlineDiff ||
-      showDetail ||
-      hasSearchHits ||
-      view.stdout ||
-      view.stderr ||
-      view.terminalCommand ||
-      view.terminalExitCode !== undefined ||
-      toolViewMode === 'technical'
+    view.inlineDiff ||
+    showDetail ||
+    hasSearchHits ||
+    view.stdout ||
+    view.stderr ||
+    view.terminalCommand ||
+    view.terminalExitCode !== undefined ||
+    toolViewMode === 'technical'
   )
 
   // copyAction reads the uncapped view.detail; clampForDisplay below only bounds
@@ -649,7 +649,9 @@ function TerminalTranscript({ command, exitCode }: TerminalTranscriptProps) {
     <div className="flex min-w-0 items-center gap-2 rounded-[0.25rem] border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-2 py-1.5 font-mono text-[0.7rem] leading-relaxed">
       {command && (
         <code className="min-w-0 flex-1 whitespace-pre-wrap wrap-anywhere text-(--ui-text-secondary)">
-          <span aria-hidden className="select-none text-(--ui-accent-secondary)">$ </span>
+          <span aria-hidden className="select-none text-(--ui-accent-secondary)">
+            ${' '}
+          </span>
           {command}
         </code>
       )}

apps/desktop/src/components/notifications.tsx

@@ -215,9 +215,7 @@ function NotificationItem({ notification }: { notification: AppNotification }) {
         {notification.title && <AlertTitle className="col-start-auto">{notification.title}</AlertTitle>}
         <AlertDescription className="col-start-auto">
           <p className="m-0">{renderMessage(notification.message, accent)}</p>
-          {notification.meta && (
-            <p className="m-0 text-xs text-muted-foreground tabular-nums">{notification.meta}</p>
-          )}
+          {notification.meta && <p className="m-0 text-xs text-muted-foreground tabular-nums">{notification.meta}</p>}
           {hasDetail && <NotificationDetail detail={notification.detail || ''} />}
           {notification.action && (
             <Button

apps/desktop/src/i18n/en.ts

@@ -132,6 +132,7 @@ export const en: Translations = {
     errors: {
       elevenLabsNeedsKey: 'ElevenLabs STT needs ELEVENLABS_API_KEY.',
       elevenLabsRejectedKey: 'ElevenLabs rejected the API key (401).',
+      gatewayAuthFailed: 'Gateway authentication failed — check your API_SERVER_KEY.',
       methodNotAllowed:
         'The desktop backend rejected that request (405 Method Not Allowed). Try restarting Hermes Desktop.',
       microphonePermission: 'Microphone permission was denied.',

apps/desktop/src/i18n/ja.ts

@@ -133,6 +133,7 @@ export const ja = defineLocale({
     errors: {
       elevenLabsNeedsKey: 'ElevenLabs STT には ELEVENLABS_API_KEY が必要です。',
       elevenLabsRejectedKey: 'ElevenLabs が API キーを拒否しました (401)。',
+      gatewayAuthFailed: 'ゲートウェイ認証に失敗しました — API_SERVER_KEY を確認してください。',
       methodNotAllowed:
         'デスクトップバックエンドがそのリクエストを拒否しました (405 Method Not Allowed)。Hermes Desktop を再起動してください。',
       microphonePermission: 'マイクのアクセス許可が拒否されました。',

apps/desktop/src/i18n/types.ts

@@ -173,6 +173,7 @@ export interface Translations {
     errors: {
       elevenLabsNeedsKey: string
       elevenLabsRejectedKey: string
+      gatewayAuthFailed: string
       methodNotAllowed: string
       microphonePermission: string
       openaiRejectedApiKey: string

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

@@ -129,6 +129,7 @@ export const zhHant = defineLocale({
     errors: {
       elevenLabsNeedsKey: 'ElevenLabs STT 需要 ELEVENLABS_API_KEY。',
       elevenLabsRejectedKey: 'ElevenLabs 拒絕了該 API 金鑰 (401)。',
+      gatewayAuthFailed: '閘道認證失敗 — 請檢查你的 API_SERVER_KEY。',
       methodNotAllowed: '桌面後端拒絕了該請求 (405 Method Not Allowed)。請嘗試重新啟動 Hermes Desktop。',
       microphonePermission: '麥克風權限已被拒絕。',
       openaiRejectedApiKey: 'OpenAI 拒絕了該 API 金鑰。',

apps/desktop/src/i18n/zh.ts

@@ -129,6 +129,7 @@ export const zh: Translations = {
     errors: {
       elevenLabsNeedsKey: 'ElevenLabs STT 需要 ELEVENLABS_API_KEY。',
       elevenLabsRejectedKey: 'ElevenLabs 拒绝了该 API key (401)。',
+      gatewayAuthFailed: '网关认证失败 — 请检查你的 API_SERVER_KEY。',
       methodNotAllowed: '桌面后端拒绝了该请求 (405 Method Not Allowed)。请尝试重启 Hermes Desktop。',
       microphonePermission: '麦克风权限已被拒绝。',
       openaiRejectedApiKey: 'OpenAI 拒绝了该 API key。',

apps/desktop/src/lib/chat-messages.test.ts

@@ -158,6 +158,39 @@ describe('toChatMessages', () => {
 
     expect(chatMessageText(message)).toBe('@file:foo.ts\n\nlook')
   })
+
+  it('projects durable timeline kinds without inspecting their text', () => {
+    const messages = toChatMessages([
+      { role: 'user', content: 'real user turn', timestamp: 1 },
+      { role: 'assistant', content: 'real assistant reply', timestamp: 2 },
+      {
+        role: 'user',
+        content: 'opaque compaction payload',
+        display_kind: 'hidden',
+        timestamp: 3
+      },
+      {
+        role: 'user',
+        content: 'opaque model context payload',
+        display_kind: 'model_switch',
+        timestamp: 4
+      },
+      {
+        role: 'user',
+        content: 'opaque delegation context payload',
+        display_kind: 'async_delegation_complete',
+        timestamp: 5
+      }
+    ])
+
+    expect(messages.map(message => message.role)).toEqual(['user', 'assistant', 'system', 'system'])
+    expect(messages.map(chatMessageText)).toEqual([
+      'real user turn',
+      'real assistant reply',
+      'model changed',
+      'background agent work finished'
+    ])
+  })
 })
 
 describe('renderMediaTags', () => {
@@ -558,7 +591,8 @@ describe('upsertToolPart', () => {
     )
 
     const terminalParts = completed.filter(
-      (part): part is Extract<ChatMessagePart, { type: 'tool-call' }> => part.type === 'tool-call' && part.toolName === 'terminal'
+      (part): part is Extract<ChatMessagePart, { type: 'tool-call' }> =>
+        part.type === 'tool-call' && part.toolName === 'terminal'
     )
 
     expect(terminalParts).toHaveLength(1)
@@ -941,10 +975,7 @@ describe('collectUnspokenTurnSpeech', () => {
   })
 
   it('reports pending from the newest assistant bubble even when it has no text yet', () => {
-    const messages = [
-      assistant('a1', 'Narration done.', { interim: true }),
-      assistant('a2', '', { pending: true })
-    ]
+    const messages = [assistant('a1', 'Narration done.', { interim: true }), assistant('a2', '', { pending: true })]
 
     const speech = collectUnspokenTurnSpeech(messages, null)
 

apps/desktop/src/lib/chat-messages.ts

@@ -94,6 +94,10 @@ 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
@@ -170,7 +174,10 @@ export interface UnspokenTurnSpeech {
  * join is a sentence boundary for the server's cutter, so a sealed bubble's
  * tail is flushed as soon as the next bubble starts.
  */
-export function collectUnspokenTurnSpeech(messages: ChatMessage[], lastSpokenId: string | null): UnspokenTurnSpeech | null {
+export function collectUnspokenTurnSpeech(
+  messages: ChatMessage[],
+  lastSpokenId: string | null
+): UnspokenTurnSpeech | null {
   const spokenIndex = lastSpokenId ? messages.findLastIndex(m => m.id === lastSpokenId) : -1
 
   let id: string | null = null
@@ -300,6 +307,29 @@ function displayContentForMessage(role: SessionMessage['role'], content: unknown
   return [refs.join('\n'), visibleText].filter(Boolean).join('\n\n') || visibleText
 }
 
+function transcriptContent(displayKind: SessionMessage['display_kind'], content: string): string | null {
+  return displayKind === 'hidden' ? null : content
+}
+
+function timelineDisplayContent(message: SessionMessage, content: string): string {
+  if (message.display_kind === 'model_switch') {
+    return 'model changed'
+  }
+
+  if (message.display_kind === 'async_delegation_complete') {
+    const count =
+      message.display_metadata && 'task_count' in message.display_metadata
+        ? message.display_metadata.task_count
+        : undefined
+
+    return count === undefined
+      ? 'background agent work finished'
+      : `${count} background agent${count === 1 ? '' : 's'} finished`
+  }
+
+  return content
+}
+
 const STREAM_PART: Record<'reasoning' | 'text', (text: string) => ChatMessagePart> = {
   reasoning: reasoningPart,
   text: textPart
@@ -881,7 +911,17 @@ export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
     }
 
     const content = message.content || message.text || message.context || message.name
-    const displayContent = displayContentForMessage(message.role, content)
+
+    const displayContent = transcriptContent(
+      message.display_kind,
+      timelineDisplayContent(message, displayContentForMessage(message.role, content))
+    )
+
+    const displayRole =
+      message.display_kind === 'model_switch' || message.display_kind === 'async_delegation_complete'
+        ? 'system'
+        : message.role
+
     const parts: ChatMessagePart[] = []
 
     const reasoning =
@@ -894,7 +934,7 @@ export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
     }
 
     if (displayContent) {
-      parts.push(message.role === 'assistant' ? assistantTextPart(displayContent) : textPart(displayContent))
+      parts.push(displayRole === 'assistant' ? assistantTextPart(displayContent) : textPart(displayContent))
     }
 
     if (message.role === 'assistant' && Array.isArray(message.tool_calls)) {
@@ -948,8 +988,8 @@ export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
     }
 
     result.push({
-      id: `${message.timestamp || Date.now()}-${index}-${message.role}`,
-      role: message.role,
+      id: `${message.timestamp || Date.now()}-${index}-${displayRole}`,
+      role: displayRole,
       parts,
       timestamp: message.timestamp
     })

apps/desktop/src/store/agent-notices.test.ts

@@ -52,7 +52,14 @@ test('sticky notices never auto-dismiss', () => {
 })
 
 test('ttl notice carries its ttl_ms as the duration', () => {
-  const toast = noticeToToast({ key: 'credits.restored', kind: 'ttl', level: 'success', text: '✓ restored', ttl_ms: 8000 })
+  const toast = noticeToToast({
+    key: 'credits.restored',
+    kind: 'ttl',
+    level: 'success',
+    text: '✓ restored',
+    ttl_ms: 8000
+  })
+
   expect(toast?.durationMs).toBe(8000)
 })
 
@@ -118,8 +125,12 @@ test('usageFraction derives $used / $cap from the notice text', () => {
 test('usage accent stays muted below 75%, then ramps orange → red', () => {
   expect(noticeAccent(usage({ text: "• You've used $10.00 of your $20.00 cap" }))).toBeUndefined() // 50%
   expect(noticeAccent(usage({ text: "• You've used $14.80 of your $20.00 cap" }))).toBeUndefined() // 74%
-  expect(noticeAccent(usage({ level: 'warn', text: "⚠ You've used $15.00 of your $20.00 cap" }))).toBe('var(--ui-orange)') // 75%
-  expect(noticeAccent(usage({ level: 'warn', text: "⚠ You've used $17.80 of your $20.00 cap" }))).toBe('var(--ui-orange)') // 89%
+  expect(noticeAccent(usage({ level: 'warn', text: "⚠ You've used $15.00 of your $20.00 cap" }))).toBe(
+    'var(--ui-orange)'
+  ) // 75%
+  expect(noticeAccent(usage({ level: 'warn', text: "⚠ You've used $17.80 of your $20.00 cap" }))).toBe(
+    'var(--ui-orange)'
+  ) // 89%
   expect(noticeAccent(usage({ level: 'warn', text: "⚠ You've used $18.00 of your $20.00 cap" }))).toBe('var(--ui-red)') // 90%
   expect(noticeAccent(usage({ level: 'warn', text: "⚠ You've used $20.00 of your $20.00 cap" }))).toBe('var(--ui-red)') // 100%
 })

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

@@ -2,17 +2,33 @@ import { afterEach, describe, expect, it } from 'vitest'
 
 import {
   $composerAttachments,
+  $voiceConversationStartRequest,
   addComposerAttachment,
   clearSessionDraft,
   type ComposerAttachment,
   migrateSessionDraft,
   removeComposerAttachment,
+  requestVoiceConversationStart,
   SESSION_DRAFTS_STORAGE_KEY,
   stashSessionDraft,
   takeSessionDraft,
+  takeVoiceConversationStart,
   updateComposerAttachment
 } from './composer'
 
+describe('voice conversation start requests', () => {
+  it('latches each request until the main composer consumes it once', () => {
+    requestVoiceConversationStart()
+    const first = $voiceConversationStartRequest.get()
+
+    expect(takeVoiceConversationStart(first)).toBe(true)
+    expect(takeVoiceConversationStart(first)).toBe(false)
+
+    requestVoiceConversationStart()
+    expect(takeVoiceConversationStart($voiceConversationStartRequest.get())).toBe(true)
+  })
+})
+
 function attachment(overrides: Partial<ComposerAttachment> & Pick<ComposerAttachment, 'id'>): ComposerAttachment {
   return { kind: 'file', label: 'doc.pdf', ...overrides }
 }

apps/desktop/src/store/composer.ts

@@ -21,6 +21,24 @@ export const $composerDraft = atom('')
 export const $composerAttachments = atom<ComposerAttachment[]>([])
 export const $composerTerminalSelections = atom<Record<string, string>>({})
 
+// Latched because opening a fresh session may remount the main composer before
+// it can start voice. Session-tile composers deliberately never consume this.
+export const $voiceConversationStartRequest = atom(0)
+let nextVoiceStartRequest = 0
+let handledVoiceStartRequest = 0
+
+export const requestVoiceConversationStart = (): void => $voiceConversationStartRequest.set(++nextVoiceStartRequest)
+
+export const takeVoiceConversationStart = (current: number): boolean => {
+  if (current <= handledVoiceStartRequest) {
+    return false
+  }
+
+  handledVoiceStartRequest = current
+
+  return true
+}
+
 // ---------------------------------------------------------------------------
 // Composer scopes — one live attachment set PER MOUNTED COMPOSER. The main
 // chat's scope wraps the module-level atom above (all existing readers keep
@@ -93,29 +111,6 @@ export function createComposerAttachmentScope($attachments = atom<ComposerAttach
  *  `$composerAttachments` reader/writer IS this scope. */
 export const mainComposerScope = createComposerAttachmentScope($composerAttachments)
 
-// Latched "start a voice conversation" request (the "Hey Hermes" wake word).
-// A nanostore, not a fire-once window event, because the wake handler opens a
-// fresh session first — the composer may remount before it can observe the
-// intent. The composer reads the current value on (re)mount and consumes it
-// once it's ready (gateway open). Module-level _voiceStartHandled tracks the
-// last consumed id so a remount doesn't re-trigger or miss a just-set request.
-export const $voiceConversationStartRequest = atom(0)
-let _voiceStartHandled = 0
-
-export const requestVoiceConversationStart = (): void =>
-  $voiceConversationStartRequest.set(Date.now())
-
-/** Returns true exactly once per new request id (claims it). */
-export const takeVoiceConversationStart = (current: number): boolean => {
-  if (current > _voiceStartHandled) {
-    _voiceStartHandled = current
-
-    return true
-  }
-
-  return false
-}
-
 // Per-thread draft stash for the decoupled composer. Session lifecycle never
 // touches this — only ChatBar's scope swap reads/writes it. Text mirrors to
 // localStorage; attachments are memory-only (blobs, upload state).

apps/desktop/src/store/gateway.ts

@@ -20,41 +20,10 @@ const normKey = (profile: string | null | undefined): string => (profile ?? '').
 // narrow the getter to a constant across guards (it genuinely changes).
 const isOpen = (gateway: HermesGateway | null): boolean => gateway?.connectionState === 'open'
 
-// The active gateway instance, exposed for inline message-stream components
-// (e.g. inline ClarifyTool, model overlays) that call gateway methods without
-// the instance threaded down through props.
-export const $gateway = atom<HermesGateway | null>(null)
-
 interface RegistryConfig {
   onEvent: (event: GatewayEvent) => void
 }
 
-let config: RegistryConfig | null = null
-
-export function configureGatewayRegistry(cfg: RegistryConfig): void {
-  config = cfg
-}
-
-/**
- * Feed a synthetic event through the exact same fan-out a real socket frame
- * takes (`config.onEvent` → the desktop's `handleGatewayEvent`). Used by
- * dev-only tooling to exercise the real event branches (e.g. the credit-notice
- * demo) without a backend that can produce the event on demand. No-op until a
- * registry is configured.
- */
-export function emitLocalGatewayEvent(event: GatewayEvent): void {
-  config?.onEvent(event)
-}
-
-// ── Primary (window) backend ───────────────────────────────────────────────
-let primaryGateway: HermesGateway | null = null
-let primaryProfile = 'default'
-
-export function setPrimaryGateway(gateway: HermesGateway | null, profile = 'default'): void {
-  primaryGateway = gateway
-  primaryProfile = normKey(profile)
-}
-
 // ── Secondary (pool) backends ──────────────────────────────────────────────
 interface Secondary {
   profile: string
@@ -69,20 +38,97 @@ interface Secondary {
   wantOpen: boolean
 }
 
-const secondaries = new Map<string, Secondary>()
+// ── HMR-stable module state ─────────────────────────────────────────────────
+// All mutable singletons (live sockets, active-profile routing, the event
+// registry) live in ONE container parked on globalThis, NOT in module-level
+// `let`/`const` bindings. Reason: this module is imported widely without an HMR
+// boundary that accepts it, so editing it (or anything that fans out to it)
+// makes Vite issue a FULL PAGE RELOAD — which would kill every live socket and
+// drop the agent session on an unrelated edit. Persisting the state on
+// globalThis + self-accepting HMR (bottom of file) turns that full reload into
+// an in-place hot update that preserves the sockets. Production strips
+// import.meta.hot, and a fresh page realm starts with an empty container, so the
+// runtime behavior is identical to plain module state.
+interface GatewayRegistryState {
+  config: RegistryConfig | null
+  primaryGateway: HermesGateway | null
+  primaryProfile: string
+  activeKey: string
+  secondaries: Map<string, Secondary>
+  $gateway: ReturnType<typeof atom<HermesGateway | null>>
+}
 
-let activeKey = 'default'
+const STATE_KEY = Symbol.for('hermes.desktop.gatewayRegistryState')
+
+function createRegistryState(): GatewayRegistryState {
+  return {
+    config: null,
+    primaryGateway: null,
+    primaryProfile: 'default',
+    activeKey: 'default',
+    secondaries: new Map<string, Secondary>(),
+    // The active gateway instance, exposed for inline message-stream
+    // components (inline ClarifyTool, model overlays) that call gateway
+    // methods without the instance threaded down through props.
+    $gateway: atom<HermesGateway | null>(null)
+  }
+}
+
+// Dev only: park the singletons on globalThis so an HMR re-eval of this module
+// (self-accepted at the bottom) hands back the SAME live sockets/atoms instead
+// of resetting them — that's what keeps the agent session alive across UI edits.
+// `import.meta.hot` is undefined in production, so Vite dead-code-eliminates the
+// entire globalThis branch and prod uses a plain module-local singleton — no
+// globalThis, no Symbol.for. Both realms load the module once, so the container's
+// shape and lifetime are identical either way.
+function gatewayState(): GatewayRegistryState {
+  if (import.meta.hot) {
+    const store = globalThis as unknown as { [STATE_KEY]?: GatewayRegistryState }
+    store[STATE_KEY] ??= createRegistryState()
+
+    return store[STATE_KEY]
+  }
+
+  return createRegistryState()
+}
+
+const g = gatewayState()
+
+// Re-exported as a stable binding: the atom instance lives in `g`, so every hot
+// reload of this module hands back the SAME atom subscribers are already wired
+// to. (A fresh `atom()` per reload would orphan existing subscriptions.)
+export const $gateway = g.$gateway
+
+export function configureGatewayRegistry(cfg: RegistryConfig): void {
+  g.config = cfg
+}
+
+/**
+ * Feed a synthetic event through the exact same fan-out a real socket frame
+ * takes (`config.onEvent` → the desktop's `handleGatewayEvent`). Used by
+ * dev-only tooling to exercise the real event branches (e.g. the credit-notice
+ * demo) without a backend that can produce the event on demand. No-op until a
+ * registry is configured.
+ */
+export function emitLocalGatewayEvent(event: GatewayEvent): void {
+  g.config?.onEvent(event)
+}
+
+export function setPrimaryGateway(gateway: HermesGateway | null, profile = 'default'): void {
+  g.primaryGateway = gateway
+  g.primaryProfile = normKey(profile)
+}
 
 export function isActivePrimary(): boolean {
-  return activeKey === primaryProfile
+  return g.activeKey === g.primaryProfile
 }
 
 export function activeGateway(): HermesGateway | null {
-  if (activeKey === primaryProfile) {
-    return primaryGateway
+  if (g.activeKey === g.primaryProfile) {
+    return g.primaryGateway
   }
 
-  return secondaries.get(activeKey)?.gateway ?? primaryGateway
+  return g.secondaries.get(g.activeKey)?.gateway ?? g.primaryGateway
 }
 
 // Mirror a backend's connection state into the global composer state, but only
@@ -90,19 +136,19 @@ export function activeGateway(): HermesGateway | null {
 // composer reflect the active profile's socket without a background reconnect
 // flipping the foreground enabled/disabled state.
 function reportGatewayState(profile: string, state: ConnectionState): void {
-  if (normKey(profile) === activeKey) {
+  if (normKey(profile) === g.activeKey) {
     setGatewayState(state)
   }
 }
 
 export function reportPrimaryGatewayState(state: ConnectionState): void {
-  reportGatewayState(primaryProfile, state)
+  reportGatewayState(g.primaryProfile, state)
 }
 
 function setActive(profile: string): void {
-  activeKey = normKey(profile)
+  g.activeKey = normKey(profile)
   const gateway = activeGateway()
-  $gateway.set(gateway)
+  g.$gateway.set(gateway)
   setGatewayState(gateway?.connectionState ?? 'closed')
 }
 
@@ -175,7 +221,7 @@ function createSecondary(profile: string): Secondary {
     wantOpen: true
   }
 
-  entry.offEvent = gateway.onEvent(event => config?.onEvent({ ...event, profile }))
+  entry.offEvent = gateway.onEvent(event => g.config?.onEvent({ ...event, profile }))
   entry.offState = gateway.onState(state => {
     reportGatewayState(profile, state)
 
@@ -187,7 +233,7 @@ function createSecondary(profile: string): Secondary {
     }
   })
 
-  secondaries.set(profile, entry)
+  g.secondaries.set(profile, entry)
 
   return entry
 }
@@ -201,11 +247,11 @@ function createSecondary(profile: string): Secondary {
 export async function openGatewayForProfile(profile: string): Promise<void> {
   const key = normKey(profile)
 
-  if (key === primaryProfile) {
+  if (key === g.primaryProfile) {
     return
   }
 
-  const entry = secondaries.get(key) ?? createSecondary(key)
+  const entry = g.secondaries.get(key) ?? createSecondary(key)
   entry.wantOpen = true
 
   if (!isOpen(entry.gateway)) {
@@ -218,13 +264,13 @@ export async function openGatewayForProfile(profile: string): Promise<void> {
 export async function ensureGatewayForProfile(profile: string): Promise<void> {
   const key = normKey(profile)
 
-  if (key === primaryProfile) {
+  if (key === g.primaryProfile) {
     setActive(key)
 
     return
   }
 
-  let entry = secondaries.get(key)
+  let entry = g.secondaries.get(key)
 
   if (!entry) {
     entry = createSecondary(key)
@@ -249,11 +295,11 @@ export async function ensureGatewayForProfile(profile: string): Promise<void> {
 // Reconnect the active gateway after a transient request failure. Primary
 // reconnects are owned by use-gateway-boot, so we only drive secondaries here.
 export async function ensureActiveGatewayOpen(): Promise<HermesGateway | null> {
-  if (activeKey === primaryProfile) {
-    return primaryGateway
+  if (g.activeKey === g.primaryProfile) {
+    return g.primaryGateway
   }
 
-  const entry = secondaries.get(activeKey)
+  const entry = g.secondaries.get(g.activeKey)
 
   if (!entry) {
     return null
@@ -268,7 +314,7 @@ export async function ensureActiveGatewayOpen(): Promise<HermesGateway | null> {
 
 // Wake signal (sleep/network/visibility): nudge every live secondary back open.
 export function reconnectSecondaryGateways(): void {
-  for (const entry of secondaries.values()) {
+  for (const entry of g.secondaries.values()) {
     if (!entry.wantOpen || isOpen(entry.gateway)) {
       continue
     }
@@ -284,38 +330,47 @@ export function reconnectSecondaryGateways(): void {
 export function touchSecondaryGateways(): void {
   const desktop = window.hermesDesktop
 
-  for (const entry of secondaries.values()) {
+  for (const entry of g.secondaries.values()) {
     if (entry.wantOpen) {
       void desktop?.touchBackend?.(entry.profile).catch(() => undefined)
     }
   }
 }
 
+// Tear a secondary down: stop its reconnect loop, detach listeners, close the
+// socket. Caller handles removal from the map.
+function disposeSecondary(entry: Secondary): void {
+  entry.wantOpen = false
+  clearTimer(entry)
+  entry.offEvent()
+  entry.offState()
+  entry.gateway.close()
+}
+
 // Close + evict secondaries whose profile is neither active nor in `keep`
 // (profiles with a running / needs-input session). Bounds cost to live work.
 export function pruneSecondaryGateways(keep: Set<string>): void {
-  for (const [key, entry] of [...secondaries]) {
-    if (key === activeKey || keep.has(key)) {
+  for (const [key, entry] of [...g.secondaries]) {
+    if (key === g.activeKey || keep.has(key)) {
       continue
     }
 
-    entry.wantOpen = false
-    clearTimer(entry)
-    entry.offEvent()
-    entry.offState()
-    entry.gateway.close()
-    secondaries.delete(key)
+    disposeSecondary(entry)
+    g.secondaries.delete(key)
   }
 }
 
 export function closeSecondaryGateways(): void {
-  for (const entry of secondaries.values()) {
-    entry.wantOpen = false
-    clearTimer(entry)
-    entry.offEvent()
-    entry.offState()
-    entry.gateway.close()
+  for (const entry of g.secondaries.values()) {
+    disposeSecondary(entry)
   }
 
-  secondaries.clear()
+  g.secondaries.clear()
+}
+
+// Self-accept so editing this module (or a fan-out that lands here) is an
+// in-place hot update instead of a full page reload — the live sockets in `g`
+// survive the swap. Dev-only: production strips import.meta.hot.
+if (import.meta.hot) {
+  import.meta.hot.accept()
 }

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

@@ -0,0 +1,34 @@
+import { beforeEach, expect, test } from 'vitest'
+
+import { $notifications, clearNotifications, notifyError } from './notifications'
+
+beforeEach(() => {
+  clearNotifications()
+})
+
+function lastMessage(): string {
+  return $notifications.get()[0]?.message ?? ''
+}
+
+// Regression for #39365: a gateway auth 401 (bad API_SERVER_KEY) must not be
+// summarized as a provider (OpenAI/OpenRouter) API key problem.
+test('gateway_auth_failed error is summarized as gateway auth, not provider key', () => {
+  notifyError(
+    new Error(
+      '401 {"error": {"message": "Invalid gateway API key (API_SERVER_KEY)", "type": "gateway_auth_error", "code": "gateway_auth_failed"}}'
+    ),
+    'Request failed'
+  )
+
+  expect(lastMessage()).toContain('API_SERVER_KEY')
+  expect(lastMessage()).not.toMatch(/OpenAI/i)
+})
+
+test('provider invalid_api_key error still maps to the OpenAI summary', () => {
+  notifyError(
+    new Error('401 {"error": {"message": "Incorrect API key provided", "code": "invalid_api_key"}}'),
+    'Request failed'
+  )
+
+  expect(lastMessage()).toMatch(/OpenAI rejected the API key/i)
+})

apps/desktop/src/store/notifications.ts

@@ -77,6 +77,10 @@ function cleanErrorText(value: string) {
 }
 
 const ERROR_SUMMARIES: { test: (msg: string) => boolean; summarize: (msg: string) => string }[] = [
+  {
+    test: msg => /['"]code['"]\s*:\s*['"]gateway_auth_failed['"]/i.test(msg),
+    summarize: () => translateNow('notifications.errors.gatewayAuthFailed')
+  },
   {
     test: msg => /incorrect api key provided/i.test(msg) || /['"]code['"]\s*:\s*['"]invalid_api_key['"]/i.test(msg),
     summarize: msg => {

apps/desktop/src/types/hermes.ts

@@ -423,6 +423,16 @@ export interface SessionInfo {
   is_default_profile?: boolean
 }
 
+export type TimelineDisplayMetadata =
+  | { model: string; provider?: string }
+  | {
+      delegation_id: string
+      task_count: number
+      completed_count?: number
+      failed_count?: number
+      duration_seconds?: number
+    }
+
 export interface SessionMessage {
   codex_reasoning_items?: unknown
   content: unknown
@@ -431,6 +441,8 @@ export interface SessionMessage {
   reasoning?: null | string
   reasoning_content?: null | string
   reasoning_details?: unknown
+  display_kind?: 'async_delegation_complete' | 'hidden' | 'model_switch' | string
+  display_metadata?: TimelineDisplayMetadata
   role: 'assistant' | 'system' | 'tool' | 'user'
   text?: unknown
   timestamp?: number
@@ -987,6 +999,7 @@ export interface MoaModelSlot {
   model: string
   /** Optional per-slot reasoning effort — round-tripped, not edited here. */
   reasoning_effort?: string
+  enabled?: boolean
 }
 
 export interface MoaConfigResponse {
@@ -997,22 +1010,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 {

apps/shared/package.json

@@ -16,7 +16,7 @@
     "lint:fix": "eslint src/ --fix",
     "fix": "npm run lint:fix",
     "typecheck": "tsc -p . --noEmit",
-    "check": "npm run typecheck"
+    "check": "npm run typecheck && npm run lint"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

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

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)
@@ -983,6 +984,7 @@ def _cleanup_all_browsers(*args, **kwargs):
 
 # Guard to prevent cleanup from running multiple times on exit
 _cleanup_done = False
+_cli_wake_owner = None
 # One-shot CLI finalization runs before process cleanup so plugins can observe
 # the session boundary while the agent is still attached. If a signal lands in
 # that narrow window, atexit cleanup must not emit that session finalize again.
@@ -1178,7 +1180,8 @@ def _run_cleanup(*, notify_session_finalize: bool = True):
 
     try:
         from tools.wake_word import stop_listening as _stop_wake_word
-        _stop_wake_word()
+        if _cli_wake_owner is not None:
+            _stop_wake_word(owner=_cli_wake_owner)
     except Exception:
         pass
     try:
@@ -1749,6 +1752,66 @@ def _worktree_is_dirty(worktree_path: str, timeout: int = 10) -> bool:
         return True
 
 
+def _worktree_commits_all_merged_upstream(
+    worktree_path: str, timeout: int = 30, max_ahead: int = 20
+) -> bool:
+    """Return whether every local-only commit is patch-equivalent to a commit
+    already on the default upstream branch.
+
+    The dominant ``.worktrees/`` leak: a branch is pushed, its PR is
+    squash-merged (or cherry-picked), and the remote branch is deleted. The
+    local commits are then unreachable from ``refs/remotes/*`` forever, so the
+    unpushed-commits guard preserves the worktree indefinitely even though its
+    content is fully merged. ``git cherry`` detects patch-equivalence, letting
+    the pruner reap these.
+
+    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).
+    """
+    import subprocess
+
+    base = None
+    for candidate in ("origin/HEAD", "origin/main", "origin/master"):
+        try:
+            probe = subprocess.run(
+                ["git", "rev-parse", "--verify", "--quiet", candidate],
+                capture_output=True, text=True, timeout=timeout, cwd=worktree_path,
+            )
+            if probe.returncode == 0 and probe.stdout.strip():
+                base = candidate
+                break
+        except Exception:
+            return False
+    if base is None:
+        return False
+
+    try:
+        ahead = subprocess.run(
+            ["git", "rev-list", "--count", f"{base}..HEAD"],
+            capture_output=True, text=True, timeout=timeout, cwd=worktree_path,
+        )
+        if ahead.returncode != 0:
+            return False
+        count = int(ahead.stdout.strip() or "0")
+        if count == 0:
+            return True
+        if count > max_ahead:
+            return False
+
+        cherry = subprocess.run(
+            ["git", "cherry", base, "HEAD"],
+            capture_output=True, text=True, 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)
+    except Exception:
+        return False
+
+
 def _worktree_lock_is_live(repo_root: str, worktree_path: str, timeout: int = 10):
     """Classify a worktree's git lock as live, dead, or absent.
 
@@ -1955,11 +2018,21 @@ def _run_checkpoint_auto_maintenance() -> None:
 def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
     """Remove stale worktrees and orphaned branches on startup.
 
-    Age-based tiers (aggressive cleanup keeps ``.worktrees/`` from growing
-    unbounded):
-    - Under max_age_hours (24h): skip — session may still be active.
-    - 24h–72h: remove if no unpushed commits.
-    - Over 72h: force remove regardless (nothing should sit this long).
+    Covers EVERY directory under ``.worktrees/`` except kanban task trees
+    (``t_<hex>`` — owned by the kanban dispatcher's own gc). Scratch trees
+    created by ``hermes -w`` (``hermes-*``) age out fast; named trees created
+    manually for salvage/review lanes age out on a slower schedule:
+
+    - ``hermes-*``: skip under 24h; reap 24h+ when clean and merged/pushed;
+      72h+ is the aggressive tier (still never deletes real work).
+    - named trees: same logic at 3x the timeline (72h soft / 9d hard).
+
+    Work-preservation guards (all tiers, any age):
+    - uncommitted changes (dirty) — never removed;
+    - unpushed commits — never removed, UNLESS every local-only commit is
+      patch-equivalent to a commit already on upstream (``git cherry``): the
+      squash-merged-PR case, which is the dominant ``.worktrees/`` leak since
+      those commits stay unreachable from ``refs/remotes/*`` forever.
 
     Lock handling (orthogonal to age): ``hermes -w`` locks each worktree with
     reason ``hermes pid=<pid>`` so a concurrent hermes process leaves an in-use
@@ -1972,9 +2045,14 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
     removal never orphans the branch (which would drop easy reachability of any
     commits still in the worktree).
 
+    Preserved-work visibility: trees skipped for unpushed/dirty reasons that
+    are older than 7 days are listed in a single WARNING so real in-flight
+    work can't rot silently.
+
     Also prunes orphaned ``hermes/*`` and ``pr-*`` local branches that
     have no corresponding worktree.
     """
+    import re
     import subprocess
     import time
 
@@ -1984,13 +2062,23 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
         return
 
     now = time.time()
-    soft_cutoff = now - (max_age_hours * 3600)       # 24h default
-    hard_cutoff = now - (max_age_hours * 3 * 3600)   # 72h default
+    stale_work_cutoff = now - (7 * 24 * 3600)
+    preserved_stale: list = []
+    # Kanban task worktrees (<repo>/.worktrees/t_<hex>) have their own
+    # 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():
-        if not entry.is_dir() or not entry.name.startswith("hermes-"):
+        if not entry.is_dir() or kanban_re.match(entry.name):
             continue
 
+        # Scratch trees (hermes-*) age out on the default schedule; named
+        # trees (salvage/review lanes someone created deliberately) get 3x.
+        scratch = entry.name.startswith("hermes-")
+        tier_hours = max_age_hours if scratch else max_age_hours * 3
+        soft_cutoff = now - (tier_hours * 3600)
+        hard_cutoff = now - (tier_hours * 3 * 3600)
+
         # Check age
         try:
             mtime = entry.stat().st_mtime
@@ -1999,19 +2087,24 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
         except Exception:
             continue
 
-        force = mtime <= hard_cutoff  # Over 72h — reap aggressively
+        force = mtime <= hard_cutoff  # Aggressive tier — reap clean trees
 
-        # Never delete real work, regardless of age. Unpushed commits and
-        # uncommitted changes may be a crashed session's in-flight work; the
-        # >72h tier reaps only abandoned *clean, fully-pushed* worktrees (the
-        # scratch trees that actually cause .worktrees/ bloat).
+        # 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
         if _worktree_has_unpushed_commits(str(entry), timeout=5):
-            continue  # Has unpushed commits or can't check — skip
-        if not force:
-            # 24h–72h tier is conservative: unpushed check above is enough.
-            pass
-        elif _worktree_is_dirty(str(entry), timeout=5):
-            continue  # >72h but dirty — preserve uncommitted work
+            # 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
 
         # Respect git-native session locks. A lock owned by a still-running
         # hermes process means the worktree is actively in use — never touch
@@ -2060,6 +2153,13 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
         except Exception as e:
             logger.debug("Failed to prune worktree %s: %s", entry.name, e)
 
+    if preserved_stale:
+        logger.warning(
+            "Preserving %d worktree(s) older than 7 days with unmerged work "
+            "(push or remove them to reclaim disk): %s",
+            len(preserved_stale), ", ".join(sorted(preserved_stale)),
+        )
+
     _prune_orphaned_branches(repo_root)
 
 
@@ -3762,6 +3862,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.
@@ -3892,6 +4014,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:
@@ -3927,7 +4055,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"
@@ -4174,6 +4303,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
         self._pending_tool_info: dict = {}  # function_name -> list of (preview, args) for stacked scrollback
         self._last_scrollback_tool: str = ""  # last tool name printed to scrollback (for "new" dedup)
         self._command_running = False
+        self._command_blocks_input = False
         self._command_status = ""
         # Petdex mascot (opt-in via display.pet). The base CLI mirrors the TUI's
         # PetPane: a half-block sprite above the prompt that reacts to agent
@@ -6187,9 +6317,17 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
         return _COMMAND_SPINNER_FRAMES[frame_idx]
 
     @contextmanager
-    def _busy_command(self, status: str):
-        """Expose a temporary busy state in the TUI while a slash command runs."""
+    def _busy_command(self, status: str, *, blocks_input: bool = True):
+        """Expose a temporary busy state in the TUI while a slash command runs.
+
+        Most synchronous slash commands must reserve the composer because their
+        completion changes the active session state. Manual compression is safe
+        to draft through: the queued input is processed against the compacted
+        history after the command completes.
+        """
+        previous_blocks_input = getattr(self, "_command_blocks_input", False)
         self._command_running = True
+        self._command_blocks_input = blocks_input
         self._command_status = status
         self._invalidate(min_interval=0.0)
         try:
@@ -6197,6 +6335,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
             yield
         finally:
             self._command_running = False
+            self._command_blocks_input = previous_blocks_input
             self._command_status = ""
             self._invalidate(min_interval=0.0)
 
@@ -9381,9 +9520,12 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
                             # has all API keys in os.environ.
                             from tools.environments.local import _sanitize_subprocess_env
                             sanitized_env = _sanitize_subprocess_env(os.environ.copy())
+                            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, timeout=30, env=sanitized_env,
+                                # No console flash on Windows (#56747).
+                                creationflags=windows_hide_flags(),
                             )
                             output = result.stdout.strip() or result.stderr.strip()
                             if output:
@@ -10017,7 +10159,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
             return
 
         original_count = len(self.conversation_history)
-        with self._busy_command("Compressing context..."):
+        with self._busy_command("Compressing context...", blocks_input=False):
             try:
                 from agent.model_metadata import estimate_request_tokens_rough
                 from agent.manual_compression_feedback import summarize_manual_compression
@@ -10073,6 +10215,39 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
                     force=True,
                     defer_context_engine_notification=True,
                 )
+
+                # If _compress_context returned unchanged because a
+                # concurrent compression lock is held, tell the user
+                # clearly instead of showing the misleading
+                # "No changes from compression" no-op text. The wording
+                # distinguishes a confirmed holder from an unconfirmed
+                # acquisition failure (describe_compression_lock_skip).
+                # Type-pinned check (is True / str): the flag's only real
+                # values are None/True/holder-string, and a bare getattr
+                # truthiness test is fooled by MagicMock auto-attributes on
+                # test-double agents (skill pitfall: MagicMock vs hasattr).
+                _lock_skip_signal = getattr(
+                    self.agent, "_compression_skipped_due_to_lock", None
+                )
+                if _lock_skip_signal is True or isinstance(_lock_skip_signal, str):
+                    from agent.manual_compression_feedback import (
+                        describe_compression_lock_skip,
+                    )
+                    print(
+                        "  "
+                        + describe_compression_lock_skip(
+                            self.agent._compression_skipped_due_to_lock
+                        )
+                    )
+                    self.agent._compression_skipped_due_to_lock = None
+                    # No boundary was committed on a lock-skip; discard the
+                    # deferred context-engine notification (exactly-once).
+                    finalize_context_engine_compression_notification(
+                        self.agent,
+                        committed=False,
+                    )
+                    return
+
                 if partial and tail:
                     compressed = rejoin_compressed_head_and_tail(compressed, tail)
                 self.conversation_history = compressed
@@ -11488,7 +11663,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
     # threading resume logic through the voice machinery.
 
     def _maybe_start_wake_word(self):
-        """Start the wake-word listener at CLI startup if this surface owns it."""
+        """Start the wake-word listener at CLI startup if this surface is eligible."""
         try:
             from tools.wake_word import wake_surface_enabled
             if not wake_surface_enabled("cli"):
@@ -11499,14 +11674,11 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
 
     def _start_wake_word_listener(self, announce: bool = False) -> bool:
         """Build + start the hotword detector. Returns True on success."""
-        if getattr(self, "_wake_word_active", False):
-            if announce:
-                _cprint(f"{_DIM}Wake word is already listening.{_RST}")
-            return True
         try:
             from tools.wake_word import (
                 check_wake_word_requirements,
                 load_wake_word_config,
+                owns_listener,
                 start_listening,
             )
         except Exception as e:
@@ -11514,6 +11686,12 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
                 _cprint(f"{_DIM}Wake word unavailable: {e}{_RST}")
             return False
 
+        if getattr(self, "_wake_word_active", False) and owns_listener(self):
+            if announce:
+                _cprint(f"{_DIM}Wake word is already listening.{_RST}")
+            return True
+        self._wake_word_active = False
+
         cfg = load_wake_word_config()
         reqs = check_wake_word_requirements(cfg)
         if not reqs["available"]:
@@ -11525,7 +11703,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
 
         self._wake_start_new_session = bool(cfg.get("start_new_session", True))
         try:
-            start_listening(self._on_wake_word, config=cfg)
+            start_listening(self._on_wake_word, owner=self, config=cfg)
         except Exception as e:
             if announce:
                 _cprint(f"\n{_DIM}Failed to start wake word: {e}{_RST}")
@@ -11533,6 +11711,8 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
 
         self._wake_word_active = True
         self._wake_suspended = False
+        global _cli_wake_owner
+        _cli_wake_owner = self
         self._start_wake_watchdog()
         if announce:
             _cprint(f"\n{_ACCENT}Wake word listening{_RST} "
@@ -11541,14 +11721,17 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
 
     def _stop_wake_word_listener(self, announce: bool = False):
         """Stop and tear down the hotword detector."""
+        global _cli_wake_owner
         was_active = getattr(self, "_wake_word_active", False)
         self._wake_word_active = False
         self._wake_suspended = False
         try:
             from tools.wake_word import stop_listening
-            stop_listening()
+            stop_listening(owner=self)
         except Exception:
             pass
+        if _cli_wake_owner is self:
+            _cli_wake_owner = None
         if announce:
             if was_active:
                 _cprint(f"{_DIM}Wake word stopped.{_RST}")
@@ -11556,7 +11739,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
                 _cprint(f"{_DIM}Wake word is not running.{_RST}")
 
     def _on_wake_word(self):
-        """Fired (on the detector thread) when the wake phrase is heard."""
+        """Fired after the detector hears the wake phrase."""
         if getattr(self, "_should_exit", False):
             return
         # Ignore wake while a turn is in flight or the mic is already in use.
@@ -11566,9 +11749,12 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
         # Release the mic so STT can capture the command utterance.
         try:
             from tools.wake_word import pause_listening
-            pause_listening()
-        except Exception:
-            pass
+            if not pause_listening(owner=self):
+                self._wake_word_active = False
+                return
+        except Exception as e:
+            logger.debug("wake word pause failed: %s", e)
+            return
         self._wake_suspended = True
 
         _cprint(f"\n{_ACCENT}✦ Wake word detected — listening...{_RST}")
@@ -11625,8 +11811,10 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
                         idle_polls = 0
                         try:
                             from tools.wake_word import resume_listening
-                            resume_listening()
-                            self._wake_suspended = False
+                            if resume_listening(owner=self):
+                                self._wake_suspended = False
+                            else:
+                                self._wake_word_active = False
                         except Exception as e:
                             logger.debug("wake word resume failed: %s", e)
             finally:
@@ -11636,21 +11824,27 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
 
     def _show_wake_word_status(self):
         """Show current wake-word listener status."""
-        from tools.wake_word import check_wake_word_requirements, load_wake_word_config
+        from tools.wake_word import (
+            check_wake_word_requirements,
+            is_listening,
+            load_wake_word_config,
+            owns_listener,
+        )
 
         cfg = load_wake_word_config()
         reqs = check_wake_word_requirements(cfg)
-        active = getattr(self, "_wake_word_active", False)
+        owned = owns_listener(self)
+        state = "LISTENING" if owned and is_listening() else "PAUSED" if owned else "OFF"
 
         _cprint(f"\n{_BOLD}Wake Word Status{_RST}")
-        _cprint(f"  State:       {'LISTENING' if active else 'OFF'}")
+        _cprint(f"  State:       {state}")
         _cprint(f"  Phrase:      \"{reqs['phrase']}\"")
         _cprint(f"  Provider:    {reqs['provider']}")
         _cprint(f"  Surface:     {cfg.get('surface', 'auto')}")
         _cprint(f"  New session: {'yes' if cfg.get('start_new_session', True) else 'no'}")
         if not reqs["available"] and reqs.get("hint"):
             _cprint(f"  {_DIM}{reqs['hint']}{_RST}")
-        if not active:
+        if not owned:
             _cprint(f"  {_DIM}Enable with /wake on{_RST}")
 
     def _toggle_voice_tts(self):
@@ -12292,6 +12486,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
                     (self.provider or "").strip(),
                     (self.model or "").strip(),
                     load_config(),
+                    requested_provider=(self.requested_provider or "").strip(),
                 )
             except Exception as _img_exc:
                 logging.debug("image_routing decision failed, defaulting to text: %s", _img_exc)
@@ -13621,6 +13816,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
 
         # Slash command loading state
         self._command_running = False
+        self._command_blocks_input = False
         self._command_status = ""
 
         # Secure secret capture state for skill setup
@@ -14582,7 +14778,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
             style='class:input-area',
             multiline=True,
             wrap_lines=True,
-            read_only=Condition(lambda: bool(cli_ref._command_running)),
+            read_only=Condition(lambda: bool(cli_ref._command_blocks_input)),
             history=FileHistory(str(self._history_file)),
             # complete_while_typing fires the completer on every keystroke. The
             # completer does blocking work — fuzzy @-file indexing shells out to
@@ -14793,8 +14989,9 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
 
             if cli_ref._command_running:
                 frame = cli_ref._command_spinner_frame()
+                detail = "input temporarily disabled" if cli_ref._command_blocks_input else "input stays active; Enter queues"
                 return [
-                    ('class:hint', f'  {frame} command in progress · input temporarily disabled'),
+                    ('class:hint', f'  {frame} command in progress · {detail}'),
                 ]
 
             return []
@@ -16474,6 +16671,9 @@ def main(
                                 (cli.provider or "").strip(),
                                 (cli.model or "").strip(),
                                 load_config(),
+                                requested_provider=(
+                                    cli.requested_provider or ""
+                                ).strip(),
                             )
                         except Exception:
                             _img_mode = "text"

contributors/emails/15167896+2001Y@users.noreply.github.com

@@ -0,0 +1 @@
+2001Y

contributors/emails/269728612+metamon-p@users.noreply.github.com

@@ -0,0 +1,2 @@
+metamon-p
+# PR #36220 salvage (channel continuity hint)

contributors/emails/aakash@plasticlabs.ai

@@ -0,0 +1 @@
+akattelu

contributors/emails/akitani@akitaninoMac-mini.local

@@ -0,0 +1 @@
+2001Y

contributors/emails/alanrbox@gmail.com

@@ -0,0 +1 @@
+AlanBurningsuit

contributors/emails/awain7@gmail.com

@@ -0,0 +1,2 @@
+awain7
+# PR #58261 salvage

contributors/emails/benjamin2026-dot@users.noreply.github.com

@@ -0,0 +1 @@
+benjamin2026-dot

contributors/emails/boumagent@gmail.com

@@ -0,0 +1 @@
+patp

contributors/emails/chaosxinglong@gmail.com

@@ -0,0 +1 @@
+chaos-xxl

contributors/emails/cluster2@Cluster2s-Mac-Studio.local

@@ -0,0 +1 @@
+robgfl45

contributors/emails/dickson.neoh@gmail.com

@@ -0,0 +1 @@
+dnth

contributors/emails/fangliquan@oppo.com

@@ -0,0 +1 @@
+fangliquanflq

contributors/emails/gonzalofrancoceballos@Gonzalos-Mac-mini.local

@@ -0,0 +1 @@
+gonzalofrancoceballos

contributors/emails/hang.li@tcredit.com

@@ -0,0 +1 @@
+airclear

contributors/emails/harrison@medmetricsrx.com

@@ -0,0 +1,2 @@
+harrisonmedmedmetrics
+# C17 Slack reaction events salvage (#33111/#44508/#45265)

contributors/emails/hello@ianks.com

@@ -0,0 +1 @@
+ianks

contributors/emails/hello@jeromeiveson.com

@@ -0,0 +1 @@
+Trantor-develops

contributors/emails/hellofrommorgan@users.noreply.github.com

@@ -0,0 +1 @@
+hellofrommorgan

contributors/emails/idrisalmalki@Idriss-MacBook-Air.local

@@ -0,0 +1 @@
+quantumbyte1617

contributors/emails/iniak@iniakdeMac-mini.local

@@ -0,0 +1 @@
+iniak

contributors/emails/janig88@gmail.com

@@ -0,0 +1,2 @@
+Janig88
+# PR #58402 salvage