test(cache): cover the public lifecycle and installed-root matrix

[Jamie-BitFlight]

Current-main reconciliation — 2026-09-29

Partially overtaken by current coverage. The focused force/empty/timestamp/root fixes (#234-#236, #238) are now implemented and have retained tests. #237 remains open, so this lifecycle matrix must stay open until same-minute history allocation is fixed and the final public matrix can assert the completed lifecycle without preserving the known collision defect.

Problem

Cache behavior is tested in fragments but lacks one public contract matrix
across lifecycle states, content integrity, CLI outcomes, and source versus
installed root ownership.

Required outcome

After the focused cache fixes land, add a public matrix without duplicating
every library state through CLI mocks. Preserve the current broad cached HTTP
fallback behavior in this sweep; test cached 401, 403, 404, and 5xx outcomes
without broadening or narrowing the error taxonomy.

Acceptance

• Exact coverage for NEW, FRESH, UNCHANGED, REFRESHED, STALE, and uncached typed
  failure.
• Content/sidecar integrity, headings/fenced headings, stdout/stderr, and exit
  behavior are asserted.
• Source, linked-worktree, wheel, and uvx roots are covered.
• Cached 401, 403, 404, 5xx, and transport failures retain current fallback
  semantics.
• One real CLI flow supplements focused library tests.

Dependencies and non-goals

Depends on NEW-CACHE-FORCE, NEW-CACHE-EMPTY, NEW-CACHE-TIME,
NEW-CACHE-HISTORY, and NEW-CACHE-ROOT. Do not redesign HTTP error taxonomy in
this issue.