6krrt/plans/tui-overhaul.md

TUI overhaul: catch the dashboard up to the schema

Status: done -- tui.py plus the tui_model.py split

Status: FINAL — decision-complete. Written 2026-09-04 against main at a0c7e8e.

Why now

The TUI (src/tui.py, tui_model.py, tui_screens.py, tui_sse.py — ~1,000 lines total) has drifted behind the data it displays. Five columns were added to route_decisions across this session's merges and none reached the dashboard, and the decision table has never had a timestamp.

The admin portal got a Profile column in PR #25. The TUI did not. It is the same data.

1. The decision table is missing a timestamp

Declared columns (src/tui.py:314-316):

"id", "kind", "category", "tier", "ctx", "selected", "est $", "flex"

observed_at is already carried by decision_row in tui_model.py — it is fetched and then never rendered. So this is a display change, not a data change.

Add a time column. Render it short (HH:MM:SS), not the full ISO timestamp: the rows are dense, the date is almost always today, and the full form would crowd out selected, which is the column people actually read. Put it first — it is the natural scan axis for a live feed.

2. Five columns exist in the schema and are invisible

Measured by diffing PRAGMA table_info(route_decisions) against what decision_row exposes:

column	shipped in	why it matters
profile	PR #25	which named profile served the request
exploration	proficiency branch	whether epsilon-greedy picked this, not the ranking
pinch_original_tokens	PR #18	context pruning input
pinch_final_tokens	PR #18	context pruning output
request_id	proficiency branch	the join key to /outcome reports
session_key	earlier	hashed session fingerprint

Do not add six more columns to the table. It already has eight and the terminal is not wide. Instead:

• Add profile to the table proper. It changes which models were even considered, so a decision cannot be read without it — the same argument that earned it a column in the admin portal.
• Add an E flag in the existing flags idiom for exploration, alongside how flex is already rendered. An exploratory pick is not a ranking result and must be visually distinguishable, or the operator reads a deliberate random sample as the router's judgement.
• Put pinch_*, request_id, session_key in the detail popup (tui_screens.py, opened with Enter or e), which already shows the full decision JSON. They are per-decision forensics, not scan-axis data.

3. The quota panel shows the wrong thing

This section depends on plans/quota-balance-and-burn-rate.md and must not land before it. That plan replaces percentage-of-plan with balance and burn rate, because the current framing is measurably wrong: the warning says "a quota is a wall, not a bill — requests fail rather than costing more" while usage sat at 146% of plan and nothing failed, since the provider bills overage against a credit balance.

Once that lands, the TUI panel (#quota-panel, #quota-progress, #quota-legend) should lead with balance and projected runway ("$12.19 left, ~23h at current burn") and demote the percentage bar to secondary. A progress bar against a plan figure that is routinely exceeded is actively misleading — it implies a ceiling that does not exist.

Sequencing: if the quota plan has not landed when this one runs, do items 1, 2 and 4 and leave the panel alone. Do NOT reimplement balance/burn independently in the TUI — metrics.quota_burn is the single source and the TUI reads /metrics.

4. Surface the warnings that already exist

coverage.warnings from /metrics already carries catalog staleness, quota burn, scoring coverage gaps and ceiling warnings. #warnings-panel exists. Confirm every warning class actually reaches it — the vision-ceiling incident on 2026-09-04 showed a whole warning family that was computed and never displayed, and the fix there was surfacing, not computing.

This is a verification task as much as a feature: for each warning the /metrics coverage.warnings list can emit, assert it renders.

Non-goals

• No new data. Everything here is already in route_decisions or /metrics.
• Do not widen the decision table beyond one added column plus one flag.
• Do not reimplement any metric in the TUI. tui_model.py is the pure data layer over /metrics and /events/decisions; keep the computation in metrics.py.
• Do not import textual outside the TUI modules. The dispatch path must stay free of the UI dependency — that separation is deliberate and tested.
• No colour/theme rework. This is about information, not appearance.

Success criteria

• The decision table shows a short HH:MM:SS time column, first.
• profile is a column; exploration renders as a flag beside flex.
• pinch_original_tokens, pinch_final_tokens, request_id and session_key appear in the detail popup.
• A test diffs PRAGMA table_info(route_decisions) against what the TUI model exposes and fails if a column is added to the schema without a decision about surfacing it. This is the test that stops the drift recurring — the rest of this plan is a one-time catch-up, this is the part that keeps it caught up.
• Every warning class /metrics can emit renders in #warnings-panel.
• Quota panel leads with balance and runway if the quota plan has landed; otherwise untouched and noted.
• textual still imported only by TUI modules (existing test stays green).
• Full suite green with local_energy.enabled both true and false.
• The user's config/config.local.yaml is byte-identical after the run (local_energy.enabled: true, tariff_usd_per_kwh: 0.159). Corrected 2026-09-05: this previously named config/config.yaml. PR #26 moved deployment values into the gitignored overlay, so config/config.yaml is clean and tracked, and editing it is an ordinary commit. The file that cannot be recovered is the overlay — it is not in git history at all.