Statusline — Phase 3 Design

• Phase: Phase 3 — Design
• Status: Approved (2026-08-02, ADR-0009) — accepted with one change request: the transcript tail window is an implementation constant, not an architectural invariant (the architecture requires only a bounded tail read)
• Date: 2026-08-02
• Based on: the approved Phase 2 architecture (Architecture.md, ADR-0004–0008) and the Phase 2 read-only verification (Findings/2026-08-02 - Phase 2 - Read-only Verification.md)

How the deliverables map to the Roadmap

Each Roadmap Phase 3 deliverable is one design document in this directory:

Roadmap deliverable	Design document
Display requirements	01-display-requirements.md
Input/output contract	02-input-output-contract.md
Provider/model naming rules	03-provider-model-naming.md
Caching and timeout policy	04-caching-timeout-policy.md
Security and privacy considerations	05-security-privacy.md
Test cases and acceptance criteria	06-test-cases-acceptance.md

Open design decisions resolved here

Architecture.md deferred four decisions to Phase 3. This design resolves them as follows:

1. Provider display source → the empirical model→provider mapping is the default provider source (fast, local, no Docker, no classifier dependency). SQLite enrichment is a documented optional enhancement for a later phase, gated on a pre-baked sqlite3 reader image existing. Rationale: the verified latency data (docker run startup 0.21–1.13 s vs the 300 ms statusline debounce) and the classifier-gating risk make SQLite non-default. See 04-caching-timeout-policy.md.
2. Empirical mapping: format and refresh → a versioned JSON file at ~/.claude/statusline-model-provider.json, maintained out-of-band by a Scripts/ maintenance script (never at statusline read time), treated strictly as a heuristic per ADR-0006. See 03-provider-model-naming.md.
3. Staleness threshold → 5 minutes by default (configurable constant). See 01-display-requirements.md.
4. Output format → a single bounded line of the form provider/model (model-only when the provider is unknown), with a [stale] marker past the threshold. See 01-display-requirements.md.

Design decisions and their evidence

Decision	Evidence	ADR
Resolved model comes from the transcript tail (message.model), not the payload	78/78 assistant messages carry message.model; values match call_logs.model; sub-ms read; session-local	ADR-0005
Provider display is best-effort, never a dependency	Transcript has no provider field; SQLite enrichment is slow and shared-gateway ambiguous	ADR-0006
Display shows the most recent route, re-read on each event	auto/cheap resolves to 20+ (provider, model) pairs; not a stable value	ADR-0007
All upstream reads are defensive against schema drift	model relocated from top level to message.model between versions; image tag unpinned	ADR-0008
Default provider source is the empirical mapping, not SQLite	docker run + apk add sqlite 0.73–1.13 s (over 300 ms budget); pre-baked image ~0.25 s (borderline); classifier gating non-deterministic	ADR-0006

How to review

The Phase 3 completion review should confirm:

1. Every displayed value has a documented source and fallback (01-display-requirements.md).
2. The behavior contract is unambiguous and testable (06-test-cases-acceptance.md).
3. No decision depends on unverified behavior.
4. Secrets, privacy, and read-only constraints are honored (05-security-privacy.md).
5. Approval is recorded in Decisions.md (a Phase 3 ADR), which closes the Phase 3 gate.