release: v5.9.0 — "Machine-wide token lens" (B1+B2+B3)

Cuts the v5.9.0 release bundling the three hardening gaps shipped since v5.8.0:
B1 (agent-listing budget — new orchestrated scanner AGT, count 15→16),
B2 (machine-wide always-loaded token roll-up in the campaign ledger), and
B3 (cache-aware filtering + stale plugin-cache disk-cleanup finding).

Version sync: plugin.json 5.8.0→5.9.0; README badges version 5.9.0 /
scanners 15→16 / tests 1168→1215; README intro + Health prose + scanner
table (new AGT row, TOK 7th pattern) + self-audit prose 15→16; new
version-history row; CHANGELOG [5.9.0]; CLAUDE.md finding-ID example (+CA-AGT)
and test count 1168→1215 / 67→68 files (scanner dir 35→36).

Gate: `self-audit --json --check-readme` -> readmeCheck.passed:true,
mismatches:[]. Full suite green (1215, 0 fail). Tag + catalog ref-bump follow.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -5,6 +5,62 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.9.0] - 2026-06-23
+
+### Summary
+"Machine-wide token lens" — the three highest-impact hardening gaps toward whole-machine token
+tuning (the shift from *correct?* to *best-practice-tuned?*). **B1** measures the always-loaded
+agent listing (a new orchestrated scanner), **B2** gives the campaign ledger a machine-wide
+always-loaded token bill that counts the shared global layer once, and **B3** makes the token and
+conflict scans cache-aware so stale plugin-cache versions stop polluting them. Every new token
+figure carries an honesty caveat where the load mechanism is inferred or the number is an
+upper-bound estimate. `--json`/`--raw` stay byte-stable; frozen v5.0.0 + SC-5 snapshots untouched.
+Scanner count 15 → **16**, agents **7**, commands **21**; **1215** tests.
+
+### Added
+- **B1 — Agent-listing budget (new orchestrated scanner `AGT`, count 15 → 16).** Claude Code injects
+  every active agent's name+description into the system prompt on every turn; on a heavily-plugged
+  machine this is often the dominant single always-loaded source, yet nothing measured it. New
+  `scanners/agent-listing-scanner.mjs` + `scanners/lib/agent-listing-budget.mjs`:
+  - `CA-AGT-001` — per-agent description over the soft bloat cap (advisory; mirrors the TOK 500-char
+    SKILL.md heuristic — agents have no verified per-description cap, so nothing is truncated, the
+    description is simply re-sent in full every turn).
+  - `CA-AGT-002` — the summed agent-listing estimate exceeding the listing budget.
+  - **Intellectual-honesty contract:** both findings are LOW and explicitly **inferred /
+    upper-bound** — the agent-listing mechanism is undocumented (agents are absent from Claude Code's
+    published context breakdown), the per-agent estimate is the frontmatter cap not a measurement,
+    and the budget is a config-audit heuristic anchored on a conservative 200k window. The evidence
+    discloses all three caveats rather than overstating certainty.
+- **B2 — Machine-wide always-loaded token roll-up (campaign).** The campaign ledger now carries a
+  token bill alongside the severity roll-up. `campaign refresh-tokens` runs a live cross-repo sweep
+  (`readActiveConfig` → `buildManifest` → ownership split) that factors out the **shared global
+  always-loaded layer** (global CLAUDE.md + agent listing + global MCP + unscoped global rules) and
+  counts it **once**, then adds each repo's delta — surfacing one machine-wide always-loaded total
+  plus a ranked "most expensive repos" table. The shared layer is written once from the first
+  readable repo (counted-once guard against the `whats-active` double-count).
+- **B3 — Stale plugin-cache disk-cleanup finding (`TOK`).** Stale `~/.claude/plugins/cache` versions
+  surface as a finding (`--global`) categorized **Dead config** (not "Wasted tokens"): they occupy
+  disk but load on zero turns. A per-finding category override (`plugin-cache-hygiene`) plus a
+  dedicated humanizer translation keep the prose honest ("safe to delete … zero tokens per turn …
+  housekeeping, not a performance problem").
+
+### Changed
+- **B3 — Cache-aware filtering (folds in B0): `--exclude-cache` (default ON) for token-hotspots and
+  the orchestrator.** `~/.claude/plugins/cache` holds *both* active and stale plugin versions —
+  `installed_plugins.json`'s `installPath` points INTO the cache — so a blunt "skip all of
+  plugins/cache" would drop *active* config. Discovery is now **version-aware**: it reads the
+  adjacent `installed_plugins.json`, keeps each plugin's active version dir, and drops only stale
+  ones. Result: stale versions no longer pollute the token-hotspot ranking, and stale cached
+  `hooks.json` no longer inflate CNF "duplicate hook" findings (verified: cache exclusion measurably
+  drops the count). `--no-exclude-cache` restores the full walk. When `installed_plugins.json` is
+  absent or unparseable, nothing is filtered (never silently drop live config).
+- **B2 — `manifest` ownership split.** `splitManifestByOwnership` separates the shared-global layer
+  from per-repo deltas; `~/.claude.json:projects` MCP is correctly classified as a per-repo delta
+  (its slice is keyed on the repo path), not a shared-global source.
+- Humanizer: a finding's `category` can now override the scanner-default impact label
+  (`CATEGORY_TO_IMPACT`), used so a TOK finding can read as **Dead config** when that is the honest
+  bucket. The raw `category` field is unchanged, so `--json`/`--raw` stay byte-stable.
+
 ## [5.8.0] - 2026-06-23
 
 ### Summary