bullswarm 0.10.8 → 0.11.1

package/AGENTS.md

@@ -37,7 +37,7 @@ content. Published as `bullswarm` on npm.
 ## Development
 
 ```bash
-npm test            # 261 tests, no network needed (meters read from cache)
+npm test            # full suite, no network needed (meters read from cache)
 node bin/bullswarm.js doctor --json   # readiness report
 node bin/bullswarm.js workflow list   # discover workflows
 node bin/bullswarm.js workflow runs   # ongoing workflow instances

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # bullswarm changelog
 
+## 0.11.1 — reliable `--watch` handoff
+
+- `workflow goal --watch` no longer races the detached child: the watcher now
+  waits up to 30 s for the run's `state.json` to appear before attaching, and
+  `runWorkflowWatch` accepts `waitForRunMs`. The 0.11.0 tag failed to publish
+  because this race made the release-gate test fail on the CI runner; 0.11.1
+  carries the full 0.11.0 change set below.
+
+## 0.11.0 — plan the whole graph, run it wide
+
+Adopts the driving mechanics of Claude Code's dynamic workflow (documented in
+`docs/claude-dynamic-workflow-mechanics.md`) into the autonomous loop.
+
+- Ready-set scheduler: every planner action whose dependencies have succeeded
+  starts immediately, and a dependent action starts the moment its own inputs
+  finish rather than when the whole round finishes. The global
+  `settings.concurrency` limiter caps real parallelism. Verify-B now overlaps
+  fix-C exactly like a Claude `pipeline()` stage.
+- Planning doctrine: the planner is told to propose the complete dependency
+  graph in one decision (per-item fix→verify chains plus one whole-system
+  verify), to declare file ownership per action and order same-file edits with
+  `dependsOn`, to write self-contained worker prompts, and what a planning round
+  trip costs. The goal orchestrator prompt no longer asks for "the smallest
+  useful set" of actions. `executionConstraints.concurrency` is exposed.
+- `workflow goal` default `--concurrency` is 8 (was 3; max 16).
+- The planner prompt's shared-working-tree caution now says what is actually
+  unsafe (whole-tree mutation, running the full suite while others edit) and
+  states that concurrent workers editing disjoint files is the expected mode;
+  the 0.10.9 orchestrator had cited the old wording as its reason not to fan
+  out ("Implementation is deliberately NOT fanned out … shared-target mutation
+  policy").
+- `verify.review` is recovered when a planner puts instructions or a filesystem
+  path there: instructions move to `prompt`, the single dependency's artifact is
+  inferred, and any `review` that is not `outputs.<actionId>.outFile` is
+  rejected at validation (feeding the corrective turn) instead of failing a
+  dispatch after a full planning round trip.
+
+## 0.10.9 — planner self-correction and honest silence
+
+- An invalid or non-JSON orchestrator decision no longer fails the run. The
+  runtime feeds the exact validator issues, the rejected proposal, and a
+  response excerpt back to the same orchestrator thread for bounded corrective
+  turns (`settings.maxPlannerCorrections`, default 2, emits
+  `decision.correction_requested`), then benches that pool as orchestrator for
+  the rest of the run and escalates to one other eligible pool
+  (`decision.orchestrator_escalated`), and only then settles on a qualified
+  `completed_with_concerns`/`blocked` outcome. The decide action's ledger status
+  now agrees with that outcome (`failed_retryable` while correcting,
+  `failed_terminal` on exhaustion) instead of reporting `succeeded`.
+- The planner prompt now shows complete `run`, `fanout` (`items` +
+  `stepTemplate.prompt` with `{{item}}`), and `verify` (`review`) skeletons, so
+  the first proposal can match what `decision.js` validates.
+- `workflow watch` separates two silences: `quiet` counts durable workflow
+  events, and a new `agent output … ago` figure (JSONL `transportQuietForSec`)
+  counts raw output from live agents, so a thinking agent and a dead one look
+  different on the same heartbeat line.
+- Removed the dead thin-leaf help renderer left over from the help unification
+  and stopped hard-coding the test count in AGENTS.md.
+
 ## 0.10.8 — quieter monitoring and resilient orchestration
 
 - Made `workflow watch` aggregate low-level activity into compact interval

package/docs/claude-dynamic-workflow-mechanics.md

@@ -0,0 +1,231 @@
+# How Claude Code drives a dynamic workflow — mechanics, and what bullswarm adopts
+
+Written 2026-08-29 from inside a Claude Code session that has the `Workflow`
+tool ("ultracode") loaded, by the model that authors those workflows.
+
+Every statement is tagged:
+
+- **[SPEC]** — quoted or closely paraphrased from the `Workflow` tool contract
+  and the `workflow-authoring` reference as loaded into the session on
+  2026-08-29. This is the documented behaviour the orchestrating model is
+  told to rely on.
+- **[OBSERVED]** — measured in this repository's experiments
+  (`docs/experiments/2026-08-29-ultracode-vs-bullswarm.md`).
+- **[INFERRED]** — my reading of how the harness must behave to satisfy the
+  spec. Not confirmed by source; treat as a hypothesis.
+
+## 0. The one-paragraph shape
+
+Claude's orchestrator (the main-loop model) does **not** decide step-by-step at
+runtime. It writes a *program* — a small JavaScript script — that declares the
+phases and calls `agent(prompt, opts)` once per worker, wired together with
+`pipeline()` / `parallel()` / plain loops. The harness executes that program
+deterministically, spawning subagents concurrently up to a cap, and the model
+reads the aggregate return value when the program finishes. Planning is
+front-loaded into one authoring act; parallelism is explicit in the code; every
+worker receives an individually written, self-contained prompt and (usually) a
+JSON schema its answer must satisfy. Re-planning happens either as ordinary
+code (loops, conditionals) inside the script, or between scripts when the model
+reads a result and authors the next one. **[SPEC]**
+
+bullswarm's `workflow goal`, by contrast, runs an LLM *at every checkpoint*: a
+`decide` step proposes JSON actions, the runtime validates and executes them,
+then asks the LLM again. **[SPEC — bullswarm source]** The rest of this document
+is about which of Claude's mechanics that loop can adopt without giving up its
+one advantage — the user supplies a goal, never a graph.
+
+## 1. Mechanics, one at a time
+
+### 1.1 The control plane is code, authored once **[SPEC]**
+
+- A script must begin with a pure-literal `export const meta = { name,
+  description, phases: [{ title, detail }] }`; the body uses `phase()`,
+  `agent()`, `pipeline()`, `parallel()`, `log()`, `args`, `budget`, and
+  `workflow()` (one level of nesting).
+- The tool is explicitly for "multi-step orchestration where control flow
+  should be deterministic (loops, conditionals, fan-out) rather than
+  model-driven."
+- The recommended pattern is **hybrid**: "scout inline first (list the files,
+  find the channels, scope the diff) to discover the work-list, then call
+  Workflow to pipeline over it. You don't need to know the shape before the
+  *task* — only before the *orchestration step*."
+- Multi-phase work is several workflows in sequence: "run several in sequence —
+  read each result before deciding the next phase. You stay in the loop; each
+  workflow is one well-scoped fan-out."
+
+Consequence: between two agents inside one workflow there is **no model
+round-trip**. The next agent starts the instant its inputs exist. **[INFERRED
+from spec; consistent with OBSERVED timings]**
+
+### 1.2 Phases are progress groups, not barriers **[SPEC]**
+
+- `phase(title)` starts a new phase; "subsequent agent() calls are grouped
+  under this title in the progress display". `opts.phase` on `agent()` assigns
+  the group explicitly and exists precisely "to avoid races on the global
+  phase() state" inside `pipeline()`/`parallel()` stages.
+- Titles are matched exactly against `meta.phases`; an unmatched title "just
+  gets its own progress group".
+- Nothing about a phase synchronises work. The **only** barrier is
+  `parallel()`.
+
+### 1.3 Parallelism primitives **[SPEC]**
+
+- `pipeline(items, stage1, stage2, …)`: "run each item through all stages
+  independently, NO barrier between stages. Item A can be in stage 3 while item
+  B is still in stage 1. This is the DEFAULT for multi-stage work. Wall-clock =
+  slowest single-item chain, not sum-of-slowest-per-stage." A stage that throws
+  drops that item to `null` and skips its remaining stages.
+- `parallel(thunks)`: "run tasks concurrently. This is a BARRIER … Use ONLY
+  when you genuinely need all results together." A barrier is justified only
+  when stage N needs cross-item context from all of stage N−1 (dedup/merge,
+  early exit on zero count, "compare with the other findings").
+- Anti-barrier guidance is explicit: "'I need to flatten/map/filter first' —
+  do it inside a pipeline stage"; "'The stages are conceptually separate' —
+  that's what pipeline() models. Separate stages ≠ synchronized stages."
+- Caps: "Concurrent agent() calls are capped at min(16, available CPUs − 2) per
+  workflow — excess calls queue and run as slots free up." Lifetime cap 1000
+  agents; ≤ 4096 items per `parallel()`/`pipeline()` call.
+
+### 1.4 One prompt per agent, structured return **[SPEC]**
+
+- `agent(prompt, opts)`; "Subagents are told their final text IS the return
+  value (not a human-facing message), so they return raw data."
+- `opts.schema` (JSON Schema): "the subagent is forced to call a
+  StructuredOutput tool and agent() returns the validated object — no parsing
+  needed … validation happens at the tool-call layer so the model retries on
+  mismatch."
+- Other per-agent knobs: `label` (display), `phase` (group), `model`
+  (override; "default to omitting it"), `effort` (`low`…`max`), `isolation:
+  'worktree'` ("EXPENSIVE … use ONLY when agents mutate files in parallel and
+  would otherwise conflict"), `agentType` (custom subagent definition).
+- `agent()` "returns null if the user skips the agent mid-run or the subagent
+  dies on a terminal API error after retries (filter with .filter(Boolean))."
+
+### 1.5 Failure semantics live in code **[SPEC]**
+
+- `parallel()` "never rejects" — a failing thunk becomes `null`.
+- Retry, repair and convergence are ordinary loops: *loop-until-count*,
+  *loop-until-budget*, *loop-until-dry* ("keep spawning finders until K
+  consecutive rounds return nothing new"). No planner turn is spent deciding to
+  retry; the script already says so.
+
+### 1.6 Determinism and resume **[SPEC]**
+
+- `Date.now()`, `Math.random()`, argless `new Date()` throw in scripts ("they
+  would break resume"); timestamps come in via `args`.
+- Every invocation persists its script; the run's `journal.jsonl` "records each
+  agent's actual return value". Resume = same script + `resumeFromRunId`: "the
+  longest unchanged prefix of agent() calls returns cached results instantly;
+  the first edited/new call and everything after it runs live."
+
+### 1.7 Budget is a hard ceiling **[SPEC]**
+
+- `budget.total / spent() / remaining()`; "The target is a HARD ceiling, not
+  advisory: once spent() reaches total, further agent() calls throw."
+- bullswarm deliberately does the opposite (advisory targets, by user
+  decision: "a failed run is more costly than a slightly over budget run").
+  This difference is kept on purpose.
+
+### 1.8 Observability **[SPEC]**
+
+- Progress is rendered as a tree grouped by phase, with per-agent labels;
+  `log()` "emit[s] a progress message to the user (shown as a narrator line
+  above the progress tree)"; `/workflows` shows live progress; the tool result
+  carries the `runId` and transcript directory.
+
+### 1.9 Quality patterns the orchestrator is told to compose **[SPEC]**
+
+Adversarial verify (N skeptics prompted to refute; kill on majority),
+perspective-diverse verify (distinct lenses instead of N identical refuters),
+judge panel (N independent attempts → parallel judges → synthesis), loop-until-
+dry, multi-modal sweep, completeness critic, and "no silent caps: if a workflow
+bounds coverage (top-N, no-retry, sampling), log() what was dropped."
+
+### 1.10 Ultracode **[SPEC]**
+
+"When a system-reminder confirms ultracode is on, that opt-in is standing:
+author and run a workflow for every substantive task by default … For
+multi-phase work (understand → design → implement → review), that often means
+several workflows in sequence — one per phase — so you stay in the loop between
+them."
+
+## 2. What that looks like from the outside **[OBSERVED]**
+
+Filled from the experiment report as runs complete. Numbers here are copied
+from `docs/experiments/2026-08-29-ultracode-vs-bullswarm.md`, never projected.
+
+- bullswarm 0.10.9 smoke goal ("create hello.txt and verify it"), single pool
+  `claude-code` pinned to `claude-opus-5`: wall 553 s; **4 orchestrator turns =
+  438 s (79 % of wall)**; 2 worker attempts = 114 s; max concurrency 1; 6
+  dispatches; ~29 k tokens (bullswarm's byte/4 estimate). Two of the four turns
+  were spent recovering from a `verify` proposal whose `review` field carried
+  instructions instead of an artifact path — a shape the 0.10.9 planner
+  skeleton itself had suggested.
+- bullswarm 0.10.9 on the 7-module fixture (baseline, `--concurrency 8`): the
+  orchestrator's first decision (152 s) proposed one serial chain
+  discover → implement → verify and wrote: "Implementation is deliberately NOT
+  fanned out: all fixes land in one shared working tree and converge on
+  src/index.js, so concurrent workers would violate the shared-target mutation
+  policy and race on the barrel file." The policy it cites was a caution line
+  in the planner prompt; a concurrency cap of 8 was available and unused.
+  Discovery alone then ran 458 s. (Final numbers: experiment report.)
+- (comparison fixture final results: pending)
+
+## 3. bullswarm today, mechanic by mechanic
+
+| Mechanic | Claude `Workflow` | bullswarm ≤ 0.10.9 | Gap |
+| --- | --- | --- | --- |
+| Control plane | Code, authored once; no model call between agents | LLM `decide` turn at every checkpoint; each turn is a fresh `claude -p --resume` process reading the full durable context | Structural. Reachable target: **one planning turn per replan-worthy event** (initial DAG; then only on failure/completion), not per action |
+| Phases | Labels for grouping; never synchronise | Forward-only kebab-case names per action; also just labels | None |
+| Parallelism | `pipeline` default, `parallel` barrier; cap min(16, CPUs−2) | `executeActions` ran dependency-ready siblings **serially** (`runner.js:558`); only `fanout` items ran concurrently; goal default concurrency 3 | **Fixed in 0.11.0** — ready-set scheduler + default 8 |
+| Planner bias | Script author is told to fan out and default to pipeline | Goal prompt said "return needs_more_work with the **smallest useful set** of bounded … actions" (`goal.js:18`) and planner prompt said "keep actions cohesive" | **Fixed in 0.11.0** — "propose the COMPLETE dependency graph", per-item fix→verify chains, file ownership, self-contained prompts |
+| Per-agent prompt | Self-contained, plus JSON schema enforced at tool layer | Planner-authored prompt; free-text answer, content-verified by heuristics; `verify` returns JSON verdict | Partial. Schema-enforced worker output is a candidate, not adopted yet |
+| Failure handling | Loops in code; `null` on agent death | Planner replans (costly); 0.10.9 added corrective turns for invalid decisions and 0.11.0 recovers mis-shaped `verify.review` before dispatch | Improved; retry-in-code per action still absent |
+| Determinism / resume | Journal of return values; prefix cache | Durable `state.json` + `events.jsonl` + action ledger; resume skips durable outputs | Equivalent |
+| Budget | Hard ceiling | Advisory targets (user decision) | Intentional difference |
+| Observability | Progress tree, narrator, `/workflows` | `watch` heartbeat (semantic quiet + agent-output quiet since 0.10.9), `tui`, events | Comparable |
+| Isolation | `isolation: 'worktree'` per agent | Shared `addDir`; planner-declared file ownership | Candidate |
+
+## 4. Adopted into bullswarm 0.11.0
+
+1. **Ready-set scheduler** (`src/workflow/runner.js`, `executeActions`).
+   Every action whose `dependsOn` have all succeeded is launched immediately;
+   a dependent action starts the moment *its own* dependencies finish, not when
+   the whole round finishes. The global dispatch limiter
+   (`settings.concurrency`) caps real concurrency. This gives `pipeline`
+   semantics to any DAG the planner proposes: verify-B overlaps fix-C.
+   Test: `dependency-ready sibling actions run concurrently and dependents
+   start as soon as their own inputs finish` (`tests/workflow-adaptive.test.js`).
+2. **Planning doctrine in the planner prompt** (`src/workflow/runtime.js`) and
+   goal orchestrator prompt (`src/workflow/goal.js`): propose the complete graph
+   in one decision; independent actions run concurrently; per-item fix→verify
+   chains plus one final whole-system verify; explicit file ownership per
+   action and `dependsOn` for any same-file edits; self-contained worker
+   prompts with absolute paths and the exact acceptance command. The prompt
+   also states the cost of a planning turn so the model can weigh it. The
+   context exposes `executionConstraints.concurrency` and
+   `readySiblingsRunConcurrently: true`.
+3. **Default `--concurrency` 8** for `workflow goal` (was 3; max 16).
+4. **`verify.review` contract made survivable**: instructions placed in
+   `review` are moved to `prompt` and the single dependency's artifact is
+   inferred; a `review` that is not `outputs.<actionId>.outFile` is rejected at
+   validation (so the 0.10.9 corrective turn fixes it) instead of failing a
+   dispatch after a planning round trip.
+
+## 5. Not adopted (yet), and why
+
+- **Schema-enforced worker output.** bullswarm's content verification and the
+  JSON `verify` verdict cover the failure mode today; adding per-action
+  `outputSchema` is the next step if planners keep re-asking workers for
+  structure.
+- **Per-action worktree isolation.** File ownership declared by the planner is
+  cheaper and matches Claude's own guidance ("EXPENSIVE … use ONLY when agents
+  mutate files in parallel and would otherwise conflict").
+- **Hard budgets.** Deliberately advisory; see 1.7.
+- **Retry policy in the graph.** Claude writes repair loops as code. A per-
+  action `retryPolicy` proposed by the planner would remove one planner turn per
+  transient failure; not yet built.
+- **Identical control plane.** bullswarm's orchestrator remains an LLM per
+  checkpoint because the user supplies only a goal. The convergence target is
+  therefore "few planning turns, full width between them", measured as
+  `plannerSec / wallSec` and `maxConcurrentAttempts` in the experiment report.

package/docs/experiments/2026-08-29-ultracode-vs-bullswarm.md

@@ -0,0 +1,240 @@
+# Claude ultracode dynamic workflow vs bullswarm `workflow goal` — side-by-side (2026-08-29)
+
+Status: IN PROGRESS — results sections are filled in as runs complete. Numbers
+below are observed, not projected; anything estimated is labelled.
+
+## Question
+
+Same goal, same models, same fixture: how does bullswarm's autonomous
+`workflow goal` loop behave next to Claude Code's native dynamic workflow
+(the `Workflow` tool, "ultracode"), and what has to change in bullswarm to make
+it feel as smooth?
+
+## Setup (identical on both sides)
+
+- **Fixture**: `swarmbench`, a zero-dependency Node ESM project with six small
+  pure-logic modules under `src/`, one `node:test` file per module under
+  `tests/`, plus an intentionally incomplete `src/index.js` barrel with its own
+  test. Bugs were planted by a separate subagent; the orchestrator of the Claude
+  side (this session) was told only file names and baseline counts, never the
+  bugs, so both orchestrators had to discover them.
+- **Two byte-identical copies**, each `git init`-ed so the diff can be audited
+  afterwards. Test files are SHA-256 fingerprinted before and after each run to
+  prove neither side edited a test.
+- **Goal text (verbatim, both sides)**: see "Goal" below.
+- **Models locked to one account**: workers on both sides are `claude-opus-5`.
+  Orchestrator: Claude side = this Claude Code session (Fable 5, authoring and
+  running the workflow script); bullswarm side = `claude-code` connector pinned
+  with `--orchestrator claude-code` and `strategy assign high|medium|low --pool
+  claude-code --model claude-opus-5`, `claude-fable-5` excluded.
+- **bullswarm** 0.10.9 (released and installed from npm for this experiment),
+  run from the installed binary with an isolated `BULLSWARM_HOME` in which every
+  pool except `claude-code` is disabled and the connector meter is `none` so a
+  5-hour burst gate cannot bench the only pool mid-run.
+- **Sequential runs** on the same laptop so wall-clock numbers are not skewed
+  by contention for the same subscription and CPUs.
+
+## Goal
+
+Verbatim, passed as the single goal argument to bullswarm and as the task
+statement the Claude-side workflow script decomposes:
+
+```text
+Make `npm test` pass in this repository. Every failing test is caused by a bug in a file under src/ (including an incomplete src/index.js barrel that must re-export every module's public API). Fix the source so all tests pass. You must not modify, delete, or add any file under tests/. Finish by running the full `npm test` and report, per file changed, what was wrong and what you changed.
+```
+
+## Fixture baseline
+
+`swarmbench`: `src/{csv,duration,index,intervals,lru,semver,slugify}.js`,
+`tests/{csv,duration,index,intervals,lru,semver,slugify}.test.js`, `npm test`
+= `node --test tests/*.test.js`. Baseline on both copies (Node v22.23.2):
+
+```text
+# tests 52
+# pass 37
+# fail 15      (failures present in all 7 test files)
+```
+
+Test-file SHA-256 before any run (identical in both copies):
+
+```text
+5106804683c7f6cef0dbc3629c4c14f4ab2e88319d934626d79bb18a080ae707  tests/csv.test.js
+b7c7d77daad8bfe03dd0b755574cf59faaf677df7d2701a717cf8e44138bd108  tests/duration.test.js
+27aa49f0f601d22748f36e161c963ac77bd9861fe84028a69e02a456a9b38302  tests/index.test.js
+80abeecbea763df43b2260a7ee03df211db5b092ea87e418e0be740c59383cbd  tests/intervals.test.js
+2aa610981dcb9a6c65a0dd9b7b3362f23c95ef5c6436a43cb3d969fc0cc3dded  tests/lru.test.js
+d62bc016abe37f4400499f4a77b94c7b60cc8f473bac6b63f5a461f9a18b6a20  tests/semver.test.js
+d611fd789caed8820eaf03b08aeb2799f564e5f0d320485f886fd9c5cf6ac112  tests/slugify.test.js
+```
+
+Both bullswarm runs and the Claude workflow use a concurrency cap of 8
+(Claude's own cap on this 10-CPU laptop is min(16, CPUs − 2) = 8; bullswarm
+gets `--concurrency 8`), so parallelism differences come from the driving
+loop, not the cap.
+
+## Warm-up: bullswarm 0.10.9 smoke goal (observed)
+
+Goal: "Create a file named hello.txt in this directory containing exactly the
+single line 'hello from smoke test', then verify it exists with that exact
+content." Run `srdwjs`, single pool `claude-code` pinned to `claude-opus-5`,
+`--max-agents 5 --max-expansion-rounds 2 --concurrency 2`.
+
+| metric | value |
+| --- | --- |
+| wall | 553 s (9m13s) |
+| dispatches | 6 (4 orchestrator turns, 1 worker, 1 verifier) |
+| orchestrator time | 438 s = 79 % of wall (turns: 108 s, 102 s, 151 s, 77 s) |
+| worker time | 38 s (create) + 76 s (verify) |
+| max concurrent attempts | 1 |
+| tokens | ≈29.1 k (bullswarm estimate: utf8 bytes / 4) |
+| outcome | `completed`, verified |
+
+Two of the four planning turns were spent on `verify` actions that died inside
+the runtime without dispatching: the planner put reviewer instructions (turn 2)
+and then a filesystem path (turn 3) into `verify.review`, which the runtime
+resolves as a dotted scope path to an artifact. The 0.10.9 planner skeleton had
+shown exactly that wrong shape. Fixed in the 0.11.0 work (see below).
+
+## Results
+
+### bullswarm 0.10.9 `workflow goal` (baseline, installed binary)
+
+Run `wf-mtd6lxfn-3912fd`, started 2026-08-28T16:44:18Z, `--orchestrator
+claude-code --concurrency 8 --max-agents 30 --max-expansion-rounds 8`.
+
+First planning turn: 152 s. It proposed one strictly serial chain —
+`discover-failures` → `implement-fixes` → `verify-suite` — and explained why
+(verbatim from `state.json` `decisions[0].reason`):
+
+> Implementation is deliberately NOT fanned out: all fixes land in one shared
+> working tree and converge on src/index.js, so concurrent workers would violate
+> the shared-target mutation policy and race on the barrel file.
+
+The "shared-target mutation policy" it cites is a caution line in the 0.10.9
+planner prompt. `discover-failures` (read-only diagnosis of 7 test files) then
+ran alone for 458 s before the single `implement-fixes` worker started.
+
+Final numbers (run `xnujua`, 16:44:18Z → 17:19:26Z):
+
+| metric | value |
+| --- | --- |
+| outcome | `completed`, verified; **52/52 tests pass**; `tests/` byte-identical (SHA-256 unchanged); 7 `src/` files changed, +20/−14 lines |
+| wall | **2108 s (35m08s)** |
+| dispatches | 7 = 3 orchestrator turns + 4 workers |
+| orchestrator time | 431 s (20 %) — turns of 152 s, 189 s, 90 s |
+| worker time | 1677 s: discover 458 s → implement 356 s → (verify-suite: runtime failure, 0 s) → independent-audit 618 s → final-verification 245 s |
+| max concurrent attempts | **1** (parallelism 1.00 — every second of the run had exactly one process working) |
+| planning rounds | 2 expansion rounds + 1 completion |
+| tokens | ≈35.8 k by bullswarm's utf8-bytes/4 estimate of outputs only — **not comparable** to real provider usage (the Claude session's own status line showed ~49 k input tokens after its first four tool calls) |
+
+Timeline of attempts (UTC):
+
+```text
+16:44:18 → 16:46:50  orchestrator turn 1 (152 s)   → serial chain of 3
+16:46:50 → 16:54:28  discover-failures (458 s)     read-only diagnosis
+16:54:28 → 17:00:24  implement-fixes (356 s)       one worker fixes all 7 files; 52/52
+                     verify-suite                  failed inside runtime (review = instructions), never dispatched
+17:00:24 → 17:03:33  orchestrator turn 2 (189 s)   → independent-audit + final-verification
+17:03:33 → 17:13:51  independent-audit (618 s)     re-tests, fuzzes (3 000 interval sets, 2 000 LRU trials, …)
+17:13:51 → 17:17:57  final-verification (245 s)    verify verdict ok
+17:17:57 → 17:19:26  orchestrator turn 3 (90 s)    complete
+```
+
+What the orchestrator did well: it delivered a correct result with an honest,
+detailed completion report, refused to fan out for a stated reason, and
+recovered from its own `verify.review` mistake ("it was my control-plane
+error") in one extra turn. What cost time: a strictly serial plan under a
+concurrency cap of 8 that was never used; a 458 s read-only discovery step
+before any fix; a 618 s audit that fuzzed every module; and one wasted
+planning round on the `verify.review` shape.
+
+### Claude Code, fresh interactive session (Opus, ultracode)
+
+Set-up: a brand-new Claude Code 2.1.250 session started by `herdr` in its own
+tab (`claude-compare`), `--model claude-opus-5 --dangerously-skip-permissions`
+(the same permission posture bullswarm's connector uses), `/effort ultracode`
+confirmed on screen, cwd = the twin fixture copy, no prior context. The goal
+text above was submitted as the first and only prompt at 17:19:16 Z. The
+bullswarm baseline's final single-process planning turn was still running
+until 17:19:26 Z — a 10-second overlap, noted for honesty.
+
+Result (session `309931b0…`, goal turn 17:19:16 Z → 17:22:45 Z):
+
+| metric | value |
+| --- | --- |
+| outcome | **52/52 tests pass**; `tests/` byte-identical (SHA-256 unchanged); 7 `src/` files changed, +21/−14 lines; per-file bug explanation printed |
+| wall | **209 s (3m29s)** — the session's own footer: "Baked for 3m 29s" |
+| agents spawned | **0** — no `Workflow`, no `Agent` call; 11 `Bash` calls in total |
+| planning round trips | 0 |
+| how it decided | 17:19:19–17:20:34 read every `src/` and `tests/` file and ran `npm test` inline; 17:20:34 "I have a complete picture: 15 failures across 7 modules. Let me get a review before I start editing." → advisor: apply directly, "the ultracode carve-out for trivial mechanical edits applies now that diagnosis is done"; 17:22:09 one Python patch script over all 7 files; 17:22:14–17:22:29 `npm test`, `git diff -- tests/` (empty), `git diff -- src/` |
+| tokens (real provider usage from the transcript) | output 41 042; cache-read 1 939 219; cache-write 119 052; uncached input 62 — 24 assistant messages |
+
+**The finding that matters for this experiment:** a fresh Opus session with
+ultracode on judged this goal *too small to orchestrate* and did it solo. The
+"smoothness" here is a fast inline scout (75 s to a complete diagnosis) and
+zero planning round trips — not parallel agents. bullswarm's orchestrator, by
+contrast, cannot do anything inline: every observation costs a worker
+dispatch and every decision a full planning turn, so the same 15 bugs took
+7 dispatches and 35 minutes.
+
+Goal #1 therefore cannot show the fan-out mechanic the user asked about. Goal
+#2 below is sized to require it.
+
+### Correctness audit — goal #1
+
+Independent `npm test` after each run: bullswarm copy 52/52, Claude copy
+52/52. All seven `tests/*.test.js` SHA-256 values identical to the pre-run
+fingerprints on both copies. Diff stat: bullswarm +20/−14 across the same 7
+`src/` files; Claude +21/−14. Both fixed the same bugs the same way.
+
+## Goal #2 — sized to require fan-out
+
+Base: the fixed fixture (52/52) committed clean, copied three times
+(`g2-claude`, `g2-bs-v2`, `g2-bs-base`). Goal text (verbatim, both sides):
+
+```text
+This repository (swarmbench) has six modules under src/ — csv, duration, intervals, lru, semver, slugify — and a passing test suite. For EACH of the six modules deliver three things: (1) a new test file tests/<module>.edge.test.js using node:test and node:assert/strict with at least 6 additional edge-case tests that are not already covered by tests/<module>.test.js, all passing against the current implementation; (2) complete JSDoc on every exported function or class in src/<module>.js (parameter types, return type, thrown errors, one @example) without changing any behaviour; (3) a documentation page docs/<module>.md describing the public API, edge-case behaviour, and examples. Then write docs/README.md as an index table linking all six pages with a one-line summary each. Do not modify the existing tests/<module>.test.js files. Finish with the full `npm test` passing (existing plus new tests) and report what you created.
+```
+
+Six independent items, three deliverables each, one cross-cutting index — the
+shape `pipeline()` exists for.
+
+### Claude Code, fresh interactive session #2 (Opus, ultracode)
+
+New session (`0754e69f…`) in herdr tab `claude-compare-2`, same set-up as
+session #1; goal submitted 17:24:4x Z. Observed driving sequence:
+
+- 17:24:50–17:25:20 inline scouting (ls, `cat -n` every source and test file,
+  `npm test` → 52 passing). First words: "I'll start by orienting myself in the
+  repo before authoring the workflow."
+- 17:25:20–17:26:44 advisor consultation ("Advisor sharpened the plan"); then
+  `mkdir docs` and a baseline snapshot of `src/` for behaviour-preservation
+  checks.
+- 17:28:42 `Workflow` call: script `swarmbench-docs-and-edge-tests`, phases
+  Probe → Author → Verify, five `agent()` call sites in a per-module
+  `pipeline()` ("probe → author → adversarially verify → fix-loop, pipelined
+  per module"), ≈23 k characters, workers inherit the session model (Opus).
+- The first call was **rejected by the harness**: "Invalid workflow script:
+  Script parse error: Unexpected token (48:15) … Workflow scripts must be plain
+  JavaScript". The session replied "Backtick inside a template literal in the
+  lru hints. Fixing and resending." — the same validate-and-correct loop
+  bullswarm 0.10.9 now has for planner decisions, except here the correction is
+  an inline retry inside one turn rather than a fresh planning process.
+
+(execution numbers pending)
+
+### bullswarm 0.11.0 code (`node bin/bullswarm.js` from the repo checkout)
+
+(pending)
+
+### bullswarm 0.10.9 (installed binary), if time allows
+
+(pending)
+
+## Behaviour differences observed
+
+(pending)
+
+## What to change in bullswarm
+
+(pending)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.10.8",
+  "version": "0.11.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/skill/SKILL.md

@@ -332,9 +332,25 @@ optional work. The loop is durable:
 execute -> observe -> decide -> validate proposal -> append -> execute -> observe
 ```
 
+Execution of an accepted proposal is a ready-set scheduler: every action whose
+`dependsOn` have succeeded starts at once (up to `settings.concurrency`, default
+8 for `workflow goal`), and a dependent action starts the moment its own inputs
+finish. The planner is instructed to propose the complete graph per decision —
+per-item fix→verify chains plus one whole-system verify — because each planning
+turn is a full orchestrator round trip. See
+`docs/claude-dynamic-workflow-mechanics.md` for the model this follows.
+
 Allowed planner decisions are `proceed`, `complete`, `needs_more_work`,
 `retry`, `escalate`, `wait_for_approval`, and `stop`. Expansion decisions must
 contain bounded actions; malformed or over-budget output executes nothing.
+A malformed or non-JSON decision does not fail the run: the runtime returns
+the exact validator issues to the same orchestrator thread for up to
+`settings.maxPlannerCorrections` (default 2) corrective turns
+(`decision.correction_requested` events), then benches that pool as
+orchestrator for the rest of the run and tries one other eligible pool
+(`decision.orchestrator_escalated`), and only then settles on a qualified
+`completed_with_concerns`/`blocked` outcome. Safety bounds (`maxActions`,
+`maxItemsPerExpansion`) still terminate immediately with a qualified outcome.
 `complete` still requires successful delivery and verification. `stop` returns
 `completed_with_concerns` with a ready best-effort artifact when useful work
 exists, or `blocked` when it does not; neither hides failed verification.

package/src/cli.js

@@ -17,7 +17,7 @@ import { release } from './lib/release.js';
 import { cmdWorkflow } from './workflow/cli.js';
 import { cmdStrategy, maybeRefreshStrategy } from './strategy-cli.js';
 import { cmdIntegrate, installIntegration } from './integrate.js';
-import { helpForArgs } from './help.js';
+import { helpForArgs, usageLine } from './help.js';
 import { resolveDispatchModel } from './lib/strategy.js';
 
 export function getBullswarmDir() {
@@ -474,9 +474,7 @@ export async function main(argv) {
     case 'release':
       return cmdRelease(opts);
     default:
-      console.error(
-        `unknown verb "${verb}". try: setup | integrate | run | health | pools | strategy | doctor | workflow | runs | version | release`,
-      );
+      console.error(`unknown verb "${verb}". Run "bullswarm --help" for the list of commands.`);
       return 2;
   }
 }
@@ -486,7 +484,7 @@ export async function main(argv) {
 function cmdRelease(opts) {
   const kind = opts.rest[0];
   if (!['patch', 'minor', 'major'].includes(kind)) {
-    console.error('usage: bullswarm release patch|minor|major [--dry-run]');
+    console.error(`usage: ${usageLine(['release'])}`);
     return 2;
   }
   try {