@maudecode/talaria-web 1.19.0 → 1.20.0

package/sidecar/talaria_sidecar/methods/chat.py

@@ -19,6 +19,7 @@ import inspect
 import json
 import logging
 import os
+import queue
 import re
 import threading
 import time
@@ -26,13 +27,15 @@ import uuid
 from collections import OrderedDict
 from functools import lru_cache
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
+from types import SimpleNamespace
 
 from ..errors import InvalidParams, RpcError
 from ..home import profile_home_param, scoped_home, session_workspace
 from ..rpc import CallContext
 from .checkpoints import checkpoint_kwargs
 from .providers import runtime_failure
+from .state_db import release_all, release_home, release_session_db
 from .toolsets import disabled_toolsets
 
 log = logging.getLogger("talaria_sidecar.chat")
@@ -65,6 +68,7 @@ class _Run:
         # agent this run binds afterwards forks no review and stays out of the cache.
         self.session_ended = False
         self.home = None  # the profile home its agent runs under, set by ``start``
+        self.mcp_discovery_outcome = "ok"
 
 
 class _ClarifyEntry:
@@ -86,13 +90,22 @@ _RUNS_LOCK = threading.Lock()
 # session id -> (agent, signature, profile home).
 _AGENT_CACHE: "OrderedDict[str, tuple[Any, str, Any]]" = OrderedDict()
 _AGENT_CACHE_LOCK = threading.Lock()
-# Running release thread -> the profile home it runs under.
-_RELEASES: dict[threading.Thread, Any] = {}
+# Running or queued release work -> the profile home it holds.
+_RELEASES: dict[threading.Thread | _ArchiveCallback, Any] = {}
 _RELEASES_LOCK = threading.Lock()
-# Agents inside ``chat.commit_memory`` or ``chat.refine`` (guarded by ``_AGENT_CACHE_LOCK``): like a turn, each defers their release.
+_ARCHIVE_MAX_WORKERS = 4
+_ARCHIVE_QUEUE: queue.Queue[_ArchiveCallback | None] = queue.Queue(maxsize=256)
+_ARCHIVE_WORKERS: list[threading.Thread] = []
+# Non-turn ``(agent, home)`` holders for memory commits, refine, context reads and MCP refresh (under
+# ``_AGENT_CACHE_LOCK``): each defers the agent's release, and deleting ``home`` waits for it.
 _COMMITTING: list = []
 # Set (under ``_RUNS_LOCK``) when shutdown drains: no turn is admitted after the drain's snapshot of ``_RUNS``.
 _DRAINING = threading.Event()
+_MCP_DISCOVERIES: dict[str, threading.Event] = {}
+_MCP_DISCOVERY_LOCK = threading.Lock()
+_MCP_CLOSING_HOMES: set[str] = set()
+_MCP_REDISCOVERY_WAIT = 2.0
+_MCP_PENDING_KEY = "mcp_discovery_pending"
 
 
 def _snippet(raw: Any, limit: int = _TOOL_RESULT_SNIPPET_MAX) -> str:
@@ -111,7 +124,17 @@ def _snippet(raw: Any, limit: int = _TOOL_RESULT_SNIPPET_MAX) -> str:
 
 
 _RAW_RESULT_MAX_KEYS = 64
-_RAW_RESULT_OUTCOME_KEYS = ("error", "exit_code", "exitCode", "success")
+_RAW_RESULT_OUTCOME_KEYS = ("error", "exit_code", "exitCode", "success", "status", "results")
+# TAL-1261: a ``results`` batch keeps up to 64 items, each projected like the result with 16 fields of 400 characters.
+_RAW_RESULT_ITEM_KEYS = 16
+_RAW_RESULT_ITEM_MAX = 400
+
+
+def _without_error(item: Any) -> bool:
+    """An item the server's ``presentError`` reads as error-free: not an object, or its ``error`` is blank text, ``false``,
+    ``null``, a number, or an empty object or list."""
+    error = item.get("error") if isinstance(item, dict) else None
+    return not (error is True or (isinstance(error, str) and error.strip()) or (isinstance(error, (dict, list)) and error))
 
 
 def _result_diff(raw: Any) -> str | None:
@@ -149,10 +172,11 @@ def _edit_metadata(name: str, args: Any, result: Any, snapshot: Any) -> dict:
     return {"diff": diff} if diff else {}
 
 
-def _raw_result(raw: Any, limit: int = _TOOL_RESULT_SNIPPET_MAX) -> Any:
+def _raw_result(raw: Any, limit: int = _TOOL_RESULT_SNIPPET_MAX, max_keys: int = _RAW_RESULT_MAX_KEYS, items: bool = True) -> Any:
     """The tool result as the server's outcome rule reads it, bounded: a dict (or JSON-object text) keeps its first
-    ``_RAW_RESULT_MAX_KEYS`` top-level fields plus its outcome fields, scalars as they are, text and non-empty nested
-    values as capped (JSON) text; anything else is the capped text. The sidecar decides nothing; the server does."""
+    ``max_keys`` top-level fields plus its outcome fields, scalars as they are, text and non-empty nested values as capped
+    (JSON) text, except a ``results`` list, whose object items keep the same shape one level down (TAL-1261); anything
+    else is the capped text. The sidecar decides nothing; the server does."""
     try:
         data = raw if isinstance(raw, dict) else json.loads(str(raw or ""))
     except Exception:  # noqa: BLE001
@@ -161,9 +185,15 @@ def _raw_result(raw: Any, limit: int = _TOOL_RESULT_SNIPPET_MAX) -> Any:
         return str(raw if raw is not None else "")[:limit]
     out: dict = {}
     # The server's outcome rule reads these, wherever they sit in the result.
-    kept = list(data.items())[:_RAW_RESULT_MAX_KEYS] + [(k, data[k]) for k in _RAW_RESULT_OUTCOME_KEYS if k in data]
+    kept = list(data.items())[:max_keys] + [(k, data[k]) for k in _RAW_RESULT_OUTCOME_KEYS if k in data]
     for key, value in kept:
-        if value is None or isinstance(value, (bool, int)) or (isinstance(value, float) and value == value and abs(value) != float("inf")):
+        if items and key == "results" and isinstance(value, list) and value:
+            # Past the cap, the first item without an error rides along, so a long batch is judged like the whole one.
+            batch = value[:_RAW_RESULT_MAX_KEYS] + [item for item in value[_RAW_RESULT_MAX_KEYS:] if _without_error(item)][:1]
+            # A non-object item stays text, even JSON-object text: only object items count toward the batch's outcome.
+            out[key] = [_raw_result(item, _RAW_RESULT_ITEM_MAX, _RAW_RESULT_ITEM_KEYS, False) if isinstance(item, dict)
+                        else (item if isinstance(item, str) else json.dumps(item, default=str))[:_RAW_RESULT_ITEM_MAX] for item in batch]
+        elif value is None or isinstance(value, (bool, int)) or (isinstance(value, float) and value == value and abs(value) != float("inf")):
             out[str(key)] = value
         elif isinstance(value, (dict, list)) and not value:
             out[str(key)] = {} if isinstance(value, dict) else []
@@ -726,56 +756,293 @@ def _turn_identity(session_id: str, workspace: str):
 _LEGACY_TOOLSET_ALIASES = {"hermes": ("hermes-cli", "hermes-api-server")}
 
 
-def _turn_toolsets(toolsets) -> list[str]:
+def _turn_toolsets(toolsets, cfg: dict | None = None) -> list[str]:
     """The session's override as sent, else the profile's configured toolsets. ``None`` would hand the Agent every
     registered toolset."""
-    return toolsets if isinstance(toolsets, list) else _profile_toolsets()
+    return toolsets if isinstance(toolsets, list) else _profile_toolsets(cfg)
 
 
-def _profile_toolsets() -> list[str]:
+def _profile_toolsets(cfg: dict | None = None) -> list[str]:
     """The profile's ``platform_toolsets.cli`` through the Agent's own resolver (default-off toolsets stay off), like
     ``hermes chat``. Runs under the call's ``scoped_home``."""
     from hermes_cli.config import load_config
     from hermes_cli.tools_config import _get_platform_tools
 
-    resolved = sorted(_get_platform_tools(load_config() or {}, "cli"))
+    resolved = sorted(_get_platform_tools((load_config() or {}) if cfg is None else cfg, "cli"))
     return list(dict.fromkeys(name for raw in resolved for name in _LEGACY_TOOLSET_ALIASES.get(raw, (raw,))))
 
 
-def _discover_mcp_tools(run: _Run) -> None:
-    """Connect the profile's MCP servers before the turn's agent snapshots its tools, like the predecessor's turn start.
-    The Agent keys connections by profile scope and skips live ones, so later turns are cheap. Runs under the call's
-    ``scoped_home``; a failure leaves the turn without MCP tools rather than failing it. A Stop does not wait for a slow
-    server: the turn moves on to its cancelled end while the connect finishes in the background."""
-    from .commands import discover_profile_mcp_tools
+def _discover_mcp_tools(run: _Run) -> threading.Event | None:
+    """Wait for the profile's first discovery; later turns give a shared background retry at most two seconds."""
+    from .commands import discover_profile_mcp_tools, profile_mcp_tools_discovered
 
-    done = threading.Event()
+    profile_home = run.home
+    home = os.path.realpath(profile_home)
+    deadline = time.monotonic() + _MCP_REDISCOVERY_WAIT if profile_mcp_tools_discovered(home) else None
 
     def discover() -> None:
         try:
-            discover_profile_mcp_tools()
+            discovered = discover_profile_mcp_tools()
+            refresh_profile_agents_mcp_tools(profile_home)
+            done.startup_outcome = "ok" if discovered else "noop"
         except Exception:  # noqa: BLE001
+            done.startup_outcome = "error"
             log.warning("MCP discovery failed", exc_info=True)
         finally:
+            with _RELEASES_LOCK:
+                _RELEASES.pop(worker, None)
             done.set()
 
-    # The copied context carries the turn's home override and secret scope into the worker.
-    threading.Thread(target=contextvars.copy_context().run, args=(discover,), daemon=True, name=f"chat-mcp-{run.stream_id[:8]}").start()
-    while not done.wait(0.25):
+    with _MCP_DISCOVERY_LOCK:
+        if _DRAINING.is_set():
+            raise RpcError("The sidecar is shutting down.", condition="sidecar_unavailable")
+        if home in _MCP_CLOSING_HOMES:
+            raise RpcError("The profile is being deleted.", condition="profile_unavailable")
+        done = _MCP_DISCOVERIES.get(home)
+        if done is None or done.is_set():
+            done = threading.Event()
+            done.startup_outcome = "unknown"
+            _MCP_DISCOVERIES[home] = done
+            # The copied context carries the turn's home override and secret scope into the worker.
+            worker = threading.Thread(target=contextvars.copy_context().run, args=(discover,), daemon=True, name=f"chat-mcp-{run.stream_id[:8]}")
+            worker.failed = False
+            # Existing profile/shutdown custody includes this worker after its originating turn has ended.
+            with _RELEASES_LOCK:
+                _RELEASES[worker] = profile_home
+            try:
+                worker.start()
+            except Exception:
+                with _RELEASES_LOCK:
+                    _RELEASES.pop(worker, None)
+                done.set()
+                raise
+    while not done.is_set():
         if run.cancel.is_set() or run.ctx.cancelled:
+            run.mcp_discovery_outcome = "cancelled"
+            return None
+        remaining = None if deadline is None else deadline - time.monotonic()
+        if remaining is not None and remaining <= 0:
+            run.mcp_discovery_outcome = "timeout"
+            run.ctx.emit("notice", {"key": _MCP_PENDING_KEY, "level": "info", "kind": "sticky",
+                                    "text": "Some tools are still connecting. Using available tools for this turn.",
+                                    "lapses_with_agent": False})
+            return done
+        done.wait(0.25 if remaining is None else min(0.25, remaining))
+    run.mcp_discovery_outcome = getattr(done, "startup_outcome", "ok")
+    return None
+
+
+# Serializes every hook change the sidecar makes, so two turns or a turn and a profile deletion never interleave a
+# drop with a registration.
+_HOOKS_LOCK = threading.Lock()
+_HOOK_CALLBACK_PREFIXES = {"agent.shell_hooks": "shell_hook[", "agent.outbound_webhooks": "outbound_webhook["}
+
+
+def _drop_home_callbacks(*modules) -> None:
+    """Forget this home's registrations in each Agent hook module and remove their callbacks from the home's plugin
+    manager; the Agent has no teardown for either registry. Runs under the call's ``scoped_home`` and ``_HOOKS_LOCK``."""
+    from agent import shell_hooks
+    from hermes_cli.plugins import get_plugin_manager
+
+    prefixes = tuple(_HOOK_CALLBACK_PREFIXES[module.__name__] for module in modules)
+    for module in modules:
+        shell_hooks._forget_home_registrations(module._registered, module._registered_lock)
+    manager = get_plugin_manager()
+    with shell_hooks._registered_lock:
+        for event, callbacks in list(manager._hooks.items()):
+            # Replaced, never edited in place: a concurrent invoke_hook keeps iterating the old list.
+            manager._hooks[event] = [cb for cb in callbacks if not getattr(cb, "__name__", "").startswith(prefixes)]
+
+
+def _hook_state_trusted(shell_hooks, cfg: dict) -> bool:
+    """``sync_from_config``'s removal guard for Agents without it: an empty (failed-open) config, an unreadable
+    allowlist or a ``hooks:`` entry the Agent could not parse must never disarm a registered guard."""
+    if not cfg:
+        return False
+    try:
+        allowlist = json.loads(shell_hooks.allowlist_path().read_text(encoding="utf-8-sig"))
+    except FileNotFoundError:
+        allowlist = {"approvals": []}
+    except (OSError, ValueError):
+        return False
+    if not isinstance(allowlist, dict) or not isinstance(allowlist.get("approvals"), list):
+        return False
+    hooks = cfg.get("hooks")
+    if hooks is None:
+        return True
+    if not isinstance(hooks, dict):
+        return False
+    events = [entries for event, entries in hooks.items() if event not in ("output_spill", "outbound") and entries is not None]
+    if not all(isinstance(entries, list) for entries in events):
+        return False
+    return len(shell_hooks.iter_configured_hooks(cfg)) == sum(len(entries) for entries in events)
+
+
+def _replace_shell_hooks(shell_hooks, cfg: dict) -> None:
+    """Agents without ``sync_from_config``: wire the home's consented hooks from ``cfg`` and drop the rest, so a hook
+    removed from config or revoked stops, as it does on v0.22.3. The stale callbacks go only after the current set is
+    wired, so a concurrent turn's tool call always meets its guard. Add-only when the hook state is not trusted."""
+    if not _hook_state_trusted(shell_hooks, cfg):
+        shell_hooks.register_from_config(cfg, accept_hooks=False)
+        return
+    from hermes_cli.plugins import get_plugin_manager
+
+    manager = get_plugin_manager()
+    stale = [cb for callbacks in manager._hooks.values() for cb in callbacks if getattr(cb, "__name__", "").startswith("shell_hook[")]
+    shell_hooks._forget_home_registrations(shell_hooks._registered, shell_hooks._registered_lock)
+    shell_hooks.register_from_config(cfg, accept_hooks=False)
+    with shell_hooks._registered_lock:
+        for event, callbacks in list(manager._hooks.items()):
+            manager._hooks[event] = [cb for cb in callbacks if not any(cb is old for old in stale)]
+
+
+def _register_profile_hooks(home: Path) -> None:
+    """Wire the profile's consented shell hooks and current outbound webhooks before the turn's tools run, like the
+    gateway on every session open (TAL-1258). Hooks added or approved since the last call join this one; hooks removed
+    from config or revoked stop, through ``sync_from_config`` or its sidecar twin for older Agents. Outbound webhooks
+    are add-only on every Agent, so each call replaces the home's set with the configured one (a concurrent turn's
+    notification can miss that instant; webhooks only observe). Consent comes from the allowlist or an opt-in in
+    force: stdin is the RPC pipe, so nothing prompts. A failure is logged and never blocks the turn."""
+    try:
+        from agent import outbound_webhooks, shell_hooks
+        from hermes_cli.config import load_config
+
+        with _HOOKS_LOCK:
+            sync = getattr(shell_hooks, "sync_from_config", None)
+            if sync is not None:
+                sync(load_config)
+            else:
+                _replace_shell_hooks(shell_hooks, load_config())
+            _drop_home_callbacks(outbound_webhooks)
+            outbound_webhooks.register_from_config(load_config())
+    except Exception:  # noqa: BLE001
+        log.warning("shell-hook sync failed; keeping the registered hooks", exc_info=True)
+
+
+def forget_profile_hooks(home: Path) -> None:
+    """Profile deletion: drop the home's shell hooks and outbound webhooks. The Agent keys both registries and its
+    plugin manager by path, so a profile recreated at that path would otherwise fire hooks its new config and allowlist
+    never approved. Raises rather than let the profile go with its hooks still wired."""
+    try:
+        from agent import outbound_webhooks, shell_hooks
+    except ImportError:  # no Agent, so no hook was ever registered
+        return
+    with _HOOKS_LOCK, scoped_home(home):
+        _drop_home_callbacks(shell_hooks, outbound_webhooks)
+
+
+@contextlib.contextmanager
+def agent_scope(home: Path):
+    """``scoped_home`` for a call that runs Agent work: the profile's hooks are wired before any of it (TAL-1258), so
+    the call's first LLM request, tool call or lifecycle event already sees them, even as a session's first work after
+    a sidecar restart."""
+    with scoped_home(home):
+        _register_profile_hooks(home)
+        yield
+
+
+class _ArchiveCallback:
+    """Queued work shares the release threads' join/liveness contract without owning an OS thread."""
+    name = "session-archive"
+    failed = False
+
+    def __init__(self, callback: Callable[[], None]):
+        self.callback = callback
+        self.done = threading.Event()
+
+    def run(self) -> None:
+        try:
+            self.callback()
+        finally:
+            self.done.set()
+
+    def join(self, timeout=None) -> None:
+        self.done.wait(timeout)
+
+    def is_alive(self) -> bool:
+        return not self.done.is_set()
+
+
+def _archive_worker(pending) -> None:
+    while True:
+        work = pending.get()
+        try:
+            if work is None:
+                return
+            try:
+                work.run()
+            except BaseException:  # a plugin must not kill a shared worker
+                log.warning("Session archive notification worker failed")
+        finally:
+            pending.task_done()
+            del work
+
+
+def _schedule_archive(work: _ArchiveCallback, home: Path) -> None:
+    # Admission shares the profile-deletion/shutdown fence; queued work uses the existing release custody roster.
+    with _MCP_DISCOVERY_LOCK:
+        if _DRAINING.is_set() or os.path.realpath(home) in _MCP_CLOSING_HOMES:
+            log.warning("Session archive notification unavailable during profile or sidecar shutdown")
             return
+        if len(_ARCHIVE_WORKERS) < _ARCHIVE_MAX_WORKERS:
+            thread = threading.Thread(target=_archive_worker, args=(_ARCHIVE_QUEUE,), name="session-archive-worker", daemon=True)
+            try:
+                thread.start()
+            except RuntimeError:
+                log.warning("Session archive notification worker could not start")
+                if not _ARCHIVE_WORKERS:
+                    return
+            else:
+                _ARCHIVE_WORKERS.append(thread)
+        with _RELEASES_LOCK:
+            _RELEASES[work] = home
+            try:
+                _ARCHIVE_QUEUE.put_nowait(work)
+            except queue.Full:
+                _RELEASES.pop(work, None)
+                log.warning("Session archive notification queue is full")
 
 
-def _profile_fallback_chain() -> list[dict] | None:
+def _notify_archive(home: Path, session_id: str, lineage: list[str] | None) -> None:
+    import hermes_state_common
+
+    emit = getattr(hermes_state_common, "emit_session_deleted", None)
+    if emit is None:
+        return
+    # Upstream hook warnings can include arbitrary callback exceptions. Keep one payload-free diagnostic.
+    thread_id, warned = threading.get_ident(), False
+
+    def bounded_diagnostic(record):
+        nonlocal warned
+        if record.thread != thread_id:
+            return True
+        warned = warned or record.levelno >= logging.WARNING
+        return False
+
+    handlers = list(logging.getLogger().handlers)
+    for handler in handlers:
+        handler.addFilter(bounded_diagnostic)
+    try:
+        # The emitter only needs db_path for profile identity. Opening SessionDB would migrate an owner's store.
+        emit(SimpleNamespace(db_path=home / "state.db"), [session_id, *(lineage or [])],
+             reason="archive", primary=session_id, sessions_dir=home / "sessions")
+    finally:
+        for handler in handlers:
+            handler.removeFilter(bounded_diagnostic)
+        if warned:
+            log.warning("Session archive notification reported a callback failure")
+
+
+def _profile_fallback_chain(cfg: dict | None = None) -> list[dict] | None:
     """The profile's fallback routes (``fallback_providers`` first, then legacy ``fallback_model``, deduplicated)
     through the Agent's own resolver, like the CLI and gateway. Runs under the call's ``scoped_home``."""
     from hermes_cli.config import load_config
     from hermes_cli.fallback_config import get_fallback_chain
 
-    return get_fallback_chain(load_config() or {}) or None
+    return copy.deepcopy(get_fallback_chain((load_config() or {}) if cfg is None else cfg)) or None
 
 
-def _profile_prefill_messages() -> list[dict] | None:
+def _profile_prefill_messages(cfg: dict | None = None) -> list[dict] | None:
     """The profile's few-shot prefill (``HERMES_PREFILL_MESSAGES_FILE``, then ``prefill_messages_file``, then legacy
     ``agent.prefill_messages_file``; relative to the profile) through the Agent's own loader, like the CLI, gateway and
     Desktop. A missing or empty file is None. Runs under the call's ``scoped_home``."""
@@ -783,15 +1050,15 @@ def _profile_prefill_messages() -> list[dict] | None:
     from hermes_cli.config import load_config
     from hermes_constants import get_hermes_home
 
-    return _load_prefill_messages(_resolve_prefill_messages_file(load_config() or {}), get_hermes_home()) or None
+    return _load_prefill_messages(_resolve_prefill_messages_file((load_config() or {}) if cfg is None else cfg), get_hermes_home()) or None
 
 
-def _main_model_request_overrides(model: str, provider, base_url: str = "") -> dict | None:
+def _main_model_request_overrides(model: str, provider, base_url: str = "", cfg: dict | None = None) -> dict | None:
     """Predecessor ``_main_model_request_overrides``: the profile's ``model.service_tier`` and ``model.extra_body``
     (written by ``/api/model/set``) apply only to turns on that configured main model. Runs under ``scoped_home``."""
     from hermes_cli.config import load_config
 
-    model_cfg = (load_config() or {}).get("model")
+    model_cfg = ((load_config() or {}) if cfg is None else cfg).get("model")
     if not isinstance(model_cfg, dict):
         return None
     main_model = str(model_cfg.get("default") or model_cfg.get("name") or "").strip()
@@ -808,15 +1075,15 @@ def _main_model_request_overrides(model: str, provider, base_url: str = "") -> d
     overrides = fast_overrides(model, str(provider or ""), base_url, str(model_cfg.get("service_tier") or "").strip().lower()) or {}
     extra_body = model_cfg.get("extra_body")
     if isinstance(extra_body, dict) and extra_body:
-        overrides["extra_body"] = extra_body
+        overrides["extra_body"] = copy.deepcopy(extra_body)
     return overrides or None
 
 
-def _request_overrides(model: str, provider, runtime: dict) -> dict | None:
+def _request_overrides(model: str, provider, runtime: dict, cfg: dict | None = None) -> dict | None:
     """The resolver's ``request_overrides`` (a custom provider entry's ``extra_body``) under the main-model ones, whose
     ``extra_body`` wins key by key, the Agent's own merge order. Runs under ``scoped_home``."""
     merged = dict(runtime.get("request_overrides") or {})
-    main = _main_model_request_overrides(model, provider, str(runtime.get("base_url") or "")) or {}
+    main = _main_model_request_overrides(model, provider, str(runtime.get("base_url") or ""), cfg) or {}
     extra_body = {**(merged.get("extra_body") or {}), **(main.get("extra_body") or {})}
     merged.update(main)
     if extra_body:
@@ -824,6 +1091,31 @@ def _request_overrides(model: str, provider, runtime: dict) -> dict | None:
     return merged or None
 
 
+def _provider_routing_kwargs(cfg: dict | None = None) -> dict:
+    """The profile's OpenRouter ``provider_routing`` and ``openrouter.min_coding_score`` as ``AIAgent`` kwargs, with the
+    Agent's own mapping (``gateway/session_worker_construct.routing_agent_kwargs``). The score is coerced like the CLI's
+    (``cli_init_mixin``), so a quoted number counts and a value outside 0..1 stays unset. Runs under ``scoped_home``."""
+    from hermes_cli.config import load_config
+
+    if cfg is None:
+        cfg = load_config() or {}
+    routing = cfg.get("provider_routing")
+    routing = routing if isinstance(routing, dict) else {}
+    openrouter = cfg.get("openrouter")
+    raw_score = openrouter.get("min_coding_score") if isinstance(openrouter, dict) else None
+    try:
+        score = float(raw_score) if raw_score not in (None, "") else None
+    except (TypeError, ValueError):
+        score = None
+    return copy.deepcopy({
+        "providers_allowed": routing.get("only"), "providers_ignored": routing.get("ignore"),
+        "providers_order": routing.get("order"), "provider_sort": routing.get("sort"),
+        "provider_require_parameters": routing.get("require_parameters", False),
+        "provider_data_collection": routing.get("data_collection"),
+        "openrouter_min_coding_score": score if score is not None and 0.0 <= score <= 1.0 else None,
+    })
+
+
 def _agent_signature(model: str, provider, runtime: dict, toolsets, home: str, kwargs: dict) -> str:
     """Cache identity of an ``AIAgent``: everything its constructor bound from the resolved runtime, so a rotated key,
     a different API mode, ACP command, or credential pool never reuses an agent built for the old bundle. The key
@@ -841,6 +1133,9 @@ def _agent_signature(model: str, provider, runtime: dict, toolsets, home: str, k
         # Bound at construction too: a reasoning-effort change from the composer must build a fresh agent.
         "reasoning_config": kwargs.get("reasoning_config"),
         "request_overrides": kwargs.get("request_overrides"),
+        "provider_routing": [kwargs.get(name) for name in (
+            "providers_allowed", "providers_ignored", "providers_order", "provider_sort", "provider_require_parameters",
+            "provider_data_collection", "openrouter_min_coding_score")],
         "checkpoints": [kwargs.get(name) for name in ("checkpoints_enabled", "checkpoint_max_snapshots", "checkpoint_max_total_size_mb", "checkpoint_max_file_size_mb")],
         # Entries may carry their own ``api_key``.
         "fallback_model": hashlib.sha256(json.dumps(kwargs.get("fallback_model"), sort_keys=True, default=str).encode("utf-8")).hexdigest()[:16],
@@ -850,7 +1145,7 @@ def _agent_signature(model: str, provider, runtime: dict, toolsets, home: str, k
     return json.dumps(bundle, sort_keys=True, default=str)
 
 
-def _agent_kwargs(AIAgent, params: dict, session_id: str, model: str, provider, runtime: dict, toolsets) -> dict:
+def _agent_kwargs(AIAgent, params: dict, session_id: str, model: str, provider, runtime: dict, toolsets, cfg: dict | None = None) -> dict:
     """The ``AIAgent`` arguments of a session's agent apart from a turn's callbacks: the resolved runtime, the session's
     toolsets and budgets, and the profile's fallback chain, request overrides, prefill and checkpoints. Everything
     ``_agent_signature`` reads is here, so an agent ``/refine`` builds (TAL-902) is the one the next turn reuses. Runs under
@@ -863,7 +1158,7 @@ def _agent_kwargs(AIAgent, params: dict, session_id: str, model: str, provider,
         platform="webui",
         quiet_mode=True,
         enabled_toolsets=toolsets,
-        disabled_toolsets=disabled_toolsets(),
+        disabled_toolsets=disabled_toolsets(cfg),
         session_id=session_id,
     )
     for name, value in (
@@ -886,17 +1181,21 @@ def _agent_kwargs(AIAgent, params: dict, session_id: str, model: str, provider,
     reasoning_config = params.get("reasoning_config")
     if isinstance(reasoning_config, dict) and _supported(AIAgent, "reasoning_config"):
         kwargs["reasoning_config"] = reasoning_config
-    fallback_chain = _profile_fallback_chain()
+    fallback_chain = _profile_fallback_chain(cfg)
     if fallback_chain and _supported(AIAgent, "fallback_model"):
         kwargs["fallback_model"] = fallback_chain
-    request_overrides = _request_overrides(model, provider, runtime)
+    request_overrides = _request_overrides(model, provider, runtime, cfg)
     if request_overrides and _supported(AIAgent, "request_overrides"):
         kwargs["request_overrides"] = request_overrides
-    prefill_messages = _profile_prefill_messages()
+    prefill_messages = _profile_prefill_messages(cfg)
     if prefill_messages and _supported(AIAgent, "prefill_messages"):
         kwargs["prefill_messages"] = prefill_messages
+    # TAL-976: the profile's OpenRouter provider routing, as the Agent's own CLI and gateway turns read it.
+    for name, value in _provider_routing_kwargs(cfg).items():
+        if _supported(AIAgent, name):
+            kwargs[name] = value
     # TAL-913: the profile's ``checkpoints`` section, as the Agent's own CLI and gateway turns read it.
-    for name, value in checkpoint_kwargs().items():
+    for name, value in checkpoint_kwargs(cfg).items():
         if _supported(AIAgent, name):
             kwargs[name] = value
     return kwargs
@@ -911,7 +1210,7 @@ def _build_agent(AIAgent, kwargs: dict, home, session_id: str, state_db: bool =
     try:
         agent = AIAgent(**kwargs)
     except BaseException:
-        _release_session_db(session_db)
+        release_session_db(session_db)
         raise
     agent._talaria_session_db = session_db  # released with the agent (``_release_agent``)
     return agent
@@ -963,7 +1262,7 @@ def _release_agent(agent, home) -> threading.Thread:
             if not released:
                 # The memory flush needs the profile; the LLM clients and the Codex child close regardless.
                 call("release_clients")
-            _release_session_db(getattr(agent, "_talaria_session_db", None))
+            release_session_db(getattr(agent, "_talaria_session_db", None))
             with _RELEASES_LOCK:
                 _RELEASES.pop(thread, None)
 
@@ -979,7 +1278,7 @@ def _release_agents_locked(entries) -> list[threading.Thread]:
     """Release cache entries that just left the cache (caller holds ``_AGENT_CACHE_LOCK``). An agent a turn still holds
     keeps its memory provider and clients; that turn releases it when it ends."""
     with _RUNS_LOCK:
-        held = [run.agent for run in _RUNS.values()] + _COMMITTING
+        held = [run.agent for run in _RUNS.values()] + [agent for agent, _home in _COMMITTING]
     return [_release_agent(agent, home) for agent, _signature, home in entries if not any(agent is other for other in held)]
 
 
@@ -1075,7 +1374,7 @@ def drain_agents(timeout: float = _AGENT_RELEASE_TIMEOUT) -> None:
     """Shutdown: release every cached agent, stop running turns (like a Stop) so each releases the agent it holds, and
     wait, bounded, for those turns and every release still running."""
     deadline = time.monotonic() + timeout
-    with _AGENT_CACHE_LOCK, _RUNS_LOCK:
+    with _MCP_DISCOVERY_LOCK, _AGENT_CACHE_LOCK, _RUNS_LOCK:
         # Admission closes with the snapshot, so no later turn forks a review outside it.
         _DRAINING.set()
         runs = list(_RUNS.values())
@@ -1096,6 +1395,8 @@ def drain_agents(timeout: float = _AGENT_RELEASE_TIMEOUT) -> None:
     with _RELEASES_LOCK:
         threads = list(_RELEASES)
     _join(threads, deadline)
+    # TAL-1191: the state.db handles state_db writes keep between turns; each final release checkpoints once.
+    release_all()
 
 
 def refresh_profile_agents_mcp_tools(home) -> None:
@@ -1108,34 +1409,69 @@ def refresh_profile_agents_mcp_tools(home) -> None:
 
     target = os.path.realpath(home)
     with _AGENT_CACHE_LOCK:
-        failed = []
-        for session_id, entry in list(_AGENT_CACHE.items()):
-            if os.path.realpath(entry[2]) != target:
-                continue
+        entries = [(sid, entry) for sid, entry in _AGENT_CACHE.items() if os.path.realpath(entry[2]) == target]
+        _COMMITTING.extend((entry[0], entry[2]) for _sid, entry in entries)
+    try:
+        for session_id, (agent, _signature, _home) in entries:
             try:
-                refresh_agent_mcp_tools(entry[0], quiet_mode=True, content_aware=True)
+                refresh_agent_mcp_tools(agent, quiet_mode=True, content_aware=True)
             except Exception:  # noqa: BLE001
-                log.warning("Failed to refresh MCP tools for session %s; evicting its agent", session_id, exc_info=True)
-                failed.append(_AGENT_CACHE.pop(session_id))
-        _release_agents_locked(failed)
+                log.warning("Failed to refresh MCP tools for session %s", session_id, exc_info=True)
+                with _AGENT_CACHE_LOCK:
+                    cached = _AGENT_CACHE.get(session_id)
+                    # A turn may have replaced or evicted this agent while its refresh ran.
+                    if cached is not None and cached[0] is agent:
+                        _AGENT_CACHE.pop(session_id)
+    finally:
+        with _AGENT_CACHE_LOCK:
+            for _sid, (agent, _signature, owner) in entries:
+                _COMMITTING.remove((agent, owner))
+                _release_if_dropped_locked(agent, owner)
+
 
+@contextlib.contextmanager
+def release_profile_agents(home):
+    """Fence discovery and drain this profile's agents and background work before the caller removes its home."""
+    from .commands import forget_profile_mcp_tools
 
-def release_profile_agents(home) -> None:
-    """Profile deletion: release the profile's cached agents, cancel their background reviews, and wait for both and
-    every release running under its home. Fails rather than let the home go while a memory flush still runs under it."""
     target = os.path.realpath(home)
+    with _MCP_DISCOVERY_LOCK:
+        if target in _MCP_CLOSING_HOMES:
+            raise RpcError("The profile is already being deleted.", condition="profile_unavailable")
+        _MCP_CLOSING_HOMES.add(target)
+    try:
+        with _AGENT_CACHE_LOCK:
+            entries = [_AGENT_CACHE.pop(sid) for sid, entry in list(_AGENT_CACHE.items()) if os.path.realpath(entry[2]) == target]
+            started = _release_agents_locked(entries)
+        started += _cancel_background_reviews([(entry[0], entry[2]) for entry in entries], "profile deleted")
+        deadline = time.monotonic() + _PROFILE_RELEASE_TIMEOUT
+        # Non-turn holders keep their agent past the cache; its release starts when the last holder lets go.
+        while (holding := _holding_home(target)) and time.monotonic() < deadline:
+            time.sleep(0.05)
+        # The threads started here count even once they left ``_RELEASES``: a fast failure must still block the delete.
+        with _RELEASES_LOCK:
+            threads = list(dict.fromkeys(started + [thread for thread, owner in _RELEASES.items() if owner is not None and os.path.realpath(owner) == target]))
+        _join(threads, deadline)
+        if any(thread.is_alive() and thread.name.startswith("chat-mcp-") for thread in threads):
+            raise RpcError("The profile is still connecting MCP tools. Retry in a moment.")
+        if holding or any(thread.is_alive() for thread in threads):
+            raise RpcError("The profile is still saving memory from its chats. Retry in a moment.")
+        if any(thread.failed for thread in threads):
+            raise RpcError("Memory from the profile's chats could not be saved; see the sidecar log. Retry to delete the profile anyway.")
+        release_home(target)
+        yield
+        # The old generation has no worker left that could restore its readiness after deletion.
+        forget_profile_mcp_tools(target)
+        with _MCP_DISCOVERY_LOCK:
+            _MCP_DISCOVERIES.pop(target, None)
+    finally:
+        with _MCP_DISCOVERY_LOCK:
+            _MCP_CLOSING_HOMES.discard(target)
+
+
+def _holding_home(target: str) -> bool:
     with _AGENT_CACHE_LOCK:
-        entries = [_AGENT_CACHE.pop(sid) for sid, entry in list(_AGENT_CACHE.items()) if os.path.realpath(entry[2]) == target]
-        started = _release_agents_locked(entries)
-    started += _cancel_background_reviews([(entry[0], entry[2]) for entry in entries], "profile deleted")
-    # The threads started here count even once they left ``_RELEASES``: a fast failure must still block the delete.
-    with _RELEASES_LOCK:
-        threads = list(dict.fromkeys(started + [thread for thread, owner in _RELEASES.items() if owner is not None and os.path.realpath(owner) == target]))
-    _join(threads, time.monotonic() + _PROFILE_RELEASE_TIMEOUT)
-    if any(thread.is_alive() for thread in threads):
-        raise RpcError("The profile is still saving memory from its chats. Retry in a moment.")
-    if any(thread.failed for thread in threads):
-        raise RpcError("Memory from the profile's chats could not be saved; see the sidecar log. Retry to delete the profile anyway.")
+        return any(os.path.realpath(home) == target for _agent, home in _COMMITTING)
 
 
 def _acquire_session_db(home):
@@ -1151,17 +1487,6 @@ def _acquire_session_db(home):
         return None
 
 
-def _release_session_db(db) -> None:
-    if db is None:
-        return
-    try:
-        from hermes_state_registry import release_or_close
-
-        release_or_close(db)
-    except Exception:  # noqa: BLE001
-        log.warning("releasing an agent's state.db handle failed", exc_info=True)
-
-
 def _execution_session_id(db, session_id: str) -> str:
     """Predecessor ``_resolve_agent_execution_session_id``: a new agent for a session the Agent rotated by compression
     (the old agent went with a sidecar restart or a runtime change) runs on the live tip, with the server's history,
@@ -1187,6 +1512,20 @@ def _agent_class():
     return AIAgent
 
 
+def _require_data_use_support(history: list) -> frozenset[str]:
+    """A downgraded Agent must never send history whose connector privacy requirements it cannot enforce."""
+    if not any(isinstance(row, dict) and row.get("data_use") for row in history):
+        return frozenset()
+    try:
+        from agent.message_metadata import DATA_USE, data_use_requirement
+    except ImportError:
+        pass
+    else:
+        if DATA_USE == "data_use" and callable(data_use_requirement):
+            return data_use_requirement(history)
+    raise RpcError("This Agent release cannot enforce connector privacy requirements. Update Hermes Agent before continuing, compressing or refining this chat.", condition="agent_incompatible")
+
+
 def _max_iterations_summary_request() -> str:
     """The user row the Agent appends to ask for a summary once its tool budget runs out; the server drops it."""
     try:
@@ -1326,7 +1665,12 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
         history = []
     if not isinstance(history, list):
         raise InvalidParams("conversation_history must be a list")
-    toolsets = _turn_toolsets(params.get("enabled_toolsets"))
+    _require_data_use_support(history)
+    from hermes_cli.config import load_config_readonly
+
+    # Borrow one snapshot per turn; helpers copy values retained by the Agent.
+    cfg = load_config_readonly() or {}
+    toolsets = _turn_toolsets(params.get("enabled_toolsets"), cfg)
     system_message = params.get("system_message")
     home = profile_home_param(params)
     run = _Run(stream_id, session_id, ctx)
@@ -1348,8 +1692,12 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
     raw_emit = ctx.emit
     steer_state = {"last": None}
     usage_state = {"last": None}
+    pending_mcp = False
+    token_parts: list[str] = []
+    last_token_flush: float | None = None
+    emit_lock = threading.Lock()
 
-    def emit(event, data=None):
+    def emit_frame(event, data=None):
         """Predecessor ``_webui_steer_events_before``: before content frames, report the Agent's pending steer text
         whenever it changed so the server can mark consumed steers live rather than only after ``done``. TAL-397: the
         Agent's session counters ride the same boundary, so the server meters cost and tokens while the turn runs."""
@@ -1363,9 +1711,38 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                 usage_state["last"] = usage
                 raw_emit("usage", usage)
         raw_emit(event, data)
+
+    def flush_tokens():
+        nonlocal last_token_flush
+        if token_parts:
+            text = "".join(token_parts)
+            token_parts.clear()
+            last_token_flush = time.monotonic()
+            emit_frame("token", {"text": text})
+
+    def emit(event, data=None):
+        # Batch before snapshots/serialization; the lock keeps tool-worker and watcher frames in order.
+        with emit_lock:
+            if event == "token":
+                token_parts.append(data["text"])
+                if last_token_flush is None or time.monotonic() - last_token_flush >= 0.016:
+                    flush_tokens()
+            else:
+                flush_tokens()
+                emit_frame(event, data)
+
+    timing = getattr(ctx, "timing", None)
     try:
-        _discover_mcp_tools(run)
-        runtime = _resolve_runtime(provider, model)
+        if timing:
+            timing.begin("mcp_discovery")
+        mcp_discovery = _discover_mcp_tools(run)
+        pending_mcp = mcp_discovery is not None
+        if timing:
+            timing.end("mcp_discovery", "cancelled" if ctx.cancelled or run.cancel.is_set() else "timeout" if pending_mcp else run.mcp_discovery_outcome)
+        with timing.span("runtime_resolution") if timing else contextlib.nullcontext():
+            runtime = _resolve_runtime(provider, model)
+        if timing:
+            timing.begin("agent_binding")
         resolved_model = model or str(runtime.get("model") or "")
         resolved_provider = provider or runtime.get("provider")
         AIAgent = _agent_class()
@@ -1449,7 +1826,12 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
             return metadata
 
         def on_tool(*cb_args, **cb_kwargs):
-            # Structured callbacks carry tool cards; the progress callback only feeds reasoning text on older builds.
+            # Structured callbacks carry tool cards; the Agent already throttles MCP progress.
+            if len(cb_args) >= 3 and cb_args[0] == "tool.progress":
+                emit("tool_progress", {"tool_call_id": str(cb_kwargs.get("tool_call_id") or ""), "message": cb_args[2],
+                                       "progress": cb_kwargs.get("progress"), "total": cb_kwargs.get("total"),
+                                       "percent": cb_kwargs.get("percent")})
+                return
             if len(cb_args) >= 3 and cb_args[0] in ("reasoning.available", "_thinking"):
                 text = cb_args[2] if cb_args[0] == "reasoning.available" else cb_args[1]
                 if text:
@@ -1634,7 +2016,7 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
             register_gateway_notify = unregister_gateway_notify = None
         approval_cb = _approval_notifier(session_id, emit) if register_gateway_notify is not None else None
 
-        kwargs = _agent_kwargs(AIAgent, params, session_id, resolved_model, resolved_provider, runtime, toolsets)
+        kwargs = _agent_kwargs(AIAgent, params, session_id, resolved_model, resolved_provider, runtime, toolsets, cfg)
         kwargs.update(stream_delta_callback=on_token, reasoning_callback=on_reasoning, tool_progress_callback=on_tool, clarify_callback=clarify_callback)
         for name, value in (
             ("interim_assistant_callback", on_interim),
@@ -1666,6 +2048,7 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                     agent = cached[0]
                     _AGENT_CACHE.move_to_end(session_id)
                     bind(agent)
+        cached_agent = agent is not None
         if agent is not None:
             for name in ("stream_delta_callback", "reasoning_callback", "tool_progress_callback", "clarify_callback", "interim_assistant_callback", "tool_start_callback", "tool_complete_callback", "tool_result_metadata_callback", "status_callback", "thinking_callback", "notice_callback", "notice_clear_callback"):
                 if name in kwargs and hasattr(agent, name):
@@ -1692,6 +2075,9 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                     _AGENT_CACHE[session_id] = (agent, signature, home)
                     _release_agents_locked([replaced] if replaced else [])
                     _evict_idle_agents_locked()
+        if timing:
+            timing.end("agent_binding", "cache_hit" if cached_agent else "ok")
+            timing.begin("conversation_setup")
         # Predecessor ``agent.ephemeral_system_prompt``: personality, surface context, progress guidance, and delivery
         # hints travel as runtime instructions that are never persisted to history.
         ephemeral = params.get("ephemeral_system_prompt")
@@ -1717,7 +2103,19 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                 log.debug("agent.clear_interrupt failed", exc_info=True)
 
         def _watch_cancel():
+            nonlocal pending_mcp
             while not run.cancel.wait(0.25):
+                if pending_mcp and mcp_discovery.is_set():
+                    # Discovery can finish while this agent is being built, after the worker's cache refresh.
+                    try:
+                        with scoped_home(home):
+                            refresh_profile_agents_mcp_tools(home)
+                    except Exception:  # noqa: BLE001 - refresh failure must not disable Stop
+                        log.warning("Late MCP refresh failed", exc_info=True)
+                    with run.lock:
+                        if pending_mcp:
+                            emit("notice_clear", {"key": _MCP_PENDING_KEY})
+                            pending_mcp = False
                 if run.finished.is_set():
                     return
                 if ctx.cancelled:
@@ -1765,6 +2163,10 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                 bind_turn_secret_capture = None
                 log.debug("Agent lacks turn-local skill secret capture; secure setup is unavailable")
             with bind_turn_secret_capture(skill_secret_prompt) if bind_turn_secret_capture and params.get("skill_secret") is True else contextlib.nullcontext():
+                if timing:
+                    timing.end("conversation_setup")
+                    timing.observe("conversation_entry")
+                    timing.emit("conversation_entry")
                 raw = agent.run_conversation(**run_kwargs)
             result = raw if isinstance(raw, dict) else {}
         except Exception as exc:  # noqa: BLE001
@@ -1827,6 +2229,12 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
             "live_tool_calls": live_tool_calls,
         }
     finally:
+        with emit_lock:
+            flush_tokens()
+        with run.lock:
+            if pending_mcp:
+                emit("notice_clear", {"key": _MCP_PENDING_KEY})
+                pending_mcp = False
         with _AGENT_CACHE_LOCK:
             with _RUNS_LOCK:
                 _RUNS.pop(stream_id, None)
@@ -1900,6 +2308,7 @@ def compress(ctx: CallContext, params: dict) -> dict:
     history = params.get("conversation_history")
     if not isinstance(history, list):
         raise InvalidParams("conversation_history must be a list")
+    _require_data_use_support(history)
     model = str(params.get("model") or "").strip()
     provider = str(params.get("model_provider") or "").strip() or None
     focus_topic = str(params.get("focus_topic") or "").strip()[:500] or None
@@ -1987,7 +2396,7 @@ def _refine_agent(params: dict, session_id: str, home):
                 return None
         cached = _AGENT_CACHE.get(session_id)
         if cached is not None:
-            _COMMITTING.append(cached[0])
+            _COMMITTING.append((cached[0], home))
             return cached[0]
     model = str(params.get("model") or "").strip()
     provider = str(params.get("model_provider") or "").strip() or None
@@ -2012,7 +2421,7 @@ def _refine_agent(params: dict, session_id: str, home):
         cached = _AGENT_CACHE.get(session_id)
         agent = None if running else cached[0] if cached else built
         if agent is not None:
-            _COMMITTING.append(agent)
+            _COMMITTING.append((agent, home))
         if agent is built:
             built._talaria_unannounced = True  # its first turn announces it (``start``)
             _AGENT_CACHE[session_id] = (built, signature, home)
@@ -2030,6 +2439,7 @@ def refine(params: dict) -> str:
     messages = params.get("messages")
     if not session_id or not isinstance(messages, list):
         raise InvalidParams("session_id and messages are required")
+    _require_data_use_support(messages)
     focus = str(params.get("focus") or "").strip()
     with _RUNS_LOCK:
         if _session_running_locked(session_id):
@@ -2049,7 +2459,7 @@ def refine(params: dict) -> str:
         return f"/refine failed to start: {exc}"
     finally:
         with _AGENT_CACHE_LOCK:
-            _COMMITTING.remove(agent)
+            _COMMITTING.remove((agent, home))
             _release_if_dropped_locked(agent, home)
     tail = f" (focus: {focus})" if focus else ""
     return f"⚗ Reviewing this conversation in the background{tail} — any memory/skill updates will be reported when done."
@@ -2074,18 +2484,18 @@ def register(registry) -> None:
         workspace = params.get("workspace")
         if not isinstance(workspace, str) or not workspace.strip():
             raise InvalidParams("workspace is required")
-        with scoped_home(profile_home_param(params)):
+        with agent_scope(profile_home_param(params)):
             with _turn_identity(session_id, workspace):
                 return start(ctx, params)
 
     @registry.method("chat.compress")
     def compress_(ctx: CallContext, params: dict) -> dict:
-        with scoped_home(profile_home_param(params)):
+        with agent_scope(profile_home_param(params)):
             return compress(ctx, params)
 
     @registry.method("chat.refine")
     def refine_(ctx: CallContext, params: dict) -> dict:
-        with scoped_home(profile_home_param(params)):
+        with agent_scope(profile_home_param(params)):
             return {"output": refine(params)}
 
     @registry.method("chat.compress_finalize", requires_agent=False)
@@ -2156,15 +2566,22 @@ def register(registry) -> None:
     def finalize_(ctx: CallContext, params: dict) -> dict:
         session_id = str(params.get("session_id") or "").strip()
         reason = params.get("reason")
-        if not session_id or reason not in ("clear", "delete"):
-            raise InvalidParams("session_id and reason (clear/delete) are required")
+        if not session_id or reason not in ("clear", "delete", "archive"):
+            raise InvalidParams("session_id and reason (clear/delete/archive) are required")
+        lineage = params.get("lineage")
+        if lineage is not None and (not isinstance(lineage, list) or len(lineage) > 10_000
+                                    or any(not isinstance(sid, str) or not sid for sid in lineage)):
+            raise InvalidParams("lineage must contain session ids")
         home = profile_home_param(params)
         messages: list[str] = []
 
         def finalize() -> None:
             try:
                 # Scope inside the worker: a timed-out plugin keeps its own profile until it finishes.
-                with scoped_home(home):
+                with agent_scope(home):
+                    if reason == "archive":
+                        _notify_archive(home, session_id, lineage)
+                        return
                     from hermes_cli import lifecycle
 
                     callback = getattr(lifecycle, "finalize_session", None)
@@ -2175,11 +2592,15 @@ def register(registry) -> None:
                     if extract is not None:
                         messages.extend(extract(results))
             except Exception:  # noqa: BLE001 - hooks must never block the boundary
-                log.warning("Session finalize failed for %s (%s)", session_id, reason, exc_info=True)
+                log.warning("Session lifecycle callback failed (%s)", reason)
             finally:
                 with _RELEASES_LOCK:
                     _RELEASES.pop(worker, None)
 
+        if reason == "archive":
+            worker = _ArchiveCallback(finalize)
+            _schedule_archive(worker, home)
+            return {"messages": []}
         worker = threading.Thread(target=finalize, name="session-finalize", daemon=True)
         worker.failed = False  # type: ignore[attr-defined] - hook failures do not prevent profile deletion
         with _RELEASES_LOCK:
@@ -2187,7 +2608,7 @@ def register(registry) -> None:
         worker.start()
         worker.join(_SESSION_FINALIZE_TIMEOUT)
         if worker.is_alive():
-            log.warning("Session finalize exceeded %ss for %s (%s)", _SESSION_FINALIZE_TIMEOUT, session_id, reason)
+            log.warning("Session lifecycle callback exceeded deadline (%s)", reason)
             return {"messages": []}
         return {"messages": messages}
 
@@ -2219,12 +2640,52 @@ def register(registry) -> None:
             _release_vault_session(session_id)
         return {"evicted": entry is not None}
 
+    @registry.method("chat.context_detail", requires_agent=False)
+    def context_detail_(ctx: CallContext, params: dict) -> dict:
+        from ..context_detail import project, unavailable
+        home = profile_home_param(params).resolve()
+        sid = str(params.get("session_id") or "")
+        with _AGENT_CACHE_LOCK:
+            cached = _AGENT_CACHE.get(sid)
+            if cached is None:
+                return unavailable("not_built")
+            agent = cached[0]
+            if (Path(cached[2]).resolve() != home or getattr(agent, "model", None) != params.get("model")
+                    or getattr(agent, "provider", None) != params.get("model_provider")):
+                return unavailable("changed")
+            def marks():
+                comp = getattr(agent, "context_compressor", None)
+                return (getattr(agent, "model", None), getattr(agent, "provider", None),
+                        getattr(comp, "compression_count", None), getattr(comp, "last_prompt_tokens", None),
+                        len(getattr(agent, "_session_messages", None) or []))
+            before = marks()
+            # Pin the cache entry across the read just like refine/memory, so eviction defers its release.
+            _COMMITTING.append((agent, cached[2]))
+        try:
+            from agent.context_breakdown import compute_session_context_breakdown
+            from agent.context_file_sources import context_file_sources_for_agent
+            with scoped_home(home), session_workspace(params.get("workspace")):
+                payload = compute_session_context_breakdown(agent, list(getattr(agent, "_session_messages", None) or []))
+                payload['context_files'] = context_file_sources_for_agent(agent)
+            with _AGENT_CACHE_LOCK:
+                if _AGENT_CACHE.get(sid) is not cached or before != marks():
+                    return unavailable("changed")
+            return project(payload)
+        except ImportError:
+            return unavailable("unsupported")
+        except Exception:  # never expose Agent diagnostics, prompt contents or paths
+            return unavailable()
+        finally:
+            with _AGENT_CACHE_LOCK:
+                _COMMITTING.remove((agent, cached[2]))
+                _release_if_dropped_locked(agent, cached[2])
+
     @registry.method("chat.commit_memory", requires_agent=False)
     def commit_memory_(ctx: CallContext, params: dict) -> dict:
         """Predecessor ``commit_session_memory``: flush the cached Agent's memory for a session the user just left.
-        Providers get the session's transcript and run under its profile's ``scoped_home``."""
+        Providers get the session's transcript and run under the ``scoped_home`` the Agent was built in, which v0.22.3
+        binds them to (like ``_release_agent``), not the request's ``profile_home``."""
         session_id = str(params.get("session_id") or "").strip()
-        home = profile_home_param(params)
         with _AGENT_CACHE_LOCK:
             cached = _AGENT_CACHE.get(session_id)
             with _RUNS_LOCK:
@@ -2233,16 +2694,16 @@ def register(registry) -> None:
             commit = getattr(agent, "commit_memory_session", None) if agent is not None else None
             if commit is None or busy:
                 return {"committed": False}
-            _COMMITTING.append(agent)
+            _COMMITTING.append((agent, cached[2]))
         try:
-            with scoped_home(home):
+            with scoped_home(cached[2]):
                 commit(list(getattr(agent, "_session_messages", None) or []))
         except Exception as exc:  # noqa: BLE001
             log.warning("commit_memory_session() failed for session %s: %s", session_id, exc)
             return {"committed": False}
         finally:
             with _AGENT_CACHE_LOCK:
-                _COMMITTING.remove(agent)
+                _COMMITTING.remove((agent, cached[2]))
                 _release_if_dropped_locked(agent, cached[2])
         return {"committed": True}
 
@@ -2259,7 +2720,7 @@ def register(registry) -> None:
             raise RpcError(f"approval module unavailable: {exc}", condition="agent_unavailable") from exc
         with scoped_home(profile_home_param(params)):
             entries = approval_mod.list_gateway_approvals(session_id)
-            targets = [e for e in entries if not request_id or e.get("request_id") == request_id]
+            targets = [e for e in entries if e.get("request_id") == request_id] if request_id else entries[:1]
             keys = []
             for entry in targets:
                 keys.extend(entry.get("pattern_keys") or [entry.get("pattern_key", "")])
@@ -2267,17 +2728,21 @@ def register(registry) -> None:
             if choice == "session":
                 for k in keys:
                     approval_mod.approve_session(session_id, k)
-            elif choice == "always":
+            elif choice == "always" and keys:
+                permanent_set = getattr(approval_mod, "_permanent_set", None)
+                baseline_key = getattr(approval_mod, "_baseline_key", None)
+                baselines = getattr(approval_mod, "_permanent_baseline_by_home", None)
+                if not callable(permanent_set) or not callable(baseline_key) or not isinstance(baselines, dict):
+                    raise RpcError("Agent cannot safely persist command approvals", condition="agent_incompatible")
                 for k in keys:
                     approval_mod.approve_session(session_id, k)
                     approval_mod.approve_permanent(k)
                 try:
-                    # Persist the set that governs THIS home (per-profile under the home override), not the launch
-                    # profile's module-level set, which would overwrite a named profile's allowlist with the wrong keys.
-                    permanent_set = getattr(approval_mod, "_permanent_set", None)
+                    # Older retained Agents' _persist_choice saves full snapshots. Capture only unsaved grants
+                    # against this home's baseline, so a concurrent revocation cannot become fresh approval intent.
                     with approval_mod._lock:
-                        snapshot = set(permanent_set()) if callable(permanent_set) else set(approval_mod._permanent_approved)
-                    approval_mod.save_permanent_allowlist(snapshot)
+                        grants = permanent_set() - baselines.get(baseline_key(), set())
+                    approval_mod.save_permanent_allowlist(grants)
                 except Exception:  # noqa: BLE001
                     log.debug("save_permanent_allowlist failed", exc_info=True)
             resolved = approval_mod.resolve_gateway_approval(session_id, choice, request_id=request_id)