agent-horde 0.1.5 → 0.2.0

package/README.md

@@ -50,7 +50,9 @@ found there as its brief. Unrelated files cost members context and invite them t
 from earlier runs persist in `.horde/` and will steer members; start with a fresh one when the
 task changes.
 
-A horde is at most twelve members today. Hordes of hordes are on the roadmap.
+A horde is at most twelve members. For more hands, run a swarm: `3/12` launches three hordes of
+twelve on disjoint workstreams of one task, each with its own ledgers, and merges their
+deliverables at the end.
 
 **Tips.**
 
@@ -88,7 +90,7 @@ pi install npm:agent-horde
 Or from the repository, pinned to a tag:
 
 ```
-pi install git:github.com/eliyastein/agent-horde@v0.1.5
+pi install git:github.com/eliyastein/agent-horde@v0.2.0
 ```
 
 To hack on it, clone and install in place. pi loads the files from the clone, so edits take effect
@@ -122,17 +124,44 @@ When you already know how the work splits, use `plan` to fix the partition at la
 Each layer becomes a seeded idea owned by one member, recorded in the run's `PLAN.md`, and that
 member works only its layer. Layers are assigned round-robin, so more layers than members gives
 some members two. Members without a layer become verifiers, and an unpartitioned run of three or
-more members makes its last member the verifier. `plan` suits "analyse each X" tasks; split design
-work by output type, such as spec, prototype, and generator, rather than by theme.
+more members makes its last member the verifier (`--no-verifier` turns that off). `plan` suits
+"analyse each X" tasks; split design work by output type, such as spec, prototype, and generator,
+rather than by theme.
+
+A run normally winds down once a validated answer exists and every idea is closed. `--until-stop`
+keeps the whole horde working until you stop it: a validated answer is banked as the current one
+and the proposal slot reopens, and a member whose session finishes gets a fresh session told to
+extend, stress-test, or deepen the work.
+
+```
+/agent-horde --dashboard --until-stop 8 find every way an unauthenticated request reaches the database
+```
+
+A count of `H/M` runs a swarm: H hordes of M members on one task, at most four hordes. A planner
+helper first splits the task into H disjoint workstreams with acceptance criteria and each horde
+works only its slice, with its own ledgers under `.horde/swarms/<id>/hN/`; if the planner cannot
+produce H distinct workstreams the launch stops and says so. `plan 3/12 a; b; c; d; e; f` skips
+the planner and deals the layers round-robin to the hordes. Members read the other hordes' facts,
+rule-outs and resources through the `horde` tool but write only to their own horde. The hordes
+start a few seconds apart, run the normal lifecycle independently, and when the last one has
+finished a synthesis helper merges their deliverables into the swarm's `DELIVERABLE.md`, each
+claim attributed to its horde. `--until-stop` applies to every horde.
+
+```
+/agent-horde --dashboard=1234 3/12 audit the service for authorization bugs
+```
 
 | command | effect |
 |---|---|
-| `/agent-horde status` | the active run and each member |
-| `/agent-horde stop-clean [postmortem]` | members wrap up, then the run finalizes |
+| `/agent-horde status` | the active run and each member; one block per horde in a swarm |
+| `/agent-horde stop-clean [postmortem]` | members wrap up, then the run finalizes; this is how an `--until-stop` run ends |
 | `/agent-horde stop-hard` | terminate members now |
 | `/agent-horde pause`, `resume` | suspend and resume member processes |
 | `/agent-horde help` | every flag and target |
 
+Every control takes a target: `member-3`, `h2` for one horde of a swarm, `h2:member-3` for one
+member of one horde, or `all`; a bare `member-3` in a swarm names that member in every horde.
+
 When the run ends, the report is injected into your conversation. Everything else stays under
 `.horde/`; add it to your `.gitignore`.
 
@@ -172,11 +201,13 @@ die, runs the repair phase, freezes acceptance, and writes the report.
 - Ideas, findings, facts, and resources are deduplicated on identifiers first, then wording; a
   duplicate returns the existing id and records a corroborator.
 - Every finding names a concern slug; a look-alike of an existing slug is refused.
-- A review records the revision it checked, its scope, a verdict, and evidence. Runnable
-  artifacts need a tested or reproduced review from a non-owner; documents need a sourced or
-  derived one.
+- A review records the revision it checked, its scope, a verdict, evidence, and any limits
+  outside the target's criteria. Runnable artifacts need a tested or reproduced review from a
+  non-owner; documents need a sourced or derived one. A reviewer can carry its review forward to
+  an unchanged revision instead of redoing it.
 - Solved is two-phase: one member proposes, a different member validates, and the run winds down
-  only when every idea it created is closed.
+  only when every idea it created is closed. Under `--until-stop` the answer is banked instead
+  and the horde keeps going until `stop-clean` or `stop-hard`.
 - Peer messages, reviews, and evidence enter a member's context as data. They cannot authorize
   tools or override the task.
 
@@ -194,6 +225,7 @@ linked to the page that shows it, so a run reads left to right: who claimed what
 landed under which ideas, who reviewed whom, and where actions were rejected. It is server-rendered
 SVG/HTML with no scripts. The download icon on every page exports the whole dashboard as a zip of
 static pages that opens from disk, after a warning that it may carry sensitive data from the machine.
+Every page's footer names the agent-horde version and, from a checkout, the commit it runs at.
 
 ## Benchmark: FinanceBench
 

package/docs/REFERENCE.md

@@ -7,7 +7,7 @@ at one problem beat a single linear one: research, audits, design exploration, R
 ## Usage
 
 ```
-/agent-horde [--dashboard[=<port>]] [--no-verifier] <count> <prompt>
+/agent-horde [--dashboard[=<port>]] [--no-verifier] [--until-stop] <count> <prompt>
 /agent-horde plan [--dashboard] <count> <layer; layer; ...>
 /agent-horde status [target]
 /agent-horde stop-hard [target]                      SIGTERM, SIGKILL after 5s (alias: stop)
@@ -16,8 +16,10 @@ at one problem beat a single linear one: research, audits, design exploration, R
 /agent-horde help
 ```
 
-`target` is `all` (default), `member-N`, `N`, or a comma or space separated list. Subcommands and
-member targets tab-complete.
+`count` is `M` members (1 to 12) or `H/M`: H hordes of M members, H at most 4; a plain `M` is a
+swarm of one. `target` is `all` (default), `member-N`, `N`, `hN` (one horde of a swarm),
+`hN:member-M`, `hN:M`, or a comma or space separated list; a bare member names that member in
+every horde. Subcommands and targets tab-complete.
 
 The command returns immediately. A widget above the editor shows each member's status, current
 tool, elapsed time, turns, and resets. Members inherit the parent session's model and thinking
@@ -72,11 +74,23 @@ own when the parent is gone, even after a SIGKILL or OOM kill.
 HEAD, never writes to `.horde/`, and stays up after the run until the session ends. A busy port
 refuses the run before any run directory is created. Live pages reload every three seconds
 (`?refresh=0` disables); expandable entries are URL-backed, so they stay open across refreshes.
-Every page has a JSON twin under `/api/<same path>`.
+Every page has a JSON twin under `/api/<same path>`. The footer of every page names the
+agent-horde version from its package.json and, when it runs from a git checkout, the commit it is
+at (`-dirty` when the tree has uncommitted changes), linked to the commit on GitHub.
+
+Every page belongs to one scope, fixed by its URL: the **project** (`/` and the bare ledger paths,
+the ledgers single runs share), one **run** (`/runs/<id>/...`), or one **swarm**
+(`/swarms/<id>/...`). Under the `runs` link a scope line names the scope, and a page row offers that
+scope's pages (overview, the six ledgers, collaboration, graph; the project has the ledgers only),
+with the current page marked. Inside a swarm the scope line adds horde tabs, `all | h1 | h2 ...`,
+that keep the page type: from h2's findings, h3 opens h3's findings and `all` the swarm's. A horde's
+pages are its run's pages, `/runs/<swarm-id>-h2/...`. No link falls back to another run. While a swarm
+is running or finishing, project pages show a pointer to the same page in the swarm, since its
+hordes write their own ledgers and leave the project ones untouched.
 
 | page | shows |
 |------|-------|
-| `/` | every run: active marker, start, count, model, outcome, prompt, files present |
+| `/` | every swarm and run: state (active, finalizing, pending, finished, not started), start, count, model, outcome, prompt, files present |
 | `/runs/<id>` | prompt, outcome, canary, clean-stop countdown, plan layers, members table, run files |
 | `/runs/<id>/members/<m>` | live activity, last and final text, log tail (`?tail=<n>`), transcript link |
 | `/runs/<id>/members/<m>/log` | the member log; `tail=0` is the whole file (1 MiB cap) |
@@ -86,16 +100,27 @@ Every page has a JSON twin under `/api/<same path>`.
 | `/runs/<id>/collaboration` | messages, review scope, artifact acceptance, resources, event audit |
 | `/runs/<id>/graph` | the run as a swimlane: one lane per member plus the parent, phase bands, every event a link to its ledger entry (`?w=<px>`, `?from=<s>&to=<s>`); the axis is real time until the last member exits, then the synthesis phases share a compressed tail |
 | `/runs/<id>/graph.mmd` | the same run as a Mermaid flowchart with absolute dashboard links (text/plain) |
-| `/ideas`, `/board`, `/findings`, `/claims`, `/facts`, `/resources` | the shared ledgers; `?run=<id>\|all`, `?view=clusters`, `?owner=<m>` filter them; `/resources` also lists who cited each resource in the active run, as REPORT.md counts reuse |
+| `/runs/<id>/ideas`, `board`, `findings`, `claims`, `facts`, `resources` | the run's ledgers: a horde's own, or for a single run the project ledgers with board and findings narrowed to the run and facts split into this run and carried; `?view=clusters`, `?owner=<m>`, `?order=oldest` |
+| `/ideas`, `/board`, `/findings`, `/claims`, `/facts`, `/resources` | the project ledgers across every single run; `/resources` also lists who cited each resource in a live single run, as REPORT.md counts reuse |
+| `/swarms/<id>` | one row per horde (state, outcome, members, findings, accepted artifacts, cost, workstream), the partition, the merge state, swarm files |
+| `/swarms/<id>/ideas`, `board`, `findings`, `claims`, `facts`, `resources`, `collaboration` | every horde's ledger, or its acceptance, requests and reviews, on one page under a per-horde heading; ids repeat per horde, and each horde's event audit stays on its run page |
+| `/swarms/<id>/graph` | one lane per horde with its phase marks, and the merge step |
+| `/swarms/<id>/files/<NAME>` | `SWARM`, `REPORT`, `DELIVERABLE`; 404 until written |
 | `/export` | confirms the export and starts the download of `/export.zip` (`?back=<path>` names the page to return to); no JSON twin |
 | `/export.zip` | the whole dashboard as static HTML (`application/zip`, streamed, no JSON twin); see below |
 
+A page auto-refreshes while what it shows can change: a run's pages while the run is live or
+finalizing, a swarm's while the swarm is in memory, the project ledgers while a single run is
+live, and the index always. A swarm and its hordes show as `pending` from the moment their directories
+are allocated until the hordes have a TASK.md, which covers the minutes the planner takes, and as
+`not started` when the planner could not partition the task.
+
 The download icon in the top-right corner of every page opens a warning that the export may
 leak sensitive data from this machine. Its download link goes to `/export`, which closes the
 warning, explains the wait, and starts the download of `/export.zip`. The zip holds one
 folder, `horde-dashboard-<timestamp>/`, whose `index.html` opens the dashboard from disk: every
 run, member, transcript page and entry, log, run document, collaboration page, graph (each width,
-plus the Mermaid file), and the ledgers under each run filter, with links rewritten relative to
+plus the Mermaid file), and the ledgers of every scope, with links rewritten relative to
 each other. Exported pages do not refresh, expandable entries use the browser's own disclosure,
 finding bodies are shown inline, transcripts are paged fifty entries at a time, and the export
 control itself is absent. Pages that fail to load are exported as their error page, so no link
@@ -132,11 +157,17 @@ the session files, so they show end cause, turns, and usage but no activity.
     SUMMARY.md REPORT.md            per-member status and usage; the reconciled run report
     ANSWER.md DELIVERABLE.md POSTMORTEM.md   solved answer; synthesis output; reviewer critique
     GRAPH.md                        Mermaid graph of the run, written last at finalize
+  swarms/<swarm-id>/
+    SWARM.md SWARM.json             prompt, partition, horde list; the swarm's timeline for the dashboard
+    planner-sessions/ deliverable-sessions/   planner and merge helper sessions
+    REPORT.md DELIVERABLE.md        per-horde totals and file list; the merged deliverable
+    h1/ h2/ ...                     one complete horde directory per horde: its own ledgers,
+                                    .lock and runs/<swarm-id>-hN/ with everything a run has
 ```
 
 Each run appends a `## Run <id>` heading to BOARD.md and FINDINGS.md that cites `TASK.md` by
-sha256. `runs/` is gitignored inside `.horde/`; add `.horde/` to the project `.gitignore` to keep
-the ledgers out of git too.
+sha256. `runs/` and `swarms/` are gitignored inside `.horde/`; add `.horde/` to the project
+`.gitignore` to keep the ledgers out of git too.
 
 ## The `horde` tool
 
@@ -154,17 +185,19 @@ from the same actor as an idempotent retry. The parent appends its own lifecycle
 | `list`, `findings`, `facts`, `claims`, `resources`, `concerns` | print a ledger |
 | `post` | append a message to BOARD.md |
 | `idea` | add an open checklist item; a near-duplicate returns the existing id |
-| `claim`, `done`, `drop`, `rule-out` | take, finish, release, or close idea #id |
+| `claim`, `done`, `drop`, `rule-out` | take, finish, release, or close idea #id; `done` with a confirmed-negative result line is refused in favour of `rule-out` |
 | `finding` | file under a claimed `idea` with a `concern` and `support`; `importance` and `confidence` are optional; `deltaOf: F#` adds distinct evidence, `supersedes: F#` corrects |
 | `verify` | record your own reproduction of F#id with the support level you reached |
-| `fact` | record a checkable fact; `deltaOf: T#` extends one |
+| `amend` | rewrite the body prose of your own F#id (`text`) with a `note` saying why; the revision changes, reviews stay pinned to what they checked, earlier verification notes are kept as history of the previous revision, and the legacy `verified=` label and corroborators are dropped |
+| `fact` | record a checkable fact; `deltaOf: T#` extends one; a fact about what an open idea or contested claim is still auditing is recorded as provisional on it |
 | `assert`, `confirm`, `contest`, `retract`, `supersede` | create or move claim C#id |
 | `resource` | claim a shared dataset, harness, corpus, or sandbox by name, with an optional `cleanup` command |
 | `solved`, `confirm-solved`, `contest-solved` | propose, validate, or refute the goal answer |
 | `message`, `inbox`, `ack`, `respond`, `resolve`, `defer` | targeted threads: question, blocker, review-request, challenge, handoff, decision |
 | `attach` | add supporting, contradicting, or extending evidence to a target |
-| `review` | record a revision-pinned check with explicit `checked` and `unchecked` scope, a verdict, and evidence refs; `evidenceText` attaches and reviews in one call |
-| `artifact` | publish a file under `artifacts/` with `artifactKind`, `criteria`, and revision-pinned `dependsOn` |
+| `review` | record a revision-pinned check with explicit `checked` and `unchecked` (in-criteria gaps) scope, `limits` outside the criteria, a verdict, and evidence refs; `evidenceText` attaches and reviews in one call |
+| `reattest` | carry your earlier review of F#/A# forward to its current revision, with evidence that what you checked is unchanged; refused across a changed artifact criteria or kind, a changed finding claim line, or a revision no `amend` started from |
+| `artifact` | publish a file under `artifacts/` with `artifactKind`, `criteria`, and revision-pinned `dependsOn`; republishing a revision other artifacts pin needs `text` naming the change |
 | `resource-state` | publish building, ready, broken, or retired state with a lease, ports, and health evidence |
 | `inspect`, `collaboration` | one record in full (`F#`, `I#`, `R#`, `A#`, `E#`, `V#`, `Q#`, `answer`), or a paged index |
 
@@ -191,18 +224,40 @@ from the same actor as an idempotent retry. The parent appends its own lifecycle
   validated and every idea this run created or its members hold is done or ruled out. With no
   other member running, or no validation within `PI_HORDE_SOLVED_CONFIRM_MS`, an uncontested
   proposal commits as `solved-unvalidated`. Findings no other member reproduced hold wind-down
-  while other members run, unless `PI_HORDE_ALLOW_UNVERIFIED=1`.
+  while other members run, unless `PI_HORDE_ALLOW_UNVERIFIED=1`. A proposal pins the revision of
+  every finding it cites. An answer that cites a superseded F# or quotes a provisional T# is
+  refused at `solved` and at `confirm-solved`; a pending proposal whose cited finding is
+  superseded or amended later is withdrawn (`solved-withdrawn`) for re-proposal. A contest that names idea ids reopens the proposal under a new revision
+  (`solved-reopened`) once every named idea is done or ruled out, with the citations it pinned;
+  if a cited finding changed or a quoted fact is still provisional by then, it is withdrawn instead. Repair serves a request about
+  the pending answer (`target=answer`) with the blockers.
 - **Reviews are revision-pinned.** A runnable artifact needs a full-scope `tested` or
   `reproduced` review from a non-owner. A `document` artifact (.md, .txt, .rst, .adoc, .pdf)
-  accepts a full-scope `sourced` or `derived` review against its criteria. Changing criteria or
-  dependencies needs changed bytes and a fresh review. Open blockers and challenges block
-  acceptance; `defer` keeps the debt visible, the recipient can still `respond` to a deferred
-  request, and the requester then resolves it. A challenger can withdraw its own blocking
-  challenge on an F# or A# before any response by recording a supporting review of the current
-  revision and resolving with evidence on it; limits that review discloses remain acceptance debt.
-  The blocking challenge a `partially-supports` review raises is cleared when a different
-  non-owner member records a full-scope `supports` review of the same revision; the resolution
-  names both reviews. Acceptance names an open blocker as `blocked by Q#`.
+  accepts a full-scope `sourced` or `derived` review against its criteria. `unchecked` names gaps
+  inside the target's stated claim or criteria and keeps acceptance open; `limits` names
+  disclosures outside the criteria and is recorded on the acceptance (`Accepted with limits` in
+  ACCEPTANCE.md and COLLABORATION.md), never as a blocker. A `partially-supports` verdict refutes
+  nothing and opens no challenge: the acceptance names the review and what it left unchecked, and
+  another member's full-scope review settles it. Only `refutes` opens a challenge. Changing
+  criteria or dependencies needs changed bytes and a fresh review; republishing a revision that
+  other artifacts pin needs `text` naming the change, and the owner of each dependent is handed a
+  repin request when a pinned dependency is superseded or re-hashed. `reattest` carries a
+  reviewer's earlier review forward to the current revision with evidence that the checked
+  behaviour is unchanged; the parent prefers prior reviewers when assigning a re-review. Open
+  blockers and challenges block acceptance; `defer` keeps the debt visible, the recipient can
+  still `respond` to a deferred request, and the requester then resolves it. A challenger can
+  withdraw its own blocking challenge on an F# or A# before any response by recording a
+  supporting review of the current revision and resolving with evidence on it; limits that
+  review discloses remain acceptance debt. Acceptance names an open blocker as `blocked by Q#`.
+- **Verifier.** The verifier's idea claims are refused while other members' findings await its
+  review at their current revision; the pending F# list follows every review, reattest and board
+  post. A verifier whose session closes with critical or high-importance findings unreviewed is
+  reset once more into a fresh session that owes them, within `PI_HORDE_RESET_CAP`. SUMMARY.md
+  derives its coverage sentence from the review records and names the unreviewed F#.
+- **Reproductions.** A finding with an independent corroborator or a full-scope review is
+  settled: a claim whose text overlaps it is told to bring a new vector as `deltaOf`, and a
+  third duplicate report is dropped. A finding that cites a runnable under `artifacts/` no R# or
+  A# covers is told to register it.
 - **Inbox.** Targeted messages are inserted at turn boundaries, for at most
   `PI_HORDE_INBOX_TURNS` extra turns per session. A recipient answers with `respond`; `ack` is an
   optional first step that signals intent. Delivery is a context insertion, not
@@ -226,6 +281,57 @@ highest-importance unchecked assertions first with `horde review`, contest or su
 not reproduce, and claim ideas only when nothing is left to review. `--no-verifier` turns this
 off.
 
+`--until-stop` keeps the whole horde working until you stop it. A validated solve does not wind
+the run down: the answer is banked in ANSWER.md (and under `answers/`) as round N and the proposal
+slot reopens, so a materially better answer can be proposed later. A member whose session finishes
+is given a fresh session that reads the board, findings, and answer and adds ideas that extend,
+stress-test, or deepen the work; these continuations count against no reset cap and are not
+resets in the report. A session that finished within `PI_HORDE_CONTINUE_COOLDOWN_MS` (default
+60000) of starting waits out the remainder first, so a member that finds nothing to do cannot spin.
+Crash and stall resets apply as usual. `stop-clean` and `stop-hard` end the run as usual and
+`stop-clean` produces the report, deliverable, and postmortem; the last banked answer stands unless
+a later proposal was validated too.
+
+## Horde of hordes
+
+`H/M` launches a swarm: H concurrent hordes of M members on one task, H at most 4. A plain `M` is
+a swarm of one and keeps the layout above; a larger swarm gets `.horde/swarms/<swarm-id>/` with one
+complete horde directory per horde (`h1/`, `h2/`, ...), each with its own ledgers, lock and
+`runs/<swarm-id>-hN/`. Hordes therefore never share a lock, a dedup pass or a coverage watermark,
+and run ids stay unique across the swarm.
+
+**Partition.** A plain prompt is split before launch by a read-only planner helper (`pi -p`, the
+parent's model, `PI_HORDE_PLANNER_MS` timeout) into exactly H disjoint workstreams with one
+acceptance criterion each, recorded in `SWARM.md` and in each horde's `TASK.md`; every member of a
+horde is told its workstream and to work only on it. If the planner cannot produce H distinct
+workstreams the launch stops with that message, the swarm directory keeps the planner session and
+a `SWARM.md` saying why, and the slot stays free. `plan H/M a; b; c; ...` skips the planner: the
+layers are dealt round-robin to the hordes (layer 1 to h1, layer 2 to h2, ...) and each horde runs
+its share as its own plan, so there must be at least H layers.
+
+**Sharing.** Shared read, local write. Each member's system prompt lists the sibling horde
+directories; `horde facts` and `horde resources` append every sibling's entries tagged `[hN]`, and
+`horde list` appends their done and ruled-out ideas, so a fact, a rule-out or a lab another horde
+recorded is not re-derived. Open sibling ideas are not shown and nothing is written to a sibling:
+the lock, dedup and coverage rules keep their per-horde scope. Members reuse a sibling's resource
+by its path, not its R#.
+
+**Lifecycle.** The hordes start `PI_HORDE_SWARM_STAGGER_MS` (default 5000) apart so H canaries do
+not hit the provider at once; each then runs the lifecycle above unchanged, with its own canary,
+resets, repair, acceptance, deliverable and post-mortem. `--until-stop` applies to every horde.
+Controls take horde targets: `stop-clean h2` winds one horde down, `pause h2:member-3` one member,
+`stop-hard` every horde, and `status` prints one block per horde. The swarm slot frees once every
+horde has written its REPORT.md; after the last horde's finalize a synthesis helper reads the
+hordes' DELIVERABLE.md, REPORT.md and ACCEPTANCE.md and writes the swarm `DELIVERABLE.md`, keeping
+each claim attributed to its horde and to that horde's acceptance label, and the swarm `REPORT.md`
+with per-horde members, turns, tokens, cost, findings and outcome. One swarm report is injected into
+the parent conversation instead of one per horde. No horde reviews another's work; a verification
+pass over the merged deliverable is not built.
+
+**Dashboard and widget.** Each swarm has its own scope in the dashboard, with horde tabs and
+swarm-wide ledger, collaboration and graph pages; see [Dashboard](#dashboard). The widget shows one
+line per horde.
+
 ## Finding metadata
 
 `importance` (critical, high, medium, low, info), `confidence` (high, medium, low), and
@@ -253,10 +359,13 @@ carries a one-line diagnosis and, when generated, the post-mortem text.
 | variable | default | effect |
 |----------|---------|--------|
 | `PI_HORDE_DASHBOARD_PORT` | 7433 | dashboard port when `--dashboard` names none |
+| `PI_HORDE_CONTINUE_COOLDOWN_MS` | 60000 | `--until-stop`: a finished session younger than this waits out the remainder before its fresh session starts |
 | `PI_HORDE_MAX_MINUTES` | off | clean stop at a wall-clock deadline |
 | `PI_HORDE_CANARY_MS` | 60000 | time for member-1 to produce output before a retry |
 | `PI_HORDE_STALL_MS` | 1800000 | reset a member with no ledger write for this long; `0` disables |
 | `PI_HORDE_RESET_CAP` | 2 | resets per member |
+| `PI_HORDE_SWARM_STAGGER_MS` | 5000 | pause between one horde's launch and the next in a swarm |
+| `PI_HORDE_PLANNER_MS` | 300000 | planner helper timeout when a swarm partitions a plain prompt |
 | `PI_HORDE_ACTIVE_GRACE_MS` | 15000 | one clean-stop extension for a member still producing output |
 | `PI_HORDE_SOLVED_CONFIRM_MS` | 120000 | wait for a second member to validate a solve |
 | `PI_HORDE_SOLVED_STOP_MS` | 30000 | extra wind-down window for a solve landing at the deadline |
@@ -295,9 +404,11 @@ watchdog.ts           child exits when its parent pid is gone
 widget.ts             TUI widget above the editor
 citations.ts          R#/F#/T# and file-path citation checks for findings and generated artifacts
 dashboard.ts          localhost HTTP server; dashboard-data.ts loads pages, dashboard-html.ts renders
+build-info.ts         the running package's version and checkout commit, for the dashboard footer
 collaboration-report.ts  acceptance checks, frozen snapshots, collaboration metrics
 run-graph.ts          events.jsonl projected into lanes, phases, nodes, and edges with dashboard links
 run-graph-svg.ts      the swimlane SVG and its legend; run-graph-mermaid.ts the Mermaid export and GRAPH.md
+swarm-graph.ts        a swarm's hordes as lanes of lifecycle marks, plus the merge step
 
 ledger/               one module per .horde/ document, all writes under the .horde lock
   files.ts            paths, init, atomic writes, shared entry formatting
@@ -322,10 +433,13 @@ tool/                 the member-side `horde` tool
   resource-contract.ts      resource generations, readiness, leases, and port coordination
 
 run/                  the parent-side run lifecycle, sharing one HordeState
-  types.ts            HordeRun, HordeState, ReportDetails
-  command.ts          /agent-horde dispatch and session shutdown
+  types.ts            HordeRun, Swarm, HordeState, ReportDetails
+  command.ts          /agent-horde dispatch, horde-prefixed targets, session shutdown
   setup.ts            run directory, TASK.md, roles, plan seeding
-  launch.ts           dashboard, deadline, canary preflight, fan-out
+  swarm.ts            swarm directories and ids, dealing plan layers, planner output parsing
+  swarm-finalize.ts   the swarm slot, the merge step, SWARM.json
+  swarm-report.ts     per-horde totals: the swarm REPORT.md and the injected message
+  launch.ts           dashboard, deadline, partition, staggered canary preflights, fan-out
   supervise.ts        member spawn, reset on exit, stall detection
   schedule.ts         artifact review assignment and superseded-dependency handoffs
   repair.ts           bounded post-discovery reviews, owner repair, and recheck attempts
@@ -333,7 +447,7 @@ run/                  the parent-side run lifecycle, sharing one HordeState
   controls.ts         stop-hard, pause and resume, clean stop and its deadline
   finalize.ts         reconcile, cleanups, SUMMARY.md and REPORT.md, report message, GRAPH.md
   lifecycle.ts        parent lifecycle events in events.jsonl
-  synthesis.ts        deliverable and post-mortem helper agents
+  synthesis.ts        deliverable, post-mortem, swarm merge and planner helper agents
   diagnosis.ts        one-line run diagnosis
   ui.ts               widget mount, status line, report renderer, notifications
   completions.ts      command argument completions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-horde",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Run a horde of pi agents on one task: shared ledgers, peer review, an auditable event log, and a live dashboard",
   "license": "MIT",
   "type": "module",