@pify/swarm 0.9.2 → 0.11.0

package/README.md

@@ -23,9 +23,25 @@ The catch is that "independent" is usually a small lie — the items do not depe
 | `agent` | string, optional | Force one agent type for all items instead of routing |
 | `isolation` | `"worktree"`, optional | Give each item its own git worktree — use it when items write |
 | `mailbox` | boolean, optional | Give the children `swarm_post` / `swarm_inbox` |
+| `gate` | string, optional | A command every item must pass — `bun test`, `tsc --noEmit` — run in that item's own working directory |
+| `gateExpect` | string, optional | Regex the gate output must match, for checks that exit 0 without proving anything |
+| `gateRepairs` | number, optional | Repair passes per item after a failed gate, 0–5 (default 1) |
+| `on_upstream_failure` | `"continue"` / `"skip"`, optional | What a dependent does when something it needs did not succeed (default `continue`) |
 | `background` | boolean, optional | Return a `runId` immediately instead of blocking |
 
-Blocking by default: returns `N done, M error` plus a per-item report.
+Blocking by default: returns `N succeeded, M failed` plus a per-item report.
+
+### Gates and outcomes
+
+A gate asks the shell, not a model. Each item's gate runs in the tree that item worked in — its own worktree under `isolation: "worktree"` — after the child finishes, so it judges what you would merge. It runs asynchronously: pi keeps rendering, Esc still lands, and the other children's streams are still read while a two-minute suite runs; at the deadline the whole process tree is killed, not just the shell that started it, so a timed-out suite does not run on holding the pipes open. A failing gate sends the child back once with the command, the verdict and the output, then re-runs; `gateRepairs: 0` turns that off. That repair brief is the whole prompt the child gets — it quotes the original task under `== Original task ==` and says to fix the cause and stop, not to do the task again — and the child rejoins the run's mailbox. A read-only agent is never asked to repair, and neither is a child that ended its report with `OUTCOME: blocked`: the wall it named is outside its reach, and a failing gate does not move it. The gate still runs once so the report says what it proved. While a repair is in flight the item shows as running, not finished.
+
+The verdict can say more than pass/fail: `success`, `failure`, `result_missing` (exited 0 but never showed the evidence `gateExpect` asked for — a runner that matched no tests), `timeout`, or `no_attestation` (never ran at all — a typo, a missing runner; not a verdict on the work, and never repaired). If other items were changing the same directory while a gate ran, the report says the verdict is true of the tree, not of that item alone — which is what `isolation` is for.
+
+Every item then reports two facts. Its **status** says whether the child finished; its **outcome** says whether the task did. A failed gate outranks a child that claims success; without a gate the outcome is the child's own account, and a child that could not finish can end its report with `OUTCOME: blocked` or `OUTCOME: failed` to say so in one parseable place. The header counts outcomes, so an item that ran to the end and failed its check is filed under `failed`, not `done` — and the widget shows it as ✗, not ✓.
+
+**Failures interrupt.** A background run wakes you once, as soon as the first item fails hard, while the rest are still running — the same rule `@pify/subagent` uses for a failed background child. The message says it is a warning and that the full report still follows; it does not ask you to poll. Subsequent failures wait for the aggregate report, since N interrupts for N failures would be worse than none.
+
+**`on_upstream_failure`.** By default a dependent still runs when something it needed failed, with a `(failed: …)` notice in place of that item's output — visible, but it spends a child on a step that is usually doomed. `skip` settles the dependent instead, marks it `skipped` (its own state, not a second failure), and the skip cascades down the branch. Independent items are unaffected either way.
 
 ### Dependencies: `needs`
 
@@ -50,8 +66,9 @@ The whole graph is checked **before anything spawns**: a cycle, a self-edge, a d
 | Parameter | Type | Notes |
 |---|---|---|
 | `runId` | string, optional | Defaults to the most recent run |
+| `wait` | number, optional | Seconds to hold the call for the run to finish, 0–120 (default 0) |
 
-Live per-item progress (`1:scout=running(3t) · 2:reviewer=queued`), and the full report once the run finishes. Completed runs survive `/reload`.
+A "not ready" answer while the run is in flight (per-item progress is on the widget and in `/swarm`), and the full report once the run finishes. Completed runs survive `/reload`. `wait` is for the headless case (`pi -p`), where nothing is delivered after the turn ends: one call that waits returns the report in one turn instead of several; the wait ends early on Esc.
 
 ### `swarm_post` / `swarm_inbox`
 
@@ -82,17 +99,19 @@ The catalog is the same `.pi/agents/*.md` one [`@pify/subagent`](https://github.
 ## Behaviour
 
 - **Independence by design.** Items share nothing, children cannot spawn children, and each child is capped at its agent's `max_turns`.
-- **Stopping stops the children.** Pressing Esc, or switching away from the session, aborts every live child rather than leaving them talking to the provider on your money. A cancelled run keeps that verdict — it is never reported as done — and `swarm_status` shows what the items that did finish produced.
+- **Stopping stops the children.** Pressing Esc stops a foreground run, `/swarm stop [runId]` stops a background one (its tool call returned long ago, so Esc has nothing to reach), and switching away from the session stops both — in every case every live child is aborted rather than left talking to the provider on your money. A cancelled run keeps that verdict — it is never reported as done — and `swarm_status` shows what the items that did finish produced, with each stopped item saying who stopped it.
 - **Isolated runs clean up after themselves.** With `isolation: "worktree"`, a worktree whose child changed nothing is removed along with its branch; otherwise a read-only step left one of each behind on every run. Anything uncommitted, and any commit the child made, is kept and reported.
 
 ## A background run comes back to you
 
-`swarm_status` on a run still in flight used to say "still running", which left the model one option: ask again. The aggregated report is **delivered** into the conversation when the run finishes — measured, not assumed: `test/live/delivery-wire.mjs` drives a real background swarm through pi, holds the session open the way an interactive one naturally stays open, and reads the report out of pi's own provider payload (3/3; the run finished and the report arrived unasked). One caveat the measurement taught: delivery is a property of sessions that outlive their runs — interactive sessions do, `pi -p` does not. Asking early returns a structured result carrying `retryable`, the elapsed time and `pollRequired: false` — a normal answer rather than an error, because a tool error over a condition only time resolves invites the model's retry machinery into a loop.
+`swarm_status` on a run still in flight used to say "still running", which left the model one option: ask again. The aggregated report is **delivered** into the conversation when the run finishes — measured, not assumed: `test/live/delivery-wire.mjs` drives a real background swarm through pi, holds the session open the way an interactive one naturally stays open, and reads the report out of pi's own provider payload (3/3; the run finished and the report arrived unasked). One caveat the measurement taught: delivery is a property of sessions that outlive their runs — interactive sessions do, `pi -p` does not. Asking early returns a structured result carrying `retryable`, the elapsed time and `pollRequired` (`false` interactively; `true` under `pi -p`, where the text tells the model to collect within the turn or use `wait`) — a normal answer rather than an error, because a tool error over a condition only time resolves invites the model's retry machinery into a loop.
 
 ## Command
 
 `/swarm` — runs in this session, and the agent types available for routing.
 
+`/swarm stop [runId]` — cancel a live run (default: the active one) and abort its children. The way to stop a background run; a foreground run stops on Esc.
+
 ## Where this sits in the suite
 
 [`@pify/subagent`](https://github.com/pifydev/subagent) is one child and one task. `@pify/swarm` is many items at once — independent, or wired together with a declarative `needs` graph (fan-out, chains, joins). [`@pify/workflow`](https://github.com/pifydev/workflow) is for when orchestration needs real control flow — loops, conditionals, retries, fan-out computed at run time — that a static graph can't express. Pick the smallest one that fits.

package/extensions/swarm.ts

@@ -22,6 +22,7 @@ import {
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 
 import { BUILTIN_AGENTS } from "../src/builtin.ts";
@@ -50,7 +51,19 @@ import {
   readInbox,
 } from "../src/mailbox.ts";
 import { parseAgentFile } from "../src/frontmatter.ts";
-import { buildReport, buildStatusLine } from "../src/report.ts";
+import { buildReport, buildStatusLine, earlyFailureNotice } from "../src/report.ts";
+import {
+  normalizeGate,
+  runGate,
+  sharedWith,
+  type GateContract,
+  type GateSibling,
+  type GateVerdict,
+} from "../src/gate.ts";
+import { runGateCycle } from "../src/repair.ts";
+import { repairAllowed } from "../src/repair-policy.ts";
+import { deriveOutcome, parseDeclaredOutcome, stripDeclaration } from "../src/outcome.ts";
+import { waitUntil } from "../src/wait.ts";
 import { routeItem } from "../src/routing.ts";
 import { normalizeItems } from "../src/graph.ts";
 import { runGraph } from "../src/schedule.ts";
@@ -62,11 +75,14 @@ import {
   type AgentDef,
   type ItemState,
   type SwarmRun,
+  type UpstreamFailurePolicy,
 } from "../src/types.ts";
 import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 
 const RUN_ENTRY = "swarm-run";
+/** Longest a swarm_status call may hold on to a running run, in seconds. */
+const MAX_STATUS_WAIT_S = 120;
 const CLEAN_WORKTREE_NOTE =
   "Ran isolated in a temporary worktree; it changed nothing, so the worktree was removed.";
 
@@ -191,6 +207,12 @@ export default function swarm(pi: ExtensionAPI) {
     workDir?: string,
     mailbox?: string,
   ): Promise<void> {
+    // A stop can land before this item has a session to abort — the scheduler
+    // launched it, the loader is still reloading — and cancelRun has already
+    // written its record. Starting anyway would overwrite that with "running"
+    // and leave a child no stop can reach.
+    const cancelled = (): boolean => runs.get(runId)?.status === "cancelled";
+    if (cancelled()) return;
     item.status = "running";
     renderWidget();
     let session: AgentSession | null = null;
@@ -228,7 +250,17 @@ export default function swarm(pi: ExtensionAPI) {
         appendSystemPrompt: [
           ...(promptOptions.appendSystemPrompt ? [promptOptions.appendSystemPrompt] : []),
           def.systemPrompt,
-          "You are one agent in a swarm, handling exactly one item. Your final assistant message is the deliverable — make it complete and self-contained.",
+          // The same contract subagent's children get, including the OUTCOME
+          // line: the report tallies `blocked`, and skip-on-upstream-failure
+          // keys off the outcome, so a child that is never told the protocol
+          // can never be anything but succeeded or failed.
+          "You are one agent in a swarm, handling exactly one item. Your final assistant message is the deliverable — " +
+            "make it complete and self-contained; the swarm cannot reply to it. Close by stating each requirement of your " +
+            "item and the concrete evidence it is met (the command you ran and what it showed); mark anything you could " +
+            "not verify as unverified rather than done. Finishing your turn is not the same as finishing the item: if you " +
+            "could not do it, end the report with a line reading exactly `OUTCOME: blocked` (a decision, access or " +
+            "information you do not have) or `OUTCOME: failed` (you tried and it does not work), so the swarm does not " +
+            "have to infer it from your prose. Say nothing if it went fine.",
           ...(mailbox ? [mailboxPrompt(item.agent + "-" + item.index)] : []),
         ],
       });
@@ -246,6 +278,9 @@ export default function swarm(pi: ExtensionAPI) {
         resourceLoader: loader,
       });
       session = created.session;
+      // Same window, other side: a stop during session creation found nothing
+      // registered. Do not prompt a child of a run that is already over.
+      if (cancelled()) return;
       releaseLive = live.register(runId, session);
 
       const guard = new LoopGuard();
@@ -345,24 +380,141 @@ export default function swarm(pi: ExtensionAPI) {
   }
 
   /**
-   * Readiness scheduler: run each item as soon as its `needs` are done, up to
-   * DEFAULT_CONCURRENCY at once. A flat run (no needs anywhere) makes every
-   * item ready immediately, so this is identical to the old parallel pool.
+   * Settle the two facts the status alone cannot give: what the item's task came
+   * to, and how well that is known. Settled once — re-running it after the
+   * isolation note is appended would find the declaration already stripped and
+   * quietly promote a blocked item to a successful one.
    */
-  async function executeRun(
+  function settleItem(item: ItemState): void {
+    if (item.status === "queued" || item.status === "running" || item.outcome) return;
+    // A skipped item was never attempted, so it has no outcome to report — not
+    // a failure of its own, and calling it one would double-count the upstream
+    // failure that caused it.
+    if (item.status === "skipped") return;
+    const declared = parseDeclaredOutcome(item.result);
+    if (declared && item.result) item.result = stripDeclaration(item.result);
+    item.verification ??= "not-requested";
+    item.outcome = deriveOutcome({
+      status: item.status === "done" ? "done" : item.status === "aborted" ? "aborted" : "error",
+      declared,
+      verification: item.verification,
+    });
+  }
+
+  /**
+   * Run the caller's gate in the tree this item worked in and, if it failed,
+   * send the child back to fix it. Recorded either way — a gate that passed is
+   * a fact worth saying, and a gate that could not run says so rather than
+   * blaming the work.
+   */
+  async function gateItem(
     ctx: UiContext,
     run: SwarmRun,
-    context: string,
-    fixed?: string,
-    isolate?: boolean,
-    useMailbox?: boolean,
+    item: ItemState,
+    def: AgentDef,
+    opts: RunOptions,
   ): Promise<void> {
+    // A cancelled run has nothing left to prove; a gate is a test suite, and
+    // spending one on work nobody is waiting for is the stop not stopping.
+    if (!opts.gate || item.status !== "done" || run.status === "cancelled") return;
+    const subject = item.workDir ?? ctx.cwd;
+    // sharedWith() reads an undefined workDir as "the subject's directory", so
+    // an item that ran in place — no worktree of its own — would count as
+    // sharing every isolated sibling's worktree, and every isolated item's
+    // pass came out attributed to the tree. Name the directory each item was
+    // actually in.
+    const dirOf = (i: ItemState): string => i.workDir ?? ctx.cwd;
+    const self: GateSibling = { id: item.index, label: item.id, status: item.status, workDir: dirOf(item) };
+    const siblings: GateSibling[] = run.items
+      .filter((i) => i.index !== item.index)
+      .map((i) => ({ id: i.index, label: i.id, status: i.status, workDir: dirOf(i) }));
+    // Read the child's declaration now, while it is still in the result:
+    // settleItem strips it, and a blocked child is not sent to fix a gate.
+    const canRepair = repairAllowed(def, item.result);
+    try {
+      // The gate that actually ran, whatever the cycle reports. After a repair
+      // the cycle re-runs the gate; on a cancelled run that is up to the whole
+      // deadline spent proving nothing anyone will read — but a check that
+      // DID run and failed before the stop landed is a real verdict, and
+      // answering no_attestation for it would file a failed gate as
+      // "proved nothing", which is the case the outcome model exists to stop.
+      let last: (GateVerdict & { output: string }) | null = null;
+      let repaired = false;
+      const { record, verification } = await runGateCycle(item.item, opts.gate, subject, {
+        runGate: async (contract, cwd) => {
+          if (run.status === "cancelled" && last) return last;
+          last = await runGate(contract, cwd);
+          return last;
+        },
+        canRepair,
+        maxAttempts: opts.gateRepairs ?? 1,
+        sharedWith: sharedWith(self, subject, siblings),
+        repair: async (prompt) => {
+          if (run.status === "cancelled") return;
+          repaired = true;
+          // The brief IS the item. Handed over as `context` it arrived as "fix
+          // exactly this" followed by the whole original task under `Your
+          // item:`, which reads as an invitation to do the task again. The
+          // brief already quotes the task; nothing else is sent.
+          //
+          // The repair is the same child type over the same tree, in the same
+          // mailbox — the siblings' facts still apply — and its report
+          // replaces the stale one, which described a tree that has changed.
+          const fix: ItemState = { ...item, item: prompt, result: null, error: null, status: "queued", turns: 0, tokens: 0 };
+          // The widget draws `item`, not `fix`; without this the row sat as a
+          // finished ✓ for the whole repair.
+          item.status = "running";
+          renderWidget();
+          await runItem(ctx, run.runId, def, fix, "", item.workDir, opts.mailbox);
+          item.turns += fix.turns;
+          item.tokens += fix.tokens;
+          // cancelRun may have marked the item aborted meanwhile; that verdict
+          // and its note stand, and the stale result is not swapped under it.
+          if (item.status !== "running") return;
+          item.status = "done";
+          if (fix.status === "done" && fix.result?.trim()) item.result = fix.result;
+        },
+      });
+      // The cycle counts a repair pass it asked for; one the stop refused is
+      // not a repair, and the record must not say the tree was fixed.
+      item.gate = repaired ? record : { ...record, repairs: undefined };
+      item.verification = verification;
+    } catch (err) {
+      // A gate that throws proved nothing; say so rather than losing the
+      // child's work to an error in the checking machinery.
+      item.gate = {
+        command: opts.gate.command,
+        outcome: "no_attestation",
+        ok: false,
+        reason: `gate could not be run: ${err instanceof Error ? err.message : String(err)}`,
+      };
+      item.verification = "inconclusive";
+    }
+  }
+
+  interface RunOptions {
+    context: string;
+    fixed?: string;
+    isolate?: boolean;
+    useMailbox?: boolean;
+    gate?: GateContract;
+    gateRepairs?: number;
+    /** The run's mailbox dir once executeRun has made one, so a repair child joins the same log. */
+    mailbox?: string;
+    onUpstreamFailure?: UpstreamFailurePolicy;
+    /** Called once, for the first item that settles badly while others run. */
+    onEarlyFailure?: (item: ItemState) => void;
+  }
+
+  async function executeRun(ctx: UiContext, run: SwarmRun, opts: RunOptions): Promise<void> {
+    const { context, fixed, isolate, useMailbox } = opts;
     // One shared log per run; only created when the caller asked for it. Keyed
     // on a per-run token (not the reused "s1" run id), so one run never reads a
     // previous run's stale messages, and removed at the end so it never leaks.
     const mailbox = useMailbox
       ? mailboxDir(getAgentDir(), mailboxKey(run.runId, run.startedAt))
       : undefined;
+    const gateOpts: RunOptions = { ...opts, mailbox };
 
     // A dependent structurally receives each upstream's output — the thing a
     // hand-sequenced coordinator forgets. Prepended to the shared preamble.
@@ -375,6 +527,18 @@ export default function swarm(pi: ExtensionAPI) {
       return [context, ...blocks].filter((s) => s && s.trim()).join("\n\n");
     };
 
+    // The first hard failure wakes the caller once, and only while there is
+    // still a run to warn it about; after that the aggregate report is the
+    // report. N interrupts for N failures would be worse than none.
+    let warned = false;
+    const settle = (item: ItemState): void => {
+      settleItem(item);
+      if (warned || !opts.onEarlyFailure) return;
+      if (item.outcome !== "failed" || item.status === "aborted") return;
+      warned = true;
+      opts.onEarlyFailure(item);
+    };
+
     // Run each item once its needs finish, up to the concurrency cap; a flat
     // run (no needs) has everything ready at once, exactly like the old pool.
     try {
@@ -382,13 +546,27 @@ export default function swarm(pi: ExtensionAPI) {
         run.items,
         DEFAULT_CONCURRENCY,
         async (item, upstream) => {
+          // A failed node still counts as done so the graph drains rather than
+          // wedging — but "unblocked" and "worth running" are different
+          // questions. With skip, a dependent of work that did not succeed is
+          // settled without spending a child on input that is a failure notice.
+          const broken = upstream.filter((up) => up.status !== "done" || up.outcome !== "succeeded");
+          if (opts.onUpstreamFailure === "skip" && broken.length > 0) {
+            item.status = "skipped";
+            item.error = `${broken.map((u) => u.id).join(", ")} did not succeed`;
+            settleItem(item);
+            renderWidget();
+            return;
+          }
           const def = routeItem(item.item, defs, fixed);
           item.agent = def.name;
           const itemContext = contextFor(upstream);
           if (isolate) {
             try {
               const iso = createIsolationWorktree(ctx.cwd, run.runId + "-i" + (item.index + 1));
+              item.workDir = iso.path;
               await runItem(ctx, run.runId, def, item, itemContext, iso.path, mailbox);
+              await gateItem(ctx, run, item, def, gateOpts);
               // Remove the worktree when the item changed nothing (the leak
               // removeIfUnchanged fixes); keep it when there is work to merge.
               const removed = removeIfUnchanged(ctx.cwd, iso);
@@ -401,7 +579,9 @@ export default function swarm(pi: ExtensionAPI) {
             }
           } else {
             await runItem(ctx, run.runId, def, item, itemContext, undefined, mailbox);
+            await gateItem(ctx, run, item, def, gateOpts);
           }
+          settle(item);
         },
         () => run.status === "cancelled",
       );
@@ -418,6 +598,10 @@ export default function swarm(pi: ExtensionAPI) {
     }
 
     if (run.status !== "cancelled") run.status = "done";
+    // A cancelled run's items were marked aborted without going through the
+    // scheduler's settle path; the report still has to be able to name what
+    // each one came to.
+    for (const item of run.items) settleItem(item);
     run.finishedAt = Date.now();
     pi.appendEntry(RUN_ENTRY, run);
     renderWidget();
@@ -459,7 +643,11 @@ export default function swarm(pi: ExtensionAPI) {
       "conventions instead of silently conflicting. " +
       "An item can be a plain string (independent) OR an object {task, id, needs:[ids]} to declare a " +
       "dependency: a needed item's output is prepended to the dependent automatically, and the dependent " +
-      "starts only once its needs finish. A cycle, a self-edge, or an unknown id is rejected before anything runs.",
+      "starts only once its needs finish. A cycle, a self-edge, or an unknown id is rejected before anything runs. " +
+      "gate is a command every item must pass — it runs in that item's own working directory when it finishes, " +
+      "a failure sends the child back to fix it once, and the report says what the check proved rather than " +
+      "only what the child claims. on_upstream_failure=skip settles a dependent without spending a child when " +
+      "something it needed did not succeed.",
     parameters: Type.Object({
       items: Type.Array(
         Type.Union([
@@ -480,6 +668,27 @@ export default function swarm(pi: ExtensionAPI) {
       mailbox: Type.Optional(
         Type.Boolean({ description: "Give the agents swarm_post/swarm_inbox to share facts mid-run" }),
       ),
+      gate: Type.Optional(
+        Type.String({
+          description:
+            "Shell command every item must pass, e.g. \"bun test\". Run in that item's working directory once it finishes.",
+        }),
+      ),
+      gateExpect: Type.Optional(
+        Type.String({
+          description:
+            "Regex the gate output must match. Use it when exit 0 does not prove the check ran; exiting 0 without a match is reported as verifying nothing.",
+        }),
+      ),
+      gateRepairs: Type.Optional(
+        Type.Number({ description: "Repair passes per item after a failed gate, 0-5 (default 1)" }),
+      ),
+      on_upstream_failure: Type.Optional(
+        StringEnum(["continue", "skip"], {
+          description:
+            "What a dependent does when something it needs did not succeed: continue (default, it runs and is told) or skip (it is settled without spending a child)",
+        }),
+      ),
       background: Type.Optional(Type.Boolean()),
     }),
     async execute(
@@ -491,6 +700,10 @@ export default function swarm(pi: ExtensionAPI) {
         background?: boolean;
         isolation?: string;
         mailbox?: boolean;
+        gate?: string;
+        gateExpect?: string;
+        gateRepairs?: number;
+        on_upstream_failure?: UpstreamFailurePolicy;
       },
       signal,
       _onUpdate,
@@ -509,6 +722,25 @@ export default function swarm(pi: ExtensionAPI) {
         throw new Error(`Swarm ${activeRun.runId} is still running — wait or check swarm_status.`);
       }
 
+      // A gate is validated up front: a broken contract should be a tool error
+      // the caller can fix now, not a "verified nothing" verdict on every item
+      // after a whole fan-out has already been spent.
+      let gate: GateContract | undefined;
+      if (params.gate?.trim()) {
+        gate = normalizeGate(params.gate.trim());
+        const expect = params.gateExpect?.trim();
+        if (expect) {
+          try {
+            new RegExp(expect, "m");
+          } catch {
+            throw new Error(`gateExpect is not a valid regular expression: ${expect}`);
+          }
+          gate.expect = expect;
+        }
+      } else if (params.gateExpect?.trim()) {
+        throw new Error("gateExpect needs a gate command to judge.");
+      }
+
       runCounter++;
       const run: SwarmRun = {
         runId: `s${runCounter}`,
@@ -545,9 +777,44 @@ export default function swarm(pi: ExtensionAPI) {
         }
       }
 
+      const options: RunOptions = {
+        context: params.context ?? "",
+        fixed: params.agent,
+        isolate: params.isolation === "worktree",
+        useMailbox: params.mailbox === true,
+        gate,
+        gateRepairs: params.gateRepairs,
+        onUpstreamFailure: params.on_upstream_failure,
+      };
+
       if (run.background) {
-        void executeRun(uiCtx, run, params.context ?? "", params.agent, params.isolation === "worktree", params.mailbox === true)
+        // A background run's caller is off doing something else, so the first
+        // hard failure interrupts it the way @pify/subagent already interrupts
+        // for a failed background child. A foreground run is already blocking
+        // that turn, so there is nothing to interrupt.
+        options.onEarlyFailure = (item) => {
+          try {
+            pi.sendMessage(
+              {
+                customType: DELIVERY_TYPE,
+                content: earlyFailureNotice(run, item),
+                display: true,
+                details: { runId: run.runId, item: item.id, status: item.status },
+              },
+              { deliverAs: "steer", triggerTurn: true },
+            );
+          } catch {
+            // A warning that cannot be delivered must not take the run with it;
+            // the aggregate report is still coming.
+          }
+        };
+        void executeRun(uiCtx, run, options)
           .then(() => {
+            // A run the user just stopped is not one that "finished", and the
+            // model is not woken to fold in a report of work that was
+            // cancelled out from under it. The stop already said what it
+            // stopped; what the items produced is in swarm_status.
+            if (run.status === "cancelled") return;
             notify(uiCtx, `swarm ${run.runId} finished`, "info");
             // The report goes to the agent, not only to the screen — otherwise
             // asking again was its only way to find out.
@@ -571,14 +838,21 @@ export default function swarm(pi: ExtensionAPI) {
           });
         return {
           content: [
-            { type: "text", text: `Swarm ${run.runId} started (${run.items.length} items). Poll swarm_status runId="${run.runId}".` },
+            {
+              type: "text",
+              text:
+                `Swarm ${run.runId} started (${run.items.length} items) in the background. Its report is delivered to you ` +
+                `when it finishes, and the first hard failure interrupts you early — do not poll. ` +
+                `swarm_status runId="${run.runId}" shows progress if you need it early. ` +
+                `The user can stop it with /swarm stop ${run.runId} (Esc does not reach a background run).`,
+            },
           ],
           details: { runId: run.runId },
         };
       }
 
       try {
-        await executeRun(uiCtx, run, params.context ?? "", params.agent, params.isolation === "worktree", params.mailbox === true);
+        await executeRun(uiCtx, run, options);
       } finally {
         if (stopListening) stopListening();
       }
@@ -593,22 +867,47 @@ export default function swarm(pi: ExtensionAPI) {
     name: "swarm_status",
     label: "Swarm status",
     promptSnippet: "Progress of a running swarm",
-    description: "Progress of a swarm run (default: the latest). Returns the full report when finished.",
+    description:
+      "Progress of a swarm run (default: the latest). Returns the full report when finished. " +
+      "wait=N (seconds, up to 120) holds this call until the run finishes or N seconds pass, so a headless " +
+      "session can collect the report in one call instead of asking repeatedly.",
     parameters: Type.Object({
       runId: Type.Optional(Type.String()),
+      wait: Type.Optional(
+        Type.Number({
+          description: "Seconds to wait for the run to finish before answering, 0-120 (default 0)",
+          minimum: 0,
+          maximum: MAX_STATUS_WAIT_S,
+        }),
+      ),
     }),
-    async execute(_id, params: { runId?: string }) {
+    async execute(_id, params: { runId?: string; wait?: number }, signal, _onUpdate, ctx) {
       const run = params.runId ? runs.get(params.runId.trim()) : activeRun ?? [...runs.values()].pop();
       if (!run) throw new Error("No swarm runs this session.");
+      // Bounded and abortable: the wait is the caller's turn, and Esc must end
+      // it the way it ends anything else the tool call is doing.
+      const waitMs = Math.max(0, Math.min(MAX_STATUS_WAIT_S, params.wait ?? 0)) * 1000;
+      if (run.status === "running" && waitMs > 0) {
+        await waitUntil(() => run.status !== "running", waitMs, 250, signal);
+      }
       if (run.status === "running") {
+        const interactive = (ctx as { hasUI?: boolean }).hasUI !== false;
         const pending = pendingResult({
           id: run.runId,
           kind: "running",
           startedAt: run.startedAt,
           now: Date.now(),
           collectWith: "swarm_status",
+          // A headless `pi -p` run ends with this turn: "it will be delivered"
+          // is a promise nothing can keep there, so the text says to collect.
+          interactive,
         });
-        return { content: [{ type: "text", text: pending.text }], details: pending.details as never };
+        // Headless is where repeated calls actually happen; one call that
+        // waits is the same answer for one turn instead of several.
+        const text = interactive
+          ? pending.text
+          : `${pending.text}\nPass wait=${MAX_STATUS_WAIT_S} (seconds) to swarm_status to hold one call until it finishes instead of asking again.`;
+        return { content: [{ type: "text", text }], details: pending.details as never };
       }
       const text =
         run.status === "cancelled"
@@ -693,9 +992,33 @@ export default function swarm(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("swarm", {
-    description: "Show swarm runs and routing-capable agent types",
-    handler: async (_args, ctx) => {
+    description: "Show swarm runs and agent types; /swarm stop [runId] cancels a live run",
+    handler: async (args, ctx) => {
       if (!ctx.hasUI) return;
+      const words = (args ?? "").trim().split(/\s+/).filter(Boolean);
+      if (words[0] === "stop") {
+        // Esc reaches a foreground run through its tool call's signal; a
+        // background run's tool call returned long ago, so until this command
+        // nothing the user could do reached its children.
+        const wanted = words[1];
+        const run = wanted ? runs.get(wanted) : activeRun;
+        if (!run) {
+          ctx.ui.notify(wanted ? `No swarm run ${wanted}.` : "No swarm run to stop.", "warning");
+          return;
+        }
+        if (run.status !== "running") {
+          ctx.ui.notify(`swarm ${run.runId} is not running (${run.status}).`, "warning");
+          return;
+        }
+        const before = live.count(run.runId);
+        cancelRun(run, "user-abort");
+        ctx.ui.notify(
+          `swarm ${run.runId} stopped — ${before === 0 ? "no child agents were running" : `${before} child agent${before === 1 ? "" : "s"} stopped`}.`,
+          "info",
+        );
+        renderWidget(ctx);
+        return;
+      }
       const routed = [...defs.values()]
         .map((d) => {
           const rules = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/swarm",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Coordinate multiple pi agents in parallel: swarm_run fan-out with per-item auto-routing, concurrency queue, aggregated reports",
   "keywords": [
     "pi-package",

package/skills/swarm/SKILL.md

@@ -6,8 +6,10 @@ description: Use when work splits into several independent items that can run in
 # Swarm
 
 This project has the `@pify/swarm` extension installed: `swarm_run` fans a
-list of independent items out to parallel child agents (concurrency 4) and
-returns one aggregated report; `swarm_status` polls background runs.
+list of items out to parallel child agents (concurrency 4) and returns one
+aggregated report. A background run's report is delivered to you when it
+finishes, and the first hard failure interrupts you early — do not poll;
+`swarm_status` shows progress if you need it before then.
 
 ## When to fan out
 
@@ -15,9 +17,11 @@ returns one aggregated report; `swarm_status` polls background runs.
 - The same question asked across many places ("check each package for X").
 - Parallel research where items do not depend on each other.
 
-Do NOT use a swarm when items depend on each other's results (do them
-sequentially yourself) or for a single task (use agent_run from
-@pify/subagent instead).
+Items that depend on each other's results are fine: write them as
+`{task, id, needs: [ids]}` and each dependent receives its needs' output
+automatically, starting only once they finish. Set
+`on_upstream_failure: "skip"` when a dependent is pointless without its
+input. For a single task use agent_run from @pify/subagent instead.
 
 ## Slicing items
 
@@ -34,7 +38,17 @@ item) then `match_keywords`, falling back to the read-only scout. Force one
 type with `agent` when the routing does not fit. Mutating items must
 explicitly target `worker` — the fallback never mutates.
 
+## Verifying
+
+Give `gate` a command every item must pass (`bun test`, `tsc --noEmit`); it
+runs in each item's own working directory after the child finishes, a
+failure sends the child back once to fix it, and the report says what the
+check proved. Each item reports an outcome (succeeded / blocked / failed)
+separately from whether its child finished; the header counts outcomes.
+
 ## Collecting
 
-Blocking runs return the report directly. For `background: true`, ALWAYS
-collect with `swarm_status` before relying on any item's outcome.
+Blocking runs return the report directly. A `background: true` run delivers
+its report when it finishes — carry on with other work or end your turn; do
+not call `swarm_status` in a loop. In a headless run (no UI) nothing can be
+delivered after your turn ends, so collect with `swarm_status` within it.