@pify/swarm 0.9.2 → 0.10.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. A failing gate sends the child back once with the command, the verdict and the output, then re-runs; `gateRepairs: 0` turns that off. A read-only agent is never asked to repair.
+
+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`
 

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,10 @@ 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 } from "../src/gate.ts";
+import { runGateCycle } from "../src/repair.ts";
+import { deriveOutcome, parseDeclaredOutcome, stripDeclaration } from "../src/outcome.ts";
 import { routeItem } from "../src/routing.ts";
 import { normalizeItems } from "../src/graph.ts";
 import { runGraph } from "../src/schedule.ts";
@@ -62,6 +66,7 @@ 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";
@@ -349,14 +354,96 @@ export default function swarm(pi: ExtensionAPI) {
    * DEFAULT_CONCURRENCY at once. A flat run (no needs anywhere) makes every
    * item ready immediately, so this is identical to the old parallel pool.
    */
-  async function executeRun(
+  /** An agent that can write is one that can fix what a gate complained about. */
+  const canWrite = (def: AgentDef) =>
+    def.tools.some((t) => t === "edit" || t === "write" || t === "bash" || t === "powershell");
+
+  /**
+   * 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.
+   */
+  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> {
+    if (!opts.gate || item.status !== "done") return;
+    const subject = item.workDir ?? ctx.cwd;
+    const self: GateSibling = { id: item.index, label: item.id, status: item.status, workDir: item.workDir };
+    const siblings: GateSibling[] = run.items
+      .filter((i) => i.index !== item.index)
+      .map((i) => ({ id: i.index, label: i.id, status: i.status, workDir: i.workDir }));
+    try {
+      const { record, verification } = await runGateCycle(item.item, opts.gate, subject, {
+        runGate,
+        canRepair: canWrite(def),
+        maxAttempts: opts.gateRepairs ?? 1,
+        sharedWith: sharedWith(self, subject, siblings),
+        repair: async (prompt) => {
+          // The repair is the same child type over the same tree; its report
+          // replaces the stale one, which described a tree that has changed.
+          const fix: ItemState = { ...item, result: null, error: null, status: "queued", turns: 0 };
+          await runItem(ctx, run.runId, def, fix, prompt, item.workDir, undefined);
+          item.turns += fix.turns;
+          item.tokens += fix.tokens;
+          if (fix.status === "done" && fix.result?.trim()) item.result = fix.result;
+        },
+      });
+      item.gate = record;
+      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;
+    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.
@@ -375,6 +462,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 +481,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, opts);
               // 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 +514,9 @@ export default function swarm(pi: ExtensionAPI) {
             }
           } else {
             await runItem(ctx, run.runId, def, item, itemContext, undefined, mailbox);
+            await gateItem(ctx, run, item, def, opts);
           }
+          settle(item);
         },
         () => run.status === "cancelled",
       );
@@ -418,6 +533,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 +578,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 +603,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 +635,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 +657,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,8 +712,38 @@ 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(() => {
             notify(uiCtx, `swarm ${run.runId} finished`, "info");
             // The report goes to the agent, not only to the screen — otherwise
@@ -578,7 +775,7 @@ export default function swarm(pi: ExtensionAPI) {
       }
 
       try {
-        await executeRun(uiCtx, run, params.context ?? "", params.agent, params.isolation === "worktree", params.mailbox === true);
+        await executeRun(uiCtx, run, options);
       } finally {
         if (stopListening) stopListening();
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/swarm",
-  "version": "0.9.2",
+  "version": "0.10.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/src/gate.ts

@@ -0,0 +1,262 @@
+/**
+ * What a gate actually proved.
+ *
+ * A gate exists so a step is verified by running something rather than by a
+ * model saying it went well. Judging that run by its exit code alone leaves a
+ * hole big enough to drive a workflow through: a command that never ran the
+ * check still exits 0. A mistyped script name under `sh -c`, a test runner
+ * that matched no tests, a `|| true` someone left in — each one reports
+ * success while proving nothing.
+ *
+ * So a gate may state what success looks like. When it does, exiting 0
+ * without that evidence is its own outcome (`result_missing`) rather than a
+ * pass. The vocabulary is FradSer/pi-monitor's result contract.
+ *
+ * The same distinction runs one step further. A check that ran and said no is
+ * evidence; a check that could not run at all is *not evidence of anything*.
+ * A misspelled command, a runner that is not installed, a gate whose own regex
+ * does not compile — none of those are the code failing, and reporting them as
+ * `failure` sends the reader looking for a bug in the work instead of a typo
+ * in the gate. That case is `no_attestation`: still not a pass, but honest
+ * about having proved nothing either way.
+ */
+
+import { spawnSync } from "node:child_process";
+
+export type GateOutcome =
+  | "success"
+  | "failure"
+  | "result_missing"
+  | "timeout"
+  | "no_attestation";
+
+export interface GateContract {
+  /** The command to run. */
+  command: string;
+  /** Regex source: success requires a match in the combined output. */
+  expect?: string;
+  /** Regex source: a match means failure even when the command exits 0. */
+  failure?: string;
+  timeoutMs?: number;
+}
+
+export interface GateRun {
+  /** Exit status, or null when the process was killed (timeout/signal). */
+  status: number | null;
+  /** Signal that killed it, when one did. */
+  signal?: string | null;
+  output: string;
+  /** True when the runner stopped it at the timeout. */
+  timedOut?: boolean;
+  /**
+   * The command never became a process — it could not be spawned, the shell
+   * was missing, the working directory was gone. Not a verdict on the work.
+   */
+  spawnError?: string;
+}
+
+export interface GateVerdict {
+  outcome: GateOutcome;
+  ok: boolean;
+  /** One line for the run log, in this package's words. */
+  reason: string;
+}
+
+/** Accept a bare command string or a full contract. */
+export function normalizeGate(gate: string | GateContract): GateContract {
+  return typeof gate === "string" ? { command: gate } : gate;
+}
+
+function compile(source: string | undefined): RegExp | null {
+  if (!source) return null;
+  try {
+    return new RegExp(source, "m");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Judge a finished gate run. Order matters: a timeout is a timeout whatever
+ * else happened, an explicit failure pattern beats a zero exit, and a missing
+ * success pattern is never a pass.
+ */
+export function evaluateGate(contract: GateContract, run: GateRun): GateVerdict {
+  if (run.spawnError) {
+    return {
+      outcome: "no_attestation",
+      ok: false,
+      reason: `gate never ran (${run.spawnError}) — nothing was proved either way`,
+    };
+  }
+
+  // A timeout is a real verdict: the check was given its deadline and did not
+  // clear it. That is different from the case below.
+  if (run.timedOut || (run.status === null && run.signal)) {
+    return {
+      outcome: "timeout",
+      ok: false,
+      reason: `gate timed out after ${contract.timeoutMs ?? "the default"}ms`,
+    };
+  }
+
+  // Neither an exit code nor a signal: the process did not run to a verdict
+  // and nothing killed it, so there is no result to report as one.
+  if (run.status === null) {
+    return {
+      outcome: "no_attestation",
+      ok: false,
+      reason: "gate produced no exit status — nothing was proved either way",
+    };
+  }
+
+  const failurePattern = compile(contract.failure);
+  if (failurePattern && failurePattern.test(run.output)) {
+    return {
+      outcome: "failure",
+      ok: false,
+      reason: `gate output matched its failure pattern /${contract.failure}/`,
+    };
+  }
+
+  if (run.status !== 0) {
+    return { outcome: "failure", ok: false, reason: `gate exited ${run.status}` };
+  }
+
+  const expectPattern = compile(contract.expect);
+  if (expectPattern && !expectPattern.test(run.output)) {
+    // The hole this closes: the command ran, said nothing that proves the
+    // check happened, and exited 0.
+    return {
+      outcome: "result_missing",
+      ok: false,
+      reason: `gate exited 0 but its output never matched /${contract.expect}/ — nothing was verified`,
+    };
+  }
+
+  return {
+    outcome: "success",
+    ok: true,
+    reason: expectPattern ? `gate passed and matched /${contract.expect}/` : "gate exited 0",
+  };
+}
+
+/** The part of a call a gate needs in order to know who else was in the room. */
+export interface GateSibling {
+  id: number;
+  label: string;
+  status: string;
+  workDir?: string;
+}
+
+/**
+ * Which other calls were live in the same working directory while this gate
+ * ran — the ones that make its verdict unattributable.
+ *
+ * Only concurrency in the *same* directory counts. Two agents under
+ * `isolation: "worktree"` have their own checkouts and cannot disturb each
+ * other, which is exactly why isolation is the fix rather than a warning.
+ */
+export function sharedWith(
+  self: GateSibling,
+  subject: string,
+  siblings: readonly GateSibling[],
+): string[] {
+  return siblings
+    .filter((s) => s.id !== self.id && s.status === "running" && (s.workDir ?? subject) === subject)
+    .map((s) => s.label);
+}
+
+/**
+ * One line saying what a verdict is worth, given who else was editing.
+ * A pass earned over a tree two other agents were changing is reported as what
+ * it is: true of the tree, not of this agent's work.
+ */
+export function attributionNote(record: {
+  ok: boolean;
+  sharedWith: readonly string[];
+}): string | null {
+  if (record.sharedWith.length === 0) return null;
+  const others = record.sharedWith.join(", ");
+  return record.ok
+    ? `judged a directory ${others} ${record.sharedWith.length === 1 ? "was" : "were"} also changing — true of the tree, not of this agent's work alone`
+    : `judged a directory ${others} ${record.sharedWith.length === 1 ? "was" : "were"} also changing — the cause may not be this agent's work`;
+}
+
+/** An unparseable pattern is a broken contract, not a passing one. */
+export function contractProblems(contract: GateContract): string[] {
+  const problems: string[] = [];
+  if (!contract.command.trim()) problems.push("gate has no command");
+  for (const [field, source] of [
+    ["expect", contract.expect],
+    ["failure", contract.failure],
+  ] as const) {
+    if (source && !compile(source)) problems.push(`gate ${field} is not a valid regular expression`);
+  }
+  if (contract.timeoutMs !== undefined && !(contract.timeoutMs > 0)) {
+    problems.push("gate timeoutMs must be positive");
+  }
+  return problems;
+}
+
+/** How long a gate may run before the deadline is its verdict. */
+export const GATE_TIMEOUT_MS = 120_000;
+
+/**
+ * Run a gate and judge it against its contract, with the shell in the subject
+ * working directory. A bare string keeps the exit-code meaning; a contract can
+ * also say what success has to look like, which is what stops a command that
+ * never ran the check from passing.
+ *
+ * The command comes from the caller — the same trust level as the bash tool in
+ * this session — so this adds no capability the caller did not already have.
+ */
+export function runGate(gate: string | GateContract, cwd: string): GateVerdict & { output: string } {
+  const contract = normalizeGate(gate);
+  const problems = contractProblems(contract);
+  if (problems.length > 0) {
+    // A gate that cannot be run is not a verdict on the work. Calling this a
+    // failure would report a typo in the gate as a defect in the code.
+    return { outcome: "no_attestation", ok: false, reason: problems.join("; "), output: "" };
+  }
+  const timeoutMs = contract.timeoutMs ?? GATE_TIMEOUT_MS;
+  try {
+    const result = spawnSync(contract.command, {
+      shell: true,
+      cwd,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      windowsHide: true,
+      // A real test suite or build easily prints past spawnSync's 1 MiB
+      // default; overflow surfaces as an ENOBUFS `error`, which this code
+      // would otherwise read as spawnError → no_attestation, rejecting work
+      // that in fact passed. Give the gate room to actually report.
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    const verdict = evaluateGate(
+      { ...contract, timeoutMs },
+      {
+        status: result.status,
+        signal: result.signal,
+        output,
+        timedOut: result.error?.message?.includes("ETIMEDOUT") || result.signal === "SIGTERM",
+        // spawnSync reports a failure to start in `error` rather than by
+        // throwing, and a timeout arrives the same way — so the timeout has to
+        // be ruled out first or every deadline would read as "never ran".
+        spawnError:
+          result.error && !result.error.message?.includes("ETIMEDOUT")
+            ? result.error.message
+            : undefined,
+      },
+    );
+    return { ...verdict, output };
+  } catch (err) {
+    return {
+      outcome: "no_attestation",
+      ok: false,
+      reason: `gate could not be started: ${err instanceof Error ? err.message : String(err)}`,
+      output: "",
+    };
+  }
+}

package/src/outcome.ts

@@ -0,0 +1,94 @@
+/**
+ * "It finished" and "it worked" are different facts.
+ *
+ * RunStatus answers the first one: did the child session run to the end, error
+ * out, or get stopped. It says nothing about whether the task was actually
+ * accomplished, so a child that hits its brief's wall at turn three and writes
+ * a polite report explaining why is recorded exactly like one that shipped the
+ * feature — `done`. The caller then has to read prose to find out which.
+ *
+ * So record the task outcome separately, and record *how well it is known*
+ * separately again. A gate that ran and failed is evidence and overrides a
+ * child's claim of success. A gate that could not run, or that exited 0 without
+ * proving anything, is not evidence of failure either — reporting it as one
+ * would blame the work for a typo in the gate. That case leaves the outcome
+ * alone and says the verification was inconclusive.
+ *
+ * Pure and dependency-free: every rule here is a function of facts the
+ * extension already has.
+ */
+
+import type { GateOutcome } from "./gate.ts";
+
+/** What the delegated task actually came to. */
+export type TaskOutcome = "succeeded" | "blocked" | "failed";
+
+/** How well that outcome is known. Orthogonal to the outcome itself. */
+export type Verification = "not-requested" | "passed" | "failed" | "inconclusive";
+
+/** The marker a child may end its report with to declare its own outcome. */
+const DECLARATION = /^\s*outcome:\s*(succeeded|blocked|failed)\s*$/gim;
+
+/**
+ * Read a child's self-declared outcome, if it made one. Last declaration wins:
+ * a report that revises itself means the later line.
+ *
+ * This is a *claim*, not evidence — the value is that it is parseable, and that
+ * a blocked child can say so in one place instead of burying it in prose.
+ * Absent or unparseable means "no claim", never a failure.
+ */
+export function parseDeclaredOutcome(text: string | null | undefined): TaskOutcome | undefined {
+  if (!text) return undefined;
+  let found: TaskOutcome | undefined;
+  DECLARATION.lastIndex = 0;
+  for (const m of text.matchAll(DECLARATION)) found = m[1]!.toLowerCase() as TaskOutcome;
+  return found;
+}
+
+/** Strip the declaration line so it does not also show up in the report body. */
+export function stripDeclaration(text: string): string {
+  return text.replace(DECLARATION, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+/** What a finished gate proved about the work, in verification terms. */
+export function gateVerification(outcome: GateOutcome): Verification {
+  if (outcome === "success") return "passed";
+  if (outcome === "failure" || outcome === "timeout") return "failed";
+  // result_missing and no_attestation both mean the gate settled without
+  // establishing anything — not a verdict against the work.
+  return "inconclusive";
+}
+
+export interface OutcomeInput {
+  /** Lifecycle: did the session itself run to the end? */
+  status: "running" | "done" | "error" | "aborted";
+  /** The child's own claim, when it made one. */
+  declared?: TaskOutcome;
+  /** What the gate proved, when one ran. */
+  verification?: Verification;
+}
+
+/**
+ * Settle the task outcome from the facts, most authoritative first:
+ * a session that did not finish cannot have succeeded; a gate that failed
+ * outranks any claim; then the child's own claim; then success by default.
+ */
+export function deriveOutcome(input: OutcomeInput): TaskOutcome {
+  if (input.status !== "done") return "failed";
+  if (input.verification === "failed") return "failed";
+  if (input.declared) return input.declared;
+  return "succeeded";
+}
+
+/** One line for the report, naming both facts. */
+export function outcomeLine(outcome: TaskOutcome, verification: Verification): string {
+  const how =
+    verification === "not-requested"
+      ? "no gate was requested, so this is the agent's own account"
+      : verification === "passed"
+        ? "a gate ran and passed"
+        : verification === "failed"
+          ? "a gate ran and failed"
+          : "a gate ran but proved nothing either way";
+  return `[outcome] ${outcome} — ${how}`;
+}

package/src/repair.ts

@@ -0,0 +1,104 @@
+/**
+ * Verification a model cannot talk its way past.
+ *
+ * `verify` asks a reviewer agent whether the work is good; that is a second
+ * opinion, and it defaults to PASS when the reply is unclear because a mangled
+ * review must not block a good result. A gate is the other kind of check: a
+ * command runs in the tree the child actually worked in, and its exit status
+ * and output are facts. The suite already had this — in @pify/workflow, where
+ * only a workflow script could reach it — while agent_run, the tool where
+ * children actually edit code, had nothing but the reviewer.
+ *
+ * A failed gate then gets one thing a workflow step does not: the child is
+ * still there, so it can be sent back with the failure and the gate re-run.
+ * Bounded, because an agent that cannot fix a build in two tries will not fix
+ * it in ten, and each attempt costs a full child run.
+ *
+ * Pure orchestration with injected seams, like verify.ts: the gate runner and
+ * the repair spawn are both parameters, so the whole cycle is testable without
+ * a shell or a live session.
+ */
+
+import type { GateContract, GateOutcome, GateVerdict } from "./gate.ts";
+import { gateVerification, type Verification } from "./outcome.ts";
+import type { GateRecord } from "./types.ts";
+
+/** The brief for a repair pass: the check, what it said, nothing else. */
+export function repairPrompt(
+  task: string,
+  contract: GateContract,
+  verdict: { reason: string; output: string },
+): string {
+  const output = verdict.output.trim();
+  return [
+    "Your work did not pass its verification check. Fix the cause and stop — do not change anything the",
+    "check did not complain about, and do not modify the check itself to make it pass.",
+    "",
+    "== Original task ==",
+    task.trim(),
+    "",
+    `== Check ==\n${contract.command}`,
+    "",
+    `== Verdict ==\n${verdict.reason}`,
+    ...(output ? ["", `== Output ==\n${output.length > 4000 ? `…\n${output.slice(-4000)}` : output}`] : []),
+    "",
+    "When you are done, report exactly what you changed and why it fixes the check.",
+  ].join("\n");
+}
+
+export interface GateCycleDeps {
+  /** Run the gate in `cwd` and judge it (src/gate.ts runGate). */
+  runGate(contract: GateContract, cwd: string): GateVerdict & { output: string };
+  /** Send the child back with a repair brief; resolves when that pass settles. */
+  repair(prompt: string): Promise<void>;
+  /**
+   * Can this agent change anything? A read-only agent handed a failing gate can
+   * only re-report it, so asking it to repair burns a child run to no purpose.
+   */
+  canRepair: boolean;
+  /** Repair passes allowed before the failure stands (0 disables). */
+  maxAttempts: number;
+  /** Other runs live in the same directory while the gate ran. */
+  sharedWith?: string[];
+}
+
+/**
+ * A repair is only worth spawning when the gate actually judged the work.
+ * `no_attestation` means the gate never produced a verdict — a missing runner,
+ * a typo, an unparseable pattern — and sending a child to fix a defect that was
+ * never demonstrated is how an agent ends up "fixing" working code.
+ */
+export function repairable(outcome: GateOutcome): boolean {
+  return outcome === "failure" || outcome === "result_missing" || outcome === "timeout";
+}
+
+/** Run the gate, repair once (or `maxAttempts` times) if it failed, re-run. */
+export async function runGateCycle(
+  task: string,
+  contract: GateContract,
+  cwd: string,
+  deps: GateCycleDeps,
+): Promise<{ record: GateRecord; verification: Verification }> {
+  let verdict = deps.runGate(contract, cwd);
+  let repairs = 0;
+  const limit = Math.max(0, Math.min(5, deps.maxAttempts));
+
+  while (!verdict.ok && deps.canRepair && repairs < limit && repairable(verdict.outcome)) {
+    await deps.repair(repairPrompt(task, contract, verdict));
+    repairs++;
+    verdict = deps.runGate(contract, cwd);
+  }
+
+  const record: GateRecord = {
+    command: contract.command,
+    outcome: verdict.outcome,
+    ok: verdict.ok,
+    reason: verdict.reason,
+    // A passing gate's output is noise in the caller's context; a failing one's
+    // is the whole point.
+    ...(verdict.ok ? {} : { output: verdict.output }),
+    ...(deps.sharedWith?.length ? { sharedWith: [...deps.sharedWith] } : {}),
+    ...(repairs > 0 ? { repairs } : {}),
+  };
+  return { record, verification: gateVerification(verdict.outcome) };
+}

package/src/report.ts

@@ -1,20 +1,70 @@
-import type { SwarmRun } from "./types.ts";
+import { outcomeLine } from "./outcome.ts";
+import type { ItemState, SwarmRun } from "./types.ts";
 
-/** Aggregated report returned to the parent model when a run finishes. */
+/** Longest gate output kept per item; a failing suite prints books. */
+const GATE_TAIL = 1200;
+
+/**
+ * What the gate proved about one item. Shown whenever a gate ran — a pass is as
+ * much a fact as a failure, and silence would make "verified" and "never
+ * checked" look identical.
+ */
+function gateLines(item: ItemState): string[] {
+  const gate = item.gate;
+  if (!gate) return [];
+  const lines = [`[gate] ${gate.outcome} — ${gate.reason} (\`${gate.command}\`)`];
+  if (gate.repairs) {
+    lines.push(`  repaired ${gate.repairs} time${gate.repairs === 1 ? "" : "s"} and re-run.`);
+  }
+  if (gate.sharedWith?.length) {
+    lines.push(
+      `  ${gate.sharedWith.join(", ")} ${gate.sharedWith.length === 1 ? "was" : "were"} also changing this directory — the verdict is true of the tree, not of this item's work alone.`,
+    );
+  }
+  if (!gate.ok && gate.output) {
+    const tail = gate.output.length > GATE_TAIL ? `…\n${gate.output.slice(-GATE_TAIL)}` : gate.output;
+    lines.push(tail.replace(/^/gm, "  "));
+  }
+  return lines;
+}
+
+function verdict(item: ItemState): string {
+  const parts = gateLines(item);
+  if (item.outcome) parts.push(outcomeLine(item.outcome, item.verification ?? "not-requested"));
+  return parts.length > 0 ? `\n\n${parts.join("\n")}` : "";
+}
+
+/**
+ * Aggregated report returned to the parent model when a run finishes.
+ *
+ * The header counts *outcomes*, not statuses. An item whose child ran to the
+ * end and then failed its gate is not something the caller wants filed under
+ * "done" — that is the whole reason the two are recorded separately.
+ */
 export function buildReport(run: SwarmRun): string {
-  const counts = { done: 0, error: 0, aborted: 0 };
+  const counts = { succeeded: 0, blocked: 0, failed: 0, skipped: 0 };
   for (const item of run.items) {
-    if (item.status === "done") counts.done++;
-    else if (item.status === "error") counts.error++;
-    else if (item.status === "aborted") counts.aborted++;
+    if (item.status === "skipped") counts.skipped++;
+    else if (item.outcome) counts[item.outcome]++;
+    else if (item.status === "done") counts.succeeded++;
+    else counts.failed++;
   }
+  const tally = [
+    `${counts.succeeded} succeeded`,
+    ...(counts.blocked ? [`${counts.blocked} blocked`] : []),
+    `${counts.failed} failed`,
+    ...(counts.skipped ? [`${counts.skipped} skipped`] : []),
+  ].join(", ");
 
-  const header = `[swarm ${run.runId}] ${run.items.length} items — ${counts.done} done, ${counts.error} error, ${counts.aborted} aborted`;
+  const header = `[swarm ${run.runId}] ${run.items.length} items — ${tally}`;
 
   const sections = run.items.map((item) => {
     const label = `### ${item.index + 1}. [${item.agent}] ${item.item}`;
-    if (item.status === "done") return `${label}\n${item.result ?? "(empty report)"}`;
-    if (item.status === "error") return `${label}\nError: ${item.error ?? "unknown"}`;
+    if (item.status === "done") return `${label}\n${item.result ?? "(empty report)"}${verdict(item)}`;
+    if (item.status === "error") return `${label}\nError: ${item.error ?? "unknown"}${verdict(item)}`;
+    if (item.status === "skipped") {
+      return `${label}\nSkipped — ${item.error ?? "something it needed did not succeed"}. Nothing ran, so nothing was spent on it.`;
+    }
     if (item.status === "aborted") {
       return `${label}\nAborted (turn cap or stop). Partial:\n${item.result ?? "(none)"}`;
     }
@@ -31,3 +81,21 @@ export function buildStatusLine(run: SwarmRun): string {
   );
   return `[swarm ${run.runId}] ${run.status} — ${parts.join(" · ")}`;
 }
+
+/**
+ * The interrupt for an item that failed while the rest of the run is still
+ * going. @pify/subagent already treats a failed background child as a steer
+ * rather than a polite follow-up — a broken intermediate the caller is likely
+ * building on should arrive now, not after the remaining items finish. This is
+ * the same rule for a swarm: one wake, for the first hard failure only.
+ */
+export function earlyFailureNotice(run: SwarmRun, item: ItemState): string {
+  const reason = item.gate && !item.gate.ok ? item.gate.reason : (item.error ?? "unknown failure");
+  const pending = run.items.filter((i) => i.status === "queued" || i.status === "running").length;
+  return [
+    `[swarm ${run.runId}] item ${item.index + 1} (${item.id}, ${item.agent}) failed: ${reason}`,
+    pending > 0
+      ? `${pending} item${pending === 1 ? " is" : "s are"} still running and the full report follows when they settle — this is a warning, not the result. Do not build on this item's output, and do not poll swarm_status.`
+      : "The full report follows.",
+  ].join("\n");
+}

package/src/types.ts

@@ -3,6 +3,9 @@
  * No imports from pi packages: src/ typechecks and runs standalone.
  */
 
+import type { GateOutcome } from "./gate.ts";
+import type { TaskOutcome, Verification } from "./outcome.ts";
+
 export const VALID_TOOLS = [
   "read",
   "bash",
@@ -48,7 +51,27 @@ export const DEFAULT_CONCURRENCY = 4;
 /** Safe default when no routing rule matches: read-only exploration. */
 export const FALLBACK_AGENT = "scout";
 
-export type ItemStatus = "queued" | "running" | "done" | "error" | "aborted";
+/**
+ * "skipped" is a settled state, not a failure: the item never ran because
+ * something it needed did not produce usable input, and the caller asked for
+ * that to stop the branch rather than feed it a failure notice.
+ */
+export type ItemStatus = "queued" | "running" | "done" | "error" | "aborted" | "skipped";
+
+/** What a gate proved about one item, kept alongside the item it judged. */
+export interface GateRecord {
+  command: string;
+  outcome: GateOutcome;
+  ok: boolean;
+  /** One line in this package's words. */
+  reason: string;
+  /** Trimmed output, kept only when the gate did not pass. */
+  output?: string;
+  /** Other items that were live in the same directory while it ran. */
+  sharedWith?: string[];
+  /** Repair passes spent trying to make it pass. */
+  repairs?: number;
+}
 
 export interface ItemState {
   index: number;
@@ -63,8 +86,18 @@ export interface ItemState {
   tokens: number;
   result: string | null;
   error: string | null;
+  /** The directory the child worked in — its worktree when isolated. */
+  workDir?: string;
+  /** Set once the item settles: what the task came to, apart from whether the child finished. */
+  outcome?: TaskOutcome;
+  /** How well that outcome is known. "not-requested" when no gate ran. */
+  verification?: Verification;
+  gate?: GateRecord;
 }
 
+/** How a dependent behaves when something it needs did not succeed. */
+export type UpstreamFailurePolicy = "continue" | "skip";
+
 /**
  * "cancelled" is its own outcome, not a completion: someone stopped the run,
  * and calling it done would report results nobody produced.

package/src/widget.ts

@@ -1,16 +1,23 @@
 import { clampRows, clampWidth, MAX_WIDGET_ROWS } from "./widget-clamp.ts";
-import type { SwarmRun, ThemeLike } from "./types.ts";
+import type { ItemState, SwarmRun, ThemeLike } from "./types.ts";
 
 const WIDTH = 54;
 
-function icon(status: string): string {
-  switch (status) {
+/**
+ * The row reports the *task*, not the child session. An item whose agent ran to
+ * the end and then failed its gate used to sit here as a green ✓, which is
+ * precisely the confusion the outcome field exists to remove.
+ */
+function icon(item: ItemState): string {
+  switch (item.status) {
     case "queued":
       return "·";
     case "running":
       return "⟳";
+    case "skipped":
+      return "⊘";
     case "done":
-      return "✓";
+      return item.outcome === "failed" ? "✗" : item.outcome === "blocked" ? "⚠" : "✓";
     case "error":
       return "✗";
     default:
@@ -18,6 +25,17 @@ function icon(status: string): string {
   }
 }
 
+type Tone = "dim" | "warning" | "success" | "error";
+
+function tone(item: ItemState): Tone {
+  if (item.status === "queued" || item.status === "skipped") return "dim";
+  if (item.status === "running") return "warning";
+  if (item.status !== "done") return "error";
+  if (item.outcome === "failed") return "error";
+  if (item.outcome === "blocked") return "warning";
+  return "success";
+}
+
 /** Widget above the editor for the active (or just-finished) run. */
 export function buildWidgetLines(run: SwarmRun | null, theme: ThemeLike, now: number): string[] {
   if (!run) return [];
@@ -33,15 +51,9 @@ export function buildWidgetLines(run: SwarmRun | null, theme: ThemeLike, now: nu
   // Cap the rows: a large swarm would otherwise push the editor off screen,
   // since a Text-factory widget bypasses pi's ten-line guard.
   const rows = run.items.map((item) => {
-    const paint =
-      item.status === "running"
-        ? (s: string) => theme.fg("warning", s)
-        : item.status === "done"
-          ? (s: string) => theme.fg("success", s)
-          : item.status === "queued"
-            ? dim
-            : (s: string) => theme.fg("error", s);
-    return `${dim("│ ")}${paint(`${icon(item.status)} ${clampWidth(item.agent, 24)}`)}${dim(` ${clampWidth(item.item, 32)}`)}`;
+    const color = tone(item);
+    const paint = (s: string) => theme.fg(color, s);
+    return `${dim("│ ")}${paint(`${icon(item)} ${clampWidth(item.agent, 24)}`)}${dim(` ${clampWidth(item.item, 32)}`)}`;
   });
   for (const row of clampRows(rows, MAX_WIDGET_ROWS, (hidden) => dim(`│ … +${hidden} more`))) {
     lines.push(row);