agent-horde 0.2.1 → 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.1
+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)
@@ -68,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
@@ -303,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
 
@@ -456,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.1",
+  "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/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/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;

package/src/prompt.ts

@@ -1,4 +1,4 @@
-import { formatClock, formatDateTime, formatElapsed, formatTokens, oneLine, taskHash } from "./format.js";
+import { formatClock, formatDateTime, formatElapsed, formatTokens, formatUsd, oneLine, taskHash } from "./format.js";
 import type { BoardEntry } from "./ledger/board.js";
 import type { ClaimEntry } from "./ledger/claims.js";
 import type { FindingCluster } from "./ledger/clusters.js";
@@ -26,6 +26,8 @@ export interface RunSummaryInput {
   userStop?: boolean | undefined;
   /** Human-readable stop reason, e.g. "stopped by user" or "stopped at deadline". */
   stopLabel?: string | undefined;
+  /** The `--budget` in dollars the run (or its swarm) clean-stops at. */
+  budget?: number | undefined;
   /** Set when a member reported the goal solved; the end sentence states whether the run wound down on it. */
   solved?: SolvedSignal | undefined;
   /** The other member that validated the proposal, if any. */
@@ -299,10 +301,16 @@ export function taskMarkdown(input: {
   startedAt: number;
   verifier?: string | undefined;
   untilStop?: boolean | undefined;
+  /** `--budget` in dollars; a swarm's budget covers every horde. */
+  budget?: number | undefined;
   /** Set for a horde of a larger swarm: which horde this is and its workstream. */
   swarm?: { id: string; horde: number; hordes: number; slice?: string | undefined } | undefined;
 }): string {
   const swarm = input.swarm;
+  const budget =
+    input.budget === undefined
+      ? "none"
+      : `${formatUsd(input.budget)} (the run clean-stops when member spend${swarm ? " across the swarm" : ""} reaches it)`;
   return [
     `# Horde run ${input.id}`,
     "",
@@ -312,6 +320,7 @@ export function taskMarkdown(input: {
     `Thinking: ${input.thinkingLevel ?? "parent default"}`,
     `Verifier: ${input.verifier ?? "none"}`,
     `Until stop: ${input.untilStop ? "yes (the run continues until stop-clean or stop-hard)" : "no"}`,
+    `Budget: ${budget}`,
     ...(swarm ? [`Swarm: ${swarm.id} (horde h${swarm.horde} of ${swarm.hordes})`] : []),
     ...(swarm?.slice ? [`Workstream: ${swarm.slice}`] : []),
     `Task-SHA256: ${taskHash(input.prompt)}`,
@@ -331,6 +340,8 @@ interface TaskInfo {
   model?: string | undefined;
   thinking?: string | undefined;
   hash?: string | undefined;
+  /** The `--budget` in dollars, when the run was started with one. */
+  budget?: number | undefined;
   prompt: string;
 }
 
@@ -342,13 +353,17 @@ export function parseTaskMarkdown(content: string): TaskInfo {
   for (const line of lines.slice(0, promptAt === -1 ? lines.length : promptAt)) {
     const title = /^# Horde run (\S+)$/.exec(line);
     if (title) info.id = title[1];
-    const field = /^(Started|Members|Model|Thinking|Task-SHA256): (.*)$/.exec(line);
+    const field = /^(Started|Members|Model|Thinking|Budget|Task-SHA256): (.*)$/.exec(line);
     if (!field) continue;
     const value = field[2] ?? "";
     if (field[1] === "Started") info.started = value;
     else if (field[1] === "Members") info.count = Number(/^\d+/.exec(value)?.[0] ?? NaN) || undefined;
     else if (field[1] === "Model") info.model = value;
     else if (field[1] === "Thinking") info.thinking = value;
+    else if (field[1] === "Budget") {
+      const amount = Number(/^\$(\d+(?:\.\d+)?)/.exec(value)?.[1] ?? NaN);
+      if (amount > 0) info.budget = amount;
+    }
     else if (field[1] === "Task-SHA256") info.hash = value;
   }
   return info;
@@ -374,13 +389,14 @@ export interface UsageTotals {
   cost: number;
 }
 
+/** Run totals over every session each member has had; turns count the current sessions only. */
 export function totalUsage(members: MemberState[]): UsageTotals {
   return members.reduce(
     (acc, m) => ({
       turns: acc.turns + m.turns,
-      input: acc.input + m.usage.input,
-      output: acc.output + m.usage.output,
-      cost: acc.cost + m.usage.cost,
+      input: acc.input + m.lifetime.input,
+      output: acc.output + m.lifetime.output,
+      cost: acc.cost + m.lifetime.cost,
     }),
     { turns: 0, input: 0, output: 0, cost: 0 },
   );
@@ -586,6 +602,9 @@ export function formatStatusReport(run: RunSummaryInput, now: number = Date.now(
     const left = Math.max(0, Math.ceil((run.cleanStopUntil - now) / 1000));
     lines.push(`clean stop requested: members wrap up now, hard stop in ${left}s`);
   }
+  if (run.budget !== undefined) {
+    lines.push(`budget: ${formatUsd(totalUsage(run.members).cost)} of ${formatUsd(run.budget)} spent`);
+  }
   for (const m of run.members) {
     lines.push(
       `${m.name.padEnd(10)} ${m.status.padEnd(8)} ${memberActivity(m)}  ` +
@@ -653,7 +672,8 @@ function reportHeader(input: RunReportInput, now: number): string[] {
   if (input.model) lines.push(`Model: ${input.model}`);
   lines.push(
     `Usage: ${usage.turns} turns, ${formatTokens(usage.input)} in / ` +
-      `${formatTokens(usage.output)} out, $${usage.cost.toFixed(4)} cost`,
+      `${formatTokens(usage.output)} out, $${usage.cost.toFixed(4)} cost` +
+      (input.budget === undefined ? "" : ` (budget ${formatUsd(input.budget)})`),
   );
   return lines;
 }

package/src/run/budget.ts

@@ -0,0 +1,30 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { formatUsd } from "../format.js";
+import { totalUsage } from "../prompt.js";
+import { requestCleanStop } from "./controls.js";
+import type { HordeState, Swarm } from "./types.js";
+
+/** Dollars the swarm's members have spent over every session, replaced ones included. */
+export function swarmSpend(swarm: Pick<Swarm, "runs">): number {
+  return swarm.runs.reduce((sum, run) => sum + totalUsage(run.members).cost, 0);
+}
+
+/**
+ * `--budget`: once the members' combined spend reaches the threshold, clean-stop every horde
+ * still working. Called on every child event, so it fires on the usage update that crosses the
+ * line. The flag is set before the first await so a burst of events requests the stop once.
+ * Hordes that already reported are skipped: a clean stop on one would re-arm a timer that
+ * `stopRunTimers` cleared and record a stop-hard on a finished run.
+ */
+export function checkBudget(launch: { state: HordeState; swarm: Swarm; ctx: ExtensionCommandContext }): void {
+  const { state, swarm, ctx } = launch;
+  if (swarm.budget === undefined || swarm.budgetHit || state.disposed) return;
+  const spent = swarmSpend(swarm);
+  if (spent < swarm.budget) return;
+  swarm.budgetHit = true;
+  ctx.ui.notify(`horde ${swarm.id}: budget reached (${formatUsd(spent)} of ${formatUsd(swarm.budget)}); stopping`, "warning");
+  for (const run of swarm.runs) {
+    if (run.stopped || run.reported || run.finalized) continue;
+    void requestCleanStop(run, { kind: "all" }, ctx, { postmortem: false, label: "budget" });
+  }
+}

package/src/run/completions.ts

@@ -31,7 +31,12 @@ const UNTIL_STOP_COMPLETION = {
   description: "keep the whole horde working until stop-clean or stop-hard; validated solves are banked",
 };
 
-const LAUNCH_FLAG_COMPLETIONS = [DASHBOARD_COMPLETION, NO_VERIFIER_COMPLETION, UNTIL_STOP_COMPLETION];
+const BUDGET_COMPLETION = {
+  value: "--budget=5 ",
+  description: "clean-stop the run once the members' combined spend reaches this many dollars; edit the number",
+};
+
+const LAUNCH_FLAG_COMPLETIONS = [DASHBOARD_COMPLETION, NO_VERIFIER_COMPLETION, UNTIL_STOP_COMPLETION, BUDGET_COMPLETION];
 
 /** Argument completions that are not member targets. */
 const EXTRA_COMPLETIONS: Record<string, Array<{ value: string; description: string }>> = {

package/src/run/controls.ts

@@ -19,7 +19,7 @@ const CLEAN_STOP_ACTIVE_GRACE_MS = Number(process.env.PI_HORDE_ACTIVE_GRACE_MS)
 const SOLVED_STOP_MS = Number(process.env.PI_HORDE_SOLVED_STOP_MS) || 30_000;
 
 /** Why a clean stop was requested; selects the report's stop label. */
-type CleanStopLabel = "stop-clean" | "deadline" | "solved";
+type CleanStopLabel = "stop-clean" | "deadline" | "solved" | "budget";
 
 interface CleanStopOptions {
   graceMs?: number | undefined;
@@ -168,6 +168,7 @@ export function setPaused(
 
 function stopLabelFor(label: CleanStopLabel): string {
   if (label === "deadline") return "stopped at deadline";
+  if (label === "budget") return "stopped at budget";
   if (label === "solved") return "stopped during solved wind-down";
   return "stopped by user";
 }

package/src/run/finalize.ts

@@ -29,7 +29,7 @@ import type { PendingCleanup } from "../ledger/resources.js";
 import { archiveSolved, clearCleanStop, clearSolved, readSolvedState, resolveSolvedState, writeAnswer } from "../ledger/run-signals.js";
 import type { SolvedSignal } from "../ledger/run-signals.js";
 import { childEnv, execPi } from "../member.js";
-import { reportText, runReportMarkdown, summaryMarkdown } from "../prompt.js";
+import { reportText, runReportMarkdown, summaryMarkdown, totalUsage } from "../prompt.js";
 import { buildRunGraph } from "../run-graph.js";
 import { runGraphMarkdown } from "../run-graph-mermaid.js";
 import type { CleanupStatus, ReportResource, RunReportInput } from "../prompt.js";
@@ -569,7 +569,10 @@ export async function finalizeRun(state: HordeState, swarm: Swarm, run: HordeRun
     await synthesize(state, run, ledgers, reportInput, now);
     if (annotate && run.deliverable) annotateAnswer(run, answer, acceptance, stale);
     sendReport(state, swarm, run, ledgers, now);
-    await recordLifecycle(run, "run-end", { outcome: runOutcome(run), elapsedMs: Date.now() - run.startedAt, stopLabel: run.stopLabel });
+    await recordLifecycle(run, "run-end", {
+      outcome: runOutcome(run), elapsedMs: Date.now() - run.startedAt, stopLabel: run.stopLabel,
+      spent: totalUsage(run.members).cost, budget: run.budget,
+    });
     writeRunGraph(run);
   } catch (error) {
     safeNotify(run, `horde ${run.id} failed to finalize: ${errorMessage(error)}`, "error");

package/src/run/launch.ts

@@ -277,6 +277,7 @@ function buildSwarm(
     plan: parsed.plan,
     partition: partition.slices,
     untilStop: parsed.untilStop === true ? true : undefined,
+    budget: parsed.budget,
     dashboardUrl,
   };
   return { swarm, launches };
@@ -287,7 +288,7 @@ async function seedHorde(swarm: Swarm, run: HordeRun, roles: string[]): Promise<
   await seedRun(run);
   await recordLifecycle(run, "run-start", {
     count: run.count, model: run.model, verifier: run.verifier, plan: run.plan, untilStop: run.untilStop,
-    roles: roles.map((role) => oneLine(role, 120)), dashboardUrl: run.dashboardUrl,
+    budget: run.budget, roles: roles.map((role) => oneLine(role, 120)), dashboardUrl: run.dashboardUrl,
     ...(swarm.hordes > 1 ? { swarm: swarm.id, horde: run.horde, hordes: swarm.hordes, slice: run.slice } : {}),
   });
   await recordPhase(run, "discovery", "start");

package/src/run/repair.ts

@@ -7,7 +7,7 @@ import { recordEvent } from "../ledger/events.js";
 import type { EventContext } from "../ledger/events.js";
 import { recordPhase } from "./lifecycle.js";
 import { envNumber } from "../format.js";
-import { resetMemberState } from "../member.js";
+import { resetMemberState, USAGE_KEYS } from "../member.js";
 import type { MemberState } from "../member.js";
 import { hardStopMembers } from "./controls.js";
 import { scheduleCollaboration, stopReason } from "./schedule.js";
@@ -289,7 +289,7 @@ async function repairMember(phase: RepairPhase, member: MemberState, ms: number,
     run.repairTokens = (run.repairTokens ?? 0) + spent();
     member.turns += prior.turns;
     member.toolCalls += prior.toolCalls;
-    for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost"] as const) member.usage[key] += prior.usage[key];
+    for (const key of USAGE_KEYS) member.usage[key] += prior.usage[key];
     member.startedAt = prior.startedAt;
   }
 }

package/src/run/setup.ts

@@ -93,7 +93,8 @@ export function createRun(
   fs.writeFileSync(
     path.join(runDir, "TASK.md"),
     taskMarkdown({
-      id, prompt, count, model, thinkingLevel: ctx.thinkingLevel, startedAt, verifier, untilStop: parsed.untilStop, swarm,
+      id, prompt, count, model, thinkingLevel: ctx.thinkingLevel, startedAt, verifier, untilStop: parsed.untilStop,
+      budget: parsed.budget, swarm,
     }),
     "utf-8",
   );
@@ -123,6 +124,7 @@ export function createRun(
     plan,
     verifier,
     untilStop: parsed.untilStop === true ? true : undefined,
+    budget: parsed.budget,
     resets: [],
     dashboardUrl,
   };

package/src/run/supervise.ts

@@ -9,6 +9,7 @@ import { reconcileOwnedIdeas } from "../ledger/ideas.js";
 import { cleanStopRequestedFor, clearHeartbeat, readHeartbeat } from "../ledger/run-signals.js";
 import { resetMemberState, spawnMember } from "../member.js";
 import type { MemberState } from "../member.js";
+import { checkBudget } from "./budget.js";
 import { hardStopMembers } from "./controls.js";
 import { recordLifecycle } from "./lifecycle.js";
 import type { HordeRun, HordeState, Swarm } from "./types.js";
@@ -72,7 +73,7 @@ export async function spawnOne(
     approve: ctx.isProjectTrusted(),
     signal: controller.signal,
     role: launch.roles[member.index - 1],
-    onChange: () => { onProgress?.(); refreshRun(run); },
+    onChange: () => { onProgress?.(); checkBudget(launch); refreshRun(run); },
     onSpawn: (proc) => run.procs.set(member.name, proc),
     onExit: () => {
       run.controller.signal.removeEventListener("abort", onMasterAbort);
@@ -84,7 +85,7 @@ export async function spawnOne(
   await recordLifecycle(run, "member-exit", {
     member: member.name, attempt: member.attempt, status: member.status, endCause: member.endCause,
     exitCode: member.exitCode, turns: member.turns, toolCalls: member.toolCalls,
-    tokens: member.usage.input + member.usage.output, partial: member.partial === true,
+    tokens: member.usage.input + member.usage.output, cost: member.usage.cost, partial: member.partial === true,
   });
 }
 

package/src/run/swarm-finalize.ts

@@ -15,6 +15,8 @@ export interface SwarmRecord {
   count: number;
   startedAt: number;
   untilStop: boolean;
+  /** The swarm's `--budget` in dollars, when one was given. */
+  budget?: number | undefined;
   partition: string[];
   runs: Array<{ label: string; runId: string; runDir: string; hordeDir: string; startedAt: number; endedAt?: number | undefined; outcome?: string | undefined }>;
   /** The merge step: when the swarm deliverable helper ran and whether it wrote anything. */
@@ -30,6 +32,7 @@ export function swarmRecord(swarm: Swarm): SwarmRecord {
     count: swarm.count,
     startedAt: swarm.startedAt,
     untilStop: swarm.untilStop === true,
+    budget: swarm.budget,
     partition: swarm.partition ?? [],
     runs: swarm.runs.map((run) => ({
       label: `h${run.horde}`,

package/src/run/swarm-report.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { formatDateTime, formatElapsed, formatTokens, oneLine } from "../format.js";
+import { formatDateTime, formatElapsed, formatTokens, formatUsd, oneLine } from "../format.js";
 import { listFindingsForRun } from "../ledger/findings.js";
 import { statusCounts, totalUsage } from "../prompt.js";
 import { hordeLabel } from "./types.js";
@@ -96,6 +96,7 @@ export function swarmReportMarkdown(swarm: Swarm, now: number = Date.now()): str
     `- elapsed: ${formatElapsed(now - swarm.startedAt)}`,
     `- hordes: ${swarm.hordes} x ${swarm.count} members`,
     `- until stop: ${swarm.untilStop ? "yes" : "no"}`,
+    ...(swarm.budget === undefined ? [] : [`- budget: ${formatUsd(swarm.budget)} across every horde`]),
     `- outcomes: ${rows.map((row) => `${row.label} ${row.outcome}`).join(", ")}`,
     `- merged deliverable: ${swarm.deliverable ? "DELIVERABLE.md" : "not written"}`,
     "",

package/src/run/swarm.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { formatDateTime, formatRunId, taskHash } from "../format.js";
+import { formatDateTime, formatRunId, formatUsd, taskHash } from "../format.js";
 import { hordePaths, initHordeDirAt } from "../ledger/files.js";
 import type { SiblingHorde } from "../member.js";
 import { hordeLabel } from "./types.js";
@@ -99,6 +99,7 @@ export function swarmMarkdown(swarm: Swarm): string {
     `Hordes: ${swarm.hordes} x ${swarm.count} members (${hordeLabel(1)} .. ${hordeLabel(swarm.hordes)})`,
     `Model: ${swarm.runs[0]?.model ?? "parent default"}`,
     `Until stop: ${swarm.untilStop ? "yes (every horde continues until stop-clean or stop-hard)" : "no"}`,
+    `Budget: ${swarm.budget === undefined ? "none" : `${formatUsd(swarm.budget)} across every horde`}`,
     `Partition: ${swarm.plan ? "plan layers dealt round-robin" : "planner helper"}`,
     `Task-SHA256: ${taskHash(swarm.prompt)}`,
     "",

package/src/run/types.ts

@@ -83,6 +83,8 @@ export interface HordeRun extends MemberRunInfo {
   solvedContest?: { proposal: SolvedSignal; blockers: number[] } | undefined;
   /** True once the parent has warned that a validated solve still has unverified findings. */
   solvedVerificationNotice?: boolean | undefined;
+  /** The swarm's `--budget` in dollars, recorded per run for TASK.md and the events. */
+  budget?: number | undefined;
   /** Solves banked so far in an `--until-stop` run. */
   solveRounds?: number | undefined;
   /** The latest banked solve of an `--until-stop` run: the answer unless a later proposal is validated. */
@@ -116,6 +118,10 @@ export interface Swarm {
   /** Per-horde workstream, indexed by horde - 1; absent for a swarm of one. */
   partition?: string[] | undefined;
   untilStop?: boolean | undefined;
+  /** `--budget`: combined member spend in dollars at which every horde is clean-stopped. */
+  budget?: number | undefined;
+  /** True once the budget tripped, so the stop is requested exactly once. */
+  budgetHit?: boolean | undefined;
   dashboardUrl?: string | undefined;
   /** Generated merged deliverable across the hordes' deliverables. */
   deliverable?: string | undefined;

package/src/tool/actions.ts

@@ -23,7 +23,7 @@ import { readEvents, recordEvent } from "../ledger/events.js";
 import type { EventContext } from "../ledger/events.js";
 
 const CLEAN_STOP_NOTICE =
-  "A clean stop was requested by the user. Stop starting new work. Mark your claimed ideas done " +
+  "A clean stop is in effect for this run. Stop starting new work. Mark your claimed ideas done " +
   "or drop them, post a one-line status to BOARD.md, then write your final summary and make no " +
   "further tool calls.";
 

package/src/tool/params.ts

@@ -1,7 +1,19 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { Type } from "typebox";
+import { Type, type TUnsafe } from "typebox";
 import { FINDING_CONFIDENCES, FINDING_IMPORTANCE, FINDING_SUPPORT } from "../ledger/findings.js";
 
+/**
+ * A string enum schema whose static type is the union of its values.
+ *
+ * pi-ai's StringEnum returns a pi-schema type since pi 1.5, which TypeBox's `Type.Object`
+ * cannot infer a static type from, so the schema is built here with TypeBox directly.
+ */
+function StringEnum<T extends readonly string[]>(
+  values: T,
+  options: { description?: string } = {},
+): TUnsafe<T[number]> {
+  return Type.Unsafe<T[number]>({ type: "string", enum: [...values], ...options });
+}
+
 export const HordeParams = Type.Object({
   action: StringEnum(
     [

package/src/widget.ts

@@ -1,6 +1,6 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import { formatElapsed, formatTokens } from "./format.js";
+import { formatElapsed, formatTokens, formatUsd } from "./format.js";
 import type { MemberState } from "./member.js";
 import { memberActivity, statusCounts, totalUsage } from "./prompt.js";
 
@@ -16,12 +16,15 @@ interface WidgetRun {
   reported?: boolean | undefined;
   finalized?: boolean | undefined;
   outcome?: string | undefined;
+  /** `--budget` in dollars; the header shows spend against it. */
+  budget?: number | undefined;
 }
 
 interface WidgetSwarm {
   id: string;
   runs: WidgetRun[];
   startedAt: number;
+  budget?: number | undefined;
   dashboardUrl?: string | undefined;
   /** The swarm step still running after every horde finalized, e.g. ["merge"]. */
   finalizing?: string[] | undefined;
@@ -56,6 +59,7 @@ export function headerLine(run: WidgetRun, now: number, theme: Theme): string {
   if (c.failed) parts.push(theme.fg("error", `${c.failed} failed`));
   if (c.stopped) parts.push(theme.fg("warning", `${c.stopped} stopped`));
   parts.push(formatElapsed(now - run.startedAt));
+  if (run.budget !== undefined) parts.push(budgetPart(run.members, run.budget, theme));
   if (run.cleanStopUntil !== undefined) {
     const left = Math.max(0, Math.ceil((run.cleanStopUntil - now) / 1000));
     parts.push(theme.fg("warning", `clean stop in ${left}s`));
@@ -67,6 +71,11 @@ export function headerLine(run: WidgetRun, now: number, theme: Theme): string {
   return `${parts.join("  ")}  ${theme.fg("dim", "/agent-horde status | stop-hard | stop-clean")}`;
 }
 
+/** `$1.20 of $5.00`: spend over every session so far against the `--budget`. */
+function budgetPart(members: MemberState[], budget: number, theme: Theme): string {
+  return theme.fg("dim", `${formatUsd(totalUsage(members).cost)} of ${formatUsd(budget)}`);
+}
+
 function memberLine(m: MemberState, now: number, frame: number, theme: Theme): string {
   const elapsed = formatElapsed((m.endedAt ?? now) - m.startedAt);
   const activity = memberActivity(m);
@@ -118,7 +127,7 @@ export function hordeLine(run: WidgetRun, now: number, frame: number, theme: The
   ];
   if (c.failed) parts.push(theme.fg("error", `${c.failed} failed`));
   if (c.stopped) parts.push(theme.fg("warning", `${c.stopped} stopped`));
-  parts.push(theme.fg("dim", `t${usage.turns}  ${formatTokens(usage.input + usage.output)} tok  $${usage.cost.toFixed(2)}`));
+  parts.push(theme.fg("dim", `t${usage.turns}  ${formatTokens(usage.input + usage.output)} tok  ${formatUsd(usage.cost)}`));
   parts.push(theme.fg("muted", hordeActivity(run, c)));
   return ` ${glyph} ${`h${run.horde}`.padEnd(3)} ${parts.join("  ")}`;
 }
@@ -135,6 +144,7 @@ function swarmHeader(swarm: WidgetSwarm, now: number, theme: Theme): string {
   if (c.failed) parts.push(theme.fg("error", `${c.failed} failed`));
   if (c.stopped) parts.push(theme.fg("warning", `${c.stopped} stopped`));
   parts.push(formatElapsed(now - swarm.startedAt));
+  if (swarm.budget !== undefined) parts.push(budgetPart(members, swarm.budget, theme));
   if (swarm.finalizing && swarm.finalizing.length > 0) {
     parts.push(theme.fg("warning", `synthesizing ${swarm.finalizing.join(", ")}`));
   }