Swarm Orchestrator

On 2026-10-11, swarm was given this task on a checkout of motdotla/dotenv-expand at 148488a4, with the local model qwen3.8:27b served by rapid-mlx on one Mac:

Upgrade the devDependency @dotenvx/primitives, which dotenv-expand bundles into its build, from 2.1.1 to exactly 3.0.3. package-lock.json is regenerated with npm so that npm ci installs 3.0.3 from the npm registry. lib/main.js keeps working on top of 3.0.3. Do not change the tests. npm test must still pass.

That goal is from the development set of the September comparison campaign, chosen because the September pilot had stalled on it; it is one run and an illustration of the workflow, not a rate. The comparative measurement is further down.

swarm takes a task and a git repository. It seals the completion criteria, declares the files it intends to touch, edits through one recording chokepoint, runs your project's checks as sealed gates, and retries failures under a ratchet that refuses a fix which trades away tests, assertions or coverage. The exact final tree is then verified in a fresh checkout, and the run ends on an outcome block: which requirements were met, unmet or unjudged, what changed, what ran, what it cost, which interventions happened, and the next action when it is not done. Everything it did is a signed, hash-chained evidence bundle that carries its own dependency-free verifier.

task in words
  -> criteria: a sealed goal contract you supply, or one the planner authors and shows you
  -> preflight: the checks are established on the base before the first model call
  -> a bounded change, every tool call recorded; a worker repeating itself is told once, then stopped
  -> the project's checks and the sealed acceptance check run as gates
  -> the ratchet: a retry may not trade away tests, assertions or coverage
  -> the exact final tree verified independently in a fresh checkout
  -> the outcome block, then evidence: a signed bundle anyone can verify offline

The model can say whatever it likes. It cannot make a check pass, mark a claim verified, or change a record after the fact. Those are the harness's to decide.

• A claim is not evidence. A structured claim the model makes names a predicate and a record; the harness evaluates it against its own records and renders the verdict. Narrative never renders green, and a claim the harness cannot evaluate renders UNVERIFIED without stopping the run.
• A pass must be able to fail. Each passing gate is handed one fixture it has to refuse, so a check that cannot fail is caught rather than counted.
• A retry cannot buy green by deleting tests. Tests collected, assertions in touched tests and covered changed lines cannot decrease across retries; skips cannot increase.
• Regression and task acceptance are two answers. A suite passing says nothing broke. Only a requirement contract or an acceptance check you supply can say the work was done, and the tool reports when neither was given.
• Unmeasured is a verdict. Nobody checked is not the same as checked and passed, and it is never rendered as a pass.

npm install -g swarm-orchestrator

This installs the registry’s latest release and leaves swarm on your path. The source version is 14.4.0; publication is tracked in the delivery record. It runs on Node 22 or newer; Node 24 or newer is recommended, because the changed-line coverage measurement spawns Node's test runner with process isolation, which Node 22 below 22.8 rejects. Below that, the measurement reports unmeasured and never counts as a pass. swarm doctor says which Node it found and what owns the swarm command, and --fix repairs an install that an older build is shadowing.

export ANTHROPIC_API_KEY=...       # or OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY,
                                   # or start Ollama or rapid-mlx and pass --model local:<id>
cd your-repository
swarm "make slugify collapse whitespace and strip punctuation" --plan-checks

--plan-checks has the planner read the repository and author completion criteria from your sentence: requirements and executable checks, shown in plain language and sealed before the first edit, labelled model-authored on the chain and in the report. Without it a run is measured by the project's own checks only, and the outcome block says so; with a contract file of your own, pass --goal-contract instead (docs/broad-use.md). Node 22 or newer is required and Node 24 is recommended; the model is a local server or a frontier key.

Keys come from the environment or your OS keychain, never from swarm.toml: that file is committed and cloned, so a key in it has already been shared with everyone holding the repository. The run shows each step, each gate and each retry as it happens, and ends on the evidence panel. swarm review <bundle> opens a run's review page later; swarm verify <bundle> checks its integrity and who signed it. Every command and flag is in docs/cli.md; sessions, several workers at once and the screen are in docs/using.md.

(back to top)

Every tool call and every check goes through one recording chokepoint, and the record is an append-only, hash-chained ledger that lives outside the workspace. The gates, their severities, their parsers and the budgets are sealed before the first model call, so nothing the model does during the run can change what it is measured against.

Six words carry most of the weight. A gate is a check declared as data: a command, a parser, and whether it blocks. The ratchet is the rule that a retry may not trade away tests, assertions or coverage to turn a gate green. A bond is one file a passing gate is handed that it must refuse, so a pass that cannot fail is caught. An oracle is the check you supply that says the task was done, as distinct from nothing broke. Reach is whether that oracle executed the lines a patch added. And unmeasured is a verdict of its own.

With a goal contract (--goal-contract), the contract's own checks are challenged (--challenges report|required): a base control per requirement, mechanical mutations of the changed lines witnessed by the suite, and sealed fixtures, so a check that could not have caught wrong work is named. With --strengthen, the model may propose one additive check per witnessed gap; the harness admits it only where it observes the check reject the counterexample and accept every sealed reference, then repairs the code under the revised contract. Nothing is asked of the model before the criteria are sealed.

The mechanics, the nine-answer report and worked examples are in docs/verifying.md. The goal contracts, presets and package scope are in docs/broad-use.md.

The product hypothesis is that Swarm completes real repository tasks with less supervision and rework than an ordinary coding agent. It is measured, not assumed, in an exploratory paired trial of twenty issue-sized historical changes mined from five public repositories outside every earlier corpus (marked, fast-xml-parser, yargs-parser, js-yaml, minimatch), Swarm against OpenCode on the same local model, the same prepared workspace, the same visible check, the same wall budget and one deterministic supervision rule applied to both, scored by the upstream commit's own tests held sealed from both arms. The protocol was registered before any launch; the counts, with their denominators, and what they do and do not support are in docs/evidence/2026-10-11/comparison/README.md. In the pass that stands (the fifth; four earlier passes were discarded for defects found in the harness, in Swarm and in the model server, each reported there), Swarm completed 5 of 20 tasks correctly and OpenCode 4 of 20, a one-task difference that supports no claim of an advantage. What separated the arms was how they ended: 19 of OpenCode's 20 first invocations had to be killed at the 30-minute wall, most of them repeating one command, while every Swarm launch returned on its own with a verdict; the correct Swarm tasks cost 355 thousand tokens each against 4.76 million for OpenCode's. Developer hours saved and real-world adoption are not measured there; the prepared, unrun protocol for five developers on their own tasks is docs/human-trial-protocol.md.

A run writes its ledger under ~/.swarm/sessions, never inside the workspace, and exports a bundle: the manifest with the chain head and the signature, the records, every blob by SHA-256, the review page, the summary, and verify.mjs, a dependency-free verifier that re-derives every verdict from the records alone.

node <bundle>/verify.mjs <bundle>          # anywhere, nothing installed
swarm verify <bundle> --signer <fp>        # here, with the signer judged too

Every number here links to the committed artifact of the thing happening; the full table, and the list of things that may not be said, is docs/claims.md.

• One changed byte breaks verification. The same bundle verified and then tampered with in a single byte, exit 0 and exit 1 side by side, with a script to reproduce it: tamper demo.
• A bundle verifies on a machine that has never seen this repository. Run in a node:24 container with no network and no mount of this repository: clean-container-verification.md.
• A green verdict is computed by the harness, and the model cannot produce one. In a real run the model asserted a predicate the language does not parse; the harness rendered it UNVERIFIED and carried on, twice: shakedown results.
• A suite passing is not the task being done. Four of eighteen patches this project's own agent and a baseline arm produced over three public TypeScript repositories passed their project's whole suite and failed a hidden acceptance test, which is why regression and task are two answers: docs/verifying.md. That is a measurement of those eighteen patches, not a rate for AI-written changes in general.
• The oracle is judged too. Certified tasks turned out to rest on oracles that could not fail; the last false green standing was refused because its oracle accepted a change to a line it had run: docs/verifying.md.
• The September 6 mined-corpus false-green rate was 0 in 15, 95% CI [0.0, 20.4], with two oracles per task, one handed to the tool and one held back: mined-corpus.

(back to top)

The five that matter most. The full list is in docs/verifying.md.

• It is not production-ready. The counts above describe the linked campaigns, not a fresh measurement of every gate on this checkout. Each row and what would settle it: docs/beta-gates.md.
• Not "fully secure". The secret detector does known-pattern scrubbing, not secret removal. Zero crashes at a fuzz budget is evidence, not proof.
• The default execution mode is restricted, not isolated. A lexical path and program policy in front of interpreters unless you pass --isolation. Reported before the run starts and recorded on the chain rather than quietly assumed, but it is not containment.
• 0 in 15 says "under 20%", not "zero". That upper bound is the honest half of the rate, and it is a rate for that corpus and that build, not for this one.
• Shown its oracle, a model still gets past this. Bonding and challenges ask whether the checks judged what the patch added. They cannot ask what the patch left out, and that is what an adversarial patch does.

Gates prove mechanical quality, not design quality. What a bundle buys you is that reviewing the change is fast and its claims are checkable, not that review is unnecessary.

The verification the agent is held to is a product of its own. Swarm Verify checks a change from any source, this agent, Claude Code, Codex, Copilot, another agent or a person, with no model, no key and no configuration:

npx swarm-verify                                   # run a repository's declared checks and report what that establishes
npx swarm-verify ci --pr owner/repo#123            # verify a pull request in a fresh checkout of its base
npx swarm-verify verify <bundle> --signer <fp>     # check a bundle this agent, or anything else, produced

It also ships as the GitHub Action moonrunnerkc/swarm-verify@v1, a Claude Code hook, an MCP server and a pre-commit hook. The same commands are in the swarm binary: swarm check, swarm ci, swarm verify, swarm verdict and swarm gates need no model, and docs/verify-only.md walks through them over committed artifacts.

There is one implementation. The swarm-verify package is built from this repository's verification modules under packages/swarm-verify, behind a build-time boundary that refuses any provider, worker or screen module; the agent composes those same modules. Swarm Orchestrator uses Swarm Verify. It is not Swarm Verify.

(back to top)

The package name has carried three different programs, and the majors are the boundary:

Pin a major. Each release names the verifier version it carries in CHANGELOG.md; the verifier's own changelog is packages/swarm-verify/CHANGELOG.md.

The bar is the one the tool applies to itself: npm run gates green with the output shown, new behaviour covered by a test that failed first, and no claim in a document that its linked artifact does not establish.

1. Fork the project
2. Create a branch (git checkout -b feature/amazing-feature)
3. Run npm run gates and paste the real output in the pull request
4. Commit (git commit -m 'Add an amazing feature')
5. Push (git push origin feature/amazing-feature)
6. Open a pull request

New dependencies need a one-line justification; the standard library is preferred. docs/build-guide.md is worth reading before structural work.

Distributed under the ISC License. See LICENSE.

Brad Kinnard, @KChackerman, bradkinnard@proton.me

Project link: github.com/moonrunnerkc/swarm-orchestrator

(back to top)