# Upgrade Guide — vNEXT

<!-- bump: minor -->

## What Changed

Phase three of the token-burn-detection-and-self-heal system. This is the first phase where the system actually starts watching.

What lands today:

- A small background process that wakes every sixty seconds, looks at the token ledger, and notices when one component is using more than its fair share of the budget.
- A new query on the token ledger that returns per-component totals, used by the background process above.
- A new degradation-log entry shape, used when a threshold is crossed.

There are still no Telegram alerts (phase five) and no automatic slowdown (phase four). When the new watcher catches something, it lands as an entry in the existing degradation log — the same place every other agent self-observation already shows up. Dashboard-visible.

## What to Tell Your User

The third of six pieces of the new self-watch system. This is the first piece you can see working. From this release on, your agent will notice when one of its own components is using an outsized share of its token budget, and it will write that finding into the degradation log. You can see those findings on the dashboard.

Nothing slows down automatically yet — that comes in the next release. For now, the agent's eyes are open; the hands come next.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Background burn detector | Automatic. Configurable via the agent config file. |
| Per-component spend query on the token ledger | Internal — used by the burn detector. |
| Degradation-log entries when thresholds cross | Visible on the dashboard's degradation tab. |

## Evidence

Sixteen new tests in `tests/unit/burn-detection-phase-3.test.ts` all pass. The detector is fully unit-testable with an injectable clock and a stub ledger — no flaky timers in CI.

Tests cover: the absolute-share trigger, the baseline-divergence trigger (with the cold-start window correctly blocking it on a new agent), the per-key cooldown, the runbook-self exempt prefix, the disabled-config path, the empty-ledger path, start/stop idempotency, the new ledger query method, and the emitted-signal shape.

The existing token-ledger unit suite and the previous Phase 1 and Phase 2 burn-detection suites all still pass — no regression.

Side-effects review for this phase is in `upgrades/side-effects/token-burn-detection-phase-3.md`. The reviewer identified two known limitations (raw-HTTP bypass paths grandfathered out of phase one, and cold-start blind spot to baseline divergence) — both accepted by the umbrella spec. No new blocking concerns. Second-pass review is not required for this phase per the instar-dev criteria; phase four (the runbook with blocking authority over LLM calls) will require it.

