@d3ara1n/pi-subagent 1.0.0 → 1.1.0

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
 
@@ -260,7 +262,7 @@ When a provider error (429, quota, timeout, ...) kills a run and the whole task
 
 ### Run history
 
-Every completed delegate run is written (best-effort) to `~/.pi/subagent/history/{sessionId}/{toolCallId}.json`, recording role, task, usage, activity log, the **full raw output** (even when the main model saw a compressed/truncated version), and the `fallbackFrom` snapshot when the run was retried on the fallback role. Useful for auditing what subagents did and how much they cost. Disable with `history.enabled: false`.
+Every **spawned** delegate run is written (best-effort) to `~/.pi/subagent/history/{sessionId}/{toolCallId}.json` — finished, failed, and aborted alike (an aborted run already consumed tokens, so its partial activity and cost stay auditable). Records cover role, task, usage, activity log, the **full raw output** (even when the main model saw a compressed/truncated version), and the `fallbackFrom` snapshot when the run was retried on the fallback role. Runs that never spawned (cancelled while queued, role/model resolution failures) are not recorded. Useful for auditing what subagents did and how much they cost. Disable with `history.enabled: false`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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/history.ts

@@ -1,9 +1,13 @@
 /**
  * History persistence for pi-subagent delegate runs.
  *
- * Best-effort audit log: writes one JSON record per delegate run under
- * ~/.pi/subagent/history/{sessionId}/{toolCallId}.json. Never throws — persistence
- * must not fail the delegation. Privacy parity with pi's own session files.
+ * Best-effort audit log: writes one JSON record per *spawned* delegate run —
+ * finished, failed, and aborted alike (an aborted run already consumed
+ * tokens, so its partial activity and cost stay auditable). Pre-run failures
+ * that never spawned (queued-cancel, role/model resolution) are not recorded.
+ * Records land under ~/.pi/subagent/history/{sessionId}/{toolCallId}.json.
+ * Never throws — persistence must not fail the delegation. Privacy parity
+ * with pi's own session files.
  */
 
 import * as os from "node:os";

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,10 +94,14 @@ 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;
 
   // Mutable guidelines array — rebuilt in session_start to reflect agentOverrides
@@ -115,10 +125,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 +140,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 +201,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 };
@@ -236,7 +248,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)" })),
@@ -345,14 +357,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
       try {
         const result = await run.promise;
 
-        // Pipeline throws (abort, spawn crash) surface as tool errors. The
-        // empty-results frame keeps the TUI on the plain-content fallback.
-        if (run.thrown) {
-          const errorText = `Subagent (${params.role}) error: ${run.thrown.message || run.thrown}`;
-          emit([], errorText);
-          throw new Error(errorText);
-        }
-
         // Fallback note: the main model must know the answer came from the
         // fallback model, not the role's primary — on success AND failure.
         // Budget note: budget stops are intentional successes, but the model
@@ -360,6 +364,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
         const fallbackNote = formatFallbackNote(result);
         const budgetNote = formatBudgetNote(result);
 
+        // Aborts and spawn crashes arrive here too: the engine resolves them
+        // into failed results that keep the partial frame (task, activity,
+        // output, usage), so the TUI renders them like any failure instead
+        // of collapsing to a bare error line.
         if (isFailedResult(result)) {
           const failedText =
             `Subagent (${params.role}) failed: ${result.errorMessage || result.stderr || "unknown error"}\n\nPartial output:\n${result.output}` +
@@ -435,10 +443,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 =
@@ -542,7 +557,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" }),
@@ -551,14 +566,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 },
@@ -660,30 +695,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,
@@ -45,11 +46,11 @@ export const renderDelegateResult: RenderResultFn = (result, { expanded }, theme
   const isRunning = !!details?.results[0] && details.results[0].exitCode === -1;
 
   // Tick elapsed time every second while running; stop once terminal.
-  // Placed BEFORE the empty-results early return so every terminal path
-  // (abort, model-resolution failure, catch) still clears the timer —
-  // otherwise the interval leaks a permanent 1 Hz re-render per aborted run.
-  // The timer calls context.invalidate() so the render recomputes elapsed
-  // time fresh from Date.now() without dirtying the data layer.
+  // Placed BEFORE the missing-details early return so every terminal path
+  // still clears the timer — otherwise the interval leaks a permanent
+  // 1 Hz re-render per row. The timer calls context.invalidate() so the
+  // render recomputes elapsed time fresh from Date.now() without dirtying
+  // the data layer.
   if (isRunning) {
     ensureElapsedTimer(context);
   } else {
@@ -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

@@ -123,7 +123,11 @@ test("non-zero exit yields state failed without thrown", async () => {
 });
 
 test("a throwing spawn resolves the promise with a failed result carrying the error", async () => {
-  const spawnImpl: SpawnImpl = async () => {
+  const spawnImpl: SpawnImpl = async (_m, _t, options) => {
+    options.onProgress?.({
+      output: "partial",
+      activityLog: [{ kind: "toolCall", id: "t1", status: "done", toolName: "read", args: {} }],
+    });
     throw new Error("Subagent was aborted");
   };
 
@@ -134,6 +138,67 @@ test("a throwing spawn resolves the promise with a failed result carrying the er
   assert.ok(run.thrown instanceof Error);
   assert.strictEqual(run.thrown.message, "Subagent was aborted");
   assert.strictEqual(result.errorMessage, "Subagent was aborted");
+  // The partial frame survives — the foreground path renders aborts like any
+  // failure (task line + activity + result line) instead of a bare error.
+  assert.strictEqual(result.output, "partial");
+  assert.strictEqual(result.activityLog.length, 1);
+});
+
+test("spawned runs persist to history on every terminal path; pre-run failures do not", async () => {
+  const persisted: SubagentResult[] = [];
+  const persistImpl = (
+    _sessionId: string | undefined,
+    _toolCallId: string,
+    _role: string,
+    _task: string,
+    r: SubagentResult,
+  ) => {
+    persisted.push(r);
+  };
+  const historyConfig = { ...testConfig, history: { enabled: true } };
+
+  // Abort mid-run: the run spawned, so it must be audited.
+  const aborted = startSubagentRun(
+    makeDeps({
+      config: historyConfig,
+      spawnImpl: async (_m, _t, options) => {
+        options.onProgress?.({
+          output: "partial",
+          activityLog: [{ kind: "toolCall", id: "t1", status: "running", toolName: "bash", args: {} }],
+        });
+        throw new Error("Subagent was aborted");
+      },
+      persistImpl,
+    }),
+  );
+  await aborted.promise;
+  assert.equal(persisted.length, 1);
+  assert.match(persisted[0].errorMessage!, /aborted/);
+  assert.equal(persisted[0].activityLog.length, 1);
+
+  // Pre-run failure (roles api unavailable): never spawned, not audited.
+  const prerun = startSubagentRun(
+    makeDeps({
+      config: historyConfig,
+      getRolesApi: () => {
+        throw new Error("not initialized");
+      },
+      persistImpl,
+    }),
+  );
+  await prerun.promise;
+  assert.equal(persisted.length, 1);
+
+  // Normal success is audited too.
+  const ok = startSubagentRun(
+    makeDeps({
+      config: historyConfig,
+      spawnImpl: async () => makeResult({ output: "done" }),
+      persistImpl,
+    }),
+  );
+  await ok.promise;
+  assert.equal(persisted.length, 2);
 });
 
 test("provider error on first attempt retries on the fallback role", async () => {

package/src/run.ts

@@ -48,7 +48,7 @@ export interface RunHandle {
   readonly snapshot: SubagentResult;
   /** Terminal result; undefined while queued/running. */
   readonly result: SubagentResult | undefined;
-  /** Set when the pipeline threw (abort, spawn crash). Foreground callers rethrow; wait/check only see state "failed". */
+  /** Set when the pipeline threw (abort, spawn crash). The terminal result still carries the partial frame — callers report it as an ordinary failed result; wait/check only see state "failed". */
   readonly thrown: Error | undefined;
   /** Resolves with the terminal result once the run finishes (always succeeds). */
   readonly promise: Promise<SubagentResult>;
@@ -81,6 +81,8 @@ export interface StartRunOptions {
   getSessionId?: () => string | undefined;
   /** @internal — injectable spawn for tests. */
   spawnImpl?: typeof spawnSubagent;
+  /** @internal — injectable history persistence for tests. */
+  persistImpl?: typeof persistSubagentHistory;
 }
 
 export function startSubagentRun(opts: StartRunOptions): RunHandle {
@@ -164,11 +166,27 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
     try {
       await opts.gate.acquire(opts.signal);
     } catch {
-      const msg = `Subagent (${opts.role}) was cancelled while queued.`;
-      finish({ ...inputFrame(1, false), errorMessage: msg }, new Error("cancelled while queued"));
+      const msg = "cancelled while queued for a concurrency slot";
+      finish({ ...inputFrame(1, false), errorMessage: msg }, new Error(msg));
       return;
     }
 
+    // Audit every spawned run — finished, failed, and aborted alike: an
+    // aborted run already consumed tokens, so its cost must stay in the
+    // audit log. Pre-run failures (queued-cancel, role/model resolution)
+    // never spawned and are not recorded.
+    const persist = opts.persistImpl ?? persistSubagentHistory;
+    const persistHistory = (terminal: SubagentResult, rawOutput?: string): void => {
+      if (!opts.config.history.enabled) return;
+      let sessionId: string | undefined;
+      try {
+        sessionId = opts.getSessionId?.();
+      } catch {
+        /* ignore */
+      }
+      persist(sessionId, opts.toolCallId, opts.role, opts.task, terminal, rawOutput);
+    };
+
     try {
       // Resolve the model AFTER acquiring so the queued period stays zero-cost.
       let rolesApi: ModelRolesAPI;
@@ -312,37 +330,30 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         runResult.summary = await generateSummary(rolesApi, runResult.output, opts.config.summary);
       }
 
-      // Persist audit record (best-effort; covers both success and failure).
-      // History keeps the raw original output even when LLM/TUI saw a compressed/truncated version.
-      if (opts.config.history.enabled) {
-        let sessionId: string | undefined;
-        try {
-          sessionId = opts.getSessionId?.();
-        } catch {
-          /* ignore */
-        }
-        persistSubagentHistory(sessionId, opts.toolCallId, opts.role, opts.task, runResult, rawOutput);
-      }
+      // Best-effort audit record. The raw original output is kept even when
+      // the LLM/TUI saw a compressed/truncated version.
+      persistHistory(runResult, rawOutput);
 
       finish(runResult);
     } catch (err: any) {
       // Keep whatever the last live frame gathered so aborted/crashed runs
       // still show their partial activity and usage.
       const partial = snapshot;
-      finish(
-        {
-          ...inputFrame(1, false),
-          output: partial.output,
-          usage: partial.usage,
-          model: partial.model,
-          stopReason: partial.stopReason,
-          activityLog: partial.activityLog,
-          budgetMs: partial.budgetMs,
-          elapsedMs: partial.startTime ? Date.now() - partial.startTime : undefined,
-          errorMessage: err?.message || String(err),
-        },
-        err instanceof Error ? err : new Error(String(err)),
-      );
+      const terminal: SubagentResult = {
+        ...inputFrame(1, false),
+        output: partial.output,
+        usage: partial.usage,
+        model: partial.model,
+        stopReason: partial.stopReason,
+        activityLog: partial.activityLog,
+        budgetMs: partial.budgetMs,
+        elapsedMs: partial.startTime ? Date.now() - partial.startTime : undefined,
+        errorMessage: 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).
+      persistHistory(terminal);
+      finish(terminal, err instanceof Error ? err : new Error(String(err)));
     } finally {
       opts.gate.release();
     }

package/src/types.ts

@@ -12,7 +12,7 @@ export interface SubagentConfig {
   maxTurns: number;
   /** Default cumulative cost budget in USD. `0` means unlimited; negative values are normalized to `0`. Per-role maxCost overrides this. */
   maxCost: number;
-  /** Persist each delegate run to ~/.pi/subagent/history/{sessionId}/{toolCallId}.json for auditing. */
+  /** Persist every spawned delegate run (finished/failed/aborted alike) to ~/.pi/subagent/history/{sessionId}/{toolCallId}.json for auditing. Pre-run failures that never spawned are not recorded. */
   history: SubagentHistoryConfig;
   summary: SubagentSummaryConfig;
   /**
@@ -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 },