bullswarm 0.37.3 → 0.38.1

package/AGENTS.md

@@ -14,31 +14,27 @@ 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`).
-0.37.0 (program v3, the generic model) has landed: a step is a run, and a
+pattern cards are in `docs/design/patterns/`. Each release updates this file.
+
+0.37.0 (program v3, the generic model) landed: a step is a run, and a
 workflow composes steps, phases, gates and loops. `bullswarm run` is a
-one-step workflow. New programs are `bullswarm.workflow.program.v3`: a step
-passes by facts (clean exit, deliverable produced, evidence passed, answer
-matching its schema), a gate waits for `workflow continue`, a loop reruns its
-steps until one condition holds (at most 5 rounds), and new work is added
-with `workflow add`, never by editing the run's steps. v3 reports facts per
-step and has no requirement IDs, `evidenceFor` or `verifyRounds`. v2 programs
-and saved runs keep running and replaying as before.
+one-step workflow. A step passes by facts (clean exit, deliverable produced,
+evidence passed, answer matching its schema), a gate waits for
+`workflow continue`, a loop reruns its steps until one condition holds (at
+most 5 rounds), and new work is added with `workflow add`, never by editing
+the run's steps. v3 reports facts per step and has no requirement IDs,
+`evidenceFor` or `verifyRounds`.
+
+0.38.0 (the removals release, `docs/design/0.38.0-removals.md`) deleted the
+mechanisms v3 replaced: the preflight scout, the dispatched planner
+(`--orchestrator`), the caller-planner gap turn (`plan show`/`plan submit`),
+whole-plan revise (`plan export`/`plan revise`), the v2 repair loop, the
+kernel-written digest and review tasks, and the old dispatch rules. New
+programs are `bullswarm.workflow.program.v3` only; a v2 program is refused
+before a run folder exists. Only a run marked `programFormat: 3` is driven.
+Every other saved run (v2, stage 1-3, legacy) is view-only: it stays
+listable, showable and countable, and every driving command refuses it
+before doing anything. Their readers and stored formats are unchanged.
 
 ## Non-negotiable doctrine
 
@@ -55,6 +51,12 @@ and saved runs keep running and replaying as before.
    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`).
+   Beside it sits one plan fact: `state.strategy.planExcludedModels[pool]`,
+   the models a provider said that pool's subscription does not include
+   (failure kind `model-not-in-plan`). It is a fact about the plan, like its
+   price, not a spent or dead pool: the pool stays pickable with its other
+   models, and the record ends when the subscription changes or the operator
+   turns the model back on (`src/lib/strategy.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
@@ -76,34 +78,31 @@ and saved runs keep running and replaying as before.
    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. In a v3 program (the format for new work) a check is an ordinary
-   step, and fixing until it passes is a loop the caller declares (`loops`,
-   `until` one condition, `maxRounds` 1-5); a loop out of rounds or a gate
-   waits for the caller (`workflow continue`), and a failed step goes to the
-   caller through the watcher's needs-you block: rerun elsewhere, add steps
-   (`workflow add`), take over, or accept anyway. v3 validate refuses
-   `defaults.verifyRounds`. In a v2 program a failed check gets one fix step
-   and one re-review (`defaults.verifyRounds`, default 1, 0-3), then the
-   caller, and `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
+   Only a failed step's dependents wait.
+6. Review is a caller option, recorded as a fact. A check is an ordinary
+   step with an `answer` and/or `evidence`, and it passes by facts only.
+   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`. Saved v2 runs keep showing their requirement verdicts
+   (`evidenceFor`, `verified`) as they were recorded.
+7. New goal workflows are caller-planned v3 programs in a shared workspace.
+   `bullswarm workflow goal --program` executes the graph; the caller writes
+   the plan (or a step whose answer is a list of steps, appended with
+   `workflow add --from-answer`). File territories are advisory scheduling
+   hints. A check is an ordinary step, and fixing until it passes is a loop
+   the caller declares (`loops`, `until` one condition, `maxRounds` 1-5); a
+   loop out of rounds or a gate waits for the caller (`workflow continue`),
+   and a failed step goes to the caller through the watcher's needs-you
+   block: rerun elsewhere, add steps (`workflow add`), take over, or accept
+   anyway. v3 validate refuses `defaults.verifyRounds`. `--isolation` opts
+   into strict per-worker worktrees. A saved run that is not v3 is view-only
+   (0.38.0): its original semantics are kept for display (`features.json`),
+   and nothing drives it again.
+8. Historical authored-graph runs remain visible as read-only `legacy` rows,
+   and `runs show`/`result`/`watch` print a bounded summary of them. Their
+   executor was removed in 0.27.0; driving commands fail closed before
    dispatch and historical run directories remain untouched.
 
 ## Development

package/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 ## Unreleased
 
+## 0.38.1 — Fewer wasted retries, honest no-pool reasons
+
+- no eligible pool: when a pool lacks a tier only because free models are
+  off for it, or because its plan was seen not to include the tier's model,
+  the reason now says so (`free models are off for <pool>`, `<pool> has no
+  <tier>-tier model its plan includes (plan excludes <models>)`, or `<model>
+  is not in <pool>'s plan` for a model the step names), also under a step's
+  route and in `run --dry-run`. Before, a routed step read only `no
+  enabled pool left has a model on the <tier> tier`.
+- dispatch: a worker can mark a blocker it may not change by starting a `##
+  Not done` line with `outside:` (`- outside: tests/router.test.js fails on
+  main before this change`); work tasks now ask for this. A step that fails
+  `failed-evidence`, `not-produced` or `semantic` with such a line skips its
+  one automatic retry and comes back to you at once, its `why` ending `retry
+  skipped: the worker reported a blocker outside this step: <item>`; the saved
+  attempt lists every such item as `outsideBlockers`. `schema` and process
+  failures keep their retry.
+- workflow add: a fragment may carry `blocks: {"<new step id>": ["<existing
+  step id>", ...]}` to make existing steps that have not started also wait for
+  a step it adds, for example a fix in front of a report (then `step accept`
+  the failed step). It is the one change a fragment may make to an existing
+  step; a started step, a loop's step, a gate, a loop or a cycle is refused in
+  fragment words. A step already blocked behind a failed step stays blocked
+  (it is not reset and blocked again). The output prints `waits    step <id>
+  now also waits for <ids>`, and `--json` carries `waits`.
+- advisories: a new `suite-wider-than-files` advisory names a step that owns
+  files but runs a command check naming none of them (a bare `npm test`),
+  because a failure elsewhere in the suite would fail a step that cannot fix
+  it. Scope the command, or run the suite in a check step. Like every advisory
+  it never refuses a program or changes an exit code.
+- advisories: with `--json`, `workflow goal` and `workflow plan validate` no
+  longer print advisory text; the advisories are in the JSON as `advisories`
+  (the detached launch document always, a foreground result when there are
+  any). In human mode `plan validate` now prints them on stderr, as `workflow
+  goal` does.
+- run --json: the verdict has top-level `pool` and `model`, the last attempt's
+  (null when nothing was dispatched). `pick` keeps them too. Small flat
+  objects such as the reasoning record now print on one line, so the verdict
+  stays within 60 lines.
+- workflow runs: the goal column skips constraint sentences that follow a
+  dropped leading folder (`Work in /abs/path (git branch x). Do not commit.
+  Fix the parser crash.` shows `Fix the parser crash.`); a goal that is only
+  constraints shows the folder name.
+- strategy: new `bullswarm strategy set-free <allow|never> [--pool <name>]
+  --yes` (and `set-free reset --pool <name>`) stops free models being
+  suggested, applied or dispatched, for every pool or one; a pool's own
+  setting wins. A pool left with only free models for a tier is out of that
+  tier with the reason `free models are off for <pool>`: a step no pool can
+  take says it in its `why` and `routeCandidates`, `run --dry-run` says it
+  too, and `strategy show` prints it under the tier. A model you name
+  yourself is still allowed. `strategy show` prints a `free models:` line, and
+  the low tier's basis stops putting free models first when every pool has
+  them off.
+- providers: a connector may list `modelPlanSignatures`, the text its CLI
+  prints when the subscription's plan does not include the requested model
+  (Command Code: `MODEL_NOT_IN_PLAN`). Only the provider's error output is
+  read: stderr, and on an event stream the records the provider flags as
+  errors (read even when the worker exits 0), so a worker's reply that quotes
+  the code, even on a line starting `Error:` or in a clean final record, is
+  still a reply. A hit is the new failure kind
+  `model-not-in-plan` (a process failure, labelled `model not in plan`): the
+  step's retry goes to another pool, and `state.strategy.planExcludedModels`
+  records the model for that pool. The pool keeps running its other models;
+  strategy, rungs, pins and dispatch pass that model over on that pool only.
+  `strategy show` prints `not in plan: <pool>: <model>`. `strategy
+  include-model <model>`, a changed `strategy set-subscription`, or turning
+  the model back on for the pool clears it, and `workflow resume` reruns such
+  a step.
+- command-code: models are ranked by family (astra, sol, gpt, terra, luna,
+  mini, fable, opus, sonnet, haiku, grok), so a newly listed model is ranked
+  the day it appears and the newer version of a family ranks first
+  (`gpt-6.1-sol` above `gpt-5.6-sol`, `claude-opus-5-5` above
+  `claude-opus-4-7`). Dated prices and the deliberate overrides (`gpt-5.4` and
+  `grok-4.5` medium, `minimax-m3` high) stay as rows; kimi and glm stay
+  unranked.
+
+## 0.38.0 — The removals release: v3 only, saved runs view-only, less code
+
+- removed: the mechanisms program v3 replaced (0.37.0) no longer run. The
+  preflight scout (`--scout`, `--no-scout`), the dispatched Workflow Planner
+  (`--orchestrator`, `--orchestrator-model`, `--orchestrator-strict`,
+  `--strict-orchestrator`, `--suggested-plan`, `--planner-reasoning`), the
+  caller-planner gap turn (`workflow plan show`, `workflow plan submit`),
+  whole-plan revise (`workflow plan export`, `workflow plan revise`),
+  `workflow plan contract --v2`, the v2 repair loop (`defaults.verifyRounds`),
+  the kernel-written digest and review tasks, and goal requirement
+  extraction are gone. For one release each removed flag and verb exits 2
+  with one sentence naming its replacement: a first step your later steps
+  depend on instead of the scout; a program you write, or a step whose answer
+  is a list of steps appended with `workflow add --from-answer`, instead of
+  the planner; `workflow add` and `workflow step rerun` instead of revise.
+- v2 programs: a `bullswarm.workflow.program.v2` is refused by
+  `workflow goal --program` and `workflow plan validate` with exit 2, before
+  any run folder exists: `bullswarm.workflow.program.v2 is no longer accepted
+  for a new run; write a program.v3 (bullswarm workflow plan contract) and
+  check it (bullswarm workflow plan validate --program <file.json>)`.
+- saved runs: only a run marked `programFormat: 3` is driven. A run an
+  earlier Bullswarm started (v2 and every earlier format, legacy included)
+  is view-only: `workflow resume`, `goal --resume`, `pause`, `steer`,
+  `step rerun`/`accept`/`restart` and the removed plan verbs exit 2 with
+  `run <id> was started by an earlier Bullswarm and is view-only; start a new
+  run: …` and change nothing (`workflow add` gives the same sentence with
+  exit 1); the kernel refuses to resume one too. `workflow cancel` still finalizes a v2 run left live. Every saved run
+  stays listed, shown and counted as before (`runs list --all`, `show`,
+  `result`, `--summary`, `watch`, the dashboard, `stats`, History), and a
+  saved repair-loop run keeps its recorded `next` text.
+- legacy runs: `workflow runs show`, `runs result`, `watch` and `tui` on a
+  run from before 0.27 print a bounded read-only summary built from its saved
+  files instead of refusing; minutes or cost the files do not hold stay
+  unknown.
+- dispatch: every step follows the one failure rule: one automatic retry,
+  then the caller; a usage limit goes straight to the caller; a transient
+  rate limit backs off on its own pool only. The rules older runs used are
+  gone with those runs' execution.
+- `workflow capabilities` no longer lists `actionRoles` or the dispatched
+  planner mode; roles and kinds stay only as the reader of saved v2 runs.
+- The text judge (`judgeContent`) stays: `pools probe`, `health` and
+  `contentUsableDespiteExit` in `bullswarm run --json` still use it.
+- dispatch: a worker a signal stopped (the kernel's SIGTERM, a timeout) is
+  recorded as `interrupted`, not as a `process` failure, on v3 steps too.
+
 ## 0.37.3 — Price-band model picks, tier-level reasoning, per-step model
 
 - strategy: a connector can opt into a price band (`priceBand: true`; Codex