fix(ccr): make expired retrieve misses terminal

[rodboev]

Description

Expired CCR hashes currently come back through headroom_retrieve as the same generic missing-content error used for typos and never-stored hashes. That leaves agents with no terminal signal, so they can retry a dead hash instead of rerunning the source command or rereading the source file. This change uses the cache store's existing TTL status metadata before the MCP retrieval path loses that distinction, then returns expired-hash guidance only when the local store proves the entry existed and expired.

Closes #1776

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• Uses CCR store status metadata to distinguish expired local hashes from never-stored hashes in the MCP retrieval path.
• Keeps proxy fallback and successful local retrieval behavior unchanged.
• Adds focused regression coverage for expired stored hashes, the status-to-retrieve TTL boundary, proxy fallback preservation, and missing-hash negative space.

Testing

• Unit tests pass (uv run pytest tests/test_ccr_mcp_server.py -q)
• Linting passes (uv run ruff check headroom/ccr/mcp_server.py tests/test_ccr_mcp_server.py)
• Type checking passes (uv run mypy headroom)
• New tests added for new functionality
• Manual testing performed

Test Output

Base pytest:
FAILED tests\test_ccr_mcp_server.py::test_mcp_retrieve_expired_hash_returns_terminal_guidance
E   KeyError: 'status'

Head pytest:
tests\test_ccr_mcp_server.py ...s..........                              [100%]
13 passed, 1 skipped in 0.35s

Ruff:
All checks passed!

Real Behavior Proof

• Environment: Windows, focused local pytest through the headless runner.
• Exact command / steps: Store a CCR entry with a short TTL, advance beyond expiry, call HeadroomMCPServer._retrieve_content(hash), force a second entry to cross TTL between status inspection and retrieve(), stub a proxy-backed retrieval for local misses, then call the same method with a never-stored hash and no proxy hit.
• Observed result: The already-expired hash and the hash that expires during retrieval both return terminal expired guidance with status: expired; missing and expired local hashes still return proxy data when the proxy fallback succeeds; a never-stored hash with no proxy hit still returns the generic missing-hash error and no expired status.
• Not tested: Full suite, live agent retry behavior, and live external proxy-backed retrieval.

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have updated the CHANGELOG.md if applicable

Additional Notes

Documentation and changelog are left unchecked because this is a narrow MCP error-shape fix and Headroom's changelog is generated from conventional commits.

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.

[JerrettDavis]

The expired-hash path now distinguishes expired local entries from never-stored misses and gives terminal guidance while still allowing a configured proxy to satisfy the hash. The race where an entry expires between status and retrieve is covered. No blocking issues from me.