swarm-orchestrator 12.0.0 → 13.1.4

package/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+## 13.1.4
+
+### Fixed
+
+- **The readme printed an install command that cannot work.** It offered
+  `npm install -g github:owner/repo#tag` beside the registry line. `dist/` is not committed, so a
+  git ref builds itself on install and needs this package's devDependencies to do it, and npm
+  does not install those under `-g`: it carries the global context into its git-dependency
+  preparation, places the clone as a root package rather than building a tree inside it, and runs
+  `prepare` without the compiler. The same ref installed without `-g` works and always did. Found
+  by a person running the line the readme printed.
+- **That failure surfaced as `ENOENT` on a path the reader never typed.** The build now names the
+  cause and the two commands that do work, rather than reporting a missing file.
+
+## 13.1.3
+
+The first 13.x on the npm registry. No behaviour changed: this is 13.1.1 with a manifest the
+registry accepts and install instructions that are true.
+
+### Fixed
+
+- **The manifest named no repository, so a signed publish was refused.** `npm publish
+  --provenance` signs a statement naming the repository the tarball was built from, and the
+  registry checks it against `repository.url` before it accepts the write. That field was
+  absent, so the statement said one thing and the manifest said `""`, and the registry answered
+  `E422` after the provenance had already been written to the transparency log. Nothing in the
+  source tree can show this, so a test now asserts the field.
+- **The package told its own readers it was not published.** The install section named a git ref
+  and said the registry served 12.0.0, because that is what was true while the credential was
+  missing. Those words ship inside the tarball, so publishing 13.1.1 as it stood would have put
+  a package on the registry whose first section denies being there. `npm install -g
+  swarm-orchestrator` is the first line again.
+
+### Added
+
+- A description, keywords, a homepage and a bug-tracker link, which is what the registry page
+  renders around the readme and what a search on the registry matches against.
+- Three flags the readme never listed, `--base`, `--max-steps` and `--local-endpoint`, and a
+  pointer to `swarm --help` for the calibration flags it still does not list.
+
+`13.1.2` was tagged and refused by the registry for the manifest reason above. The tag is left
+where it is rather than moved, because it names a real tree and the refusal is part of the
+record.
+
+## 13.1.1
+
+A packaging fix. Nothing about how the tool runs changed.
+
+### Fixed
+
+- **Installing from a git ref produced a package with no binary.** `dist/` is not committed and
+  is built by a script, and npm runs `prepare` for a git install but never `prepublishOnly`.
+  Only the latter was declared, so `npm install github:moonrunnerkc/swarm-orchestrator#v13.1.0`
+  resolved, reported no error, and left a directory with no `dist/` and no `swarm`. This is the
+  install path that matters while the registry publish is blocked, and it was the one that did
+  not work.
+
+## 13.1.0
+
+A run you can watch and drive, and an end-of-run panel that shows you what it produced.
+Everything below is additive: no flag, command or output changed meaning, and the plain-line
+stream a pipe or a CI job reads is byte-for-byte what it was.
+
+### Added
+
+- **An interactive terminal interface.** On a TTY, a run draws a single screen: the task and
+  the model in a header, the plan, the action stream, the gate strip, and a status line.
+  Scroll it, expand a row to the whole tool input and output and the ledger record it came
+  from, filter it, freeze the render without touching the run, and press `?` for the keymap.
+  Two exits that are not the same thing: `q` leaves the view and lets the run finish, `ctrl+c`
+  cancels the run.
+- **An end-of-run evidence panel.** What the run produced, named by what each artifact is for,
+  with the record count and how many claims the harness verified against how many it refused.
+  One keystroke opens the review page, another the bundle directory. It says the bundle
+  verified only if the bundle's own verifier ran in that session and exited 0, and it names the
+  exit code; otherwise it says "not verified in this run" and prints the command.
+- **`swarm review <bundle directory>`**, which shows that same panel for any bundle already on
+  disk, running the same verifier. Nothing is re-run.
+- **`swarm --help`**, which used to report that `--help` needs a value.
+- **Screen flags**: `--no-tui` for plain lines even on a terminal, `--color` and `--no-color`,
+  `--open-evidence` and `--no-open-evidence`. Opening is opt-in and never happens off a
+  terminal.
+- **Three `swarm.toml` tables**: `[interface]` (`tui`, `color`, `open_evidence`), `[theme]`
+  (a colour per slot), and `[keys]` (a key per action). Flags win over the file, as everything
+  else does. An unknown key, colour or action is a typed error naming what was wrong and what
+  would have been accepted.
+- **Sampling settings on the wire for a calibration run**: temperature and top-p pinned and
+  recorded in every model-call record, with a seed per repeat. An ordinary task run sends
+  nothing and is unchanged.
+
+### Fixed
+
+- **Two consumers of one stdin.** The CLI built a readline interface on `process.stdin` while
+  Ink held the same stdin in raw mode. A confirmation firing mid-run raced them, which is the
+  least acceptable place to drop a keystroke. Confirmation is now a component inside the
+  running screen, answered by the same key dispatcher.
+- **The curated model shortlist and pricing table answered 404.** Both URLs named the branch
+  `main`, which is the v12 lineage and carries neither file, so `swarm select` fell back to the
+  bundled snapshot on every machine.
+- **A missing verifier read as a refused bundle.** Node exits 1 on a module it cannot find,
+  which at the exit code is the same as a verifier that ran and said no. One is the absence of
+  a verdict.
+- **Local models reported no tokens, and so cost nothing.** An OpenAI-compatible server streams
+  a usage chunk only when the request carries `stream_options.include_usage`, and the local
+  provider was not built to send it. Every local run recorded `outputTokens: 0`, so throughput
+  was unmeasurable and every run priced at `$0.0000`, which the routing reward is built from.
+  The router had been learning that local models are free.
+- **One keychain message for three different failures.** A key that could not be read, an entry
+  holding something that is not a key, and a keychain that would not accept a new one now say
+  which happened and what to do about it. The middle one names the service and the account, and
+  says the entry can be deleted.
+
+## 13.0.0
+
+Same package name, different product. If you installed `swarm-orchestrator` before this
+release, read this before upgrading: v13 is not a newer v12, and nothing in v12's interface
+survives.
+
+### What v12 was, and what v13 is
+
+v12 was a PR auditor. It ran as a GitHub Action, read pull requests opened by AI coding
+agents, looked for cheat patterns (test relaxation, mock-of-hallucination, assertion strip,
+no-op fix), posted findings as a comment, and gated merges.
+
+v13 is a coding agent. It does the work rather than auditing somebody else's, and every
+claim it makes about that work resolves to machine-captured evidence in a tamper-evident
+ledger. The two share a name and nothing else: no shared history, no shared interface, no
+migration path from one to the other, because there is nothing to migrate.
+
+### Breaking
+
+- **The `swarm-audit` and `swarm-orchestrator` binaries are gone.** One binary now, `swarm`.
+- **The GitHub Action is retired.** v13 ships no `action.yml`. There is no v13 equivalent of
+  the merge gate, and none is planned.
+- **Node 24 or newer.** v12 asked for 20. The floor is not stylistic: the coverage cycle
+  spawns the test runner with `--test-isolation=process`, which Node 22 rejects as a bad
+  option, so on anything older that arm measures nothing.
+- **The histories share no merge base.** v13 is a separate lineage. `git log` will not show
+  you v12's commits from here.
+
+### If you are using v12
+
+Stay on it. It is tagged `v12-final` and that tag is not going away.
+
+    npm install swarm-orchestrator@12.0.0
+
+That is the newest v12 the registry carries. The `v12-final` tag is at 12.1.1, which was
+tagged but never published, so `@12.1.1` does not resolve; install from the tag if you need
+exactly that tree.
+
+For the Action, pin the tag rather than a branch, since the default branch is moving to the
+v13 lineage:
+
+    uses: moonrunnerkc/swarm-orchestrator@v12-final
+
+### What v13 does
+
+One task, start to finish, in a git workspace: plan, edit through a chokepoint that records
+every tool call, run the gates, auto-resolve failures under a numeric ratchet, and export a
+signed evidence bundle a stranger can verify without installing anything.
+
+The parts worth knowing before you try it:
+
+- Gate results, claim verdicts and bundle status are computed by the harness. Model prose
+  renders as unverified narrative and cannot render green.
+- The ledger is append-only and hash-chained, signed with a key from the OS keychain.
+- The bundle carries its own verifier. `node verify.mjs <bundle>` needs Node and nothing
+  else.
+- Local model selection is measured on your hardware rather than guessed from model cards.
+
+`README.md` links each of those to a committed artifact of it happening. `docs/claims.md`
+maps every claim to its evidence, and lists what this tree cannot back.

package/README.md

@@ -1,255 +1,224 @@
-<p align="center">
-  <img src="./assets/cover.svg" alt="Swarm Orchestrator cover" width="100%">
-</p>
-
-# Swarm Orchestrator
-
-Reads a pull request (PR) diff and flags the shortcuts artificial intelligence (AI) coding agents use to look done without being done. Relaxed tests, swallowed errors, fake renames, eleven categories in all. Grading patches against typed obligation contracts via a multi-persona pipeline is the second surface.
-
-For engineers reviewing AI-written PRs at volume. Compliance teams generate CycloneDX-ML (machine learning) and SPDX (Software Package Data Exchange) 3.0 AI-BOM (bill of materials) artifacts. The artifacts map to EU AI Act (European Union Artificial Intelligence Act) Annex IV and CISA (Cybersecurity and Infrastructure Security Agency) reporting. Maintainers keep a hash-chained evidence record for every graded patch.
-
-**Flags are tips, blocks are proof.** A flag is a structural detector seeing a cheat-shaped pattern; it is advisory and never blocks a merge (`--mode advise` is the default). A block is a self-certifying runtime result whose per-instance controls are all green, and every block ships the exact command that reproduces it in a fresh checkout. Eight proof protocols back the gate today: six execution-grounded restoration proofs (`test-tamper`, `mock-mutation`, `no-op-fix`, `type-suppression`, `fake-refactor`, `dead-branch`) plus `claim-falsified` and `obligation-failure`. The measured proven-finding precision on the execution-grounded-viable corpus slice, with its plain n, is in [`benchmarks/real-corpus/GATE-PRECISION-REPORT.md`](benchmarks/real-corpus/GATE-PRECISION-REPORT.md).
-
-<!-- BADGES:START -->
-[![CI](https://github.com/moonrunnerkc/swarm-orchestrator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/moonrunnerkc/swarm-orchestrator/actions/workflows/ci.yml)
-[![license ISC](https://img.shields.io/static/v1?label=license&message=ISC&color=blue)](LICENSE)
-[![node >= 20](https://img.shields.io/static/v1?label=node&message=%3E%3D%2020&color=3c873a)](package.json)
-[![version 12.0.0](https://img.shields.io/static/v1?label=version&message=12.0.0&color=22d3ee)](package.json)
-[![oracle recall 93% (301/325)](https://img.shields.io/static/v1?label=oracle%20recall&message=93%25%20(301%2F325)&color=brightgreen)](benchmarks/results/AB-REPORT.md)
-[![real-PR false alarms 0.11/PR](https://img.shields.io/static/v1?label=real-PR%20false%20alarms&message=0.11%2FPR&color=brightgreen)](benchmarks/real-prs/REAL-WORLD-REPORT.md)
-[![real-PR cheats vs linters 4 confirmed (Semgrep+ESLint: 1)](https://img.shields.io/static/v1?label=real-PR%20cheats%20vs%20linters&message=4%20confirmed%20(Semgrep%2BESLint%3A%201)&color=brightgreen)](benchmarks/real-prs/v11-BENEFIT-REPORT.md)
-<!-- BADGES:END -->
-
-<p align="center">
-  <a href="#install">Install</a> ·
-  <a href="#quick-start">Quick start</a> ·
-  <a href="#results">Results</a> ·
-  <a href="#cheat-detectors">Detectors</a> ·
-  <a href="#use-as-a-github-action">GitHub Action</a> ·
-  <a href="#ai-bom">AI-BOM</a> ·
-  <a href="#orchestrator-mode">Orchestrator</a> ·
-  <a href="#architecture">Architecture</a> ·
-  <a href="#commands">Commands</a> ·
-  <a href="#limitations">Limitations</a>
-</p>
+# swarm-orchestrator
 
-## Install
-
-Node 20 or later. See [`package.json`](package.json).
-
-```bash
-git clone https://github.com/moonrunnerkc/swarm-orchestrator.git
-cd swarm-orchestrator
-npm install
-npm run build
-npm link
-swarm --help
-```
-
-## Quick start
-
-```bash
-# Audit a PR by reference (advisory by default; never blocks the merge)
-GITHUB_TOKEN=... swarm audit moonrunnerkc/swarm-orchestrator#42
-
-# Opt in to merge-blocking gate mode (blocks only on a self-certifying
-# runtime proof; enable the execution-grounded layer in
-# .swarm/audit-config.yaml first; see docs/audit-config.md)
-GITHUB_TOKEN=... swarm audit moonrunnerkc/swarm-orchestrator#42 --mode gate
-
-# Audit a local diff with all 11 detectors
-git diff main...HEAD | swarm audit --diff-stdin --detectors experimental
-
-# Audit and emit a CycloneDX 1.6 ML-BOM
-swarm audit --diff-file my.patch --emit-aibom cyclonedx-ml
-
-# Shadow mode: record verdicts to disk without commenting or gating
-swarm audit --pr <ref> --shadow my-org/my-repo
-```
-
-Exit codes: `0` advisory or any advise-mode run, `1` block (gate mode only), `2` usage error.
-
-## Results
-
-Every number here is reproducible from this repo and runs offline.
-
-### Catches cheats that linters miss
-
-| PR | Cheat caught | Semgrep / ESLint |
-|---|---|---|
-| [cloudflare/workers-sdk#14063](https://github.com/cloudflare/workers-sdk/pull/14063) | fake refactor: function renamed but two callers still use the old name | not flagged |
-| [cloudflare/workers-sdk#14132](https://github.com/cloudflare/workers-sdk/pull/14132) | error swallow: bare empty `catch` silently hides every error in the block | not flagged |
-
-Both reproduce deterministically from the committed diffs. Semgrep (210 rules) and the ESLint security ruleset flag neither. Reproduce either with `swarm audit --diff-file benchmarks/real-prs/diffs/cloudflare-workers-sdk/<pr>.diff`. Full study across twelve repos in [`benchmarks/real-prs/v11-BENEFIT-REPORT.md`](benchmarks/real-prs/v11-BENEFIT-REPORT.md).
-
-### Detection numbers
-
-**301 of 325** planted cheats recovered (92.6%) across thirteen categories scored against a defect-injection oracle: 258/275 structural plus 43/50 on the two semantic categories the judge-primary path covers. The behavioral `cheat-mock-mutation` category drove the latest gain: focusing the judge on the hunks that add a value-injecting mock lifted its recall from 0.16 (the prior rapid-mlx glm47 run) to 0.96 (24/25) on the local qwen3.6 judge, while the clean-PR judge false-positive rate fell from 10% to 0%. Reproduce with `SWARM_JUDGE_PROVIDER=ollama SWARM_JUDGE_MODEL=qwen3.6:35b-a3b npm run benchmarks:full`; A/B with the same-model decomposition in [`benchmarks/results/AB-REPORT.md`](benchmarks/results/AB-REPORT.md) and per-detector recall in [`benchmarks/oracle-corpus/per-detector-recall.md`](benchmarks/oracle-corpus/per-detector-recall.md).
-
-**0.11 findings per PR** on an 18-PR pilot across five public repos. At or below the pre-upgrade auditor's false-alarm burden, with the oracle recall gain intact. Full numbers in [`benchmarks/real-prs/REAL-WORLD-REPORT.md`](benchmarks/real-prs/REAL-WORLD-REPORT.md).
-
-### Execution-grounded layer
-
-Reproduce with `npm run execution-grounded:full`. This optional layer sets up a sandboxed checkout and runs mutation testing, repro execution, and a coverage delta scoped to the lines the PR changed. It surfaced one proof-correlated catch: proof anchor [`trpc/trpc#6098`](https://github.com/trpc/trpc/pull/6098), where 8 lines with surviving mutations were later changed by a hotfix. Evaluation in [`benchmarks/real-prs/v11-EXECUTION-GROUNDED-REPORT.md`](benchmarks/real-prs/v11-EXECUTION-GROUNDED-REPORT.md).
+[![gates](https://img.shields.io/github/actions/workflow/status/moonrunnerkc/swarm-orchestrator/gates.yml?branch=v13-main&style=flat-square&label=gates)](https://github.com/moonrunnerkc/swarm-orchestrator/actions/workflows/gates.yml)
+[![npm](https://img.shields.io/npm/v/swarm-orchestrator?style=flat-square&label=npm)](https://www.npmjs.com/package/swarm-orchestrator)
+[![node](https://img.shields.io/badge/node-%3E%3D24-blue?style=flat-square)](package.json)
+[![license](https://img.shields.io/github/license/moonrunnerkc/swarm-orchestrator?style=flat-square)](LICENSE)
 
-## Cheat detectors
+A coding agent whose claims about its own work resolve to machine-captured evidence.
 
-Eleven detectors. Eight load by default; three (`comment-only-fix`, `exception-rethrow-lost-context`, `dead-branch-insertion`) require `--detectors experimental` because they have no real-PR signal yet to measure against. Registered in [`src/audit/cheat-detector/detector-sets.ts`](src/audit/cheat-detector/detector-sets.ts).
+The model can say whatever it likes. It cannot make a gate pass, it cannot mark a claim
+verified, and it cannot change a record after the fact. Those are the harness's to decide,
+and the run exports a signed, hash-chained bundle that anybody can check without installing
+this tool.
 
-| Category | Set | Trigger |
-|---|---|---|
-| `error-swallow` | default | Bare empty or comment-only `catch` block added in non-test code. |
-| `mock-of-hallucination` | default | `jest.mock` / `vi.mock` / `@patch` against a module declared in no manifest in the repo. |
-| `no-op-fix` | default | Test modified with no source change, or vice versa; import-graph reachability fallback when only one side moved. |
-| `fake-refactor` | default | Exported symbol renamed in source, no caller in the diff updates the old name. |
-| `coverage-erosion` | default | Source branch added with no compensating test addition. |
-| `test-relaxation` | default | Strict matcher swapped for a loose one, or a test block removed without same-chunk replacement. |
-| `assertion-strip` | default | Net assertion count in a test file drops after the PR. |
-| `type-suppression` | default | A type-checker or linter suppression (for example `@ts-ignore` or `eslint-disable`) added over a changed line. |
-| `comment-only-fix` | experimental | Source modifications are all comment additions. |
-| `exception-rethrow-lost-context` | experimental | `throw err` replaced with `throw new Error(...)` and `{ cause }` not forwarded. |
-| `dead-branch-insertion` | experimental | Branch guarded by a literal-false condition added. |
+[What it does](#what-it-does) | [Install](#install) | [Use](#use) | [Watching it work](#watching-it-work) | [What is claimed](#what-is-claimed) | [What is not claimed](#what-is-not-claimed) | [How it works](#how-it-works) | [Limits](#limits) | [Upgrading from v12](#upgrading-from-v12)
 
-Beyond the structural detectors, a judge-primary path catches two semantic categories (`goal-not-fixed`, `cheat-mock-mutation`) by asking the judge whether the diff delivers the PR's stated claim. For `cheat-mock-mutation` a deterministic pre-filter hands the judge only the test hunks that add a value-injecting mock, so the judge reads the six-line cheat instead of skimming a 40k-char diff, and is never asked on a clean PR that adds no such mock. A proven mock-mutation can also block under `--mode gate` as a self-certifying `mock-mutation-proven` trigger (see [`docs/limitations.md`](docs/limitations.md)).
+## What it does
 
-Per-repo configuration in `.swarm/audit-config.yaml`: `excludePaths`, `intentSeverityPolicy` (`strict` | `lenient` | `off`), and `judgePrimary`. See [`docs/audit-config.md`](docs/audit-config.md).
+Give it a task and a git workspace. It plans, declares the files it intends to touch, edits
+through a chokepoint that records every tool call, runs your gates, and retries failures
+under a numeric ratchet that refuses a fix which trades away tests, assertions, or coverage.
+Then it exports the evidence.
 
-## Use as a GitHub Action
+Here is a real run, committed: [`live-tasks.md`](docs/evidence/2026-08-18/live-tasks.md),
+with its bundle in [`live-frontier/`](docs/evidence/2026-08-18/live-frontier). And here is the
+packaged tool doing it, installed from a tarball into a directory holding nothing else, against
+a workspace it had never seen, recorded in a real terminal:
+[`installed-package-run.md`](docs/evidence/2026-08-23/installed-package-run.md).
 
-```yaml
-name: PR audit
-on:
-  pull_request:
-    types: [opened, synchronize, reopened, ready_for_review]
-permissions:
-  pull-requests: write
-  contents: read
-jobs:
-  audit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: moonrunnerkc/swarm-orchestrator@main
-        with:
-          audit-mode: true
-          mode: advise           # advise | gate
-          detectors: default     # default | experimental
-          emit-aibom: cyclonedx-ml
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-```
-
-Outputs: `audit-pass`, `audit-findings`, `audit-ledger`. Full input list in [`action.yml`](action.yml).
-
-### Enabling the execution-grounded layer
-
-Structural detectors run with no setup and only ever flag (advisory). The six runtime proofs that can gate a merge (`test-tamper`, `mock-mutation`, `no-op-fix`, `type-suppression`, `fake-refactor`, `dead-branch`) need the execution-grounded layer, which is off until you set `executionGrounded.enabled: true` in [`.swarm/audit-config.yaml`](docs/audit-config.md). Turning it on is what lets `--mode gate` block, and every block it produces ships the exact command that reproduces it in a fresh checkout.
-
-What it costs: for each audited PR the layer provisions the repository in a sandbox (clone the head, install dependencies, run the affected tests), so it adds clone, install, and test wall-clock to the job, and only PRs in a Node project with a lockfile and a recognized test runner (jest, vitest, mocha) provision at all. Everything else fails closed to advisory. The static viability screen on the project corpus measured 12 of 197 PRs as provisionable ([`benchmarks/real-corpus/eg-viability.json`](benchmarks/real-corpus/eg-viability.json)); your own repository, where the suite is known to run in CI, provisions far more reliably than an arbitrary sample. Nothing the layer cannot prove ever blocks: with the layer off, or on a non-provisionable PR, gate mode passes on advisory findings alone.
-
-## AI-BOM
-
-`--emit-aibom cyclonedx-ml | spdx-ai | both` writes one document per format per run under `.swarm/aibom/`. Emitters in [`src/audit/aibom/`](src/audit/aibom/) produce hand-rolled JSON against the upstream specs with no third-party AI-BOM runtime dependency.
-
-Procurement mappings:
-
-- [`docs/eu-ai-act-mapping.md`](docs/eu-ai-act-mapping.md): EU AI Act (European Union Artificial Intelligence Act) Article 11 + Annex IV fields.
-- [`docs/cisa-sbom-ai-mapping.md`](docs/cisa-sbom-ai-mapping.md): CISA (Cybersecurity and Infrastructure Security Agency) SBOM-for-AI minimum elements.
-
-## Orchestrator mode
+## Install
 
-Grades patches against a typed contract instead of auditing a PR diff.
+    npm install -g swarm-orchestrator
 
-```bash
-swarm init                                    # Scaffold contract.yaml + patches.jsonl
-swarm run --goal "check this project builds"  # Deterministic provider, no API key
-```
+That is **13.1.4**, and it leaves `swarm` on your path.
 
-Minimal contract:
+Installing from a tag works too, but only into a project rather than globally:
 
-```yaml
-obligations:
-  - type: build-must-pass
-    command: npm run build
-  - type: test-must-pass
-    command: npm test
-```
+    npm install github:moonrunnerkc/swarm-orchestrator#v13.1.4
 
-Hosted-model run:
+`dist/` is not committed, so a git ref builds itself on install and needs this package's
+devDependencies to do it. npm does not install those when a git ref is installed with `-g`: it
+carries the global context into its git-dependency preparation, places the clone as a root
+package, and runs the build without the compiler. The published package needs no build, which
+is why the line above it is the one to use.
 
-```bash
-export ANTHROPIC_API_KEY=sk-...
-swarm run --goal "add a /health endpoint" --extractor anthropic --session anthropic
-```
+Anything below 13 is a different program. This package name carried a pull-request auditor
+through 12.x, and `npm install -g swarm-orchestrator@12` still installs it, so pin the major if
+you depend on one or the other: [Upgrading from v12](#upgrading-from-v12).
 
-Local-LLM run (Ollama):
+Node 24 or newer. That is a runtime floor rather than a preference: the coverage cycle
+spawns the test runner with `--test-isolation=process`, which Node 22 rejects as a bad
+option, so on anything older that measurement does not happen.
 
-```bash
-swarm run --goal "add a named export sum(a, b)" \
-  --session local --local-backend ollama \
-  --local-base-url http://localhost:11434 \
-  --local-model-session gemma4:31b \
-  --local-grammar none --local-max-concurrency 1 --preset fast
-```
+## Use
 
-Provider details in [`docs/providers.md`](docs/providers.md). Obligation taxonomy in [`docs/check-types.md`](docs/check-types.md). Schema in [`src/contract/schema/v1.json`](src/contract/schema/v1.json).
+    swarm "make slugify collapse whitespace and strip punctuation"
 
-## Architecture
+    swarm gates                      # run the gates over a workspace, no model
+    swarm select                     # probe this machine, recommend a local model
+    swarm calibrate                  # measure candidate models on the golden set
+    swarm routing                    # what the reward log adds up to
+    swarm parallel --tasks <file>    # one worktree per task, then a merge queue
+    swarm review <bundle>            # what a past run produced, and open it
+    swarm replay <bundle>            # read a bundle back
 
-Two command-line interface (CLI) surfaces share one core. `swarm run` drives the v8 pipeline (extractor, session, predicate-runner, falsifier, verifier). No patch reaches main without passing both `verifyObligation` and `postMergeVerify`.
+    swarm --no-tui "..."             # plain lines even on a terminal
+    swarm --no-color "..."           # no colour, whatever the terminal says
+    swarm --open-evidence "..."      # open the review page when it finishes
+    swarm --model local:<id> "..."   # a specific model
+    swarm --workspace <dir> "..."    # a repository other than the current directory
+    swarm --base <ref> "..."         # what the diff and the ratchet measure against
+    swarm --attempts <n> "..."       # how many times the ratchet may retry a gate
+    swarm --max-steps <n> "..."      # how long the loop may run before it stops
+    swarm --local-endpoint <url>     # an OpenAI-compatible server other than the default
 
-`swarm audit` reuses the verifier and falsifier layers against a unified diff, with no session, extractor, or model credentials needed. Both surfaces write to the same append-only hash-chained ledger ([`src/ledger/ledger.ts`](src/ledger/ledger.ts)); tampering breaks the chain.
+`swarm --help` prints all of it, including the calibration flags.
 
-## Commands
+Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` for a frontier
+model, or start Ollama or rapid-mlx and pass `--model local:<id>`. With no model named, the
+router picks one from what the calibration measured on this machine, and `swarm routing` shows
+what it has learned.
 
-| Command | Purpose |
-|---|---|
-| `swarm audit <ref \| --diff-*>` | Audit a PR or local diff. Advisory by default. |
-| `swarm run --goal "<text>"` | Compile and grade in one step. |
-| `swarm compile <goal>` | Write a reusable compiled contract directory. |
-| `swarm run <contract-dir>` | Grade against a pre-compiled contract directory. |
-| `swarm resume <run-id>` | Resume a killed run from its ledger. |
-| `swarm stats <run-id>` | Aggregate diagnostic counts from a run ledger. |
-| `swarm ledger verify <run-id>` | Verify a hash-chained ledger at rest. |
-| `swarm init` | Scaffold `contract.yaml` and `patches.jsonl`. |
-| `swarm doctor [--fix] [--connectors]` | Probe local prerequisites. |
+Settings live in one optional `swarm.toml`: providers and endpoints, gate definitions, budgets,
+model pins, and the `[interface]`, `[theme]` and `[keys]` tables. Flags win over the file.
 
-`swarm <cmd> --help` for the flag list of any subcommand.
+## Watching it work
 
-## Run artifacts
+On a terminal, a run draws a single screen you can drive. Off one, it writes the same plain
+lines it always did, so pipes and CI are unchanged.
 
-```text
-.swarm/contracts/<id>/contract.jsonl   compiled contract (orchestrator mode)
-.swarm/ledger/<run-id>.jsonl           orchestrator ledger
-.swarm/ledger/audit-<run-id>.jsonl     audit ledger
-.swarm/aibom/<run-id>.cdx.json         CycloneDX-ML (when --emit-aibom)
-.swarm/aibom/<run-id>.spdx.json        SPDX 3.0 AI-Profile (when --emit-aibom)
-.swarm/shadow/<repo>/<run-id>.json     shadow-mode verdict (when --shadow)
 ```
-
-`.swarm/` is in [`.gitignore`](.gitignore) at the consumer-repo level.
-
-## Integrations
-
-- Claude Code slash command: [`.claude/commands/swarm-audit.md`](.claude/commands/swarm-audit.md)
-- Cursor rule pack: [`integrations/cursor/swarm-audit.mdc`](integrations/cursor/swarm-audit.mdc)
-- Aider pre-commit hook: [`integrations/aider/pre-commit-swarm-audit`](integrations/aider/pre-commit-swarm-audit)
-
-## Limitations
-
-No single detector has cleared the precision bar to block on its own. Gate mode blocks only on a self-certifying runtime proof whose per-instance controls are all green: test-tamper, mock-mutation, no-op-fix, type-suppression, or fake-refactor restoration, claim falsification, or obligation failure. The first such proof fired on a dogfood PR in June 2026. The full accounting, including the measured gate precision and what blocks today and what doesn't, is in [`docs/limitations.md`](docs/limitations.md).
-
-## Contributing
-
-```bash
-npm install && npm run build && npm test
-npm run typecheck && npm run lint
+swarm  make the parser trim before it splits
+  local:qwen3-coder:30b-a3b  /Users/brad/projects/scratch-repo  20s  step 4  5812 tokens  attempt 1/3
+plan
+  read the failing test, fix the parser, run the gates
+actions
+  edit path=src/parse.ts find=text.split replace=text.trim().split
+  shell command=npm test
+  shell failed: 1 failing
+  ratchet accepted: tests collected 12 to 12, assertions 34 to 35, skips 0 to 0
+gates  attempt 1/3
+  PASS tests: 12 collected, 0 failed
+  PASS lint: no findings in 208 files
+  N/A  coverage: no lcov artifact was written to the path the harness named
+  WARN diff-budget (advisory): 1 file changed, 1 line added, budget 12 files and 400 lines
+DONE stopped: completed (4 steps, 5812 tokens)
+j scroll  enter expand  tab pane  / filter  e evidence  ? help  q detach  ctrl+c cancel run
 ```
 
-Project conventions in [`CONTRIBUTING.md`](CONTRIBUTING.md). New cheat detectors must include an injector under `src/audit/oracle/inject/` so recall is measurable from day one. Security disclosures via [`SECURITY.md`](SECURITY.md), never via public issues.
+`?` lists every key. `enter` expands a row to its whole payload and the ledger record it came
+from. `q` leaves the view and lets the run finish; `ctrl+c` cancels the run. There is no
+progress bar, because an agent run has no denominator.
+
+When the run ends, the screen lists what it produced, says how many claims the harness
+verified and how many it refused, and offers to open the review page. It says the bundle
+verified only if the bundle's own verifier ran here and exited 0. `swarm review <bundle>`
+shows the same panel for any bundle already on disk.
+
+The keymap, the `swarm.toml` surface, the degradation matrix, and a recording of a session
+are in [`interface.md`](docs/evidence/2026-08-23/interface.md), with the frames in
+[`interface-frames.txt`](docs/evidence/2026-08-23/interface-frames.txt) and a playable
+asciinema capture in [`interface.cast`](docs/evidence/2026-08-23/interface.cast).
+
+## What is claimed
+
+Every line here links to a committed artifact of the thing happening. The full table,
+including what backs each one, is [`docs/claims.md`](docs/claims.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 (predicate-unparseable)` and carried on, twice, until the model wrote one that
+could be evaluated:
+[shakedown results](docs/evidence/2026-08-18/shakedown/results.md).
+
+**One changed byte breaks verification.** The same bundle, verified and then tampered with
+in a single byte of one record, exit 0 and exit 1 side by side, with a script to reproduce
+it: [tamper demo](docs/evidence/2026-08-18/tamper-demo).
+
+**The bundle carries its own verifier, and it works on a machine that has never seen this
+repo.** `node verify.mjs <bundle>` checks the manifest, the chain, the signature, every blob
+against its content address, and recomputes every claim verdict. Run in a `node:24` container
+with no network and no mount of this repository: exit 0 on the committed bundle, exit 1 on the
+same bundle one byte later, with the image digest and both transcripts in
+[`clean-container-verification.md`](docs/evidence/2026-08-23/clean-container-verification.md).
+Transcripts from two earlier runs outside the repository:
+[`live-tasks.md`](docs/evidence/2026-08-18/live-tasks.md).
+
+**Bundles are signed from the OS keychain**, not from a key in the workspace. Both manifests
+in [`live-tasks.md`](docs/evidence/2026-08-18/live-tasks.md) say `"keySource": "keychain"` and
+both verifiers confirm it. Where the keychain holds no usable key the run signs with a per-run
+key and says which of the three keychain failures happened, rather than signing quietly with
+something else; the manifest then records `keySource: ephemeral`, which is what the bundles in
+[`installed-package-run.md`](docs/evidence/2026-08-23/installed-package-run.md) carry.
+
+**Local model choice is measured on your machine.** The probe output and recommendation from
+real hardware: [`hardware-select.md`](docs/evidence/2026-08-18/hardware-select.md). A hundred
+and eighty calibration runs across three models, distributions rather than averages, with the
+pick ranked against the other two:
+[`calibration-report.md`](docs/evidence/2026-08-23/calibration-report.md).
+
+**Eight untrusted boundaries are fuzzed**, and the harnesses are checked against a defect
+injected on purpose so a clean run cannot be a blind one: [`fuzz/`](fuzz/README.md) and
+[`security-coverage.md`](docs/security-coverage.md).
+
+**The screen renders from ledger projections, and a keystroke has no route to a verdict.**
+Interactive state is a separate type with a separate reducer, and a test asserts across every
+action that none of its fields can be mistaken for a gate result:
+[`interface.md`](docs/evidence/2026-08-23/interface.md).
+
+**Adversarial passes, with each closure locked as a regression test.** Six pass directories
+under [`redteam/`](redteam), 49 cases in `src/evidence/redteam-adversarial.test.ts`, and an
+accounting record mapping each pass to what it actually was, because the driver ledger
+records one completed lap and a directory is not a lap.
+
+## What is not claimed
+
+Kept short and kept honest, because the point of the rest of this file is that claims cost
+something.
+
+- **Not "fully secure".** The secret detector does known-pattern scrubbing, not secret
+  removal, with a four-character floor. Zero crashes at a fuzz budget is evidence, not proof.
+- **No benchmark numbers.** Nothing here is measured against another tool. The calibration
+  results are self-run, on one machine, and labelled directional in the file itself.
+- **Four known gaps are open**, not closed, and they ship that way. They are in
+  [build guide 7.1](docs/build-guide.md), and each is a permanent test case asserting the
+  gap as it stands.
+- **A signature does not make the machine honest.** It proves the bundle was not altered
+  after it left the machine that produced it. The review page says that on its face.
+
+## How it works
+
+- **Claims are predicates, not prose.** A claim names a record, a record kind, and a
+  machine-checkable predicate. The harness recomputes the record's kind, evaluates the
+  predicate, and decides. Model narrative always renders as unverified prose.
+- **The ledger is append-only and hash-chained.** Each record carries the previous record's
+  hash. A failed write aborts the run. Nothing is updated or deleted, ever.
+- **Every tool call goes through one chokepoint** that records it, tags its provenance, and
+  enforces the sandbox. Credential paths are denied by default and each denial is itself
+  recorded.
+- **Gates are data.** A gate declares a command, a parser, and whether it blocks. The engine
+  never special-cases one.
+- **The ratchet is numeric.** Tests collected, assertions in touched test files, coverage of
+  changed lines, skip markers. Coverage comes from a report the runner wrote where the
+  harness told it to, never from what a gate printed, and an unobtainable measure is
+  reported as "not measured" rather than as a pass.
+
+The full design, including what it refuses to build and why, is in
+[`docs/build-guide.md`](docs/build-guide.md).
+
+## Limits
+
+Gates prove mechanical quality. They do not prove design quality, and nothing here pretends
+a passing run means the change is good. What the bundle buys you is that reviewing the
+change is fast and that its claims are checkable, not that review is unnecessary.
+
+## Upgrading from v12
+
+v12 was a PR auditor that ran as a GitHub Action. v13 is a coding agent. Same package name,
+different product, no migration path. If you are using v12, stay on it: it is tagged
+`v12-final`. Details in [`CHANGELOG.md`](CHANGELOG.md).
 
 ## License
 
-[ISC](LICENSE).
+ISC. See [`LICENSE`](LICENSE).