@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/extensions/session-bus/runtime.ts

@@ -22,7 +22,7 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { claimPathMessage, resolveClaimPaths } from "./resolve.ts";
 import { realPathOfNearest } from "../../lib/path.ts";
 import { repoKeyFor } from "../../lib/repo-key.ts";
-import { sessionNameOf } from "../../lib/session-label.ts";
+import { sessionNameOf, SESSION_LABEL_CHANNEL } from "../../lib/session-label.ts";
 import { defaultInterval, type RepeatTimer } from "../../lib/timer.ts";
 import {
 	defaultLabel,
@@ -39,7 +39,7 @@ import {
 } from "./protocol.ts";
 import { createMailWatch, type WatchingState } from "./mail-watch.ts";
 import { createBusStore, releaseClaimed, type BusStore } from "./store.ts";
-import type { BusMessage, ClaimConflict, SessionRecord, SessionStatus } from "./types.ts";
+import type { BusMessage, ClaimConflict, InboxPeek, SessionRecord, SessionStatus } from "./types.ts";
 import {
 	BUS_DIR_NAME,
 	type RosterSeams,
@@ -131,9 +131,6 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 	const interval = options.interval ?? defaultInterval;
 	const pid = options.pid ?? process.pid;
 	const seams: RosterSeams = { alive: options.alive ?? isPidAlive, token: options.startTokenFn ?? startTokenOf };
-	// Asked once, here: a reused pid is settled from the record afterwards, so no
-	// heartbeat tick spawns `ps`.
-	const processToken = (seams.token ?? startTokenOf)(pid);
 
 	/**
 	 * What one record says about its session.
@@ -161,7 +158,8 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 
 	/** The watch reads this session's own inbox; nothing is consumed or marked. */
 	const mailWatch = createMailWatch({
-		peek: async () => (store && record ? store.peek(record.id, MAX_LIMIT) : []),
+		peek: async (known): Promise<InboxPeek> =>
+			store && record ? store.peek(record.id, { limit: MAX_LIMIT, known }) : { mail: [], unread: new Set() },
 		interval,
 		watchMs,
 	});
@@ -178,6 +176,10 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 			await store.ensure();
 			const id = context.sessionManager.getSessionId();
 			const mode = sessionMode(context.mode);
+			// Asked once, when the bus starts: a reused pid is settled from the record
+			// afterwards, so no heartbeat tick spawns `ps`, and a session that never
+			// joins pays nothing in its factory.
+			const processToken = (seams.token ?? startTokenOf)(pid);
 			record = {
 				id,
 				label: defaultLabel(sessionNameOf(context), cwd, id),
@@ -208,6 +210,7 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		record.lastSeen = now();
 		await store.writeSession(record);
 		await settleLabel();
+		publishLabel();
 		joined = true;
 		armHeartbeat();
 	}
@@ -225,7 +228,7 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 				await store.writeSession(record);
 				// A heartbeat that resumed after a long pause can find its label taken; the
 				// tick is where a revived session notices and yields, after its own write.
-				await settleLabel();
+				if (await settleLabel()) publishLabel();
 			})().catch(() => {});
 		});
 	}
@@ -248,18 +251,35 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 	 * that keeps the label does not look again, and two of them can each decide that.
 	 * Every writer that observes a rival yields, and the record written last always
 	 * observes the other, so a collision ends with two distinct labels.
+	 *
+	 * Answers whether this call yielded, which is the only thing that can change a label
+	 * after it is settled — the heartbeat tick is where that happens.
 	 */
-	async function settleLabel(): Promise<void> {
-		if (!store || !record) return;
+	async function settleLabel(): Promise<boolean> {
+		if (!store || !record) return false;
 		const me = record;
 		let yields = 0;
 		while (yields < 3 && (await takenLabels(store, me.id)).has(me.label.toLowerCase())) {
 			me.label = suffixLabel(me.label, me.id);
 			yields += 1;
 		}
-		if (yields === 0) return;
+		if (yields === 0) return false;
 		me.lastSeen = now();
 		await store.writeSession(me);
+		return true;
+	}
+
+	/**
+	 * Tell the footer what peers address this session by.
+	 *
+	 * Nothing else can say what a label is: the bus settles it, yields it on a collision, and
+	 * gives it to a caller that asked for a name. The footer draws it in place of Pi's own
+	 * session name, which the terminal knows but a card, a handoff, and `/team` do not.
+	 */
+	function publishLabel(): void {
+		if (!record) return;
+		// A host with no event bus has no listener: the footer it would feed keeps Pi's own name.
+		pi.events?.emit(SESSION_LABEL_CHANNEL, { id: record.id, label: record.label });
 	}
 
 	/**
@@ -376,6 +396,7 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		// A rename that raced another one ends on the label the bus settled on, which
 		// is what the caller hands to Pi as this session's name.
 		await settleLabel();
+		publishLabel();
 		joined = true;
 		armHeartbeat();
 		return record.label;
@@ -458,7 +479,7 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 
 		async peek() {
 			if (!store || !record) throw new Error("session bus is not started.");
-			return store.peek(record.id, MAX_LIMIT);
+			return (await store.peek(record.id, { limit: MAX_LIMIT })).mail;
 		},
 
 		/**
@@ -482,7 +503,14 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 			if ("error" in text) throw new Error(text.error);
 			const kind = normalizeKind(input.kind);
 			if (input.to.trim() === "*" && kind !== "event") throw new Error('a broadcast needs kind: "event".');
-			const sessions = await store.sessions();
+			// Mail reaches a session that can still answer, by the rule `status` and the prune
+			// already use: a record whose process is gone is not a recipient, so naming it is
+			// refused instead of confirmed, and a broadcast skips it. This session is always its
+			// own recipient, which is what a note to itself is.
+			const at = now();
+			const sessions = (await store.sessions()).filter(
+				(session) => session.id === me.id || stateOf(session, at) !== "gone",
+			);
 			const resolved = resolveRecipients(sessions, input.to, me.id);
 			if ("error" in resolved) throw new Error(resolved.error);
 			let paths: string[] | undefined;

package/extensions/session-bus/store.ts

@@ -8,11 +8,11 @@
  */
 
 import { createHash, randomBytes } from "node:crypto";
-import { mkdir, link, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import { mkdir, link, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { asRecord, readJson } from "../../lib/config.ts";
 import { claimsConflict } from "./overlap.ts";
-import type { BusMessage, ClaimConflict, ClaimRecord, SessionRecord } from "./types.ts";
+import type { BusMessage, ClaimConflict, ClaimRecord, InboxPeek, SessionRecord } from "./types.ts";
 import { INBOX_DIR_NAME, SESSIONS_DIR_NAME } from "../../lib/session-roster.ts";
 
 const DIR_MODE = 0o700;
@@ -32,8 +32,11 @@ export interface BusStore {
 	session(id: string): Promise<SessionRecord | undefined>;
 	removeSession(id: string): Promise<void>;
 	writeMessage(target: string, message: BusMessage): Promise<void>;
-	/** Read a recipient's messages without consuming them, oldest first. */
-	peek(id: string, limit: number): Promise<BusMessage[]>;
+	/**
+	 * Read up to `limit` messages from the front of a recipient's inbox without consuming
+	 * them, skipping the ids the caller already has, with every id still unread.
+	 */
+	peek(id: string, options: { limit: number; known?: ReadonlySet<string> }): Promise<InboxPeek>;
 	inbox(id: string, limit: number): Promise<BusMessage[]>;
 	unread(id: string): Promise<number>;
 	claims(): Promise<ClaimRecord[]>;
@@ -42,6 +45,8 @@ export interface BusStore {
 		owner: string,
 		ownerLabel: string,
 		at: number,
+		/** Test seam: runs after each path is published, so a suite can interleave a rival. */
+		afterClaim?: (path: string) => Promise<void>,
 	): Promise<{ claimed: string[]; conflicts: ClaimConflict[] }>;
 	release(path: string, owner: string): Promise<boolean>;
 	releaseAll(owner: string): Promise<string[]>;
@@ -148,14 +153,19 @@ async function writeJson(path: string, value: unknown): Promise<void> {
 	}
 }
 
+const MESSAGE_SUFFIX = ".json";
+
 async function listFiles(dir: string): Promise<string[]> {
 	try {
-		return (await readdir(dir)).filter((name) => name.endsWith(".json")).sort();
+		return (await readdir(dir)).filter((name) => name.endsWith(MESSAGE_SUFFIX)).sort();
 	} catch {
 		return [];
 	}
 }
 
+/** The message id a file name holds, which is the id a reader compares against. */
+const idOfFile = (name: string): string => name.slice(0, -MESSAGE_SUFFIX.length);
+
 /**
  * Drop a recipient's directory once it holds no files, so a bus does not keep
  * one empty directory for every session that ever joined it. An inbox with mail
@@ -168,6 +178,32 @@ async function dropIfEmpty(dir: string): Promise<void> {
 	await rmdir(dir).catch(() => {});
 }
 
+/**
+ * How long a writer's temp file may sit before it is debris.
+ *
+ * A record and a claim are published by renaming or linking a temp file, so the file
+ * exists for milliseconds; one left behind is a process that stopped between the
+ * write and the publish. The window is measured on the filesystem's own clock, not
+ * the bus's, because that is the clock the timestamps came from.
+ */
+const TEMP_TTL_MS = 60_000;
+
+/**
+ * Remove the temp files a crashed writer left in one directory.
+ *
+ * Readers only ever look at `*.json`, so this debris is invisible and would live
+ * forever without a pass of its own.
+ */
+async function dropStaleTemps(dir: string): Promise<void> {
+	const cut = Date.now() - TEMP_TTL_MS;
+	for (const name of await readdir(dir).catch(() => [] as string[])) {
+		if (name.endsWith(".json")) continue;
+		const path = join(dir, name);
+		const info = await stat(path).catch(() => undefined);
+		if (info !== undefined && info.mtimeMs < cut) await rm(path, { force: true });
+	}
+}
+
 /** Create a store rooted at one repository's bus directory. */
 export function createBusStore(options: BusStoreOptions): BusStore {
 	const { dir } = options;
@@ -188,17 +224,39 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 		return sessions.sort((a, b) => b.lastSeen - a.lastSeen || a.label.localeCompare(b.label));
 	}
 
-	async function readMessages(id: string, limit: number, remove: boolean): Promise<BusMessage[]> {
-		const directory = inboxDir(id);
+	/**
+	 * Up to `limit` messages from the front of a recipient's inbox, oldest first.
+	 *
+	 * The front is the queue, not a detail: consuming starts there so a limit never starves,
+	 * and so does a read, because the caller names the ids it already has. A file name holds
+	 * the id, so a skip costs no read — which is what lets a watch page a backlog one poll at
+	 * a time without ever reading the same file twice.
+	 *
+	 * Only the consuming read deletes, and it deletes a file it cannot validate too, so a
+	 * truncated message cannot linger on the bus. A read that promises not to consume leaves
+	 * such a file where it is: it may be mail this build cannot read and the next one can, and
+	 * `inbox` or the prune TTL is what ends it.
+	 */
+	async function readMessages(
+		directory: string,
+		names: readonly string[],
+		options: { limit: number; known?: ReadonlySet<string>; remove: boolean },
+	): Promise<BusMessage[]> {
+		const { limit, known, remove } = options;
 		const messages: BusMessage[] = [];
-		for (const name of await listFiles(directory)) {
+		for (const name of names) {
+			if (known?.has(idOfFile(name))) continue;
 			const path = join(directory, name);
 			const message = readTyped(path, isMessage);
-			if (message) messages.push(message);
-			if (remove || !message) await rm(path, { force: true });
+			if (!message) {
+				if (remove) await rm(path, { force: true });
+				continue;
+			}
+			messages.push(message);
+			if (remove) await rm(path, { force: true });
 			if (messages.length >= limit) break;
 		}
-		return messages.sort((a, b) => a.at - b.at || a.id.localeCompare(b.id)).slice(0, limit);
+		return messages.sort((a, b) => a.at - b.at || a.id.localeCompare(b.id));
 	}
 
 	async function readClaims(): Promise<ClaimRecord[]> {
@@ -215,7 +273,7 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 		owner: string,
 		ownerLabel: string,
 		at: number,
-	): Promise<{ claim: ClaimRecord; conflict?: ClaimRecord }> {
+	): Promise<{ claim: ClaimRecord; conflict?: ClaimRecord; created: boolean }> {
 		await mkdir(claimsDir, { recursive: true, mode: DIR_MODE });
 		const file = claimFile(path);
 		const claim: ClaimRecord = { path, owner, ownerLabel, at };
@@ -227,19 +285,21 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 		try {
 			try {
 				await link(temp, file);
-				return { claim };
+				return { claim, created: true };
 			} catch (error) {
 				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
 			}
 			const existing = readTyped(file, isClaim);
 			if (existing) {
-				return existing.owner === owner ? { claim: existing } : { claim, conflict: existing };
+				return existing.owner === owner
+					? { claim: existing, created: false }
+					: { claim, conflict: existing, created: false };
 			}
 			// A claim file that does not parse is debris from before claims were
 			// published whole; clear it once so a stale path cannot block forever.
 			await rm(file, { force: true });
 			await link(temp, file);
-			return { claim };
+			return { claim, created: true };
 		} finally {
 			await rm(temp, { force: true });
 		}
@@ -258,13 +318,19 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 	 *
 	 * The pre-check reads the claims once and reports every blocking owner, so a
 	 * batch that cannot be satisfied touches no file. A create that loses a race
-	 * after the pre-check releases the paths this batch already took.
+	 * after the pre-check gives back only what this batch published: a path the
+	 * owner already held carries an older `at` and is not this batch's to release.
+	 *
+	 * `afterClaim` is a test seam: it runs after a path is published, which is the
+	 * only way a suite can put a rival claim in the window between the pre-check and
+	 * the next create.
 	 */
 	async function claimAll(
 		paths: readonly string[],
 		owner: string,
 		ownerLabel: string,
 		at: number,
+		afterClaim?: (path: string) => Promise<void>,
 	): Promise<{ claimed: string[]; conflicts: ClaimConflict[] }> {
 		const existing = await readClaims();
 		const conflicts: ClaimConflict[] = [];
@@ -277,14 +343,17 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 		}
 		if (conflicts.length > 0) return { claimed: [], conflicts };
 		const claimed: string[] = [];
+		const created: string[] = [];
 		for (const path of paths) {
 			const result = await claimOne(path, owner, ownerLabel, at);
 			if (result.conflict) {
-				for (const done of claimed) await releaseOne(done, owner);
+				for (const done of created) await releaseOne(done, owner);
 				const { owner: holder, ownerLabel: holderLabel } = result.conflict;
 				return { claimed: [], conflicts: [{ path, owner: holder, ownerLabel: holderLabel }] };
 			}
 			claimed.push(path);
+			if (result.created) created.push(path);
+			if (afterClaim) await afterClaim(path);
 		}
 		return { claimed, conflicts: [] };
 	}
@@ -318,9 +387,19 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 			await writeJson(join(directory, `${message.id}.json`), message);
 		},
 
-		peek: (id, limit) => readMessages(id, limit, false),
+		async peek(id, options) {
+			const directory = inboxDir(id);
+			const names = await listFiles(directory);
+			return {
+				mail: await readMessages(directory, names, { ...options, remove: false }),
+				unread: new Set(names.map(idOfFile)),
+			};
+		},
 
-		inbox: (id, limit) => readMessages(id, limit, true),
+		async inbox(id, limit) {
+			const directory = inboxDir(id);
+			return readMessages(directory, await listFiles(directory), { limit, remove: true });
+		},
 
 		async unread(id) {
 			return (await listFiles(inboxDir(id))).length;
@@ -364,12 +443,15 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 			for (const claim of await readClaims()) {
 				if (!live.has(claim.owner)) await rm(claimFile(claim.path), { force: true });
 			}
+			await dropStaleTemps(sessionsDir);
+			await dropStaleTemps(claimsDir);
 			for (const name of await readdir(inboxRoot).catch(() => [] as string[])) {
 				const directory = join(inboxRoot, name);
 				for (const file of await listFiles(directory)) {
 					const message = readTyped(join(directory, file), isMessage);
 					if (!message || at - message.at > messageTtlMs) await rm(join(directory, file), { force: true });
 				}
+				await dropStaleTemps(directory);
 				await dropIfEmpty(directory);
 			}
 		},

package/extensions/session-bus/types.ts

@@ -53,6 +53,25 @@ export interface BusMessage {
 	at: number;
 }
 
+/**
+ * One read of a recipient's inbox.
+ *
+ * The watch and `inbox` ask two questions of the same directory — which mail is new,
+ * and which mail is gone — and one readdir answers both, so a queue's health never
+ * depends on what a single page happened to cover.
+ */
+export interface InboxPeek {
+	/** Up to one page of messages the caller has not seen, oldest first. */
+	mail: BusMessage[];
+	/**
+	 * Every id whose file is still in the inbox, whether or not this read returned it.
+	 *
+	 * A file this build cannot read counts: it stays where it is, and `inbox` or the prune
+	 * TTL is what ends it, so its id is never in `mail` while it is still here.
+	 */
+	unread: ReadonlySet<string>;
+}
+
 /** One repository-relative claim. */
 export interface ClaimRecord {
 	path: string;

package/extensions/session-bus/{tui.ts → view/session-list.ts}

@@ -10,14 +10,14 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { matchesKey, Key } from "@earendil-works/pi-tui";
-import { messageOf } from "../../lib/errors.ts";
-import { formatDuration, sanitizeLine } from "../../lib/format.ts";
-import type { ScreenHint, ViewportRowsSource } from "../../lib/tui/chrome.ts";
-import { type DetailContents, DockListScreen } from "../../lib/tui/dock-screen.ts";
-import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { keyValueRow } from "../../lib/tui/rows.ts";
-import { paint } from "../../lib/tui/tokens.ts";
-import { idSuffix } from "./format.ts";
+import { messageOf } from "../../../lib/errors.ts";
+import { formatDuration, sanitizeLine } from "../../../lib/format.ts";
+import type { ScreenHint, ViewportRowsSource } from "../../../lib/tui/chrome.ts";
+import { type DetailContents, DockListScreen } from "../../../lib/tui/dock-screen.ts";
+import { SEPARATORS } from "../../../lib/tui/glyphs.ts";
+import { keyValueRow } from "../../../lib/tui/rows.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { idSuffix } from "../format.ts";
 import {
 	type SessionRow,
 	claimRowLine,
@@ -27,8 +27,8 @@ import {
 	sessionRowLine,
 	sessionRows,
 	summaryCells,
-} from "./rows.ts";
-import type { BoardSnapshot, BusMessage, ClaimRecord } from "./types.ts";
+} from "../rows.ts";
+import type { BoardSnapshot, BusMessage, ClaimRecord } from "../types.ts";
 
 /** The scopes `Tab` cycles through. */
 export type BoardScope = "sessions" | "inbox" | "claims";
@@ -112,8 +112,8 @@ export interface SessionListCallbacks {
 }
 
 interface SessionListOptions {
-	/** The latest board, or undefined before the first read. */
-	latest(): BoardSnapshot | undefined;
+	/** The board the screen opens on; the command's poll replaces it, and it is never read back. */
+	board: BoardSnapshot | undefined;
 	theme: Theme;
 	callbacks: SessionListCallbacks;
 	onClose(): void;
@@ -150,7 +150,7 @@ export class SessionListComponent extends DockListScreen<BoardRow> {
 		});
 		this.callbacks = options.callbacks;
 		this.now = options.now ?? Date.now;
-		this.board = options.latest();
+		this.board = options.board;
 	}
 
 	/** Replace the board; a poll that changed nothing does not repaint. */
@@ -257,7 +257,7 @@ export class SessionListComponent extends DockListScreen<BoardRow> {
 				hints.push(enter("read"), this.watchHint(), "↑/↓", "PgUp/PgDn");
 				break;
 			case "claims":
-				hints.push(enter("open"), { text: "x release", color: "warning" }, "↑/↓", "PgUp/PgDn");
+				hints.push(enter("open"), { text: "x release", color: "warn" }, "↑/↓", "PgUp/PgDn");
 				break;
 		}
 		return hints;
@@ -265,7 +265,7 @@ export class SessionListComponent extends DockListScreen<BoardRow> {
 
 	protected detailHints(row: BoardRow | undefined): ScreenHint[] {
 		if (row?.kind === "claim" && row.claim.owner === this.me()) {
-			return ["Esc back", { text: "x release", color: "warning" }, "↑/↓ scroll", "g/G ends"];
+			return ["Esc back", { text: "x release", color: "warn" }, "↑/↓ scroll", "g/G ends"];
 		}
 		return ["Esc back", "↑/↓ scroll", "g/G ends", "PgUp/PgDn"];
 	}
@@ -366,7 +366,7 @@ export class SessionListComponent extends DockListScreen<BoardRow> {
 
 	private watchHint(): ScreenHint {
 		return this.board?.status.watching
-			? { text: "w watch off", color: "warning" }
+			? { text: "w watch off", color: "warn" }
 			: { text: "w watch on", color: "accent" };
 	}
 

package/extensions/subagent/agents.ts

@@ -2,7 +2,7 @@
  * Agent definitions and discovery.
  *
  * Built-in agents ship with the extension. User agents are loaded from
- * `<agentDir>/agents` and project agents from the nearest
+ * `<agent-dir>/agents` and project agents from the nearest
  * `<CONFIG_DIR_NAME>/agents` (for example `.pi/agents`). Each external file is
  * markdown with YAML frontmatter (`name`, `description`, `tools`, `model`) and
  * the system prompt as the body.

package/extensions/subagent/commands.ts

@@ -9,9 +9,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { planModeRefusal } from "../../lib/plan-entry.ts";
 import { isPlanModeEnabled } from "../../lib/plan-state.ts";
-import { withRailsSuppressed } from "../../lib/rails.ts";
 import type { BackgroundRuntime } from "./background.ts";
-import { AgentsBoardComponent } from "./background-tui.ts";
 import { formatAgentsList } from "./format.ts";
 
 /** Open `/agents`; the TUI gets the board, other modes get the list. */
@@ -35,6 +33,10 @@ async function openAgents(
 		return;
 	}
 
+	// The board is the TUI's: the list above and registration load neither it nor
+	// its rails wrapper.
+	const { withRailsSuppressed } = await import("../../lib/rails.ts");
+	const { AgentsBoardComponent } = await import("./view/agents-board.ts");
 	let collectId: string | undefined;
 	await withRailsSuppressed(pi, async () => {
 		await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {

package/extensions/subagent/format.ts

@@ -9,6 +9,7 @@
 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 { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import { USAGE_COUNTERS, zeroUsage } from "../../lib/usage.ts";
 import type { BackgroundRun } from "./background.ts";
 import type { UsageSource, UsageStats } from "./types.ts";
@@ -116,13 +117,13 @@ export function formatToolCall(
 	theme: Theme,
 	preview: boolean,
 ): string {
-	const fg = theme.fg.bind(theme);
+	const fg = (role: TuiRole, text: string) => paint(theme, role, text);
 	// Defensive: a malformed tool-call part can carry a null/undefined `arguments`.
 	const a = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
 
 	switch (toolName) {
 		case "bash":
-			return fg("muted", "$ ") + fg("toolOutput", clip(sanitizeLine(String(a.command ?? "…")), preview ? 60 : 200));
+			return fg("meta", "$ ") + fg("toolOutput", clip(sanitizeLine(String(a.command ?? "…")), preview ? 60 : 200));
 		case "read": {
 			const rawPath = clipPath(shortenPath(sanitizeLine(String(a.file_path ?? a.path ?? "…"))), preview ? 60 : 200);
 			const offset = a.offset as number | undefined;
@@ -131,44 +132,43 @@ export function formatToolCall(
 			if (offset !== undefined || limit !== undefined) {
 				const start = offset ?? 1;
 				const end = limit !== undefined ? start + limit - 1 : "";
-				text += fg("warning", `:${start}${end ? `-${end}` : ""}`);
+				text += fg("warn", `:${start}${end ? `-${end}` : ""}`);
 			}
-			return fg("muted", "read ") + text;
+			return fg("meta", "read ") + text;
 		}
 		case "write": {
 			const rawPath = clipPath(shortenPath(sanitizeLine(String(a.file_path ?? a.path ?? "…"))), preview ? 60 : 200);
 			const content = String(a.content ?? "");
 			const lines = content.split("\n").length;
-			const text = fg("muted", "write ") + fg("accent", rawPath);
-			return lines > 1 ? text + fg("dim", ` (${lines} lines)`) : text;
+			const text = fg("meta", "write ") + fg("accent", rawPath);
+			return lines > 1 ? text + fg("faint", ` (${lines} lines)`) : text;
 		}
 		case "edit":
 			return (
-				fg("muted", "edit ") +
+				fg("meta", "edit ") +
 				fg("accent", clipPath(shortenPath(sanitizeLine(String(a.file_path ?? a.path ?? "…"))), preview ? 60 : 200)) +
-				fg("dim", " (diff)")
+				fg("faint", " (diff)")
 			);
 		case "ls":
 			return (
-				fg("muted", "ls ") +
-				fg("accent", clipPath(shortenPath(sanitizeLine(String(a.path ?? "."))), preview ? 60 : 200))
+				fg("meta", "ls ") + fg("accent", clipPath(shortenPath(sanitizeLine(String(a.path ?? "."))), preview ? 60 : 200))
 			);
 		case "find":
 			return (
-				fg("muted", "find ") +
+				fg("meta", "find ") +
 				fg("accent", clip(sanitizeLine(String(a.pattern ?? "*")), preview ? 40 : 120)) +
-				fg("dim", ` in ${clipPath(shortenPath(sanitizeLine(String(a.path ?? "."))), preview ? 40 : 120)}`)
+				fg("faint", ` in ${clipPath(shortenPath(sanitizeLine(String(a.path ?? "."))), preview ? 40 : 120)}`)
 			);
 		case "grep":
 			return (
-				fg("muted", "grep ") +
+				fg("meta", "grep ") +
 				fg("accent", `/${clip(sanitizeLine(String(a.pattern ?? "")), preview ? 40 : 120)}/`) +
-				fg("dim", ` in ${clipPath(shortenPath(sanitizeLine(String(a.path ?? "."))), preview ? 40 : 120)}`)
+				fg("faint", ` in ${clipPath(shortenPath(sanitizeLine(String(a.path ?? "."))), preview ? 40 : 120)}`)
 			);
 		default: {
 			const json = JSON.stringify(a);
 			const text = clip(json, preview ? 50 : 200);
-			return fg("accent", sanitizeLine(toolName)) + fg("dim", ` ${text}`);
+			return fg("accent", sanitizeLine(toolName)) + fg("faint", ` ${text}`);
 		}
 	}
 }

package/extensions/subagent/index.ts

@@ -8,7 +8,7 @@
  * output).
  *
  * Agents are the built-ins in `agents.ts` plus optional user agents loaded from
- * `<agentDir>/agents` and project agents from the nearest `.pi/agents`; the
+ * `<agent-dir>/agents` and project agents from the nearest `.pi/agents`; the
  * `agentScope` parameter decides which external directories are consulted.
  * Subagents inherit the dispatching session's model and thinking level.
  *

package/extensions/subagent/render.ts

@@ -179,7 +179,7 @@ function indentBody(text: string, theme: Theme): string {
 	return stripControlChars(text)
 		.trim()
 		.split("\n")
-		.map((line) => indent + theme.fg("toolOutput", line))
+		.map((line) => indent + paint(theme, "toolOutput", line))
 		.join("\n");
 }
 
@@ -192,7 +192,7 @@ function renderDisplayItems(items: DisplayItem[], theme: Theme, limit?: number,
 		if (item.type === "text") {
 			const safe = stripControlChars(item.text);
 			const text = preview ? safe.split("\n").slice(0, COLLAPSED_TEXT_LINES).join("\n") : safe;
-			lines.push(theme.fg("toolOutput", text));
+			lines.push(paint(theme, "toolOutput", text));
 		} else {
 			lines.push(paint(theme, "meta", "→ ") + formatToolCall(item.name, item.args, theme, preview));
 		}
@@ -419,7 +419,7 @@ function multiHeader(details: SubagentDetails, theme: Theme, now: number): strin
 			: bad > 0
 				? paint(theme, bad === total ? "bad" : "warn", bad === total ? GLYPHS.jobsFailure : GLYPHS.half)
 				: paint(theme, "ok", GLYPHS.check);
-	return `${icon} ${theme.fg("toolTitle", theme.bold(`${details.mode} · `))}${paint(theme, "accent", status)}`;
+	return `${icon} ${paint(theme, "toolTitle", theme.bold(`${details.mode} · `))}${paint(theme, "accent", status)}`;
 }
 
 function collapsedMultiText(details: SubagentDetails, theme: Theme, now: number): string {