@d3ara1n/pi-subagent 3.1.0 → 3.2.1

package/README.md

@@ -1,5 +1,7 @@
 # @d3ara1n/pi-subagent
 
+[![npm version](https://img.shields.io/npm/v/@d3ara1n/pi-subagent)](https://www.npmjs.com/package/@d3ara1n/pi-subagent) [![npm downloads](https://img.shields.io/npm/dm/@d3ara1n/pi-subagent)](https://www.npmjs.com/package/@d3ara1n/pi-subagent) [![license](https://img.shields.io/npm/l/@d3ara1n/pi-subagent)](https://www.npmjs.com/package/@d3ara1n/pi-subagent)
+
 Role-based subagent orchestration for [pi](https://github.com/earendil-works/pi).
 
 Provides a `subagent_delegate` tool that lets the main model offload tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries. Runs can be foreground (blocking) or background (asynchronous, collected later via `subagent_wait`/`subagent_check`, cancellable via `subagent_cancel`). A centered live view (`/subagent:view`) shows every run's activity feed as it happens, with a per-run brief page for inputs and stats; mid-run corrections can be queued into a running subagent from the view's steer editor or via `subagent_steer`.
@@ -41,13 +43,13 @@ Observations on how main models behave with this plugin, one family per subsecti
 | Role | Model Role | Timeout | Tools | Can Delegate To | Description |
 |------|-----------|---------|-------|-----------------|-------------|
 | `explorer` | fast | 900s | read, find, grep, bash | — | Fast code exploration incl. git history inspection (read-only) |
-| `reviewer` | heavy | 3600s | read, bash, grep, find | — | Deep code review, runs git/tests for evidence (read-only) |
+| `reviewer` | heavy | 3600s | read, bash, grep, find, subagent_delegate | explorer, researcher | Deep code review, runs git/tests for evidence (read-only); delegates exploration & web verification |
 | `worker` | default | 2400s | all (no whitelist) | explorer, researcher | Implementation — the only role that can modify files; full tool access (web, MCP, everything) |
-| `researcher` | fast | 2400s | web_search, fetch_content, source_check, get_search_content, read, bash, edit, write, delegate | explorer | Web research + GitHub repo analysis; writes artifacts only inside its temp dir |
+| `researcher` | fast | 2400s | web_search, fetch_content, source_check, get_search_content, read, bash, edit, write, subagent_delegate | explorer | Web research + GitHub repo analysis; writes artifacts only inside its temp dir |
 
 **Web tool naming**: `researcher`'s web tools use the community-standard names (`web_search`, `fetch_content`, `source_check`, `get_search_content`) shared by the most popular Pi web extensions — [pi-web-access](https://github.com/nicobailon/pi-web-access), `pi-web-tools`, `pi-browse`, and others. Install any of those and the researcher gets web access out of the box. If your web extension uses different tool names (e.g. `websearch`/`webfetch`) or you renamed the tools via a `toolNames` config, override `researcher.tools` in `agentOverrides` to match.
 
-**Nested delegation**: `worker` and `researcher` can spawn their own subagents. This keeps the main model's context clean — a worker can explore unfamiliar code via an `explorer` subagent without returning intermediate results to the main model.
+**Nested delegation**: `worker`, `reviewer`, and `researcher` can spawn their own subagents. This keeps the caller's context clean — a worker can explore unfamiliar code via an `explorer` subagent without returning intermediate results, and a reviewer can verify third-party library behavior via a `researcher` subagent without leaving the diff.
 
 **Parallel execution**: To run multiple subagents concurrently, emit multiple `subagent_delegate` calls in a single turn. Pi's framework executes them in parallel automatically, with each subagent getting its own TUI progress display.
 
@@ -134,6 +136,8 @@ Timeouts are defined per role. Built-in defaults are `explorer: 900`, `reviewer:
 
 Override, disable, or add subagent roles via `agentOverrides`. Built-in and custom roles are treated equally — all descriptions, examples, and decision triggers feed into the LLM's prompt dynamically.
 
+The built-in roles are defined in [`src/roles.ts`](src/roles.ts) — read them as reference templates when overriding. Each entry shows the exact shape and wording of every field (`role`, `description`, `examples`, `decisionTrigger`, `tools`/`subagentRoles`, `systemPrompt`, `timeout`, `fallbackRole`), so you can copy the built-in closest to what you want, paste it under `agentOverrides`, and adjust from a known-good starting point rather than writing a role from scratch.
+
 ```json
 {
   "subagent": {
@@ -172,7 +176,7 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
 
 Configuring both on the same role is an error — the role is skipped with an error notification at session start.
 
-**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role the whole run is retried on after a provider error; unset means no retry — see [Fallback observability](#fallback-observability)).
+**Optional fields:** `subagentRoles` (roles this role can spawn via delegate; absent means any available role, mirroring the `tools` default — declare it explicitly when a restricted role grants `subagent_delegate`), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role the whole run is retried on after a provider error; unset means no retry — see [Fallback observability](#fallback-observability)).
 
 Invalid custom roles (missing required fields) are skipped with an error notification at session start.
 
@@ -236,10 +240,10 @@ Three execution properties, kept separate:
 | Tool | Purpose | Returns to the model |
 |------|---------|---------------------|
 | `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. Checking a terminal run **collects** it: the output is returned once and the run leaves the registry |
+| `subagent_wait(ids?, timeout?)` | Block until **all** listed runs finish (omit `ids` for all current background runs) | A per-run roll call — one `id (role): state (turns, elapsed, tokens, cost)` line per run, never the output; on timeout, the same roll call (live runs carry usage so far) under a timeout header |
+| `subagent_check(id)` | One-shot snapshot of a single run | `queued` / `running` + current activity, elapsed/budget, and usage so far / the **full output** with a usage footer once finished / failure reason + partial output + usage on failed or cancelled. Idempotent: re-delivers the same terminal snapshot — the run stays in the registry for the whole session |
 | `subagent_steer(id, message)` | Queue a mid-run correction into one running run (typically right after a check revealed it heading down a wrong path) | Confirmation that the steer is queued — delivered after the child's current tool batch, before its next LLM call; the run keeps its progress |
-| `subagent_cancel(id, reason?)` | Kill one live (queued/running) run | Confirmation with the partial-output size — the run settles as `cancelled` (warning styling, same family as timeout/budget) with the reason in its error message; the partial output stays in the registry for `subagent_check` to collect |
+| `subagent_cancel(id, reason?)` | Kill one live (queued/running) run | Confirmation — the same roll-call line wait uses, plus a pointer to check for the partial output; the run settles as `cancelled` (warning styling, same family as timeout/budget) with the reason in its error message |
 
 Typical flow:
 
@@ -263,9 +267,9 @@ Semantics worth knowing:
 - **Results are pull-only for the model.** A purple completion notice is shown to the user, but nothing delivers the result to the model or wakes it up. The notice is a pure notification in the same visual family as pi's `[compaction]` card — a `[subagent] id (role) outcome` header with the bare task preview beneath, each line truncated to the terminal width — and deliberately unlike the tool rows, so it never reads as model behavior; the result itself never appears in the notice, only in `subagent_check` (model) or `/subagent:status` (user). The model owns the collection point: `subagent_wait`, then `subagent_check` each run. The inbox reminder (below) lists runs not yet checked on the active branch on every request, but it never pushes results.
 - **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.
 - **Idempotent check, session-tree delivery state:** `subagent_check` re-delivers the same terminal snapshot on every call — runs stay in the registry for the whole session, so no result can ever be stranded by branch navigation or compaction. Whether a run still needs collecting is not tracked in the registry: it derives from the session tree itself. The session is append-only, so branching back past a check entry drops it from the active path — the inbox reminder re-arms and the model simply checks again (the id still resolves; the run is still there). Branching forward to the original branch restores the check entry and silences the reminder again.
-- **Cancellation keeps the partial output.** `subagent_cancel(id, reason?)` kills the child (SIGTERM, escalating to SIGKILL) and settles the run as `cancelled` — its own stop reason in the same family as `timeout`/`budget_exceeded` (TUI warning styling ⏹, not the error-red ✗ of real failures) — with whatever it had produced. The `reason` becomes the error message verbatim, so whoever reads the partial output later via `subagent_check` — or the audit history — sees `cancelled — <reason>`; the source is distinguishable too (`user: ...` for `/subagent:cancel`, the model's own words for the tool, `session shutdown` for reaping). Cancelling does not remove the run: `subagent_check` still returns the partial output, and `subagent_wait` reports the run as `cancelled (partial output kept)`.
+- **Cancellation keeps the partial output.** `subagent_cancel(id, reason?)` kills the child (SIGTERM, escalating to SIGKILL) and settles the run as `cancelled` — its own stop reason in the same family as `timeout`/`budget_exceeded` (TUI warning styling ⏹, not the error-red ✗ of real failures) — with whatever it had produced. The `reason` becomes the error message verbatim, so whoever reads the partial output later via `subagent_check` — or the audit history — sees `cancelled — <reason>`; the source is distinguishable too (`user: ...` for `/subagent:cancel`, the model's own words for the tool, `session shutdown` for reaping). Cancelling does not remove the run: `subagent_check` still returns the partial output, and `subagent_wait` reports the run as `cancelled` with its usage stats.
 - **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the runs not yet checked on the active branch (queued, running, and finished-but-unchecked alike, including cancelled ones — shown as `cancelled — <reason>`), injected at a cache-stable head position. Runs missing from the list were already checked on this branch — so a finished run the model forgot to check keeps surfacing until it does. Branch navigation keeps this honest: the list derives from the session tree, not registry bookkeeping.
-- **`timeout_ms` is optional.** Without it, `subagent_wait` blocks until every run finishes; each run is still bounded by its own role timeout.
+- **`timeout` (seconds) is optional — omitting it is the normal usage.** `subagent_wait` blocks until every run finishes, with each run bounded by its own role timeout; subagent runs typically take minutes. Set a timeout only when the waiter must resume soon (e.g. to report progress to the user).
 - 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.
@@ -322,7 +326,7 @@ Each path is injected as an independent `<file name="...">` block in the child's
 
 ### Budget enforcement
 
-`maxTurns` / `maxCost` cap a run. When exceeded, the child is killed and the last completed output is returned with `stopReason: "budget_exceeded"`. Budget stops are **intentional finishes** — the output is partial but valid: the TUI marks the run with a ⏲ line stating the reason, `subagent_wait` reports `finished (budget exceeded — output is partial)`, and the tool result (and `subagent_check`) append a `--- Budget exceeded (...) ---` note so the model knows to treat the output as partial. Defaults are unlimited (`0`); set global defaults in config or per-role overrides in `agentOverrides`. Negative values are normalized to `0`.
+`maxTurns` / `maxCost` cap a run. When exceeded, the child is killed and the last completed output is returned with `stopReason: "budget_exceeded"`. Budget stops are **intentional finishes** — the output is partial but valid: the TUI marks the run with a ⏲ line stating the reason, and the tool result (and `subagent_check`) append a `--- Budget exceeded (...) ---` note so the model knows to treat the output as partial (`subagent_wait` shows them as plain `finished` with usage stats — the roll call carries no notes, check is the complete view). Defaults are unlimited (`0`); set global defaults in config or per-role overrides in `agentOverrides`. Negative values are normalized to `0`.
 
 ### Oversized outputs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "3.1.0",
+  "version": "3.2.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

@@ -30,6 +30,7 @@ import {
   formatCancelText,
   formatCheckText,
   formatFallbackNote,
+  formatRunLine,
   formatTimePart,
   formatUsageFooter,
   freezeFrame,
@@ -42,7 +43,7 @@ import { startSubagentRun, type RunHandle } from "./run.ts";
 import { buildInboxReminder, injectReminder } from "./reminder.ts";
 import { serializeInheritedConversation } from "./inheritance.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render.ts";
-import { createViewPanel } from "./view.ts";
+import { createViewPanel, filterDeliveredRuns } from "./view.ts";
 import {
   createSteerCallRender,
   renderBackgroundDelegateCall,
@@ -59,6 +60,11 @@ import {
 
 const BACKGROUND_COMPLETION_MESSAGE_TYPE = "subagent-completion";
 
+/** Refresh ceiling for the /subagent:view delivered-ids cache (ms). The panel
+ * re-renders on every animation tick (~150ms); deriving delivery from the
+ * session tree is throttled so the overlay stays cheap. */
+const VIEW_DELIVERED_CACHE_MS = 1000;
+
 // ── Extension entry ────────────────────────────────────────────────
 
 export default function subagentExtension(pi: ExtensionAPI) {
@@ -178,7 +184,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       "BACKGROUND DELEGATION:",
       "",
       "- Use it only when you have your own work this turn (including an ongoing discussion with the user) while the run executes; otherwise let the call block and return the result directly.",
-      "- Results are pull-only for the model — a completion notice is shown to the user, but nothing wakes you or delivers the result. Dispatching means owning the collection point: finish your own work, then subagent_check(id) for each result. Use subagent_wait(ids) to block until the run finish.",
+      "- Results are pull-only for the model — a completion notice is shown to the user, but nothing wakes you or delivers the result. Dispatching means owning the collection point: finish your own work, then subagent_check(id) for each result. Use subagent_wait(ids) to block until runs finish.",
       "- Cancel a run you no longer need with subagent_cancel(id) — the child stops and its partial output stays in the registry for subagent_check to collect.",
       "- Background delegation works only in the top-level session.",
     );
@@ -497,8 +503,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
         // 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}` +
-            fallbackNote;
+            `${params.role}: failed — ${result.errorMessage || result.stderr || "unknown error"}\n\nPartial output:\n${result.output}` +
+            fallbackNote +
+            formatUsageFooter(result);
           emit([result], failedText);
           return {
             content: [{ type: "text", text: failedText }],
@@ -506,7 +513,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
           };
         }
 
-        const finalText = result.output + budgetNote + fallbackNote + formatUsageFooter(result);
+        const finalText = `${params.role}: finished\n\n${result.output}${budgetNote}${fallbackNote}${formatUsageFooter(result)}`;
         emit([result], finalText);
         return {
           content: [{ type: "text", text: finalText }],
@@ -543,7 +550,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_wait",
     label: "Wait for background subagents",
     description:
-      "Block until one or more background subagents (started via subagent_delegate with background: true) finish. Omit ids to wait for ALL current background runs. Returns ONLY each run's final status — one `id (role): finished/failed` line per run, never the results; fetch them afterwards with subagent_check. If timeout_ms elapses before every run finishes, returns an error listing per-run statuses. Cancelling the wait never cancels the runs — to stop a run, use subagent_cancel(id).",
+      "Block until one or more background subagents (started via subagent_delegate with background: true) finish. Omit ids to wait for ALL current background runs. Returns a per-run roll call — one `id (role): state (turns, elapsed, tokens, cost)` line per run, never the output; fetch it afterwards with subagent_check. If timeout elapses before every run finishes, returns the same roll call (live runs carry usage so far) under a timeout header. Cancelling the wait never cancels the runs — to stop a run, use subagent_cancel(id).",
     promptSnippet: "Wait for background subagents to finish",
     parameters: Type.Object({
       ids: Type.Optional(
@@ -553,10 +560,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
             "Run ids returned by background delegate calls. Omit to wait for all current background runs.",
         }),
       ),
-      timeout_ms: Type.Optional(
+      timeout: Type.Optional(
         Type.Number({
           description:
-            "Max time to wait in milliseconds. Omit to wait until all runs finish (each run still has its own role timeout).",
+            "Max time to wait in seconds. Subagent runs typically take minutes — omit this and let the wait block until they finish (each run's own role timeout is the ceiling); that is the normal usage. Set it only when you must resume soon, e.g. to report progress to the user.",
         }),
       ),
     }),
@@ -576,8 +583,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
         );
       }
       const runs = ids.map((id) => backgroundRuns.get(id)!);
-      const timeoutMs =
-        typeof params.timeout_ms === "number" && params.timeout_ms > 0 ? params.timeout_ms : 0;
+      const timeoutMs = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1000 : 0;
 
       // ── Live mirror: forward combined snapshots into this tool row ──
       const entries = () => runs.map((r) => ({ id: r.id, role: r.role, result: r.snapshot }));
@@ -642,20 +648,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
         for (const u of unsubscribers) u();
       }
 
-      // Status line per run — same `id (role): state` shape check uses, so
-      // the model can map ids to roles from wait output alone. Budget stops
-      // report "finished" but their output is partial; cancelled runs keep
-      // their partial output in the registry for check — flag both inline.
-      const perId = () =>
-        runs
-          .map((r) =>
-            r.result?.stopReason === "budget_exceeded"
-              ? `${r.id} (${r.role}): ${r.state} (budget exceeded — output is partial)`
-              : r.result?.stopReason === "cancelled"
-                ? `${r.id} (${r.role}): cancelled (partial output kept)`
-                : `${r.id} (${r.role}): ${r.state}`,
-          )
-          .join("\n");
+      // One roll-call line per run — the same `id (role): state (stats)`
+      // shape cancel uses, so the model can map ids to roles and gauge
+      // task scale from wait output alone; the output itself stays
+      // check's to deliver. Timeout reuses the same lines: live runs carry
+      // their so-far usage.
+      const perId = () => runs.map((r) => formatRunLine(r.id, r.role, r.snapshot)).join("\n");
       if (timedOut) {
         const unfinished = runs.filter((r) => r.state === "queued" || r.state === "running");
         const text =
@@ -680,7 +678,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. Idempotent: checking a terminal run again re-delivers the same snapshot, so the result stays reachable even after branch navigation or compaction. One id per call because results can be large.",
+      "Get an instant snapshot of ONE background subagent run: queued / running (with current activity, elapsed/budget, and usage so far) / finished (with the full output and usage) / failed or cancelled (with reason, partial output, and usage). Does not wait — use subagent_wait for that. Idempotent: checking a terminal run again re-delivers the same snapshot, so the result stays reachable even after branch navigation or compaction. 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" }),
@@ -818,7 +816,24 @@ export default function subagentExtension(pi: ExtensionAPI) {
     handler: async (_args, ctx) => {
       // Union of every known run: the background registry plus live
       // in-flight runs (foreground delegate calls included). Dedupe by id —
-      // background runs appear in both.
+      // background runs appear in both. Terminal runs stay listed until
+      // their result is delivered (subagent_check on the active branch,
+      // derived from the session tree — same source of truth as the inbox
+      // reminder), then leave the view: it is for live watching and pending
+      // collection, not an archive. Delivery re-derivation is throttled
+      // because the panel re-renders on every animation tick.
+      const deliveredCache = { ids: new Set<string>(), at: 0 };
+      const deliveredIds = (): Set<string> => {
+        if (Date.now() - deliveredCache.at > VIEW_DELIVERED_CACHE_MS) {
+          try {
+            deliveredCache.ids = collectDeliveredIds(ctx.sessionManager.buildContextEntries());
+          } catch {
+            /* keep the previous set */
+          }
+          deliveredCache.at = Date.now();
+        }
+        return deliveredCache.ids;
+      };
       const runsProvider = () => {
         const seen = new Set<string>();
         const out: RunHandle[] = [];
@@ -828,7 +843,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
             out.push(r);
           }
         }
-        return out;
+        return filterDeliveredRuns(out, deliveredIds());
       };
       if (runsProvider().length === 0) {
         ctx.ui.notify("No subagent runs yet.", "info");
@@ -1035,8 +1050,8 @@ export default function subagentExtension(pi: ExtensionAPI) {
         const result = await run.promise;
         lines.push(
           result.usage.turns > 0 || result.output
-            ? `\u2717 ${run.id} (${run.role}): cancelled after ${result.usage.turns} turn${result.usage.turns === 1 ? "" : "s"} — partial output kept (subagent_check / history)`
-            : `\u2717 ${run.id} (${run.role}): cancelled (nothing had run yet)`,
+            ? `✗ ${formatRunLine(run.id, run.role, result)} — partial output kept`
+            : `✗ ${formatRunLine(run.id, run.role, result)}`,
         );
       }
       ctx.ui.notify(lines.join("\n"), "info");

package/src/render-async.ts

@@ -341,11 +341,11 @@ export const renderBackgroundDelegateResult: RenderResultFn = (result, { expande
 
 export const renderWaitCall: RenderCallFn = (args, theme) => {
   const ids = ((args as any).ids as string[] | undefined) ?? [];
-  const timeoutMs = ((args as any).timeout_ms as number | undefined) ?? 0;
+  const timeoutSec = ((args as any).timeout as number | undefined) ?? 0;
   const label = ids.length > 0 ? ids.join(", ") : "(all)";
   // Show the wait ceiling up front — the user should know how long this row
   // can block before it gives up. Omitted timeout = wait until runs finish.
-  const cap = timeoutMs > 0 ? ` \u2264${Math.max(1, Math.round(timeoutMs / 1000))}s` : "";
+  const cap = timeoutSec > 0 ? ` \u2264${Math.max(1, Math.round(timeoutSec))}s` : "";
   const text =
     theme.fg("toolTitle", theme.bold("subagent_wait ")) +
     theme.fg("accent", label) +

package/src/roles.ts

@@ -40,17 +40,24 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     fallbackRole: "default",
     timeout: 3600,
     description:
-      "READ-ONLY code review & analysis — audit code, assess architecture, review diffs, run tests for evidence. Reports findings and suggested fixes but never implements them.",
+      "READ-ONLY code review & analysis — audit code, assess architecture, review diffs, run tests for evidence. Reports findings and suggested fixes but never implements them. Can delegate to explorer/researcher.",
     examples: [
       "Review the error handling in src/api/ for security issues",
       "Audit this PR diff for performance regressions",
     ],
     decisionTrigger: "Task audits or reviews code quality?",
-    tools: ["read", "bash", "grep", "find"],
+    tools: ["read", "bash", "grep", "find", "subagent_delegate"],
+    subagentRoles: ["explorer", "researcher"],
     systemPrompt: [
       "Senior code reviewer. READ-ONLY — you must NOT modify any file.",
       "If the task asks you to fix or implement, do NOT do it: report findings and suggested fixes, and state that implementation is out of scope for this role.",
       "Run only read-only commands (git diff/log/show, test runs). Never use sed, tee, echo >, or any write command.",
+      "",
+      "## Delegation",
+      "You have a `subagent_delegate` tool — spend it to keep your review context focused:",
+      "- subagent_delegate(role=explorer) to map unfamiliar code touched by the change under review",
+      "- subagent_delegate(role=researcher) to verify third-party library APIs/versions against official docs",
+      "Don't delegate the review itself — reading and judging the code is your job.",
       "Provide evidence-backed findings with file:line references.",
       "",
       "Output format (prioritize critical issues first):",

package/src/utils.test.ts

@@ -37,6 +37,7 @@ import {
   formatBudgetNote,
   formatCheckText,
   formatCancelText,
+  formatRunLine,
   formatTimePart,
   freezeFrame,
   createThrottler,
@@ -654,13 +655,14 @@ describe("background run helpers", () => {
     assert.equal(describeCurrentActivity(withTool), "$ ls");
   });
 
-  test("formatUsageFooter renders turns, tokens, cost, and model", () => {
+  test("formatUsageFooter renders turns, elapsed, tokens, cost, and model", () => {
     assert.equal(formatUsageFooter(baseResult()), "");
     const r = baseResult({
+      elapsedMs: 135000,
       usage: { input: 1200, output: 300, cacheRead: 0, cacheWrite: 0, cost: 0.5, contextTokens: 0, turns: 2 },
       model: "test/model-x",
     });
-    assert.equal(formatUsageFooter(r), "\n\n--- 2 turns \u21911.2k \u2193300 $0.5000 test/model-x ---");
+    assert.equal(formatUsageFooter(r), "\n\n--- 2 turns ~135s \u21911.2k \u2193300 $0.5000 test/model-x ---");
   });
 
   test("formatUsageStats adds cache and peak-context figures the footer omits", () => {
@@ -671,7 +673,7 @@ describe("background run helpers", () => {
     );
     // Footer stays lean — no cache/context parts.
     assert.equal(
-      formatUsageFooter({ usage, model: "test/model-x" }),
+      formatUsageFooter(baseResult({ usage, model: "test/model-x" })),
       "\n\n--- 2 turns \u21911.2k \u2193300 $0.5000 test/model-x ---",
     );
   });
@@ -706,45 +708,84 @@ describe("background run helpers", () => {
     assert.match(formatCheckText("sub-1", "explorer", baseResult()), /^sub-1 \(explorer\): finished\n\nok$/);
   });
 
-  test("formatCheckText renders cancelled with the bare reason and partial output", () => {
+  test("formatCheckText running carries elapsed/budget in the head and a usage footer", () => {
+    const r = runningFrame();
+    r.startTime = Date.now() - 135000;
+    r.budgetMs = 300000;
+    r.usage = { input: 8000, output: 900, cacheRead: 0, cacheWrite: 0, cost: 0.02, contextTokens: 0, turns: 2 };
+    const text = formatCheckText("sub-1", "explorer", r);
+    assert.match(text, /^sub-1 \(explorer\): running — waiting for first event \(135s\/300s\)/);
+    assert.match(text, /\n\n--- 2 turns \u21918.0k \u2193900 \$0\.0200 ---$/);
+  });
+
+  test("formatRunLine is the shared roll-call line for wait and cancel", () => {
+    assert.equal(formatRunLine("sub-1", "explorer", queuedFrame()), "sub-1 (explorer): queued");
+    assert.equal(formatRunLine("sub-1", "explorer", baseResult()), "sub-1 (explorer): finished");
+    const finished = baseResult({
+      elapsedMs: 120000,
+      usage: { input: 12000, output: 1000, cacheRead: 0, cacheWrite: 0, cost: 0.01, contextTokens: 0, turns: 3 },
+    });
+    assert.equal(
+      formatRunLine("sub-1", "explorer", finished),
+      "sub-1 (explorer): finished (3 turns ~120s \u219112k \u21931.0k $0.0100)",
+    );
+  });
+
+  test("formatCheckText renders cancelled with reason, partial output, and usage", () => {
     assert.match(
       formatCheckText(
         "sub-1",
         "explorer",
-        baseResult({ exitCode: 1, stopReason: "cancelled", errorMessage: "user: wrong direction" }),
+        baseResult({
+          exitCode: 1,
+          stopReason: "cancelled",
+          errorMessage: "user: wrong direction",
+          elapsedMs: 45000,
+          usage: { input: 1000, output: 200, cacheRead: 0, cacheWrite: 0, cost: 0.1, contextTokens: 0, turns: 3 },
+        }),
       ),
-      /^sub-1 \(explorer\): cancelled — user: wrong direction\n\nPartial output:\nok$/,
+      /^sub-1 \(explorer\): cancelled — user: wrong direction\n\nPartial output:\nok\n\n--- 3 turns ~45s \u21911.0k \u2193200 \$0\.1000 ---$/,
+    );
+    // Queue-time cancel: never spawned — nothing to show past the head.
+    assert.equal(
+      formatCheckText(
+        "sub-2",
+        "worker",
+        baseResult({ exitCode: 1, stopReason: "cancelled", errorMessage: "still queued (user: x)" }),
+      ),
+      "sub-2 (worker): cancelled — never started",
     );
   });
 
   test("formatCancelText distinguishes never-started cancels from mid-run cancels", () => {
     // Never-started cancel (gate/model-resolution phase): terminal frame has
-    // NO elapsedMs — nothing ran. Mirrors the real terminal-frame shape:
-    // startTime never survives (live-frame-only field), duration freezes
-    // into elapsedMs.
-    assert.match(
-      formatCancelText("sub-1", "explorer", baseResult({ exitCode: -1, output: "", usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 } })),
-      /^sub-1 \(explorer\): cancelled — never started, no partial output\. subagent_check\(sub-1\) clears the registry entry\.$/,
+    // no elapsedMs and zero usage — nothing ran. Mirrors the real terminal
+    // shape (run.ts settles aborts via inputFrame(1, false)).
+    assert.equal(
+      formatCancelText("sub-1", "explorer", baseResult({ exitCode: 1, stopReason: "cancelled", output: "" })),
+      "sub-1 (explorer): cancelled — never started",
     );
     // Mid-run cancel: real terminal shape — elapsedMs frozen, no startTime.
     const midRun = baseResult({
-      exitCode: -1,
+      exitCode: 1,
+      stopReason: "cancelled",
       elapsedMs: 45000,
       output: "partial findings",
       usage: { input: 1000, output: 200, cacheRead: 0, cacheWrite: 0, cost: 0.1, contextTokens: 0, turns: 3 },
     });
-    assert.match(
+    assert.equal(
       formatCancelText("sub-2", "worker", midRun),
-      /^sub-2 \(worker\): cancelled after 3 turns \(~45s\) — partial output \(16 chars\) kept in the registry; subagent_check\(sub-2\) returns it once\.$/,
+      "sub-2 (worker): cancelled (3 turns ~45s \u21911.0k \u2193200 $0.1000) — partial output kept; subagent_check(sub-2) returns it.",
     );
-    // Aborted before the first completed turn: "under a turn", not "0 turns".
+    // Aborted before the first completed turn: elapsed-only stats.
     const underATurn = baseResult({
-      exitCode: -1,
+      exitCode: 1,
+      stopReason: "cancelled",
       elapsedMs: 2000,
       output: "",
-      usage: { input: 1000, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0.05, contextTokens: 0, turns: 0 },
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
     });
-    assert.match(formatCancelText("sub-3", "worker", underATurn), /cancelled after under a turn \(~2s\)/);
+    assert.equal(formatCancelText("sub-3", "worker", underATurn), "sub-3 (worker): cancelled (~2s)");
   });
 
   test("formatCheckText flags budget-stopped runs as partial on the finished line", () => {

package/src/utils.ts

@@ -45,9 +45,8 @@ export function formatInheritedConversationInput(chars: number, truncated: boole
 }
 
 /**
- * Usage parts shared by the TUI stats line and the LLM usage footer.
- * `withCache` adds the cache-read/write and peak-context figures (TUI only —
- * the LLM footer stays lean).
+ * Usage parts for the TUI stats line. `withCache` adds the
+ * cache-read/write and peak-context figures (TUI only).
  */
 function usageParts(usage: SubagentUsage, model: string | undefined, withCache: boolean): string[] {
   const parts: string[] = [];
@@ -63,6 +62,31 @@ function usageParts(usage: SubagentUsage, model: string | undefined, withCache:
   if (model) parts.push(model);
   return parts;
 }
+/**
+ * Usage-stat segments for every LLM-facing run line: turns, elapsed,
+ * tokens, cost — model last when requested. Empty segments are omitted; an
+ * empty array means nothing measurable ran. `withElapsed` is off where
+ * elapsed already lives elsewhere in the same view (check's running head
+ * shows it as `42s/900s` next to the activity).
+ */
+function statsParts(
+  r: { usage: SubagentUsage; exitCode: number; startTime?: number; elapsedMs?: number },
+  opts: { withElapsed?: boolean; model?: string } = {},
+): string[] {
+  const parts: string[] = [];
+  if (r.usage.turns) parts.push(`${r.usage.turns} turn${r.usage.turns > 1 ? "s" : ""}`);
+  if (opts.withElapsed) {
+    const secs = elapsedSeconds(r);
+    if (secs != null && secs > 0) parts.push(`~${secs}s`);
+  }
+  if (r.usage.input) parts.push(`↑${formatTokens(r.usage.input)}`);
+  if (r.usage.output) parts.push(`↓${formatTokens(r.usage.output)}`);
+  if (r.usage.cost) parts.push(`$${r.usage.cost.toFixed(4)}`);
+  // The model is an annotation on the stats, never a stat itself — skip it
+  // when nothing measurable ran.
+  if (opts.model && parts.length > 0) parts.push(opts.model);
+  return parts;
+}
 
 export function formatUsageStats(usage: SubagentUsage, model?: string): string {
   return usageParts(usage, model, true).join(" ");
@@ -602,12 +626,32 @@ export function describeCurrentActivity(r: { activityLog: ActivityEntry[] }): st
   return formatToolCall(last.toolName ?? "?", last.args ?? {}, (_color, text) => text);
 }
 
-/** Footer appended to terminal results for the main model: `\n\n--- 3 turns ↑12k ↓1k $0.01 model ---` (empty when nothing to show). */
-export function formatUsageFooter(r: { usage: SubagentUsage; model?: string }): string {
-  const parts = usageParts(r.usage, r.model, false);
+/**
+ * Terminal-result footer for full views (check, foreground delegate):
+ * `\n\n--- 3 turns ~45s ↑12k ↓1k $0.01 model ---` (empty when nothing to show).
+ */
+export function formatUsageFooter(r: SubagentResult): string {
+  const parts = statsParts(r, { withElapsed: true, model: r.model });
   return parts.length > 0 ? `\n\n--- ${parts.join(" ")} ---` : "";
 }
 
+/**
+ * One-line roll-call status shared by wait's per-run lines and cancel's
+ * confirmation: `id (role): state (stats)` — state plus usage stats (turns,
+ * elapsed, tokens, cost), nothing else; no output, no model, no notes.
+ * check is the complete view.
+ */
+export function formatRunLine(id: string, role: string, r: SubagentResult): string {
+  const state = r.stopReason === "cancelled" ? "cancelled" : deriveRunState(r);
+  const head = `${id} (${role}): ${state}`;
+  // Queue-time cancels never spawned: nothing measurable ran.
+  if (state === "cancelled" && r.elapsedMs == null && !r.usage.turns) {
+    return `${head} — never started`;
+  }
+  const parts = statsParts(r, { withElapsed: true });
+  return parts.length > 0 ? `${head} (${parts.join(" ")})` : head;
+}
+
 /** Fallback provenance note appended to terminal results (empty when no retry happened). */
 export function formatFallbackNote(r: { fallbackFrom?: FallbackFrom; model?: string }): string {
   return r.fallbackFrom
@@ -631,27 +675,40 @@ export function formatCheckText(id: string, role: string, r: SubagentResult): st
   const state = deriveRunState(r);
   const head = `${id} (${role})`;
   if (state === "queued") return `${head}: queued — waiting for a concurrency slot.`;
-  if (state === "running") return `${head}: running — ${describeCurrentActivity(r)}`;
+  if (state === "running") {
+    // Elapsed/budget live in the head next to the activity (`42s/900s`); the
+    // footer carries turns/tokens/cost so elapsed is never shown twice.
+    const time = formatTimePart(r);
+    const parts = statsParts(r, { model: r.model });
+    return (
+      `${head}: running — ${describeCurrentActivity(r)}${time ? ` (${time})` : ""}` +
+      (parts.length > 0 ? `\n\n--- ${parts.join(" ")} ---` : "")
+    );
+  }
   if (r.stopReason === "cancelled") {
     // errorMessage is the bare abort reason ("user: ..." / "session shutdown")
     // — the "cancelled" prefix here is the only wrapper it gets.
-    return `${head}: cancelled — ${r.errorMessage || "no reason recorded"}\n\nPartial output:\n${r.output}${formatFallbackNote(r)}`;
+    if (r.elapsedMs == null && !r.usage.turns) return `${head}: cancelled — never started`;
+    return (
+      `${head}: cancelled — ${r.errorMessage || "no reason recorded"}\n\nPartial output:\n${r.output}` +
+      formatFallbackNote(r) +
+      formatUsageFooter(r)
+    );
   }
   if (state === "failed") {
-    return `${head}: failed — ${r.errorMessage || r.stderr || "unknown error"}\n\nPartial output:\n${r.output}${formatFallbackNote(r)}`;
+    return (
+      `${head}: failed — ${r.errorMessage || r.stderr || "unknown error"}\n\nPartial output:\n${r.output}` +
+      formatFallbackNote(r) +
+      formatUsageFooter(r)
+    );
   }
   return `${head}: finished\n\n${r.output}${formatBudgetNote(r)}${formatFallbackNote(r)}${formatUsageFooter(r)}`;
 }
 
 /**
- * Cancel confirmation text for the /subagent:cancel command: short, no output
- * dump — the partial output is check's job to return. Always points at check
- * so the user knows where the partial output lives.
- */
-/**
- * Compact stop summary shared by the cancel tool text and its TUI row:
- * `cancelled after 3 turns (~45s)` / `cancelled after under a turn (~2s)` /
- * `cancelled — never started` (never spawned: no elapsedMs on the frame).
+ * Compact stop summary for the cancel TUI row: `cancelled after 3 turns
+ * (~45s)` / `cancelled after under a turn (~2s)` / `cancelled — never
+ * started` (never spawned: no elapsedMs on the frame).
  */
 export function cancelStopSummary(r: SubagentResult): string {
   if (r.elapsedMs == null) return "cancelled — never started";
@@ -662,19 +719,15 @@ export function cancelStopSummary(r: SubagentResult): string {
 }
 
 /**
- * Cancel confirmation text: short, no output dump — the partial output is
- * check's job to return. Always points at check so the model fetches the
- * partial output it is entitled to.
+ * Cancel confirmation: the same roll-call line wait uses (state + usage
+ * stats) plus a pointer to check — cancel never dumps the partial output
+ * itself (layer contract: cancel intervenes, check fetches).
  */
 export function formatCancelText(id: string, role: string, r: SubagentResult): string {
-  const head = `${id} (${role})`;
-  if (r.elapsedMs == null) {
-    return `${head}: cancelled — never started, no partial output. subagent_check(${id}) clears the registry entry.`;
-  }
-  return (
-    `${head}: ${cancelStopSummary(r)} — partial output (${r.output.length} chars) ` +
-    `kept in the registry; subagent_check(${id}) returns it once.`
-  );
+  const line = formatRunLine(id, role, r);
+  return r.usage.turns > 0 || r.output.length > 0
+    ? `${line} — partial output kept; subagent_check(${id}) returns it.`
+    : line;
 }
 
 /** Freeze a live frame into a static snapshot: stop the elapsed clock and fold the open pause into grace. */

package/src/view.test.ts

@@ -0,0 +1,45 @@
+import test from "node:test";
+import assert from "node:assert";
+import { filterDeliveredRuns, sortViewRuns } from "./view.ts";
+import type { RunHandle } from "./run.ts";
+
+// ── Fakes ──────────────────────────────────────────────────────────
+
+function fakeHandle(id: string, state: RunHandle["state"]): RunHandle {
+  return { id, state } as unknown as RunHandle;
+}
+
+// ── filterDeliveredRuns ────────────────────────────────────────────
+
+test("filterDeliveredRuns drops delivered terminal runs, keeps live and undelivered", () => {
+  const running = fakeHandle("sub-1", "running");
+  const queued = fakeHandle("sub-2", "queued");
+  const finishedUndelivered = fakeHandle("sub-3", "finished");
+  const finishedDelivered = fakeHandle("sub-4", "finished");
+  const failedDelivered = fakeHandle("sub-5", "failed");
+
+  const out = filterDeliveredRuns(
+    [running, queued, finishedUndelivered, finishedDelivered, failedDelivered],
+    new Set(["sub-4", "sub-5"]),
+  );
+
+  assert.deepEqual(
+    out.map((r) => r.id),
+    ["sub-1", "sub-2", "sub-3"],
+  );
+});
+
+// ── sortViewRuns ───────────────────────────────────────────────────
+
+test("sortViewRuns ranks running before finished, each group by id", () => {
+  const out = sortViewRuns([
+    fakeHandle("sub-3", "finished"),
+    fakeHandle("sub-2", "running"),
+    fakeHandle("sub-4", "running"),
+    fakeHandle("sub-1", "failed"),
+  ]);
+  assert.deepEqual(
+    out.map((r) => r.id),
+    ["sub-2", "sub-4", "sub-1", "sub-3"],
+  );
+});

package/src/view.ts

@@ -23,8 +23,8 @@
  * Steer input is modal so keys never conflict with the editor: browse mode
  * owns navigation; `s` opens the editor (Enter sends and returns to browse,
  *    Esc cancels and clears). Esc in browse closes the overlay; Tab cycles
- * the focused run and resets scrolls (activity re-pins, brief returns to
- * the top).
+ *    the focused run and resets its view — page back to activity, scrolls
+ *    re-pinned.
  *
  * Layout: a centered screen overlay (overlay:true) occupying most of the
  * terminal, framed with a thin border. An embedded Editor accepts steering
@@ -119,6 +119,19 @@ export function sortViewRuns(runs: RunHandle[]): RunHandle[] {
   return [...runs].sort((a, b) => rank(a) - rank(b) || a.id.localeCompare(b.id));
 }
 
+/**
+ * Drop terminal runs whose result is already in the conversation — delivered
+ * by subagent_check on the active branch (the same session-tree source of
+ * truth as the inbox reminder). Live runs and undelivered terminal runs
+ * stay: the view is for live watching and pending collection, not an
+ * archive.
+ */
+export function filterDeliveredRuns(runs: RunHandle[], delivered: Set<string>): RunHandle[] {
+  return runs.filter(
+    (r) => (r.state !== "finished" && r.state !== "failed") || !delivered.has(r.id),
+  );
+}
+
 export class SubagentViewPanel implements Component, Focusable {
   focused = true;
 
@@ -180,8 +193,8 @@ export class SubagentViewPanel implements Component, Focusable {
   }
 
   /** Resolve the focused run by id; stable across sort-order reshuffles
-   *  (e.g. a run finishing re-ranks the list). Scroll state resets only when
-   *  the focused run actually changes. */
+   *  (e.g. a run finishing re-ranks the list). The focused run's view state
+   *  (page + scrolls) resets only when the focused run actually changes. */
   private focusedRun(): RunHandle | undefined {
     const runs = sortViewRuns(this.runsProvider());
     if (runs.length === 0) {
@@ -192,12 +205,15 @@ export class SubagentViewPanel implements Component, Focusable {
     if (!run) {
       run = runs[0];
       this.focusId = run.id;
-      this.resetScrolls();
+      this.resetRunView();
     }
     return run;
   }
 
-  private resetScrolls(): void {
+  /** Reset the focused run's view state: page back to activity, activity
+   *  pinned to the end (auto-follow), brief at the top. */
+  private resetRunView(): void {
+    this.page = "activity";
     this.activityTop = null;
     this.briefTop = 0;
   }
@@ -206,10 +222,12 @@ export class SubagentViewPanel implements Component, Focusable {
     const runs = sortViewRuns(this.runsProvider());
     if (runs.length < 2) return;
     const idx = runs.findIndex((r) => r.id === this.focusId);
-    const next = runs[((idx >= 0 ? idx : 0) + 1) % runs.length];
+    // Focus id gone from the list: fall back to the first run, same as
+    // focusedRun() — not to the second.
+    const next = idx < 0 ? runs[0] : runs[(idx + 1) % runs.length];
     if (next.id === this.focusId) return;
     this.focusId = next.id;
-    this.resetScrolls();
+    this.resetRunView();
     this.tui.requestRender();
   }