Token report: say what the RTK and Headroom counters actually count (client-visible RTK view, Headroom ledger presence) - #282

Scope

• What this PR changes: the portable token report now says what the RTK and Headroom counters actually count, in the manifest's JSON and HTML. The semantics come from the independently reviewed host receipts in Lifetime token-counter receipts on the WSL authoring laptop, with what each counter actually counts #270.
  • RTK: when rtk_database is configured, the global snapshot gets a client_visible view.
    • It re-counts every retained row as a client first shows the output: whole up to 30,000 characters, otherwise a 2,000-character preview. These are Claude Code 2.1.282's bashOutputMaxChars default and saved-output preview (Rwe), overridable with client_inline_chars and client_preview_chars.
    • It reports the top-10 share and the net, and the boundary text says so.
    • It is a model: later reads of saved files are not counted, and Codex has its own limits.
  • Headroom: ledger_present comes from the path the report itself prints. An absent ledger is labelled instead of being read as a measured zero.
  • Static text: the coverage-matrix boundaries and the README say the same, including Context Mode's lifetime = retained events × 256.
• Base commit: f5812d3f (origin/main, rebased)
• Lane: lane:foundation
• Owned paths touched: tools/token-report/token_manifest.py, test_token_manifest.py, README.md and token_manifest.full.html.in. The RTK card now shows the client-visible net and the boundary; the Headroom card marks an absent ledger; the hot file manifests/evidence.json, re-registered in the last commit.

Evidence-class table

Independent review

An evidence-reviewer (Opus 5.5 at max) reviewed three rounds.

• Round 1: needs_changes. Findings:
  • the floor at zero was missing;
  • the Headroom relative path;
  • view errors failed the counter;
  • the model assumptions were missing;
  • there was no database cross-check;
  • the tests had gaps;
  • the template showed none of it.
• Round 2: needs_changes. The component-table wording, and "by default" appearing with overridden limits.
• Round 3: agree.

Its two non-blocking notes are also applied: a precise code comment, and a test that pins the 1% threshold. Seven targeted mutations are killed by the tests.

A real-host refresh with the revised code, against a copy of this host's report config with outputs redirected, exited 0 with no issues:

• rtk-global: 742,550,141, with client_visible net 8,985,531 (1.21%), 80,978 rows and top-10 74.3%;
• Headroom: ledger_present: false, with the absent note;
• the HTML rendered with no placeholder left.

Local commands run

$ python3 -m unittest discover -s tools/token-report -p test_token_manifest.py
Ran 55 tests ... OK
$ python3 -m unittest tests.test_native_token_ci tests.test_ecosystem_manifest
OK
$ python3 scripts/validate.py
{"components": 69, "hashed_files": 5612, "profiles": 4, "receipts": 147, "status": "passed"}
$ python3 scripts/component_matrix.py --check; python3 scripts/new_host_grand_list.py --check
checked; passed
$ gitleaks git --log-opts="origin/main..HEAD" --redact .   (guarded ecosystem wrapper)
no leaks found

Checklist

• No workflows changed, no secrets, and no billing surface.
• The reporter still installs nothing and runs no new upstream command. It reads the already-configured RTK database read-only.

🤖 Generated with Claude Code