@henryqw/pi-subagent 11.1.0 → 12.0.1

package/README.md

@@ -1,13 +1,13 @@
 # `@henryqw/pi-subagent`
 
-Main, the parent Pi session, can delegate bounded single, parallel, and chained tasks to isolated child Roles. It also provides a fixed Git Flow for independent implementation work.
+Delegate bounded work from Main to isolated Pi Roles, or run independent implementation units through a fixed Git Flow.
 
 ![Pi showing six delegated tasks running in parallel](./example.png)
 
 ## Why
 
-- **Created for**: Delegate bounded work to isolated child Pi processes without losing Main's context.
-- **Advantage**: Generic delegation and Git Flow use the same Role settings.
+- **Created for**: Pi users who want focused child work without loading every detail into Main.
+- **Advantage**: One Role system covers research, review, implementation, parallel work, and ordered chains.
 
 ## Install
 
@@ -16,16 +16,30 @@ pi install npm:@henryqw/pi-task-models
 pi install npm:@henryqw/pi-subagent
 ```
 
+Run `/task-models` and configure the `fast` profile before delegating.
+
 ## With
 
 | Package | Why |
 | --- | --- |
-| `@henryqw/pi-task-models` | Required. Supplies `fast`, `balanced`, `frontier`, and `fav` model routes. |
+| [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) | Required. Supplies `fast`, `balanced`, `frontier`, and `fav` model routes. |
 
 Routes come from `~/.pi/agent/config/pi-task-models/config.json`. It stores explicit task overrides. An explicit call `modelClass` wins over a Role `modelClass`; without either, pi-subagent uses its configured `pi-subagent/delegateTask` assignment or declared `fast` default. Missing shared model config warns once because delegation needs a route.
 
 ## Use
 
+Start with one read-only delegation:
+
+```json
+{
+  "role": "scout",
+  "name": "Map sign-in flow",
+  "task": "Trace the sign-in request from entry point to session creation. Report the relevant files and unresolved risks. Do not edit files."
+}
+```
+
+A separate child returns a bounded report to Main. It creates no saved Pi session and makes model requests through the selected route.
+
 | Tool | Purpose |
 | --- | --- |
 | `delegate_task` | Run one bounded task, independent tasks in parallel, or dependent tasks in a chain. |
@@ -51,7 +65,7 @@ Main supplies each `name`. It must be a short description, about five words and
 
 Parallel tasks start together, settle together, and report in input order. Chains are sequential and fail at the first failure. `{previous}` passes only the immediately preceding successful assistant output. Foreground failures throw after keeping bounded sibling and recovery evidence.
 
-One call has one aggregate 50 KiB cap for Main-visible text. Background work belongs to its launching session; shutdown or reload aborts it and may leave only recoverable-work evidence or no follow-up message.
+One call has one aggregate 50 KiB cap for Main-visible text. Live updates show task names and statuses without opaque IDs. Final results show summaries first and full evidence below. Background work belongs to its launching session; shutdown or reload aborts it and may leave only recoverable-work evidence or no follow-up message.
 
 Each entry resolves its own Role, resources, route, and optional isolation. A Role with `isolation: worktree` gets a separate deterministic worktree when available. Non-Git and unborn-`HEAD` contexts can use Main's directory. Other setup failures, including unsafe submodule layouts, reject instead of falling back. Siblings and chain steps never share a created worktree.
 
@@ -59,6 +73,8 @@ See the [orchestration guide](./docs/orchestration.md) for full delegation, tran
 
 ### Flow
 
+![Delegate Flow lifecycle](./docs/delegate-flow.svg)
+
 Flow requires a clean Main worktree on an attached branch with a committed `HEAD`. Use it only for independent Git changes that can merge in any order. Do not split units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.
 
 ```text
@@ -141,4 +157,6 @@ The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated
 
 The package root exports `loadRoles`, `resolveRoleSkills`, `resolveRoleLaunch`, `createRoleLaunch`, `createEphemeralSubagentExecutor`, and worktree helpers. The executor works only inside the active Pi process; it does not discover or start a standalone Node.js Pi installation.
 
+`finalizeChildWorktree` returns the breaking `WorktreePayload` lifecycle union. `pruned` proves zero commits, a clean tree, and removed worktree and branch. `retained` contains measured `commits` and `dirty` values. `recovery` has an actionable `note` and only completed measurements. An omitted recovery measurement is unknown.
+
 See the [public Role and executor API](./docs/orchestration.md#public-role-and-executor-api) for contracts and a `prepare` example. Pass `modelClass` to `resolveRoleLaunch` to override a Role default.

package/dist/worktree.d.ts

@@ -5,15 +5,24 @@ export interface WorktreeInfo {
     repoRoot: string;
     baseCommit: string;
 }
-export interface WorktreePayload {
+export type WorktreePayload = {
+    outcome: "pruned";
+    path: string;
+    branch: string;
+} | {
+    outcome: "retained";
     path: string;
     branch: string;
     commits: number;
     dirty: boolean;
-    pruned: boolean;
-    inspection_failed?: boolean;
-    note?: string;
-}
+} | {
+    outcome: "recovery";
+    path: string;
+    branch: string;
+    note: string;
+    commits?: number;
+    dirty?: boolean;
+};
 export type GitRunner = (args: string[], cwd: string, signal?: AbortSignal) => Promise<{
     code: number;
     stdout: string;
@@ -49,8 +58,7 @@ export declare function inspectWorktreeDirty(cwd: string, run?: GitRunner): Prom
  * names it; the clean-tree proof includes untracked, ignored, and submodule
  * changes despite repository config. A worktree with zero branch commits and a
  * clean tree is removed only when every probe succeeds and base_commit was
- * recorded; any probe failure keeps everything and reports `inspection_failed`
- * so unmeasured state is never read as empty.
+ * recorded; any uncertainty preserves work and omits unknown measurements.
  */
 export declare function finalizeChildWorktree(info: WorktreeInfo, run?: GitRunner): Promise<WorktreePayload>;
 /** Context block telling the child to work inside its isolated worktree. */

package/dist/worktree.js

@@ -149,13 +149,20 @@ export async function createChildWorktree(cwd, childId, run = runGit, signal) {
     }
     return worktree;
 }
-/** Flags a payload whose state could not be measured (#88113): unmeasured is not zero. */
-function markUnproven(payload, reason, unmeasured = "commits/dirty") {
-    payload.inspection_failed = true;
-    payload.note =
-        `git inspection failed (${reason}): ${unmeasured} UNKNOWN — not proven zero/clean. `
-            + `Any remaining worktree or branch was preserved — inspect ${payload.path} (branch ${payload.branch}) before assuming no work.`;
-    return payload;
+/** Records only measurements that completed before recovery became necessary. */
+function recoveryPayload(info, reason, measurements = {}, action = `Inspect ${info.path} (branch ${info.branch}) before assuming no work.`) {
+    const unknown = [
+        ...(measurements.commits === undefined ? ["commits"] : []),
+        ...(measurements.dirty === undefined ? ["dirty"] : []),
+    ].join("/");
+    return {
+        outcome: "recovery",
+        path: info.path,
+        branch: info.branch,
+        ...(measurements.commits === undefined ? {} : { commits: measurements.commits }),
+        ...(measurements.dirty === undefined ? {} : { dirty: measurements.dirty }),
+        note: `Worktree recovery required (${reason})${unknown ? `: ${unknown} UNKNOWN` : ""}. ${action}`,
+    };
 }
 export async function inspectIndexFlags(cwd, run = runGit, signal) {
     const flags = await run(["ls-files", "-v", "-z"], cwd, signal);
@@ -213,56 +220,54 @@ export async function inspectWorktreeDirty(cwd, run = runGit) {
  * names it; the clean-tree proof includes untracked, ignored, and submodule
  * changes despite repository config. A worktree with zero branch commits and a
  * clean tree is removed only when every probe succeeds and base_commit was
- * recorded; any probe failure keeps everything and reports `inspection_failed`
- * so unmeasured state is never read as empty.
+ * recorded; any uncertainty preserves work and omits unknown measurements.
  */
 export async function finalizeChildWorktree(info, run = runGit) {
-    const payload = { path: info.path, branch: info.branch, commits: 0, dirty: false, pruned: false };
     const checkoutExists = existsSync(info.path);
     const gitCwd = checkoutExists ? info.path : info.repoRoot || info.path;
     if (!info.baseCommit)
-        return markUnproven(payload, "no base_commit recorded — commit count unmeasurable", "commits");
+        return recoveryPayload(info, "no base_commit recorded — commit count unmeasurable");
     const counted = await run(["rev-list", "--count", `${info.baseCommit}..${info.branch}`], gitCwd);
     const commits = Number.parseInt(counted.stdout.trim(), 10);
     const countFailure = counted.code !== 0
         ? `rev-list exit ${counted.code}: ${counted.stderr.trim().slice(0, 200)}`
         : Number.isNaN(commits) ? "rev-list produced non-numeric output" : undefined;
     const inspection = checkoutExists ? await inspectDirty(run, info.path) : undefined;
-    if (!countFailure)
-        payload.commits = commits;
-    if (inspection)
-        payload.dirty = inspection.dirty;
+    const measurements = {
+        ...(countFailure === undefined ? { commits } : {}),
+        ...(inspection?.failure === undefined && inspection !== undefined ? { dirty: inspection.dirty } : {}),
+    };
     if (countFailure || inspection?.failure) {
-        return markUnproven(payload, [countFailure, inspection?.failure].filter(Boolean).join("; "), [countFailure && "commits", inspection?.failure && "dirty"].filter(Boolean).join("/"));
+        return recoveryPayload(info, [countFailure, inspection?.failure].filter(Boolean).join("; "), measurements);
     }
     let forceRemove = false;
     if (checkoutExists) {
-        if (payload.commits > 0 || payload.dirty)
-            return payload;
+        const dirty = inspection.dirty;
+        if (commits > 0 || dirty)
+            return { outcome: "retained", path: info.path, branch: info.branch, commits, dirty };
         const head = await run(["symbolic-ref", "--quiet", "HEAD"], info.path);
         if (head.code !== 0 || head.stdout.trim() !== `refs/heads/${info.branch}`) {
-            return markUnproven(payload, "HEAD is detached, switched, or unreadable", "checked-out commits");
+            return recoveryPayload(info, "HEAD is detached, switched, or unreadable", measurements);
         }
         const rechecked = await inspectWorktreeDirty(info.path, run);
         if (rechecked.failure)
-            return markUnproven(payload, `final ${rechecked.failure}`, "dirty");
-        if (rechecked.dirty) {
-            payload.dirty = true;
-            return payload;
-        }
+            return recoveryPayload(info, `final ${rechecked.failure}`, { commits });
+        if (rechecked.dirty)
+            return { outcome: "retained", path: info.path, branch: info.branch, commits, dirty: true };
         forceRemove = Boolean(rechecked.initializedSubmodules);
     }
-    else if (payload.commits > 0)
-        return payload;
+    else if (commits > 0) {
+        return recoveryPayload(info, "worktree checkout is missing", { commits });
+    }
     const cleanupCwd = info.repoRoot || info.path;
     const removed = await run(["worktree", "remove", ...(forceRemove ? ["--force"] : []), info.path], cleanupCwd);
     if (removed.code !== 0)
-        return markUnproven(payload, `worktree remove exit ${removed.code}: ${removed.stderr.trim().slice(0, 200)}`, "cleanup");
+        return recoveryPayload(info, `worktree remove exit ${removed.code}: ${removed.stderr.trim().slice(0, 200)}`);
     const deleted = await run(["update-ref", "-d", `refs/heads/${info.branch}`, info.baseCommit], cleanupCwd);
-    if (deleted.code !== 0)
-        return markUnproven(payload, `branch delete exit ${deleted.code}: ${deleted.stderr.trim().slice(0, 200)}`, "cleanup");
-    payload.pruned = true;
-    return payload;
+    if (deleted.code !== 0) {
+        return recoveryPayload(info, `branch delete exit ${deleted.code}: ${deleted.stderr.trim().slice(0, 200)}`, {}, `Inspect branch ${info.branch}; recreate ${info.path} from it before assuming no work.`);
+    }
+    return { outcome: "pruned", path: info.path, branch: info.branch };
 }
 /** Context block telling the child to work inside its isolated worktree. */
 export function worktreeContextNote(info) {

package/docs/delegate-flow.svg

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<svg viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="delegate-flow-title delegate-flow-desc">
+<svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="delegate-flow-title delegate-flow-desc">
       <title id="delegate-flow-title">Delegate Flow lifecycle</title>
       <desc id="delegate-flow-desc">Flowchart showing setup, implementation, validation, optional exact review, one repair attempt, integration, cleanup, and retained-worktree failure outcomes.</desc>
       <defs>

package/docs/orchestration.md

@@ -155,6 +155,14 @@ The package root exports the following mechanism-level APIs:
 | `createEphemeralSubagentExecutor(options)` | Queue and run one prepared no-session child per `run`. |
 | `createChildWorktree` / `finalizeChildWorktree` | Optional caller-managed worktree lifecycle. |
 
+`finalizeChildWorktree` returns the breaking `WorktreePayload` lifecycle union:
+
+| `outcome` | Fields | Contract |
+| --- | --- | --- |
+| `pruned` | `path`, `branch` | Zero commits and a clean tree were proved. Worktree and branch cleanup completed. |
+| `retained` | `path`, `branch`, `commits`, `dirty` | Work was preserved. Both measurements are known. |
+| `recovery` | `path`, `branch`, `note`, optional `commits`, `dirty` | Recovery needs action. The note tells Main what to inspect. Present measurements completed; omitted values are unknown. |
+
 A loaded `Role` contains `name`, `description`, required normalized `tools`, `extensions`, and `skills` arrays, optional `modelClass` and `isolation`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, a caller-owned `task` Model Task declaration, optional call-level `modelClass`, and optional caller `agentDir`, `extensions`, `tools`, and `env`. At extension load, callers invoke `registerModelTask(pi, task)` from `@henryqw/pi-task-models` once to expose that declaration in the shared control plane. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
 
 `createEphemeralSubagentExecutor` requires:

package/extensions/config.ts

@@ -98,7 +98,7 @@ function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfi
 		}
 	}
 
-	return { config, error: problems.length ? `${path}: ${problems.join("; ")}; using defaults.` : undefined };
+	return { config, error: problems.length ? `${path}: ${problems.join("; ")}; invalid settings use defaults while valid settings still apply.` : undefined };
 }
 
 /**

package/extensions/result-transport.ts

@@ -14,6 +14,7 @@ export type WorkflowTransportStatus = "pending" | "running" | "succeeded" | "fai
 type TransportEntryBase = {
 	id: WorkflowEntry["id"];
 	index: WorkflowEntry["index"];
+	name: WorkflowEntry["delegation"]["name"];
 	role: WorkflowEntry["delegation"]["role"];
 	model?: string;
 	thinkingLevel?: string;
@@ -33,6 +34,7 @@ export type WorkflowTransportEntry =
 export type WorkflowTransportEntryDetails = {
 	id: string;
 	index: number;
+	name: string;
 	role: string;
 	status: WorkflowTransportStatus;
 	summary?: string;
@@ -46,6 +48,13 @@ export type WorkflowTransportDetails = {
 	entries: WorkflowTransportEntryDetails[];
 };
 
+export type BackgroundWorkflowTransportDetails = WorkflowTransportDetails & {
+	taskId: string;
+	outcome: "completed" | "failed" | "aborted";
+	recovery?: true;
+	usage?: Usage;
+};
+
 export type WorkflowTransport = {
 	text: string;
 	details: WorkflowTransportDetails;
@@ -65,24 +74,63 @@ function splitEvidence(text: string): [string, string] {
 	return [preview, text.slice(preview.length)];
 }
 
-function label(kind: TransportKind, failed: boolean): string {
-	if (kind === "update") return "Workflow update.";
-	if (kind === "background") return `Background workflow ${failed ? "failed" : "succeeded"}.`;
-	if (kind === "abort") return "Workflow aborted.";
-	return `Workflow ${failed ? "failed" : "succeeded"}.`;
+function workflowTitle(mode: WorkflowMode): string {
+	if (mode === "single") return "Delegation";
+	if (mode === "parallel") return "Parallel delegation";
+	return "Delegation chain";
+}
+
+function statusCounts(entries: readonly WorkflowTransportEntry[], kind: TransportKind): string[] {
+	const count = (statuses: WorkflowTransportStatus[]) => entries.filter(({ status }) => statuses.includes(status)).length;
+	const labels = kind === "update"
+		? [["running"], ["succeeded"], ["failed", "rejected"], ["pending"], ["skipped"]] as const
+		: [["failed", "rejected"], ["succeeded"], ["skipped"]] as const;
+	const words = kind === "update" ? ["running", "completed", "failed", "queued", "skipped"] : ["failed", "completed", "skipped"];
+	return labels.flatMap((statuses, index) => {
+		const total = count([...statuses]);
+		return total ? [`${total} ${words[index]}`] : [];
+	});
+}
+
+function heading(mode: WorkflowMode, entries: readonly WorkflowTransportEntry[], kind: TransportKind, failed: boolean): string {
+	const title = kind === "background" ? `Background ${workflowTitle(mode).toLowerCase()}` : workflowTitle(mode);
+	if (kind === "update") return [title, ...statusCounts(entries, kind)].join(" · ");
+	const outcome = kind === "abort" ? "stopped" : failed ? "failed" : "completed";
+	return [`${title} ${outcome}`, ...statusCounts(entries, kind)].join(" · ");
 }
 
 export function displaySummary(text: string): string {
 	const line = text.split(/\r?\n/).find((candidate) => candidate.trim()) ?? "";
-	return Array.from(line.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().split(/\s+/).join(" ")).slice(0, 160).join("");
+	const normalized = line.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().replace(/^[-*+]\s+/, "").split(/\s+/).join(" ");
+	return Array.from(normalized).slice(0, 160).join("");
 }
 
-function evidenceFor(entry: WorkflowTransportEntry): Evidence | undefined {
-	if (entry.status === "pending" || entry.status === "skipped") return;
-	const source = entry.status === "failed" || entry.status === "rejected" ? entry.failure : entry.assistantOutput;
-	const [preview, remainder] = splitEvidence(source || (entry.status === "running" ? "(no output yet)" : "(no output)"));
+export type WorkflowEntryStatusPresentation = { glyph: string; fallback: string };
+
+const ENTRY_STATUS_PRESENTATION = {
+	pending: { glyph: "○", fallback: "queued" },
+	running: { glyph: "◌", fallback: "working" },
+	succeeded: { glyph: "✓", fallback: "completed" },
+	failed: { glyph: "✗", fallback: "failed" },
+	rejected: { glyph: "✗", fallback: "failed" },
+	skipped: { glyph: "–", fallback: "skipped" },
+} as const satisfies Record<WorkflowTransportEntryDetails["status"], WorkflowEntryStatusPresentation>;
+
+export function presentWorkflowEntryStatus(status: WorkflowTransportEntryDetails["status"]): WorkflowEntryStatusPresentation {
+	return ENTRY_STATUS_PRESENTATION[status];
+}
+
+function sourceFor(entry: WorkflowTransportEntry): string | undefined {
+	if (entry.status === "failed" || entry.status === "rejected") return entry.failure;
+	if (entry.status === "running" || entry.status === "succeeded") return entry.assistantOutput;
+}
+
+function evidenceFor(entry: WorkflowTransportEntry, position: number, total: number): Evidence | undefined {
+	const source = sourceFor(entry);
+	if (source === undefined || !source) return;
+	const [preview, remainder] = splitEvidence(source);
 	return {
-		heading: `- [${entry.index}] ${JSON.stringify(entry.id)} ${entry.status === "failed" || entry.status === "rejected" ? "failure" : "assistant"}:`,
+		heading: `- [${position}/${total}] ${entry.name} · ${entry.role} · ${entry.status === "failed" || entry.status === "rejected" ? "failure" : "result"}:`,
 		preview,
 		remainder,
 	};
@@ -98,27 +146,32 @@ function formatWorkflowTransport(
 		throw new TypeError("Final workflow transport requires terminal entry states.");
 	}
 	const failed = ordered.some(({ status }) => status === "failed" || status === "rejected");
-	const recoveries = ordered.filter(({ worktreePayload }) => worktreePayload && !worktreePayload.pruned);
-	const evidence = ordered.flatMap((entry) => {
-		const value = evidenceFor(entry);
+	const positioned = ordered.map((entry, index) => ({ entry, position: index + 1 }));
+	const recoveries = positioned.flatMap(({ entry, position }) => {
+		const worktree = entry.worktreePayload;
+		return worktree === undefined || worktree.outcome === "pruned" ? [] : [{ entry, position, worktree }];
+	});
+	const evidence = kind === "update" ? [] : positioned.flatMap(({ entry, position }) => {
+		const value = evidenceFor(entry, position, ordered.length);
 		return value ? [value] : [];
 	});
 	const lines = [
-		label(kind, failed),
-		`Mode: ${mode}`,
-		"Entries:",
-		...ordered.map((entry) =>
-			`- [${entry.index}] id=${JSON.stringify(entry.id)} role=${JSON.stringify(entry.role)} status=${entry.status}`),
+		heading(mode, ordered, kind, failed),
+		...positioned.map(({ entry, position }) => {
+			const { glyph, fallback } = presentWorkflowEntryStatus(entry.status);
+			const summary = displaySummary(sourceFor(entry) ?? "") || fallback;
+			return `${glyph} [${position}/${ordered.length}] ${entry.name} · ${entry.role} — ${summary}`;
+		}),
 		...(recoveries.length ? [
-			"Retained worktrees:",
-			...recoveries.map((entry) =>
-				`- [${entry.index}] path=${JSON.stringify(entry.worktreePayload!.path)} branch=${JSON.stringify(entry.worktreePayload!.branch)}`),
+			"Recovery:",
+			...recoveries.map(({ entry, position, worktree }) =>
+				`- [${position}/${ordered.length}] ${entry.name} · worktree ${JSON.stringify(worktree.path)} · branch ${JSON.stringify(worktree.branch)}`),
 		] : []),
 		...(evidence.length ? [
-			"Evidence:",
+			"Results:",
 			...evidence.flatMap(({ heading, preview }) => [heading, preview]),
 			...(evidence.some(({ remainder }) => remainder) ? [
-				"Continued evidence:",
+				"More detail:",
 				...evidence.flatMap(({ heading, remainder }) => remainder ? [heading, remainder] : []),
 			] : []),
 		] : []),
@@ -130,11 +183,11 @@ function formatWorkflowTransport(
 		details: {
 			mode,
 			entries: ordered.map((entry) => {
-				const source = entry.status === "failed" || entry.status === "rejected" ? entry.failure
-					: entry.status === "running" || entry.status === "succeeded" ? entry.assistantOutput : undefined;
+				const source = sourceFor(entry);
 				return {
 					id: entry.id,
 					index: entry.index,
+					name: entry.name,
 					role: entry.role,
 					status: entry.status,
 					...(source === undefined ? {} : { summary: displaySummary(source) }),

package/extensions/subagent.ts

@@ -1,7 +1,7 @@
 import { basename } from "node:path";
 import type { Usage } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+import { type Component, Text, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
 import {
 	availableTaskModels,
 	loadTaskModelsConfig,
@@ -23,6 +23,7 @@ import {
 	formatDuration,
 	loadRoles,
 	resolveRoleLaunch,
+	WorktreeSetupError,
 	worktreeContextNote,
 	type EphemeralSubagentActivityEvent,
 	type EphemeralSubagentResult,
@@ -38,8 +39,10 @@ import {
 	formatBackgroundWorkflowResult,
 	formatWorkflowResult,
 	formatWorkflowUpdate,
+	presentWorkflowEntryStatus,
 	WorkflowAbortedError,
 	WorkflowFailureError,
+	type BackgroundWorkflowTransportDetails,
 	type WorkflowTransportEntry,
 } from "./result-transport.ts";
 import {
@@ -222,6 +225,30 @@ export default function subagentExtension(
 	overrideTimeoutPolicy?: TimeoutPolicy,
 ): void {
 	registerModelTask(pi, DELEGATE_TASK);
+	pi.registerMessageRenderer(BACKGROUND_RESULT_TYPE, (message, { expanded, outputPad }, theme) => {
+		const details = message.details as BackgroundWorkflowTransportDetails | undefined;
+		const content = typeof message.content === "string"
+			? message.content
+			: message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n");
+		if (!details?.entries) return new Text(content, outputPad, 0);
+		const count = details.entries.length;
+		const subject = count === 1 ? "Background subagent" : `${count} background subagents`;
+		const state = details.recovery ? "stopped; recovery needed"
+			: details.outcome === "completed" ? "completed"
+				: details.outcome === "failed" ? "failed" : "stopped";
+		const glyph = details.recovery || details.outcome === "aborted" ? "■" : details.outcome === "completed" ? "✓" : "✗";
+		const color = details.recovery || details.outcome === "aborted" ? "warning" : details.outcome === "completed" ? "success" : "error";
+		const rows = details.entries.map(({ name, role, status, summary }) => {
+			const { glyph, fallback } = presentWorkflowEntryStatus(status);
+			return `${glyph} ${name} · ${role} — ${details.recovery ? fallback : summary || fallback}`;
+		});
+		const raw = content.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, " ");
+		return new Text([
+			theme.fg(color, `${glyph} ${subject} ${state}`),
+			...rows,
+			...(expanded ? ["", raw] : []),
+		].join("\n"), outputPad, 0);
+	});
 	const widgetItems = new Map<string, WidgetItem>();
 	// Each child is a full Pi process issuing its own model calls; cap parallel
 	// spend. Precedence: PI_SUBAGENT_MAX_SUBAGENTS env > config/pi-subagent/config.json
@@ -450,26 +477,35 @@ export default function subagentExtension(
 		setupRecoveries: ReadonlyMap<string, string>,
 	): void => {
 		const stale = launchEpoch !== sessionEpoch;
-		const retained = entries.filter(({ worktreePayload }) => worktreePayload && !worktreePayload.pruned);
-		if (stale && !retained.length && !setupRecoveries.size) return;
+		const recoveries = entries.flatMap((entry) => {
+			const worktree = entry.worktreePayload;
+			return worktree === undefined || worktree.outcome === "pruned" ? [] : [{ entry, worktree }];
+		});
+		if (stale && !recoveries.length && !setupRecoveries.size) return;
 		const transport = formatBackgroundWorkflowResult(mode, entries);
-		const outcome = stale ? "aborted" : transport.failed ? "failed" : "completed";
+		const outcome: BackgroundWorkflowTransportDetails["outcome"] = stale ? "aborted" : transport.failed ? "failed" : "completed";
 		const content = stale
 			? capOutput([
 				"Background workflow left recoverable isolated work after session shutdown.",
 				`Task ID: ${taskId}`,
 				`Mode: ${mode}`,
 				"Recovery locations:",
-				...retained.map((entry) =>
-					`- [${entry.index}] worktree path=${JSON.stringify(entry.worktreePayload!.path)} branch=${JSON.stringify(entry.worktreePayload!.branch)}`),
+				...recoveries.map(({ entry, worktree }) =>
+					`- [${entry.index}] worktree path=${JSON.stringify(worktree.path)} branch=${JSON.stringify(worktree.branch)}`),
 				...[...setupRecoveries].map(([id, recovery]) => {
 					const entry = entries.find((candidate) => candidate.id === id)!;
 					return `- [${entry.index}] setup state: ${recovery}`;
 				}),
 				"Evidence:",
-				...retained.map((entry) => {
-					const payload = entry.worktreePayload!;
-					return `- [${entry.index}] retained worktree commits=${payload.commits} dirty=${payload.dirty} inspection_failed=${payload.inspection_failed === true}`;
+				...recoveries.flatMap(({ entry, worktree }) => {
+					const measurements = [
+						...(worktree.commits === undefined ? [] : [`commits=${worktree.commits}`]),
+						...(worktree.dirty === undefined ? [] : [`dirty=${worktree.dirty}`]),
+					];
+					return [
+						`- [${entry.index}] ${worktree.outcome} worktree${measurements.length ? ` ${measurements.join(" ")}` : ""}`,
+						...(worktree.outcome === "recovery" ? [`  ${worktree.note}`] : []),
+					];
 				}),
 				...[...setupRecoveries].map(([id, recovery]) => {
 					const entry = entries.find((candidate) => candidate.id === id)!;
@@ -477,6 +513,13 @@ export default function subagentExtension(
 				}),
 			].join("\n"))
 			: transport.text;
+		const details: BackgroundWorkflowTransportDetails = {
+			...transport.details,
+			taskId,
+			outcome,
+			...(transport.usage === undefined ? {} : { usage: transport.usage }),
+			...(stale ? { recovery: true } : {}),
+		};
 		try {
 			// Custom messages convert to user-role LLM messages, so the parent agent
 			// sees the aggregate on its next turn without forcing one now.
@@ -484,13 +527,7 @@ export default function subagentExtension(
 				customType: BACKGROUND_RESULT_TYPE,
 				content,
 				display: true,
-				details: {
-					...transport.details,
-					taskId,
-					outcome,
-					...(transport.usage === undefined ? {} : { usage: transport.usage }),
-					...(stale ? { recovery: true } : {}),
-				},
+				details,
 			}, { triggerTurn: false });
 		} catch (error) {
 			// Delivery can disappear during teardown; only an active UI gets a visible failure.
@@ -592,6 +629,7 @@ export default function subagentExtension(
 			const states = new Map<string, WorkflowTransportEntry>(entries.map((entry) => [entry.id, {
 				id: entry.id,
 				index: entry.index,
+				name: entry.delegation.name,
 				role: entry.delegation.role,
 				status: "pending",
 			}]));
@@ -627,6 +665,7 @@ export default function subagentExtension(
 						const base = {
 							id: entry.id,
 							index: entry.index,
+							name: entry.delegation.name,
 							role: role.name,
 							...(model === undefined ? {} : { model }),
 							...(thinkingLevel === undefined ? {} : { thinkingLevel }),
@@ -680,7 +719,7 @@ export default function subagentExtension(
 							? (error as EphemeralSubagentError & { usage?: Usage }).usage
 							: undefined;
 						const cause = error instanceof EphemeralSubagentError ? error.cause : error;
-						if (cause instanceof Error && cause.name === "WorktreeSetupError") {
+						if (cause instanceof WorktreeSetupError) {
 							setupRecoveries.set(entry.id, cause.message);
 						}
 						text = capOutput(error instanceof Error ? error.message : String(error));
@@ -693,17 +732,14 @@ export default function subagentExtension(
 						status = "rejected";
 						text = capOutput(error instanceof Error ? error.message : String(error));
 						worktreePayload = worktree ? {
+							outcome: "recovery",
 							path: worktree.path,
 							branch: worktree.branch,
-							commits: 0,
-							dirty: false,
-							pruned: false,
-							inspection_failed: true,
-							note: capOutput(`Worktree finalization failed (${text}); commits/dirty UNKNOWN. Inspect retained work before assuming no changes.`),
+							note: capOutput(`Worktree finalization failed (${text}); commits/dirty UNKNOWN. Inspect ${worktree.path} (branch ${worktree.branch}) before assuming no work.`),
 						} : undefined;
 					}
-					if (worktreePayload?.inspection_failed) {
-						const note = capOutput(worktreePayload.note ?? `Worktree inspection failed; inspect ${worktreePayload.path} before assuming no work.`);
+					if (worktreePayload?.outcome === "recovery") {
+						const note = capOutput(worktreePayload.note);
 						worktreePayload = { ...worktreePayload, note };
 						rejected = new Error(note, rejected === undefined ? undefined : { cause: rejected });
 						status = "rejected";
@@ -741,6 +777,7 @@ export default function subagentExtension(
 				states.set(target.id, {
 					id: target.id,
 					index: target.index,
+					name: target.name,
 					role: target.role,
 					...(target.model === undefined ? {} : { model: target.model }),
 					...(target.thinkingLevel === undefined ? {} : { thinkingLevel: target.thinkingLevel }),
@@ -775,13 +812,13 @@ export default function subagentExtension(
 				})();
 				backgroundTasks.set(taskId, { controller, settled });
 				void settled;
+				const title = workflow.mode === "single" ? "Background delegation"
+					: workflow.mode === "parallel" ? "Background parallel delegation" : "Background delegation chain";
 				const acknowledgement = capOutput([
-					`Background workflow ${taskId} accepted.`,
-					`Mode: ${workflow.mode}`,
-					"Entries:",
-					...entries.map((entry) =>
-						`- [${entry.index}] id=${JSON.stringify(entry.id)} role=${JSON.stringify(entry.delegation.role)}`),
-					"The aggregate outcome arrives as one message; keep working or end your turn.",
+					`${title} started${entries.length === 1 ? "" : ` · ${entries.length} tasks`}`,
+					...entries.map((entry, index) =>
+						`○ [${index + 1}/${entries.length}] ${entry.delegation.name} · ${entry.delegation.role}`),
+					"Results will arrive in one message.",
 				].join("\n"));
 				return {
 					content: [{ type: "text" as const, text: acknowledgement }],
@@ -789,7 +826,7 @@ export default function subagentExtension(
 						taskId,
 						background: true,
 						mode: workflow.mode,
-						entries: entries.map((entry) => ({ id: entry.id, index: entry.index, role: entry.delegation.role })),
+						entries: entries.map((entry) => ({ id: entry.id, index: entry.index, name: entry.delegation.name, role: entry.delegation.role })),
 					},
 				};
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "11.1.0",
+  "version": "12.0.1",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@henryqw/pi-config-store": "^0.1.0",
-    "@henryqw/pi-multi-codex": "^0.3.8",
+    "@henryqw/pi-multi-codex": "^0.4.1",
     "@henryqw/pi-task-models": "^4.0.0"
   }
 }