README
¶
nova-swarm
What it is
nova-swarm: one-task AI workers, each run in the sandbox with a deadline and a token budget
Why use it
Get independent jobs done in parallel.
Install
go install github.com/mas-bandwidth/nova-tools/cmd/nova-swarm@latest
nova-swarm version
First run
The transcript below is executed line for line by the docs tests; the full record is in docs/TESTS.md.
Fixture: owned directories under t.TempDir() and fake harnesses. The transcript
comparators invoke the dispatcher with fixture paths and compare its output with
the examples below. The quickstart guide shows a
native run and a sprint member.
$ nova-swarm template --name read-pr
read-pr — read one pull request against the rules
1. READ THE PR BODY'S OWED LIST FIRST, before reading any code, and for every
finding you report, say whether it is already on that list. A finding that
is already owed is marked `dup:` and is not a new finding.
[batch 1: 25 of 67 findings were duplicates of the owed list]
2. QUOTE EVERY RULE VERBATIM, with `file:line`. Never paraphrase a rule from
memory, and never assert a rule you did not open.
[batch 1: 5 of 67 findings were wrong, each a paraphrase]
3. APPEND EACH FINDING TO RESULT.md THE MOMENT IT EXISTS. Not at the end.
You may be killed at your deadline; what is on disk is what you found.
4. A FILE BUDGET: read at most <n> files (the limit stated in the card). When the budget
is spent, write what you have and stop. Say in RESULT.md which files you
did not open.
[batch 3: with a budget, 2 of 3 tasks complete; without, 0 of 3]
5. A RESULT.md CONTAINING ONLY A PLAN IS A FAILED TASK. The plan belongs at
the top, before the work; the findings are the work. A finished read that
found nothing is NOT a failed task: write the `## Head` with `findings: 0`.
Never report a finding to have something to report.
6. If a board was supplied, check it before reporting: a card that already names
this is a `dup:`. Do not search for an unspecified board.
7. A SEVERITY FLOOR: emit only findings at or above `HIGH`. A finding below the
floor is not emitted at all. State the floor in RESULT.md's `## Head`
paragraph as `floor: HIGH`, and mark each emitted finding with its
severity. The floor decides which findings are emitted, not how they are
written: every emitted finding still quotes its rule verbatim with `file:line`.
Keep RESULT.md concise: omit progress narration, praise, repeated task text, and a
separate summary. Each finding keeps its proof in compact form: severity, `file:line`,
the exact quoted rule, the fix, and `dup:` status when applicable. Retain every valid
finding, its context and evidence, and any coverage limitation; do not drop context or
evidence by default. Brevity is a soft target: never hard-truncate findings or proof; if
the report overflows, preserve the proof and say so. Preserve the complete RESULT.md
shape and its mandatory `## Head`, `## Findings`, `## Per item`, `## Gates`,
`## Left owed`, and `## One line` sections.
In Gates, distinguish source checks from tests and report-writing commands.
Mark only checks actually performed as pass; no tests run does not mean no commands run.
BOUND THE REPORT: findings only. No narration of the clone, no restated
task, no praise, no summary. One line per finding: `file:line`, the rule
quoted verbatim in at most twelve words (a longer rule by the twelve of its
own words the finding rests on, never a paraphrase: rule 2 holds), the
severity, and the fix in one clause. Keep RESULT.md under 40 lines and
every line under 300 characters, and no pipe inside backticks: a `|` in a
quote breaks the report's table grammar, so quote the rule without it. Put
the verdict line last. When there is nothing to report, write `findings: 0`.
Verbs
The nova-swarm section of the command reference documents every verb's flags, effect and exit codes.
versiondoctorverifylintsteptemplateprofilenativememberdisk-guardslotsworker
Spec
The contract is docs/SPEC-SWARM.md.
Documentation
¶
Overview ¶
nova-swarm doctor: refuse to launch under a shadowed or unreadable binary.
A card that a rebuilt swarm starts must run the build that was rebuilt. When PATH puts an older nova-swarm before the one at ~/.local/bin, every card runs the older one and nothing downstream can tell which build ran. The doctor reads the one `version` line the nova-swarm first on PATH prints and the one the literal ~/.local/bin/nova-swarm prints, and if the two differ it prints both in full and names the fix. `native` runs the same check before they start anything, so a launch refuses before it spends rather than after somebody notices. It invents no version of its own: pkg/buildinfo produces the line and this file only reads what a binary said.
`DOCTOR OK stamp=<line>` says the two agree, or that there is one binary to read. A mismatch is exit 2 with both stamps and one remedy, because a refusal that does not say which line is stale sends the reader back to run the check by hand.
A binary that cannot be read is a refusal, not a shrug. A `version` that hangs past the deadline, exits non-zero, prints nothing, prints a first line past the limit, or names a file that is not there is exit 2 with one DOCTOR UNREADABLE line: the binary's path, the cause, what the other binary came to, and the next action. A stamp printed before the failure is still compared. The one tolerated absence is the ~/.local/bin copy: with none installed there is nothing to shadow with.
Only the first line of a binary's output is kept, up to a fixed limit, and a stamp is printed as a bounded, escaped excerpt, so a binary that streams forever costs the doctor neither memory nor an unbounded line. The two binaries are read at the same time under one deadline.
The machine is a doctorEnv (the PATH lookup, the home directory and the version reader), so the whole check is driven with fixed binaries and short deadlines; production uses the real LookPath, the real home, and `<path> version`.
nova-swarm runs one-task AI workers through a harness. Each native launch has its own job directory and data home, with a deadline and token budget held by the runner. A member runs a sprint's cards as native children and reports their results to the sprint server (docs/SPEC-SWARM.md).
A card names the task and its rules. Worker descriptions name the model, credentials and readable directories. Templates and lint prepare a card; native runs it; verify checks its result against a contract.
Worker output is data. RESULT.md reports a claim to check against the repository; it grants no authority (docs/SPEC-SWARM.md).
slots are bench-wide leases with shares, reserve, expiry and live-pid fencing (docs/SPEC-SWARM.md, "Bench slot leases"): `slots init` makes a store, `slots take` grants (optional --kind charges the card's admission weight), `slots release` frees, `slots list` prints one line per lease, `slots run` wraps a command under a lease.
nova-swarm version: which build is running.
A refusal, a green or a line somebody pastes into a note is evidence about a BUILD, and until this verb existed this binary could not say which one it was: `nova-swarm version` was exit 2, unknown subcommand. So "we are all running the same nova-swarm" was a belief rather than a reading, and the release could not assert over the set what no member of the set would answer.
The version is NOT a constant maintained by hand -- a hand-maintained constant is wrong exactly at the commit after the release, where it still names the release. It is read from the build itself by pkg/buildinfo, which holds the resolution order and the shape of the line for every binary here, so that eleven tools answer this question in one spelling rather than eleven.
Source Files
¶
- authmode.go
- catalog.go
- diskfree_unix.go
- diskguard.go
- doctor.go
- executable.go
- executable_unix.go
- install.go
- keys.go
- lazyclean.go
- lint.go
- lintdecide.go
- main.go
- member.go
- memberattempt.go
- memberpush.go
- mirror.go
- native.go
- native_proc_unix.go
- nativedecide.go
- nativegate.go
- nativeprovider.go
- nativesample.go
- shellshim.go
- slotclean.go
- slots.go
- startretry.go
- step.go
- verbhelp.go
- version.go
- workercheck.go