agent-horde 0.1.6 → 0.2.1

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.6
+pi install git:github.com/eliyastein/agent-horde@v0.2.1
 ```
 
 To hack on it, clone and install in place. pi loads the files from the clone, so edits take effect
@@ -135,14 +137,31 @@ 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 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`.
 

package/docs/REFERENCE.md

@@ -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
@@ -40,7 +42,14 @@ synthesize it.
    The default totals follow the queues' demand (one floor per queue plus one per further review
    request or blocking challenge), each attempt's share is cut in proportion to its demand, and
    every attempt gets at least a floor; the phase start records the budget, `repair-start` the
-   attempt's demand, and `repair-end` its turns and first-turn cost. A user stop skips this phase.
+   attempt's demand, and `repair-end` its turns, first-turn cost and the threads it left
+   `unchanged`. A thread that two consecutive completed attempts did not move (same state and
+   response revision) is held back from that member until another member changes it; a member
+   whose whole queue is held is recorded as `repair-skipped` with reason `no-progress` and costs
+   later rounds nothing. Each round serves a member at most once, but a round other than the last
+   ends early when the only blocking threads left belong to members it already served, so a
+   requester rechecks a correction before unserved members' non-blocking threads.
+   A user stop skips this phase.
 4. **Finalize.** Acceptance is frozen (`ACCEPTANCE.*`, `snapshot/`), resource cleanup commands
    run, `SUMMARY.md` and `REPORT.md` are written, then a synthesis member writes `DELIVERABLE.md`
    and a read-only reviewer writes `POSTMORTEM.md`. The widget shows `synthesizing` until both
@@ -76,9 +85,19 @@ Every page has a JSON twin under `/api/<same path>`. The footer of every page na
 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) |
@@ -88,16 +107,27 @@ at (`-dirty` when the tree has uncommitted changes), linked to the commit on Git
 | `/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
@@ -134,11 +164,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
 
@@ -196,9 +232,12 @@ from the same actor as an idempotent retry. The parent appends its own lifecycle
   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`. 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
+  every finding and artifact 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, or whose cited A# is republished, is withdrawn (`solved-withdrawn`)
+  for re-proposal, and ANSWER.md's status says so instead of keeping an earlier validation. At
+  finalize, ANSWER.md's status names every citation that changed after the proposal pinned it. 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.
@@ -219,7 +258,10 @@ from the same actor as an idempotent retry. The parent appends its own lifecycle
   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#`.
+  review discloses remain acceptance debt. A blocking request about the sender's own work (a
+  re-review after a correction) resolves on the recipient's supporting review of the current
+  revision, full-scope for an A#, since the owner may not review it. 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
@@ -263,6 +305,46 @@ Crash and stall resets apply as usual. `stop-clean` and `stop-hard` end the run
 `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
@@ -281,7 +363,9 @@ for an abnormal end after measurable work; distinct finding clusters with review
 superseded findings in their own section, and any resets; claim states; this run's facts split
 from carried context; resources and cleanup results; coverage (released and still-open ideas,
 the solved answer); late board posts; and consistency warnings for missing metadata,
-mixed-concern clusters, unknown R# citations, and cited paths that do not exist. A killed
+mixed-concern clusters, unknown R# citations, and cited paths that do not exist (rooted URL paths
+and templates with a date or placeholder slot, such as `logs/gate-YYYY-MM-DD.jsonl` or
+`out/<id>.json`, are not checked). A killed
 member's summary is reconstructed from its last board post. The message injected into the parent
 carries a one-line diagnosis and, when generated, the post-mortem text.
 
@@ -295,6 +379,8 @@ carries a one-line diagnosis and, when generated, the post-mortem text.
 | `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 |
@@ -337,6 +423,7 @@ build-info.ts         the running package's version and checkout commit, for the
 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
@@ -361,10 +448,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
@@ -372,7 +462,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.6",
+  "version": "0.2.1",
   "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",

package/src/args.ts

@@ -1,8 +1,13 @@
 export const MAX_MEMBERS = 12;
 
+/** Hordes per swarm; `H/M` launches H hordes of M members. */
+export const MAX_HORDES = 4;
+
 export const USAGE = [
   "usage: /agent-horde [--dashboard[=<port>]] [--no-verifier] [--until-stop] <count> <prompt>",
-  "                                          spawn <count> members with the same prompt",
+  "                                          spawn <count> members with the same prompt;",
+  "                                          <count> may be H/M: H hordes of M members, the",
+  "                                          task partitioned between the hordes by a planner",
   "       /agent-horde status [target]       show the active run",
   "       /agent-horde stop-hard [target]    terminate members now (SIGTERM, then SIGKILL)",
   "       /agent-horde stop-clean [target]   let members wrap up, then reconcile their ideas",
@@ -11,11 +16,13 @@ export const USAGE = [
   "       /agent-horde pause [target]        suspend members (SIGSTOP)",
   "       /agent-horde resume [target]       resume suspended members (SIGCONT)",
   `       /agent-horde plan [--dashboard] <count> <a; b; ...>`,
-  "                                          partition members across workstreams",
+  "                                          partition members across workstreams; with H/M",
+  "                                          the layers go round-robin to the hordes",
   "       /agent-horde help                  show this text",
   "",
-  "target is 'all' (default), 'member-N', 'N', or a comma/space separated list.",
-  `count is a whole number from 1 to ${MAX_MEMBERS}`,
+  "target is 'all' (default), 'member-N', 'N', 'hN' (one horde), 'hN:member-M', 'hN:M', or a",
+  "comma/space separated list; a bare member names that member in every horde.",
+  `count is a whole number from 1 to ${MAX_MEMBERS}, or H/M with H from 1 to ${MAX_HORDES}`,
   "--dashboard serves a read-only localhost dashboard (default port 7433, or",
   "PI_HORDE_DASHBOARD_PORT); --dashboard=<port> picks the port.",
   "--no-verifier skips the default verifier role that runs of 3 or more members assign",
@@ -25,10 +32,18 @@ export const USAGE = [
   "session told to add new ideas.",
 ].join("\n");
 
-/** Which members a control command applies to. */
+/** One token of a control target: a horde, a member in every horde, or a member of one horde. */
+export interface TargetItem {
+  /** 1-based horde index (`h2`); absent for every horde. */
+  horde?: number;
+  /** `member-N`; absent for every member of the horde. */
+  member?: string;
+}
+
+/** Which hordes and members a control command applies to. */
 export type HordeTarget =
   | { kind: "all" }
-  | { kind: "members"; names: string[] };
+  | { kind: "selection"; items: TargetItem[] };
 
 type HordeStopMode = "hard" | "clean";
 
@@ -46,6 +61,9 @@ type HordeArgs =
   | { kind: "resume"; target: HordeTarget }
   | {
       kind: "run";
+      /** Concurrent hordes; `12` is one horde, `3/12` three. */
+      hordes: number;
+      /** Members per horde. */
       count: number;
       prompt: string;
       plan?: string[] | undefined;
@@ -58,22 +76,51 @@ type HordeArgs =
 
 export type HordeRunArgs = Extract<HordeArgs, { kind: "run" }>;
 
+const HORDE_TOKEN = /^h(\d+)$/i;
+const MEMBER_TOKEN = /^(?:member-)?(\d+)$/i;
+
+function memberName(token: string): string | undefined {
+  const match = MEMBER_TOKEN.exec(token);
+  if (!match) return undefined;
+  const index = Number(match[1]);
+  return index >= 1 && index <= MAX_MEMBERS ? `member-${index}` : undefined;
+}
+
+function hordeIndex(token: string): number | undefined {
+  const match = HORDE_TOKEN.exec(token);
+  if (!match) return undefined;
+  const index = Number(match[1]);
+  return index >= 1 && index <= MAX_HORDES ? index : undefined;
+}
+
+/** `h2`, `h2:member-3`, `h2:3`, `member-3`, or `3`; undefined for anything else. */
+function parseTargetItem(token: string): TargetItem | undefined {
+  const colon = token.indexOf(":");
+  if (colon === -1) {
+    const horde = hordeIndex(token);
+    if (horde !== undefined) return { horde };
+    const member = memberName(token);
+    return member === undefined ? undefined : { member };
+  }
+  const horde = hordeIndex(token.slice(0, colon));
+  const member = memberName(token.slice(colon + 1));
+  return horde === undefined || member === undefined ? undefined : { horde, member };
+}
+
 function parseTargets(raw: string): HordeTarget | undefined {
   const trimmed = raw.trim();
   if (trimmed === "") return { kind: "all" };
-  const names: string[] = [];
+  const items: TargetItem[] = [];
   for (const token of trimmed.split(/[\s,]+/).filter(Boolean)) {
     if (token.toLowerCase() === "all") return { kind: "all" };
-    const match = /^(?:member-)?(\d+)$/i.exec(token);
-    if (!match) return undefined;
-    const index = Number(match[1]);
-    if (index < 1 || index > MAX_MEMBERS) return undefined;
-    names.push(`member-${index}`);
+    const item = parseTargetItem(token);
+    if (!item) return undefined;
+    items.push(item);
   }
-  return names.length > 0 ? { kind: "members", names } : { kind: "all" };
+  return items.length > 0 ? { kind: "selection", items } : { kind: "all" };
 }
 
-const TARGET_ERROR = "invalid target; use all, member-N, or N";
+const TARGET_ERROR = "invalid target; use all, member-N, N, hN, or hN:member-M";
 
 function parseStopRest(
   rest: string,
@@ -166,24 +213,31 @@ function mergeLaunchFlags(leading: LaunchFlags, trailing: LaunchFlags): LaunchFl
   };
 }
 
-/** Parse `<count> [flags] <tail>`. */
-function parseCountedRun(
-  text: string,
-  leading: LaunchFlags,
-): { count: number; rest: string; flags: LaunchFlags } | { error: string } {
-  const match = /^(\d+)(?:\s+([\s\S]*))?$/.exec(text.trim());
-  if (!match) return { error: `count must be a whole number from 1 to ${MAX_MEMBERS}` };
-  const count = Number(match[1]);
-  if (count < 1 || count > MAX_MEMBERS) {
-    return { error: `count must be a whole number from 1 to ${MAX_MEMBERS}` };
-  }
-  const flags = mergeLaunchFlags(leading, takeLaunchFlags(match[2] ?? ""));
+const COUNT_ERROR =
+  `count must be a whole number from 1 to ${MAX_MEMBERS}, or H/M with H from 1 to ${MAX_HORDES} hordes`;
+
+interface CountedRun {
+  hordes: number;
+  count: number;
+  rest: string;
+  flags: LaunchFlags;
+}
+
+/** Parse `<count> [flags] <tail>`, where count is `M` or `H/M`. */
+function parseCountedRun(text: string, leading: LaunchFlags): CountedRun | { error: string } {
+  const match = /^(?:(\d+)\/)?(\d+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+  if (!match) return { error: COUNT_ERROR };
+  const hordes = match[1] === undefined ? 1 : Number(match[1]);
+  const count = Number(match[2]);
+  if (count < 1 || count > MAX_MEMBERS || hordes < 1 || hordes > MAX_HORDES) return { error: COUNT_ERROR };
+  const flags = mergeLaunchFlags(leading, takeLaunchFlags(match[3] ?? ""));
   if (flags.error) return { error: flags.error };
-  return { count, rest: flags.rest, flags };
+  return { hordes, count, rest: flags.rest, flags };
 }
 
-function runArgs(count: number, prompt: string, flags: LaunchFlags, plan?: string[]): HordeRunArgs {
-  const args: HordeRunArgs = { kind: "run", count, prompt };
+function runArgs(parsed: CountedRun, prompt: string, plan?: string[]): HordeRunArgs {
+  const { hordes, count, flags } = parsed;
+  const args: HordeRunArgs = { kind: "run", hordes, count, prompt };
   if (plan) args.plan = plan;
   if (flags.dashboard) args.dashboard = flags.dashboard;
   if (flags.noVerifier) args.noVerifier = true;
@@ -191,6 +245,26 @@ function runArgs(count: number, prompt: string, flags: LaunchFlags, plan?: strin
   return args;
 }
 
+function parsePlan(rest: string, leading: LaunchFlags): HordeArgs {
+  const afterPlan = takeLaunchFlags(rest);
+  if (afterPlan.error) return { kind: "usage", error: afterPlan.error };
+  const parsed = parseCountedRun(afterPlan.rest, mergeLaunchFlags(leading, afterPlan));
+  if ("error" in parsed) {
+    return { kind: "usage", error: "plan usage: /agent-horde plan <count> <layer1; layer2; ...>" };
+  }
+  const layers = parsed.rest
+    .split(/[;\n]/)
+    .map((layer) => layer.trim())
+    .filter(Boolean);
+  if (layers.length < 2) {
+    return { kind: "usage", error: "plan needs at least 2 layers separated by ';'" };
+  }
+  if (layers.length < parsed.hordes) {
+    return { kind: "usage", error: `plan with ${parsed.hordes} hordes needs at least ${parsed.hordes} layers` };
+  }
+  return runArgs(parsed, layers.join("; "), layers);
+}
+
 export function parseHordeArgs(raw: string): HordeArgs {
   const leading = takeLaunchFlags(raw);
   if (leading.error) return { kind: "usage", error: leading.error };
@@ -203,7 +277,7 @@ export function parseHordeArgs(raw: string): HordeArgs {
   const space = trimmed.search(/\s/);
   const head = (space === -1 ? trimmed : trimmed.slice(0, space)).toLowerCase();
   const rest = space === -1 ? "" : trimmed.slice(space + 1);
-  if (hasFlags && head !== "plan" && !/^\d+$/.test(head)) {
+  if (hasFlags && head !== "plan" && !/^\d+(?:\/\d+)?$/.test(head)) {
     return { kind: "usage", error: "launch flags only apply when starting a run" };
   }
 
@@ -232,22 +306,8 @@ export function parseHordeArgs(raw: string): HordeArgs {
       const target = parseTargets(rest);
       return target ? { kind: "pause", target } : { kind: "usage", error: TARGET_ERROR };
     }
-    case "plan": {
-      const afterPlan = takeLaunchFlags(rest);
-      if (afterPlan.error) return { kind: "usage", error: afterPlan.error };
-      const parsed = parseCountedRun(afterPlan.rest, mergeLaunchFlags(leading, afterPlan));
-      if ("error" in parsed) {
-        return { kind: "usage", error: "plan usage: /agent-horde plan <count> <layer1; layer2; ...>" };
-      }
-      const layers = parsed.rest
-        .split(/[;\n]/)
-        .map((layer) => layer.trim())
-        .filter(Boolean);
-      if (layers.length < 2) {
-        return { kind: "usage", error: "plan needs at least 2 layers separated by ';'" };
-      }
-      return runArgs(parsed.count, layers.join("; "), parsed.flags, layers);
-    }
+    case "plan":
+      return parsePlan(rest, leading);
     case "resume": {
       const target = parseTargets(rest);
       return target ? { kind: "resume", target } : { kind: "usage", error: TARGET_ERROR };
@@ -257,5 +317,5 @@ export function parseHordeArgs(raw: string): HordeArgs {
   const parsed = parseCountedRun(trimmed, leading);
   if ("error" in parsed) return { kind: "usage", error: parsed.error };
   if (parsed.rest === "") return { kind: "usage", error: "prompt is required" };
-  return runArgs(parsed.count, parsed.rest, parsed.flags);
+  return runArgs(parsed, parsed.rest);
 }

package/src/citations.ts

@@ -32,6 +32,12 @@ const DATA_EXT =
 /** Path roots that are worth checking even without a file extension. */
 const RUN_ROOT = /^(?:\.horde|\.tmp|runs|artifacts)(?:[/-]|$)/;
 
+/**
+ * A path with a date or placeholder slot (`logs/gate-YYYY-MM-DD.jsonl`, `out/<id>.json`,
+ * `%Y%m%d.log`) names a pattern the code writes, not one file that must exist.
+ */
+const PATH_TEMPLATE = /(?:^|[^A-Za-z])(?:YYYY|YYYYMMDD|yyyy|yyyymmdd)(?:[^A-Za-z]|$)|<[^<>]+>|%[YmdHMS]/;
+
 /** Host-anchored references such as docs.example.com/page are URLs, not local paths. */
 const HOST_PATH = /^(?:[a-z0-9-]+\.)+[a-z]{2,}\//i;
 
@@ -57,6 +63,7 @@ export function citedDataFiles(text: string): string[] {
     if (ref === "") return;
     if (ref.startsWith("/") || /^[a-z][a-z0-9+.-]*:\/\//i.test(ref)) return;
     if (/[{}*$]/.test(ref)) return;
+    if (PATH_TEMPLATE.test(ref)) return;
     if (HOST_PATH.test(ref)) return;
     const isRooted = RUN_ROOT.test(ref);
     // Under a run root, any extension is a member artifact worth checking. Off a
@@ -66,7 +73,9 @@ export function citedDataFiles(text: string): string[] {
     out.add(ref);
   };
   for (const match of text.matchAll(/`([^`\s]+)`/g)) consider(match[1] ?? "");
-  for (const match of text.matchAll(/(?<![\w:/.])(?:\.{1,2}\/)?[\w.-]+(?:\/[\w.-]+)+(?:\.[A-Za-z0-9]{1,6})?/g)) {
+  // A match never starts inside a hyphenated word: `/standalone-client-gate/logs` is one URL path,
+  // not a relative `client-gate/logs` with its leading slash cut off.
+  for (const match of text.matchAll(/(?<![\w:/.-])(?:\.{1,2}\/)?[\w.-]+(?:\/[\w.-]+)+(?:\.[A-Za-z0-9]{1,6})?/g)) {
     consider(match[0] ?? "", text[(match.index ?? 0) + match[0].length] ?? "");
   }
   for (const match of text.matchAll(/(?<![\w/.-])([\w-]+\.[A-Za-z0-9]{1,6})\b/g)) consider(match[1] ?? "");
@@ -95,14 +104,16 @@ function fileNamedUnder(dir: string, name: string, depth = 6): boolean {
 
 /**
  * True when a cited file cannot be resolved to an existing file on disk. Paths
- * are tried against the repo root, the run directory, its artifacts directory,
- * and the directory of the citing file. Because generated artifacts usually cite
- * retained files by a relative name, and a deliverable cites the reviewed project's
+ * are tried against the repo root, the horde directory (where `runs/<id>/...`
+ * references resolve, in a single run and in a swarm horde alike), the run
+ * directory, its artifacts directory, and the directory of the citing file; a
+ * path without a file extension may name a directory. Because generated artifacts
+ * usually cite retained files by a relative name, and a deliverable cites the reviewed project's
  * own files by bare name, a basename match in this run's tree or in the project tree
  * also counts, which keeps the warning precise instead of noisy.
  */
 function citedFileMissing(run: HordeRun, ref: string, baseDir?: string): boolean {
-  const roots = [run.cwd, run.runDir, path.join(run.runDir, "artifacts")];
+  const roots = [run.cwd, run.hordeDir, run.runDir, path.join(run.runDir, "artifacts")];
   if (baseDir) roots.push(baseDir);
   const mustBeFile = FILE_EXT.test(ref);
   for (const root of roots) {