@oh-my-pi/pi-tui 18.8.2 → 18.8.4

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [18.8.4] - 2026-10-08
+
+### Changed
+
+- Agent Hub keeps existing agents in place while open; new agents appear first in the flat roster or within their tree sibling group ([#13066](https://github.com/can1357/oh-my-pi/pull/13066) by [@kmccleary3301](https://github.com/kmccleary3301))
+
+### Fixed
+
+- Fixed relative file links in Tern assistant replies opening against the folder omp was started in; they now open the file in the session's working directory ([#14879](https://github.com/can1357/oh-my-pi/pull/14879) by [@H4vC](https://github.com/H4vC))
+- Fixed Tern modals with no clickable exit: BTW history, git shortcuts and autoresearch gain a Close button, plan review a Cancel button, the agent transcript viewer and `/annotate` review a top-right `esc` that runs Esc, and the `/move` dialog Accept, Cancel and Confirm buttons; new `escCloseButton()` builds the `esc` keycap button ([#14894](https://github.com/can1357/oh-my-pi/pull/14894) by [@H4vC](https://github.com/H4vC))
+
 ## [18.8.2] - 2026-10-07
 
 ### Removed

package/dist/types/apps/git/help.d.ts

@@ -1,4 +1,4 @@
-import type { NativeNode } from "../../native/node.js";
+import type { NativeNode, NativeUiEvent } from "../../native/node.js";
 import type { Component } from "../../tui.js";
 /** The shortcuts overlay; any of `?`, escape or `q` closes it. */
 export declare class GitHelpSheet implements Component {
@@ -10,6 +10,8 @@ export declare class GitHelpSheet implements Component {
     };
     constructor(close: () => void);
     handleInput(data: string): void;
+    /** Close runs what Esc runs. */
+    handleNativeEvent(event: NativeUiEvent): void;
     describe(): NativeNode;
     render(width: number): readonly string[];
     invalidate(): void;

package/dist/types/components/markdown.d.ts

@@ -33,6 +33,17 @@ export interface MarkdownLink {
  * Duplicate hrefs are kept; callers decide how to fold them.
  */
 export declare function extractMarkdownLinks(text: string): MarkdownLink[];
+/**
+ * Rewrite the destinations of inline links and link reference definitions in
+ * `text` to `resolve(href)`, leaving everything else byte-for-byte intact.
+ * Hosts that render the Markdown source themselves (a native terminal's `md`
+ * node) resolve relative destinations against their own idea of the working
+ * directory; handing them the session-resolved target keeps links pointing at
+ * what the author meant. Links inside code, images, autolinks and reference
+ * uses (`[x][ref]`, rewritten through their definition) are untouched; a link
+ * whose source cannot be located exactly is left as written.
+ */
+export declare function rewriteMarkdownLinkDestinations(text: string, resolve: (href: string) => string | undefined): string;
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export declare function clearRenderCache(): void;
 /**

package/dist/types/native/overlay.d.ts

@@ -58,6 +58,11 @@ export interface ActionButtonOptions {
  * which the component routes to the same code path as the key.
  */
 export declare function actionButton(label: string, act: string, options?: ActionButtonOptions): NativeNode;
+/**
+ * A bare `esc` keycap button for a view's top-right corner: a click sends
+ * `act` (default `close`), which the component routes to its Esc path.
+ */
+export declare function escCloseButton(act?: string, key?: string): NativeNode;
 /** A row of {@link actionButton}s (role `omp.actions`); `null` entries become the spacer that end-aligns what follows. */
 export declare function actionBar(buttons: readonly (NativeNode | null)[], key?: string): NativeNode;
 /** Spans of an annotation callout: a dim `label:` then the note. */

package/dist/types/overlays/agent-hub-projection.d.ts

@@ -37,6 +37,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/dist/types/overlays/agent-hub.d.ts

@@ -114,6 +114,8 @@ export declare class AgentHubOverlayComponent<TRecord extends AgentRecordLike =
      * was raised by that gesture.
      */
     armCloseTap(): void;
+    /** Show `section`, as a slash-command deep link into an already-open hub does. */
+    showSection(section: AgentHubSection): void;
     /**
      * Open the fullscreen transcript viewer for an agent id (public for table Enter
      * and tests). Mounts {@link AgentTranscriptViewer} as a `fullscreen` overlay so it

package/dist/types/overlays/agent-transcript-viewer.d.ts

@@ -23,7 +23,7 @@ import type { AgentHubRegistry } from "./agent-hub-types.js";
 import type { SessionMessageEntryLike } from "../chat/transcript-entry.js";
 import type { SessionObserverRegistry } from "./session-observer-registry.js";
 import type { AgentHubRemote } from "./agent-hub.js";
-import type { DescribeContext, NativeNode } from "../native/node.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** Parsed message and model metadata relevant to a transcript viewer. */
 export type AgentTranscriptEntry = SessionMessageEntryLike | {
     type: "model_change";
@@ -77,6 +77,8 @@ export declare class AgentTranscriptViewer implements Component {
     dispose(): void;
     handleInput(data: string): void;
     render(width: number): readonly string[];
+    /** The top-right `esc` runs Esc. */
+    handleNativeEvent(event: NativeUiEvent): void;
     /**
      * Header, transcript body (the builder's container, which describes its own
      * blocks), notice, message editor, stats and key hints. Scrolling is the

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.8.2",
+	"version": "18.8.4",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -41,14 +41,14 @@
 		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.8.2",
-		"@oh-my-pi/pi-agent-core": "18.8.2",
-		"@oh-my-pi/pi-ai": "18.8.2",
-		"@oh-my-pi/pi-catalog": "18.8.2",
-		"@oh-my-pi/pi-natives": "18.8.2",
-		"@oh-my-pi/pi-utils": "18.8.2",
-		"@oh-my-pi/pi-wire": "18.8.2",
-		"@oh-my-pi/snapcompact": "18.8.2"
+		"@oh-my-pi/omptype": "18.8.4",
+		"@oh-my-pi/pi-agent-core": "18.8.4",
+		"@oh-my-pi/pi-ai": "18.8.4",
+		"@oh-my-pi/pi-catalog": "18.8.4",
+		"@oh-my-pi/pi-natives": "18.8.4",
+		"@oh-my-pi/pi-utils": "18.8.4",
+		"@oh-my-pi/pi-wire": "18.8.4",
+		"@oh-my-pi/snapcompact": "18.8.4"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/apps/autoresearch-dashboard.ts

@@ -17,8 +17,8 @@ import {
 import { formatNum, type ExperimentResult, type ExperimentState } from "../tools/autoresearch";
 import type { TspSpan, TspTableColumn, TspText } from "@oh-my-pi/pi-wire";
 import { card, col, elapsed, keyed, node, row, span, text } from "../native/describe";
-import type { DescribeContext, NativeNode } from "../native/node";
-import { hintsRow } from "../native/overlay";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node";
+import { actionBar, actionButton, hintsRow } from "../native/overlay";
 import { Memo } from "../native/memo";
 import { isNativeRendering } from "../native/state";
 
@@ -190,9 +190,9 @@ export function createDashboardController(): DashboardController {
 											{ keys: ["up", "down", "j", "k"], label: "scroll" },
 											{ keys: ["pageUp", "pageDown"], label: "page" },
 											{ keys: ["g", "shift+g"], label: "top/bottom" },
-											{ keys: ["escape"], label: "close" },
 										]),
 									);
+									children.push(actionBar([null, actionButton("Close", "close", { keys: "escape" })]));
 									return col(children, { gap: "md", role: "omp.app.autoresearch" });
 								},
 							);
@@ -214,6 +214,10 @@ export function createDashboardController(): DashboardController {
 							scrollView.setHeight(viewportRows);
 							return [header, ...scrollView.render(width), renderOverlayFooter(width, theme)];
 						},
+						/** The Close button runs Esc's path. */
+						handleNativeEvent(event: NativeUiEvent): void {
+							if (event.type === "action" && event.act === "close") done(undefined);
+						},
 						handleInput(data: string): void {
 							if (matchesKey(data, "escape") || matchesKey(data, "esc") || data === "q") {
 								done(undefined);

package/src/apps/git/help.ts

@@ -11,7 +11,8 @@ import { formatKeyHint } from "../../app-keybindings";
 import type { KeyName } from "../../key-hint-format";
 import { matchesKey } from "../../keys";
 import { col, node, span } from "../../native/describe";
-import type { NativeNode } from "../../native/node";
+import type { NativeNode, NativeUiEvent } from "../../native/node";
+import { actionBar, actionButton } from "../../native/overlay";
 import { theme } from "../../theme/theme";
 import type { Component } from "../../tui";
 import { truncateToWidth, visibleWidth } from "../../utils";
@@ -79,28 +80,36 @@ export class GitHelpSheet implements Component {
 		if (data === "?" || data === "q" || matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) this.#close();
 	}
 
+	/** Close runs what Esc runs. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "close") this.#close();
+	}
+
 	describe(): NativeNode {
 		this.#native ??= col(
-			GROUPS.map(group =>
-				node(
-					"section",
-					{ head: group.title, role: "omp.hotkeys.group" },
-					[
-						node("table", {
-							role: "omp.hotkeys.table",
-							cols: [
-								{ id: "keys", head: "Keys" },
-								{ id: "does", head: "Action", grow: 1 },
-							],
-							rows: group.rows.map((row, index) => ({
-								id: String(index),
-								cells: { keys: row.keys.map(key => span(formatKeyHint(key), "key")), does: row.label },
-							})),
-						}),
-					],
-					group.title,
+			[
+				...GROUPS.map(group =>
+					node(
+						"section",
+						{ head: group.title, role: "omp.hotkeys.group" },
+						[
+							node("table", {
+								role: "omp.hotkeys.table",
+								cols: [
+									{ id: "keys", head: "Keys" },
+									{ id: "does", head: "Action", grow: 1 },
+								],
+								rows: group.rows.map((row, index) => ({
+									id: String(index),
+									cells: { keys: row.keys.map(key => span(formatKeyHint(key), "key")), does: row.label },
+								})),
+							}),
+						],
+						group.title,
+					),
 				),
-			),
+				actionBar([null, actionButton("Close", "close", { keys: "escape" })]),
+			],
 			{ gap: "lg", role: "omp.app.git.help" },
 		);
 		return this.#native;

package/src/chat/assistant-message.ts

@@ -2,7 +2,7 @@ import type { AssistantMessage, ImageContent, TextContent } from "@oh-my-pi/pi-a
 import { type Component, Container } from "../tui";
 import { Image, type ImageBudget } from "../components/image";
 import { ImageProtocol, TERMINAL } from "../terminal-capabilities";
-import { Markdown, type MarkdownTheme } from "../components/markdown";
+import { Markdown, type MarkdownTheme, rewriteMarkdownLinkDestinations } from "../components/markdown";
 import { Spacer } from "../components/spacer";
 import { Text } from "../components/text";
 import { formatDuration, formatNumber } from "@oh-my-pi/pi-utils";
@@ -364,6 +364,8 @@ export class AssistantMessageComponent extends Container {
 	#textColorTransform?: (text: string) => string;
 	#linkTargets: ReadonlyMap<string, string> = EMPTY_LINK_TARGETS;
 	#markdownTheme: MarkdownTheme | undefined;
+	/** Text-block sources with {@link #linkTargets} applied, for the native `md` nodes; reset with the targets. */
+	#nativeLinkSources = new Map<string, string>();
 	/** Block this reply reacts to; undefined when the preceding block takes no reactions. */
 	#reactionTarget: ReactionTarget | undefined;
 	/** Reaction lifted from the reply's opening emoji, once resolved. */
@@ -415,6 +417,8 @@ export class AssistantMessageComponent extends Container {
 		this.#fastPathKey = undefined;
 		this.#fastPathItems = undefined;
 		for (const block of this.#figureBlocks.values()) block.restyle();
+		this.#nativeLinkSources.clear();
+		this.#nativeViewVersion++;
 		if (this.#lastMessage) {
 			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
 		}
@@ -842,8 +846,20 @@ export class AssistantMessageComponent extends Container {
 				const streaming = live && index === tailIndex;
 				if (content.type === "text" && canonicalizeMessage(content.text)) {
 					const source = content.text.trim();
+					// The terminal renders this source itself and would resolve a relative
+					// link against its own idea of the cwd: hand it the session-resolved
+					// targets (resolved once the segment closes, so never while streaming).
+					const linked = (text: string, live: boolean): string => {
+						if (live || this.#linkTargets.size === 0) return text;
+						const targets = this.#linkTargets;
+						const resolved =
+							this.#nativeLinkSources.get(text) ??
+							rewriteMarkdownLinkDestinations(text, href => targets.get(href));
+						this.#nativeLinkSources.set(text, resolved);
+						return resolved;
+					};
 					if (!this.#showImages || !this.#showTableCharts || !hasChartTable(source)) {
-						children.push(markdown(`t${index}`, `t${index}`, source, streaming));
+						children.push(markdown(`t${index}`, `t${index}`, linked(source, streaming), streaming));
 						continue;
 					}
 					// A chart follows its table as an SVG image node; the prose splits around it.
@@ -851,9 +867,8 @@ export class AssistantMessageComponent extends Container {
 					segments.forEach((segment, part) => {
 						const slot = part === 0 ? `t${index}` : `t${index}.${part}`;
 						if (segment.kind === "markdown") {
-							children.push(
-								markdown(slot, slot, segment.text.trim(), streaming && part === segments.length - 1),
-							);
+							const live = streaming && part === segments.length - 1;
+							children.push(markdown(slot, slot, linked(segment.text.trim(), live), live));
 							return;
 						}
 						const chart = lookupTableChart(segment.table);

package/src/components/markdown.ts

@@ -1173,6 +1173,120 @@ export function extractMarkdownLinks(text: string): MarkdownLink[] {
 	return links;
 }
 
+/**
+ * Offset just past the destination that starts at or after `start` in `raw`
+ * (CommonMark link destination grammar), plus where it begins. `null` when no
+ * destination is there.
+ */
+function scanLinkDestination(raw: string, start: number): { start: number; end: number } | null {
+	let i = start;
+	while (i < raw.length && (raw[i] === " " || raw[i] === "\t" || raw[i] === "\n" || raw[i] === "\r")) i++;
+	if (i >= raw.length) return null;
+	if (raw[i] === "<") {
+		for (let j = i + 1; j < raw.length; j++) {
+			if (raw[j] === "\\") j++;
+			else if (raw[j] === ">") return { start: i, end: j + 1 };
+			else if (raw[j] === "<" || raw[j] === "\n") return null;
+		}
+		return null;
+	}
+	let depth = 0;
+	let j = i;
+	for (; j < raw.length; j++) {
+		const ch = raw[j]!;
+		if (ch === "\\") {
+			j++;
+			continue;
+		}
+		if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch.charCodeAt(0) < 0x20) break;
+		if (ch === "(") depth++;
+		else if (ch === ")") {
+			if (depth === 0) break;
+			depth--;
+		}
+	}
+	return j > i ? { start: i, end: j } : null;
+}
+
+/** A destination that stays one destination whatever bytes the target holds. */
+function formatLinkDestination(target: string): string {
+	return /[\s()<>\\]/.test(target) ? `<${target.replaceAll(/[<>\\]/g, ch => encodeURIComponent(ch))}>` : target;
+}
+
+function isListToken(token: Token): token is Tokens.List {
+	return token.type === "list";
+}
+
+function isTableToken(token: Token): token is Tokens.Table {
+	return token.type === "table";
+}
+
+/**
+ * Rewrite the destinations of inline links and link reference definitions in
+ * `text` to `resolve(href)`, leaving everything else byte-for-byte intact.
+ * Hosts that render the Markdown source themselves (a native terminal's `md`
+ * node) resolve relative destinations against their own idea of the working
+ * directory; handing them the session-resolved target keeps links pointing at
+ * what the author meant. Links inside code, images, autolinks and reference
+ * uses (`[x][ref]`, rewritten through their definition) are untouched; a link
+ * whose source cannot be located exactly is left as written.
+ */
+export function rewriteMarkdownLinkDestinations(text: string, resolve: (href: string) => string | undefined): string {
+	const edits: Array<{ start: number; end: number; target: string }> = [];
+	let cursor = 0;
+	const rewrite = (token: Token, labelEnd: number | undefined): void => {
+		const at = text.indexOf(token.raw, cursor);
+		if (at < 0) return;
+		cursor = at + token.raw.length;
+		const href = "href" in token && typeof token.href === "string" ? token.href : "";
+		if (!href || labelEnd === undefined) return;
+		const target = resolve(href);
+		if (!target || target === href) return;
+		const dest = scanLinkDestination(token.raw, labelEnd);
+		if (dest) edits.push({ start: at + dest.start, end: at + dest.end, target });
+	};
+	const walk = (tokens: readonly Token[] | undefined): void => {
+		if (!tokens) return;
+		for (const token of tokens) {
+			if (token.type === "link") {
+				const label = "text" in token && typeof token.text === "string" ? `[${token.text}](` : undefined;
+				rewrite(token, label && token.raw.startsWith(label) ? label.length : undefined);
+				continue;
+			}
+			if (token.type === "def") {
+				const close = token.raw.indexOf("]:");
+				rewrite(token, close < 0 ? undefined : close + 2);
+				continue;
+			}
+			const children = "tokens" in token && Array.isArray(token.tokens) ? token.tokens : undefined;
+			const items = isListToken(token) ? token.items : undefined;
+			const table = isTableToken(token) ? token : undefined;
+			if (token.type === "image" || (!children && !items && !table)) {
+				// A leaf (text, code span, fenced code, html, image…): step past it so a
+				// later link's source is never matched inside it.
+				const at = token.raw ? text.indexOf(token.raw, cursor) : -1;
+				if (at >= 0) cursor = at + token.raw.length;
+				continue;
+			}
+			walk(children);
+			walk(items);
+			if (table) {
+				for (const cell of table.header) walk(cell.tokens);
+				for (const row of table.rows) for (const cell of row) walk(cell.tokens);
+			}
+		}
+	};
+	walk(markdownParser.lexer(text));
+	if (edits.length === 0) return text;
+	let out = "";
+	let last = 0;
+	for (const edit of edits) {
+		out += text.slice(last, edit.start) + formatLinkDestination(edit.target);
+		last = edit.end;
+	}
+	return out + text.slice(last);
+}
+
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export function clearRenderCache(): void {
 	renderCache.clear();

package/src/native/overlay.ts

@@ -119,6 +119,19 @@ export function actionButton(label: string, act: string, options: ActionButtonOp
 	);
 }
 
+/**
+ * A bare `esc` keycap button for a view's top-right corner: a click sends
+ * `act` (default `close`), which the component routes to its Esc path.
+ */
+export function escCloseButton(act = "close", key = "esc-close"): NativeNode {
+	return node(
+		"row",
+		{ role: "omp.btn", align: "center", actions: { click: act }, title: `Close  ${formatTooltipKey("escape")}` },
+		[kbd("escape")],
+		key,
+	);
+}
+
 /** A row of {@link actionButton}s (role `omp.actions`); `null` entries become the spacer that end-aligns what follows. */
 export function actionBar(buttons: readonly (NativeNode | null)[], key = "actions"): NativeNode {
 	const children = buttons.map(button => button ?? node("spacer", { grow: 1 }));

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

@@ -251,9 +251,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>();
@@ -286,7 +287,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.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
@@ -1519,35 +1529,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 +1566,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;

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

@@ -41,8 +41,8 @@ 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 };
@@ -559,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;
 		}
 
@@ -647,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
@@ -675,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[] = [
@@ -683,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")
@@ -747,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" },
 			]),
 		);

package/src/overlays/annotation-overlay.ts

@@ -42,7 +42,15 @@ import { matchesAppExternalEditor } from "../keybinding-matchers";
 import type { KeyName } from "../key-hint-format";
 import { item, keyed, node, row as rowNode, span, text } from "../native/describe";
 import { leafKey, type NativeChild, type NativeNode, type NativeUiEvent } from "../native/node";
-import { hintsRow, itemIndex, type NativeHint, noteSpans, overlayCard, selectList } from "../native/overlay";
+import {
+	escCloseButton,
+	hintsRow,
+	itemIndex,
+	type NativeHint,
+	noteSpans,
+	overlayCard,
+	selectList,
+} from "../native/overlay";
 
 function fit(text: string, width: number): string {
 	if (width <= 0) return "";
@@ -317,7 +325,7 @@ export class AnnotationOverlay implements Focusable {
 			return;
 		}
 		if (this.#keybindings.matches(data, "tui.select.cancel")) {
-			this.#finish(undefined);
+			this.#escape();
 			return;
 		}
 		if (data === "A" && (this.#focus === "files" || this.#focus === "diff")) {
@@ -369,6 +377,13 @@ export class AnnotationOverlay implements Focusable {
 		}
 	}
 
+	/** Esc, by state: leave the note chooser, drop the note draft, else close the review. */
+	#escape(): void {
+		if (this.#annotationChooser) this.#annotationChooser = undefined;
+		else if (this.#annotating) this.#cancelAnnotation();
+		else this.#finish(undefined);
+	}
+
 	#cycleFocus(direction: number): void {
 		const regions: FocusRegion[] = this.#sidebarShown ? ["files", "diff", "actions"] : ["diff", "actions"];
 		const current = regions.indexOf(this.#focus);
@@ -1263,7 +1278,10 @@ export class AnnotationOverlay implements Focusable {
 			role: this.#textSource ? "omp.overlay.annotateText.lines" : "omp.overlay.codeReview.diff",
 			tone: this.#focus === "diff" ? "accent" : undefined,
 		});
-		const main = node("col", { grow: 1 }, [this.#describeHeader(), lines], "main");
+		// The header row ends in a clickable `esc` at the top right.
+		const title = node("col", { grow: 1, min: { w: 0 } }, [this.#describeHeader()], "title");
+		const head = keyed(rowNode([title, escCloseButton()], { gap: "md", align: "center" }), "head");
+		const main = node("col", { grow: 1 }, [head, lines], "main");
 		if (this.#sidebarShown) {
 			const files = selectList(
 				"files",
@@ -1312,6 +1330,10 @@ export class AnnotationOverlay implements Focusable {
 
 	handleNativeEvent(event: NativeUiEvent): void {
 		if (this.#finished || this.#externalOperation) return;
+		if (event.type === "action" && event.act === "close") {
+			this.#escape();
+			return;
+		}
 		if (event.type !== "select" && event.type !== "activate") return;
 		const activate = event.type === "activate";
 		const leaf = leafKey(event.key);

package/src/overlays/btw-history-panel.ts

@@ -37,7 +37,7 @@ import { clampSelection, contentRowWidth, padLinesToHeight, renderScrollableList
 import type { TspScrollBy, TspSpan } from "@oh-my-pi/pi-wire";
 import type { NativeChild, NativeNode, NativeScroll, NativeUiEvent } from "../native/node";
 import { col, md, node, span, text } from "../native/describe";
-import { actionHint, hintsRow, type NativeHint, statusHintsRow } from "../native/overlay";
+import { actionBar, actionButton, actionHint, hintsRow, type NativeHint, statusHintsRow } from "../native/overlay";
 
 interface BtwHistoryPanelOptions {
 	records: readonly BtwHistoryRecord[];
@@ -485,6 +485,13 @@ export class BtwHistoryPanel implements Component, Focusable {
 			children.push(node("col", undefined, lines, "composer"));
 		}
 		children.push({ ...this.#describeFooter(record, canFollowUp, copied), key: "footer" });
+		// Clicking Close always dismisses the sheet; the Esc keycap only shows where Esc does too.
+		const running = record !== undefined && getBtwLatestTurn(record).status === "running";
+		const escapeCloses = !composer && !(running && !this.#options.escapeHides);
+		children.push({
+			...actionBar([null, actionButton("Close", "close", escapeCloses ? { keys: "escape" } : undefined)]),
+			key: "actions",
+		});
 		// The sheet is the frame (`nativeOverlay`): a borderless column.
 		const described = col(children, { gap: "md" });
 		this.#native = {
@@ -504,6 +511,10 @@ export class BtwHistoryPanel implements Component, Focusable {
 	}
 
 	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "close") {
+			this.#options.onClose();
+			return;
+		}
 		if ((event.type !== "select" && event.type !== "activate") || this.#composer) return;
 		const index = this.#records.findIndex(record => record.id === event.item);
 		if (index === -1) return;

package/src/overlays/move-overlay.ts

@@ -15,7 +15,8 @@ import { formatKeyHint } from "../app-keybindings";
 import { editorKey, editorKeys } from "../chrome/keybinding-hints";
 import type { NativeNode, NativeUiEvent } from "../native/node";
 import { node, span } from "../native/describe";
-import { actionHint, overlayCard, statusHintsRow } from "../native/overlay";
+import { actionBar, actionButton, actionHint, overlayCard, statusHintsRow } from "../native/overlay";
+import { getKeybindings } from "../keybindings";
 
 export interface MoveOverlayResult {
 	directory: string;
@@ -122,12 +123,7 @@ export class MoveOverlay implements Component, Focusable {
 			return;
 		}
 		if (matchesKey(data, Key.tab)) {
-			const selected = this.#results[this.#selectedIndex];
-			if (selected) {
-				this.#field.setValue(selected.value);
-				this.#selectedIndex = 0;
-				this.#updateResults();
-			}
+			this.#accept();
 			return;
 		}
 		const before = this.#field.getValue();
@@ -192,19 +188,28 @@ export class MoveOverlay implements Component, Focusable {
 		);
 		const hints = statusHintsRow(
 			[span("Type to filter", "dim")],
-			[
-				actionHint(["tui.select.up", "tui.select.down"], "navigate"),
-				{ keys: ["tab"], label: "accept" },
-				{ keys: ["enter"], label: "confirm" },
-				actionHint("tui.select.cancel", "cancel"),
-			],
+			[actionHint(["tui.select.up", "tui.select.down"], "navigate")],
 		);
-		const described = overlayCard("omp.dialog.move", "Move to directory", [this.#field, list, hints]);
+		// Accept, Confirm and Cancel run what Tab, Enter and Esc run.
+		const actions = actionBar([
+			actionButton("Accept", "accept", { keys: "tab" }),
+			null,
+			// The bound cancel key; Esc also cancels when it is unbound.
+			actionButton("Cancel", "cancel", { keys: getKeybindings().getKeys("tui.select.cancel")[0] ?? "escape" }),
+			actionButton("Confirm", "confirm", { keys: "enter", tone: "accent" }),
+		]);
+		const described = overlayCard("omp.dialog.move", "Move to directory", [this.#field, list, hints, actions]);
 		this.#native = { revision: this.#revision, node: described };
 		return described;
 	}
 
 	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action") {
+			if (event.act === "accept") this.#accept();
+			else if (event.act === "confirm") this.#field.submit();
+			else if (event.act === "cancel") this.#done(undefined);
+			return;
+		}
 		if (event.type !== "select" && event.type !== "activate") return;
 		const index = this.#results.findIndex(result => result.value === event.item);
 		if (index === -1) return;
@@ -216,6 +221,15 @@ export class MoveOverlay implements Component, Focusable {
 		if (event.type === "activate") this.#field.submit();
 	}
 
+	/** Tab: fill the field with the highlighted suggestion. */
+	#accept(): void {
+		const selected = this.#results[this.#selectedIndex];
+		if (!selected) return;
+		this.#field.setValue(selected.value);
+		this.#selectedIndex = 0;
+		this.#updateResults();
+	}
+
 	invalidate(): void {
 		this.#field.input.prompt = theme.fg("dim", "Path: ");
 		this.#field.invalidate();

package/src/overlays/plan-review-overlay.ts

@@ -1607,7 +1607,7 @@ export class PlanReviewOverlay implements Component {
 		return this.#nativeRoot;
 	}
 
-	/** Head tools: Copy `c` and the external editor, mirroring their keys. */
+	/** Head tools: Copy `c`, the external editor and Cancel, mirroring their keys. */
 	#describeTools(): NativeNode | undefined {
 		if (this.#committed) return undefined;
 		const buttons: NativeNode[] = [];
@@ -1618,6 +1618,12 @@ export class PlanReviewOverlay implements Component {
 		if (this.callbacks.onExternalEditor) {
 			buttons.push(actionButton("Edit in $EDITOR", "externalEditor", editorKeyId ? { keys: editorKeyId } : {}));
 		}
+		// Cancel the review the way the cancel key does; while annotating that key
+		// only leaves the draft/chooser, so the button is hidden there.
+		if (!this.#annotating && !this.#annotationChooser) {
+			const cancelKeyId = getKeybindings().getKeys("tui.select.cancel")[0];
+			buttons.push(actionButton("Cancel", "cancel", cancelKeyId ? { keys: cancelKeyId } : {}));
+		}
 		if (buttons.length === 0) return undefined;
 		return node("row", { role: "omp.plan.tools", gap: "sm", align: "center", justify: "end" }, buttons, "tools");
 	}
@@ -1625,12 +1631,15 @@ export class PlanReviewOverlay implements Component {
 	handleNativeEvent(event: NativeUiEvent): void {
 		if (this.#committed) return;
 		if (event.type === "action") {
-			// Head tools run exactly what `c` and the external-editor key run.
+			// Head tools run exactly what `c`, the external-editor key and Esc run.
 			if (this.#annotating || this.#annotationChooser) return;
 			if (event.act === "copyPlan" && this.callbacks.onCopyPlan) {
 				void this.callbacks.onCopyPlan(joinPlanSections(this.#sections));
 			} else if (event.act === "externalEditor") {
 				this.callbacks.onExternalEditor?.();
+			} else if (event.act === "cancel") {
+				this.#committed = true;
+				this.callbacks.onCancel();
 			}
 			return;
 		}