bullswarm 0.32.0 → 0.32.1

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # 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

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/docs/guide/routing.md

@@ -9,19 +9,20 @@ After this page you can predict which pool a task will go to, read the reason li
 
 ## The order decisions are made
 
-Routing runs the same five checks every time, in this order. Each one is a filter or a preference within the set that survived the one before it.
+Routing runs the same six checks every time, in this order. Each one is a filter or a preference within the set that survived the one before it.
 
-1. **Eligibility** — enabled, capable of the lane, not quarantined, not exhausted, and allowed a model for the effort tier.
+1. **Eligibility** — enabled, capable of the lane, not quarantined, not benched, not exhausted, and allowed a model for the effort tier.
 2. **Forecast gate** — a pool projected at or above 90% of its 5-hour window is pushed to the back.
 3. **5-hour headroom** — while any pool is below the near-limit line, only those are selectable.
-4. **Expiring-soon urgency** — while any pool's week or month is about to reset with quota left, only those are selectable.
-5. **Preference inside the survivors** — an explicit tier assignment, then incumbency, then the highest effective surplus.
+4. **Free models** — while any surviving pool's model for this effort tier costs nothing, only those are selectable.
+5. **Expiring-soon urgency** — while any pool's week or month is about to reset with quota left, only those are selectable.
+6. **Preference inside the survivors** — an explicit tier assignment, then incumbency, then the highest effective surplus.
 
-The rest of this page is those five steps in detail.
+The rest of this page is those six steps in detail.
 
 ## Eligibility
 
-A pool has to be enabled, declare the lane, hold any capabilities the work requires, not be quarantined, not be exhausted (100% of its window used), and have an allowed model for the effort tier. A disabled pool simply is not a candidate. Nothing in the later steps can rescue a pool that fails here.
+A pool has to be enabled, declare the lane, hold any capabilities the work requires, not be quarantined, not be soft-benched, not be exhausted (100% of its window used), and have an allowed model for the effort tier. A disabled pool simply is not a candidate. Nothing in the later steps can rescue a pool that fails here.
 
 ## Pace and surplus
 
@@ -31,13 +32,78 @@ Pace compares a pool with itself: **surplus = elapsed% − used%** of its own su
 
 The rolling 5-hour window never paces — it only gates. A pool whose forecast is at or above 75% (`FIVE_HOUR_NEAR_LIMIT_PCT`) **and** above the share of that window already elapsed is tiered down: it is picked only when no eligible pool below the line exists for the lane. A pool at or above 90% (`BURST_BLOCK_PCT`) is left out of selection entirely, and that gate ignores the clock.
 
+## Free models first
+
+A model that costs nothing does not spend anyone's quota, so a pool holding one is ranked ahead of every metered pool. While any eligible pool's model for this effort tier is free, the metered pools are not selectable at all — they are not merely outscored, so the pick is not a close call that a surplus swing can flip.
+
+Free-ness is a property of **(pool, effort tier)**, never of a pool: the same pool can hold a free model on `medium` and a paid one on `high`. It comes from the connector, which declares `"free": true` on the model profile that matches the selected model (`providers/*/connector.json`, `modelProfiles`); a discovered model whose name carries a standalone `free` segment — `openrouter/qwen:free` — counts as well.
+
+The rest of the order is untouched. Free sits *below* the forecast gate and the 5-hour headroom tier, so a free pool at or above its 5-hour line still loses to a pool with headroom. It sits *above* expiring-soon urgency, which is a deliberate trade: while free work is available, a metered pool's expiring quota can expire unspent. And the ranking **among** metered pools is exactly what it was — the free tier is a constant across all of them, so their relative order is still decided by the existing keys.
+
+The reason line says which rule applied, and names what it passed over:
+
+```text
+free pool first: opencode (free model opencode/union-alpha, 5h used 12.0%, 1 in flight) · metered pools ranked below free: codex 40.0, grok 12.3
+```
+
+## Soft bench: alive, but not producing
+
+A free endpoint does not fail the way a metered one does. It has no usage meter, so it can never read as exhausted — when its free window ends the API starts erroring or falling silent rather than reporting 100%. The soft bench is the backstop.
+
+Three failures count as a **strike** against a pool:
+
+- **stall** — the worker wrote no output for longer than its silence threshold and was stopped;
+- **provider** — the provider returned a server error;
+- **empty output** — a free pool returned literally nothing. (An answer that has substance but the verifier judged thin stays a semantic failure and is not retried elsewhere; that is a verdict about the answer, not about the pool.)
+
+Strikes are **consecutive**. The first one is recorded without taking the pool out of service. The second benches it for a 10-minute cooldown — the same re-probe window a quarantine uses — after which it returns automatically. The count survives that cooldown and is cleared only by a success, so a pool that stalls again straight after coming back is benched again immediately.
+
+A bench is not a quarantine, and it changes nothing about auth. An upstream auth failure still quarantines, still spreads across a credential group, and its deadline is never shortened by a bench. A benched pool also keeps having its meter read, because it is coming back in ten minutes.
+
+## Stall fallback
+
+The silence clock bounds silence, not run time: it restarts on every byte a worker writes. A metered pool keeps the one-hour default. A **free** pool is stopped after the median wall time its own recorded runs at that (pool, effort) rung actually took — the `p50` in `bullswarm strategy`, and only once at least 3 runs have been recorded there — with a floor of 5 minutes. Stalled attempts are excluded from that median, so a pool cannot tighten its own threshold by stalling. `BULLSWARM_WORKER_SILENCE_SEC` overrides it for a probe.
+
+When an attempt stalls, the run does not stop and the work is not lost:
+
+- the worker's process is ended and **whatever it had already written stays on disk** — the retry writes a new `out-<action>-attempt-<n>` file beside it, never over it;
+- the in-flight ledger entry is released, so the next pick sees the pool as idle;
+- the same action is re-dispatched on the next eligible pool **in the same run**, and its reason line is prefixed with where it came from;
+- the second consecutive stall benches the pool, so later actions in that run do not each wait out the threshold.
+
+`--retry-attempts` (default 1) caps mechanical retries for metered failures. A
+stall on a free pool (and its literally-empty-output provider reclassification)
+does not spend that allowance: the dispatcher advances through eligible pools,
+trying each pool at most once for the action, so the tried-set remains the
+termination bound. A stall on a metered pool keeps the mechanical accounting.
+
+```text
+fallback from opencode after stall 300s · most-behind capable pool (surplus 40)
+benched (stall, back at 2026-09-17T02:40:36.911Z): opencode
+```
+
+The run's events carry the same facts: `attempt.finished` gains `stalled`,
+`partialOutput`, `silentSec` and `willRetry`, and a `pool.benched` event names
+the pool, the reason, the strike count and the deadline. `bullswarm workflow
+watch` renders `retrying on another pool` only when `willRetry` is true;
+otherwise it says `no retry left`.
+
+## Evidence steps keep normal routing
+
+An evidence or acceptance step is never pushed onto the free pool: the free tier is switched off for it, and it routes on pace like any other action. It does get one preference — **a pool that wrote the work being judged is chosen last**. While any other eligible pool exists, the writer is not selected; when it is the only one left, it runs and the reason says so rather than failing the step.
+
+```text
+evidence step: normal routing (free tier not applied)
+evidence step: only the writer pool answerer is eligible
+```
+
 ## Expiring-soon urgency
 
-A pool whose pacing window resets within 24 hours (weekly) or 3 days (monthly) is ranked on urgency — its surplus divided by the fraction of the window still to run — instead of on the surplus alone. While any urgent pool can still spend its quota, it is the only one selectable, which is how a pool with two hours left beats a pool with three days left. A pool already forecast at or above 95% of its pacing window is `draining` and goes last.
+A pool whose pacing window resets within 24 hours (weekly) or 3 days (monthly) is ranked on urgency — its surplus divided by the fraction of the window still to run — instead of on the surplus alone. While any urgent pool can still spend its quota, it is the only one selectable, which is how a pool with two hours left beats a pool with three days left. A pool forecast at or above 95% of its pacing window *and* ahead of the window's own clock (forecast above the elapsed share) is `draining` and goes last; a pool at 96% with 98% of its month gone is spending at its own pace, not draining, and keeps its quota in play until the reset.
 
 ## In-flight load
 
-Work already dispatched is charged against a pool before the next pick: each pool's effective surplus is its pace minus what its in-flight agents are expected to spend, and minus at least 3 surplus points per agent when no measured rate exists. A busier pool therefore yields to a quieter one at similar pace. The floor is `config.inflightPenaltyPct` in `~/.bullswarm/state.json` (default 3; `0` turns it off).
+Work already dispatched is charged against a pool before the next pick: each pool's effective surplus is its pace minus what its in-flight agents and the candidate are expected to spend. When the pacing window has a measured rate, each timed in-flight record is charged at `rate × remaining minutes` with no floor. A pool with no measured rate uses the flat `config.inflightPenaltyPct` tie-breaker in `~/.bullswarm/state.json` (default 3; `0` turns it off); a measured pool uses that value only for an in-flight record whose remaining duration is unknown. A busier pool therefore yields to a quieter one at similar pace.
 
 ## Assignments and incumbency
 
@@ -57,7 +123,12 @@ A relayed credential fails upstream, not in the CLI. When a provider's event str
 
 ## How the decision shows its work
 
-`bullswarm pools` prints one line per pool: `cost=`, `lanes=`, the meter it is paced from, `surplus=`, `inflight=`, the 5-hour column as `5h=<reading>%-><projected>%` with `(<n>% elapsed)`, then `ready`, `disabled`, `QUARANTINED until …`, `NEAR-5H-LIMIT`, `BURST-GATED`, or `resets in … EXPIRING-SOON urgency=<n>`.
+`bullswarm pools` prints one line per pool: `cost=`, `lanes=`, the meter it is paced from, `surplus=`, `inflight=`, the 5-hour column as `5h=<reading>%-><projected>%` with `(<n>% elapsed)`, `free=<model>` when its model costs nothing, then `ready`, `disabled`, `QUARANTINED until …`, `BENCHED until … (<reason>, <n> strikes)`, `NEAR-5H-LIMIT`, `BURST-GATED`, or `resets in … EXPIRING-SOON urgency=<n>`. A pool carrying an uncounted-out strike prints `strikes=<n>(<reason>)` beside `ready`. `pools` names no lane and therefore no effort tier, so when free-ness differs per tier the column names each one — `free=medium:opencode/union-alpha`. A stale meter held after a failed poll is marked `[stale · <status-or-kind>, retry in <time>]`; `pools --json` carries the same `meterError` and `meterHoldUntil` fields.
+
+```text
+answerer       cost=3 lanes=analyze/build/chore unmetered surplus=0 inflight=0 ready
+opencode       cost=1 lanes=analyze/build/chore unmetered surplus=0 inflight=0 free=opencode/union-alpha BENCHED until 10:40:36 AM (stall, 2 strikes)
+```
 
 ```bash
 # every pool, with its meter, pace, load, and quarantine state
@@ -92,7 +163,7 @@ forecast: inflight=0 5h ?%->?% expected=5.67m rate=unmeasured basis=bootstrap
 
 Grok won because it was the only pool left: this `analyze` task resolves to the medium effort tier, whose allow-list names a model only on grok and codex, and codex is disabled — eligibility runs before any pace comparison, so the +35.6 on `claude-code:wati` never entered the race.
 
-When a pool is passed over, the reason says so in the same line — `skipped near 5h limit (projected): claude-code:wati 88.1% (92.3% elapsed)`, `forecast-gated at/above 90%: …`, `expiring but draining (forecast >= 95%): …`, or `preferred over busier: … (2 in flight)`.
+When a pool is passed over, the reason says so in the same line — `skipped near 5h limit (projected): claude-code:wati 88.1% (92.3% elapsed)`, `forecast-gated at/above 90%: …`, `expiring but draining (forecast >= 95% and past its clock): grok 99.5% (98.8% elapsed)`, or `preferred over busier: … (2 in flight)`.
 
 ## Next steps
 

package/docs/reference/cli.md

@@ -522,7 +522,7 @@ Record known subscription pricing for a pool so refresh's value-multiple math is
 ```bash
 # Record plan economics, then declare a refill date a wallet does not report.
 bullswarm strategy set-subscription claude --plan max --monthly-usd 200 --included-usd 1000
-bullswarm strategy set-subscription opencode2 --resets-at 2026-09-17T01:46:01Z
+bullswarm strategy set-subscription opencode --resets-at 2026-09-17T01:46:01Z
 ```
 
 | Flag | Meaning | Default |
@@ -619,7 +619,7 @@ Write a commented provider directory: a `provider.mjs` skeleton showing every ex
 
 ```bash
 # Scaffold a reseller that runs through OpenCode.
-bullswarm provider scaffold relay --from opencode2
+bullswarm provider scaffold relay --from opencode
 ```
 
 | Flag | Meaning | Default |
@@ -679,6 +679,8 @@ Without a program the command refuses (exit 2, nothing launched) unless `--scout
 
 Launches independently by default. `--resume <shortId|runId>` resumes a V2 run and is mutually exclusive with new goal text.
 
+A duplicate launch is refused before anything is validated or started: when an ongoing run in the same `--cwd` already has this goal text, the command exits 2 with that run's `shortId`, its age, and the command to watch it. `--json` prints `{"error":"duplicate-goal","shortId":…,"runId":…,"startedAt":…,"next":{"watch":…,"again":…}}`. Pass `--again` to start the second copy anyway.
+
 ```bash
 # Caller-planned launch that follows progress until terminal.
 bullswarm workflow goal "1. Fix src/parser.js. 2. Update docs." --cwd . --program plan.json --watch
@@ -711,6 +713,7 @@ bullswarm workflow goal "1. Fix src/parser.js. 2. Update docs." --cwd . --progra
 | `--retry-attempts <0..3>` | bounded retries for mechanical failures only; semantic evidence never auto-repairs | `1` |
 | `--resume <shortId\|runId>` | resume a V2 autonomous run; old autonomous runs fail closed before dispatch | starts a new goal |
 | `--detach` | rarely needed — explicitly requests the default independent-launch behavior; cannot combine with `--watch` | the default launch already detaches |
+| `--again` | start another copy even when an ongoing run already has the same goal text in the same `--cwd`; only a new launch is checked, never `--resume` or the internal `--request` relaunch | off (a duplicate of an ongoing goal is refused) |
 
 Workers keep their edits even when their action fails. Failed dependencies skip downstream actions and independent branches finish. Saved V2 runs keep their original completion and isolation policy when resumed.
 

package/docs/reference/configuration.md

@@ -116,7 +116,7 @@ A provider is a directory with `connector.json` and/or `provider.mjs`. Three tie
 
 ```bash
 # Write a local provider directory (default ~/.bullswarm/providers/<name>/).
-bullswarm provider scaffold relay --from opencode2
+bullswarm provider scaffold relay --from opencode
 bullswarm provider validate relay
 bullswarm provider probe relay
 ```

package/docs/reference/providers.md

@@ -16,7 +16,7 @@ A provider is a directory holding a `connector.json`, a `provider.mjs`, or both.
 | Tier | Directory | Loaded when | Members |
 |---|---|---|---|
 | first-class | `src/providers/<name>/` | always | `claude-code`, `codex`, `grok`, `echo` |
-| contrib | `providers/contrib/<name>/` | listed in `~/.bullswarm/providers.json` | `command-code`, `opencode2` |
+| contrib | `providers/contrib/<name>/` | listed in `~/.bullswarm/providers.json` | `command-code`, `opencode` |
 | local | `~/.bullswarm/providers/<name>/` | always | your own, never in the repository |
 
 First-class and contrib providers ship in the package. A contrib provider loads only on a machine that lists it:
@@ -80,7 +80,7 @@ Every method receives the same `ctx`:
 
 `readUsage` also receives `subscription`: the pool's entry in `state.strategy.subscriptions`, or `null`. It carries `includedValueUsd`, `quotaWindow`, `resetsAt`, `plan`, and `monthlyPriceUsd`.
 
-`templates` exists so a provider can build on a shipped CLI without copying its template: a reseller of OpenCode access clones `templates.opencode2`.
+`templates` exists so a provider can build on a shipped CLI without copying its template: a reseller of OpenCode access clones `templates.opencode`.
 
 ## The kit
 
@@ -143,7 +143,7 @@ These are all the pool fields a provider may set, and the part of the core that
 
 ## Example: a reseller named relay
 
-Relay sells OpenCode access through two accounts. The provider clones the shipped `opencode2` template once per account, pins each account's model and reasoning variants, groups both under one credential so a usage limit on one benches its sibling, and reports spend from a wallet:
+Relay sells OpenCode access through two accounts. The provider clones the shipped `opencode` template once per account, pins each account's model and reasoning variants, groups both under one credential so a usage limit on one benches its sibling, and reports spend from a wallet:
 
 ```js
 // ~/.bullswarm/providers/relay/provider.mjs
@@ -152,7 +152,7 @@ export const displayName = 'Relay';
 
 export function connectors({ kit, templates }) {
   const accounts = [{ id: 'a', models: ['gpt-5.6-sol'] }, { id: 'b', models: ['gpt-5.6-sol'] }];
-  return accounts.map((acc, i) => kit.clonePool(templates.opencode2, {
+  return accounts.map((acc, i) => kit.clonePool(templates.opencode, {
     name: i === 0 ? 'relay' : `relay:${acc.id}`,
     model: `${acc.id}/gpt-5.6-sol`,
     env: { OPENCODE_CONFIG_CONTENT: kit.opencodeVariants(acc.id, acc.models) },
@@ -187,7 +187,7 @@ The `usedUsd = 12.5` line is a placeholder: a real `readUsage` fetches the walle
 
 ```bash
 # Author a local provider from a shipped template, then check shape and spawn.
-bullswarm provider scaffold relay --from opencode2
+bullswarm provider scaffold relay --from opencode
 bullswarm provider validate relay
 bullswarm provider probe relay --json
 ```

package/docs/workflow-design.md

@@ -175,7 +175,7 @@ bullswarm workflow · route-review · run wf-a1b2c3
 ▐ phase 2/2 · review                                      ⏳ running
   ⟡ per-file-review[0/47]       grok         31.0s   … verifying
   ✓ per-file-review[1/47]       command-code 28.9s   ok
-  ✗ per-file-review[2/47]       opencode2    40.1s   fail · announcement without substance
+  ✗ per-file-review[2/47]       opencode    40.1s   fail · announcement without substance
     ↳ escalate → codex
   ⋈ per-file-review[3/47]       —            —       quarantined pool, waiting
 

package/mods/bullswarm/hooks/pane.tsx

@@ -69,6 +69,25 @@ export type PaneActions = {
   close: () => void
 }
 
+/** The single-row Usage header, including the oldest failed meter reason. */
+export function poolsHeaderText(
+  pools: readonly BullswarmPool[],
+  nowMs: number,
+  nameOf: (pool: string | null) => string = pool => pool ?? '',
+): string {
+  const sampled = pools
+    .filter(p => !!p.capturedAt)
+    .sort((a, b) => Date.parse(a.capturedAt!) - Date.parse(b.capturedAt!))
+  const oldest = sampled[0] ?? null
+  const oldestError = sampled.find(p => !!p.meterError) ?? null
+  const shown = oldestError ?? oldest
+  if (!shown) return 'Pools · no meter snapshot yet'
+  const age = ageOf(shown.capturedAt, nowMs) || '0m'
+  return oldestError
+    ? `Pools · ${nameOf(shown.name)} sampled ${age} ago · ${oldestError.meterError}`
+    : `Pools · sampled ${age} ago`
+}
+
 /** Below this many body rows the pane draws its compact layout (a phone terminal, a short inline pane). */
 export const COMPACT_ROWS = 20
 /** Blank rows drawn past the footer so the engine reports the pane's true height. */
@@ -253,13 +272,12 @@ export function paneView(
   const blank = (key: string) => <Text key={key}> </Text>
 
   if (model.poolsPage) {
-    const sampled = model.pools.map(p => p.capturedAt).filter((x): x is string => !!x).sort()[0] ?? null
     const header: RenderElement[] = [
       <Text key="h0" wrap="truncate-end">
         <Text bold color="cyan">
           Pools
         </Text>
-        <Text dimColor>{sampled ? ` · sampled ${ageOf(sampled, model.nowMs) || '0m'} ago` : ' · no meter snapshot yet'}</Text>
+        <Text dimColor>{poolsHeaderText(model.pools, model.nowMs, nameOf).slice('Pools'.length)}</Text>
       </Text>,
     ]
     if (!compact) header.push(nav)

package/mods/bullswarm/hooks/pools.ts

@@ -33,6 +33,8 @@ export function parsePools(stdout: string): BullswarmPool[] {
         fiveHourUsedPct: num(p.fiveHourUsedPct),
         costRank: num(p.costRank),
         meterSource: str(p.meterSource),
+        meterError: str(p.meterError),
+        meterHoldUntil: num(p.meterHoldUntil),
         incumbentLane: Array.isArray(p.incumbentLane)
           ? p.incumbentLane.filter((l): l is string => typeof l === 'string')
           : [],

package/mods/bullswarm/types/index.d.ts

@@ -166,6 +166,10 @@ export type BullswarmPool = {
   fiveHourUsedPct: number | null
   costRank: number | null
   meterSource: string | null
+  /** A short provider error reason while a stale meter is held. */
+  meterError: string | null
+  /** Epoch milliseconds at which a stale-meter hold may be retried. */
+  meterHoldUntil: number | null
   incumbentLane: readonly string[]
   quarantine: { until: number; reason: string; kind: string } | null
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.32.0",
+  "version": "0.32.1",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/providers/contrib/README.md

@@ -7,7 +7,7 @@ Bullswarm loads one only when your machine opts in. The providers under
 | provider | what it runs | meter |
 |---|---|---|
 | `command-code` | the Command Code CLI (`command-code -p`) | monthly credits, 5-hour and weekly windows from the Command Code billing API |
-| `opencode2` | the OpenCode CLI (`opencode run`) | none; also the template reseller providers clone as `ctx.templates.opencode2` |
+| `opencode` | the OpenCode CLI (`opencode run`) | none; also the template reseller providers clone as `ctx.templates.opencode` |
 
 ## Enabling one
 

package/providers/contrib/command-code/provider.mjs

@@ -8,6 +8,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { MeterError } from '../../../src/provider-kit.js';
+import { retryAfterMsFromHeaders } from '../../../src/meters/framework.js';
 
 export const name = 'command-code';
 export const displayName = 'Command Code';
@@ -39,8 +40,8 @@ const PLAN_CREDITS = {
 };
 
 export class CommandCodeMeterError extends MeterError {
-  constructor(message, code) {
-    super(message, code); // no_auth | http | parse | network
+  constructor(message, code, options = {}) {
+    super(message, code, options); // no_auth | http | parse | network
     this.name = 'CommandCodeMeterError';
   }
 }
@@ -176,13 +177,14 @@ async function fetchJson(url, key) {
   } catch (err) {
     throw new CommandCodeMeterError(`Network error reaching Command Code billing: ${err.message}`, 'network');
   }
+  const retryAfterMs = retryAfterMsFromHeaders(res.headers);
   let body = null;
   try {
     body = await res.json();
   } catch {
     /* leave null */
   }
-  return { status: res.status, body };
+  return { status: res.status, body, retryAfterMs };
 }
 
 /**
@@ -197,10 +199,16 @@ export async function readUsage(pool = name, ctx = {}) {
 
   const creditsRes = await fetchJson(`${base}${CREDITS_PATH}`, key);
   if (creditsRes.status === 401 || creditsRes.status === 403) {
-    throw new CommandCodeMeterError(`Command Code credits HTTP ${creditsRes.status}`, 'no_auth');
+    throw new CommandCodeMeterError(`Command Code credits HTTP ${creditsRes.status}`, 'no_auth', {
+      status: creditsRes.status,
+      retryAfterMs: creditsRes.retryAfterMs,
+    });
   }
   if (creditsRes.status < 200 || creditsRes.status >= 300) {
-    throw new CommandCodeMeterError(`Command Code credits HTTP ${creditsRes.status}`, 'http');
+    throw new CommandCodeMeterError(`Command Code credits HTTP ${creditsRes.status}`, 'http', {
+      status: creditsRes.status,
+      retryAfterMs: creditsRes.retryAfterMs,
+    });
   }
 
   const credits = parseCommandCodeCredits(creditsRes.body);

package/providers/contrib/{opencode2 → opencode}/connector.json

@@ -1,5 +1,5 @@
 {
-  "name": "opencode2",
+  "name": "opencode",
   "bin": "opencode",
   "configDirs": ["~/.config/opencode"],
   "spawn": {
@@ -46,6 +46,7 @@
     { "match": "gpt-5\\.6-sol$", "tier": "high", "qualityRank": 6, "autoRecommend": true },
     { "match": "(?:opus|gpt-5\\.5$)", "tier": "high", "qualityRank": 5 },
     { "match": "(?:sonnet|terra|gpt-5\\.4$|deepseek-v4)", "tier": "medium", "qualityRank": 4 },
+    { "match": "(?:union-alpha|-free$)", "tier": "medium", "qualityRank": 3, "free": true },
     { "match": "(?:haiku|luna|(?:^|[/.-])mini(?:$|[/.-])|flash|free)", "tier": "low", "qualityRank": 2 }
   ],
   "subscription": { "plan": null, "monthlyPriceUsd": null, "includedValueUsd": null, "quotaWindow": null },

package/providers/contrib/{opencode2 → opencode}/provider.mjs

@@ -1,7 +1,7 @@
-// bullswarm contrib provider: opencode2 — the generic OpenCode CLI pool.
+// bullswarm contrib provider: opencode — the generic OpenCode CLI pool.
 // connector.json is the whole pool; there is no meter. It is also the
-// template a reseller provider clones through `ctx.templates.opencode2`
+// template a reseller provider clones through `ctx.templates.opencode`
 // (see docs/reference/providers.md).
 
-export const name = 'opencode2';
+export const name = 'opencode';
 export const displayName = 'OpenCode';

package/skill/references/providers.md

@@ -40,7 +40,7 @@ second login), skip most of this: clone the shipped template.
 
 ```bash
 bullswarm provider scaffold <name>
-bullswarm provider scaffold <name> --from opencode2
+bullswarm provider scaffold <name> --from opencode
 ```
 
 This writes a commented `provider.mjs` with every export. `--from` copies

package/src/cli.js

@@ -4,15 +4,15 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from
 import { join, resolve } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import {
-  expiringSoonView, fiveHourElapsedPct, formatResetsIn, pickPool,
+  expiringSoonView, fiveHourElapsedPct, formatResetsIn, isBenched, pickPool,
 } from './lib/route.js';
 import { argvWithModel, watchOnce } from './lib/watch.js';
 import {
   isReasoningLevel, REASONING_DEFAULT, REASONING_LEVELS, resolveReasoningLevel,
 } from './lib/reasoning.js';
 import {
-  loadState, quarantinePool, quarantineUpstreamSiblings, sweepQuarantines, updateState,
-  assertDepthAllowed, childDepthEnv, upstreamGroupOf,
+  loadState, quarantinePool, quarantineUpstreamSiblings, sweepBenches, sweepQuarantines,
+  updateState, assertDepthAllowed, childDepthEnv, upstreamGroupOf,
 } from './lib/state.js';
 import { buildPools, buildPoolsLive } from './lib/config.js';
 import { getAllMeterReadings } from './meters/registry.js';
@@ -73,6 +73,23 @@ export function parseArgs(argv) {
 
 // --- pools ----------------------------------------------------------------
 
+/** The bracketed meter source shown by `bullswarm pools`. */
+export function meterSourceLabel(pool, nowMs = Date.now()) {
+  const source = pool?.meterSource ?? 'none';
+  if (source === 'stale' && pool?.meterError) {
+    const holdUntil = Number(pool.meterHoldUntil);
+    const remainingMs = holdUntil - nowMs;
+    const retry = Number.isFinite(remainingMs) && remainingMs > 0
+      ? `, retry in ${remainingMs < 60_000
+        ? `${Math.ceil(remainingMs / 1000)}s`
+        : `${Math.ceil(remainingMs / 60_000)}m`}`
+      : '';
+    return `stale · ${pool.meterError}${retry}`;
+  }
+  const resetTag = pool?.resetSource === 'declared' ? ' declared-reset' : '';
+  return `${source}${resetTag}`;
+}
+
 async function cmdPools(opts) {
   const now = Date.now();
   const { state, pools } = await buildPoolsLive(getBullswarmDir(), now, {
@@ -84,13 +101,26 @@ async function cmdPools(opts) {
   // persists when it actually released something: `pools` is an observation
   // command and must not rewrite state.json just for being run.
   let released = [];
+  let unbenched = [];
   updateState(getBullswarmDir(), (fresh) => {
     released = sweepQuarantines(fresh, now);
-    return released.length > 0;
+    // A soft bench expires on the same terms and by the same rule (S6): the
+    // cooldown passing returns the pool to service, and the strike count stays
+    // so a stall immediately afterwards is still its second in a row.
+    unbenched = sweepBenches(fresh, now);
+    return released.length > 0 || unbenched.length > 0;
   });
   if (released.length && !opts.json) {
     console.error(`quarantine expired, returned to service: ${released.join(', ')}`);
   }
+  if (unbenched.length && !opts.json) {
+    console.error(`bench expired, returned to service: ${unbenched.join(', ')}`);
+  }
+  // The sweep above wrote to state, not to the pool views built before it, so
+  // an expired bench would still print as BENCHED. Re-read what the sweep left.
+  for (const p of pools) {
+    if (p.bench && !isBenched(p, now)) p.bench = { ...p.bench, until: null };
+  }
   // Current cross-process load, from the shared ledger rather than this
   // process's own memory: work another Bullswarm started still shows here —
   // plus the spend rates that turn that load into a projected utilization.
@@ -108,10 +138,9 @@ async function cmdPools(opts) {
     const window = p.pacingWindow && p.elapsedPct != null ? `${p.pacingWindow} ` : '';
     // A window whose end the operator declared (the provider reported none)
     // is paced from that date and says so; the used% is still the provider's.
-    const resetTag = p.resetSource === 'declared' ? ' declared-reset' : '';
     const meter = src === 'none'
       ? 'unmetered'
-      : `${window}used ${p.usedPct ?? '?'}% elapsed ${p.elapsedPct ?? '?'}% [${src}${resetTag}]`;
+      : `${window}used ${p.usedPct ?? '?'}% elapsed ${p.elapsedPct ?? '?'}% [${meterSourceLabel(p, now)}]`;
     const burst = p.burstGate ? ' BURST-GATED' : '';
     // 5h is a gate, never a pace (doctrine M3): show the reading and whether
     // routing now deprioritizes this pool for it. When in-flight work makes
@@ -137,13 +166,32 @@ async function cmdPools(opts) {
       ? ` resets in ${formatResetsIn(expiring.minutesToReset)} EXPIRING-SOON`
         + ` urgency=${Math.round(expiring.urgency)}`
       : '';
+    // R12: the model this pool would run costs nothing, so routing puts it
+    // ahead of every metered pool while it is healthy. `pools` names no lane
+    // and therefore no effort tier, and free-ness is per tier — so the tiers
+    // that hold a free model are named one by one rather than collapsed into a
+    // single claim that would be untrue on the others.
+    const freeTiers = Object.entries(p.freeTiers ?? {});
+    const free = p.free === true
+      ? ` free=${p.freeModel ?? '?'}`
+      : freeTiers.length
+        ? ` free=${freeTiers.map(([tier, model]) => `${tier}:${model}`).join(',')}`
+        : '';
+    // A soft bench (S6) is not a quarantine: the pool is alive but was not
+    // producing. A first strike is counted without taking it out, so say that
+    // too — otherwise a pool one stall from the bench looks perfectly healthy.
+    const strikes = p.bench && !isBenched(p, now) && Number(p.bench.count ?? 0) > 0
+      ? ` strikes=${p.bench.count}(${p.bench.reason ?? '?'})`
+      : '';
     const status = !p.enabled
       ? 'disabled'
       : p.quarantine
         ? `QUARANTINED until ${new Date(p.quarantine.until).toLocaleTimeString()} (${p.quarantine.reason})`
-        : `ready${burst}${nearLimit}`;
+        : isBenched(p, now)
+          ? `BENCHED until ${new Date(Number(p.bench.until)).toLocaleTimeString()} (${p.bench.reason ?? '?'}, ${p.bench.count ?? '?'} strikes)`
+          : `ready${burst}${nearLimit}${strikes}`;
     console.log(
-      `${p.name.padEnd(14)} cost=${p.costRank} lanes=${p.lanes.join('/')} ${meter} surplus=${p.pace ?? '-'} inflight=${p.inflight?.count ?? 0}${fiveHour} ${status}${expiringNote}`,
+      `${p.name.padEnd(14)} cost=${p.costRank} lanes=${p.lanes.join('/')} ${meter} surplus=${p.pace ?? '-'} inflight=${p.inflight?.count ?? 0}${fiveHour}${free} ${status}${expiringNote}`,
     );
   }
   return 0;