Add files using upload-large-folder tool

tests/agent/conftest.py

@@ -0,0 +1,39 @@
+"""Fast-path fixtures shared across tests/agent/.
+
+Many tests in this directory exercise the retry/backoff paths in the
+agent loop. Production code uses ``jittered_backoff(base_delay=5.0)``
+with a ``while time.time() < sleep_end`` loop — a single retry test
+spends 5+ seconds of real wall-clock time on backoff waits.
+
+Mocking ``jittered_backoff`` to return 0.0 collapses the while-loop
+to a no-op (``time.time() < time.time() + 0`` is false immediately),
+which handles the most common case without touching ``time.sleep``.
+
+We deliberately DO NOT mock ``time.sleep`` here — some tests
+(test_interrupt_propagation, test_primary_runtime_restore, etc.) use
+the real ``time.sleep`` for threading coordination or assert that it
+was called with specific values. Tests that want to additionally
+fast-path direct ``time.sleep(N)`` calls in production code should
+monkeypatch ``run_agent.time.sleep`` locally (see
+``test_anthropic_error_handling.py`` for the pattern).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _fast_retry_backoff(request, monkeypatch):
+    """Short-circuit retry backoff for all tests in this directory.
+
+    Tests that assert on the real backoff value opt out with
+    ``@pytest.mark.real_retry_backoff``.
+    """
+    if request.node.get_closest_marker("real_retry_backoff"):
+        return
+    # The agent.turn_* retry paths import ``jittered_backoff`` lazily from
+    # ``agent.retry_utils``; patch it there so rate-limit / invalid-response /
+    # server-error retries don't burn real wall-clock seconds.
+    from agent import retry_utils as _retry_utils
+    monkeypatch.setattr(_retry_utils, "jittered_backoff", lambda *a, **k: 0.0)

tests/agent/test_account_usage.py

@@ -0,0 +1,229 @@
+from types import SimpleNamespace
+
+import pytest
+
+from agent import account_usage
+
+
+class _FakeResponse:
+    def __init__(self, payload):
+        self._payload = payload
+
+    def raise_for_status(self):
+        return None
+
+    def json(self):
+        return self._payload
+
+
+class _FakeClient:
+    def __init__(self, calls, payload):
+        self.calls = calls
+        self.payload = payload
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def get(self, url, headers):
+        self.calls.append({"url": url, "headers": headers})
+        return _FakeResponse(self.payload)
+
+
+@pytest.fixture
+def codex_usage_payload():
+    return {
+        "plan_type": "plus",
+        "rate_limit": {
+            "primary_window": {
+                "used_percent": 21,
+                "reset_at": 1779846359,
+            },
+            "secondary_window": {
+                "used_percent": 4,
+                "reset_at": 1780230796,
+            },
+        },
+        "credits": {"has_credits": False},
+    }
+
+
+def test_codex_usage_prefers_explicit_live_agent_credentials(monkeypatch, codex_usage_payload):
+    calls = []
+    monkeypatch.setattr(
+        account_usage.httpx,
+        "Client",
+        lambda timeout: _FakeClient(calls, codex_usage_payload),
+    )
+    monkeypatch.setattr(
+        account_usage,
+        "resolve_codex_runtime_credentials",
+        lambda **kwargs: (_ for _ in ()).throw(AssertionError("legacy auth should not be used")),
+    )
+
+    snapshot = account_usage.fetch_account_usage(
+        "openai-codex",
+        base_url="https://chatgpt.com/backend-api/codex",
+        api_key="live-agent-token",
+    )
+
+    assert snapshot is not None
+    assert snapshot.provider == "openai-codex"
+    assert snapshot.plan == "Plus"
+    assert [w.label for w in snapshot.windows] == ["Session", "Weekly"]
+    assert snapshot.windows[0].used_percent == 21
+    assert calls[0]["url"] == "https://chatgpt.com/backend-api/wham/usage"
+    assert calls[0]["headers"]["Authorization"] == "Bearer live-agent-token"
+
+
+def test_codex_usage_falls_back_to_native_credential_pool(monkeypatch, codex_usage_payload):
+    calls = []
+    monkeypatch.setattr(
+        account_usage.httpx,
+        "Client",
+        lambda timeout: _FakeClient(calls, codex_usage_payload),
+    )
+    # Pool fallback fires only on AuthError (the documented "no creds" mode of
+    # the resolver), NOT on arbitrary exceptions — see the transient-error guard
+    # test below.
+    monkeypatch.setattr(
+        account_usage,
+        "resolve_codex_runtime_credentials",
+        lambda **kwargs: (_ for _ in ()).throw(
+            account_usage.AuthError("no singleton auth", provider="openai-codex", code="codex_auth_missing")
+        ),
+    )
+
+    pool_entry = SimpleNamespace(
+        runtime_api_key="pooled-token",
+        runtime_base_url="https://chatgpt.com/backend-api/codex",
+    )
+    pool = SimpleNamespace(select=lambda: pool_entry)
+
+    import agent.credential_pool as credential_pool
+
+    monkeypatch.setattr(credential_pool, "load_pool", lambda provider: pool)
+
+    snapshot = account_usage.fetch_account_usage("openai-codex")
+
+    assert snapshot is not None
+    assert snapshot.windows[0].label == "Session"
+    assert snapshot.windows[1].label == "Weekly"
+    assert calls[0]["url"] == "https://chatgpt.com/backend-api/wham/usage"
+    assert calls[0]["headers"]["Authorization"] == "Bearer pooled-token"
+    # Pool creds have no account_id concept — the ChatGPT-Account-Id header must
+    # be omitted rather than sent stale/wrong.
+    assert "ChatGPT-Account-Id" not in calls[0]["headers"]
+
+
+
+
+def test_codex_usage_account_id_read_failure_keeps_singleton_token(monkeypatch, codex_usage_payload):
+    """When the resolver succeeds but the separate account_id read raises, the
+    working singleton token must still be used (best-effort account_id), NOT
+    abandoned in favor of a header-less pool credential."""
+    calls = []
+    monkeypatch.setattr(
+        account_usage.httpx,
+        "Client",
+        lambda timeout: _FakeClient(calls, codex_usage_payload),
+    )
+    monkeypatch.setattr(
+        account_usage,
+        "resolve_codex_runtime_credentials",
+        lambda **kwargs: {
+            "api_key": "singleton-token",
+            "base_url": "https://chatgpt.com/backend-api/codex",
+        },
+    )
+    monkeypatch.setattr(
+        account_usage,
+        "_read_codex_tokens",
+        lambda *a, **k: (_ for _ in ()).throw(
+            account_usage.AuthError("partial store", provider="openai-codex", code="codex_auth_invalid_shape")
+        ),
+    )
+
+    import agent.credential_pool as credential_pool
+
+    monkeypatch.setattr(
+        credential_pool,
+        "load_pool",
+        lambda provider: (_ for _ in ()).throw(AssertionError("pool must not be consulted")),
+    )
+
+    snapshot = account_usage.fetch_account_usage("openai-codex")
+
+    assert snapshot is not None
+    assert calls[0]["headers"]["Authorization"] == "Bearer singleton-token"
+    # account_id read failed → header omitted, but the singleton token is kept.
+    assert "ChatGPT-Account-Id" not in calls[0]["headers"]
+
+
+
+
+# ── Banked rate-limit reset credits (`/usage reset`) ─────────────────────────
+
+
+class _FakeResetClient:
+    """GET returns the usage payload; POST returns the consume payload."""
+
+    def __init__(self, calls, usage_payload, consume_payload=None):
+        self.calls = calls
+        self.usage_payload = usage_payload
+        self.consume_payload = consume_payload or {}
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def get(self, url, headers):
+        self.calls.append({"method": "GET", "url": url, "headers": headers})
+        return _FakeResponse(self.usage_payload)
+
+    def post(self, url, headers=None, json=None):
+        self.calls.append({"method": "POST", "url": url, "headers": headers, "json": json})
+        return _FakeResponse(self.consume_payload)
+
+
+def _usage_payload_with_resets(primary_used, secondary_used, banked):
+    return {
+        "plan_type": "plus",
+        "rate_limit": {
+            "primary_window": {"used_percent": primary_used, "reset_at": 1779846359},
+            "secondary_window": {"used_percent": secondary_used, "reset_at": 1780230796},
+        },
+        "rate_limit_reset_credits": {"available_count": banked},
+        "credits": {"has_credits": False},
+    }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+def test_redeem_missing_credentials_reports_unavailable(monkeypatch):
+    monkeypatch.setattr(
+        account_usage,
+        "_resolve_codex_usage_credentials",
+        lambda base_url, api_key: (_ for _ in ()).throw(RuntimeError("no creds")),
+    )
+
+    result = account_usage.redeem_codex_reset_credit()
+
+    assert result.status == "unavailable"
+    assert "hermes auth" in result.message

tests/agent/test_anthropic_borrowed_row_authority.py

@@ -0,0 +1,281 @@
+"""The borrowed ``claude_code`` row is a reference, never a token authority.
+
+``claude_code`` is absent from ``_PERSISTABLE_PROVIDER_SOURCES``, so
+``sanitize_borrowed_credential_payload`` strips ``access_token`` and
+``refresh_token`` before the pool row reaches ``auth.json``: what survives on
+disk is provenance, status and a ``secret_fingerprint``.  ``load_pool()``
+re-hydrates the live pair from ``~/.claude/.credentials.json`` on every load,
+which is what makes the singleton -- not the pool store -- authoritative for
+this source.
+
+Two failure modes follow from forgetting that, and both are covered here:
+
+1. ``_sync_anthropic_entry_from_pool_store()`` re-reads the persisted row
+   during refresh.  For a borrowed source that row has *no* tokens, so it
+   "differs" from the live entry and was adopted as though another process had
+   rotated the pair -- blanking a usable credential and returning before
+   ``_claude_code_credentials_lock()`` and the authoritative re-read were ever
+   entered.
+2. ``_available_entries()`` only refused to lease empty *API-key* rows, so the
+   blanked OAuth entry stayed selectable and would have been sent as an empty
+   bearer.
+
+The existing race/write-through suites build ``CredentialPool`` objects
+directly or back the store with unsanitized in-memory rows, so neither crosses
+the real persistence boundary.  Every test below starts from ``load_pool()``
+reading an actually persisted, actually sanitized row.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import replace as dc_replace
+
+import pytest
+
+from agent import anthropic_credentials as AA
+from agent.credential_persistence import sanitize_borrowed_credential_payload
+from agent.credential_pool import (
+    AUTH_TYPE_OAUTH,
+    CredentialPool,
+    PooledCredential,
+    load_pool,
+)
+
+_EXPIRED_MS = 1_000
+
+_STALE_ACCESS = "sk-ant-oat01-borrowed-stale"
+_STALE_REFRESH = "sk-ant-ort01-borrowed-stale"
+_ROTATED_ACCESS = "sk-ant-oat01-borrowed-rotated"
+_ROTATED_REFRESH = "sk-ant-ort01-borrowed-rotated"
+
+
+@pytest.fixture
+def hermes_home(tmp_path, monkeypatch):
+    """Real on-disk HERMES_HOME so ``load_pool()`` re-reads what it persisted."""
+    home = tmp_path / "hermes"
+    home.mkdir(parents=True, exist_ok=True)
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    for var in ("ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"):
+        monkeypatch.delenv(var, raising=False)
+    (home / "auth.json").write_text(
+        json.dumps({"version": 1, "providers": {}}), encoding="utf-8"
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth.is_provider_explicitly_configured", lambda pid: True
+    )
+    return home
+
+
+@pytest.fixture
+def claude_credentials(tmp_path, monkeypatch):
+    """Point the ``claude_code`` singleton at a tmp file holding a stale pair."""
+    cred_path = tmp_path / "claude" / ".credentials.json"
+    cred_path.parent.mkdir(parents=True, exist_ok=True)
+    cred_path.write_text(
+        json.dumps(
+            {
+                "claudeAiOauth": {
+                    "accessToken": _STALE_ACCESS,
+                    "refreshToken": _STALE_REFRESH,
+                    "expiresAt": _EXPIRED_MS,
+                    "scopes": ["user:inference", "user:profile"],
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(AA, "claude_code_credentials_path", lambda: cred_path)
+    monkeypatch.setattr(AA, "_read_claude_code_credentials_from_keychain", lambda: None)
+    return cred_path
+
+
+def _persisted_rows(home):
+    store = json.loads((home / "auth.json").read_text(encoding="utf-8"))
+    return store.get("credential_pool", {}).get("anthropic", [])
+
+
+def _claude_pair(cred_path):
+    data = json.loads(cred_path.read_text(encoding="utf-8"))["claudeAiOauth"]
+    return data["accessToken"], data["refreshToken"]
+
+
+def _rotating_refresh(refresh_token, **_kw):
+    return {
+        "access_token": _ROTATED_ACCESS,
+        "refresh_token": _ROTATED_REFRESH,
+        "expires_at_ms": int(time.time() * 1000) + 3_600_000,
+    }
+
+
+def test_persisted_claude_code_row_carries_no_token_material(
+    hermes_home, claude_credentials
+):
+    """Baseline: the row the refresh path re-reads really is sanitized.
+
+    Every other test in this file only means something if the disk row is
+    token-less, so assert the boundary rather than assuming it.
+    """
+    pool = load_pool("anthropic")
+
+    live = [e for e in pool._entries if e.source == "claude_code"]
+    assert len(live) == 1
+    assert live[0].access_token == _STALE_ACCESS, (
+        "load_pool must hydrate the live pair from the singleton"
+    )
+
+    rows = [r for r in _persisted_rows(hermes_home) if r.get("source") == "claude_code"]
+    assert len(rows) == 1
+    assert not rows[0].get("access_token")
+    assert not rows[0].get("refresh_token")
+    assert str(rows[0].get("secret_fingerprint", "")).startswith("sha256:")
+    assert sanitize_borrowed_credential_payload(rows[0], "anthropic") == rows[0]
+
+
+def test_pool_store_sync_never_adopts_a_borrowed_row(hermes_home, claude_credentials):
+    """The sanitized row must not be mistaken for a rotation by another process."""
+    pool = load_pool("anthropic")
+    entry = next(e for e in pool._entries if e.source == "claude_code")
+
+    synced = pool._sync_anthropic_entry_from_pool_store(entry)
+
+    assert synced is entry, "a borrowed row is a reference, not token authority"
+    assert synced.access_token == _STALE_ACCESS
+    assert synced.refresh_token == _STALE_REFRESH
+
+
+def test_refresh_from_persisted_sanitized_row_keeps_the_full_pair(
+    hermes_home, claude_credentials, monkeypatch
+):
+    """The production ``load -> sanitize -> refresh`` path refreshes, not blanks.
+
+    Exactly one POST and one authoritative write, the returned entry carries
+    the complete rotated pair, and the shared credentials file is the copy that
+    was updated.
+    """
+    posts = []
+    writes = []
+
+    def _counting_refresh(refresh_token, **kwargs):
+        posts.append(refresh_token)
+        return _rotating_refresh(refresh_token, **kwargs)
+
+    real_write = AA._write_claude_code_credentials
+
+    def _counting_write(access_token, refresh_token, expires_at_ms):
+        writes.append(refresh_token)
+        return real_write(access_token, refresh_token, expires_at_ms)
+
+    monkeypatch.setattr(AA, "refresh_anthropic_oauth_pure", _counting_refresh)
+    monkeypatch.setattr(AA, "_write_claude_code_credentials", _counting_write)
+
+    pool = load_pool("anthropic")
+    entry = next(e for e in pool._entries if e.source == "claude_code")
+
+    refreshed = pool._refresh_entry(entry, force=True)
+
+    assert refreshed is not None, "the refresh must not be abandoned"
+    assert refreshed.access_token == _ROTATED_ACCESS
+    assert refreshed.refresh_token == _ROTATED_REFRESH
+    assert posts == [_STALE_REFRESH], f"expected exactly one POST, got {posts}"
+    assert writes == [_ROTATED_REFRESH], f"expected exactly one commit, got {writes}"
+    assert _claude_pair(claude_credentials) == (_ROTATED_ACCESS, _ROTATED_REFRESH)
+
+
+def test_refresh_reaches_the_shared_credentials_lock(
+    hermes_home, claude_credentials, monkeypatch
+):
+    """``claude_code`` must always take the path-keyed lock before deciding.
+
+    That lock is what serializes profiles sharing one
+    ``~/.claude/.credentials.json``; an adopt-and-return shortcut firing first
+    would leave the cross-profile race exactly where it was.
+    """
+    taken = []
+    real_lock = CredentialPool._claude_code_credentials_lock
+
+    def _tracking_lock(self):
+        taken.append(True)
+        return real_lock(self)
+
+    monkeypatch.setattr(CredentialPool, "_claude_code_credentials_lock", _tracking_lock)
+    monkeypatch.setattr(AA, "refresh_anthropic_oauth_pure", _rotating_refresh)
+
+    pool = load_pool("anthropic")
+    entry = next(e for e in pool._entries if e.source == "claude_code")
+    pool._refresh_entry(entry, force=True)
+
+    assert taken, "the authoritative re-read must happen under the shared-file lock"
+
+
+def test_empty_oauth_entry_is_never_leased(hermes_home, claude_credentials):
+    """A token-less OAuth row must not be selectable as an empty bearer.
+
+    The pre-existing guard covered ``AUTH_TYPE_API_KEY`` only, so an OAuth row
+    that failed to hydrate went straight into the available list.
+    """
+    pool = load_pool("anthropic")
+    entry = next(e for e in pool._entries if e.source == "claude_code")
+    blanked = dc_replace(entry, access_token="", refresh_token="")
+    pool._replace_entry(entry, blanked)
+
+    available, _pending = pool._available_entries(clear_expired=False, refresh=False)
+
+    assert all(e.access_token for e in available), (
+        "an OAuth entry with no access token must never be leased"
+    )
+    assert blanked.id not in {e.id for e in available}
+
+
+def test_selection_after_refresh_leases_only_hydrated_entries(
+    hermes_home, claude_credentials, monkeypatch
+):
+    """End-to-end: refresh through selection leaves a usable, non-empty lease."""
+    monkeypatch.setattr(AA, "refresh_anthropic_oauth_pure", _rotating_refresh)
+
+    pool = load_pool("anthropic")
+    available, _pending = pool._available_entries(clear_expired=True, refresh=True)
+
+    assert available, "the credential must survive the refresh, not be dropped"
+    assert all(e.access_token for e in available)
+    assert any(e.access_token == _ROTATED_ACCESS for e in available)
+
+
+def test_hermes_pkce_row_still_syncs_from_the_pool_store(monkeypatch):
+    """The borrowed-source refusal must not disable pool-owned adoption.
+
+    ``hermes_pkce`` *is* pool-owned, so its persisted row keeps its tokens and
+    stays a legitimate rotation witness for another pool instance.
+    """
+    rotated = {
+        "id": "anthropic-pkce",
+        "label": "anthropic oauth",
+        "auth_type": AUTH_TYPE_OAUTH,
+        "priority": 0,
+        "source": "hermes_pkce",
+        "access_token": _ROTATED_ACCESS,
+        "refresh_token": _ROTATED_REFRESH,
+        "expires_at_ms": int(time.time() * 1000) + 3_600_000,
+    }
+    monkeypatch.setattr(
+        "agent.credential_pool.read_credential_pool", lambda provider=None: [rotated]
+    )
+
+    entry = PooledCredential(
+        provider="anthropic",
+        id="anthropic-pkce",
+        label="anthropic oauth",
+        auth_type=AUTH_TYPE_OAUTH,
+        priority=0,
+        source="hermes_pkce",
+        access_token=_STALE_ACCESS,
+        refresh_token=_STALE_REFRESH,
+        expires_at_ms=_EXPIRED_MS,
+    )
+    pool = CredentialPool("anthropic", [entry])
+
+    synced = pool._sync_anthropic_entry_from_pool_store(entry)
+
+    assert synced.access_token == _ROTATED_ACCESS
+    assert synced.refresh_token == _ROTATED_REFRESH

tests/agent/test_anthropic_client_auth.py

@@ -0,0 +1,79 @@
+"""Auth-boundary shard for the Anthropic adapter.
+
+An api-key-style client must not inherit ANTHROPIC_AUTH_TOKEN from the environment: the SDK
+fills an unset ``auth_token`` from that variable and then sends ``Authorization: Bearer ***``
+alongside ``x-api-key`` on every request, shipping a foreign shell credential to third-party
+Anthropic-compatible endpoints (#105774). Kept out of ``test_anthropic_adapter.py`` for the
+per-file line ceiling.
+"""
+
+import pytest
+
+from agent.anthropic_adapter import build_anthropic_client
+
+SENTINEL = "sentinel-env-token-DO-NOT-SEND"
+
+
+def wire_headers(client) -> dict:
+    """Headers the SDK would put on a /v1/messages POST (the Omit() default is resolved here)."""
+    from anthropic._models import FinalRequestOptions
+
+    return dict(client._build_headers(FinalRequestOptions(method="post", url="/v1/messages", json_data={})))
+
+
+
+def test_api_key_client_and_its_copies_never_carry_the_env_bearer(monkeypatch):
+    """The guard is a copy-safe Omit() default header: ``with_options()`` re-runs the constructor
+    and re-reads ANTHROPIC_AUTH_TOKEN, so an attribute clear alone would re-leak on the copy."""
+    anthropic_sdk = pytest.importorskip("anthropic")
+    monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", SENTINEL)
+    from agent.anthropic_adapter import _new_sdk_client
+
+    client = _new_sdk_client(anthropic_sdk, {"api_key": "provider-key", "base_url": "http://127.0.0.1:1"}, {})
+    for wire_client in (client, client.with_options(timeout=30)):
+        headers = wire_headers(wire_client)
+        assert headers.get("x-api-key") == "provider-key"
+        assert "authorization" not in headers
+    # The bearer mirror (no env x-api-key beside a portal JWT) is owned by
+    # tests/agent/test_nous_portal_anthropic_wire.py::TestClientShape.
+
+
+def test_third_party_request_on_the_wire_carries_no_foreign_bearer(monkeypatch):
+    """End-to-end through ``build_anthropic_client`` against a local header-capturing server."""
+    pytest.importorskip("anthropic")
+    import json
+    import threading
+    from http.server import BaseHTTPRequestHandler, HTTPServer
+
+    monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", SENTINEL)
+    captured = {}
+
+    class _Handler(BaseHTTPRequestHandler):
+        def do_POST(self):
+            captured["headers"] = {k.lower(): v for k, v in self.headers.items()}
+            self.rfile.read(int(self.headers.get("content-length", 0)))
+            body = json.dumps({
+                "id": "msg_test", "type": "message", "role": "assistant",
+                "content": [{"type": "text", "text": "ok"}], "model": "test",
+                "stop_reason": "end_turn", "usage": {"input_tokens": 1, "output_tokens": 1},
+            }).encode()
+            self.send_response(200)
+            self.send_header("content-type", "application/json")
+            self.send_header("content-length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *args):
+            pass
+
+    server = HTTPServer(("127.0.0.1", 0), _Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    try:
+        client = build_anthropic_client("third-party-provider-key", base_url=f"http://127.0.0.1:{server.server_port}")
+        client.with_options(timeout=30).messages.create(
+            model="test-model", max_tokens=8, messages=[{"role": "user", "content": "hi"}])
+    finally:
+        server.shutdown()
+
+    assert captured["headers"].get("x-api-key") == "third-party-provider-key"
+    assert "authorization" not in captured["headers"]

tests/agent/test_anthropic_oauth_stress.py

@@ -0,0 +1,387 @@
+"""Load / stress test for the Anthropic OAuth cross-process refresh race fix.
+
+Companion to ``tests/agent/test_credential_pool_anthropic_refresh_race.py``,
+which proves the bug in isolation with two racers. This test scales the same scenario up to look for bottlenecks and degradation
+under real concurrency. The thread stress case keeps the suite fast while a
+separate spawn-based case uses independent interpreters, distinct profile
+homes, and one shared Claude Code credentials file. Both exercise the REAL
+cross-process file lock (``_auth_store_lock``) and REAL credential-pool
+persistence under throwaway directories — only the network call to Anthropic
+is faked. The process case also counts refresh POSTs and requires exactly one
+use of the stale single-use token, so a broken lock cannot remain green merely
+because two in-process mocks happened to finish quickly.
+"""
+
+from __future__ import annotations
+
+import json
+import multiprocessing as mp
+import os
+import queue
+import threading
+import time
+from dataclasses import replace as dc_replace
+from pathlib import Path
+
+import pytest
+
+from agent.credential_pool import (
+    AUTH_TYPE_OAUTH,
+    STATUS_EXHAUSTED,
+    CredentialPool,
+    PooledCredential,
+)
+
+CONCURRENCY = 20
+
+
+def _process_claude_code_refresh_worker(
+    profile_home: str,
+    shared_credentials_path: str,
+    server_state_path: str,
+    start_event,
+    result_queue,
+) -> None:
+    """Refresh one shared Claude Code credential from an independent process."""
+    os.environ["HERMES_HOME"] = profile_home
+
+    from agent import anthropic_credentials as anthropic_mod
+    from agent import credential_pool as credential_pool_mod
+    from hermes_cli import auth as auth_mod
+
+    shared_path = Path(shared_credentials_path)
+    server_path = Path(server_state_path)
+
+    def read_shared_credentials():
+        data = json.loads(shared_path.read_text(encoding="utf-8"))
+        oauth = data["claudeAiOauth"]
+        return {
+            "accessToken": oauth["accessToken"],
+            "refreshToken": oauth.get("refreshToken", ""),
+            "expiresAt": oauth.get("expiresAt", 0),
+            "source": "claude_code_credentials_file",
+        }
+
+    def write_shared_credentials(access_token, refresh_token, expires_at_ms, **_kwargs):
+        data = json.loads(shared_path.read_text(encoding="utf-8"))
+        data["claudeAiOauth"] = {
+            "accessToken": access_token,
+            "refreshToken": refresh_token,
+            "expiresAt": expires_at_ms,
+        }
+        shared_path.write_text(json.dumps(data), encoding="utf-8")
+
+    def fake_refresh(refresh_token, *, use_json=False):
+        # The state file models a single-use token endpoint. The lock here
+        # protects only the fake server's accounting; the production lock is
+        # what must ensure that the second Hermes process never calls this
+        # function after the first one has rotated the shared credential.
+        with auth_mod._auth_store_lock(timeout_seconds=10, target_path=server_path):
+            state = json.loads(server_path.read_text(encoding="utf-8"))
+            state["calls"].append(refresh_token)
+            if refresh_token in state["spent"]:
+                server_path.write_text(json.dumps(state), encoding="utf-8")
+                raise ValueError("invalid_grant: refresh token already used")
+            state["spent"].append(refresh_token)
+            state["rotation"] += 1
+            rotation = state["rotation"]
+            server_path.write_text(json.dumps(state), encoding="utf-8")
+        # Keep the simulated network operation inside the production shared
+        # lock long enough for the second profile to prove it waits, then
+        # re-reads the newly-written shared credentials file.
+        time.sleep(0.1)
+        return {
+            "access_token": f"process-access-{rotation}",
+            "refresh_token": f"process-refresh-{rotation}",
+            "expires_at_ms": int(time.time() * 1000) + 3_600_000,
+        }
+
+    # Keep this worker hermetic: each profile has its own auth store, while
+    # both workers deliberately point at the same Claude credential source.
+    auth_mod._global_auth_file_path = lambda: None
+    anthropic_mod.claude_code_credentials_path = lambda: shared_path
+    anthropic_mod.read_claude_code_credentials = read_shared_credentials
+    anthropic_mod._write_claude_code_credentials = write_shared_credentials
+    anthropic_mod.refresh_anthropic_oauth_pure = fake_refresh
+
+    result_queue.put({"kind": "ready", "pid": os.getpid()})
+    if not start_event.wait(timeout=10):
+        result_queue.put({"kind": "result", "ok": False, "error": "start barrier timeout"})
+        return
+
+    entry = _entry(id="pool-entry", refresh_token="stale-rt", source="claude_code")
+    pool = credential_pool_mod.CredentialPool("anthropic", [entry])
+    try:
+        refreshed = pool._refresh_entry(pool.entries()[0], force=True)
+        result_queue.put({
+            "kind": "result",
+            "ok": refreshed is not None,
+            "refresh_token": refreshed.refresh_token if refreshed else None,
+            "pool_refresh_token": pool.entries()[0].refresh_token,
+        })
+    except BaseException as exc:  # pragma: no cover - failure diagnostics
+        result_queue.put({"kind": "result", "ok": False, "error": repr(exc)})
+
+
+def _entry(*, id: str, refresh_token: str, source: str) -> PooledCredential:
+    return PooledCredential(
+        provider="anthropic",
+        id=id,
+        label="anthropic oauth",
+        auth_type=AUTH_TYPE_OAUTH,
+        priority=0,
+        source=source,
+        access_token="stale-at",
+        refresh_token=refresh_token,
+        expires_at_ms=0,
+    )
+
+
+class _SingleUseTokenServer:
+    """Same single-use-refresh-token contract as the race test, tuned for
+    a wider fan-out (more callers, less per-call delay so the suite stays
+    fast while still exercising real contention).
+    """
+
+    def __init__(self, delay_seconds: float = 0.02) -> None:
+        self._lock = threading.Lock()
+        self._spent: set[str] = set()
+        self._rotation = 0
+        self.calls: list[str] = []
+        self.delay_seconds = delay_seconds
+
+    def refresh(self, refresh_token: str, *, use_json: bool = False):
+        with self._lock:
+            self.calls.append(refresh_token)
+        time.sleep(self.delay_seconds)
+        with self._lock:
+            if refresh_token in self._spent:
+                raise ValueError("invalid_grant: refresh token already used")
+            self._spent.add(refresh_token)
+            self._rotation += 1
+            rotation = self._rotation
+        return {
+            "access_token": f"sk-ant-oat-rotated-{rotation}",
+            "refresh_token": f"sk-ant-ort-rotated-{rotation}",
+            "expires_at_ms": int(time.time() * 1000) + 3_600_000,
+        }
+
+
+@pytest.fixture
+def hermes_home(tmp_path, monkeypatch):
+    """Real, throwaway HERMES_HOME so _auth_store_lock and
+    write_credential_pool/read_credential_pool exercise the genuine
+    file-lock + on-disk persistence path, not a mock.
+    """
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    return tmp_path
+
+
+def test_high_concurrency_anthropic_refresh_no_lost_updates_no_deadlock(
+    hermes_home, monkeypatch
+):
+    """CONCURRENCY 'Hermes processes' race the same stale refresh token
+    against the real cross-process lock + real on-disk pool persistence.
+
+    Bottleneck check: total wall-clock time must stay close to what a
+    correctly-serialized (or adopt-without-refreshing) implementation would
+    take, not blow up toward CONCURRENCY * network_delay -- and every
+    participant must end up with a usable, non-exhausted credential.
+    """
+    server = _SingleUseTokenServer(delay_seconds=0.02)
+    monkeypatch.setattr(
+        "agent.anthropic_credentials.refresh_anthropic_oauth_pure",
+        lambda refresh_token, use_json=False: server.refresh(refresh_token, use_json=use_json),
+    )
+    monkeypatch.setattr(
+        "agent.anthropic_credentials.read_claude_code_credentials", lambda: None
+    )
+
+    shared_stale_entry = _entry(
+        id="pool-entry", refresh_token="stale-rt", source="manual:hermes_pkce"
+    )
+    pools = [
+        CredentialPool("anthropic", [dc_replace(shared_stale_entry)])
+        for _ in range(CONCURRENCY)
+    ]
+
+    results: dict[int, object] = {}
+    errors: dict[int, BaseException] = {}
+
+    def _run(idx: int) -> None:
+        try:
+            entry = pools[idx].entries()[0]
+            results[idx] = pools[idx]._refresh_entry(entry, force=True)
+        except BaseException as exc:  # pragma: no cover - failure diagnostics
+            errors[idx] = exc
+
+    threads = [threading.Thread(target=_run, args=(i,)) for i in range(CONCURRENCY)]
+    start = time.monotonic()
+    for t in threads:
+        t.start()
+    # Generous per-thread join budget: a correct implementation serializes
+    # through one file lock, so worst case is roughly
+    # CONCURRENCY * (delay + lock overhead), well under this ceiling. A
+    # deadlock or livelock would blow straight through it.
+    deadline = start + max(10.0, CONCURRENCY * server.delay_seconds * 5)
+    for t in threads:
+        remaining = max(0.1, deadline - time.monotonic())
+        t.join(timeout=remaining)
+    elapsed = time.monotonic() - start
+
+    still_alive = [t for t in threads if t.is_alive()]
+    assert not still_alive, (
+        f"{len(still_alive)}/{CONCURRENCY} threads never finished -- "
+        "possible deadlock in the cross-process refresh lock."
+    )
+    assert not errors, f"unexpected exceptions during concurrent refresh: {errors!r}"
+
+    assert len(results) == CONCURRENCY
+    assert all(r is not None for r in results.values()), (
+        "at least one of the concurrent processes could not recover a "
+        "usable Anthropic credential after the refresh race"
+    )
+    for idx, pool in enumerate(pools):
+        entry_after = pool.entries()[0]
+        assert entry_after.last_status != STATUS_EXHAUSTED, (
+            f"process {idx} ended up with an exhausted Anthropic credential "
+            "despite valid tokens existing on disk"
+        )
+
+    # Bottleneck signal: this must stay well below "every thread pays the
+    # full network delay independently" (CONCURRENCY * delay). If the fix
+    # regresses into N sequential POSTs instead of lock+adopt, this is
+    # where it would show up first.
+    naive_serial_upper_bound = CONCURRENCY * server.delay_seconds * 3
+    assert elapsed < naive_serial_upper_bound, (
+        f"refresh race took {elapsed:.2f}s for {CONCURRENCY} concurrent "
+        f"processes -- expected well under {naive_serial_upper_bound:.2f}s "
+        "if the lock + pool-store adoption path is working efficiently"
+    )
+
+
+@pytest.mark.live_system_guard_bypass
+@pytest.mark.windows_only
+def test_distinct_profiles_share_one_claude_refresh_without_duplicate_post(
+    hermes_home,
+):
+    """Independent profiles must serialize a shared Claude Code refresh.
+
+    The profile auth locks intentionally have different paths here; only the
+    dedicated lock keyed to the shared Claude credentials file can prevent the
+    second process from POSTing the already-spent refresh token.
+    """
+    shared_credentials_path = hermes_home / "shared-claude-credentials.json"
+    shared_credentials_path.write_text(
+        json.dumps({
+            "claudeAiOauth": {
+                "accessToken": "stale-at",
+                "refreshToken": "stale-rt",
+                "expiresAt": 0,
+            }
+        }),
+        encoding="utf-8",
+    )
+    server_state_path = hermes_home / "fake-token-server.json"
+    server_state_path.write_text(
+        json.dumps({"calls": [], "spent": [], "rotation": 0}),
+        encoding="utf-8",
+    )
+
+    profile_homes = [hermes_home / "profile-a", hermes_home / "profile-b"]
+    for profile_home in profile_homes:
+        profile_home.mkdir(parents=True)
+        (profile_home / "auth.json").write_text(
+            json.dumps({
+                "version": 1,
+                "providers": {},
+                # claude_code is a borrowed source; its raw tokens must not
+                # be persisted in a profile pool. Each worker constructs the
+                # runtime entry from the shared credential source below.
+                "credential_pool": {},
+            }),
+            encoding="utf-8",
+        )
+
+    ctx = mp.get_context("spawn")
+    start_event = ctx.Event()
+    result_queue = ctx.Queue()
+    processes = [
+        ctx.Process(
+            target=_process_claude_code_refresh_worker,
+            args=(
+                str(profile_home),
+                str(shared_credentials_path),
+                str(server_state_path),
+                start_event,
+                result_queue,
+            ),
+        )
+        for profile_home in profile_homes
+    ]
+
+    messages = []
+    try:
+        for process in processes:
+            process.start()
+
+        ready_deadline = time.monotonic() + 20.0
+        while len([m for m in messages if m.get("kind") == "ready"]) < len(processes):
+            remaining = max(0.1, ready_deadline - time.monotonic())
+            if remaining <= 0.1:
+                break
+            try:
+                messages.append(result_queue.get(timeout=remaining))
+            except queue.Empty:
+                break
+        assert len([m for m in messages if m.get("kind") == "ready"]) == len(processes), (
+            f"not all refresh workers reached the start barrier: {messages!r}"
+        )
+        start_event.set()
+
+        for process in processes:
+            process.join(timeout=30)
+        assert not [process for process in processes if process.is_alive()], (
+            "a profile refresh worker did not finish; possible shared-lock deadlock"
+        )
+
+        result_deadline = time.monotonic() + 5.0
+        results = [m for m in messages if m.get("kind") == "result"]
+        while len(results) < len(processes) and time.monotonic() < result_deadline:
+            try:
+                message = result_queue.get(timeout=0.5)
+            except queue.Empty:
+                break
+            messages.append(message)
+            if message.get("kind") == "result":
+                results.append(message)
+    finally:
+        start_event.set()
+        for process in processes:
+            process.join(timeout=2)
+        for process in processes:
+            if process.is_alive():
+                process.kill()
+                process.join(timeout=5)
+        result_queue.close()
+        result_queue.join_thread()
+
+    assert len(results) == len(processes), f"missing process results: {messages!r}"
+    assert all(result.get("ok") for result in results), results
+    assert {result.get("refresh_token") for result in results} == {"process-refresh-1"}
+    assert all((profile_home / "auth.lock").exists() for profile_home in profile_homes)
+    assert shared_credentials_path.with_suffix(".lock").exists()
+
+    server_state = json.loads(server_state_path.read_text(encoding="utf-8"))
+    assert server_state["calls"] == ["stale-rt"], (
+        "the shared stale refresh token must be POSTed exactly once across "
+        f"distinct profiles, got {server_state['calls']!r}"
+    )
+    assert server_state["spent"] == ["stale-rt"]
+
+    shared_credentials = json.loads(shared_credentials_path.read_text(encoding="utf-8"))
+    assert shared_credentials["claudeAiOauth"]["refreshToken"] == "process-refresh-1"
+    for profile_home in profile_homes:
+        profile_text = (profile_home / "auth.json").read_text(encoding="utf-8")
+        assert "stale-rt" not in profile_text
+        assert "process-refresh-1" not in profile_text

tests/agent/test_anthropic_output_field_leak.py

@@ -0,0 +1,76 @@
+"""Regression: output-only SDK fields must not leak into Anthropic request input.
+
+Reproduces HTTP 400 `messages.N.content.M.text.parsed_output: Extra inputs are
+not permitted`. Anthropic SDK response blocks carry output-only attributes
+(text blocks: `parsed_output`, `citations=None`; tool_use blocks: `caller`)
+that the Messages *input* schema forbids. normalize_response captured blocks
+verbatim via _to_plain_data and replayed them as input → 400.
+
+Fix: whitelist input-permitted fields per block type at three points —
+normalize_response capture, _sanitize_replay_block (ordered-blocks replay), and
+_convert_content_part_to_anthropic (content-list replay).
+"""
+import pytest
+from agent.anthropic_message_convert import _sanitize_replay_block, _convert_content_part_to_anthropic, _convert_assistant_message
+
+FORBIDDEN = {"parsed_output", "caller"}
+
+
+def _assert_clean(block):
+    """No forbidden output-only key, and no null citations, anywhere."""
+    assert isinstance(block, dict)
+    for k in FORBIDDEN:
+        assert k not in block, f"forbidden field {k!r} survived: {block}"
+    if "citations" in block:
+        assert isinstance(block["citations"], list) and block["citations"], \
+            "citations must be a non-empty list if present (None/[] is input-invalid)"
+
+
+class TestSanitizeReplayBlock:
+
+    def test_tool_use_strips_caller(self):
+        poisoned = {"type": "tool_use", "id": "toolu_1", "name": "read_file",
+                    "input": {"path": "a"}, "caller": {"type": "agent"}}
+        out = _sanitize_replay_block(poisoned)
+        _assert_clean(out)
+        assert out["name"] == "read_file" and out["input"] == {"path": "a"}
+
+
+
+    def test_unknown_type_dropped(self):
+        assert _sanitize_replay_block({"type": "server_tool_use", "foo": 1}) is None
+
+
+class TestContentPartConversion:
+    def test_stored_text_block_with_parsed_output_cleaned(self):
+        # The exact content.N.text.parsed_output failure shape.
+        part = {"type": "text", "text": "hello", "parsed_output": None, "citations": None}
+        out = _convert_content_part_to_anthropic(part)
+        _assert_clean(out)
+
+
+class TestAssistantReplay:
+    def test_interleaved_blocks_replayed_clean_and_ordered(self):
+        m = {
+            "role": "assistant",
+            "anthropic_content_blocks": [
+                {"type": "thinking", "thinking": "plan", "signature": "s1"},
+                {"type": "text", "text": "doing it", "parsed_output": None, "citations": None},
+                {"type": "tool_use", "id": "toolu_1", "name": "read_file",
+                 "input": {"path": "a"}, "caller": {"type": "agent"}},
+            ],
+        }
+        out = _convert_assistant_message(m)
+        blocks = out["content"]
+        # order preserved
+        assert [b["type"] for b in blocks] == ["thinking", "text", "tool_use"]
+        # every block clean
+        for b in blocks:
+            _assert_clean(b)
+        # signature + tool fields intact
+        assert blocks[0]["signature"] == "s1"
+        assert blocks[2]["name"] == "read_file"
+
+
+if __name__ == "__main__":
+    raise SystemExit(pytest.main([__file__, "-v"]))

tests/agent/test_anthropic_truncation_continuation.py

@@ -0,0 +1,97 @@
+"""Regression test for anthropic_messages truncation continuation.
+
+When an Anthropic response hits ``stop_reason: max_tokens`` (mapped to
+``finish_reason == 'length'`` in run_agent), the agent must retry with
+a continuation prompt — the same behavior it has always had for
+chat_completions and bedrock_converse.  Before this PR, the
+``if self.api_mode in ('chat_completions', 'bedrock_converse'):`` guard
+silently dropped Anthropic-wire truncations on the floor, returning a
+half-finished response with no retry.
+
+We don't exercise the full agent loop here (it's 3000 lines of inference,
+streaming, plugin hooks, etc.) — instead we verify the normalization
+adapter produces exactly the shape the continuation block now consumes.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+
+def _make_anthropic_text_block(text: str) -> SimpleNamespace:
+    return SimpleNamespace(type="text", text=text)
+
+
+def _make_anthropic_tool_use_block(name: str = "my_tool") -> SimpleNamespace:
+    return SimpleNamespace(
+        type="tool_use",
+        id="toolu_01",
+        name=name,
+        input={"foo": "bar"},
+    )
+
+
+def _make_anthropic_response(blocks, stop_reason: str = "max_tokens"):
+    return SimpleNamespace(
+        id="msg_01",
+        type="message",
+        role="assistant",
+        model="claude-sonnet-4-6",
+        content=blocks,
+        stop_reason=stop_reason,
+        stop_sequence=None,
+        usage=SimpleNamespace(input_tokens=100, output_tokens=200),
+    )
+
+
+class TestTruncatedAnthropicResponseNormalization:
+    """AnthropicTransport.normalize_response() gives us the shape _build_assistant_message expects."""
+
+    def test_text_only_truncation_produces_text_content_no_tool_calls(self):
+        """Pure-text Anthropic truncation → continuation path should fire."""
+        from agent.transports import get_transport
+
+        response = _make_anthropic_response(
+            [_make_anthropic_text_block("partial response that was cut off")]
+        )
+        nr = get_transport("anthropic_messages").normalize_response(response)
+
+        # The continuation block checks these two attributes:
+        #   assistant_message.content  → appended to truncated_response_parts
+        #   assistant_message.tool_calls → guards the text-retry branch
+        assert nr.content is not None
+        assert "partial response" in nr.content
+        assert not nr.tool_calls, (
+            "Pure-text truncation must have no tool_calls so the text-continuation "
+            "branch (not the tool-retry branch) fires"
+        )
+        assert nr.finish_reason == "length", "max_tokens stop_reason must map to OpenAI-style 'length'"
+
+
+    def test_empty_content_does_not_crash(self):
+        """Empty response.content — defensive: treat as a truncation with no text."""
+        from agent.transports import get_transport
+
+        response = _make_anthropic_response([])
+        nr = get_transport("anthropic_messages").normalize_response(response)
+        # Depending on the adapter, content may be "" or None — both are
+        # acceptable; what matters is no exception.
+        assert nr is not None
+        assert not nr.tool_calls
+
+
+class TestContinuationLogicBranching:
+    """Symbolic check that the api_mode gate now includes anthropic_messages."""
+
+    @pytest.mark.parametrize("api_mode", ["chat_completions", "bedrock_converse", "anthropic_messages"])
+    def test_all_three_api_modes_hit_continuation_branch(self, api_mode):
+        # The guard in run_agent.py is:
+        #   if self.api_mode in ("chat_completions", "bedrock_converse", "anthropic_messages"):
+        assert api_mode in {"chat_completions", "bedrock_converse", "anthropic_messages"}
+
+    def test_codex_responses_still_excluded(self):
+        # codex_responses has its own truncation path (not continuation-based)
+        # and should NOT be routed through the shared block.
+        assert "codex_responses" not in {"chat_completions", "bedrock_converse", "anthropic_messages"}

tests/agent/test_api_content_row_addressed_backfill.py

@@ -0,0 +1,238 @@
+"""Row-addressed ``api_content`` backfill (NousResearch/hermes-agent#102194).
+
+The sidecar is stamped by the turn prologue and normally reaches the DB in the
+same INSERT as the clean content (the crash persist runs after the stamp). When
+another writer materialized the current turn's user row FIRST — in-place
+preflight compaction, or a close/early flush that raced the prologue — that
+insert never happens: the crash persist marker-skips the message and the row
+keeps ``api_content = NULL``, so the next turn replays clean content and the
+request prefix diverges exactly at that message.
+
+The prologue therefore backfills, but only when a row provably exists for THIS
+dict. ``_row_id`` is that proof and that address: both early writers stamp it on
+the live message (``_insert_message_rows`` directly, ``sync_flushed_message_markers``
+after the batch commit). A positional "newest active user row" update cannot be
+substituted for it — a repeated user turn ("ok", "y", "continue") makes the
+previous turn's row compare equal on content, and the backfill would overwrite
+that turn's sidecar with this turn's bytes.
+"""
+
+from __future__ import annotations
+
+import types
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent.session_persistence import SessionPersistenceMixin
+from agent.turn_context import _stamp_api_content_sidecar, compose_user_api_content
+from hermes_state import SessionDB
+from tests.agent.test_api_content_sidecar import _FakeAgent, _build
+
+
+class TestSetMessageApiContent:
+    """The store primitive: addressed by row id, guarded on the rest."""
+
+    def _open(self, tmp_path):
+        db = SessionDB(db_path=tmp_path / "state.db")
+        db.create_session("s1", source="cli")
+        return db
+
+    def test_older_identical_row_is_untouched(self, tmp_path):
+        """Two user turns with the same text — the repeated-"ok" shape.
+
+        Addressing the row makes the older turn's sidecar unreachable; the
+        positional helper cannot tell them apart (asserted on the same DB).
+        """
+        db = self._open(tmp_path)
+        try:
+            db.append_message("s1", "user", content="ok", api_content="ok\n\nTURN-1")
+            db.append_message("s1", "assistant", content="reply")
+            db.append_message("s1", "user", content="ok")
+            rows = db.get_messages("s1")
+            turn_1_id, turn_2_id = rows[0]["id"], rows[2]["id"]
+
+            assert db.set_message_api_content("s1", turn_2_id, "ok", "ok\n\nTURN-2") == 1
+            rows = {r["id"]: r for r in db.get_messages("s1")}
+            assert rows[turn_1_id]["api_content"] == "ok\n\nTURN-1"
+            assert rows[turn_2_id]["api_content"] == "ok\n\nTURN-2"
+
+        finally:
+            db.close()
+
+    def test_guards_refuse_wrong_session_or_mismatched_content_or_archived_row(self, tmp_path):
+        db = self._open(tmp_path)
+        try:
+            db.create_session("s2", source="cli")
+            db.append_message("s1", "user", content="hello")
+            row_id = db.get_messages("s1")[0]["id"]
+
+            assert db.set_message_api_content("s2", row_id, "hello", "x") == 0
+            assert db.set_message_api_content("s1", row_id, "other", "x") == 0
+            assert db.set_message_api_content("s1", row_id + 999, "hello", "x") == 0
+            assert db.get_messages("s1")[0]["api_content"] is None
+
+            # Archived by compaction: active = 0, so the row is off limits.
+            db.archive_and_compact("s1", [{"role": "user", "content": "hello"}])
+            assert db.set_message_api_content("s1", row_id, "hello", "x") == 0
+        finally:
+            db.close()
+
+class TestPrologueRowAddressedBackfill:
+    """The prologue gate: backfill iff a durable row exists for this dict."""
+
+    def test_no_row_id_and_no_compaction_writes_nothing(self):
+        """The normal path: the row does not exist yet and the crash persist
+        writes it WITH the sidecar. A backfill here has no row to address and
+        would have to guess — so it must not run at all."""
+        agent = _FakeAgent()
+        agent._session_db = MagicMock()
+        with patch(
+            "hermes_cli.plugins.invoke_hook",
+            return_value=[{"context": "PLUGIN-CTX"}],
+        ):
+            ctx = _build(agent)
+
+        assert (
+            ctx.messages[ctx.current_turn_user_idx]["api_content"]
+            == "hello\n\nPLUGIN-CTX"
+        )
+        agent._session_db.set_message_api_content.assert_not_called()
+        agent._session_db.set_latest_user_api_content.assert_not_called()
+
+class _RealPersistenceAgent(SessionPersistenceMixin, _FakeAgent):
+    """Stand-in agent with the real SessionPersistenceMixin flush implementation."""
+
+    def __init__(self, db=None, sid="s1"):
+        _FakeAgent.__init__(self)
+        self._session_db = db
+        self.session_id = sid
+        self._session_db_created = True
+        self._flushed_db_message_ids = set()
+        self._last_flushed_db_idx = 0
+
+
+class TestRealEarlyFlushAndOverrideLifecycle:
+    """End-to-end tests exercising real database flushes and API-only overrides."""
+
+    def test_real_close_flush_syncs_row_id_and_prologue_backfills(self, tmp_path):
+        """Proof that the real _flush_messages_to_session_db path syncs _row_id onto
+        the live dict (via sync_flushed_message_markers) and the prologue backfills it."""
+        path = tmp_path / "state.db"
+        db = SessionDB(db_path=path)
+        sid = "sess-real-flush"
+        db.create_session(sid, source="cli")
+        try:
+            agent = _RealPersistenceAgent(db, sid)
+
+            staged = {"role": "user", "content": "hello"}
+            agent._pending_cli_user_message = staged
+
+            # Simulate the early/close flush racing the prologue
+            flushed = agent._flush_messages_to_session_db([staged], None)
+            assert flushed is True
+            assert staged.get("_db_persisted") is True
+            assert isinstance(staged.get("_row_id"), int)
+            assert staged["_row_id"] == db.get_messages(sid)[-1]["id"]
+            # At this point, the row in SQLite has api_content = None
+            assert db.get_messages(sid)[-1]["api_content"] is None
+
+            # Now build_turn_context runs
+            with patch(
+                "hermes_cli.plugins.invoke_hook",
+                return_value=[{"context": "PLUGIN-CTX"}],
+            ):
+                ctx = _build(agent)
+
+            expected = compose_user_api_content("hello", "", "PLUGIN-CTX")
+            assert ctx.messages[ctx.current_turn_user_idx]["api_content"] == expected
+            # Backfilled to the exact row in SQLite!
+            assert db.get_messages(sid)[-1]["api_content"] == expected
+        finally:
+            db.close()
+
+    def test_pre_flushed_api_only_turn_without_injections_preserves_sidecar(self, tmp_path):
+        """[ehz0ah bug 1]: Pre-flushed clean input where the API turn has an API-only
+        variant (e.g. voice prefix) and NO memory/plugin injection is composed.
+        compose_user_api_content returns None, but the differing API-only bytes must
+        be preserved as api_content and backfilled onto the row."""
+        path = tmp_path / "state.db"
+        db = SessionDB(db_path=path)
+        sid = "sess-api-only-no-inj"
+        db.create_session(sid, source="cli")
+        try:
+            agent = _RealPersistenceAgent(db, sid)
+
+            clean_text = "hello"
+            api_text = "[voice] hello"
+
+            staged = {"role": "user", "content": clean_text}
+            agent._pending_cli_user_message = staged
+            agent._flush_messages_to_session_db([staged], None)
+            assert staged.get("_row_id") is not None
+
+            # Worker resumes with API-facing message and clean persist override
+            with patch("hermes_cli.plugins.invoke_hook", return_value=[]):
+                ctx = _build(
+                    agent,
+                    user_message=api_text,
+                    persist_user_message=clean_text,
+                )
+
+            # Live user message has the API text and api_content
+            turn_msg = ctx.messages[ctx.current_turn_user_idx]
+            assert turn_msg["content"] == api_text
+            assert turn_msg["api_content"] == api_text
+
+            # Database row has clean text as content, but api_text as api_content!
+            db_rows = db.get_messages(sid)
+            assert len(db_rows) == 1
+            assert db_rows[0]["content"] == clean_text
+            assert db_rows[0]["api_content"] == api_text
+
+            # Replay via get_messages_as_conversation preserves clean content
+            # alongside the api_content sidecar.
+            conv = db.get_messages_as_conversation(sid)
+            assert conv[0]["content"] == clean_text
+            assert conv[0]["api_content"] == api_text
+            from agent.turn_context import substitute_api_content
+            substitute_api_content(conv[0])
+            assert conv[0]["content"] == api_text
+        finally:
+            db.close()
+
+    def test_repeated_prompt_protected_against_positional_overwrite(self, tmp_path):
+        """Repeated prompts 'ok' across turns: Turn 1 has sidecar, Turn 2 is pre-flushed.
+        Row-addressed backfill on Turn 2 never mutates Turn 1's stored sidecar."""
+        path = tmp_path / "state.db"
+        db = SessionDB(db_path=path)
+        sid = "sess-repeated-ok"
+        db.create_session(sid, source="cli")
+        try:
+            # Turn 1
+            db.append_message(sid, "user", content="ok", api_content="ok\n\nTURN-1-CTX")
+            db.append_message(sid, "assistant", content="acknowledged")
+            t1_user_row = db.get_messages(sid)[0]
+
+            # Turn 2: staged and pre-flushed
+            staged_t2 = {"role": "user", "content": "ok"}
+            agent = _RealPersistenceAgent(db, sid)
+            agent._pending_cli_user_message = staged_t2
+
+            agent._flush_messages_to_session_db([staged_t2], None)
+            t2_user_row = db.get_messages(sid)[2]
+            assert t2_user_row["id"] != t1_user_row["id"]
+            assert t2_user_row["api_content"] is None
+
+            # Prologue backfills Turn 2
+            with patch(
+                "hermes_cli.plugins.invoke_hook",
+                return_value=[{"context": "TURN-2-CTX"}],
+            ):
+                _build(agent, user_message="ok")
+
+            rows = {r["id"]: r for r in db.get_messages(sid)}
+            assert rows[t1_user_row["id"]]["api_content"] == "ok\n\nTURN-1-CTX"
+            assert rows[t2_user_row["id"]]["api_content"] == "ok\n\nTURN-2-CTX"
+        finally:
+            db.close()

tests/agent/test_arcee_trinity_overrides.py

@@ -0,0 +1,189 @@
+"""Tests for Arcee Trinity Large Thinking per-model overrides.
+
+Arcee Trinity Large Thinking is a reasoning model that wants:
+- Fixed temperature=0.5 (vs the global default)
+- Compression threshold=0.75 (delay compression to preserve reasoning context)
+
+The helpers must match the bare model name, including when it arrives via
+OpenRouter as ``arcee-ai/trinity-large-thinking``, but must NOT hit sibling
+Arcee models like trinity-large-preview or trinity-mini.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from agent.agent_init import _resolve_compression_threshold
+from agent.auxiliary_client import (
+    _compression_threshold_for_model,
+    _fixed_temperature_for_model,
+    _is_arcee_trinity_thinking,
+    _is_codex_gpt54_or_gpt55,
+    _is_codex_spark,
+)
+
+
+@pytest.mark.parametrize(
+    "model",
+    [
+        "trinity-large-thinking",
+        "arcee-ai/trinity-large-thinking",
+        "Arcee-AI/Trinity-Large-Thinking",  # case-insensitive
+        "  trinity-large-thinking  ",  # whitespace tolerant
+    ],
+)
+def test_is_arcee_trinity_thinking_matches(model: str) -> None:
+    assert _is_arcee_trinity_thinking(model) is True
+
+
+
+
+def test_fixed_temperature_for_trinity_thinking() -> None:
+    assert _fixed_temperature_for_model("trinity-large-thinking") == 0.5
+    assert _fixed_temperature_for_model("arcee-ai/trinity-large-thinking") == 0.5
+
+
+
+
+
+
+def test_compression_threshold_default_none_for_other_models() -> None:
+    # None means "leave the user's config value unchanged".
+    assert _compression_threshold_for_model(None) is None
+    assert _compression_threshold_for_model("") is None
+    assert _compression_threshold_for_model("trinity-large-preview") is None
+    assert _compression_threshold_for_model("claude-sonnet-4.6") is None
+    assert _compression_threshold_for_model("kimi-k2") is None
+
+
+# ---------------------------------------------------------------------------
+# Codex gpt-5.4 / gpt-5.5 compaction-threshold autoraise
+#
+# ChatGPT's Codex OAuth backend caps both families at a 272K window (verified
+# live via the Codex /models resolver and per-slug fallback table). The default
+# 50% compaction trigger would fire at ~136K — half the usable window — so this
+# route raises the trigger to 85%. Only the Codex OAuth route is affected; the
+# same slugs on OpenAI direct / OpenRouter / Copilot expose a larger window and
+# keep the user's global threshold.
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+@pytest.mark.parametrize(
+    "model",
+    [
+        "gpt-5", "gpt-5.55", "gpt-5.50", "gpt-5.45", "gpt-5.40",
+        "gpt-daybreak-blue-latest-mini", "", None,
+    ],
+)
+def test_is_codex_gpt54_or_gpt55_rejects_non_54_55_models(model) -> None:
+    # Close numeric neighbours must NOT match — the prefix guards require a
+    # separator after "5.4" / "5.5" so e.g. gpt-5.45 and gpt-5.55 stay out.
+    assert _is_codex_gpt54_or_gpt55(model, "openai-codex") is False
+
+
+def test_compression_threshold_for_codex_gpt55() -> None:
+    assert _compression_threshold_for_model("gpt-5.4", "openai-codex") == 0.85
+    assert _compression_threshold_for_model("gpt-5.4-pro", "openai-codex") == 0.85
+    assert _compression_threshold_for_model("openai/gpt-5.4", "openai-codex") == 0.85
+    assert _compression_threshold_for_model("gpt-5.5", "openai-codex") == 0.85
+    assert _compression_threshold_for_model("gpt-5.5-pro", "openai-codex") == 0.85
+    assert _compression_threshold_for_model("openai/gpt-5.5", "openai-codex") == 0.85
+    assert _is_codex_gpt54_or_gpt55("gpt-daybreak-blue-latest", "openai-codex") is True
+    assert _compression_threshold_for_model("gpt-daybreak-blue-latest", "openai-codex") == 0.85
+
+
+@pytest.mark.parametrize(
+    "model",
+    [
+        "gpt-5.6-sol-900k",
+        "gpt-5.6-terra-900k",
+        "gpt-5.6-luna-900k",
+        "gpt-5.4-900k",
+        "gpt-daybreak-blue-latest-900k",
+        "openai/gpt-5.6-sol-900k",
+    ],
+)
+def test_900k_variants_keep_global_threshold(model) -> None:
+    """The 85% autoraise compensates for the small 272K window; ``-900k``
+    opt-in variants run at ~900K, so they keep the user's global
+    ``compression.threshold`` (default 50%) — no override returned."""
+    assert _is_codex_gpt54_or_gpt55(model, "openai-codex") is False
+    assert _compression_threshold_for_model(model, "openai-codex") is None
+
+
+def test_base_slugs_still_autoraised_alongside_900k_variants() -> None:
+    """Sanity pair: the base slug autoraises while its variant does not."""
+    assert _compression_threshold_for_model("gpt-5.6-sol", "openai-codex") == 0.85
+    assert _compression_threshold_for_model("gpt-5.6-sol-900k", "openai-codex") is None
+
+
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# Codex gpt-5.3-codex-spark compaction-threshold autoraise
+#
+# gpt-5.3-codex-spark is Codex-OAuth-only (ChatGPT Pro entitlement) with a
+# native 128K context window.  The default 50% compaction trigger would fire
+# at ~64K — wasting half the usable window, often before the session has
+# accumulated enough turns to summarize meaningfully.  This route raises the
+# trigger to 70% (~90K) to preserve more raw context while leaving ~38K
+# headroom before the 128K hard limit.
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+@pytest.mark.parametrize(
+    "model",
+    [
+        "gpt-5.5",  # different family
+        "gpt-5.3-codex",  # sibling, not spark
+        "gpt-5.3",  # bare 5.3, not spark
+        "gpt-5.3-codex-spark-mini",  # hypothetical variant — not matched yet
+        "", None,
+    ],
+)
+def test_is_codex_spark_rejects_non_spark_models(model) -> None:
+    assert _is_codex_spark(model, "openai-codex") is False
+
+
+
+
+
+
+
+
+# ── _resolve_compression_threshold (init_agent application logic) ────────────
+#
+# The Codex overrides are *autoraises*: they raise the trigger (0.85 for the
+# gpt-5.4/5.5 272K family, 0.70 for spark) but must never LOWER a higher
+# user-configured global threshold.
+
+
+
+
+
+
+
+
+
+
+def test_resolve_no_override_keeps_global() -> None:
+    # No per-model override (model_cthresh is None) → global threshold, no notice.
+    effective, notice = _resolve_compression_threshold(
+        0.50, None, is_codex_autoraise=False
+    )
+    assert effective == 0.50
+    assert notice is None
+
+

tests/agent/test_aux_affordable_402_retry.py

@@ -0,0 +1,197 @@
+"""Credit-limited 402 handling: clamp to the affordable budget and retry.
+
+Regression tests for the masoria stall (Aug 2026): compression fell back to
+OpenRouter, which defaulted the omitted output cap to the model's full 65,536
+window and rejected with ``402 ... can only afford 7117`` — three times in a
+row — on an account whose balance easily covered a summary.
+
+Two coordinated fixes:
+
+1. ``_build_call_kwargs`` preserves an explicit ``max_tokens`` for OpenRouter
+   routes (salvage of PR #41055 by @liuhao1024, issue #41035).
+2. ``_create_with_progress`` retries ONCE with the provider-stated affordable
+   budget when a 402 names one (pattern proven in closed PR #49785 for the
+   main loop; this is the auxiliary-path equivalent).
+"""
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from agent.auxiliary_client import (
+    _affordable_max_tokens_from_error,
+    _build_call_kwargs,
+    _create_with_progress,
+)
+
+
+class _Payment402(Exception):
+    status_code = 402
+
+
+_OPENROUTER_402 = (
+    "Error code: 402 - {'error': {'message': 'This request requires more "
+    "credits, or fewer max_tokens. You requested up to 65536 tokens, but can "
+    "only afford 7117. To increase, visit https://openrouter.ai/settings/"
+    "credits and add more credits', 'code': 402}}"
+)
+
+
+class TestAffordableExtraction:
+    def test_extracts_budget_minus_margin(self):
+        assert _affordable_max_tokens_from_error(_Payment402(_OPENROUTER_402)) == 7117 - 64
+
+    def test_plain_exhaustion_returns_none(self):
+        err = _Payment402("Error code: 402 - insufficient funds")
+        assert _affordable_max_tokens_from_error(err) is None
+
+    def test_tiny_budget_treated_as_exhaustion(self):
+        err = _Payment402("You requested up to 65536 tokens, but can only afford 100.")
+        assert _affordable_max_tokens_from_error(err) is None
+
+    def test_non_payment_error_returns_none(self):
+        assert _affordable_max_tokens_from_error(TimeoutError(
+            "Codex auxiliary Responses stream stalled: no new output for 60.0s"
+        )) is None
+
+    def test_comma_grouped_count(self):
+        err = _Payment402("can only afford 12,345 tokens")
+        assert _affordable_max_tokens_from_error(err) == 12345 - 64
+
+
+class _FlakyClient:
+    """402s with the affordable message until max_tokens fits the budget."""
+
+    def __init__(self, affordable=7117):
+        self.calls = []
+        self._affordable = affordable
+        self.chat = SimpleNamespace(
+            completions=SimpleNamespace(create=self._create)
+        )
+
+    def _create(self, **kwargs):
+        self.calls.append(kwargs)
+        cap = kwargs.get("max_tokens") or kwargs.get("max_completion_tokens")
+        if cap is None or cap > self._affordable:
+            raise _Payment402(_OPENROUTER_402)
+        return SimpleNamespace(
+            choices=[SimpleNamespace(
+                index=0,
+                message=SimpleNamespace(role="assistant", content="summary"),
+                finish_reason="stop",
+            )],
+            model=kwargs.get("model"), usage=None,
+        )
+
+
+class TestCreateWithProgressAffordableRetry:
+    def test_uncapped_402_retries_once_with_affordable_cap(self):
+        client = _FlakyClient()
+        response = _create_with_progress(
+            client,
+            {"model": "google/gemini-3.6-flash",
+             "messages": [{"role": "user", "content": "summarize"}]},
+            "compression",
+        )
+        assert response.choices[0].message.content == "summary"
+        assert len(client.calls) == 2
+        assert client.calls[1]["max_tokens"] == 7117 - 64
+
+    def test_already_affordable_cap_does_not_spin(self):
+        """A 402 on a request already within budget re-raises immediately."""
+        client = _FlakyClient(affordable=100)  # everything 402s
+        with pytest.raises(_Payment402):
+            _create_with_progress(
+                client,
+                {"model": "m", "max_tokens": 5000,
+                 "messages": [{"role": "user", "content": "x"}]},
+                "compression",
+            )
+        # 5000 > 7053 is false → within stated budget → single attempt.
+        assert len(client.calls) == 1
+
+    def test_plain_exhaustion_402_is_not_retried(self):
+        class _Broke:
+            def __init__(self):
+                self.calls = []
+                self.chat = SimpleNamespace(
+                    completions=SimpleNamespace(create=self._create)
+                )
+
+            def _create(self, **kwargs):
+                self.calls.append(kwargs)
+                raise _Payment402("Error code: 402 - insufficient funds")
+
+        client = _Broke()
+        with pytest.raises(_Payment402):
+            _create_with_progress(
+                client,
+                {"model": "m", "messages": [{"role": "user", "content": "x"}]},
+                "compression",
+            )
+        assert len(client.calls) == 1
+
+    def test_retry_402_surfaces_without_spinning(self):
+        """If the clamped retry 402s again, it propagates (single retry)."""
+
+        class _Always402:
+            def __init__(self):
+                self.calls = []
+                self.chat = SimpleNamespace(
+                    completions=SimpleNamespace(create=self._create)
+                )
+
+            def _create(self, **kwargs):
+                self.calls.append(kwargs)
+                raise _Payment402(_OPENROUTER_402)
+
+        client = _Always402()
+        with pytest.raises(_Payment402):
+            _create_with_progress(
+                client,
+                {"model": "m", "messages": [{"role": "user", "content": "x"}]},
+                "compression",
+            )
+        assert len(client.calls) == 2
+
+
+class TestOpenRouterMaxTokensPreserved:
+    """Salvage of PR #41055 (@liuhao1024): OpenRouter keeps an explicit cap."""
+
+    def test_openrouter_provider_includes_max_tokens(self):
+        kwargs = _build_call_kwargs(
+            provider="openrouter",
+            model="openai/gpt-4o-mini",
+            messages=[{"role": "user", "content": "test"}],
+            max_tokens=2000,
+        )
+        assert kwargs.get("max_tokens") == 2000 or kwargs.get("max_completion_tokens") == 2000
+
+    def test_openrouter_base_url_includes_max_tokens(self):
+        kwargs = _build_call_kwargs(
+            provider="openai",
+            model="google/gemini-3.6-flash",
+            messages=[{"role": "user", "content": "test"}],
+            max_tokens=2000,
+            base_url="https://openrouter.ai/api/v1",
+        )
+        assert kwargs.get("max_tokens") == 2000 or kwargs.get("max_completion_tokens") == 2000
+
+    def test_generic_provider_still_omits_max_tokens(self):
+        kwargs = _build_call_kwargs(
+            provider="openai",
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "test"}],
+            max_tokens=2000,
+        )
+        assert "max_tokens" not in kwargs and "max_completion_tokens" not in kwargs
+
+    def test_none_max_tokens_never_included_for_openrouter(self):
+        kwargs = _build_call_kwargs(
+            provider="openrouter",
+            model="test-model",
+            messages=[{"role": "user", "content": "test"}],
+            max_tokens=None,
+        )
+        assert "max_tokens" not in kwargs and "max_completion_tokens" not in kwargs

tests/agent/test_auxiliary_anthropic_pool_fallback_regression.py

@@ -0,0 +1,85 @@
+"""Regression: _try_anthropic() must fall back to the legacy token resolver
+when the credential pool is present but has no usable entry.
+
+Root cause (observed 2026-07-05): the pooled Anthropic OAuth entry expired and
+its refresh_token was stale, so `_select_pool_entry("anthropic")` returned
+`(True, None)` — pool exists, no selectable entry. The old `_try_anthropic`
+hard-failed on that branch (`return None, None`), even though a perfectly
+valid `ANTHROPIC_TOKEN` / credentials-file token was available. This wedged
+every auxiliary task routed to Anthropic (goal judge → "no auxiliary client
+configured"), while the MAIN session stayed healthy because it resolves the
+env token directly.
+
+openrouter (test_try_openrouter_pool_exhausted_falls_back_to_env) and codex
+(TestBuildCodexClient.test_pool_without_selected_entry_falls_back_to_auth_store)
+already fall through to their standalone credential on `(True, None)`. This
+test pins the same invariant for anthropic so the three paths stay symmetric:
+a temporarily dead pool entry must never hard-fail when a valid standalone
+credential exists.
+"""
+
+from unittest.mock import MagicMock, patch
+
+
+class TestAnthropicPoolExhaustedFallsBackToEnv:
+    def test_pool_present_no_entry_falls_back_to_resolve_token(self, monkeypatch):
+        """pool=(True, None) but a valid env token exists → client is built."""
+        monkeypatch.setenv("ANTHROPIC_TOKEN", "«redacted:sk-…»-oauth-token")
+        with patch(
+            "agent.auxiliary_client._select_pool_entry", return_value=(True, None)
+        ), patch(
+            "agent.anthropic_adapter.build_anthropic_client"
+        ) as mock_build:
+            mock_build.return_value = MagicMock()
+            from agent.auxiliary_client import _try_anthropic, AnthropicAuxiliaryClient
+
+            client, model = _try_anthropic()
+
+        assert client is not None, (
+            "_try_anthropic must fall back to resolve_anthropic_token() when the "
+            "pool is present but has no usable entry (parity with openrouter/codex)"
+        )
+        assert isinstance(client, AnthropicAuxiliaryClient)
+        # Default aux model when none configured.
+        assert model == "claude-haiku-4-5-20251001"
+        # Must have used the env/legacy token, not a pooled entry.
+        assert mock_build.call_args.args[0] == "«redacted:sk-…»-oauth-token"
+
+    def test_pool_present_no_entry_and_no_token_still_returns_none(self, monkeypatch):
+        """No pooled entry AND no resolvable token → clean (None, None), no crash."""
+        monkeypatch.delenv("ANTHROPIC_TOKEN", raising=False)
+        monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+        monkeypatch.delenv("CLAUDE_CODE_OAUTH_TOKEN", raising=False)
+        with patch(
+            "agent.auxiliary_client._select_pool_entry", return_value=(True, None)
+        ), patch(
+            "agent.anthropic_credentials.resolve_anthropic_token", return_value=None
+        ):
+            from agent.auxiliary_client import _try_anthropic
+
+            client, model = _try_anthropic()
+
+        assert client is None
+        assert model is None
+
+    def test_base_url_defaults_when_pool_present_but_no_entry(self, monkeypatch):
+        """Falling through with pool_present=True must not crash on base_url
+        resolution (previously guarded by `if pool_present`)."""
+        monkeypatch.setenv("ANTHROPIC_TOKEN", "«redacted:sk-…»-oauth-token")
+        captured = {}
+
+        def _fake_build(token, base_url):
+            captured["base_url"] = base_url
+            return MagicMock()
+
+        with patch(
+            "agent.auxiliary_client._select_pool_entry", return_value=(True, None)
+        ), patch(
+            "agent.anthropic_adapter.build_anthropic_client", side_effect=_fake_build
+        ):
+            from agent.auxiliary_client import _try_anthropic
+
+            client, _model = _try_anthropic()
+
+        assert client is not None
+        assert captured["base_url"] == "https://api.anthropic.com"

tests/agent/test_auxiliary_client_azure_foundry.py

@@ -0,0 +1,325 @@
+"""Tests for auxiliary client routing of the ``azure-foundry`` provider.
+
+Covers the dedicated branch in ``agent.auxiliary_client.resolve_provider_client``
+that delegates to :func:`hermes_cli.runtime_provider._resolve_azure_foundry_runtime`
+instead of falling into the generic ``resolve_api_key_provider_credentials``
+path (which only knows about ``AZURE_FOUNDRY_API_KEY`` and would 401 for
+Entra ID users and miss ``model.base_url`` overrides for api-key users
+with non-standard Foundry-projects endpoints).
+
+Pinned scenarios:
+
+  * ``auth_mode: api_key`` → plain OpenAI client with the static string
+    key for ``chat_completions``.
+  * ``auth_mode: entra_id`` + ``chat_completions`` → plain OpenAI
+    client with a callable ``api_key`` (the bearer-token provider) —
+    confirms the callable survives the auxiliary path end-to-end.
+  * ``auth_mode: entra_id`` + GPT-5.x model → CodexAuxiliaryClient
+    wrapping the OpenAI client (api_mode auto-upgrades to
+    codex_responses).
+  * Anthropic-style + entra_id → rejected at the runtime resolver,
+    so the aux path returns ``(None, None)``.
+  * Failure path when no model is configured returns ``(None, None)``
+    cleanly so the auto chain falls through.
+"""
+
+from __future__ import annotations
+
+import sys
+from types import SimpleNamespace
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _reset_credential_cache():
+    from agent.azure_identity_adapter import reset_credential_cache
+    reset_credential_cache()
+    yield
+    reset_credential_cache()
+
+
+@pytest.fixture
+def fake_azure_identity(monkeypatch):
+    """Stand-in for azure.identity (keeps CI hermetic when the SDK is
+    not installed)."""
+    from agent import azure_identity_adapter as _adapter
+
+    last = {"scope": None}
+
+    def _provider(scope):
+        return lambda: f"jwt-for-{scope}"
+
+    fake_module = SimpleNamespace(
+        DefaultAzureCredential=lambda **kw: SimpleNamespace(
+            kwargs=kw,
+            get_token=lambda scope: SimpleNamespace(token="fake", expires_on=9999999999),
+        ),
+        get_bearer_token_provider=lambda credential, scope: (
+            last.__setitem__("scope", scope),
+            _provider(scope),
+        )[-1],
+    )
+    monkeypatch.setattr(_adapter, "_require_azure_identity", lambda: fake_module)
+    monkeypatch.setitem(sys.modules, "azure.identity", fake_module)
+    return last
+
+
+@pytest.fixture
+def patch_load_config(monkeypatch):
+    """Helper to set model_cfg seen by _try_azure_foundry."""
+    def _apply(model_cfg):
+        monkeypatch.setattr(
+            "hermes_cli.config.load_config",
+            lambda: {"model": model_cfg},
+        )
+        monkeypatch.setattr(
+            "hermes_cli.config.load_config_readonly",
+            lambda: {"model": model_cfg},
+        )
+    return _apply
+
+
+# ---------------------------------------------------------------------------
+# auth_mode: api_key (default) — regression for the legacy path
+# ---------------------------------------------------------------------------
+
+
+class TestAuxAzureFoundryApiKey:
+    def test_chat_completions_returns_plain_openai_client(self, monkeypatch, patch_load_config):
+        from agent.auxiliary_client import _try_azure_foundry
+        from openai import OpenAI as _OpenAI
+
+        monkeypatch.setenv("AZURE_FOUNDRY_API_KEY", "sk-azure-static-key")
+        patch_load_config({
+            "provider": "azure-foundry",
+            "base_url": "https://r.openai.azure.com/openai/v1",
+            "api_mode": "chat_completions",
+            "default": "gpt-4o",
+        })
+        client, resolved = _try_azure_foundry(model="gpt-4o")
+        assert client is not None
+        assert resolved == "gpt-4o"
+        assert isinstance(client, _OpenAI)
+        assert client.api_key == "sk-azure-static-key"
+
+
+    def test_no_key_returns_none(self, monkeypatch, patch_load_config):
+        from agent.auxiliary_client import _try_azure_foundry
+
+        monkeypatch.delenv("AZURE_FOUNDRY_API_KEY", raising=False)
+        patch_load_config({
+            "provider": "azure-foundry",
+            "base_url": "https://r.openai.azure.com/openai/v1",
+            "api_mode": "chat_completions",
+            "default": "gpt-4o",
+        })
+        client, resolved = _try_azure_foundry(model="gpt-4o")
+        assert client is None
+        assert resolved is None
+
+
+
+# ---------------------------------------------------------------------------
+# auth_mode: entra_id — callable api_key survives end-to-end
+# ---------------------------------------------------------------------------
+
+
+class TestAuxAzureFoundryEntra:
+    def test_callable_api_key_reaches_openai_constructor(
+        self, monkeypatch, fake_azure_identity, patch_load_config,
+    ):
+        """The token provider callable must arrive at ``OpenAI(api_key=...)``
+        intact — never stringified to ``"no-key-required"`` or to the
+        SDK-internal empty-string representation BEFORE we hand it off.
+
+        We assert on the public SDK contract (constructor receives the
+        callable) rather than ``client.api_key``, because OpenAI 2.24.0
+        stores callable api_keys in a private attribute and exposes
+        ``client.api_key`` as ``""``. The SDK still calls the callable
+        per request to mint ``Authorization: Bearer <token>``; that
+        behaviour is the documented Microsoft/OpenAI contract we rely on.
+        """
+        from agent import auxiliary_client as _aux
+
+        received = {}
+
+        class _FakeOpenAI:
+            def __init__(self, **kwargs):
+                received.update(kwargs)
+                # Mirror the fields downstream callers read.
+                self.api_key = kwargs.get("api_key", "")
+                self.base_url = kwargs.get("base_url", "")
+
+        monkeypatch.setattr(_aux, "OpenAI", _FakeOpenAI)
+        patch_load_config({
+            "provider": "azure-foundry",
+            "base_url": "https://r.openai.azure.com/openai/v1",
+            "api_mode": "chat_completions",
+            "auth_mode": "entra_id",
+            "default": "gpt-4o",
+        })
+        client, resolved = _aux._try_azure_foundry(model="gpt-4o")
+        assert client is not None
+        assert resolved == "gpt-4o"
+        # Public-contract assertion: the OpenAI SDK constructor saw the
+        # callable, exactly as Microsoft's Foundry sample requires.
+        assert callable(received["api_key"])
+        assert not isinstance(received["api_key"], str)
+        assert received["api_key"]().startswith("jwt-for-")
+        # Base URL forwarded verbatim (no /responses suffix stripping
+        # in this path — that's a separate concern handled by the
+        # runtime resolver only when the user re-saves config).
+        assert received["base_url"] == "https://r.openai.azure.com/openai/v1"
+
+    def test_codex_responses_with_entra_wraps_correctly(
+        self, monkeypatch, fake_azure_identity, patch_load_config,
+    ):
+        """GPT-5.x deployment on Entra ID — auto-upgraded to
+        codex_responses, wrapped in CodexAuxiliaryClient, callable
+        api_key handed to the underlying OpenAI SDK."""
+        from agent import auxiliary_client as _aux
+
+        received = {}
+
+        class _FakeOpenAI:
+            def __init__(self, **kwargs):
+                received.update(kwargs)
+                self.api_key = kwargs.get("api_key", "")
+                self.base_url = kwargs.get("base_url", "")
+
+        monkeypatch.setattr(_aux, "OpenAI", _FakeOpenAI)
+        patch_load_config({
+            "provider": "azure-foundry",
+            "base_url": "https://r.openai.azure.com/openai/v1",
+            "api_mode": "chat_completions",
+            "auth_mode": "entra_id",
+            "default": "gpt-5.4-mini",
+        })
+        client, resolved = _aux._try_azure_foundry(model="gpt-5.4-mini")
+        assert resolved == "gpt-5.4-mini"
+        assert isinstance(client, _aux.CodexAuxiliaryClient)
+        # The Codex wrapper received an OpenAI client built with the
+        # callable api_key — verify against the SDK constructor record,
+        # not the wrapper attribute (which mirrors the SDK's empty-
+        # string representation).
+        assert callable(received["api_key"])
+        assert received["api_key"]().startswith("jwt-for-")
+
+    def test_entra_anthropic_messages_uses_bearer_hook(
+        self, monkeypatch, fake_azure_identity, patch_load_config,
+    ):
+        """Entra ID + anthropic_messages: runtime returns a callable
+        api_key; ``_maybe_wrap_anthropic`` → ``build_anthropic_client``
+        detects the callable and installs the bearer-injecting httpx
+        event hook on a custom ``httpx.Client`` passed to the
+        Anthropic SDK via ``http_client=``."""
+        from agent import auxiliary_client as _aux
+        from agent import anthropic_adapter as _anthropic
+
+        received = {}
+
+        class _FakeOpenAI:
+            def __init__(self, **kwargs):
+                received["openai"] = kwargs
+                self.api_key = kwargs.get("api_key", "")
+                self.base_url = kwargs.get("base_url", "")
+
+        class _FakeAnthropicSDK:
+            Omit = object  # the adapter omits the unused credential header via sdk.Omit()
+
+            class Anthropic:
+                def __init__(self, **kwargs):
+                    received["anthropic"] = kwargs
+
+        monkeypatch.setattr(_aux, "OpenAI", _FakeOpenAI)
+        monkeypatch.setattr(_anthropic, "_get_anthropic_sdk", lambda: _FakeAnthropicSDK)
+
+        patch_load_config({
+            "provider": "azure-foundry",
+            "base_url": "https://r.services.ai.azure.com/anthropic",
+            "api_mode": "anthropic_messages",
+            "auth_mode": "entra_id",
+            "default": "claude-sonnet-4-5",
+        })
+        client, resolved = _aux._try_azure_foundry(model="claude-sonnet-4-5")
+        assert client is not None
+        assert resolved == "claude-sonnet-4-5"
+        # The Anthropic SDK constructor received a custom http_client
+        # (the bearer-injecting hook) and a placeholder auth_token.
+        anthropic_kwargs = received.get("anthropic") or {}
+        assert "http_client" in anthropic_kwargs, (
+            "build_anthropic_client must pass a custom http_client when "
+            "given a callable api_key, otherwise the SDK cannot mint "
+            "fresh tokens per request"
+        )
+        assert anthropic_kwargs.get("auth_token") == "entra-id-bearer-via-http-hook"
+        # Verify the http_client actually has our event hook installed.
+        http_client = anthropic_kwargs["http_client"]
+        hooks = getattr(http_client, "event_hooks", {})
+        assert "request" in hooks and len(hooks["request"]) >= 1
+
+
+# ---------------------------------------------------------------------------
+# resolve_provider_client → azure-foundry dispatch
+# ---------------------------------------------------------------------------
+
+
+class TestResolveProviderClientAzureFoundry:
+    def test_dispatches_to_azure_branch_not_generic_api_key_path(
+        self, monkeypatch, fake_azure_identity, patch_load_config,
+    ):
+        """End-to-end: the public ``resolve_provider_client`` entry
+        point must take the dedicated azure-foundry branch, NOT the
+        generic api-key registry path that would call
+        ``resolve_api_key_provider_credentials`` and return None for
+        Entra users."""
+        from agent import auxiliary_client as _aux
+
+        received = {}
+
+        class _FakeOpenAI:
+            def __init__(self, **kwargs):
+                received.update(kwargs)
+                self.api_key = kwargs.get("api_key", "")
+                self.base_url = kwargs.get("base_url", "")
+
+        monkeypatch.setattr(_aux, "OpenAI", _FakeOpenAI)
+        patch_load_config({
+            "provider": "azure-foundry",
+            "base_url": "https://r.openai.azure.com/openai/v1",
+            "api_mode": "chat_completions",
+            "auth_mode": "entra_id",
+            "default": "gpt-4o",
+        })
+        client, resolved = _aux.resolve_provider_client("azure-foundry", "gpt-4o")
+        assert client is not None
+        assert resolved == "gpt-4o"
+        # The callable made it through resolve_provider_client → _try_azure_foundry
+        # → OpenAI(api_key=...).
+        assert callable(received["api_key"])
+
+    def test_warns_and_returns_none_on_failure(
+        self, monkeypatch, patch_load_config, caplog,
+    ):
+        """When azure-foundry is requested but cannot be resolved
+        (e.g. no model + no key), we return (None, None) and log a
+        clear warning pointing at ``hermes doctor``."""
+        import logging
+        from agent.auxiliary_client import resolve_provider_client
+
+        monkeypatch.delenv("AZURE_FOUNDRY_API_KEY", raising=False)
+        patch_load_config({
+            "provider": "azure-foundry",
+            "base_url": "https://r.openai.azure.com/openai/v1",
+            "api_mode": "chat_completions",
+            # No default → resolver yields no model → bail
+        })
+        with caplog.at_level(logging.WARNING, logger="agent.auxiliary_client"):
+            client, resolved = resolve_provider_client("azure-foundry")
+        assert client is None
+        assert resolved is None
+        assert any(
+            "azure-foundry" in rec.message and "hermes doctor" in rec.message
+            for rec in caplog.records
+        )

tests/agent/test_auxiliary_concurrency.py

@@ -0,0 +1,403 @@
+"""Tests for per-task concurrency limiting on auxiliary LLM calls (#23324)."""
+
+import asyncio
+import threading
+import time
+from unittest.mock import MagicMock, AsyncMock, patch
+
+import pytest
+
+from agent.auxiliary_client import (
+    call_llm,
+    async_call_llm,
+    _acquire_sync_aux_semaphore,
+    _acquire_async_aux_semaphore,
+    _get_task_max_concurrency,
+    _reset_aux_semaphores,
+)
+
+
+@pytest.fixture(autouse=True)
+def _clean_semaphore_cache():
+    _reset_aux_semaphores()
+    yield
+    _reset_aux_semaphores()
+
+
+class TestGetTaskMaxConcurrency:
+    def test_returns_none_for_missing_task(self):
+        assert _get_task_max_concurrency(None) is None
+        assert _get_task_max_concurrency("") is None
+
+    def test_returns_none_when_unset(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config", return_value={}
+        ):
+            assert _get_task_max_concurrency("title_generation") is None
+
+    def test_does_not_reuse_vision_cpu_limit_for_llm_calls(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value={"max_concurrency": 1},
+        ):
+            assert _get_task_max_concurrency("vision") is None
+
+    def test_returns_int_when_configured(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value={"max_concurrency": 3},
+        ):
+            assert _get_task_max_concurrency("compression") == 3
+
+    def test_returns_none_for_non_numeric(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value={"max_concurrency": "not-a-number"},
+        ):
+            assert _get_task_max_concurrency("compression") is None
+
+    def test_returns_none_for_zero_or_negative(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value={"max_concurrency": 0},
+        ):
+            assert _get_task_max_concurrency("compression") is None
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value={"max_concurrency": -2},
+        ):
+            assert _get_task_max_concurrency("compression") is None
+
+
+class TestSemaphoreCache:
+    def test_sync_returns_none_when_unset(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config", return_value={}
+        ):
+            assert _acquire_sync_aux_semaphore("title_generation") is None
+
+    def test_sync_reuses_semaphore_for_same_limit(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value={"max_concurrency": 2},
+        ):
+            sem1 = _acquire_sync_aux_semaphore("compression")
+            sem2 = _acquire_sync_aux_semaphore("compression")
+            assert sem1 is sem2
+
+    def test_sync_rebuilds_when_limit_changes(self):
+        cfg = {"max_concurrency": 2}
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value=cfg,
+        ):
+            sem1 = _acquire_sync_aux_semaphore("compression")
+            cfg["max_concurrency"] = 5
+            sem2 = _acquire_sync_aux_semaphore("compression")
+            assert sem1 is not sem2
+
+    @pytest.mark.asyncio
+    async def test_async_reuses_semaphore_within_same_loop(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value={"max_concurrency": 2},
+        ):
+            sem1 = _acquire_async_aux_semaphore("compression")
+            sem2 = _acquire_async_aux_semaphore("compression")
+            assert sem1 is sem2
+
+    def test_async_returns_none_with_no_running_loop(self):
+        with patch(
+            "agent.auxiliary_client._get_auxiliary_task_config",
+            return_value={"max_concurrency": 2},
+        ):
+            # Called outside an asyncio loop — should bail rather than crash.
+            assert _acquire_async_aux_semaphore("compression") is None
+
+
+class TestSyncCallEnforcesLimit:
+    def test_call_llm_caps_concurrent_inflight(self):
+        limit = 2
+        n_callers = 6
+
+        active = 0
+        max_active = 0
+        lock = threading.Lock()
+
+        def fake_create(**kwargs):
+            nonlocal active, max_active
+            with lock:
+                active += 1
+                if active > max_active:
+                    max_active = active
+            try:
+                time.sleep(0.05)
+            finally:
+                with lock:
+                    active -= 1
+            return MagicMock()
+
+        client = MagicMock()
+        client.base_url = "https://example.test/v1"
+        client.chat.completions.create.side_effect = fake_create
+
+        with (
+            patch(
+                "agent.auxiliary_client._resolve_task_provider_model",
+                return_value=("openrouter", "test-model", None, None, None),
+            ),
+            patch(
+                "agent.auxiliary_client._get_cached_client",
+                return_value=(client, "test-model"),
+            ),
+            patch(
+                "agent.auxiliary_client._validate_llm_response",
+                side_effect=lambda resp, _task, **_kwargs: resp,
+            ),
+            patch(
+                "agent.auxiliary_client._get_auxiliary_task_config",
+                return_value={"max_concurrency": limit},
+            ),
+        ):
+            threads = [
+                threading.Thread(
+                    target=lambda: call_llm(
+                        task="title_generation",
+                        messages=[{"role": "user", "content": "hi"}],
+                    )
+                )
+                for _ in range(n_callers)
+            ]
+            for t in threads:
+                t.start()
+            for t in threads:
+                t.join(timeout=5)
+
+        assert max_active <= limit, f"observed {max_active} > limit {limit}"
+        assert client.chat.completions.create.call_count == n_callers
+
+    def test_call_llm_unlimited_when_not_configured(self):
+        client = MagicMock()
+        client.base_url = "https://example.test/v1"
+        client.chat.completions.create.return_value = MagicMock()
+
+        with (
+            patch(
+                "agent.auxiliary_client._resolve_task_provider_model",
+                return_value=("openrouter", "test-model", None, None, None),
+            ),
+            patch(
+                "agent.auxiliary_client._get_cached_client",
+                return_value=(client, "test-model"),
+            ),
+            patch(
+                "agent.auxiliary_client._validate_llm_response",
+                side_effect=lambda resp, _task, **_kwargs: resp,
+            ),
+            patch(
+                "agent.auxiliary_client._get_auxiliary_task_config",
+                return_value={},
+            ),
+        ):
+            # With no max_concurrency in config, no semaphore is acquired.
+            call_llm(
+                task="title_generation",
+                messages=[{"role": "user", "content": "hi"}],
+            )
+
+        assert client.chat.completions.create.call_count == 1
+
+    def test_semaphore_released_on_exception(self):
+        """Errors inside call_llm must release the semaphore so the next call proceeds."""
+        client = MagicMock()
+        client.base_url = "https://example.test/v1"
+        client.chat.completions.create.side_effect = RuntimeError("boom")
+
+        with (
+            patch(
+                "agent.auxiliary_client._resolve_task_provider_model",
+                return_value=("openrouter", "test-model", None, None, None),
+            ),
+            patch(
+                "agent.auxiliary_client._get_cached_client",
+                return_value=(client, "test-model"),
+            ),
+            patch(
+                "agent.auxiliary_client._validate_llm_response",
+                side_effect=lambda resp, _task, **_kwargs: resp,
+            ),
+            patch(
+                "agent.auxiliary_client._get_auxiliary_task_config",
+                return_value={"max_concurrency": 1},
+            ),
+        ):
+            for _ in range(3):
+                with pytest.raises(RuntimeError, match="boom"):
+                    call_llm(
+                        task="title_generation",
+                        messages=[{"role": "user", "content": "hi"}],
+                    )
+
+    def test_stream_holds_permit_until_consumed_and_preserves_options(self):
+        client = MagicMock()
+        client.base_url = "https://example.test/v1"
+        client.chat.completions.create.side_effect = [iter(["chunk"]), MagicMock()]
+        second_call_started = threading.Event()
+
+        def make_second_call():
+            second_call_started.set()
+            call_llm(
+                task="compression",
+                messages=[{"role": "user", "content": "second"}],
+            )
+
+        with (
+            patch(
+                "agent.auxiliary_client._resolve_task_provider_model",
+                return_value=("openrouter", "test-model", None, None, None),
+            ),
+            patch(
+                "agent.auxiliary_client._get_cached_client",
+                return_value=(client, "test-model"),
+            ),
+            patch(
+                "agent.auxiliary_client._validate_llm_response",
+                side_effect=lambda response, _task, **_kwargs: response,
+            ),
+            patch(
+                "agent.auxiliary_client._get_auxiliary_task_config",
+                return_value={"max_concurrency": 1},
+            ),
+        ):
+            stream = call_llm(
+                task="compression",
+                messages=[{"role": "user", "content": "first"}],
+                stream=True,
+                stream_options={"include_usage": True},
+            )
+            thread = threading.Thread(target=make_second_call)
+            thread.start()
+            assert second_call_started.wait(timeout=1)
+            time.sleep(0.05)
+            assert client.chat.completions.create.call_count == 1
+            assert list(stream) == ["chunk"]
+            thread.join(timeout=1)
+
+        assert not thread.is_alive()
+        assert client.chat.completions.create.call_count == 2
+        assert client.chat.completions.create.call_args_list[0].kwargs["stream"] is True
+        assert client.chat.completions.create.call_args_list[0].kwargs["stream_options"] == {
+            "include_usage": True
+        }
+
+    def test_api_mode_is_forwarded_to_client_resolution(self):
+        client = MagicMock()
+        client.base_url = "https://example.test/v1"
+        client.chat.completions.create.return_value = MagicMock()
+
+        with (
+            patch(
+                "agent.auxiliary_client._resolve_task_provider_model",
+                return_value=("openrouter", "test-model", None, None, None),
+            ),
+            patch(
+                "agent.auxiliary_client._get_cached_client",
+                return_value=(client, "test-model"),
+            ) as get_client,
+            patch(
+                "agent.auxiliary_client._validate_llm_response",
+                side_effect=lambda response, _task, **_kwargs: response,
+            ),
+        ):
+            call_llm(
+                task="title_generation",
+                messages=[{"role": "user", "content": "hi"}],
+                api_mode="codex_responses",
+            )
+
+        assert get_client.call_args.kwargs["api_mode"] == "codex_responses"
+
+
+class TestAsyncCallEnforcesLimit:
+    @pytest.mark.asyncio
+    async def test_async_call_llm_caps_concurrent_inflight(self):
+        limit = 2
+        n_callers = 6
+
+        active = 0
+        max_active = 0
+
+        async def fake_create(**kwargs):
+            nonlocal active, max_active
+            active += 1
+            if active > max_active:
+                max_active = active
+            try:
+                await asyncio.sleep(0.05)
+            finally:
+                active -= 1
+            return MagicMock()
+
+        client = MagicMock()
+        client.base_url = "https://example.test/v1"
+        client.chat.completions.create = AsyncMock(side_effect=fake_create)
+
+        with (
+            patch(
+                "agent.auxiliary_client._resolve_task_provider_model",
+                return_value=("openrouter", "test-model", None, None, None),
+            ),
+            patch(
+                "agent.auxiliary_client._get_cached_client",
+                return_value=(client, "test-model"),
+            ),
+            patch(
+                "agent.auxiliary_client._validate_llm_response",
+                side_effect=lambda resp, _task, **_kwargs: resp,
+            ),
+            patch(
+                "agent.auxiliary_client._get_auxiliary_task_config",
+                return_value={"max_concurrency": limit},
+            ),
+        ):
+            await asyncio.gather(*[
+                async_call_llm(
+                    task="compression",
+                    messages=[{"role": "user", "content": "hi"}],
+                )
+                for _ in range(n_callers)
+            ])
+
+        assert max_active <= limit, f"observed {max_active} > limit {limit}"
+        assert client.chat.completions.create.await_count == n_callers
+
+    @pytest.mark.asyncio
+    async def test_async_semaphore_released_on_exception(self):
+        client = MagicMock()
+        client.base_url = "https://example.test/v1"
+        client.chat.completions.create = AsyncMock(side_effect=RuntimeError("boom"))
+
+        with (
+            patch(
+                "agent.auxiliary_client._resolve_task_provider_model",
+                return_value=("openrouter", "test-model", None, None, None),
+            ),
+            patch(
+                "agent.auxiliary_client._get_cached_client",
+                return_value=(client, "test-model"),
+            ),
+            patch(
+                "agent.auxiliary_client._validate_llm_response",
+                side_effect=lambda resp, _task, **_kwargs: resp,
+            ),
+            patch(
+                "agent.auxiliary_client._get_auxiliary_task_config",
+                return_value={"max_concurrency": 1},
+            ),
+        ):
+            for _ in range(3):
+                with pytest.raises(RuntimeError, match="boom"):
+                    await async_call_llm(
+                        task="compression",
+                        messages=[{"role": "user", "content": "hi"}],
+                    )

tests/agent/test_auxiliary_named_custom_providers.py

@@ -0,0 +1,480 @@
+"""Tests for named custom provider and 'main' alias resolution in auxiliary_client."""
+
+import json
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _isolate(tmp_path, monkeypatch):
+    """Redirect HERMES_HOME and clear module caches."""
+    hermes_home = tmp_path / ".hermes"
+    hermes_home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+    # Write a minimal config so load_config doesn't fail
+    (hermes_home / "config.yaml").write_text("model:\n  default: test-model\n")
+
+
+def _write_config(tmp_path, config_dict):
+    """Write a config.yaml to the test HERMES_HOME."""
+    import yaml
+    config_path = tmp_path / ".hermes" / "config.yaml"
+    config_path.write_text(yaml.dump(config_dict))
+
+
+class TestNormalizeVisionProvider:
+    """_normalize_vision_provider should resolve 'main' to actual main provider."""
+
+
+    def test_main_resolves_to_openrouter(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "anthropic/claude-sonnet-4", "provider": "openrouter"},
+        })
+        from agent.auxiliary_client import _normalize_vision_provider
+        assert _normalize_vision_provider("main") == "openrouter"
+
+
+
+
+
+
+    def test_auto_unchanged(self):
+        from agent.auxiliary_client import _normalize_vision_provider
+        assert _normalize_vision_provider("auto") == "auto"
+        assert _normalize_vision_provider(None) == "auto"
+
+
+class TestResolveProviderClientMainAlias:
+    """resolve_provider_client('main', ...) should resolve to actual main provider."""
+
+    def test_main_resolves_to_named_custom_provider(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "my-model", "provider": "beans"},
+            "custom_providers": [
+                {"name": "beans", "base_url": "http://beans.local/v1", "api_key": "k"},
+            ],
+        })
+        from agent.auxiliary_client import resolve_provider_client
+        client, model = resolve_provider_client("main", "override-model")
+        assert client is not None
+        assert model == "override-model"
+        assert "beans.local" in str(client.base_url)
+
+    def test_main_with_custom_colon_prefix(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "my-model", "provider": "custom:beans"},
+            "custom_providers": [
+                {"name": "beans", "base_url": "http://beans.local/v1", "api_key": "k"},
+            ],
+        })
+        from agent.auxiliary_client import resolve_provider_client
+        client, model = resolve_provider_client("main", "test")
+        assert client is not None
+        assert "beans.local" in str(client.base_url)
+
+    def test_main_resolves_github_copilot_alias(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "gpt-5.4", "provider": "github-copilot"},
+        })
+        with (
+            patch("hermes_cli.auth.resolve_api_key_provider_credentials", return_value={
+                "api_key": "ghu_test_token",
+                "base_url": "https://api.githubcopilot.com",
+            }),
+            patch("agent.auxiliary_client.OpenAI") as mock_openai,
+        ):
+            mock_openai.return_value = MagicMock()
+            from agent.auxiliary_client import resolve_provider_client
+
+            client, model = resolve_provider_client("main", "gpt-5.4")
+
+        assert client is not None
+        assert model == "gpt-5.4"
+        assert mock_openai.called
+
+
+class TestResolveProviderClientNamedCustom:
+    """resolve_provider_client should resolve named custom providers directly."""
+
+    def test_named_custom_provider(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "test-model"},
+            "custom_providers": [
+                {"name": "beans", "base_url": "http://beans.local/v1", "api_key": "k"},
+            ],
+        })
+        from agent.auxiliary_client import resolve_provider_client
+        client, model = resolve_provider_client("beans", "my-model")
+        assert client is not None
+        assert model == "my-model"
+        assert "beans.local" in str(client.base_url)
+
+
+    def test_named_custom_no_api_key_uses_fallback(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "test"},
+            "custom_providers": [
+                {"name": "local", "base_url": "http://localhost:8080/v1"},
+            ],
+        })
+        from agent.auxiliary_client import resolve_provider_client
+        client, model = resolve_provider_client("local", "test")
+        assert client is not None
+        # no-key-required should be used
+
+    def test_providers_dict_uses_durable_pool_when_no_inline_key(self, tmp_path):
+        """Titles/compression/vision must read credential_pool.<key>, not a placeholder."""
+        _write_config(tmp_path, {
+            "providers": {
+                "b-ai": {
+                    "name": "B.AI",
+                    "base_url": "https://api.b.ai/v1",
+                },
+            },
+        })
+        auth_path = tmp_path / ".hermes" / "auth.json"
+        auth_path.write_text(json.dumps({
+            "version": 1,
+            "providers": {},
+            "credential_pool": {
+                "b-ai": [
+                    {
+                        "id": "k1",
+                        "label": "primary",
+                        "auth_type": "api_key",
+                        "priority": 0,
+                        "source": "manual",
+                        "access_token": "sk-real-b-ai-pool-key-12345",
+                    }
+                ]
+            },
+        }))
+        from agent.auxiliary_client import resolve_provider_client
+        client, _model = resolve_provider_client("b-ai", "b-ai-model")
+        assert client is not None
+        assert "api.b.ai" in str(client.base_url)
+        assert client.api_key == "sk-real-b-ai-pool-key-12345"
+
+
+class TestResolveProviderClientModelNormalization:
+    """Direct-provider auxiliary routing should normalize models like main runtime."""
+
+    def test_matching_native_prefix_is_stripped_for_main_provider(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "zai/glm-5.1", "provider": "zai"},
+        })
+        with (
+            patch("hermes_cli.auth.resolve_api_key_provider_credentials", return_value={
+                "api_key": "glm-key",
+                "base_url": "https://api.z.ai/api/paas/v4",
+            }),
+            patch("agent.auxiliary_client.OpenAI") as mock_openai,
+        ):
+            mock_openai.return_value = MagicMock()
+            from agent.auxiliary_client import resolve_provider_client
+
+            client, model = resolve_provider_client("main", "zai/glm-5.1")
+
+        assert client is not None
+        assert model == "glm-5.1"
+
+
+    def test_aggregator_vendor_slug_is_preserved(self, monkeypatch):
+        monkeypatch.setenv("OPENROUTER_API_KEY", "or-key")
+        with patch("agent.auxiliary_client.OpenAI") as mock_openai:
+            mock_openai.return_value = MagicMock()
+            from agent.auxiliary_client import resolve_provider_client
+
+            client, model = resolve_provider_client(
+                "openrouter", "anthropic/claude-sonnet-4.6"
+            )
+
+        assert client is not None
+        assert model == "anthropic/claude-sonnet-4.6"
+
+
+class TestResolveVisionProviderClientModelNormalization:
+    """Vision auto-routing should reuse the same provider-specific normalization."""
+
+    def test_vision_auto_strips_matching_main_provider_prefix(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "zai/glm-5.1", "provider": "zai"},
+        })
+        with (
+            patch("agent.auxiliary_client._read_nous_auth", return_value=None),
+            patch("hermes_cli.auth.resolve_api_key_provider_credentials", return_value={
+                "api_key": "glm-key",
+                "base_url": "https://api.z.ai/api/paas/v4",
+            }),
+            patch("agent.auxiliary_client.OpenAI") as mock_openai,
+        ):
+            mock_openai.return_value = MagicMock()
+            from agent.auxiliary_client import resolve_vision_provider_client
+
+            provider, client, model = resolve_vision_provider_client()
+
+        assert provider == "zai"
+        assert client is not None
+        assert model == "glm-5v-turbo"  # zai has dedicated vision model in _PROVIDER_VISION_MODELS
+
+
+class TestAutoClientCacheModelCompatibility:
+    """Auto client cache should not keep OpenRouter-format model overrides on non-OR clients."""
+
+    def test_first_auto_cache_miss_drops_openrouter_model_for_named_custom_runtime(self, tmp_path):
+        from agent import auxiliary_client as ac
+
+        ac._client_cache.clear()
+        try:
+            fake_client = MagicMock()
+            fake_client.base_url = "https://aixj.vip/v1"
+            fake_client.api_key = "test-key"
+
+            runtime = {
+                "provider": "custom:aixj.vip",
+                "model": "gpt-5.4",
+                "base_url": "https://aixj.vip/v1",
+                "api_key": "***",
+                "api_mode": "codex_responses",
+            }
+
+            with patch(
+                "agent.auxiliary_client.resolve_provider_client",
+                return_value=(fake_client, "gpt-5.4"),
+            ) as mock_resolve:
+                client, model = ac._get_cached_client(
+                    "auto",
+                    "google/gemini-3-flash-preview",
+                    main_runtime=runtime,
+                )
+
+            assert client is fake_client
+            assert model == "gpt-5.4"
+            mock_resolve.assert_called_once()
+        finally:
+            ac._client_cache.clear()
+
+
+class TestVisionPathApiMode:
+    """Vision path should propagate api_mode to _get_cached_client."""
+
+    def test_explicit_provider_passes_api_mode(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"default": "test-model"},
+            "auxiliary": {"vision": {"api_mode": "chat_completions"}},
+        })
+        with patch("agent.auxiliary_client._get_cached_client") as mock_gcc:
+            mock_gcc.return_value = (MagicMock(), "test-model")
+            from agent.auxiliary_client import resolve_vision_provider_client
+
+            provider, client, model = resolve_vision_provider_client(provider="deepseek")
+
+        mock_gcc.assert_called_once()
+        _, kwargs = mock_gcc.call_args
+        assert kwargs.get("api_mode") == "chat_completions"
+
+
+class TestProvidersDictApiModeAnthropicMessages:
+    """Regression guard for #15033.
+
+    Named providers declared under the ``providers:`` dict with
+    ``api_mode: anthropic_messages`` must route auxiliary calls through
+    the Anthropic Messages API (via AnthropicAuxiliaryClient), not
+    through an OpenAI chat-completions client.
+
+    The bug had two halves: the providers-dict branch of
+    ``_get_named_custom_provider`` dropped the ``api_mode`` field, and
+    ``resolve_provider_client``'s named-custom branch never read it.
+    """
+
+    def test_providers_dict_propagates_api_mode(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("MYRELAY_API_KEY", "sk-test")
+        _write_config(tmp_path, {
+            "providers": {
+                "myrelay": {
+                    "name": "myrelay",
+                    "base_url": "https://example-relay.test/anthropic",
+                    "key_env": "MYRELAY_API_KEY",
+                    "api_mode": "anthropic_messages",
+                    "default_model": "claude-opus-4-7",
+                },
+            },
+        })
+        from hermes_cli.runtime_provider import _get_named_custom_provider
+        entry = _get_named_custom_provider("myrelay")
+        assert entry is not None
+        assert entry.get("api_mode") == "anthropic_messages"
+        assert entry.get("base_url") == "https://example-relay.test/anthropic"
+        assert entry.get("api_key") == "sk-test"
+
+
+
+    def test_resolve_provider_client_returns_anthropic_client(self, tmp_path, monkeypatch):
+        """Named custom provider with api_mode=anthropic_messages must
+        route through AnthropicAuxiliaryClient."""
+        monkeypatch.setenv("MYRELAY_API_KEY", "sk-test")
+        _write_config(tmp_path, {
+            "providers": {
+                "myrelay": {
+                    "name": "myrelay",
+                    "base_url": "https://example-relay.test/anthropic",
+                    "key_env": "MYRELAY_API_KEY",
+                    "api_mode": "anthropic_messages",
+                    "default_model": "claude-opus-4-7",
+                },
+            },
+        })
+        from agent.auxiliary_client import (
+            resolve_provider_client,
+            AnthropicAuxiliaryClient,
+            AsyncAnthropicAuxiliaryClient,
+        )
+        sync_client, sync_model = resolve_provider_client("myrelay", async_mode=False)
+        assert isinstance(sync_client, AnthropicAuxiliaryClient), (
+            f"expected AnthropicAuxiliaryClient, got {type(sync_client).__name__}"
+        )
+        assert sync_model == "claude-opus-4-7"
+
+        async_client, async_model = resolve_provider_client("myrelay", async_mode=True)
+        assert isinstance(async_client, AsyncAnthropicAuxiliaryClient), (
+            f"expected AsyncAnthropicAuxiliaryClient, got {type(async_client).__name__}"
+        )
+        assert async_model == "claude-opus-4-7"
+
+
+
+
+class TestCustomProviderAliasCollision:
+    """A user-declared custom_providers entry whose name matches a built-in
+    *alias* (not a canonical provider) must win over the built-in.
+
+    Regression guard for #15743: users who defined fallback_model pointing at
+    a custom_providers entry named ``kimi`` were having requests routed to
+    the built-in kimi-coding endpoint because ``_normalize_aux_provider``
+    rewrote ``kimi`` → ``kimi-coding`` before the named-custom lookup.
+    """
+
+    def test_custom_named_kimi_wins_over_builtin_alias(self, tmp_path):
+        _write_config(tmp_path, {
+            "model": {"provider": "openrouter", "default": "anthropic/claude-sonnet-4.6"},
+            "custom_providers": [
+                {
+                    "name": "kimi",
+                    "base_url": "https://my-custom-kimi.example.com/v1",
+                    "api_key": "my-kimi-key",
+                    "models": {"my-kimi-model": {"context_length": 200000}},
+                },
+            ],
+        })
+        from agent.auxiliary_client import resolve_provider_client
+        from openai import OpenAI
+        client, model = resolve_provider_client("kimi", model="my-kimi-model", raw_codex=True)
+        assert isinstance(client, OpenAI)
+        assert "my-custom-kimi.example.com" in str(client.base_url)
+        assert client.api_key == "my-kimi-key"
+        assert model == "my-kimi-model"
+
+    def test_bare_kimi_without_custom_still_routes_to_builtin(self, tmp_path, monkeypatch):
+        """Regression guard: bare 'kimi' with no custom entry must still
+        reach the built-in kimi-coding provider."""
+        _write_config(tmp_path, {
+            "model": {"provider": "openrouter", "default": "anthropic/claude-sonnet-4.6"},
+        })
+        monkeypatch.setenv("KIMI_API_KEY", "builtin-kimi-key")
+        from agent.auxiliary_client import resolve_provider_client
+        client, _ = resolve_provider_client("kimi", model="kimi-k2-0905-preview", raw_codex=True)
+        assert client is not None
+        base_url = str(client.base_url)
+        # Built-in kimi-coding points at api.moonshot.ai
+        assert "moonshot" in base_url or "kimi" in base_url, f"unexpected base_url {base_url!r}"
+
+    def test_explicit_overrides_applied_on_api_key_branch(self, tmp_path, monkeypatch):
+        """Explicit base_url/api_key from the caller must override the
+        registered provider's defaults on the API-key branch.  Used by
+        _try_activate_fallback to route a fallback through a built-in
+        provider name but targeting a user-supplied endpoint."""
+        _write_config(tmp_path, {
+            "model": {"provider": "openrouter", "default": "anthropic/claude-sonnet-4.6"},
+        })
+        monkeypatch.setenv("KIMI_API_KEY", "builtin-kimi-key")
+        from agent.auxiliary_client import resolve_provider_client
+        from openai import OpenAI
+        client, _ = resolve_provider_client(
+            "kimi-coding", model="kimi-k2", raw_codex=True,
+            explicit_base_url="https://override.example.com",
+            explicit_api_key="override-key",
+        )
+        assert isinstance(client, OpenAI)
+        assert "override.example.com" in str(client.base_url)
+        assert client.api_key == "override-key"
+
+
+class TestResolveProviderClientMainRuntimeCustom:
+    """When the main agent uses a named custom provider (custom:<name>),
+    resolve_provider_client('custom', ..., main_runtime=...) must reuse the
+    main_runtime's base_url + api_key instead of re-resolving from the bare
+    'custom' provider name.  Re-resolution loses the provider name and falls
+    back to OpenRouter or a wrong API-key provider. (#45472)"""
+
+    def test_custom_provider_main_runtime_used_directly(self, tmp_path, monkeypatch):
+        """main_runtime with base_url + api_key for a named custom provider
+        is used directly, bypassing the _try_custom_endpoint / API-key
+        fallback chain."""
+        from agent.auxiliary_client import resolve_provider_client
+        main_runtime = {
+            "provider": "custom",
+            "base_url": "https://my-gateway.example.com/v1",
+            "api_key": "***",
+            "model": "glm-5.1",
+        }
+        client, model = resolve_provider_client(
+            "custom",
+            model="explicit-glm-5.1",
+            main_runtime=main_runtime,
+        )
+        assert client is not None
+        assert model == "explicit-glm-5.1"
+        assert "my-gateway.example.com" in str(client.base_url)
+        assert client.api_key == "***"
+
+    def test_custom_provider_main_runtime_no_credentials_falls_through(self, tmp_path, monkeypatch):
+        """When main_runtime has no base_url or no api_key, the existing
+        _try_custom_endpoint / _resolve_api_key_provider fallback chain is
+        still tried."""
+        # Ensure no env-provided credentials interfere
+        monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+        monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+        monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+        monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+
+        from agent.auxiliary_client import resolve_provider_client
+        # main_runtime with key but no base_url → must fall through
+        client, model = resolve_provider_client(
+            "custom",
+            main_runtime={"api_key": "k", "base_url": ""},
+        )
+        # Should fall through to _try_custom_endpoint → return None,None
+        # because no OPENAI_BASE_URL is set and no custom endpoint is configured
+        assert client is None
+
+    def test_custom_provider_main_runtime_respects_explicit_base_url(self, tmp_path):
+        """explicit_base_url still wins over main_runtime — the caller's
+        explicit argument is the strongest signal."""
+        from agent.auxiliary_client import resolve_provider_client
+        main_runtime = {
+            "base_url": "https://main-runtime.example.com/v1",
+            "api_key": "sk-main",
+            "model": "ignored-model",
+        }
+        client, model = resolve_provider_client(
+            "custom",
+            model="explicit-model",
+            explicit_base_url="https://explicit.example.com/v1",
+            explicit_api_key="sk-explicit",
+            main_runtime=main_runtime,
+        )
+        assert client is not None
+        assert model == "explicit-model"
+        assert "explicit.example.com" in str(client.base_url)
+        assert client.api_key == "sk-explicit"

tests/agent/test_auxiliary_transient_retry.py

@@ -0,0 +1,62 @@
+"""Transient-transport retry count + per-model client-cache isolation.
+
+Two related hardening behaviors for auxiliary calls (which include MoA
+reference advisors, a pinned-model path where provider fallback is not a
+meaningful recovery):
+
+1. A transient transport blip (connection reset / timeout / 5xx) is retried
+   on the SAME provider several times with backoff before giving up — a single
+   upstream blip should not silently lose a pinned auxiliary call (root of the
+   run2 double-advisor "Connection error" collapse).
+2. Two auxiliary calls to the same provider/base_url/key but DIFFERENT models
+   get DISTINCT client-cache keys, so a concurrent fan-out (e.g. opus + gpt-5.5
+   advisors) never shares one client entry.
+"""
+
+from __future__ import annotations
+
+import os
+import types
+from unittest.mock import patch
+
+import pytest
+
+
+
+
+def test_transient_retry_count_default(monkeypatch):
+    from agent import auxiliary_client as ac
+
+    # No config value -> default.
+    monkeypatch.setattr(ac, "load_config", lambda: {}, raising=False)
+    with patch("hermes_cli.config.load_config", return_value={}), \
+         patch("hermes_cli.config.cfg_get", return_value=None):
+        assert ac._transient_retry_count() == ac._DEFAULT_TRANSIENT_RETRIES
+
+
+
+
+def test_model_participates_in_client_cache_key():
+    """Same provider/base_url/key, different model -> different cache key.
+
+    This is what stops two concurrent advisors from sharing (and racing on)
+    one cached client entry."""
+    from agent.auxiliary_client import _client_cache_key
+
+    k_opus = _client_cache_key(
+        "openrouter", async_mode=False, base_url="https://openrouter.ai/api/v1",
+        api_key="K", model="anthropic/claude-opus-4.8",
+    )
+    k_gpt = _client_cache_key(
+        "openrouter", async_mode=False, base_url="https://openrouter.ai/api/v1",
+        api_key="K", model="openai/gpt-5.5",
+    )
+    assert k_opus != k_gpt
+    # Same model still collides (cache still works for reuse).
+    k_opus2 = _client_cache_key(
+        "openrouter", async_mode=False, base_url="https://openrouter.ai/api/v1",
+        api_key="K", model="anthropic/claude-opus-4.8",
+    )
+    assert k_opus == k_opus2
+
+

tests/agent/test_azure_identity_adapter.py

@@ -0,0 +1,496 @@
+"""Tests for the Microsoft Entra ID adapter (agent/azure_identity_adapter.py).
+
+Covers:
+  - Scope resolution per Azure host shape
+  - Display masking for callable + string + None inputs
+  - Cache-fingerprint stability under callable refresh
+  - is_token_provider truthiness on callables vs strings
+  - EntraIdentityConfig serialization round-trip
+  - Token provider construction with mocked azure-identity
+  - Credential cache reuse + reset
+  - has_azure_identity_credentials timeout / failure paths
+  - describe_active_credential structural reporting
+  - Lazy-install error path when azure-identity absent + lazy installs
+    disabled
+
+We mock azure.identity at the import boundary rather than hitting any
+real Azure endpoint. Tests must remain hermetic per AGENTS.md.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from types import SimpleNamespace
+from typing import cast
+
+import pytest
+
+# Ensure we always import a fresh adapter module — credential caches in
+# the adapter persist across tests otherwise, polluting assertions
+# about cache invalidation.
+@pytest.fixture(autouse=True)
+def _reset_adapter_cache():
+    from agent.azure_identity_adapter import reset_credential_cache
+    reset_credential_cache()
+    yield
+    reset_credential_cache()
+
+
+# ---------------------------------------------------------------------------
+# Scope constant
+# ---------------------------------------------------------------------------
+
+
+class TestEntraScopeConstant:
+    """Pin the Microsoft-documented Foundry inference scope.
+
+    Microsoft's official samples for both ``*.openai.azure.com`` and
+    ``*.services.ai.azure.com`` use ``https://ai.azure.com/.default``.
+    The older ``cognitiveservices.azure.com/.default`` is the
+    control-plane scope and is rejected for inference by newer
+    Azure OpenAI / Foundry resources.
+
+    Users with sovereign-cloud or unusual-tenant requirements pass the
+    scope explicitly via ``model.entra.scope`` in ``config.yaml``.
+
+    Refs:
+      * https://learn.microsoft.com/azure/ai-foundry/openai/how-to/managed-identity
+      * https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id
+    """
+
+    def test_default_scope_matches_microsoft_documentation(self):
+        from agent.azure_identity_adapter import SCOPE_AI_AZURE_DEFAULT
+        assert SCOPE_AI_AZURE_DEFAULT == "https://ai.azure.com/.default"
+
+
+# ---------------------------------------------------------------------------
+# Cache fingerprint + http-bearer helpers
+# ---------------------------------------------------------------------------
+
+
+class TestMaterializeBearerForHttp:
+    """The only helper that mints a real bearer JWT — must call the
+    callable exactly once and never fall through to display masking."""
+
+    def test_callable_is_invoked_and_returns_token(self):
+        from agent.azure_identity_adapter import materialize_bearer_for_http
+
+        invoked = {"count": 0}
+
+        def provider():
+            invoked["count"] += 1
+            return "fresh-jwt"
+
+        assert materialize_bearer_for_http(provider) == "fresh-jwt"
+        assert invoked["count"] == 1
+
+
+
+    def test_empty_string_raises(self):
+        from agent.azure_identity_adapter import materialize_bearer_for_http
+        with pytest.raises(ValueError):
+            materialize_bearer_for_http("")
+        with pytest.raises(ValueError):
+            materialize_bearer_for_http(None)
+
+
+# ---------------------------------------------------------------------------
+# build_bearer_http_client — the Anthropic-on-Foundry bridge
+# ---------------------------------------------------------------------------
+
+
+class TestBuildBearerHttpClient:
+    """``build_bearer_http_client`` returns an ``httpx.Client`` whose
+    request event hook mints a fresh JWT per outbound request. This is
+    how Entra ID auth reaches the Anthropic SDK (which does not accept
+    callable ``auth_token``)."""
+
+
+    def test_hook_overrides_authorization_header(self):
+        import httpx
+        from agent.azure_identity_adapter import build_bearer_http_client
+
+        minted_tokens = []
+
+        def provider():
+            minted_tokens.append(f"jwt-{len(minted_tokens) + 1}")
+            return minted_tokens[-1]
+
+        client = build_bearer_http_client(provider)
+        try:
+            hook = client.event_hooks["request"][0]
+            # Build a request with conflicting pre-set headers and verify
+            # the hook strips them and installs the fresh bearer.
+            req = httpx.Request(
+                "POST", "https://example.com/v1/messages",
+                headers={
+                    "Authorization": "Bearer stale-token",
+                    "api-key": "static-key",
+                    "x-api-key": "static-key",
+                },
+                json={"hello": "world"},
+            )
+            hook(req)
+            assert req.headers["Authorization"] == "Bearer jwt-1"
+            # The static-key headers must be stripped — sending both
+            # auth values would be ambiguous on Azure.
+            assert "api-key" not in req.headers
+            assert "x-api-key" not in req.headers
+
+            # Second invocation mints a fresh token.
+            req2 = httpx.Request("GET", "https://example.com/v1/models")
+            hook(req2)
+            assert req2.headers["Authorization"] == "Bearer jwt-2"
+            assert len(minted_tokens) == 2
+        finally:
+            client.close()
+
+    def test_hook_strips_auth_headers_and_warns_when_token_provider_fails(self, caplog):
+        """When the token provider fails (chain exhausted, IMDS down, az
+        login expired), the hook must:
+          1. Log at WARNING level so the misconfiguration is visible at
+             default log level (not buried at DEBUG).
+          2. Strip any pre-set Authorization headers — including the
+             placeholder ``entra-id-bearer-via-http-hook`` sentinel that
+             :func:`_build_anthropic_client_with_bearer_hook` sets on the
+             Anthropic SDK constructor. This produces a clean
+             "missing auth" 401 from Azure rather than a sentinel-bearing
+             401 that's harder to diagnose AND avoids leaking the
+             sentinel string into upstream access logs.
+        """
+        import logging
+        import httpx
+        from agent.azure_identity_adapter import build_bearer_http_client
+
+        def bad_provider():
+            return ""  # empty token → materialize_bearer_for_http raises
+
+        client = build_bearer_http_client(bad_provider)
+        try:
+            hook = client.event_hooks["request"][0]
+            req = httpx.Request(
+                "POST", "https://example.com/v1/messages",
+                headers={
+                    "Authorization": "Bearer entra-id-bearer-via-http-hook",
+                    "api-key": "leaked-placeholder",
+                },
+            )
+            with caplog.at_level(logging.WARNING, logger="agent.azure_identity_adapter"):
+                hook(req)  # Must not raise.
+            # Pre-set auth headers stripped — no sentinel makes it to Azure.
+            assert "Authorization" not in req.headers
+            assert "api-key" not in req.headers
+            # WARNING was logged so the user sees the misconfiguration.
+            assert any(
+                rec.levelno == logging.WARNING and "Entra ID token provider" in rec.message
+                for rec in caplog.records
+            )
+        finally:
+            client.close()
+
+
+
+
+class TestIsTokenProvider:
+    def test_callable_is_token_provider(self):
+        from agent.azure_identity_adapter import is_token_provider
+        assert is_token_provider(lambda: "x") is True
+
+    def test_string_is_not_token_provider(self):
+        from agent.azure_identity_adapter import is_token_provider
+        assert is_token_provider("static-key") is False
+        # ``str`` instances are technically callable in some edge cases
+        # — confirm they're never classified as token providers.
+        assert is_token_provider("") is False
+
+
+# ---------------------------------------------------------------------------
+# EntraIdentityConfig
+# ---------------------------------------------------------------------------
+
+
+class TestEntraIdentityConfig:
+    """The serializable config that crosses multiprocessing boundaries —
+    must round-trip through dict cleanly and never lose fields."""
+
+    def test_to_dict_round_trip(self):
+        from agent.azure_identity_adapter import EntraIdentityConfig
+        cfg = EntraIdentityConfig(
+            scope="https://ai.azure.com/.default",
+            exclude_interactive_browser=False,
+        )
+        rebuilt = EntraIdentityConfig.from_dict(cfg.to_dict())
+        assert rebuilt == cfg
+
+
+
+
+
+    def test_dataclass_is_frozen(self):
+        # Frozen dataclasses are hashable / safe to pass through caches.
+        from agent.azure_identity_adapter import EntraIdentityConfig
+        cfg = EntraIdentityConfig()
+        with pytest.raises((AttributeError, Exception)):
+            setattr(cfg, "scope", "mutated")
+
+
+# ---------------------------------------------------------------------------
+# Credential / token provider construction
+# ---------------------------------------------------------------------------
+
+
+class _FakeAzureIdentity:
+    """Stand-in for the ``azure.identity`` module.
+
+    Captures kwargs passed to ``DefaultAzureCredential`` so tests can
+    assert how config flows into the SDK.
+    """
+
+    def __init__(self):
+        self.last_credential_kwargs = None
+        self.last_scope = None
+        self.credential_count = 0
+
+    def DefaultAzureCredential(self, **kwargs):  # noqa: N802 — match SDK
+        self.last_credential_kwargs = kwargs
+        self.credential_count += 1
+        return SimpleNamespace(
+            get_token=lambda scope: SimpleNamespace(token="fake-jwt", expires_on=9999999999),
+            kwargs=kwargs,
+        )
+
+    def get_bearer_token_provider(self, credential, scope):
+        self.last_scope = scope
+        # Return a callable that mints a token when invoked.
+        return lambda: f"jwt-for-{scope}"
+
+
+@pytest.fixture
+def fake_azure_identity(monkeypatch):
+    """Install a fake azure.identity into sys.modules and stub the
+    adapter's `_require_azure_identity` so all tests use the fake."""
+    fake = _FakeAzureIdentity()
+
+    fake_module = SimpleNamespace(
+        DefaultAzureCredential=fake.DefaultAzureCredential,
+        get_bearer_token_provider=fake.get_bearer_token_provider,
+    )
+    monkeypatch.setitem(sys.modules, "azure", SimpleNamespace(identity=fake_module))
+    monkeypatch.setitem(sys.modules, "azure.identity", fake_module)
+
+    # The adapter's `_require_azure_identity` does its own import, so
+    # patch that too to make sure tests never hit the real package's
+    # singleton state.
+    from agent import azure_identity_adapter as _adapter
+    monkeypatch.setattr(_adapter, "_require_azure_identity", lambda: fake_module)
+
+    return fake
+
+
+class TestBuildCredential:
+    def test_default_kwargs_are_minimal(self, fake_azure_identity):
+        """SDK default for ``exclude_interactive_browser_credential`` is
+        True; we only pass it when the user opts IN to interactive
+        browser auth. Tenant / authority / service principal config
+        flow through the standard ``AZURE_*`` env vars (read by
+        azure-identity directly), not Hermes config kwargs."""
+        from agent.azure_identity_adapter import EntraIdentityConfig, build_credential
+        cred = build_credential(EntraIdentityConfig())
+        kwargs = fake_azure_identity.last_credential_kwargs
+        # Default config should produce empty kwargs — SDK uses its own
+        # defaults plus env-var-driven settings.
+        assert kwargs == {}
+        assert cred is not None
+
+
+    def test_credential_is_cached_per_config(self, fake_azure_identity):
+        from agent.azure_identity_adapter import EntraIdentityConfig, build_credential
+        cfg = EntraIdentityConfig(scope="s1")
+        c1 = build_credential(cfg)
+        c2 = build_credential(cfg)
+        assert c1 is c2
+        assert fake_azure_identity.credential_count == 1
+
+    def test_distinct_configs_get_distinct_credentials(self, fake_azure_identity):
+        from agent.azure_identity_adapter import EntraIdentityConfig, build_credential
+        c1 = build_credential(EntraIdentityConfig(scope="s1"))
+        c2 = build_credential(EntraIdentityConfig(scope="s2"))
+        assert c1 is not c2
+        assert fake_azure_identity.credential_count == 2
+
+
+
+class TestBuildTokenProvider:
+    def test_returns_callable_for_scope(self, fake_azure_identity):
+        from agent.azure_identity_adapter import build_token_provider
+        provider = build_token_provider(scope="https://ai.azure.com/.default")
+        assert callable(provider)
+        assert provider() == "jwt-for-https://ai.azure.com/.default"
+        assert fake_azure_identity.last_scope == "https://ai.azure.com/.default"
+
+
+
+    def test_config_object_wins_over_kwargs(self, fake_azure_identity):
+        from agent.azure_identity_adapter import (
+            EntraIdentityConfig,
+            build_token_provider,
+        )
+        cfg = EntraIdentityConfig(scope="cfg-scope")
+        build_token_provider(scope="ignored", config=cfg)
+        assert fake_azure_identity.last_scope == "cfg-scope"
+        assert fake_azure_identity.last_credential_kwargs == {}
+
+
+# ---------------------------------------------------------------------------
+# Lazy-install / missing-package surface
+# ---------------------------------------------------------------------------
+
+
+class TestRequireAzureIdentityMissing:
+    def test_clear_error_when_lazy_install_disabled(self, monkeypatch):
+        """When azure-identity isn't importable AND lazy installs are
+        off, the adapter must raise ImportError with an actionable
+        message, not propagate FeatureUnavailable."""
+        from agent import azure_identity_adapter as _adapter
+
+        # Force the import path to fail.
+        original_import = __builtins__["__import__"] if isinstance(__builtins__, dict) else __import__
+        def _fake_import(name, *args, **kwargs):
+            if name == "azure.identity" or name.startswith("azure.identity."):
+                raise ImportError("simulated missing azure-identity")
+            return original_import(name, *args, **kwargs)
+
+        monkeypatch.setattr("builtins.__import__", _fake_import)
+
+        # Simulate lazy installs disabled.
+        from tools.lazy_deps import FeatureUnavailable
+
+        def _fake_ensure(*args, **kwargs):
+            raise FeatureUnavailable(
+                "provider.azure_identity",
+                ("azure-identity==1.25.3",),
+                "lazy installs disabled (test simulation)",
+            )
+
+        # The adapter calls ``ensure`` from ``tools.lazy_deps``; intercept
+        # it by patching the actual symbol path.
+        monkeypatch.setattr("tools.lazy_deps.ensure", _fake_ensure)
+
+        with pytest.raises(ImportError) as exc_info:
+            _adapter._require_azure_identity()
+        msg = str(exc_info.value)
+        assert "azure-identity" in msg
+        assert "Foundry" in msg or "foundry" in msg.lower()
+
+
+# ---------------------------------------------------------------------------
+# has_azure_identity_credentials probe (timeout-bounded)
+# ---------------------------------------------------------------------------
+
+
+class TestHasAzureIdentityCredentials:
+
+    def test_lazy_install_triggered_when_package_missing(self, monkeypatch):
+        """With allow_install=True (default), the probe must trigger the
+        lazy-install path before bailing — otherwise the wizard's
+        ``preflight`` would silently fail for fresh installs that haven't
+        run ``pip install azure-identity`` yet."""
+        from agent import azure_identity_adapter as _adapter
+
+        installed = {"called": False}
+
+        def _fake_install():
+            installed["called"] = True
+            # After install, pretend the package is now importable.
+            monkeypatch.setattr(_adapter, "has_azure_identity_installed", lambda: True)
+            return SimpleNamespace(
+                DefaultAzureCredential=lambda **kw: SimpleNamespace(
+                    kwargs=kw,
+                    get_token=lambda scope: SimpleNamespace(token="post-install-jwt", expires_on=0),
+                ),
+                get_bearer_token_provider=lambda c, s: lambda: "x",
+            )
+
+        monkeypatch.setattr(_adapter, "has_azure_identity_installed", lambda: False)
+        monkeypatch.setattr(_adapter, "_require_azure_identity", _fake_install)
+
+        # Provide a credential factory so the probe proceeds after install.
+        monkeypatch.setattr(
+            _adapter, "build_credential",
+            lambda config: SimpleNamespace(
+                get_token=lambda scope: SimpleNamespace(token="probe-jwt", expires_on=0),
+            ),
+        )
+
+        result = _adapter.has_azure_identity_credentials(
+            "https://x/.default", timeout_seconds=0.5,
+        )
+        assert installed["called"] is True, (
+            "has_azure_identity_credentials must trigger lazy install "
+            "before bailing"
+        )
+        assert result is True
+
+
+
+    def test_returns_false_on_timeout(self, monkeypatch):
+        """Slow IMDS / network must time out, not hang the caller."""
+        import threading
+        from agent import azure_identity_adapter as _adapter
+
+        slow_release = threading.Event()
+
+        def _slow_credential(_config):
+            class _Cred:
+                def get_token(self, scope):
+                    # Block forever from the test's perspective; the
+                    # adapter must give up via its thread-bounded probe.
+                    slow_release.wait(timeout=10)
+                    return SimpleNamespace(token="never-returned", expires_on=0)
+            return _Cred()
+
+        monkeypatch.setattr(_adapter, "build_credential", _slow_credential)
+        monkeypatch.setattr(_adapter, "has_azure_identity_installed", lambda: True)
+        try:
+            assert _adapter.has_azure_identity_credentials(
+                "https://x/.default", timeout_seconds=0.1
+            ) is False
+        finally:
+            slow_release.set()
+
+
+# ---------------------------------------------------------------------------
+# describe_active_credential — used by hermes doctor + hermes auth
+# ---------------------------------------------------------------------------
+
+
+class TestDescribeActiveCredential:
+
+    def test_reports_install_failure(self, monkeypatch):
+        """When lazy install is allowed but fails (e.g. lazy installs
+        disabled), the diagnostic surfaces the failure as the error."""
+        from agent import azure_identity_adapter as _adapter
+        monkeypatch.setattr(_adapter, "has_azure_identity_installed", lambda: False)
+
+        def _fail_install():
+            raise ImportError("simulated: lazy installs disabled")
+
+        monkeypatch.setattr(_adapter, "_require_azure_identity", _fail_install)
+        info = _adapter.describe_active_credential(
+            scope="https://x/.default", allow_install=True,
+        )
+        assert info["ok"] is False
+        assert "lazy installs disabled" in info["error"]
+        assert "lazy" in info["hint"].lower()
+
+    def test_reports_env_sources_for_managed_identity(self, fake_azure_identity, monkeypatch):
+        from agent.azure_identity_adapter import describe_active_credential
+        monkeypatch.setenv("IDENTITY_ENDPOINT", "http://169.254.169.254")
+        info = describe_active_credential(scope="https://x/.default", timeout_seconds=0.5)
+        assert info["ok"] is True
+        sources = info.get("env_sources") or []
+        assert any("ManagedIdentity" in s for s in sources)
+
+
+

tests/agent/test_background_review_input_budget.py

@@ -0,0 +1,239 @@
+"""Regression tests for the background-review aggregate input budget (#93057).
+
+The review fork replays its snapshot on every provider request in its tool
+loop. Detached in-memory compaction bounds any SINGLE request; the aggregate
+input budget (``_review_input_token_budget``, set by
+``_run_review_in_thread`` from ``auxiliary.background_review.max_input_tokens``)
+bounds the WHOLE review: the tool loop stops before the provider call that
+would cross it, mirroring the iteration-budget exit.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from run_agent import AIAgent
+
+
+def _tool_call() -> SimpleNamespace:
+    return SimpleNamespace(
+        id="call_1",
+        type="function",
+        function=SimpleNamespace(name="web_search", arguments='{"query": "x"}'),
+    )
+
+
+def _tool_response(prompt_tokens: int) -> SimpleNamespace:
+    message = SimpleNamespace(
+        content=None,
+        reasoning_content=None,
+        reasoning=None,
+        tool_calls=[_tool_call()],
+    )
+    return SimpleNamespace(
+        choices=[SimpleNamespace(message=message, finish_reason="tool_calls")],
+        model="test/model",
+        usage=SimpleNamespace(
+            prompt_tokens=prompt_tokens,
+            completion_tokens=1,
+            total_tokens=prompt_tokens + 1,
+        ),
+    )
+
+
+def _final_response() -> SimpleNamespace:
+    message = SimpleNamespace(
+        content="done",
+        reasoning_content=None,
+        reasoning=None,
+        tool_calls=None,
+    )
+    return SimpleNamespace(
+        choices=[SimpleNamespace(message=message, finish_reason="stop")],
+        model="test/model",
+        usage=None,
+    )
+
+
+def _tool_definition() -> dict:
+    return {
+        "type": "function",
+        "function": {
+            "name": "web_search",
+            "description": "Search the web",
+            "parameters": {
+                "type": "object",
+                "properties": {"query": {"type": "string"}},
+                "required": ["query"],
+            },
+        },
+    }
+
+
+def _make_loop_agent():
+    with (
+        patch("model_tools.get_tool_definitions", return_value=[_tool_definition()]),
+        patch("model_tools.check_toolset_requirements", return_value={}),
+        patch("agent.process_bootstrap.OpenAI"),
+        patch("agent.model_metadata.get_model_context_length", return_value=256_000),
+        patch("agent.context_compressor.get_model_context_length", return_value=256_000),
+    ):
+        agent = AIAgent(
+            api_key="test-key-1234567890",
+            base_url="https://openrouter.ai/api/v1",
+            model="test/model",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            max_iterations=10,
+        )
+
+    agent.client = MagicMock()
+    agent._cached_system_prompt = "You are helpful."
+    agent._use_prompt_caching = False
+    agent._disable_streaming = True
+    agent.tool_delay = 0
+    agent.save_trajectories = False
+    agent.max_compression_attempts = 1
+
+    compressor = MagicMock()
+    compressor.protect_first_n = 3
+    compressor.protect_last_n = 20
+    compressor.threshold_tokens = 999_999_999  # never fire compaction here
+    compressor.context_length = 1_000_000_000
+    compressor.last_prompt_tokens = -1
+    compressor._verify_compaction_cleared_threshold = False
+    compressor.awaiting_real_usage_after_compression = False
+    compressor.should_compress.return_value = False
+    compressor.should_compress_info.return_value = (False, None)
+    compressor.should_compress_preflight.return_value = False
+    compressor.should_defer_preflight_to_real_usage.return_value = False
+    compressor.get_active_compression_failure_cooldown.return_value = None
+    compressor.select_context.return_value = None
+    compressor.get_automatic_compaction_status_message.return_value = ""
+    agent.compression_enabled = False  # isolate the budget behavior under test
+    agent.context_compressor = compressor
+
+    def _fake_execute_tool_calls(assistant_message, messages, *_args):
+        tool_call = assistant_message.tool_calls[0]
+        messages.append(
+            {
+                "role": "tool",
+                "name": tool_call.function.name,
+                "tool_call_id": tool_call.id,
+                "content": "ok",
+            }
+        )
+
+    agent._execute_tool_calls = _fake_execute_tool_calls
+    return agent
+
+
+def _run_with_responses(agent, responses):
+    agent.client.chat.completions.create.side_effect = responses
+    with (
+        patch.object(agent, "_flush_messages_to_session_db", return_value=True),
+        patch.object(agent, "_persist_session"),
+        patch.object(agent, "_save_trajectory"),
+        patch.object(agent, "_cleanup_task_resources"),
+    ):
+        result = agent.run_conversation("do some tool work")
+    return result
+
+
+def test_review_input_budget_stops_tool_loop_before_next_provider_call():
+    """Once a fork's cumulative input crosses its budget, no further provider
+    call is made — the crossing request completes, then the loop stops."""
+    agent = _make_loop_agent()
+    agent._review_input_token_budget = 100_000
+
+    responses = [
+        _tool_response(50_000),
+        _tool_response(50_000),  # cumulative 100_000 -> budget crossed
+        _tool_response(50_000),  # must never be consumed
+        _final_response(),
+    ]
+    result = _run_with_responses(agent, responses)
+
+    create = agent.client.chat.completions.create
+    assert create.call_count == 2, (
+        f"expected the loop to stop after crossing the input budget, "
+        f"but {create.call_count} provider calls were made (budget "
+        f"{agent._review_input_token_budget}, "
+        f"used {agent.session_input_tokens})"
+    )
+    assert agent.session_input_tokens == 100_000
+    assert result["completed"] is False
+
+
+def test_no_budget_attribute_leaves_tool_loop_unbounded():
+    """Agents without ``_review_input_token_budget`` (every normal agent)
+    are unaffected by the gate and consume all scripted responses."""
+    agent = _make_loop_agent()
+
+    responses = [
+        _tool_response(50_000),
+        _tool_response(50_000),
+        _tool_response(50_000),
+        _final_response(),
+    ]
+    result = _run_with_responses(agent, responses)
+
+    assert agent.client.chat.completions.create.call_count == 4
+    assert result["completed"] is True
+    assert result["final_response"] == "done"
+
+
+def test_review_input_budget_exhausted_predicate_edge_cases():
+    """The gate only arms for a positive int budget and a real token count."""
+    from agent.conversation_loop import _review_input_budget_exhausted
+
+    class _Agent:
+        pass
+
+    agent = _Agent()
+    assert _review_input_budget_exhausted(agent) is False
+
+    agent._review_input_token_budget = None
+    agent.session_input_tokens = 999_999
+    assert _review_input_budget_exhausted(agent) is False
+
+    agent._review_input_token_budget = 0
+    assert _review_input_budget_exhausted(agent) is False
+
+    agent._review_input_token_budget = -1
+    assert _review_input_budget_exhausted(agent) is False
+
+    agent._review_input_token_budget = "100"
+    assert _review_input_budget_exhausted(agent) is False
+
+    agent._review_input_token_budget = True
+    assert _review_input_budget_exhausted(agent) is False
+
+    agent._review_input_token_budget = 100_000
+    agent.session_input_tokens = 99_999
+    assert _review_input_budget_exhausted(agent) is False
+
+    agent.session_input_tokens = 100_000
+    assert _review_input_budget_exhausted(agent) is True
+
+
+@pytest.mark.parametrize(
+    ("config_value", "expected"),
+    [
+        ({}, 600_000),
+        ({"max_input_tokens": 1_000_000}, 1_000_000),
+        ({"max_input_tokens": 0}, None),
+        ({"max_input_tokens": -5}, None),
+        ({"max_input_tokens": "not-a-number"}, 600_000),
+        ({"max_input_tokens": "300000"}, 300_000),
+    ],
+)
+def test_review_input_token_budget_resolution(config_value, expected):
+    """Config parsing: default, override, explicit disable, garbage fallback."""
+    from agent.background_review import _review_input_token_budget
+
+    assert _review_input_token_budget(config_value) == expected

tests/agent/test_background_review_summary.py

@@ -0,0 +1,112 @@
+"""Tests for AIAgent._summarize_background_review_actions.
+
+Regression coverage for issue #14944: the background memory/skill review used
+to re-surface tool results that were already present in the conversation
+history before the review started (e.g. an earlier "Cron job '...' created.").
+"""
+
+import json
+
+from run_agent import AIAgent
+
+
+_summarize = AIAgent._summarize_background_review_actions
+
+
+def _tool_msg(tool_call_id, payload):
+    return {
+        "role": "tool",
+        "tool_call_id": tool_call_id,
+        "content": json.dumps(payload),
+    }
+
+
+def test_skips_prior_tool_messages_by_tool_call_id():
+    """Stale 'created' tool result from prior history must not be re-surfaced."""
+    prior_payload = {"success": True, "message": "Cron job 'remind-me' created."}
+    new_payload = {
+        "success": True,
+        "message": "Entry added",
+        "target": "user",
+    }
+
+    snapshot = [
+        {"role": "user", "content": "create a reminder"},
+        _tool_msg("call_old", prior_payload),
+        {"role": "assistant", "content": "done"},
+    ]
+    review_messages = list(snapshot) + [
+        {"role": "user", "content": "<review prompt>"},
+        _tool_msg("call_new", new_payload),
+    ]
+
+    actions = _summarize(review_messages, snapshot)
+
+    assert "Cron job 'remind-me' created." not in actions
+    assert "User profile updated" in actions
+
+
+def test_includes_genuinely_new_actions():
+    new_payload = {
+        "success": True,
+        "message": "Memory entry created.",
+    }
+    review_messages = [_tool_msg("call_new", new_payload)]
+
+    actions = _summarize(review_messages, prior_snapshot=[])
+
+    assert actions == ["Memory entry created."]
+
+
+def test_falls_back_to_content_equality_when_tool_call_id_missing():
+    """If a tool message has no tool_call_id, match prior entries by content."""
+    payload = {"success": True, "message": "Cron job 'X' created."}
+    raw = json.dumps(payload)
+    prior_msg = {"role": "tool", "content": raw}  # no tool_call_id
+    review_messages = [
+        {"role": "tool", "content": raw},  # same content -> stale, skip
+        _tool_msg("call_new", {"success": True, "message": "Skill created."}),
+    ]
+
+    actions = _summarize(review_messages, [prior_msg])
+
+    assert "Cron job 'X' created." not in actions
+    assert "Skill created." in actions
+
+
+
+
+def test_handles_non_json_tool_content_gracefully():
+    review_messages = [
+        {"role": "tool", "tool_call_id": "x", "content": "not-json"},
+        _tool_msg("call_y", {"success": True, "message": "Memory updated."}),
+    ]
+
+    actions = _summarize(review_messages, [])
+
+    assert actions == ["Memory updated."]
+
+
+def test_empty_inputs():
+    assert _summarize([], []) == []
+    assert _summarize(None, None) == []
+
+
+
+
+def test_removed_or_replaced_relabels_by_target():
+    review_messages = [
+        _tool_msg(
+            "c1",
+            {"success": True, "message": "Entry removed.", "target": "user"},
+        ),
+        _tool_msg(
+            "c2",
+            {"success": True, "message": "Entry replaced.", "target": "memory"},
+        ),
+    ]
+
+    actions = _summarize(review_messages, [])
+
+    assert "User profile updated" in actions
+    assert "Memory updated" in actions

tests/agent/test_background_review_tool_call_guard.py

@@ -0,0 +1,125 @@
+"""The background-review fork must not spawn when it could only no-op.
+
+The review fork's whole job is to emit ``memory`` / ``skill_manage`` tool calls,
+and by default it inherits the parent's live runtime. When the parent provider IS
+an autonomous agent reached through a client shim that cannot carry Hermes tool
+calls back, that fork is a guaranteed no-op — one that still pays for a full
+agent spawn (a whole CLI process, sometimes a JVM) on every review cadence.
+
+So: a client declaring ``SUPPORTS_HERMES_TOOL_CALLS = False`` skips the fork with
+a log line pointing at the ``auxiliary.background_review`` override. A client
+that can emit tool calls is unaffected, as are ordinary providers whose clients
+say nothing at all.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+
+import agent.background_review as bg  # noqa: E402
+
+
+def _fake_parent(client, *, runtime=None) -> SimpleNamespace:
+    """The minimal parent-agent surface _run_review_in_thread touches pre-fork."""
+    return SimpleNamespace(
+        provider="acp-agent",
+        model="acp-agent",
+        client=client,
+        session_id="s1",
+        platform="cli",
+        request_overrides={},
+        max_tokens=None,
+        acp_command="acp-agent",
+        acp_args=["--acp"],
+        enabled_toolsets=None,
+        disabled_toolsets=None,
+        reasoning_config=None,
+        _credential_pool=None,
+        _current_main_runtime=lambda: runtime or {
+            "api_key": "k",
+            "base_url": "acp://agent",
+            "api_mode": "chat_completions",
+        },
+        _emit_auxiliary_failure=lambda *_a, **_k: None,
+        _safe_print=lambda *_a, **_k: None,
+        background_review_callback=None,
+    )
+
+
+def _run(agent, task_cfg=None):
+    """Run the worker with AIAgent patched; return the AIAgent mock."""
+    with (
+        patch("hermes_cli.config.load_config", return_value={}),
+        patch("run_agent.AIAgent") as mock_aiagent,
+        patch("tools.terminal_tool.set_approval_callback"),
+    ):
+        bg._run_review_in_thread(
+            agent, [{"role": "user", "content": "hi"}], "review please", task_cfg
+        )
+    return mock_aiagent
+
+
+def test_fork_is_skipped_when_the_provider_cannot_emit_tool_calls(caplog):
+    client = MagicMock()
+    client.SUPPORTS_HERMES_TOOL_CALLS = False
+    with caplog.at_level(logging.WARNING, logger=bg.logger.name):
+        mock_aiagent = _run(_fake_parent(client))
+    mock_aiagent.assert_not_called()
+    # The user needs to know which knob makes the review work again.
+    assert "auxiliary.background_review" in caplog.text
+
+
+def test_fork_is_spawned_when_the_provider_can_emit_tool_calls():
+    client = MagicMock()
+    client.SUPPORTS_HERMES_TOOL_CALLS = True
+    assert _run(_fake_parent(client)).called
+
+
+def test_ordinary_providers_are_unaffected():
+    # A plain OpenAI-style client says nothing about the capability.
+    class _PlainClient:
+        pass
+
+    assert _run(_fake_parent(_PlainClient())).called
+
+
+def test_the_capability_is_read_off_the_class_too():
+    """Clients declare it as a class attribute; an instance need not set it."""
+
+    class _IncapableClient:
+        SUPPORTS_HERMES_TOOL_CALLS = False
+
+    assert bg._parent_can_emit_tool_calls(_fake_parent(_IncapableClient())) is False
+    assert bg._parent_can_emit_tool_calls(_fake_parent(None)) is True
+
+
+def test_an_incapable_provider_still_reviews_when_the_review_is_routed_away():
+    """``auxiliary.background_review.{provider,model}`` sends the fork to a normal
+    model, so the parent's shim no longer matters."""
+
+    class _IncapableClient:
+        SUPPORTS_HERMES_TOOL_CALLS = False
+
+    routed = {
+        "provider": "openai",
+        "model": "gpt-5",
+        "api_key": "k",
+        "base_url": None,
+        "api_mode": "chat_completions",
+        "credential_pool": None,
+        "request_overrides": {},
+        "max_tokens": None,
+        "command": None,
+        "args": [],
+        "routed": True,
+    }
+    with patch.object(bg, "_resolve_review_runtime", return_value=routed):
+        assert _run(_fake_parent(_IncapableClient())).called

tests/agent/test_bedrock_empty_text_blocks.py

@@ -0,0 +1,78 @@
+"""Regression tests for Bedrock Converse empty/whitespace text block rejection.
+
+Bedrock's Converse API raises::
+
+    ValidationException: The model returned the following errors: messages:
+    text content blocks must contain non-whitespace text
+
+for ANY text content block that is empty OR whitespace-only. Anthropic's native
+API tolerates these; Bedrock does not. Such blocks most often appear after
+context compression rewrites an assistant/tool turn into a blank string — once
+in history the block is re-sent on every call and fails deterministically
+(all retries fail identically). Ref: issue #9486.
+
+These tests assert convert_messages_to_converse never emits a blank text block
+(including inside toolResult content) and never uses a whitespace-only
+placeholder (a lone space would be rejected by the same validation).
+"""
+import pytest
+
+from agent.bedrock_adapter import (
+    convert_messages_to_converse,
+    _convert_content_to_converse,
+    _safe_text,
+    _EMPTY_TEXT_PLACEHOLDER,
+)
+
+
+def _iter_text_blocks(msgs):
+    """Yield every text string that will be sent to Bedrock, incl. toolResult."""
+    for m in msgs:
+        for b in m["content"]:
+            if "text" in b:
+                yield b["text"]
+            if "toolResult" in b:
+                for tb in b["toolResult"]["content"]:
+                    if "text" in tb:
+                        yield tb["text"]
+
+
+
+
+
+
+def test_safe_text_preserves_real_content():
+    assert _safe_text("hello") == "hello"
+    assert _safe_text("  padded  ") == "  padded  "  # inner content kept verbatim
+
+
+
+
+
+
+def test_real_content_is_preserved_alongside_blank_siblings():
+    messages = [
+        {"role": "user", "content": [
+            {"type": "text", "text": "  "},
+            {"type": "text", "text": "real question"},
+        ]},
+    ]
+    _system, msgs = convert_messages_to_converse(messages)
+    texts = list(_iter_text_blocks(msgs))
+    assert "real question" in texts
+    assert all(t.strip() for t in texts)
+
+
+def test_blank_system_blocks_dropped_not_blanked():
+    messages = [
+        {"role": "system", "content": [
+            {"type": "text", "text": "keep me"},
+            {"type": "text", "text": "   "},
+        ]},
+        {"role": "user", "content": "hi"},
+    ]
+    system, _msgs = convert_messages_to_converse(messages)
+    assert system is not None
+    for block in system:
+        assert block["text"].strip()
+    assert any(b["text"] == "keep me" for b in system)

tests/agent/test_billing_unverified_carrythrough.py

@@ -0,0 +1,171 @@
+"""#82154: an unverified billing verdict must carry its ambiguity through
+every downstream surface — the returned terminal response, the structured
+result fields, the credential-pool failure_reason, and the persisted entry —
+not just the explanatory guidance text.
+
+Anthropic returns the identical "out of extra usage" HTTP 400 body on a
+subscription OAuth token both for genuine overage depletion and for a
+server-side content-filter rejection of the request. The classifier marks
+that verdict ``billing_unverified``; these tests pin that the marking is not
+dropped on the way out.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from agent.conversation_loop import _billing_failure_result, _billing_terminal_label
+from agent.error_classifier import FailoverReason, classify_api_error
+
+
+class MockAPIError(Exception):
+    def __init__(self, message, status_code=None, body=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+_EXTRA_USAGE_BODY = (
+    "You're out of extra usage. Add more at claude.ai/settings/usage and keep going."
+)
+
+
+def _classified_unverified():
+    e = MockAPIError(
+        _EXTRA_USAGE_BODY,
+        status_code=400,
+        body={"error": {"type": "invalid_request_error", "message": _EXTRA_USAGE_BODY}},
+    )
+    return classify_api_error(e, provider="anthropic")
+
+
+def _classified_confirmed():
+    e = MockAPIError(
+        "Your credit balance is too low to access the Anthropic API.",
+        status_code=400,
+        body={"error": {
+            "type": "invalid_request_error",
+            "message": "Your credit balance is too low to access the Anthropic API.",
+        }},
+    )
+    return classify_api_error(e, provider="anthropic")
+
+
+# ── Returned terminal response ───────────────────────────────────────────────
+
+
+class TestTerminalResponse:
+    def test_unverified_terminal_response_does_not_assert_billing(self):
+        """The exact ambiguous 400 must not produce an unhedged
+        'Billing or credits exhausted' terminal response."""
+        result = _billing_failure_result(
+            classified=_classified_unverified(),
+            summary="HTTP 400: out of extra usage",
+            messages=[],
+            api_call_count=3,
+            provider="anthropic",
+            base_url="https://api.anthropic.com",
+            model="claude-opus-5",
+        )
+        final = result["final_response"]
+        assert not final.startswith("Billing or credits exhausted")
+        assert "unverified" in final
+        assert "content-filter" in final or "content filter" in final
+        # The guidance must ride along and hedge too.
+        assert "still shows quota remaining" in final
+
+    def test_unverified_terminal_response_structured_fields(self):
+        """The structured result carries the ambiguity, not just the prose."""
+        result = _billing_failure_result(
+            classified=_classified_unverified(),
+            summary="HTTP 400: out of extra usage",
+            messages=[],
+            api_call_count=3,
+            provider="anthropic",
+            base_url="https://api.anthropic.com",
+            model="claude-opus-5",
+        )
+        assert result["failed"] is True
+        assert result["failure_reason"] == "billing"
+        assert result["billing_unverified"] is True
+        block = result["billing_block"]
+        if block is not None:  # None only if billing_links is unavailable
+            assert block.get("unverified") is True
+
+    def test_confirmed_terminal_response_stays_assertive(self):
+        """A confirmed billing verdict keeps the original terminal label and
+        carries no ambiguity flag."""
+        result = _billing_failure_result(
+            classified=_classified_confirmed(),
+            summary="HTTP 400: credit balance too low",
+            messages=[],
+            api_call_count=1,
+            provider="anthropic",
+            base_url="https://api.anthropic.com",
+            model="claude-opus-5",
+        )
+        assert result["final_response"].startswith("Billing or credits exhausted")
+        assert result["billing_unverified"] is False
+        block = result["billing_block"]
+        if block is not None:
+            assert "unverified" not in block
+
+    def test_terminal_label_contract(self):
+        assert _billing_terminal_label("boom", False) == "Billing or credits exhausted: boom"
+        hedged = _billing_terminal_label("boom", True)
+        assert "unverified" in hedged
+        assert "content-filter" in hedged
+        assert not hedged.startswith("Billing or credits exhausted")
+
+
+# ── Credential-pool plumbing ─────────────────────────────────────────────────
+
+
+class TestPoolFailureReason:
+    def _run_recovery(self, *, billing_unverified: bool) -> dict:
+        """Drive recover_with_credential_pool with a billing classification and
+        capture what the pool is told."""
+        from agent.agent_runtime_helpers import recover_with_credential_pool
+
+        captured: dict = {}
+        next_entry = SimpleNamespace(label="secondary")
+
+        class _Pool:
+            provider = "anthropic"
+
+            def current(self):
+                return None
+
+            def entries(self):
+                return []
+
+            def mark_exhausted_and_rotate(self, **kwargs):
+                captured.update(kwargs)
+                return next_entry
+
+        agent = SimpleNamespace(
+            provider="anthropic",
+            base_url="https://api.anthropic.com",
+            api_key="sk-ant-oat01-test",
+            _credential_pool=_Pool(),
+            _credential_pool_entry_id=None,
+            _swap_credential=MagicMock(),
+        )
+        recovered, _ = recover_with_credential_pool(
+            agent,
+            status_code=400,
+            has_retried_429=False,
+            classified_reason=FailoverReason.billing,
+            billing_unverified=billing_unverified,
+        )
+        assert recovered is True
+        return captured
+
+    def test_unverified_billing_reaches_pool_as_unverified(self):
+        captured = self._run_recovery(billing_unverified=True)
+        assert captured["failure_reason"] == "billing_unverified"
+
+    def test_confirmed_billing_reaches_pool_as_billing(self):
+        captured = self._run_recovery(billing_unverified=False)
+        assert captured["failure_reason"] == "billing"

tests/agent/test_billing_view.py

@@ -0,0 +1,346 @@
+"""Unit tests for the Phase 2b Remote Spending core + HTTP client.
+
+Covers:
+- Decimal money parsing/formatting (server emits decimal strings, not 2dp).
+- BillingState payload parsing (role tiering, presets, bounds, sub-structs).
+- Error-code → typed-exception mapping (the live-verified contract matrix).
+- Fail-open builder behavior.
+- Idempotency key generation.
+- Custom-amount validation against bounds + multipleOf 0.01.
+
+No network: HTTP-layer tests drive _raise_for_error directly and monkeypatch the
+request function for the builder.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import pytest
+
+import agent.billing_view as bv
+from agent.billing_view import (
+    AutoReload,
+    AutoReloadCard,
+    BillingState,
+    CardInfo,
+    MonthlyCap,
+    PaymentMethodInfo,
+    billing_state_from_payload,
+    build_billing_state,
+    format_money,
+    new_idempotency_key,
+    parse_money,
+    validate_charge_amount,
+)
+import hermes_cli.nous_billing as nb
+from hermes_cli.nous_billing import (
+    BillingAuthError,
+    BillingError,
+    BillingRateLimited,
+    BillingScopeRequired,
+    BillingStripeUnavailable,
+    BillingTransient,
+    BillingUpgradeCapExceeded,
+    _raise_for_error,
+    resolve_portal_base_url,
+)
+
+
+# ---------------------------------------------------------------------------
+# Decimal money
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# BillingState payload parsing
+# ---------------------------------------------------------------------------
+
+
+def _member_payload() -> dict:
+    return {
+        "org": {"id": "o1", "slug": "acme", "name": "Acme", "role": "MEMBER"},
+        "balanceUsd": "142.5",
+        "cliBillingEnabled": True,
+        "chargePresets": ["100", "250", "500"],
+        "bounds": {"minUsd": "10", "maxUsd": "10000"},
+        "card": None,
+        "monthlyCap": None,
+        "autoReload": None,
+    }
+
+
+def _owner_payload() -> dict:
+    p = _member_payload()
+    p["org"]["role"] = "OWNER"
+    p["card"] = {"brand": "visa", "last4": "4242"}
+    p["monthlyCap"] = {
+        "limitUsd": "1000",
+        "spentThisMonthUsd": "180",
+        "isDefaultCeiling": True,
+    }
+    p["autoReload"] = {"enabled": True, "thresholdUsd": "20", "reloadToUsd": "100"}
+    return p
+
+
+def test_state_member_tier_parse():
+    s = billing_state_from_payload(_member_payload())
+    assert s.logged_in
+    assert s.role == "MEMBER"
+    assert s.balance_usd == Decimal("142.5")
+    assert s.cli_billing_enabled is True
+    assert s.charge_presets == (Decimal("100"), Decimal("250"), Decimal("500"))
+    assert s.min_usd == Decimal("10") and s.max_usd == Decimal("10000")
+    assert s.card is None and s.monthly_cap is None and s.auto_reload is None
+    assert s.is_admin is False
+    assert s.can_charge is False  # not admin
+
+
+@pytest.mark.parametrize(
+    "role,can_change_plan_raw,is_admin,can_change_plan",
+    [
+        ("OWNER", None, True, True),
+        ("ADMIN", None, True, True),
+        ("FINANCE_ADMIN", True, False, True),
+        ("SECURITY_ADMIN", None, False, False),
+        ("MEMBER", None, False, False),
+    ],
+)
+def test_state_five_roles(
+    role, can_change_plan_raw, is_admin, can_change_plan
+):
+    payload = _member_payload()
+    payload["org"]["role"] = role
+    if can_change_plan_raw is not None:
+        payload["canChangePlan"] = can_change_plan_raw
+
+    state = billing_state_from_payload(payload)
+
+    assert state.is_admin is is_admin
+    assert state.can_change_plan_raw is can_change_plan_raw
+    assert state.can_change_plan is can_change_plan
+    if role == "SECURITY_ADMIN":
+        assert state.card is None
+        assert state.monthly_cap is None
+        assert state.auto_reload is None
+
+
+
+
+
+
+
+
+def test_state_owner_tier_parse():
+    s = billing_state_from_payload(_owner_payload())
+    assert s.is_admin is True
+    assert s.can_charge is True  # admin + kill-switch on
+    assert s.card == CardInfo(brand="visa", last4="4242")
+    assert s.card is not None and s.card.masked == "visa ····4242"
+    assert s.monthly_cap == MonthlyCap(
+        limit_usd=Decimal("1000"),
+        spent_this_month_usd=Decimal("180"),
+        is_default_ceiling=True,
+    )
+    assert s.auto_reload == AutoReload(
+        enabled=True, threshold_usd=Decimal("20"), reload_to_usd=Decimal("100")
+    )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# Error-code → typed-exception mapping (live-verified contract)
+# ---------------------------------------------------------------------------
+
+
+class _Headers:
+    def __init__(self, d):
+        self._d = d
+
+    def get(self, k):
+        return self._d.get(k)
+
+
+def test_401_maps_to_auth_error():
+    with pytest.raises(BillingAuthError) as ei:
+        _raise_for_error(401, {"error": "invalid_token"})
+    assert ei.value.status == 401
+
+
+def test_403_insufficient_scope_maps_to_scope_required():
+    with pytest.raises(BillingScopeRequired) as ei:
+        _raise_for_error(403, {"error": "insufficient_scope", "portalUrl": "/billing"})
+    assert ei.value.error == "insufficient_scope"
+    # portalUrl is resolved to an absolute URL (relative-by-design from the server).
+    assert (ei.value.portal_url or "").startswith("http")
+    assert (ei.value.portal_url or "").endswith("/billing")
+
+
+
+
+@pytest.mark.parametrize(
+    "status,error,expected_type",
+    [
+        (503, "stripe_unavailable", BillingStripeUnavailable),
+        (429, "upgrade_cap_exceeded", BillingUpgradeCapExceeded),
+    ],
+)
+def test_specific_billing_throttle_errors_remain_distinguishable(
+    status, error, expected_type
+):
+    with pytest.raises(expected_type) as ei:
+        _raise_for_error(
+            status,
+            {"error": error},
+            _Headers({"Retry-After": "90"}),
+        )
+
+    assert ei.value.error == error
+    assert ei.value.retry_after == 90
+    assert isinstance(ei.value, BillingTransient)
+    assert not isinstance(ei.value, BillingRateLimited)
+
+
+
+
+
+
+def test_400_amount_out_of_bounds_is_base_error():
+    with pytest.raises(BillingError) as ei:
+        _raise_for_error(400, {"error": "amount_out_of_bounds", "message": "too big"})
+    assert ei.value.status == 400
+    assert "too big" in str(ei.value)
+
+
+# ---------------------------------------------------------------------------
+# post_charge requires idempotency key (client-side guard)
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# Base-URL resolution precedence
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+def test_portal_base_url_default(monkeypatch):
+    monkeypatch.delenv("HERMES_PORTAL_BASE_URL", raising=False)
+    monkeypatch.delenv("NOUS_PORTAL_BASE_URL", raising=False)
+    assert resolve_portal_base_url() == nb.DEFAULT_PORTAL_BASE_URL
+
+
+# ---------------------------------------------------------------------------
+# Fail-open builder
+# ---------------------------------------------------------------------------
+
+
+
+
+def test_build_billing_state_fail_open_on_http_error(monkeypatch):
+    def _boom(*a, **kw):
+        raise BillingError("portal exploded", status=500)
+
+    monkeypatch.setattr(nb, "get_billing_state", _boom)
+    s = build_billing_state()
+    assert s.logged_in is False
+    assert "portal exploded" in (s.error or "")
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# Idempotency
+# ---------------------------------------------------------------------------
+
+
+def test_new_idempotency_key_unique_and_uuid_shaped():
+    a, b = new_idempotency_key(), new_idempotency_key()
+    assert a != b
+    assert len(a) == 36 and a.count("-") == 4
+
+
+# ---------------------------------------------------------------------------
+# Amount validation (Screen 3 custom input)
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+@pytest.mark.parametrize(
+    "raw,err_substr",
+    [
+        ("", "dollar amount"),
+        ("0", "greater than"),
+        ("-5", "greater than"),
+        ("10.005", "cent"),       # multipleOf 0.01 — sub-cent rejected
+        ("5", "Minimum"),         # below bounds.minUsd
+        ("99999", "Maximum"),     # above bounds.maxUsd
+    ],
+)
+def test_validate_amount_rejections(raw, err_substr):
+    v = validate_charge_amount(raw, min_usd=Decimal("10"), max_usd=Decimal("10000"))
+    assert not v.ok
+    assert err_substr.lower() in (v.error or "").lower()
+
+
+# ---------------------------------------------------------------------------
+# HERMES_DEV_BILLING_FIXTURE — offline card/scope state scaffolding (T0)
+# ---------------------------------------------------------------------------
+
+
+
+
+@pytest.mark.parametrize(
+    "name,has_card,is_admin,billing_on",
+    [
+        ("nocard", False, True, True),
+        ("card", True, True, True),
+        ("card-autoreload", True, True, True),
+        ("notadmin", True, False, True),
+        ("billing-off", False, True, False),
+    ],
+)
+def test_billing_fixture_card_and_gate_invariants(monkeypatch, name, has_card, is_admin, billing_on):
+    """Each fixture state honors the card/admin/kill-switch contract the gate reads."""
+    monkeypatch.setenv("HERMES_DEV_BILLING_FIXTURE", name)
+    s = build_billing_state()
+    assert s.logged_in is True
+    assert (s.card is not None) is has_card
+    assert s.is_admin is is_admin
+    assert s.cli_billing_enabled is billing_on
+
+
+
+

tests/agent/test_bitwarden_secrets.py

@@ -0,0 +1,523 @@
+"""Hermetic tests for the Bitwarden Secrets Manager integration.
+
+We never hit GitHub or Bitwarden in tests — subprocess + urllib are
+mocked so the suite stays fast and offline-safe.  The "live" pull and
+binary download are exercised manually by `hermes secrets bitwarden
+setup` outside of pytest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import os
+import stat
+import subprocess
+import sys
+import time
+import zipfile
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+
+# Make the worktree importable without depending on the installed wheel.
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from agent.secret_sources import bitwarden as bw  # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def _reset_caches():
+    bw._reset_cache_for_tests()
+    yield
+    bw._reset_cache_for_tests()
+
+
+@pytest.fixture
+def hermes_home(tmp_path, monkeypatch):
+    """Point Hermes at an isolated home directory."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    # Some modules cache get_hermes_home; clear if needed.
+    import hermes_constants
+    if hasattr(hermes_constants, "_HERMES_HOME_CACHE"):
+        hermes_constants._HERMES_HOME_CACHE = None  # type: ignore[attr-defined]
+    return home
+
+
+# ---------------------------------------------------------------------------
+# _platform_asset_name
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "system,machine,libc_text,expected",
+    [
+        ("Darwin", "x86_64", "",
+         f"bws-macos-universal-{bw._BWS_VERSION}.zip"),
+        ("Darwin", "arm64", "",
+         f"bws-macos-universal-{bw._BWS_VERSION}.zip"),
+        ("Linux", "x86_64", "glibc",
+         f"bws-x86_64-unknown-linux-gnu-{bw._BWS_VERSION}.zip"),
+        ("Linux", "x86_64", "musl libc",
+         f"bws-x86_64-unknown-linux-musl-{bw._BWS_VERSION}.zip"),
+        ("Linux", "aarch64", "",
+         f"bws-aarch64-unknown-linux-gnu-{bw._BWS_VERSION}.zip"),
+        ("Windows", "AMD64", "",
+         f"bws-x86_64-pc-windows-msvc-{bw._BWS_VERSION}.zip"),
+        ("Windows", "ARM64", "",
+         f"bws-aarch64-pc-windows-msvc-{bw._BWS_VERSION}.zip"),
+    ],
+)
+def test_platform_asset_name(system, machine, libc_text, expected):
+    with mock.patch.object(bw.platform, "system", return_value=system), \
+         mock.patch.object(bw.platform, "machine", return_value=machine), \
+         mock.patch.object(
+             bw.subprocess,
+             "run",
+             return_value=mock.Mock(stdout=libc_text, stderr=libc_text),
+         ):
+        assert bw._platform_asset_name() == expected
+
+
+# ---------------------------------------------------------------------------
+# install_bws — fully mocked HTTP
+# ---------------------------------------------------------------------------
+
+
+def _make_fake_zip(binary_bytes: bytes) -> bytes:
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as zf:
+        zf.writestr("bws", binary_bytes)
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# _safe_extract_member — zip-slip containment
+# ---------------------------------------------------------------------------
+
+
+
+
+@pytest.mark.parametrize(
+    "evil_name",
+    [
+        "../escape",
+        "../../escape",
+        "sub/../../escape",
+    ],
+)
+def test_safe_extract_member_rejects_traversal(tmp_path, evil_name):
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as zf:
+        zf.writestr(evil_name, b"pwned")
+    buf.seek(0)
+
+    dest = tmp_path / "extract"
+    dest.mkdir()
+    outside = tmp_path / "escape"
+
+    with zipfile.ZipFile(buf) as zf:
+        with pytest.raises(RuntimeError, match="unsafe archive member"):
+            bw._safe_extract_member(zf, evil_name, dest)
+
+    # The traversal target must not have been written.
+    assert not outside.exists()
+
+
+
+
+
+
+def test_install_bws_happy_path(hermes_home, monkeypatch):
+    fake_binary = b"#!/bin/sh\necho 'bws fake 2.0.0'\n"
+    zip_bytes = _make_fake_zip(fake_binary)
+    asset_name = bw._platform_asset_name()
+    checksum_text = (
+        f"{hashlib.sha256(zip_bytes).hexdigest()}  {asset_name}\n"
+        "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff  other-file\n"
+    )
+
+    def fake_download(url, dest):
+        if url.endswith(".zip"):
+            Path(dest).write_bytes(zip_bytes)
+        elif url.endswith(".txt"):
+            Path(dest).write_text(checksum_text)
+        else:
+            raise AssertionError(f"unexpected download url: {url}")
+
+    monkeypatch.setattr(bw, "_http_download", fake_download)
+
+    path = bw.install_bws()
+    assert path.exists()
+    assert path.read_bytes() == fake_binary
+    # Executable bit set
+    assert path.stat().st_mode & stat.S_IXUSR
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# fetch_bitwarden_secrets
+# ---------------------------------------------------------------------------
+
+
+def _fake_bws_payload(items):
+    return json.dumps(items)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+def test_fetch_server_url_sets_env(monkeypatch, tmp_path):
+    """server_url must be plumbed into the subprocess as BWS_SERVER_URL."""
+    fake_binary = tmp_path / "bws"
+    fake_binary.write_text("")
+    payload = _fake_bws_payload([{"key": "K", "value": "v"}])
+
+    captured_env = {}
+
+    def fake_run(cmd, **kwargs):
+        captured_env.update(kwargs["env"])
+        return mock.Mock(returncode=0, stdout=payload, stderr="")
+
+    monkeypatch.setattr(bw.subprocess, "run", fake_run)
+
+    bw.fetch_bitwarden_secrets(
+        access_token="0.t",
+        project_id="p",
+        binary=fake_binary,
+        use_cache=False,
+        server_url="https://vault.bitwarden.eu",
+    )
+    assert captured_env.get("BWS_SERVER_URL") == "https://vault.bitwarden.eu"
+
+
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# apply_bitwarden_secrets — the public entry point used by env_loader
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# env_loader integration
+# ---------------------------------------------------------------------------
+
+
+
+
+def test_env_loader_calls_bsm_when_enabled(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        "secrets:\n"
+        "  bitwarden:\n"
+        "    enabled: true\n"
+        "    project_id: 'proj-1'\n"
+        "    access_token_env: 'BWS_ACCESS_TOKEN'\n"
+        "    cache_ttl_seconds: 0\n"
+        "    override_existing: false\n"
+        "    auto_install: false\n"
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    monkeypatch.setenv("BWS_ACCESS_TOKEN", "0.t")
+    monkeypatch.delenv("MY_BSM_KEY", raising=False)
+
+    called = {"n": 0}
+
+    def fake_fetch(**kwargs):
+        called["n"] += 1
+        assert kwargs["project_id"] == "proj-1"
+        return {"MY_BSM_KEY": "from-bsm"}, []
+
+    monkeypatch.setattr(
+        "agent.secret_sources.bitwarden.find_bws",
+        lambda **_kw: Path("/fake/bws"),
+    )
+    monkeypatch.setattr(
+        "agent.secret_sources.bitwarden.fetch_bitwarden_secrets",
+        fake_fetch,
+    )
+    from agent.secret_sources import registry as reg_module
+
+    reg_module._reset_registry_for_tests()
+
+    from hermes_cli.env_loader import _apply_external_secret_sources
+    _apply_external_secret_sources(home)
+
+    assert called["n"] == 1
+    assert os.environ.get("MY_BSM_KEY") == "from-bsm"
+
+
+# ---------------------------------------------------------------------------
+# Disk-persisted cache (cross-process — speeds up back-to-back CLI invocations)
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+
+
+def test_disk_cache_key_mismatch_triggers_refetch(monkeypatch, tmp_path):
+    """Disk cache entry written by a different token/project is ignored."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    fake_binary = tmp_path / "bws"
+    fake_binary.write_text("")
+    payload = _fake_bws_payload([{"key": "K1", "value": "v1"}])
+
+    call_count = {"n": 0}
+    def fake_run(*a, **kw):
+        call_count["n"] += 1
+        return mock.Mock(returncode=0, stdout=payload, stderr="")
+    monkeypatch.setattr(bw.subprocess, "run", fake_run)
+    bw._reset_cache_for_tests(home)
+
+    # Write a cache entry for a DIFFERENT token/project pair
+    cache_path = bw._disk_cache_path(home)
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    cache_path.write_text(json.dumps({
+        "key": "deadbeef00000000|other-project|",
+        "secrets": {"OTHER": "should-not-leak"},
+        "fetched_at": time.time(),
+    }))
+
+    secrets, _ = bw.fetch_bitwarden_secrets(
+        access_token="0.t", project_id="proj-1", binary=fake_binary,
+        cache_ttl_seconds=300, home_path=home,
+    )
+    # We must NOT have used the foreign cache entry
+    assert secrets == {"K1": "v1"}
+    assert "OTHER" not in secrets
+    assert call_count["n"] == 1
+
+
+
+
+
+
+def test_encrypted_cache_writes_without_plaintext(monkeypatch, tmp_path):
+    """Encrypted cache stores last-good secrets without raw values on disk."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    fake_binary = tmp_path / "bws"
+    fake_binary.write_text("")
+    payload = _fake_bws_payload([{"key": "K1", "value": "secret-value"}])
+
+    monkeypatch.setattr(
+        bw.subprocess,
+        "run",
+        lambda *a, **kw: mock.Mock(returncode=0, stdout=payload, stderr=""),
+    )
+    bw._reset_cache_for_tests(home)
+    # A successful encrypted write must remove a pre-existing legacy plaintext
+    # cache from the migration path.
+    legacy_key = (bw._token_fingerprint("0.t"), "proj-1", "")
+    bw._DISK_CACHE.write(
+        legacy_key,
+        bw._CachedFetch(secrets={"K1": "legacy"}, fetched_at=time.time()),
+        300,
+        home,
+    )
+    assert bw._disk_cache_path(home).exists()
+
+    secrets, warnings = bw.fetch_bitwarden_secrets(
+        access_token="0.t", project_id="proj-1", binary=fake_binary,
+        cache_ttl_seconds=0, encrypted_cache_enabled=True,
+        encrypted_cache_max_stale_seconds=604800, home_path=home,
+    )
+
+    assert secrets == {"K1": "secret-value"}
+    assert warnings == []
+    assert not bw._disk_cache_path(home).exists()
+    cache_path = bw._encrypted_disk_cache_path(home)
+    assert cache_path.exists()
+    mode = stat.S_IMODE(os.stat(cache_path).st_mode)
+    assert mode == 0o600, f"expected 0o600, got 0o{mode:o}"
+    text = cache_path.read_text()
+    assert "secret-value" not in text
+    assert "0.t" not in text
+    payload_disk = json.loads(text)
+    assert set(payload_disk.keys()) == {
+        "version", "key", "salt", "nonce", "ciphertext",
+    }
+    assert not bw._disk_cache_path(home).exists()
+
+
+
+
+def test_encrypted_cache_falls_back_on_network_error(monkeypatch, tmp_path):
+    """A fresh-enough encrypted cache is used when BWS is unreachable."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    fake_binary = tmp_path / "bws"
+    fake_binary.write_text("")
+    calls = {"n": 0}
+
+    def fake_run(*a, **kw):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return mock.Mock(
+                returncode=0,
+                stdout=_fake_bws_payload([{"key": "K1", "value": "cached"}]),
+                stderr="",
+            )
+        return mock.Mock(
+            returncode=1,
+            stdout="",
+            stderr="Error: network is unreachable",
+        )
+
+    monkeypatch.setattr(bw.subprocess, "run", fake_run)
+    bw._reset_cache_for_tests(home)
+
+    first, _ = bw.fetch_bitwarden_secrets(
+        access_token="0.t", project_id="proj-1", binary=fake_binary,
+        cache_ttl_seconds=0, encrypted_cache_enabled=True,
+        encrypted_cache_max_stale_seconds=604800, home_path=home,
+    )
+    assert first == {"K1": "cached"}
+    bw._CACHE.clear()
+
+    second, warnings = bw.fetch_bitwarden_secrets(
+        access_token="0.t", project_id="proj-1", binary=fake_binary,
+        cache_ttl_seconds=0, encrypted_cache_enabled=True,
+        encrypted_cache_max_stale_seconds=604800, home_path=home,
+    )
+    assert second == {"K1": "cached"}
+    assert calls["n"] == 2
+    assert len(warnings) == 1
+    assert "stale ENCRYPTED disk cache" in warnings[0]
+    assert "bws live fetch failed" in warnings[0]
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# Stale disk cache fallback when live bws fetch fails
+# ---------------------------------------------------------------------------
+
+
+def _seed_stale_disk_cache(home, *, secrets, age_seconds, project_id="proj-1",
+                           access_token="0.t", server_url=""):
+    """Populate the disk cache as if a successful fetch happened `age_seconds`
+    ago. Writes the JSON payload directly (same shape the shared DiskCache
+    reads/writes) rather than going through DiskCache.write, since that
+    would honor cache_ttl_seconds and refuse to persist an already-"stale"
+    entry — this needs to land on disk regardless of TTL."""
+    cache_key = (
+        bw._token_fingerprint(access_token), project_id, server_url,
+    )
+    cache_path = bw._disk_cache_path(home)
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    cache_path.write_text(json.dumps({
+        "key": bw._cache_key_str(cache_key),
+        "secrets": secrets,
+        "fetched_at": time.time() - age_seconds,
+    }))
+
+
+def test_stale_disk_cache_returned_when_bws_fails(monkeypatch, tmp_path):
+    """When bws fails and the disk cache is stale, return the stale secrets
+    with a warning rather than raising."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    fake_binary = tmp_path / "bws"
+    fake_binary.write_text("")
+    bw._reset_cache_for_tests(home)
+
+    # Seed a stale (older than TTL) disk cache from a previous successful fetch
+    _seed_stale_disk_cache(home, secrets={"OPENAI_API_KEY": "sk-old"},
+                           age_seconds=3600)
+
+    # Now simulate a BWS network failure
+    def fail_run(*a, **kw):
+        return mock.Mock(returncode=1, stdout="",
+                         stderr="Error: dns resolution failed")
+    monkeypatch.setattr(bw.subprocess, "run", fail_run)
+
+    secrets, warnings = bw.fetch_bitwarden_secrets(
+        access_token="0.t", project_id="proj-1", binary=fake_binary,
+        cache_ttl_seconds=300, home_path=home,
+    )
+    assert secrets == {"OPENAI_API_KEY": "sk-old"}
+    assert len(warnings) == 1
+    assert "stale disk cache" in warnings[0]
+    assert "dns resolution failed" in warnings[0]
+
+
+
+
+
+
+
+
+
+
+def test_stale_fallback_skipped_on_auth_failure(monkeypatch, tmp_path):
+    """An AUTH_FAILED bws error must raise, not serve stale secrets — a bad
+    access token indicates a real credential problem the caller needs to
+    see, not a transient outage worth papering over."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    fake_binary = tmp_path / "bws"
+    fake_binary.write_text("")
+    bw._reset_cache_for_tests(home)
+
+    _seed_stale_disk_cache(home, secrets={"K1": "v1"}, age_seconds=3600)
+
+    monkeypatch.setattr(
+        bw.subprocess, "run",
+        lambda *a, **kw: mock.Mock(returncode=1, stdout="",
+                                   stderr="Error: unauthorized (401)"),
+    )
+
+    with pytest.raises(RuntimeError, match="unauthorized"):
+        bw.fetch_bitwarden_secrets(
+            access_token="0.t", project_id="proj-1", binary=fake_binary,
+            cache_ttl_seconds=300, home_path=home,
+        )
+
+
+
+

tests/agent/test_bounded_response.py

@@ -0,0 +1,113 @@
+"""Tests for bounded reads of streaming HTTP error response bodies.
+
+Exercises the real ``httpx`` streaming path against an in-process socket server
+(no mocks) so the byte-cap and hard-deadline contracts are validated end to end,
+the way they behave against a real misbehaving provider.
+
+Covers the bug class ported from openclaw/openclaw#95108: an unbounded
+``response.read()`` on a non-OK streaming response can balloon memory (huge
+body) or hang forever (body opens then stalls).
+"""
+
+from __future__ import annotations
+
+import http.server
+import json
+import socketserver
+import threading
+import time
+
+import httpx
+import pytest
+
+from agent.bounded_response import read_streaming_error_body
+
+
+class _ThreadingServer(socketserver.ThreadingTCPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+
+def _make_handler():
+    class _Handler(http.server.BaseHTTPRequestHandler):
+        def log_message(self, format, *args):  # noqa: A002 - http.server API
+            pass
+
+        def do_POST(self):  # noqa: N802 - http.server API
+            if self.path == "/oversize":
+                # ~128 MiB if read unbounded; no Content-Length.
+                self.send_response(500)
+                self.send_header("Content-Type", "text/plain")
+                self.end_headers()
+                try:
+                    for _ in range(2000):
+                        self.wfile.write(b"x" * 65536)
+                        self.wfile.flush()
+                except Exception:
+                    pass
+            elif self.path == "/stall":
+                # Send a little, then stall forever (no further bytes).
+                self.send_response(500)
+                self.send_header("Content-Type", "text/plain")
+                self.end_headers()
+                self.wfile.write(b"partial failure detail")
+                self.wfile.flush()
+                time.sleep(60)
+            elif self.path == "/normal":
+                body = json.dumps(
+                    {
+                        "error": {
+                            "code": 429,
+                            "message": "quota exceeded",
+                            "status": "RESOURCE_EXHAUSTED",
+                        }
+                    }
+                ).encode()
+                self.send_response(429)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+            elif self.path == "/empty":
+                self.send_response(500)
+                self.send_header("Content-Length", "0")
+                self.end_headers()
+
+    return _Handler
+
+
+@pytest.fixture()
+def server_base():
+    httpd = _ThreadingServer(("127.0.0.1", 0), _make_handler())
+    port = httpd.server_address[1]
+    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{port}"
+    finally:
+        httpd.shutdown()
+
+
+@pytest.fixture()
+def client():
+    # Generous read timeout so the bounding is provably done by our helper,
+    # not by httpx's own timeout.
+    c = httpx.Client(
+        timeout=httpx.Timeout(connect=5.0, read=45.0, write=5.0, pool=5.0)
+    )
+    try:
+        yield c
+    finally:
+        c.close()
+
+
+def test_oversize_body_is_capped(server_base, client):
+    start = time.monotonic()
+    with client.stream("POST", server_base + "/oversize") as response:
+        text = read_streaming_error_body(
+            response, max_bytes=64 * 1024, timeout_s=10.0
+        )
+    elapsed = time.monotonic() - start
+    assert 0 < len(text) <= 64 * 1024
+    # Capping must return promptly, not after draining the whole body.
+    assert elapsed < 9.0

tests/agent/test_budget_reasoning_details_exclusion.py

@@ -0,0 +1,125 @@
+"""Regression tests for #73298 (second site): the tail-budget walk must not
+charge the signed/base64 ``reasoning_details`` envelope at chars/4.
+
+The preflight estimator (``model_metadata._estimate_message_tokens_without_images``)
+excludes ``reasoning_details`` entirely; ``_estimate_msg_budget_tokens`` in the
+compressor mirrors that for the envelope while — per the #51800 counter-argument —
+still counting actual thinking TEXT when it is not already carried by
+``reasoning``/``reasoning_content``.
+"""
+
+from agent.context_compressor import (
+    _estimate_msg_budget_tokens,
+    _reasoning_details_text_chars,
+)
+
+
+def _signed_thinking_block(thinking_chars: int, sig_chars: int) -> dict:
+    return {
+        "type": "thinking",
+        "thinking": "t" * thinking_chars,
+        "signature": "s" * sig_chars,
+    }
+
+
+class TestBudgetExcludesReasoningDetailsEnvelope:
+    def test_signature_blob_not_charged(self):
+        base = {"role": "assistant", "content": "hello there"}
+        with_envelope = dict(
+            base,
+            reasoning_details=[_signed_thinking_block(0, 40_000)],
+        )
+        plain = _estimate_msg_budget_tokens(base)
+        loaded = _estimate_msg_budget_tokens(with_envelope)
+        # 40K chars of base64 signature would add ~10K phantom tokens at
+        # chars/4. The envelope must be invisible to the budget.
+        assert loaded - plain < 50, (
+            f"signed envelope inflated the budget by {loaded - plain} tokens"
+        )
+
+    def test_thinking_text_still_counted(self):
+        """#51800: real reasoning text must stay visible to the budget when
+        it is not duplicated into reasoning/reasoning_content."""
+        base = {"role": "assistant", "content": "hello there"}
+        with_text = dict(
+            base,
+            reasoning_details=[_signed_thinking_block(8_000, 0)],
+        )
+        plain = _estimate_msg_budget_tokens(base)
+        loaded = _estimate_msg_budget_tokens(with_text)
+        # 8K chars of thinking ≈ 2K tokens at chars/4.
+        assert loaded - plain > 1_000, (
+            "thinking TEXT inside reasoning_details was dropped from the "
+            f"budget (delta {loaded - plain}); only the envelope may be excluded"
+        )
+
+    def test_duplicated_thinking_text_not_double_charged(self):
+        """Anthropic-wire sessions carry the prose byte-identical in both
+        reasoning_content and reasoning_details; charge it once."""
+        prose = "deep thought " * 1_000
+        msg = {
+            "role": "assistant",
+            "content": "hi",
+            "reasoning_content": prose,
+            "reasoning_details": [
+                {"type": "thinking", "thinking": prose, "signature": "s" * 5_000},
+            ],
+        }
+        once = _estimate_msg_budget_tokens(
+            {"role": "assistant", "content": "hi", "reasoning_content": prose}
+        )
+        both = _estimate_msg_budget_tokens(msg)
+        assert both - once < 100, (
+            f"thinking prose charged twice (delta {both - once} tokens)"
+        )
+
+    def test_codex_encrypted_content_is_opaque_to_local_estimates(self):
+        """Ciphertext is priced by the provider's own count, never by its bytes (a native
+        compaction checkpoint alone is ~5M chars, #100611): the budget walk and the trigger
+        estimator both charge it ~0, so only real usage ever prices it (#104462)."""
+        from agent.model_metadata import estimate_messages_tokens_rough
+
+        base = {"role": "assistant", "content": "hi"}
+        loaded = dict(base, codex_reasoning_items=[{"type": "reasoning", "encrypted_content": "e" * 20_000}])
+        assert _estimate_msg_budget_tokens(loaded) - _estimate_msg_budget_tokens(base) < 50
+        assert estimate_messages_tokens_rough([loaded]) - estimate_messages_tokens_rough([base]) < 50
+
+
+class TestReasoningDetailsTextChars:
+    def test_none_and_empty(self):
+        assert _reasoning_details_text_chars(None) == 0
+        assert _reasoning_details_text_chars([]) == 0
+        assert _reasoning_details_text_chars("") == 0
+
+    def test_string_counts_fully(self):
+        assert _reasoning_details_text_chars("abcd" * 10) == 40
+
+    def test_envelope_keys_skipped(self):
+        blocks = [
+            {"type": "thinking", "thinking": "abc", "signature": "S" * 999},
+            {"type": "redacted_thinking", "data": "D" * 999},
+            {"type": "text", "text": "xy"},
+        ]
+        assert _reasoning_details_text_chars(blocks) == 5
+
+
+class TestPreflightExcludesReasoningDetails:
+    """Regression coverage for the preflight half (#73306 shipped without a
+    test): _estimate_message_tokens_without_images must not count the
+    reasoning_details envelope."""
+
+    def test_preflight_estimate_ignores_reasoning_details(self):
+        from agent.model_metadata import _estimate_message_tokens_without_images
+
+        base = {"role": "assistant", "content": "hello there"}
+        loaded = dict(
+            base,
+            reasoning_details=[_signed_thinking_block(10_000, 40_000)],
+        )
+        plain = _estimate_message_tokens_without_images(base)
+        with_details = _estimate_message_tokens_without_images(loaded)
+        assert with_details - plain < 50, (
+            "preflight estimator counted the reasoning_details payload "
+            f"(delta {with_details - plain} tokens) — compression would fire "
+            "at a fraction of real usage on thinking models (#73298)"
+        )

tests/agent/test_builtin_memory_disabled_surface.py

@@ -0,0 +1,315 @@
+"""Built-in memory disabled in config must leave no dead surface behind.
+
+Setting ``memory.memory_enabled: false`` and ``memory.user_profile_enabled:
+false`` stops ``agent_init`` from building a ``MemoryStore``, so the ``memory``
+tool dispatches against ``store=None`` and every call comes back "Memory is not
+available". Before the fix the tool stayed in the schema and MEMORY_GUIDANCE
+stayed in the system prompt, so users running a third-party provider (Hindsight,
+Mem0, …) paid for both on every API call with no way to drop them — listing
+``memory`` under ``disabled_toolsets`` takes the provider's tools down too.
+
+These tests exercise the real resolution chain (config on disk → check_fn →
+``get_tool_definitions``) against a temp ``HERMES_HOME``, not mocks.
+"""
+
+import json
+from unittest.mock import patch
+
+import pytest
+import yaml
+
+from model_tools import get_tool_definitions
+
+
+@pytest.fixture(autouse=True)
+def _clear_caches():
+    """check_fn results and tool definitions are both cached; config written by
+    a test only takes effect once those are dropped."""
+    from model_tools import _clear_tool_defs_cache
+    from tools.registry import invalidate_check_fn_cache
+
+    invalidate_check_fn_cache()
+    _clear_tool_defs_cache()
+    yield
+    invalidate_check_fn_cache()
+    _clear_tool_defs_cache()
+
+
+def _write_memory_config(home, **memory_section):
+    home.mkdir(parents=True, exist_ok=True)
+    (home / "config.yaml").write_text(
+        yaml.safe_dump({"memory": memory_section}), encoding="utf-8"
+    )
+
+
+@pytest.fixture
+def hermes_home(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    return home
+
+
+def _memory_tool_definition():
+    return next(
+        tool["function"]
+        for tool in get_tool_definitions(enabled_toolsets=["memory"], quiet_mode=True)
+        if tool["function"]["name"] == "memory"
+    )
+
+
+def _memory_tool_names():
+    tools = get_tool_definitions(enabled_toolsets=["memory"], quiet_mode=True)
+    return {tool["function"]["name"] for tool in tools}
+
+
+class TestBuiltinMemoryToolAvailability:
+    def test_tool_hidden_when_both_stores_disabled(self, hermes_home):
+        _write_memory_config(
+            hermes_home, memory_enabled=False, user_profile_enabled=False
+        )
+        assert "memory" not in _memory_tool_names()
+
+    def test_tool_present_when_only_user_profile_enabled(self, hermes_home):
+        _write_memory_config(
+            hermes_home, memory_enabled=False, user_profile_enabled=True
+        )
+        definition = _memory_tool_definition()
+        assert definition["parameters"]["properties"]["target"]["enum"] == ["user"]
+        assert "only 'user' is enabled" in definition["description"]
+        assert "only 'memory' is enabled" not in definition["description"]
+
+    def test_tool_present_when_only_memory_enabled(self, hermes_home):
+        _write_memory_config(
+            hermes_home, memory_enabled=True, user_profile_enabled=False
+        )
+        definition = _memory_tool_definition()
+        assert definition["parameters"]["properties"]["target"]["enum"] == ["memory"]
+        assert "only 'memory' is enabled" in definition["description"]
+        assert "only 'user' is enabled" not in definition["description"]
+
+    def test_tool_present_by_default(self, hermes_home):
+        """No config file at all must not strip a working tool."""
+        assert "memory" in _memory_tool_names()
+
+    def test_missing_memory_flags_fail_open_consistently(self):
+        from tools.memory_tool import get_builtin_memory_store_flags
+
+        assert get_builtin_memory_store_flags({"memory": {}}) == (True, True)
+        assert get_builtin_memory_store_flags({}) == (True, True)
+
+    def test_quoted_false_flags_are_disabled(self):
+        from tools.memory_tool import get_builtin_memory_store_flags
+
+        assert get_builtin_memory_store_flags(
+            {"memory": {"memory_enabled": "false", "user_profile_enabled": "false"}}
+        ) == (False, False)
+
+    def test_schema_reuses_availability_flag_snapshot(self, monkeypatch):
+        """One definition pass must not reread config between check and schema."""
+        from tools import memory_tool as memory_tool_module
+
+        calls = 0
+
+        def _flags():
+            nonlocal calls
+            calls += 1
+            return (False, True) if calls == 1 else (True, False)
+
+        monkeypatch.setattr(memory_tool_module, "get_builtin_memory_store_flags", _flags)
+        definition = _memory_tool_definition()
+
+        assert calls == 1
+        assert definition["parameters"]["properties"]["target"]["enum"] == ["user"]
+
+    def test_unavailable_snapshot_cannot_survive_failed_recheck(self, monkeypatch):
+        from tools import memory_tool as memory_tool_module
+
+        monkeypatch.setattr(
+            memory_tool_module,
+            "get_builtin_memory_store_flags",
+            lambda: (False, False),
+        )
+        assert memory_tool_module.check_memory_requirements() is False
+
+        def _boom():
+            raise RuntimeError("config read failed")
+
+        monkeypatch.setattr(memory_tool_module, "get_builtin_memory_store_flags", _boom)
+        with pytest.raises(RuntimeError, match="config read failed"):
+            memory_tool_module.check_memory_requirements()
+
+        assert memory_tool_module._memory_surface_flags.get() is None
+
+    def test_config_flip_updates_tool_without_manual_cache_clear(self, hermes_home):
+        _write_memory_config(
+            hermes_home, memory_enabled=False, user_profile_enabled=False
+        )
+        assert "memory" not in _memory_tool_names()
+
+        _write_memory_config(
+            hermes_home, memory_enabled=True, user_profile_enabled=False
+        )
+        assert "memory" in _memory_tool_names()
+
+    def test_unreadable_config_fails_open(self, hermes_home, monkeypatch):
+        """A config read error must not silently remove the tool."""
+        from tools import memory_tool as memory_tool_module
+
+        def _boom():
+            raise RuntimeError("config unreadable")
+
+        monkeypatch.setattr(
+            "hermes_cli.config.load_config_readonly", _boom, raising=False
+        )
+        assert memory_tool_module.check_memory_requirements() is True
+
+    def test_malformed_memory_section_normalizes_to_defaults(self):
+        from tools.memory_tool import (
+            get_builtin_memory_config,
+            get_builtin_memory_store_flags,
+        )
+
+        config = {"memory": "not-a-mapping"}
+        assert get_builtin_memory_config(config) == {}
+        assert get_builtin_memory_store_flags(config) == (True, True)
+
+
+class TestIndependentStoreWriteGates:
+    def _store(self, *, memory_enabled, user_profile_enabled):
+        from tools.memory_tool import MemoryStore
+
+        store = MemoryStore(
+            memory_char_limit=500,
+            user_char_limit=500,
+            memory_enabled=memory_enabled,
+            user_profile_enabled=user_profile_enabled,
+        )
+        store.load_from_disk()
+        return store
+
+    def test_user_profile_only_rejects_memory_write(self, hermes_home):
+        from tools.memory_tool import memory_tool
+
+        store = self._store(memory_enabled=False, user_profile_enabled=True)
+        denied = json.loads(memory_tool(action="add", target="memory", content="fact", store=store))
+        allowed = json.loads(memory_tool(action="add", target="user", content="pref", store=store))
+
+        assert denied["success"] is False
+        assert denied["target"] == "memory"
+        assert allowed["success"] is True
+
+    def test_memory_only_rejects_user_profile_write(self, hermes_home):
+        from tools.memory_tool import memory_tool
+
+        store = self._store(memory_enabled=True, user_profile_enabled=False)
+        denied = json.loads(memory_tool(action="add", target="user", content="pref", store=store))
+        allowed = json.loads(memory_tool(action="add", target="memory", content="fact", store=store))
+
+        assert denied["success"] is False
+        assert denied["target"] == "user"
+        assert allowed["success"] is True
+
+    def test_staged_write_cannot_bypass_target_gate(self, hermes_home):
+        from tools.memory_tool import apply_memory_pending
+
+        store = self._store(memory_enabled=False, user_profile_enabled=True)
+        result = apply_memory_pending(
+            {"action": "add", "target": "memory", "content": "fact"}, store
+        )
+
+        assert result["success"] is False
+        assert result["target"] == "memory"
+
+    def test_invalid_target_error_is_bounded_and_carries_recovery_hint(self, hermes_home):
+        """Model-supplied target is interpolated into the error: it must stay
+        capped at the shared tool_error bound and keep the recovery hint."""
+        from tools.memory_tool import memory_tool
+        from tools.registry import _MAX_TOOL_ERROR_CHARS
+
+        store = self._store(memory_enabled=True, user_profile_enabled=True)
+        result = json.loads(
+            memory_tool(action="add", target="x" * 10_000, content="fact", store=store)
+        )
+
+        assert result["success"] is False
+        assert len(result["error"]) <= _MAX_TOOL_ERROR_CHARS + 32
+
+        short = json.loads(
+            memory_tool(action="add", target="bogus", content="fact", store=store)
+        )
+        assert short["success"] is False
+        assert "Use 'memory' or 'user'" in short["error"]
+
+
+class TestExternalProviderSurvivesBuiltinDisable:
+    """Dropping the built-in tool must not drop the external provider's tools.
+
+    ``memory_provider_tools_enabled`` short-circuits on the built-in tool being
+    present, so hiding that tool moves the decision onto the toolset gate. The
+    provider must still be reachable for every way a caller can ask for memory.
+    """
+
+    def test_provider_tools_enabled_when_memory_toolset_requested(self):
+        from agent.memory_manager import memory_provider_tools_enabled
+
+        assert memory_provider_tools_enabled(
+            ["memory", "file"], None, memory_tool_present=False
+        )
+
+    def test_provider_tools_enabled_for_unrestricted_toolsets(self):
+        from agent.memory_manager import memory_provider_tools_enabled
+
+        assert memory_provider_tools_enabled(None, None, memory_tool_present=False)
+
+    def test_disabled_toolsets_still_takes_everything_down(self):
+        """The heavy switch keeps its documented meaning."""
+        from agent.memory_manager import memory_provider_tools_enabled
+
+        assert not memory_provider_tools_enabled(
+            None, ["memory"], memory_tool_present=False
+        )
+
+
+class TestInjectionEndToEnd:
+    """The real ``inject_memory_provider_tools`` with no built-in memory tool."""
+
+    def test_provider_tools_injected_without_builtin_memory_tool(self):
+        from types import SimpleNamespace
+
+        from agent.memory_manager import MemoryManager, inject_memory_provider_tools
+        from agent.memory_provider import MemoryProvider
+
+        class _Provider(MemoryProvider):
+            @property
+            def name(self):
+                return "fake_hindsight"
+
+            def is_available(self):
+                return True
+
+            def initialize(self, session_id, **kwargs):
+                pass
+
+            def get_tool_schemas(self):
+                return [
+                    {
+                        "name": "hindsight_retain",
+                        "description": "retain",
+                        "parameters": {"type": "object", "properties": {}},
+                    }
+                ]
+
+        manager = MemoryManager()
+        manager.add_provider(_Provider())
+        agent = SimpleNamespace(
+            _memory_manager=manager,
+            enabled_toolsets=["memory"],
+            disabled_toolsets=None,
+            tools=[],
+            valid_tool_names=set(),
+        )
+
+        added = inject_memory_provider_tools(agent)
+
+        assert added == 1
+        assert "hindsight_retain" in agent.valid_tool_names

tests/agent/test_cache_disabled_on_stubs.py

@@ -0,0 +1,382 @@
+"""Regression for #76085: prompt_caching.cache_ttl off on stub policy paths.
+
+Blank SimpleNamespace stubs used by MoA decoration and auxiliary/MoA
+plan_cache_sections_for_destination never carried ``_cache_disabled``, so
+``anthropic_prompt_cache_policy`` re-enabled cache_control markers even when
+the operator set ``prompt_caching.cache_ttl: false``.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+
+def _has_cache_control(obj) -> bool:
+    if isinstance(obj, dict):
+        if "cache_control" in obj:
+            return True
+        return any(_has_cache_control(v) for v in obj.values())
+    if isinstance(obj, list):
+        return any(_has_cache_control(v) for v in obj)
+    return False
+
+
+class TestPromptCachingDisabledFromConfig:
+    def test_off_values(self):
+        from agent.agent_runtime_helpers import prompt_caching_disabled_from_config
+
+        for ttl in (False, None, "off", "false", "disabled", "no", "none", "OFF"):
+            with patch(
+                "hermes_cli.config.load_config_readonly",
+                return_value={"prompt_caching": {"cache_ttl": ttl}},
+            ):
+                assert prompt_caching_disabled_from_config() is True, ttl
+
+    def test_enabled_values(self):
+        from agent.agent_runtime_helpers import prompt_caching_disabled_from_config
+
+        for ttl in ("5m", "1h"):
+            with patch(
+                "hermes_cli.config.load_config_readonly",
+                return_value={"prompt_caching": {"cache_ttl": ttl}},
+            ):
+                assert prompt_caching_disabled_from_config() is False, ttl
+
+    def test_shared_predicate_matches_agent_init_semantics(self):
+        """agent_init and the stub paths must share one disable predicate.
+
+        Unknown values keep caching enabled (default TTL), exactly like the
+        historical inline detection in agent_init (#76085 drift guard).
+        """
+        from agent.agent_runtime_helpers import cache_ttl_means_disabled
+
+        for ttl in (False, None, "off", "false", "disabled", "no", "none", "OFF"):
+            assert cache_ttl_means_disabled(ttl) is True, ttl
+        for ttl in ("5m", "1h", "2h", 5, True, "weird"):
+            assert cache_ttl_means_disabled(ttl) is False, ttl
+
+
+class TestPlanCacheSectionsHonorsDisable:
+    def test_explicit_cache_disabled_strips_markers(self):
+        from agent.agent_runtime_helpers import plan_cache_sections_for_destination
+
+        messages = [
+            {"role": "system", "content": "You are helpful."},
+            {"role": "user", "content": "hello"},
+        ]
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "web_search",
+                    "description": "search",
+                    "parameters": {"type": "object", "properties": {}},
+                },
+            }
+        ]
+        out_msgs, out_tools = plan_cache_sections_for_destination(
+            messages,
+            tools,
+            provider="anthropic",
+            base_url="https://api.anthropic.com",
+            api_mode="anthropic_messages",
+            model="claude-opus-4.8",
+            cache_disabled=True,
+        )
+        assert not _has_cache_control(out_msgs)
+        assert not _has_cache_control(out_tools)
+
+    def test_config_off_without_explicit_flag(self):
+        from agent.agent_runtime_helpers import plan_cache_sections_for_destination
+
+        messages = [
+            {"role": "system", "content": "You are helpful."},
+            {"role": "user", "content": "hello"},
+        ]
+        with patch(
+            "hermes_cli.config.load_config_readonly",
+            return_value={"prompt_caching": {"cache_ttl": "off"}},
+        ):
+            out_msgs, out_tools = plan_cache_sections_for_destination(
+                messages,
+                None,
+                provider="anthropic",
+                base_url="https://api.anthropic.com",
+                api_mode="anthropic_messages",
+                model="claude-opus-4.8",
+            )
+        assert not _has_cache_control(out_msgs)
+        assert out_tools is None or not _has_cache_control(out_tools)
+
+    def test_enabled_still_adds_markers_on_native_anthropic(self):
+        from agent.agent_runtime_helpers import plan_cache_sections_for_destination
+
+        messages = [
+            {"role": "system", "content": "You are helpful."},
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi"},
+            {"role": "user", "content": "again"},
+        ]
+        with patch(
+            "hermes_cli.config.load_config_readonly",
+            return_value={"prompt_caching": {"cache_ttl": "5m"}},
+        ):
+            out_msgs, _ = plan_cache_sections_for_destination(
+                messages,
+                None,
+                provider="anthropic",
+                base_url="https://api.anthropic.com",
+                api_mode="anthropic_messages",
+                model="claude-opus-4.8",
+                cache_disabled=False,
+            )
+        assert _has_cache_control(out_msgs), (
+            "With caching enabled, native Anthropic destinations must still "
+            "receive cache_control breakpoints."
+        )
+
+
+class TestMoASlotDecorationHonorsDisable:
+    def test_maybe_apply_skips_markers_when_disabled(self):
+        from agent.moa_loop import _maybe_apply_moa_cache_control
+
+        messages = [
+            {"role": "system", "content": "sys"},
+            {"role": "user", "content": "q1"},
+            {"role": "assistant", "content": "a1"},
+            {"role": "user", "content": "q2"},
+        ]
+        runtime = {
+            "provider": "anthropic",
+            "model": "claude-opus-4.8",
+            "base_url": "",
+            "api_mode": "anthropic_messages",
+        }
+        out = _maybe_apply_moa_cache_control(
+            messages, runtime, cache_disabled=True
+        )
+        assert not _has_cache_control(out)
+        # Inputs must not be mutated.
+        assert not _has_cache_control(messages)
+
+    def test_maybe_apply_config_off(self):
+        from agent.moa_loop import _maybe_apply_moa_cache_control
+
+        messages = [
+            {"role": "system", "content": "sys"},
+            {"role": "user", "content": "q1"},
+            {"role": "assistant", "content": "a1"},
+            {"role": "user", "content": "q2"},
+        ]
+        runtime = {
+            "provider": "anthropic",
+            "model": "claude-opus-4.8",
+            "base_url": "",
+            "api_mode": "anthropic_messages",
+        }
+        with patch(
+            "hermes_cli.config.load_config_readonly",
+            return_value={"prompt_caching": {"cache_ttl": False}},
+        ):
+            out = _maybe_apply_moa_cache_control(messages, runtime)
+        assert not _has_cache_control(out)
+
+
+class TestPreparedAggregatorNoAgentConfigOff:
+    """Prepared-aggregator facades from ``MoAChatCompletions.__new__`` have
+    no ``_agent``. The planner must not raise and must honor config-off.
+    """
+
+    def test_prepared_aggregator_without_agent_honors_config_off(self):
+        import copy
+
+        from agent import moa_loop
+
+        calls = []
+        with (
+            patch.object(
+                moa_loop,
+                "call_llm",
+                side_effect=lambda **kwargs: calls.append(kwargs) or SimpleNamespace(
+                    choices=[SimpleNamespace(
+                        message=SimpleNamespace(content="ok", tool_calls=[]),
+                        finish_reason="stop",
+                    )],
+                    usage=None,
+                    model="fake",
+                ),
+            ),
+            patch.object(
+                moa_loop,
+                "_slot_runtime",
+                return_value={
+                    "provider": "anthropic",
+                    "model": "claude-sonnet-4-6",
+                    "base_url": "https://api.anthropic.com",
+                    "api_mode": "anthropic_messages",
+                },
+            ),
+            patch(
+                "hermes_cli.config.load_config_readonly",
+                return_value={"prompt_caching": {"cache_ttl": "off"}},
+            ),
+        ):
+            completions = moa_loop.MoAChatCompletions.__new__(
+                moa_loop.MoAChatCompletions
+            )
+            # No _agent attribute — the regression surface from review.
+            completions._pending_trace = None
+            prepared = {
+                "messages": [
+                    {"role": "system", "content": "system"},
+                    {"role": "user", "content": "lookup"},
+                    {
+                        "role": "assistant",
+                        "content": "",
+                        "tool_calls": [{
+                            "id": "lookup",
+                            "function": {"name": "lookup", "arguments": "{}"},
+                        }],
+                    },
+                    {
+                        "role": "tool",
+                        "tool_call_id": "lookup",
+                        "content": "result",
+                    },
+                ],
+                "guidance": None,
+                "aggregator": {
+                    "provider": "anthropic",
+                    "model": "claude-sonnet-4-6",
+                },
+                "aggregator_temperature": None,
+            }
+            tools = [{
+                "type": "function",
+                "function": {
+                    "name": "lookup",
+                    "parameters": {"type": "object", "properties": {}},
+                },
+            }]
+            canonical_tools = copy.deepcopy(tools)
+
+            completions._call_prepared_aggregator(prepared, {"tools": tools})
+
+        assert calls, "prepared aggregator must still call the LLM"
+        assert not _has_cache_control(calls[0].get("tools") or []), (
+            "config cache_ttl=off with no live _agent must not inject "
+            "cache_control (planner config fallback, not forced False)."
+        )
+        assert not _has_cache_control(calls[0].get("messages") or [])
+        assert tools == canonical_tools
+
+
+class TestBlankCachePolicyStubFactory:
+    def test_factory_sets_cache_disabled_from_config(self):
+        from agent.agent_runtime_helpers import blank_cache_policy_stub
+
+        with patch(
+            "hermes_cli.config.load_config_readonly",
+            return_value={"prompt_caching": {"cache_ttl": "off"}},
+        ):
+            stub = blank_cache_policy_stub()
+        assert stub._cache_disabled is True
+
+    def test_factory_honors_explicit_false(self):
+        from agent.agent_runtime_helpers import blank_cache_policy_stub
+
+        with patch(
+            "hermes_cli.config.load_config_readonly",
+            return_value={"prompt_caching": {"cache_ttl": "off"}},
+        ):
+            stub = blank_cache_policy_stub(False)
+        assert stub._cache_disabled is False
+
+
+class TestOneShotSynthesisAgentDisable:
+    """aggregate_moa_context must pin agent._cache_disabled onto decoration
+    so the one-shot synthesis path cannot re-enable markers mid-session.
+    """
+
+    def test_synthesis_untouched_when_agent_disables_cache(self):
+        from agent import moa_loop
+
+        calls = []
+        with (
+            patch.object(
+                moa_loop,
+                "call_llm",
+                side_effect=lambda **kwargs: calls.append(kwargs) or SimpleNamespace(
+                    choices=[SimpleNamespace(
+                        message=SimpleNamespace(content="synth", tool_calls=[]),
+                        finish_reason="stop",
+                    )],
+                    usage=None,
+                    model="fake",
+                ),
+            ),
+            patch.object(
+                moa_loop,
+                "_run_references_parallel",
+                return_value=[("advisor-a", "advice from a", None)],
+            ),
+            patch.object(
+                moa_loop,
+                "_slot_runtime",
+                return_value={
+                    "provider": "anthropic",
+                    "model": "claude-opus-4.8",
+                    "base_url": "",
+                    "api_mode": "anthropic_messages",
+                },
+            ),
+            # Config would enable caching; agent snapshot must win.
+            patch(
+                "hermes_cli.config.load_config_readonly",
+                return_value={"prompt_caching": {"cache_ttl": "5m"}},
+            ),
+        ):
+            moa_loop.aggregate_moa_context(
+                user_prompt="what should I do next?",
+                api_messages=[{"role": "user", "content": "help me plan"}],
+                reference_models=[{"provider": "openrouter", "model": "openai/gpt-5.5"}],
+                aggregator={"provider": "anthropic", "model": "claude-opus-4.8"},
+                agent=SimpleNamespace(_cache_disabled=True),
+            )
+
+        assert calls, "synthesis must still call the LLM"
+        synth_msgs = calls[0].get("messages") or []
+        assert not _has_cache_control(synth_msgs), (
+            "agent._cache_disabled must keep the one-shot synthesis "
+            "message undecorated even on a cache-honoring route"
+        )
+
+
+class TestAdvisorRuntimeDisable:
+    def test_maybe_apply_honors_runtime_cache_disabled_snapshot(self):
+        from agent.moa_loop import _maybe_apply_moa_cache_control
+
+        messages = [
+            {"role": "system", "content": "advisor"},
+            {"role": "user", "content": "review"},
+            {"role": "assistant", "content": "a1"},
+            {"role": "user", "content": "again"},
+        ]
+        with patch(
+            "hermes_cli.config.load_config_readonly",
+            return_value={"prompt_caching": {"cache_ttl": "5m"}},
+        ):
+            out = _maybe_apply_moa_cache_control(
+                messages,
+                {
+                    "provider": "anthropic",
+                    "model": "claude-sonnet-4-6",
+                    "base_url": "https://api.anthropic.com",
+                    "api_mode": "anthropic_messages",
+                    "_cache_disabled": True,
+                },
+            )
+        assert not _has_cache_control(out)
+        # Inputs must not be mutated.
+        assert not _has_cache_control(messages)

tests/agent/test_chat_completion_helpers_provider_sort.py

@@ -0,0 +1,13 @@
+from agent.chat_completion_helpers import _validated_openrouter_provider_sort
+
+
+def test_validated_openrouter_provider_sort_accepts_valid_values():
+    assert _validated_openrouter_provider_sort("price") == "price"
+    assert _validated_openrouter_provider_sort(" latency ") == "latency"
+    assert _validated_openrouter_provider_sort("THROUGHPUT") == "throughput"
+
+
+def test_validated_openrouter_provider_sort_rejects_invalid_values():
+    assert _validated_openrouter_provider_sort("intelligence") is None
+    assert _validated_openrouter_provider_sort("") is None
+    assert _validated_openrouter_provider_sort(None) is None

tests/agent/test_codex_app_server_event_bridge.py

@@ -0,0 +1,401 @@
+"""Regression tests for the codex_app_server → Hermes UI event bridge.
+
+Pin the translation of codex JSON-RPC notifications into agent callbacks
+(`tool_progress_callback`, `_fire_stream_delta`, `_fire_reasoning_delta`,
+`_emit_interim_assistant_message`) so Discord/Telegram/TUI continue to
+surface live tool-progress bubbles and interim assistant commentary when
+the active provider runs on `openai_runtime: codex_app_server` (#33200).
+
+Each test drives `make_codex_app_server_event_bridge(agent)` directly with
+fixture notifications that mirror codex 0.130.0's `item/*` shape and
+asserts the right agent callback fired with the right arguments. The
+bridge is deliberately small (~150 lines of pure dict mapping) so the
+tests can stay focused on the wire format ↔ callback contract.
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+from agent.codex_runtime import (
+    _codex_item_completion_payload,
+    _codex_item_to_args,
+    _codex_item_to_preview,
+    _codex_item_to_tool_name,
+    make_codex_app_server_event_bridge,
+)
+
+
+def _make_stub_agent() -> SimpleNamespace:
+    """Minimal stand-in for AIAgent that records every callback fire."""
+    return SimpleNamespace(
+        tool_progress_callback=MagicMock(name="tool_progress_callback"),
+        _fire_stream_delta=MagicMock(name="_fire_stream_delta"),
+        _fire_reasoning_delta=MagicMock(name="_fire_reasoning_delta"),
+        _emit_interim_assistant_message=MagicMock(
+            name="_emit_interim_assistant_message"
+        ),
+    )
+
+
+def _item_started(item: dict) -> dict:
+    return {"method": "item/started", "params": {"item": item}}
+
+
+def _item_completed(item: dict) -> dict:
+    return {"method": "item/completed", "params": {"item": item}}
+
+
+# ---------- name / args / preview / result mapping ----------
+
+
+class TestCodexItemToToolName:
+
+
+
+
+    def test_dynamic_tool_call_uses_tool_field(self):
+        assert _codex_item_to_tool_name(
+            {"type": "dynamicToolCall", "tool": "web_search"}
+        ) == "web_search"
+
+    def test_hermes_tools_mcp_server_emits_bare_tool_name(self):
+        """The hermes-tools MCP server wraps Hermes' own tools for codex;
+        the inner dispatch subprocess can't fire native progress events,
+        so the codex-level event IS the display event — shown without the
+        mcp.hermes-tools.* namespacing (from #26541 by @simpolism)."""
+        assert _codex_item_to_tool_name(
+            {"type": "mcpToolCall", "server": "hermes-tools", "tool": "web_search"}
+        ) == "web_search"
+        assert _codex_item_to_tool_name(
+            {"type": "mcpToolCall", "server": "hermes-tools", "tool": "browser_navigate"}
+        ) == "browser_navigate"
+
+
+
+
+
+class TestCodexItemToArgs:
+
+    def test_file_change_args_normalize_changes(self):
+        args = _codex_item_to_args({
+            "type": "fileChange",
+            "changes": [
+                {"path": "/a.py", "kind": {"type": "add"}},
+                {"path": "/b.py", "kind": {"type": "update"}},
+                "not-a-dict",
+            ],
+        })
+        assert args == {
+            "changes": [
+                {"kind": "add", "path": "/a.py"},
+                {"kind": "update", "path": "/b.py"},
+            ]
+        }
+
+
+    def test_non_dict_arguments_get_wrapped(self):
+        args = _codex_item_to_args({
+            "type": "dynamicToolCall", "arguments": ["a", "b"],
+        })
+        assert args == {"arguments": ["a", "b"]}
+
+
+class TestCodexItemToPreview:
+    def test_command_preview_truncated(self):
+        long_cmd = "echo " + "x" * 500
+        preview = _codex_item_to_preview({
+            "type": "commandExecution", "command": long_cmd
+        })
+        assert preview is not None
+        assert len(preview) <= 120
+
+    def test_file_change_preview_lists_first_three_paths(self):
+        preview = _codex_item_to_preview({
+            "type": "fileChange",
+            "changes": [
+                {"path": f"/p{i}.py", "kind": {"type": "update"}}
+                for i in range(5)
+            ],
+        })
+        assert "/p0.py" in preview and "/p2.py" in preview
+        assert "+2 more" in preview
+
+
+
+
+
+class TestCodexItemCompletionPayload:
+    def test_command_success_returns_aggregated_output(self):
+        result, is_error = _codex_item_completion_payload({
+            "type": "commandExecution",
+            "exitCode": 0,
+            "aggregatedOutput": "hello\nworld\n",
+        })
+        assert result == "hello\nworld\n"
+        assert is_error is False
+
+
+
+    def test_mcp_tool_error_is_error(self):
+        result, is_error = _codex_item_completion_payload({
+            "type": "mcpToolCall",
+            "error": {"message": "nope"},
+        })
+        assert "[error]" in result
+        assert is_error is True
+
+
+
+# ---------- bridge: dispatch contracts ----------
+
+
+class TestStreamDeltaDispatch:
+    def test_agent_message_delta_fires_stream_delta(self):
+        agent = _make_stub_agent()
+        bridge = make_codex_app_server_event_bridge(agent)
+        bridge({"method": "item/agentMessage/delta",
+                "params": {"delta": "hello "}})
+        bridge({"method": "item/agentMessage/delta",
+                "params": {"delta": "world"}})
+        assert agent._fire_stream_delta.call_count == 2
+        assert agent._fire_stream_delta.call_args_list[0].args == ("hello ",)
+        assert agent._fire_stream_delta.call_args_list[1].args == ("world",)
+
+
+
+    def test_reasoning_delta_fires_reasoning_callback(self):
+        agent = _make_stub_agent()
+        bridge = make_codex_app_server_event_bridge(agent)
+        bridge({"method": "item/reasoning/delta",
+                "params": {"delta": "thinking..."}})
+        agent._fire_reasoning_delta.assert_called_once_with("thinking...")
+        agent._fire_stream_delta.assert_not_called()
+
+
+class TestToolProgressDispatch:
+    def test_command_started_fires_tool_started(self):
+        agent = _make_stub_agent()
+        bridge = make_codex_app_server_event_bridge(agent)
+        bridge(_item_started({
+            "type": "commandExecution",
+            "id": "exec-1",
+            "command": "ls /tmp",
+            "cwd": "/tmp",
+        }))
+        agent.tool_progress_callback.assert_called_once()
+        call = agent.tool_progress_callback.call_args
+        assert call.args[0] == "tool.started"
+        assert call.args[1] == "exec_command"
+        assert "ls /tmp" in call.args[2]  # preview
+        assert call.args[3] == {"command": "ls /tmp", "cwd": "/tmp"}
+
+    def test_command_completed_fires_tool_completed_with_result(self):
+        agent = _make_stub_agent()
+        bridge = make_codex_app_server_event_bridge(agent)
+        bridge(_item_started({
+            "type": "commandExecution",
+            "id": "exec-2",
+            "command": "echo hi",
+            "cwd": "/tmp",
+        }))
+        bridge(_item_completed({
+            "type": "commandExecution",
+            "id": "exec-2",
+            "exitCode": 0,
+            "aggregatedOutput": "hi\n",
+            "durationMs": 42,
+        }))
+        # tool.started then tool.completed
+        assert agent.tool_progress_callback.call_count == 2
+        completed = agent.tool_progress_callback.call_args_list[1]
+        assert completed.args[0] == "tool.completed"
+        assert completed.args[1] == "exec_command"
+        assert completed.args[2] is None  # preview unused on completion
+        assert completed.args[3] is None  # args unused on completion
+        assert completed.kwargs["duration"] == pytest.approx(0.042)
+        assert completed.kwargs["is_error"] is False
+        assert completed.kwargs["result"] == "hi\n"
+
+
+
+
+
+    def test_web_search_builtin_fires_started_and_completed(self):
+        """Codex's built-in webSearch produces a start/complete bubble pair
+        with the query as preview and args (#26541)."""
+        agent = _make_stub_agent()
+        bridge = make_codex_app_server_event_bridge(agent)
+        bridge(_item_started({
+            "type": "webSearch",
+            "id": "ws-1",
+            "query": "hermes agent docs",
+        }))
+        bridge(_item_completed({
+            "type": "webSearch",
+            "id": "ws-1",
+            "query": "hermes agent docs",
+        }))
+        calls = agent.tool_progress_callback.call_args_list
+        assert [c.args[0] for c in calls] == ["tool.started", "tool.completed"]
+        assert calls[0].args[1] == "web_search"
+        assert calls[0].args[2] == "hermes agent docs"
+        assert calls[0].args[3] == {"query": "hermes agent docs"}
+
+
+
+
+class TestAgentMessageInterimDispatch:
+    def test_completed_agent_message_emits_interim(self):
+        agent = _make_stub_agent()
+        bridge = make_codex_app_server_event_bridge(agent)
+        bridge(_item_completed({
+            "type": "agentMessage",
+            "id": "am-1",
+            "text": "I'll check the config first.",
+        }))
+        agent._emit_interim_assistant_message.assert_called_once_with(
+            {"role": "assistant", "content": "I'll check the config first."}
+        )
+
+
+
+    def test_show_commentary_off_suppresses_interim(self):
+        """display.show_commentary=false silences agentMessage interim
+        delivery on the app-server runtime (same contract as the
+        codex_responses commentary channel)."""
+        agent = _make_stub_agent()
+        agent.show_commentary = False
+        bridge = make_codex_app_server_event_bridge(agent)
+        bridge(_item_completed({
+            "type": "agentMessage", "id": "am-5", "text": "I'll check config.",
+        }))
+        agent._emit_interim_assistant_message.assert_not_called()
+        # Tool progress is unaffected by the commentary toggle.
+        bridge(_item_started({
+            "type": "commandExecution", "id": "cmd-1", "command": "ls",
+        }))
+        agent.tool_progress_callback.assert_called_once()
+
+
+class TestBridgeRobustness:
+
+    def test_missing_params_is_ignored(self):
+        agent = _make_stub_agent()
+        bridge = make_codex_app_server_event_bridge(agent)
+        bridge({"method": "item/started"})
+        bridge({"method": "item/completed"})
+        agent.tool_progress_callback.assert_not_called()
+
+    def test_callback_exceptions_do_not_propagate(self):
+        # Buggy display callbacks must not tear down the codex turn loop.
+        agent = _make_stub_agent()
+        agent.tool_progress_callback.side_effect = RuntimeError("boom")
+        agent._fire_stream_delta.side_effect = RuntimeError("boom")
+        agent._emit_interim_assistant_message.side_effect = RuntimeError("boom")
+        bridge = make_codex_app_server_event_bridge(agent)
+        # All three paths must swallow exceptions silently.
+        bridge(_item_started({
+            "type": "commandExecution", "id": "exec-x", "command": "ls",
+        }))
+        bridge({"method": "item/agentMessage/delta",
+                "params": {"delta": "x"}})
+        bridge(_item_completed({
+            "type": "agentMessage", "id": "am-x", "text": "hi",
+        }))
+
+
+
+
+# ---------- end-to-end: bridge is wired in run_codex_app_server_turn ----------
+
+
+class TestBridgeWiredInRuntime:
+    """Verify run_codex_app_server_turn actually constructs the session
+    with `on_event=<bridge>`. This is the integration guard that prevents
+    a future refactor from dropping the bridge wiring and silently
+    regressing Discord/Telegram live progress visibility."""
+
+    def test_session_constructor_receives_on_event(self, monkeypatch):
+        from agent import codex_runtime
+
+        captured: dict = {}
+
+        class FakeSession:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+            def run_turn(self, user_input, **_):
+                from agent.transports.codex_app_server_session import TurnResult
+                return TurnResult(
+                    final_text="done",
+                    projected_messages=[],
+                    tool_iterations=0,
+                    turn_id="t1",
+                    thread_id="th1",
+                )
+
+            def close(self):
+                pass
+
+        monkeypatch.setattr(
+            "agent.transports.codex_app_server_session.CodexAppServerSession",
+            FakeSession,
+        )
+
+        # Minimal stub agent — the runtime only touches a handful of
+        # attributes and we mock the heavy ones to keep the test fast.
+        agent = SimpleNamespace(
+            session_cwd=None,
+            _codex_session=None,
+            tool_progress_callback=MagicMock(),
+            _fire_stream_delta=MagicMock(),
+            _fire_reasoning_delta=MagicMock(),
+            _emit_interim_assistant_message=MagicMock(),
+            _iters_since_skill=0,
+            _skill_nudge_interval=0,
+            valid_tool_names=set(),
+            _sync_external_memory_for_turn=lambda **_: None,
+            _spawn_background_review=lambda **_: None,
+            # Usage accounting attrs read by _record_codex_app_server_usage.
+            session_api_calls=0,
+            session_prompt_tokens=0,
+            session_completion_tokens=0,
+            session_reasoning_tokens=0,
+            session_cached_tokens=0,
+            session_total_tokens=0,
+            context_compressor=None,
+            event_callback=None,
+            _session_db=None,
+        )
+
+        codex_runtime.run_codex_app_server_turn(
+            agent,
+            user_message="hi",
+            original_user_message="hi",
+            messages=[],
+            effective_task_id="t",
+        )
+
+        assert "on_event" in captured, (
+            "run_codex_app_server_turn must pass on_event=<bridge> to the "
+            "session — without it the gateway sees no live progress (#33200)"
+        )
+        assert callable(captured["on_event"]), (
+            "on_event must be the bridge callable, not None or a sentinel"
+        )
+
+        # And the bridge must actually drive the agent's callbacks when
+        # fed a representative notification.
+        captured["on_event"](_item_started({
+            "type": "commandExecution",
+            "id": "wired-1",
+            "command": "ls",
+        }))
+        agent.tool_progress_callback.assert_called_once()
+        assert agent.tool_progress_callback.call_args.args[0] == "tool.started"
+        assert agent.tool_progress_callback.call_args.args[1] == "exec_command"

tests/agent/test_codex_app_server_lifecycle.py

@@ -0,0 +1,82 @@
+"""Codex app-server session lifecycle on hard agent teardown (#65260).
+
+The Codex runtime drops ``agent._codex_session`` on turn crash and on
+retirement (agent/codex_runtime.py), but ``AIAgent.close()`` — the hard
+teardown for /new, /reset, and session expiry — had no owner for it, so
+the app-server child process survived until interpreter exit.
+"""
+
+import threading
+
+from run_agent import AIAgent
+
+
+class _FakeCodexSession:
+    def __init__(self, raises: bool = False):
+        self.close_calls = 0
+        self._raises = raises
+
+    def close(self):
+        self.close_calls += 1
+        if self._raises:
+            raise RuntimeError("app-server already dead")
+
+
+def _bare_agent(session_id: str) -> AIAgent:
+    """Minimal agent shell exercising close() without a real build."""
+    agent = AIAgent.__new__(AIAgent)
+    agent.session_id = session_id
+    agent.client = None
+    agent._active_children_lock = threading.Lock()
+    agent._active_children = set()
+    agent._end_session_on_close = False
+    agent._session_messages = ["retained"]
+    return agent
+
+
+def test_agent_close_releases_codex_app_server_session(monkeypatch):
+    agent = _bare_agent("test-codex-lifecycle")
+    codex_session = _FakeCodexSession()
+    agent._codex_session = codex_session
+
+    monkeypatch.setattr("run_agent.cleanup_vm", lambda _task_id: None)
+    monkeypatch.setattr("run_agent.cleanup_browser", lambda _task_id: None)
+
+    agent.close()
+    agent.close()
+
+    # Idempotent: the second close must not re-close a released session.
+    assert codex_session.close_calls == 1
+    assert agent._codex_session is None
+    assert agent._session_messages == []
+
+
+def test_close_clears_reference_even_when_session_close_raises(monkeypatch):
+    """A wedged app-server must not strand a stale session reference.
+
+    The attribute is cleared BEFORE close() precisely so a raising close
+    can't leave a dead session attached to the agent.
+    """
+    agent = _bare_agent("test-codex-lifecycle-raises")
+    codex_session = _FakeCodexSession(raises=True)
+    agent._codex_session = codex_session
+
+    monkeypatch.setattr("run_agent.cleanup_vm", lambda _task_id: None)
+    monkeypatch.setattr("run_agent.cleanup_browser", lambda _task_id: None)
+
+    agent.close()
+
+    assert codex_session.close_calls == 1
+    assert agent._codex_session is None
+
+
+def test_close_without_codex_session_is_a_noop(monkeypatch):
+    """Non-Codex sessions (the common case) must be unaffected."""
+    agent = _bare_agent("test-no-codex")
+
+    monkeypatch.setattr("run_agent.cleanup_vm", lambda _task_id: None)
+    monkeypatch.setattr("run_agent.cleanup_browser", lambda _task_id: None)
+
+    agent.close()
+
+    assert getattr(agent, "_codex_session", None) is None

tests/agent/test_codex_echo_ownership.py

@@ -0,0 +1,50 @@
+"""The accepted input owns its row; transport echoes do not own new rows."""
+import threading
+from types import SimpleNamespace
+
+import pytest
+
+from agent.codex_runtime import _persist_projected_messages
+from agent.message_metadata import append_message
+from agent.session_persistence import SessionPersistenceMixin
+from agent.transports.codex_event_projector import CodexEventProjector
+from hermes_state import SessionDB
+
+
+@pytest.mark.parametrize("platform_id", ["2146", None])
+@pytest.mark.parametrize("projection", ["echo", "assistant_only", "different", "later_equal"])
+def test_only_submitted_leading_echo_is_excluded(tmp_path, platform_id, projection):
+    db = SessionDB(tmp_path / "state.db")
+    try:
+        db.create_session(session_id="echo", source="telegram", model="codex")
+        agent = SessionPersistenceMixin()
+        agent.session_id = "echo"
+        agent._session_db = db
+        agent._session_db_created = True
+        agent._last_flushed_db_idx = 0
+        agent._session_persist_lock = threading.RLock()
+        messages = []
+        # Two independently accepted identical inputs must both survive.
+        for turn_index in range(2):
+            append_message(messages, {"role": "user", "content": "accepted", "platform_message_id": platform_id})
+            assert agent._flush_messages_to_session_db(messages)
+            projector = CodexEventProjector()
+            items = []
+            if projection != "assistant_only":
+                items.append({"type": "userMessage", "id": f"u{turn_index}", "content": [
+                    {"type": "text", "text": "different" if projection == "different" else "wire caption"}]})
+            items.append({"type": "agentMessage", "id": f"a{turn_index}", "text": "reply"})
+            if projection == "later_equal":
+                items.append({"type": "userMessage", "id": f"s{turn_index}", "content": [
+                    {"type": "text", "text": "wire caption"}]})
+            projected = []
+            for item in items:
+                projected.extend(projector.project({"method": "item/completed", "params": {"item": item}}).messages)
+            _persist_projected_messages(agent, SimpleNamespace(
+                projected_messages=projected, submitted_user_text="wire caption"), messages)
+            assert agent._flush_messages_to_session_db(messages)
+        users = [row["content"] for row in db.get_messages_as_conversation("echo") if row["role"] == "user"]
+        extra = {"different": ["different"], "later_equal": ["wire caption"]}.get(projection, [])
+        assert users == (["accepted"] + extra) * 2
+    finally:
+        db.close()

tests/agent/test_codex_no_tools_nonetype.py

@@ -0,0 +1,132 @@
+"""Regression coverage for #32892.
+
+The openai SDK's ``responses.stream()`` / ``responses.parse()`` eagerly
+call ``_make_tools(tools)``, which iterates ``tools`` *without* a None
+guard.  Passing ``tools=None`` therefore raises::
+
+    TypeError: 'NoneType' object is not iterable
+
+…before any HTTP request is issued.  This trips the
+``openai-codex`` / ``gpt-5.5`` combo on ``chatgpt.com/backend-api/codex``
+whenever the user runs Hermes without external tools registered: the
+agent loop catches the TypeError, sees no HTTP status, classifies it as
+non-retryable, and aborts (#32892).
+
+These tests pin the defence:
+:func:`agent.transports.codex.ResponsesApiTransport.build_kwargs` must
+never emit ``tools=None`` — only add the ``tools`` key when there are
+function tools to expose.  When there are no tools, the entire ``tools``
+key (plus ``tool_choice`` and ``parallel_tool_calls`` which are
+meaningless without it) is omitted from the kwargs.
+
+Note: #33042 separately removed the SDK's ``responses.stream()`` helper
+from our own Codex call paths, so the specific iteration crash inside
+``_make_tools`` is also structurally avoided in normal operation.  This
+test class additionally pins the SDK's ``_make_tools(None)`` contract so
+we notice if upstream ever changes it.
+"""
+from __future__ import annotations
+
+import sys
+import types
+from typing import Any, Dict, List
+
+import pytest
+
+
+# Stub optional deps the parent module imports at top level — keeps this
+# test file runnable in the same environment as the existing Codex tests.
+sys.modules.setdefault("fire", types.SimpleNamespace(Fire=lambda *a, **k: None))
+sys.modules.setdefault("firecrawl", types.SimpleNamespace(Firecrawl=object))
+sys.modules.setdefault("fal_client", types.SimpleNamespace())
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def transport():
+    """Fresh ``ResponsesApiTransport`` per test (it is stateless but
+    the import has side-effects on a global transport registry)."""
+    from agent.transports.codex import ResponsesApiTransport
+
+    return ResponsesApiTransport()
+
+
+@pytest.fixture
+def codex_messages() -> List[Dict[str, Any]]:
+    """Minimal Codex-shaped chat history mirroring the #32892 reproducer:
+    one system + one short user message, with no tool calls in history."""
+    return [
+        {"role": "system", "content": "You are Hermes."},
+        {"role": "user", "content": "Hey! What can I help you with?"},
+    ]
+
+
+def _build_kwargs_no_tools(transport, messages) -> Dict[str, Any]:
+    """Exercise the real ``build_kwargs`` for the codex backend with no tools."""
+    return transport.build_kwargs(
+        model="gpt-5.5",
+        messages=messages,
+        tools=None,
+        is_codex_backend=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# build_kwargs: the "tools=None" key must never appear
+# ---------------------------------------------------------------------------
+
+
+def test_build_kwargs_omits_tools_key_when_no_tools(transport, codex_messages):
+    """``build_kwargs`` must not place ``tools=None`` in the outgoing dict.
+
+    Putting ``tools=None`` reaches ``responses.stream()`` which calls
+    ``_make_tools(None)`` and crashes with the #32892 TypeError before any
+    request is sent.
+    """
+    kwargs = _build_kwargs_no_tools(transport, codex_messages)
+
+    assert "tools" not in kwargs, (
+        f"tools key must be omitted entirely when no tools are registered, "
+        f"got kwargs={sorted(kwargs)}"
+    )
+
+
+
+
+def test_build_kwargs_keeps_required_codex_fields_without_tools(transport, codex_messages):
+    """The toolless build must still emit the non-negotiable Codex fields
+    (model / instructions / input / store) — otherwise we'd just be moving
+    the bug from the SDK to preflight."""
+    kwargs = _build_kwargs_no_tools(transport, codex_messages)
+
+    assert kwargs["model"] == "gpt-5.5"
+    assert kwargs["instructions"] == "You are Hermes."
+    assert kwargs["store"] is False
+    assert isinstance(kwargs["input"], list)
+    assert kwargs["input"] and kwargs["input"][0]["role"] == "user"
+
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# ---------------------------------------------------------------------------
+
+
+def test_openai_sdk_raises_typeerror_on_tools_none():
+    """Document the upstream behaviour the two defences guard against.
+
+    If the SDK ever fixes ``_make_tools(None)`` to return ``omit``
+    gracefully, this test will start failing — at which point the agent
+    defences become belt-only and this test should be flipped to an
+    ``xfail`` so we notice the upstream change.
+    """
+    from openai.resources.responses.responses import _make_tools
+
+    with pytest.raises(TypeError, match="NoneType.*not iterable"):
+        _make_tools(None)

tests/agent/test_command_secret_source.py

@@ -0,0 +1,223 @@
+"""E2E tests for the ``command`` secret source.
+
+These exercise the REAL resolution path: real helper shell scripts written
+to a temp dir (chmod +x), real ``/bin/sh -c`` subprocesses, and a real temp
+HERMES_HOME with a config.yaml routing ``secrets.provider: command`` through
+``hermes_cli.env_loader._apply_external_secret_sources``.
+
+Security invariants under test (ported from the desktop TS provider):
+
+* the requested key travels ONLY via the ``HERMES_SECRET_KEY`` env var —
+  never interpolated into the shell string (hostile key names are inert);
+* hard timeout + degrade-to-empty on every failure mode, never raise;
+* failure logging carries structured fields only — never the command
+  string or any secret value.
+
+NOTE: tests assert on key NAMES, lengths, and presence — never log secret
+values themselves.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from agent.secret_sources.command import (  # noqa: E402
+    CommandSource,
+    _run_helper,
+    unquote_dotenv_value,
+)
+from agent.secret_sources.base import (  # noqa: E402
+    reset_source_environment,
+    set_source_environment,
+)
+from hermes_cli import env_loader  # noqa: E402
+
+
+pytestmark = pytest.mark.skipif(
+    os.name == "nt", reason="the command secret provider is POSIX-only"
+)
+
+
+def _write_helper(tmp_path: Path, body: str, name: str = "helper.sh") -> Path:
+    """Write a real executable helper script and return its path."""
+    script = tmp_path / name
+    script.write_text("#!/bin/sh\n" + body + "\n", encoding="utf-8")
+    script.chmod(script.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return script
+
+
+def test_profile_helper_does_not_inherit_process_secret(monkeypatch):
+    monkeypatch.setenv("LEAK_CANARY", "global-secret")
+    token = set_source_environment({"PROFILE_ONLY": "profile-value"})
+    try:
+        output = _run_helper(
+            'printf "%s|%s" "${LEAK_CANARY-unset}" "$PROFILE_ONLY"',
+            "",
+            1.0,
+            1024,
+        )
+    finally:
+        reset_source_environment(token)
+
+    assert output == "unset|profile-value"
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch):
+    """Each test starts with a clean source map, applied-home guard, and no
+    leftover test keys in os.environ."""
+    env_loader._SECRET_SOURCES.clear()
+    env_loader.reset_secret_source_cache()
+    for key in ("CMDTEST_API_KEY", "CMDTEST_TOKEN", "CMDTEST_OTHER_KEY"):
+        monkeypatch.delenv(key, raising=False)
+    yield
+    env_loader._SECRET_SOURCES.clear()
+    env_loader.reset_secret_source_cache()
+    for key in ("CMDTEST_API_KEY", "CMDTEST_TOKEN", "CMDTEST_OTHER_KEY"):
+        os.environ.pop(key, None)
+
+
+# ---------------------------------------------------------------------------
+# Parsing semantics (pure functions, mirroring the TS parseSecretOutput)
+# ---------------------------------------------------------------------------
+
+
+def test_unquote_strips_one_layer_of_matching_quotes():
+    assert unquote_dotenv_value('"abc"') == "abc"
+    assert unquote_dotenv_value("'abc'") == "abc"
+    assert unquote_dotenv_value('""') == ""
+    assert unquote_dotenv_value('"') == '"'  # lone quote left intact
+    assert unquote_dotenv_value("  plain  ") == "plain"
+
+
+# ---------------------------------------------------------------------------
+# Real-subprocess resolution
+# ---------------------------------------------------------------------------
+
+
+def test_helper_stdout_is_returned_verbatim(tmp_path):
+    helper = _write_helper(tmp_path, "printf 'sk-test-bare-12345'")
+    value = _run_helper(str(helper), "CMDTEST_API_KEY", 3.0, 1024)
+    assert value == "sk-test-bare-12345"
+
+
+def test_timeout_kills_hung_helper_and_degrades_to_empty(tmp_path):
+    helper = _write_helper(tmp_path, "sleep 30")
+    start = time.monotonic()
+    value = _run_helper(str(helper), "CMDTEST_API_KEY", 2.0, 1024)
+    elapsed = time.monotonic() - start
+    assert value is None
+    assert elapsed < 6.0, f"helper not killed within the bound (took {elapsed:.1f}s)"
+
+
+def test_failure_logging_never_leaks_command_or_secret(tmp_path, capfd):
+    secret_value = "sk-super-secret-value-do-not-log"
+    helper = _write_helper(
+        tmp_path,
+        f"echo '{secret_value}' >&2\nexit 7",
+        name="my-distinctive-helper-name.sh",
+    )
+    value = _run_helper(str(helper), "CMDTEST_API_KEY", 3.0, 1024)
+    assert value is None
+    captured = capfd.readouterr()
+    combined = captured.out + captured.err
+    # Structured fields only — never the command string, the helper's
+    # stderr, or any secret value.
+    assert "my-distinctive-helper-name" not in combined
+    assert secret_value not in combined
+    assert "code=7" in combined  # the structured field IS logged
+
+
+def test_fetch_parses_dotenv_blob(tmp_path):
+    helper = _write_helper(
+        tmp_path,
+        "printf 'CMDTEST_API_KEY=sk-applied\\nCMDTEST_TOKEN=tok-applied\\n'",
+    )
+    result = CommandSource().fetch({"enabled": True, "command": str(helper)}, tmp_path)
+    assert result.error is None
+    assert result.secrets == {"CMDTEST_API_KEY": "sk-applied", "CMDTEST_TOKEN": "tok-applied"}
+
+
+# ---------------------------------------------------------------------------
+# Dispatch E2E through env_loader against a real temp HERMES_HOME
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _clean_registry():
+    from agent.secret_sources import registry
+    registry._reset_registry_for_tests()
+    yield
+    registry._reset_registry_for_tests()
+
+
+def test_registry_command_source_applies_and_records_source(tmp_path, monkeypatch):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    helper = _write_helper(
+        tmp_path, "printf 'CMDTEST_API_KEY=sk-dispatch\\nCMDTEST_TOKEN=tok-dispatch\\n'"
+    )
+    (tmp_path / "config.yaml").write_text(
+        "secrets:\n"
+        "  command:\n"
+        "    enabled: true\n"
+        f"    command: {helper}\n",
+        encoding="utf-8",
+    )
+
+    env_loader._apply_external_secret_sources(tmp_path)
+
+    assert os.environ.get("CMDTEST_API_KEY") == "sk-dispatch"
+    assert env_loader.get_secret_source("CMDTEST_API_KEY") == "command"
+    assert env_loader.get_secret_source("CMDTEST_TOKEN") == "command"
+    assert (
+        env_loader.format_secret_source_suffix("CMDTEST_API_KEY")
+        == " (from Command helper)"
+    )
+
+
+def test_registry_status_line_printed_once_per_home(tmp_path, monkeypatch, capsys):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    helper = _write_helper(tmp_path, "printf 'CMDTEST_API_KEY=sk-once\\n'")
+    (tmp_path / "config.yaml").write_text(
+        "secrets:\n  command:\n    enabled: true\n"
+        f"    command: {helper}\n",
+        encoding="utf-8",
+    )
+
+    for _ in range(3):  # idempotency guard: only the first call does work
+        env_loader._apply_external_secret_sources(tmp_path)
+
+    err = capsys.readouterr().err
+    assert err.count("Command helper: applied 1 secret") == 1
+
+
+def test_registry_failing_helper_does_not_block_startup(tmp_path, monkeypatch):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    (tmp_path / "config.yaml").write_text(
+        "secrets:\n  command:\n    enabled: true\n    command: exit 9\n",
+        encoding="utf-8",
+    )
+    # Must not raise — config/helper errors never block startup.
+    env_loader._apply_external_secret_sources(tmp_path)
+    assert env_loader.get_secret_source("CMDTEST_API_KEY") is None
+
+
+def test_registry_helper_error_prints_remediation(tmp_path, monkeypatch, capsys):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    (tmp_path / "config.yaml").write_text(
+        "secrets:\n  command:\n    enabled: true\n    command: ''\n",
+        encoding="utf-8",
+    )
+    env_loader._apply_external_secret_sources(tmp_path)
+    err = capsys.readouterr().err
+    assert "secrets.command.command" in err

tests/agent/test_compaction_ops_notification_anchor.py

@@ -0,0 +1,103 @@
+"""Operational notifications must not anchor compaction or auto-focus (#92703).
+
+Kanban/background completion wakes are persisted as ``role="user"`` rows typed
+with ``display_kind="internal_notification"`` (run.py -- the synthetic-wake
+path). The model-payload builder already strips ``display_kind`` before the
+request, and ``is_user_originated_turn`` already ignores it, but the compaction
+tail-anchor / auto-focus scans must do the same. Otherwise routine machine
+traffic becomes the "last user turn" the compressor protects and the focus
+hint derives from, displacing the user's real objective.
+
+These are behavior contracts against the real compressor functions, not mocks:
+feed a transcript of 1,000 operational notifications around a single human turn
+and assert the operational rows are invisible to the anchor/focus logic.
+"""
+import pytest
+
+from agent.context_compressor import ContextCompressor
+
+
+def _compressor() -> ContextCompressor:
+    cc = ContextCompressor(
+        model="test-model",
+        threshold_percent=0.75,
+        protect_first_n=5,
+        protect_last_n=20,
+        quiet_mode=True,
+        config_context_length=40960,
+        provider="test",
+    )
+    cc._generate_summary = lambda *a, **k: "Summary of earlier turns."
+    return cc
+
+
+def _ops_notice(text: str) -> dict:
+    """A Kanban/background completion wake, as persisted by the wake path."""
+    return {
+        "role": "user",
+        "content": text,
+        "display_kind": "internal_notification",
+    }
+
+
+def _human(text: str) -> dict:
+    return {"role": "user", "content": text}
+
+
+def _assistant(text: str) -> dict:
+    return {"role": "assistant", "content": text}
+
+
+def _transcript_with_n_ops(n: int, human_text: str = "Actually deploy the fix") -> list:
+    """1,000 operational notifications with a single real human turn at the end."""
+    msgs: list = [{"role": "system", "content": "sys"}]
+    for i in range(n):
+        msgs.append(_ops_notice(f"✔ Kanban T-{i} done — worker summary line {i}"))
+        msgs.append(_assistant(f"Noted task {i} completion."))
+    msgs.append(_human(human_text))
+    msgs.append(_assistant("On it."))
+    return msgs
+
+
+def test_ops_notice_is_not_actionable_user_turn():
+    cc = _compressor()
+    assert cc._is_actionable_user_turn(_ops_notice("✔ Kanban T-1 done")) is False
+    # A real human turn still is.
+    assert cc._is_actionable_user_turn(_human("deploy the fix")) is True
+
+
+def test_ops_notices_do_not_anchor_compaction_tail():
+    cc = _compressor()
+    msgs = _transcript_with_n_ops(1000)
+    # The tail anchor must land on the human turn, not on any operational notice.
+    idx = cc._find_last_user_message_idx(msgs, head_end=0)
+    assert idx >= 0
+    assert msgs[idx]["role"] == "user"
+    assert msgs[idx].get("display_kind") is None, (
+        "compaction tail anchored on an operational notification, "
+        "not the user's real objective"
+    )
+    assert msgs[idx]["content"] == "Actually deploy the fix"
+
+
+def test_ops_notices_do_not_become_auto_focus_source():
+    cc = _compressor()
+    msgs = _transcript_with_n_ops(1000, human_text="Summarize the Q3 roadmap")
+    focus = cc._derive_auto_focus_topic(msgs)
+    assert focus is not None
+    assert "Q3 roadmap" in focus, (
+        f"auto-focus derived from operational traffic instead of the user: {focus!r}"
+    )
+    assert "Kanban T-" not in focus, (
+        f"auto-focus leaked an operational notification: {focus!r}"
+    )
+
+
+def test_conversational_user_count_unchanged_by_ops_notices():
+    """1,000 notifications must not be counted as actionable user turns."""
+    cc = _compressor()
+    msgs = _transcript_with_n_ops(1000)
+    actionable = [m for m in msgs if cc._is_actionable_user_turn(m)]
+    # Exactly one: the human turn at the end.
+    assert len(actionable) == 1
+    assert actionable[0]["content"] == "Actually deploy the fix"

tests/agent/test_compaction_redaction_boundaries.py

@@ -0,0 +1,223 @@
+"""Strict redaction at every compaction text boundary (issue #43666 item 2).
+
+Compaction summaries persist across sessions and re-enter every subsequent
+summarizer prompt, so ``_redact_compaction_text()`` applies strict mode
+(``force=True, redact_url_credentials=True``) at each boundary:
+
+- serializer input (``_serialize_for_summary``: message content + tool args)
+- deterministic fallback summary (``_build_static_fallback_summary``)
+- summarizer LLM output (``_generate_summary`` return / ``_previous_summary``)
+- focus text (manual ``/compress <focus>`` and ``_derive_auto_focus_topic``)
+- previous-summary re-entry into the iterative-update prompt
+
+Every test disables the global redaction flag (simulating
+``security.redact_secrets: false``) to prove ``force=True`` still redacts at
+the persistence boundary, and uses an OAuth-callback-style URL to prove
+``redact_url_credentials=True`` strips opaque URL tokens that default-mode
+redaction deliberately passes through.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent.context_compressor import (
+    ContextCompressor,
+    SUMMARY_PREFIX,
+    _redact_compaction_text,
+)
+
+SECRET = "sk-proj-" + ("a" * 40)
+OAUTH_URL = (
+    "https://localhost/callback?code=opaque-code-123"
+    "&access_token=opaque-token-456&state=keep"
+)
+
+
+@pytest.fixture(autouse=True)
+def _redaction_globally_disabled(monkeypatch):
+    """Simulate security.redact_secrets: false — force=True must still win."""
+    monkeypatch.setattr("agent.redact._REDACT_ENABLED", False)
+
+
+def _compressor() -> ContextCompressor:
+    with patch(
+        "agent.context_compressor.get_model_context_length",
+        return_value=100000,
+    ):
+        return ContextCompressor(model="test/model", quiet_mode=True)
+
+
+def _response(content: str):
+    mock_response = MagicMock()
+    mock_response.choices = [MagicMock()]
+    mock_response.choices[0].message.content = content
+    return mock_response
+
+
+def _assert_clean(text: str):
+    assert SECRET not in text
+    assert "sk-proj-" not in text
+    assert "code=opaque-code-123" not in text
+    assert "access_token=opaque-token-456" not in text
+    assert "code=***" in text
+    assert "access_token=***" in text
+    assert "state=keep" in text
+
+
+def test_helper_is_strict_even_when_redaction_disabled():
+    result = _redact_compaction_text(f"key {SECRET} url {OAUTH_URL}")
+    _assert_clean(result)
+    # None-safety: helper is used on optional fields.
+    assert _redact_compaction_text(None) == ""
+
+
+def test_serializer_input_redacts_content_and_tool_args():
+    c = _compressor()
+    messages = [
+        {"role": "user", "content": f"token {SECRET} url {OAUTH_URL}"},
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "call-1",
+                    "function": {
+                        "name": "terminal",
+                        "arguments": (
+                            f'{{"command": "curl {OAUTH_URL}",'
+                            f' "note": "{SECRET}"}}'
+                        ),
+                    },
+                }
+            ],
+        },
+        {"role": "tool", "tool_call_id": "call-1", "content": f"got {SECRET}"},
+    ]
+
+    serialized = c._serialize_for_summary(messages)
+
+    _assert_clean(serialized)
+
+
+def test_fallback_summary_redacts_secrets():
+    c = _compressor()
+    turns = [
+        {"role": "user", "content": f"deploy with {SECRET} via {OAUTH_URL}"},
+        {"role": "assistant", "content": f"ran curl {OAUTH_URL}"},
+    ]
+
+    summary = c._build_static_fallback_summary(turns, reason="test outage")
+
+    _assert_clean(summary)
+
+
+def test_summary_output_redacts_llm_echoed_secrets():
+    c = _compressor()
+    leaked = f"Summary leaked OPENAI_API_KEY {SECRET} and {OAUTH_URL}"
+
+    with patch(
+        "agent.context_compressor.call_llm", return_value=_response(leaked)
+    ):
+        summary = c._generate_summary([{"role": "user", "content": "hi"}])
+
+    assert summary is not None
+    _assert_clean(summary)
+    # The stored iterative-update seed must be clean too.
+    _assert_clean(c._previous_summary)
+
+
+def test_manual_focus_topic_redacted_before_summary_prompt():
+    c = _compressor()
+    turns = [
+        {"role": "user", "content": "Summarize safely"},
+        {"role": "assistant", "content": "OK"},
+    ]
+
+    with patch(
+        "agent.context_compressor.call_llm",
+        return_value=_response("## Goal\nSafe summary."),
+    ) as mock_call:
+        result = c._generate_summary(
+            turns, focus_topic=f"manual focus {SECRET} {OAUTH_URL}"
+        )
+
+    assert result is not None
+    prompt = mock_call.call_args.kwargs["messages"][0]["content"]
+    _assert_clean(prompt)
+
+
+def test_auto_focus_topic_redacted():
+    c = _compressor()
+
+    focus = c._derive_auto_focus_topic(
+        [
+            {"role": "assistant", "content": "older assistant turn"},
+            {"role": "user", "content": f"focus has {SECRET} and {OAUTH_URL}"},
+        ]
+    )
+
+    assert focus is not None
+    _assert_clean(focus)
+
+
+def test_previous_summary_redacted_before_iterative_prompt_reentry():
+    """Legacy persisted summaries may predate compaction redaction."""
+    c = _compressor()
+    c._previous_summary = f"Old summary leaked {SECRET} and {OAUTH_URL}"
+
+    with patch(
+        "agent.context_compressor.call_llm",
+        return_value=_response("updated summary"),
+    ) as mock_call:
+        result = c._generate_summary(
+            [
+                {"role": "user", "content": "new turn"},
+                {"role": "assistant", "content": "new work"},
+            ]
+        )
+
+    assert result is not None
+    prompt = mock_call.call_args.kwargs["messages"][0]["content"]
+    assert "PREVIOUS SUMMARY:" in prompt
+    _assert_clean(prompt)
+    # After generation, _previous_summary holds the new (clean) LLM output —
+    # the leaked secret must not have survived anywhere in it.
+    assert SECRET not in c._previous_summary
+    assert "access_token=opaque-token-456" not in c._previous_summary
+
+
+def test_resumed_handoff_summary_redacted_before_iterative_prompt():
+    """Persisted handoff messages may contain pre-fix secrets after resume."""
+    with patch(
+        "agent.context_compressor.get_model_context_length",
+        return_value=100000,
+    ):
+        c = ContextCompressor(
+            model="test/model",
+            threshold_percent=0.85,
+            protect_first_n=1,
+            protect_last_n=1,
+            quiet_mode=True,
+        )
+    old_summary = f"RESUMED-SUMMARY leaked {SECRET} and {OAUTH_URL}"
+    messages = [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": f"{SUMMARY_PREFIX}\n{old_summary}"},
+        {"role": "assistant", "content": "handoff acknowledged after resume"},
+        {"role": "user", "content": "new user turn after resume"},
+        {"role": "assistant", "content": "new assistant work after resume"},
+        {"role": "user", "content": "more new work after resume"},
+        {"role": "assistant", "content": "latest tail response"},
+        {"role": "user", "content": "final active request stays in tail"},
+    ]
+
+    with patch(
+        "agent.context_compressor.call_llm",
+        return_value=_response("updated summary"),
+    ) as mock_call:
+        c.compress(messages)
+
+    prompt = mock_call.call_args.kwargs["messages"][0]["content"]
+    assert "PREVIOUS SUMMARY:" in prompt
+    _assert_clean(prompt)

tests/agent/test_compression_attempt_lifecycle.py

@@ -0,0 +1,360 @@
+"""Attempt-lifecycle regression tests for #97488 / #96775.
+
+Pins the three attempt-level lifecycle guarantees added after PR #98628
+collapsed lean compaction to one auxiliary request per attempt:
+
+1. A ceiling/idle-timeout host TEARS DOWN its worker: a cooperative worker is
+   joined within the bounded grace (releasing the lease normally), while an
+   uninterruptible worker is orphaned behind the poison fence — its late
+   result is discarded and, on the total-ceiling path, the durable lease is
+   retained until it exits so no new attempt overlaps the unchanged session.
+2. A failed/stalled/cancelled attempt records a durable per-session backoff
+   (strategy + failure kind stamped into the state.db cooldown row) that
+   SURVIVES a gateway restart; the next automatic turn skips the same
+   strategy inside the window, and a successful compression clears it.
+3. Late results from a superseded attempt are discarded, never committed
+   over newer state (generation counter), and a transiently-blocked no-op is
+   reported as a soft defer — never compression_exhausted (false auto-reset).
+"""
+
+from __future__ import annotations
+
+import copy
+import os
+import threading
+import time
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from agent.auxiliary_client import AuxiliaryExplicitCancellation
+from agent.conversation_compression import (
+    CompressionCommitFence,
+    _claim_compressor_attempt,
+    compress_context,
+    compression_blocked_transiently,
+    run_compress_context_with_progress_timeout,
+)
+from hermes_state import SessionDB
+
+
+def _build_agent(tmp_path: Path, session_id: str, db: SessionDB | None = None):
+    if db is None:
+        db = SessionDB(db_path=tmp_path / "state.db")
+        db.create_session(session_id, source="cli")
+    with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}):
+        from run_agent import AIAgent
+
+        agent = AIAgent(
+            api_key="test-key",
+            base_url="https://openrouter.ai/api/v1",
+            model="test/model",
+            quiet_mode=True,
+            session_db=db,
+            session_id=session_id,
+            skip_context_files=True,
+            skip_memory=True,
+        )
+    agent._compression_feasibility_checked = True
+    agent.compression_in_place = True
+    agent._cached_system_prompt = "sys"
+    agent.context_compressor.threshold_tokens = 1_000
+    return db, agent
+
+
+def _messages():
+    return [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+
+class TestWorkerTeardownOnCeiling:
+    def test_cooperative_worker_joined_within_grace(self):
+        """A worker that exits promptly after cancel is joined on the
+        total-ceiling path; the lease is released normally (no retention) —
+        the sabotage check for this test is removing the
+        `_join_cancelled_worker` call, which makes
+        `worker_done.is_set()` False when the host returns."""
+        original = [{"role": "user", "content": "keep"}]
+        worker_done = threading.Event()
+
+        def cooperative_worker(fence: CompressionCommitFence):
+            # Continuous progress (the #97488 'last progress 0.0s ago'
+            # shape) so only the TOTAL ceiling expires; poll the poison
+            # fence like the production worker does between provider phases.
+            deadline = time.monotonic() + 5.0
+            while time.monotonic() < deadline:
+                if fence.is_cancelled:
+                    break
+                fence.touch_progress()
+                time.sleep(0.01)
+            # Cooperative-but-not-instant exit: the unwind after seeing the
+            # poison takes real time (rollback, telemetry). Long enough that
+            # a host WITHOUT the bounded-grace join returns first; far
+            # inside the 5s grace for a host WITH it.
+            time.sleep(0.08)
+            worker_done.set()
+            return (original, "late")
+
+        fence = CompressionCommitFence()
+        msgs, prompt = run_compress_context_with_progress_timeout(
+            worker=cooperative_worker,
+            messages=original,
+            system_prompt_fallback="fallback",
+            # Keep idle expiry out of this total-ceiling test under runner load.
+            idle_timeout_seconds=2.0,
+            total_ceiling_seconds=0.2,
+            fence=fence,
+            stall_fallback=False,
+        )
+        # The bounded-grace join must have reaped the cooperative worker
+        # BEFORE the host returned.
+        assert worker_done.is_set(), (
+            "host returned before tearing down a cooperative cancelled "
+            "worker — bounded-grace join missing (#97488)"
+        )
+        # Whichever return path won the race (fallback via join, or the
+        # worker's own return adopted inside the final wait slice), the
+        # transcript must be unchanged.
+        assert msgs == [{"role": "user", "content": "keep"}]
+        assert prompt in ("fallback", "late")
+        # Teardown proved quiescence, so the lease must NOT stay retained.
+        assert fence._retain_cancelled_lock_until_worker_done is False
+
+    def test_uninterruptible_worker_is_orphaned_with_lease_retained(self):
+        """A worker stuck in an uninterruptible provider call is orphaned:
+        the host returns after the grace, the poison fence discards its late
+        result, and on the total-ceiling path the durable lease release hook
+        does NOT fire while the worker is alive (no overlap window)."""
+        original = [{"role": "user", "content": "keep"}]
+        release = threading.Event()
+        worker_finished = threading.Event()
+        lock_released: list[float] = []
+
+        def stuck_worker(fence: CompressionCommitFence):
+            # Continuous progress so only the TOTAL ceiling can expire
+            # (the #97488 'last progress 0.0s ago' shape).
+            while not release.wait(timeout=0.02):
+                fence.touch_progress()
+            worker_finished.set()
+            if not fence.begin_commit():
+                return (original, "")
+            try:
+                return ([{"role": "assistant", "content": "late"}], "late")
+            finally:
+                fence.finish_commit()
+
+        fence = CompressionCommitFence()
+        fence.register_cancelled_lock_release(
+            lambda: lock_released.append(time.monotonic())
+        )
+        msgs, prompt = run_compress_context_with_progress_timeout(
+            worker=stuck_worker,
+            messages=original,
+            system_prompt_fallback="fallback",
+            idle_timeout_seconds=0.1,
+            total_ceiling_seconds=0.3,
+            fence=fence,
+            stall_fallback=False,
+        )
+        # Precondition: the worker is genuinely still running.
+        assert not worker_finished.is_set()
+        assert msgs is original and prompt == "fallback"
+        # Total-ceiling path: lease retained until the worker exits, so no
+        # new attempt can overlap the unchanged session.
+        assert not lock_released, (
+            "durable lease released while the timed-out worker was still "
+            "alive — overlap window reopened (#97488)"
+        )
+        release.set()
+        assert worker_finished.wait(timeout=2)
+        # Late result was fence-poisoned, never adopted.
+        assert msgs == [{"role": "user", "content": "keep"}]
+
+
+class TestDurableAttemptBackoff:
+    def test_backoff_row_records_strategy_and_kind(self, tmp_path: Path):
+        db, agent = _build_agent(tmp_path, "BACKOFF_KIND")
+        agent.context_compressor.record_timeout_failure(
+            "host ceiling exhausted", failure_kind="ceiling_exhausted"
+        )
+        row = db.get_compression_failure_cooldown("BACKOFF_KIND")
+        assert row is not None, "backoff must persist to state.db"
+        assert row["remaining_seconds"] > 0
+        assert "backoff:ceiling_exhausted:strategy=lean" in (row["error"] or "")
+
+    def test_backoff_blocks_same_strategy_reentry_next_turn(self, tmp_path: Path):
+        db, agent = _build_agent(tmp_path, "BACKOFF_REENTRY")
+        agent.context_compressor.record_timeout_failure(
+            "stall", failure_kind="stalled"
+        )
+        # Precondition: over threshold, so only the backoff can block.
+        assert 500_000 >= agent.context_compressor.threshold_tokens
+        should, reason = agent.context_compressor.should_compress_info(500_000)
+        assert should is False
+        assert reason and reason.startswith("cooldown"), (
+            "next-turn re-entry of the same strategy must be skipped inside "
+            "the backoff window (#96775)"
+        )
+
+    def test_backoff_survives_simulated_gateway_restart(self, tmp_path: Path):
+        db, agent = _build_agent(tmp_path, "BACKOFF_RESTART")
+        agent.context_compressor.record_timeout_failure(
+            "stall before restart", failure_kind="stall_interrupted"
+        )
+        # Precondition: row is durable in this DB file.
+        assert db.get_compression_failure_cooldown("BACKOFF_RESTART")
+        # Simulated restart: brand-new SessionDB handle + brand-new agent
+        # objects rebuilt from the same state.db file.
+        db2 = SessionDB(db_path=tmp_path / "state.db")
+        _db2, agent2 = _build_agent(tmp_path, "BACKOFF_RESTART", db=db2)
+        cooldown = agent2.context_compressor.get_active_compression_failure_cooldown(
+            refresh=True
+        )
+        assert cooldown is not None, (
+            "backoff must survive a gateway restart via state.db (#96775)"
+        )
+        assert "stall_interrupted" in (cooldown["error"] or "")
+        should, reason = agent2.context_compressor.should_compress_info(500_000)
+        assert should is False and reason.startswith("cooldown")
+
+    def test_success_clears_backoff(self, tmp_path: Path):
+        db, agent = _build_agent(tmp_path, "BACKOFF_CLEAR")
+        compressor = agent.context_compressor
+        compressor.record_timeout_failure("stall", failure_kind="stalled")
+        assert db.get_compression_failure_cooldown("BACKOFF_CLEAR")
+        # What a successful compression does on commit:
+        compressor._clear_compression_failure_cooldown()
+        assert db.get_compression_failure_cooldown("BACKOFF_CLEAR") is None
+        assert compressor.should_compress_info(500_000)[0] is True
+
+
+class TestSupersessionDiscardsLateResults:
+    def test_superseded_attempt_candidate_never_commits(self, tmp_path: Path):
+        db, agent = _build_agent(tmp_path, "SUPERSEDE")
+        live = _messages()
+        original = copy.deepcopy(live)
+
+        def compress_and_get_superseded(messages, **_kwargs):
+            # While this attempt's summary was in flight, a NEWER attempt
+            # claimed the compressor (what a retry/fallback does).
+            _claim_compressor_attempt(agent.context_compressor)
+            return [{"role": "assistant", "content": "stale summary"}]
+
+        agent.context_compressor.compress = compress_and_get_superseded
+        out, _prompt = compress_context(
+            agent, live, "sys", approx_tokens=500_000
+        )
+        assert out == original, (
+            "late candidate from a superseded attempt must be discarded, "
+            "never committed over newer state (#97488)"
+        )
+        assert live == original
+        # Session stayed writable and unrotated.
+        assert db.get_compression_lock_holder("SUPERSEDE") is None
+        db.append_message("SUPERSEDE", "assistant", "still writable")
+
+
+class TestTransientBlockIsNotExhaustion:
+    def test_cooldown_blocked_noop_sets_transient_signal(self, tmp_path: Path):
+        db, agent = _build_agent(tmp_path, "TRANSIENT_SIGNAL")
+        agent.context_compressor.record_timeout_failure(
+            "host ceiling", failure_kind="ceiling_exhausted"
+        )
+        live = _messages()
+        before = copy.deepcopy(live)
+        out, _ = compress_context(agent, live, "sys", approx_tokens=500_000)
+        # Preconditions: the pass no-oped and it was NOT a lock skip.
+        assert out == before
+        assert getattr(agent, "_compression_skipped_due_to_lock", None) is None
+        assert compression_blocked_transiently(agent) is True, (
+            "a cooldown-blocked no-op must be distinguishable from "
+            "exhaustion or the gateway falsely auto-resets (#97488)"
+        )
+
+    def test_signal_cleared_per_attempt_and_not_set_when_unblocked(
+        self, tmp_path: Path
+    ):
+        db, agent = _build_agent(tmp_path, "TRANSIENT_CLEAR")
+        # Stale signal from a previous pass must not leak.
+        agent._compression_blocked_transient = "cooldown:999"
+        agent.context_compressor.compress = lambda messages, **kw: list(messages)
+        live = _messages()
+        compress_context(agent, live, "sys", approx_tokens=500_000)
+        assert compression_blocked_transiently(agent) is False
+
+    def test_type_pinned_against_magicmock_agents(self):
+        from unittest.mock import MagicMock
+
+        mock_agent = MagicMock()
+        # MagicMock auto-attributes are truthy but not str.
+        assert compression_blocked_transiently(mock_agent) is False
+
+
+def _summary_response(content: str):
+    from unittest.mock import MagicMock
+
+    response = MagicMock()
+    response.choices = [MagicMock()]
+    response.choices[0].message.content = content
+    return response
+
+
+class TestProviderOverflowBypassesCooldown:
+    """#100661: a provider-proven overflow must get one REAL summary attempt
+    while the summary-failure cooldown is armed. Before the fix every turn of
+    a wedged session hit the cooldown gate, returned the soft "temporarily
+    paused" deferral, and the next failure extended the ladder — 4 long
+    sessions were lost this way. Ordinary (non-overflow) automatic passes
+    must still defer."""
+
+    def _armed_agent(self, tmp_path: Path, session_id: str):
+        db, agent = _build_agent(tmp_path, session_id)
+        # Realistic arming: a failed/stalled attempt recorded the ladder.
+        agent.context_compressor.record_timeout_failure(
+            "stall", failure_kind="stalled"
+        )
+        assert agent.context_compressor.should_compress_info(500_000)[0] is False
+        return db, agent
+
+    def test_overflow_attempt_invokes_summarizer_while_cooldown_armed(
+        self, tmp_path: Path
+    ):
+        db, agent = self._armed_agent(tmp_path, "OVERFLOW_BYPASS")
+        calls = []
+
+        def fake_call_llm(**kwargs):
+            calls.append(kwargs)
+            return _summary_response("## Goal\nRecovered after overflow.")
+
+        # Bulky turns so the compacted transcript is genuinely smaller.
+        live = [
+            {"role": "user" if i % 2 == 0 else "assistant", "content": f"m{i} " * 400}
+            for i in range(20)
+        ]
+        with patch("agent.context_compressor.call_llm", fake_call_llm):
+            out, _ = compress_context(
+                agent, live, "sys", approx_tokens=500_000, bypass_cooldown=True
+            )
+        assert len(calls) == 1, (
+            "provider-proven overflow must reach the summary LLM even while "
+            "the failure cooldown is armed (#100661)"
+        )
+        assert compression_blocked_transiently(agent) is False
+        assert len(out) < len(live), "the attempt must actually compact"
+
+    def test_non_overflow_pass_still_deferred_by_cooldown(self, tmp_path: Path):
+        db, agent = self._armed_agent(tmp_path, "OVERFLOW_ORDINARY")
+        calls = []
+
+        def fake_call_llm(**kwargs):  # pragma: no cover - must not run
+            calls.append(kwargs)
+            return _summary_response("unexpected")
+
+        live = _messages()
+        before = copy.deepcopy(live)
+        with patch("agent.context_compressor.call_llm", fake_call_llm):
+            out, _ = compress_context(agent, live, "sys", approx_tokens=500_000)
+        assert calls == [] and out == before
+        assert compression_blocked_transiently(agent) is True, (
+            "ordinary threshold pressure keeps honoring the cooldown (#11529)"
+        )

tests/agent/test_compression_boundary.py

@@ -0,0 +1,145 @@
+"""Tests for context compression boundary alignment.
+
+Verifies that _align_boundary_backward correctly handles tool result groups
+so that parallel tool calls are never split during compression.
+"""
+
+from unittest.mock import patch
+
+from agent.context_compressor import ContextCompressor
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _tc(call_id: str) -> dict:
+    """Create a minimal tool_call dict."""
+    return {"id": call_id, "type": "function", "function": {"name": "test", "arguments": "{}"}}
+
+
+def _tool_result(call_id: str, content: str = "result") -> dict:
+    """Create a tool result message."""
+    return {"role": "tool", "tool_call_id": call_id, "content": content}
+
+
+def _assistant_with_tools(*call_ids: str) -> dict:
+    """Create an assistant message with tool_calls."""
+    return {"role": "assistant", "tool_calls": [_tc(cid) for cid in call_ids], "content": None}
+
+
+def _make_compressor(**kwargs) -> ContextCompressor:
+    defaults = dict(
+        model="test-model",
+        threshold_percent=0.75,
+        protect_first_n=3,
+        protect_last_n=4,
+        quiet_mode=True,
+    )
+    defaults.update(kwargs)
+    with patch("agent.context_compressor.get_model_context_length", return_value=8000):
+        return ContextCompressor(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# _align_boundary_backward tests
+# ---------------------------------------------------------------------------
+
+class TestAlignBoundaryBackward:
+    """Test that compress-end boundary never splits a tool_call/result group."""
+
+    def test_boundary_at_clean_position(self):
+        """Boundary after a user message — no adjustment needed."""
+        comp = _make_compressor()
+        messages = [
+            {"role": "system", "content": "sys"},
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi"},
+            {"role": "user", "content": "do something"},
+            _assistant_with_tools("tc_1"),
+            _tool_result("tc_1", "done"),
+            {"role": "user", "content": "thanks"},  # idx=6
+            {"role": "assistant", "content": "np"},
+        ]
+        # Boundary at 7, messages[6] = user — no adjustment
+        assert comp._align_boundary_backward(messages, 7) == 7
+
+    def test_boundary_after_assistant_with_tools(self):
+        """Original case: boundary right after assistant with tool_calls."""
+        comp = _make_compressor()
+        messages = [
+            {"role": "system", "content": "sys"},
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi"},
+            _assistant_with_tools("tc_1", "tc_2"),  # idx=3
+            _tool_result("tc_1"),                    # idx=4
+            _tool_result("tc_2"),                    # idx=5
+            {"role": "user", "content": "next"},
+        ]
+        # Boundary at 4, messages[3] = assistant with tool_calls → pull back to 3
+        assert comp._align_boundary_backward(messages, 4) == 3
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# End-to-end: compression must not lose tool results
+# ---------------------------------------------------------------------------
+
+class TestCompressionToolResultPreservation:
+    """Verify that compress() never silently drops tool results."""
+
+    def test_parallel_tool_results_not_lost(self):
+        """The exact scenario that triggered silent data loss before the fix."""
+        comp = _make_compressor(protect_first_n=3, protect_last_n=4)
+
+        messages = [
+            {"role": "system", "content": "You are helpful."},            # 0
+            {"role": "user", "content": "Hello"},                         # 1
+            {"role": "assistant", "content": "Hi there!"},                # 2  (end of head)
+            {"role": "user", "content": "Read 7 files for me"},           # 3
+            _assistant_with_tools("tc_A", "tc_B", "tc_C", "tc_D", "tc_E", "tc_F", "tc_G"),  # 4
+            _tool_result("tc_A", "content of file A"),                    # 5
+            _tool_result("tc_B", "content of file B"),                    # 6
+            _tool_result("tc_C", "content of file C"),                    # 7
+            _tool_result("tc_D", "content of file D"),                    # 8
+            _tool_result("tc_E", "content of file E"),                    # 9
+            _tool_result("tc_F", "content of file F"),                    # 10
+            _tool_result("tc_G", "CRITICAL DATA in file G"),              # 11 ← compress_end=15-4=11
+            {"role": "user", "content": "Now summarize them"},            # 12
+            {"role": "assistant", "content": "Here is the summary..."},   # 13
+            {"role": "user", "content": "Thanks"},                        # 14
+        ]
+        # 15 messages. compress_end = 15 - 4 = 11 (before fix: splits tool group)
+
+        fake_summary = "[Summary of earlier conversation]"
+        with patch.object(comp, "_generate_summary", return_value=fake_summary):
+            result = comp.compress(messages, current_tokens=7000)
+
+        # After compression, no tool results should be orphaned/lost.
+        # All tool results in the result must have a matching assistant tool_call.
+        assistant_call_ids = set()
+        for msg in result:
+            if msg.get("role") == "assistant":
+                for tc in msg.get("tool_calls") or []:
+                    cid = tc.get("id", "")
+                    if cid:
+                        assistant_call_ids.add(cid)
+
+        tool_result_ids = set()
+        for msg in result:
+            if msg.get("role") == "tool":
+                cid = msg.get("tool_call_id")
+                if cid:
+                    tool_result_ids.add(cid)
+
+        # Every tool result must have a parent — no orphans
+        orphaned = tool_result_ids - assistant_call_ids
+        assert not orphaned, f"Orphaned tool results found (data loss!): {orphaned}"
+
+        # Every assistant tool_call must have a real result (not a stub)
+        for msg in result:
+            if msg.get("role") == "tool":
+                assert msg["content"] != "[Result from earlier conversation — see context summary above]", \
+                    f"Stub result found for {msg.get('tool_call_id')} — real result was lost"

tests/agent/test_compression_concurrent_fork.py

@@ -0,0 +1,2403 @@
+"""Regression: prevent transcript fork when two paths compress the same session_id.
+
+Damien's incident (Discord, 2026-05-28): a long Hermes session in a Discord
+gateway hit the compression threshold at the end of a turn.  The parent agent
+finished delivering the response and ``conversation_loop.py`` fired
+``_spawn_background_review(...)`` — which builds a forked ``AIAgent`` that
+inherits ``agent.session_id`` (see ``agent/background_review.py``::
+``review_agent.session_id = agent.session_id``).  Roughly two seconds later
+a synthetic ``Background process proc_… completed`` event arrived and
+started a fresh turn on the same parent ``session_id`` (still cached in the
+gateway's ``SessionEntry``).  Both paths hit preflight compression on the
+same parent transcript and called ``_compress_context`` concurrently.  Each
+ended the parent and created its own CHILD session in ``state.db``, both
+parented to the same old id.  The gateway's ``SessionEntry`` only caught one
+rotation; the other child became an orphan that silently accumulated writes.
+
+Repro shape on Damien's machine:
+
+  parent 20260527_234659_e65f0e  ended_at=set  end_reason='compression'
+  child  20260528_113619_fc80e1  parent=20260527_234659_e65f0e  (in SessionEntry)
+  child  <orphan>                parent=20260527_234659_e65f0e  (silent writes)
+
+This regression simulates the two concurrent ``compress_context`` calls
+against a shared ``state.db`` and asserts that the per-session compression
+lock added in this PR prevents the orphan child.  Without the lock the
+fixture deterministically produces 2 children; with the lock, exactly 1.
+"""
+
+from __future__ import annotations
+
+import copy
+import inspect
+import json
+import logging
+import os
+import sqlite3
+import threading
+import time
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hermes_state import SessionDB
+
+
+def _build_agent_with_db(
+    db: SessionDB,
+    session_id: str,
+    *,
+    stub_compressor: bool = True,
+):
+    """Build an AIAgent that's wired to ``db`` and pinned to ``session_id``."""
+    with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}):
+        from run_agent import AIAgent
+
+        agent = AIAgent(
+            api_key="test-key",
+            base_url="https://openrouter.ai/api/v1",
+            model="test/model",
+            quiet_mode=True,
+            session_db=db,
+            session_id=session_id,
+            skip_context_files=True,
+            skip_memory=True,
+        )
+
+    # Stub the compressor so it returns deterministic output and DOESN'T make
+    # an LLM call.  Sleep inside compress() so the two threads' rotations
+    # actually overlap — without that the OS could happen to serialize them
+    # and hide the bug.
+    if not stub_compressor:
+        return agent
+
+    compressor = MagicMock()
+
+    def _compress_with_overlap(*_a, **_kw):
+        time.sleep(0.15)
+        return [
+            {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+            {"role": "user", "content": "tail"},
+        ]
+
+    compressor.compress.side_effect = _compress_with_overlap
+    compressor.compression_count = 1
+    compressor.last_prompt_tokens = 0
+    compressor.last_completion_tokens = 0
+    compressor._last_summary_error = None
+    compressor._last_compress_aborted = False
+    compressor._last_aux_model_failure_model = None
+    compressor._last_aux_model_failure_error = None
+    agent.context_compressor = compressor
+    # The compressor is a stub — the one-time compression-model feasibility
+    # probe would resolve a REAL auxiliary provider (credential pools, live
+    # token exchanges over the network on some dev machines). That makes the
+    # first _compress_context call in a test nondeterministically slow (>2s)
+    # and flakes event-based timing assertions. Mark it done: these tests
+    # exercise locking/fencing/rotation, never aux-model feasibility.
+    agent._compression_feasibility_checked = True
+    # These tests cover the ROTATION fallback path (forking, child sessions,
+    # lock contention) — pin in_place=False so they keep exercising it
+    # regardless of the global default (which flipped to True in #38763).
+    agent.compression_in_place = False
+    return agent
+
+
+def _count_children(db: SessionDB, parent_sid: str) -> int:
+    """Count rows in state.db whose parent_session_id == parent_sid."""
+    rows = db._conn.execute(
+        "SELECT id FROM sessions WHERE parent_session_id = ?",
+        (parent_sid,),
+    ).fetchall()
+    return len(rows)
+
+
+def _live_child_id(db: SessionDB, parent_sid: str) -> str | None:
+    """The single child id of ``parent_sid``, or None when there is none.
+
+    Fails loudly on more than one child: callers use this to prove the agents
+    converged on the winner's session, so a multi-child state is a fork and
+    must not be silently reduced to 'the first row'.
+    """
+    rows = db._conn.execute(
+        "SELECT id FROM sessions WHERE parent_session_id = ?",
+        (parent_sid,),
+    ).fetchall()
+    assert len(rows) <= 1, f"expected at most one child of {parent_sid}, got {rows!r}"
+    return rows[0][0] if rows else None
+
+
+def _wait_for_touch(touch_calls: list[str], value: str, timeout: float = 1.0) -> None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if value in touch_calls:
+            return
+        time.sleep(0.01)
+    pytest.fail(f"Timed out waiting for touch activity {value!r}; calls={touch_calls!r}")
+
+
+def test_compression_activity_heartbeat_touches_agent_during_long_compress(tmp_path: Path) -> None:
+    """Long compression must refresh agent activity so gateway watchdogs do not fire."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HEARTBEAT_TEST"
+    db.create_session(session_id, source="test")
+
+    agent = _build_agent_with_db(db, session_id)
+    agent._compression_activity_heartbeat_interval = 0.1
+    touch_calls: list[str] = []
+    agent._touch_activity = lambda desc, **_kw: touch_calls.append(desc)
+
+    def _slow_compress(*_a, **_kw):
+        _wait_for_touch(touch_calls, "context compression in progress")
+        return [
+            {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+            {"role": "user", "content": "tail"},
+        ]
+
+    agent.context_compressor.compress.side_effect = _slow_compress
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert touch_calls[0] == "context compression started"
+    assert "context compression in progress" in touch_calls
+    assert touch_calls[-1] == "context compression completed"
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_compression_activity_heartbeat_emits_client_status_events(tmp_path: Path) -> None:
+    """The heartbeat must re-emit the compacting status, not just DB touches.
+
+    Remote transports (e.g. the Android relay app) run idle-progress turn
+    watchdogs that ``session.interrupt`` a turn after ~180s with no gateway
+    events. Compression is silent on the event stream, so without periodic
+    status heartbeats a long compression is killed mid-flight and retriggers
+    forever on sessions near the context ceiling.
+    """
+    from agent.conversation_compression import (
+        COMPACTION_HEARTBEAT_STATUS,
+        is_compaction_progress_status,
+    )
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HEARTBEAT_STATUS_TEST"
+    db.create_session(session_id, source="test")
+
+    agent = _build_agent_with_db(db, session_id)
+    agent._compression_activity_heartbeat_interval = 0.1
+    touch_calls: list[str] = []
+    agent._touch_activity = lambda desc, **_kw: touch_calls.append(desc)
+    status_events: list[tuple[str, str]] = []
+    setattr(
+        agent,
+        "status_callback",
+        lambda event, message: status_events.append((event, message)),
+    )
+
+    def _slow_compress(*_a, **_kw):
+        _wait_for_touch(touch_calls, "context compression in progress")
+        return [
+            {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+            {"role": "user", "content": "tail"},
+        ]
+
+    agent.context_compressor.compress.side_effect = _slow_compress
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    heartbeats = [e for e in status_events if e[1] == COMPACTION_HEARTBEAT_STATUS]
+    assert heartbeats, "no heartbeat status reached the client"
+    # Same "lifecycle" key as the other compaction statuses so the TUI gateway
+    # re-tags it to kind="compacting" and Telegram edits one bubble in place.
+    assert {event for event, _ in heartbeats} == {"lifecycle"}
+    assert is_compaction_progress_status(COMPACTION_HEARTBEAT_STATUS)
+    # Exactly one routine start line precedes the first heartbeat; the
+    # heartbeat no longer re-emits a start of its own (adapters without
+    # send_or_update_status would otherwise post two messages).
+    assert status_events[0][1] != COMPACTION_HEARTBEAT_STATUS
+    # Every heartbeat is a periodic tick: none may precede the first
+    # "in progress" DB touch, which is what start() would have produced.
+    first_tick_touch = touch_calls.index("context compression in progress")
+    assert first_tick_touch >= 1  # "started" touch came first
+    assert len(heartbeats) <= touch_calls.count("context compression in progress")
+
+
+def test_compression_heartbeat_is_silent_for_quiet_context_engines(tmp_path: Path) -> None:
+    """A context engine that suppresses the routine start status opens no
+    visible compaction phase; the heartbeat must not open one either (there
+    would be no terminal edge to close it)."""
+    from agent.conversation_compression import COMPACTION_HEARTBEAT_STATUS
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HEARTBEAT_QUIET_TEST"
+    db.create_session(session_id, source="test")
+
+    agent = _build_agent_with_db(db, session_id)
+    agent._compression_activity_heartbeat_interval = 0.1
+    touch_calls: list[str] = []
+    agent._touch_activity = lambda desc, **_kw: touch_calls.append(desc)
+    status_events: list[tuple[str, str]] = []
+    setattr(
+        agent,
+        "status_callback",
+        lambda event, message: status_events.append((event, message)),
+    )
+
+    def _slow_compress(*_a, **_kw):
+        _wait_for_touch(touch_calls, "context compression in progress")
+        return [
+            {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+            {"role": "user", "content": "tail"},
+        ]
+
+    agent.context_compressor.compress.side_effect = _slow_compress
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    with patch(
+        "agent.conversation_compression.automatic_compaction_status_message",
+        return_value="",
+    ):
+        agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert all(m != COMPACTION_HEARTBEAT_STATUS for _, m in status_events)
+    assert "context compression in progress" in touch_calls  # DB touches still ran
+
+
+def test_lock_contender_preserves_terminal_compaction_lifecycle(tmp_path: Path) -> None:
+    """A lock loser still closes the structured compaction lifecycle.
+
+    The gateway independently filters this routine notice for chat surfaces
+    unless ``compression.progress_notices`` is enabled.  The low-level event
+    must remain available so the desktop can retire its compaction phase.
+    """
+    from agent.conversation_compression import COMPACTION_DONE_STATUS
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "LOCK_CONTENDER_STATUS_TEST"
+    db.create_session(session_id, source="discord")
+    assert db.try_acquire_compression_lock(session_id, "winner", ttl_seconds=60)
+
+    agent = _build_agent_with_db(db, session_id)
+    status_events: list[tuple[str, str]] = []
+    setattr(
+        agent,
+        "status_callback",
+        lambda event, message: status_events.append((event, message)),
+    )
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    returned, _system_prompt = agent._compress_context(
+        messages,
+        "sys",
+        approx_tokens=120_000,
+    )
+
+    assert returned is messages
+    assert getattr(agent, "_compression_skipped_due_to_lock", None) == "winner"
+    assert status_events.count(("compacted", COMPACTION_DONE_STATUS)) == 1
+
+
+def test_failed_session_split_does_not_announce_compaction_complete(tmp_path: Path) -> None:
+    """A failed durable split must not emit a successful completion edge."""
+    from agent.conversation_compression import COMPACTION_DONE_STATUS
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "FAILED_SPLIT_STATUS_TEST"
+    db.create_session(session_id, source="discord")
+    agent = _build_agent_with_db(db, session_id)
+    setattr(agent, "compression_in_place", False)
+    db.publish_compression_child = MagicMock(side_effect=RuntimeError("split boom"))
+    status_events: list[tuple[str, str]] = []
+    setattr(
+        agent,
+        "status_callback",
+        lambda event, message: status_events.append((event, message)),
+    )
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    agent._compress_context(
+        messages,
+        "sys",
+        approx_tokens=120_000,
+        force=True,
+    )
+
+    db.publish_compression_child.assert_called_once()
+    assert ("compacted", COMPACTION_DONE_STATUS) not in status_events
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_failed_in_place_split_does_not_announce_compaction_complete(tmp_path: Path) -> None:
+    """An in-place persistence failure must not emit a completion edge."""
+    from agent.conversation_compression import COMPACTION_DONE_STATUS
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "FAILED_IN_PLACE_STATUS_TEST"
+    db.create_session(session_id, source="discord")
+    agent = _build_agent_with_db(db, session_id)
+    setattr(agent, "compression_in_place", True)
+    db.archive_and_compact = MagicMock(side_effect=RuntimeError("archive boom"))
+    status_events: list[tuple[str, str]] = []
+    setattr(
+        agent,
+        "status_callback",
+        lambda event, message: status_events.append((event, message)),
+    )
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    agent._compress_context(
+        messages,
+        "sys",
+        approx_tokens=120_000,
+        force=True,
+    )
+
+    db.archive_and_compact.assert_called_once()
+    assert ("compacted", COMPACTION_DONE_STATUS) not in status_events
+    assert getattr(agent, "session_id", None) == session_id
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_compression_activity_heartbeat_stops_on_compress_exception(tmp_path: Path) -> None:
+    """Exception paths must stop the heartbeat and release the compression lock."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HEARTBEAT_FAIL_TEST"
+    db.create_session(session_id, source="test")
+
+    agent = _build_agent_with_db(db, session_id)
+    agent._compression_activity_heartbeat_interval = 0.1
+    touch_calls: list[str] = []
+    agent._touch_activity = lambda desc, **_kw: touch_calls.append(desc)
+
+    def _failing_compress(*_a, **_kw):
+        _wait_for_touch(touch_calls, "context compression in progress")
+        raise RuntimeError("compress boom")
+
+    agent.context_compressor.compress.side_effect = _failing_compress
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    with pytest.raises(RuntimeError, match="compress boom"):
+        agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert touch_calls[0] == "context compression started"
+    assert "context compression in progress" in touch_calls
+    assert touch_calls[-1] == "context compression failed"
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_compression_activity_heartbeat_ignores_touch_errors(tmp_path: Path) -> None:
+    """Activity touch failures must not affect compression success semantics."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HEARTBEAT_TOUCH_ERROR_TEST"
+    db.create_session(session_id, source="test")
+
+    agent = _build_agent_with_db(db, session_id)
+    agent._compression_activity_heartbeat_interval = 0.1
+    agent._touch_activity = lambda _desc, **_kw: (_ for _ in ()).throw(RuntimeError("touch boom"))
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    compressed, _sp = agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert compressed[0]["content"] == "[CONTEXT COMPACTION] summary"
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_compression_activity_heartbeat_strict_signature_fallback_releases_lock(tmp_path: Path) -> None:
+    """Strict compressor signatures still compress while heartbeat cleanup runs.
+
+    Main inspects the engine signature up front (_supported_compression_kwargs)
+    instead of catching TypeError, so a strict-signature engine is invoked
+    exactly once with only the kwargs it accepts. The heartbeat (with a
+    non-numeric configured interval falling back to the default) must still
+    wrap the call and stop cleanly.
+    """
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HEARTBEAT_TYPEERROR_TEST"
+    db.create_session(session_id, source="test")
+
+    agent = _build_agent_with_db(db, session_id)
+    agent._compression_activity_heartbeat_interval = "not-a-number"
+    touch_calls: list[str] = []
+    agent._touch_activity = lambda desc, **_kw: touch_calls.append(desc)
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    strict_calls: list[int | None] = []
+
+    def _strict_compress(messages, current_tokens=None):
+        strict_calls.append(current_tokens)
+        return [
+            {"role": "user", "content": "[CONTEXT COMPACTION] strict summary"},
+            {"role": "user", "content": "tail"},
+        ]
+
+    agent.context_compressor.compress = _strict_compress
+
+    compressed, _sp = agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert compressed[0]["content"] == "[CONTEXT COMPACTION] strict summary"
+    assert touch_calls[0] == "context compression started"
+    assert touch_calls[-1] == "context compression completed"
+    assert db.get_compression_lock_holder(session_id) is None
+    assert strict_calls == [120_000]
+
+
+def test_compression_activity_heartbeat_nonfinite_interval_falls_back(tmp_path: Path) -> None:
+    """Non-finite heartbeat intervals must not reach Event.wait()."""
+    from agent.conversation_compression import _CompressionActivityHeartbeat
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HEARTBEAT_NONFINITE_INTERVAL_TEST"
+    db.create_session(session_id, source="test")
+
+    agent = _build_agent_with_db(db, session_id)
+    touch_calls: list[str] = []
+    touch_provenances: list = []
+
+    def _capture(desc, *, provenance=None, force_persist=False):
+        touch_calls.append(desc)
+        touch_provenances.append(provenance)
+
+    agent._touch_activity = _capture
+
+    heartbeat = _CompressionActivityHeartbeat(agent, interval_seconds=float("inf"))
+
+    assert heartbeat._interval_seconds == 60.0
+    heartbeat.start()
+    heartbeat.stop()
+    assert touch_calls == ["context compression started", "context compression completed"]
+    from agent.session_activity import ActivityProvenance
+
+    assert touch_provenances == [
+        ActivityProvenance.AGENT_COMPRESSION,
+        ActivityProvenance.AGENT_COMPRESSION,
+    ]
+
+
+def test_compression_heartbeat_stop_persists_completed_over_in_progress(
+    tmp_path: Path,
+) -> None:
+    """/compress is outside run_conversation, so turn-end clear never runs.
+
+    Heartbeat progress stamps persist to SessionDB; completion is often
+    rate-limited out. stop() must force-persist the terminal label so idle
+    sessions show "context compression completed", not a stale "in progress".
+    """
+    from agent.conversation_compression import _CompressionActivityHeartbeat
+    from agent.session_activity import ActivityProvenance
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HEARTBEAT_PERSIST_COMPLETED_TEST"
+    db.create_session(session_id, source="test")
+
+    agent = _build_agent_with_db(db, session_id)
+    # Long interval: only start/stop touch; we inject the progress stamp.
+    hb = _CompressionActivityHeartbeat(agent, interval_seconds=3600.0)
+    hb.start()
+
+    agent._session_activity_last_persist_mono = 0.0
+    agent._touch_activity(
+        "context compression in progress",
+        provenance=ActivityProvenance.AGENT_COMPRESSION,
+    )
+    row = db.get_session(session_id)
+    assert row["last_activity_description"] == "context compression in progress"
+    assert row["last_activity_provenance"] == ActivityProvenance.AGENT_COMPRESSION.value
+
+    # Mimic the common case: completion falls inside the 60s persist window.
+    agent._session_activity_last_persist_mono = time.monotonic()
+    hb.stop("context compression completed")
+
+    row = db.get_session(session_id)
+    assert row["last_activity_description"] == "context compression completed"
+    assert row["last_activity_provenance"] == ActivityProvenance.AGENT_COMPRESSION.value
+    assert agent._last_activity_desc == "context compression completed"
+    assert agent._last_activity_provenance is ActivityProvenance.AGENT_COMPRESSION
+
+
+def test_compression_heartbeat_does_not_clobber_timeout_provenance() -> None:
+    """Detached heartbeat/stop must not overwrite a host timeout stamp."""
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import _CompressionActivityHeartbeat
+    from agent.session_activity import ActivityProvenance
+
+    agent = SimpleNamespace(
+        _last_activity_provenance=ActivityProvenance.AGENT_COMPRESSION_TIMEOUT,
+        _last_activity_desc="context compression timed out",
+        touches=[],
+    )
+
+    def _touch(desc, *, provenance=None, force_persist=False):
+        agent.touches.append((desc, provenance))
+        agent._last_activity_provenance = provenance
+        agent._last_activity_desc = desc
+
+    agent._touch_activity = _touch
+
+    hb = _CompressionActivityHeartbeat(agent, interval_seconds=60.0)
+    hb._touch("context compression in progress")
+    hb.stop("context compression completed")
+
+    assert agent.touches == []
+    assert agent._last_activity_provenance is ActivityProvenance.AGENT_COMPRESSION_TIMEOUT
+    assert agent._last_activity_desc == "context compression timed out"
+
+
+def test_compression_heartbeat_does_not_clobber_cooldown_provenance() -> None:
+    """Cooldown/abort stamps must also survive a late heartbeat stop."""
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import _CompressionActivityHeartbeat
+    from agent.session_activity import ActivityProvenance
+
+    agent = SimpleNamespace(
+        _last_activity_provenance=ActivityProvenance.AGENT_COMPRESSION_COOLDOWN,
+        _last_activity_desc="compression blocked (cooldown: 30s remaining)",
+        touches=[],
+    )
+
+    def _touch(desc, *, provenance=None, force_persist=False):
+        agent.touches.append((desc, provenance))
+        agent._last_activity_provenance = provenance
+        agent._last_activity_desc = desc
+
+    agent._touch_activity = _touch
+
+    hb = _CompressionActivityHeartbeat(agent, interval_seconds=60.0)
+    hb._touch("context compression in progress")
+    hb.stop("context compression failed")
+
+    assert agent.touches == []
+    assert agent._last_activity_provenance is ActivityProvenance.AGENT_COMPRESSION_COOLDOWN
+
+
+def test_compression_heartbeat_start_republishes_after_terminal_provenance() -> None:
+    """A new compression episode may overwrite a prior timeout/cooldown stamp."""
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import _CompressionActivityHeartbeat
+    from agent.session_activity import ActivityProvenance
+
+    agent = SimpleNamespace(
+        _last_activity_provenance=ActivityProvenance.AGENT_COMPRESSION_TIMEOUT,
+        _last_activity_desc="context compression timed out",
+        touches=[],
+    )
+
+    def _touch(desc, *, provenance=None, force_persist=False):
+        agent.touches.append((desc, provenance))
+        agent._last_activity_provenance = provenance
+        agent._last_activity_desc = desc
+
+    agent._touch_activity = _touch
+
+    hb = _CompressionActivityHeartbeat(agent, interval_seconds=60.0)
+    hb.start()
+    hb.stop()
+
+    assert agent.touches[0] == (
+        "context compression started",
+        ActivityProvenance.AGENT_COMPRESSION,
+    )
+    assert agent.touches[-1] == (
+        "context compression completed",
+        ActivityProvenance.AGENT_COMPRESSION,
+    )
+    assert agent._last_activity_provenance is ActivityProvenance.AGENT_COMPRESSION
+
+
+def test_compression_heartbeat_does_not_rearm_after_unknown_provenance() -> None:
+    """After a terminal stamp, UNKNOWN must not re-arm a detached heartbeat."""
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import _CompressionActivityHeartbeat
+    from agent.session_activity import ActivityProvenance
+
+    agent = SimpleNamespace(
+        _last_activity_provenance=ActivityProvenance.AGENT_COMPRESSION_TIMEOUT,
+        _last_activity_desc="context compression timed out",
+        touches=[],
+    )
+
+    def _touch(desc, *, provenance=None, force_persist=False):
+        agent.touches.append((desc, provenance))
+        agent._last_activity_provenance = provenance
+        agent._last_activity_desc = desc
+
+    agent._touch_activity = _touch
+
+    hb = _CompressionActivityHeartbeat(agent, interval_seconds=60.0)
+    # First tick observes TIMEOUT and latches silent.
+    hb._touch("context compression in progress")
+    assert hb._suppressed is True
+    # Turn continues / ends and clears labels to UNKNOWN — must stay silent.
+    agent._last_activity_provenance = ActivityProvenance.UNKNOWN
+    agent._last_activity_desc = "calling model"
+    hb._touch("context compression in progress")
+    hb.stop("context compression completed")
+
+    assert agent.touches == []
+    assert agent._last_activity_provenance is ActivityProvenance.UNKNOWN
+    assert agent._last_activity_desc == "calling model"
+
+
+def test_compression_heartbeat_stops_when_commit_fence_cancelled() -> None:
+    """Host fence cancel must silence detached heartbeat refresh and late stop."""
+    from types import SimpleNamespace
+
+    from agent.conversation_compression import (
+        CompressionCommitFence,
+        _CompressionActivityHeartbeat,
+    )
+    from agent.session_activity import ActivityProvenance
+
+    agent = SimpleNamespace(
+        _last_activity_provenance=ActivityProvenance.AGENT_COMPRESSION,
+        _last_activity_desc="context compression started",
+        touches=[],
+    )
+
+    def _touch(desc, *, provenance=None, force_persist=False):
+        agent.touches.append((desc, provenance))
+        agent._last_activity_provenance = provenance
+        agent._last_activity_desc = desc
+
+    agent._touch_activity = _touch
+
+    fence = CompressionCommitFence()
+    assert fence.cancel_before_commit() is True
+
+    hb = _CompressionActivityHeartbeat(
+        agent, interval_seconds=60.0, commit_fence=fence
+    )
+    hb._touch("context compression in progress")
+    hb.stop("context compression completed")
+
+    assert agent.touches == []
+    assert hb._suppressed is True
+    assert agent._last_activity_provenance is ActivityProvenance.AGENT_COMPRESSION
+    assert agent._last_activity_desc == "context compression started"
+
+
+def test_concurrent_compression_does_not_fork_session(tmp_path: Path) -> None:
+    """Two AIAgents that share a session_id MUST NOT both rotate it.
+
+    Without the per-session compression lock this fixture deterministically
+    produces 2 child sessions (transcript fork). With the lock at most one
+    path rotates: normally exactly 1 canonical child, or — under heavy DB
+    write contention that makes the winner's child create_session exhaust its
+    retries — 0, because _compress_context safely rolls back to the parent
+    instead of orphaning a child. The forbidden outcome is 2+ (the fork).
+    """
+    db = SessionDB(db_path=tmp_path / "state.db")
+
+    parent_sid = "PARENT_TEST_SESSION"
+    db.create_session(parent_sid, source="discord")
+
+    # Two agents on the same session_id, both wired to the same db —
+    # mirrors the parent-turn agent + the background-review fork right
+    # after a turn ends.
+    agent_a = _build_agent_with_db(db, parent_sid)
+    agent_b = _build_agent_with_db(db, parent_sid)
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    def run(agent):
+        try:
+            agent._compress_context(messages, "sys", approx_tokens=120_000)
+        except Exception:
+            # Surface to the test if either raises — should not happen.
+            raise
+
+    t_a = threading.Thread(target=run, args=(agent_a,), name="main_turn")
+    t_b = threading.Thread(target=run, args=(agent_b,), name="review_fork")
+    t_a.start()
+    t_b.start()
+    t_a.join(timeout=10)
+    t_b.join(timeout=10)
+
+    # The invariant Damien's incident is about: the parent must NEVER end up
+    # with two (or more) children — that is the transcript fork. The lock
+    # guarantees only one path rotates.
+    #
+    # Zero children is also a valid, non-forking outcome: under heavy DB write
+    # contention the winner's child ``create_session`` can exhaust its retry
+    # budget, and ``_compress_context`` deliberately rolls the live id back to
+    # the (still-indexed) parent rather than stranding an orphan child — see
+    # the create-failure rollback in agent/conversation_compression.py. That
+    # safe rollback leaves 0 children and is correct. So the contract is
+    # ``children <= 1``; only ``>= 2`` is the bug. Asserting an exact ``== 1``
+    # made this test flaky under the concurrent CI load that triggers the
+    # contention rollback (#54465 churn surfaced it).
+    n_children = _count_children(db, parent_sid)
+    assert n_children <= 1, (
+        f"Compression lock failed: parent session has {n_children} children in "
+        "state.db (transcript fork). This is Damien's incident shape — see the "
+        "test docstring. Two or more children means the lock did not serialize "
+        "the concurrent rotations."
+    )
+
+    # Every agent that moved off the parent must have landed on the SAME id.
+    # Counting movers is the wrong contract: the loser can legitimately end up
+    # on the child too, without rotating anything itself — it takes the lock
+    # after the winner released it, sees the parent was already rotated, and
+    # _adopt_live_compression_child() points it at the winner's single child
+    # (the "compression recovery: stale session=... adopted live child=..."
+    # path). That convergence is the fix working, not a fork; the fork is two
+    # DIFFERENT live ids. Asserting ``movers <= 1`` failed on that healthy
+    # outcome under concurrent load.
+    moved = {a.session_id for a in (agent_a, agent_b) if a.session_id != parent_sid}
+    assert len(moved) <= 1, (
+        f"Expected at most one post-compression session id, got {sorted(moved)}. "
+        "Two distinct ids means the lock didn't serialize them (transcript fork)."
+    )
+    assert len(moved) == n_children, (
+        f"Inconsistent state: agents live on {sorted(moved)} but {n_children} "
+        "child session(s) exist — rotation and child creation diverged."
+    )
+    if moved:
+        child = _live_child_id(db, parent_sid)
+        assert moved == {child}, (
+            f"Agents live on {sorted(moved)} but the parent's only child is "
+            f"{child} — an agent is writing to a session outside the lineage."
+        )
+
+    # The lock must be released after both paths finished, regardless of
+    # whether the winner committed a child or rolled back.
+    assert db.get_compression_lock_holder(parent_sid) is None, (
+        "Compression lock leaked: still held after both paths completed."
+    )
+
+
+def test_durable_message_committed_before_lease_is_adopted(
+    tmp_path: Path,
+) -> None:
+    """A durable row absent from the caller snapshot must still be compressed.
+
+    Previously this path aborted and returned the stale snapshot unchanged,
+    which permanently wedged busy sessions: every compress attempt saw the
+    DB ahead of the in-memory list, logged "changed before lease
+    acquisition", and never called the compressor. Adopting the durable
+    transcript keeps the late-committed turn and lets compression proceed.
+    """
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "PRE_LEASE_DURABLE_RACE"
+    db.create_session(parent_sid, source="webui")
+    db.append_message(parent_sid, "user", "old durable")
+
+    # Frontend takes its snapshot, then another producer commits before this
+    # compressor acquires the lease.
+    stale_snapshot = [{"role": "user", "content": "old durable"}]
+    db.append_message(parent_sid, "assistant", "late committed before lease")
+    agent = _build_agent_with_db(db, parent_sid)
+
+    returned, _system_prompt = agent._compress_context(
+        stale_snapshot, "sys", approx_tokens=120_000
+    )
+
+    agent.context_compressor.compress.assert_called_once()
+    compressed_arg = agent.context_compressor.compress.call_args.args[0]
+    assert [m["content"] for m in compressed_arg] == [
+        "old durable",
+        "late committed before lease",
+    ]
+    # Must not echo the stale snapshot — compression proceeded on the
+    # adopted durable transcript (rotation publishes a child session).
+    assert returned is not stale_snapshot
+    assert returned[0]["content"] == "[CONTEXT COMPACTION] summary"
+    assert agent.session_id != parent_sid
+    child_id = _live_child_id(db, parent_sid)
+    assert child_id is not None
+    assert child_id == agent.session_id
+
+
+
+
+
+def test_fence_cancelled_compression_leaves_lock_reacquirable(tmp_path: Path) -> None:
+    """A fence-cancelled attempt must not poison the per-session lock.
+
+    Lock-release verification for the hygiene-timeout path: after the gateway
+    times out and cancels a hygiene compression at the commit fence, the very
+    next attempt on the same session (e.g. the user running ``/compress``)
+    must acquire the compression lock and commit normally. A leaked lock here
+    would silently block every future compaction for the session until TTL
+    expiry.
+    """
+    from agent.conversation_compression import CompressionCommitFence
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HYGIENE_LOCK_REACQUIRE"
+    db.create_session(session_id, source="telegram")
+
+    agent = _build_agent_with_db(db, session_id)
+    agent.compression_in_place = True
+    agent._cached_system_prompt = "sys"
+    summary_started = threading.Event()
+    release_summary = threading.Event()
+
+    def _slow_summary(*_args, **_kwargs):
+        summary_started.set()
+        assert release_summary.wait(timeout=5)
+        agent.context_compressor._proactive_prune_rearm_tokens = 0
+        return [
+            {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+            {"role": "user", "content": "tail"},
+        ]
+
+    agent.context_compressor.compress.side_effect = _slow_summary
+    agent.context_compressor._proactive_prune_rearm_tokens = 120_000
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    fence = CompressionCommitFence()
+    result = {}
+
+    def _run_compression() -> None:
+        result["value"] = agent._compress_context(
+            messages,
+            "sys",
+            approx_tokens=120_000,
+            commit_fence=fence,
+        )
+
+    worker = threading.Thread(target=_run_compression, name="fenced-hygiene")
+    worker.start()
+    assert summary_started.wait(timeout=2)
+    assert fence.cancel_before_commit() is True
+    release_summary.set()
+    worker.join(timeout=5)
+    assert not worker.is_alive()
+
+    # Cancelled attempt: no mutation, and — the invariant under test — the
+    # per-session compression lock is fully released.
+    assert result["value"][0] is messages
+    assert agent.context_compressor._proactive_prune_rearm_tokens == 120_000
+    assert db.get_compression_lock_holder(session_id) is None
+
+    # The NEXT attempt (no fence — a manual /compress retry) must be able to
+    # acquire the lock and commit an in-place compaction normally.
+    agent.context_compressor.compress.side_effect = lambda *_a, **_kw: [
+        {"role": "user", "content": "[CONTEXT COMPACTION] retry summary"},
+        {"role": "user", "content": "tail"},
+    ]
+    retried, _sp = agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert retried is not messages
+    assert len(retried) < len(messages)
+    assert agent.session_id == session_id  # in-place: same session id
+    assert agent._last_compaction_in_place is True
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_commit_fence_waits_for_an_active_commit() -> None:
+    """A timeout that loses the fence race cannot overlap the live turn."""
+    from agent.conversation_compression import CompressionCommitFence
+
+    fence = CompressionCommitFence()
+    assert fence.begin_commit() is True
+    assert fence.try_cancel_before_commit() is None
+    cancel_started = threading.Event()
+    cancel_finished = threading.Event()
+    result = {}
+
+    def _cancel() -> None:
+        cancel_started.set()
+        result["cancelled"] = fence.cancel_before_commit()
+        cancel_finished.set()
+
+    waiter = threading.Thread(target=_cancel, name="hygiene-timeout-fence")
+    waiter.start()
+    try:
+        assert cancel_started.wait(timeout=2)
+        assert not cancel_finished.is_set()
+    finally:
+        fence.finish_commit()
+    waiter.join(timeout=2)
+
+    assert not waiter.is_alive()
+    assert result["cancelled"] is False
+
+
+def test_total_deadline_cancellation_retains_lock_until_worker_cleanup() -> None:
+    """A total-ceiling timeout must exclude retries while its worker is alive."""
+    from agent.conversation_compression import CompressionCommitFence
+
+    released = threading.Event()
+    fence = CompressionCommitFence(total_ceiling_seconds=1.0)
+    fence.register_cancelled_lock_release(released.set)
+    fence.retain_compression_lock_until_worker_done()
+
+    now = time.monotonic()
+    with patch(
+        "agent.conversation_compression.time.monotonic",
+        return_value=now + 2.0,
+    ):
+        assert fence.is_cancelled
+        assert fence.try_cancel_before_commit() is True
+    fence.release_cancelled_compression_lock()
+
+    assert not released.is_set()
+
+
+def test_delayed_contender_adopts_unique_rotated_child(tmp_path: Path) -> None:
+    """A stale agent must continue on the winner's compacted child transcript."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "STALE_PARENT"
+    child_sid = "CANONICAL_CHILD"
+    db.create_session(parent_sid, source="webui")
+    db.end_session(parent_sid, "compression")
+    db.create_session(child_sid, source="webui", parent_session_id=parent_sid)
+    compacted = [
+        {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+        {"role": "assistant", "content": "compacted tail"},
+    ]
+    db.replace_messages(child_sid, compacted)
+
+    agent = _build_agent_with_db(db, parent_sid)
+    stale_messages = [
+        {"role": "user", "content": "stale"},
+        {"role": "assistant", "content": "x" * 1000},
+    ]
+    recovered, _system_prompt = agent._compress_context(
+        stale_messages, "sys", approx_tokens=120_000
+    )
+
+    assert agent.session_id == child_sid
+    assert [(m["role"], m["content"]) for m in recovered] == [
+        ("user", "[CONTEXT COMPACTION] summary"),
+        ("assistant", "compacted tail"),
+    ]
+    assert agent._session_db_created is True
+    assert agent._flushed_db_message_session_id == child_sid
+    assert agent._last_flushed_db_idx == len(recovered)
+    agent.context_compressor.compress.assert_not_called()
+    lifecycle_args, lifecycle_kwargs = agent.context_compressor.on_session_start.call_args
+    assert lifecycle_args == (child_sid,)
+    assert lifecycle_kwargs["boundary_reason"] == "compression"
+    assert lifecycle_kwargs["old_session_id"] == parent_sid
+    assert lifecycle_kwargs["session_db"] is db
+
+
+
+
+
+
+
+
+def _no_consecutive_user_roles(messages: list) -> bool:
+    roles = [m.get("role") for m in messages if isinstance(m, dict)]
+    return all(
+        not (roles[i] == roles[i + 1] == "user") for i in range(len(roles) - 1)
+    )
+
+
+def test_restored_anchor_never_creates_consecutive_user_roles() -> None:
+    """Anchor restoration must preserve strict role alternation (#55677).
+
+    The original insertion helper could land the human anchor directly next
+    to user-role scaffolding (index-0 insert before a leading synthetic user
+    turn, or a bare scaffolding-only transcript), producing user/user
+    adjacency that strict chat templates reject.
+    """
+    from agent.conversation_compression import _insert_real_user_anchor
+
+    anchor = {"role": "user", "content": "REAL HUMAN ASK"}
+
+    # Leading synthetic user turn before the assistant summary.
+    compressed = [
+        {
+            "role": "user",
+            "content": "[System: Your previous response was truncated ...]",
+            "_empty_recovery_synthetic": True,
+        },
+        {"role": "assistant", "content": "summary"},
+        {
+            "role": "user",
+            "content": "[Your active task list was preserved across context compression]",
+            "_todo_snapshot_synthetic": True,
+        },
+    ]
+    _insert_real_user_anchor(compressed, dict(anchor))
+    assert _no_consecutive_user_roles(compressed)
+    assert any(m.get("content", "").startswith("REAL HUMAN ASK") for m in compressed)
+
+    # Scaffolding-only transcript: the anchor is merged, not inserted
+    # adjacent, and the merged turn leads with the human ask.
+    compressed = [
+        {
+            "role": "user",
+            "content": "[Your active task list was preserved across context compression]",
+            "_todo_snapshot_synthetic": True,
+        },
+    ]
+    _insert_real_user_anchor(compressed, dict(anchor))
+    assert _no_consecutive_user_roles(compressed)
+    assert len(compressed) == 1
+    assert compressed[0]["content"].startswith("REAL HUMAN ASK")
+    assert not compressed[0].get("_todo_snapshot_synthetic")
+
+
+
+
+def test_compression_persists_child_handoff_immediately(tmp_path: Path) -> None:
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "HEADLESS_PREFLIGHT_PARENT"
+    db.create_session(parent_sid, source="cli")
+
+    agent = _build_agent_with_db(db, parent_sid)
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    compressed, _sp = agent._compress_context(messages, "sys", approx_tokens=120_000)
+    child_sid = agent.session_id
+
+    assert child_sid != parent_sid
+    assert db.get_session(parent_sid)["end_reason"] == "compression"
+    assert len(db.get_messages(child_sid)) == len(compressed)
+
+    agent._flush_messages_to_session_db(compressed, None)
+    assert len(db.get_messages(child_sid)) == len(compressed)
+
+
+
+
+def test_rotation_publish_failure_restores_proactive_prune_runway(
+    tmp_path: Path,
+) -> None:
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "PRUNE_RUNWAY_ROLLBACK_PARENT"
+    db.create_session(
+        parent_sid,
+        source="cli",
+        model_config={"keep": "value", "_proactive_prune_rearm_tokens": 120_000},
+    )
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    db.append_messages_batch(parent_sid, messages)
+    for message in messages:
+        message["_db_persisted"] = True
+    agent = _build_agent_with_db(db, parent_sid)
+    agent.context_compressor._proactive_prune_rearm_tokens = 120_000
+
+    def _compress(*_args, **_kwargs):
+        agent.context_compressor._proactive_prune_rearm_tokens = 0
+        return [
+            {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+            {"role": "user", "content": "tail"},
+        ]
+
+    agent.context_compressor.compress.side_effect = _compress
+    durable_before = db.get_messages_as_conversation(parent_sid)
+    with patch.object(
+        db,
+        "publish_compression_child",
+        side_effect=RuntimeError("publish failed"),
+    ):
+        returned, _sp = agent._compress_context(
+            messages, "sys", approx_tokens=120_000,
+        )
+
+    assert returned is messages
+    assert agent.session_id == parent_sid
+    assert agent.context_compressor._proactive_prune_rearm_tokens == 120_000
+    assert db.get_messages_as_conversation(parent_sid) == durable_before
+    assert json.loads(db.get_session(parent_sid)["model_config"]) == {
+        "keep": "value",
+        "_proactive_prune_rearm_tokens": 120_000,
+    }
+
+
+def test_full_in_place_compression_atomically_clears_durable_prune_runway(
+    tmp_path: Path,
+) -> None:
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "IN_PLACE_CLEARS_PRUNE_RUNWAY"
+    db.create_session(
+        session_id,
+        source="cli",
+        model_config={"keep": "value", "_proactive_prune_rearm_tokens": 120_000},
+    )
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    db.append_messages_batch(session_id, messages)
+    agent = _build_agent_with_db(db, session_id)
+    agent.compression_in_place = True
+    agent.context_compressor._proactive_prune_rearm_tokens = 120_000
+
+    compressed, _sp = agent._compress_context(
+        messages, "sys", approx_tokens=120_000,
+    )
+
+    assert agent.session_id == session_id
+    assert [message["content"] for message in db.get_messages_as_conversation(session_id)] == [
+        message["content"] for message in compressed
+    ]
+    assert json.loads(db.get_session(session_id)["model_config"]) == {"keep": "value"}
+
+
+def test_rotation_child_starts_without_durable_prune_runway(tmp_path: Path) -> None:
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "ROTATION_CLEARS_PRUNE_RUNWAY"
+    db.create_session(
+        parent_sid,
+        source="cli",
+        model_config={"keep": "parent", "_proactive_prune_rearm_tokens": 120_000},
+    )
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    db.append_messages_batch(parent_sid, messages)
+    agent = _build_agent_with_db(db, parent_sid)
+
+    agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert agent.session_id != parent_sid
+    child_config = json.loads(db.get_session(agent.session_id)["model_config"])
+    assert "_proactive_prune_rearm_tokens" not in child_config
+    assert json.loads(db.get_session(parent_sid)["model_config"])[
+        "_proactive_prune_rearm_tokens"
+    ] == 120_000
+
+
+@pytest.mark.parametrize("in_place", [False, True])
+def test_equal_copy_compression_result_does_not_rewrite_session(
+    tmp_path: Path,
+    in_place: bool,
+) -> None:
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = f"EQUAL_COPY_NOOP_{in_place}"
+    db.create_session(parent_sid, source="cli")
+
+    agent = _build_agent_with_db(db, parent_sid)
+    setattr(agent, "compression_in_place", in_place)
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    compressor = getattr(agent, "context_compressor")
+    compressor.compress.side_effect = lambda incoming, **_kw: list(incoming)
+
+    with patch.object(
+        db,
+        "archive_and_compact",
+        wraps=db.archive_and_compact,
+    ) as archive_and_compact:
+        returned, _sp = agent._compress_context(
+            messages,
+            "sys",
+            approx_tokens=120_000,
+        )
+
+    assert returned is messages
+    assert getattr(agent, "session_id") == parent_sid
+    assert _count_children(db, parent_sid) == 0
+    parent = db.get_session(parent_sid)
+    assert parent is not None
+    assert parent["end_reason"] is None
+    assert db.get_compression_lock_holder(parent_sid) is None
+    archive_and_compact.assert_not_called()
+
+
+
+
+def test_post_compress_exception_stops_lock_refresher(tmp_path: Path, monkeypatch) -> None:
+    """A warning-path exception after compress() returns must still release the lock."""
+    real_try_acquire = SessionDB.try_acquire_compression_lock
+
+    def _short_ttl(self, session_id: str, holder: str, ttl_seconds: float = 300.0) -> bool:
+        return real_try_acquire(self, session_id, holder, ttl_seconds=0.15)
+
+    monkeypatch.setattr(SessionDB, "try_acquire_compression_lock", _short_ttl)
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "REFRESH_EXCEPTION_TEST"
+    db.create_session(parent_sid, source="discord")
+
+    agent = _build_agent_with_db(db, parent_sid)
+    agent._compression_lock_ttl_seconds = 0.15
+    agent._compression_lock_refresh_interval = 0.05
+    agent.context_compressor._last_summary_error = "summary failed"
+    agent._emit_warning = lambda *_a, **_k: (_ for _ in ()).throw(RuntimeError("warn boom"))
+
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    with pytest.raises(RuntimeError, match="warn boom"):
+        agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    time.sleep(0.25)
+    assert db.try_acquire_compression_lock(parent_sid, "probe", ttl_seconds=1.0) is True
+
+
+
+
+
+
+
+
+def test_signature_introspection_exception_releases_lock_and_refresher(
+    tmp_path: Path, monkeypatch
+) -> None:
+    """Capability inspection failures must not leak the acquired lock lease."""
+    from agent.conversation_compression import (
+        _CompressionLockLeaseRefresher as RealLeaseRefresher,
+    )
+
+    refreshers = []
+
+    class RecordingLeaseRefresher(RealLeaseRefresher):
+        def start(self):
+            refreshers.append(self)
+            return super().start()
+
+    monkeypatch.setattr(
+        "agent.conversation_compression._CompressionLockLeaseRefresher",
+        RecordingLeaseRefresher,
+    )
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "SIGNATURE_EXCEPTION_TEST"
+    db.create_session(parent_sid, source="discord")
+
+    agent = _build_agent_with_db(db, parent_sid)
+    agent._compression_lock_refresh_interval = 0.1
+
+    class SignatureBomb:
+        calls = 0
+
+        @property
+        def __signature__(self):
+            raise RuntimeError("signature boom")
+
+        def __call__(self, *_args, **_kwargs):
+            self.calls += 1
+            raise AssertionError("engine must not run after signature failure")
+
+    bomb = SignatureBomb()
+    agent.context_compressor.compress = bomb
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    with pytest.raises(RuntimeError, match="signature boom"):
+        agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert bomb.calls == 0
+    assert db.get_compression_lock_holder(parent_sid) is None
+    assert len(refreshers) == 1
+    assert not refreshers[0]._thread.is_alive()
+
+
+
+
+
+
+
+
+def _make_legacy_session_db_class() -> type:
+    """Model the class retained in ``sys.modules`` before the lock API existed.
+
+    During the real version-skew incident, a re-imported compression module
+    imports the same still-loaded ``hermes_state`` module, whose ``SessionDB``
+    class is old. The test replaces that module attribute with this lockless
+    class and forwards all persistence operations to a current real database.
+    """
+    source_path = inspect.getfile(SessionDB)
+    namespace = {"__name__": "hermes_state"}
+    source = '''
+class SessionDB:
+    def __init__(self, real_db):
+        self._real = real_db
+
+    def __getattribute__(self, name):
+        if name in {"_real", "__class__"}:
+            return object.__getattribute__(self, name)
+        return getattr(object.__getattribute__(self, "_real"), name)
+'''
+    exec(compile(source, source_path, "exec"), namespace)
+    return namespace["SessionDB"]
+
+
+class _NominalSessionDBImpostor:
+    """A proxy that spoofs names but lacks the real SessionDB source contract."""
+
+    def __init__(self, real_db: SessionDB) -> None:
+        self._real = real_db
+
+    def create_session(self, *args, **kwargs):
+        return self._real.create_session(*args, **kwargs)
+
+    def __getattr__(self, name):
+        if name == "try_acquire_compression_lock":
+            raise AttributeError(name)
+        return getattr(self._real, name)
+
+
+_NominalSessionDBImpostor.__module__ = "hermes_state"
+_NominalSessionDBImpostor.__name__ = "SessionDB"
+
+
+class _BrokenLockLookupDB:
+    """A present lock API whose instance lookup fails unexpectedly."""
+
+    def __init__(self, real_db: SessionDB, error: Exception) -> None:
+        self._real = real_db
+        self._error = error
+
+    def try_acquire_compression_lock(self, *_args, **_kwargs):
+        raise AssertionError("the broken lookup must not resolve to a callable")
+
+    def __getattribute__(self, name):
+        if name == "try_acquire_compression_lock":
+            raise object.__getattribute__(self, "_error")
+        if name in {"_real", "_error", "__class__"}:
+            return object.__getattribute__(self, name)
+        return getattr(object.__getattribute__(self, "_real"), name)
+
+
+class _NonCallableLockAPI:
+    """A present lock API descriptor that resolves to a non-callable value."""
+
+    def __init__(self, real_db: SessionDB) -> None:
+        self._real = real_db
+
+    try_acquire_compression_lock = None
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)
+
+
+
+
+
+
+
+
+
+
+@pytest.mark.parametrize(
+    "error",
+    [
+        RuntimeError("simulated lock-table corruption"),
+        AttributeError("simulated internal lock attribute error"),
+        TypeError("simulated internal lock type error"),
+    ],
+)
+def test_real_lock_api_internal_errors_fail_closed_skips_compression(
+    tmp_path: Path, monkeypatch, error: Exception
+) -> None:
+    """Errors after a real lock API resolves must preserve session lineage.
+
+    ``AttributeError`` only means version skew while resolving the method. This
+    test injects failures beneath the real ``SessionDB.try_acquire...`` body,
+    proving that an internal AttributeError or TypeError cannot take the
+    structural-absence compatibility path.
+    """
+    db = SessionDB(db_path=tmp_path / "state.db")
+    parent_sid = "ERRORING_LOCK_TEST"
+    db.create_session(parent_sid, source="discord")
+
+    def _fail_lock_write(_fn):
+        raise error
+
+    monkeypatch.setattr(db, "_execute_write", _fail_lock_write)
+    agent = _build_agent_with_db(db, parent_sid)
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    compressed, _sp = agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    # Skipped: messages returned verbatim, no rotation, compressor never ran.
+    assert compressed is messages or compressed == messages
+    assert agent.session_id == parent_sid
+    assert _count_children(db, parent_sid) == 0
+    agent.context_compressor.compress.assert_not_called()
+
+
+
+
+def test_review_fork_compacts_oversized_snapshot_in_memory(tmp_path: Path) -> None:
+    """An oversized review snapshot replays warm on the first request, then
+    compacts in memory before further requests — without mutating the parent.
+
+    Regression for #93057: the fork historically pinned ``compression_enabled =
+    False`` because it shares the parent's session_id (issue #38727). That
+    left the review's private snapshot unbounded — every follow-up request in
+    the review tool loop replayed the whole snapshot (350k-384k input tokens
+    per request in production). The fix detaches the fork's compressor from
+    the parent's SessionDB/session_id and enables in-memory-only compaction.
+
+    This test drives the REAL ``_run_review_in_thread`` + ``run_conversation``
+    with a threshold-crossing snapshot across two provider requests and
+    asserts:
+      • the FIRST request replays the full snapshot untouched (warm
+        prompt-cache parity) — no compaction summary, middle turns present;
+      • compression actually fired before the SECOND request (a real
+        threshold crossing, not just setup-time binding state), and that
+        request carries the compaction summary and none of the middle
+        snapshot turns;
+      • the fork keeps the parent's session_id (prompt-cache parity) but its
+        agent-level AND compressor-level session bindings are detached;
+      • the parent's durable transcript, session row, and child-session graph
+        are byte-for-byte unchanged after the compaction ran.
+    """
+    import agent.background_review as br
+
+    parent_sid = "REVIEW_FORK_IN_MEMORY_COMPACTION_93057"
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    db.create_session(parent_sid, source="discord")
+    db.append_message(parent_sid, role="user", content="durable parent turn")
+    durable_before = db.get_messages(parent_sid)
+    session_row_before = tuple(
+        db._conn.execute(
+            "SELECT id, parent_session_id, ended_at, end_reason FROM sessions WHERE id = ?",
+            (parent_sid,),
+        ).fetchone()
+    )
+    parent = _build_agent_with_db(db, parent_sid)
+    parent._cached_system_prompt = "stable parent prompt"
+
+    snapshot = [
+        {
+            "role": "user" if i % 2 == 0 else "assistant",
+            "content": f"review turn {i} " + "x" * 200,
+        }
+        for i in range(24)
+    ]
+
+    captured = {}
+
+    def _tool_response(prompt_tokens: int) -> SimpleNamespace:
+        message = SimpleNamespace(
+            content=None,
+            reasoning_content=None,
+            reasoning=None,
+            tool_calls=[
+                SimpleNamespace(
+                    id="call_1",
+                    type="function",
+                    function=SimpleNamespace(
+                        name="web_search", arguments='{"query": "x"}'
+                    ),
+                )
+            ],
+        )
+        return SimpleNamespace(
+            choices=[SimpleNamespace(message=message, finish_reason="tool_calls")],
+            model="test/model",
+            usage=SimpleNamespace(
+                prompt_tokens=prompt_tokens,
+                completion_tokens=1,
+                total_tokens=prompt_tokens + 1,
+            ),
+        )
+
+    def _final_response():
+        return SimpleNamespace(
+            choices=[
+                SimpleNamespace(
+                    index=0,
+                    message=SimpleNamespace(
+                        role="assistant",
+                        content="review complete",
+                        tool_calls=None,
+                        reasoning_content=None,
+                    ),
+                    finish_reason="stop",
+                )
+            ],
+            usage=SimpleNamespace(
+                prompt_tokens=100, completion_tokens=10, total_tokens=110
+            ),
+            model="test/model",
+        )
+
+    # The worker does a local ``from run_agent import AIAgent``; patching the
+    # class method covers that import path.
+    from run_agent import AIAgent
+
+    real_run_conversation = AIAgent.run_conversation
+
+    def _run_threshold_crossing_review(self, *args, **kwargs):
+        captured["compression_enabled"] = self.compression_enabled
+        captured["compression_in_place"] = self.compression_in_place
+        captured["session_id"] = self.session_id
+        captured["session_db"] = self._session_db
+        captured["input_budget"] = getattr(
+            self, "_review_input_token_budget", "missing"
+        )
+        captured["defer_first_request"] = getattr(
+            self, "_review_defer_compaction_before_first_response", "missing"
+        )
+        captured["compressor_session_db"] = getattr(
+            self.context_compressor, "_session_db", "missing"
+        )
+        captured["compressor_session_id"] = getattr(
+            self.context_compressor, "_session_id", "missing"
+        )
+        # Stub the fork's compressor so compaction output is deterministic
+        # and no aux-LLM call happens; the trigger/commit paths stay real.
+        self.context_compressor.threshold_tokens = 1
+        self.context_compressor.protect_first_n = 1
+        self.context_compressor.protect_last_n = 1
+        self.context_compressor.compress = MagicMock(
+            return_value=[
+                {"role": "user", "content": "[CONTEXT COMPACTION] review summary"},
+                {"role": "assistant", "content": "summary acknowledged"},
+            ]
+        )
+        # Compress on the first pressure check after the first response, then
+        # stand down so the compacted request proceeds instead of looping.
+        _should_compress_calls = {"count": 0}
+
+        def _should_compress(_tokens):
+            _should_compress_calls["count"] += 1
+            return _should_compress_calls["count"] == 1
+
+        self.context_compressor.should_compress = MagicMock(
+            side_effect=_should_compress
+        )
+        self.context_compressor.should_compress_info = MagicMock(
+            return_value=(True, "over threshold")
+        )
+        self.context_compressor.should_compress_preflight = MagicMock(
+            return_value=True
+        )
+        self.context_compressor.should_defer_preflight_to_real_usage = MagicMock(
+            return_value=False
+        )
+        self.context_compressor.get_active_compression_failure_cooldown = MagicMock(
+            return_value=None
+        )
+        self.context_compressor.select_context = MagicMock(return_value=None)
+        self._compression_feasibility_checked = True
+        self.client = MagicMock()
+        self.client.chat.completions.create.side_effect = [
+            _tool_response(100),
+            _final_response(),
+        ]
+        self._disable_streaming = True
+        self._use_prompt_caching = False
+
+        def _fake_execute_tool_calls(assistant_message, messages, *_args):
+            tool_call = assistant_message.tool_calls[0]
+            messages.append(
+                {
+                    "role": "tool",
+                    "name": tool_call.function.name,
+                    "tool_call_id": tool_call.id,
+                    "content": "ok",
+                }
+            )
+
+        self._execute_tool_calls = _fake_execute_tool_calls
+
+        result = real_run_conversation(self, *args, **kwargs)
+        captured["compression_calls"] = self.context_compressor.compress.call_count
+        create = self.client.chat.completions.create
+        captured["create_calls"] = create.call_count
+        captured["outbound"] = [
+            call.kwargs.get("messages") for call in create.call_args_list
+        ]
+        return result
+
+    try:
+        with patch.object(AIAgent, "run_conversation", _run_threshold_crossing_review):
+            br._run_review_in_thread(parent, snapshot, "review this conversation")
+
+        assert captured["compression_calls"] >= 1, (
+            "FIX REGRESSION: the review fork did not compact its oversized "
+            "snapshot. compression_enabled was historically set False on the "
+            "fork, which removed the only bound on the replayed snapshot "
+            "(issue #93057)."
+        )
+        assert captured["create_calls"] == 2, (
+            f"expected a 2-request review (tool call + final), "
+            f"got {captured['create_calls']}"
+        )
+        first_outbound, second_outbound = captured["outbound"]
+        first_contents = [str(m.get("content", "")) for m in first_outbound]
+        second_contents = [str(m.get("content", "")) for m in second_outbound]
+        # Warm-cache parity: the first request replays the full snapshot
+        # untouched — middle turns present, no compaction summary yet.
+        assert any("review turn 12" in text for text in first_contents), (
+            "the review fork's FIRST request must replay the full snapshot "
+            "(warm prompt-cache read) — compaction must not rewrite it before "
+            "the first provider call"
+        )
+        assert not any(
+            "[CONTEXT COMPACTION]" in text for text in first_contents
+        ), f"first request was compacted prematurely: {first_contents!r}"
+        # The SECOND request carries the compaction summary and none of the
+        # middle snapshot turns.
+        assert any(
+            "[CONTEXT COMPACTION] review summary" in text
+            for text in second_contents
+        ), f"outbound request did not contain the compaction summary: {second_contents!r}"
+        assert not any("review turn 12" in text for text in second_contents), (
+            "outbound request still replays the middle of the snapshot — "
+            "the review replayed an unbounded transcript despite compaction"
+        )
+        assert captured["session_id"] == parent_sid, (
+            "Review fork should inherit the parent's session_id for "
+            "prompt-cache parity."
+        )
+        assert captured["session_db"] is None, (
+            "Review fork must keep its agent-level SessionDB detached "
+            "(_session_db=None) so compaction can never persist."
+        )
+        assert captured["compressor_session_db"] is None, (
+            "Review fork's compressor must be detached from the parent "
+            "SessionDB, otherwise durable cooldown/streak writes land on "
+            "the parent's row (issue #93057)."
+        )
+        assert captured["compressor_session_id"] == ""
+        assert captured["compression_enabled"] is True
+        assert captured["compression_in_place"] is True
+        assert captured["defer_first_request"] is True
+        assert isinstance(captured["input_budget"], int) and captured["input_budget"] > 0
+
+        # Parent session must be byte-for-byte unchanged after the review
+        # compacted its private snapshot.
+        assert parent.session_id == parent_sid
+        assert db.get_messages(parent_sid) == durable_before
+        session_row_after = tuple(
+            db._conn.execute(
+                "SELECT id, parent_session_id, ended_at, end_reason FROM sessions WHERE id = ?",
+                (parent_sid,),
+            ).fetchone()
+        )
+        assert session_row_after == session_row_before
+        assert _count_children(db, parent_sid) == 0
+    finally:
+        db.close()
+
+
+def test_review_fork_fails_closed_when_compressor_rebind_raises(
+    tmp_path: Path, caplog
+) -> None:
+    """A failed compressor detachment must keep the fork's compression OFF.
+
+    Regression for the #93057 adversarial review: if ``bind_session_state``
+    cannot sever the engine's binding to the parent's SessionDB/session_id,
+    enabling compression would run it against the parent's live session
+    binding — durable cooldown/streak/ineffective-count writes on the
+    parent's row and the sibling-session race behind #38727 re-opened. The
+    fork must fail CLOSED: keep the historical ``compression_enabled = False``
+    behavior and warn. The review still runs (the iteration cap and the
+    aggregate input budget still bound it).
+    """
+    import agent.background_review as br
+    from agent.context_compressor import ContextCompressor
+
+    parent_sid = "REVIEW_FORK_REBIND_FAIL_CLOSED_93057"
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    db.create_session(parent_sid, source="discord")
+    parent = _build_agent_with_db(db, parent_sid)
+    parent._cached_system_prompt = "stable parent prompt"
+
+    snapshot = [
+        {
+            "role": "user" if i % 2 == 0 else "assistant",
+            "content": f"review turn {i}",
+        }
+        for i in range(8)
+    ]
+
+    captured = {}
+
+    def _capture_fork_flags(self, *args, **kwargs):
+        captured["compression_enabled"] = self.compression_enabled
+        captured["compression_in_place"] = self.compression_in_place
+        captured["input_budget"] = getattr(
+            self, "_review_input_token_budget", "missing"
+        )
+        return {
+            "completed": True,
+            "final_response": "review complete",
+            "api_call_count": 0,
+        }
+
+    # The worker does a local ``from run_agent import AIAgent``; patching the
+    # class method covers that import path.
+    from run_agent import AIAgent
+
+    _real_bind = ContextCompressor.bind_session_state
+
+    def _failing_bind(self, session_db=None, session_id=""):
+        # Only the detachment rebind may fail; any other binding passes
+        # through so the fork's construction path stays intact.
+        if session_db is None:
+            raise RuntimeError("detachment boom")
+        return _real_bind(self, session_db, session_id)
+
+    try:
+        with (
+            patch.object(AIAgent, "run_conversation", _capture_fork_flags),
+            patch.object(
+                ContextCompressor, "bind_session_state", _failing_bind
+            ),
+        ):
+            with caplog.at_level(logging.WARNING, logger="agent.background_review"):
+                br._run_review_in_thread(parent, snapshot, "review this conversation")
+
+        assert captured["compression_enabled"] is False, (
+            "FIX REGRESSION: a failed compressor rebind must leave "
+            "compression_enabled False on the review fork (fail-closed). "
+            "Enabling compression with the engine still bound to the "
+            "parent's session re-opens the #38727 race (issue #93057)."
+        )
+        assert any(
+            "detachment failed" in record.message for record in caplog.records
+        ), (
+            "the failed rebind must log a warning so operators can see the "
+            "fork fell back to the pre-fix behavior"
+        )
+        assert (
+            isinstance(captured["input_budget"], int) and captured["input_budget"] > 0
+        ), (
+            "the aggregate input budget must still be armed on the fail-closed "
+            "path — it bounds the review even when compaction stays off"
+        )
+    finally:
+        db.close()
+
+
+# ── Lease-refresher bounded-failure tolerance (salvage follow-up, #54465) ────
+# A single falsy refresh (transient DB blip) must NOT permanently kill the
+# lease — only a *persistent* failure (genuine lost-ownership) should stop the
+# refresher after a bounded number of consecutive failures. Without this, one
+# escaped lock-contention error silently reintroduces the TTL-expiry wedge the
+# PR set out to fix.
+
+
+class _FlakyRefreshDB:
+    """A db whose refresh_compression_lock returns a scripted sequence."""
+
+    def __init__(self, results):
+        self._results = list(results)
+        self.calls = 0
+
+    def refresh_compression_lock(self, session_id, holder, ttl_seconds=300.0):
+        self.calls += 1
+        if self._results:
+            return self._results.pop(0)
+        return True  # steady-state success after the scripted prefix
+
+
+def _no_sleep(refresher) -> None:
+    """Make the refresher loop iterate without real wall-clock sleeps.
+
+    ``_stop.wait(interval)`` returns False (keep looping) instantly instead of
+    blocking for the (clamped) interval, so count-based tests stay fast and
+    deterministic — the loop's termination is driven by the failure cap / the
+    scripted db, not by timing.
+    """
+    refresher._stop.wait = lambda _interval: False  # type: ignore[assignment]
+
+
+
+
+
+
+
+
+def test_lease_refresher_failure_window_is_bounded_by_ttl() -> None:
+    """Persistent failure stops within one lease's worth of time, not forever.
+
+    The contract (not a magic count): the give-up window
+    ``cap * refresh_interval`` must be <= the TTL, so a stuck refresher can
+    never hold the lock past its TTL. We assert that relationship directly
+    rather than freezing a literal cap (behavior contract over snapshot).
+    """
+    from agent.conversation_compression import _CompressionLockLeaseRefresher
+
+    ttl, interval = 10.0, 2.0  # cap should be int(10/2) = 5
+    db = _FlakyRefreshDB([False] * 50)  # never recovers (lost ownership)
+    refresher = _CompressionLockLeaseRefresher(
+        db, "sess", "holder", ttl_seconds=ttl, refresh_interval_seconds=interval
+    )
+    _no_sleep(refresher)
+    refresher._run()
+
+    cap = refresher._max_consecutive_failures
+    assert cap == int(ttl / interval), "cap must derive from ttl/interval"
+    # Stops at the cap — not on the first failure, not forever.
+    assert db.calls == cap
+    # The invariant that makes the cap honest: total tolerance <= one TTL.
+    assert cap * interval <= ttl, (
+        f"give-up window {cap * interval}s must not exceed the lease TTL {ttl}s"
+    )
+
+
+def test_hard_interrupt_aborts_compression_and_unblocks_session_writes(tmp_path: Path) -> None:
+    """Ctrl+C must abort an interrupt-protected summary without leaving the
+    session write-blocked behind its compression lease."""
+    from agent import auxiliary_client as aux
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HARD_INTERRUPT_COMPRESSION_TEST"
+    db.create_session(session_id, source="cli")
+
+    agent = _build_agent_with_db(db, session_id)
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    original_messages = copy.deepcopy(messages)
+
+    def _cancelled_compress(current, *_args, **_kwargs):
+        agent._hard_interrupt_requested.set()
+        assert aux._aux_interrupt_cancel_requested() is True
+        # F3 isolation: the engine only ever sees the pooled snapshot, so an
+        # in-place mutation lands on ``current`` (the worker's copy), never on
+        # the caller's live list. The rollback contract is that the RETURNED
+        # transcript equals the pre-compression one.
+        current[0]["content"] = "must be rolled back"
+        raise aux.AuxiliaryExplicitCancellation()
+
+    agent.context_compressor.compress.side_effect = _cancelled_compress
+
+    compressed, _prompt = agent._compress_context(
+        messages, "sys", approx_tokens=120_000
+    )
+
+    assert compressed == original_messages
+    assert messages == original_messages
+    assert db.get_compression_lock_holder(session_id) is None
+    db.append_message(session_id, "assistant", "writes recovered")
+
+
+def test_late_hard_interrupt_restores_full_compressor_attempt_state_and_retry(
+    tmp_path: Path,
+) -> None:
+    """A stop after provider success but before compress() returns is a true no-op."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "LATE_HARD_INTERRUPT_STATE_TEST"
+    db.create_session(session_id, source="cli")
+    agent = _build_agent_with_db(db, session_id)
+    agent.compression_in_place = True
+    agent._cached_system_prompt = "sys"
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    provider_returned = threading.Event()
+    allow_compress_return = threading.Event()
+    shared_telemetry = {"shared": [1, 2, 3]}
+    state_fields = {
+        "_previous_summary": "old-summary",
+        "_summary_has_user_turn": False,
+        "compression_count": 4,
+        "_last_compression_savings_pct": 37.5,
+        "_ineffective_compression_count": 1,
+        "_anti_thrash_recovery_deadline": 123.0,
+        "_fallback_compression_streak": 1,
+        "_verify_compaction_cleared_threshold": False,
+        "_last_compression_made_progress": False,
+        "_summary_failure_cooldown_until": 456.0,
+        "_cooldown_persist_failed": True,
+        "_last_summary_error": "old-error",
+        "_consecutive_timeout_failures": 2,
+        "_last_summary_dropped_count": 3,
+        "_last_summary_fallback_used": True,
+        "_last_compress_aborted": False,
+        "_last_summary_auth_failure": True,
+        "_last_summary_network_failure": True,
+        "_last_aux_model_failure_error": "old-aux-error",
+        "_last_aux_model_failure_model": "old-aux-model",
+        "_summary_model_fallen_back": True,
+        "summary_model": "old-summary-model",
+        "_last_compression_telemetry": shared_telemetry,
+        "_active_compression_telemetry": shared_telemetry,
+        "_compression_telemetry_seed": {"seed": [3]},
+    }
+    for name, value in state_fields.items():
+        setattr(agent.context_compressor, name, copy.deepcopy(value))
+    restored_shared_telemetry = copy.deepcopy(shared_telemetry)
+    agent.context_compressor._last_compression_telemetry = restored_shared_telemetry
+    agent.context_compressor._active_compression_telemetry = restored_shared_telemetry
+
+    def _provider_succeeded_then_waits(*_args, **_kwargs):
+        for name in state_fields:
+            setattr(agent.context_compressor, name, f"mutated-{name}")
+        provider_returned.set()
+        assert allow_compress_return.wait(timeout=5)
+        return [
+            {"role": "user", "content": "[CONTEXT COMPACTION] cancelled summary"},
+            {"role": "user", "content": "tail"},
+        ]
+
+    agent.context_compressor.compress.side_effect = _provider_succeeded_then_waits
+    result: dict[str, tuple] = {}
+    worker = threading.Thread(
+        target=lambda: result.setdefault(
+            "value", agent._compress_context(messages, "sys", approx_tokens=120_000)
+        ),
+        daemon=True,
+    )
+    worker.start()
+    assert provider_returned.wait(timeout=2)
+    agent.hard_interrupt("cancel after provider return")
+    allow_compress_return.set()
+    worker.join(timeout=5)
+
+    assert not worker.is_alive()
+    assert result["value"][0] is messages
+    assert {
+        name: copy.deepcopy(getattr(agent.context_compressor, name))
+        for name in state_fields
+    } == state_fields
+    assert (
+        agent.context_compressor._active_compression_telemetry
+        is agent.context_compressor._last_compression_telemetry
+    )
+    assert db.get_compression_lock_holder(session_id) is None
+
+    agent.clear_interrupt()
+    agent.context_compressor.compress.side_effect = lambda *_a, **_kw: [
+        {"role": "user", "content": "[CONTEXT COMPACTION] retry summary"},
+        {"role": "user", "content": "tail"},
+    ]
+    retried, _prompt = agent._compress_context(
+        messages, "sys", approx_tokens=120_000
+    )
+    assert retried is not messages
+    assert retried[0]["content"] == "[CONTEXT COMPACTION] retry summary"
+
+
+def test_force_cancel_restores_newer_durable_cooldown_captured_under_lease(
+    tmp_path: Path,
+) -> None:
+    """A stale forced attempt rolls back to the lease-protected durable row."""
+    from agent.auxiliary_client import AuxiliaryExplicitCancellation
+    from agent.context_compressor import ContextCompressor
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "FORCE_CANCEL_DURABLE_COOLDOWN"
+    db.create_session(session_id, source="cli")
+
+    # B binds first and therefore has no local cooldown. A then persists a
+    # newer cooldown for the same durable session before B acquires its lease.
+    stale_agent = _build_agent_with_db(
+        db, session_id, stub_compressor=False
+    )
+    writer_agent = _build_agent_with_db(
+        db, session_id, stub_compressor=False
+    )
+    stale = stale_agent.context_compressor
+    writer = writer_agent.context_compressor
+    assert isinstance(stale, ContextCompressor)
+    assert isinstance(writer, ContextCompressor)
+    assert stale._summary_failure_cooldown_until == 0.0
+
+    writer._record_compression_failure_cooldown(120.0, "newer durable failure")
+    durable_before = tuple(
+        db._conn.execute(
+            "SELECT compression_failure_cooldown_until, compression_failure_error "
+            "FROM sessions WHERE id = ?",
+            (session_id,),
+        ).fetchone()
+    )
+    assert durable_before[0] is not None
+
+    stale_seed = {"seed": ["truly-pre-attempt"]}
+    stale._compression_telemetry_seed = copy.deepcopy(stale_seed)
+    stale._previous_summary = "pre-attempt-summary"
+    stale_agent._compression_feasibility_checked = True
+    stale_agent.compression_in_place = True
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    real_clear = ContextCompressor._clear_compression_failure_cooldown
+
+    def _clear_then_hard_cancel() -> None:
+        real_clear(stale)
+        stale_agent._hard_interrupt_requested.set()
+        raise AuxiliaryExplicitCancellation()
+
+    # Exercise the built-in force=True mutation point deterministically: force
+    # clears the durable cooldown, then the frozen host cancellation unwinds it.
+    stale._clear_compression_failure_cooldown = _clear_then_hard_cancel
+
+    compressed, _prompt = stale_agent._compress_context(
+        messages,
+        "sys",
+        approx_tokens=120_000,
+        force=True,
+    )
+
+    assert compressed is messages
+    durable_after = tuple(
+        db._conn.execute(
+            "SELECT compression_failure_cooldown_until, compression_failure_error "
+            "FROM sessions WHERE id = ?",
+            (session_id,),
+        ).fetchone()
+    )
+    assert durable_after == durable_before
+    assert stale._summary_failure_cooldown_until > time.monotonic()
+    assert stale._last_summary_error == "newer durable failure"
+    assert stale._cooldown_persist_failed is False
+    assert stale._compression_telemetry_seed == stale_seed
+    assert stale._previous_summary == "pre-attempt-summary"
+    assert db.get_compression_lock_holder(session_id) is None
+
+    # A future compressor refresh must still observe the exact row rather than
+    # the cancelled force attempt having permanently cleared it.
+    future_agent = _build_agent_with_db(
+        db, session_id, stub_compressor=False
+    )
+    future = future_agent.context_compressor.get_active_compression_failure_cooldown(
+        refresh=True
+    )
+    assert future is not None
+    assert future["error"] == "newer durable failure"
+
+
+def test_unrelated_interrupted_error_propagates_and_releases_compression_lease(
+    tmp_path: Path,
+) -> None:
+    """A plugin/OS InterruptedError is a failure, not an explicit transaction abort."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "UNRELATED_INTERRUPT_COMPRESSION_TEST"
+    db.create_session(session_id, source="cli")
+
+    agent = _build_agent_with_db(db, session_id)
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    def _provider_interrupted(*_args, **_kwargs):
+        messages[0]["content"] = "must be rolled back"
+        raise InterruptedError("provider syscall interrupted")
+
+    agent.context_compressor.compress.side_effect = _provider_interrupted
+
+    with pytest.raises(InterruptedError, match="provider syscall interrupted"):
+        agent._compress_context(messages, "sys", approx_tokens=120_000)
+
+    assert db.get_compression_lock_holder(session_id) is None
+    db.append_message(session_id, "assistant", "writes recovered")
+
+
+def test_redirect_interrupt_remains_protected_during_compression(tmp_path: Path) -> None:
+    """Redirects use interrupt_requested=True/message=None; only the atomic
+    hard-cancel event may override summary protection."""
+    from agent import auxiliary_client as aux
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "REDIRECT_COMPRESSION_TEST"
+    db.create_session(session_id, source="cli")
+    agent = _build_agent_with_db(db, session_id)
+    agent._interrupt_requested = True
+    agent._interrupt_message = None
+    agent._pending_redirect = "new correction"
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    def _protected_noop(current, **_kwargs):
+        assert aux._aux_interrupt_cancel_requested() is False
+        return copy.deepcopy(current)
+
+    agent.context_compressor.compress.side_effect = _protected_noop
+
+    compressed, _prompt = agent._compress_context(
+        messages, "sys", approx_tokens=120_000
+    )
+
+    assert compressed == messages
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_hard_cancel_between_compress_return_and_commit_begin_wins_atomically(
+    tmp_path: Path,
+) -> None:
+    """The hard-stop admission and commit admission share one fence lock."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HARD_CANCEL_COMMIT_RACE"
+    db.create_session(session_id, source="tui")
+    agent = _build_agent_with_db(db, session_id)
+    agent.compression_in_place = True
+    agent._cached_system_prompt = "sys"
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    before_commit = threading.Event()
+    allow_commit_check = threading.Event()
+
+    class _CommitBarrierList(list):
+        def __eq__(self, other):
+            before_commit.set()
+            assert allow_commit_check.wait(timeout=5)
+            return super().__eq__(other)
+
+    agent.context_compressor.compress.side_effect = lambda *_a, **_kw: _CommitBarrierList(
+        [
+            {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+            {"role": "user", "content": "tail"},
+        ]
+    )
+    archive_spy = MagicMock(wraps=db.archive_and_compact)
+    db.archive_and_compact = archive_spy
+    result: dict[str, tuple] = {}
+    worker = threading.Thread(
+        target=lambda: result.setdefault(
+            "value", agent._compress_context(messages, "sys", approx_tokens=120_000)
+        ),
+        daemon=True,
+    )
+    worker.start()
+    assert before_commit.wait(timeout=2)
+
+    agent.hard_interrupt("cancel before commit admission")
+    allow_commit_check.set()
+    worker.join(timeout=5)
+
+    assert not worker.is_alive()
+    assert result["value"][0] is messages
+    archive_spy.assert_not_called()
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_hard_stop_waits_for_commit_already_admitted(tmp_path: Path) -> None:
+    """A surfaced stop never races an untracked post-return transcript commit."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "HARD_CANCEL_AFTER_COMMIT_ADMISSION"
+    db.create_session(session_id, source="tui")
+    agent = _build_agent_with_db(db, session_id)
+    agent.compression_in_place = True
+    agent._cached_system_prompt = "sys"
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    commit_started = threading.Event()
+    allow_commit = threading.Event()
+    stop_returned = threading.Event()
+    original_archive = db.archive_and_compact
+
+    def _blocked_archive(*args, **kwargs):
+        commit_started.set()
+        assert allow_commit.wait(timeout=5)
+        return original_archive(*args, **kwargs)
+
+    db.archive_and_compact = _blocked_archive
+    agent.context_compressor.compress.side_effect = lambda *_a, **_kw: [
+        {"role": "user", "content": "[CONTEXT COMPACTION] summary"},
+        {"role": "user", "content": "tail"},
+    ]
+    compression_result: dict[str, tuple] = {}
+    compression = threading.Thread(
+        target=lambda: compression_result.setdefault(
+            "value", agent._compress_context(messages, "sys", approx_tokens=120_000)
+        ),
+        daemon=True,
+    )
+    compression.start()
+    assert commit_started.wait(timeout=2)
+
+    stop = threading.Thread(
+        target=lambda: (
+            agent.hard_interrupt("stop after commit admission"),
+            stop_returned.set(),
+        ),
+        daemon=True,
+    )
+    stop.start()
+    assert not stop_returned.wait(timeout=0.1)
+    allow_commit.set()
+    compression.join(timeout=5)
+    stop.join(timeout=5)
+
+    assert not compression.is_alive()
+    assert not stop.is_alive()
+    assert stop_returned.is_set()
+    assert compression_result["value"][0][0]["content"] == (
+        "[CONTEXT COMPACTION] summary"
+    )
+    assert agent._hard_interrupt_requested.is_set()
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+@pytest.mark.parametrize("deadline_offset", [-10.0, 0.05, None])
+def test_force_cancel_restores_exact_expired_or_expiring_cooldown_row(
+    tmp_path: Path,
+    deadline_offset: float | None,
+) -> None:
+    """Cancellation preserves raw cooldown columns even after their deadline."""
+    from agent.auxiliary_client import AuxiliaryExplicitCancellation
+    from agent.context_compressor import ContextCompressor
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = f"RAW_COOLDOWN_{deadline_offset}"
+    db.create_session(session_id, source="cli")
+    deadline = time.time() + deadline_offset if deadline_offset is not None else None
+    db.restore_compression_failure_cooldown_row(
+        session_id,
+        {
+            "session_exists": True,
+            "cooldown_until": deadline,
+            "error": "expired-but-exact",
+        },
+    )
+    before = db.get_compression_failure_cooldown_row(session_id)
+
+    agent = _build_agent_with_db(db, session_id, stub_compressor=False)
+    compressor = agent.context_compressor
+    assert isinstance(compressor, ContextCompressor)
+    # A stale local persistence-failure marker must not suppress restoration
+    # once the raw durable row was captured authoritatively under the lease.
+    compressor._cooldown_persist_failed = True
+    agent._compression_feasibility_checked = True
+    agent.compression_in_place = True
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    real_clear = ContextCompressor._clear_compression_failure_cooldown
+
+    def _mutate_then_cancel() -> None:
+        real_clear(compressor)
+        if deadline_offset is not None and deadline_offset > 0:
+            assert deadline is not None
+            while time.time() <= deadline:
+                time.sleep(0.005)
+        agent._hard_interrupt_requested.set()
+        raise AuxiliaryExplicitCancellation()
+
+    compressor._clear_compression_failure_cooldown = _mutate_then_cancel
+
+    compressed, _prompt = agent._compress_context(
+        messages,
+        "sys",
+        approx_tokens=120_000,
+        force=True,
+    )
+
+    assert compressed is messages
+    assert db.get_compression_failure_cooldown_row(session_id) == before
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_exact_cooldown_restore_tolerates_a_concurrently_deleted_session(
+    tmp_path: Path,
+) -> None:
+    """A deleted session has no cooldown state left to compensate (#106271)."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "COOLDOWN_ROLLBACK_DELETED_SESSION"
+    db.create_session(session_id, source="cli")
+    snapshot = db.get_compression_failure_cooldown_row(session_id)
+    assert snapshot["session_exists"] is True
+
+    assert db.delete_session(session_id) is True
+    db.restore_compression_failure_cooldown_row(session_id, snapshot)
+
+    assert db.get_compression_failure_cooldown_row(session_id) == {
+        "session_exists": False,
+        "cooldown_until": None,
+        "error": None,
+    }
+
+
+def test_exact_cooldown_restore_tolerates_deletion_before_verification(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A deletion after the compensating write is still an intentional no-op (#106271)."""
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "COOLDOWN_ROLLBACK_DELETE_DURING_VERIFY"
+    db.create_session(session_id, source="cli")
+    snapshot = db.get_compression_failure_cooldown_row(session_id)
+    real_execute_write = db._execute_write
+
+    def _restore_then_delete(callback):
+        monkeypatch.setattr(db, "_execute_write", real_execute_write)
+        result = real_execute_write(callback)
+        assert db.delete_session(session_id) is True
+        return result
+
+    monkeypatch.setattr(db, "_execute_write", _restore_then_delete)
+    db.restore_compression_failure_cooldown_row(session_id, snapshot)
+
+    assert db.get_compression_failure_cooldown_row(session_id)["session_exists"] is False
+
+
+def test_cooldown_rollback_failure_surfaces_and_releases_lease(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A failed compensating write cannot masquerade as a mutation-free cancel."""
+    from agent.auxiliary_client import AuxiliaryExplicitCancellation
+    from agent.context_compressor import ContextCompressor
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "COOLDOWN_ROLLBACK_WRITE_FAILURE"
+    db.create_session(session_id, source="cli")
+    db.record_compression_failure_cooldown(
+        session_id,
+        time.time() + 120.0,
+        "must-restore",
+    )
+    agent = _build_agent_with_db(db, session_id, stub_compressor=False)
+    compressor = agent.context_compressor
+    assert isinstance(compressor, ContextCompressor)
+    agent._compression_feasibility_checked = True
+    agent.compression_in_place = True
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+    real_clear = ContextCompressor._clear_compression_failure_cooldown
+
+    def _mutate_then_cancel() -> None:
+        real_clear(compressor)
+        agent._hard_interrupt_requested.set()
+        raise AuxiliaryExplicitCancellation()
+
+    compressor._clear_compression_failure_cooldown = _mutate_then_cancel
+
+    def _rollback_write_fails(_self, _session_id, _snapshot) -> None:
+        raise sqlite3.OperationalError("forced rollback write failure")
+
+    monkeypatch.setattr(
+        SessionDB,
+        "restore_compression_failure_cooldown_row",
+        _rollback_write_fails,
+    )
+
+    with pytest.raises(sqlite3.OperationalError, match="forced rollback write failure"):
+        agent._compress_context(
+            messages,
+            "sys",
+            approx_tokens=120_000,
+            force=True,
+        )
+
+    assert db.get_compression_lock_holder(session_id) is None
+
+
+def test_exact_cooldown_restore_api_propagates_sqlite_write_failure(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "RAW_COOLDOWN_WRITE_FAILURE"
+    db.create_session(session_id, source="test")
+
+    def _write_fails(_callback) -> None:
+        raise sqlite3.OperationalError("forced low-level write failure")
+
+    monkeypatch.setattr(db, "_execute_write", _write_fails)
+
+    with pytest.raises(sqlite3.OperationalError, match="forced low-level write failure"):
+        db.restore_compression_failure_cooldown_row(
+            session_id,
+            {
+                "session_exists": True,
+                "cooldown_until": time.time() + 10.0,
+                "error": "must propagate",
+            },
+        )
+
+
+def test_failed_split_arms_failure_cooldown(tmp_path: Path) -> None:
+    """Regression #97948 symptom B: a failed split/archive must arm the
+    compression failure cooldown so the next automatic turn cannot
+    immediately re-run the identical doomed compression."""
+    from agent.conversation_compression import _SPLIT_FAILURE_COOLDOWN_SECONDS
+
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "SPLIT_FAIL_COOLDOWN_TEST"
+    db.create_session(session_id, source="test")
+    agent = _build_agent_with_db(db, session_id)
+    setattr(agent, "compression_in_place", True)
+    db.archive_and_compact = MagicMock(side_effect=RuntimeError("archive boom"))
+    messages = [{"role": "user", "content": f"m{i}"} for i in range(20)]
+
+    agent._compress_context(
+        messages,
+        "sys",
+        approx_tokens=120_000,
+        force=True,
+    )
+
+    cooldown_calls = (
+        agent.context_compressor._record_compression_failure_cooldown.call_args_list
+    )
+    assert len(cooldown_calls) == 1, (
+        "split failure must arm the failure cooldown (#97948 symptom B)"
+    )
+    seconds, error = cooldown_calls[0].args
+    assert seconds == _SPLIT_FAILURE_COOLDOWN_SECONDS
+    assert "session_split_failed" in str(error)

tests/agent/test_compression_interrupt_protection.py

@@ -0,0 +1,175 @@
+"""Regression for #23975: context compression must survive a mid-flight
+gateway interrupt.
+
+While the compression summary LLM call is in flight, an incoming gateway
+message sets the thread interrupt flag. The Codex Responses aux stream polls
+that flag and used to raise InterruptedError unconditionally — aborting the
+summary, which then fell back to a degraded static "summary unavailable"
+marker (losing the real handoff). Compression now runs its summary call
+under aux_interrupt_protection(), so the interrupt poll is masked for the
+compression task only (timeouts and other aux tasks stay interruptible).
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+
+import agent.auxiliary_client as aux
+
+
+class TestAuxInterruptProtection:
+
+
+    def test_context_manager_is_reentrant(self):
+        with aux.aux_interrupt_protection():
+            assert aux._aux_interrupt_protected() is True
+            with aux.aux_interrupt_protection():
+                assert aux._aux_interrupt_protected() is True
+            # inner exit must NOT clear protection while still inside outer
+            assert aux._aux_interrupt_protected() is True
+        assert aux._aux_interrupt_protected() is False
+
+    def test_restores_on_exception(self):
+        try:
+            with aux.aux_interrupt_protection():
+                raise ValueError("boom")
+        except ValueError:
+            pass
+        assert aux._aux_interrupt_protected() is False
+
+
+    def test_nested_protection_preserves_explicit_cancel_check(self):
+        """A hard-cancel hook installed by the compression host survives the
+        compressor's nested protection scope."""
+        with aux.aux_interrupt_protection(cancel_check=lambda: True):
+            with aux.aux_interrupt_protection():
+                assert aux._aux_interrupt_protected() is True
+                assert aux._aux_interrupt_cancel_requested() is True
+        assert aux._aux_interrupt_cancel_requested() is False
+
+
+class TestCompressionProtectsSummaryCall:
+    """The compressor must wrap its summary call_llm in aux_interrupt_protection
+    so a mid-flight interrupt doesn't abort it (#23975)."""
+
+    def test_compressor_call_site_uses_protection(self):
+        # The summary call must run inside aux_interrupt_protection. We assert
+        # the protection flag is ACTIVE at the moment call_llm is invoked.
+        from agent.context_compressor import ContextCompressor
+
+        seen = {}
+
+        class _Resp:
+            class _Choice:
+                class _Msg:
+                    content = "[CONTEXT SUMMARY]: ok"
+                message = _Msg()
+            choices = [_Choice()]
+
+        def fake_call_llm(**kwargs):
+            # Capture whether protection was active during the call.
+            seen["protected"] = aux._aux_interrupt_protected()
+            seen["task"] = kwargs.get("task")
+            return _Resp()
+
+        with patch("agent.context_compressor.get_model_context_length", return_value=100000):
+            c = ContextCompressor(model="test", quiet_mode=True)
+
+        msgs = [
+            {"role": "user", "content": "do a thing"},
+            {"role": "assistant", "content": "working"},
+            {"role": "user", "content": "more"},
+            {"role": "assistant", "content": "done"},
+        ]
+        with patch("agent.context_compressor.call_llm", side_effect=fake_call_llm):
+            summary = c._generate_summary(msgs)
+
+        assert summary is not None
+        assert seen.get("task") == "compression"
+        assert seen.get("protected") is True, (
+            "compression summary call must run under aux_interrupt_protection"
+        )
+        # Protection must be cleared after the call returns.
+        assert aux._aux_interrupt_protected() is False
+
+    def test_explicit_interrupt_is_not_degraded_into_summary_fallback(self):
+        """Ctrl+C cancellation must escape summary fallback so the outer
+        compression transaction can abort without rotating the session."""
+        from agent.context_compressor import ContextCompressor
+
+        with patch("agent.context_compressor.get_model_context_length", return_value=100000):
+            c = ContextCompressor(model="test", quiet_mode=True)
+
+        msgs = [
+            {"role": "user", "content": "do a thing"},
+            {"role": "assistant", "content": "working"},
+            {"role": "user", "content": "more"},
+            {"role": "assistant", "content": "done"},
+        ]
+        with aux.aux_interrupt_protection(cancel_check=lambda: True), patch(
+            "agent.context_compressor.call_llm",
+            side_effect=aux.AuxiliaryExplicitCancellation(),
+        ):
+            try:
+                c._generate_summary(msgs)
+            except aux.AuxiliaryExplicitCancellation as exc:
+                assert exc.cause == "explicit_host_cancel"
+            else:
+                raise AssertionError("compression swallowed an explicit interrupt")
+
+    def test_non_explicit_interrupted_error_remains_provider_failure(self):
+        """An unrelated provider/OS InterruptedError must keep the established
+        summary-failure fallback semantics when no host cancel was requested."""
+        from agent.context_compressor import ContextCompressor
+
+        with patch("agent.context_compressor.get_model_context_length", return_value=100000):
+            c = ContextCompressor(model="test", quiet_mode=True)
+
+        msgs = [
+            {"role": "user", "content": "do a thing"},
+            {"role": "assistant", "content": "working"},
+            {"role": "user", "content": "more"},
+            {"role": "assistant", "content": "done"},
+        ]
+        with patch(
+            "agent.context_compressor.call_llm",
+            side_effect=InterruptedError("provider syscall interrupted"),
+        ):
+            assert c._generate_summary(msgs) is None
+
+    def test_explicit_interrupt_restores_rehydration_state(self):
+        """Cancellation after the handoff scan must be a compressor no-op."""
+        from agent.context_compressor import ContextCompressor
+
+        with patch("agent.context_compressor.get_model_context_length", return_value=100000):
+            c = ContextCompressor(
+                model="test",
+                protect_first_n=1,
+                protect_last_n=1,
+                quiet_mode=True,
+            )
+        c._previous_summary = "foreign-session-summary"
+        c._summary_has_user_turn = False
+        msgs = [
+            {"role": "system", "content": "system"},
+            {"role": "user", "content": "one"},
+            {"role": "assistant", "content": "two"},
+            {"role": "user", "content": "three"},
+            {"role": "assistant", "content": "four"},
+            {"role": "user", "content": "five"},
+            {"role": "assistant", "content": "six"},
+            {"role": "user", "content": "tail"},
+        ]
+
+        with patch.object(
+            c,
+            "_generate_summary",
+            side_effect=aux.AuxiliaryExplicitCancellation(),
+        ):
+            with pytest.raises(aux.AuxiliaryExplicitCancellation):
+                c.compress(msgs)
+
+        assert c._previous_summary == "foreign-session-summary"
+        assert c._summary_has_user_turn is False

tests/agent/test_compression_max_attempts_config.py

@@ -0,0 +1,93 @@
+"""compression.max_attempts — config-driven compression retry cap.
+
+The conversation loop's compression retry cap was hardcoded to 3, stranding
+sessions that legitimately need more rounds — e.g. a restart history reload
+whose incompressible tool schemas keep the request estimate above the
+threshold while the messages themselves compress fine (the #62605 failure
+class).  The cap is now parsed from ``compression.max_attempts`` in
+``agent_init`` and read by the loop via
+``getattr(agent, "max_compression_attempts", 3)``.
+
+These tests pin the parse/validate/attach seam: default preserved, custom
+value honored, floor and ceiling enforced, garbage tolerated.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+from pathlib import Path
+
+from hermes_state import SessionDB
+from run_agent import AIAgent
+
+
+def _config(max_attempts=None) -> dict:
+    compression = {
+        "enabled": True,
+        "threshold": 0.50,
+        "target_ratio": 0.20,
+        "protect_first_n": 3,
+        "protect_last_n": 20,
+    }
+    if max_attempts is not None:
+        compression["max_attempts"] = max_attempts
+    return {
+        "compression": compression,
+        "prompt_caching": {"cache_ttl": "5m"},
+        "sessions": {},
+        "bedrock": {},
+    }
+
+
+def _make_agent(monkeypatch, tmp_path: Path, *, max_attempts=None):
+    from hermes_cli import config as config_mod
+
+    monkeypatch.setattr(
+        config_mod, "load_config", lambda: _config(max_attempts=max_attempts)
+    )
+    monkeypatch.setattr(
+        config_mod, "load_config_readonly", lambda: _config(max_attempts=max_attempts)
+    )
+    db = SessionDB(db_path=tmp_path / "state.db")
+    with contextlib.redirect_stdout(io.StringIO()):
+        agent = AIAgent(
+            base_url="https://chatgpt.com/backend-api/codex",
+            api_key="test-key",
+            provider="openai-codex",
+            model="gpt-5.5",
+            enabled_toolsets=[],
+            disabled_toolsets=[],
+            quiet_mode=True,
+            skip_memory=True,
+            session_db=db,
+            session_id="max-attempts-test",
+        )
+    return agent
+
+
+class TestCompressionMaxAttemptsConfig:
+    def test_default_is_three_when_unset(self, monkeypatch, tmp_path):
+        agent = _make_agent(monkeypatch, tmp_path)
+        assert agent.max_compression_attempts == 3
+
+    def test_custom_value_is_honored(self, monkeypatch, tmp_path):
+        agent = _make_agent(monkeypatch, tmp_path, max_attempts=6)
+        assert agent.max_compression_attempts == 6
+
+
+
+
+
+
+
+    def test_loop_pickup_degrades_to_default_when_attribute_missing(
+        self, monkeypatch, tmp_path
+    ):
+        # The loop reads getattr(agent, "max_compression_attempts", 3): a
+        # configured agent exposes its value, and an object without the
+        # attribute (older pickle / minimal stub) degrades to the prior
+        # hardcoded behavior.
+        agent = _make_agent(monkeypatch, tmp_path, max_attempts=7)
+        assert getattr(agent, "max_compression_attempts", 3) == 7
+        assert getattr(object(), "max_compression_attempts", 3) == 3

tests/agent/test_compression_split_failure_cooldown.py

@@ -0,0 +1,56 @@
+"""Regression tests: a failed compression split must arm the failure cooldown.
+
+Extracted from PR #98137's test file (author: vsd2807); two sibling unit
+tests were dropped as duplicates of existing coverage in
+test_compression_rotation_state.py / test_context_compressor.py, and the
+timeout-reconciliation tests were not carried because that production path
+was not salvaged (blocking review on #98137).
+
+Issue #97948 symptom B: without the cooldown, the turn after a
+session_split_failed abort immediately re-runs the identical doomed
+compression.
+"""
+
+import time
+from unittest.mock import MagicMock
+
+
+def test_manual_compress_bypasses_cooldown():
+    """Manual /compress (force=True) bypasses cooldown — existing behavior preserved."""
+    from agent.conversation_compression import compress_context
+
+    compressor_mock = MagicMock()
+    compressor_mock._summary_failure_cooldown_until = time.monotonic() + 60.0
+    compressor_mock._last_summary_error = "session_split_failed"
+    compressor_mock._cooldown_persist_failed = False
+    compressor_mock._anti_thrash_recovery_deadline = 0.0
+    compressor_mock._consecutive_ineffective_compressions = 0
+    compressor_mock._summary_failure_streak = 0
+    compressor_mock._last_compaction_boundary_tokens = None
+    compressor_mock._verify_compaction_cleared_threshold = False
+    compressor_mock._proactive_prune_rearm_tokens = None
+    compressor_mock.compression_count = 0
+    compressor_mock.threshold_tokens = 10000
+    compressor_mock.context_length = 128000
+    compressor_mock.tail_token_budget = 25000
+    compressor_mock.summary_target_ratio = 0.1
+    compressor_mock._last_cooldown_refresh_was_authoritative = None
+
+    agent_mock = MagicMock()
+    agent_mock.context_compressor = compressor_mock
+    agent_mock.compression_enabled = True
+    agent_mock.session_id = "test-session"
+    agent_mock._session_db = MagicMock()
+    agent_mock._session_db.try_acquire_compression_lock.return_value = False
+
+    messages = [{"role": "user", "content": "hello"}]
+
+    result = compress_context(
+        agent_mock,
+        messages,
+        None,
+        force=True,
+        task_id="test",
+    )
+
+    assert result is not None

tests/agent/test_content_policy_blocked.py

@@ -0,0 +1,142 @@
+"""Regression guard for #18028: provider content-policy / safety-filter
+blocks must classify as ``content_policy_blocked``, be non-retryable, and
+trigger the ``is_client_error`` abort path so the loop jumps straight to a
+configured fallback or surfaces a clear policy-block message — instead of
+burning ``api_max_retries`` paid attempts on a deterministic refusal and
+delivering "API failed after 3 retries" to Telegram/cron with no provider
+context.
+
+Real-world symptom from the issue:
+    ``API call failed after 3 retries — This content was flagged for
+    possible cybersecurity risk... | provider=openai-codex model=gpt-5.5``
+repeating across cron jobs and gateway sessions, with the user unable to
+tell whether the gateway was broken, the model was down, or their prompt
+was the problem.
+"""
+from __future__ import annotations
+
+
+class TestContentPolicyBlockedClassification:
+    """Verify classify_api_error returns the right shape so downstream
+    recovery (fallback activation, final_response wording) fires correctly.
+    """
+
+    def test_openai_codex_cybersecurity_no_status(self):
+        """The reported #18028 case — SDK raises without a status code."""
+        from agent.error_classifier import classify_api_error, FailoverReason
+
+        e = Exception(
+            "This content was flagged for possible cybersecurity risk. "
+            "If this seems wrong, try rephrasing your request. To get "
+            "authorized for security work, join the Trusted Access for "
+            "Cyber program."
+        )
+        result = classify_api_error(e, provider="openai-codex", model="gpt-5.5")
+        # Must NOT fall into the retryable ``unknown`` bucket — that's what
+        # caused the 3x retry burn.
+        assert result.reason == FailoverReason.content_policy_blocked
+        assert result.retryable is False
+        # Recovery is fallback model, not credential rotation or compression.
+        assert result.should_fallback is True
+        assert result.should_compress is False
+        assert result.should_rotate_credential is False
+
+
+
+class TestContentPolicyTriggersClientErrorAbort:
+    """Mirror the ``is_client_error`` predicate in
+    ``agent/conversation_loop.py`` and verify
+    ``FailoverReason.content_policy_blocked`` resolves to True so the loop
+    aborts (after attempting fallback) instead of falling into the
+    retry-backoff path.
+    """
+
+    def _mirror_is_client_error(
+        self,
+        *,
+        classified_retryable: bool,
+        classified_reason,
+        classified_should_compress: bool = False,
+        is_local_validation_error: bool = False,
+        is_context_length_error: bool = False,
+    ) -> bool:
+        """Exact shape of conversation_loop.py's is_client_error check.
+
+        Kept in lock-step with the source. If you change one, change both.
+        """
+        from agent.error_classifier import FailoverReason
+
+        return (
+            is_local_validation_error
+            or (
+                not classified_retryable
+                and not classified_should_compress
+                and classified_reason not in {
+                    FailoverReason.rate_limit,
+                    FailoverReason.overloaded,
+                    FailoverReason.context_overflow,
+                    FailoverReason.payload_too_large,
+                    FailoverReason.long_context_tier,
+                    FailoverReason.thinking_signature,
+                }
+            )
+        ) and not is_context_length_error
+
+    def test_content_policy_blocked_triggers_abort(self):
+        """Safety-filter block must reach is_client_error → fallback/abort."""
+        from agent.error_classifier import FailoverReason
+
+        # What classify_api_error returns for a content-policy block:
+        #   reason=content_policy_blocked, retryable=False, should_compress=False
+        assert self._mirror_is_client_error(
+            classified_retryable=False,
+            classified_reason=FailoverReason.content_policy_blocked,
+        ), (
+            "FailoverReason.content_policy_blocked must trigger the "
+            "is_client_error path so fallback fires immediately instead of "
+            "burning api_max_retries paid attempts on a deterministic "
+            "safety refusal — see #18028."
+        )
+
+
+class TestContentPolicyPatternsAreNarrow:
+    """Defensive guard: the safety-filter patterns must not collide with
+    benign error wording from billing / format / generic 400 errors. If
+    these regress to ``content_policy_blocked``, recovery will route to
+    the wrong code path (fallback model instead of credential rotation).
+    """
+
+    def test_generic_400_format_error_not_misclassified(self):
+        from agent.error_classifier import classify_api_error, FailoverReason
+
+        class _Err(Exception):
+            def __init__(self, msg, status_code):
+                super().__init__(msg)
+                self.status_code = status_code
+
+        e = _Err("Invalid request: messages must be a non-empty list", status_code=400)
+        result = classify_api_error(e, provider="openai", model="gpt-4o")
+        assert result.reason != FailoverReason.content_policy_blocked
+
+
+    def test_openrouter_account_policy_block_stays_distinct(self):
+        """``provider_policy_blocked`` (OpenRouter account-level data
+        policy) must remain a separate classification from
+        ``content_policy_blocked`` (upstream model safety filter) — they
+        have different recovery strategies.
+        """
+        from agent.error_classifier import classify_api_error, FailoverReason
+
+        class _Err(Exception):
+            def __init__(self, msg, status_code):
+                super().__init__(msg)
+                self.status_code = status_code
+
+        e = _Err(
+            "No endpoints available matching your guardrail restrictions "
+            "and data policy",
+            status_code=404,
+        )
+        result = classify_api_error(e, provider="openrouter", model="anthropic/claude-opus")
+        assert result.reason == FailoverReason.provider_policy_blocked
+        assert result.reason != FailoverReason.content_policy_blocked

tests/agent/test_context_compressor_structural_backoff.py

@@ -0,0 +1,161 @@
+"""Structural no-op backoff (#93022).
+
+A compression attempt that finds nothing eligible inside the protection
+window (too few messages / empty window / post-handoff residue) is "nothing
+to compress right now", not an ineffective attempt: it must defer retries
+transiently instead of arming the permanent anti-thrash breaker, so a short
+session can still auto-compact after it grows real compressible material.
+"""
+
+import time
+from unittest.mock import MagicMock, patch
+
+from agent.context_compressor import ContextCompressor
+
+
+def _compressor(protect_first_n: int = 1) -> ContextCompressor:
+    with patch("agent.context_compressor.get_model_context_length", return_value=100000):
+        return ContextCompressor(
+            model="test/model",
+            threshold_percent=0.85,
+            protect_first_n=protect_first_n,
+            protect_last_n=1,
+            quiet_mode=True,
+        )
+
+
+def _response(content: str):
+    mock_response = MagicMock()
+    mock_response.choices = [MagicMock()]
+    mock_response.choices[0].message.content = content
+    return mock_response
+
+
+def test_insufficient_messages_backs_off_without_strike():
+    """Too few messages -> structural backoff, breaker stays untouched."""
+    compressor = _compressor()
+    messages = [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": "hello"},
+    ]
+
+    result = compressor.compress(messages, current_tokens=90_000)
+
+    assert result == messages
+    assert compressor._ineffective_compression_count == 0
+    assert compressor._structural_no_op_backoff_until > 0.0
+    telemetry = compressor._last_compression_telemetry or {}
+    assert telemetry.get("failure_class") == "insufficient_messages"
+
+
+def test_no_compressible_window_backs_off_without_strike():
+    """Transcript inside the tail budget -> backoff, breaker untouched."""
+    compressor = _compressor()
+    messages = [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": "turn one"},
+        {"role": "assistant", "content": "answer one"},
+        {"role": "user", "content": "turn two"},
+        {"role": "assistant", "content": "answer two"},
+        {"role": "user", "content": "turn three"},
+        {"role": "assistant", "content": "answer three"},
+        {"role": "user", "content": "latest request in protected tail"},
+    ]
+
+    with patch.object(compressor, "_find_tail_cut_by_tokens", return_value=2):
+        result = compressor.compress(messages, current_tokens=90_000)
+
+    assert result == messages
+    assert compressor._ineffective_compression_count == 0
+    assert compressor._structural_no_op_backoff_until > 0.0
+    telemetry = compressor._last_compression_telemetry or {}
+    assert telemetry.get("failure_class") == "no_compressible_window"
+
+
+def test_gate_blocked_during_backoff_then_resumes():
+    """should_compress defers during the backoff and recovers after it lapses.
+
+    The transcript sits over the compression threshold the whole time; only
+    the clock changes, proving the block is transient rather than a latched
+    breaker state.
+    """
+    compressor = _compressor()
+
+    # While the structural backoff is live the gate must say blocked.
+    compressor._structural_no_op_backoff_until = time.monotonic() + 300.0
+    with patch.object(
+        compressor, "_automatic_compression_blocked", return_value=True
+    ):
+        should, reason = compressor.should_compress_info(prompt_tokens=300_000)
+        assert should is False
+        assert reason is not None
+        assert reason.startswith("structural_backoff:")
+        assert compressor._compression_block_reason().startswith(
+            "structural_backoff:"
+        )
+
+    # After the backoff lapses nothing blocks: same over-threshold
+    # transcript compresses again (real gate, real state).
+    compressor._structural_no_op_backoff_until = (
+        time.monotonic() - 1.0
+    )
+    should, reason = compressor.should_compress_info(prompt_tokens=300_000)
+    assert should is True
+    assert reason is None
+
+
+SUMMARY_RESPONSE = "fresh replacement summary body"
+
+
+def _messages_with_old_handoff():
+    return [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": (
+            "CONTEXT SUMMARY (from previous session):\nold summary body"
+        )},
+        {"role": "assistant", "content": "handoff acknowledged after resume"},
+        {"role": "user", "content": "new user turn after resume"},
+        {"role": "assistant", "content": "new assistant work after resume"},
+        {"role": "user", "content": "more new work after resume"},
+        {"role": "assistant", "content": "latest tail response"},
+        {"role": "user", "content": "final active request stays in protected tail"},
+    ]
+
+
+def test_forced_attempt_and_success_lift_the_backoff():
+    """Manual /compress clears an active backoff; a completed boundary lifts it.
+
+    Both are proof the transcript is being actively worked on — neither may
+    leave auto-compaction deferred by a stale structural no-op.
+    """
+    compressor = _compressor()
+    compressor._structural_no_op_backoff_until = time.monotonic() + 300.0
+
+    with patch(
+        "agent.context_compressor.call_llm",
+        return_value=_response(SUMMARY_RESPONSE),
+    ):
+        compressed = compressor.compress(
+            _messages_with_old_handoff(), force=True
+        )
+
+    assert compressor._structural_no_op_backoff_until == 0.0
+    # The forced attempt actually committed a boundary.
+    assert len(compressed) < len(_messages_with_old_handoff())
+
+
+def test_real_attempt_underperformance_still_strikes_breaker():
+    """Only genuine attempted-but-underperformed compressions strike.
+
+    A real summary pass that saves <10% goes through the ineffective
+    verdict (persisted); structural no-ops must not touch that counter —
+    that distinction IS this fix.
+    """
+    compressor = _compressor()
+    before = compressor._ineffective_compression_count
+    compressor._record_ineffective_compression_verdict(before + 1)
+    assert compressor._ineffective_compression_count == before + 1
+
+    compressor._record_structural_no_op("test reason")
+    assert compressor._structural_no_op_backoff_until > 0.0
+    assert compressor._ineffective_compression_count == before + 1

tests/agent/test_context_compressor_summary_continuity.py

@@ -0,0 +1,461 @@
+"""Regression tests for iterative context-summary continuity."""
+
+from unittest.mock import MagicMock, patch
+
+from agent.context_compressor import (
+    COMPRESSED_SUMMARY_METADATA_KEY,
+    ContextCompressor,
+    SUMMARY_PREFIX,
+    _MERGED_PRIOR_CONTEXT_HEADER,
+    _MERGED_SUMMARY_DELIMITER,
+    _RESTART_HANDOFF_PROBE_EXTRA_MESSAGES,
+    _SUMMARY_END_MARKER,
+)
+
+
+def _compressor(protect_first_n: int = 1) -> ContextCompressor:
+    with patch("agent.context_compressor.get_model_context_length", return_value=100000):
+        return ContextCompressor(
+            model="test/model",
+            threshold_percent=0.85,
+            protect_first_n=protect_first_n,
+            protect_last_n=1,
+            quiet_mode=True,
+            # Pinned: these tests assert the stored summary ENDS with the raw
+            # LLM text. Lean mode (the default since the tail-default flip)
+            # appends the verbatim-user-quote appendix after it by design;
+            # the continuity contract under test is mode-independent.
+            tail_mode="legacy",
+        )
+
+
+def _response(content: str):
+    mock_response = MagicMock()
+    mock_response.choices = [MagicMock()]
+    mock_response.choices[0].message.content = content
+    return mock_response
+
+
+def _messages_with_handoff(summary_body: str):
+    return [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": f"{SUMMARY_PREFIX}\n{summary_body}"},
+        {"role": "assistant", "content": "handoff acknowledged after resume"},
+        {"role": "user", "content": "new user turn after resume"},
+        {"role": "assistant", "content": "new assistant work after resume"},
+        {"role": "user", "content": "more new work after resume"},
+        {"role": "assistant", "content": "latest tail response"},
+        {"role": "user", "content": "final active request stays in protected tail"},
+    ]
+
+
+def _messages_with_merged_handoff(summary_body: str, prior_tail: str):
+    merged = {
+        "role": "user",
+        "content": (
+            f"{_MERGED_PRIOR_CONTEXT_HEADER}\n{prior_tail}\n\n"
+            f"{_MERGED_SUMMARY_DELIMITER}\n\n"
+            f"{SUMMARY_PREFIX}\n{summary_body}\n\n{_SUMMARY_END_MARKER}"
+        ),
+        COMPRESSED_SUMMARY_METADATA_KEY: True,
+    }
+    messages = _messages_with_handoff(summary_body)
+    messages[1] = merged
+    return messages
+
+
+def _messages_with_default_handoff(summary_body: str):
+    return [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": "original task before first compaction"},
+        {"role": "assistant", "content": "original answer before first compaction"},
+        {"role": "user", "content": "original follow-up before first compaction"},
+        {"role": "assistant", "content": f"{SUMMARY_PREFIX}\n{summary_body}"},
+        {"role": "user", "content": "new user turn after restart"},
+        {"role": "assistant", "content": "new assistant work after restart"},
+        {"role": "user", "content": "more new work after restart"},
+        {"role": "assistant", "content": "latest tail response"},
+        {"role": "user", "content": "final active request stays in protected tail"},
+    ]
+
+
+def _messages_with_summary_at_index(summary_index: int):
+    msgs = [{"role": "system", "content": "system prompt"}]
+    for idx in range(1, summary_index):
+        role = "user" if idx % 2 else "assistant"
+        msgs.append({"role": role, "content": f"probe filler {idx}"})
+    role = "user" if summary_index % 2 else "assistant"
+    msgs.append({"role": role, "content": f"{SUMMARY_PREFIX}\nboundary summary"})
+    msgs.extend([
+        {"role": "assistant", "content": "new answer"},
+        {"role": "user", "content": "tail request"},
+    ])
+    return msgs
+
+
+
+
+
+
+
+
+def test_handoff_in_protected_head_is_replaced_not_duplicated():
+    """Re-compaction must replace a protected old handoff with the updated one."""
+    compressor = _compressor()
+    old_summary = "OLD-PROTECTED-HANDOFF unique old summary body"
+
+    with patch("agent.context_compressor.call_llm", return_value=_response("UPDATED summary body")):
+        compressed = compressor.compress(_messages_with_handoff(old_summary))
+
+    # The summary may be emitted standalone or merged into the first tail
+    # message (alternation corner case), so detect it the same way the
+    # compressor does rather than via a startswith(SUMMARY_PREFIX) check.
+    summary_messages = [
+        msg
+        for msg in compressed
+        if isinstance(msg, dict)
+        and ContextCompressor._is_context_summary_content(msg.get("content"))
+    ]
+    assert len(summary_messages) == 1
+    assert "UPDATED summary body" in str(summary_messages[0]["content"])
+    assert old_summary not in str(summary_messages[0]["content"])
+    assert old_summary not in "\n".join(str(msg.get("content") or "") for msg in compressed)
+
+
+
+
+
+
+def test_recompression_of_current_merged_handoff_preserves_prior_tail_once():
+    """Current merged handoffs lose only stale summary data on recompression.
+
+    Composed contract after #57835 (restart head-protection decay): the
+    merged handoff's genuine prior-tail content must be RECOVERED — either
+    verbatim in the output (pre-decay head protection) or by entering the
+    summarizer input so the fresh summary folds it in (post-decay). It must
+    never be silently deleted, and the stale summary body must never be
+    re-emitted verbatim.
+    """
+    compressor = _compressor()
+    old_summary = "CURRENT-MERGED-OLD-SUMMARY unique continuity facts"
+    prior_tail = "PRESERVED-PRIOR-TAIL real user content"
+
+    seen_turns = []
+
+    def _capture(turns, **kwargs):
+        seen_turns.extend(turns)
+        return ContextCompressor._with_summary_prefix(
+            "fresh replacement summary"
+        )
+
+    with patch.object(
+        compressor,
+        "_generate_summary",
+        side_effect=_capture,
+    ):
+        result = compressor.compress(
+            _messages_with_merged_handoff(old_summary, prior_tail)
+        )
+
+    joined = "\n".join(str(message.get("content", "")) for message in result)
+    summarizer_input = "\n".join(str(t.get("content", "")) for t in seen_turns)
+    # Prior tail recovered: verbatim in output OR folded via summarizer input.
+    assert prior_tail in joined or prior_tail in summarizer_input
+    # Never duplicated in the output.
+    assert joined.count(prior_tail) <= 1
+    assert old_summary not in joined
+    assert joined.count(SUMMARY_PREFIX) == 1
+    assert "fresh replacement summary" in joined
+
+
+
+
+
+
+
+
+def test_resume_handoff_after_default_protected_head_decays_initial_turns():
+    """Default protect_first_n=3 should not fossilize old protected head turns."""
+    compressor = _compressor(protect_first_n=3)
+    old_summary = "DEFAULT-RESTART-SUMMARY durable facts from before restart"
+
+    with patch("agent.context_compressor.call_llm", return_value=_response("fresh summary")) as mock_call:
+        result = compressor.compress(_messages_with_default_handoff(old_summary))
+
+    prompt = mock_call.call_args.kwargs["messages"][0]["content"]
+    assert "PREVIOUS SUMMARY:" in prompt
+    assert prompt.count(old_summary) == 1
+    assert "original task before first compaction" in prompt
+    assert "original answer before first compaction" in prompt
+    assert "original follow-up before first compaction" in prompt
+    assert f"[ASSISTANT]: {SUMMARY_PREFIX}" not in prompt
+    # Grounding (761a0b124e) may prepend a deterministic task-snapshot
+    # section — pin the contract, not the exact stored string.
+    stored_summary = compressor._previous_summary or ""
+    assert stored_summary.endswith("fresh summary")
+    assert old_summary not in stored_summary
+    assert all(
+        "original task before first compaction" not in str(msg.get("content", ""))
+        for msg in result
+    )
+    assert all(
+        "original answer before first compaction" not in str(msg.get("content", ""))
+        for msg in result
+    )
+    assert all(
+        old_summary not in str(msg.get("content", ""))
+        for msg in result
+    )
+
+
+def test_restart_simulation_fresh_compressor_does_not_reprotect_head():
+    """Gateway-restart simulation: a FRESH ContextCompressor (in-memory decay
+    state reset — compression_count == 0, _previous_summary is None) over a
+    transcript that contains a persisted handoff summary must NOT re-protect
+    the head. compress_start must reflect decayed protection exactly as a
+    live (non-restarted) process would compute it (#57814)."""
+    # Live process: has already compacted once, decay is in-memory.
+    live = _compressor(protect_first_n=3)
+    live.compression_count = 1
+
+    # Restarted process: brand-new compressor, all in-memory state fresh.
+    restarted = _compressor(protect_first_n=3)
+    assert restarted.compression_count == 0
+    assert not restarted._previous_summary
+
+    msgs = _messages_with_default_handoff(
+        "PERSISTED-HANDOFF durable facts from before restart"
+    )
+
+    # The protected-head boundary the compressor uses for compress_start
+    # must be identical for both: system prompt only (decayed protection).
+    assert restarted._effective_protect_first_n(msgs) == 0
+    assert restarted._protect_head_size(msgs) == live._protect_head_size(msgs) == 1
+    restarted_start = restarted._align_boundary_forward(
+        msgs, restarted._protect_head_size(msgs)
+    )
+    assert restarted_start == 1
+
+    # End-to-end: the first post-restart compaction must not preserve the
+    # pre-restart head turns or the old handoff verbatim.
+    with patch("agent.context_compressor.call_llm", return_value=_response("fresh summary")):
+        result = restarted.compress(msgs)
+    result_text = "\n".join(str(msg.get("content", "")) for msg in result)
+    assert "PERSISTED-HANDOFF durable facts" not in result_text
+    assert "original task before first compaction" not in result_text
+    assert "original answer before first compaction" not in result_text
+
+
+
+
+
+
+
+
+def test_zero_protect_first_n_still_folds_restart_fossil():
+    """protect_first_n=0 should still self-heal restarted summaries."""
+    compressor = _compressor(protect_first_n=0)
+    old_summary = "OLD-SUMMARY-ZERO-PROTECT durable facts"
+    msgs = [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": "task one"},
+        {"role": "assistant", "content": "answer one"},
+        {"role": "user", "content": "task two"},
+        {"role": "assistant", "content": f"{SUMMARY_PREFIX}\n{old_summary}"},
+        {"role": "user", "content": "active request"},
+    ]
+
+    with patch("agent.context_compressor.call_llm", return_value=_response("fresh summary")):
+        result = compressor.compress(msgs)
+
+    result_text = "\n".join(str(msg.get("content", "")) for msg in result)
+    assert old_summary not in result_text
+    assert result_text.index(_SUMMARY_END_MARKER) < result_text.index("active request")
+    assert sum(
+        1 for msg in result if ContextCompressor._is_context_summary_message(msg)
+    ) == 1
+
+
+
+
+def test_restart_fossil_survives_summary_abort_then_retry():
+    """An aborted first compaction must not strand the rehydrated fossil.
+
+    Regression for the abort/retry path. The first-compaction self-heal scan
+    (``compression_count < 1``) populates ``_previous_summary`` from a fossil
+    that drifted past the decay probe. If summary generation then aborts
+    (auth / network / ``abort_on_summary_failure``) and returns the transcript
+    unchanged, the aborted attempt must not leave that rehydrated state behind:
+    otherwise the retry — still ``compression_count == 0`` but now with a
+    truthy ``_previous_summary`` — takes the narrow rescan, misses the
+    beyond-window fossil, and then discards the rehydrated summary as
+    cross-session leakage, copying the fossil forward as a stacked summary.
+    """
+    compressor = _compressor(protect_first_n=1)
+    compressor.abort_on_summary_failure = True
+    old_summary = "ABORT-RETRY-OLD-SUMMARY durable facts"
+    msgs = [{"role": "system", "content": "system prompt"}]
+    msgs += [
+        {
+            "role": "user" if idx % 2 else "assistant",
+            "content": f"filler {idx}",
+        }
+        for idx in range(1, 6)
+    ]
+    msgs += [
+        {"role": "assistant", "content": f"{SUMMARY_PREFIX}\n{old_summary}"},
+        {"role": "user", "content": "active request"},
+    ]
+
+    # First compaction aborts on a summary-generation failure. The transcript
+    # is returned unchanged AND the self-heal state it rehydrated must be
+    # rolled back, so a retry behaves like the original first compaction.
+    with patch.object(compressor, "_generate_summary", return_value=None):
+        aborted = compressor.compress([dict(m) for m in msgs])
+    assert compressor._last_compress_aborted is True
+    assert all(m["content"] for m in aborted)  # returned unchanged
+    assert compressor.compression_count == 0
+    assert compressor._previous_summary is None
+
+    # Retry: the fossil beyond the narrow window is still folded, not copied
+    # forward as a second stacked summary.
+    with patch("agent.context_compressor.call_llm", return_value=_response("fresh summary")):
+        result = compressor.compress([dict(m) for m in msgs])
+
+    assert all(old_summary not in str(msg.get("content", "")) for msg in result)
+    assert sum(
+        1 for msg in result if ContextCompressor._is_context_summary_message(msg)
+    ) == 1
+
+
+def test_degenerate_compress_end_keeps_same_session_previous_summary():
+    """Handoff beyond a degenerate compress_end must not clear same-session state.
+
+    Regression for #83248: with compression_count >= 1 and a truthy
+    ``_previous_summary`` from this session's prior compaction, a scan bounded
+    at ``compress_end`` can miss an in-window handoff sitting past the cut.
+    The #57835 cross-session guard then discarded the valid summary and the
+    from-scratch path replaced a rich handoff with a one-turn summary.
+    """
+    compressor = _compressor(protect_first_n=0)
+    rich_summary = (
+        "RICH-SAME-SESSION-HANDOFF\n"
+        "1. completed action alpha\n"
+        "2. completed action beta\n"
+        "3. completed action gamma"
+    )
+    compressor.compression_count = 1
+    compressor._previous_summary = rich_summary
+
+    messages = [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": "early turn before cut"},
+        {"role": "assistant", "content": "early answer"},
+        {"role": "user", "content": "mid turn before handoff"},
+        {"role": "assistant", "content": f"{SUMMARY_PREFIX}\n{rich_summary}"},
+        {"role": "user", "content": "post handoff turn"},
+        {"role": "assistant", "content": "post handoff answer"},
+        {"role": "user", "content": "tail request"},
+    ]
+    # Handoff is at index 4; force compress_end=2 so a compress_end-bounded
+    # scan would miss it while still leaving a non-empty middle window.
+    assert ContextCompressor._is_context_summary_message(messages[4])
+
+    previous_at_generate = []
+
+    def _capture(turns, **kwargs):
+        previous_at_generate.append(compressor._previous_summary)
+        return ContextCompressor._with_summary_prefix("updated iterative summary")
+
+    with (
+        patch.object(compressor, "_find_tail_cut_by_tokens", return_value=2),
+        patch.object(compressor, "_generate_summary", side_effect=_capture),
+    ):
+        result = compressor.compress(messages, current_tokens=90_000)
+
+    assert previous_at_generate, "_generate_summary should have run"
+    assert previous_at_generate[0] is not None, (
+        "same-session _previous_summary must not be discarded when a handoff "
+        "exists beyond a degenerate compress_end"
+    )
+    assert "RICH-SAME-SESSION-HANDOFF" in previous_at_generate[0]
+    # Iterative state must remain available after the attempt (either the
+    # prior rich handoff, or the updated summary if the compaction committed).
+    assert compressor._previous_summary is not None
+    stored = compressor._previous_summary or ""
+    assert (
+        "RICH-SAME-SESSION-HANDOFF" in stored
+        or "updated iterative summary" in stored
+    )
+    assert sum(
+        1 for msg in result if ContextCompressor._is_context_summary_message(msg)
+    ) >= 1
+
+
+
+
+def test_forced_leading_merged_summary_strips_live_tail_from_summary_body():
+    """Rehydrating a forced-leading merged summary should ignore live tail."""
+    merged = (
+        f"{SUMMARY_PREFIX}\nSUMMARY_BODY\n\n"
+        f"{_SUMMARY_END_MARKER}\n\n"
+        "LIVE_TAIL_REQUEST"
+    )
+
+    assert ContextCompressor._is_context_summary_content(merged) is True
+    assert ContextCompressor._strip_summary_prefix(merged) == "SUMMARY_BODY"
+
+
+
+
+
+
+
+
+
+
+def test_empty_post_handoff_window_noops_without_summary_call():
+    """A latest handoff that consumes the window must not trigger an empty summary.
+
+    Regression test from PR #59526 (#59496), fixture adapted to current main:
+    the standalone handoff sits alone in the compressible window, strips to
+    None via _strip_context_summary_handoff_message, and leaves
+    turns_to_summarize empty — the guard must skip _generate_summary
+    entirely instead of wasting an aux LLM call on empty input.
+    """
+    compressor = _compressor()
+    old_summary = "WINDOW-END-SUMMARY durable facts already captured"
+    messages = [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": f"{SUMMARY_PREFIX}\n{old_summary}"},
+        {"role": "assistant", "content": "recent tail response"},
+        {"role": "user", "content": "tail request"},
+        {"role": "assistant", "content": "tail answer"},
+        {"role": "user", "content": "latest tail request"},
+        {"role": "assistant", "content": "latest tail answer"},
+    ]
+
+    with (
+        patch.object(compressor, "_find_tail_cut_by_tokens", return_value=2),
+        patch.object(compressor, "_generate_summary") as mock_generate_summary,
+    ):
+        result = compressor.compress(messages, current_tokens=90_000)
+
+    mock_generate_summary.assert_not_called()
+    assert result == messages
+    # The rehydrated summary state is deliberately kept: the handoff is
+    # genuinely present in the returned (unchanged) transcript.
+    assert compressor._previous_summary == old_summary
+    assert compressor.compression_count == 0
+    # Mirrors the sibling no-compressible-window guard, but as a structural
+    # no-op (#93022): the window holds nothing eligible to compress, so the
+    # compressor defers retries transiently instead of arming the permanent
+    # anti-thrash breaker.
+    assert compressor._ineffective_compression_count == 0
+    assert compressor._structural_no_op_backoff_until > 0.0
+    assert compressor._last_compression_savings_pct == 0.0
+    assert compressor._last_summary_dropped_count == 0
+    assert compressor._last_summary_fallback_used is False
+    assert compressor._last_compress_aborted is False
+    telemetry = compressor._last_compression_telemetry or {}
+    assert telemetry.get("failure_class") == "empty_post_handoff_window"

tests/agent/test_context_compressor_zero_user_provenance.py

@@ -0,0 +1,459 @@
+"""Regression coverage for zero-user compaction integrity (#64539)."""
+
+import os
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from agent.context_compressor import (
+    COMPRESSION_CONTINUATION_USER_CONTENT,
+    COMPRESSED_SUMMARY_HAS_USER_TURN_KEY,
+    COMPRESSED_SUMMARY_METADATA_KEY,
+    HISTORICAL_TASK_HEADING,
+    MAX_ITERATIONS_SUMMARY_REQUEST,
+    SUMMARY_PREFIX,
+    ContextCompressor,
+    _NO_USER_TASK_SENTINEL,
+)
+from agent.conversation_compression import (
+    _ensure_compressed_has_user_turn,
+    compress_context,
+)
+from hermes_state import SessionDB
+from tools.process_registry_notifications import format_process_notification
+from tools.todo_tool import TODO_INJECTION_HEADER
+
+
+def _response(content: str) -> SimpleNamespace:
+    return SimpleNamespace(
+        choices=[SimpleNamespace(message=SimpleNamespace(content=content))]
+    )
+
+
+def _valid_zero_user_summary(label: str = "Checked artifacts.") -> str:
+    return f"""{HISTORICAL_TASK_HEADING}
+{_NO_USER_TASK_SENTINEL}
+
+## Goal
+Historical cron work only.
+
+## Completed Actions
+1. {label}
+
+## Resolved Questions
+None. No user-authored questions exist.
+
+## Historical Pending User Asks
+None. No user-authored requests exist.
+"""
+
+
+def _assistant_tool_turns(start: int, count: int) -> list[dict]:
+    turns: list[dict] = []
+    for idx in range(start, start + count):
+        turns.extend(
+            [
+                {
+                    "role": "assistant",
+                    "content": "Continuing scheduled work in English.",
+                    "tool_calls": [
+                        {
+                            "id": f"call-{idx}",
+                            "function": {
+                                "name": "terminal",
+                                "arguments": '{"command":"pwd"}',
+                            },
+                        }
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": f"call-{idx}",
+                    "content": "/workspace/project\n" + ("x" * 300),
+                },
+            ]
+        )
+    return turns
+
+
+def _assistant_turns(start: int, count: int) -> list[dict]:
+    return [
+        {
+            "role": "assistant",
+            "content": f"Scheduled step {idx} completed. " + ("x" * 500),
+        }
+        for idx in range(start, start + count)
+    ]
+
+
+def _lifecycle_agent(db: SessionDB, session_id: str):
+    with patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}):
+        from run_agent import AIAgent
+
+        agent = AIAgent(
+            api_key="test-key",
+            base_url="https://openrouter.ai/api/v1",
+            model="test/model",
+            quiet_mode=True,
+            session_db=db,
+            session_id=session_id,
+            skip_context_files=True,
+            skip_memory=True,
+        )
+    agent.compression_in_place = True
+    agent.context_compressor.protect_first_n = 0
+    agent.context_compressor.protect_last_n = 2
+    agent.context_compressor.tail_token_budget = 80
+    agent._todo_store.write(
+        [{"id": "inspect", "content": "Inspect artifacts", "status": "pending"}]
+    )
+    return agent
+
+
+@pytest.fixture()
+def compressor() -> ContextCompressor:
+    with patch(
+        "agent.context_compressor.get_model_context_length",
+        return_value=100_000,
+    ):
+        instance = ContextCompressor(
+            model="test/model",
+            threshold_percent=0.50,
+            protect_first_n=0,
+            protect_last_n=2,
+            quiet_mode=True,
+        )
+    instance.tail_token_budget = 80
+    return instance
+
+
+def test_generate_summary_rejects_fabricated_user_ask(compressor):
+    fabricated = f"""{HISTORICAL_TASK_HEADING}
+User asked: 'Waar zijn de bestanden gedownload?'
+
+## Goal
+Vind de bestanden.
+"""
+
+    with patch(
+        "agent.context_compressor.call_llm",
+        return_value=_response(fabricated),
+    ):
+        result = compressor._generate_summary(_assistant_tool_turns(0, 2))
+
+    assert result is None
+    assert compressor._previous_summary is None
+    assert "invented user attribution" in compressor._last_summary_error
+
+
+
+
+def test_zero_user_provenance_survives_iterative_compaction(compressor):
+    messages = _assistant_tool_turns(0, 12)
+    first_summary = f"{SUMMARY_PREFIX}\n{_valid_zero_user_summary('First pass').strip()}"
+
+    with patch.object(compressor, "_generate_summary", return_value=first_summary):
+        first = compressor.compress(messages, current_tokens=90_000)
+
+    first_handoffs = [
+        message
+        for message in first
+        if message.get(COMPRESSED_SUMMARY_METADATA_KEY)
+    ]
+    assert len(first_handoffs) == 1
+    assert first_handoffs[0][COMPRESSED_SUMMARY_HAS_USER_TURN_KEY] is False
+
+    with patch(
+        "agent.context_compressor.get_model_context_length",
+        return_value=100_000,
+    ):
+        resumed = ContextCompressor(
+            model="test/model",
+            threshold_percent=0.50,
+            protect_first_n=0,
+            protect_last_n=2,
+            quiet_mode=True,
+        )
+    resumed.tail_token_budget = 80
+    # SessionDB persists the summary content/role but not arbitrary internal
+    # message keys. Simulate that round trip: the exact sentinel must recover
+    # false provenance even when both in-process metadata keys are absent.
+    persisted_handoff = dict(first_handoffs[0])
+    persisted_handoff.pop(COMPRESSED_SUMMARY_METADATA_KEY)
+    persisted_handoff.pop(COMPRESSED_SUMMARY_HAS_USER_TURN_KEY)
+    second_input = [persisted_handoff, *_assistant_tool_turns(20, 12)]
+
+    def assert_provenance_then_summarize(*_args, **_kwargs):
+        assert resumed._summary_has_user_turn is False
+        return f"{SUMMARY_PREFIX}\n{_valid_zero_user_summary('Second pass').strip()}"
+
+    with patch.object(
+        resumed,
+        "_generate_summary",
+        side_effect=assert_provenance_then_summarize,
+    ):
+        second = resumed.compress(second_input, current_tokens=90_000)
+
+    second_handoffs = [
+        message
+        for message in second
+        if message.get(COMPRESSED_SUMMARY_METADATA_KEY)
+    ]
+    assert len(second_handoffs) == 1
+    assert second_handoffs[0][COMPRESSED_SUMMARY_HAS_USER_TURN_KEY] is False
+
+
+def test_max_iterations_nudge_is_synthetic_not_actionable():
+    """#78580: the max-iteration runtime nudge is runtime scaffolding, not a
+    human turn. It is appended as ``role="user"`` and persisted verbatim in
+    state.db (metadata flags do not survive projection), so recognition must be
+    content-based — exactly like the continuation/todo markers."""
+    # The projected form: a bare role/content row with no internal metadata.
+    nudge = {"role": "user", "content": MAX_ITERATIONS_SUMMARY_REQUEST}
+
+    assert ContextCompressor._is_synthetic_compression_user_turn(nudge) is True
+    # A real human turn with the same shape stays actionable.
+    human = {"role": "user", "content": "Ship the release notes for v2."}
+    assert ContextCompressor._is_synthetic_compression_user_turn(human) is False
+    assert ContextCompressor._transcript_has_real_user_turn([nudge]) is False
+    assert ContextCompressor._transcript_has_real_user_turn([human, nudge]) is True
+
+
+def test_real_task_wins_over_trailing_max_iterations_nudge(compressor):
+    """The tail anchor must resolve to the human task, not the nudge that the
+    runtime appended after it when iterations were exhausted."""
+    human = {"role": "user", "content": "Refactor the auth module and add tests."}
+    messages = [
+        human,
+        {"role": "assistant", "content": "Working on it.", "tool_calls": [
+            {"id": "c1", "function": {"name": "terminal", "arguments": "{}"}}
+        ]},
+        {"role": "tool", "tool_call_id": "c1", "content": "ok"},
+        {"role": "user", "content": MAX_ITERATIONS_SUMMARY_REQUEST},
+    ]
+
+    idx = compressor._find_last_user_message_idx(messages, head_end=0)
+    assert idx == 0, "nudge was selected as the anchor instead of the human task"
+    assert messages[idx]["content"] == human["content"]
+
+
+@pytest.mark.parametrize(
+    "event",
+    [
+        pytest.param(
+            {
+                "type": "completion",
+                "session_id": "proc_build",
+                "command": "scripts/run_tests.sh tests/agent/",
+                "exit_code": 0,
+                "output": "42 passed",
+            },
+            id="completion",
+        ),
+        pytest.param(
+            {
+                "type": "watch_match",
+                "session_id": "proc_server",
+                "command": "python server.py",
+                "pattern": "Application startup complete",
+                "output": "Application startup complete",
+            },
+            id="watch_match",
+        ),
+    ],
+)
+def test_background_process_notifications_do_not_become_compaction_anchors(
+    compressor, event
+):
+    notification = format_process_notification(event)
+    assert notification is not None
+    process_turn = {"role": "user", "content": notification}
+    human = {"role": "user", "content": "Refactor the auth module and add tests."}
+    messages = [
+        human,
+        {"role": "assistant", "content": "Working on it."},
+        process_turn,
+    ]
+
+    assert ContextCompressor._is_synthetic_compression_user_turn(process_turn) is True
+    assert ContextCompressor._transcript_has_real_user_turn([process_turn]) is False
+    assert compressor._derive_auto_focus_topic(messages) == (
+        "Recent user focus:\n- Refactor the auth module and add tests."
+    )
+    assert compressor._find_last_user_message_idx(messages, head_end=0) == 0
+
+
+@pytest.mark.parametrize(
+    "content",
+    [
+        pytest.param(
+            "[System: The previous response was cut off by a "
+            "network error mid-stream. Continue exactly where "
+            "you left off. Do not restart or repeat prior text. "
+            "Finish the answer directly.]",
+            id="length_continuation_network_stub",
+        ),
+        pytest.param(
+            "[System: Your previous response was truncated by the output "
+            "length limit. Continue exactly where you left off. Do not "
+            "restart or repeat prior text. Finish the answer directly.]",
+            id="length_continuation_output_limit",
+        ),
+        pytest.param(
+            "[System: Your previous tool call (write_file) was too large and "
+            "the stream timed out before it could be delivered. Do NOT retry "
+            "the same tool call with the same large content. Instead, break the "
+            "content into multiple smaller tool calls (e.g. use multiple patch "
+            "calls or write smaller files). Each tool call's arguments must be "
+            "under ~8K tokens to avoid stream timeouts.]",
+            id="length_continuation_dropped_tools",
+        ),
+        pytest.param(
+            "[System: Your previous response contained only internal reasoning and "
+            "never produced a visible answer or tool call. Do not keep thinking. "
+            "Produce your final answer as plain text now (or make the tool call "
+            "you were planning).]",
+            id="codex_incomplete_nudge",
+        ),
+        pytest.param(
+            "[System: Continue now. Execute the required tool calls and only "
+            "send your final answer after completing the task.]",
+            id="codex_ack_continuation_nudge",
+        ),
+        pytest.param(
+            "Your previous turn indicated a tool call but none was "
+            "included. Do not narrate a plan or restate intent — issue "
+            "the actual tool call now to continue the task.",
+            id="dropped_toolcall_nudge",
+        ),
+        pytest.param(
+            "You just executed tool calls but returned an "
+            "empty response. Please process the tool "
+            "results above and continue with the task.",
+            id="empty_tool_response_nudge",
+        ),
+    ],
+)
+def test_conversation_loop_retry_nudges_are_synthetic(content):
+    """These are runtime recovery nudges appended by conversation_loop's retry
+    loop (length-continuation, codex incomplete/ack-continuation,
+    dropped-tool-call) — same "ephemeral scaffolding, not a human turn" class
+    as MAX_ITERATIONS_SUMMARY_REQUEST above. A turn interrupted/crashed mid-
+    retry can persist one of these as a plain role="user" row (their
+    _length_continuation_nudge/_dropped_toolcall_nudge metadata tags do not
+    survive SessionDB projection), so recognition must be content-based."""
+    nudge = {"role": "user", "content": content}
+    assert ContextCompressor._is_synthetic_compression_user_turn(nudge) is True
+
+    human = {"role": "user", "content": "Ship the release notes for v2."}
+    assert ContextCompressor._is_synthetic_compression_user_turn(human) is False
+
+
+def test_real_task_wins_over_trailing_dropped_tools_continuation_nudge(compressor):
+    """The dropped-tools continuation nudge interpolates the tool name list,
+    so it can only be recognized by a stable prefix (unlike the other nudges,
+    which are exact-matched) — this proves that prefix path actually wires
+    into anchor selection, not just the classifier in isolation."""
+    human = {"role": "user", "content": "Refactor the auth module and add tests."}
+    messages = [
+        human,
+        {"role": "assistant", "content": "Working on it.", "tool_calls": [
+            {"id": "c1", "function": {"name": "write_file", "arguments": "{}"}}
+        ]},
+        {"role": "tool", "tool_call_id": "c1", "content": "ok"},
+        {
+            "role": "user",
+            "content": (
+                "[System: Your previous tool call (write_file, patch_file) was "
+                "too large and the stream timed out before it could be "
+                "delivered. Do NOT retry the same tool call with the same "
+                "large content. Instead, break the content into multiple "
+                "smaller tool calls (e.g. use multiple patch calls or write "
+                "smaller files). Each tool call's arguments must be under "
+                "~8K tokens to avoid stream timeouts.]"
+            ),
+        },
+    ]
+
+    idx = compressor._find_last_user_message_idx(messages, head_end=0)
+    assert idx == 0, "nudge was selected as the anchor instead of the human task"
+    assert messages[idx]["content"] == human["content"]
+
+
+def test_compress_context_todo_snapshot_stays_synthetic_across_two_boundaries(
+    tmp_path, monkeypatch
+):
+    hermes_home = tmp_path / "hermes-home"
+    monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+    db = SessionDB(db_path=tmp_path / "state.db")
+    session_id = "zero-user-todo-lifecycle"
+    db.create_session(session_id, source="cron", model="test/model")
+
+    first_agent = _lifecycle_agent(db, session_id)
+    with patch(
+        "agent.context_compressor.call_llm",
+        return_value=_response(_valid_zero_user_summary("First boundary")),
+    ):
+        first, _ = compress_context(
+            first_agent,
+            _assistant_turns(0, 24),
+            "system",
+            approx_tokens=90_000,
+            force=True,
+        )
+
+    first_handoff = next(
+        message
+        for message in first
+        if message.get(COMPRESSED_SUMMARY_METADATA_KEY)
+    )
+    assert first_handoff[COMPRESSED_SUMMARY_HAS_USER_TURN_KEY] is False
+    assert "First boundary" in first_handoff["content"]
+    assert any(
+        message.get("role") == "user"
+        and str(message.get("content") or "").startswith(TODO_INJECTION_HEADER)
+        for message in first
+    )
+    projected = db.get_messages_as_conversation(session_id)
+    assert projected
+    assert all(
+        COMPRESSED_SUMMARY_METADATA_KEY not in message
+        and COMPRESSED_SUMMARY_HAS_USER_TURN_KEY not in message
+        for message in projected
+    )
+
+    second_agent = _lifecycle_agent(db, session_id)
+    with patch(
+        "agent.context_compressor.call_llm",
+        return_value=_response(_valid_zero_user_summary("Second boundary")),
+    ):
+        second, _ = compress_context(
+            second_agent,
+            [*projected, *_assistant_turns(30, 24)],
+            "system",
+            approx_tokens=90_000,
+            force=True,
+        )
+
+    handoff = next(
+        message
+        for message in second
+        if message.get(COMPRESSED_SUMMARY_METADATA_KEY)
+    )
+    assert handoff[COMPRESSED_SUMMARY_HAS_USER_TURN_KEY] is False
+    assert "Second boundary" in handoff["content"]
+    assert "User asked:" not in handoff["content"]
+    db.close()
+
+
+
+
+
+
+
+
+
+
+
+

tests/agent/test_context_refs_concurrent.py

@@ -0,0 +1,90 @@
+"""Tests for concurrent @-reference expansion in context_references.
+
+test_refs_expand_concurrently asserts that N URL refs are fetched CONCURRENTLY.
+It proves this with an asyncio.Barrier rendezvous rather than a stopwatch: all
+N fetches must be in flight at the same instant before any is allowed to
+return. On the serial `for ref in refs: await` loop the first fetch waits for
+partners that never arrive and the test fails; with asyncio.gather it passes.
+The output-contract test guards that concurrency does NOT change ordering,
+warnings, blocks, or token accounting.
+"""
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from agent.context_references import preprocess_context_references_async
+
+
+async def _slow_fetcher(url: str) -> str:
+    # Simulate a per-URL network fetch (web_extract round trip).
+    await asyncio.sleep(0.2)
+    return f"CONTENT[{url}]"
+
+
+@pytest.mark.asyncio
+async def test_refs_expand_concurrently(tmp_path):
+    # Three independent URL refs in one message.
+    msg = "see @url:https://a.example/x @url:https://b.example/y @url:https://c.example/z please"
+
+    # Concurrency is proven by construction, not by measuring elapsed time.
+    #
+    # The old form asserted `elapsed < 0.4` ("well under 2x one 0.2s fetch").
+    # That makes the event-loop scheduler and any fixed setup part of the
+    # assertion: under a loaded CI box the inequality can flip with nothing
+    # wrong in the code under test, and the margin shrinks silently if setup
+    # cost is ever added ahead of dispatch.
+    #
+    # A barrier asserts the invariant directly: all THREE fetches must be
+    # inside the fetcher AT THE SAME TIME before any is allowed to return. If
+    # expansion ever goes serial the first fetch blocks waiting for partners
+    # that will not arrive, the barrier times out, and the test fails with an
+    # explicit message. No wall-clock constant, no load sensitivity.
+    N_REFS = 3
+    rendezvous = asyncio.Barrier(N_REFS)
+    entered: list[str] = []
+    overlapped = asyncio.Event()
+
+    async def barrier_fetcher(url: str) -> str:
+        entered.append(url)
+        # Generous relative to real scheduling latency (a rendezvous between
+        # already-dispatched coroutines needs milliseconds), but finite so a
+        # serial regression fails fast instead of hanging the suite.
+        async with asyncio.timeout(10):
+            await rendezvous.wait()
+        overlapped.set()
+        return f"CONTENT[{url}]"
+
+    try:
+        res = await preprocess_context_references_async(
+            msg, cwd=tmp_path, context_length=100_000, url_fetcher=barrier_fetcher,
+        )
+    except (asyncio.BrokenBarrierError, TimeoutError):  # pragma: no cover - serial regression
+        pytest.fail(
+            "references did not expand concurrently: a fetch reached the "
+            f"rendezvous alone, so expansion never had {N_REFS} fetches in "
+            f"flight at once (entered: {entered})"
+        )
+
+    # The barrier only clears when all three fetches are in flight together.
+    assert overlapped.is_set(), f"references never overlapped (entered: {entered})"
+    assert len(entered) == N_REFS, f"expected {N_REFS} fetches, got {entered}"
+    # All three blocks present, in order.
+    assert res.expanded
+    body = res.message
+    assert body.index("a.example") < body.index("b.example") < body.index("c.example"), \
+        "reference blocks must stay in original order"
+
+
+@pytest.mark.asyncio
+async def test_concurrent_preserves_output_contract(tmp_path):
+    """Concurrency must not change which blocks/warnings appear or their order."""
+    msg = "@url:https://one.example/p @url:https://two.example/q"
+    res = await preprocess_context_references_async(
+        msg, cwd=tmp_path, context_length=100_000, url_fetcher=_slow_fetcher,
+    )
+    assert "CONTENT[https://one.example/p]" in res.message
+    assert "CONTENT[https://two.example/q]" in res.message
+    assert res.message.index("one.example") < res.message.index("two.example")
+    assert res.injected_tokens > 0

tests/agent/test_conversation_loop_interpreter_shutdown.py

@@ -0,0 +1,68 @@
+"""Regression guard: interpreter-shutdown errors must abort the conversation
+loop immediately instead of retrying.
+
+When the Python interpreter begins its teardown sequence, every executor-backed
+operation (API calls, tool dispatch, memory sync) raises::
+
+    RuntimeError: cannot schedule new futures after interpreter shutdown
+
+Before the fix, the outer ``except Exception`` handler in
+``run_conversation`` caught this error but did not recognise it as fatal.
+Since ``api_call_count`` was nowhere near ``agent.max_iterations - 1``, the
+loop continued — each iteration hit the same dead executor and failed
+identically, producing a cascade of ``❌ Error during OpenAI-compatible API
+call #N`` messages (#93217).
+
+The fix adds an early check in the outer except handler: if
+``sys.is_finalizing()`` is True or the error message matches the
+``"cannot schedule new futures"`` pattern, the loop breaks immediately with
+a clean ``interpreter_shutdown`` exit reason.
+"""
+from __future__ import annotations
+
+from agent.conversation_loop import _is_interpreter_shutdown_error
+
+
+class TestInterpreterShutdownDetection:
+    """Verify the interpreter-shutdown error matcher used by the
+    conversation loop's outer except handler."""
+
+    def test_matches_full_interpreter_shutdown_message(self):
+        """The canonical CPython asyncio shutdown message."""
+        exc = RuntimeError(
+            "cannot schedule new futures after interpreter shutdown"
+        )
+        assert _is_interpreter_shutdown_error(exc) is True
+
+    def test_matches_short_shutdown_variant(self):
+        """Plain ThreadPoolExecutor shutdown variant (no 'interpreter')."""
+        exc = RuntimeError("cannot schedule new futures after shutdown")
+        assert _is_interpreter_shutdown_error(exc) is True
+
+    def test_case_insensitive_match(self):
+        """Error text may arrive in different case from some executor types."""
+        exc = RuntimeError("Cannot Schedule New Futures After Interpreter Shutdown")
+        assert _is_interpreter_shutdown_error(exc) is True
+
+    def test_does_not_match_unrelated_runtime_error(self):
+        """Unrelated RuntimeErrors must not trigger the shutdown path."""
+        exc = RuntimeError("connection reset by peer")
+        assert _is_interpreter_shutdown_error(exc) is False
+
+    def test_does_not_match_non_runtime_error(self):
+        """Non-RuntimeError exceptions must not match."""
+        exc = ValueError("cannot schedule new futures")
+        assert _is_interpreter_shutdown_error(exc) is False
+
+    def test_does_not_match_none(self):
+        """None must not match (defensive — caller may pass None)."""
+        try:
+            result = _is_interpreter_shutdown_error(None)  # type: ignore[arg-type]
+        except TypeError:
+            result = False
+        assert result is False
+
+    def test_does_not_match_empty_string_exception(self):
+        """Empty-message exceptions must not match."""
+        exc = RuntimeError("")
+        assert _is_interpreter_shutdown_error(exc) is False

tests/agent/test_copilot_initiator.py

@@ -0,0 +1,139 @@
+"""Tests for per-turn Copilot x-initiator header injection (issue #3040).
+
+Copilot bills "premium requests" only when a request is marked as
+user-initiated via the ``x-initiator: user`` header. Hermes previously sent
+``x-initiator: agent`` on every request (client-level default headers), so
+user prompts never consumed premium requests and were throttled as agent
+traffic. The fix marks the FIRST API call of each user turn as "user" and
+lets tool-loop follow-ups keep the "agent" default.
+
+Salvaged from PR #4097 (@tjp2021); adapted to the post-refactor layout
+(conversation_loop.py owns the injection site, the codex transport now
+accepts extra_headers).
+"""
+
+import pytest
+
+from run_agent import AIAgent
+
+
+def _tool_defs(*names):
+    return [
+        {"type": "function", "function": {"name": n, "description": n, "parameters": {}}}
+        for n in names
+    ]
+
+
+class _FakeOpenAI:
+    def __init__(self, **kw):
+        self.api_key = kw.get("api_key", "test")
+        self.base_url = kw.get("base_url", "http://test")
+
+    def close(self):
+        pass
+
+
+def _make_agent(monkeypatch, base_url, api_mode="chat_completions"):
+    """Create an AIAgent pointing at the given base_url."""
+    monkeypatch.setattr("model_tools.get_tool_definitions", lambda **kw: _tool_defs("web_search"))
+    monkeypatch.setattr("model_tools.check_toolset_requirements", lambda: {})
+    monkeypatch.setattr("agent.process_bootstrap.OpenAI", _FakeOpenAI)
+    return AIAgent(
+        api_key="test-key",
+        base_url=base_url,
+        provider="copilot" if "githubcopilot" in base_url else "openrouter",
+        api_mode=api_mode,
+        max_iterations=4,
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+
+
+def _inject(agent, api_kwargs):
+    """Mirror the injection block in agent/conversation_loop.py."""
+    if getattr(agent, "_is_user_initiated_turn", False) and agent._is_copilot_url():
+        _xh = dict(api_kwargs.get("extra_headers") or {})
+        _xh["x-initiator"] = "user"
+        api_kwargs["extra_headers"] = _xh
+        agent._is_user_initiated_turn = False
+    return api_kwargs
+
+
+class TestIsCopilotUrl:
+    """_is_copilot_url() detects GitHub Copilot endpoints."""
+
+    def test_standard_copilot_url(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://api.githubcopilot.com")
+        assert agent._is_copilot_url() is True
+
+
+    def test_github_models_url(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://models.github.ai/inference")
+        assert agent._is_copilot_url() is True
+
+    def test_openrouter_url(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://openrouter.ai/api/v1")
+        assert agent._is_copilot_url() is False
+
+    def test_case_insensitive(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://API.GITHUBCOPILOT.COM")
+        assert agent._is_copilot_url() is True
+
+
+class TestUserInitiatedTurnFlag:
+    """_is_user_initiated_turn lifecycle."""
+
+    def test_default_is_false(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://api.githubcopilot.com")
+        assert agent._is_user_initiated_turn is False
+
+    def test_reset_session_clears_flag(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://api.githubcopilot.com")
+        agent._is_user_initiated_turn = True
+        agent.reset_session_state()
+        assert agent._is_user_initiated_turn is False
+
+
+class TestFlagFlipOnInjection:
+    """Flag flips immediately on injection so tool-loop calls use 'agent'."""
+
+    def test_first_call_injects_user_initiator(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://api.githubcopilot.com")
+        agent._is_user_initiated_turn = True
+        kwargs = _inject(agent, {})
+        assert kwargs["extra_headers"] == {"x-initiator": "user"}
+        assert agent._is_user_initiated_turn is False
+
+    def test_second_call_has_no_injection(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://api.githubcopilot.com")
+        agent._is_user_initiated_turn = True
+        kwargs1 = _inject(agent, {})
+        kwargs2 = _inject(agent, {})
+        assert "extra_headers" in kwargs1
+        assert "extra_headers" not in kwargs2
+
+
+    def test_non_copilot_flag_not_flipped(self, monkeypatch):
+        agent = _make_agent(monkeypatch, "https://openrouter.ai/api/v1")
+        agent._is_user_initiated_turn = True
+        kwargs = _inject(agent, {})
+        assert "extra_headers" not in kwargs
+        # Flag unchanged — non-Copilot path doesn't touch it
+        assert agent._is_user_initiated_turn is True
+
+
+class TestHeaderValues:
+    """copilot_default_headers(is_agent_turn=...) sets x-initiator correctly."""
+
+    def test_default_is_agent(self):
+        from hermes_cli.models import copilot_default_headers
+        assert copilot_default_headers()["x-initiator"] == "agent"
+
+    def test_user_turn(self):
+        from hermes_cli.models import copilot_default_headers
+        assert copilot_default_headers(is_agent_turn=False)["x-initiator"] == "user"
+
+    def test_agent_turn_explicit(self):
+        from hermes_cli.models import copilot_default_headers
+        assert copilot_default_headers(is_agent_turn=True)["x-initiator"] == "agent"

tests/agent/test_create_openai_client_disables_sdk_retries.py

@@ -0,0 +1,78 @@
+"""Regression guard: _create_openai_client must disable SDK-level retries.
+
+#26293: the OpenAI SDK default ``max_retries=2`` uses its own 1-2s backoff that
+ignores ``Retry-After`` and double-retries *inside* hermes's outer conversation
+loop — burning request slots against a rate-limited bucket that won't refill for
+minutes. The outer loop already owns rate-limit backoff (honors Retry-After,
+adaptive + jittered), so every primary OpenAI/aggregator client must be built
+with ``max_retries=0``. This is the OpenAI-path twin of the Anthropic adapter
+fix in tests/agent/test_anthropic_adapter.py.
+"""
+from unittest.mock import MagicMock, patch
+
+from run_agent import AIAgent
+
+
+@patch("agent.process_bootstrap.OpenAI")
+def test_create_openai_client_disables_sdk_retries(mock_openai):
+    mock_openai.return_value = MagicMock()
+    agent = AIAgent(
+        api_key="test-key",
+        base_url="https://openrouter.ai/api/v1",
+        model="test/model",
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+
+    agent._create_openai_client(
+        {"api_key": "test-key", "base_url": "https://openrouter.ai/api/v1"},
+        reason="test",
+        shared=False,
+    )
+
+    # Find the construction call that carries our base_url (AIAgent() also
+    # builds a client during init; the assertion targets the explicit call).
+    matching = [
+        c for c in mock_openai.call_args_list
+        if c.kwargs.get("base_url") == "https://openrouter.ai/api/v1"
+    ]
+    assert matching, "OpenAI was never constructed with the expected base_url"
+    for call in matching:
+        assert call.kwargs.get("max_retries") == 0, (
+            "_create_openai_client must set max_retries=0 so the SDK does not "
+            "double-retry inside the outer rate-limit loop (#26293); got "
+            f"{call.kwargs.get('max_retries')!r}"
+        )
+
+
+@patch("agent.process_bootstrap.OpenAI")
+def test_create_openai_client_honors_explicit_max_retries(mock_openai):
+    """An explicit max_retries in client_kwargs is respected (setdefault, not
+    clobber) — future callers can opt back into SDK retries if needed."""
+    mock_openai.return_value = MagicMock()
+    agent = AIAgent(
+        api_key="test-key",
+        base_url="https://openrouter.ai/api/v1",
+        model="test/model",
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+
+    agent._create_openai_client(
+        {
+            "api_key": "test-key",
+            "base_url": "https://explicit.example.com/v1",
+            "max_retries": 5,
+        },
+        reason="test",
+        shared=False,
+    )
+
+    matching = [
+        c for c in mock_openai.call_args_list
+        if c.kwargs.get("base_url") == "https://explicit.example.com/v1"
+    ]
+    assert matching, "OpenAI was never constructed with the explicit base_url"
+    assert matching[-1].kwargs.get("max_retries") == 5

tests/agent/test_create_openai_client_reuse.py

@@ -0,0 +1,347 @@
+"""Regression guardrail: sequential _create_openai_client calls must not
+share a closed transport across invocations.
+
+This is the behavioral twin of test_create_openai_client_kwargs_isolation.py.
+That test pins "don't mutate input kwargs" at the syntactic level — it catches
+#10933 specifically because the bug mutated ``client_kwargs`` in place. This
+test pins the user-visible invariant at the behavioral level: no matter HOW a
+future keepalive / transport reimplementation plumbs sockets in, the Nth call
+to ``_create_openai_client`` must not hand back a client wrapping a
+now-closed httpx transport from an earlier call.
+
+AlexKucera's Discord report (2026-04-16): after ``hermes update`` pulled
+#10933, the first chat on a session worked, every subsequent chat failed
+with ``APIConnectionError('Connection error.')`` whose cause was
+``RuntimeError: Cannot send a request, as the client has been closed``.
+That is the exact scenario this test reproduces at object level without a
+network, so it runs in CI on every PR.
+"""
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from run_agent import AIAgent
+
+
+def _make_agent():
+    return AIAgent(
+        api_key="test-key",
+        base_url="https://openrouter.ai/api/v1",
+        model="test/model",
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+
+
+def _make_fake_openai_factory(constructed):
+    """Return a fake ``OpenAI`` class that records every constructed instance
+    along with whatever ``http_client`` it was handed (or ``None`` if the
+    caller did not inject one).
+
+    The fake also forwards ``.close()`` calls down to the http_client if one
+    is present, mirroring what the real OpenAI SDK does during teardown and
+    what would expose the #10933 bug.
+    """
+
+    class _FakeOpenAI:
+        def __init__(self, **kwargs):
+            self._kwargs = kwargs
+            self._http_client = kwargs.get("http_client")
+            self._closed = False
+            constructed.append(self)
+
+        def close(self):
+            self._closed = True
+            hc = self._http_client
+            if hc is not None and hasattr(hc, "close"):
+                try:
+                    hc.close()
+                except Exception:
+                    pass
+
+    return _FakeOpenAI
+
+
+def test_second_create_does_not_wrap_closed_transport_from_first():
+    """Back-to-back _create_openai_client calls on the same _client_kwargs
+    must not hand call N a closed http_client from call N-1.
+
+    The bug class: call 1 injects an httpx.Client into self._client_kwargs,
+    client 1 closes (SDK teardown), its http_client closes with it, call 2
+    reads the SAME now-closed http_client from self._client_kwargs and wraps
+    it. Every request through client 2 then fails.
+    """
+    agent = _make_agent()
+    constructed: list = []
+    fake_openai = _make_fake_openai_factory(constructed)
+
+    # Seed a baseline kwargs dict resembling real runtime state.
+    agent._client_kwargs = {
+        "api_key": "test-key-value",
+        "base_url": "https://api.example.com/v1",
+    }
+
+    with patch("agent.process_bootstrap.OpenAI", fake_openai):
+        # Call 1 — what _replace_primary_openai_client does at init/rebuild.
+        client_a = agent._create_openai_client(
+            agent._client_kwargs, reason="initial", shared=True
+        )
+        # Simulate the SDK teardown that follows a rebuild: the old client's
+        # close() is invoked, which closes its underlying http_client if one
+        # was injected. This is exactly what _replace_primary_openai_client
+        # does via _close_openai_client after a successful rebuild.
+        client_a.close()
+
+        # Call 2 — the rebuild path. This is where #10933 crashed on the
+        # next real request.
+        client_b = agent._create_openai_client(
+            agent._client_kwargs, reason="rebuild", shared=True
+        )
+
+    assert len(constructed) == 2, f"expected 2 OpenAI constructions, got {len(constructed)}"
+    assert constructed[0] is client_a
+    assert constructed[1] is client_b
+
+    hc_a = constructed[0]._http_client
+    hc_b = constructed[1]._http_client
+
+    # If the implementation does not inject http_client at all, we're safely
+    # past the bug class — nothing to share, nothing to close. That's fine.
+    if hc_a is None and hc_b is None:
+        return
+
+    # If ANY http_client is injected, the two calls MUST NOT share the same
+    # object, because call 1's object was closed between calls.
+    if hc_a is not None and hc_b is not None:
+        assert hc_a is not hc_b, (
+            "Regression of #10933: _create_openai_client handed the same "
+            "http_client to two sequential constructions. After the first "
+            "client is closed (normal SDK teardown on rebuild), the second "
+            "wraps a closed transport and every subsequent chat raises "
+            "'Cannot send a request, as the client has been closed'."
+        )
+
+    # And whatever http_client the LATEST call handed out must not be closed
+    # already. This catches implementations that cache the injected client on
+    # ``self`` (under any attribute name) and rebuild the SDK client around
+    # it even after the previous SDK close closed the cached transport.
+    if hc_b is not None:
+        is_closed_attr = getattr(hc_b, "is_closed", None)
+        if is_closed_attr is not None:
+            assert not is_closed_attr, (
+                "Regression of #10933: second _create_openai_client returned "
+                "a client whose http_client is already closed. New chats on "
+                "this session will fail with 'Cannot send a request, as the "
+                "client has been closed'."
+            )
+
+
+def test_replace_primary_openai_client_survives_repeated_rebuilds():
+    """Full rebuild path: exercise _replace_primary_openai_client three times
+    back-to-back and confirm every resulting ``self.client`` is a fresh,
+    usable construction rather than a wrapper around a previously-closed
+    transport.
+
+    _replace_primary_openai_client is the real rebuild entrypoint — it is
+    what runs on 401 credential refresh, pool rotation, and model switch.
+    If a future keepalive tweak stores state on ``self`` between calls,
+    this test is what notices.
+    """
+    agent = _make_agent()
+    constructed: list = []
+    fake_openai = _make_fake_openai_factory(constructed)
+
+    agent._client_kwargs = {
+        "api_key": "test-key-value",
+        "base_url": "https://api.example.com/v1",
+    }
+
+    with patch("agent.process_bootstrap.OpenAI", fake_openai):
+        # Seed the initial client so _replace has something to tear down.
+        agent.client = agent._create_openai_client(
+            agent._client_kwargs, reason="seed", shared=True
+        )
+        # Three rebuilds in a row. Each one must install a fresh live client.
+        for label in ("rebuild_1", "rebuild_2", "rebuild_3"):
+            ok = agent._replace_primary_openai_client(reason=label)
+            assert ok, f"rebuild {label} returned False"
+            cur = agent.client
+            assert not cur._closed, (
+                f"after rebuild {label}, self.client is already closed — "
+                "this breaks the very next chat turn"
+            )
+            hc = cur._http_client
+            if hc is not None:
+                is_closed_attr = getattr(hc, "is_closed", None)
+                if is_closed_attr is not None:
+                    assert not is_closed_attr, (
+                        f"after rebuild {label}, self.client.http_client is "
+                        "closed — reproduces #10933 (AlexKucera report, "
+                        "Discord 2026-04-16)"
+                    )
+
+    # All four constructions (seed + 3 rebuilds) should be distinct objects.
+    # If two are the same, the rebuild is cacheing the SDK client across
+    # teardown, which also reproduces the bug class.
+    assert len({id(c) for c in constructed}) == len(constructed), (
+        "Some _create_openai_client calls returned the same object across "
+        "a teardown — rebuild is not producing fresh clients"
+    )
+
+
+def test_force_close_tcp_sockets_descends_httpcore_1_connection_wrapper():
+    """httpcore 1.x stores the real stream below conn._connection.
+
+    Post-#29507: the helper must shut sockets down but must NOT release the
+    FD via ``sock.close()`` — that race recycled FDs into unrelated file
+    descriptors (kanban.db) and let TLS bytes overwrite SQLite headers. The
+    owning httpx thread is responsible for closing FDs on its own unwind.
+    """
+    from agent.agent_runtime_helpers import force_close_tcp_sockets
+
+    class FakeSocket:
+        def __init__(self):
+            self.shutdown_calls = 0
+            self.close_calls = 0
+
+        def shutdown(self, _how):
+            self.shutdown_calls += 1
+
+        def close(self):
+            self.close_calls += 1
+
+    sock = FakeSocket()
+    stream = SimpleNamespace(_sock=sock)
+    http11 = SimpleNamespace(_network_stream=stream)
+    pool_entry = SimpleNamespace(_connection=http11)
+    pool = SimpleNamespace(_connections=[pool_entry])
+    transport = SimpleNamespace(_pool=pool)
+    http_client = SimpleNamespace(_transport=transport)
+    openai_client = SimpleNamespace(_client=http_client)
+
+    assert force_close_tcp_sockets(openai_client) == 1
+    assert sock.shutdown_calls == 1
+    # #29507: close() must NOT be called from this helper — the owning
+    # httpx worker thread releases the FD, not us.
+    assert sock.close_calls == 0
+
+
+def test_force_close_tcp_sockets_finds_sockets_on_httpx_mounts():
+    """HTTP(S)_PROXY / keepalive mounts put live sockets on ``_mounts``.
+
+    #72975: walking only ``_transport`` returned tcp_force_closed=0 while the
+    stream was still mid-recv on a mounted proxy pool, so interrupt logged
+    success and the provider kept the slot for minutes.
+    """
+    from agent.agent_runtime_helpers import force_close_tcp_sockets
+
+    class FakeSocket:
+        def __init__(self):
+            self.shutdown_calls = 0
+            self.close_calls = 0
+
+        def shutdown(self, _how):
+            self.shutdown_calls += 1
+
+        def close(self):
+            self.close_calls += 1
+
+    sock = FakeSocket()
+    stream = SimpleNamespace(_sock=sock)
+    # TunnelHTTPConnection-shaped: outer proxy wrapper → HTTP11 stream.
+    http11 = SimpleNamespace(_network_stream=stream)
+    tunnel = SimpleNamespace(_connection=http11)
+    mount_pool = SimpleNamespace(_connections=[tunnel])
+    mount_transport = SimpleNamespace(_pool=mount_pool)
+    # Default transport is empty — the failing layout from #72975.
+    empty_pool = SimpleNamespace(_connections=[])
+    default_transport = SimpleNamespace(_pool=empty_pool)
+    http_client = SimpleNamespace(
+        _transport=default_transport,
+        _mounts={"https://": mount_transport},
+    )
+    openai_client = SimpleNamespace(_client=http_client)
+
+    assert force_close_tcp_sockets(openai_client) == 1
+    assert sock.shutdown_calls == 1
+    assert sock.close_calls == 0
+
+
+def test_force_close_tcp_sockets_finds_in_flight_pool_request_sockets():
+    """httpcore keeps the live connection on PoolRequest.connection.
+
+    #85252: walking only ``_connections`` (and treating an empty list as
+    falsy) returned tcp_force_closed=0 while the hung recv was still on
+    the in-flight request. Must shut that socket down without close().
+    """
+    from agent.agent_runtime_helpers import force_close_tcp_sockets
+
+    class FakeSocket:
+        def __init__(self):
+            self.shutdown_calls = 0
+            self.close_calls = 0
+            self.timeouts = []
+
+        def settimeout(self, value):
+            self.timeouts.append(value)
+
+        def shutdown(self, _how):
+            self.shutdown_calls += 1
+
+        def close(self):
+            self.close_calls += 1
+
+    sock = FakeSocket()
+    stream = SimpleNamespace(_sock=sock)
+    http11 = SimpleNamespace(_network_stream=stream)
+    in_flight = SimpleNamespace(_connection=http11)
+    pool_req = SimpleNamespace(connection=in_flight)
+    # Empty _connections is the failing layout: the live socket lives
+    # only on the in-flight PoolRequest.
+    pool = SimpleNamespace(_connections=[], _requests=[pool_req])
+    transport = SimpleNamespace(_pool=pool)
+    http_client = SimpleNamespace(_transport=transport)
+    openai_client = SimpleNamespace(_client=http_client)
+
+    assert force_close_tcp_sockets(openai_client) == 1
+    assert sock.shutdown_calls == 1
+    assert sock.close_calls == 0
+    assert sock.timeouts == [0]
+
+
+def test_force_close_tcp_sockets_clears_timeout_before_shutdown():
+    """Hung SSL recv with timeout=None can ignore SHUT_RDWR until the
+    socket timeout is cleared (#85252). Still no close() (#29507)."""
+    from agent.agent_runtime_helpers import force_close_tcp_sockets
+
+    class FakeSocket:
+        def __init__(self):
+            self.order = []
+
+        def settimeout(self, value):
+            self.order.append(("settimeout", value))
+
+        def shutdown(self, _how):
+            self.order.append(("shutdown", _how))
+
+        def close(self):
+            self.order.append(("close", None))
+
+    sock = FakeSocket()
+    stream = SimpleNamespace(_sock=sock)
+    http11 = SimpleNamespace(_network_stream=stream)
+    pool_entry = SimpleNamespace(_connection=http11)
+    pool = SimpleNamespace(_connections=[pool_entry])
+    transport = SimpleNamespace(_pool=pool)
+    http_client = SimpleNamespace(_transport=transport)
+    openai_client = SimpleNamespace(_client=http_client)
+
+    import socket as _socket
+
+    assert force_close_tcp_sockets(openai_client) == 1
+    assert sock.order == [
+        ("settimeout", 0),
+        ("shutdown", _socket.SHUT_RDWR),
+    ]
+
+