@maxiaochao/pi-toolkit 0.10.2 → 0.10.3

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2026-10-08 - v0.10.3
+
+- bundle herdr-subagents v0.4.0: add the live compact Fleet footer with authoritative metrics and refreshed media
+- Add the responsive below-editor Herdr Fleet monitor with real personas, task states, cumulative active durations, and authoritative child Pi token totals, including event-driven live updates and safe partial-JSONL handling.
+- Color running Fleet rows yellow and completed rows green, compact the shared metrics column instead of pushing it to the terminal edge, and update the published media with focus restoration after capture.
+
 ## 2026-10-08 - v0.10.2
 
 - bundle herdr-subagents v0.3.0: split execution and control tools and unify task runs
@@ -183,6 +189,7 @@
 
 ## Unreleased
 
+- redesign bundled Todo as a branch-local execution plan with lifecycle-only model actions, expected-current guards, serialized calls, preserved branch history, and a live current-plan widget
 - let `/cache_export` switch between all history and individual compaction-defined Context segments, defaulting to the latest segment; cache-hit cumulative lines reset at compaction or model boundaries
 - add the independent `@maxiaochao/pi-codex-edit` package with model-aware Codex-style `apply_patch`
 - include the benchmark summary and interactive HTML architecture explainer

package/README.md

@@ -22,7 +22,7 @@ The root package embeds the child-package source snapshots listed below. Install
 
 | Package | Capability | Install | Update |
 |---|---|---|---|
-| [pi-todo](packages/todo/README.md) | Session plans, automatic task advancement, `/todos` | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` |
+| [pi-todo](packages/todo/README.md) | Branch-local execution plans, guarded advancement, `/todos` history | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` |
 | [pi-cache-export](packages/cache-export/README.md) | Tau-aligned interactive cache dashboard for Pi sessions | `pi install npm:@maxiaochao/pi-cache-export` | `pi update npm:@maxiaochao/pi-cache-export` |
 | [pi-codex-edit](packages/codex-edit/README.md) | Codex-harness `apply_patch` routing for selected GPT models | `pi install npm:@maxiaochao/pi-codex-edit` | `pi update npm:@maxiaochao/pi-codex-edit` |
 | [pi-herdr-subagents](packages/herdr-subagents/README.md) | Interactive Herdr Pi Agents with bounded concurrency, direct navigation, and recovery | `pi install npm:@maxiaochao/pi-herdr-subagents` | `pi update npm:@maxiaochao/pi-herdr-subagents` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.2",
-  "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
+  "version": "0.10.3",
+  "description": "Personal pi coding agent toolkit: execution plans, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
     "packages/*"

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-10-08 - v0.4.0
+
+- add the live compact Fleet footer with authoritative metrics and refreshed media
+- Replace the below-editor task list with a compact responsive Fleet monitor showing authoritative persona, task status, cumulative active time, and true child Pi usage from assistant, tool-result, standalone usage, compaction, and branch-summary entries.
+- Update Fleet metrics from child-session file events, repaint elapsed time only while work runs, safely ignore malformed or partial JSONL tails, and dispose every watcher and timer with the widget.
+- Preserve exact-pane keyboard focus while extending blocked-response and historical-resume activity projections with durable timing and session metadata.
+- Use warning/yellow indicators for running Fleet rows and success/green indicators for completed rows, compact the shared metrics column instead of pushing it to the terminal edge, and publish media that demonstrates the live parent footer while restoring focus after capture.
+
 ## 2026-10-08 - v0.3.0
 
 - split execution and control tools and unify task runs

package/packages/herdr-subagents/README.md

@@ -2,16 +2,15 @@
 
 A Pi extension that runs focused foreground or background work as normal interactive Pi Agents in visible Herdr panes. Full answers and sessions stay in project-local records while the parent receives only concise summaries and document paths.
 
-![A parent Pi conversation running three visible Herdr Subagents panes](docs/screenshot.png)
+![A parent Pi conversation showing the live Herdr Subagents Fleet footer](docs/screenshot.png)
 
 ## Demo
 
-The recording shows a real Pi conversation invoking a three-task read-only batch, Herdr opening one interactive Agent pane per task, and the compact results returning to the parent.
+The recording shows a real Pi conversation invoking a three-task read-only batch, the active Fleet footer in the parent, Herdr opening one interactive Agent pane per task, and the compact results returning to the parent.
 
 https://github.com/user-attachments/assets/8ddf3ae6-a11a-492b-9cae-d9496ba65b67
 
-The video starts a three-agent batch, focuses each live child pane in turn, then returns
-to the parent summary. The reproducible source recording is retained as [`docs/demo.webm`](docs/demo.webm).
+The video starts a three-agent batch, focuses each live child pane in turn, captures the parent Fleet footer with yellow running indicators and true usage, then returns to the parent summary. Completed Fleet rows use green indicators. The reproducible source recording is retained as [`docs/demo.webm`](docs/demo.webm).
 
 ## Requirements and install
 
@@ -73,7 +72,9 @@ A child missing required information reports `needs-input` with an exact questio
 herdr_subagents_control({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
 ```
 
-While a batch is active, its task rows stay below the editor. With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback.
+While a batch is active, a compact Fleet monitor stays below the editor. Its divider/title row summarizes the run, and each task row shows a hollow or filled status circle, the real persona and task name, status, live active duration, and cumulative child Pi token usage in one compact shared metrics column after the longest row rather than at the terminal edge. Running work uses Pi's warning/yellow semantic color and completed work uses success/green. Token totals use the child session's persisted assistant, tool-result, standalone usage, compaction, and branch-summary usage; they are never estimated. Queued tasks show neither fabricated time nor tokens. The monitor follows Pi theme semantics, truncates by visible terminal columns, and updates session usage from file events while one lightweight repaint timer advances running durations.
+
+With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback.
 
 ## History
 
@@ -83,7 +84,7 @@ Continue a saved conversation in a new Herdr tab with `herdr_subagents_control({
 
 Read-only tasks start FIFO up to the configured concurrency limit. A pane is created only when its task starts, belongs exclusively to that task, and is never reused. Completed panes remain inspectable while another task in the batch is unsettled. Results remain in input order, and one failed task does not cancel its siblings. Any batch containing a write-capable persona is forced to concurrency one.
 
-The widget shows one row per queued, running, blocked, failed, or completed task. Answering a blocked task refreshes rows and pane IDs as that task resumes and queued siblings start. Completed rows remain selectable until the whole batch settles. `/herdr-subagents active` shows the same compact state. Native labels stay short: `SA · <batch>` for the tab and `<order> · <task>` for each pane. When all tasks settle, the tab closes immediately if unfocused or after the user leaves it; a deferred close failure is persisted and shown as a warning.
+The widget shows one row per queued, running, blocked, failed, or completed task. Answering a blocked task or resuming saved history refreshes authoritative persona, timing, session, status, and pane projections as work advances. Active duration accumulates only while the task is running, excluding time spent queued or waiting for an answer. Completed rows remain selectable until the whole batch settles. `/herdr-subagents active` shows the same compact state. Native labels stay short: `SA · <batch>` for the tab and `<order> · <task>` for each pane. When all tasks settle, the tab closes immediately if unfocused or after the user leaves it; a deferred close failure is persisted and shown as a warning.
 
 Foreground calls block until all children report completion, failure, or a request for input. Every child is started with Herdr's Agent lifecycle as a normal Pi TUI and prompted with wait semantics; no print-mode command or completion marker is injected into the pane.
 

package/packages/herdr-subagents/TESTING.md

@@ -4,9 +4,9 @@
 
 1. `npm --prefix packages/herdr-subagents test` runs deterministic scheduler, recovery, and persona tests.
 2. `pi -ne -ns --no-session -e ./packages/herdr-subagents/extensions/herdr-subagents.ts` verifies extension loading.
-3. From a visible X11 Herdr client with the GStreamer X11 and VP8 plugins installed, run `HERDR_MEDIA_WINDOW_ID=<window-id> node scripts/capture-package-media.mjs`. The Herdr capture must show a parent Pi conversation, a three-task run tab, each of the three real interactive Agent panes receiving focus in turn, and the final compact parent response.
+3. From a dedicated visible X11 Herdr client/window with the GStreamer X11 and VP8 plugins installed, run `HERDR_MEDIA_WINDOW_ID=<window-id> node scripts/capture-package-media.mjs`. Capture intentionally cycles through the live child panes, so avoid using that client/window for other work while recording; the script restores the previously focused pane afterward when it still exists. The Herdr capture must show a parent Pi conversation, a three-task run tab, each of the three real interactive Agent panes receiving focus in turn, the active parent Fleet footer with yellow running indicators and real metrics, and the final compact parent response. The published screenshot must be the parent Fleet view, while the full WebM preserves the parent → three focused children → Fleet → parent sequence.
 4. `npm pack ./packages/herdr-subagents --dry-run` verifies package contents.
-5. Verify the README renders the GitHub attachment video directly and live Herdr UI media `docs/screenshot.png` and `docs/demo.webm` are present in the tarball; `docs/demo.gif` must be absent. Inspect the WebM metadata and play it through once to confirm the parent → three focused children → parent sequence.
+5. Verify the README renders the GitHub attachment video directly and live Herdr UI media `docs/screenshot.png` and `docs/demo.webm` are present in the tarball; `docs/demo.gif` must be absent. Inspect the WebM metadata and play it through once to confirm the parent → three focused children → Fleet → parent sequence.
 
 ## Cases
 
@@ -17,9 +17,11 @@
 - Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
 - Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
 - Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify Fleet divider/row formatting, warning/yellow running indicators, success/green completed indicators, persona and task projections, cumulative active duration across blocking/resume, exact Pi usage aggregation from assistant messages, tool results, standalone usage, compaction, and branch summaries, malformed/truncated JSONL tolerance, queued metric omission, and visible-column bounds at narrow widths.
+- Verify live token updates are file-event driven, elapsed repainting exists only while work runs, and widget disposal closes watchers and timers.
 - Verify blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
 - Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
 
 ## Latest baseline
 
-All 137 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.
+All 159 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.

package/packages/herdr-subagents/extensions/herdr-subagents.ts

@@ -12,7 +12,7 @@ import { cancelActiveSubagentRuns, reconcileSubagentRuns } from "../src/reconcil
 import { executeHerdrSubagents, executeHerdrSubagentsControl, type HerdrSubagentsBatchDetails, type HerdrSubagentsControlToolParams, type HerdrSubagentsDetails, type HerdrSubagentsRunParams } from "../src/tool.ts";
 import { HerdrSubagentsControlParams, HerdrSubagentsParams } from "../src/parameters.ts";
 import { HERDR_ACTIONS } from "../src/validation.ts";
-import { FleetController } from "../src/fleet-controller.ts";
+import { FleetController, type FleetWidgetRuntime } from "../src/fleet-controller.ts";
 import { isSettledRunStatus } from "../src/records.ts";
 
 const packageAgentsDir = fileURLToPath(new URL("../agents/", import.meta.url));
@@ -121,6 +121,7 @@ export interface HerdrSubagentsExtensionDependencies {
 	executeControl?: typeof executeHerdrSubagentsControl;
 	isEditor?: (value: unknown) => boolean;
 	createFleetWidget?: (lines: string[]) => Container;
+	fleetWidgetRuntime?: FleetWidgetRuntime;
 }
 
 async function recoverParentSession(cwd: string, herdr: HerdrAutomation, owner: { sessionId?: string; processId: number }, notify: (message: string) => void): Promise<void> {
@@ -157,7 +158,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	const executeControl = dependencies.executeControl ?? executeHerdrSubagentsControl;
 	const isEditorComponent = dependencies.isEditor ?? ((value: unknown) => value instanceof Editor);
 	const dispatcher = new RunDispatcher();
-	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget);
+	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget, dependencies.fleetWidgetRuntime);
 	const runControllers = new Map<string, AbortController>();
 	const inFlight = new Set<Promise<unknown>>();
 	let sessionController = new AbortController();

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

package/packages/herdr-subagents/src/batch-runner.ts

@@ -10,7 +10,7 @@ import { writeJsonAtomic } from "./state.ts";
 import type { OwnerIdentity } from "./ownership.ts";
 import { ownerRecord } from "./ownership.ts";
 import { RunPaneAllocator } from "./run-pane-allocator.ts";
-import { applyReport, applyTaskStatus, settleAttemptFailure, type PersistedReport, type RunRecord, type TaskRecord, type TaskStatus } from "./records.ts";
+import { applyReport, applyTaskStatus, projectTaskActivity, settleAttemptFailure, type PersistedReport, type RunRecord, type TaskActivity, type TaskRecord, type TaskStatus } from "./records.ts";
 import { reportProtocolPrompt } from "./protocol.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import { applyRunStatus } from "./run-status.ts";
@@ -63,7 +63,7 @@ export interface BatchResult {
 	requestedConcurrency: number;
 	effectiveConcurrency: number;
 	tasks: BatchTaskResult[];
-	activity: Array<{ index: number; name: string; status: BatchTaskStatus; paneId?: string }>;
+	activity: TaskActivity[];
 	summary: string;
 	documents: HerdrSubagentsDocument[];
 	recordDirectory: string;
@@ -114,7 +114,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 	await writeJsonAtomic(runFile, runRecord);
 	const herdr = options.herdr ?? new CliHerdrAutomation();
 	const results = new Array<BatchTaskResult>(tasks.length);
-	const activity: BatchResult["activity"] = tasks.map((task, index) => ({ index, name: task.name, status: "queued" }));
+	const activity: BatchResult["activity"] = contexts.map((context, index) => projectTaskActivity(context.taskRecord, index));
 	let tabId: string | undefined;
 	const paneAllocator = new RunPaneAllocator({ herdr, run: runRecord, runFile, signal: options.signal, onCleanupError: options.onCleanupError });
 	const emit = (status: BatchResult["status"], summary: string) => options.onUpdate?.({
@@ -146,7 +146,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 				applyTaskStatus(context.taskRecord, "running");
 				Object.assign(context.taskRecord, { tabId, paneId, paneLabel, agentName, startedAt: timestamp() });
 				await writeJsonAtomic(context.taskFile, context.taskRecord);
-				activity[index] = { index, name: task.name, status: "running", paneId };
+				activity[index] = projectTaskActivity(context.taskRecord, index);
 				emit("running", `${settled}/${tasks.length} tasks settled.`);
 				const prompted = await promptLiveAgent({ herdr, task: { ...task, id: context.taskId, sessionFile: context.sessionFile }, paneId, prompt: task.prompt, systemPromptFile: context.systemPromptFile, agentName, signal: options.signal, stalledWarningMs: options.stalledWarningSeconds ? options.stalledWarningSeconds * 1000 : undefined, onStalled: () => emit("running", `${task.name} appears stalled; it is still running.`) });
 				agentName = prompted.agentName;
@@ -164,7 +164,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 			Object.assign(context.taskRecord, { paneId, agentName });
 			await writeJsonAtomic(context.taskFile, context.taskRecord);
 			results[index] = { index, name: task.name, status, summary: report.summary, documents: report.documents, ...(report.error ? { error: report.error } : {}), ...(report.question ? { question: report.question } : {}), paneId, recordDirectory: context.taskDirectory, sessionFile: context.sessionFile };
-			activity[index] = { index, name: task.name, status, ...(paneId ? { paneId } : {}) };
+			activity[index] = projectTaskActivity(context.taskRecord, index);
 			settled += 1;
 			emit("running", `${settled}/${tasks.length} tasks settled.`);
 		};

package/packages/herdr-subagents/src/blocking.ts

@@ -9,7 +9,7 @@ import { cleanupRunTab } from "./tab-cleanup.ts";
 import type { OwnerIdentity } from "./ownership.ts";
 import { ownerRecord } from "./ownership.ts";
 import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
-import { applyReport, applyTaskStatus, isActiveStatus, persistFailureReport, readReport, readRunRecord, readTaskRecord, readTurnRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type TaskRecord, type TaskStatus, type TurnRecord } from "./records.ts";
+import { applyReport, applyTaskStatus, isActiveStatus, persistFailureReport, projectTaskActivity, readReport, readRunRecord, readTaskRecord, readTurnRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type TaskActivity, type TaskRecord, type TaskStatus, type TurnRecord } from "./records.ts";
 import { isAbortError } from "./errors.ts";
 import { continuationSystemPrompt } from "./protocol.ts";
 import { RunPaneAllocator } from "./run-pane-allocator.ts";
@@ -28,7 +28,7 @@ export interface ResumeBlockedResult {
 	requestedConcurrency: number;
 	effectiveConcurrency: number;
 	tasks?: Array<{ index: number; name: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; error?: string; question?: string; paneId: string; recordDirectory: string; sessionFile: string }>;
-	activity?: Array<{ index: number; name: string; status: TaskStatus; paneId?: string }>;
+	activity?: TaskActivity[];
 	tabId?: string;
 }
 
@@ -45,7 +45,7 @@ async function emitProgress(options: RespondToBlockedTaskOptions, runDirectory:
 		recordDirectory: runDirectory,
 		requestedConcurrency: Number(run.requestedConcurrency ?? 1),
 		effectiveConcurrency: Number(run.effectiveConcurrency ?? 1),
-		activity: tasks.map((entry, index) => ({ index, name: String(entry.name ?? entry.agent ?? `Task ${index + 1}`), status: entry.status, ...(entry.paneId ? { paneId: entry.paneId } : {}) })),
+		activity: tasks.map((entry, index) => projectTaskActivity(entry, index)),
 		...(run.tabId ? { tabId: run.tabId } : {}),
 	});
 }
@@ -73,7 +73,7 @@ async function projectSettledRun(runDirectory: string, runFile: string, run: Run
 	await writeJsonAtomic(runFile, run);
 	if (runStatus !== "blocked" && run.tabId) await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, onError: onCleanupError, failureStatus: "failed" });
 	const summary = runStatus === "completed" ? "All tasks completed after the answer." : runStatus === "blocked" ? `${finalTasks[blockedIndex]?.name ?? "Task"} needs input: ${blockedReport?.question ?? "Input required."}` : finalReports.map((entry, index) => `${finalTasks[index].name}: ${entry.summary}`).join("\n");
-	const activity = finalTasks.map((entry, index) => ({ index, name: String(entry.name ?? entry.agent ?? `Task ${index + 1}`), status: entry.status, ...(entry.paneId ? { paneId: String(entry.paneId) } : {}) }));
+	const activity = finalTasks.map((entry, index) => projectTaskActivity(entry, index));
 	const tasks = finalTasks.map((entry, index) => ({ index, name: activity[index].name, status: entry.status, summary: String(finalReports[index].summary ?? "Task has no report."), documents: finalReports[index].documents ?? [], ...(entry.error ? { error: String(entry.error) } : {}), ...(entry.question ? { question: String(entry.question) } : {}), paneId: String(entry.paneId ?? ""), recordDirectory: taskDirectories[index], sessionFile: String(entry.sessionFile ?? "") }));
 	return { ok: runStatus === "completed", runId: run.id, label: String(run.label ?? "batch"), status: runStatus, summary, ...(blockedReport?.question ? { question: blockedReport.question } : {}), documents: finalReports.flatMap((entry) => entry.documents ?? []), recordDirectory: runDirectory, requestedConcurrency: Number(run.requestedConcurrency ?? run.effectiveConcurrency ?? 1), effectiveConcurrency: Number(run.effectiveConcurrency ?? 1), tasks, activity, ...(run.tabId ? { tabId: String(run.tabId) } : {}) };
 }

package/packages/herdr-subagents/src/fleet-controller.ts

@@ -1,40 +1,175 @@
+import { watch } from "node:fs";
+import { basename, dirname } from "node:path";
 import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import { Container, isKeyRelease, matchesKey, Text } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, isKeyRelease, matchesKey, type Component, type TUI } from "@earendil-works/pi-tui";
 import type { HerdrAutomation } from "./herdr.ts";
-import { fleetEditorHasFocus, FleetSelection, fleetLines } from "./fleet.ts";
+import { fleetEditorHasFocus, FleetSelection, fleetLines, readSessionTokens, type FleetTaskMetrics } from "./fleet.ts";
 import { focusActiveTask } from "./monitor.ts";
 import { isActiveStatus } from "./records.ts";
 import type { HerdrSubagentsBatchDetails } from "./tool.ts";
 
+interface Closable { close(): void; }
+export interface FleetWidgetRuntime {
+	watchSession(path: string, onChange: () => void, onError: () => void): Closable;
+	setInterval(callback: () => void, ms: number): unknown;
+	clearInterval(handle: unknown): void;
+	setTimeout(callback: () => void, ms: number): unknown;
+	clearTimeout(handle: unknown): void;
+	readTokens(path: string): Promise<number | undefined>;
+}
+
+const defaultFleetWidgetRuntime: FleetWidgetRuntime = {
+	watchSession(path, onChange, onError) {
+		const watcher = watch(dirname(path), (_event, filename) => {
+			if (!filename || filename.toString() === basename(path)) onChange();
+		});
+		watcher.on("error", () => { watcher.close(); onError(); });
+		return watcher;
+	},
+	setInterval: (callback, ms) => setInterval(callback, ms),
+	clearInterval: (handle) => clearInterval(handle as ReturnType<typeof setInterval>),
+	setTimeout: (callback, ms) => setTimeout(callback, ms),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+	readTokens: readSessionTokens,
+};
+
+export class FleetWidget implements Component {
+	private readonly tui: TUI;
+	private readonly theme: Theme;
+	private readonly selection: FleetSelection;
+	private readonly runtime: FleetWidgetRuntime;
+	private batch: HerdrSubagentsBatchDetails;
+	private readonly metrics = new Map<number, FleetTaskMetrics>();
+	private readonly watchers = new Map<string, Closable>();
+	private elapsedTimer?: unknown;
+	private refreshTimer?: unknown;
+	private generation = 0;
+	private disposed = false;
+	private sourceKey = "";
+
+	constructor(tui: TUI, theme: Theme, batch: HerdrSubagentsBatchDetails, selection: FleetSelection, runtime: FleetWidgetRuntime = defaultFleetWidgetRuntime) {
+		this.tui = tui;
+		this.theme = theme;
+		this.selection = selection;
+		this.runtime = runtime;
+		this.batch = batch;
+		this.configureLiveUpdates();
+	}
+
+	update(batch: HerdrSubagentsBatchDetails): void {
+		if (this.disposed) return;
+		this.batch = batch;
+		this.configureLiveUpdates();
+		this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		return fleetLines(this.batch, this.selection, { width, metrics: this.metrics, theme: this.theme });
+	}
+
+	invalidate(): void {}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.generation += 1;
+		for (const watcher of this.watchers.values()) watcher.close();
+		this.watchers.clear();
+		if (this.elapsedTimer) this.runtime.clearInterval(this.elapsedTimer);
+		if (this.refreshTimer) this.runtime.clearTimeout(this.refreshTimer);
+		this.elapsedTimer = undefined;
+		this.refreshTimer = undefined;
+	}
+
+	private configureLiveUpdates(): void {
+		const sessionFiles = new Set(this.batch.activity.map((task) => task.sessionFile).filter((path): path is string => Boolean(path)));
+		const nextSourceKey = `${this.batch.runId}\n${[...sessionFiles].sort().join("\n")}`;
+		if (nextSourceKey !== this.sourceKey) {
+			this.sourceKey = nextSourceKey;
+			this.generation += 1;
+			this.metrics.clear();
+		}
+		for (const [path, watcher] of this.watchers) {
+			if (sessionFiles.has(path)) continue;
+			watcher.close();
+			this.watchers.delete(path);
+		}
+		for (const path of sessionFiles) {
+			if (this.watchers.has(path)) continue;
+			try {
+				const watcher = this.runtime.watchSession(path, () => this.scheduleMetricsRefresh(), () => this.watchers.delete(path));
+				this.watchers.set(path, watcher);
+			} catch { /* The next durable activity update can retry the watch. */ }
+		}
+		const hasRunning = this.batch.activity.some((task) => task.status === "running");
+		if (hasRunning && !this.elapsedTimer) this.elapsedTimer = this.runtime.setInterval(() => this.tui.requestRender(), 1_000);
+		else if (!hasRunning && this.elapsedTimer) { this.runtime.clearInterval(this.elapsedTimer); this.elapsedTimer = undefined; }
+		this.scheduleMetricsRefresh(0);
+	}
+
+	private scheduleMetricsRefresh(delay = 25): void {
+		if (this.disposed) return;
+		if (this.refreshTimer) this.runtime.clearTimeout(this.refreshTimer);
+		this.refreshTimer = this.runtime.setTimeout(() => { this.refreshTimer = undefined; void this.refreshMetrics(); }, delay);
+	}
+
+	private async refreshMetrics(): Promise<void> {
+		const generation = ++this.generation;
+		const next = await Promise.all(this.batch.activity.map(async (task) => ({ index: task.index, tokens: task.sessionFile ? await this.runtime.readTokens(task.sessionFile) : undefined })));
+		if (this.disposed || generation !== this.generation) return;
+		this.metrics.clear();
+		for (const metric of next) if (metric.tokens !== undefined) this.metrics.set(metric.index, { tokens: metric.tokens });
+		this.tui.requestRender();
+	}
+}
+
 export class FleetController {
+	private readonly herdr: HerdrAutomation;
+	private readonly isEditor: (value: unknown) => boolean;
+	private readonly createWidget?: (lines: string[]) => Container;
+	private readonly widgetRuntime: FleetWidgetRuntime;
 	private activeBatch?: HerdrSubagentsBatchDetails;
 	private readonly selection = new FleetSelection(matchesKey);
 	private unsubscribeInput?: () => void;
 	private ui?: ExtensionUIContext;
-	private tui?: { focusedComponent?: unknown };
+	private tui?: TUI;
+	private widget?: FleetWidget;
 
-	constructor(
-		private readonly herdr: HerdrAutomation,
-		private readonly isEditor: (value: unknown) => boolean,
-		private readonly createWidget?: (lines: string[]) => Container,
-	) {}
+	constructor(herdr: HerdrAutomation, isEditor: (value: unknown) => boolean, createWidget?: (lines: string[]) => Container, widgetRuntime: FleetWidgetRuntime = defaultFleetWidgetRuntime) {
+		this.herdr = herdr;
+		this.isEditor = isEditor;
+		this.createWidget = createWidget;
+		this.widgetRuntime = widgetRuntime;
+	}
 
 	get active(): HerdrSubagentsBatchDetails | undefined { return this.activeBatch; }
 
 	bind(ui: ExtensionUIContext, tuiMode: boolean): void {
 		this.unsubscribeInput?.();
+		if (this.ui && this.ui !== ui) {
+			this.ui.setWidget("herdr-subagents", undefined, { placement: "belowEditor" });
+			this.widget = undefined;
+			this.tui = undefined;
+		}
 		this.ui = ui;
 		this.unsubscribeInput = tuiMode ? ui.onTerminalInput((data) => this.handleInput(data)) : undefined;
+		if (this.activeBatch) this.render();
 	}
 
 	sync(details: unknown): void {
+		if (!this.ui) return;
 		const batch = details as Partial<HerdrSubagentsBatchDetails>;
 		if (!batch.activity || !batch.label || !batch.status) return;
+		if (this.activeBatch && batch.runId !== this.activeBatch.runId) return;
+		if (this.activeBatch?.runId !== batch.runId) this.selection.reset();
 		this.activeBatch = isActiveStatus(batch.status) ? batch as HerdrSubagentsBatchDetails : undefined;
 		this.render();
 	}
 
 	setActive(batch: HerdrSubagentsBatchDetails | undefined): void {
+		if (!this.ui) return;
+		if (this.activeBatch?.runId !== batch?.runId) this.selection.reset();
 		this.activeBatch = batch;
 		this.render();
 	}
@@ -53,18 +188,31 @@ export class FleetController {
 		this.activeBatch = undefined;
 		this.selection.reset();
 		this.render();
+		this.ui = undefined;
+		this.widget = undefined;
+		this.tui = undefined;
 	}
 
 	render(): void {
 		if (!this.ui) return;
-		this.ui.setWidget("herdr-subagents", this.activeBatch ? ((tui) => {
-			this.tui = tui as { focusedComponent?: unknown };
-			const lines = fleetLines(this.activeBatch as HerdrSubagentsBatchDetails, this.selection);
-			if (this.createWidget) return this.createWidget(lines);
-			const container = new Container();
-			for (const line of lines) container.addChild(new Text(line, 1, 0));
-			return container;
-		}) : undefined, { placement: "belowEditor" });
+		if (!this.activeBatch) {
+			this.widget = undefined;
+			this.ui.setWidget("herdr-subagents", undefined, { placement: "belowEditor" });
+			return;
+		}
+		if (this.createWidget) {
+			this.ui.setWidget("herdr-subagents", (tui) => {
+				this.tui = tui;
+				return this.createWidget?.(fleetLines(this.activeBatch as HerdrSubagentsBatchDetails, this.selection)) ?? new Container();
+			}, { placement: "belowEditor" });
+			return;
+		}
+		if (this.widget) { this.widget.update(this.activeBatch); return; }
+		this.ui.setWidget("herdr-subagents", (tui, theme) => {
+			this.tui = tui;
+			this.widget = new FleetWidget(tui, theme, this.activeBatch as HerdrSubagentsBatchDetails, this.selection, this.widgetRuntime);
+			return this.widget;
+		}, { placement: "belowEditor" });
 	}
 
 	private handleInput(data: string): { consume: true } | undefined {

package/packages/herdr-subagents/src/fleet.ts

@@ -1,4 +1,8 @@
+import { readFile } from "node:fs/promises";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { BatchResult } from "./batch-runner.ts";
+import type { TaskActivity } from "./records.ts";
 
 type FleetKey = "up" | "down" | "enter" | "escape";
 type KeyMatcher = (data: string, key: FleetKey) => boolean;
@@ -7,6 +11,8 @@ const legacyKeys: Record<FleetKey, string> = { up: "\u001b[A", down: "\u001b[B",
 const legacyMatchesKey: KeyMatcher = (data, key) => data === legacyKeys[key];
 
 export interface FleetInputResult { consume?: boolean; focusTask?: number; changed?: boolean; }
+export interface FleetTaskMetrics { tokens?: number; }
+export type FleetMetrics = ReadonlyMap<number, FleetTaskMetrics>;
 
 export function fleetEditorHasFocus(focused: unknown, isEditor: (value: unknown) => boolean): boolean {
 	return isEditor(focused);
@@ -25,6 +31,7 @@ export class FleetSelection {
 
 	handle(data: string, editorText: string, taskCount: number): FleetInputResult {
 		if (taskCount === 0) { this.reset(); return {}; }
+		this.selected = this.selectedIndex(taskCount);
 		if (!this.selecting) {
 			if (!this.matchesKey(data, "down") || editorText.length !== 0) return {};
 			this.selecting = true;
@@ -36,21 +43,125 @@ export class FleetSelection {
 			this.selected = (this.selected + delta + taskCount) % taskCount;
 			return { consume: true, changed: true };
 		}
-		if (this.matchesKey(data, "enter")) return { consume: true, focusTask: this.selected + 1 };
+		if (this.matchesKey(data, "enter")) return { consume: true, focusTask: this.selectedIndex(taskCount) + 1 };
 		if (this.matchesKey(data, "escape")) { this.selecting = false; return { consume: true, changed: true }; }
 		this.selecting = false;
 		return { changed: true };
 	}
 }
 
-export function fleetLines(batch: Pick<BatchResult, "label" | "activity">, selection: FleetSelection): string[] {
+function finiteTokenPart(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+function usageTokens(value: unknown): number {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return 0;
+	const usage = value as Record<string, unknown>;
+	return finiteTokenPart(usage.input) + finiteTokenPart(usage.output) + finiteTokenPart(usage.cacheRead) + finiteTokenPart(usage.cacheWrite);
+}
+
+/** Match Pi's cumulative footer semantics without trusting an incomplete JSONL tail. */
+export function aggregateSessionTokens(jsonl: string): number {
+	let total = 0;
+	for (const line of jsonl.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		let entry: Record<string, unknown>;
+		try {
+			const parsed: unknown = JSON.parse(line);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+			entry = parsed as Record<string, unknown>;
+		} catch { continue; }
+		if (entry.type === "usage") total += usageTokens(entry.usage);
+		else if (entry.type === "compaction" || entry.type === "branch_summary") total += usageTokens(entry.usage);
+		else if (entry.type === "message") {
+			const message = entry.message;
+			if (!message || typeof message !== "object" || Array.isArray(message)) continue;
+			const record = message as Record<string, unknown>;
+			if (record.role === "assistant" || record.role === "toolResult") total += usageTokens(record.usage);
+		}
+	}
+	return total;
+}
+
+export async function readSessionTokens(path: string): Promise<number | undefined> {
+	try { return aggregateSessionTokens(await readFile(path, "utf8")); }
+	catch { return undefined; }
+}
+
+export function formatFleetDuration(task: TaskActivity, now = Date.now()): string | undefined {
+	if (!task.startedAt || task.status === "queued" || task.status === "starting") return undefined;
+	let elapsed = typeof task.elapsedMs === "number" && Number.isFinite(task.elapsedMs) ? Math.max(0, task.elapsedMs) : undefined;
+	if (task.status === "running" && task.activeStartedAt) {
+		const activeStarted = Date.parse(task.activeStartedAt);
+		if (Number.isFinite(activeStarted) && now >= activeStarted) elapsed = (elapsed ?? 0) + (now - activeStarted);
+	}
+	if (elapsed === undefined) {
+		const started = Date.parse(task.startedAt);
+		const terminal = task.completedAt ?? (task.status === "blocked" ? task.updatedAt : undefined);
+		const ended = terminal ? Date.parse(terminal) : now;
+		if (!Number.isFinite(started) || !Number.isFinite(ended) || ended < started) return undefined;
+		elapsed = ended - started;
+	}
+	const seconds = Math.floor(elapsed / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+	return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+
+export function formatFleetTokens(tokens: number): string {
+	if (tokens < 1_000) return `${tokens} tok`;
+	if (tokens < 10_000) return `${(tokens / 1_000).toFixed(1)}k tok`;
+	if (tokens < 1_000_000) return `${Math.round(tokens / 1_000)}k tok`;
+	return `${(tokens / 1_000_000).toFixed(1)}m tok`;
+}
+
+function statusSummary(activity: TaskActivity[]): string {
 	const counts = new Map<string, number>();
-	for (const task of batch.activity) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
-	const summary = ["running", "queued", "blocked", "failed", "completed", "cancelled"]
+	for (const task of activity) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+	return ["running", "queued", "blocked", "failed", "completed", "cancelled"]
 		.filter((status) => counts.has(status)).map((status) => `${status} ${counts.get(status)}`).join(" · ");
+}
+
+function fitColumns(left: string, right: string, width: number): string {
+	if (width <= 0) return "";
+	if (!right) return truncateToWidth(left, width);
+	const rightWidth = visibleWidth(right);
+	if (rightWidth + 2 >= width) return truncateToWidth(left, width);
+	const fittedLeft = truncateToWidth(left, width - rightWidth - 1);
+	const gap = " ".repeat(Math.max(1, width - visibleWidth(fittedLeft) - rightWidth));
+	return truncateToWidth(fittedLeft + gap + right, width);
+}
+
+type FleetTheme = Pick<Theme, "fg" | "bold">;
+const plainTheme: FleetTheme = { fg: (_color, text) => text, bold: (text) => text } as FleetTheme;
+
+export function fleetLines(
+	batch: Pick<BatchResult, "label" | "activity">,
+	selection: FleetSelection,
+	options: { width?: number; now?: number; metrics?: FleetMetrics; theme?: FleetTheme } = {},
+): string[] {
+	const width = Math.max(1, options.width ?? 120);
+	const theme = options.theme ?? plainTheme;
 	const selected = selection.selectedIndex(batch.activity.length);
-	return [
-		`Subagents · ${batch.label} · ${summary}`,
-		...batch.activity.map((task, index) => `${selection.isSelecting() && index === selected ? "›" : " "} ${String(task.index + 1).padStart(2, "0")} · ${task.name}  ${task.status}`),
-	];
+	const title = `─ ${theme.bold("Fleet")} · ${batch.label} · ${statusSummary(batch.activity)} `;
+	const titleWidth = visibleWidth(title);
+	const lines = [truncateToWidth(title + "─".repeat(Math.max(0, width - titleWidth)), width)];
+	const rows = batch.activity.map((task, index) => {
+		const chosen = selection.isSelecting() && index === selected;
+		const circle = task.status === "queued" || task.status === "starting" ? "○" : "●";
+		const color = task.status === "completed" ? "success" : task.status === "running" ? "warning" : task.status === "failed" ? "error" : task.status === "blocked" ? "warning" : task.status === "cancelled" ? "dim" : "accent";
+		const marker = chosen ? theme.fg("accent", "›") : " ";
+		const persona = theme.fg("muted", task.agent || "worker");
+		const left = `${marker} ${theme.fg(color, circle)} ${persona}  ${task.name}  ${theme.fg("dim", task.status)}`;
+		const duration = formatFleetDuration(task, options.now);
+		const tokens = task.status === "queued" || task.status === "starting" ? undefined : options.metrics?.get(task.index)?.tokens;
+		const right = [duration, tokens === undefined ? undefined : formatFleetTokens(tokens)].filter(Boolean).join("  ");
+		return { left, right: theme.fg("dim", right) };
+	});
+	const maxLeft = Math.max(0, ...rows.map(({ left }) => visibleWidth(left)));
+	const maxRight = Math.max(0, ...rows.map(({ right }) => visibleWidth(right)));
+	const contentWidth = Math.min(width, maxLeft + (maxRight ? 2 + maxRight : 0));
+	for (const row of rows) lines.push(fitColumns(row.left, row.right, contentWidth));
+	return lines;
 }