@d3ara1n/pi-subagent 1.0.1 → 1.1.1

package/README.md

@@ -181,7 +181,7 @@ Foreground and background delegation share one async run engine — foreground i
 |------|---------|---------------------|
 | `subagent_delegate(background: true)` | Start an async run | Just the id (`sub-N`) |
 | `subagent_wait(ids?, timeout_ms?)` | Block until **all** listed runs finish (omit `ids` for all current background runs) | Statuses only, one `id (role): finished/failed` line per run — never results; errors when the timeout hits with runs unfinished |
-| `subagent_check(id)` | One-shot snapshot of a single run | `queued` / `running` + current activity / the **full output** once finished / failure reason + partial output |
+| `subagent_check(id)` | One-shot snapshot of a single run | `queued` / `running` + current activity / the **full output** once finished / failure reason + partial output. Checking a terminal run **collects** it: the output is returned once and the run leaves the registry |
 
 Typical flow:
 
@@ -203,10 +203,12 @@ Typical flow:
 Semantics worth knowing:
 
 - **Background runs survive turn cancellation** and are unaffected by a cancelled `subagent_wait` — cancelling the wait never cancels the runs; call `subagent_wait` or `subagent_check` again later.
+- **Read-once collection:** `subagent_check` on a terminal run returns the result and frees it — the output now lives in the conversation history, and only a lightweight tombstone stays in the registry (`/subagent:status` lists it under "Collected"). Re-checking a collected id explains that its result is already in the history.
+- **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the unclaimed runs (queued, running, and finished-but-unchecked alike), injected at a cache-stable head position. Runs missing from the list were already collected — so a finished run the model forgot to check keeps surfacing until it does.
 - **`timeout_ms` is optional.** Without it, `subagent_wait` blocks until every run finishes; each run is still bounded by its own role timeout.
 - Background runs share the global `maxConcurrency` gate — extra runs show up as `queued` in wait/check views.
 - **Top-level only:** nested subagents cannot delegate in the background (a subagent process exits when its task finishes, which would orphan the run).
-- The run registry lives in the pi process: a `/reload` or restart orphans in-flight background runs (their ids stop resolving). `/subagent:status` lists every registered run and its current state.
+- The run registry lives in the pi process: a `/reload` or restart orphans in-flight background runs (their ids stop resolving). `/subagent:status` lists every registered run (active + collected) and its current state.
 
 ### Background TUI display
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/index.ts

@@ -16,7 +16,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
-import type { SubagentConfig, SubagentResult, SubagentRole } from "./types.ts";
+import type {
+  CollectedRun,
+  SubagentConfig,
+  SubagentResult,
+  SubagentRole,
+} from "./types.ts";
 import { DEFAULT_CONFIG } from "./types.ts";
 import { loadSubagentConfig } from "./config.ts";
 import { BUILTIN_ROLES } from "./roles.ts";
@@ -37,6 +42,7 @@ import {
   taskPreview,
 } from "./utils.ts";
 import { startSubagentRun, type RunHandle } from "./run.ts";
+import { buildInboxReminder, injectReminder } from "./reminder.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render.ts";
 import {
   renderBackgroundDelegateCall,
@@ -88,12 +94,26 @@ export default function subagentExtension(pi: ExtensionAPI) {
   refreshAvailableRoles();
 
   // ── Background run registry ────────────────────────────────────
-  // Process-lifetime map of background runs. Foreground delegate runs are NOT
-  // registered — their lifecycle is the tool call itself. Cleared never: ids
-  // must stay resolvable so check can fetch results long after wait returned.
+  // Process-lifetime map of unclaimed background runs (queued, running, and
+  // finished/failed alike). Foreground delegate runs are NOT registered —
+  // their lifecycle is the tool call itself. subagent_check on a terminal run
+  // collects it: the handle is freed and a lightweight CollectedRun tombstone
+  // takes its place, so ids stay resolvable while memory does not grow with
+  // full results.
   const backgroundRuns = new Map<string, RunHandle>();
+  const collectedRuns = new Map<string, CollectedRun>();
   let runCounter = 0;
 
+  // ── Live-run reaping ─────────────────────────────────────────
+  // Every in-flight run (foreground and background alike), removed once
+  // settled. session_shutdown aborts whatever is still here so no child
+  // process outlives the parent — quit, reload, or session replacement.
+  const liveRuns = new Set<RunHandle>();
+  function trackRun(run: RunHandle): void {
+    liveRuns.add(run);
+    void run.promise.then(() => liveRuns.delete(run));
+  }
+
   // Mutable guidelines array — rebuilt in session_start to reflect agentOverrides
   const guidelines: string[] = [];
 
@@ -115,10 +135,8 @@ export default function subagentExtension(pi: ExtensionAPI) {
     guidelines.push(
       "WHEN TO DELEGATE — offload substantial work when you only need the result:",
       "",
-      "- Delegate ONLY when a task involves significant work (heavy analysis, multi-step investigation, large-scope changes) AND you only care about the conclusion, not intermediate steps.",
-      "- DO NOT delegate simple tasks: a single read, a one-line edit, a basic grep. Just do them yourself.",
-      "- DO NOT delegate straightforward file modifications touching 1-2 files. Use edit/write directly.",
-      "- Delegation has overhead (spawning a child process). Reserve it for tasks that would genuinely clutter your context with 3+ turns of raw tool output.",
+      "- Delegate ONLY when a task involves significant work (heavy analysis, multi-step investigation, large-scope changes) AND you only care about the conclusion, not intermediate steps. A good test: the task would clutter your context with 3+ turns of raw tool output.",
+      "- DO NOT delegate simple tasks — a single read, a one-line edit, a basic grep, or straightforward changes touching 1-2 files. Just do them yourself; spawning a child process costs more than the task.",
       "",
       "AVAILABLE ROLES:",
       ...entries.map(([name, role]) => `  - ${name}: ${role.description}`),
@@ -132,17 +150,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
       ...exampleLines,
       "",
       "For multiple independent substantial tasks, emit multiple subagent_delegate calls in one turn — they run in parallel.",
-      "Subagents have no access to this conversation — everything they need must come through `task`, `context`, and `files`.",
-      'Pass reference files via the `files` parameter (e.g. files: ["src/auth.ts"]) instead of pasting their contents into `context` — the subagent reads them directly without consuming your context window.',
-      "Override the model per-call with the `model` parameter for one-off vision or model-specific jobs.",
       "",
       "BACKGROUND DELEGATION — start runs now, collect results later:",
       "",
-      "- subagent_delegate(background: true) starts a run and returns immediately with just an id (sub-N). The run is unaffected by turn cancellation.",
-      "- After starting background runs, keep working (or start more); then subagent_wait(ids) blocks until every listed run reaches a final state (omit ids to wait for all of them).",
-      "- subagent_wait returns ONLY each run's status (finished/failed, one `id (role): status` line per run) — it never returns results. With timeout_ms it errors if anything is still unfinished.",
-      "- subagent_check(id) is the result-fetcher: for a finished run it returns the full output; mid-run it returns a snapshot (queued/running + current activity). One id per call — results can be large.",
-      "- Typical flow: subagent_delegate(background: true) ×N → work on something else → subagent_wait([id1, id2, ...]) → subagent_check(id) for each finished run.",
+      "- Typical flow: subagent_delegate(background: true) ×N → keep working → subagent_wait(ids) to block until every listed run finishes (omit ids to wait for all) → subagent_check(id) for each finished run.",
+      "- A terminal check collects the run — the output is returned once and the run leaves the registry. Mid-run checks are free: peek at progress as often as you like; only terminal checks collect.",
+      "- Every LLM call carries a [background subagent runs] reminder listing your unclaimed runs (queued, running, and finished-but-unchecked alike). Runs missing from that list were already collected.",
       "- Background delegation works only in the top-level session.",
     );
   }
@@ -198,6 +211,15 @@ export default function subagentExtension(pi: ExtensionAPI) {
     rebuildGuidelines(availableRoles);
   });
 
+  pi.on("context", async (event) => {
+    // The model's inbox: every unclaimed background run, injected at a
+    // cache-stable head position before every provider call. Empty inbox →
+    // zero injection (context untouched, cache fully stable).
+    const reminder = buildInboxReminder(backgroundRuns.values());
+    if (!reminder) return;
+    return { messages: injectReminder(event.messages, reminder) };
+  });
+
   pi.on("tool_result", (event) => {
     if (event.toolName === "subagent_delegate" && hasFailedSubagentResult(event.details)) {
       return { isError: true };
@@ -207,6 +229,15 @@ export default function subagentExtension(pi: ExtensionAPI) {
     }
   });
 
+  // Fires before the extension runtime is torn down (quit, reload, or
+  // session replacement). Aborting funnels through the standard abort path:
+  // children get SIGTERM → their own handlers kill grandchildren, aborted
+  // runs are audited to history, gates release. Without this, background
+  // children would burn tokens as unwaitable orphans after /reload or /new.
+  pi.on("session_shutdown", () => {
+    for (const run of liveRuns) run.abort("session shutdown");
+  });
+
   pi.registerTool({
     name: "subagent_delegate",
     label: "Delegate to subagent",
@@ -236,7 +267,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       background: Type.Optional(
         Type.Boolean({
           description:
-            "Run asynchronously: returns an id (sub-N) immediately instead of blocking. Then subagent_wait(ids) to await completion and subagent_check(id) to fetch each result. The run survives turn cancellation.",
+            "Run asynchronously: returns an id (sub-N) immediately instead of blocking. The run survives turn cancellation.",
         }),
       ),
       cwd: Type.Optional(Type.String({ description: "Working directory (defaults to current)" })),
@@ -295,6 +326,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
         getRolesApi: getModelRolesAPI,
         getSessionId: () => ctx.sessionManager?.getSessionId(),
       });
+      trackRun(run);
 
       // ── Background: return the id immediately; the pipeline keeps running. ──
       if (params.background) {
@@ -431,10 +463,17 @@ export default function subagentExtension(pi: ExtensionAPI) {
       }
       const unknown = ids.filter((id) => !backgroundRuns.has(id));
       if (unknown.length > 0) {
-        const known = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
-        throw new Error(
-          `Unknown subagent id(s): ${unknown.join(", ")}. Known: ${known.length > 0 ? known.join(", ") : "(none)"}.`,
-        );
+        const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
+        const collectedNotes = unknown
+          .filter((id) => collectedRuns.has(id))
+          .map((id) => `${id} was already collected (result is in your history)`);
+        const trulyUnknown = unknown.filter((id) => !collectedRuns.has(id));
+        const parts = [
+          `Unknown subagent id(s): ${trulyUnknown.length > 0 ? trulyUnknown.join(", ") : "(none)"}.`,
+          collectedNotes.length > 0 ? `${collectedNotes.join("; ")}.` : "",
+          `Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
+        ].filter(Boolean);
+        throw new Error(parts.join(" "));
       }
       const runs = ids.map((id) => backgroundRuns.get(id)!);
       const timeoutMs =
@@ -538,7 +577,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_check",
     label: "Check a background subagent",
     description:
-      "Get an instant snapshot of ONE background subagent run: queued / running (with current activity) / finished (with the full output as the run result) / failed (with reason and partial output). Does not wait — use subagent_wait for that. One id per call because results can be large.",
+      "Get an instant snapshot of ONE background subagent run: queued / running (with current activity) / finished (with the full output as the run result) / failed (with reason and partial output). Does not wait — use subagent_wait for that. Checking a terminal run collects it: the output is returned once and the run leaves the background registry. One id per call because results can be large.",
     promptSnippet: "Inspect a background subagent run",
     parameters: Type.Object({
       id: Type.String({ description: "Run id returned by a background delegate call" }),
@@ -547,14 +586,34 @@ export default function subagentExtension(pi: ExtensionAPI) {
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const run = backgroundRuns.get(params.id);
       if (!run) {
-        const known = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
+        const collected = collectedRuns.get(params.id);
+        if (collected) {
+          throw new Error(
+            `${params.id} (${collected.role}) was already collected — its result is in your conversation history. Check the remaining runs or delegate new ones.`,
+          );
+        }
+        const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         throw new Error(
-          `Unknown subagent id: ${params.id}. Known: ${known.length > 0 ? known.join(", ") : "(none)"}.`,
+          `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
         );
       }
 
       // Freeze live frames so the snapshot's elapsed time stays static.
       const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
+
+      // Read-once collection: a terminal check returns the result AND frees
+      // the run — the output now lives in the conversation history, so the
+      // registry keeps only a lightweight tombstone for id resolution.
+      if (run.state === "finished" || run.state === "failed") {
+        backgroundRuns.delete(run.id);
+        collectedRuns.set(run.id, {
+          id: run.id,
+          role: run.role,
+          task: taskPreview(run.task),
+          state: run.state,
+        });
+      }
+
       return {
         content: [{ type: "text", text: formatCheckText(run.id, run.role, snap) }],
         details: { id: run.id, role: run.role, result: snap },
@@ -656,30 +715,40 @@ export default function subagentExtension(pi: ExtensionAPI) {
   pi.registerCommand("subagent:status", {
     description: "List background subagent runs and their current state",
     handler: async (_args, ctx) => {
-      if (backgroundRuns.size === 0) {
+      if (backgroundRuns.size === 0 && collectedRuns.size === 0) {
         ctx.ui.notify("No background runs.", "info");
         return;
       }
       const lines: string[] = [];
-      for (const run of backgroundRuns.values()) {
-        // Freeze live frames so elapsed-dependent details don't drift in the listing.
-        const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
-        let icon: string;
-        let detail: string;
-        if (run.state === "failed") {
-          icon = "\u2717";
-          detail = snap.errorMessage || "unknown error";
-        } else if (run.state === "finished") {
-          icon = "\u2713";
-          detail = snap.summary || taskPreview(snap.output) || "(no output)";
-        } else if (run.state === "queued") {
-          icon = "\u23F8";
-          detail = "queued — waiting for a concurrency slot";
-        } else {
-          icon = "\u23F3";
-          detail = `running — ${describeCurrentActivity(snap)}`;
+      if (backgroundRuns.size > 0) {
+        lines.push("Active:");
+        for (const run of backgroundRuns.values()) {
+          // Freeze live frames so elapsed-dependent details don't drift in the listing.
+          const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
+          let icon: string;
+          let detail: string;
+          if (run.state === "failed") {
+            icon = "\u2717";
+            detail = snap.errorMessage || "unknown error";
+          } else if (run.state === "finished") {
+            icon = "\u2713";
+            detail = snap.summary || taskPreview(snap.output) || "(no output)";
+          } else if (run.state === "queued") {
+            icon = "\u23F8";
+            detail = "queued — waiting for a concurrency slot";
+          } else {
+            icon = "\u23F3";
+            detail = `running — ${describeCurrentActivity(snap)}`;
+          }
+          lines.push(`${icon} ${run.id} (${run.role}): ${detail}`);
+        }
+      }
+      if (collectedRuns.size > 0) {
+        if (lines.length > 0) lines.push("");
+        lines.push("Collected (result already returned via subagent_check):");
+        for (const c of collectedRuns.values()) {
+          lines.push(`\u2713 ${c.id} (${c.role}): ${c.state} — "${c.task}"`);
         }
-        lines.push(`${icon} ${run.id} (${run.role}): ${detail}`);
       }
       ctx.ui.notify(lines.join("\n"), "info");
     },

package/src/reminder.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Unit tests for the background-run inbox reminder.
+ *
+ * Zero-dependency: runs on node's built-in test runner.
+ *   node --test packages/pi-subagent/src/reminder.test.ts
+ *
+ * Coverage: row formatting per state (queued/running/finished/failed/budget),
+ * byte-stability between calls (the cache-prefix contract), empty-inbox
+ * no-op, and cache-stable head injection (string content, block content,
+ * non-user first message, empty transcript).
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { buildInboxReminder, injectReminder, type InboxEntry } from "./reminder.ts";
+import type { SubagentResult } from "./types.ts";
+import { emptyUsage } from "./utils.ts";
+
+function frame(partial: Partial<SubagentResult>): SubagentResult {
+  return {
+    role: "worker",
+    task: "task",
+    exitCode: 0,
+    output: "",
+    stderr: "",
+    usage: emptyUsage(),
+    activityLog: [],
+    ...partial,
+  };
+}
+
+function entry(partial: Partial<InboxEntry> & Pick<InboxEntry, "id" | "state">): InboxEntry {
+  return {
+    role: "worker",
+    task: "Investigate flaky tests in packages/pi-subagent",
+    snapshot: frame({}),
+    ...partial,
+  };
+}
+
+describe("buildInboxReminder", () => {
+  test("empty inbox returns undefined (zero injection)", () => {
+    assert.equal(buildInboxReminder([]), undefined);
+  });
+
+  test("queued and running rows carry no time-derived detail", () => {
+    const text = buildInboxReminder([
+      entry({ id: "sub-3", state: "queued", snapshot: frame({ exitCode: -1, queued: true }) }),
+      entry({
+        id: "sub-2",
+        state: "running",
+        // Live frame: startTime present — a naive formatter would derive elapsed from it.
+        snapshot: frame({ exitCode: -1, startTime: Date.now() - 60_000 }),
+      }),
+    ])!;
+    assert.match(text, /\n- sub-3 \(worker\) — queued — "Investigate flaky tests/);
+    assert.match(text, /\n- sub-2 \(worker\) — running — "Investigate flaky tests/);
+    // No seconds anywhere on live rows — byte-stability contract.
+    assert.doesNotMatch(text, /\d+s/);
+  });
+
+  test("finished row freezes duration from elapsedMs", () => {
+    const text = buildInboxReminder([
+      entry({
+        id: "sub-1",
+        state: "finished",
+        snapshot: frame({ exitCode: 0, elapsedMs: 192_000 }),
+      }),
+    ])!;
+    assert.match(text, /\n- sub-1 \(worker\) — finished \(ran 3m12s\) — "Investigate flaky tests/);
+  });
+
+  test("budget-stopped finished row is flagged partial", () => {
+    const text = buildInboxReminder([
+      entry({
+        id: "sub-1",
+        state: "finished",
+        snapshot: frame({ exitCode: 0, elapsedMs: 300_000, stopReason: "budget_exceeded" }),
+      }),
+    ])!;
+    assert.match(text, /— finished, partial — budget exceeded \(ran 5m\) —/);
+  });
+
+  test("failed row carries the error preview, first line only", () => {
+    const text = buildInboxReminder([
+      entry({
+        id: "sub-4",
+        state: "failed",
+        snapshot: frame({
+          exitCode: 1,
+          elapsedMs: 5_000,
+          errorMessage: "provider timeout\nretry hint: check quota",
+        }),
+      }),
+    ])!;
+    assert.match(text, /— failed — provider timeout \(ran 5s\) —/);
+    assert.doesNotMatch(text, /retry hint/);
+  });
+
+  test("byte-stable: identical state produces identical text", () => {
+    const entries = [
+      entry({ id: "sub-1", state: "finished", snapshot: frame({ exitCode: 0, elapsedMs: 42_000 }) }),
+      entry({ id: "sub-2", state: "running", snapshot: frame({ exitCode: -1, startTime: 123 }) }),
+    ];
+    assert.equal(buildInboxReminder(entries), buildInboxReminder(entries));
+  });
+
+  test("long task text is truncated to the shared 70-char preview cap", () => {
+    const long = "x".repeat(120);
+    const text = buildInboxReminder([entry({ id: "sub-9", state: "running", task: long })])!;
+    assert.ok(text.includes(`"${"x".repeat(70)}..."`));
+  });
+
+  test("header explains collection semantics", () => {
+    const text = buildInboxReminder([entry({ id: "sub-1", state: "running" })])!;
+    assert.match(text, /^\[background subagent runs — subagent_check claims/);
+    assert.match(text, /already collected\]/);
+  });
+});
+
+describe("injectReminder", () => {
+  const reminder = "[background subagent runs]\n- sub-1 (worker) — running";
+
+  test("string content: reminder prepended, rest of transcript identical", () => {
+    const messages = [
+      { role: "user" as const, content: "original prompt", timestamp: 1 },
+      { role: "assistant" as const, content: [{ type: "text" as const, text: "answer" }] },
+    ];
+    const out = injectReminder(messages as any, reminder);
+    assert.equal(out.length, 2);
+    assert.equal(out[0].role, "user");
+    assert.equal((out[0] as any).content, `${reminder}\n\noriginal prompt`);
+    assert.deepEqual(out[1], messages[1]);
+  });
+
+  test("block content: reminder becomes the first text block", () => {
+    const messages = [
+      {
+        role: "user" as const,
+        content: [
+          { type: "text" as const, text: "original" },
+          { type: "text" as const, text: "blocks" },
+        ],
+        timestamp: 1,
+      },
+    ];
+    const out = injectReminder(messages as any, reminder);
+    const content = (out[0] as any).content;
+    assert.equal(content[0].type, "text");
+    assert.equal(content[0].text, reminder);
+    assert.equal(content.length, 3);
+  });
+
+  test("non-user first message: synthetic leading user message", () => {
+    const messages = [{ role: "assistant" as const, content: [{ type: "text" as const, text: "hi" }] }];
+    const out = injectReminder(messages as any, reminder);
+    assert.equal(out.length, 2);
+    assert.equal(out[0].role, "user");
+    assert.equal((out[0] as any).content, reminder);
+    assert.deepEqual(out[1], messages[0]);
+  });
+
+  test("empty transcript: single injected user message", () => {
+    const out = injectReminder([] as any, reminder);
+    assert.equal(out.length, 1);
+    assert.equal(out[0].role, "user");
+    assert.equal((out[0] as any).content, reminder);
+  });
+
+  test("input messages are not mutated", () => {
+    const messages = [{ role: "user" as const, content: "original", timestamp: 1 }];
+    injectReminder(messages as any, reminder);
+    assert.equal(messages[0].content, "original");
+  });
+});

package/src/reminder.ts

@@ -0,0 +1,93 @@
+/**
+ * The model's inbox of unclaimed background subagent runs.
+ *
+ * Injected into the LLM context before every provider call via the `context`
+ * event. The reminder lists every delegated run whose result has not been
+ * claimed yet — queued, running, and finished/failed alike — so the model
+ * cannot forget about them. `subagent_check` on a terminal run returns the
+ * output AND removes the run from this list (read-once collection).
+ *
+ * Cache discipline: the reminder is prepended to the FIRST user message, so
+ * it sits at a stable position in the message prefix. Its content must stay
+ * byte-stable between state transitions — that rules out elapsed time on
+ * running rows and any other live-derived detail. Only terminal rows may
+ * carry a duration (frozen in elapsedMs at completion).
+ */
+
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+import type { RunState, SubagentResult } from "./types.ts";
+import { elapsedSeconds, taskPreview } from "./utils.ts";
+
+/** One row of the inbox. RunHandle satisfies this shape structurally. */
+export interface InboxEntry {
+  id: string;
+  role: string;
+  task: string;
+  state: RunState;
+  snapshot: SubagentResult;
+}
+
+const INBOX_HEADER =
+  "[background subagent runs — subagent_check claims a terminal run's output and removes it from this list; runs missing here were already collected]";
+
+/** `42s`, `3m12s`, `4m` — whole seconds, no live clocks. */
+function formatDuration(totalSec: number): string {
+  if (totalSec < 60) return `${totalSec}s`;
+  const m = Math.floor(totalSec / 60);
+  const s = totalSec % 60;
+  return s > 0 ? `${m}m${s}s` : `${m}m`;
+}
+
+/** Status segment of one row: state plus its stable extras (duration, error). */
+function inboxStatus(entry: InboxEntry): string {
+  if (entry.state === "queued") return "queued";
+  if (entry.state === "running") return "running";
+  const secs = elapsedSeconds(entry.snapshot);
+  const ran = secs != null ? ` (ran ${formatDuration(secs)})` : "";
+  if (entry.state === "failed") {
+    const reason = taskPreview(entry.snapshot.errorMessage || entry.snapshot.stderr || "unknown error");
+    return `failed — ${reason}${ran}`;
+  }
+  const partial = entry.snapshot.stopReason === "budget_exceeded" ? ", partial — budget exceeded" : "";
+  return `finished${partial}${ran}`;
+}
+
+/**
+ * Build the inbox reminder text, or undefined when every delegated run has
+ * been collected (nothing to remind about — inject nothing, keep the context
+ * untouched and the provider cache fully stable).
+ */
+export function buildInboxReminder(entries: Iterable<InboxEntry>): string | undefined {
+  const rows: string[] = [];
+  for (const entry of entries) {
+    rows.push(`- ${entry.id} (${entry.role}) — ${inboxStatus(entry)} — "${taskPreview(entry.task)}"`);
+  }
+  if (rows.length === 0) return undefined;
+  return `${INBOX_HEADER}\n${rows.join("\n")}`;
+}
+
+/** Message array type of the `context` event (AgentMessage[]). */
+type ContextMessages = ContextEvent["messages"];
+
+/**
+ * Prepend the reminder at a cache-stable position: the first text block of
+ * the first user message (or a synthetic leading user message when the
+ * transcript does not start with one).
+ */
+export function injectReminder(messages: ContextMessages, reminder: string): ContextMessages {
+  if (messages.length === 0) {
+    return [{ role: "user", content: reminder, timestamp: 0 } as ContextMessages[number]];
+  }
+  const [first, ...rest] = messages;
+  if (first.role === "user") {
+    const content =
+      typeof first.content === "string"
+        ? `${reminder}\n\n${first.content}`
+        : [{ type: "text", text: reminder }, ...first.content];
+    return [{ ...first, content } as ContextMessages[number], ...rest];
+  }
+  return [
+    { role: "user", content: reminder, timestamp: 0 } as ContextMessages[number],
+    ...messages,
+  ];
+}

package/src/render-async.ts

@@ -32,6 +32,7 @@ import type {
 import {
   buildDisplayItems,
   clearElapsedTimer,
+  collapsedText,
   contentText,
   deriveRunState,
   ensureElapsedTimer,
@@ -234,7 +235,7 @@ export const renderBackgroundDelegateCall: RenderCallFn = (args, theme) => {
 
 export const renderBackgroundDelegateResult: RenderResultFn = (result, { expanded }, theme) => {
   const details = result.details as BackgroundDelegateDetails | undefined;
-  if (!details) return new Text(contentText(result), 0, 0);
+  if (!details) return collapsedText(contentText(result));
 
   const fg = theme.fg.bind(theme) as Fg;
   // One-line anchor: marker + id + task preview. The run's live state is NOT
@@ -242,7 +243,7 @@ export const renderBackgroundDelegateResult: RenderResultFn = (result, { expande
   // progresses invisibly until a wait/check row picks it up.
   const summaryLine = `${fg("accent", "\u25B6")} ${fg("dim", details.id)} ${fg("text", taskPreview(details.task))}`;
 
-  if (!expanded) return new Text(summaryLine, 0, 0);
+  if (!expanded) return collapsedText(summaryLine);
 
   // Expanded: full input — reference files, context size, task text.
   const container = new Container();
@@ -272,7 +273,7 @@ export const renderWaitCall: RenderCallFn = (args, theme) => {
 export const renderWaitResult: RenderResultFn = (result, { expanded }, theme, context) => {
   const details = result.details as WaitDetails | undefined;
   if (!details || details.entries.length === 0) {
-    return new Text(contentText(result), 0, 0);
+    return collapsedText(contentText(result));
   }
 
   // Tick while any watched run is still live. A timed-out wait freezes the
@@ -301,7 +302,7 @@ export const renderWaitResult: RenderResultFn = (result, { expanded }, theme, co
   }
 
   const text = details.entries.map((e) => waitEntryCollapsedText(e, fg)).join("\n\n");
-  return new Text(text, 0, 0);
+  return collapsedText(text);
 };
 
 // ── check: frozen single-run snapshot ──────────────────────────
@@ -314,11 +315,11 @@ export const renderCheckCall: RenderCallFn = (args, theme) => {
 
 export const renderCheckResult: RenderResultFn = (result, { expanded }, theme, _context) => {
   const details = result.details as CheckDetails | undefined;
-  if (!details) return new Text(contentText(result), 0, 0);
+  if (!details) return collapsedText(contentText(result));
 
   const fg = theme.fg.bind(theme) as Fg;
   // Static snapshot — never starts the animation timer (the execute layer
   // freezes the frame before handing it over).
   if (expanded) return checkEntryExpandedContainer(details.result, fg);
-  return new Text(checkEntryCollapsedText(details.result, fg), 0, 0);
+  return collapsedText(checkEntryCollapsedText(details.result, fg));
 };

package/src/render.ts

@@ -11,6 +11,7 @@ import type { SubagentDetails } from "./types.ts";
 import {
   buildDisplayItems,
   clearElapsedTimer,
+  collapsedText,
   contentText,
   ensureElapsedTimer,
   formatFallback,
@@ -57,7 +58,7 @@ export const renderDelegateResult: RenderResultFn = (result, { expanded }, theme
   }
 
   if (!details || details.results.length === 0) {
-    return new Text(contentText(result), 0, 0);
+    return collapsedText(contentText(result));
   }
 
   const r = details.results[0];
@@ -192,5 +193,5 @@ export const renderDelegateResult: RenderResultFn = (result, { expanded }, theme
   }
   if (fallbackLine) text += `\n${fallbackLine}`;
   if (usageLine) text += `\n${theme.fg("dim", usageLine)}`;
-  return new Text(text, 0, 0);
+  return collapsedText(text);
 };

package/src/run.test.ts

@@ -256,6 +256,63 @@ test("abort while queued fails the run and exposes thrown for the foreground pat
   gate.release();
 });
 
+test("handle.abort() reaps a queued background run (no caller signal)", async () => {
+  const gate = new AsyncSemaphore(1);
+  await gate.acquire();
+  const spawnImpl: SpawnImpl = async () => makeResult({ output: "never" });
+
+  const run = startSubagentRun(makeDeps({ gate, spawnImpl }));
+  run.abort("session shutdown");
+  const result = await run.promise;
+
+  assert.strictEqual(run.state, "failed");
+  assert.ok(run.thrown instanceof Error);
+  assert.match(result.errorMessage!, /cancelled while queued/);
+  assert.match(result.errorMessage!, /session shutdown/);
+  gate.release();
+});
+
+test("handle.abort(reason) fails a running run with the reason in the error message", async () => {
+  const signals: AbortSignal[] = [];
+  // Mirrors real spawn's abort handling: pre-aborted signals settle immediately
+  // (an "abort" listener alone would never fire — the event already happened).
+  const honoringSpawn: SpawnImpl = (_m, _t, options) =>
+    new Promise((_resolve, reject) => {
+      signals.push(options.signal!);
+      const die = () => reject(new Error("Subagent was aborted"));
+      if (options.signal?.aborted) die();
+      else options.signal?.addEventListener("abort", die, { once: true });
+    });
+
+  const run = startSubagentRun(makeDeps({ spawnImpl: honoringSpawn }));
+  run.abort("session shutdown");
+  const result = await run.promise;
+
+  assert.strictEqual(run.state, "failed");
+  assert.match(result.errorMessage!, /Subagent was aborted \(session shutdown\)/);
+  assert.ok(run.thrown instanceof Error);
+  // The internal controller the spawn honored is the same channel abort() used.
+  assert.ok(signals[0].aborted);
+});
+
+test("a pre-aborted caller signal chains into the run before spawn", async () => {
+  const controller = new AbortController();
+  controller.abort();
+  const spawnImpl: SpawnImpl = async (_m, _t, options) => {
+    if (options.signal?.aborted) throw new Error("Subagent was aborted");
+    return makeResult({ output: "done" });
+  };
+
+  const run = startSubagentRun(makeDeps({ signal: controller.signal, spawnImpl }));
+  const result = await run.promise;
+
+  assert.strictEqual(run.state, "failed");
+  assert.strictEqual(result.errorMessage, "Subagent was aborted");
+  // abort() after settle is a no-op — the terminal state never flips.
+  run.abort("session shutdown");
+  assert.strictEqual(run.state, "failed");
+});
+
 test("subscribers are notified on progress and terminal frames", async () => {
   let notifications = 0;
   const spawnImpl: SpawnImpl = async (_m, _t, options) => {

package/src/run.ts

@@ -9,6 +9,11 @@
  * exposed via `thrown`), and a subscriber list the `wait` tool uses to mirror
  * live progress into its own tool row.
  *
+ * Every run owns an AbortController. The foreground tool signal chains into
+ * it; runs started without a caller signal (background) are still abortable
+ * via handle.abort() — session_shutdown reaps every live run that way, so no
+ * child process outlives the parent.
+ *
  * All post-processing (fallback retry, output compression, summary
  * generation, history persistence) runs inside the pipeline, so background
  * runs finish exactly like foreground ones.
@@ -52,6 +57,8 @@ export interface RunHandle {
   readonly thrown: Error | undefined;
   /** Resolves with the terminal result once the run finishes (always succeeds). */
   readonly promise: Promise<SubagentResult>;
+  /** Abort the run — no-op after settle. Tool-cancellation and session-shutdown reaping both funnel here. */
+  abort(reason?: string): void;
   /** Get notified on every frame change. Returns an unsubscribe function. */
   subscribe(fn: () => void): () => void;
 }
@@ -69,7 +76,7 @@ export interface StartRunOptions {
   cwd: string;
   /** Nesting depth for the child (CURRENT_DEPTH + 1). */
   depth: number;
-  /** Foreground callers pass the tool's AbortSignal; background runs pass none and outlive the turn. */
+  /** Foreground callers chain the tool's AbortSignal in; background runs pass none and are aborted via handle.abort() instead. */
   signal?: AbortSignal;
   /** Per-call model override ('provider/model-id'), bypassing the role's configured model. */
   modelOverride?: string;
@@ -106,6 +113,14 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
   let snapshot: SubagentResult = inputFrame(-1, true);
   let result: SubagentResult | undefined;
   let thrown: Error | undefined;
+  let settled = false;
+  let abortReason: string | undefined;
+  const controller = new AbortController();
+  const onCallerAbort = () => controller.abort();
+  if (opts.signal) {
+    if (opts.signal.aborted) controller.abort();
+    else opts.signal.addEventListener("abort", onCallerAbort, { once: true });
+  }
   let resolvePromise!: (r: SubagentResult) => void;
   const promise = new Promise<SubagentResult>((resolve) => {
     resolvePromise = resolve;
@@ -126,11 +141,14 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
     notify();
   };
   const finish = (terminal: SubagentResult, error?: Error) => {
+    if (settled) return;
+    settled = true;
     result = terminal;
     snapshot = terminal;
     thrown = error;
     currentState = isFailedResult(terminal) ? "failed" : "finished";
     notify();
+    opts.signal?.removeEventListener("abort", onCallerAbort);
     resolvePromise(terminal);
   };
 
@@ -158,15 +176,22 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         listeners.delete(fn);
       };
     },
+    abort(reason?: string) {
+      if (settled) return;
+      if (reason) abortReason = reason;
+      controller.abort();
+    },
     promise,
   };
 
   (async () => {
     // ── Concurrency gate (abortable while queued) ──
     try {
-      await opts.gate.acquire(opts.signal);
+      await opts.gate.acquire(controller.signal);
     } catch {
-      const msg = "cancelled while queued for a concurrency slot";
+      const msg =
+        "cancelled while queued for a concurrency slot" +
+        (abortReason ? ` (${abortReason})` : "");
       finish({ ...inputFrame(1, false), errorMessage: msg }, new Error(msg));
       return;
     }
@@ -262,7 +287,7 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         maxTurns,
         maxCost,
         depth: opts.depth,
-        signal: opts.signal,
+        signal: controller.signal,
         onProgress: emitProgress,
       });
 
@@ -294,7 +319,7 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
             maxTurns,
             maxCost,
             depth: opts.depth,
-            signal: opts.signal,
+            signal: controller.signal,
             onProgress: emitProgress,
           });
           runResult.fallbackFrom = fallbackFrom;
@@ -348,7 +373,9 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         activityLog: partial.activityLog,
         budgetMs: partial.budgetMs,
         elapsedMs: partial.startTime ? Date.now() - partial.startTime : undefined,
-        errorMessage: err?.message || String(err),
+        errorMessage: abortReason
+          ? `Subagent was aborted (${abortReason})`
+          : err?.message || String(err),
       };
       // The run spawned before throwing — audit it like any terminal state.
       // The partial output is raw (compression never ran on it).

package/src/spawn.ts

@@ -19,6 +19,29 @@ const INLINE_LIMIT = 8000;
 
 const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
 
+// ── Parent-exit safety net ─────────────────────────────────────
+// process.on("exit") fires synchronously on every terminal path that goes
+// through process.exit — normal quit, signal-triggered graceful shutdown,
+// emergency terminal exit, uncaught crash. SIGTERM the live children so each
+// pi child runs its own cleanup (killing ITS tracked grandchildren) instead
+// of burning tokens as an orphan. This covers the paths where the graceful
+// session_shutdown reaping never fires; a SIGKILL'd parent is beyond help.
+const liveChildren = new Set<ChildProcess>();
+let exitHookInstalled = false;
+function reapChildrenOnExit(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.on("exit", () => {
+    for (const child of liveChildren) {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        /* already dead */
+      }
+    }
+  });
+}
+
 function isRunnableScript(filePath: string): boolean {
   try {
     if (!fs.existsSync(filePath)) return false;
@@ -508,6 +531,8 @@ export async function spawnSubagent(
         stdio: ["ignore", "pipe", "pipe"],
       });
       proc = p;
+      liveChildren.add(p);
+      reapChildrenOnExit();
 
       p.stdout.on("data", (data: Buffer) => {
         buffer += data.toString();
@@ -522,6 +547,7 @@ export async function spawnSubagent(
 
       p.on("exit", () => {
         processExited = true;
+        liveChildren.delete(p);
         clearEscalationTimer();
       });
 
@@ -548,6 +574,7 @@ export async function spawnSubagent(
 
       p.on("error", (err) => {
         processExited = true;
+        liveChildren.delete(p);
         if (timeoutHandle) clearTimeout(timeoutHandle);
         clearEscalationTimer();
         if (onAbort && options.signal) options.signal.removeEventListener("abort", onAbort);

package/src/types.ts

@@ -212,6 +212,15 @@ export interface WaitDetails {
   timedOut?: boolean;
 }
 
+/** Lightweight tombstone kept in the registry after a run's result was claimed via subagent_check — /subagent:status history without the full state machine. */
+export interface CollectedRun {
+  id: string;
+  role: string;
+  /** First-line task preview (same 70-char cap as the inbox reminder). */
+  task: string;
+  state: "finished" | "failed";
+}
+
 /** Details for a check tool result — a frozen one-shot snapshot of a single run. */
 export interface CheckDetails {
   id: string;

package/src/utils.ts

@@ -5,6 +5,8 @@
  */
 
 import * as os from "node:os";
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth } from "@earendil-works/pi-tui";
 import type {
   ActivityEntry,
   FallbackFrom,
@@ -259,6 +261,23 @@ export function taskPreview(task: string): string {
   return firstLine.length > 70 ? `${firstLine.slice(0, 70)}...` : firstLine;
 }
 
+/**
+ * Width-aware collapsed-view component: renders each line truncated with "…"
+ * to the actual viewport width (never wraps), padded full-width like Text(0,0).
+ *
+ * The char caps in taskPreview/formatToolCall/etc. stay as they are — they are
+ * content limits shared with the LLM-facing text (check output, error
+ * messages), which has no viewport semantics. This component is the TUI-side
+ * final guard, applied where the folding affordance exists.
+ */
+export function collapsedText(text: string): Component {
+  const lines = text.split("\n");
+  return {
+    render: (width: number) => lines.map((ln) => truncateToWidth(ln, width, "…", true)),
+    invalidate: () => {},
+  };
+}
+
 /** Status icon for a run frame: ⏸ queued / ⏳ running / ⏱ timeout / ⏲ budget / ✗ failed / ✓ ok */
 export function runIcon(
   r: { exitCode: number; queued?: boolean; stopReason?: string },