@pify/swarm 0.10.0 → 0.11.0

package/README.md

@@ -33,7 +33,7 @@ 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.
+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.
 
@@ -66,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`
 
@@ -98,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

@@ -52,9 +52,18 @@ import {
 } from "../src/mailbox.ts";
 import { parseAgentFile } from "../src/frontmatter.ts";
 import { buildReport, buildStatusLine, earlyFailureNotice } from "../src/report.ts";
-import { normalizeGate, runGate, sharedWith, type GateContract, type GateSibling } from "../src/gate.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";
@@ -72,6 +81,8 @@ import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "no
 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.";
 
@@ -196,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;
@@ -233,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)] : []),
         ],
       });
@@ -251,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();
@@ -349,15 +379,6 @@ 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.
-   */
-  /** 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
@@ -393,29 +414,70 @@ export default function swarm(pi: ExtensionAPI) {
     def: AgentDef,
     opts: RunOptions,
   ): Promise<void> {
-    if (!opts.gate || item.status !== "done") return;
+    // 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;
-    const self: GateSibling = { id: item.index, label: item.id, status: item.status, workDir: item.workDir };
+    // 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: i.workDir }));
+      .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,
-        canRepair: canWrite(def),
+        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) => {
-          // The repair is the same child type over the same tree; its report
+          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, result: null, error: null, status: "queued", turns: 0 };
-          await runItem(ctx, run.runId, def, fix, prompt, item.workDir, undefined);
+          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;
         },
       });
-      item.gate = record;
+      // 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
@@ -437,6 +499,8 @@ export default function swarm(pi: ExtensionAPI) {
     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;
@@ -450,6 +514,7 @@ export default function swarm(pi: ExtensionAPI) {
     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.
@@ -501,7 +566,7 @@ export default function swarm(pi: ExtensionAPI) {
               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);
+              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);
@@ -514,7 +579,7 @@ export default function swarm(pi: ExtensionAPI) {
             }
           } else {
             await runItem(ctx, run.runId, def, item, itemContext, undefined, mailbox);
-            await gateItem(ctx, run, item, def, opts);
+            await gateItem(ctx, run, item, def, gateOpts);
           }
           settle(item);
         },
@@ -745,6 +810,11 @@ export default function swarm(pi: ExtensionAPI) {
         };
         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.
@@ -768,7 +838,14 @@ 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 },
         };
@@ -790,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"
@@ -890,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.10.0",
+  "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.

package/src/builtin.ts

@@ -16,8 +16,18 @@ You are a disciplined review subagent. Inspect, evaluate, and report findings
 with evidence — never guess; verify from the code itself. You cannot modify
 anything: your deliverable is the report.
 
-For each finding give: file:line, what is wrong, why it matters, and a
-concrete suggestion. Rank findings by severity. If the code is fine, say so
+Flag only defects you can prove: a concrete, introduced problem with a real
+impact you can name — a bug, a broken contract, data loss, a security hole. Do
+not report style, taste, or hypotheticals; "could theoretically" is not a
+finding. Weight the review on:
+ - correctness: logic errors, wrong edge cases, broken or unhandled contracts;
+ - untrusted input reaching a dangerous sink: SQL/command injection, path
+   traversal, SSRF, open redirect, unsafe deserialization, missing authz;
+ - clean code, but only where it bites: needless duplication, dead code, an
+   abstraction that hides a real bug — never mere preference.
+
+For each finding give: file:line, what is wrong, why it matters (the concrete
+impact), and a concrete fix. Rank by severity. If the code is sound, say so
 plainly — do not invent issues. End with a one-paragraph verdict.`,
 
   scout: `---

package/src/frontmatter.ts

@@ -33,11 +33,13 @@ export function parseAgentFile(
 
   const thinkingRaw = fields.get("thinking")?.toLowerCase();
   const maxTurnsRaw = Number.parseInt(fields.get("max_turns") ?? "", 10);
+  const tools = parseTools(fields.get("tools"));
+  if (tools === null) return null;
 
   return {
     name: name.toLowerCase(),
     description,
-    tools: parseTools(fields.get("tools")),
+    tools,
     model: fields.get("model") || null,
     thinking: (THINKING_LEVELS as readonly string[]).includes(thinkingRaw ?? "")
       ? (thinkingRaw as ThinkingLevelName)
@@ -64,11 +66,20 @@ function parseList(raw: string | undefined): string[] {
     .filter(Boolean);
 }
 
-function parseTools(raw: string | undefined): ValidTool[] {
+/**
+ * Read-only default keeps a def missing `tools:` from mutating anything.
+ * A `tools:` line where NOTHING resolves is different: the author asked for
+ * a specific tool set and got the read-only default instead, so the agent
+ * runs with a contract nobody wrote. That is rejected — the file is dropped,
+ * rather than quietly running as something else. (Same rule as @pify/subagent.)
+ */
+function parseTools(raw: string | undefined): ValidTool[] | null {
   if (!raw) return ["read", "grep", "find", "ls"];
-  const valid = raw
+  const requested = raw
     .split(",")
     .map((t) => t.trim().toLowerCase())
-    .filter((t): t is ValidTool => (VALID_TOOLS as readonly string[]).includes(t));
-  return valid.length > 0 ? valid : ["read", "grep", "find", "ls"];
+    .filter(Boolean);
+  if (requested.length === 0) return ["read", "grep", "find", "ls"];
+  const valid = requested.filter((t): t is ValidTool => (VALID_TOOLS as readonly string[]).includes(t));
+  return valid.length > 0 ? valid : null;
 }

package/src/gate.ts

@@ -21,7 +21,7 @@
  * about having proved nothing either way.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 
 export type GateOutcome =
   | "success"
@@ -202,61 +202,150 @@ export function contractProblems(contract: GateContract): string[] {
 /** How long a gate may run before the deadline is its verdict. */
 export const GATE_TIMEOUT_MS = 120_000;
 
+/**
+ * Output kept from a gate. A real suite prints books; the verdict is at the
+ * end, so it is the tail that is kept when a gate prints past this.
+ */
+const GATE_MAX_OUTPUT = 16 * 1024 * 1024;
+
 /**
  * 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.
  *
+ * Asynchronous, and that is load-bearing. A gate is a test suite or a build,
+ * and the first version ran it with spawnSync — which held pi's whole event
+ * loop for the duration: nothing rendered, Esc could not be delivered, and
+ * every other child's provider stream sat unread until the gate returned,
+ * up to the full deadline. The deadline is enforced here (the shell is
+ * killed on timeout) and output is capped rather than erroring, so a
+ * chatty-but-passing gate still passes.
+ *
  * 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 } {
+export function runGate(gate: string | GateContract, cwd: string): Promise<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: "" };
+    return Promise.resolve({ 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,
+
+  return new Promise((resolve) => {
+    let child: ChildProcess;
+    try {
+      child = spawn(contract.command, {
+        shell: true,
+        cwd,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        // POSIX: lead a process group, so a timeout can kill the whole tree
+        // and not just the shell that started it.
+        detached: process.platform !== "win32",
+      });
+    } catch (err) {
+      resolve({
+        outcome: "no_attestation",
+        ok: false,
+        reason: `gate could not be started: ${err instanceof Error ? err.message : String(err)}`,
+        output: "",
+      });
+      return;
+    }
+
+    // stdout and stderr in arrival order — how a person would have read the
+    // terminal — trimmed from the front once past the cap.
+    const chunks: Buffer[] = [];
+    let size = 0;
+    const keep = (chunk: Buffer): void => {
+      chunks.push(chunk);
+      size += chunk.length;
+      while (size > GATE_MAX_OUTPUT && chunks.length > 1) size -= chunks.shift()!.length;
+    };
+    child.stdout?.on("data", keep);
+    child.stderr?.on("data", keep);
+
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree(child);
+    }, timeoutMs);
+
+    let settled = false;
+    let exited: { status: number | null; signal: string | null } | null = null;
+    const finish = (spawnError?: string): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      const output = Buffer.concat(chunks).toString("utf8").trim();
+      resolve({
+        ...evaluateGate(
+          { ...contract, timeoutMs },
+          { status: exited?.status ?? null, signal: exited?.signal ?? null, output, timedOut, spawnError },
+        ),
         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: "",
+      });
     };
+    // A failure to start arrives as an event, not a throw. After a timeout
+    // kill, an error is the kill's doing, not a spawn failure.
+    child.on("error", (err) => {
+      exited ??= { status: null, signal: null };
+      finish(timedOut ? undefined : err.message);
+    });
+    // `close` waits for the pipes, which a grandchild that outlived the shell
+    // can hold open indefinitely; `exit` is the shell's own verdict. Wait for
+    // the pipes briefly so a normal exit keeps all of its output, then finish
+    // regardless — a gate must never hang a run past its deadline.
+    child.on("close", (status, signal) => {
+      exited ??= { status, signal };
+      finish();
+    });
+    child.on("exit", (status, signal) => {
+      exited = { status, signal };
+      const grace = setTimeout(() => finish(), EXIT_DRAIN_MS);
+      grace.unref?.();
+    });
+  });
+}
+
+/** How long to wait for a gate's pipes after its shell has exited. */
+const EXIT_DRAIN_MS = 500;
+
+/**
+ * Kill a gate's whole process tree. The shell alone dying leaves the test
+ * suite it started running — on Windows `child.kill()` reaches only cmd.exe,
+ * and on POSIX only the shell — so a deadline that merely killed the shell
+ * would report a timeout while the suite ran on, holding the pipes open.
+ */
+function killTree(child: ChildProcess): void {
+  const pid = child.pid;
+  if (pid === undefined) return;
+  if (process.platform === "win32") {
+    // By absolute path: PATH is the user's, and a gate has run under odd ones.
+    const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+    try {
+      spawn(taskkill, ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" }).on("error", () => {});
+    } catch {
+      // taskkill unavailable: the plain kill below is all that is left
+    }
+    try {
+      child.kill();
+    } catch {
+      // already gone
+    }
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // already gone
+    }
   }
 }

package/src/isolate.ts

@@ -33,7 +33,12 @@ export function sanitizeSlug(raw: string): string {
   return slug || "run";
 }
 
-export function createIsolationWorktree(cwd: string, rawSlug: string): Isolation {
+/** Where isolation worktrees live by default: ~/.worktrees. */
+export function defaultWorktreeRoot(): string {
+  return join(homedir(), ".worktrees");
+}
+
+export function createIsolationWorktree(cwd: string, rawSlug: string, root: string = defaultWorktreeRoot()): Isolation {
   let toplevel: string;
   try {
     toplevel = git(cwd, ["rev-parse", "--show-toplevel"]);
@@ -44,11 +49,11 @@ export function createIsolationWorktree(cwd: string, rawSlug: string): Isolation
   const slug = sanitizeSlug(rawSlug);
 
   let branch = `agent/${slug}`;
-  let path = join(homedir(), ".worktrees", repo, slug);
+  let path = join(root, repo, slug);
   let counter = 2;
   while (existsSync(path) || branchExists(cwd, branch)) {
     branch = `agent/${slug}-${counter}`;
-    path = join(homedir(), ".worktrees", repo, `${slug}-${counter}`);
+    path = join(root, repo, `${slug}-${counter}`);
     counter++;
     if (counter > 50) throw new Error("Could not find a free worktree slot.");
   }
@@ -71,15 +76,70 @@ function branchExists(cwd: string, branch: string): boolean {
   }
 }
 
-/** Note appended to a child's report when it ran isolated. */
+/**
+ * Note appended to a child's report when it ran isolated and left work
+ * behind. That work is UNCOMMITTED unless the child chose to commit — the
+ * builtin worker never does — and @pify/worktree's worktree_merge refuses a
+ * dirty tree, so the old note ("merge with worktree_merge") sent the model to
+ * a tool that would turn it away. Say what state the tree is in and what to
+ * do about it.
+ */
 export function isolationNote(isolation: Isolation): string {
+  const at = `git -C "${isolation.path}"`;
   return [
-    `Ran isolated in worktree ${isolation.path} (branch ${isolation.branch}).`,
-    `The main checkout is untouched. Merge with @pify/worktree's worktree_merge branch="${isolation.branch}",`,
-    `or inspect: cd "${isolation.path}" && git log --stat`,
+    `Ran isolated in worktree ${isolation.path} (branch ${isolation.branch}); the main checkout is untouched.`,
+    `Its changes are in that worktree, uncommitted unless the child committed them. To bring them back:`,
+    `  review:  ${at} status && ${at} diff`,
+    `  commit:  ${at} add -A && ${at} commit -m "<what changed>"`,
+    `  merge:   @pify/worktree's worktree_merge branch="${isolation.branch}" (refuses an uncommitted tree)`,
+    `or discard it: git worktree remove --force "${isolation.path}".`,
   ].join("\n");
 }
 
+/** Note when an isolated run changed nothing and its worktree was removed. */
+export const CLEAN_WORKTREE_NOTE =
+  "Ran isolated in a temporary worktree; it changed nothing, so the worktree was removed.";
+
+/**
+ * The fields the isolation epilogue writes onto a call record. Kept structural
+ * so isolate.ts stays free of any dependency on the extension's types — the
+ * run's AgentCallState satisfies it by shape.
+ */
+export interface IsolationSink {
+  worktree?: string;
+  branch?: string;
+}
+
+/**
+ * Close out an isolated child's worktree exactly once, whatever its outcome.
+ *
+ * This is the epilogue EVERY terminal path of a child call must reach —
+ * success, schema mismatch, gate failure, abort, or a thrown error. Before,
+ * only the prose success path ran it, so a `schema:` step (or any failure or
+ * abort) left its worktree and branch behind forever. It runs
+ * removeIfUnchanged — a read-only step's worktree is deleted, a step that did
+ * work is kept — and when the worktree is kept it records where the edits live
+ * on the call so a non-prose result (a schema object, a null from an error)
+ * can still name the location instead of orphaning it.
+ *
+ * Returns the human note for callers that render prose; callers on non-prose
+ * paths rely on the pointer written to `sink`. Never throws (removeIfUnchanged
+ * already swallows its own failures): the cleanup must not sink a run.
+ */
+export function settleWorktree(
+  cwd: string,
+  isolation: Isolation,
+  sink: IsolationSink,
+): { removed: boolean; note: string } {
+  const removed = removeIfUnchanged(cwd, isolation);
+  if (removed) return { removed: true, note: CLEAN_WORKTREE_NOTE };
+  // Kept: there is work to merge. Record the pointer so the location survives
+  // on the call record even when the returned value is data or null.
+  sink.worktree = isolation.path;
+  sink.branch = isolation.branch;
+  return { removed: false, note: isolationNote(isolation) };
+}
+
 /**
  * Remove a worktree the child left untouched. An isolated run that changed
  * nothing is the common case — a review, a search, a question — and keeping

package/src/pending.ts

@@ -29,6 +29,13 @@ export interface PendingInput {
   now: number;
   /** What the caller asks for to collect it, e.g. `agent_result`. */
   collectWith: string;
+  /**
+   * Whether a UI/interactive session is present. Delivery needs a session
+   * that outlives the run; a headless `pi -p` run tears down when the prompt
+   * resolves, so "it will be delivered, do not poll" is a promise that cannot
+   * be kept there. Default true so existing callers keep the interactive text.
+   */
+  interactive?: boolean;
 }
 
 export interface PendingResult {
@@ -39,8 +46,12 @@ export interface PendingResult {
     /** True: this will resolve on its own. It is a wait, not a failure. */
     retryable: boolean;
     elapsedMs: number;
-    /** False, and load-bearing: there is nothing to poll for. */
-    pollRequired: false;
+    /**
+     * Interactive: false, and load-bearing — there is nothing to poll for.
+     * Headless: true — the session ends with this turn, so the model MUST
+     * collect within it or the result is lost.
+     */
+    pollRequired: boolean;
   };
 }
 
@@ -58,15 +69,28 @@ function elapsed(ms: number): string {
 export function pendingResult(input: PendingInput): PendingResult {
   const ms = Math.max(0, input.now - input.startedAt);
   const state = input.kind === "queued" ? "queued behind the concurrency cap" : "still running";
+  // A headless run has no session to deliver into — it ends when this turn
+  // does. Telling the model "do not poll, it will be delivered" there strands
+  // it awaiting a message that never comes; it must collect within the turn.
+  const headless = input.interactive === false;
+  const text = headless
+    ? [
+        `${input.id} is ${state} (${elapsed(ms)}).`,
+        "",
+        "This is a headless run: nothing is delivered after your turn ends. Call",
+        `${input.collectWith} again in this same turn until it returns the result — do not end`,
+        "your turn expecting to be picked back up.",
+      ].join("\n")
+    : [
+        `${input.id} is ${state} (${elapsed(ms)}).`,
+        "",
+        "Do not poll for it. The result is delivered to you automatically the moment it lands,",
+        `so there is nothing to wait for here — carry on with other work, or finish your turn and`,
+        `you will be picked back up. ${input.collectWith} is only needed if you want it early.`,
+      ].join("\n");
   return {
-    text: [
-      `${input.id} is ${state} (${elapsed(ms)}).`,
-      "",
-      "Do not poll for it. The result is delivered to you automatically the moment it lands,",
-      `so there is nothing to wait for here — carry on with other work, or finish your turn and`,
-      `you will be picked back up. ${input.collectWith} is only needed if you want it early.`,
-    ].join("\n"),
-    details: { id: input.id, status: input.kind, retryable: true, elapsedMs: ms, pollRequired: false },
+    text,
+    details: { id: input.id, status: input.kind, retryable: true, elapsedMs: ms, pollRequired: headless },
   };
 }
 

package/src/repair-policy.ts

@@ -0,0 +1,28 @@
+/**
+ * Who gets sent back to fix a failed gate.
+ *
+ * repair.ts bounds *how many* repair passes a failing gate may spend; this
+ * decides whether one is worth spending at all. Two facts rule it out. An
+ * agent with no writing tool can only re-read the failure and re-report it,
+ * so the pass buys nothing. And a child that ended its report with
+ * `OUTCOME: blocked` has said the wall is outside its reach — a decision,
+ * access or information it does not have — and a failing gate does not move
+ * that wall; a repair pass would just re-discover it at the cost of a full
+ * child run.
+ *
+ * The declaration has to be read *before* the item settles: settleItem
+ * strips it from the result so the report does not repeat it.
+ */
+
+import { parseDeclaredOutcome } from "./outcome.ts";
+import type { AgentDef } from "./types.ts";
+
+/** An agent that can write is one that can fix what a gate complained about. */
+export function canWrite(def: AgentDef): boolean {
+  return def.tools.some((t) => t === "edit" || t === "write" || t === "bash" || t === "powershell");
+}
+
+/** May this item be sent on a repair pass, given the agent and what it said? */
+export function repairAllowed(def: AgentDef, result: string | null | undefined): boolean {
+  return canWrite(def) && parseDeclaredOutcome(result) !== "blocked";
+}

package/src/repair.ts

@@ -47,8 +47,8 @@ export function repairPrompt(
 }
 
 export interface GateCycleDeps {
-  /** Run the gate in `cwd` and judge it (src/gate.ts runGate). */
-  runGate(contract: GateContract, cwd: string): GateVerdict & { output: string };
+  /** Run the gate in `cwd` and judge it (src/gate.ts runGate); a stub may answer synchronously. */
+  runGate(contract: GateContract, cwd: string): (GateVerdict & { output: string }) | Promise<GateVerdict & { output: string }>;
   /** Send the child back with a repair brief; resolves when that pass settles. */
   repair(prompt: string): Promise<void>;
   /**
@@ -79,14 +79,14 @@ export async function runGateCycle(
   cwd: string,
   deps: GateCycleDeps,
 ): Promise<{ record: GateRecord; verification: Verification }> {
-  let verdict = deps.runGate(contract, cwd);
+  let verdict = await 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);
+    verdict = await deps.runGate(contract, cwd);
   }
 
   const record: GateRecord = {

package/src/report.ts

@@ -66,7 +66,12 @@ export function buildReport(run: SwarmRun): string {
       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)"}`;
+      // cancelRun writes who stopped the run and what that cost into `error`;
+      // a turn-cap stop leaves it empty. Either way the reader should not have
+      // to guess which one it was.
+      // cancelNote ends its sentence itself; do not add a second period.
+      const why = (item.error ?? "turn cap or stop").replace(/\.$/, "");
+      return `${label}\nAborted — ${why}. Partial:\n${item.result ?? "(none)"}`;
     }
     return `${label}\n(${item.status})`;
   });

package/src/wait.ts

@@ -0,0 +1,48 @@
+/**
+ * Waiting on a run without teaching the model to poll.
+ *
+ * pending.ts says "do not poll" and means it — in an interactive session the
+ * report arrives on its own. A headless `pi -p` run has no such delivery, so
+ * there the model's only move was to call swarm_status again, and again, each
+ * call a full turn. `wait` lets one call sit on the run for a bounded time
+ * instead: the answer is the same either way, it just arrives in one turn.
+ *
+ * Pure: the condition, the budget and the tool's own AbortSignal. The
+ * extension owns what is being waited for.
+ */
+
+/**
+ * Resolve true as soon as `check()` holds, false when `ms` runs out or the
+ * signal fires first. Polls rather than subscribes: the run has no event to
+ * listen to, and a check every `intervalMs` costs nothing measurable.
+ */
+export function waitUntil(
+  check: () => boolean,
+  ms: number,
+  intervalMs = 250,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (check()) return Promise.resolve(true);
+  if (!(ms > 0) || signal?.aborted) return Promise.resolve(false);
+  const interval = Math.max(1, intervalMs);
+  return new Promise((resolve) => {
+    const deadline = Date.now() + ms;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (value: boolean): void => {
+      if (timer !== undefined) clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      resolve(value);
+    };
+    // An abort is the caller leaving, not a verdict; if the condition happens
+    // to hold by then, say so rather than reporting a wait that never happened.
+    const onAbort = (): void => finish(check());
+    const tick = (): void => {
+      if (check()) return finish(true);
+      const left = deadline - Date.now();
+      if (left <= 0) return finish(false);
+      timer = setTimeout(tick, Math.min(interval, left));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    timer = setTimeout(tick, Math.min(interval, ms));
+  });
+}