Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

29.3 KB
Raw Blame
from __future__ import annotations

import asyncio
import contextlib
import http.server
import json
import logging
import os
import shutil
import threading

import pytest

from headroom.cache import compression_store as compression_store_module
from headroom.cache.compression_store import (
    get_compression_store,
    reset_compression_store,
)
from headroom.tokenizers.estimator import EstimatingTokenCounter
from tests._mcp_stub import import_module_with_mcp_stub

mcp_server = import_module_with_mcp_stub("headroom.ccr.mcp_server")


def test_shared_stats_work_without_fcntl(monkeypatch, tmp_path) -> None:
    monkeypatch.setattr(mcp_server, "_HAS_FCNTL", False)
    monkeypatch.setattr(mcp_server, "fcntl", None)
    monkeypatch.setattr(mcp_server, "SHARED_STATS_DIR", tmp_path)
    monkeypatch.setattr(mcp_server, "SHARED_STATS_FILE", tmp_path / "session_stats.jsonl")
    monkeypatch.setattr(mcp_server.os, "getpid", lambda: 4242)
    monkeypatch.setattr(mcp_server.time, "time", lambda: 1001.0)

    event = {"type": "compress", "timestamp": 1000.0}
    mcp_server._append_shared_event(event)

    raw_lines = mcp_server.SHARED_STATS_FILE.read_text(encoding="utf-8").splitlines()
    assert len(raw_lines) == 1
    assert json.loads(raw_lines[0]) == {"type": "compress", "timestamp": 1000.0, "pid": 4242}

    events = mcp_server._read_shared_events(window_seconds=60)
    assert events == [{"type": "compress", "timestamp": 1000.0, "pid": 4242}]


# --- Shared compression store wiring ---------------------------------------
# MCP's _get_local_store() must return the get_compression_store() singleton —
# the same instance the proxy and response_handler use — so content compressed
# on either side is retrievable in-process. These pin that wiring so a private
# store can't creep back.


@pytest.fixture
def fresh_store():
    reset_compression_store()
    yield
    reset_compression_store()


def test_mcp_uses_shared_singleton_store(fresh_store) -> None:
    """MCP's store is the global singleton, not a private instance."""
    server = mcp_server.HeadroomMCPServer(check_proxy=False)
    assert server._get_local_store() is get_compression_store()


def test_mcp_retrieves_proxy_stored_content(fresh_store) -> None:
    """Content stored via the singleton (as the proxy does) is retrievable
    through MCP's local-store path. The HTTP fallback is disabled so this
    passes only via the shared store."""
    original = '{"some": "original proxy-compressed content"}'
    hash_key = get_compression_store().store(original, '{"compressed": true}')

    server = mcp_server.HeadroomMCPServer(check_proxy=False)
    result = asyncio.run(server._retrieve_content(hash_key))

    assert result.get("source") == "local"
    assert result["original_content"] == original


def test_compress_savings_percent_tracks_token_counts(fresh_store) -> None:
    """``savings_percent`` must be the *removed* percentage derived from the
    token counts — never the retained percentage. Regression for the inversion
    where ``(1 - compression_ratio)`` reported a no-op (0% saved) as 100%."""
    pytest.importorskip("mcp", reason="MCP SDK required")
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    # Repetitive JSON array — the shape the engine actually compresses.
    content = json.dumps([{"id": i, "status": "ok", "kind": "run"} for i in range(40)])
    result = server._compress_content(content)

    orig = result["original_tokens"]
    comp = result["compressed_tokens"]
    expected = round((1 - comp / orig) * 100, 1) if orig > 0 else 0

    # Reported savings agrees with the token fields (and with tokens_saved).
    assert result["savings_percent"] == expected
    assert 0.0 <= result["savings_percent"] <= 100.0
    if result["tokens_saved"] == 0:
        assert result["savings_percent"] == 0.0  # not inverted to 100
    else:
        assert result["savings_percent"] > 0.0


def _compact_json(tmp_path):
    """A single-line JSON file: one whitespace-separated word, thousands of tokens."""
    path = tmp_path / "payload.json"
    path.write_text(
        json.dumps(
            [{"id": i, "status": "ok", "kind": "run"} for i in range(60)],
            separators=(",", ":"),
        ),
        encoding="utf-8",
    )
    return path


def test_read_tool_prices_files_in_tokens_not_words(fresh_store, tmp_path, monkeypatch) -> None:
    """``headroom_read`` caches a token estimate and stores it as the entry's
    ``original_tokens``. It used to be ``len(content.split())`` — a word count
    in a token field, which is 1 for a single-line JSON document that is
    thousands of tokens long."""
    monkeypatch.chdir(tmp_path)
    path = _compact_json(tmp_path)
    content = path.read_text(encoding="utf-8")
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    asyncio.run(server._handle_read({"file_path": str(path), "fresh": True}))

    estimated = next(iter(server._file_cache.values()))[3]
    assert estimated == EstimatingTokenCounter().count_text(content)
    assert estimated > len(content.split())


def test_read_tool_cache_note_reports_tokens(fresh_store, tmp_path, monkeypatch) -> None:
    """The 'already in your context' note is read by the agent to decide whether
    to re-read the file, so its ``~N tokens`` figure has to be a token count."""
    monkeypatch.chdir(tmp_path)
    path = _compact_json(tmp_path)
    content = path.read_text(encoding="utf-8")
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    asyncio.run(server._handle_read({"file_path": str(path)}))
    response = asyncio.run(server._handle_read({"file_path": str(path)}))
    payload = json.loads(response[0].kwargs["text"])

    assert payload["status"] == "cached"
    assert f"~{EstimatingTokenCounter().count_text(content)} tokens" in payload["note"]


# --- headroom_read workspace boundary (GHSA-8g49-pg6g-xgrf) -----------------
# headroom_read is offered to the agent "INSTEAD of the built-in Read tool", so
# it must not read where the harness's own Read rules would not: it reads only
# under the server's working directory or HEADROOM_MCP_READ_ROOTS.


@pytest.fixture
def workspace_and_secret(tmp_path, monkeypatch):
    workspace = tmp_path / "workspace"
    private = tmp_path / "private"
    workspace.mkdir()
    private.mkdir()
    secret = private / "secret.txt"
    secret.write_text("TOP_SECRET\n", encoding="utf-8")
    (workspace / "notes.txt").write_text("hello\n", encoding="utf-8")
    monkeypatch.chdir(workspace)
    monkeypatch.delenv("HEADROOM_MCP_READ_ROOTS", raising=False)
    return workspace, secret


def _read_text(server, file_path: str) -> str:
    return asyncio.run(server._handle_read({"file_path": file_path, "fresh": True}))[0].kwargs[
        "text"
    ]


@pytest.mark.parametrize(
    "how", ["absolute", "dotdot", "symlink", "symlinked_dir", "sibling_prefix", "missing", "loop"]
)
def test_read_tool_refuses_files_outside_the_workspace(
    fresh_store, workspace_and_secret, how
) -> None:
    workspace, secret = workspace_and_secret
    if how == "absolute":
        file_path = str(secret)
    elif how == "dotdot":
        file_path = "../private/secret.txt"
    elif how == "symlink":
        (workspace / "link.txt").symlink_to(secret)
        file_path = str(workspace / "link.txt")
    elif how == "symlinked_dir":
        (workspace / "d").symlink_to(secret.parent)
        file_path = "d/secret.txt"
    elif how == "sibling_prefix":
        # Same leading characters as the workspace, but a different directory.
        sibling = workspace.parent / (workspace.name + "-evil")
        sibling.mkdir()
        (sibling / "secret.txt").write_text("TOP_SECRET\n", encoding="utf-8")
        file_path = str(sibling / "secret.txt")
    elif how == "missing":
        # Same answer as for a file that exists: no existence oracle.
        file_path = str(secret.parent / "does-not-exist.txt")
    else:
        loop = secret.parent / "loop"
        loop.symlink_to(loop)
        file_path = str(loop)
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    text = _read_text(server, file_path)

    assert "TOP_SECRET" not in text
    assert "outside the workspace" in json.loads(text)["error"]
    assert server._file_cache == {}


@pytest.mark.parametrize("start_in", ["filesystem_root", "home"])
def test_read_tool_reads_nothing_from_root_or_home_without_roots(
    fresh_store, workspace_and_secret, monkeypatch, start_in
) -> None:
    # GUI hosts launch MCP servers from `/`; a working-directory root there
    # (or in $HOME) would cover ~/.ssh and everything else.
    _, secret = workspace_and_secret
    # Path.home(), not $HOME: Windows reads USERPROFILE, so only the former
    # makes this directory the process home on every platform.
    monkeypatch.setattr(mcp_server.Path, "home", lambda: secret.parent)
    monkeypatch.chdir(secret.parent if start_in == "home" else secret.anchor)
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    text = _read_text(server, str(secret))

    assert "TOP_SECRET" not in text
    assert "HEADROOM_MCP_READ_ROOTS" in json.loads(text)["error"]


def _swap_before_open(monkeypatch, swap) -> None:
    """Run ``swap`` between the boundary check and the open, as a racing writer would."""
    real_open = mcp_server._open_nofollow

    def swap_then_open(path):
        swap()
        return real_open(path)

    monkeypatch.setattr(mcp_server, "_open_nofollow", swap_then_open)


def _read_text_promptly(server, file_path: str, fifo) -> str:
    # A FIFO put in the way must not block the open. If the read is stuck,
    # open the FIFO for writing to release it, then fail: the test ends in
    # bounded time either way and leaves no worker thread behind.
    result: list[str] = []
    worker = threading.Thread(target=lambda: result.append(_read_text(server, file_path)))
    worker.start()
    worker.join(timeout=5)
    if worker.is_alive():
        with contextlib.suppress(OSError):
            os.close(os.open(fifo, os.O_WRONLY | os.O_NONBLOCK))
        worker.join(timeout=5)
        pytest.fail(f"headroom_read blocked on the FIFO at {fifo}")
    return result[0]


@pytest.mark.parametrize("replaced", ["directory", "root"])
def test_read_tool_refuses_a_symlink_swapped_in_after_the_check(
    fresh_store, workspace_and_secret, monkeypatch, replaced
) -> None:
    # The boundary check and the open are separate steps. If a directory on
    # the way, or the permitted root itself, is replaced by a symlink in
    # between, the open must refuse it rather than follow it out.
    workspace, secret = workspace_and_secret
    (workspace / "data").mkdir()
    (workspace / "data" / "report.txt").write_text("PUBLIC\n", encoding="utf-8")
    (secret.parent / "report.txt").write_text("OUTSIDE_SECRET\n", encoding="utf-8")
    if replaced == "directory":
        file_path = "data/report.txt"

        def swap():
            shutil.rmtree(workspace / "data")
            (workspace / "data").symlink_to(secret.parent)
    else:
        # Configure the workspace as a root instead of working in it: Windows
        # cannot rename the process's working directory.
        monkeypatch.setenv("HEADROOM_MCP_READ_ROOTS", str(workspace))
        monkeypatch.chdir(workspace.parent)
        (workspace / "report.txt").write_text("PUBLIC\n", encoding="utf-8")
        file_path = str(workspace / "report.txt")

        def swap():
            workspace.rename(workspace.parent / "moved-away")
            workspace.symlink_to(secret.parent, target_is_directory=True)

    _swap_before_open(monkeypatch, swap)
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    text = _read_text(server, file_path)

    assert "OUTSIDE_SECRET" not in text
    assert "outside the workspace" in json.loads(text)["error"]
    assert server._file_cache == {}


@pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="named pipes are POSIX")
@pytest.mark.parametrize("where", ["target", "directory"])
def test_read_tool_does_not_block_on_a_fifo(
    fresh_store, workspace_and_secret, monkeypatch, where
) -> None:
    # Opening a FIFO for reading blocks until a writer appears; the read tool
    # runs on the MCP event loop, so it must refuse one without waiting.
    workspace, _ = workspace_and_secret
    if where == "target":
        fifo = workspace / "pipe"
        os.mkfifo(fifo)
        file_path = "pipe"
    else:
        (workspace / "data").mkdir()
        (workspace / "data" / "report.txt").write_text("PUBLIC\n", encoding="utf-8")
        file_path = "data/report.txt"
        fifo = workspace / "data"

        def swap():
            shutil.rmtree(fifo)
            os.mkfifo(fifo)

        _swap_before_open(monkeypatch, swap)
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    text = _read_text_promptly(server, file_path, fifo)

    assert "PUBLIC" not in text
    assert json.loads(text)["error"].startswith(("Not a file", "File not found"))
    assert server._file_cache == {}


def test_read_tool_reads_inside_the_workspace(fresh_store, workspace_and_secret) -> None:
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    assert "hello" in _read_text(server, "notes.txt")


def test_read_tool_reads_under_configured_roots(
    fresh_store, workspace_and_secret, monkeypatch
) -> None:
    _, secret = workspace_and_secret
    monkeypatch.setenv("HEADROOM_MCP_READ_ROOTS", str(secret.parent))
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    assert "TOP_SECRET" in _read_text(server, str(secret))
    assert "outside the workspace" in _read_text(server, "notes.txt")


def test_mcp_compress_surfaces_unreachable_proxy(fresh_store) -> None:
    server = mcp_server.HeadroomMCPServer(
        proxy_url="http://127.0.0.1:9",
        check_proxy=True,
    )

    response = asyncio.run(server._handle_compress({"content": "dead proxy check"}))
    payload = json.loads(response[0].kwargs["text"])

    assert payload["proxy"]["status"] == "unreachable"
    assert payload["proxy"]["url"] == "http://127.0.0.1:9"
    assert "unreachable" in payload["warning"].lower()


def test_mcp_stats_surfaces_unreachable_proxy() -> None:
    server = mcp_server.HeadroomMCPServer(
        proxy_url="http://127.0.0.1:9",
        check_proxy=True,
    )

    response = asyncio.run(server._handle_stats())
    payload = json.loads(response[0].kwargs["text"])

    assert payload["proxy"]["status"] == "unreachable"
    assert payload["proxy"]["url"] == "http://127.0.0.1:9"
    assert "unreachable" in payload["warning"].lower()


def test_mcp_proxy_probe_preserves_shared_proxy_client(monkeypatch: pytest.MonkeyPatch) -> None:
    class ProbeResponse:
        status_code = 200
        text = ""

        @staticmethod
        def json() -> dict[str, object]:
            return {"status": "healthy", "alive": True}

    class ProbeClient:
        def __init__(self, *, timeout: float) -> None:
            seen["timeout"] = timeout

        async def __aenter__(self) -> ProbeClient:
            return self

        async def __aexit__(self, *_args: object) -> None:
            seen["closed"] = True

        async def get(self, url: str) -> ProbeResponse:
            seen["url"] = url
            return ProbeResponse()

    seen: dict[str, object] = {}
    shared_client = object()
    monkeypatch.setattr(mcp_server.httpx, "AsyncClient", ProbeClient)

    server = mcp_server.HeadroomMCPServer(
        proxy_url="http://127.0.0.1:8765",
        check_proxy=True,
    )
    server._http_client = shared_client  # type: ignore[assignment]

    result = asyncio.run(server._probe_proxy_unreachable())

    assert result is None
    assert seen == {
        "timeout": 5.0,
        "url": "http://127.0.0.1:8765/livez",
        "closed": True,
    }
    assert server._http_client is shared_client


def test_mcp_local_mode_still_works_without_proxy_checking(fresh_store) -> None:
    server = mcp_server.HeadroomMCPServer(
        proxy_url="http://127.0.0.1:9",
        check_proxy=False,
    )

    response = asyncio.run(server._handle_compress({"content": "local mode stays available"}))
    payload = json.loads(response[0].kwargs["text"])

    assert "proxy" not in payload
    assert "warning" not in payload or "unreachable" not in payload["warning"].lower()


def test_mcp_retrieve_returns_full_content(fresh_store) -> None:
    """Retrieval is by hash: a stored, unexpired entry always returns its full
    original content (never empty, never a spurious "not found")."""
    original = "the the the the the the the the the the\n" * 5
    hash_key = get_compression_store().store(original, "<<small>>")

    server = mcp_server.HeadroomMCPServer(check_proxy=False)
    result = asyncio.run(server._retrieve_content(hash_key))

    assert "error" not in result
    assert result.get("source") == "local"
    assert result["original_content"] == original


def test_mcp_retrieve_expired_hash_returns_terminal_guidance(
    monkeypatch,
    fresh_store,
) -> None:
    """An expired local hash should say it expired and tell the agent to stop retrying."""
    current_time = [1000.0]

    def fake_time() -> float:
        return current_time[0]

    monkeypatch.setattr(mcp_server.time, "time", fake_time)
    monkeypatch.setattr(compression_store_module.time, "time", fake_time)

    store = get_compression_store()
    hash_key = store.store("expired content", "<<small>>", ttl=1)
    current_time[0] = 1002.0

    server = mcp_server.HeadroomMCPServer(check_proxy=False)
    result = asyncio.run(server._retrieve_content(hash_key))

    assert result["status"] == "expired"
    assert result["ttl_seconds"] == 1
    assert result["age_seconds"] == pytest.approx(2.0)
    assert "Entry expired" in result["error"]
    assert "do not retry the same hash" in result["error"].lower()
    assert "re-run the command" in result["hint"].lower()


def test_mcp_retrieve_hash_expiring_during_lookup_returns_terminal_guidance(
    monkeypatch,
    fresh_store,
) -> None:
    phase = "store"
    status_seen = False

    def fake_time() -> float:
        if phase == "store":
            return 1000.0
        return 1001.1 if status_seen else 1000.5

    monkeypatch.setattr(mcp_server.time, "time", fake_time)
    monkeypatch.setattr(compression_store_module.time, "time", fake_time)

    store = get_compression_store()
    hash_key = store.store("expired during retrieve", "<<small>>", ttl=1)
    phase = "retrieve"

    original_get_entry_status = store.get_entry_status
    original_retrieve = store.retrieve

    def get_entry_status_then_expire(*args, **kwargs):
        nonlocal status_seen
        result = original_get_entry_status(*args, **kwargs)
        status_seen = True
        return result

    monkeypatch.setattr(store, "get_entry_status", get_entry_status_then_expire)
    monkeypatch.setattr(store, "retrieve", original_retrieve)

    server = mcp_server.HeadroomMCPServer(check_proxy=False)
    result = asyncio.run(server._retrieve_content(hash_key))

    assert result["status"] == "expired"
    assert result["ttl_seconds"] == 1
    assert result["age_seconds"] == pytest.approx(1.1)
    assert "Entry expired" in result["error"]
    assert "do not retry the same hash" in result["error"].lower()


def test_mcp_retrieve_missing_local_hash_can_still_hit_proxy(
    monkeypatch,
    fresh_store,
) -> None:
    monkeypatch.setattr(mcp_server, "HTTPX_AVAILABLE", True)
    server = mcp_server.HeadroomMCPServer(check_proxy=True)

    async def retrieve_via_proxy(hash_key: str) -> dict[str, object]:
        return {"hash": hash_key, "original_content": "from proxy"}

    server._retrieve_via_proxy = retrieve_via_proxy

    result = asyncio.run(server._retrieve_content("proxy_hash"))

    assert result["source"] == "proxy"
    assert result["hash"] == "proxy_hash"
    assert result["original_content"] == "from proxy"


def test_mcp_retrieve_expired_local_hash_can_still_hit_proxy(
    monkeypatch,
    fresh_store,
) -> None:
    current_time = [1000.0]

    def fake_time() -> float:
        return current_time[0]

    monkeypatch.setattr(mcp_server, "HTTPX_AVAILABLE", True)
    monkeypatch.setattr(mcp_server.time, "time", fake_time)
    monkeypatch.setattr(compression_store_module.time, "time", fake_time)

    store = get_compression_store()
    hash_key = store.store("expired local content", "<<small>>", ttl=1)
    current_time[0] = 1002.0

    server = mcp_server.HeadroomMCPServer(check_proxy=True)

    async def retrieve_via_proxy(proxy_hash_key: str) -> dict[str, object]:
        return {"hash": proxy_hash_key, "original_content": "from proxy"}

    server._retrieve_via_proxy = retrieve_via_proxy

    result = asyncio.run(server._retrieve_content(hash_key))

    assert result["source"] == "proxy"
    assert result["hash"] == hash_key
    assert result["original_content"] == "from proxy"


def test_mcp_retrieve_missing_hash_still_errors(fresh_store) -> None:
    """A never-stored hash must stay on the generic missing path, not expired guidance."""
    server = mcp_server.HeadroomMCPServer(check_proxy=False)
    result = asyncio.run(server._retrieve_content("nonexistent_hash"))
    assert result.get("status") is None
    assert result["error"] == "Content not found. It may have expired or the hash may be incorrect."
    assert "do not retry the same hash" not in result.get("hint", "").lower()


def test_handle_stats_session_output_is_window_scoped() -> None:
    """window-scoped stats output should be explicitly labeled after this change."""

    async def fetch_stats() -> dict[str, object]:
        return {
            "summary": {
                "mode": "token",
                "api_requests": 3,
                "compression": {},
            }
        }

    server = mcp_server.HeadroomMCPServer(check_proxy=True)
    server._fetch_full_proxy_stats = fetch_stats
    response = asyncio.run(server._handle_stats())
    text = response[0].kwargs["text"]

    assert "Headroom Window-Scoped Session Summary" in text
    assert "Headroom Session Summary" not in text


def test_handle_stats_includes_lifetime_totals_from_persistent_savings() -> None:
    """Lifetime savings are appended from /stats persistent_savings.lifetime."""

    async def fetch_stats() -> dict[str, object]:
        return {
            "summary": {
                "mode": "token",
                "api_requests": 3,
                "compression": {},
            },
            "persistent_savings": {
                "lifetime": {"tokens_saved": 12345, "compression_savings_usd": 7.25}
            },
        }

    server = mcp_server.HeadroomMCPServer(check_proxy=True)
    server._fetch_full_proxy_stats = fetch_stats
    response = asyncio.run(server._handle_stats())
    text = response[0].kwargs["text"]

    assert "Lifetime Savings:" in text
    assert "Tokens saved: 12,345" in text
    assert "Compression savings: $7.25" in text


def test_handle_stats_falls_back_gracefully_without_persistent_lifetime() -> None:
    """Missing lifetime data should still return a valid session summary."""

    async def fetch_stats() -> dict[str, object]:
        return {
            "summary": {
                "mode": "token",
                "api_requests": 3,
                "compression": {},
            },
            "persistent_savings": {"lifetime": None},
        }

    server = mcp_server.HeadroomMCPServer(check_proxy=True)
    server._fetch_full_proxy_stats = fetch_stats
    response = asyncio.run(server._handle_stats())
    text = response[0].kwargs["text"]

    assert "Headroom Window-Scoped Session Summary" in text
    assert "Lifetime Savings:" not in text


def test_handle_stats_shows_zero_lifetime_totals_when_present() -> None:
    """A present lifetime payload should still render explicit zero totals."""

    async def fetch_stats() -> dict[str, object]:
        return {
            "summary": {
                "mode": "token",
                "api_requests": 3,
                "compression": {},
            },
            "persistent_savings": {"lifetime": {"tokens_saved": 0, "compression_savings_usd": 0.0}},
        }

    server = mcp_server.HeadroomMCPServer(check_proxy=True)
    server._fetch_full_proxy_stats = fetch_stats
    response = asyncio.run(server._handle_stats())
    text = response[0].kwargs["text"]

    assert "Lifetime Savings:" in text
    assert "Tokens saved: 0" in text
    assert "Compression savings: $0.00" in text


# --- Parent-death watchdog: reap orphaned `mcp serve` on client death --------
# When the launching MCP client is SIGKILLed, stdin EOF may never arrive and the
# SDK's blocking stdin reader wedges server.run() forever, orphaning this process
# under init/launchd. run_stdio() runs a watchdog that detects the reparent and
# forces shutdown. Refs headroomlabs-ai/headroom#2185 (secondary), #1761.


def test_parent_death_watchdog_fires_when_reparented(monkeypatch) -> None:
    """When ppid changes (client died), the watchdog resolves promptly."""
    server = mcp_server.HeadroomMCPServer(check_proxy=False)
    calls = {"n": 0}

    def fake_getppid() -> int:
        calls["n"] += 1
        return 500 if calls["n"] == 1 else 1  # captured live, then reparented

    monkeypatch.setattr(mcp_server.os, "getppid", fake_getppid)

    async def run() -> None:
        await asyncio.wait_for(server._await_parent_death(0.001), timeout=1.0)

    asyncio.run(run())  # returns => detected reparent; TimeoutError would fail


def test_parent_death_watchdog_stays_quiet_with_live_parent(monkeypatch) -> None:
    """A stable ppid must never trip the watchdog."""
    server = mcp_server.HeadroomMCPServer(check_proxy=False)
    monkeypatch.setattr(mcp_server.os, "getppid", lambda: 500)

    async def run() -> None:
        with pytest.raises(asyncio.TimeoutError):
            await asyncio.wait_for(server._await_parent_death(0.001), timeout=0.05)

    asyncio.run(run())


def test_run_stdio_reaps_process_on_parent_death(monkeypatch) -> None:
    """On reparent, run_stdio cleans up and calls os._exit(0) even though the
    (stubbed) server.run never returns — the orphan-reaper path."""
    server = mcp_server.HeadroomMCPServer(check_proxy=False)

    @contextlib.asynccontextmanager
    async def fake_stdio_server():
        yield (object(), object())

    monkeypatch.setattr(mcp_server, "stdio_server", fake_stdio_server)

    async def never_returns(*_args, **_kwargs) -> None:
        await asyncio.sleep(3600)  # emulate the wedged SDK reader

    # DummyServer (MCP SDK stub) has no `.run`; raising=False lets us add it.
    monkeypatch.setattr(server.server, "run", never_returns, raising=False)

    calls = {"n": 0}

    def fake_getppid() -> int:
        calls["n"] += 1
        return 500 if calls["n"] == 1 else 1

    monkeypatch.setattr(mcp_server.os, "getppid", fake_getppid)

    cleaned = {"done": False}

    async def fake_cleanup() -> None:
        cleaned["done"] = True

    monkeypatch.setattr(server, "cleanup", fake_cleanup)

    class _Exited(Exception):
        pass

    def fake_exit(code: int) -> None:
        raise _Exited(code)  # intercept so pytest survives

    monkeypatch.setattr(mcp_server.os, "_exit", fake_exit)

    with pytest.raises(_Exited) as excinfo:
        asyncio.run(server.run_stdio(parent_death_poll_interval=0.001))

    assert excinfo.value.args[0] == 0
    assert cleaned["done"] is True


class _RecordList(logging.Handler):
    def __init__(self) -> None:
        super().__init__(level=logging.DEBUG)
        self.records: list[logging.LogRecord] = []

    def emit(self, record: logging.LogRecord) -> None:
        self.records.append(record)


@pytest.mark.parametrize("level", [logging.DEBUG, logging.WARNING])
def test_proxy_stats_failure_keeps_url_credentials_out_of_logs(level) -> None:
    canary = "pw-canary-7c1e"
    # A path segment can carry a token too, plain or %-encoded (%50 is "P").
    path_canaries = ("PLAIN_PATH_CANARY", "%50RIVATE_PATH_CANARY", "PRIVATE_PATH_CANARY")

    class _MalformedJson(http.server.BaseHTTPRequestHandler):
        def do_GET(self) -> None:  # noqa: N802 - stdlib handler name
            body = b"{not json"
            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: object) -> None:
            pass

    httpd = http.server.ThreadingHTTPServer(("127.0.0.1", 0), _MalformedJson)
    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
    thread.start()
    # Attach directly: caplog misses `headroom.*` loggers once logging is configured.
    logger = logging.getLogger("headroom.ccr.mcp")
    handler = _RecordList()
    previous = logger.level
    logger.addHandler(handler)
    logger.setLevel(level)
    try:
        port = httpd.server_address[1]
        server = mcp_server.HeadroomMCPServer(
            proxy_url=f"http://user:{canary}@127.0.0.1:{port}/bot{path_canaries[0]}/{path_canaries[1]}",
            check_proxy=True,
        )

        async def fetch() -> object:
            try:
                return await server._fetch_full_proxy_stats()
            finally:
                if server._http_client is not None:
                    await server._http_client.aclose()

        assert asyncio.run(fetch()) is None
    finally:
        logger.removeHandler(handler)
        logger.setLevel(previous)
        httpd.shutdown()
        httpd.server_close()

    formatted = [logging.Formatter().format(record) for record in handler.records]
    for secret in (canary, *path_canaries):
        assert all(secret not in line for line in formatted)
    if level == logging.DEBUG:
        # The failure is still diagnosable: the redacted URL and the exception type.
        assert any(f"127.0.0.1:{port}" in line and "JSONDecodeError" in line for line in formatted)