v0.4.0 — TokenJam Lens + Reuse

First minor bump since v0.3.0. Significant new product surface — substantially more than the 0.3.x patch cadence — so we bumped the minor.

🔭 TokenJam Lens — the local UI is a product

The local dashboard you get from tj serve has been rebranded and rebuilt as TokenJam Lens. It's the same offline-first single-file SPA, but with a real triage front door instead of a list of tables.

• Overview screen — the new default landing route. Three bands: spend hero (with a real chart and a "to end of month" run-rate projection that's explicitly not a forecast), recoverable-waste tiles (one per analyzer, registry-driven so future analyzers auto-appear), and health-at-a-glance (alerts, drift, budgets, recent activity).
• Optimize detail tab — every analyzer's findings rendered in one place, with ?finding=<name> deep-links from the Overview tiles.
• Real charts — uPlot, vendored offline (zero CDN loads, the dashboard works air-gapped). Hover tooltips, theme-aware (light/dark/system), tick granularity scales with the window (hours/days/weeks).
• URL state as the source of truth — every filter (window, group-by, agent, finding) lives in the hash, so back/forward/reload work cleanly and cross-screen drill-through carries context.
• Cost transparency — the tj cost table and the Cost screen now show CACHE R and CACHE W columns alongside input/output tokens, so a cache-heavy $1.44 span no longer looks like it came out of nowhere. (The hidden ~91% cost driver on Claude Code-style workloads finally has a name.)

🔁 Reuse — the 5th analyzer

Agents re-plan the same work constantly. Reuse detects clusters of sessions that share a planning skeleton (the first LLM call before any tool call) and surfaces what that repeated planning costs.

• tj optimize reuse — clusters sessions by structural similarity (tool-sequence signature, plus prompt-prefix hashing when [capture] prompts = true); produces two honest numbers per cluster: cache-reuse savings (what you'd recover by reusing the skeleton) and script-replacement savings (the upper bound if you converted the planning to a deterministic template).
• tj report --reuse — renders the clusters as an HTML report plus per-cluster Markdown sidecars with variable slots highlighted ({{slot_N}}), idempotent on cluster_id so re-runs overwrite cleanly. The Markdown is copy-paste-usable as a Claude Code slash command or saved prompt.
• Honesty by construction: "skeleton match," "recoverable," "review before reusing" — never "saves you."

Known limitation: tj report --reuse needs direct DB access today, so tj stop first if the daemon is running. HTTP fallback is tracked for v0.4.1 (#154).

💰 Cost transparency

• cache_write_tokens is now surfaced everywhere — in tj cost, on the web Cost screen, in the trace-detail view, and via /api/v1/cost. Previously it was billed but invisible above the DB layer.
• Plan-tier-aware rendering — core/framing.py is the single source of truth for whether to show dollars (api), token-share (subscription), tokens only (local), or a "may overstate" qualifier (unknown). The CLI and the REST API consume it identically.
• Analyzer recoverable contract — every savings analyzer now emits estimated_recoverable_usd + estimated_recoverable_tokens + estimate_basis + estimate_confidence on a single time basis (window), so Overview tiles are directly comparable.
• Honest run-rate — the Lens chart and tj cost projection use a window-average run-rate × days remaining in cycle, captioned "linear run-rate, not a forecast." No EWMA, no seasonality, no anomaly bands.

🔒 Security

• A committed .tj/config.toml with a live ingest_secret (in repo since v0.2.0) is now untracked. Limited blast radius — local network ingest token only — but a CI test now guards against re-staging it. See PR #145 for the full advisory.

🧹 Quality

• 17 v0.3.5 post-release findings closed (#141) from an external contributor; 5 rounds of Lens UI bug fixes; 9 individual fix PRs across the release. The full pre-release smoke pass ran twice and is committed under tests/results/ as a record.

Honesty discipline

This release is the most public-facing one yet. The framing language is deliberate everywhere:

• Recoverable amounts are estimated, never saved.
• Cache hits at 100% efficacy show "✓ Already optimized," not "no findings."
• Subscription users see token-share framing, not dollar figures.
• Forecasting is bounded to a single linear projection captioned "not a forecast."

Upgrade

pipx upgrade tokenjam
tj stop && tj serve &
tj --version   # expect 0.4.0

Existing installs keep their config, data, and daemon setup. Open the dashboard:

open http://127.0.0.1:7391/

…and you'll land on the new Overview.

Full changelog

v0.3.5...v0.4.0