pi-chassis 0.0.0-stage → 0.7.1

package/extensions/widgets/mcp/status.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure logic for the MCP footer status (no pi imports, so the tests run standalone).
+ *
+ * pi's built-in MCP support has no public connection-state API, so the state is inferred:
+ *   - configured: enabled servers from ~/.pi/agent/mcp.json, the trusted project's
+ *     .pi/mcp.json (project entries replace global ones of the same name), plus servers
+ *     extensions registered with pi.registerMcpServer() (mcp.json wins on name clashes).
+ *   - connected: the server has at least one registered tool in namespace mcp__<server>
+ *     whose exposure is not "hidden". Tools register when a server connects; a disabled
+ *     server's tools are re-registered as hidden.
+ * Limits: a dropped connection keeps its tools registered until the next call reconnects it,
+ * and a server that offers zero tools never counts as connected.
+ */
+
+/** Only `enabled` is read; other mcp.json fields (url, command, ...) pass through untyped. */
+export interface ServerConfig {
+	enabled?: boolean;
+	url?: string;
+	command?: string;
+}
+
+export interface ToolLike {
+	exposure: string;
+	namespace?: { name: string };
+}
+
+/** Same rule as pi's mcpNamespace(): "-" and "_" are equivalent in server names. */
+export function mcpNamespace(server: string): string {
+	return `mcp__${server.replace(/-/g, "_")}`;
+}
+
+/** The mcpServers object of an mcp.json text, or {} when missing or invalid. */
+export function parseMcpServers(text: string | undefined): Record<string, ServerConfig> {
+	if (!text) return {};
+	try {
+		const servers = JSON.parse(text)?.mcpServers;
+		if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return {};
+		const out: Record<string, ServerConfig> = {};
+		for (const [name, cfg] of Object.entries(servers)) {
+			if (typeof cfg === "object" && cfg !== null && !Array.isArray(cfg)) out[name] = cfg as ServerConfig;
+		}
+		return out;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Names of enabled servers, in precedence order: global < project (replaces by namespace),
+ * then registered servers whose namespace no config file defines.
+ */
+export function enabledServers(
+	global: Record<string, ServerConfig>,
+	project: Record<string, ServerConfig>,
+	registered: Array<{ name: string; config: ServerConfig }>,
+): string[] {
+	const byNs = new Map<string, { name: string; config: ServerConfig }>();
+	for (const [name, config] of Object.entries(global)) byNs.set(mcpNamespace(name), { name, config });
+	for (const [name, config] of Object.entries(project)) byNs.set(mcpNamespace(name), { name, config });
+	for (const r of registered) {
+		const ns = mcpNamespace(r.name);
+		if (!byNs.has(ns)) byNs.set(ns, r);
+	}
+	return [...byNs.values()].filter((s) => s.config.enabled !== false).map((s) => s.name);
+}
+
+/** Servers among `servers` that have at least one non-hidden registered tool. */
+export function connectedServers(servers: string[], tools: ToolLike[]): string[] {
+	const live = new Set(tools.filter((t) => t.exposure !== "hidden" && t.namespace).map((t) => t.namespace!.name));
+	return servers.filter((s) => live.has(mcpNamespace(s)));
+}
+
+export type StatusLevel = "ok" | "partial" | "down";
+
+export interface McpStatus {
+	connected: number;
+	enabled: number;
+	level: StatusLevel;
+	/** Enabled servers that are not connected yet. */
+	pending: string[];
+}
+
+/** Undefined when no server is enabled (the footer segment is hidden). */
+export function summarize(enabled: string[], connected: string[]): McpStatus | undefined {
+	if (enabled.length === 0) return undefined;
+	const live = new Set(connected);
+	const pending = enabled.filter((s) => !live.has(s));
+	const level: StatusLevel = pending.length === 0 ? "ok" : connected.length === 0 ? "down" : "partial";
+	return { connected: connected.length, enabled: enabled.length, level, pending };
+}
+
+export function formatStatus(s: McpStatus): string {
+	return `${s.connected}/${s.enabled}`;
+}

package/extensions/widgets/session-todos/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Session todos widget: the latest todo list that a todo-style tool (pi's todo example, todowrite,
+ * ...) reported in this session, as its own sidebar section. Hidden when there is no list or
+ * everything is done. Separate from the TODO widget, which reads a TODO file in the repo.
+ *
+ *     Todo
+ *     [✓] Read the API
+ *     [•] Write the tests
+ *     [ ] Update the README
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerWidget } from "../../chassis/api.ts";
+import { ICONS } from "../../chassis/icons.ts";
+import { primary } from "../../chassis/palette.ts";
+import { branchKey, latestTodos, type TodoItem } from "../../chassis/session-info.ts";
+
+const SHOWN = 12;
+
+/** Open todos only count as visible; a stale ctx after a session switch reads as "none". */
+function todosOf(ctx: Parameters<typeof latestTodos>[0] | undefined): TodoItem[] {
+	if (!ctx) return [];
+	try {
+		return latestTodos(ctx);
+	} catch {
+		return [];
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	registerWidget(pi, {
+		id: "session-todos",
+		title: "Todo",
+		icon: { nerd: ICONS.widgetSessionTodos.nerd, plain: ICONS.widgetSessionTodos.plain },
+		slots: ["sidebar"],
+		sidebar: "section",
+		order: 50,
+		// latestTodos scans the branch; redo it only when the branch changes.
+		cacheKey: ({ ctx }) => {
+			try {
+				return ctx ? branchKey(ctx) : "";
+			} catch {
+				return ""; // stale ctx after a session switch
+			}
+		},
+		render: ({ ctx }) => (todosOf(ctx).some((t) => !t.done) ? {} : undefined),
+		detail: ({ theme, ctx }) =>
+			todosOf(ctx)
+				.slice(0, SHOWN)
+				.map((t) => {
+					const box = t.done ? theme.fg("success", "[✓]") : t.active ? primary(theme, "[•]") : theme.fg("muted", "[ ]");
+					return `${box} ${t.done ? theme.fg("muted", t.text) : theme.fg("text", t.text)}`;
+				}),
+	});
+}

package/extensions/widgets/subagents/index.ts

@@ -0,0 +1,170 @@
+/**
+ * Subagents widget: a sidebar section with this session's pi-subagents children.
+ *
+ *   Subagents  2 running · 1 done
+ *   ● build-api           bash  1m02s
+ *   ● scout fg                    18s
+ *   ✓ reviewer                  2m10s
+ *   ↓ on an empty prompt to inspect
+ *
+ * Data comes from pi-subagents' public in-process RPC (`status`, see its docs/extension-api.md),
+ * never from its files on disk, so this keeps working as pi-subagents changes internally.
+ * Inspecting, steering and stopping are FleetView's job (pi-subagents' own UI under the
+ * editor); the hint line points there. Hidden when pi-subagents isn't installed or nothing ran.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { registerWidget } from "../../chassis/api.ts";
+import { ICONS } from "../../chassis/icons.ts";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { asyncActiveFrom, elapsed, fmtCount, GLYPH, type Limits, limitsLine, orderRows, parallelFrom, type Row, rowsFromStatus, shortModel, spawnedFrom, summary } from "./status.ts";
+
+const REQUEST = "subagents:rpc:v1:request";
+const REPLY = "subagents:rpc:v1:reply:";
+const READY = "subagents:rpc:v1:ready";
+const POLL_MS = 2_000;
+const TIMEOUT_MS = 5_000;
+const SHOWN = 8;
+/** Running children that also get a model and token line, so the section stays short. */
+const SHOWN_DETAIL = 5;
+/** The spawn budget needs the heavier executor-backed status call: at most this often. */
+const BUDGET_MIN_MS = 5_000;
+/** Even lifecycle events (which can come in bursts) wait this long between budget calls. */
+const BUDGET_FLOOR_MS = 1_000;
+
+function readConfigText(): string | undefined {
+	try {
+		return readFileSync(join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "extensions", "subagent", "config.json"), "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** One `status` request; resolves to the reply's data, or undefined without pi-subagents. */
+function requestStatus(pi: ExtensionAPI, params: Record<string, unknown> = {}): Promise<unknown> {
+	return new Promise((resolve) => {
+		const requestId = randomUUID();
+		let off: (() => void) | undefined;
+		const timer = setTimeout(() => {
+			off?.();
+			resolve(undefined);
+		}, TIMEOUT_MS);
+		timer.unref?.();
+		off = pi.events.on(`${REPLY}${requestId}`, (raw) => {
+			clearTimeout(timer);
+			off?.();
+			const r = raw as { success?: boolean; data?: unknown } | undefined;
+			resolve(r?.success ? r.data : undefined);
+		});
+		pi.events.emit(REQUEST, { version: 1, requestId, method: "status", params, source: { extension: "pi-chassis" } });
+	});
+}
+
+export default function (pi: ExtensionAPI) {
+	let rows: Row[] = [];
+	let inFlight = false;
+	let limits: Limits = {};
+	let budgetBusy = false;
+	let budgetAt = 0;
+
+	/** Spawn count and cap. Rarely needed, and costlier than the poll, so throttled. */
+	const refreshBudget = async (force = false): Promise<void> => {
+		if (budgetBusy || Date.now() - budgetAt < (force ? BUDGET_FLOOR_MS : BUDGET_MIN_MS)) return;
+		budgetBusy = true;
+		budgetAt = Date.now();
+		try {
+			const data = await requestStatus(pi, { view: "fleet" });
+			if (data !== undefined) limits = { ...limits, spawned: spawnedFrom(data) ?? limits.spawned };
+		} finally {
+			budgetBusy = false;
+		}
+	};
+
+	const update = async (_ctx?: ExtensionContext) => {
+		if (inFlight) return;
+		inFlight = true;
+		try {
+			const data = await requestStatus(pi);
+			if (data !== undefined) {
+				rows = orderRows(rowsFromStatus(data));
+				limits = { ...limits, asyncActive: asyncActiveFrom(data), parallel: parallelFrom(readConfigText()) };
+				// A new child changes the spawn count, so look again while something is active.
+				if (rows.some((r) => r.state === "running" || r.state === "queued")) void refreshBudget();
+			}
+		} finally {
+			inFlight = false;
+		}
+	};
+
+	const handle = registerWidget(pi, {
+		id: "subagents",
+		title: "Subagents",
+		icon: { nerd: ICONS.widgetSubagents.nerd, plain: ICONS.widgetSubagents.plain },
+		// pi-subagents' slash commands publish short-lived statuses ("0 tools | ctrl+o live detail")
+		// that this section already covers with per-child rows, so they're not listed a second time.
+		statusKeys: ["subagent-slash", "subagent-slash-text"],
+		slots: ["sidebar", "footer"],
+		sidebar: "section",
+		order: 35,
+		refreshMs: POLL_MS,
+		update,
+		render: () => {
+			if (!rows.length) return undefined;
+			const s = summary(rows);
+			return { label: "subagents", text: s.text, level: s.running ? "ok" : s.failed ? "warn" : "off", color: s.running ? "text" : undefined };
+		},
+		detail: ({ theme, width }) => {
+			if (!rows.length) return undefined;
+			const tone = (r: Row, x: string) =>
+				theme.fg(r.state === "running" ? "accent" : r.state === "done" ? "success" : r.state === "failed" ? "error" : r.state === "paused" ? "warning" : "dim", x);
+			const lines = rows.slice(0, SHOWN).map((r) => {
+				const active = r.state === "running" || r.state === "queued" || r.state === "paused";
+				const left = `${tone(r, GLYPH[r.state])} ${theme.fg(active ? "text" : "muted", r.label)}${r.foreground ? theme.fg("dim", " fg") : ""}`;
+				const right = theme.fg("dim", [r.currentTool, elapsed(r)].filter(Boolean).join("  "));
+				const gap = width - visibleWidth(left) - visibleWidth(right);
+				return gap >= 1 ? `${left}${" ".repeat(gap)}${right}` : truncateToWidth(left, width, "…");
+			});
+			// Model and tokens under running children: "  opus-5-5 · 16k tokens".
+			const withFacts: string[] = [];
+			let factRows = 0;
+			rows.slice(0, SHOWN).forEach((r, i) => {
+				withFacts.push(lines[i]!);
+				const facts = [r.model ? shortModel(r.model) : "", r.tokens ? `${fmtCount(r.tokens)} tokens` : ""].filter(Boolean).join(" · ");
+				if (facts && r.state === "running" && factRows < SHOWN_DETAIL) {
+					factRows++;
+					withFacts.push(truncateToWidth(`  ${theme.fg("dim", facts)}`, width, "…"));
+				}
+			});
+			lines.length = 0;
+			lines.push(...withFacts);
+			if (rows.length > SHOWN) lines.push(theme.fg("dim", `+${rows.length - SHOWN} more`));
+			const limit = limitsLine(limits);
+			if (limit) lines.push(theme.fg("dim", limit));
+			if (summary(rows).running) lines.push(theme.fg("dim", "↓ on an empty prompt to inspect"));
+			return lines;
+		},
+	});
+
+	// Refresh promptly on pi-subagents' lifecycle events, on top of the poll.
+	for (const ev of [READY, "subagent:async-started", "subagent:async-complete", "subagent:child-status"]) {
+		pi.events.on(ev, () => {
+			setTimeout(() => handle.refresh(), 150);
+			void refreshBudget(true);
+		});
+	}
+	pi.on("tool_execution_start", async (e) => {
+		if (e.toolName === "subagent") setTimeout(() => handle.refresh(), 300);
+	});
+	pi.on("tool_execution_end", async (e) => {
+		if (e.toolName === "subagent") setTimeout(() => handle.refresh(), 300);
+	});
+	pi.on("session_start", async () => {
+		rows = [];
+		limits = {};
+		budgetAt = 0;
+	});
+}

package/extensions/widgets/subagents/status.ts

@@ -0,0 +1,237 @@
+/**
+ * Projection of pi-subagents' public `status` RPC reply into sidebar rows.
+ *
+ * Reads only the documented, versioned shapes from pi-subagents' docs/extension-api.md:
+ * `data.asyncSnapshot` (kind "pi-subagents.async-status-snapshot", version 1) for background
+ * runs, and `data.fleet` (version 1) for active foreground children, which the snapshot doesn't
+ * cover. Unknown fields are ignored, as that doc asks. No pi imports, so tests stay light.
+ */
+
+export type RowState = "running" | "queued" | "done" | "failed" | "paused" | "stopped";
+
+export interface Row {
+	label: string;
+	state: RowState;
+	currentTool?: string;
+	startedAt?: number;
+	endedAt?: number;
+	/** A foreground child (from the fleet DTO). */
+	foreground?: boolean;
+	/** Model as the fleet DTO reports it, e.g. "anthropic/claude-opus-5-5". Active children only. */
+	model?: string;
+	/** Tokens so far (input + output). Active children only. */
+	tokens?: number;
+}
+
+/** What the sidebar shows about the limits, from the status reply and the config file. */
+export interface Limits {
+	/** Children launched this session, and the cap (null: no cap). */
+	spawned?: { used: number; limit: number | null };
+	/** Background runs active in this session, and the cap (only when a cap is configured). */
+	asyncActive?: { used: number; limit: number };
+	/** `globalConcurrencyLimit`: children running at once inside one run. */
+	parallel?: number;
+}
+
+interface SnapshotNode {
+	kind?: string;
+	label?: string;
+	state?: string;
+	startedAt?: number;
+	endedAt?: number;
+	activity?: { currentTool?: string };
+	children?: SnapshotNode[];
+}
+
+const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+const str = (v: unknown) => (typeof v === "string" && v.trim() ? v : undefined);
+
+function rowState(s: unknown): RowState {
+	switch (s) {
+		case "running":
+			return "running";
+		case "queued":
+			return "queued";
+		case "complete":
+			return "done";
+		case "paused":
+			return "paused";
+		case "stopped":
+			return "stopped";
+		default:
+			return "failed"; // failed, partial, rejected
+	}
+}
+
+/** A node's leaves: the children you'd open in FleetView. Workflow parents aren't rows. */
+function leaves(node: SnapshotNode, out: Row[]): void {
+	const kids = Array.isArray(node.children) ? node.children : [];
+	if (kids.length) {
+		for (const k of kids) if (k && typeof k === "object") leaves(k, out);
+		return;
+	}
+	const state = rowState(node.state);
+	out.push({
+		label: str(node.label) ?? "subagent",
+		state,
+		currentTool: state === "running" ? str(node.activity?.currentTool) : undefined,
+		startedAt: num(node.startedAt),
+		endedAt: state === "running" || state === "queued" ? undefined : num(node.endedAt),
+	});
+}
+
+/** Rows from a `status` reply's `data`: background leaves, then active foreground children. */
+export function rowsFromStatus(data: unknown): Row[] {
+	if (!data || typeof data !== "object") return [];
+	const d = data as { asyncSnapshot?: { kind?: string; version?: number; runs?: unknown }; fleet?: { version?: number; entries?: unknown } };
+	const rows: Row[] = [];
+	const snap = d.asyncSnapshot;
+	if (snap?.kind === "pi-subagents.async-status-snapshot" && snap.version === 1 && Array.isArray(snap.runs)) {
+		for (const run of snap.runs) if (run && typeof run === "object") leaves(run as SnapshotNode, rows);
+	}
+	// The fleet DTO lists every active child, background and foreground (plus a "workflow" entry
+	// per active workflow parent), but exposes no ids. Background children are already rows from
+	// the snapshot, so the entries beyond that count are foreground ones: take the newest.
+	const fleet = d.fleet;
+	if (fleet?.version === 1 && Array.isArray(fleet.entries)) {
+		const entries = (fleet.entries as FleetEntry[]).filter(
+			(e) => e && typeof e === "object" && e.agent !== "workflow",
+		);
+		const background = rows.filter((r) => r.state === "running" || r.state === "queued" || r.state === "paused").length;
+		const extra = entries.length - background;
+		if (extra > 0) {
+			const newest = [...entries].sort((a, b) => (num(b.startedAt) ?? 0) - (num(a.startedAt) ?? 0)).slice(0, extra);
+			for (const e of newest) {
+				rows.push({ label: str(e.role) ?? str(e.agent) ?? "subagent", state: "running", startedAt: num(e.startedAt), foreground: true, ...liveFacts(e) });
+			}
+		}
+		attachLiveFacts(rows, entries);
+	}
+	return rows;
+}
+
+interface FleetEntry {
+	agent?: unknown;
+	role?: unknown;
+	model?: unknown;
+	startedAt?: unknown;
+	tokens?: { total?: unknown; input?: unknown; output?: unknown };
+}
+
+function liveFacts(e: FleetEntry): { model?: string; tokens?: number } {
+	const t = e.tokens;
+	const total = num(t?.total) ?? (num(t?.input) !== undefined || num(t?.output) !== undefined ? (num(t?.input) ?? 0) + (num(t?.output) ?? 0) : undefined);
+	return { ...(str(e.model) ? { model: str(e.model) } : {}), ...(total ? { tokens: total } : {}) };
+}
+
+/** Fleet start times differ from the snapshot's by a few milliseconds; this is the match window. */
+const MATCH_MS = 1_000;
+
+/**
+ * Background rows come from the async snapshot, which has no model or tokens, and the fleet DTO
+ * has no ids. Pair each active background row with the fleet entry that started nearest to it
+ * (within MATCH_MS, each entry used once) to borrow the model and token count.
+ */
+function attachLiveFacts(rows: Row[], entries: FleetEntry[]): void {
+	const free = entries.filter((e) => num(e.startedAt) !== undefined && (str(e.model) || e.tokens));
+	const active = rows.filter((r) => !r.foreground && r.startedAt !== undefined && (r.state === "running" || r.state === "queued" || r.state === "paused"));
+	const pairs: Array<{ row: Row; entry: FleetEntry; gap: number }> = [];
+	for (const row of active) for (const entry of free) pairs.push({ row, entry, gap: Math.abs(row.startedAt! - num(entry.startedAt)!) });
+	pairs.sort((a, b) => a.gap - b.gap);
+	const usedRows = new Set<Row>();
+	const usedEntries = new Set<FleetEntry>();
+	for (const { row, entry, gap } of pairs) {
+		if (gap > MATCH_MS) break;
+		if (usedRows.has(row) || usedEntries.has(entry)) continue;
+		usedRows.add(row);
+		usedEntries.add(entry);
+		Object.assign(row, liveFacts(entry));
+	}
+}
+
+/** "anthropic/claude-opus-5-5" becomes "opus-5-5". */
+export function shortModel(model: string): string {
+	return model.split("/").pop()!.replace(/^claude-/, "");
+}
+
+/** 16147 becomes "16k", 1_200_000 becomes "1.2M". */
+export function fmtCount(n: number): string {
+	if (n < 1_000) return String(n);
+	if (n < 1_000_000) return `${Math.round(n / 1_000)}k`;
+	return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+}
+
+/** Spawn budget from a `status` reply made with `view: "fleet"` (`data.details.spawnBudget`). */
+export function spawnedFrom(data: unknown): Limits["spawned"] {
+	const b = (data as { details?: { spawnBudget?: { used?: unknown; limit?: unknown } } } | undefined)?.details?.spawnBudget;
+	const used = num(b?.used);
+	if (used === undefined) return undefined;
+	return { used, limit: num(b?.limit) ?? null };
+}
+
+/** Active async runs and their cap from the fleet DTO; undefined when no cap is configured. */
+export function asyncActiveFrom(data: unknown): Limits["asyncActive"] {
+	const c = (data as { fleet?: { topLevelAsyncCapacity?: { used?: unknown; limit?: unknown } } } | undefined)?.fleet?.topLevelAsyncCapacity;
+	const used = num(c?.used);
+	const limit = num(c?.limit);
+	return used !== undefined && limit !== undefined && limit > 0 ? { used, limit } : undefined;
+}
+
+/** `globalConcurrencyLimit` from pi-subagents' config.json text (default 20 when absent). */
+export function parallelFrom(configText: string | undefined): number {
+	try {
+		const n = num(JSON.parse(configText ?? "{}")?.globalConcurrencyLimit);
+		return n !== undefined && n > 0 ? Math.floor(n) : 20;
+	} catch {
+		return 20;
+	}
+}
+
+/** The limits line under the rows, or undefined when there is nothing to say. */
+export function limitsLine(l: Limits): string | undefined {
+	const parts: string[] = [];
+	if (l.spawned) parts.push(l.spawned.limit === null ? `${l.spawned.used} spawned` : `${l.spawned.used}/${l.spawned.limit} spawned`);
+	if (l.asyncActive) parts.push(`${l.asyncActive.used}/${l.asyncActive.limit} async`);
+	else if (l.parallel) parts.push(`max ${l.parallel} parallel`);
+	return parts.length ? parts.join(" · ") : undefined;
+}
+
+const ORDER: Record<RowState, number> = { running: 0, paused: 1, queued: 2, failed: 3, stopped: 3, done: 3 };
+
+/** Active first (oldest first), then finished (newest first). */
+export function orderRows(rows: Row[]): Row[] {
+	return [...rows].sort((a, b) => {
+		const o = ORDER[a.state] - ORDER[b.state];
+		if (o) return o;
+		if (ORDER[a.state] < 3) return (a.startedAt ?? 0) - (b.startedAt ?? 0);
+		return (b.endedAt ?? b.startedAt ?? 0) - (a.endedAt ?? a.startedAt ?? 0);
+	});
+}
+
+export function summary(rows: Row[]): { text: string; running: number; failed: number } {
+	let running = 0;
+	let queued = 0;
+	let done = 0;
+	let failed = 0;
+	for (const r of rows) {
+		if (r.state === "running" || r.state === "paused") running++;
+		else if (r.state === "queued") queued++;
+		else if (r.state === "done") done++;
+		else failed++;
+	}
+	const text = [running ? `${running} running` : "", queued ? `${queued} queued` : "", done ? `${done} done` : "", failed ? `${failed} failed` : ""].filter(Boolean).join(" · ");
+	return { text, running, failed };
+}
+
+export function elapsed(r: Row, now = Date.now()): string {
+	if (!r.startedAt) return "";
+	const end = r.endedAt ?? (r.state === "running" || r.state === "paused" ? now : undefined);
+	if (end === undefined) return "";
+	const s = Math.max(0, Math.round((end - r.startedAt) / 1000));
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	return m < 60 ? `${m}m${String(s % 60).padStart(2, "0")}s` : `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+}
+
+/** Plain glyphs that exist in common monospace fonts. */
+export const GLYPH: Record<RowState, string> = { running: "●", queued: "○", paused: "‖", done: "✓", failed: "×", stopped: "■" };

package/extensions/widgets/todo/index.ts

@@ -0,0 +1,66 @@
+/**
+ * TODO widget: when the current repo has a TODO file at its root (TODO.md, TODO, TODO.txt, ...),
+ * shows it as its own sidebar section: the open item count beside the title and the first few
+ * items underneath. Hidden when there's no file or nothing is open. Re-reads the file when it
+ * changes. The file belongs to the project, so it is read only when the project is trusted.
+ *
+ *     TODO  3 open
+ *     • Test the provider section…
+ *     • Add a cost breakdown
+ *     +1 more
+ */
+
+import { statSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerWidget } from "../../chassis/api.ts";
+import { ICONS } from "../../chassis/icons.ts";
+import { sanitize } from "../../chassis/palette.ts";
+import { findTodoFile, readTodos } from "./parse.ts";
+
+const POLL_MS = 5_000;
+const SHOWN = 5;
+
+export default function (pi: ExtensionAPI) {
+	let items: string[] = [];
+	let key = ""; // path + mtime, so unchanged files aren't re-parsed
+
+	registerWidget(pi, {
+		id: "todo",
+		title: "TODO",
+		icon: { nerd: ICONS.widgetTodo.nerd, plain: ICONS.widgetTodo.plain },
+		slots: ["sidebar"],
+		sidebar: "section",
+		order: 40,
+		refreshMs: POLL_MS,
+		update: (ctx) => {
+			if (!ctx.isProjectTrusted()) {
+				items = [];
+				key = "";
+				return;
+			}
+			const path = findTodoFile(ctx.cwd);
+			if (!path) {
+				items = [];
+				key = "";
+				return;
+			}
+			let mtime = 0;
+			try {
+				mtime = statSync(path).mtimeMs;
+			} catch {
+				// vanished between calls
+			}
+			const next = `${path}:${mtime}`;
+			if (next === key) return;
+			key = next;
+			items = readTodos(ctx.cwd)?.items ?? [];
+		},
+		render: () => (items.length ? { text: `${items.length} open` } : undefined),
+		detail: ({ theme }) => {
+			if (!items.length) return undefined;
+			const lines = items.slice(0, SHOWN).map((t) => `${theme.fg("muted", "•")} ${theme.fg("text", sanitize(t))}`);
+			if (items.length > SHOWN) lines.push(theme.fg("dim", `+${items.length - SHOWN} more`));
+			return lines;
+		},
+	});
+}