bullswarm 0.35.6 → 0.36.0

package/AGENTS.md

@@ -8,31 +8,86 @@ A CLI that routes bounded tasks to whichever coding-agent CLI subscription
 has the most quota headroom, paced by live provider meters, verified by
 content. Published as `bullswarm` on npm.
 
+## Redesign in progress (2026-09)
+
+The core is being redesigned around facts-only mechanics, four mandatory
+principles, caller-chosen options and a pattern library, for any kind of work
+rather than code only. The design, the decisions taken and the staged build
+plan are in `docs/design/redesign-mechanics-principles-options.md`, and draft
+pattern cards are in `docs/design/patterns/`. Build in the plan's stage order.
+The doctrine below stays in force until the stage that changes an item lands.
+The redesign rewords items 1, 5, 6 and 7, and each stage updates this file.
+Stage 1 (step vocabulary) has landed: program-mode steps may state a role and a
+deliverable, each kind belongs to one role and keeps its exact routing, and
+the no-op gate is now 'declared deliverable not produced' (failure kind
+`not-produced`), measured over the whole step. Stage 2 (evidence v1) has landed:
+program steps may declare command and schema `evidence` that the kernel runs
+after the worker, a failure is `failed-evidence` with one same-pool retry, and
+finished steps in new runs are labelled `proven by …` or `finished · unproven`.
+Stage 3 (failure rule and routing constraints) has landed: one automatic retry
+per step, then the caller; a usage limit goes straight to the caller, from a
+step, the dispatched planner or the preflight scout alike; the
+needs-you block with `step rerun --avoid` and `step accept`; the per-step
+`route`; `verifyRounds` counts fixes (default 1); reviews are placed only by
+route. Runs started earlier keep their rules (`features.json`).
+
 ## Non-negotiable doctrine
 
-1. Judge delegate output by CONTENT, not exit code (see `src/lib/verify.js`).
+1. Judge delegate output by what can be checked, never by the delegate's exit code or its own report: the content (`src/lib/verify.js`) and, when a step declares them, the command and schema evidence Bullswarm runs itself (`src/workflow/evidence-runner.js`).
 2. Pace by meter surplus = elapsed% (from provider resets_at) − used%.
    Weekly/monthly windows pace; 5h windows are burst gates only (M1–M5 in
-   `src/meters/framework.js`).
+   `src/meters/framework.js`). Any metered window at 100% (5h, weekly or
+   monthly) keeps its pool out of every pick until that window resets.
 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/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:
-   `BULLSWARM_DEPTH` is propagated, burst-gated pools are excluded, and
-   auth verdicts quarantine the pool + append to the shared decision log
-   (R6/R7/R8 in `src/workflow/v2-dispatch.js`).
-6. Adversarial verification is a first-class primitive: an action naming
-   requirements in `evidenceFor` is dispatched under an evidence contract and
-   judges them from the durable artifact, so a requirement is only verified by
-   work someone else inspected (R-skeptic).
+4. A spent or dead pool is never remembered across steps: nothing pauses or
+   benches a pool, and every pick reads the live meters. The one fact that
+   outlives a step is the 100% refusal marker a usage limit writes when the
+   meter cannot be read, and it counts only when its reset was named or
+   measured, never guessed (`refusalResetKnown` in `src/meters/framework.js`).
+   Recursion depth is core-owned via env (`BULLSWARM_DEPTH`).
+5. Workflow dispatches honor the same guarantees as single runs, in
+   `src/workflow/v2-dispatch.js`: `BULLSWARM_DEPTH` is checked and propagated
+   (`assertDepthAllowed` and `childDepthEnv` in `dispatchV2Action`), pools at
+   a spent window are excluded (`preparePools`), and a sign-in failure is
+   failure kind `auth`: the step's retry skips every pool in the dead
+   credential's group (`upstreamGroupOf`), a choice held for that dispatch
+   only and never stored. A step's `route`, the run's pin and the step's
+   capability tier are hard filters applied before pace ranks what is left. The failure rule is one automatic retry per step (a
+   process failure on another eligible pool, a gate failure on the same pool
+   with the failure attached), then the caller. An `act` step is never retried
+   once its worker started. A usage limit (a spent 5-hour or weekly window, or
+   no credit left) ends the step and sends it to the caller: no wait, no
+   automatic move, no retry. The pool's meter is re-read after it
+   (when that read fails, the refusal marker counts the pool as full only until
+   a reset the provider named or a reading measured, never a guessed one), so
+   a window at 100% keeps that pool out of later steps. Finding no capable pool
+   free at the pick sends the step to the caller too. Nothing waits for a
+   pool inside a run; only a transient rate limit backs off on the same pool,
+   at most twice (20 s, then 60 s, or a named wait of at most 2 minutes), then
+   goes to the caller.
+   Only a failed step's dependents wait. The dispatched planner and the
+   preflight scout follow the same usage-limit rule (`usageLimitsToCaller` in
+   `dispatchV2Action`): they stop and the run tells the caller, with no
+   automatic move to another pool.
+6. Review is a caller option, recorded as a fact. A step naming requirements
+   in `evidenceFor` is dispatched under the evidence contract and judges them
+   from the durable artifact. Where it runs is the caller's choice through
+   `route` (`independentOf`, `providers`, `pools`); Bullswarm never moves a
+   review on its own, and records who reviewed (pool, model, provider) and
+   whether that provider also wrote the work. A caller's `step accept` is
+   recorded as evidence `choice` and never makes a requirement verified.
+   Runs started before this rule keep automatic writer avoidance (R12/R13).
 7. New goal workflows are caller-planned programs in a shared workspace.
    `bullswarm workflow goal --program` executes the graph; `--orchestrator`
    explicitly delegates planning. File territories are advisory scheduling
-   hints, and the graph finishes without automatic gap rounds. `verified`
-   separately records requirement evidence. `--isolation` opts into strict
-   per-worker worktrees. Saved V2 runs preserve their original semantics.
+   hints. A failed check gets one fix step and one re-review
+   (`defaults.verifyRounds`, default 1, 0-3), then the caller, who takes over
+   through the watcher's needs-you block: rerun elsewhere, change the step,
+   take over, or accept anyway. `verified` separately records requirement
+   evidence. `--isolation` opts into strict per-worker worktrees. Saved V2
+   runs preserve their original semantics (`features.json`).
 8. Historical authored-graph runs remain visible as read-only `legacy` rows.
    Their executor was removed in 0.27.0; driving commands fail closed before
    dispatch and historical run directories remain untouched.

package/CHANGELOG.md

@@ -2,6 +2,316 @@
 
 ## Unreleased
 
+## 0.36.0 — Usage limits go back to the caller; each account bills itself
+
+- known issues in this release: a limit marker whose reset was guessed still
+  counts as a 100% reading in the spend forecast, so it can rank a pool lower
+  for up to 5 hours (it never keeps the pool out); the Claude Code mod's pool
+  panes still read the removed pausing fields, so a pool held by a usage limit
+  can show as ready there; the preflight scout and the dispatched planner can
+  make up to three attempts (a correction plus a retry); `strategy
+  set-pausing` exits 2 with the general usage text instead of naming the
+  removed command.
+- workflow: every step gets one automatic retry, then comes back to you. A
+  crashed, silent or signed-out worker is retried once on another pool that can
+  run the step (the same pool when it is the only one, except after a sign-in
+  failure). A failed gate (declared evidence, a deliverable not produced, a
+  report in the wrong format, or output judged failed) is retried once on the
+  same pool with the failure attached. A usage limit is never retried, moved or
+  waited out: the step comes back to you (see below). An `act` step (one that
+  changes the outside world) is never retried automatically once its worker has
+  started. Steps that do not depend on a failed step keep running.
+  `--retry-attempts` (0-3, default 1) sets the retries per step. Runs started
+  before this version keep their old retry rules when resumed.
+- workflow: when a step needs you, `watch` prints one block: what failed, each
+  try, what is still running and what waits on it, and four commands (rerun
+  elsewhere, change the step, take over, accept anyway). Two commands are new.
+  `bullswarm workflow step rerun <run> <step> --avoid <pool>` runs a step again
+  off the pools you name, with its last attempt's handoff; the pools stay in the
+  step's route. `bullswarm workflow step accept <run> <step> --reason "…"`
+  accepts a failed step, or a check's failing requirements, as your choice: its
+  dependents run, the step reads `accepted by choice`, the record says "choice"
+  and never counts as proof (the end-of-run proof line counts it apart from
+  proven steps), and rerunning the step undoes it. A run that ends with a
+  failed step, or with a requirement its review loop left failing, lists
+  `rerun` and `accept` under `your call:`; for a requirement they name the
+  check that judged it (`--avoid <pool>`, `--requirement <id>`).
+- workflow: a usage limit, or no pool free, sends the step back to you; a step
+  never waits for a pool. A spent usage window (5-hour, weekly or monthly), or
+  no credit left, ends the step at once: no wait, no move to another pool, no
+  retry, even for a limit notice that names no reset. The pool's meter is
+  then read again at once (when it cannot be read, the pool counts as full
+  until its reset only when the provider named that reset or an earlier meter
+  reading gave it), so a window it shows at 100% keeps the pool out of later
+  steps until that window resets; a single `bullswarm run` does the same.
+  When every pool that can run the step is nearly spent, or at a 5-hour,
+  weekly or monthly limit, the step stops as well (`no pool with quota to
+  spare: <pool> at its 5-hour limit until …`, `<pool> nearly spent (forecast
+  …%) until …`, or `no pool free: …`; a pool at its 5-hour limit no longer
+  reads as "no enabled pool has a model on the tier"); when another pool is
+  free, it takes the step as usual. A
+  retry the step was promised that finds no free pool keeps its own failure
+  and says why (`· no retry: <pool> <reason>; …`). The rest of the run keeps
+  going. When a return time is known, the needs-you block shows `back at
+  <time>` (the failed pool's reset, the end of a rate limit's named wait, or
+  the earliest known return of the pools that can run the step) and a `wait
+  for it` command (`after <time>: bullswarm workflow step rerun <run>
+  <step>`); with `--jsonl` they are `backAt` and `options.waitForIt`. The
+  watch's usage-limit line ends `back to you`. A short "too many requests"
+  rate limit still backs off on the same pool, at most twice (20 s, then 60 s,
+  or the wait it names when that is at most 2 minutes), before the step comes
+  back to you; a try after one reads `· after a rate-limit backoff`, and the
+  block's header says `backed off twice` (never `not retried`: a backoff is
+  not the step's retry). One that names a longer wait comes back to you at
+  once, and so does one whose pool runs out during the backoff. Runs started
+  before this version keep their old rules.
+- pools: Bullswarm no longer pauses or benches a pool, and never remembers a
+  spent or dead pool from one step to the next. `bullswarm strategy
+  set-pausing`, `bullswarm pools resume`, and the `PAUSED`, `BENCHED`,
+  `strikes=` and `automatic pausing: off` lines in `bullswarm pools` are gone;
+  a pause or bench record an earlier version left in `state.json` is ignored.
+  What replaces them: every pick reads the live meters, so a window at 100%
+  (5-hour, weekly or monthly) keeps a pool out until that window resets, and
+  nothing else does. A usage limit goes back to the caller, and the pool's
+  meter is read again at once; when it cannot be read, the pool counts as full
+  only until a reset the provider named or an earlier reading gave, and a
+  reset nobody knows keeps no pool out (the meter column then reads
+  `[refused <age> · reset unknown]`; such a reset used to be guessed as a
+  whole window from the refusal, which could keep a pool with no meter reader
+  out for up to a week, or a month). After a sign-in failure the step's one
+  automatic retry goes to a pool that does not share the dead credential; the
+  next step routes as usual. A stall, a provider error or a failed free-model
+  probe no longer counts a strike: the step's retry, or the pick, goes to
+  another pool. Before, a proven usage limit paused the pool until its reset,
+  a sign-in failure paused the pool and every pool sharing its credential for
+  10 minutes, and a second stall or failure in a row benched a pool for 10
+  minutes, until the pause ran out, `pools resume` lifted it or `set-pausing
+  off` turned pausing off. For scripts: `pools --json` drops `pausing`,
+  `quarantine` and `pauseWhy`; a `run --json` verdict drops `quarantineHint`,
+  `quarantineUntil`, `quarantineSource`, `quarantinedUntil` and
+  `quarantinedSiblings`, names its limit decision `usageLimit` (it was
+  `quotaPause`), and carries `retryAfter` when a usage limit's reset is
+  known; a run no longer writes `pool.benched` events, and `workflow watch`
+  skips one a saved run holds, prints no `paused until` or `not paused` on
+  its usage-limit line, and with `--jsonl` drops `paused` and `proof` from
+  `attempt.quota`; `bullswarm health` no longer reports paused pools
+  (`quarantined`, `quarantineCluster`) or exits 1 for them; and neither
+  `pools` nor `health` changes `state.json` any more.
+- workflow: the dispatched Workflow Planner (`--orchestrator`) and the
+  preflight scout (`--scout`, or the scout before a dispatched planner) follow
+  the same rule. A usage limit, a rate limit still there after its short
+  backoff, or no free pool stops it and tells you; it no longer moves to
+  another pool by itself. The run finishes `partial` with `the workflow
+  planner stopped on a usage limit: <why> · back at <time> · your call: resume
+  after <time> with bullswarm workflow resume <run>, plan it yourself with
+  bullswarm workflow plan revise <run> --program <file.json>, or start a new
+  run` (`stopped: no pool free` when a pool was out for another reason or no
+  pool can run it at all), and `planner.finished` and
+  `preflight.scout_finished` carry `retryAfter` (the scout's also
+  `runContinues`: whether the run goes on without its report). The watch
+  prints the planner's stop as `✗ planner stopped · out of quota on <pool> ·
+  back at <time>` (it used to read `× planning attempt rejected · …`). A scout
+  with no program after it ends the run the same way (`the preflight scout
+  stopped on a usage limit: …`). A scout before your own program lets the run
+  go on without its report, and the watch prints `⚠ preflight scout stopped ·
+  out of quota on <pool> · back at <time> · the run continues without its
+  report`. `--until trouble` wakes on either stop. The Run page's timeline has
+  a row for either stop: `[Workflow Planner] planner stopped · <label> on
+  <pool> · back at <time>` or `Scout stopped · <label> on <pool> · back at
+  <time>` (ending `· the run continues without its report` when the run goes
+  on without it), where `<label>` is `out of quota`, `rate limited` or `no
+  eligible pool`, as in the watch. A sign-in failure, a provider error or a worker that
+  died at start still moves the planner or the scout to another pool.
+  `bullswarm run` still stops after its one attempt on a usage limit. Runs
+  started before this version keep their old rules.
+- workflow: when a usage limit or no free pool stopped the planner or scout
+  and ended the run, `workflow resume <run>` runs it again, and the run goes
+  on from there. Run it after the `back at` time in the stop reason; it
+  prints `✓ reopened the partial run <run>; running again: the workflow
+  planner` (or `the preflight scout`). Before that time it can stop the same
+  way, and it adds `note: the workflow planner stopped with its pool back at
+  <time>; run before then, it can fail the same way again`. When no return
+  time is known, the reason says `bullswarm workflow resume <run> once a pool
+  is free`. The result's `retry` option names it too (`bullswarm workflow
+  resume <run> after <time> (reruns the workflow planner)`). `plan revise`
+  with your own program and a new run stay the other choices. A scout the run
+  went on without (one before your own program) is not run again. Any run that
+  `workflow resume` reopens now reads `run reopened from <status> by workflow
+  resume` in the watch; it used to say `by a plan revision` whichever command
+  reopened the run.
+- workflow: a pool that is nearly spent (the router's "expiring but
+  draining": its weekly or monthly window closes soon and the step would push
+  it past its limit) is no longer given a step in runs started by this
+  version, even when it is the only pool left; the router used to pick it as a
+  last resort. The step takes another pool that can run it, or comes back to
+  you when none is free (`no pool with quota to spare: <pool> nearly spent
+  (forecast …%) until …`). The dispatched planner and the preflight scout
+  follow the same rule, and their schema correction, and the one retry on the
+  same pool they get when no other pool can run them, never go back to a pool
+  that has become nearly spent: the correction moves to another free pool, and
+  with none free they stop and tell you, with that pool's `nearly spent`
+  reason. A pool the caller pinned is exempt: the run's `--worker-pool` (for a
+  step or the scout), a route that allows only that pool (for a step), and
+  `--orchestrator <pool> --orchestrator-strict` (for the planner).
+- routing: a pool whose weekly or monthly window reads 100% is no longer
+  picked until that window resets, by `bullswarm run` or any workflow. Only a
+  5-hour window at 100% used to keep a pool out, so a spent week whose reset
+  was more than a day away was still given work that then failed on the
+  limit. In a workflow started by this version, a step with no other pool free
+  comes back to you with `<pool> at its weekly limit until <time>` (or
+  `monthly`) in its `why`, and `bullswarm run`
+  names such a pool in its reason as `(burst-gated: <pool> at its weekly
+  limit)`.
+- routing: the last-mile reason no longer promises a retry. A pool near its
+  5-hour limit that still gets the work reads `last mile: <pool> 88.1% of 5h,
+  a limit mid-attempt goes back to the caller`; it used to end `handoff covers
+  the wall`.
+- workflow: `step rerun` and `resume` after a failure the pool caused (a
+  sign-in failure, a provider error, or a worker that died before it answered
+  or changed a file) start on another pool when one can take the step now.
+  Before, the rerun's first pick knew nothing of the failure and could go
+  straight back to the pool whose sign-in had just failed. A usage limit is
+  not one of these: a rerun after one is routed as usual (`--avoid <pool>`
+  keeps it off that pool).
+- workflow: a step can say where it runs with `route`: `pools` and `providers`
+  to use or avoid, and `independentOf` (earlier steps, or "writers" on a check)
+  whose providers it must not use. It is applied before quota pacing, and the
+  kernel's fix and re-review steps inherit it. Reviews are no longer moved away
+  from writers' pools on their own; route a check when you want an independent
+  reviewer. Every review records who reviewed (pool, model, provider) and
+  whether that provider also wrote the work. Runs started before this version
+  keep the automatic placement.
+- workflow: a failed check gets one fix step and one re-review, then comes
+  back to you. `defaults.verifyRounds` counts those fix cycles (0-3, default
+  1; 0 means no automatic fix). A plan file written for an earlier version
+  changes meaning: `verifyRounds: 1` used to mean one review round and no fix,
+  and now means one fix and one re-review; set 0 for review only. `plan
+  validate`, launch and `plan revise` print a note when a plan sets it. The
+  fix step also runs the command evidence of the steps it repairs. When every
+  step affecting a failed requirement declares a `report`, the repair step is
+  a read-only `analyze` step whose deliverable is `report` and which owns no
+  files. A requirement an `act` step affects gets no repair: the loop stops
+  with `stoppedBy: act-step`. Runs started before this version keep their
+  budget of up to 3 review rounds.
+- workflow: a program-mode step can say what it does and what it leaves
+  behind. `role` is one of `investigate`, `produce`, `transform`, `combine`,
+  `check` or `act`, and `deliverable` is `files`, `report`, `data`, `media`
+  or `outward` (`data` and `media` name exact `paths`). A role sets lane and
+  effort the way `kind` does. Every kind still validates and belongs to one
+  role, keeping its own lane, effort and gate: `mechanical` is a
+  transform, `io-read` and `architecture` investigate, `implement` produces,
+  `integration` and `digest` combine, `check` and `adversarial-acceptance`
+  check. A step may give both only when they agree, and then only the kind is
+  stored, so annotating an exported plan changes nothing. An `act` step works
+  outside the workspace (send, post, publish, deploy): it may not edit
+  workspace files, and the kernel never repairs a requirement it affects.
+- workflow: a step whose declared deliverable was not produced fails as
+  `not-produced`. A `files` deliverable needs a changed file or a new commit.
+  A deliverable with `paths` needs every path present and at least one
+  written during the step, checked without git, so git-ignored output counts
+  in a shared workspace (an isolated run refuses a git-ignored deliverable
+  path, and any run refuses a path that names a directory). A `report` must
+  not be empty, and that includes a `combine` step's report. `act` steps, and
+  `combine` steps with a `files` deliverable and no paths, are not judged.
+  The check covers the whole step, so a retry or rerun that finds the work
+  already done is not failed; a rerun of a step that failed `not-produced` is
+  judged again. A program written only with kinds or lanes
+  validates exactly as before. One behavior is new in runs started by this
+  version: a build-lane step other than `integration` that changes no file
+  and makes no commit fails as `not-produced`; 0.35.6 recorded it as
+  succeeded. Chore and analyze steps with no declared deliverable are not
+  judged. Runs started before this version keep their original rules when
+  resumed. The failure gets one retry on the same pool with the failure
+  attached, then comes back to you; `workflow resume` never reruns it. The
+  skill and planner rules make the gate a `check` and keep commit and PR steps
+  `mechanical`.
+- workflow: a program step can declare `evidence`, checks Bullswarm runs
+  itself after the worker finishes. `{"type":"command","cmd":"npm test -- tests/x.test.js"}` passes on exit code 0; `{"type":"schema","file":"out/records.json","schema":"schemas/record.json"}` passes when the JSON
+  (or JSONL) file matches the schema. Up to 5 per step; each is stopped after
+  `timeoutSec` (default 120, at most 600). The worker sees them in its brief.
+  They run in the step's workspace once the "not produced" check has passed,
+  in their own process group, and their full output is saved next to the
+  step's task. A check sees `BULLSWARM_EVIDENCE=1`, `BULLSWARM_STEP_ID`,
+  `BULLSWARM_STEP_OUTPUT` and `BULLSWARM_RUN_DIR`; `"file": "$output"`
+  checks the step's own final response. A check that changes the step's files
+  fails; untracked by-products are reported, not failed, and in an isolated
+  copy the ones a check created are removed and the ones it changed are put
+  back, so they never reach the merge. A failing check
+  fails the attempt as `failed-evidence`: Bullswarm retries once on the same
+  pool with the check's output attached, and after that the step fails and
+  comes back to you (`workflow resume` does not rerun it). A failed check on an
+  act step, and a check that cannot run (a missing or unsupported schema),
+  come straight back to you, and so does an act step whose checks were
+  stopped, because its worker may already have acted. Only the caller declares
+  evidence; a dispatched planner cannot, and review steps and digests take
+  none. Each check's result is in `runs result <id> --json` under
+  `actions[].evidenceResults`; when the worker fails first, no check runs and
+  that value is `null`. Schema checks cover the JSON Schema subset listed in
+  the program reference; any other keyword is refused, never skipped, and a
+  JSONL file with no records fails.
+  `node <package>/bin/check-schema.js <file> <schema>` runs the same check by
+  hand.
+- workflow: each finished step in a new run says what backs it: `proven by
+  command`, `schema` or `review` (a check step passed every requirement the
+  step affects), `review pending` while a check step still covers them, or
+  `finished · unproven`. `watch`, `runs result` and the
+  result summary show it, with a one-line count at the end of the run. Runs
+  started before this version show no labels.
+- workflow: an attempt's diff file is named from its task file
+  (`diff-<action>-attempt-<n>.txt` beside `task-<action>-attempt-<n>.md`), so
+  a rerun writes a new diff and leaves the earlier attempt's diff in place.
+- providers: running out of credit is a usage limit for every provider, not a
+  failure. Claude Code's `Credit balance is too low` used to bench the pool as
+  a broken sign-in; Codex (`You're out of credits`, `You hit your spend cap`),
+  Command Code (`You have insufficient credits`, `Premium credits exhausted`,
+  `You've reached today's limit on …`) and OpenCode (`Quota exceeded. Check
+  your plan and billing details.`) messages were not recognised at all, and a
+  spent Grok Build balance (`API error (status 402 Payment Required): Grok
+  Build usage balance exhausted`, in an error event with exit code 0) was
+  accepted as a finished reply, so the step failed on its missing report and
+  was retried on grok itself. Each is now read as a usage limit; in a
+  workflow started by this version the step comes back to you. HTTP 402
+  counts as an error-shaped line for every provider. The phrases come from
+  each CLI's own strings (claude 2.1.282, codex 0.155.1, command-code 1.65.0,
+  opencode 1.18.31).
+- run, workflow: limit and sign-in notices are read only where the provider
+  reports them, with their own kind. A long reply that quotes sign-in or limit
+  wording (for example a review of the auth checks that mentions
+  `unauthorized`) is no longer failed as a sign-in failure or a usage limit:
+  Claude Code repeats the whole reply in its final record, and a reply long
+  enough to be shortened in the live view was read as the provider's own
+  error. A usage-limit or rate-limit notice inside the provider's stream error
+  event keeps its limit kind; it used to be read as a provider error.
+- workers bill the account of the pool they run on. When the caller itself ran
+  under a Claude home (`CLAUDE_CONFIG_DIR` set), every `claude-code` pool
+  spawned with the caller's home instead of its own, so every Claude pool
+  billed, and hit the limits of, the caller's one account. A pool's own
+  settings now win over the caller's environment; Bullswarm's own
+  `BULLSWARM_*` variables still come from the caller.
+- command-code: headless runs no longer pass `--tools-all`. The default tool
+  set still reads, writes, searches and runs shell commands. The flag was what
+  added `enter_plan_mode`, so a headless run can no longer switch itself into
+  plan mode. `--yolo` is unchanged.
+- dashboard: a Run timeline row and the live block label the routing tier as
+  `tier <effort>` and, when the attempt recorded one, the applied level as
+  `reasoning <level>`. A narrow timeline row keeps the tier and drops the
+  model and reasoning; the narrow live block keeps the model and its
+  reasoning and drops the tier. The selected timeline row, the live block and
+  the Step header list a step's stored not-done items, clipped to the width; a
+  collapsed timeline row still shows only `returned early · N not done`.
+- planner: the skill, the program reference, and the program-mode planner
+  rules say `dependsOn` is how a writer waits for a file or contract it needs,
+  that a behavior and its focused test stay in one action, and that the full
+  browser gate, the commit, and the PR are separate steps after integration,
+  with an explicit `timeBox` on the browser step.
+- watch: the stale check for a writing step that owns no files reads the
+  changed files `git status` lists, including a file edited again through a
+  shell command. A step that declares owned files is still scored from those
+  files only. When git cannot be read, that check contributes nothing.
+- watch: event mode no longer keeps every new event in memory until the next
+  heartbeat. An opted-in heartbeat still prints the event count and the action
+  count. Plain `workflow watch <runId>` follows until the outcome.
+
 ## 0.35.6 — set reasoning per tier and per model from the setup screen
 
 - setup: the setup screen (`bullswarm setup`, `strategy tui`) can now set
@@ -687,7 +997,6 @@ under `docs/design/prototype-frames-0.33.1/` (`budget-55.txt`,
 `budget-120.txt`, `home-today-55.txt`, `home-today-120.txt` and their READMEs),
 drawn from the real pool figures of 2026-09-18.
 
-
 ## 0.33.0 — the dashboard release
 
 - dashboard: the phone `Home` no longer hides data behind its width. The

package/README.md

@@ -36,7 +36,7 @@ flowchart LR
 
 - **Spends quota by pace.** Each task goes to the plan with the most spare quota for how far its window has run, so a plan that is behind, or about to reset with quota left, gets used first.
 - **Picks models for you.** Tasks come in three lanes (`analyze`, `build`, `chore`). Setup asks each CLI which models it offers and suggests the newest one for each effort level, so you don't have to update settings every time a vendor ships a model.
-- **Runs one task or a whole workflow.** `bullswarm run` sends one task to one agent and returns a verdict. For bigger goals your main agent writes a plan; Bullswarm runs the independent steps in parallel across agents, then integration and a final check by a different agent.
+- **Runs one task or a whole workflow.** `bullswarm run` sends one task to one agent and returns a verdict. For bigger goals your main agent writes a plan; Bullswarm runs the independent steps in parallel across agents, then integration, and a review by a different agent when the plan asks for one.
 - **Checks the work, not the exit code.** A delegate saying "done" isn't enough. Bullswarm reads what it actually produced, and a workflow finishing is kept separate from its requirements being verified.
 - **Shows everything live.** A terminal dashboard covers quota, history, running workflows and each agent's individual turns.
 - **Works with the agent you already use.** The `/bullswarm` skill teaches Claude Code, Codex and Grok when to delegate. There's also an early-access Claude Code Mod that shows runs and usage inside Claude Code.
@@ -62,7 +62,7 @@ More screens, including phone-sized ones, are in the [gallery](https://bulls-wor
 | **One agent's built-in subagents or workflows** | Everything draws on that one plan's quota, the same vendor grades its own work, and your process is tied to that vendor's feature. |
 | **An API gateway that re-exposes your subscriptions** | Turning a consumer subscription into a generic API endpoint can conflict with provider terms, and you lose each agent's own tools and harness. |
 | **Switching tools by hand** | You become the scheduler, and the quota you did not get to still expires. |
-| **Bullswarm** | Drives each vendor's own headless CLI—`claude -p`, `codex exec`, `grok -p`—the way those CLIs are meant to be scripted, with the accounts you already signed in. Work lands where quota is spare, and a different agent checks it. |
+| **Bullswarm** | Drives each vendor's own headless CLI—`claude -p`, `codex exec`, `grok -p`—the way those CLIs are meant to be scripted, with the accounts you already signed in. Work lands where quota is spare, and a different agent can check it. |
 
 Bullswarm never proxies a subscription as an API and never collects or shares your vendor credentials.
 

package/bin/check-schema.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// check-schema <file> <schema> [--json] [--format json|jsonl] [--unfence]
+// Everything after `--` is positional, so a path may start with '-'.
+// Exit 0 valid, 1 invalid, 2 cannot check (or a usage error). The evidence
+// runner calls this by absolute path; it has no package.json bin entry.
+
+import { checkSchemaFiles } from '../src/workflow/schema-check.js';
+
+const USAGE = 'usage: check-schema <file> <schema> [--json] [--format json|jsonl] [--unfence]';
+const PRINTED_ERRORS = 20;
+
+function parseArgs(argv) {
+  const positional = [];
+  const options = { json: false, format: undefined, unfence: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--') { positional.push(...argv.slice(index + 1)); break; }
+    if (arg === '--json') options.json = true;
+    else if (arg === '--unfence') options.unfence = true;
+    else if (arg === '--format') {
+      const value = argv[index += 1];
+      if (value !== 'json' && value !== 'jsonl') return null;
+      options.format = value;
+    } else if (arg.startsWith('--format=')) {
+      const value = arg.slice('--format='.length);
+      if (value !== 'json' && value !== 'jsonl') return null;
+      options.format = value;
+    } else if (arg.startsWith('-') && arg !== '-') return null;
+    else positional.push(arg);
+  }
+  if (positional.length !== 2) return null;
+  return { file: positional[0], schema: positional[1], ...options };
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (!args) {
+    if (argv.includes('--json')) {
+      process.stdout.write(`${JSON.stringify({ ok: false, exit: 2, errorCount: 0, errors: [], notes: [], why: USAGE, fault: 'check' })}\n`);
+    } else {
+      process.stderr.write(`${USAGE}\n`);
+    }
+    return 2;
+  }
+  let result;
+  try {
+    result = checkSchemaFiles({ cwd: process.cwd(), file: args.file, schema: args.schema, format: args.format, unfence: args.unfence });
+  } catch (error) {
+    result = { exit: 2, errorCount: 0, errors: [], notes: [], why: `checker error: ${error.message}`, fault: 'check' };
+  }
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify({
+      ok: result.exit === 0,
+      exit: result.exit,
+      errorCount: result.errorCount,
+      errors: result.errors.slice(0, PRINTED_ERRORS),
+      notes: result.notes,
+      why: result.why,
+      fault: result.exit === 2 ? result.fault : null,
+    })}\n`);
+    return result.exit;
+  }
+  const lines = [];
+  if (result.exit === 0) lines.push(`${args.file} matches ${args.schema}`);
+  else if (result.exit === 1) {
+    const count = result.why.replace(/^not valid: /, '');
+    lines.push(`${args.file} does not match ${args.schema}: ${count}`);
+    for (const error of result.errors.slice(0, PRINTED_ERRORS)) lines.push(`  ${error}`);
+    if (result.errors.length > PRINTED_ERRORS) lines.push(`  … and ${result.errors.length - PRINTED_ERRORS} more`);
+  } else {
+    lines.push(`cannot check ${args.file} against ${args.schema}: ${result.why}`);
+  }
+  for (const note of result.notes) lines.push(`note: ${note}`);
+  (result.exit === 2 ? process.stderr : process.stdout).write(`${lines.join('\n')}\n`);
+  return result.exit;
+}
+
+process.exitCode = main(process.argv.slice(2));