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

package/extensions/plan/web-markdown.ts

@@ -0,0 +1,222 @@
+/**
+ * The Markdown half of the review client script.
+ *
+ * It is a fragment of the same IIFE `web-client.ts` ships (`WEB_MARKDOWN_JS` is
+ * interpolated into `REVIEW_CLIENT_JS`), kept in its own module so the client's
+ * event wiring and its document rendering are read one at a time. Every value it
+ * writes is a DOM text node: plan and comment text never becomes markup, and the
+ * only HTML it copies is the server's own `tok-*` spans.
+ */
+
+export const WEB_MARKDOWN_JS = String.raw`  // A link is rendered only for an http(s) or mailto target. Resolving against
+  // the review origin is what catches a target that only looks relative: the
+  // URL parser strips a tab or newline, so "/\t/evil.com" is cross-origin once
+  // it is parsed, and a disguised target must stay text.
+  function safeHref(url, base) {
+    var trimmed = String(url).trim();
+    if (!trimmed || /^\/\//.test(trimmed)) return null;
+    var resolved;
+    try { resolved = new URL(trimmed, base); } catch (error) { return null; }
+    if (resolved.protocol === "mailto:") return trimmed;
+    if (resolved.protocol !== "http:" && resolved.protocol !== "https:") return null;
+    if (resolved.username || resolved.password) return null;
+    if (resolved.origin === new URL(base).origin) return resolved.href;
+    return /^https?:\/\//i.test(trimmed) ? resolved.href : null;
+  }
+
+  // Inline token order matters: code, emphasis, and links are matched before a
+  // bare URL, so a URL inside a link target or a code span is never re-split.
+  var INLINE = /(\x60[^\x60]+\x60|\*\*[^*]+\*\*|\*[^*]+\*|\[[^\]]+\]\([^)]+\)|(?:https?:\/\/|www\.)[^\s<]+)/g;
+
+  function renderInline(container, text) {
+    String(text).split(INLINE).forEach(function (part) {
+      if (!part) return;
+      var match;
+      if ((match = /^\x60([^\x60]+)\x60$/.exec(part))) {
+        var code = el("code"); code.textContent = match[1]; container.appendChild(code); return;
+      }
+      if ((match = /^\*\*([^*]+)\*\*$/.exec(part))) {
+        var strong = el("strong"); strong.textContent = match[1]; container.appendChild(strong); return;
+      }
+      if ((match = /^\*([^*]+)\*$/.exec(part))) {
+        var em = el("em"); em.textContent = match[1]; container.appendChild(em); return;
+      }
+      if ((match = /^\[([^\]]+)\]\(([^)]+)\)$/.exec(part))) {
+        var href = safeHref(match[2], location.href);
+        if (!href) { container.appendChild(document.createTextNode(part)); return; }
+        var link = el("a"); link.textContent = match[1]; link.href = href; link.target = "_blank"; link.rel = "noreferrer noopener";
+        container.appendChild(link); return;
+      }
+      // GFM extended autolink: a bare http(s) or www. URL in running text.
+      if ((match = /^(?:https?:\/\/|www\.)[^\s<]+$/.exec(part))) {
+        var url = match[0].replace(/[.,;:!?*_~]+$/, "");
+        while (url.charAt(url.length - 1) === ")" && (url.match(/\(/g) || []).length < (url.match(/\)/g) || []).length) {
+          url = url.slice(0, -1).replace(/[.,;:!?*_~]+$/, "");
+        }
+        var dot = url.indexOf(".");
+        var target = /^www\./i.test(url) ? "http://" + url : url;
+        var safe = dot > 0 && /\.[^./]/.test(url.slice(dot)) ? safeHref(target, location.href) : null;
+        if (safe) {
+          var auto = el("a");
+          auto.textContent = url;
+          auto.href = safe;
+          auto.target = "_blank";
+          auto.rel = "noreferrer noopener";
+          container.appendChild(auto);
+          return;
+        }
+      }
+      container.appendChild(document.createTextNode(part));
+    });
+  }
+
+  // Copy only text and tok-* spans out of server-highlighted HTML, so a code
+  // line can never introduce markup even though it arrives as a string.
+  function copyTokens(from, to) {
+    Array.prototype.forEach.call(from.childNodes, function (node) {
+      if (node.nodeType === 3) { to.appendChild(document.createTextNode(node.nodeValue)); return; }
+      if (node.nodeType === 1 && node.tagName === "SPAN" && /^tok-/.test(node.className || "")) {
+        var span = el("span", node.className);
+        copyTokens(node, span);
+        to.appendChild(span);
+        return;
+      }
+      to.appendChild(document.createTextNode(node.textContent || ""));
+    });
+  }
+
+  function codeBody(lines) {
+    var body = Array.isArray(lines) ? lines.slice() : [];
+    if (body.length && /^ {0,3}(\x60{3,}|~{3,})/.test(body[0])) body.shift();
+    if (body.length && /^ {0,3}(\x60{3,}|~{3,})/.test(body[body.length - 1])) body.pop();
+    return body;
+  }
+
+  function renderCode(wrap, block) {
+    var body = codeBody(block.lines);
+    var highlighted = data.code && data.code[String(block.start)];
+    var pre = el("pre", "bf-code");
+    var code = el("code");
+    if (Array.isArray(highlighted)) {
+      body.forEach(function (line, index) {
+        var span = el("span", "bf-code__line");
+        var html = highlighted[index];
+        if (html) {
+          try { copyTokens(new DOMParser().parseFromString(html, "text/html").body, span); }
+          catch (error) { span.textContent = line; }
+        } else {
+          span.textContent = line;
+        }
+        code.appendChild(span);
+        if (index < body.length - 1) code.appendChild(document.createTextNode("\n"));
+      });
+    } else {
+      code.textContent = body.join("\n");
+    }
+    pre.appendChild(code);
+    wrap.appendChild(pre);
+  }
+
+  // A GFM table: split each pipe row into cells and honour the alignment row.
+  function splitRow(line) {
+    var text = String(line).trim();
+    if (text.charAt(0) === "|") text = text.slice(1);
+    if (text.charAt(text.length - 1) === "|") text = text.slice(0, -1);
+    return text.split("|").map(function (cell) { return cell.trim(); });
+  }
+
+  function columnAlign(delim) {
+    return splitRow(delim).map(function (cell) {
+      var left = cell.charAt(0) === ":";
+      var right = cell.charAt(cell.length - 1) === ":";
+      return left && right ? "center" : right ? "right" : left ? "left" : "";
+    });
+  }
+
+  function renderTable(wrap, block) {
+    var rows = block.lines.map(splitRow);
+    var align = columnAlign(block.lines[1] || "");
+    var table = el("table", "review-table");
+    var thead = el("thead");
+    var headRow = el("tr");
+    rows[0].forEach(function (cell, index) {
+      var th = el("th");
+      if (align[index]) th.style.textAlign = align[index];
+      renderInline(th, cell);
+      headRow.appendChild(th);
+    });
+    thead.appendChild(headRow);
+    table.appendChild(thead);
+    var tbody = el("tbody");
+    rows.slice(2).forEach(function (cells) {
+      var tr = el("tr");
+      rows[0].forEach(function (unused, index) {
+        var td = el("td");
+        if (align[index]) td.style.textAlign = align[index];
+        renderInline(td, cells[index] || "");
+        tr.appendChild(td);
+      });
+      tbody.appendChild(tr);
+    });
+    table.appendChild(tbody);
+    var scroll = el("div", "review-table-wrap");
+    scroll.appendChild(table);
+    wrap.appendChild(scroll);
+  }
+
+  function renderBlockContent(wrap, block) {
+    var lines = Array.isArray(block.lines) ? block.lines : [];
+    if (block.kind === "heading") {
+      var text = lines.join(" ").replace(/^\s*#{1,6}\s*/, "");
+      var level = Math.min(6, Math.max(1, (lines[0].match(/^ {0,3}(#{1,6})/) || ["", "#"])[1].length));
+      var heading = el("h" + level);
+      renderInline(heading, text);
+      wrap.appendChild(heading);
+      return;
+    }
+    if (block.kind === "code") { renderCode(wrap, block); return; }
+    if (block.kind === "table") { renderTable(wrap, block); return; }
+    if (block.kind === "hr") { wrap.appendChild(el("hr")); return; }
+    if (block.kind === "quote") {
+      var quote = el("blockquote");
+      renderInline(quote, lines.map(function (line) { return line.replace(/^\s*>\s?/, ""); }).join("\n"));
+      wrap.appendChild(quote);
+      return;
+    }
+    if (block.kind === "list") {
+      var items = [];
+      lines.forEach(function (line) {
+        var match = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/.exec(line);
+        if (!match) {
+          // A following unmarked line is a CommonMark lazy continuation of the
+          // item above; join it so the paragraph hangs under the item's text.
+          var last = items[items.length - 1];
+          if (last) { if (line.trim()) last.rest += " " + line.trim(); return; }
+          var plain = el("p"); renderInline(plain, line); wrap.appendChild(plain); return;
+        }
+        var row = el("div", "bf-block__li");
+        row.style.paddingLeft = String(Math.floor(match[1].replace(/\t/g, "    ").length / 2) * 16) + "px";
+        var markerText = match[2];
+        var rest = match[3];
+        var box = /^\[([ xX])\]\s*(.*)$/.exec(rest);
+        var marker = el("span", "marker");
+        if (box) {
+          var done = box[1].toLowerCase() === "x";
+          markerText = done ? "\u2713" : "\u2610";
+          marker.className = done ? "bf-block__marker bf-block__marker--done" : "bf-block__marker";
+          rest = box[2];
+        }
+        marker.textContent = markerText;
+        var body = el("span");
+        row.appendChild(marker); row.appendChild(body); wrap.appendChild(row);
+        items.push({ body: body, rest: rest });
+      });
+      // Render each body once, after its continuation lines are collected.
+      items.forEach(function (item) { renderInline(item.body, item.rest); });
+      return;
+    }
+    var paragraph = el("p");
+    renderInline(paragraph, lines.join(" "));
+    wrap.appendChild(paragraph);
+  }
+`;

package/extensions/plan/web-page.ts

@@ -179,7 +179,16 @@ ${WEB_COMPONENTS_CSS}
 }
 @media (prefers-reduced-motion:no-preference){.bf-block{transition:background var(--motion-fast) var(--motion-ease)}}
 @media (hover:none){.bf-block__add{opacity:1}}
-`.trim();
+/* On paper the document is the whole page: no comment rail to hover, no composer,
+   no reading progress, and the comments stay with the blocks they belong to. */
+@media print{
+.bf-review{padding:0}
+.bf-review>.bf-block{max-width:none;padding:0 0 6px}
+.bf-block__rail,.bf-composer,.bf-block__add,.review-progress{display:none}
+.bf-block:hover,.bf-block--active{background:none;box-shadow:none}
+.bf-comments{padding-left:0}
+.bf-comment{break-inside:avoid}
+}`.trim();
 
 /**
  * The sidebar's one-line keyboard reminder. It names the keys a reviewer reaches
@@ -206,6 +215,22 @@ function reviewKeys(canApprove: boolean): KeyHint[] {
 	return rows;
 }
 
+/**
+ * The approval confirmation. Approving leaves plan mode and runs the plan, which
+ * cannot be undone from the page, so it is one deliberate dialog rather than the
+ * header button's single click. The shared `bf-dialog` styles and the shared
+ * dialog runtime supply the backdrop, the Tab trap, and `Esc`.
+ */
+function approveDialog(): string {
+	return `<div class="bf-dialog" id="approve-dialog" hidden>
+<div class="bf-dialog__panel" role="dialog" aria-modal="true" aria-labelledby="approve-title">
+<div class="bf-dialog__head"><h2 id="approve-title">Approve and run the plan?</h2></div>
+<div class="bf-dialog__body"><p>Pi leaves plan mode and starts the work. The comments you added are saved with the plan.</p><p class="bf-dialog__hint">Choose <strong>Approve &amp; run</strong> to go ahead, or <strong>Cancel</strong> to keep reviewing.</p></div>
+<div class="bf-dialog__actions"><button type="button" class="bf-btn" id="approve-cancel">Cancel</button><button type="button" class="bf-btn bf-btn--primary" id="approve-confirm">Approve &amp; run</button></div>
+</div>
+</div>`;
+}
+
 /**
  * Render the review page for `data`. The markup is a fixed shell; the client
  * fills every dynamic field, so this function is the only place that needs the
@@ -258,6 +283,7 @@ ${saveButton}
 ${outlinePanel}<main class="bf-app__main bf-review" id="plan" aria-label="Plan"></main>
 </div>
 ${keysSheet(reviewKeys(data.canApprove))}
+${data.canApprove ? approveDialog() : ""}
 <script type="application/json" id="review-data">${island}</script>
 <script src="/client.js" defer></script>
 </body>
@@ -271,7 +297,7 @@ ${keysSheet(reviewKeys(data.canApprove))}
  */
 function reviewFacts(): string {
 	return `<div class="review-facts" id="review-facts">
-<div class="review-fact"><span>Steps</span><span class="bf-progress"><span class="bf-progress__track"><span class="bf-progress__fill" id="step-fill"></span></span><span class="review-fact__value" id="step-count">0/0</span></span></div>
+<div class="review-fact" id="step-fact"><span>Steps</span><span class="bf-progress"><span class="bf-progress__track"><span class="bf-progress__fill" id="step-fill"></span></span><span class="review-fact__value" id="step-count">0/0</span></span></div>
 <div class="review-fact"><span>Comments</span><span class="review-fact__value" id="comment-total">0</span></div>
 </div>`;
 }

package/extensions/plan/web-router.ts

@@ -23,7 +23,7 @@ import {
 	scriptHeaders,
 	type ServeResponse,
 } from "../../lib/http/index.ts";
-import { THEME_JS } from "../../lib/web/index.ts";
+import { THEME_JS, THEME_JS_PATH } from "../../lib/web/index.ts";
 import { coerceAnnotations, type PlanAnnotation } from "./feedback.ts";
 import { REVIEW_CLIENT_JS } from "./web-client.ts";
 import { renderReviewPage, type ReviewPageData } from "./web-page.ts";
@@ -109,7 +109,7 @@ export async function handleReviewRequest(
 	const { pathname, search } = parsed;
 
 	if (pathname === "/favicon.ico") return { status: 204, headers: { "Cache-Control": "no-store" } };
-	if (pathname === "/theme.js") return { status: 200, headers: scriptHeaders(), body: THEME_JS };
+	if (pathname === THEME_JS_PATH) return { status: 200, headers: scriptHeaders(), body: THEME_JS };
 	if (pathname === "/client.js") return { status: 200, headers: scriptHeaders(), body: REVIEW_CLIENT_JS };
 
 	if (search.get("token") !== ctx.token) return jsonError(403, "Invalid or missing token.");

package/extensions/rewind/checklist.ts

@@ -152,6 +152,8 @@ export abstract class ChecklistScreen<T> implements Component {
 		const rows = this.rows();
 		if (rows.length === 0 && this.options.emptyLabel !== undefined) {
 			return dockListFrame({
+				theme: this.theme,
+				width: w,
 				header,
 				body: emptyState(this.theme, w, { label: this.options.emptyLabel }),
 				hint: this.hint(w),
@@ -172,6 +174,8 @@ export abstract class ChecklistScreen<T> implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header,
 			summary: clip(`  ${paint(this.theme, "meta", this.summaryText())}`, w),
 			body,

package/extensions/rewind/review-tui.ts

@@ -28,7 +28,7 @@ import { SELECTION_MARKS, type PathChange, type ReviewEntry } from "./paths.ts";
 
 /** Rows a diff screen shows when the terminal height is unknown. */
 const DIFF_DEFAULT_ITEMS = 20;
-/** Header, summary, blank, blank, hint, and blank rows around the diff. */
+/** Header, summary, blank, blank, hint, and closing-rule rows around the diff. */
 const DIFF_CHROME_ROWS = 6;
 
 /** Lines one wheel notch moves in the diff pane. */
@@ -294,6 +294,8 @@ export class ReviewDiffComponent implements Component {
 		if (body.length === 0) body.push(...emptyState(this.theme, w, { label: "No textual diff." }));
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header,
 			summary,
 			body,

package/extensions/rewind/rewind-tui.ts

@@ -79,6 +79,8 @@ export class RewindListComponent implements Component {
 
 		if (this.points.length === 0) {
 			return dockListFrame({
+				theme: this.theme,
+				width: w,
 				header,
 				body: emptyState(this.theme, w, { label: "No prompts on this branch yet." }),
 				hint: this.hint(w),
@@ -122,6 +124,8 @@ export class RewindListComponent implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header,
 			summary: clip(`  ${paint(this.theme, "meta", `${count}${SEPARATORS.item}newest first`)}`, w),
 			body,

package/extensions/subagent/README.md

@@ -275,9 +275,18 @@ child's system prompt for behavior; the tool list is the enforcement.
 → grep /retry/ in ~/src
 → read ~/src/http.ts:40-120
 Retries are configured in http.ts:64...
-2 turns ↑12.4k ↓1.1k R8.0k $0.0042 ctx:18.2k claude-sonnet-4-5
+
+2 turns ↑12.4k ↓1.1k R8.0k ctx:18.2k claude-sonnet-4-5
 ```
 
+The footnote is the same in every mode: a blank line, the faint usage row, then —
+when the run has more to show — the expand affordance, so the hint is always the
+block's last line. The row carries turns, token counts, context size, and the
+model — never money. A price needs a currency and a tariff, and those belong to
+the status bar, which shows every child run as its own `↳` roll-up priced in the
+configured currency (see [Non-goals](#non-goals)). A parallel or chain `Total:`
+row sums the counters, and names a model only when every task ran the same one.
+
 **Expanded** (the `app.tools.expand` key, `ctrl+o` by default): the full task,
 every intermediate assistant message and tool call, the final output rendered as
 Markdown, and per-step/per-task usage with a total.
@@ -296,7 +305,9 @@ the first failing step also reports `stopped at step N`. Running tasks show an
 elapsed-time label on the shared 1s repaint timer (the package's common
 duration format, e.g. `12.0s`), and a finished run keeps its duration. A result
 that hit tool errors appends `N tool errors` to its
-usage line (and to the multi `Total:`).
+usage line (and to the multi `Total:`). A usage payload the child reports with a
+non-number (a string, `NaN`) contributes nothing, so a malformed event cannot
+corrupt the row.
 
 A chain step's expanded `Task` section shows the step's original instruction,
 with `{previous}` left in place, rather than the substituted prior output that
@@ -317,15 +328,17 @@ step's `Output`.
   details; keeping it on disk is opt-in, parent-written, and bounded by age and
   count. It is an audit and handoff record, not a resume point: replaying a run
   whose writes already landed is not attempted.
-- **No cost attribution to the parent session.** A subagent's tokens and cost are
+- **No cost attribution to the parent session.** A subagent's token counts are
   captured in the tool result and shown in the transcript, but they belong to a
-  separate process and are not added to the dispatching session's totals. Instead,
-  each finished run publishes `my-pi-agent/subagent-finished`
-  (`SubagentFinishedEvent` in `lib/events.ts`) and bytefly's footer shows the
-  session's child runs as their own `↳` roll-up, priced separately from the
-  session total (the last 500 runs). The roll-up is per process: a resumed session
-  starts from zero, and a run that never produced an assistant message publishes
-  nothing.
+  separate process and are not added to the dispatching session's totals. The
+  child's own dollar cost stays in the tool details (and in a run's `meta.json`)
+  and is never printed in the transcript: only the status bar prices a delegated
+  run, in the configured currency and tariff. Each finished run publishes
+  `my-pi-agent/subagent-finished` (`SubagentFinishedEvent` in `lib/events.ts`)
+  and bytefly's footer shows the session's child runs as their own `↳` roll-up,
+  priced separately from the session total (the last 500 runs). The roll-up is
+  per process: a resumed session starts from zero, and a run that never produced
+  an assistant message publishes nothing.
 
 ## Limitations
 
@@ -421,7 +434,7 @@ step's `Output`.
 | `agents.ts` | Built-in agent definitions, external markdown discovery, and pool resolution. |
 | `schema.ts` | TypeBox params, limits, and `resolveMode`. |
 | `invocation.ts` | `pi` subprocess invocation and argument construction. |
-| `stream.ts` | JSON-event parsing, usage accounting, output helpers (pure). |
+| `stream.ts` | JSON-event parsing, guarded usage accounting, output helpers (pure). |
 | `transcripts.ts` | Per-run transcript buffer, run ids, the store directory, and pruning. |
 | `config.ts` | The `subagent` section of `bytefly.json`: deadline, transcripts, retention. |
 | `run.ts` | Runs one subagent process and captures its result (including the background abort-as-result path). |
@@ -429,6 +442,6 @@ step's `Output`.
 | `background-tui.ts` | The `/agents` board: a `DockListScreen` with a live output pane and width-aware facts. |
 | `commands.ts` | The `/agents` command. |
 | `ui.ts` | The running-count footer chip and finish notices. |
-| `format.ts` | Token/usage/tool-call formatting (pure). |
+| `format.ts` | Token/usage/total line and tool-call formatting (pure, money-free). |
 | `render.ts` | `renderCall` / `renderResult` transcript rendering. |
 | `types.ts` | Shared result and process types. |

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). */