pi-crew 0.10.2 → 0.10.3

package/src/ui/render-diff.ts

@@ -36,10 +36,10 @@ const WORD_DIFF_MIN_SIM = 0.15;
  * characters relative to the longer of the two strings, using word-level
  * diff to identify the common (unchanged) parts. Returns a value in [0, 1].
  */
-function computeSimilarity(oldContent: string, newContent: string): number {
-	const wordDiff = Diff.diffWords(oldContent, newContent);
+function computeSimilarity(oldContent: string, newContent: string, wordDiff?: Diff.Change[]): number {
+	const parts = wordDiff ?? Diff.diffWords(oldContent, newContent);
 	let commonChars = 0;
-	for (const part of wordDiff) {
+	for (const part of parts) {
 		if (!part.removed && !part.added) {
 			commonChars += part.value.length;
 		}
@@ -49,14 +49,19 @@ function computeSimilarity(oldContent: string, newContent: string): number {
 	return commonChars / maxLen;
 }
 
-function renderIntraLineDiff(theme: CrewTheme, oldContent: string, newContent: string): { removedLine: string; addedLine: string } {
-	const wordDiff = Diff.diffWords(oldContent, newContent);
+function renderIntraLineDiff(
+	theme: CrewTheme,
+	oldContent: string,
+	newContent: string,
+	wordDiff?: Diff.Change[],
+): { removedLine: string; addedLine: string } {
+	const parts = wordDiff ?? Diff.diffWords(oldContent, newContent);
 	let removedLine = "";
 	let addedLine = "";
 	let isFirstRemoved = true;
 	let isFirstAdded = true;
 
-	for (const part of wordDiff) {
+	for (const part of parts) {
 		if (part.removed) {
 			let value = part.value;
 			if (isFirstRemoved) {
@@ -130,9 +135,12 @@ export function renderDiff(diffText: string, options: RenderDiffOptions = {}): s
 			if (removedLines.length === 1 && addedLines.length === 1) {
 				const oldContent = replaceTabs(removedLines[0]!.content);
 				const newContent = replaceTabs(addedLines[0]!.content);
-				const similarity = computeSimilarity(oldContent, newContent);
+				// PERF (2026-08-24): diffWords is the expensive call and was run
+				// TWICE on identical inputs (similarity + render). One pass, shared.
+				const wordDiff = Diff.diffWords(oldContent, newContent);
+				const similarity = computeSimilarity(oldContent, newContent, wordDiff);
 				if (similarity >= WORD_DIFF_MIN_SIM) {
-					const { removedLine, addedLine } = renderIntraLineDiff(theme, oldContent, newContent);
+					const { removedLine, addedLine } = renderIntraLineDiff(theme, oldContent, newContent, wordDiff);
 					result.push(theme.fg("toolDiffRemoved", `-${removedLines[0]!.lineNum} ${removedLine}`));
 					result.push(theme.fg("toolDiffAdded", `+${addedLines[0]!.lineNum} ${addedLine}`));
 				} else {

package/src/ui/run-dashboard.ts

@@ -162,11 +162,11 @@ function formatAge(iso: string | undefined): string | undefined {
 	return `${Math.floor(ms / 3_600_000)}h`;
 }
 
-function readProgressPreview(run: TeamRunManifest, maxLines = 5, snapshotCache?: RunSnapshotCache): string[] {
+function readProgressPreview(run: TeamRunManifest, maxLines = 5, snapshotCache?: RunSnapshotCache, resolve?: SnapshotResolver): string[] {
 	// P0-6: prefer the snapshot's `recentOutputLines` (no disk I/O) over reading the
 	// progress artifact on every render. The progress artifact content is captured
 	// into the snapshot's recent events / output pipeline upstream.
-	const snapshot = snapshotFor(run, snapshotCache);
+	const snapshot = resolve ? resolve(run) : snapshotFor(run, snapshotCache);
 	if (snapshot?.recentOutputLines?.length) {
 		return ["Progress:", ...snapshot.recentOutputLines.slice(0, maxLines)];
 	}
@@ -206,8 +206,20 @@ function snapshotFor(run: TeamRunManifest, snapshotCache?: RunSnapshotCache): Ru
 	}
 }
 
-function readRunTasks(run: TeamRunManifest, snapshotCache?: RunSnapshotCache): TeamTaskState[] {
-	const snapshot = snapshotFor(run, snapshotCache);
+/**
+ * PERF (2026-08-24, task 20) — per-frame snapshot resolver. The render path
+ * used to resolve each run's snapshot 6-8 times per frame (refreshRuns,
+ * buildSignature, groupedRuns, per-row, selected-run), and every
+ * `snapshotFor → refreshIfStale` call can stat several files per run when its
+ * own TTL expires. `renderUnsafe` now builds a frame-local Map keyed by runId
+ * and threads this resolver through every render-path helper. Helpers keep
+ * their plain direct-resolution behavior when no resolver is passed
+ * (keypress handlers and other callers outside a render frame).
+ */
+type SnapshotResolver = (run: TeamRunManifest) => RunUiSnapshot | undefined;
+
+function readRunTasks(run: TeamRunManifest, snapshotCache?: RunSnapshotCache, resolve?: SnapshotResolver): TeamTaskState[] {
+	const snapshot = resolve ? resolve(run) : snapshotFor(run, snapshotCache);
 	if (snapshot) return snapshot.tasks;
 	// P0-6: when a snapshot cache is provided but hasn't populated yet, return
 	// empty (the render loop falls back to the empty pane placeholder) instead
@@ -266,15 +278,15 @@ function agentPreviewLine(agent: CrewAgentRecord, task: TeamTaskState | undefine
 	);
 }
 
-function readAgentPreview(run: TeamRunManifest, maxLines = 5, options: RunDashboardOptions = {}): string[] {
+function readAgentPreview(run: TeamRunManifest, maxLines = 5, options: RunDashboardOptions = {}, resolve?: SnapshotResolver): string[] {
 	try {
-		const snapshot = snapshotFor(run, options.snapshotCache);
+		const snapshot = resolve ? resolve(run) : snapshotFor(run, options.snapshotCache);
 		// P0-6: when a snapshot cache is provided but hasn't populated yet, return
 		// the empty-pane placeholder instead of calling `readCrewAgents` (disk I/O)
 		// on every render tick. Legacy callers (no cache) keep the disk-read path
 		// so existing unit tests continue to assert against concrete agent data.
 		const agents = snapshot?.agents ?? (options.snapshotCache ? [] : readCrewAgents(run));
-		const tasks = snapshot?.tasks ?? readRunTasks(run, options.snapshotCache);
+		const tasks = snapshot?.tasks ?? readRunTasks(run, options.snapshotCache, resolve);
 		if (!agents.length) return ["Agents: (none)"];
 		const totals = tasks.reduce(
 			(acc, task) => {
@@ -305,8 +317,8 @@ function readAgentPreview(run: TeamRunManifest, maxLines = 5, options: RunDashbo
 	}
 }
 
-function agentsFor(run: TeamRunManifest, snapshotCache?: RunSnapshotCache): CrewAgentRecord[] {
-	const snapshot = snapshotFor(run, snapshotCache);
+function agentsFor(run: TeamRunManifest, snapshotCache?: RunSnapshotCache, resolve?: SnapshotResolver): CrewAgentRecord[] {
+	const snapshot = resolve ? resolve(run) : snapshotFor(run, snapshotCache);
 	if (snapshot) return snapshot.agents;
 	// P0-6: when a snapshot cache is provided but hasn't populated yet, return
 	// empty (callers handle the empty-state placeholder) instead of calling
@@ -319,8 +331,14 @@ function agentsFor(run: TeamRunManifest, snapshotCache?: RunSnapshotCache): Crew
 	}
 }
 
-function runLabel(run: TeamRunManifest, selected: boolean, snapshotCache?: RunSnapshotCache, maxW?: number): string {
-	const agents = agentsFor(run, snapshotCache);
+function runLabel(
+	run: TeamRunManifest,
+	selected: boolean,
+	snapshotCache?: RunSnapshotCache,
+	maxW?: number,
+	resolve?: SnapshotResolver,
+): string {
+	const agents = agentsFor(run, snapshotCache, resolve);
 	const stale = isLikelyOrphanedActiveRun(run, agents);
 	const running = agents.find((agent) => agent.status === "running");
 	const queued = agents.find((agent) => agent.status === "queued");
@@ -366,11 +384,11 @@ interface ResolvedRun {
 	status: RunStatus;
 }
 
-function resolveRuns(runs: TeamRunManifest[], snapshotCache?: RunSnapshotCache): Map<string, ResolvedRun> {
+function resolveRuns(runs: TeamRunManifest[], snapshotCache?: RunSnapshotCache, resolve?: SnapshotResolver): Map<string, ResolvedRun> {
 	const map = new Map<string, ResolvedRun>();
 	for (const run of runs) {
-		const snapshot = snapshotFor(run, snapshotCache);
-		const agents = snapshot?.agents ?? agentsFor(run, snapshotCache);
+		const snapshot = resolve ? resolve(run) : snapshotFor(run, snapshotCache);
+		const agents = snapshot?.agents ?? agentsFor(run, snapshotCache, resolve);
 		const displayRun = snapshot?.manifest ?? run;
 		const status: RunStatus = isLikelyOrphanedActiveRun(displayRun, agents) ? "stale" : (displayRun.status as RunStatus);
 		map.set(run.runId, { manifest: run, snapshot, agents, status });
@@ -378,8 +396,12 @@ function resolveRuns(runs: TeamRunManifest[], snapshotCache?: RunSnapshotCache):
 	return map;
 }
 
-function groupedRuns(runs: TeamRunManifest[], snapshotCache?: RunSnapshotCache): Array<{ label: string; run?: TeamRunManifest }> {
-	const resolved = resolveRuns(runs, snapshotCache);
+function groupedRuns(
+	runs: TeamRunManifest[],
+	snapshotCache?: RunSnapshotCache,
+	resolve?: SnapshotResolver,
+): Array<{ label: string; run?: TeamRunManifest }> {
+	const resolved = resolveRuns(runs, snapshotCache, resolve);
 	const rows: Array<{ label: string; run?: TeamRunManifest }> = [];
 	const active = runs.filter((run) =>
 		isDisplayActiveRun(resolved.get(run.runId)?.snapshot?.manifest ?? run, resolved.get(run.runId)?.agents ?? []),
@@ -392,8 +414,13 @@ function groupedRuns(runs: TeamRunManifest[], snapshotCache?: RunSnapshotCache):
 	return rows;
 }
 
-function selectedRunFromGrouped(runs: TeamRunManifest[], selected: number, snapshotCache?: RunSnapshotCache): TeamRunManifest | undefined {
-	return groupedRuns(runs, snapshotCache).filter((row) => row.run)[selected]?.run;
+function selectedRunFromGrouped(
+	runs: TeamRunManifest[],
+	selected: number,
+	snapshotCache?: RunSnapshotCache,
+	resolve?: SnapshotResolver,
+): TeamRunManifest | undefined {
+	return groupedRuns(runs, snapshotCache, resolve).filter((row) => row.run)[selected]?.run;
 }
 
 function countByStatus(runs: TeamRunManifest[], snapshotCache?: RunSnapshotCache): string {
@@ -520,9 +547,9 @@ export class RunDashboard implements DashboardComponent {
 		return Math.max(12, Math.min(36, rows - 2));
 	}
 
-	private refreshRuns(): void {
+	private refreshRuns(resolve?: SnapshotResolver): void {
 		if (!this.options.runProvider) return;
-		const selectedRunId = this.selectedRunId();
+		const selectedRunId = this.selectedRunId(resolve);
 		const next = this.options.runProvider();
 		// P3 (#8): re-apply the workspaceId filter on EVERY refresh, not just
 		// the constructor. Without this, runs from other sessions leak back in
@@ -532,7 +559,7 @@ export class RunDashboard implements DashboardComponent {
 			? unfiltered.filter((run) => !run.ownerSessionId || run.ownerSessionId === this.options.workspaceId)
 			: unfiltered;
 		if (selectedRunId) {
-			const nextIndex = groupedRuns(this.runs, this.options.snapshotCache)
+			const nextIndex = groupedRuns(this.runs, this.options.snapshotCache, resolve)
 				.filter((row) => row.run)
 				.findIndex((row) => row.run?.runId === selectedRunId);
 			if (nextIndex >= 0) this.selected = nextIndex;
@@ -564,7 +591,7 @@ export class RunDashboard implements DashboardComponent {
 		}
 	}
 
-	private buildSignature(): string {
+	private buildSignature(resolve?: SnapshotResolver): string {
 		// 1.10 (UI-P1-2) — short-TTL cache so we don't re-read every run's
 		// snapshot on every render tick. `snapshotFor → refreshIfStale` can
 		// stat multiple files per run when its own TTL expires, and the
@@ -579,9 +606,9 @@ export class RunDashboard implements DashboardComponent {
 		let hasRunning = false;
 		const statuses = this.runs
 			.map((run) => {
-				const snapshot = snapshotFor(run, this.options.snapshotCache);
+				const snapshot = resolve ? resolve(run) : snapshotFor(run, this.options.snapshotCache);
 				const displayRun = snapshot?.manifest ?? run;
-				const agents = snapshot?.agents ?? agentsFor(run, this.options.snapshotCache);
+				const agents = snapshot?.agents ?? agentsFor(run, this.options.snapshotCache, resolve);
 				const stale = isLikelyOrphanedActiveRun(displayRun, agents);
 				const status: RunStatus = stale ? "stale" : (displayRun.status as RunStatus);
 				if (status === "running" || agents.some((agent) => agent.status === "running")) hasRunning = true;
@@ -611,8 +638,8 @@ export class RunDashboard implements DashboardComponent {
 		this.schedulerHandle?.dispose();
 	}
 
-	private selectedRunId(): string | undefined {
-		return selectedRunFromGrouped(this.runs, this.selected, this.options.snapshotCache)?.runId;
+	private selectedRunId(resolve?: SnapshotResolver): string | undefined {
+		return selectedRunFromGrouped(this.runs, this.selected, this.options.snapshotCache, resolve)?.runId;
 	}
 
 	render(width: number): string[] {
@@ -625,13 +652,25 @@ export class RunDashboard implements DashboardComponent {
 	}
 
 	private renderUnsafe(width: number): string[] {
-		this.refreshRuns();
-		const signature = this.buildSignature();
+		// PERF (2026-08-24): snapshot resolution stat'd 7-8 files per run 6-8
+		// times per frame. Resolve once per frame into a local map and thread
+		// it through every render-path consumer below.
+		const frameSnapshots = new Map<string, RunUiSnapshot | undefined>();
+		const snapshotOnce: SnapshotResolver = (run) => {
+			if (!frameSnapshots.has(run.runId)) frameSnapshots.set(run.runId, snapshotFor(run, this.options.snapshotCache));
+			return frameSnapshots.get(run.runId);
+		};
+		this.refreshRuns(snapshotOnce);
+		const signature = this.buildSignature(snapshotOnce);
 		if (signature !== this.cachedVersion || this.cachedWidth !== width) {
 			const innerWidth = Math.max(20, width - 4);
 			const borderWidth = Math.min(innerWidth, Math.max(0, width - 2));
 			const fg = (color: Parameters<CrewTheme["fg"]>[0], text: string) => this.theme.fg(color, text);
-			const borderFill = (count: number) => new DynamicCrewBorder(this.theme).render(count)[0];
+			// PERF (2026-08-24): DynamicCrewBorder caches the rendered fill per
+			// instance — a new instance per line defeated it. One per render
+			// pass; every border()/sep() call below reuses the cached line.
+			const crewBorder = new DynamicCrewBorder(this.theme);
+			const borderFill = (count: number) => crewBorder.render(count)[0];
 			const border = (left: string, right: string) => `${fg("border", left)}${borderFill(borderWidth)}${fg("border", right)}`;
 			const row = (text: string) => `│ ${pad(truncate(text, innerWidth - 1), innerWidth - 1)}│`;
 			const sep = () => border("├", "┤");
@@ -655,7 +694,7 @@ export class RunDashboard implements DashboardComponent {
 					lines.push(row(fg("dim", "Start one: team action='run' · r reload · Esc close")));
 				} else {
 					// L-1: windowed run list so the selection can never scroll off-screen.
-					const allGrouped = groupedRuns(this.runs, this.options.snapshotCache);
+					const allGrouped = groupedRuns(this.runs, this.options.snapshotCache, snapshotOnce);
 					const selectable = allGrouped.filter((rowItem) => rowItem.run);
 					const selectableCount = selectable.length;
 					if (this.selected > selectableCount - 1) this.selected = Math.max(0, selectableCount - 1);
@@ -668,11 +707,11 @@ export class RunDashboard implements DashboardComponent {
 								continue;
 							}
 							const idx = selectable.findIndex((c) => c.run?.runId === rowItem.run?.runId);
-							const snap = snapshotFor(rowItem.run, this.options.snapshotCache);
+							const snap = snapshotOnce(rowItem.run);
 							const run = snap?.manifest ?? rowItem.run;
-							const agents = snap?.agents ?? agentsFor(rowItem.run, this.options.snapshotCache);
+							const agents = snap?.agents ?? agentsFor(rowItem.run, this.options.snapshotCache, snapshotOnce);
 							const status: RunStatus = isLikelyOrphanedActiveRun(run, agents) ? "stale" : (run.status as RunStatus);
-							const label = runLabel(run, idx === this.selected, this.options.snapshotCache, innerWidth - 2);
+							const label = runLabel(run, idx === this.selected, this.options.snapshotCache, innerWidth - 2, snapshotOnce);
 							lines.push(row(applyStatusColor(this.theme, status, label)));
 						}
 					} else {
@@ -682,25 +721,28 @@ export class RunDashboard implements DashboardComponent {
 						for (let gi = this.runScrollOffset; gi < Math.min(this.runScrollOffset + win.slots, selectableCount); gi++) {
 							const rowItem = selectable[gi];
 							if (!rowItem?.run) continue;
-							const snap = snapshotFor(rowItem.run, this.options.snapshotCache);
+							const snap = snapshotOnce(rowItem.run);
 							const run = snap?.manifest ?? rowItem.run;
-							const agents = snap?.agents ?? agentsFor(rowItem.run, this.options.snapshotCache);
+							const agents = snap?.agents ?? agentsFor(rowItem.run, this.options.snapshotCache, snapshotOnce);
 							const status: RunStatus = isLikelyOrphanedActiveRun(run, agents) ? "stale" : (run.status as RunStatus);
-							const label = runLabel(run, gi === this.selected, this.options.snapshotCache, innerWidth - 2);
+							const label = runLabel(run, gi === this.selected, this.options.snapshotCache, innerWidth - 2, snapshotOnce);
 							lines.push(row(applyStatusColor(this.theme, status, label)));
 						}
 						if (win.hasBottom)
 							lines.push(row(fg("dim", `↓ ${selectableCount - (this.runScrollOffset + win.slots)} more below`)));
 					}
 
-					// Selected run detail — compact
-					const selectedRun = selectedRunFromGrouped(this.runs, this.selected, this.options.snapshotCache);
+					// Selected run detail — compact. PERF (2026-08-24): reuse the
+					// `selectable` rows already derived from the single groupedRuns()
+					// computation above instead of recomputing grouping a third time
+					// (`selectedRunFromGrouped` is exactly `selectable[selected].run`).
+					const selectedRun = selectable[Math.min(this.selected, selectable.length - 1)]?.run;
 					if (selectedRun) {
-						const snap = snapshotFor(selectedRun, this.options.snapshotCache);
+						const snap = snapshotOnce(selectedRun);
 						const r = snap?.manifest ?? selectedRun;
-						const agents = snap?.agents ?? agentsFor(selectedRun, this.options.snapshotCache);
+						const agents = snap?.agents ?? agentsFor(selectedRun, this.options.snapshotCache, snapshotOnce);
 						const statusStr: RunStatus = isLikelyOrphanedActiveRun(r, agents) ? "stale" : (r.status as RunStatus);
-						const selectedTasks = snap?.tasks ?? readRunTasks(r, this.options.snapshotCache);
+						const selectedTasks = snap?.tasks ?? readRunTasks(r, this.options.snapshotCache, snapshotOnce);
 						lines.push(sep());
 						lines.push(row(`${fg("accent", "▸")} ${truncate(sanitizeLine(r.goal), innerWidth - 6)}`));
 						// L-2: surface the failure/cancellation reason inline for terminal runs.
@@ -741,7 +783,10 @@ export class RunDashboard implements DashboardComponent {
 												: this.activePane === "plan"
 													? safeRenderPane("plan", () => renderPlanPane(snap, { diff: this.planDiff }))
 													: safeRenderPane("transcript", () => renderTranscriptPane(snap))
-							: [...readAgentPreview(r, 4, this.options), ...readProgressPreview(r, 2, this.options.snapshotCache)];
+							: [
+									...readAgentPreview(r, 4, this.options, snapshotOnce),
+									...readProgressPreview(r, 2, this.options.snapshotCache, snapshotOnce),
+								];
 						const filteredPane = paneLines.filter((l) => l && !l.includes("(none)") && l.trim() !== "");
 						if (filteredPane.length > 0) {
 							lines.push(row(fg("dim", `── ${this.activePane} ──`)));

package/src/ui/run-event-bus.ts

@@ -359,7 +359,16 @@ export function teamEventToRunEventType(event: TeamEvent): RunEventType | undefi
 	if (type === "run.blocked") return "run_blocked";
 	if (type === "run.running") return "run_started";
 	if (type === "run.cancelled") return "run_cancelled";
-	if (type === "task.progress" || type === "mailbox.message_queued" || type === "mailbox.message_delivered") return "mailbox_updated";
+	if (
+		type === "task.progress" ||
+		type === "mailbox.message_queued" ||
+		type === "mailbox.message_delivered" ||
+		// Task 5b (§15.2 wake): broker-side worker→parent wake signal. Maps to
+		// the existing mailbox_updated/run:state channel so sidebar+widget
+		// refresh through the render scheduler without new UI code.
+		type === "worker.message"
+	)
+		return "mailbox_updated";
 	if (type === "run.effectiveness" || type === "task.attention") return "effectiveness_changed";
 	return undefined;
 }

package/src/ui/run-snapshot-cache.ts

@@ -25,6 +25,8 @@ import type {
 export interface RunSnapshotCache extends RunSnapshotCacheBase {
 	preloadStale(runId: string): Promise<RunUiSnapshot | undefined>;
 	preloadAllStale(runIds: string[]): Promise<void>;
+	/** Task 17 (perf/review-2026-08-24): watcher-facing coalesced async refresh. */
+	scheduleRefresh(runId: string): void;
 }
 
 /** WP-7 (R7): the plans slice + Plan pane load only when this flag is set —
@@ -191,9 +193,18 @@ function sameStamps(a: SnapshotStamps, b: SnapshotStamps): boolean {
 	);
 }
 
-/** Tail-read JSONL lines from a file, returning parsed objects (limited). */
-function tailJsonlLines<T>(filePath: string, limit: number, parse: (line: string) => T | undefined): T[] {
-	if (limit <= 0) return [];
+/** Raw tail-window of a file: split lines plus whether the window clipped content. */
+interface TailContent {
+	lines: string[];
+	approximate: boolean;
+}
+
+/**
+ * PERF (2026-08-24): single tail read of a file, shareable across consumers.
+ * `approximate` mirrors the old tailApproximate() stat (size > MAX_TAIL_BYTES)
+ * so callers keep reporting clipped mailboxes without re-statting.
+ */
+function readTailContent(filePath: string): TailContent {
 	try {
 		const stat = fs.statSync(filePath);
 		const bytesToRead = Math.min(stat.size, MAX_TAIL_BYTES);
@@ -201,21 +212,35 @@ function tailJsonlLines<T>(filePath: string, limit: number, parse: (line: string
 		try {
 			const buffer = Buffer.alloc(bytesToRead);
 			fs.readSync(fd, buffer, 0, bytesToRead, stat.size - bytesToRead);
-			const lines = buffer.toString("utf-8").split(/\r?\n/).filter(Boolean);
-			return lines
-				.flatMap((line) => {
-					const item = parse(line);
-					return item ? [item] : [];
-				})
-				.slice(-limit);
+			return {
+				lines: buffer.toString("utf-8").split(/\r?\n/).filter(Boolean),
+				approximate: stat.size > MAX_TAIL_BYTES,
+			};
 		} finally {
 			fs.closeSync(fd);
 		}
 	} catch {
-		return [];
+		return { lines: [], approximate: false };
 	}
 }
 
+/** Parse pre-read tail lines, keeping the last `limit` parseable items. */
+function parseTailLines<T>(lines: string[], limit: number, parse: (line: string) => T | undefined): T[] {
+	if (limit <= 0) return [];
+	return lines
+		.flatMap((line) => {
+			const item = parse(line);
+			return item ? [item] : [];
+		})
+		.slice(-limit);
+}
+
+/** Tail-read JSONL lines from a file, returning parsed objects (limited). */
+function tailJsonlLines<T>(filePath: string, limit: number, parse: (line: string) => T | undefined): T[] {
+	if (limit <= 0) return [];
+	return parseTailLines(readTailContent(filePath).lines, limit, parse);
+}
+
 /** Async tail-read JSONL lines from a file, returning parsed objects (limited). */
 async function tailJsonlLinesAsync<T>(filePath: string, limit: number, parse: (line: string) => T | undefined): Promise<T[]> {
 	if (limit <= 0) return [];
@@ -406,8 +431,9 @@ async function readDeliveryMessagesAsync(filePath: string): Promise<Record<strin
 	}
 }
 
-function readGroupJoinMailbox(filePath: string, delivery: Record<string, MailboxMessageStatus>): RunUiGroupJoin[] {
-	return tailJsonlLines(filePath, MAX_TAIL_LINES, (line) => {
+/** Parse pre-read outbox lines into group-join records (ack status from `delivery`). */
+function parseGroupJoinLines(lines: string[], delivery: Record<string, MailboxMessageStatus>): RunUiGroupJoin[] {
+	return parseTailLines(lines, MAX_TAIL_LINES, (line) => {
 		try {
 			const parsed = JSON.parse(line) as unknown;
 			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
@@ -464,14 +490,6 @@ interface MailboxKindCount extends MailboxCount {
 	message: number;
 }
 
-function tailApproximate(filePath: string): boolean {
-	try {
-		return fs.statSync(filePath).size > MAX_TAIL_BYTES;
-	} catch {
-		return false;
-	}
-}
-
 async function tailApproximateAsync(filePath: string): Promise<boolean> {
 	try {
 		return (await fs.promises.stat(filePath)).size > MAX_TAIL_BYTES;
@@ -481,8 +499,13 @@ async function tailApproximateAsync(filePath: string): Promise<boolean> {
 }
 
 function readMailboxCounts(filePath: string, delivery: Record<string, MailboxMessageStatus>): MailboxKindCount {
+	return mailboxCountsFrom(readTailContent(filePath), delivery);
+}
+
+/** Count unread/pending by kind from a pre-read tail window (shared outbox read). */
+function mailboxCountsFrom(tail: TailContent, delivery: Record<string, MailboxMessageStatus>): MailboxKindCount {
 	const kindCounts = { steer: 0, followUp: 0, response: 0, message: 0 };
-	const items = tailJsonlLines(filePath, MAX_TAIL_LINES, (line) => {
+	const items = parseTailLines(tail.lines, MAX_TAIL_LINES, (line) => {
 		try {
 			const parsed = JSON.parse(line) as unknown;
 			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return 0;
@@ -514,7 +537,7 @@ function readMailboxCounts(filePath: string, delivery: Record<string, MailboxMes
 	const count = items.reduce((sum, val) => sum + val, 0);
 	return {
 		count,
-		approximate: tailApproximate(filePath),
+		approximate: tail.approximate,
 		steer: kindCounts.steer,
 		followUp: kindCounts.followUp,
 		response: kindCounts.response,
@@ -564,10 +587,12 @@ async function readMailboxCountsAsync(filePath: string, delivery: Record<string,
 	};
 }
 
-function groupJoinsFrom(manifest: TeamRunManifest): RunUiGroupJoin[] {
-	const root = path.join(manifest.stateRoot, "mailbox");
-	const delivery = readDeliveryMessages(path.join(root, "delivery.json"));
-	return readGroupJoinMailbox(path.join(root, "outbox.jsonl"), delivery).slice(-5);
+function groupJoinsFrom(
+	manifest: TeamRunManifest,
+	delivery: Record<string, MailboxMessageStatus>,
+	outboxTail: TailContent,
+): RunUiGroupJoin[] {
+	return parseGroupJoinLines(outboxTail.lines, delivery).slice(-5);
 }
 
 async function groupJoinsFromAsync(manifest: TeamRunManifest): Promise<RunUiGroupJoin[]> {
@@ -587,11 +612,15 @@ function mergeKindCounts(a: MailboxKindCount, b: MailboxKindCount): MailboxKindC
 	};
 }
 
-function mailboxFrom(manifest: TeamRunManifest, agents: CrewAgentRecord[]): RunUiMailbox {
+function mailboxFrom(
+	manifest: TeamRunManifest,
+	agents: CrewAgentRecord[],
+	delivery: Record<string, MailboxMessageStatus>,
+	outboxTail: TailContent,
+): RunUiMailbox {
 	const root = path.join(manifest.stateRoot, "mailbox");
-	const delivery = readDeliveryMessages(path.join(root, "delivery.json"));
 	let inbox = readMailboxCounts(path.join(root, "inbox.jsonl"), delivery);
-	let outbox = readMailboxCounts(path.join(root, "outbox.jsonl"), delivery);
+	let outbox = mailboxCountsFrom(outboxTail, delivery);
 	const tasksRoot = path.join(root, "tasks");
 	try {
 		for (const entry of fs.readdirSync(tasksRoot, {
@@ -865,8 +894,14 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 			if (previous) return previous;
 			throw new Error(`Run '${runId}' could not be parsed.`);
 		}
-		const mailbox = mailboxFrom(loaded.manifest, agents);
-		const groupJoins = groupJoinsFrom(loaded.manifest);
+		// PERF (2026-08-24): mailboxFrom and groupJoinsFrom each parsed
+		// delivery.json and tailed outbox.jsonl — read both once here and
+		// thread the results into both consumers.
+		const mailboxRoot = path.join(loaded.manifest.stateRoot, "mailbox");
+		const delivery = readDeliveryMessages(path.join(mailboxRoot, "delivery.json"));
+		const outboxTail = readTailContent(path.join(mailboxRoot, "outbox.jsonl"));
+		const mailbox = mailboxFrom(loaded.manifest, agents, delivery, outboxTail);
+		const groupJoins = groupJoinsFrom(loaded.manifest, delivery, outboxTail);
 		const recentEvents = safeRecentEvents(loaded.manifest.eventsPath, recentEventsLimit);
 		const base = {
 			runId: loaded.manifest.runId,
@@ -1048,7 +1083,7 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 	}
 	const pendingRefreshes = new Map<string, ReturnType<typeof setTimeout>>();
 	const INVAL_COALESCE_MS = 80;
-	const scheduleRefresh = (runId: string): void => {
+	const scheduleCoalescedRefresh = (runId: string): void => {
 		const existing = pendingRefreshes.get(runId);
 		if (existing) clearTimeout(existing);
 		const timer = setTimeout(() => {
@@ -1062,10 +1097,10 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 		pendingRefreshes.set(runId, timer);
 	};
 	const unsubState = runEventBus.onChannel("run:state", (event) => {
-		if (entries.has(event.runId)) scheduleRefresh(event.runId);
+		if (entries.has(event.runId)) scheduleCoalescedRefresh(event.runId);
 	});
 	const unsubLifecycle = runEventBus.onChannel("worker:lifecycle", (event) => {
-		if (entries.has(event.runId)) scheduleRefresh(event.runId);
+		if (entries.has(event.runId)) scheduleCoalescedRefresh(event.runId);
 	});
 	const unsubscribe = () => {
 		unsubState();
@@ -1085,6 +1120,19 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 		refreshIfStale(runId: string): RunUiSnapshot {
 			return localRefreshIfStale(runId);
 		},
+		/**
+		 * PERF (2026-08-24): watcher-facing refresh. The fs.watch path used to
+		 * call the SYNC refresh() directly on every file event — a full
+		 * snapshot rebuild (manifest+tasks parse, agents.json, mailbox readdir,
+		 * per-agent tail reads, 2x stringify+sha256) many times per second,
+		 * blocking the UI event loop. This routes through the same 80ms
+		 * coalesced → async (preloadStale) pipeline the run event bus uses.
+		 * FLICKER FIX semantics preserved: buildAsync re-sets the entry in
+		 * place; nothing is deleted.
+		 */
+		scheduleRefresh(runId: string): void {
+			scheduleCoalescedRefresh(runId);
+		},
 		preloadStale,
 		preloadAllStale,
 		invalidate(runId?: string): void {