bullswarm 0.4.0 → 0.9.0

package/AGENTS.md

@@ -17,14 +17,52 @@ content. Published as `bullswarm` on npm.
 3. Connector quirks live in `connectors/*.json`, never in core logic.
 4. Quarantine always auto-releases; recursion depth is core-owned via env
    (`BULLSWARM_DEPTH`).
+5. Workflow dispatches must honor the same guarantees as single runs:
+   `BULLSWARM_DEPTH` is propagated, burst-gated pools are excluded, and
+   auth verdicts quarantine the pool + append to the shared decision log
+   (R6/R7/R8 in `src/workflow/runtime.js`).
+6. Adversarial verification is a first-class primitive: a `verify` step
+   reads a prior outFile and demands a JSON `{ok, concerns, summary}`
+   verdict before downstream steps can trust the work (R-skeptic).
+7. Workflows can be built incrementally from the shell
+   (`bullswarm workflow draft create/phase/step/set/...`). Drafts are
+   stored under `~/.bullswarm/drafts/<name>/` and are runnable by name
+   without an upfront JSON. JSON is still the durable artifact — drafts
+   are JSON documents, just built one mutation at a time.
+8. Goal-driven execution is zero-graph by default: `bullswarm workflow goal`
+   internalizes the planner contract, chooses the orchestrator and workers,
+   persists the generated workflow, and can detach so observation never
+   depends on the initiating agent or CLI process.
 
 ## Development
 
 ```bash
-npm test            # 61+ tests, no network needed (meters read from cache)
+npm test            # 195 tests, 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
+node bin/bullswarm.js workflow runs --all   # including historical
+node bin/bullswarm.js workflow validate <file>  # dry-run
+BULLSWARM_HOME=/tmp/bs node bin/bullswarm.js workflow run <file>   # sandboxed run
+# Build a workflow from the shell:
+bullswarm workflow draft create my-audit
+bullswarm workflow draft phase add my-audit discover
+bullswarm workflow draft step add my-audit discover list-files --type run --prompt 'List files'
+bullswarm workflow draft run my-audit
+# Operate on a run by shortId (6 chars) or full runId (`wf-...`):
+bullswarm workflow runs show <shortId>
+bullswarm workflow runs delete <shortId> --yes
 ```
 
+## Using bullswarm from another agent
+
+If you are an agent that wants to offload bounded work via bullswarm,
+read `skill/SKILL.md` — that's the agent-facing user guide. It covers
+when to reach for `run` vs `workflow draft`, the verify-step pattern,
+how to write prompts that pass the content gate, and the failure modes
+you'll hit. The skill is published alongside the package and is the
+canonical reference for the CLI surface.
+
 - Zero runtime dependencies. Node >= 18. Tests must never require network:
   prime `~/.bullswarm/meters/*.json` caches with fresh timestamps if needed.
 - Every verb must work non-interactively (no TTY). The interactive wizard is

package/CHANGELOG.md

@@ -0,0 +1,202 @@
+# bullswarm changelog
+
+## 0.9.0 — resilient dynamic workflow routing
+
+- Added cooperative `SIGTERM`/`SIGINT` handling, durable `interrupted` states,
+  dead/stale owner reconciliation, and clean resume after interruption.
+- Added capability-context filtering for model recommendations plus an explicit
+  `strategy apply --yes` approval gate and TTL-based automatic refresh.
+- Added setup-time worktree policy and strategy-autopilot choices.
+- Added per-attempt routing reasons/candidate surplus to durable events, state,
+  decision logs, and the printable workflow tree.
+- Added top-level `runs` and `--version` aliases, complete `workflow goal`
+  budget help, and correct phase/terminal display for completed runs.
+
+## 0.8.0 — autonomous goals, model strategy, and auditable usage
+
+- Added `workflow goal` for bounded observe-plan-execute loops without an
+  upfront graph, including planner-owned expansion, completion policy,
+  detachment, resume, cancellation, ordered events, and durable action and
+  attempt ledgers.
+- Added first-class `decide` and adversarial `verify` actions with strict JSON
+  contracts, capability-aware routing, bounded retries/escalation, and hard
+  expansion/dispatch/time limits.
+- Added `strategy refresh/show/set-subscription/assign` to discover models from
+  installed CLIs, combine connector-owned dated price/benchmark metadata with
+  live quota surplus, and persist high/medium/low effort preferences.
+- Added connector-owned model selection plus `--effort` routing for ordinary
+  runs and workflow actions. Safety eligibility always overrides preferences.
+- Added per-attempt agent/model, standard-read/cache-read/cache-write/output
+  token estimates, API-equivalent cost, subscription-normalized quota, and
+  honest partial totals when a provider omits model or usage data.
+- Added `workflow tui <runId>` as a printable historical phase/action/attempt
+  tree in both TTY and non-TTY environments, alongside JSON state/events.
+- Expanded the offline suite to 195 tests. A fresh-home real-provider trial
+  autonomously fixed and independently verified a failing Node fixture; a
+  deliberately undersized dispatch budget also stopped truthfully rather than
+  claiming completion.
+
+## 0.7.0 — short run IDs + workflow runs
+
+Workflow runs were opaque (`wf-mtapqmfm-ad9ba7` everywhere) and
+there was no way to list or operate on past runs except by
+file-system diving. v0.7.0 adds:
+
+- **6-character short IDs** (Crockford-style 32-char alphabet, no
+  `0/1/i/l/o` for visual clarity). Every new run gets a `shortId`
+  on both `state.json` and `report.json`. The full `wf-...` runId
+  stays the durable handle.
+- **`bullswarm workflow runs ...`** sub-verb:
+  - `runs` (default = ongoing only) — list with a `●`/`○` marker
+  - `runs --all` — ongoing + historical
+  - `runs --historical` — only historical
+  - `runs --name <wf>` — filter by workflow
+  - `runs --limit N` — cap result count
+  - `runs show <id>` — dump `state.json` + `report.json`. Accepts
+    shortId, full runId, or run-dir path.
+  - `runs delete <id> --yes` — remove a run directory. Refuses
+    ongoing runs without `--force`.
+- **Resume by short ID**: `bullswarm workflow run <wf> --resume
+  <shortId>` resolves the shortId to the full runId before any
+  dispatch. Bogus tokens fail fast, before workflow load.
+- **`isOngoing(runDir, state)`** helper: classifies a run as
+  ongoing when `state.finishedAt` is unset AND `state.json` was
+  modified within the last 90 s. After the 90 s window a run is
+  treated as historical even if `finishedAt` was never written
+  (e.g. process killed before terminal `persist()`).
+
+### New files
+
+- `src/workflow/short-id.js` — Crockford-style generator, resolver,
+  `isOngoing`, `listRuns`
+- `src/workflow/runs-cli.js` — `cmdRuns` dispatch
+- `tests/workflow-runs.test.js` — 16 new tests
+
+### Tests
+
+- 16 new tests covering shortId generation, resolution, lock-free
+  ongoing detection, list filtering, show, delete, and the resume
+  pre-flight.
+- Full suite is 147 green (131 prior + 16 new), stable across 3
+  stress runs.
+- Verified end-to-end by `cmd -p --yolo` against a real CLI
+  installation: every step of the runbook passed.
+
+## 0.6.0 — incremental workflow drafts (CLI builder)
+
+The static `workflow run <file>` shape required every workflow to be
+authored as a JSON file in advance. That's not "dynamic" — it's a script
+of record. v0.6.0 introduces `bullswarm workflow draft ...`, a
+sub-verb group that lets you build a workflow interactively from the
+shell, one mutation at a time. Drafts persist under
+`~/.bullswarm/drafts/<name>/` and are promoted to first-class
+workflows (discoverable, runnable by name, validatable) the moment
+they're created.
+
+### New CLI surface
+
+```
+bullswarm workflow draft create <name> [--description ...] [--input k=v]...
+bullswarm workflow draft show <name>
+bullswarm workflow draft list
+bullswarm workflow draft phase add <name> <phase>
+bullswarm workflow draft phase remove <name> <phase>
+bullswarm workflow draft step add <name> <phase> <step-id> --type run|fanout|verify [--lane ... --prompt ... --add-dir ... --pool ... --items-from ... --review ... --concurrency N --timeout N --on-error ... --step-template <json>]
+bullswarm workflow draft step remove <name> <phase> <step-id>
+bullswarm workflow draft step set <name> <phase> <step-id> <field> --value <text>
+bullswarm workflow draft set <name> <field> --value <text>
+bullswarm workflow draft validate <name>
+bullswarm workflow draft export <name> <out-file>
+bullswarm workflow draft delete <name> --yes
+bullswarm workflow draft run <name> [--input k=v]... [--resume id] [--json] [--quiet]
+```
+
+- Every mutation re-validates immediately and persists the verdict on
+  `meta.json.lastValidation`. `bullswarm workflow list` shows drafts
+  with a `(draft)` tag.
+- `bullswarm workflow run <draft-name>` and `workflow validate
+  <draft-name>` accept a draft name the same way they accept a JSON
+  filename — the new `workflowDirs()` entry `~/.bullswarm/drafts/`
+  makes drafts first-class.
+- `bullswarm workflow draft export <name> <file>` promotes a draft
+  to a checked-in JSON for version control.
+- Partial drafts (zero phases, or a phase with zero steps) are
+  treated as BUILDING, not INVALID — the validator's
+  `phases-must-be-non-empty` rule is downgraded to a warning during
+  construction. Real schema violations (bad lane, duplicate step id,
+  etc.) still return nonzero.
+- `delete` requires `--yes` so a stray arrow-key can't nuke a draft.
+- The `BULLSWARM_HOME` env var redirects drafts to a sandbox under
+  any temp dir, so the same `autoSetup` flow agents use elsewhere
+  works here.
+
+### Tests
+
+- 25 new tests in `tests/workflow-draft.test.js`. Two layers:
+  module-level (no spawn) for every mutation, CLI-level (spawnSync)
+  for the user-facing contract.
+- Full suite is now 131 green (106 prior + 25 new).
+
+### Files
+
+- New: `src/workflow/draft.js` — storage, atomic writes, validation hook
+- New: `src/workflow/draft-cli.js` — `cmdDraft` dispatch + flag parsing
+- New: `tests/workflow-draft.test.js`
+- Modified: `src/workflow/cli.js` (added `draft` sub-verb, drafts in
+  `workflowDirs()` and `discover()`)
+
+## 0.5.0 — gap-closure release
+
+Workflow parity with Claude Code dynamic workflows plus deep-QA hardening.
+All 10 gaps identified in the v0.4.0 audit are closed; 23 new tests
+added; full suite is 105 green (82 prior + 23 new).
+
+### Workflow runtime (R-numbered doctrine)
+
+- **R4 — global concurrency limiter**: a real `Semaphore` (`src/workflow/semaphore.js`) is shared by every `runSingle` and every fanout worker. Per-fanout worker count is capped at `min(per-fanout, limiter.permits, items.length)`. A `step.blocked` event fires when items queue behind the cap.
+- **R6 — recursion-guard propagation**: every workflow dispatch computes `childDepthEnv(parentEnv)` and passes it to `watchOnce`. The runtime asserts `assertDepthAllowed(coreState, parentEnv)` before each dispatch. A workflow that itself spawns `bullswarm` is refused at the core's depth limit instead of recursing forever. `src/lib/watch.js` now honors caller-supplied `opts.env` so the depth env actually reaches the child.
+- **R7 — quarantine + decision log on workflow auth failures**: when a dispatch inside a workflow returns `quarantineHint: true`, the runtime calls `quarantinePool(state, poolName, why, now)` against the core state file and appends a `source: "workflow"` entry to the shared `decisionLog` so `bullswarm health` and `pools` see workflow runs. The live `pools` view is updated so the next dispatch in the same run does not re-select the benched pool.
+- **R8 — burst-gate exclusion in workflows**: `preparePools` now drops any pool with `burstGate === true` (5h ≥ 90 %), matching the single-run path.
+- **R10 — fingerprint-aligned fanout resume**: every fanout result is now stamped with `sha1(JSON.stringify(item)).slice(0,12)`. On resume, items are matched by fingerprint first; positional alignment is a fallback for state.json from prior versions. Reordering, adding, or removing items no longer breaks resume.
+- **R9 — outputText truncation**: `recordOutput` caps `state.outputs[id].outputText` at `OUTPUT_TEXT_CAP_BYTES = 64 KB`. The on-disk outFile always holds the full transcript. Persisted state.json is now bounded.
+
+### New step type: `verify` (skeptic)
+
+- Adversarial review of a prior step. Schema: `{ type: "verify", review: "outputs.<prior>.outFile", lane, prompt?, timeoutSec? }`. The runtime reads the prior outFile, inlines it into a structured prompt asking for `RETURN ONLY {"ok": <bool>, "concerns": [...], "summary": ...}`, dispatches through the standard pool-routed pipeline, and parses the first JSON object in the response. Step is `ok:true` only if dispatch verifies AND the JSON `ok` is `true`. The parsed `verify` object is recorded on `state.outputs[id].verify` so downstream steps can reference `concerns` and `summary`.
+- Validated: `review` must resolve to a known prior outFile or a declared input; `inputs.<k>.required` is now type-checked and runtime-enforced.
+- See `workflows/verify-and-cap.json` for an end-to-end example.
+
+### New settings
+
+- `settings.maxAgents` — hard cap; a step that would push dispatch count past the cap fails with `why: "spend guard: maxAgents=... reached"`.
+- `settings.warnAtAgents` — advisory; a `workflow.large` event fires once when the threshold is crossed. TUI renders it as `⚠ Large workflow: N dispatches ≥ threshold M`.
+- `settings.concurrency` is now validated to be `≤ 16`, matching Claude Code's runtime cap.
+- `inputs.<k>.required: true` is now a hard pre-flight refusal. `runWorkflow` throws `required input "<k>" missing` before any dispatch.
+
+### New runtime events
+
+- `item.skipped` — emitted by fanout resume; was dropped silently in TTY mode. Now rendered as `⏭ <stepId>[i]   ok from previous run (resume)`.
+- `step.blocked` — emitted when items queue behind the global cap; rendered as `⋈ N item(s) queued behind concurrency cap in <stepId>`.
+- `workflow.large` — emitted once when the dispatch threshold is crossed.
+
+### CLI
+
+- `BULLSWARM_HOME` env var now overrides the workflow CLI's `BULLSWARM_DIR` (previously hardcoded to `~/.bullswarm`). Matches the meter registry.
+- `--input k=v` accepts JSON-encoded values so arrays and objects can be passed: `--input 'items=["a","b"]'`. The legacy string form is unchanged.
+
+### TUI
+
+- `item.skipped`, `step.blocked`, and `workflow.large` are all rendered in human mode (previously `item.skipped` was TTY-invisible).
+
+### Tests
+
+- 23 new tests in `tests/workflow-gaps.test.js`, one per gap closure.
+- 105 total tests, all green, no network, ~1 s.
+
+### Files
+
+- New: `src/workflow/semaphore.js`
+- New: `tests/workflow-gaps.test.js`
+- New: `workflows/verify-and-cap.json`
+- New: `CHANGELOG.md`
+- Modified: `src/workflow/runtime.js`, `src/workflow/runner.js`, `src/workflow/validate.js`, `src/workflow/tui.js`, `src/workflow/cli.js`, `src/lib/watch.js`

package/GOAL.md

@@ -0,0 +1,135 @@
+# bullswarm — Goal Statement
+
+**Status:** PROTOTYPE · **Owner:** cowcow02 · **Created:** 2026-08-21
+
+## One sentence
+
+A standalone CLI that lets *any* coding agent offload work to *any other* coding
+agent CLI on the same machine — routing by lane, pacing by subscription meter,
+and verifying by content — so no provider's quota expires unused and no agent's
+"success" is taken at face value.
+
+## Why this exists
+
+Every agent CLI assumes it is the center of the universe. Multi-subscription
+developers (Claude Max + Codex + Grok + …) watch quota expire on some pools
+while others are exhausted mid-task, and every delegate CLI can exit 0 while
+having done nothing. No existing router treats subscription windows as the
+scheduling resource; proxy routers spend API credits instead of subscriptions;
+prompt-policy layers can't compel dispatch. bullswarm sits *above* all agents as
+the neutral coordinator vendors will never build.
+
+## Outcome
+
+A working prototype installed at `~/.bullswarm/` with:
+
+1. **`bullswarm` CLI** with four verbs (`setup` detailed in #8):
+   - `setup` — interactive front door: discover → enable → route → write
+   - `run` — route → dispatch → watch → verify → one JSON verdict
+     (`ok`, `keepOnClaude`, `why`, `pick.command`, `contentUsableDespiteExit`)
+   - `health` — re-judge saved outputs against verdicts; surface gate failures
+     and quarantine clusters after every round
+   - `pools` — show each pool's meter state, pace position, quarantine status
+2. **Connector registry** (`~/.bullswarm/connectors/*.json`): declarative per-CLI
+   spawn command, auth-failure signatures, output extraction, verify contract,
+   quirk fields (e.g. PWD resolution). Seeded with codex, grok,
+   command-code, opencode2 — extracted from the proven `/offload` skill.
+3. **Meter layer**: per-pool window definition (5h / weekly / none) with
+   programmatic readers where providers expose usage, manual declaration
+   (`--meter pool=window,pct`) where they don't. Unmetered pools pace as
+   time-proportional and are labeled as such.
+4. **Pacing brain**: time-adjusted pace (elapsed% − used%; most-behind wins),
+   incumbency margin, cost guard (pace may only promote a cheaper pool),
+   lanes by work nature (analyze/build/chore) — never a hard-coded lane→pool map.
+5. **Verify gate**: content-based judgment ported intact from delegate-watch —
+   exit code never trusted alone, announcement-vs-work splitting, failure
+   patterns scoped to first 400 chars (whole text under 600), fixture suite
+   green before any release.
+6. **Recursion guard**: depth limit owned by the core; an offloaded agent that
+   calls bullswarm cannot exceed configured depth.
+7. **MCP server**: exposes `run`/`health`/`pools` so Claude Code, Codex, Cursor
+   or any MCP client can offload without shell plumbing.
+8. **Setup wizard as the front door**: bare `bullswarm` with no config (or
+   `bullswarm setup`) launches an interactive guide that:
+   - **discovers** installed agent CLIs (binary on PATH + config dir present +
+     cheap auth probe — never credential entry), showing quota/burn-rate state
+     per pool immediately; burn rate starts empty and is labeled "learning"
+     until the decision log fills it;
+   - lets the user **toggle which discovered pools to enable**;
+   - **suggests a routing table** (lane → pool defaults from enabled pools)
+     presented as an editable artifact, not a questionnaire;
+   - writes `~/.bullswarm/` config + connectors, idempotent and re-runnable
+     (`bullswarm setup` repairs);
+   - can generate an agent-facing integration block for CLAUDE.md / AGENTS.md,
+     shown as a diff with explicit approval before any write, delimited by
+     versioned `bullswarm:begin/end` markers (pilotfish pattern);
+   - a thin companion skill (`bullswarm-setup`) ships alongside so agents can
+     recommend running `/bullswarm:setup` to users — the skill nudges, the CLI
+     owns the flow.
+
+## Success proofs
+
+The prototype is done when ALL hold:
+
+- [x] `bullswarm run --lane analyze --add-dir <repo> --task-file t.md --json`
+      returns a verdict whose shape matches the delegate-watch contract, using
+      a real pool, end to end, on this machine.
+- [x] The verify gate passes its full fixture suite (≥17 fixtures:
+      true failures AND real outputs) unchanged in behavior vs. `/offload`.
+- [x] `bullswarm pools` reflects a manually declared meter change within one
+      run, and pace ordering flips the pick when a pool crosses the margin.
+- [x] A wrong-repo scenario (stale PWD) produces a correct-repo dispatch for
+      every connector whose quirk field declares it.
+- [x] `bullswarm health` flags a planted FAILED-verdict-but-good-output case
+      and a two-quarantine cluster.
+- [x] An MCP client (Claude Code) completes one offload round via the MCP
+      server with zero shell commands.
+- [x] Recursion guard stops a self-calling delegate at the configured depth.
+- [x] Bare `bullswarm` on a machine with no `~/.bullswarm/` launches the
+      wizard; discovery lists at least the four seeded connectors with correct
+      found/not-found status, and completing it produces a working `run`.
+- [x] The wizard's CLAUDE.md/AGENTS.md integration step shows a diff and
+      writes nothing without explicit approval; re-running setup is idempotent
+      (no duplicate marker blocks).
+- [x] `bullswarm setup` on an already-configured machine reports current state
+      and repairs a deliberately broken connector file.
+
+## Invariants
+
+- Judge by CONTENT, not exit code. A non-zero exit is never a success;
+  `ok:true` requires passing verification.
+- Never hard-code lane→pool mappings; pools serve lanes only via runtime
+  selection over declared capability.
+- Delegate output is input to verify, never the answer. Final synthesis,
+  architecture decisions, and anything needing live conversation context stay
+  with the caller.
+- Quarantine must have a re-probe path; a recovered pool must return to
+  service automatically (this fixes the known `/offload` gap).
+- Connector quirks live in connector files, never in core logic.
+- Stealth/retention-hostile models are opt-in per connector, flagged in the
+  registry, never defaults.
+
+## Non-goals (prototype)
+
+- No hosted service, no daemon required for basic operation.
+- No per-host hook integrations beyond MCP.
+- No measured routing table yet (smart-router-style pass@k benchmarking is
+  post-prototype).
+- No savings ledger yet (post-prototype).
+- Windows support deferred; macOS/Linux first.
+
+## Authority envelope
+
+Build freely inside `~/Repo/bullswarm`. Installing to `~/.bullswarm/` and
+reading existing `~/.claude/skills/offload/*` sources for extraction is
+authorized. Do NOT modify the live `/offload` skill during extraction — copy,
+never move. No publishing (npm/GitHub push) without explicit instruction.
+
+## Provenance
+
+Extracted from the working `/offload` system (~/.claude/skills/offload/):
+delegate-route.mjs (routing brain), delegate-watch.mjs (verify+watch),
+delegate-health.mjs (re-judging), SKILL.md (operational doctrine). The four
+2026-08-21 failure modes (wrong-repo silence, three verify-gate bugs, invisible
+workflow health, exit-1-after-success) are the regression baseline this
+prototype must never reintroduce.

package/README.md

@@ -1,8 +1,9 @@
 # bullswarm
 
-Route work across coding-agent CLIs. The frontier agent keeps orchestration,
-judgment, and synthesis; bounded work goes to whichever subscription has the
-most quota left; every delegate output is judged by content before it counts.
+Route work across coding-agent CLIs. For a goal, Bullswarm can choose a capable
+orchestrator, build and expand the plan, route bounded worker actions by quota,
+verify the result, and finish without an initiating agent authoring a graph.
+Every delegate output is judged by content before it counts.
 
 ## The doctrine (non-negotiable)
 
@@ -12,9 +13,9 @@ most quota left; every delegate output is judged by content before it counts.
 2. **Pace by meter.** The scheduling resource is the subscription window:
    elapsed% minus used%, most-behind pool wins. Pace may only promote a
    *cheaper* pool. Lanes are work-nature, never hard-coded to pools.
-3. **Delegate output is input, never the answer.** Final synthesis,
-   architecture decisions, and anything needing live conversation context
-   stays with the caller.
+3. **Delegate output is evidence, never authority.** A goal orchestrator may
+   synthesize completion, but only after the deterministic runtime accepts its
+   bounded plan and durable verification evidence.
 4. **Quarantine re-probes.** A benched pool must be able to return to service
    automatically; a lane is never allowed to silently go down.
 
@@ -30,7 +31,9 @@ npm install -g bullswarm   # or: node bin/bullswarm.js directly from a checkout
 bullswarm          # first run: interactive setup wizard
 bullswarm setup    # re-run or repair
 bullswarm pools    # meter state, pace position, quarantine status
+bullswarm strategy refresh --apply --yes  # approve capability-aware tier autopilot
 bullswarm run --lane analyze --add-dir ~/some-repo --task-file /tmp/t.md --json
+bullswarm workflow goal "Fix the failing tests and verify the change" --cwd ~/some-repo
 bullswarm health   # re-judge saved outputs; catch gate failures
 ```
 
@@ -42,6 +45,220 @@ bullswarm health   # re-judge saved outputs; catch gate failures
 | `run` | route → dispatch → watch → verify → one JSON verdict |
 | `health` | Re-judge saved outputs against their verdicts; surface verify-gate failures and quarantine clusters |
 | `pools` | Show each pool's meter state, pace position, quarantine status |
+| `strategy` | Discover models, record subscription value, recommend or assign high/medium/low effort routes |
+| `doctor` | Machine-readable readiness report; self-heals on first call |
+| `workflow` | Start an autonomous goal, or run / validate / draft / inspect explicit workflows and their live instances. |
+
+## Model strategy and invocation telemetry
+
+Bullswarm can inventory the models exposed by installed agent CLIs and combine
+connector-declared, dated pricing/benchmark metadata with live quota surplus:
+
+```bash
+bullswarm strategy refresh
+bullswarm strategy show --json
+bullswarm strategy apply --yes --refresh-hours 24
+bullswarm strategy auto status
+bullswarm strategy set-subscription command-code \
+  --plan GOAT --monthly-usd 10 --included-usd 70 --quota-window monthly
+bullswarm strategy assign high --pool claude-code --model claude-opus-4-6
+bullswarm run --effort high --lane analyze --task-file /tmp/task.md --json
+```
+
+Interactive setup asks whether to enable strategy autopilot; non-interactive
+setup requires the explicit `setup --yes --strategy` flag. Recommendations are
+context-filtered before ranking: high requires analysis plus workflow-planning,
+medium requires build/edit capabilities, and low targets bounded chores. An
+approved policy refreshes stale discovery before later runs and re-applies the
+best eligible models on its configured interval. Disable it with
+`strategy auto off --yes`. Discovery commands, model argument syntax, pricing,
+and benchmark declarations remain connector-owned. Unknown license value,
+prices, and benchmarks stay `null` rather than being guessed. An assignment is
+only a preference: quarantine, exhaustion, burst gates, and capability checks
+still win.
+
+Every run and workflow attempt reports its selected agent/model and estimated
+usage. When a delegate does not expose counters, Bullswarm labels its UTF-8
+byte/4 token estimate. The breakdown separates standard read, cache read,
+cache write, and output; API-equivalent cost and normalized subscription quota
+remain unknown unless the connector and user-provided subscription data can
+support them. `workflow tui --json <id>` exposes the aggregate and the full
+phase/step/attempt tree.
+
+## One-command autonomous goals
+
+For normal multi-step work, give Bullswarm the goal—not a JSON graph:
+
+```bash
+# Foreground: streams progress and returns when terminal.
+bullswarm workflow goal \
+  "Fix the failing tests with the smallest correct change and verify them" \
+  --cwd ~/some-repo
+
+# Detached: the initiating CLI exits; the workflow continues independently.
+bullswarm workflow goal \
+  "Audit and repair the parser, then run its acceptance tests" \
+  --cwd ~/some-repo --detach --json
+```
+
+Bullswarm first honors an approved high-tier provider/model assignment when it
+remains eligible, otherwise it selects an eligible `workflow-planning`
+orchestrator by live quota surplus. The orchestrator observes durable evidence, proposes bounded actions,
+and decides when another expansion or verification is necessary. Bullswarm
+validates the proposal, owns agent/process selection, routes workers, and calls
+the orchestrator again until completion, cancellation, failure, approval, or a
+budget limit. No initial phases, prompts, JSON schema, or agent choice are
+required from the user.
+
+The detached response includes a short ID and exact observation commands:
+
+```bash
+bullswarm workflow runs show <shortId>
+bullswarm workflow tui <shortId>          # printable phase/action/attempt tree
+bullswarm workflow tui --json <shortId>
+bullswarm workflow events --json <shortId> --after 0
+bullswarm workflow action show --json <shortId> <actionId>
+```
+
+Resume a process-interrupted autonomous run from its persisted workflow:
+
+```bash
+bullswarm workflow goal --resume <shortId> --json
+```
+
+`--orchestrator <pool>` exists for controlled testing; ordinary use should
+leave selection on `auto`. Hard limits can be adjusted with `--max-agents`,
+`--max-expansion-rounds`, `--max-actions`, `--max-items-per-expansion`, and
+`--max-workflow-seconds`. Interactive setup also records a worktree-isolation
+preference (`agent-decides`, `off`, or `required`); Bullswarm communicates that
+policy to the orchestrator without imposing repository topology itself.
+
+## Building a workflow from the shell
+
+Use an explicit draft when the graph itself is a durable contract and should
+not be planner-defined. `bullswarm workflow draft ...` lets you assemble it one
+mutation at a time. No upfront JSON required. Drafts persist under
+`~/.bullswarm/drafts/<name>/` and become first-class workflows
+(discoverable, runnable by name) the moment they exist.
+
+```bash
+bullswarm workflow draft create audit-code \
+    --description "Audit the source code" --input targetDir=.
+bullswarm workflow draft phase add audit-code discover
+bullswarm workflow draft phase add audit-code review
+bullswarm workflow draft step add audit-code discover list-files \
+    --type run --lane chore --prompt "List every .js file in src/" \
+    --addDir '{{inputs.targetDir}}'
+bullswarm workflow draft step add audit-code review per-file \
+    --type fanout --items-from 'outputs.list-files.outFile' \
+    --lane analyze --concurrency 2 \
+    --step-template '{"lane":"analyze","addDir":"{{inputs.targetDir}}","prompt":"Review {{item}}"}'
+bullswarm workflow draft show audit-code    # inspect the JSON
+bullswarm workflow draft run audit-code     # execute it
+bullswarm workflow draft export audit-code workflows/audit-code.json   # promote to file
+```
+
+`step add` re-validates after every mutation; partial drafts (zero
+phases, etc.) are treated as building, not invalid. `set` and
+`step set` patch fields in place. `delete` requires `--yes`.
+
+## Operating on workflow runs
+
+Every run gets a 6-character shortId (Crockford-style alphabet,
+no `0/1/i/l/o`). The full `wf-...` runId stays the durable handle.
+
+```bash
+bullswarm workflow runs                    # ongoing only (default)
+bullswarm workflow runs --all              # ongoing + historical
+bullswarm workflow runs --historical       # only historical
+bullswarm workflow runs --name audit-code  # filter by workflow
+bullswarm workflow runs --limit 20         # cap the result count
+bullswarm workflow runs show <shortId>     # state + report + summary
+bullswarm runs show <shortId>              # top-level shorthand
+bullswarm workflow runs delete <shortId> --yes    # remove the run dir
+
+# Resume by shortId — runs the same logic as the full runId
+bullswarm workflow run audit-code --resume <shortId>
+```
+
+### Live workflow dashboard
+
+`workflow tui` is the interactive, Claude-style `/workflows` view. It watches
+ongoing runs from disk and supports `j`/`k` or arrow-key selection, Enter for
+details, `c` to request a cooperative stop, `r` to refresh, and `q` to quit.
+
+```bash
+bullswarm workflow tui
+```
+
+The same dashboard is agent-friendly and never requires a TTY when used with
+JSON/control flags:
+
+```bash
+bullswarm workflow tui --json                 # ongoing dashboard rows
+bullswarm workflow tui --json --all           # ongoing + historical runs
+bullswarm workflow tui --json <shortId>       # inspect one run
+bullswarm workflow tui --json --cancel <id>   # request cooperative stop
+bullswarm workflow capabilities --json       # pools, lanes, models, meters, limits
+bullswarm workflow inspect <file-or-name>     # workflow shape and semantics
+bullswarm workflow events --json <id> --after 20
+bullswarm workflow action show --json <id> <actionId>
+bullswarm workflow approval approve --json <id>  # then resume the run
+```
+
+Cancellation is persisted as `cancelling`, terminates an active child process,
+records its termination signal and latency evidence, then commits `cancelled`.
+`SIGTERM` and `SIGINT` use the same cooperative child termination path but
+commit a distinct resumable `interrupted` state. On every workflow command,
+active states with a dead/stale owner are automatically reconciled to
+`interrupted` instead of remaining falsely `running`.
+
+Each attempt records the phase/action, selected pool and model, effort tier,
+routing reason, all eligible candidates with quota surplus, timestamps,
+artifact paths, outcome, and reported-or-estimated token/cost/quota usage.
+`workflow tui <id>` renders this breakdown for completed runs as well as live
+ones; `workflow tui --json <id>` exposes the durable audit document.
+
+### Adaptive workflows
+
+Static workflows remain zero-extra-LLM orchestration. An adaptive workflow adds
+an explicit `decide` step and hard limits:
+
+```json
+{
+  "mode": "adaptive",
+  "settings": {
+    "maxAgents": 12,
+    "maxExpansionRounds": 3,
+    "maxActions": 20,
+    "maxItemsPerExpansion": 8,
+    "maxWorkflowSeconds": 1800
+  },
+  "phases": [{
+    "name": "review",
+    "steps": [
+      { "id": "initial", "type": "run", "prompt": "Inspect the code." },
+      {
+        "id": "planner",
+        "type": "decide",
+        "requiresCapabilities": ["workflow-planning", "strong-analysis"],
+        "prompt": "Judge sufficiency and propose only bounded missing work."
+      }
+    ]
+  }]
+}
+```
+
+The planner returns versioned JSON. It may propose `needs_more_work` with
+bounded `run`, inline-`fanout`, or `verify` actions. The deterministic runtime
+validates IDs, dependencies, operation types, capabilities, and budgets before
+appending anything. It executes ready actions, observes their durable results,
+and calls the planner again. `events.jsonl`, `state.json`, the TUI, and JSON
+inspection expose the same plan, actions, attempts, decisions, budgets, and
+artifacts. See `workflows/adaptive-code-review.json` for a complete example.
+Planner actions cannot set `pool`, `addDir`, or `taskFile`. If those need to be
+fixed by the initiator, declare them under the `decide` step's `actionDefaults`;
+otherwise eligible capable pools are ranked by live quota surplus.
 
 ## The verdict