6krrt/plans/cockpit-quick-wins.md

# Cockpit quick wins: six small admin-portal fixes

Status: done -- shipped in PR #101
Date: 2026-09-23
Source: `plans/cockpit-brainstorm.md` section 5 (items R2, R5, E3, C1, G1, G3).
Each item below was observed on the live portal or checked read-only against
the live `router.db` on 2026-09-23.

## Ground rules (all items)

- **Worktree, not the main checkout.** Create a worktree from `main` HEAD
  (`c87e675` or later) on branch `feat/cockpit-quick-wins`. The main checkout
  at `/home/alee/Sources/6krrt` has UNCOMMITTED edits from other work,
  including `admin/frontend/controls.html` (a `confidence_threshold` ->
  `confidence_min` rename around lines 1026 and 1150) and
  `tests/test_admin_frontend.py`. Do not touch, stash, or commit them. C1 edits
  a different region of `controls.html`; keep it that way so the later merge
  is clean.
- Commit by explicit path. Never `git add -A` or `git add .`.
- **Never touch port 8080** (production). For visual checks, run a throwaway
  instance on **8081** from the worktree, with a temp copy of the DB, never the
  live `router.db` for writes.
- Never edit `config/config.yaml` or `config/config.local.yaml`.
- ASCII only in new code, comments, and UI strings. No middle-dot separators
  (U+00B7); relate facts with layout, or with `:` or a rephrase.
- No paragraphs of prose in the UI. One line per hint at most.
- One commit per item, in the order listed. `pytest` (offline) and
  `ruff check` stay green after each commit.
- For every UI change, take a screenshot on 8081 and check the changed area
  zoomed in, not just the item's checklist.

---

## 1. R5: Classifier card shows a wrong value on first paint

**Problem.** `admin/frontend/controls.html:264-268`: the
`#classifier-mode-select` `<select>` renders with `local_llm` selected by
default (first `<option>`). Until `loadClassifierConfig` (sets `.value` at
~line 1116) returns, the card claims `local_llm` when the live mode is
`local_encoder`.

**Fix.** Render the select disabled, with a leading
`<option value="" selected>loading...</option>`, and the Save button
disabled. On load: remove the placeholder option, set the value, enable both.
On fetch failure: keep them disabled and show an inline one-line error.

**Test.** In `tests/test_admin_frontend.py`: assert that the static HTML of the
select has a selected placeholder and the `disabled` attribute, and that no
real mode option is `selected` in the static markup.

## 2. G1: Nav links hardcoded in eight files

**Problem.** Every page (`index.html`, `models.html`, `profiles.html`,
`proficiency.html`, `decisions.html`, `quota.html`, `controls.html`,
`providers.html`) hardcodes the same `<ul>` of seven `nav-item` links, and
sets `active` by hand. `navbar.js` (the header comment) already records that
adding Quota was an eight-file edit.

**Fix.** Define the link list once in `navbar.js`
(`[{href, label}]`, same order as today: Models, Profiles, Proficiency,
Decisions, Quota, Controls, Providers). Render it into a placeholder
(e.g. `<ul class="navbar-nav" id="nav-links"></ul>`) on each page. Mark
`active` by matching `location.pathname`, with `/admin` and `/admin/` mapping
to Home (no link active). Remove the hardcoded `<li>`s from all eight pages.

Keep the rendered markup identical: same classes (`nav-item`, `nav-link`,
`active`), same hrefs, same order. Pages must still render their nav when
`navbar.js` is loaded, and it is already loaded on every page.

**Test.** One test that parses all eight HTML files and asserts none contains
a hardcoded `class="nav-link" href="/admin/...` list. One test asserting that
the `navbar.js` link list has exactly the seven hrefs above.

## 3. E3: Decisions filters are not in the URL

**Problem.** `admin/frontend/decisions.html` never reads or writes
`URLSearchParams`. No other page can link to "decisions for this model" or
"this session", and a filtered view cannot be shared or reloaded.

**Fix.**
- On load, after the filter `<select>`s are populated (~lines 405-420), read
  `kind`, `category`, `profile`, `tier`, `q` (search) and `size` from
  `location.search` and apply them. If a value is not among a select's
  options, add it as an option rather than dropping it (a link may name a
  category that has no rows in the loaded window).
- On any filter change (`resetPageAndRender`, the Clear button, page size),
  write the current filters with `history.replaceState`. Omit empty values.
  Don't push history entries.
- `q` also accepts a model id or a session id, since search already matches
  both (`search` at ~line 433).

**Test.** A static test that `decisions.html` reads `URLSearchParams` and calls
`history.replaceState`. On 8081, open
`/admin/decisions?category=diff_checking&q=deepseek`, confirm the filters and
the rows match, and screenshot it.

## 4. R2: The Decisions tile counts verifications and mixes diagnostics with ground truth

**Problem.** `admin/frontend/index.html:597-610`: the Home "Decisions" tile
sums `_snap.verdict_mix`, which is `metrics.verdict_mix()` and counts
`verifications` rows by verdict. Live DB, last 7 days:

| verdict | kind | n |
|---|---|---|
| unverifiable | structural | 2,660 |
| succeeded | client_outcome | 96 |
| failed | client_outcome | 82 |
| ok | local_llm | 29 |
| ok | structural | 7 |
| malformed | local_llm / structural | 4 / 7 |
| truncated | structural | 2 |

The tile shows "2,887 verified in 7 days: 132 ok, 93 failed". Actual route
decisions in 7 days: **2,678**. "ok" adds client `succeeded` to structural and
`local_llm` ok. "failed" adds client `failed` to `malformed`. Per CLAUDE.md,
structural and `local_llm` verdicts are diagnostics only; `/outcome`
(`kind = 'client_outcome'`) is the only ground truth.

**Fix.**
- Backend: in `src/metrics.py`, add `decision_outcome_summary(conn,
  since_days=7)` returning
  `{decisions, client_reports, client_ok, client_failed}`:
  `decisions` = `route_decisions` rows with `observed_at` inside the window;
  `client_*` = `verifications` rows with `kind = 'client_outcome'` inside the
  window (`succeeded` = ok, `failed` = failed). Include it in the admin
  snapshot (`src/admin.py` near line 2131) as `decision_outcomes`. Leave
  `verdict_mix` unchanged; the TUI uses it.
- Frontend: the tile headline becomes `decisions`. Qualifier lines:
  - `routed in 7 days`
  - `178 client reports (6.6%): 96 ok, 82 failed` (coverage =
    `client_reports / decisions`; the failed count uses the warn colour when
    the fail rate among reports is above 10%, matching the existing Signal
    quality card threshold).
  - With zero reports: `no client reports in 7 days`.
- Drop the word "verified".
- Use `metrics.py`'s existing window idiom:
  `julianday(observed_at) > julianday('now', '-' || ? || ' days')`.

**Test.** `tests/`: a metrics unit test with a seeded in-memory DB that
includes structural, `local_llm` and `client_outcome` rows, asserting only
`client_outcome` rows are counted and that `decisions` comes from
`route_decisions`. A frontend static test that the tile no longer reads
`verdict_mix`.

## 5. G3: Warning dismissals don't stick on rate warnings

**Problem.** `admin/frontend/index.html:1010-1040`: a dismissal is keyed on
the warning's exact text. That's deliberate ("when the underlying numbers move
the text moves with them... the warning comes back"). But warnings that embed
a live rate or count ("3.2x pace", "n=4") change text on nearly every poll, so
a dismissal never holds.

**Fix (interim, until structured warnings exist).** Key each dismissal on
`digit-normalized text + severity`: replace every run of digits (and decimal
points inside a number) with `#`, then append `|` + `warningSeverity(text)`.
The warning comes back when its wording or its severity changes, not when a
digit moves. This is the same normalization `rejection_warnings` already uses
for grouping (CLAUDE.md, the reactive detector section).
- Migrate the existing stored keys on load: normalize each and dedupe, same
  pattern as the existing one-time carry-over from `dismissedWarnings`.
- Update the block comment to state the new rule and why it changed.

**Test.** A static or JS-extracted unit test: two texts differing only in
digits produce the same key; the same text at different severity produces a
different key.

## 6. C1: One knob table instead of two columns

**Problem.** `admin/frontend/controls.html`: "Runtime Knobs" (`#runtime-list`,
`renderRuntime` ~line 687) and "Persisted Config" (`#config-list`,
`renderConfig` ~line 821) list largely the same knobs in two side-by-side
cards, in different orders, and persisted labels truncate
(`objective.incumbent_cache_pri...`). Checking whether a runtime value has
drifted from its persisted value means matching rows by eye.

**Fix.**
- One card, **Knobs**, full width, as a table:
  `knob | live | persisted | layer | ` with the columns meaning:
  - `knob`: the dotted config key, never truncated (wrap if needed).
  - `live`: the runtime control, if the knob has one, else empty.
  - `persisted`: the persisted-config control, if the key is in the persisted
    allowlist, else empty.
  - `layer`: the existing `base` / `overlay` badge.
  - A **drift** badge in the row when live differs from persisted
    ("reverts on restart").
- Pair rows through the runtime-to-config mapping that already exists in
  `src/admin.py` (`_BOOL_KNOBS` at ~line 348, plus the non-bool runtime knob
  tables beside it). Expose that mapping to the frontend: add the dotted
  config key to each item in the `GET /admin/api/runtime` response, rather
  than duplicating the table in JS.
- Keep the existing save semantics exactly: runtime controls POST to
  `api/runtime/{knob}` immediately, as today; persisted controls stay dirty
  until the Save button, as today. Keep the existing hint badges (for example
  "enables the reuse window").
- Keep the help lines ("Live on the next request...", "Applied on
  restart...") as one line each, placed as column-header tooltips or a single
  line under the table.
- Don't touch the classifier-card region (lines ~1000-1160); another branch
  edits it.

**Test.** `test_admin_knob_coverage.py` must still pass unchanged. Add a
test that every runtime knob in the API response carries a config key, and
that the key resolves to a real `RouterConfig` path. Visual check on 8081:
set one runtime knob so it differs from persisted (on the 8081 instance
only), then confirm the drift badge shows. Screenshot the whole table and a
zoomed crop of one drifted row.

---

## Done means

- Six commits on `feat/cockpit-quick-wins`, one per item, in the order above.
- `pytest` and `ruff check` green on the worktree.
- Screenshots from 8081 for items 1, 3, 4 and 6.
- The 8081 instance stopped, by the PID you started.
- A short report listing each commit, the tests added, and anything
  deferred, with the reason.