bullswarm 0.19.0 → 0.20.0

package/AGENTS.md

@@ -57,18 +57,21 @@ 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.
+read `skill/SKILL.md` — that's the agent-facing user guide. Use
+`bullswarm delegate` (or the installed `/bullswarm` skill) by default: it
+previews whether one bounded agent or an autonomous workflow is appropriate,
+shows the conceptual plan, and executes the chosen engine. Reach for `run`,
+`workflow goal`, or a fixed workflow graph directly only when the caller has
+already chosen that execution shape. 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
   a human convenience, never a requirement.
 - Version single source: package.json. Release via
-  `node bin/bullswarm.js release patch|minor|major` then `git push --tags`
+  `node bin/bullswarm.js release patch|minor|major`, then `git push` and
+  `git push --tags`
   — CI publishes through npm trusted publishing (OIDC), no tokens.
 
 ## Adding a connector

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # bullswarm changelog
 
+## 0.20.0 — common agent delegation entry point
+
+- `/bullswarm` and `bullswarm delegate` now give agents one transparent entry
+  point for arbitrary self-contained tasks: classify the request as one bounded
+  delegate or an autonomous workflow, show the reason and conceptual plan, then
+  execute the selected engine. Explicit mode and lane overrides remain
+  available, and `--dry-run --json` exposes the decision without dispatching.
+- Workflow decisions persist the suggested conceptual plan alongside the
+  original intent, while the packaged skill keeps the common path concise and
+  moves operational detail into a focused reference.
+- Planner context now labels the preflight scout as completion-ineligible and
+  requires the first program to contain a real delivery worker plus its
+  verifier, preventing an apparently complete scout report from causing a
+  rejected completion and redundant recovery round.
+- Ready siblings now honor a connector-owned soft concurrency preference. The
+  OpenCode route prefers one in-flight worker, so additional parallel work is
+  spread across healthy subscriptions instead of risking correlated headless
+  session exits; a lone eligible pool still runs rather than failing capacity.
+- Agent integration upgrades its managed awareness marker to advertise the
+  common interface consistently across Codex, Claude, and Grok.
+- Classification now understands negated and instructional mutation language,
+  so read-only requests that discuss how to add or write something do not
+  accidentally enter the build lane, while a later affirmative implementation
+  request still does.
+- A trailing `help` token remains contextual and side-effect-free even after
+  options, matching `-h` and `--help`; several README and setup/help examples
+  were also brought back into sync with the real CLI.
+- Historical workflow design documents now identify themselves as dated
+  implementation records and list the current `verify`, `decide`, and
+  `outputSchema` surfaces instead of presenting resolved gaps as current.
+- Extra KaiHK providers in `~/.config/opencode/opencode.json` (`kaihk-2`, …)
+  become `opencode2:<id>` pools, spawned with `--model <id>/gpt-5.6-luna`.
+  Spend is read from `GET /api/usage/token` plus
+  `/v1/dashboard/billing/usage` (USD = `total_usage / 100`). The HTML wallet
+  page still needs a browser session and is not the key API.
+
 ## 0.19.0 — unified workflow dashboard
 
 - Running `bullswarm workflow` on an interactive terminal now opens one

package/README.md

@@ -5,6 +5,11 @@ 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.
 
+For agents, `/bullswarm` (or `$bullswarm` where skills use that syntax) is the
+common entry point. Its durable CLI equivalent is `bullswarm delegate`: it
+first explains whether the request needs one bounded agent or an autonomous
+workflow, shows the conceptual plan, and then executes the selected engine.
+
 Every command and nested subcommand supports contextual `-h` / `--help`
 without initializing state or executing the command:
 
@@ -66,6 +71,9 @@ 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 delegate --cwd ~/some-repo --prompt "Explain the parser"            # one agent
+bullswarm delegate --cwd ~/some-repo --prompt "Audit all commands, fix help, and independently verify"  # workflow
+bullswarm delegate --dry-run --json --cwd ~/some-repo --prompt "Your task"     # decision + plan only
 bullswarm run --lane analyze --add-dir ~/some-repo --task-file /tmp/t.md --json
 bullswarm run --lane analyze --add-dir ~/some-repo --prompt "Inspect the parser" --json
 bullswarm workflow goal "Fix the failing tests and verify the change" --cwd ~/some-repo
@@ -78,6 +86,7 @@ bullswarm health   # re-judge saved outputs; catch gate failures
 |---|---|
 | `setup` | Discover installed agent CLIs, show quota state, toggle pools, suggest a routing table, write config. Approval-gated, idempotent. |
 | `integrate` | Register or remove the canonical Bullswarm skill and global awareness rules for Codex, Claude, and Grok. |
+| `delegate` | Explain and execute the smallest reliable shape: one content-verified agent or an autonomous verified workflow. |
 | `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 |
@@ -227,7 +236,7 @@ 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}}'
+    --add-dir '{{inputs.targetDir}}'
 bullswarm workflow draft step add audit-code review per-file \
     --type fanout --items-from 'outputs.list-files.outFile' \
     --lane analyze --concurrency 2 \

package/bin/check-output-schema.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { isValidOutputSchema, validateAgainstSchema } from '../src/workflow/schema.js';
+
+function argValue(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+const schemaPath = argValue('--schema');
+const valuePath = argValue('--value');
+if (!schemaPath || !valuePath) {
+  console.error('Usage: check-output-schema --schema <schema.json> --value <candidate.json>');
+  process.exit(2);
+}
+
+try {
+  const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+  const value = JSON.parse(readFileSync(valuePath, 'utf8'));
+  const schemaValidity = isValidOutputSchema(schema);
+  const result = schemaValidity.ok
+    ? validateAgainstSchema(value, schema)
+    : { ok: false, errors: schemaValidity.issues };
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exit(result.ok ? 0 : 1);
+} catch (error) {
+  process.stdout.write(`${JSON.stringify({ ok: false, errors: [error.message] })}\n`);
+  process.exit(1);
+}

package/connectors/opencode2.json

@@ -25,6 +25,8 @@
   "$comment-exit1": "known failure mode: writes a complete correct answer, then dies with a Console-sync auth error and exit 1. The verdict sets contentUsableDespiteExit instead of discarding the work.",
   "meter": { "type": "none" },
   "costRank": 1,
+  "preferredConcurrency": 1,
+  "$comment-preferredConcurrency": "OpenCode's shared local/provider session can terminate sibling headless runs together under parallel load. Prefer one in-flight OpenCode worker and route other ready siblings to healthy pools; if no alternative is eligible, availability wins and OpenCode may still be used.",
   "lanes": ["analyze", "build", "chore"],
   "capabilities": ["strong-analysis", "code-reading", "file-editing", "workflow-planning"],
   "modelDiscovery": { "cmd": ["opencode", "models"], "parse": "lines", "includePattern": "^[^\\s]+/[^\\s]+$", "timeoutMs": 20000, "maxModels": 250 },

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

@@ -13,6 +13,8 @@ Every statement is tagged:
   (`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.
+- **[IMPLEMENTED]** — behavior shipped in Bullswarm and backed by its source
+  and regression suite, rather than a claim about Claude's workflow contract.
 
 ## 0. The one-paragraph shape
 
@@ -349,7 +351,7 @@ author and the `Workflow` runtime.
    exist — the script's `while (!ok)` loop *is* the evidence — which is the
    general lesson: every piece of control flow bullswarm moves from planner
    into runtime needs its evidence rule moved with it.
-11. **[SPEC] Schema-enforced worker output** — a planner `run` action or fan-out
+11. **[IMPLEMENTED] Schema-enforced worker output** — a planner `run` action or fan-out
     `stepTemplate` may declare an object-typed `outputSchema` subset. The
     runtime appends instructions for one trailing matching JSON object, with no
     prose or markdown fences after it, then parses and validates the object.
@@ -363,7 +365,10 @@ author and the `Workflow` runtime.
     fields, and `fanout.itemsFrom` can consume `outputs.<id>.data.items` without
     extraction when it is already an array. Planner decision validation rejects
     `outputSchema` on a proposed `verify` because verify has a fixed verdict
-    shape.
+    shape. Schema-backed dispatches suppress ordinary same-pool retries so the
+    schema contract gets exactly its one bounded correction attempt. On resume,
+    a fan-out item is skipped only when both its verdict and declared schema
+    are satisfied; the schema must be declared on `stepTemplate.outputSchema`.
 
 **Honest limitation.** `itemsFrom` removes the planner *turn*, not the stage
 *barrier*: a verify depending on a data-driven fan-out waits for all items,

package/docs/dynamic-workflow-handoff.md

@@ -1,4 +1,4 @@
-# Bullswarm Dynamic Workflow Handoff
+# Bullswarm Dynamic Workflow Handoff (Historical)
 
 **Purpose:** iteration brief for making bullswarm's workflow system behave like
 Claude Code's dynamic workflows while preserving bullswarm's provider routing,
@@ -6,8 +6,10 @@ quota pacing, content verification, and agent-friendly CLI contracts.
 
 **Audience:** the next implementation agent.
 
-**Status:** build target, based on repository inspection, real OpenCode/Luna QA,
-and a Fleetlens inspection of Claude workflow telemetry.
+**Status:** historical implementation brief from 2026-08-21. The gaps and task
+list below describe the state at that date; they are not a current capability
+matrix. For current behavior use `README.md`, `skill/SKILL.md`,
+`docs/claude-dynamic-workflow-mechanics.md`, and the contextual CLI help.
 
 ## Executive Summary
 
@@ -23,10 +25,12 @@ understand request
   -> repeat until complete
 ```
 
-Bullswarm currently has a validated JSON plan, sequential phases, dynamic
-fan-out, retries, escalation, verification, resume, and a basic dashboard. It
-does not yet have the central `observe -> decide -> schedule` loop. Its graph
-is fixed after validation; only a fan-out's item count can expand at runtime.
+Bullswarm now has the control loop this brief proposed: a durable orchestrator
+observes completed work, proposes a bounded program, deterministic validation
+accepts or rejects it, and the runtime schedules ready actions before the next
+checkpoint. Static JSON workflows remain supported alongside zero-graph
+`workflow goal` execution. The rest of this document preserves the historical
+evidence and build rationale that led to that implementation.
 
 The target is not an uncontrolled mutable DAG and not an LLM that owns the
 runtime. The target is a hybrid:
@@ -235,6 +239,8 @@ Supported step types:
 - `run`: one delegate invocation.
 - `fanout`: one delegate invocation per item.
 - `verify`: a skeptical review of a prior output artifact.
+- `decide`: a durable adaptive planning gate whose proposal is validated before
+  any new action is appended or executed.
 
 The implementation is mainly in:
 
@@ -276,8 +282,19 @@ A later step can reference them with templates:
 {{outputs.previous.pool}}
 {{outputs.previous.outputText}}
 {{outputs.previous.outFile}}
+{{outputs.previous.data.field}}
 ```
 
+For a structured `run`, declare an object `outputSchema` when a later step
+needs typed data. The successful state record contains `data` and
+`schemaOk: true`; after the single schema correction retry fails it retains the
+output text and contains `schemaOk: false` and `schemaErrors`. A schema retry is
+observable as `action.output_schema_retry`, followed by
+`action.output_validated` only when the corrected object passes validation.
+The task also supplies an exact local schema-preflight command. The worker uses
+it on a temporary candidate before replying, while the runtime independently
+revalidates the captured response before exposing `data` downstream.
+
 A fan-out can use a prior output file as its item source:
 
 ```json
@@ -290,8 +307,13 @@ A fan-out can use a prior output file as its item source:
 }
 ```
 
-The runtime reads the referenced file and parses a JSON array. This is dynamic
-item expansion, not dynamic workflow graph expansion.
+The runtime first consumes an already-recorded array such as
+`outputs.discover.data.items`. For the legacy `outputs.<id>.outFile` form it
+reads the referenced file and parses a JSON array. This is dynamic item
+expansion, not dynamic workflow graph expansion. Fan-out schemas belong on
+`stepTemplate.outputSchema`; each item stores its own `data`, `schemaOk`, and
+possible `schemaErrors`, and resume re-runs only items whose verdict or schema
+is incomplete.
 
 ### Routing and model selection
 
@@ -335,6 +357,7 @@ Bullswarm currently has:
 - Recursion-depth propagation and guard
 - Resume of successful steps
 - Fan-out resume by item fingerprint
+- Structured worker output with one schema retry and durable schema state
 - Cooperative cancellation through `state.json`
 - Heartbeats during long dispatches
 - Basic interactive dashboard
@@ -346,6 +369,7 @@ Bullswarm currently has:
 bullswarm doctor --json
 bullswarm workflow capabilities --json
 bullswarm workflow inspect <file-or-name>
+bullswarm workflow runs result <shortId> --json
 bullswarm workflow tui --json
 bullswarm workflow tui --json <shortId>
 bullswarm workflow tui --json --cancel <shortId>
@@ -360,7 +384,14 @@ bullswarm workflow inspect <file-or-name>
 bullswarm workflow tui --json
 ```
 
-## 3. Important Gaps, Ordered by Priority
+## 3. Historical Gaps, Ordered by Priority
+
+This section is an as-built checklist from the original handoff. The adaptive
+decision loop, bounded graph expansion, structured decisions, attempt ledger,
+ordered event log, cancellation, and timeline/dashboard surfaces described
+below are implemented now. The past-tense gap text is retained so reviewers can
+trace requirements to the resulting runtime and tests; it must not be read as
+current product status.
 
 ### P0: no observe-plan-execute loop
 

package/docs/dynamic-workflow-qa.md

@@ -94,6 +94,19 @@ the internal `review` artifact path. Bullswarm now deterministically infers that
 path for a verifier with one dependency and always appends the required JSON
 verdict contract. This is deliberately runtime knowledge, not caller steering.
 
+## Structured Output Evidence
+
+For an optional object `outputSchema` on a `run`, the runtime appends the
+contract to the worker prompt, parses the trailing object, and allows exactly
+one schema correction retry. The durable `state.json` record exposes
+`outputs.<id>.data` and `schemaOk`; a failed correction retains `schemaErrors`
+and the output text. Fan-out item records use the same fields under
+`outputs.<fanoutId>.items[]`. Offline regressions in
+`tests/workflow-adaptive.test.js` and `tests/workflow-gaps.test.js` verify retry
+events, persisted state, resume behavior, downstream rendering, and data-backed
+fan-out. The stable result envelope returns the durable artifact content; typed
+worker data remains inspectable in `state.outputs.<id>.data`.
+
 ## Acceptance interpretation
 
 - Provider output is accepted by content verification, never by exit status alone.

package/docs/workflow-design.md

@@ -1,6 +1,6 @@
 # bullswarm Dynamic Workflows — Design
 
-**Status:** PROTOTYPE · **Branch:** `feat/dynamic-workflow` · **Created:** 2026-08-21
+**Status:** implemented; historical design rationale retained · **Created:** 2026-08-21
 
 ## Problem
 
@@ -65,7 +65,7 @@ added as a second format without touching the runtime contract.
       "steps": [
         {
           "id": "fanout-review",            // required, unique
-          "type": "run",                    // run | fanout
+          "type": "run",                    // run | fanout | verify | decide
           "taskFile": "/tmp/wf/{{runId}}/task-{{item}}.md",
           "lane": "analyze",
           "addDir": "{{inputs.targetDir}}",
@@ -105,6 +105,25 @@ Step fields (all pass through to the existing `run` pipeline):
 - **`fanout`** — expand `stepTemplate` once per item from `itemsFrom`.
   Items may be strings or objects (`{{item.path}}` paths work). Concurrency
   capped by min(step, settings).
+- **`verify`** — independently review a prior artifact and require structured
+  `{ok, concerns, summary}` evidence before dependent work may trust it.
+- **`decide`** — give the durable orchestrator current intent, outputs,
+  failures, budgets, and capabilities. Its versioned proposal is validated
+  before bounded `run`, `fanout`, or `verify` actions enter the plan.
+
+`run` and fan-out templates may declare `outputSchema` when later actions need
+structured data. The schema is an object-typed JSON-Schema subset. A successful
+run records `outputs.<id>.data` and `schemaOk: true`; a fan-out records the same
+fields on each `outputs.<fanoutId>.items[]` entry. A mismatch gets one bounded
+schema retry and records `schemaOk: false` plus `schemaErrors` if the retry also
+fails. Ordinary prose should leave `outputSchema` unset; `verify` has its own
+fixed verdict schema.
+
+Before replying, a schema-bound worker receives the exact schema file and a
+deterministic `check-output-schema` command for a temporary candidate object.
+It must correct the candidate until that preflight exits zero and then emit the
+validated object. The runtime validates the captured response again; worker
+preflight reduces avoidable retries but never replaces the authoritative gate.
 
 ### Templating
 
@@ -134,9 +153,9 @@ artifacts + report + exit code
 - **State**: `~/.bullswarm/workflows/<runId>/state.json` after every step —
   crash-safe by construction.
 - **Resume**: `workflow run --resume <runId>` skips steps whose saved verdict
-  is `ok:true`; everything else re-runs. Fanout re-runs only unverified items.
-  (Simpler than odw fingerprints and sufficient because our units are
-  coarse-grained.)
+  is `ok:true` and whose declared output schema, if any, is satisfied;
+  everything else re-runs. Fanout items resume by content fingerprint, so
+  already verified items remain complete even when discovery order changes.
 - **Artifacts** per run: `state.json`, `report.json`, every task/out file.
 
 ## Terminal UX (the deliverable's face)

package/mcp/server.mjs

@@ -46,6 +46,13 @@ function result(id, r) {
   write({ jsonrpc: '2.0', id, result: r });
 }
 
+let inputClosed = false;
+let pendingCalls = 0;
+
+function exitWhenDrained() {
+  if (inputClosed && pendingCalls === 0) process.exit(0);
+}
+
 async function callTool(name, args) {
   // Reuse the CLI verbs but capture stdout instead of leaking to our protocol
   // stream: swap console.log for the duration of the call.
@@ -108,6 +115,7 @@ function handleMessage(line) {
       result(id, { tools: TOOLS });
       break;
     case 'tools/call':
+      pendingCalls += 1;
       callTool(params.name, params.arguments ?? {})
         .then((r) => id != null && result(id, r))
         .catch((err) =>
@@ -117,7 +125,11 @@ function handleMessage(line) {
             id,
             error: { code: -32603, message: err?.message ?? 'internal error' },
           }),
-        );
+        )
+        .finally(() => {
+          pendingCalls -= 1;
+          exitWhenDrained();
+        });
       break;
     case 'ping':
       result(id, {});
@@ -135,4 +147,7 @@ function handleMessage(line) {
 
 const rl = createInterface({ input: process.stdin });
 rl.on('line', handleMessage);
-rl.on('close', () => process.exit(0));
+rl.on('close', () => {
+  inputClosed = true;
+  exitWhenDrained();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {