@gavin-hu/my-pi-agent 0.16.0 → 0.18.0

package/extensions/subagent/format.ts

@@ -1,46 +1,93 @@
 /**
  * Pure formatting helpers shared by the transcript renderers.
+ *
+ * The usage line keeps tokens, turns, model, and context — the facts the child
+ * reported — and never money: a price needs a currency and a tariff, which the
+ * bytefly footer owns for the whole session. See `usageLine` / `totalUsageLine`.
  */
 
 import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { formatDuration, formatTokens, sanitizeLine, shortenPath } from "../../lib/format.ts";
+import { USAGE_COUNTERS, zeroUsage } from "../../lib/usage.ts";
 import type { BackgroundRun } from "./background.ts";
-import type { UsageStats } from "./types.ts";
+import type { UsageSource, UsageStats } from "./types.ts";
 
-/** Dollar cost, keeping four decimals for the sub-cent amounts these runs produce. */
-function formatCost(cost: number): string {
-	if (cost >= 1) return `$${cost.toFixed(2)}`;
-	if (cost >= 0.0001) return `$${cost.toFixed(4)}`;
-	return `$${cost.toPrecision(2)}`;
+/** `2 turns` / `1 turn`, or "" when no turn was counted. */
+function turnPart(turns: number | undefined): string {
+	if (!turns) return "";
+	return `${turns} turn${turns > 1 ? "s" : ""}`;
+}
+
+/** A prefix and a compact count, or "" when the counter is zero. */
+function tokenPart(prefix: string, count: number | undefined): string {
+	return count ? `${prefix}${formatTokens(count)}` : "";
+}
+
+/** `ctx:18.2k`, or "" when no context was reported. */
+function contextPart(tokens: number | undefined): string {
+	const count = tokens ?? 0;
+	return count > 0 ? `ctx:${formatTokens(count)}` : "";
 }
 
 /** A space-separated usage line, omitting zero fields. */
 export function formatUsageStats(usage: Partial<UsageStats>, model?: string): string {
-	const parts: string[] = [];
-	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
-	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
-	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
-	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
-	if (usage.cost) parts.push(formatCost(usage.cost));
-	if (usage.contextTokens && usage.contextTokens > 0) parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-	if (model) parts.push(model);
-	return parts.join(" ");
+	return [
+		turnPart(usage.turns),
+		tokenPart("↑", usage.input),
+		tokenPart("↓", usage.output),
+		tokenPart("R", usage.cacheRead),
+		tokenPart("W", usage.cacheWrite),
+		contextPart(usage.contextTokens),
+		model ?? "",
+	]
+		.filter(Boolean)
+		.join(" ");
 }
 
 /** Sum usage across results, for the chain/parallel totals line. */
-export function aggregateUsage(results: { usage: UsageStats }[]): Partial<UsageStats> {
-	const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+export function aggregateUsage(results: readonly { usage: UsageStats }[]): Partial<UsageStats> {
+	const counters = zeroUsage();
+	let turns = 0;
 	for (const { usage } of results) {
-		total.input += usage.input;
-		total.output += usage.output;
-		total.cacheRead += usage.cacheRead;
-		total.cacheWrite += usage.cacheWrite;
-		total.cost += usage.cost;
-		total.turns += usage.turns;
+		for (const counter of USAGE_COUNTERS) counters[counter] += usage[counter];
+		turns += usage.turns;
 	}
-	return total;
+	return { ...counters, turns };
+}
+
+/** "2 tool errors", "1 tool error", or "" when the run hit none. */
+function toolErrorsLabel(count: number | undefined): string {
+	if (!count) return "";
+	return `${count} tool error${count > 1 ? "s" : ""}`;
+}
+
+/**
+ * The one model every result ran, or undefined when they differ.
+ *
+ * A total may name a model only when the name is true of all of it: a batch whose
+ * tasks pinned different models gets no label rather than one task's.
+ */
+function sharedModel(sources: readonly UsageSource[]): string | undefined {
+	const models = new Set(sources.map((source) => source.model).filter((model): model is string => Boolean(model)));
+	return models.size === 1 ? [...models][0] : undefined;
+}
+
+/** One result's usage line, with its tool-error count when it hit any. */
+export function usageLine(source: UsageSource): string {
+	return [formatUsageStats(source.usage, source.model), toolErrorsLabel(source.toolErrors)].filter(Boolean).join(" ");
+}
+
+/**
+ * The `Total:` line for a multi run: summed counters, the shared model when there
+ * is one, and summed tool errors. A total carries no `ctx:` — every child has its
+ * own context window, so a sum of them would mean nothing.
+ */
+export function totalUsageLine(sources: readonly UsageSource[]): string {
+	const usage = formatUsageStats(aggregateUsage(sources), sharedModel(sources));
+	const errors = sources.reduce((sum, source) => sum + (source.toolErrors ?? 0), 0);
+	const line = [usage, toolErrorsLabel(errors)].filter(Boolean).join(" ");
+	return line ? `Total: ${line}` : "";
 }
 
 /** Display-width-aware truncation with a trailing ellipsis (keeps wide chars/surrogates intact). */

package/extensions/subagent/index.ts

@@ -17,6 +17,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled, resolveEffectiveCwd } from "../../lib/env.ts";
+import { textResult } from "../../lib/tool-result.ts";
 import {
 	type AgentConfig,
 	type AgentScope,
@@ -158,12 +159,10 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 			const resolution = resolveMode(args);
 			if ("error" in resolution) {
 				const roster = discoverAgents(root, args.agentScope ?? "user").agents;
-				return {
-					content: [
-						{ type: "text" as const, text: `${resolution.error} Available agents: ${formatAgentList(roster)}` },
-					],
-					details: { mode: "single", results: [] } satisfies SubagentDetails,
-				};
+				return textResult(`${resolution.error} Available agents: ${formatAgentList(roster)}`, {
+					mode: "single",
+					results: [],
+				} satisfies SubagentDetails);
 			}
 
 			const mode = resolution.mode;
@@ -195,17 +194,11 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 					.filter((agent): agent is AgentConfig => agent?.source === "project");
 				if (projectAgents.length > 0) {
 					if (!ctx.hasUI) {
-						return {
-							content: [
-								{
-									type: "text" as const,
-									text:
-										"Refusing to run project-local agents without confirmation. " +
-										'Trust the project or use agentScope: "user".',
-								},
-							],
-							details: makeDetails([]),
-						};
+						return textResult(
+							"Refusing to run project-local agents without confirmation. " +
+								'Trust the project or use agentScope: "user".',
+							makeDetails([]),
+						);
 					}
 					const names = projectAgents.map((agent) => agent.name).join(", ");
 					const dir = discovery.projectAgentsDir ?? "(unknown)";
@@ -214,31 +207,20 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 						`Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
 					);
 					if (!approved) {
-						return {
-							content: [{ type: "text" as const, text: "Canceled: project-local agents not approved." }],
-							details: makeDetails([]),
-						};
+						return textResult("Canceled: project-local agents not approved.", makeDetails([]));
 					}
 				}
 			}
 
 			if (args.background) {
 				if (mode !== "single") {
-					return {
-						content: [{ type: "text" as const, text: "`background` supports single mode only." }],
-						details: makeDetails([]),
-					};
+					return textResult("`background` supports single mode only.", makeDetails([]));
 				}
 				if (!agents.some((candidate) => candidate.name === args.agent)) {
-					return {
-						content: [
-							{
-								type: "text" as const,
-								text: `Unknown agent: "${args.agent ?? ""}". Available agents: ${formatAgentList(agents)}`,
-							},
-						],
-						details: makeDetails([]),
-					};
+					return textResult(
+						`Unknown agent: "${args.agent ?? ""}". Available agents: ${formatAgentList(agents)}`,
+						makeDetails([]),
+					);
 				}
 				const started = background.start(
 					{
@@ -259,19 +241,11 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 					},
 				);
 				if (!started.ok) {
-					return {
-						content: [{ type: "text" as const, text: started.error }],
-						details: makeDetails([]),
-					};
+					return textResult(started.error, makeDetails([]));
 				}
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text: `Started ${started.run.agent} as ${started.run.id} in the background. Use /agents to inspect, collect, or cancel it.`,
-						},
-					],
-					details: {
+				return textResult(
+					`Started ${started.run.agent} as ${started.run.id} in the background. Use /agents to inspect, collect, or cancel it.`,
+					{
 						...makeDetails([]),
 						background: {
 							runId: started.run.id,
@@ -281,7 +255,7 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 							startedAt: started.run.startedAt,
 						},
 					} satisfies SubagentDetails,
-				};
+				);
 			}
 
 			const context: ModeContext = {

package/extensions/subagent/orchestrate.ts

@@ -5,6 +5,7 @@
  */
 
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { failedResult, textResult } from "../../lib/tool-result.ts";
 import type { AgentConfig } from "./agents.ts";
 import type { TranscriptMode } from "./config.ts";
 import type { RunOptions } from "./run.ts";
@@ -73,25 +74,16 @@ export async function runChainMode(ctx: ModeContext): Promise<AgentToolResult<Su
 		results.push(result);
 
 		if (isFailedResult(result)) {
-			return {
-				content: [
-					{
-						type: "text" as const,
-						text: `Chain stopped at step ${i + 1} (${step.agent}): ${getResultOutput(result)}`,
-					},
-				],
-				details: makeDetails(results),
-				isError: true,
-			};
+			return failedResult(
+				`Chain stopped at step ${i + 1} (${step.agent}): ${getResultOutput(result)}`,
+				makeDetails(results),
+			);
 		}
 		previous = getFinalOutput(result.messages);
 	}
 
 	const last = results[results.length - 1];
-	return {
-		content: [{ type: "text" as const, text: last ? getFinalOutput(last.messages) || "(no output)" : "(no output)" }],
-		details: makeDetails(results),
-	};
+	return textResult(last ? getFinalOutput(last.messages) || "(no output)" : "(no output)", makeDetails(results));
 }
 
 /** Independent tasks with bounded concurrency, reporting running/done progress. */
@@ -104,10 +96,9 @@ export async function runParallelMode(ctx: ModeContext): Promise<AgentToolResult
 		if (!onUpdate) return;
 		const running = allResults.filter((r) => r.exitCode === -1).length;
 		const done = allResults.length - running;
-		onUpdate({
-			content: [{ type: "text", text: `Parallel: ${done}/${allResults.length} done, ${running} running…` }],
-			details: makeDetails([...allResults]),
-		});
+		onUpdate(
+			textResult(`Parallel: ${done}/${allResults.length} done, ${running} running…`, makeDetails([...allResults])),
+		);
 	};
 
 	const results = await mapWithConcurrencyLimit(tasks, MAX_CONCURRENCY, async (task, index) => {
@@ -146,15 +137,10 @@ export async function runParallelMode(ctx: ModeContext): Promise<AgentToolResult
 		return `### [${result.agent}] ${status}\n\n${output}`;
 	});
 
-	return {
-		content: [
-			{
-				type: "text" as const,
-				text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n---\n\n")}`,
-			},
-		],
-		details: makeDetails(results),
-	};
+	return textResult(
+		`Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n---\n\n")}`,
+		makeDetails(results),
+	);
 }
 
 /** One agent + task. */
@@ -176,20 +162,11 @@ export async function runSingleMode(ctx: ModeContext): Promise<AgentToolResult<S
 	});
 
 	if (isFailedResult(result)) {
-		return {
-			content: [
-				{
-					type: "text" as const,
-					text: `Agent ${result.agent} ${result.stopReason ?? "failed"}: ${getResultOutput(result)}`,
-				},
-			],
-			details: makeDetails([result]),
-			isError: true,
-		};
+		return failedResult(
+			`Agent ${result.agent} ${result.stopReason ?? "failed"}: ${getResultOutput(result)}`,
+			makeDetails([result]),
+		);
 	}
 
-	return {
-		content: [{ type: "text" as const, text: getFinalOutput(result.messages) || "(no output)" }],
-		details: makeDetails([result]),
-	};
+	return textResult(getFinalOutput(result.messages) || "(no output)", makeDetails([result]));
 }

package/extensions/subagent/render.ts

@@ -8,6 +8,11 @@
  *
  * Status and error rendering is shared across single- and multi-result modes so
  * a failed task never loses its message, regardless of how many tasks ran.
+ *
+ * The usage footnote follows the same grammar in every mode: a blank line, the
+ * faint metrics row, then the expand hint, so the affordance is always the
+ * block's last line. `format.ts` owns the row's text; it carries no money,
+ * because a price needs the footer's currency and tariff.
  */
 
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
@@ -20,7 +25,7 @@ import { expandHint, GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { centeredRule } from "../../lib/tui/rules.ts";
 import { BODY_INDENT } from "../../lib/tui/indent.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
-import { aggregateUsage, clip, formatToolCall, formatUsageStats } from "./format.ts";
+import { clip, formatToolCall, totalUsageLine, usageLine } from "./format.ts";
 import { COLLAPSED_ERROR_MAX, COLLAPSED_ITEM_COUNT, COLLAPSED_TEXT_LINES, type SubagentArgs } from "./schema.ts";
 import { getFinalOutput, isFailedResult } from "./stream.ts";
 import type { SingleResult, SubagentDetails } from "./types.ts";
@@ -132,27 +137,6 @@ function isExpandable(result: SingleResult, status: ResultStatus, items: Display
 	return hasExpandableContent(items) || hasClippedError(result, status);
 }
 
-/** "2 tool errors" / "1 tool error". */
-function toolErrorsLabel(count: number): string {
-	return `${count} tool error${count > 1 ? "s" : ""}`;
-}
-
-/** Usage plus a tool-error count when the subagent hit any. */
-function usageLine(result: SingleResult): string {
-	const base = formatUsageStats(result.usage, result.model);
-	if (!result.toolErrors) return base;
-	const label = toolErrorsLabel(result.toolErrors);
-	return base ? `${base} ${label}` : label;
-}
-
-/** The `Total:` usage line for a multi run, including summed tool errors. */
-function totalUsageLine(results: SingleResult[]): string {
-	const usage = formatUsageStats(aggregateUsage(results));
-	const errors = results.reduce((sum, result) => sum + (result.toolErrors ?? 0), 0);
-	const label = errors ? toolErrorsLabel(errors) : "";
-	return [usage, label].filter(Boolean).join(" ");
-}
-
 /** " 12s" while running or once finished, or "" when no start time was recorded. */
 function durationSuffix(result: SingleResult, status: ResultStatus, now: number): string {
 	if (!result.startedAt) return "";
@@ -306,6 +290,22 @@ function transcriptLine(result: SingleResult, theme: Theme): string | undefined
 	return paint(theme, "faint", `transcript: ${sanitizeLine(result.artifactPath)}${cut}`);
 }
 
+/** A blank line and one faint row: the shape every expanded footnote takes. */
+function addFaintRow(container: Container, theme: Theme, text: string): void {
+	container.addChild(new Spacer(1));
+	container.addChild(new Text(paint(theme, "faint", text), 0, 0));
+}
+
+/**
+ * The collapsed block's footnote: a blank line, the faint metrics row, then the
+ * expand hint. Both collapsed views end through here, so the metrics row and the
+ * affordance cannot swap places again.
+ */
+function collapsedFooter(theme: Theme, metrics: string, hinted: boolean): string {
+	const rows = metrics ? `\n\n${paint(theme, "faint", metrics)}` : "";
+	return hinted ? `${rows}\n${expandHint(theme)}` : rows;
+}
+
 /** Append one result's expanded block: header, error, task, output, usage. */
 function addExpandedResult(
 	container: Container,
@@ -359,15 +359,12 @@ function addExpandedResult(
 	}
 
 	const usage = usageLine(result);
-	if (usage) {
-		container.addChild(new Spacer(1));
-		container.addChild(new Text(paint(theme, "faint", usage), 0, 0));
-	}
+	if (usage) addFaintRow(container, theme, usage);
 	const transcript = transcriptLine(result, theme);
 	if (transcript) container.addChild(new Text(transcript, 0, 0));
 }
 
-/** The collapsed single result: header, a word, body, expand hint, and usage. */
+/** The collapsed single result: header, a word, body, and the shared footer. */
 function collapsedSingleText(result: SingleResult, theme: Theme, isPartial: boolean, now: number): string {
 	const status = resultStatus(result, isPartial);
 	// The leading blank line separates the result block from the call line, matching
@@ -377,10 +374,7 @@ function collapsedSingleText(result: SingleResult, theme: Theme, isPartial: bool
 	const displayItems = getDisplayItems(result.messages);
 	// A blank line separates the header from the body, matching the multi view.
 	text += `\n\n${collapsedBody(result, status, displayItems, theme)}`;
-	if (isExpandable(result, status, displayItems)) text += `\n${expandHint(theme)}`;
-	const usage = usageLine(result);
-	if (usage) text += `\n${paint(theme, "faint", usage)}`;
-	return text;
+	return text + collapsedFooter(theme, usageLine(result), isExpandable(result, status, displayItems));
 }
 
 function summarizeResults(results: SingleResult[]) {
@@ -445,12 +439,8 @@ function collapsedMultiText(details: SubagentDetails, theme: Theme, now: number)
 		text += statusSuffix(result, status, theme, now);
 		text += `\n${collapsedBody(result, status, displayItems, theme)}`;
 	}
-	if (running === 0) {
-		const usage = totalUsageLine(results);
-		if (usage) text += `\n\n${paint(theme, "faint", `Total: ${usage}`)}`;
-	}
-	if (running > 0 || hasHidden) text += `\n${expandHint(theme)}`;
-	return text;
+	const metrics = running === 0 ? totalUsageLine(results) : "";
+	return text + collapsedFooter(theme, metrics, running > 0 || hasHidden);
 }
 
 function fillExpandedMulti(container: Container, details: SubagentDetails, theme: Theme, now: number): void {
@@ -464,11 +454,8 @@ function fillExpandedMulti(container: Container, details: SubagentDetails, theme
 
 	const { running } = summarizeResults(details.results);
 	if (running === 0) {
-		const usage = totalUsageLine(details.results);
-		if (usage) {
-			container.addChild(new Spacer(1));
-			container.addChild(new Text(paint(theme, "faint", `Total: ${usage}`), 0, 0));
-		}
+		const total = totalUsageLine(details.results);
+		if (total) addFaintRow(container, theme, total);
 	}
 }
 

package/extensions/subagent/stream.ts

@@ -6,11 +6,13 @@
  */
 
 import type { Message } from "@earendil-works/pi-ai";
+import { asNumber, asRecord } from "../../lib/config.ts";
+import { USAGE_COUNTERS, type UsageCounts, zeroUsage } from "../../lib/usage.ts";
 import type { SingleResult, UsageStats } from "./types.ts";
 
 /** A zeroed usage accumulator. */
 export function emptyUsage(): UsageStats {
-	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+	return { ...zeroUsage(), contextTokens: 0, turns: 0 };
 }
 
 /** A fresh result for one subagent run; `exitCode: -1` marks it still running. */
@@ -29,6 +31,23 @@ export function parseJsonLine(line: string): Record<string, unknown> | undefined
 	}
 }
 
+/**
+ * The counters and context size one assistant message reported.
+ *
+ * The payload is a child process's JSON, so every number is read defensively: a
+ * string, `NaN`, or a missing field contributes nothing instead of concatenating
+ * into the accumulator or publishing a bogus recorded cost. `contextTokens` is
+ * the message's `totalTokens`, the occupancy of the child's window at that turn.
+ */
+function readUsage(raw: unknown): { counters: UsageCounts; contextTokens?: number } {
+	const usage = asRecord(raw);
+	const counters = zeroUsage();
+	for (const counter of USAGE_COUNTERS) counters[counter] = asNumber(usage?.[counter]) ?? 0;
+	// The wire nests the dollar amount one level down, as `{ total }`.
+	counters.cost = asNumber(asRecord(usage?.cost)?.total) ?? 0;
+	return { counters, contextTokens: asNumber(usage?.totalTokens) };
+}
+
 /**
  * Fold one parsed event into `result`.
  *
@@ -51,25 +70,12 @@ export function applyEvent(result: SingleResult, event: unknown): boolean {
 				model?: string;
 				stopReason?: string;
 				errorMessage?: string;
-				usage?: {
-					input?: number;
-					output?: number;
-					cacheRead?: number;
-					cacheWrite?: number;
-					totalTokens?: number;
-					cost?: { total?: number };
-				};
+				usage?: unknown;
 			};
 			result.usage.turns++;
-			const usage = assistant.usage;
-			if (usage) {
-				result.usage.input += usage.input ?? 0;
-				result.usage.output += usage.output ?? 0;
-				result.usage.cacheRead += usage.cacheRead ?? 0;
-				result.usage.cacheWrite += usage.cacheWrite ?? 0;
-				result.usage.cost += usage.cost?.total ?? 0;
-				result.usage.contextTokens = usage.totalTokens ?? result.usage.contextTokens;
-			}
+			const reported = readUsage(assistant.usage);
+			for (const counter of USAGE_COUNTERS) result.usage[counter] += reported.counters[counter];
+			if (reported.contextTokens !== undefined) result.usage.contextTokens = reported.contextTokens;
 			if (!result.provider && assistant.provider) result.provider = assistant.provider;
 			if (!result.model && assistant.model) result.model = assistant.model;
 			if (assistant.stopReason) result.stopReason = assistant.stopReason;

package/extensions/subagent/types.ts

@@ -24,6 +24,13 @@ export interface UsageStats {
 	turns: number;
 }
 
+/** The fields a usage line reads from one result. */
+export interface UsageSource {
+	usage: UsageStats;
+	model?: string;
+	toolErrors?: number;
+}
+
 /** Everything captured from one subagent subprocess. */
 export interface SingleResult {
 	agent: string;

package/extensions/todo/tools.ts

@@ -13,6 +13,7 @@
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { TODO_TOOL } from "../../lib/tool-names.ts";
+import { failedResult, textResult } from "../../lib/tool-result.ts";
 import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { normalizeTodos } from "../../lib/todo-state.ts";
 import { callLine, detailsOrLine, rejectionLine } from "../../lib/tui/tool.ts";
@@ -54,12 +55,10 @@ function toStructuredContent(todos: Todo[], action: "write" | "clear", error?: s
  */
 function todoResult(todos: Todo[], action: "write" | "clear", error?: string) {
 	const details: TodoDetails = error === undefined ? { todos, action } : { todos, action, error };
-	return {
-		content: [{ type: "text" as const, text: error === undefined ? formatTodoText(todos) : `Error: ${error}` }],
-		details,
-		structuredContent: toStructuredContent(todos, action, error),
-		...(error === undefined ? {} : { isError: true as const }),
-	};
+	const structuredContent = toStructuredContent(todos, action, error);
+	return error === undefined
+		? textResult(formatTodoText(todos), details, structuredContent)
+		: failedResult(`Error: ${error}`, details, structuredContent);
 }
 
 export function registerTools(pi: ExtensionAPI, runtime: TodoRuntime): void {

package/extensions/todo/tui.ts

@@ -161,13 +161,15 @@ export class TodoListComponent implements Component {
 
 		if (this.todos.length === 0) {
 			return dockListFrame({
+				theme: this.theme,
+				width: w,
 				header,
 				body: emptyState(this.theme, w, { label: "No todos yet. Ask the agent to plan some work." }),
 				hint: screenHint(this.theme, w, ["Esc close"]),
 			});
 		}
 
-		// header, summary, blank, blank-after-list, hint, blank
+		// header, summary, blank, blank-after-list, hint, closing rule
 		const chrome = 6;
 		this.visible = fitRows(this.viewportRowsSource, this.todos.length, chrome, SCREEN_DEFAULT_ITEMS);
 		this.scrollTop = clampScroll(this.scrollTop, this.todos.length, this.visible);
@@ -177,6 +179,8 @@ export class TodoListComponent implements Component {
 		for (let i = this.scrollTop; i < end; i++) body.push(todoRow(this.todos[i], this.theme, w));
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header,
 			summary: clip(`  ${paint(this.theme, "meta", progressSummary(this.todos))}`, w),
 			body,

package/extensions/watch/README.md

@@ -3,7 +3,8 @@
 Tail a file or a command's merged output, match each new line against a regular
 expression, and keep the matching lines. Matches are sanitized and alerted in
 the TUI, reported to the model at the next turn, or — when a watcher opts into
-`wake` — raise one triggered turn immediately.
+`wake` — raise one triggered turn as soon as the agent is idle, including right
+after a running turn settles.
 
 ```
 pi --extension ./extensions/watch    # load just this extension
@@ -29,7 +30,9 @@ How the `watch` call and its result look in the transcript — the call line as
 - Shows a `⊚ N` running-watcher chip and a `! N` unreported-match chip, raises a
   `ctx.ui.notify` alert once per unreported burst, and offers a `/watch` screen.
 - Reports pending matches to the model at the start of the next turn, or wakes a
-  turn for a watcher added with `wake: true`. A wake also leaves the terminal: the
+  turn for a watcher added with `wake: true` as soon as the agent is idle. A wake
+  that arrives mid-turn is raised once that run settles. A wake also leaves the
+  terminal: the
   match is announced on `my-pi-agent/watch-match`, which bytefly's
   [notify](../bytefly/README.md#notifications) capability turns into a desktop
   notification when `notify.enabled` and `notify.matchFound` are on.
@@ -172,8 +175,8 @@ other.
 - Matching is per line; a pattern cannot span a newline.
 - Only a **wake** match raises an OS notification, and only when bytefly's
   `notify.enabled` and `notify.matchFound` are on. A match collected while the
-  agent was busy is reported at the next turn without a notification, and `watch`
-  itself never sends one — it announces the match and bytefly owns delivery.
+  agent was busy notifies once that run settles, and `watch` itself never sends
+  one — it announces the match and bytefly owns delivery.
 
 ## Non-goals
 
@@ -213,7 +216,8 @@ UTF-8 sequence split across a read boundary is never mangled. State is
 session-only by design: a watcher is a live process or file position, not
 transcript state, so it cannot be faithfully rebuilt from a `/tree` fork. Match
 delivery mirrors `job` — reported at the next turn, with `wake` triggering one
-turn — so a match is never dropped when the wake window is busy. Stopping a
+turn as soon as the agent is idle — so a match is never dropped when the wake
+window is busy; a mid-turn wake is raised once that run settles. Stopping a
 command sends SIGTERM to its process group and escalates to SIGKILL after a 2 s
 grace; shutdown waits the same grace, so a command that ignores SIGTERM cannot
 outlive the session.