bullswarm 0.30.0 → 0.32.1

package/AGENTS.md

@@ -16,7 +16,7 @@ content. Published as `bullswarm` on npm.
    `src/meters/framework.js`).
 3. Provider quirks live in the provider's directory (`src/providers/<name>/`,
    `providers/contrib/<name>/`, or `~/.bullswarm/providers/<name>/`), never in
-   core logic (see `docs/guide/providers.md`).
+   core logic (see `docs/reference/providers.md`).
 4. Quarantine always auto-releases; recursion depth is core-owned via env
    (`BULLSWARM_DEPTH`).
 5. Workflow dispatches must honor the same guarantees as single runs:
@@ -84,7 +84,7 @@ providers live in `src/providers/<name>/`, contrib providers in
 `bullswarm provider scaffold <name> [--from <template>]`, then
 `bullswarm provider validate` and `bullswarm provider probe <pool>`. Write a
 `readUsage` export only if the vendor exposes a usage API — declared meters
-are the fallback, never the goal. The contract is `docs/guide/providers.md`;
+are the fallback, never the goal. The contract is `docs/reference/providers.md`;
 the authoring method is `skill/references/providers.md`.
 
 ## Releasing

package/CHANGELOG.md

@@ -1,5 +1,156 @@
 # bullswarm changelog
 
+## Unreleased
+
+## 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
+  product prints them (`Phase 2 · integrate`), matching what the planner's runs
+  already say; the ids in the events are unchanged.
+- dashboard: the full-screen Home, Run, Step, Usage, and Help pages now share
+  a sticky header and bottom nav, keyboard shortcuts, mouse clicks, and wheel
+  scrolling, so a live workflow can be understood in one place.
+- usage and edit: Usage renders every meter window, elapsed mark, reset, pace,
+  credit meter, and rung record with the same coloured cells as the status
+  view; its read-only note hands `[edit]` to setup and returns with fresh data.
+- install: Home's `[install]` action runs the same integration install as
+  `bullswarm integrate install --yes`, then shows each agent's skill,
+  awareness, and Claude Mod status.
+- bare command: after setup, bare `bullswarm` opens the dashboard; the first
+  run and `bullswarm --setup` or `bullswarm setup` open setup, while
+  `bullswarm workflow tui` remains the explicit dashboard form.
+- docs: the README, guides, CLI reference, and Claude Code pages now make the
+  dashboard the main screen and describe the Claude Mod as its read-only
+  counterpart — the same Run, Step, and Usage pages in the same colours, with
+  no edit or install action.
+
+## 0.31.0 — the Claude Mod, and a documentation site
+
+- mod: `mods/bullswarm` puts Bullswarm inside Claude Code's own interface as a
+  Claude Mod (function hooks, early access behind
+  `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`). Claude's general-purpose subagents
+  are routed to the pool with spare quota through `bullswarm run --no-caller`
+  and answered with the verified output; the verdict of every `bullswarm run`
+  and `workflow goal` the model runs is appended to its Bash result; the pool
+  meters are named in the model's context; a strip above the prompt lists
+  the ongoing workflow runs; and a docked pane shows one run as
+  `bullswarm workflow tui` draws it, every step a button that opens the
+  step laid out as the TUI's agent panel. `/bullswarm pools|status|on|off|
+  refresh|runs|pane|open <step> [run]|routed` answer from the mod; anything
+  else still reaches the packaged skill. The pool rows draw a white mark
+  where the window's elapsed time falls, and `usage` in the pane's bottom
+  nav opens a page with every meter window of every pool, its reset time
+  and pace, the credit meter where there is one, and every pool × tier rung
+  with its model, reasoning and record, grouped by lane or by provider. A
+  `route` tool lets the model switch routing when the person asks. Pool
+  display names come from the
+  `poolAliases` option; `strip` picks `runs`, `full` or `off`.
+- integrate: `bullswarm integrate install --agents claude --yes` also links
+  the mod under `~/.claude/skills/bullswarm-mod` and sets
+  `env.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` to `"1"` in `~/.claude/settings.json`;
+  `status` reports both and `remove` undoes both. A `settings.json` that is
+  not a JSON object is left alone and reported. `.claude-plugin/marketplace.json`
+  at the repository root makes `claude plugin marketplace add Bulls-Work/bullswarm`
+  and `claude plugin install bullswarm@bullswarm` work too.
+- workflow tui: the Preflight milestone now states the accepted goal (wrapped)
+  with the paths of `goal.json` and `initial-planner-response.json`, and the
+  planner milestone says how many actions in how many dependency levels the
+  plan has. The Live section lists the planner only while it is planning;
+  the "waiting for N workers" planner row and the "· N waiting" count are
+  gone, since Next already says that. The first plan's own milestone is gone
+  too: the levels that follow it say what it planned; plan revisions and
+  rejected planning attempts still appear. A goal with several lines wraps
+  line by line instead of carrying a line break inside one row. `workflow tui <run> --overview
+  [--width <cols>] [--height <rows>]` prints one overview frame (or `--json`)
+  for a caller that draws its own.
+- docs: the documentation site is now a VitePress site under `docs-site/`,
+  built from `docs/` and deployed to GitHub Pages by
+  `.github/workflows/docs.yml` at https://bulls-work.github.io/bullswarm/.
+  Guide (introduction, getting started, concepts, run, workflows, observing,
+  routing), Reference (CLI, workflow program, configuration, providers,
+  result envelope) and Integrations (Claude Code, Codex and Grok, issue
+  watcher) replace the Jekyll pages; the historical notes are indexed under
+  `/notes/`. `tests/unknown-flags.test.js` now checks every command form on
+  the new pages against the CLI.
+
 ## 0.30.0 — a run never waits: it finishes and hands back what is left
 
 - workflow: a run no longer waits for anyone. Every point where a

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

@@ -43,12 +43,53 @@ version in place (`bullswarm update --check` only reports). Requires Node.js
 22.12 or later. `bullswarm setup` walks through detecting your
 installed agent CLIs, showing their quota state, and writing a routing
 configuration. See
-[Getting started](https://cowcow02.github.io/bullswarm/guide/getting-started/)
+[Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started)
 for integrating Bullswarm's skill into Codex, Claude, and Grok, and for the
 full quick-start command list.
 
+## Claude Mod (early access)
+
+`mods/bullswarm` is the same routing injected into Claude Code's own engine
+as a Claude Mod (a plugin of TypeScript function hooks, behind
+`CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`): the pool meters drawn above the
+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).
+
+Three ways to load it:
+
+```bash
+# with the CLI: links the mod under ~/.claude/skills and sets the flag in ~/.claude/settings.json
+bullswarm integrate install --agents claude --yes
+
+# from Claude Code's plugin marketplace (a copy that `claude plugin update` refreshes)
+claude plugin marketplace add Bulls-Work/bullswarm
+claude plugin install bullswarm@bullswarm
+
+# one session only, from the installed package
+CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir "$(npm root -g)/bullswarm/mods/bullswarm"
+```
+
+The marketplace route still needs `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`, in
+the shell or under `env` in `~/.claude/settings.json`, and the `bullswarm`
+CLI on `PATH`. Pick one route: an installed marketplace copy takes precedence
+over the skills-dir link, and Claude says so at startup.
+
 ## Quick start
 
+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.
+
 One bounded outcome — a task with a clear finish line:
 
 ```bash
@@ -107,7 +148,7 @@ instead.
   and never retried early.
 
 The full mechanics behind each of these are in
-[Routing](https://cowcow02.github.io/bullswarm/guide/routing/).
+[Routing](https://bulls-work.github.io/bullswarm/guide/routing).
 
 ## What you get back
 
@@ -121,7 +162,7 @@ The full mechanics behind each of these are in
   content still verified; read it before re-running
 
 A non-zero exit from the delegate is never treated as success on its own. See
-[Doctrine](https://cowcow02.github.io/bullswarm/guide/doctrine/) for the full
+[Result envelope](https://bulls-work.github.io/bullswarm/reference/result) for the full
 verdict shape.
 
 A workflow produces a durable, versioned result envelope — a JSON document
@@ -137,29 +178,37 @@ bullswarm workflow runs result <shortId> --json --summary  # compact status once
 the exact flags to keep polling; `runs result --summary` is what to read once
 a run finishes, and `runs result --json` (no `--summary`) gives the full
 envelope for a failed or partial run. See
-[Operations](https://cowcow02.github.io/bullswarm/guide/operations/) for the
+[Observing runs](https://bulls-work.github.io/bullswarm/guide/observing) for the
 full shape of both.
 
 ## Documentation
 
 The full documentation is published at
-[cowcow02.github.io/bullswarm](https://cowcow02.github.io/bullswarm/) once
-GitHub Pages is enabled for this repository (Settings → Pages → deploy from
-branch `main`, folder `/docs`). Until then, the same pages are readable
-directly under [`docs/guide/`](docs/guide/) in this repository.
+[bulls-work.github.io/bullswarm](https://bulls-work.github.io/bullswarm/).
+
+The dashboard is the main screen after setup: bare `bullswarm` opens Home,
+`bullswarm --setup` or `bullswarm setup` opens setup, and
+`bullswarm workflow tui` is the explicit form. The [Observing runs](https://bulls-work.github.io/bullswarm/guide/observing)
+page maps its pages, keys, and mouse controls.
 
 | Page | What it covers |
 |---|---|
-| [Entry points](https://cowcow02.github.io/bullswarm/guide/entry-points/) | `run` vs `workflow goal`, and every top-level verb |
-| [Doctrine](https://cowcow02.github.io/bullswarm/guide/doctrine/) | The non-negotiable rules, and the result verdict shape |
-| [Getting started](https://cowcow02.github.io/bullswarm/guide/getting-started/) | Install, agent integration, quick-start commands |
-| [Strategy](https://cowcow02.github.io/bullswarm/guide/strategy/) | Model/provider configuration, rungs (model plus reasoning level per effort tier), benchmark evidence |
-| [Workflows](https://cowcow02.github.io/bullswarm/guide/workflows/) | Authoring a program, kinds, advisories, plan contract/validate/goal |
-| [Operations](https://cowcow02.github.io/bullswarm/guide/operations/) | Listing/inspecting runs, the result envelope, context diet |
-| [Dashboard](https://cowcow02.github.io/bullswarm/guide/dashboard/) | `workflow watch`, the interactive TUI, terminal glyph fallback |
-| [Repository operations](https://cowcow02.github.io/bullswarm/guide/repository-operations/) | The issue-watcher launchd agent |
-| [Routing](https://cowcow02.github.io/bullswarm/guide/routing/) | How a pool is picked: pace, headroom, urgency, load, quarantine |
-| [Providers](https://cowcow02.github.io/bullswarm/guide/providers/) | Adding your own agent CLI or reseller account as a provider plugin |
+| [Introduction](https://bulls-work.github.io/bullswarm/guide/) | What Bullswarm is, the two entry points, and the four rules it never breaks |
+| [Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started) | Install, `setup`, `doctor`, agent integration, and your first verified run |
+| [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 |
+| [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 |
+| [Configuration](https://bulls-work.github.io/bullswarm/reference/configuration) | The Bullswarm home, `state.json`, strategy models and rungs, environment variables |
+| [Providers](https://bulls-work.github.io/bullswarm/reference/providers) | Adding your own agent CLI or reseller account as a provider plugin |
+| [Result envelope](https://bulls-work.github.io/bullswarm/reference/result) | Every field of `run --json` and of the workflow result document |
+| [Claude Code](https://bulls-work.github.io/bullswarm/integrations/claude-code) | The packaged skill, the MCP server, and the read-only Claude Mod counterpart under `mods/bullswarm` |
+| [Codex and Grok](https://bulls-work.github.io/bullswarm/integrations/agent-clis) | What `bullswarm integrate` writes for each agent CLI, and how to check it |
+| [Issue watcher](https://bulls-work.github.io/bullswarm/integrations/issue-watcher) | The launchd agent that triages and fixes new GitHub issues |
+| [Historical notes](https://bulls-work.github.io/bullswarm/notes/) | Working notes, audits, and experiment writeups, kept as records |
 
 ## License