@pify/swarm 0.9.2 → 0.11.0

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

@@ -0,0 +1,351 @@
+/**
+ * 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 { spawn, type ChildProcess } 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;
+
+/**
+ * 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): 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 Promise.resolve({ outcome: "no_attestation", ok: false, reason: problems.join("; "), output: "" });
+  }
+  const timeoutMs = contract.timeoutMs ?? GATE_TIMEOUT_MS;
+
+  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,
+      });
+    };
+    // 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/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/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 },
   };
 }