bullswarm 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,300 @@
 # bullswarm changelog
 
+## 0.33.0 — the dashboard release
+
+- dashboard: the phone `Home` no longer hides data behind its width. The
+  `budget · this week` block draws every pool the desktop draws — four today —
+  or ends with `+N more` when the rows genuinely do not fit, and its names are
+  wide enough that `claude-code:wati` and `claude-code` read as two pools
+  rather than one truncated one. The by-pool, by-model and by-project lists
+  keep at least their top three rows (`+N more` for the rest) and always paint
+  the whole percentage, never `24…`. The summary figures sit one per line, so
+  `Busiest project` and `Favourite model` are whole at 55 columns, and the
+  spent tile's empty state fits the phone row.
+- dashboard, **keys corrected**: `h` opens **Home** and `?` opens **Help**.
+  In 0.32.0 both opened Help, and an earlier 0.33.0 entry wrongly listed them
+  as unchanged. `r` `b` `s` `y` `f` keep the pages they opened. The key table,
+  the nav tail (`[Top] [End] [?.Help]`), the Help page, the README and the
+  observing guide all say the same thing, and tests pin both bindings.
+- dashboard: a finished run the history index has not covered yet is named by
+  the project its `goal.json` working directory belongs to — the same
+  derivation `bullswarm workflow reindex` uses — instead of reading
+  `unknown project`. `unknown project` now means only what it says: no working
+  directory was recorded for that run.
+- dashboard: the stacked column charts on `Home` (spent per day) and `Stats`
+  `Trends` are drawn to eighth-block precision. The top cell of a bar is one of
+  `▁▂▃▄▅▆▇█`, so a `≈$2.93` bar sits below its own `≈$3.00` tick instead of
+  overshooting it; the axis top and the row count are chosen together so every
+  tick label lands on a row with even spacing; and every non-zero pool slice
+  gets at least one eighth-block, smallest on top, so `codex` and
+  `command-code` appear on any day they spent anything.
+- dashboard: `Stats` `Pools` drops the shared unlabelled “licence used per day,
+  by pool” line chart. Each pool now carries its own seven-day sparkline on its
+  own row — one glyph per day of end-of-day usage, `▏` on a day the quota
+  window rolled over — under one caption saying that a drop after `▏` is the
+  window resetting. A reset is read from the recorded `resets_at` moving, never
+  guessed from a falling reading. The row tails (`≈ $3.06 API`, `✓ 100%`) are
+  measured before the meter is sized, so nothing truncates at 170 or 200
+  columns.
+- dashboard: `Budget` reads in plain words. Each pool is a header
+  (`name · weekly plan · resets <day time> (in Nd Nh)`) over four labelled
+  rows: `used` (the meter, a whole percent, and `N% of the window gone → on
+  track`), `by bullswarm` (this tool's share of the whole plan, with the
+  measured minutes and `other tools N%`), `room` (`about N more medium runs
+  before the reset`) and `so far` (≈ money and the two biggest workflows).
+  Figures are whole numbers. The subscription line appears only where a price
+  is declared — the `Subscription rate: —` rows are gone — and
+  `workflows 131.24% · rest 0% · workflows exceeds the reported meter` is
+  replaced by one footnote in words when the measured share exceeds the meter.
+  The page-foot notes are one short block.
+- dashboard: **Runs and History are one page.** `Runs` opens on an `active`
+  block — every running or waiting run with its plan strip and per-step bar,
+  drawn exactly as `Home`'s running section draws it — and History's
+  day-grouped table below it: a day header with its count and ≈ total, then one
+  row per run with status glyph, short id, project, goal, duration, ≈ cost and
+  time, under the selection cursor, so `Enter` and the digits open a run and
+  older days load as the reader scrolls. The `agents` and `run it` blocks moved
+  to `Help`. The `History` tab is gone from the tab row — the tabs are Home,
+  Runs, Budget, Stats, Fleet — and **`y` jumps to the first day header** of
+  Runs. The one-second refresh keeps the table cursor where the reader put it
+  (it used to snap back to the in-flight run, so `Enter` opened the wrong
+  workflow).
+- dashboard: the second owner-review round, from phone screenshots of the
+  0.33.0 preview. `Stats` `Models` draws stacked columns per day and model
+  instead of a three-row line chart that flattened every model under four
+  hours onto the zero line (Opus ran 29, 9, 897, 75, 278 and 686 minutes on
+  six consecutive days and showed on one). Axis labels mark the bottom of
+  their row, so a bar of 15 rises half a row above `14` instead of reading as
+  16. Phone columns are equal width and the charts use the rows the screen
+  has. A column never lays two colours side by side in one row: slices too
+  small for their own eighth merge into one grey `other` slice, counted in the
+  legend. Each pool and model keeps one colour on every page and period. Under
+  a column, totals keep one blank cell apart and a long duration falls back to
+  whole hours. `Budget`: a pool whose meter never moved during its measured
+  runs says `share unknown · meter did not move during 32 measured runs`
+  instead of `≈ 0%`; credits join the `used` row (`0 of 70 credits`); a pool
+  with nothing left says `no room left before the reset`. The Runs day table
+  never cuts a duration (`3h21m`, not `3h2…`). The tab row stays five tabs on
+  the Help page. Charts draw from fourteen hues and never give two series in
+  one chart the same colour (the 30-day Trends had three purples and the
+  Models chart seven models in two colours); slices stack smallest at the
+  bottom, biggest on top; the legend wraps to name every series instead of
+  hiding the rest behind `+N more`. The mouse now lights the clickable row
+  under the pointer in reverse video, the way the Mod pane does (a whole row
+  when it is the row's only target, just the button when several share a
+  row); the TUI asks the terminal for motion reports and releases them on the
+  way out. Only list rows light up (a run in the table, a step in a plan);
+  chart columns, tiles, meters and tabs do not, and inside a lit row only the
+  words reverse — a step's bar and the plan strip's `──○──` connectors keep
+  their colours. Home's breakdown percents sit right-aligned in one column, so `2%`
+  lines up under `19%`.
+- dashboard, **no longer laggy**: a CPU profile of the idle TUI showed it busy
+  61% of the time. Every one-second tick re-discovered Claude accounts through
+  the macOS keychain (`security`, 100–300 ms, blocking), re-ran the pool-rename
+  migration check over the whole state.json, and on Runs re-read all 300 run
+  directories. Usage now reloads every 10 s, the keychain read is cached for a
+  minute, the migration check is remembered per file fingerprint, the run
+  catalogue rebuilds only when an active run changes or 15 s pass, and the
+  unknown-project fallback asks `git` once per working directory. Idle busy
+  share after: 14%. The painter now rewrites only the rows that changed
+  since the last frame (a spinner tick is a few dozen bytes instead of the
+  whole 120×40 screen), which is what a phone or a remote terminal feels.
+- dashboard: no page draws an empty track where it has no data. The `Run`
+  page's budget block is titled `licence this run used`, shows whole percents
+  (`≈ 0.4% of the weekly plan`, as a one-cell `▏` sliver rather than an empty
+  bar), writes `free model · no licence meter` for an unmetered pool instead of
+  a dotted track and a `—`, and collapses to a single sentence when no pool is
+  metered. The plan strip's pool row prints the pool name alone when the cell
+  cannot hold pool and model. A paused run's live block says
+  `paused · bullswarm workflow resume <id> continues it` instead of `waiting for
+  the next dispatch`, and the ETA footnote is
+  `ETA —: <step> has no recorded duration yet` rather than
+  `N of N remaining steps recorded no expected duration`. The same rule removed
+  the dotted `meter unavailable` tracks from `Stats` `Pools`.
+
+- dashboard: the visual-fidelity pass now composes `Home` with a four-column
+  7-day breakdown and a budget block, `Run` with a plan strip, per-step bars
+  and a `budget` / `live` / `so far` band, `Budget` with seven rows per pool
+  plus one consolidated footer, coloured stacked columns on `Stats` `Trends`,
+  and fixed columns on `History`, reducing its phone form from two rows per run
+  to one at 55 columns.
+- dashboard: the shared palette keeps its four existing meter colours and adds
+  seven named roles, including the four-shade heat ramp; `Help` groups the `r`,
+  `b`, `s`, `y`, and `f` keys into 35 body rows at 55 columns (from about 51)
+  and drops the nonexistent `Budget` sub-tabs.
+- dashboard: the `Run` plan strip closes a fan the way the prototype does —
+  each lower branch hangs under the `┬` that opened it, is ruled across to the
+  joint, and the last one ends in `┘` under the closing `┬`; it used to draw a
+  `┴` with nothing beneath it when the lower branch was the longer name. The
+  `Stats` `Models` footnote says `no per-model money` in words instead of
+  naming the `apiEquivalentUsd` field.
+- dashboard: the phone layouts now put one item on one row where the page is a
+  list — `Stats` `Models`, `Stats` `Projects` (with its sparkline beside the
+  name), `Stats` `Pools`, `Fleet` and `History`, plus `Home`'s today tiles and
+  per-step bars. `Budget`'s seven-row pool block, `Home`'s `budget · this week`
+  pool and the `Runs` list keep their extra lines on purpose.
+- dashboard: `Stats` `Models` draws a worker-minutes-per-day chart whose series
+  are coloured to match the model list beneath it, and `Stats` `Projects` draws
+  a sparkline beside every project name. At a 200-column frame a project keeps
+  name, sparkline and figures on one row, with the sparkline capped at four
+  cells per measured day so seven days read as a shape rather than a
+  frame-wide run of repeated glyphs.
+- dashboard: `Stats` rows built from the shared `compactRow` now lay their
+  fields out on the frame minus their one-cell indent, so the last field no
+  longer lost its final character to the frame's own truncation (`p50 5…`
+  where `p50 54m` fits).
+- dashboard: every page now composes to a 200-column frame instead of stopping
+  at the 120-column composition — measured on the real binary, the widest
+  painted row is 200 cells on every page except `Fleet`, which reaches 188.
+- dashboard: `Run` draws a bar for the running step inside the plan strip, using
+  an empty indeterminate bar when the step recorded no expected duration, and
+  `Step` keeps its task summary short enough that the `output` and `artifacts`
+  sections both start inside a 26-row phone frame rather than below it.
+- data: the pass keeps real figures and the `≈`/basis rule. An undeclared
+  subscription price, an expected duration, and a per-run licence draw
+  deliberately remain blank with their reasons. The months-wide heatmap does
+  not move over: `Stats` uses only history that exists and, when there are no
+  measured days, renders a blank with `No workflow history yet — the heatmap
+  has no measured days.` rather than inventing the prototype's number.
+- docs: `README.md` and the observing guide now describe the shipped
+  composition and the same data-honesty rule, and name the three places whose
+  phone form deliberately keeps more than one row per item rather than claiming
+  a universal one-row layout.
+
+- routing: measured pacing rates now charge timed in-flight work at the actual
+  `rate × remaining minutes` with no 3-point floor, so an expiring-soon pool
+  with a known burn rate is not demoted by a tie-breaker meant for unmeasured
+  pools. `config.inflightPenaltyPct` remains the per-agent fallback for pools
+  without a measured rate (and for in-flight records with unknown duration).
+- workflow: every attempt record now carries `routeWhy` (the router's reason)
+  and `routeCandidates` (each pool's effective surplus, urgency state and
+  pacing forecast at pick time); `workflow action show --json` and
+  `runs result --json` print them, and older state files still load.
+- dashboard: the full-screen surface now has eight pages — Home, Runs, Run,
+  Step, Budget, Stats, Fleet, and Help (History is the day table inside Runs,
+  see above). Home answers what happened today and what is active; Runs is the
+  active block over the day-grouped table; the integration actions sit on Help; Run
+  and Step explain a workflow and one action; Budget shows quota, measured
+  worker-time share, labelled money, fit, and biggest workflows; Stats covers
+  Overview, Trends, Pools, Models, and Projects; History is the dated timeline;
+  Fleet shows lane/provider rungs; Help names the controls. Home, Stats, and
+  History read the rollup index instead of parsing every run directory on each
+  refresh.
+- workflow: every finished V2 run now records a per-run `rollup.json` and
+  appends an idempotent line to `~/.bullswarm/history/runs.jsonl`. On the real
+  corpus used for the release, `294` run directories yielded `181` indexed
+  finished V2 records; `105` legacy and `8` unfinished directories were left
+  out. History spans `15` recorded days, and `94` of the `188` V2 results are
+  verified.
+- dashboard, **keys rebound** — three keys changed meaning, one is gone, and
+  seven are new. Rebound: `r` opened nothing and refreshed the view in 0.32.0
+  and now opens **Runs** (the 1 s timer refreshes, so no key needs to);
+  `b` was **move out** and now opens **Budget** (`Esc` and `←` are move out);
+  `Tab` was **next workflow** and now cycles the current page's **sub-tabs**
+  (`Shift+Tab` cycles workflows, as it did). Removed: the Usage page is
+  replaced by **Budget** (`b`) and **Fleet** (`f`), so **`u` is gone**, and
+  Usage's `l`/`p` lane/provider grouping keys are now **`Tab`** on Fleet.
+  New: `s` Stats, `y` History, `f` Fleet, `p` cycles the period, `Home` top,
+  `End` bottom, and `ctrl+s` copies the screen. Moved, not rebound: `i`, `/`
+  and `a` are **Runs-page** keys now that Home is the prototype's Home.
+  Unchanged: `1`–`9`, `Enter`/`→`/`l`, the arrows, `PgUp`, `PgDn` and `q`.
+  (Corrected: an earlier draft of this entry said `h`/`?` were unchanged. They
+  are not — `h` opened Help in 0.32.0 and now opens **Home**, and `?` alone
+  opens **Help**. `y` no longer opens a History page; it opens **Runs** at the
+  first day header of its history table. See the two entries below.)
+- accounting: money and licence figures are either measured or carry `≈` with
+  their basis. API-equivalent estimates use the recorded per-attempt estimate;
+  a licence draw uses the measured pool rate multiplied by measured worker-
+  minutes and stays blank when no rate is available; an undeclared subscription
+  price stays null. On the release corpus, `113` of `188` V2 runs carried a
+  cost figure and the other `75` did not, so no zero was manufactured for them.
+- workflow: `bullswarm workflow reindex [--json] [--force]` backfills finished
+  runs from their durable directories, skips legacy and unfinished runs,
+  repairs missing index entries, and can rebuild existing rollups with
+  `--force`. The JSON form reports `ok`, `indexPath`, `scanned`, `written`,
+  `skipped`, `legacy`, `unfinished`, `present`, `failed`, and `failures[]`.
+- docs: the observing guide, README, CLI reference, command help, and Claude
+  Mod README now describe the eight pages, the full key map, the measured/
+  labelled money rule, and the Mod's smaller Run/Step/Usage-Pools surface.
+
+## 0.32.1 — free models first, with graceful failover
+
+- meters: rate-limited or failed live reads now persist a per-pool negative-cache hold (honouring `Retry-After` or the five-minute freshness window), and `pools`/the Claude Mod identify the stale snapshot's error and retry time.
+- rename: the OpenCode pool is now `opencode`; the first run migrates saved
+  state, routing, provider, and meter names automatically, while historical
+  workflow run records keep their recorded `opencode2` name.
+- routing: a pool whose model for the effort tier costs nothing is ranked ahead
+  of every metered pool while it is healthy. Free-ness is per (pool, effort
+  tier) and comes from the connector — `modelProfiles[].free`, or a model name
+  carrying a standalone `free` segment. The free tier sits below the forecast
+  gate and the 5-hour headroom tier and above expiring-soon urgency, so an
+  expiring metered window can now go unspent while free work runs; the ranking
+  among metered pools is unchanged. The reason reads `free pool first: <pool>
+  (free model <model>, …) · metered pools ranked below free: <pool> <surplus>`.
+- routing: a pool that stalls, returns a server error, or (on a free pool) hands
+  back literally empty output takes a strike. The first is recorded; the second
+  consecutive one soft-benches the pool for a 10-minute cooldown, after which it
+  returns automatically. The strike count survives the cooldown and is cleared
+  only by a success. Auth is untouched: an upstream auth failure still
+  quarantines and still spreads across a credential group. An answer the
+  verifier judged thin but not empty stays semantic and is not retried
+  elsewhere.
+- workflow: a free pool's silence clock is the median wall time of its own
+  recorded runs at that (pool, effort) rung — the `p50`, once 3 runs exist there
+  — with a 5-minute floor, instead of the one-hour default a metered pool keeps.
+  The multiplier on that median is 1 (`FREE_STALL_P50_FACTOR`): a worker silent
+  for as long as the whole rung usually takes has stopped working. Stalled
+  attempts are excluded from the median so a pool cannot tighten its own
+  threshold by stalling.
+- workflow: a stalled attempt ends, keeps its partial output on disk (the retry
+  writes a new `-attempt-N` file beside it, never over it), releases its
+  in-flight ledger entry, and re-dispatches the same action on the next eligible
+  pool in the same run. The attempt record and `attempt.finished` carry
+  `stalled`, `partialOutput`, `silentSec` and `willRetry`; a new `pool.benched` event names
+  the pool, reason, strike count and deadline; the retry's reason is prefixed
+  `fallback from <pool> after stall <n>s`. A free-pool stall (and the
+  free-only literally-empty-output provider reclassification) does not spend
+  `maxMechanicalRetries`; the tried-set is the bound and each pool is tried at
+  most once for the action. A metered-pool stall keeps the mechanical retry
+  accounting.
+- workflow: evidence and acceptance steps are exempt from the free tier and
+  route on pace as before, with one preference — a pool that wrote the work
+  being judged is chosen last, and only when no other pool is eligible, which
+  the reason then says (`evidence step: only the writer pool <pool> is
+  eligible`). This restores, in prefer-not rather than forbid form, the steering
+  removed in `eb83b79`; the reason line now names the exception, which its
+  absence was half the reason for that removal.
+- pools: `bullswarm pools` prints `free=<model>` for a pool whose model costs
+  nothing (`free=<tier>:<model>` when it differs per effort tier, since `pools`
+  names no lane), `BENCHED until <time> (<reason>, <n> strikes)` for a benched
+  pool, and `strikes=<n>(<reason>)` for one carrying an uncounted-out strike. It
+  sweeps expired benches the same way it sweeps expired quarantines.
+- routing: measured pacing rates now charge timed in-flight work at the actual
+  `rate × remaining minutes` with no 3-point floor, so an expiring-soon pool
+  with a known burn rate is not demoted by a tie-breaker meant for unmeasured
+  pools. `config.inflightPenaltyPct` remains the per-agent fallback for pools
+  without a measured rate (and for in-flight records with unknown duration).
+- workflow: every attempt record now carries `routeWhy` (the router's reason)
+  and `routeCandidates` (each pool's effective surplus, urgency state and
+  pacing forecast at pick time); `workflow action show --json` and
+  `runs result --json` print them, and older state files still load.
+
+- routing: a pool whose pacing window is about to reset is `draining` only
+  when its forecast is at or above 95% *and* ahead of the window's own clock,
+  the same clock-relative shape the 5h near-limit line already has. A pool on
+  or behind pace keeps spending right up to its reset instead of being ranked
+  last by a fixed line (observed 2026-09-16: command-code at 94.9% used with
+  98% of the month gone was passed over while +3 points of quota expired).
+  The skip reason now reads `expiring but draining (forecast >= 95% and past
+  its clock): <pool> <forecast>% (<elapsed>% elapsed)`.
+- workflow goal: refuses to launch a duplicate of a run that is already going.
+  Before anything is validated or launched, an ongoing run with the same goal
+  text and cwd exits 2, naming that run's shortId, age, and watch command
+  (JSON: `{"error":"duplicate-goal",...}`); `--again` starts the copy anyway
+  (observed 2026-09-16: a caller whose JSON parser failed on the first
+  launch's output retried five seconds later and two identical workflows ran
+  side by side in the same directory).
+
 ## 0.32.0 — the dashboard is the main screen
 
 - wording: a program run's dependency levels are called phases everywhere the

package/GOAL.md

@@ -35,7 +35,7 @@ A working prototype installed at `~/.bullswarm/` with:
 2. **Connector registry** (`~/.bullswarm/connectors/*.json`): declarative per-CLI
    spawn command, auth-failure signatures, output extraction, verify contract,
    quirk fields (e.g. PWD resolution). Seeded with codex, grok,
-   command-code, opencode2 — extracted from the proven `/offload` skill.
+   command-code, opencode — extracted from the proven `/offload` skill.
 3. **Meter layer**: per-pool window definition (5h / weekly / none) with
    programmatic readers where providers expose usage, manual declaration
    (`--meter pool=window,pct`) where they don't. Unmetered pools pace as

package/README.md

@@ -55,9 +55,10 @@ as a Claude Mod (a plugin of TypeScript function hooks, behind
 prompt, the pools named in the model's context, Claude's general-purpose
 subagents routed to whichever pool has surplus and answered with the
 verified output, and the verdict appended to every `bullswarm run` the model
-runs. The Mod is the dashboard's read-only counterpart: the same Run, Step and
-Usage pages in the same meter colours, with no edit or install action. See
-[mods/bullswarm/README.md](mods/bullswarm/README.md).
+runs. The Mod is the dashboard's read-only counterpart: its pane shows Run,
+Step, and the Usage/Pools view in the same meter colours. It does not expose
+the dashboard's Home, Runs, Budget, Stats, Fleet, or Help pages, and
+it has no edit or install action. See [mods/bullswarm/README.md](mods/bullswarm/README.md).
 
 Three ways to load it:
 
@@ -83,12 +84,67 @@ over the skills-dir link, and Claude says so at startup.
 Once setup is complete, bare `bullswarm` opens the dashboard on its Home page.
 Use `bullswarm --setup` or `bullswarm setup` to open setup again, and use
 `bullswarm workflow tui` when you want the explicit dashboard command. The
-pages are Home, Run, Step, Usage, and Help. A sticky header and bottom nav
-(`[ 1.<run> ] … [ usage ] [ help ] [ quit ]`, each button's key
-underlined inside its label) carry `q` (quit),
-`h` or `?` (help), `u` (usage), `e` (edit), `i` (install), `l`/`p` (Usage tabs), arrows or
-PgUp/PgDn (scroll), and Enter; click any button, tab, run or step, or use the
-wheel to scroll.
+eight pages answer different questions:
+
+| Page | What it answers |
+|---|---|
+| Home | What happened today, what is verified, what measured or labelled money/licence data exists, and what is active or recent; includes pool/model/project breakdowns. |
+| Runs | Which workflows are active or historical — one `active` block and the History day table below it — plus the product commands; the integration line and `/` filter live here, and `?` carries the agents and `run it` blocks. |
+| Run | Where one workflow is in its plan, which workers are live or next, and its ETA and budget shares. |
+| Step | What one action is doing: route, attempt, activity, verdict/failure, prompt, usage, events, output, and artifacts. |
+| Budget | Pool quota windows, measured worker-minutes versus rest, measured or `≈` money, fit, and biggest workflows. |
+| Stats | Runs, spend, worker-minutes, and verification over 7d/30d/all, by pool, model, and project. |
+| Fleet | Lane/provider model and reasoning rungs, records, meter state, and the setup edit hand-off. |
+| Help | Every key, click, layout rule, and dashboard command. |
+
+The visual-fidelity pass keeps the same real numbers while composing and
+colouring these pages like the approved prototype. At 55 columns every Home
+today tile and per-step bar, every Stats model, project and its sparkline, every
+Stats and Fleet pool row, and every run row in the Runs history table keeps one
+row per item on the phone; Budget's per-pool block (a header over `used`,
+`by bullswarm`, `room` and `so far`), Home's `budget · this week` pool (meter
+plus a reset line, as the prototype draws it) and the Runs `active` entry are
+the deliberate exceptions. At 200 columns every page composes to the frame
+rather than capping at the 120-column composition. Estimated figures still
+carry `≈` and their basis; a figure that cannot be measured is a line of words
+saying so — no page draws an empty or dotted track for missing data.
+
+Every page has a sticky header, a page tab row, and a sticky bottom nav. The
+tab row is five tabs — Home, Runs, Budget, Stats, Fleet — with Run and Step
+marking Runs, and Help shown only while it is open. The shared key table is:
+
+| Key | Does |
+|---|---|
+| `r` | open Runs; the view refreshes itself, so `r` is no longer refresh |
+| `b` | open Budget; it is no longer move-out |
+| `s` | open Stats |
+| `y` | open Runs at its History table (the first day header), except that it confirms a pending stop |
+| `f` | open Fleet |
+| `h` | open Home |
+| `?` | open Help |
+| `1`–`9` | open that run from the nav |
+| `Tab` | cycle the current page's sub-tabs |
+| `Shift+Tab` | cycle workflows |
+| `p` | cycle the period on Home and Stats |
+| `Esc` / `←` | move out one page, then Home |
+| `↑`/`k`, `↓`/`j` | move one line |
+| `Enter` / `→` / `l` | open the selected run, step, tab, or action |
+| `PgUp` / `PgDn` | scroll one screen |
+| `Home` / `End` | jump to the top or bottom |
+| `ctrl+s` | copy the screen through OSC 52, falling back to `pbcopy`, `wl-copy`, or `xclip` |
+| `q` | quit the dashboard; workflows keep running |
+
+The 0.33.0 rebinding is deliberate: `r` no longer refreshes, `b` no longer
+moves out, and `Tab` no longer cycles workflows. Esc/left moves out, the view
+refreshes itself, and Shift+Tab still cycles workflows. Runs also provides `/`
+(filter), `a` (active/all), and `i` (install); Run provides `o`, `v`, and `t`,
+and Fleet provides `e` for setup. Click tabs, tiles, bars, runs, steps, dates,
+or controls, or use the wheel to scroll.
+
+Home, Runs, Budget, and Stats read a per-run rollup that every finishing
+run appends to `~/.bullswarm/history/runs.jsonl`. After upgrading, backfill
+the runs that finished before 0.33.0 once with `bullswarm workflow reindex`;
+legacy runs get a minimal record and only runs still in flight are skipped.
 
 One bounded outcome — a task with a clear finish line:
 
@@ -198,7 +254,7 @@ page maps its pages, keys, and mouse controls.
 | [Concepts](https://bulls-work.github.io/bullswarm/guide/concepts) | Pools, lanes, surplus, the two windows, verdicts, quarantine, and the run directory |
 | [Run one task](https://bulls-work.github.io/bullswarm/guide/run) | Every `bullswarm run` option, and what each verdict asks you to do |
 | [Workflows](https://bulls-work.github.io/bullswarm/guide/workflows) | Authoring the program `workflow goal` executes: territories, dependencies, integration, acceptance |
-| [Observing runs](https://bulls-work.github.io/bullswarm/guide/observing) | `workflow watch`, the Home/Run/Step/Usage/Help dashboard pages, keys, mouse, and terminal glyphs |
+| [Observing runs](https://bulls-work.github.io/bullswarm/guide/observing) | `workflow watch`, the Home/Runs/Run/Step/Budget/Stats/Fleet/Help dashboard pages, keys, mouse, and terminal glyphs |
 | [Routing](https://bulls-work.github.io/bullswarm/guide/routing) | How a pool is picked: pace, 5-hour headroom, urgency, load, quarantine |
 | [CLI reference](https://bulls-work.github.io/bullswarm/reference/cli) | Every verb and nested subcommand, with its flags and defaults |
 | [Workflow program](https://bulls-work.github.io/bullswarm/reference/program) | The `bullswarm.workflow.program.v2` document: action fields, kinds, validation rules |