How to verify a Headroom MCP recovery path before using compressed diagnostics

A shorter MCP response is not enough reason to let a diagnostic record disappear. The useful question is whether the line that changes the next action remains visible, and whether the original can be recovered before the compact result is allowed to stand in for it.

Headroom exposes that sequence through headroom_compress and headroom_retrieve. The checkpoint below follows one recorded Headroom 0.34.0 run through headroom mcp serve over stdio: create a disposable artifact, capture the returned recovery fields, retrieve the original, then compare both SHA-256 values. It also includes one executed invalid-hash case. No coding-agent profile, running HTTP proxy service, provider call, real repository, customer log, or paid plan is part of the recorded boundary. The server command deliberately configures http://127.0.0.1:9 as an unreachable proxy fallback; its recorded proxy.status=unreachable warning is expected in this isolated run, while the successful retrieval remains local.

Create an isolated disposable artifact

Use a temporary root so the MCP server does not share a workspace, configuration directory, or cache with a normal Headroom setup. The recorded run used Python 3.13.13, Headroom 0.34.0, the mcp extra, and separate workspace, configuration, and cache roots.

ROOT="$(mktemp -d)"
uv venv --python 3.13 "$ROOT/mcp-runtime"
uv pip install --python "$ROOT/mcp-runtime/bin/python" "headroom-ai[mcp]==0.34.0"

export PYTHON_BIN="$ROOT/mcp-runtime/bin/python"
export HEADROOM_BIN="$ROOT/mcp-runtime/bin/headroom"
export HEADROOM_WORKSPACE_DIR="$ROOT/workspace"
export HEADROOM_CONFIG_DIR="$ROOT/config"
export XDG_CACHE_HOME="$ROOT/cache"
export RAW_ARTIFACT="$ROOT/diagnostic.txt"
export RECOVERED_ARTIFACT="$ROOT/recovered.txt"
export CAPTURE_DIR="$ROOT/capture"
mkdir -p "$HEADROOM_WORKSPACE_DIR" "$HEADROOM_CONFIG_DIR" "$XDG_CACHE_HOME" "$CAPTURE_DIR"

"$PYTHON_BIN" - <<'PY' > "$RAW_ARTIFACT"
print("build stage: compiling 184 modules")
for index in range(260):
    print(f"warning: generated source map fragment {index:03d} omitted from compact artifact")
print("error: migration verify failed at ledger/reconcile.ts:214")
print("recovery command: npm run verify:migrations -- --case reconciliation-idempotency")
print("request id: synthetic-7f12")
print("next action: restore the pre-migration snapshot before retrying")
PY

The exact recovery command is the decision-changing line in this artifact. The repeated warnings create a realistic reason to compress without introducing private or production material. A different diagnostic grammar needs its own decisive line and its own check.

Start the public MCP server and capture the compression response

The public server command is headroom mcp serve. The following MCP SDK client starts that stdio server, lists its tools, and calls the exposed names rather than an implementation method. Save it as $ROOT/mcp-check.py beside the temporary artifact, then run it with "$PYTHON_BIN" "$ROOT/mcp-check.py".

import asyncio, json, os
from pathlib import Path

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

def payload(result):
    return json.loads(result.content[0].text)

async def main():
    raw = Path(os.environ["RAW_ARTIFACT"]).read_text(encoding="utf-8")
    params = StdioServerParameters(
        command=os.environ["HEADROOM_BIN"],
        args=["mcp", "serve", "--proxy-url", "http://127.0.0.1:9"],
        env={**os.environ, "HEADROOM_TELEMETRY": "off"},
    )
    async with stdio_client(params) as (read_stream, write_stream):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            names = {tool.name for tool in (await session.list_tools()).tools}
            if not {"headroom_compress", "headroom_retrieve"} <= names:
                raise RuntimeError("required Headroom MCP tools are not exposed")

            compressed = payload(await session.call_tool(
                "headroom_compress", {"content": raw}
            ))
            for field in ("hash", "original_tokens", "compressed_tokens", "transforms"):
                if field not in compressed:
                    raise RuntimeError(f"missing compression field: {field}")
            Path(os.environ["CAPTURE_DIR"], "compress.json").write_text(
                json.dumps(compressed, indent=2), encoding="utf-8"
            )

            recovered = payload(await session.call_tool(
                "headroom_retrieve", {"hash": compressed["hash"]}
            ))
            Path(os.environ["RECOVERED_ARTIFACT"]).write_text(
                recovered["original_content"], encoding="utf-8"
            )
            Path(os.environ["CAPTURE_DIR"], "retrieve.json").write_text(
                json.dumps(recovered, indent=2), encoding="utf-8"
            )

            failed = payload(await session.call_tool(
                "headroom_retrieve", {"hash": "toolflock-owned-invalid-hash-20260805"}
            ))
            if not failed.get("error"):
                raise RuntimeError("invalid hash did not return a visible error")
            Path(os.environ["CAPTURE_DIR"], "invalid-hash.json").write_text(
                json.dumps(failed, indent=2), encoding="utf-8"
            )

asyncio.run(main())

The --proxy-url http://127.0.0.1:9 argument is deliberate. No proxy service runs at that address in the recorded environment, so the compression response records proxy.status=unreachable with a warning that the configured proxy is unreachable. Treat that warning as an expected boundary condition for this isolated path, not as a successful proxy call or a failed local recovery. The recorded headroom_retrieve response still reports source: local.

Keep the returned hash, transforms, original_tokens, and compressed_tokens with the compact response. The hash is the handoff to retrieval; a smaller response without one cannot prove that the raw artifact is still available.

Under the recorded conditions, headroom_compress accepted the 260-warning artifact, returned a non-empty hash, used router:log:0.05, and reported 3,447 input tokens and 199 compressed tokens. Those values describe one synthetic artifact and one route. They are not a cost estimate or a general compression result.

Inspect the compact response before trusting it

Read the compact response against the line chosen before compression. In the recorded artifact, the recovery command remained in the first headroom_compress response. That makes the compact result actionable for this case, but it does not make the result self-sufficient.

When the chosen line is absent, keep the compact response as orientation only. Do not select a next action from it until retrieval restores the raw artifact. A different input shape can hide a decisive line even when it returns a valid hash and a lower token count.

Retrieve the original and compare the SHA-256 values

Run the MCP client, then compare the raw and recovered files directly:

"$PYTHON_BIN" "$ROOT/mcp-check.py"
shasum -a 256 "$RAW_ARTIFACT" "$RECOVERED_ARTIFACT"

The two digest lines must contain the same SHA-256 value. That verifies the complete artifact rather than only the recovery command that was easy to spot in the compact response.

The recorded result contained one headroom_retrieve call against the returned hash. It reported source: local, retrieval_count: 1, equal pre- and post-retrieval SHA-256 values, and byte_exact_recovery: true. The recovery command also appeared in the restored artifact. This supports a narrow operating rule: use the compact response only after the recorded hash still resolves to the original bytes.

Exercise an invalid-hash fallback

The same MCP session also called headroom_retrieve with one owned invalid hash after the successful recovery. The recorded call returned a visible not-found response while the raw synthetic artifact remained on disk. The fallback was therefore to retain that raw artifact rather than replace it with a failed lookup.

Treat that as one executed failure/recovery case, not as a guarantee about every missing or expired hash. The recorded result does not establish identical error text, retry behavior, expiry handling, proxy retrieval, or cross-process recovery. When a retrieval fails in another environment, preserve the raw source, record the visible result, and investigate the relevant storage or host condition before compression becomes a replacement step.

Keep the checkpoint inside its tested boundary

This procedure proves a controlled stdio MCP sequence for one synthetic diagnostic grammar: the exposed tools were available, the first response retained the chosen recovery command, one local retrieval restored matching bytes, and one invalid-hash call retained the raw-artifact fallback. It does not prove automatic agent retrieval, retention after expiry, proxy behavior, provider savings, or reliability for another artifact type.

Use the checkpoint when a compressed diagnostic might replace a raw record: isolate the input, capture the returned hash and transform, inspect the decisive line, retrieve the original, compare SHA-256 values, and stop on a failed recovery. Broaden the workflow only after the same sequence has been exercised against the actual host and data boundary that will carry it.