chore(pi): add session affinity and cache diagnostics

[dgokeeffe]

Issue and stack

Closes #331.

Depends on #217, #333, #223, #239, and #243, but is independent of #334/#335. Review only the session-affinity/diagnostic range relative to the pushed integrated base:

dgokeeffe/ucode@review/integrated-consolidation-base...review/pi-cache-affinity-independent

Equivalent immutable range: 168038b...e672d4e. Do not merge before the prerequisite stack. The only production behavior in this unit is Pi session affinity; it does not force or claim short GPT-subagent retention.

---

Unit 07 — Pi cache/session-affinity diagnostics

Objective and user-visible behavior

Enable Pi's production-safe session-affinity headers so a conversation remains on one UAG destination when traffic splitting is configured. Add sanitized, explicit diagnostic tools/tests for prompt-cache investigations without asserting a backend retention guarantee.

Candidate: review/pi-cache-affinity-independent (e672d4e), independent incremental base dev (168038b).

Exact scope

Production: one Pi Claude-provider compat flag in src/ucode/agents/pi.py.
Diagnostics: scripts/prompt_cache_repro.py, scripts/prompt_cache_http_trace.py.
Tests: one Pi compat assertion plus tests/test_prompt_cache_repro.py, tests/test_prompt_cache_http_trace.py.
Non-goals: forcing PI_CACHE_RETENTION, installing a child/subagent cache extension, claiming short GPT-subagent retention, MLflow discovery/proxying.

Before / after reproduction

git show dev:src/ucode/agents/pi.py | rg 'sendSessionAffinityHeaders' || echo '<absent>'
# <absent>

git show review/pi-cache-affinity-independent:src/ucode/agents/pi.py \
  | rg 'sendSessionAffinityHeaders'
# "sendSessionAffinityHeaders": True

git grep -nE 'short retention|PI_CACHE_RETENTION|in_memory.*supported' \
  review/pi-cache-affinity-independent -- src/ucode scripts tests \
  || echo '<no production short-retention claim>'

Focused validation:

uv run --frozen pytest tests/test_agent_pi.py \
  tests/test_prompt_cache_repro.py tests/test_prompt_cache_http_trace.py -q
# 74 passed
uv run --frozen ruff check .
# All checks passed
uv run --frozen ruff format --check src tests scripts
# candidate files formatted (focused check: 6 files already formatted)

Full suite:

uv run --frozen pytest -q
# 2 failed, 1751 passed, 36 skipped

The installed Claude capture and preferred-Pi-model state assertion reproduce on integrated dev; neither is touched by this six-file range.

Retained cache investigation evidence

• Pi long mode constructs requests with prompt_cache_key and prompt_cache_retention: "24h".
• UAG accepts/validates 24h; invalid values report in_memory and 24h as supported values.
• Direct UAG: GPT-5.6 Sol missed after 45 minutes despite requested 24h.
• Direct UAG: GPT-5.5 hit at 45 and 50 minutes, then missed at 60 minutes.
• These facts rule out a Pi request-construction failure but do not distinguish UAG forwarding, backend eviction, or prefix matching.
• GPT-5.6 Sol rejects explicit in_memory; therefore this unit makes no short-retention claim for GPT subagents.

The trace script prints sanitized request/response JSON, never prints authorization headers, redacts an echoed exact token, and persists only a cache key, assistant text, and usage metadata. Tests verify omission vs 24h vs in_memory, stable prefixes, cache usage extraction, phase/state behavior, malformed saved-state rejection without traceback, and redaction.

Impact map

• Agent/provider: Pi's Databricks Claude provider gains session-affinity headers; diagnostics call the Codex Responses endpoint only when explicitly run.
• Config: one compat flag in generated Pi models config; no environment/cache policy override.
• Compatibility: if a Pi release ignores the flag, behavior falls back to current routing; tests lock generated config shape.
• Managed config/MCP/skills/MLflow: unchanged.

Rollback and residual risk

Revert the two unit-07 commits (945b0c2, e672d4e); session affinity and diagnostic scripts disappear with no state migration. Residual risk remains backend cache eviction/forwarding/prefix behavior; the scripts diagnose but do not promise retention.

Hygiene

git diff --check dev..review/pi-cache-affinity-independent passes. Six-file range; no MLflow production files, generated outputs/state files, credentials, uv.lock, .pi-subagents/, or goal.md; no merge markers or unresolved index entries.