agent-horde 0.2.0 → 0.3.0

package/README.md

@@ -90,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.2.0
+pi install git:github.com/eliyastein/agent-horde@v0.3.0
 ```
 
 To hack on it, clone and install in place. pi loads the files from the clone, so edits take effect
@@ -137,6 +137,16 @@ extend, stress-test, or deepen the work.
 /agent-horde --dashboard --until-stop 8 find every way an unauthenticated request reaches the database
 ```
 
+`--budget=<usd>` puts a dollar ceiling on a run: once the members' combined spend, counted across
+every session they have had, reaches it, the parent performs a clean stop on its own and the
+report says `stopped at budget`. It pairs with `--until-stop` to bound an open-ended run. The
+spend counted is what the members' model calls report; the planner, deliverable and post-mortem
+helpers are not included, and members still get the clean-stop grace period to wrap up.
+
+```
+/agent-horde --until-stop --budget=20 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
@@ -145,7 +155,8 @@ the planner and deals the layers round-robin to the hordes. Members read the oth
 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.
+claim attributed to its horde. `--until-stop` applies to every horde, and `--budget` is one ceiling
+for all hordes combined.
 
 ```
 /agent-horde --dashboard=1234 3/12 audit the service for authorization bugs

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] [--until-stop] <count> <prompt>
+/agent-horde [--dashboard[=<port>]] [--no-verifier] [--until-stop] [--budget=<usd>] <count> <prompt>
 /agent-horde plan [--dashboard] <count> <layer; layer; ...>
 /agent-horde status [target]
 /agent-horde stop-hard [target]                      SIGTERM, SIGKILL after 5s (alias: stop)
@@ -42,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
@@ -61,7 +68,14 @@ unfinished ideas return to the open pool.
 A clean stop still produces the deliverable; add `postmortem` to also run the reviewer. Runs
 that end on their own (all members finished, solved, canary or provider failure) get both.
 `PI_HORDE_MAX_MINUTES` forces a clean stop at a wall-clock deadline, reported as
-`stopped at deadline`.
+`stopped at deadline`. `--budget=<usd>` forces one when the members' combined spend reaches that
+many dollars, reported as `stopped at budget`; in a swarm the ceiling covers every horde and every
+horde still working is stopped. The check runs on every usage update a member reports, so it fires
+on the model call that crosses the line, during discovery or repair alike. The spend counted is the
+members' own, summed over every session a member slot has had (resets, continuations and repair
+attempts included); the planner, deliverable, post-mortem and merge helpers are not counted, and
+the clean-stop grace period lets members finish, so the final total overshoots the ceiling by what
+the wind-down costs.
 
 Members and helper agents are children of the pi session. Quitting or reloading pi sends every
 live child SIGTERM, and each child polls `PI_HORDE_PARENT_PID` every two seconds and exits on its
@@ -225,9 +239,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.
@@ -248,7 +265,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
@@ -290,7 +310,11 @@ resets in the report. A session that finished within `PI_HORDE_CONTINUE_COOLDOWN
 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.
+a later proposal was validated too. `--budget=<usd>` bounds such a run by spend (see Stopping).
+
+Usage totals in the widget, status, dashboard and reports are summed over every session each
+member slot has had, so a reset or continuation never hides what the replaced session spent. The
+per-session figures stay in the `member-exit` events and the per-member report sections.
 
 ## Horde of hordes
 
@@ -350,7 +374,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.
 
@@ -441,6 +467,7 @@ run/                  the parent-side run lifecycle, sharing one HordeState
   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
+  budget.ts           `--budget`: swarm-wide spend check, clean stop when it is reached
   schedule.ts         artifact review assignment and superseded-dependency handoffs
   repair.ts           bounded post-discovery reviews, owner repair, and recheck attempts
   solved.ts           two-phase SOLVED poll

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-horde",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -50,7 +50,7 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.5.2",
     "@types/node": "26.6.5",
     "oxlint": "1.88.0",
     "typescript": "7.0.2"

package/src/args.ts

@@ -4,7 +4,7 @@ export const MAX_MEMBERS = 12;
 export const MAX_HORDES = 4;
 
 export const USAGE = [
-  "usage: /agent-horde [--dashboard[=<port>]] [--no-verifier] [--until-stop] <count> <prompt>",
+  "usage: /agent-horde [--dashboard[=<port>]] [--no-verifier] [--until-stop] [--budget=<usd>] <count> <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",
@@ -15,7 +15,7 @@ export const USAGE = [
   "                                          additionally run a post-mortem on the run",
   "       /agent-horde pause [target]        suspend members (SIGSTOP)",
   "       /agent-horde resume [target]       resume suspended members (SIGCONT)",
-  `       /agent-horde plan [--dashboard] <count> <a; b; ...>`,
+  "       /agent-horde plan [--dashboard[=<port>]] [--no-verifier] [--until-stop] [--budget=<usd>] <count> <a; b; ...>",
   "                                          partition members across workstreams; with H/M",
   "                                          the layers go round-robin to the hordes",
   "       /agent-horde help                  show this text",
@@ -30,6 +30,8 @@ export const USAGE = [
   "--until-stop keeps the whole horde working until you run stop-clean or stop-hard: a",
   "validated solve is banked as the current answer and a member that finishes gets a fresh",
   "session told to add new ideas.",
+  "--budget=<usd> clean-stops the run (every horde of a swarm) once the members' combined",
+  "spend reaches that many dollars.",
 ].join("\n");
 
 /** One token of a control target: a horde, a member in every horde, or a member of one horde. */
@@ -72,6 +74,8 @@ type HordeArgs =
       noVerifier?: boolean | undefined;
       /** Present (true) only when `--until-stop` was given. */
       untilStop?: boolean | undefined;
+      /** Dollar spend at which the run clean-stops itself; present only when `--budget` was given. */
+      budget?: number | undefined;
     };
 
 export type HordeRunArgs = Extract<HordeArgs, { kind: "run" }>;
@@ -155,7 +159,9 @@ function parseStopRest(
 const DASHBOARD_FLAG = /^--dashboard(?:=(\S*))?(?=\s|$)/;
 const NO_VERIFIER_FLAG = /^--no-verifier(?=\s|$)/;
 const UNTIL_STOP_FLAG = /^--until-stop(?=\s|$)/;
+const BUDGET_FLAG = /^--budget(?:=(\S*)|\s+(\S+))?(?=\s|$)/;
 const DASHBOARD_ERROR = "invalid --dashboard; use --dashboard or --dashboard=<port 1-65535>";
+const BUDGET_ERROR = "invalid --budget; use --budget=<usd>, a positive dollar amount";
 
 /** Launch flags found at one position of the command; `rest` is the remaining text. */
 interface LaunchFlags {
@@ -163,6 +169,7 @@ interface LaunchFlags {
   dashboard?: DashboardOption | undefined;
   noVerifier?: boolean | undefined;
   untilStop?: boolean | undefined;
+  budget?: number | undefined;
   error?: string | undefined;
 }
 
@@ -174,7 +181,14 @@ function parseDashboardFlag(port: string | undefined): DashboardOption | { error
   return { port: value };
 }
 
-/** Strip leading `--dashboard[=<port>]`, `--no-verifier`, and `--until-stop` tokens, in any order. */
+function parseBudgetFlag(amount: string | undefined): number | { error: string } {
+  if (amount === undefined || !/^\d+(?:\.\d+)?$/.test(amount)) return { error: BUDGET_ERROR };
+  const value = Number(amount);
+  if (value <= 0) return { error: BUDGET_ERROR };
+  return value;
+}
+
+/** Strip leading `--dashboard[=<port>]`, `--no-verifier`, `--until-stop` and `--budget` tokens, in any order. */
 function takeLaunchFlags(text: string): LaunchFlags {
   const flags: LaunchFlags = { rest: text.trim() };
   for (;;) {
@@ -186,6 +200,14 @@ function takeLaunchFlags(text: string): LaunchFlags {
       flags.rest = flags.rest.slice(dashboard[0].length).trim();
       continue;
     }
+    const budget = BUDGET_FLAG.exec(flags.rest);
+    if (budget) {
+      const value = parseBudgetFlag(budget[1] ?? budget[2]);
+      if (typeof value !== "number") return { ...flags, error: value.error };
+      flags.budget = value;
+      flags.rest = flags.rest.slice(budget[0].length).trim();
+      continue;
+    }
     const noVerifier = NO_VERIFIER_FLAG.exec(flags.rest);
     if (noVerifier) {
       flags.noVerifier = true;
@@ -209,6 +231,7 @@ function mergeLaunchFlags(leading: LaunchFlags, trailing: LaunchFlags): LaunchFl
     dashboard: leading.dashboard ?? trailing.dashboard,
     noVerifier: leading.noVerifier === true || trailing.noVerifier === true ? true : undefined,
     untilStop: leading.untilStop === true || trailing.untilStop === true ? true : undefined,
+    budget: leading.budget ?? trailing.budget,
     error: leading.error ?? trailing.error,
   };
 }
@@ -242,6 +265,7 @@ function runArgs(parsed: CountedRun, prompt: string, plan?: string[]): HordeRunA
   if (flags.dashboard) args.dashboard = flags.dashboard;
   if (flags.noVerifier) args.noVerifier = true;
   if (flags.untilStop) args.untilStop = true;
+  if (flags.budget !== undefined) args.budget = flags.budget;
   return args;
 }
 
@@ -269,7 +293,9 @@ export function parseHordeArgs(raw: string): HordeArgs {
   const leading = takeLaunchFlags(raw);
   if (leading.error) return { kind: "usage", error: leading.error };
   const trimmed = leading.rest;
-  const hasFlags = leading.dashboard !== undefined || leading.noVerifier === true || leading.untilStop === true;
+  const hasFlags =
+    leading.dashboard !== undefined || leading.noVerifier === true || leading.untilStop === true ||
+    leading.budget !== undefined;
   if (trimmed === "") {
     return hasFlags ? { kind: "usage", error: "count is required" } : { kind: "usage" };
   }

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) {

package/src/dashboard-data.ts

@@ -26,7 +26,7 @@ import { buildRunGraph } from "./run-graph.js";
 import { buildSwarmGraph } from "./swarm-graph.js";
 import type { RunGraph } from "./run-graph.js";
 import { readCleanStop } from "./ledger/run-signals.js";
-import { memberSessionDir, parseMemberLog } from "./member.js";
+import { emptyUsage, memberSessionDir, parseMemberLog, USAGE_KEYS } from "./member.js";
 import type { MemberEndCause, MemberState, MemberStatus, MemberUsage } from "./member.js";
 import { memberActivity, parseReportOutcome, parseTaskMarkdown, statusCounts, totalUsage } from "./prompt.js";
 import type { RunSummaryInput, UsageTotals } from "./prompt.js";
@@ -72,6 +72,7 @@ export interface LiveSwarm {
   runs: LiveRun[];
   partition?: string[] | undefined;
   untilStop?: boolean | undefined;
+  budget?: number | undefined;
   /** The swarm step still running after every horde finalized. */
   finalizing?: string[] | undefined;
   deliverable?: string | undefined;
@@ -383,6 +384,7 @@ interface SwarmRecordOnDisk {
   count?: number;
   startedAt?: number;
   untilStop?: boolean;
+  budget?: number;
   partition?: string[];
   runs?: Array<{ label?: string; runId?: string; startedAt?: number; endedAt?: number; outcome?: string }>;
   merge?: { startedAt?: number; endedAt?: number; written?: boolean };
@@ -500,7 +502,7 @@ function liveMemberRow(m: MemberState, now: number, runDir: string): MemberRowVm
     paused: m.paused === true,
     turns: m.turns,
     toolCalls: m.toolCalls,
-    usage: { ...m.usage },
+    usage: { ...m.lifetime },
     elapsedMs: (m.endedAt ?? now) - m.startedAt,
     endCause: m.endCause,
     partial: m.partial === true,
@@ -521,10 +523,28 @@ function safeSessionStats(filePath: string): SessionStats | undefined {
   }
 }
 
+/** Stats over every session file of a member (resets and continuations leave one each); oversized files are skipped. */
+function memberSessionStats(runDir: string, name: string): SessionStats | undefined {
+  const dir = memberSessionDir(runDir, name);
+  const all = listSessionFiles(dir).map((file) => safeSessionStats(path.join(dir, file.name)));
+  const parts = all.filter((stats): stats is SessionStats => stats !== undefined);
+  if (parts.length === 0) return undefined;
+  const total: SessionStats = { entries: 0, turns: 0, toolCalls: 0, usage: emptyUsage() };
+  for (const stats of parts) {
+    total.entries += stats.entries;
+    total.turns += stats.turns;
+    total.toolCalls += stats.toolCalls;
+    for (const key of USAGE_KEYS) total.usage[key] += stats.usage[key];
+    if (stats.first && (!total.first || stats.first < total.first)) total.first = stats.first;
+    if (stats.last && (!total.last || stats.last > total.last)) total.last = stats.last;
+  }
+  return total;
+}
+
 function diskMemberRow(runDir: string, name: string): MemberRowVm {
   const log = parseMemberLog(readOptional(path.join(runDir, `${name}.log`)) ?? "");
   const sessionFile = memberSessionFile(runDir, name);
-  const stats = sessionFile ? safeSessionStats(sessionFile) : undefined;
+  const stats = memberSessionStats(runDir, name);
   const elapsedMs =
     stats?.first && stats.last ? Date.parse(stats.last) - Date.parse(stats.first) : undefined;
   return {
@@ -535,7 +555,7 @@ function diskMemberRow(runDir: string, name: string): MemberRowVm {
     paused: false,
     turns: log.turns ?? stats?.turns ?? 0,
     toolCalls: log.toolCalls ?? stats?.toolCalls ?? 0,
-    usage: stats?.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 },
+    usage: stats?.usage ?? emptyUsage(),
     elapsedMs,
     endCause: log.endCause,
     partial: log.partial,
@@ -572,6 +592,8 @@ export interface RunOverviewVm {
   outcome?: string | undefined;
   stopLabel?: string | undefined;
   cleanStop?: { secondsLeft?: number | undefined; members: string[] } | undefined;
+  /** `--budget` in dollars; the header shows `totals.cost` against it. */
+  budget?: number | undefined;
   plan?: string[] | undefined;
   canary?: string | undefined;
   canaryError?: string | undefined;
@@ -617,6 +639,7 @@ function liveOverview(src: DashboardSource, live: LiveRun): RunOverviewVm {
     outcome: liveOutcome(live),
     stopLabel: live.stopLabel,
     cleanStop: liveCleanStop(live, now),
+    budget: live.budget,
     plan: live.plan,
     canary: live.canary,
     canaryError: live.canaryError,
@@ -658,6 +681,7 @@ function diskOverview(runId: string, runDir: string): RunOverviewVm {
     elapsedMs: elapsed.length > 0 ? Math.max(...elapsed) : undefined,
     outcome: runStateOnDisk(runDir) === "pending" ? "pending" : diskOutcome(runDir),
     cleanStop: cleanStop ? { members: cleanStop.members } : undefined,
+    budget: task.budget,
     plan: readOptional(path.join(runDir, "PLAN.md"))
       ?.split("\n")
       .filter((line) => line.startsWith("- layer ")),
@@ -1095,6 +1119,8 @@ export interface SwarmVm {
   started?: string | undefined;
   elapsedMs?: number | undefined;
   untilStop: boolean;
+  /** `--budget` in dollars across every horde; the header shows the hordes' summed cost against it. */
+  budget?: number | undefined;
   partition: string[];
   /** What the merge step is doing or did: "pending", "merging", "merged", "no deliverable". */
   merge: string;
@@ -1175,6 +1201,7 @@ export function loadSwarm(src: DashboardSource, swarmId: string): SwarmVm {
     started: startedAt !== undefined ? formatDateTime(new Date(startedAt)) : undefined,
     elapsedMs: startedAt !== undefined ? (endedAt ?? nowOf(src)) - startedAt : undefined,
     untilStop: live?.untilStop === true || record?.untilStop === true,
+    budget: live?.budget ?? record?.budget,
     partition,
     merge: mergeLabel(live, record, rows),
     rows,

package/src/dashboard-html.ts

@@ -456,6 +456,7 @@ function overviewHeader(vm: RunOverviewVm): string {
     const left = vm.cleanStop.secondsLeft === undefined ? "" : `hard stop in ${vm.cleanStop.secondsLeft}s: `;
     rows.push(["clean stop", e(`${left}${who}`)]);
   }
+  if (vm.budget !== undefined) rows.push(["budget", `${cost(vm.totals.cost)} of ${cost(vm.budget)} spent`]);
   if (vm.canary) rows.push(["canary", e(vm.canary + (vm.canaryError ? ` (${vm.canaryError})` : ""))]);
   if (vm.diagnosis) rows.push(["diagnosis", e(vm.diagnosis)]);
   if (vm.plan && vm.plan.length > 0) rows.push(["plan", pre(vm.plan.join("\n"))]);
@@ -981,6 +982,9 @@ function swarmHeader(vm: SwarmVm): string {
     ["until stop", vm.untilStop ? "yes" : "no"],
     ["merge", e(vm.merge)],
   ];
+  if (vm.budget !== undefined) {
+    rows.push(["budget", `${cost(vm.rows.reduce((sum, row) => sum + row.totals.cost, 0))} of ${cost(vm.budget)} spent`]);
+  }
   if (vm.notStarted) rows.push(["not started", e(vm.notStarted)]);
   if (vm.partition.length > 0) {
     rows.push(["partition", pre(vm.partition.map((slice, index) => `h${index + 1}: ${slice}`).join("\n"))]);

package/src/format.ts

@@ -43,6 +43,11 @@ export function formatTokens(n: number): string {
   return `${(n / 1_000_000).toFixed(2)}M`;
 }
 
+/** A dollar amount for the widget, status and reports, e.g. `$1.20`. */
+export function formatUsd(amount: number): string {
+  return `$${amount.toFixed(2)}`;
+}
+
 export function oneLine(text: string, max: number): string {
   const collapsed = text.replace(/\s+/g, " ").trim();
   if (collapsed.length <= max) return collapsed;

package/src/ledger/findings.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import { createHash } from "node:crypto";
 import { collaborationState } from "./collaboration.js";
-import type { PeerMessage, ReviewRecord } from "./collaboration.js";
+import type { ArtifactRecord, PeerMessage, ReviewRecord } from "./collaboration.js";
 import { formatClock } from "../format.js";
 import { RUN_HEADING } from "./board.js";
 import { registerConcern } from "./concerns.js";
@@ -558,28 +558,47 @@ export function supersededCitations(text: string, findings: FindingEntry[]): str
     .map((finding) => `F${finding.id} (now F${finding.supersededBy})`);
 }
 
-/** The current revision of every live finding a text cites, pinned so a later amend is visible. */
-export function answerCitations(findings: FindingEntry[], text: string): Record<string, string> {
+/**
+ * The current revision of every live finding and published artifact a text cites, pinned so a
+ * later amend or republish is visible.
+ */
+export function answerCitations(findings: FindingEntry[], text: string, artifacts: ArtifactRecord[] = []): Record<string, string> {
   const cites: Record<string, string> = {};
   for (const finding of findings) {
     if (finding.supersededBy === undefined && new RegExp(`\\bF${finding.id}\\b`).test(text)) cites[`F${finding.id}`] = findingRevision(finding);
   }
+  for (const artifact of artifacts) {
+    if (new RegExp(`\\b${artifact.id}\\b`).test(text)) cites[artifact.id] = artifact.hash;
+  }
   return cites;
 }
 
 /**
- * Citations an answer can no longer stand on: findings superseded since it was written, and
- * findings amended since the revisions it pinned. Both ship a stale reading as the result.
+ * Citations an answer can no longer stand on: findings superseded since it was written, findings
+ * amended and artifacts republished since the revisions it pinned. Each ships a stale reading as
+ * the result.
  */
-export function staleAnswerCitations(findings: FindingEntry[], text: string, cites: Record<string, string> = {}): string[] {
+export function staleAnswerCitations(
+  findings: FindingEntry[],
+  text: string,
+  cites: Record<string, string> = {},
+  artifacts: ArtifactRecord[] = [],
+): string[] {
   const stale = supersededCitations(text, findings).map((citation) => `superseded ${citation}`);
   for (const [target, revision] of Object.entries(cites)) {
     const finding = findings.find((entry) => `F${entry.id}` === target);
     if (finding && finding.supersededBy === undefined && findingRevision(finding) !== revision) stale.push(`amended ${target}`);
+    const artifact = artifacts.find((entry) => entry.id === target);
+    if (artifact && artifact.hash !== revision) stale.push(`republished ${target}`);
   }
   return stale;
 }
 
+/** The answer's stale citations against this run's current findings and artifacts. */
+export function staleAnswerFor(hordeDir: string, runId: string, text: string, cites?: Record<string, string>): string[] {
+  return staleAnswerCitations(listFindingsForRun(hordeDir, runId), text, cites, collaborationState(hordeDir, runId).artifacts);
+}
+
 /** A body line that reads as a verification note would move the subject boundary the revision hashes. */
 function neutralizeNotes(text: string): string {
   return text.replace(/^((?:Verified|Reviewed) by )/gm, "\\$1");

package/src/member.ts

@@ -35,7 +35,10 @@ export interface MemberState {
   streaming?: "text" | "thinking" | undefined;
   turns: number;
   toolCalls: number;
+  /** Usage of the current session; zeroed by every reset, continuation and repair attempt. */
   usage: MemberUsage;
+  /** Usage across every session of this member slot; never reset. Totals and the budget read it. */
+  lifetime: MemberUsage;
   lastText: string;
   finalText: string;
   /** In-progress assistant text retained if termination interrupts the final message. */
@@ -120,6 +123,7 @@ interface SpawnMemberInput {
   onFirstOutput?: () => void;
 }
 
+export const USAGE_KEYS = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const;
 const LAST_TEXT_CHARS = 80;
 const STDERR_TAIL_LINES = 20;
 const KILL_GRACE_MS = 5_000;
@@ -254,13 +258,18 @@ export function newMemberState(index: number): MemberState {
     status: "starting",
     turns: 0,
     toolCalls: 0,
-    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 },
+    usage: emptyUsage(),
+    lifetime: emptyUsage(),
     lastText: "",
     finalText: "",
     startedAt: Date.now(),
   };
 }
 
+export function emptyUsage(): MemberUsage {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}
+
 /** Reset a member to its initial state so it can be respawned (canary retry, stall reset). */
 export function resetMemberState(member: MemberState): void {
   member.status = "starting";
@@ -268,7 +277,7 @@ export function resetMemberState(member: MemberState): void {
   member.attempt = randomUUID();
   member.turns = 0;
   member.toolCalls = 0;
-  member.usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+  member.usage = emptyUsage();
   member.lastText = "";
   member.finalText = "";
   member.draftText = undefined;
@@ -419,11 +428,17 @@ function applyAssistantMessageEnd(member: MemberState, message: Record<string, u
   member.streaming = undefined;
   const usage = (message.usage ?? {}) as Record<string, unknown>;
   const num = (v: unknown): number => (typeof v === "number" ? v : 0);
-  member.usage.input += num(usage.input);
-  member.usage.output += num(usage.output);
-  member.usage.cacheRead += num(usage.cacheRead);
-  member.usage.cacheWrite += num(usage.cacheWrite);
-  member.usage.cost += num((usage.cost as Record<string, unknown> | undefined)?.total);
+  const delta: MemberUsage = {
+    input: num(usage.input),
+    output: num(usage.output),
+    cacheRead: num(usage.cacheRead),
+    cacheWrite: num(usage.cacheWrite),
+    cost: num((usage.cost as Record<string, unknown> | undefined)?.total),
+  };
+  for (const key of USAGE_KEYS) {
+    member.usage[key] += delta[key];
+    member.lifetime[key] += delta[key];
+  }
   const text = messageText(message);
   if (text.trim()) {
     member.finalText = text;