@linxiraos/pi-tui 1.1.27 → 1.2.0

package/src/overlays/agent-hub-projection.d.ts

@@ -15,11 +15,12 @@ interface AgentTreeProjection<TRecord extends AgentRecordLike> {
 export declare const STATUS_ORDER: Record<AgentStatus, number>;
 /** Exact observer usage for one roster entry. */
 export declare function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined;
-/** Live session whose own messages back a row's metrics when no observer progress exists. */
+/** Live session used to cache a row's direct assistant usage, including with observer progress. */
 export declare function hubFallbackStatsSession<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined): NonNullable<TRecord["session"]> | undefined;
 /**
- * One roster row's usage: live observer progress, then persisted history, then
- * the cached fallback read of a live session (populated by {@link aggregateMetrics}).
+ * Preserve progress/history for non-cost metrics, overlaying cumulative direct-session cost.
+ * Persisted `history.metrics.cost` is a leaf-scoped snapshot, so it never overrides live
+ * progress; only the cumulative direct-cost sources do.
  */
 export declare function hubRowMetrics<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined, sessionMetrics: WeakMap<object, {
     metrics: AgentMetrics | undefined;
@@ -37,6 +38,6 @@ export declare function aggregateMetrics<TRecord extends AgentRecordLike>(args:
     metrics: AggregateMetrics;
     hasFallbackLiveSessions: boolean;
 };
-/** Parent-before-child projection preserving the roster's stable sibling order. */
-export declare function projectAgentTree<TRecord extends AgentRecordLike>(refs: readonly TRecord[]): AgentTreeProjection<TRecord>;
+/** Parent-before-child projection preserving initial subtree rank and prepending new siblings. */
+export declare function projectAgentTree<TRecord extends AgentRecordLike>(refs: readonly TRecord[], rosterRank: ReadonlyMap<TRecord, number> | undefined): AgentTreeProjection<TRecord>;
 export {};

package/src/overlays/agent-hub-projection.ts

@@ -23,6 +23,68 @@ function finiteMetric(value: number | undefined): number {
 	return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+/** Message list a fallback metrics read was taken from; unchanged list ⇒ unchanged metrics. */
+interface FallbackReadStamp {
+	messages: readonly unknown[];
+	length: number;
+	last: unknown;
+	/** Usage and block count of the last message, which a streaming turn mutates in place. */
+	lastShape: string;
+	/** Session model, whose context window the context gauge reports. */
+	model: unknown;
+	contextWindow: number | null | undefined;
+}
+
+/** Stamp of each cached fallback read, keyed by the cache entry so it cannot outlive that read. */
+const fallbackReadStamps = new WeakMap<object, FallbackReadStamp>();
+
+function lastMessageShape(last: unknown): string {
+	if (!last || typeof last !== "object") return "";
+	const { usage, content } = last as {
+		usage?: { input?: number; output?: number; cacheWrite?: number; cost?: { total?: number } };
+		content?: unknown;
+	};
+	const blocks = Array.isArray(content) ? content.length : -1;
+	return `${usage?.input}:${usage?.output}:${usage?.cacheWrite}:${usage?.cost?.total}:${blocks}`;
+}
+
+function fallbackReadStamp(session: NonNullable<AgentRecordLike["session"]>): FallbackReadStamp | undefined {
+	try {
+		const messages = session.agent?.state?.messages;
+		if (!Array.isArray(messages)) return undefined;
+		const last = messages[messages.length - 1];
+		return {
+			messages,
+			length: messages.length,
+			last,
+			lastShape: lastMessageShape(last),
+			model: session.model,
+			contextWindow: session.model?.contextWindow,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Whether a cached fallback read still matches the session's message list
+ * (append, compaction, rewrite, streaming tail) and model (context window).
+ */
+function fallbackReadCurrent(entry: object, session: NonNullable<AgentRecordLike["session"]>): boolean {
+	const stamp = fallbackReadStamps.get(entry);
+	if (!stamp) return false;
+	const current = fallbackReadStamp(session);
+	return (
+		current !== undefined &&
+		current.messages === stamp.messages &&
+		current.length === stamp.length &&
+		current.last === stamp.last &&
+		current.lastShape === stamp.lastShape &&
+		current.model === stamp.model &&
+		current.contextWindow === stamp.contextWindow
+	);
+}
+
 /** Exact observer usage for one roster entry. */
 export function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined {
 	const progress = observed?.progress;
@@ -60,12 +122,33 @@ export function progressMetrics(observed: ObservableSession | undefined): AgentM
 	};
 }
 
+/** Lifetime cost from the authoritative session index, excluding task-result child billing. */
+function readSessionDirectCost(session: NonNullable<AgentRecordLike["session"]>): number | undefined {
+	try {
+		const usage = session.sessionManager?.getUsageStatistics();
+		if (
+			usage &&
+			Number.isFinite(usage.cost) &&
+			Number.isFinite(usage.subagentCost) &&
+			usage.cost >= usage.subagentCost
+		) {
+			return usage.cost - usage.subagentCost;
+		}
+	} catch {
+		// A session stopping during render may have already closed its stats host.
+	}
+	return undefined;
+}
+
 /**
  * Read direct assistant usage from a live session. SessionStats also includes
  * usage embedded in completed `task` tool results, so using it for a parent
  * row would double-count child rows in the aggregate.
  */
-function readSessionMetrics(session: NonNullable<AgentRecordLike["session"]>): AgentMetrics | undefined {
+function readSessionMetrics(
+	session: NonNullable<AgentRecordLike["session"]>,
+	directCost: number | undefined,
+): AgentMetrics | undefined {
 	try {
 		const stats = session.getSessionStats();
 		const messages = session.agent?.state?.messages;
@@ -74,7 +157,7 @@ function readSessionMetrics(session: NonNullable<AgentRecordLike["session"]>): A
 				tokens: stats.tokens.input + stats.tokens.output + stats.tokens.cacheWrite,
 				requests: stats.assistantMessages,
 				tools: stats.toolCalls,
-				cost: stats.cost,
+				cost: directCost ?? stats.cost,
 				durationMs: 0,
 				durationKind: "unknown",
 				contextTokens: stats.contextUsage?.tokens,
@@ -97,7 +180,7 @@ function readSessionMetrics(session: NonNullable<AgentRecordLike["session"]>): A
 			tokens,
 			requests,
 			tools,
-			cost,
+			cost: directCost ?? cost,
 			durationMs: 0,
 			durationKind: "unknown",
 			contextTokens: stats.contextUsage?.tokens,
@@ -110,29 +193,39 @@ function readSessionMetrics(session: NonNullable<AgentRecordLike["session"]>): A
 	}
 }
 
-/** Live session whose own messages back a row's metrics when no observer progress exists. */
+/** Live session used to cache a row's direct assistant usage, including with observer progress. */
 export function hubFallbackStatsSession<TRecord extends AgentRecordLike>(
 	ref: TRecord,
 	observed: ObservableSession | undefined,
 ): NonNullable<TRecord["session"]> | undefined {
-	if (observed?.progress) return undefined;
+	void observed;
 	const session = ref.session;
 	return session && typeof session.getSessionStats === "function" ? session : undefined;
 }
 
+function withDirectCost(metrics: AgentMetrics | undefined, cost: number | undefined): AgentMetrics | undefined {
+	return metrics && cost !== undefined ? { ...metrics, cost } : metrics;
+}
+
 /**
- * One roster row's usage: live observer progress, then persisted history, then
- * the cached fallback read of a live session (populated by {@link aggregateMetrics}).
+ * Preserve progress/history for non-cost metrics, overlaying cumulative direct-session cost.
+ * Persisted `history.metrics.cost` is a leaf-scoped snapshot, so it never overrides live
+ * progress; only the cumulative direct-cost sources do.
  */
 export function hubRowMetrics<TRecord extends AgentRecordLike>(
 	ref: TRecord,
 	observed: ObservableSession | undefined,
 	sessionMetrics: WeakMap<object, { metrics: AgentMetrics | undefined }>,
 ): AgentMetrics | undefined {
-	if (observed?.progress) return progressMetrics(observed);
-	if (ref.history?.metrics) return ref.history.metrics;
 	const session = hubFallbackStatsSession(ref, observed);
-	return session ? sessionMetrics.get(session)?.metrics : undefined;
+	const liveEntry = session ? sessionMetrics.get(session) : undefined;
+	const retainedEntry = sessionMetrics.get(ref);
+	const historyMetrics = ref.history?.metrics;
+	const cost = liveEntry?.metrics?.cost ?? ref.history?.directCost ?? retainedEntry?.metrics?.cost;
+	if (observed?.progress) return withDirectCost(progressMetrics(observed), cost);
+	if (historyMetrics) return withDirectCost(historyMetrics, cost);
+	if (!session && retainedEntry?.metrics) return withDirectCost(retainedEntry.metrics, cost);
+	return withDirectCost(liveEntry?.metrics, cost);
 }
 
 export function aggregateMetrics<TRecord extends AgentRecordLike>(args: {
@@ -163,9 +256,21 @@ export function aggregateMetrics<TRecord extends AgentRecordLike>(args: {
 		const fallbackSession = args.fallbackStatsSession(ref, observed);
 		if (fallbackSession) {
 			hasFallbackLiveSessions = true;
-			if (args.refreshFallback || !args.sessionMetrics.has(fallbackSession)) {
-				args.sessionMetrics.set(fallbackSession, { metrics: readSessionMetrics(fallbackSession) });
+			let cached = args.sessionMetrics.get(fallbackSession);
+			const directCost = readSessionDirectCost(fallbackSession);
+			// Refresh cost independently from the message scan: model_usage entries
+			// are cumulative but do not alter the agent's live message list.
+			if (!cached || (args.refreshFallback && !fallbackReadCurrent(cached, fallbackSession))) {
+				const stamp = fallbackReadStamp(fallbackSession);
+				const entry = { metrics: readSessionMetrics(fallbackSession, directCost) };
+				if (stamp) fallbackReadStamps.set(entry, stamp);
+				args.sessionMetrics.set(fallbackSession, entry);
+				cached = entry;
+			} else if (cached.metrics && directCost !== undefined) {
+				cached.metrics.cost = directCost;
 			}
+			// Preserve valid direct-session snapshots through parking or a failed teardown read.
+			if (cached.metrics) args.sessionMetrics.set(ref, cached);
 		}
 		const metrics = args.metricsFor(ref, observed);
 		if (!metrics || (fallbackSession && countedFallbackSessions.has(fallbackSession))) continue;
@@ -183,9 +288,10 @@ export function aggregateMetrics<TRecord extends AgentRecordLike>(args: {
 	return { metrics: total, hasFallbackLiveSessions };
 }
 
-/** Parent-before-child projection preserving the roster's stable sibling order. */
+/** Parent-before-child projection preserving initial subtree rank and prepending new siblings. */
 export function projectAgentTree<TRecord extends AgentRecordLike>(
 	refs: readonly TRecord[],
+	rosterRank: ReadonlyMap<TRecord, number> | undefined,
 ): AgentTreeProjection<TRecord> {
 	const ids = new Set<string>();
 	const operationalIndex = new Map<string, number>();
@@ -218,7 +324,12 @@ export function projectAgentTree<TRecord extends AgentRecordLike>(
 			if (!current) continue;
 			if (current.expanded) {
 				let order = operationalIndex.get(current.ref.id) ?? Number.MAX_SAFE_INTEGER;
+				const parentRank = rosterRank?.get(current.ref);
 				for (const child of children.get(current.ref.id) ?? []) {
+					const childRank = rosterRank?.get(child);
+					// A child spawned later cannot move an existing parent's group.
+					if (parentRank !== undefined && childRank !== undefined && childRank < 0 && childRank < parentRank)
+						continue;
 					order = Math.min(order, subtreeOrder.get(child.id) ?? Number.MAX_SAFE_INTEGER);
 				}
 				subtreeOrder.set(current.ref.id, order);

package/src/overlays/agent-hub-types.d.ts

@@ -28,6 +28,13 @@ export interface AgentHubSession {
             messages: AgentMessage[];
         };
     };
+    /** Existing session ledger includes off-transcript model usage and nested-task attribution. */
+    readonly sessionManager?: {
+        getUsageStatistics(): {
+            cost: number;
+            subagentCost: number;
+        };
+    };
     getSessionStats(): {
         tokens: {
             input: number;
@@ -64,6 +71,8 @@ export interface AgentRecordLike {
         resolvedModel?: string;
         resolvedModelIsFallback?: boolean;
         metrics?: AgentMetricsSummary;
+        /** Cumulative own-session assistant and model_usage cost, excluding nested task results. */
+        directCost?: number;
         readOnly?: boolean;
         outputPath?: string;
         patchPath?: string;

package/src/overlays/agent-hub-types.ts

@@ -22,6 +22,10 @@ export interface AgentHubSession {
 	readonly model: Model | undefined;
 	readonly servingModel?: { selector: string; isFallback: boolean };
 	readonly agent?: { state: { messages: AgentMessage[] } };
+	/** Existing session ledger includes off-transcript model usage and nested-task attribution. */
+	readonly sessionManager?: {
+		getUsageStatistics(): { cost: number; subagentCost: number };
+	};
 	getSessionStats(): {
 		tokens: { input: number; output: number; cacheWrite: number };
 		assistantMessages: number;
@@ -49,6 +53,8 @@ export interface AgentRecordLike {
 		resolvedModel?: string;
 		resolvedModelIsFallback?: boolean;
 		metrics?: AgentMetricsSummary;
+		/** Cumulative own-session assistant and model_usage cost, excluding nested task results. */
+		directCost?: number;
 		readOnly?: boolean;
 		outputPath?: string;
 		patchPath?: string;

package/src/overlays/agent-hub.ts

@@ -200,6 +200,12 @@ const DATA_CHANGE_RENDER_COALESCE_MS = 100;
 /** Double-tap window for the table's left-left "close hub" gesture. */
 const LEFT_TAP_WINDOW_MS = 500;
 
+function compareRosterAgents(a: AgentRecordLike, b: AgentRecordLike): number {
+	return (
+		STATUS_ORDER[a.status] - STATUS_ORDER[b.status] || b.lastActivity - a.lastActivity || a.id.localeCompare(b.id)
+	);
+}
+
 function activityGlyph(row: AgentActivityRow): string {
 	if (row.status === "error") return theme.fg("error", theme.status.error);
 	if (row.status === "aborted") return theme.fg("warning", theme.status.aborted);
@@ -358,11 +364,10 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 	#rows: TRecord[] = [];
 	#statusCounts: Record<AgentStatus, number> = { running: 0, idle: 0, parked: 0, aborted: 0 };
 	#selectedRow = 0;
-	/** Stable roster order captured on first refresh: keyboard navigation must
-	 *  not jump as agents heartbeat. Existing agent generations keep their rank
-	 *  while the hub is open; newly appearing generations append at the end. */
+	/** Initial status/recency rank stays fixed while open; new generations
+	 *  prepend without changing the relative order of existing rows. */
 	#rowOrder: Map<TRecord, number> | undefined;
-	#nextRowOrder = 0;
+	#nextNewRowOrder = 0;
 	#hoveredRow: number | null = null;
 	/** Per-render screen-line to agent-row map, shared by click and hover routing. */
 	#hitRows: Array<number | undefined> = [];
@@ -616,6 +621,11 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 		this.#lastLeftTap = Date.now();
 	}
 
+	/** Show `section`, as a slash-command deep link into an already-open hub does. */
+	showSection(section: AgentHubSection): void {
+		this.#switchSection(section);
+	}
+
 	/**
 	 * Open the fullscreen transcript viewer for an agent id (public for table Enter
 	 * and tests). Mounts {@link AgentTranscriptViewer} as a `fullscreen` overlay so it
@@ -941,12 +951,16 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 			return { ...item, depth, open: this.#childrenByParent.has(ref.id) ? true : undefined };
 		}
 		if (!metrics) return item;
+		// A running agent's active time ticks terminal-side from the age at send; a settled one
+		// is frozen text. Progress `durationMs` was current when its frame arrived, so age it to now
+		// — re-sending the stale value on every repaint rewinds Tern's clock. A first frame can
+		// report 0 ms, so a progress timestamp alone makes the row clockable.
+		const progressAt = observed?.progress ? observed.progressAt : undefined;
 		const facts: Record<string, string | number> = {
 			cost: formatCost(metrics.cost),
-			// A running agent's active time ticks terminal-side; a settled one is frozen text.
 			time:
-				ref.status === "running" && metrics.durationMs > 0
-					? metrics.durationMs
+				ref.status === "running" && (metrics.durationMs > 0 || progressAt !== undefined)
+					? metrics.durationMs + (progressAt === undefined ? 0 : Math.max(0, Date.now() - progressAt))
 					: formatDuration(metrics.durationMs),
 			req: metrics.requests,
 			tools: metrics.tools,
@@ -1519,35 +1533,35 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 		const refs = this.#registry.list().filter(ref => ref.id !== MAIN_AGENT_ID);
 		this.#observedById = new Map();
 		for (const session of this.#observers.getSessions()) this.#observedById.set(session.id, session);
-		// Stable roster order: capture the status+recency ranking once so keyboard
-		// navigation is not disrupted by heartbeats (issue #10524). Existing rows
-		// keep their rank while the hub is open; new agents append at the end.
-		// Defer the capture until persisted-subagent discovery settles so a
-		// mid-scan refresh cannot freeze a partial roster (the remaining agents
-		// would otherwise append in readdir order instead of being ranked).
+		// Capture the status+recency ranking once so keyboard navigation does
+		// not jump on heartbeats. Defer until persisted-subagent discovery
+		// settles so a partial roster is not frozen in readdir order.
 		const rowOrder = this.#rowOrder;
 		let ordered: TRecord[];
 		if (!rowOrder) {
-			ordered = refs.sort(
-				(a, b) =>
-					STATUS_ORDER[a.status] - STATUS_ORDER[b.status] ||
-					b.lastActivity - a.lastActivity ||
-					a.id.localeCompare(b.id),
-			);
+			ordered = refs.sort(compareRosterAgents);
 			if (!this.#loadingPersistedSubagents && ordered.length > 0) {
-				this.#rowOrder = new Map();
-				for (const ref of ordered) this.#rowOrder.set(ref, this.#nextRowOrder++);
+				const rowOrder = new Map<TRecord, number>();
+				for (const [index, ref] of ordered.entries()) rowOrder.set(ref, index);
+				this.#rowOrder = rowOrder;
 			}
 		} else {
 			for (const rankedRef of rowOrder.keys()) {
 				if (!refs.includes(rankedRef)) rowOrder.delete(rankedRef);
 			}
-			ordered = refs.sort(
-				(a, b) => (rowOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (rowOrder.get(b) ?? Number.MAX_SAFE_INTEGER),
-			);
-			for (const ref of ordered) {
-				if (!rowOrder.has(ref)) rowOrder.set(ref, this.#nextRowOrder++);
+			// Each batch of newly appearing generations uses the initial sort,
+			// then takes ranks above every agent already on screen.
+			let newcomers: TRecord[] | undefined;
+			for (const ref of refs) {
+				if (!rowOrder.has(ref)) (newcomers ??= []).push(ref);
+			}
+			if (newcomers) {
+				newcomers.sort(compareRosterAgents);
+				for (let i = newcomers.length - 1; i >= 0; i--) {
+					rowOrder.set(newcomers[i]!, --this.#nextNewRowOrder);
+				}
 			}
+			ordered = refs.sort((a, b) => rowOrder.get(a)! - rowOrder.get(b)!);
 		}
 		const query = this.#agentFilter.getValue().trim();
 		const rosterRows =
@@ -1556,7 +1570,7 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 				: ordered;
 
 		if (this.#viewMode === "tree") {
-			const tree = projectAgentTree(rosterRows);
+			const tree = projectAgentTree(rosterRows, rowOrder);
 			this.#rows = tree.rows;
 			this.#treeDepthById = tree.depthById;
 			this.#treeParentById = tree.parentById;
@@ -1589,7 +1603,8 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 		for (const ref of rosterRows) this.#statusCounts[ref.status]++;
 		this.#refreshAggregate();
 		this.#refreshActivityData(rosterRows);
-		this.#refreshActivityRows();
+		// The 2,000-row activity query only feeds the Activity tab; switching to it refreshes.
+		if (this.#section === "activity") this.#refreshActivityRows();
 	}
 
 	#refreshActivityData(refs: readonly TRecord[]): void {
@@ -1620,7 +1635,7 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 		void Promise.all(pending)
 			.then(() => {
 				if (this.#disposed || generation !== this.#activitySyncGeneration) return;
-				this.#refreshActivityRows();
+				if (this.#section === "activity") this.#refreshActivityRows();
 				this.#requestRender();
 			})
 			.catch(() => {

package/src/overlays/agent-transcript-viewer.ts

@@ -41,15 +41,22 @@ import { sanitizeErrorLine } from "../chrome/error-block";
 import type { ScrollRangeAnchor } from "../components/scroll-view";
 import { formatContextUsage } from "../chrome/context-thresholds";
 import { node, span, text } from "../native/describe";
-import type { DescribeContext, NativeChild, NativeNode } from "../native/node";
-import { actionHint, hintsRow, overlayCard } from "../native/overlay";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
+import { actionHint, escCloseButton, hintsRow, overlayCard } from "../native/overlay";
 
 /** Parsed message and model metadata relevant to a transcript viewer. */
 export type AgentTranscriptEntry = SessionMessageEntryLike | { type: "model_change"; model: string };
 
 /** Local filesystem and session parsing capabilities supplied by the host. */
 export interface AgentTranscriptSource {
-	fs: Pick<typeof fs, "openSync" | "closeSync" | "readSync" | "readFileSync" | "statSync">;
+	/**
+	 * Sync primitives drive the first paint and the incremental tail. When the
+	 * host also supplies `promises.readFile` (e.g. passes `node:fs` itself), full
+	 * reloads after rotation/rewrite read the file off the UI thread.
+	 */
+	fs: Pick<typeof fs, "openSync" | "closeSync" | "readSync" | "readFileSync" | "statSync"> & {
+		promises?: Pick<typeof fs.promises, "readFile">;
+	};
 	parseEntries(text: string): AgentTranscriptEntry[];
 }
 
@@ -86,6 +93,8 @@ export interface AgentTranscriptViewerDeps {
 
 /** How often to re-stat a file-backed transcript for growth (advisor/live tail). */
 const POLL_MS = 250;
+/** Every Nth idle poll re-verifies sentinels, catching same-size/mtime rewrites. */
+const IDLE_SENTINEL_CHECK_EVERY = 5;
 
 const SENTINEL_BYTES = 4096;
 
@@ -183,6 +192,10 @@ export class AgentTranscriptViewer implements Component {
 	#model: string | undefined;
 	#pollTimer: NodeJS.Timeout | undefined;
 	#disposed = false;
+	/** Async full reload in flight; polls are skipped until it lands. */
+	#localLoadInFlight = false;
+	/** Idle polls since the sentinels were last verified. */
+	#idlePolls = 0;
 	#initialEntryId: string | undefined;
 	/** Last described node and the visible inputs it was built from. */
 	#nativeCache: { signature: string; node: NativeNode } | undefined;
@@ -201,6 +214,8 @@ export class AgentTranscriptViewer implements Component {
 			hideThinkingBlock: deps.hideThinkingBlock,
 			proseOnlyThinking: deps.proseOnlyThinking,
 			expandThinkingBlocks: deps.expandThinkingBlocks,
+			// Charts are for the main session's answers, not parked subagent, advisor, or guest transcripts.
+			tableCharts: false,
 			requestRender: deps.requestRender,
 		});
 		this.#browser = new TranscriptBrowser({
@@ -213,8 +228,10 @@ export class AgentTranscriptViewer implements Component {
 			this.#editor.setMaxHeight(4);
 			this.#editor.onSubmit = text => this.#submit(text);
 		}
-		this.#refresh();
-		this.#pollTimer = setInterval(() => this.#refresh(), POLL_MS);
+		// First paint loads synchronously so the initial entry can be revealed
+		// immediately; later full reloads from the poll may go async.
+		this.#refresh(false);
+		this.#pollTimer = setInterval(() => this.#refresh(true), POLL_MS);
 		this.#pollTimer.unref?.();
 	}
 
@@ -243,12 +260,13 @@ export class AgentTranscriptViewer implements Component {
 	// ========================================================================
 
 	/** Refresh the transcript from a local file or remote host. */
-	#refresh(): void {
+	#refresh(allowAsync: boolean): void {
 		if (this.#disposed) return;
 		if (this.#deps.remote) {
 			this.#fetchRemote();
 			return;
 		}
+		if (this.#localLoadInFlight) return;
 		const sessionFile = this.#deps.registry.get(this.#deps.agentId)?.sessionFile;
 		if (!sessionFile) {
 			this.#clearLocal("none");
@@ -262,14 +280,29 @@ export class AgentTranscriptViewer implements Component {
 			return;
 		}
 		const state = this.#localState;
-		if (state && this.#canAppendLocal(sessionFile, stat, state)) {
-			if (stat.size === state.size && stat.mtimeMs === state.mtimeMs) return;
-			if (stat.size > state.size) {
-				this.#appendLocal(sessionFile, stat, state);
+		if (state) {
+			// Idle fast path: an unchanged identity/size/mtime costs one stat;
+			// sentinels are re-read only every Nth idle poll so a rewrite that
+			// keeps size and mtime is still noticed.
+			if (
+				state.path === sessionFile &&
+				state.dev === stat.dev &&
+				state.ino === stat.ino &&
+				stat.size === state.size &&
+				stat.mtimeMs === state.mtimeMs
+			) {
+				if (++this.#idlePolls < IDLE_SENTINEL_CHECK_EVERY) return;
+				this.#idlePolls = 0;
+				if (this.#canAppendLocal(sessionFile, stat, state)) return;
+				this.#loadLocalFull(sessionFile, stat, allowAsync);
+				return;
+			}
+			if (stat.size > state.size && this.#canAppendLocal(sessionFile, stat, state)) {
+				this.#appendLocal(sessionFile, stat, state, allowAsync);
 				return;
 			}
 		}
-		this.#loadLocalFull(sessionFile, stat);
+		this.#loadLocalFull(sessionFile, stat, allowAsync);
 	}
 
 	#clearLocal(reason: string): void {
@@ -303,7 +336,23 @@ export class AgentTranscriptViewer implements Component {
 		return true;
 	}
 
-	#loadLocalFull(sessionFile: string, stat: fs.Stats): void {
+	#loadLocalFull(sessionFile: string, stat: fs.Stats, allowAsync: boolean): void {
+		const promises = allowAsync ? this.#deps.transcript.fs.promises : undefined;
+		if (promises) {
+			this.#localLoadInFlight = true;
+			void promises
+				.readFile(sessionFile)
+				.then(data => {
+					this.#localLoadInFlight = false;
+					if (!this.#disposed) this.#applyLocalFull(sessionFile, stat, data);
+				})
+				.catch((err: unknown) => {
+					// Leave #localState unchanged so a transient read error retries next poll.
+					this.#localLoadInFlight = false;
+					logger.debug("transcript viewer: read failed", { err: String(err) });
+				});
+			return;
+		}
 		let data: Buffer;
 		try {
 			data = this.#deps.transcript.fs.readFileSync(sessionFile);
@@ -312,6 +361,10 @@ export class AgentTranscriptViewer implements Component {
 			logger.debug("transcript viewer: read failed", { err: String(err) });
 			return;
 		}
+		this.#applyLocalFull(sessionFile, stat, data);
+	}
+
+	#applyLocalFull(sessionFile: string, stat: fs.Stats, data: Buffer): void {
 		// The file may have grown between the earlier `statSync` and this read.
 		// Anchor the tail cursor to what we actually consumed so the next poll's
 		// `#appendLocal` never re-renders bytes already in the rebuilt transcript;
@@ -345,7 +398,7 @@ export class AgentTranscriptViewer implements Component {
 		this.#rebuild(this.#extractMessages(this.#deps.transcript.parseEntries(complete)));
 	}
 
-	#appendLocal(sessionFile: string, stat: fs.Stats, state: LocalTranscriptState): void {
+	#appendLocal(sessionFile: string, stat: fs.Stats, state: LocalTranscriptState, allowAsync: boolean): void {
 		let chunk: string;
 		try {
 			chunk = readFileRangeSync(
@@ -356,7 +409,7 @@ export class AgentTranscriptViewer implements Component {
 			).toString("utf-8");
 		} catch (err) {
 			logger.debug("transcript viewer: tail read failed", { err: String(err) });
-			this.#loadLocalFull(sessionFile, stat);
+			this.#loadLocalFull(sessionFile, stat, allowAsync);
 			return;
 		}
 		const combined = state.pending + chunk;
@@ -371,7 +424,7 @@ export class AgentTranscriptViewer implements Component {
 			// File unlinked/rotated mid-poll: fall back to a guarded full reload
 			// instead of letting the open escape the poll timer.
 			logger.debug("transcript viewer: sentinel recompute failed", { err: String(err) });
-			this.#loadLocalFull(sessionFile, stat);
+			this.#loadLocalFull(sessionFile, stat, allowAsync);
 			return;
 		}
 		this.#localState = {
@@ -506,12 +559,7 @@ export class AgentTranscriptViewer implements Component {
 		}
 
 		if (matchesKey(data, "escape")) {
-			if (this.#editor && this.#editor.getText().trim() !== "") {
-				this.#editor.setText("");
-				this.#deps.requestRender();
-				return;
-			}
-			this.#deps.onClose();
+			this.#escape();
 			return;
 		}
 
@@ -594,6 +642,21 @@ export class AgentTranscriptViewer implements Component {
 		return lines;
 	}
 
+	/** The top-right `esc` runs Esc. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "close") this.#escape();
+	}
+
+	/** Esc: clear a non-empty draft first, else close the viewer. */
+	#escape(): void {
+		if (this.#editor && this.#editor.getText().trim() !== "") {
+			this.#editor.setText("");
+			this.#deps.requestRender();
+			return;
+		}
+		this.#deps.onClose();
+	}
+
 	/**
 	 * Header, transcript body (the builder's container, which describes its own
 	 * blocks), notice, message editor, stats and key hints. Scrolling is the
@@ -622,6 +685,8 @@ export class AgentTranscriptViewer implements Component {
 
 		const id = this.#deps.agentId;
 		const children: NativeChild[] = [];
+		// Top row: the agent's meta on the left, a clickable `esc` (close) on the right.
+		const top: NativeChild[] = [];
 		if (ref) {
 			const kindTag = ref.parentId ? `${ref.kind} ${theme.sep.dot} of ${ref.parentId}` : ref.kind;
 			const meta: NativeChild[] = [
@@ -630,8 +695,12 @@ export class AgentTranscriptViewer implements Component {
 				text([span(kindTag, "dim")], { truncate: "end" }),
 			];
 			if (this.#model) meta.push(text([span(this.#model, "muted")], { truncate: "end" }));
-			children.push(node("row", { gap: "sm", align: "center" }, meta, "meta"));
+			top.push(node("row", { gap: "sm", align: "center", grow: 1, min: { w: 0 } }, meta, "meta"));
+		} else {
+			top.push(node("spacer", { grow: 1 }));
 		}
+		top.push(escCloseButton());
+		children.push(node("row", { gap: "md", align: "center" }, top, "top"));
 		children.push(
 			placeholder === undefined
 				? node("col", { grow: 1 }, [this.#builder.container], "transcript")
@@ -694,7 +763,6 @@ export class AgentTranscriptViewer implements Component {
 		children.push(
 			hintsRow([
 				this.#editor ? actionHint("tui.input.submit", "send") : undefined,
-				{ keys: ["escape"], label: "close" },
 				{ keys: [this.#deps.expandKeys[0] ?? "ctrl+o"], label: "expand" },
 			]),
 		);