bullswarm 0.10.9 → 0.11.1

package/CHANGELOG.md

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

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.9",
+  "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,6 +332,14 @@ 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.

package/src/help.js

@@ -587,7 +587,7 @@ const workflowGoalText = rich({
     { flag: '--max-actions <n>', desc: 'planning target for total dispatched actions', default: '40 (max 1000)' },
     { flag: '--max-items-per-expansion <n>', desc: 'cap on fanout items added per planner round', default: '8 (max 100)' },
     { flag: '--max-workflow-seconds <n>', desc: 'planning target for total wall-clock seconds', default: '3600 (max 86400)' },
-    { flag: '--concurrency <n>', desc: 'max parallel dispatches', default: '3 (max 16)' },
+    { flag: '--concurrency <n>', desc: 'max parallel dispatches; dependency-ready actions from one decision run concurrently up to this cap', default: '8 (max 16)' },
     { flag: '--retry-attempts <0..3>', desc: 'same-pool retries per failed action', default: '1' },
     { flag: '--resume <shortId|runId>', desc: 'resume a previously started run instead of starting a new goal; mutually exclusive with typing new goal text', default: 'starts a new goal' },
     { flag: '--detach', desc: 'rarely needed — explicitly requests the default independent-launch behavior; cannot combine with --watch', default: 'the default launch already detaches' },

package/src/workflow/cli.js

@@ -400,7 +400,9 @@ async function wfGoal(opts) {
   if (!opts.foreground && !resumeRunId && !opts.request) {
     const launch = await launchDetachedGoal(doc, opts);
     if (shouldAutoWatchGoal(opts)) {
-      return runWorkflowWatch(BULLSWARM_DIR(), launch.shortId ?? launch.runId);
+      // The detached child writes state.json asynchronously; give it a
+      // bounded grace period instead of failing the handoff on a slow host.
+      return runWorkflowWatch(BULLSWARM_DIR(), launch.runId ?? launch.shortId, { waitForRunMs: 30_000 });
     }
     return 0;
   }

package/src/workflow/decision.js

@@ -32,16 +32,39 @@ export function parseDecisionText(text) {
 // a verifier depending on exactly one action plainly intends to review that
 // action's durable output artifact. Ambiguous or missing dependencies remain
 // untouched and are rejected by normal validation.
+// verify.review is a dotted scope path to the artifact under review
+// (outputs.<actionId>.outFile), never instructions. Planners routinely put the
+// reviewer's instructions there; recover that shape instead of failing a
+// dispatch: instructions move to prompt, and a single-dependency verify reviews
+// its dependency's artifact.
+export const REVIEW_PATH_RE = /^outputs\.([A-Za-z0-9_-]+(?:\[\d+\])?)\.outFile$/;
+
+export function looksLikeReviewPath(value) {
+  return typeof value === 'string' && REVIEW_PATH_RE.test(value.trim());
+}
+
 export function normalizeDecisionProposal(proposal) {
   if (!proposal || typeof proposal !== 'object' || !Array.isArray(proposal.actions)) return proposal;
   return {
     ...proposal,
     actions: proposal.actions.map((action) => {
-      if (action?.type !== 'verify' || action.review != null ||
-          !Array.isArray(action.dependsOn) || action.dependsOn.length !== 1) {
-        return action;
+      if (action?.type !== 'verify') return action;
+      const singleDependency = Array.isArray(action.dependsOn) && action.dependsOn.length === 1
+        ? action.dependsOn[0] : null;
+      if (action.review == null) {
+        return singleDependency ? { ...action, review: `outputs.${singleDependency}.outFile` } : action;
+      }
+      if (looksLikeReviewPath(action.review)) return { ...action, review: action.review.trim() };
+      if (typeof action.review === 'string' && singleDependency) {
+        const { review, ...rest } = action;
+        return {
+          ...rest,
+          ...(rest.prompt == null && /\s/.test(review.trim()) ? { prompt: review } : {}),
+          review: `outputs.${singleDependency}.outFile`,
+          reviewNormalizedFrom: review,
+        };
       }
-      return { ...action, review: `outputs.${action.dependsOn[0]}.outFile` };
+      return action;
     }),
   };
 }
@@ -77,6 +100,7 @@ export function validateDecisionProposal(proposal, {
   }
 
   const known = new Set(knownActionIds);
+  const proposedIds = new Set(safeActions.map((action) => action?.id).filter((id) => typeof id === 'string'));
   const closed = new Set(closedPhases);
   const proposed = new Set();
   let proposedItems = 0;
@@ -122,7 +146,18 @@ export function validateDecisionProposal(proposal, {
         }
       }
     }
-    if (action.type === 'verify' && typeof action.review !== 'string') issues.push(`${at}.review is required`);
+    if (action.type === 'verify') {
+      if (typeof action.review !== 'string') {
+        issues.push(`${at}.review is required: a verify with one dependsOn reviews that artifact automatically; with several, set review to "outputs.<actionId>.outFile" and put reviewer instructions in prompt`);
+      } else if (!looksLikeReviewPath(action.review)) {
+        issues.push(`${at}.review must be a dotted artifact path like "outputs.<actionId>.outFile" (the artifact to review), not instructions or a filesystem path; put reviewer instructions in ${at}.prompt`);
+      } else {
+        const reviewed = REVIEW_PATH_RE.exec(action.review.trim())[1].replace(/\[\d+\]$/, '');
+        if (!known.has(reviewed) && !proposedIds.has(reviewed)) {
+          issues.push(`${at}.review references unknown action "${reviewed}"`);
+        }
+      }
+    }
   }
   if (proposedItems > maxItemsPerExpansion) {
     issues.push(`proposal has ${proposedItems} fanout items, exceeding maxItemsPerExpansion=${maxItemsPerExpansion}`);

package/src/workflow/goal.js

@@ -15,10 +15,10 @@ export const AUTONOMOUS_ORCHESTRATOR_PROMPT = [
   '',
   'At every checkpoint:',
   '1. Observe the intent, completed actions, artifacts, failures, verification results, available capabilities, and remaining budget.',
-  '2. If evidence is insufficient, return needs_more_work with the smallest useful set of bounded run, fanout, or verify actions.',
-  '3. Give workers self-contained prompts with the exact goal, scope, expected artifact, and acceptance checks they need.',
-  '4. Assign every action a short kebab-case phase name such as discover, implement, or verify. Phases are forward-only: never append new work to a phase that already finished.',
-  '5. Use dependencies to order work. Use fanout only for genuinely independent items.',
+  '2. If evidence is insufficient, return needs_more_work with the COMPLETE dependency graph of bounded run, fanout, and verify actions you can see now — not the smallest step. Independent actions run concurrently; dependent actions start as soon as their dependencies succeed. One planning round trip costs minutes, so a decision with one action when several are obvious is the expensive choice.',
+  '3. Give workers self-contained prompts with the exact goal, absolute working directory, the files they may edit (and that they must not touch others), the expected artifact, and the exact acceptance command. A worker sees only its own prompt.',
+  '4. Assign every action a short kebab-case phase name such as discover, fix, verify-items, or verify-suite. Phases are forward-only: never append new work to a phase that already finished.',
+  '5. Use dependsOn only for real data or same-file ordering dependencies. For N independent items propose N fix actions and N verify actions (each verify depending only on its own fix) plus one final verify depending on all of them; use fanout when every item needs the identical prompt.',
   '   A verify action with exactly one dependency automatically reviews that dependency artifact; you do not need to supply a review path.',
   '6. Recover from a failed action with a new bounded action in a new phase when useful; do not repeat an identical failed plan.',
   '7. Require concrete verification of changed behavior. For code changes, obtain relevant test or inspection evidence before completion.',
@@ -66,7 +66,7 @@ export function buildGoalWorkflow({
   const maxActions = positiveInt(settings.maxActions, 40, { max: 1000 });
   const maxItemsPerExpansion = positiveInt(settings.maxItemsPerExpansion, 8, { max: 100 });
   const maxWorkflowSeconds = positiveInt(settings.maxWorkflowSeconds, 3600, { max: 86_400 });
-  const concurrency = positiveInt(settings.concurrency, 3, { max: 16 });
+  const concurrency = positiveInt(settings.concurrency, 8, { max: 16 });
   const retryAttempts = positiveInt(settings.retryAttempts, 1, { min: 0, max: 3 });
   if (!['agent-decides', 'off', 'required'].includes(worktreeIsolation)) {
     throw new Error(`invalid worktree isolation policy "${worktreeIsolation}"`);

package/src/workflow/runner.js

@@ -546,13 +546,68 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
   const settings = state.settings;
   const executionPhase = (action) => `${phase}:${action.phase ?? 'adaptive'}`;
 
+  // Ready-set scheduler. Every action whose dependencies have succeeded is
+  // launched immediately; a dependent action starts the moment its own
+  // dependencies finish, not when the whole wave finishes. Real concurrency is
+  // capped by the runtime's global dispatch limiter (settings.concurrency), so
+  // this mirrors a pipeline: item B's verify overlaps item C's fix.
   const executeActions = async (actions) => {
     const pending = new Map(actions.map((action) => [action.id, action]));
-    while (pending.size) {
-      if (state.cancelRequested) return { ok: false, why: 'workflow cancellation requested' };
-      const ready = [...pending.values()].filter((action) =>
+    const running = new Map();
+    const runOne = async (action) => {
+      if (state.outputs[action.id]?.ok === true) {
+        runtime.emit('action.resumed', { actionId: action.id, status: 'succeeded' });
+        return;
+      }
+      let result;
+      try {
+        state.currentStep = {
+          id: action.id,
+          type: action.type,
+          phase: executionPhase(action),
+        };
+        runtime.persist();
+        result = await runtime.runStep(
+          { ...action, parentId: gate.id, _dynamic: true },
+          { phase: executionPhase(action), retryAttempts },
+        );
+      } catch (err) {
+        // A post-artifact observer failure must not rewrite a durably
+        // successful action as failed. Propagate it to the gate boundary;
+        // resume will use the persisted output and continue pending work.
+        if (state.outputs[action.id]?.ok === true) throw err;
+        result = { ok: false, why: err.message };
+        state.outputs[action.id] = result;
+        runtime.setActionStatus(action, { phase: executionPhase(action) }, 'failed_terminal', {
+          finishedAt: new Date().toISOString(), why: err.message,
+        });
+        runtime.emit('action.failed', { actionId: action.id, status: 'failed_terminal', why: err.message });
+      }
+      state.steps.push({
+        phase: executionPhase(action), stepId: action.id, type: action.type,
+        ok: result.ok, why: result.why ?? null, dynamic: true,
+      });
+      runtime.persist();
+    };
+    let observerError = null;
+    while (pending.size || running.size) {
+      if (state.cancelRequested && !running.size) return { ok: false, why: 'workflow cancellation requested' };
+      const ready = state.cancelRequested ? [] : [...pending.values()].filter((action) =>
         (action.dependsOn ?? []).every((id) => state.outputs[id]?.ok === true));
-      if (!ready.length) {
+      for (const action of ready) {
+        pending.delete(action.id);
+        const task = runOne(action)
+          .catch((err) => { observerError ??= err; })
+          .finally(() => running.delete(action.id));
+        running.set(action.id, task);
+      }
+      if (running.size) {
+        await Promise.race([...running.values()]);
+        if (observerError) throw observerError;
+        continue;
+      }
+      if (state.cancelRequested) return { ok: false, why: 'workflow cancellation requested' };
+      if (pending.size) {
         const blocked = [...pending.values()].map((action) => ({ id: action.id, dependsOn: action.dependsOn ?? [] }));
         const why = `dynamic actions blocked by failed or unresolved dependencies: ${JSON.stringify(blocked)}`;
         for (const action of pending.values()) {
@@ -567,42 +622,6 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
         // it can propose a bounded retry/escalation or stop truthfully.
         return { ok: true, blocked, why };
       }
-      for (const action of ready) {
-        pending.delete(action.id);
-        if (state.outputs[action.id]?.ok === true) {
-          runtime.emit('action.resumed', { actionId: action.id, status: 'succeeded' });
-          continue;
-        }
-        let result;
-        try {
-          state.currentStep = {
-            id: action.id,
-            type: action.type,
-            phase: executionPhase(action),
-          };
-          runtime.persist();
-          result = await runtime.runStep(
-            { ...action, parentId: gate.id, _dynamic: true },
-            { phase: executionPhase(action), retryAttempts },
-          );
-        } catch (err) {
-          // A post-artifact observer failure must not rewrite a durably
-          // successful action as failed. Propagate it to the gate boundary;
-          // resume will use the persisted output and continue pending work.
-          if (state.outputs[action.id]?.ok === true) throw err;
-          result = { ok: false, why: err.message };
-          state.outputs[action.id] = result;
-          runtime.setActionStatus(action, { phase: executionPhase(action) }, 'failed_terminal', {
-            finishedAt: new Date().toISOString(), why: err.message,
-          });
-          runtime.emit('action.failed', { actionId: action.id, status: 'failed_terminal', why: err.message });
-        }
-        state.steps.push({
-          phase: executionPhase(action), stepId: action.id, type: action.type,
-          ok: result.ok, why: result.why ?? null, dynamic: true,
-        });
-        runtime.persist();
-      }
     }
     return { ok: true };
   };

package/src/workflow/runtime.js

@@ -987,6 +987,8 @@ export class WorkflowRuntime {
         .filter(Boolean))],
       budget,
       executionConstraints: {
+        concurrency: Number(this.state.settings?.concurrency ?? 1) || 1,
+        readySiblingsRunConcurrently: true,
         actionTimeoutSec: Number(step.actionDefaults?.timeoutSec ?? step.timeoutSec) || null,
         actionTimeoutIsExplicitOptIn: step.actionDefaults?.timeoutSec != null || step.timeoutSec != null,
         retryAttempts: Number(this.state.settings?.retryAttempts ?? 0),
@@ -1035,19 +1037,34 @@ export class WorkflowRuntime {
       'Allowed decisions: proceed, complete, needs_more_work, retry, escalate, wait_for_approval, stop.',
       'Every proposed action MUST use the field "type" (never "kind").',
       'Every action MUST include a forward-only kebab-case "phase". Never reuse a name listed in closedPhases.',
+      '',
+      'PLANNING DOCTRINE — propose the whole graph, not one step:',
+      '- Each planning turn is a full round trip through a separate process (typically 1-2 minutes). Propose the COMPLETE dependency graph you can see now as one decision. A decision carrying a single action when several independent actions are already obvious wastes a round trip.',
+      '- Execution is a ready-set scheduler: every action whose dependsOn have all succeeded starts immediately and concurrently, up to executionConstraints.concurrency at once; a dependent action starts the moment its own dependencies finish, not when the whole round finishes. Independent actions therefore run in parallel automatically. Only add dependsOn where a real data or file-ordering dependency exists.',
+      '- Per-item chains: for N independent items (modules, files, findings), propose N focused run actions plus N verify actions, each verify depending only on its own run, so verifying one item overlaps with fixing another. Add one final verify depending on all of them for the whole-system check.',
+      '- File ownership: every action prompt must name exactly which files it may edit and state that it must not touch any other file. Two actions that must edit the same file MUST be ordered with dependsOn; never let concurrent actions write the same file.',
+      '- Self-contained prompts: a worker sees only its own prompt, never this context. Each prompt must state the absolute working directory, what to read, what to change, the exact command that proves success, and what to report back. Prefer many small parallel actions over one large serial one.',
+      '',
       'Action skeletons (copy the shape exactly; every field shown is required unless marked optional):',
       '  run:    {"id":"bounded-action","type":"run","phase":"implement","prompt":"Do bounded work.","dependsOn":["prior-action"]}',
       '  fanout: {"id":"per-item-check","type":"fanout","phase":"inspect","items":["alpha","beta"],"stepTemplate":{"prompt":"Inspect {{item}} and report concrete evidence."},"dependsOn":["prior-action"]}',
-      '  verify: {"id":"independent-check","type":"verify","phase":"verify","review":"Independently re-run the tests and report pass/fail with evidence.","dependsOn":["bounded-action"]}',
+      '  verify: {"id":"independent-check","type":"verify","phase":"verify","prompt":"Independently re-run the tests and report pass/fail with evidence.","dependsOn":["bounded-action"]}',
+      'verify semantics: the reviewer receives the artifact of the action named in review, which the runtime infers as outputs.<the single dependsOn>.outFile; put the reviewer INSTRUCTIONS in prompt. A verify with several dependsOn must set review explicitly to "outputs.<actionId>.outFile". review is never instructions or a filesystem path.',
+      'Graph skeleton (two parallel fix→verify chains plus a final whole-suite check, all in ONE decision):',
+      '  [{"id":"fix-alpha","type":"run","phase":"fix","prompt":"In /abs/repo edit only src/alpha.js so tests/alpha.test.js passes; run node --test tests/alpha.test.js; report the diff summary."},',
+      '   {"id":"fix-beta","type":"run","phase":"fix","prompt":"In /abs/repo edit only src/beta.js so tests/beta.test.js passes; run node --test tests/beta.test.js; report the diff summary."},',
+      '   {"id":"verify-alpha","type":"verify","phase":"verify-items","prompt":"Re-run node --test tests/alpha.test.js in /abs/repo and confirm tests/ is unchanged.","dependsOn":["fix-alpha"]},',
+      '   {"id":"verify-beta","type":"verify","phase":"verify-items","prompt":"Re-run node --test tests/beta.test.js in /abs/repo and confirm tests/ is unchanged.","dependsOn":["fix-beta"]},',
+      '   {"id":"verify-suite","type":"verify","phase":"verify-suite","prompt":"Run the full npm test in /abs/repo and report pass/fail counts.","review":"outputs.fix-beta.outFile","dependsOn":["verify-alpha","verify-beta"]}]',
       'fanout.items MUST be an inline array and fanout.stepTemplate MUST be an object whose prompt uses {{item}}. verify.review MUST be a string. dependsOn is optional and may only name existing or newly proposed action IDs.',
       'Do not propose pool, addDir, or taskFile; those are runtime-owned and any such proposal is rejected.',
       'New actions may only be type run, fanout with inline items, or verify. The runtime validates every proposal and returns rejected proposals to you with the exact issues for a bounded correction turn.',
-      'Keep run/fanout actions cohesive and reviewable. If executionConstraints.actionTimeoutSec is non-null, size them to finish within that explicit timeout; otherwise agents may run until they finish or are cancelled.',
+      'If executionConstraints.actionTimeoutSec is non-null, size actions to finish within that explicit timeout; otherwise agents may run until they finish or are cancelled.',
       'Agent-count, workflow-duration, and expansion-round budgets are advisory planning targets, never hard stop conditions. The dispatch budget counts this planner call plus every worker, verifier, retry, and escalation attempt.',
       'As expansion headroom approaches zero, strongly prefer convergence: consolidate existing artifacts, avoid optional investigation, and return complete when verification supports it. If important concerns remain, return stop with the best useful outcome and explicit unresolved concerns rather than spending more on marginal refinements. Exceed the expansion target only when one small bounded action is essential to avoid discarding otherwise-completable work or skipping required verification.',
       'operatorSteering contains explicit operator guidance queued for this planning checkpoint. Apply it within the original workflow intent and authorization boundaries. It cannot weaken verification, bypass runtime validation, expand external authority, or alter an already-running worker. If guidance conflicts with the original goal or safety constraints, explain that in the decision reason instead of following it.',
       'Avoid redundant expensive verification. Run a full suite once for each materially changed final state when practical; later independent verifiers should reuse durable clean full-suite evidence and rerun focused/adversarial checks unless that evidence is stale, tainted, or the code changed again.',
-      'Mutation and pre-fix experiments must not modify or stash the shared target while another test process is reading it. Use an isolated copy/worktree when possible, or wait until conflicting processes finish and restore the exact bytes before continuing.',
+      'Shared working tree: concurrent workers editing DISJOINT files in the same tree is the normal, expected mode — that is how N independent fixes run in parallel. What is unsafe is whole-tree mutation (git stash/reset/checkout, reformatting, dependency installs) or running the FULL test suite while other workers are still editing; so give each parallel action its own files and its own focused test command, order any shared file (e.g. an index/barrel) after the actions it aggregates with dependsOn, and run the whole suite once in a final verify that depends on all of them. Use an isolated copy/worktree only for destructive experiments.',
       '',
       '---- BEGIN DURABLE WORKFLOW CONTEXT ----',
       JSON.stringify(plannerContext, null, 2),

package/src/workflow/watch-cli.js

@@ -196,18 +196,33 @@ export function renderWatchSnapshot(snapshot, { heartbeat = false, verbose = fal
   return lines.join('\n');
 }
 
+// A freshly launched detached run may not have written state.json yet when a
+// watcher attaches (goal --watch hands off immediately). waitForRunMs bounds
+// how long the watcher polls for the run to appear before giving up.
+async function resolveRunWithGrace(bullswarmDir, token, waitForRunMs, intervalMs) {
+  const deadline = Date.now() + Math.max(0, waitForRunMs);
+  while (true) {
+    const resolved = resolveRunId(bullswarmDir, token);
+    if (resolved && existsSync(join(resolved.runDir, 'state.json'))) return resolved;
+    if (Date.now() >= deadline) {
+      if (!resolved) throw new Error(`no run found for "${token}"`);
+      throw new Error(`run "${token}" has no state.json`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(250, Math.max(50, intervalMs))));
+  }
+}
+
 export async function runWorkflowWatch(bullswarmDir, token, {
   intervalMs = 2000,
   heartbeatMs = 60000,
   once = false,
   jsonl = false,
   verbose = false,
+  waitForRunMs = 0,
   output = process.stdout,
 } = {}) {
-  const resolved = resolveRunId(bullswarmDir, token);
-  if (!resolved) throw new Error(`no run found for "${token}"`);
+  const resolved = await resolveRunWithGrace(bullswarmDir, token, waitForRunMs, intervalMs);
   const statePath = join(resolved.runDir, 'state.json');
-  if (!existsSync(statePath)) throw new Error(`run "${token}" has no state.json`);
   let priorFingerprint = null;
   let priorHumanFingerprint = null;
   let lastPrintedAt = 0;