ultraswarm

Ultraswarm is a durable multi-worker coding orchestrator for Codex, Claude Code, Cursor Agent, Grok, and shell usage. One standalone Node runner owns decomposition, worker routing, process supervision, isolated Git worktrees, adaptive review, transactional integration, approvals, recovery, and reporting.

What's New In v3.6.0

The run report now ends with an estimated-vs-used token breakdown by CLI, model, and effort, and the CLI gained onboarding/recovery commands:

• TOKENS BY CLI / MODEL / EFFORT table closes every report — CLI | model | effort | est. | used | Δ | attempts, plus a total row. est. is a calibration-informed heuristic: ultraswarm prefers the measured per-(CLI, model, effort) average persisted in .ultraswarm/state.sqlite (route_calibration, self-correcting across runs) and falls back to a static tier curve (simple 10k / moderate 30k / complex 75k / expert 150k tokens) until enough runs accumulate. used is ONLY structured usage summed across attempts — — when a CLI reports none, never backfilled from the estimate (the v3.5.13 honesty invariant still holds).
• Attempts now record the resolved model id, tier, and effort, not just the tier where "model" used to live (schema migration v3, additive — existing v2 databases upgrade in place). Failed attempts record their burned tokens too, so a rejected retry still counts toward the table above. When a CLI doesn't self-report cost, worker spend is now priced from config.intelligence.pricing[model] (USD per million tokens; falls back to built-in Claude rates, else 0 for an unpriced model) so maxCostUsd can actually bound external worker spend.
• Declarative usage capture widens real token reporting from 2 built-ins to 3. Each registry entry can now declare a usage array of { input, output, cost? } dot-path descriptors (with a * wildcard for keyed maps), evaluated against structured worker output; overrides.<cli>.usage and aliases.<name>.usage let you add or override a descriptor for a CLI without a built-in parser. Gemini now runs with --output-format json and its stats.models.*.tokens.* usage is captured, joining codex and opencode as real-usage CLIs.
• Routing feedback — --decompose planning and doctor now show each worker's measured track record (codex (backend…; 12 runs, 92% pass)) pulled from worker_metrics, so the brain and the operator both see what has actually been working, not just declared specialties.
• doctor --models prints the resolved model per CLI per tier (registry + overrides + aliases), so a stale model pin is visible without reading config files; an optional modelListCmd per registry entry/alias warns when a resolved model is missing from the CLI's own model list.
• ultraswarm replan <runId> emits a plan JSON of a run's failed/blocked tasks, ready to feed straight back into run --plan-file - — a partially-failed run's surviving tasks never need to be retyped by hand.
• ultraswarm add-cli <name> --binary <bin> [--extends <builtin>] [--model <id>] onboards a new CLI in one command: probes the binary, builds a valid alias skeleton, and merges + validates it into ultraswarm.config.json, refusing to clobber an existing alias.
• Prompt efficiency — worker prompts are hard-capped at 64k chars with a loud [ultraswarm: truncated N chars] marker instead of silently growing; retry feedback is bounded to the last 10 rejected attempts (500 chars each) and now names the files the rejected attempt changed, so a retry converges instead of re-exploring from scratch.
• Ledger guard — the report now prints a loud ⚠ LEDGER MISMATCH line if the merged/failed/ blocked task rows don't add up to the plan's task count, instead of printing plausible-looking numbers that quietly don't reconcile.

What's New In v3.5.18

Run-output polish:

• Plain terminal report by default (no markdown #/**/_ showing as literal chars); pass --markdown to keep GitHub-markdown for pasting into a PR.
• Color — the live stream and report verdict are color-coded (green pass / red fail / yellow retry); auto-off when piped, honors NO_COLOR / --no-color.
• Run wall-clock in the Summary, and short 8-char run-ids (merge/status/logs/… accept an unambiguous prefix).

What's New In v3.5.17

• Every table in the run report is now a clean aligned terminal table — the per-task list was the last markdown table; it now matches the per-CLI / PLAN PREVIEW / WORKER ROSTER fixed-width style.

What's New In v3.5.16

• Per-CLI token table now renders as a clean aligned terminal table (the 3.5.15 version was a markdown table whose pipes didn't line up in a raw CLI) — fixed-width columns with a ─ separator and right-aligned numbers, matching the PLAN PREVIEW / WORKER ROSTER style.

What's New In v3.5.15

Per-CLI token breakdown (see the CHANGELOG):

• "Work offloaded" now breaks usage down by CLI — a table of landed (tokens that produced integrated work) vs spent (all attempts, incl. rejected retries and competition losers) vs overhead, with a reconciling total. You can see at a glance which worker burned tokens and how much went to retries/competition (e.g. Workers used ≈ 383,578 tokens — ≈ 274,485 landed, ≈ 109,093 on retries + competition).

What's New In v3.5.14

Real token-usage capture (see the CHANGELOG):

• codex and opencode now report real usage. Their default invocations use exec --json / run --format json, and ultraswarm parses the structured JSONL usage events — so the report's "Work offloaded" section shows the actual token count (e.g. Workers reported ≈ 238,656 tokens) instead of "not reported". No more scraped guesswork (removed in 3.5.13), and no fabrication when a CLI doesn't report — a custom invocation without the JSON flag honestly shows "not reported".

What's New In v3.5.13

Honest run-report value section (see the CHANGELOG):

• No more scraped token noise — the old "Tokens saved" number was regex-scraped from worker stdout and matched incidental digits (e.g. "≈ 62 tokens" for a run that used thousands). The free-text scrape is gone; token/cost now come only from a worker's structured usage, else nothing is claimed.
• "Work offloaded" reports what's measured — tasks, worker-attempt count, and total external wall-clock. A token figure shows only when a worker actually reported one; otherwise the report says "Token/cost usage: not reported by these CLIs" rather than inventing a misleading count.

What's New In v3.5.12

Live-stream readability follow-up to v3.5.11 (see the CHANGELOG):

• No more git chatter in the stream — git worktree add / merge --squash output is captured instead of inherited, so a big swarm's progress lines aren't buried under "Preparing worktree …".
• Consistent glyphs everywhere — routine-path escalation/rejection/blocked lines now carry the same ↑/✗/⊘ glyphs as the high-risk competition path, so the whole stream scans uniformly.

What's New In v3.5.11

Readability + accuracy pass on the two human-facing output surfaces (see the CHANGELOG for detail):

• Accurate run-end report — reports "integrated" (not "merged") while a run awaits merge approval, with a staging line making clear nothing lands on your branch until you approve; the headline counts every task (including post-merge regressions) so the numbers reconcile.
• Honest token offload — the offload headline no longer leads with a misleading ≈ N/≈ 0; it shows the exact figure on full coverage, an explicit floor (x of y tasks reported) on partial, and "not measurable here" when no worker reports usage. Retried-but-integrated tasks are named.
• Visible competition retries — when a high-risk competition winner is rejected by adversarial QA, the live stream now logs the judged winner and ✗ … rejected by QA — retrying instead of silently jumping to the next attempt.

What's New In v3.5.1–v3.5.10

Hardening from a full audit of the orchestrator (each fix shipped as its own patch release; see the CHANGELOG for per-version detail):

• Concurrency — fixed a re-entrant limiter deadlock that could hang an entire run, and froze runs deterministically on ≤3-core hosts (CI), whenever a high-risk task fanned out competition/QA work.
• Security — plan contract.commands now reject shell metacharacters (no more npm test; rm -rf ~ reaching the shell); worker env passthrough narrowed from the whole XDG_* namespace to named vars.
• Integration — a no-op squash records a clean skip instead of throwing and blocking the whole wave; a failed per-task commit fails loud instead of reporting ok; post-run cleanup deletes only the current run's branches.
• Recovery — resume judges liveness on a persisted orchestrator identity (pid + boot id), so it can't reap a still-running run or be fooled by PID reuse after a reboot; terminal runs are immutable.
• Brain — Anthropic schema calls extract JSON defensively and fall back to raw text so the validate-and-retry loop works; malformed --plan-file / package.json fail with a clear USAGE error.
• Alias workers in competition — user-defined alias workers can now participate in (and be retried within) high-risk competition; they previously tombstoned as "only N usable worker(s)".

What's New In v3.5

• Functional preflight — preflight runs a cached exec smoke test per CLI (write a file in an isolated temp dir) and excludes workers that pass --version but can't actually run (dead auth, no-op). Routing keys off the functional verdict. See Prerequisites.
• Human-readable output — preflight, plan previews, status, and doctor render aligned tables by defaul