@esso0428/pi-subagents 0.17.12 → 0.17.13

package/src/ui/agent-widget.ts

@@ -5,9 +5,9 @@
  * Uses the callback form of setWidget for themed rendering.
  */
 
-import { Editor, isKeyRelease, Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { Editor, isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { renderAgentName } from "../agent-color.js";
-import { type AgentManager, isTopLevelAgent } from "../agent-manager.js";
+import type { AgentManager } from "../agent-manager.js";
 import { getConfig } from "../agent-types.js";
 import type { AgentInvocation, AgentRecord, SubagentType, WidgetMode } from "../types.js";
 import { getLifetimeCost, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, type SessionLike } from "../usage.js";
@@ -16,19 +16,17 @@ import { getLifetimeCost, getLifetimeTotal, getSessionContextPercent, type Lifet
 
 /** Maximum number of rendered lines before overflow collapse kicks in. */
 export const MAX_WIDGET_LINES = 12;
+/** Keep a small editor/input area visible below the above-editor widget. */
+const MIN_EDITOR_LINES = 4;
 
-/** Number of lines available above an editor, retaining room for the prompt. */
-export function getWidgetLineBudget(terminalRows: number): number {
-  if (!Number.isFinite(terminalRows)) return MAX_WIDGET_LINES;
-  return Math.min(MAX_WIDGET_LINES, Math.max(0, Math.floor(terminalRows) - 4));
-}
-
-export type AgentWidgetOpenMode = "live" | "history";
-
-export interface AgentWidgetOptions {
-  canOpenHistory?: (record: import("../types.js").AgentRecord) => boolean;
-  onOpen?: (record: import("../types.js").AgentRecord, mode: AgentWidgetOpenMode) => void;
-  showCost?: () => boolean;
+/**
+ * Derive the widget ceiling from the terminal height while retaining the
+ * historical MAX_WIDGET_LINES ceiling. Very short terminals may have no room
+ * for the widget; that is preferable to consuming the editor/input area.
+ */
+export function getWidgetLineBudget(rows: number): number {
+  if (!Number.isFinite(rows)) return MAX_WIDGET_LINES;
+  return Math.min(MAX_WIDGET_LINES, Math.max(0, Math.floor(rows) - MIN_EDITOR_LINES));
 }
 
 /** Braille spinner frames for animated running indicator. */
@@ -55,6 +53,20 @@ export type Theme = {
   bold(text: string): string;
 };
 
+export type AgentWidgetOpenMode = "live" | "history";
+export type AgentWidgetOpenCallback = (record: AgentRecord, mode: AgentWidgetOpenMode) => void | Promise<void>;
+export interface AgentWidgetOptions {
+  canOpenHistory?: (record: AgentRecord) => boolean;
+  onOpen?: AgentWidgetOpenCallback;
+  showCost?: () => boolean;
+}
+/** @deprecated Use AgentWidgetOpenMode. */
+export type AgentOpenMode = AgentWidgetOpenMode;
+/** @deprecated Use AgentWidgetOpenCallback. */
+export type AgentOpenCallback = AgentWidgetOpenCallback;
+/** @deprecated Use AgentWidgetOptions.canOpenHistory. */
+export type AgentHistoryCapability = AgentWidgetOptions["canOpenHistory"];
+
 export type UICtx = {
   setStatus(key: string, text: string | undefined): void;
   setWidget(
@@ -76,7 +88,7 @@ export interface AgentActivity {
   turnCount: number;
   /** Effective max turns for this agent (undefined = unlimited). */
   maxTurns?: number;
-  /** Lifetime token usage, including partial runs. */
+  /** Lifetime usage breakdown — see LifetimeUsage docs. */
   lifetimeUsage: LifetimeUsage;
 }
 
@@ -93,7 +105,7 @@ export interface AgentDetails {
   activity?: string;
   /** Current spinner frame index (for animated running indicator). */
   spinnerFrame?: number;
-  /** Short label for the model the run used, e.g. "haiku 4.5". */
+  /** Short model name if different from parent (e.g. "haiku", "sonnet"). */
   modelName?: string;
   /** Notable config tags (e.g. ["thinking: high", "isolated"]). */
   tags?: string[];
@@ -123,31 +135,6 @@ export function formatTokens(count: number): string {
   return `${count} token`;
 }
 
-/**
- * Format a cost as `~$0.0042`, or "" when there is nothing to show.
- *
- * The tilde is load-bearing: this is pi's own estimate from the model's listed
- * rates, not a billed figure, and the surfaces that print it sit next to token
- * counts that ARE exact.
- *
- * Nothing is printed for zero, which is also what a model with no pricing data
- * reports: `$0.00` beside a local model's tokens would claim its cost was
- * measured and found to be nothing, rather than never measured at all. For the
- * same reason a real cost too small for four decimals reads `<$0.0001` — it was
- * measured, and rounding it to `~$0.0000` would say the opposite.
- */
-export function formatCost(cost: number): string {
-  if (!(cost > 0)) return "";                     // also catches NaN
-  if (cost < 0.0001) return "<$0.0001";
-  if (cost >= 1) return `~$${cost.toFixed(2)}`;
-  // Under a dollar: cents at minimum, four decimals at most, nothing trailing.
-  // Most single runs land between a tenth of a cent and a dime, where rounding
-  // to cents would collapse a 4x difference in spend into the same figure.
-  const rounded = Number(cost.toFixed(4));
-  const decimals = (String(rounded).split(".")[1] ?? "").length;
-  return `~$${rounded.toFixed(Math.max(2, decimals))}`;
-}
-
 /**
  * Token count with optional context-fill % and compaction-count annotations.
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
@@ -193,6 +180,16 @@ export function formatDuration(startedAt: number, completedAt?: number): string
   return `${formatMs(Date.now() - startedAt)} (running)`;
 }
 
+/** Format an estimated model cost without implying billing precision. */
+export function formatCost(cost: number): string {
+  if (!(cost > 0)) return "";
+  if (cost < 0.0001) return "<$0.0001";
+  if (cost >= 1) return `~$${cost.toFixed(2)}`;
+  const rounded = Number(cost.toFixed(4));
+  const decimals = (String(rounded).split(".")[1] ?? "").length;
+  return `~$${rounded.toFixed(Math.max(2, decimals))}`;
+}
+
 /** Get display name for any agent type (built-in or custom). */
 export function getDisplayName(type: SubagentType): string {
   return getConfig(type).displayName;
@@ -204,13 +201,7 @@ export function getPromptModeLabel(type: SubagentType): string | undefined {
   return config.promptMode === "append" ? "twin" : undefined;
 }
 
-/**
- * Mode label is not included — callers add it where they want it.
- *
- * Both model forms come back so each surface can pick by width; the
- * "(asked X)" annotation is applied here rather than by callers, so a value the
- * spawn did not honor cannot be rendered as though it had been (#182).
- */
+/** Mode label is not included — callers add it where they want it. */
 export function buildInvocationTags(
   invocation: AgentInvocation | undefined,
 ): { modelName?: string; modelId?: string; tags: string[] } {
@@ -232,9 +223,9 @@ export function buildInvocationTags(
   };
 }
 
-/** Truncate text to a single line, max `len` chars. */
+/** Normalize and truncate text so it can never add physical widget rows. */
 function truncateLine(text: string, len = 60): string {
-  const line = text.split("\n").find(l => l.trim())?.trim() ?? "";
+  const line = text.replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim();
   if (line.length <= len) return line;
   return line.slice(0, len) + "…";
 }
@@ -273,10 +264,25 @@ export class AgentWidget {
   private uiCtx: UICtx | undefined;
   private widgetFrame = 0;
   private widgetInterval: ReturnType<typeof setInterval> | undefined;
-  /** Tracks how many turns each finished agent has survived. Key: agent ID, Value: turns since finished. */
-  private finishedTurnAge = new Map<string, number>();
-  /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
-  private static readonly ERROR_LINGER_TURNS = 2;
+  private inputUnsub: (() => void) | undefined;
+  /** Whether arrow keys currently navigate the agent roster. */
+  private navigationActive = false;
+  /** Number of modal surfaces currently owning this listener's input suspension. */
+  private navigationSuspensionDepth = 0;
+  /** Stable identity of the selected row, so roster changes do not jump selection. */
+  private selectedAgentId: string | undefined;
+  /** Last logical roster index of the selected row, used when it disappears. */
+  private selectedRosterIndex = 0;
+  /** First logical row currently represented by the bounded viewport. */
+  private viewportStart = 0;
+
+  /** Cached records and roster. Rebuilt by update(), never by an arrow press. */
+  private cachedAgents: AgentRecord[] = [];
+  private cachedRoster: AgentRecord[] = [];
+  private rosterCacheKey: string | undefined;
+  private rosterCacheInitialized = false;
+  /** Terminal history capability is a potentially filesystem-backed lookup. */
+  private historyOpenabilityCache = new Map<string, { key: string; value: boolean }>();
 
   /** Whether the widget callback is currently registered with the TUI. */
   private widgetRegistered = false;
@@ -284,38 +290,17 @@ export class AgentWidget {
   private tui: any | undefined;
   /** Last status bar text, used to avoid redundant setStatus calls. */
   private lastStatusText: string | undefined;
-  private lastSnapshot = "";
-  private inputCleanup: (() => void) | undefined;
-  private navigationSuspended = false;
-  private navigationActive = false;
-  private selectedAgentId: string | undefined;
-  private viewportStart = 0;
-  private selectedRosterIndex = 0;
-  private openOptions: AgentWidgetOptions;
-  private showCost: () => boolean;
-  private showModel: () => boolean;
+  /** Snapshot of the state used for the last widget registration/render request. */
+  private lastRenderKey: string | undefined;
+  private readonly openOptions: AgentWidgetOptions;
+  private readonly showCost: () => boolean;
+  private readonly showModel: () => boolean;
 
   constructor(
     private manager: AgentManager,
     private agentActivity: Map<string, AgentActivity>,
-    /**
-     * Read live at render time. Selects which agents the widget shows — see
-     * `WidgetMode`. Defaults to `"all"` when a caller supplies no policy; the
-     * extension supplies one defaulting to `"background"`.
-     */
+    /** Read live at render time. Selects which agents the widget shows. */
     private mode: () => WidgetMode = () => "all",
-    /**
-     * Read live at render time, like `mode`. Whether running agents show an
-     * estimated cost beside their token count. Defaults to off — the extension
-     * supplies the user's `showCost` setting.
-     */
-    /**
-     * Read live at render time, like `mode`. Whether running agents name the
-     * model driving them and the thinking level it is running at. Defaults to
-     * off — the extension supplies the user's `showModel` setting — because the
-     * row is already dense and the same pair is on the tool result and in the
-     * conversation viewer unconditionally.
-     */
     showCostOrOptions: (() => boolean) | AgentWidgetOptions = () => false,
     showModel: () => boolean = () => false,
   ) {
@@ -340,8 +325,8 @@ export class AgentWidget {
    *     only proven-foreground runs drop out — nothing else silently vanishes.
    *   - `all`: every agent.
    */
-  private widgetAgents() {
-    const all = this.manager.listAgents().filter(isTopLevelAgent);
+  private widgetAgentsFromManager(): AgentRecord[] {
+    const all = this.manager.listAgents();
     switch (this.mode()) {
       case "off": return [];
       case "background": return all.filter(a => a.isBackground !== false);
@@ -349,130 +334,257 @@ export class AgentWidget {
     }
   }
 
-  /** Temporarily stop global navigation from consuming input handled by another UI surface. */
+  /** Records currently visible to the widget; safe for render and input paths. */
+  private widgetAgents(): AgentRecord[] {
+    return this.rosterCacheInitialized ? this.cachedAgents : this.widgetAgentsFromManager();
+  }
+
+  private canOpenHistory(record: AgentRecord): boolean {
+    return this.openOptions.canOpenHistory?.(record) ?? true;
+  }
+
+  private historyOpenabilityKey(record: AgentRecord): string {
+    return JSON.stringify([
+      record.status,
+      record.completedAt ?? null,
+      record.transcriptPath ?? null,
+      record.session !== undefined,
+    ]);
+  }
+
+  /**
+   * Cache terminal history capability by the record state that can affect it.
+   * The supplied predicate may call `existsSync`, so it must not run from a
+   * timer refresh, render-key calculation, or arrow-navigation path more than
+   * once for the same terminal record state.
+   */
+  private cachedCanOpenHistory(record: AgentRecord): boolean {
+    if (record.status === "running" || record.status === "queued") return true;
+
+    const key = this.historyOpenabilityKey(record);
+    const cached = this.historyOpenabilityCache.get(record.id);
+    if (cached?.key === key) return cached.value;
+
+    const value = this.canOpenHistory(record);
+    this.historyOpenabilityCache.set(record.id, { key, value });
+    return value;
+  }
+
+  /** Refresh the manager snapshot and openability cache at lifecycle/update time. */
+  private refreshRoster(): AgentRecord[] {
+    const agents = this.widgetAgentsFromManager();
+    const key = JSON.stringify({
+      mode: this.mode(),
+      agents: agents.map(record => [
+        record.id,
+        record.type,
+        record.description,
+        record.status,
+        record.completedAt ?? null,
+        record.startedAt,
+        record.toolUses,
+        record.error ?? null,
+        record.transcriptPath ?? null,
+        record.session !== undefined,
+        record.isBackground,
+        record.status !== "running" && record.status !== "queued"
+          ? this.cachedCanOpenHistory(record)
+          : undefined,
+      ]),
+    });
+    if (this.rosterCacheInitialized && key === this.rosterCacheKey) return this.cachedRoster;
+
+    const finished = agents.filter(record =>
+      record.status !== "running" && record.status !== "queued"
+      && record.completedAt !== undefined
+      && this.cachedCanOpenHistory(record),
+    );
+    const running = agents.filter(record => record.status === "running");
+    const queued = agents.filter(record => record.status === "queued");
+    this.cachedAgents = agents;
+    this.cachedRoster = [...running, ...queued, ...finished];
+    this.rosterCacheKey = key;
+    this.rosterCacheInitialized = true;
+    return this.cachedRoster;
+  }
+
+  /** Suspend only this listener's keyboard ownership; never alter the widget. */
   suspendNavigation(): void {
-    this.navigationSuspended = true;
+    this.navigationSuspensionDepth++;
   }
 
-  /** Resume global navigation after another UI surface has closed. */
+  /** Restore one layer of this listener's keyboard ownership. */
   resumeNavigation(): void {
-    this.navigationSuspended = false;
+    if (this.navigationSuspensionDepth > 0) this.navigationSuspensionDepth--;
   }
 
   /** Set the UI context (grabbed from first tool execution). */
   setUICtx(ctx: UICtx): boolean {
     if (ctx === this.uiCtx) return false;
-    this.inputCleanup?.();
-    this.inputCleanup = undefined;
+
+    // UICtx changed — the widget and input handler registered on the old
+    // context are gone. Re-register both on the next update().
+    this.inputUnsub?.();
+    this.inputUnsub = undefined;
     this.uiCtx = ctx;
     this.widgetRegistered = false;
     this.tui = undefined;
     this.lastStatusText = undefined;
-    this.navigationSuspended = false;
+    this.lastRenderKey = undefined;
+    this.navigationSuspensionDepth = 0;
     this.navigationActive = false;
     this.selectedAgentId = undefined;
+    this.selectedRosterIndex = 0;
     this.viewportStart = 0;
-    if (ctx.onTerminalInput) this.inputCleanup = ctx.onTerminalInput(data => this.handleInput(data));
+    this.cachedAgents = [];
+    this.cachedRoster = [];
+    this.rosterCacheKey = undefined;
+    this.rosterCacheInitialized = false;
+    this.historyOpenabilityCache.clear();
+    // Print/RPC tests and lightweight embedders may provide only the widget
+    // surface; real interactive contexts always implement this hook.
+    if (typeof ctx.onTerminalInput === "function") {
+      this.inputUnsub = ctx.onTerminalInput(data => this.handleKey(data));
+    }
     return true;
   }
 
-  /**
-   * Called on each new turn (tool_execution_start).
-   * Ages finished agents and clears those that have lingered long enough.
-   */
+  /** Request a render on the currently registered TUI without touching input. */
+  requestUiRefresh(force = true): boolean {
+    if (!this.tui || typeof this.tui.requestRender !== "function") return false;
+    this.tui.requestRender(force);
+    return true;
+  }
+
+  /** Called on each new turn (tool_execution_start). */
   onTurnStart() {
-    // Age all finished agents
-    for (const [id, age] of this.finishedTurnAge) {
-      this.finishedTurnAge.set(id, age + 1);
-    }
-    // Trigger a widget refresh (will filter out expired agents)
     this.update();
   }
 
-  /** Ensure the widget update timer is running. */
+  /** Keep the spinner/elapsed-time timer alive only while a visible agent runs. */
   ensureTimer() {
+    if (!this.uiCtx) return;
+    const roster = this.rosterCacheInitialized ? this.cachedRoster : this.refreshRoster();
+    if (!roster.some(a => a.status === "running")) return;
     if (!this.widgetInterval) {
       this.widgetInterval = setInterval(() => this.update(true), 250);
     }
   }
 
-  /** Check if a finished agent should still be shown in the widget. */
-  private shouldShowFinished(agentId: string, status: string, durable = false): boolean {
-    // A persisted transcript is a durable history row, not a transient
-    // completion notification. Keep it navigable after the one-turn visual
-    // linger expires; runtime GC must not make `/agents` history disappear.
-    if (durable) return true;
-    const age = this.finishedTurnAge.get(agentId) ?? 0;
-    const maxAge = ERROR_STATUSES.has(status) ? AgentWidget.ERROR_LINGER_TURNS : 1;
-    return age < maxAge;
-  }
-
-  /** Record an agent as finished (call when agent completes). */
-  markFinished(agentId: string) {
-    if (!this.finishedTurnAge.has(agentId)) {
-      this.finishedTurnAge.set(agentId, 0);
+  private syncTimer(shouldRun: boolean): void {
+    if (shouldRun) {
+      this.ensureTimer();
+    } else if (this.widgetInterval) {
+      clearInterval(this.widgetInterval);
+      this.widgetInterval = undefined;
     }
   }
 
   /**
-   * Drop an agent's finished-age (call when a settled agent starts running
-   * again, i.e. a background resume). markFinished only seeds an age it has not
-   * seen before, so a resumed agent would otherwise keep the age from its
-   * previous run — already past the linger limit, hiding the new run's
-   * completion line entirely.
+   * Retained for the lifecycle call sites. Terminal visibility is determined
+   * by the manager record and the history capability, not a one-turn timer.
    */
-  markRunning(agentId: string) {
-    this.finishedTurnAge.delete(agentId);
-  }
+  markFinished(_agentId: string) {}
 
-  private navigationAgents(): AgentRecord[] {
-    const agents = this.widgetAgents().filter(agent =>
-      agent.status === "running" || agent.status === "queued" || (agent.completedAt !== undefined && this.shouldShowFinished(agent.id, agent.status, agent.transcriptPath !== undefined)),
-    );
-    return agents.filter(agent =>
-      agent.status === "running" || agent.status === "queued" || (this.openOptions.canOpenHistory?.(agent) ?? true),
-    ).sort((a, b) => {
-      const activeA = a.status === "running" || a.status === "queued" ? 0 : 1;
-      const activeB = b.status === "running" || b.status === "queued" ? 0 : 1;
-      return activeA - activeB;
-    });
-  }
+  /** Retained for lifecycle call sites; terminal rows are record-driven now. */
+  markRunning(_agentId: string) {}
 
-  private updateViewport(roster: AgentRecord[]): void {
-    const budget = getWidgetLineBudget(this.tui?.terminal?.rows ?? 24);
-    const visibleRows = Math.max(1, budget - 1);
-    if (this.selectedRosterIndex < this.viewportStart) this.viewportStart = this.selectedRosterIndex;
-    if (this.selectedRosterIndex >= this.viewportStart + visibleRows) this.viewportStart = this.selectedRosterIndex - visibleRows + 1;
-    this.viewportStart = Math.max(0, Math.min(this.viewportStart, Math.max(0, roster.length - visibleRows)));
+  /**
+   * Records represented by selectable rows in the above-editor widget.
+   *
+   * Keep this order as the single source of truth for both rendering and key
+   * navigation. `listAgents()` is newest-first; active rows come first so the
+   * panel exposes currently useful work before terminal history.
+   */
+  private roster(): AgentRecord[] {
+    return this.rosterCacheInitialized ? this.cachedRoster : this.refreshRoster();
   }
 
+  /** True when pi's prompt editor owns the keyboard. */
   private editorHasFocus(): boolean {
     const focused = (this.tui as { focusedComponent?: unknown } | undefined)?.focusedComponent;
     return focused == null || focused instanceof Editor;
   }
 
+  private selectedIndexOf(records: readonly AgentRecord[]): number {
+    if (!this.selectedAgentId) return -1;
+    return records.findIndex(record => record.id === this.selectedAgentId);
+  }
+
   private deactivate(): void {
+    // Keep the selected row and viewport so re-entering navigation can resume
+    // where the user left off. Lifecycle resets (context, dispose, empty
+    // roster) clear this state explicitly instead of treating every exit as a
+    // reset.
     this.navigationActive = false;
     this.requestUiRefresh();
   }
 
-  private handleInput(data: string): { consume?: boolean; data?: string } | undefined {
+  /** Resume navigation from the retained row, or select the first row. */
+  private activate(records: readonly AgentRecord[]): void {
+    this.navigationActive = true;
+    const selectedIndex = this.selectedIndexOf(records);
+    if (selectedIndex >= 0) {
+      this.selectedRosterIndex = selectedIndex;
+    } else {
+      // The previously selected row may have been cleaned up while navigation
+      // was inactive. Resume at its old logical position, clamped to the new
+      // roster, rather than jumping back to the first row.
+      const fallbackIndex = Math.max(0, Math.min(this.selectedRosterIndex, records.length - 1));
+      this.selectedAgentId = records[fallbackIndex].id;
+      this.selectedRosterIndex = fallbackIndex;
+      this.viewportStart = Math.min(this.viewportStart, Math.max(0, records.length - 1));
+    }
+    this.requestUiRefresh();
+  }
+
+  /** Move the selected row, activating only from an empty focused editor. */
+  private moveSelection(direction: -1 | 1): boolean {
+    const records = this.roster();
+    const ui = this.uiCtx;
+    if (records.length === 0 || !ui) return false;
+
+    if (!this.navigationActive) {
+      if (direction !== 1 || !this.editorHasFocus() || (ui.getEditorText?.() ?? "") !== "") return false;
+      this.activate(records);
+      return true;
+    }
+
+    const currentIndex = Math.max(0, this.selectedIndexOf(records));
+    if (direction === -1 && currentIndex === 0) {
+      this.deactivate();
+      return true;
+    }
+    const nextIndex = Math.max(0, Math.min(records.length - 1, currentIndex + direction));
+    this.selectedAgentId = records[nextIndex].id;
+    this.selectedRosterIndex = nextIndex;
+    this.requestUiRefresh();
+    return true;
+  }
+
+  private openSelected(): void {
+    const record = this.roster().find(candidate => candidate.id === this.selectedAgentId);
+    this.deactivate();
+    if (!record) return;
+    const mode: AgentWidgetOpenMode = record.status === "running" || record.status === "queued" ? "live" : "history";
+    void this.openOptions.onOpen?.(record, mode);
+  }
+
+  /** Handle terminal input before it reaches the focused prompt editor. */
+  handleKey(data: string): { consume?: boolean; data?: string } | undefined {
     if (!this.uiCtx || isKeyRelease(data)) return undefined;
-    if (this.navigationSuspended) return undefined;
+    if (this.navigationSuspensionDepth > 0) return undefined;
     if (!this.editorHasFocus()) {
       if (this.navigationActive) this.deactivate();
       return undefined;
     }
 
     if (!this.navigationActive) {
-      const roster = this.navigationAgents();
-      if (!matchesKey(data, "down") || (this.uiCtx.getEditorText?.() ?? "") !== "" || roster.length === 0) return undefined;
-      this.navigationActive = true;
-      const index = this.selectedAgentId ? roster.findIndex(agent => agent.id === this.selectedAgentId) : -1;
-      this.selectedRosterIndex = index >= 0 ? index : 0;
-      this.selectedAgentId = roster[this.selectedRosterIndex]?.id;
-      this.updateViewport(roster);
-      this.requestUiRefresh();
+      const records = this.roster();
+      if (!matchesKey(data, "down") || (this.uiCtx.getEditorText?.() ?? "") !== "" || records.length === 0) {
+        return undefined;
+      }
+      this.activate(records);
       return { consume: true };
     }
 
@@ -480,47 +592,19 @@ export class AgentWidget {
       this.deactivate();
       return { consume: true };
     }
-    if (matchesKey(data, "up") || matchesKey(data, "down")) {
-      const roster = this.navigationAgents();
-      if (roster.length === 0) return { consume: true };
-      if (matchesKey(data, "up") && this.selectedRosterIndex === 0) {
-        this.deactivate();
-      } else {
-        this.selectedRosterIndex = Math.max(0, Math.min(roster.length - 1, this.selectedRosterIndex + (matchesKey(data, "down") ? 1 : -1)));
-        this.selectedAgentId = roster[this.selectedRosterIndex]?.id;
-        this.updateViewport(roster);
-        this.requestUiRefresh();
-      }
-      return { consume: true };
-    }
+    if (matchesKey(data, "up")) return this.moveSelection(-1) ? { consume: true } : undefined;
+    if (matchesKey(data, "down")) return this.moveSelection(1) ? { consume: true } : undefined;
     if (matchesKey(data, Key.enter)) {
-      const record = this.navigationAgents()[this.selectedRosterIndex];
-      if (record) {
-        const terminal = record.status !== "running" && record.status !== "queued";
-        if (!terminal || (this.openOptions.canOpenHistory?.(record) ?? true)) {
-          this.openOptions.onOpen?.(record, terminal ? "history" : "live");
-        }
-      }
+      this.openSelected();
       return { consume: true };
     }
 
-    // Only arrow keys navigate. Other keys flow to the editor and leave navigation mode.
+    // Only ↑/↓ navigate. Other keys, including j/k/←/→, flow to the editor
+    // and leave navigation mode.
     this.deactivate();
     return undefined;
   }
 
-  private requestUiRefresh(force = true): boolean {
-    if (!this.tui || typeof this.tui.requestRender !== "function") return false;
-    this.tui.requestRender(force);
-    return true;
-  }
-
-  private selectionBullet(agentId: string, theme: Theme): string {
-    return this.navigationActive && this.selectedAgentId === agentId
-      ? theme.fg("accent", "●")
-      : theme.fg("dim", "○");
-  }
-
   /** Render a finished agent line. */
   private renderFinishedLine(a: { id: string; type: SubagentType; status: string; description: string; toolUses: number; startedAt: number; completedAt?: number; error?: string; lifetimeUsage?: LifetimeUsage }, theme: Theme): string {
     const modeLabel = getPromptModeLabel(a.type);
@@ -539,7 +623,7 @@ export class AgentWidget {
       statusText = theme.fg("dim", " stopped");
     } else if (a.status === "error") {
       icon = theme.fg("error", "✗");
-      const errMsg = a.error ? `: ${a.error.slice(0, 60)}` : "";
+      const errMsg = a.error ? `: ${truncateLine(a.error)}` : "";
       statusText = theme.fg("error", ` error${errMsg}`);
     } else {
       // aborted
@@ -551,15 +635,12 @@ export class AgentWidget {
     const activity = this.agentActivity.get(a.id);
     if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns));
     if (a.toolUses > 0) parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
-    // From the record, not the activity tracker: that entry is deleted the
-    // moment an agent finishes, and "what did it cost" is a question asked
-    // about finished agents.
-    const costText = this.showCost() ? formatCost(getLifetimeCost(a.lifetimeUsage)) : "";
+    const costText = this.showCost() && a.lifetimeUsage ? formatCost(getLifetimeCost(a.lifetimeUsage)) : "";
     if (costText) parts.push(costText);
     parts.push(duration);
 
     const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
-    const description = a.description.replace(/[\r\n]+/g, " ");
+    const description = truncateLine(a.description);
     return `${icon} ${renderAgentName(a.type, theme, { fallbackColor: "dim" })}${modeTag}  ${theme.fg("dim", description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
   }
 
@@ -568,14 +649,12 @@ export class AgentWidget {
    * reading live state each time instead of capturing it in a closure.
    */
   private renderWidget(tui: any, theme: Theme): string[] {
-    const allAgents = this.widgetAgents();
-    const running = allAgents.filter(a => a.status === "running");
-    const queued = allAgents.filter(a => a.status === "queued");
-    const finished = allAgents.filter(a =>
-      a.status !== "running" && a.status !== "queued" && a.completedAt
-      && this.shouldShowFinished(a.id, a.status, a.transcriptPath !== undefined),
-    );
+    const roster = this.roster();
+    const running = roster.filter(a => a.status === "running");
+    const queued = roster.filter(a => a.status === "queued");
+    const finished = roster.filter(a => a.status !== "running" && a.status !== "queued");
 
+    const selectedId = this.navigationActive ? this.selectedAgentId : undefined;
     const hasActive = running.length > 0 || queued.length > 0;
     const hasFinished = finished.length > 0;
 
@@ -583,9 +662,9 @@ export class AgentWidget {
     if (!hasActive && !hasFinished) return [];
 
     const w = tui.terminal.columns;
-    const budget = getWidgetLineBudget(tui.terminal.rows ?? 24);
-    if (budget === 0) return [];
-    const truncate = (line: string) => truncateToWidth(line.replace(/[\r\n]+/g, " "), w);
+    const maxLines = getWidgetLineBudget(tui.terminal.rows);
+    if (maxLines === 0) return [];
+    const truncate = (line: string, width = w) => truncateToWidth(line, Math.max(0, width));
     const headingColor = hasActive ? "accent" : "dim";
     const headingIcon = hasActive ? "●" : "○";
     const frame = SPINNER[this.widgetFrame % SPINNER.length];
@@ -593,12 +672,18 @@ export class AgentWidget {
     // Build sections separately for overflow-aware assembly.
     // Each running agent = 2 lines (header + activity), finished = 1 line, queued = 1 line.
 
-    const finishedLines: string[] = [];
+    type WidgetRow = { record: AgentRecord; lines: string[]; recordCount?: number };
+
+    const finishedLines: WidgetRow[] = [];
     for (const a of finished) {
-      finishedLines.push(truncate(theme.fg("dim", "├─") + ` ${this.selectionBullet(a.id, theme)} ` + this.renderFinishedLine(a, theme)));
+      const marker = a.id === selectedId ? theme.fg("accent", "●") : theme.fg("dim", "○");
+      finishedLines.push({
+        record: a,
+        lines: [truncate(theme.fg("dim", "├─") + ` ${marker} ` + this.renderFinishedLine(a, theme))],
+      });
     }
 
-    const runningLines: string[][] = []; // each entry is [header, activity]
+    const runningLines: WidgetRow[] = []; // each entry is [header, activity]
     for (const a of running) {
       const modeLabel = getPromptModeLabel(a.type);
       const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
@@ -607,9 +692,7 @@ export class AgentWidget {
       const bg = this.agentActivity.get(a.id);
       const toolUses = bg?.toolUses ?? a.toolUses;
       // Spend comes from the record, never from the activity tracker: the record
-      // is the one that survives the agent finishing, and the one nested-tools
-      // folds a hidden child's spend into. Reading the tracker while an agent
-      // runs and the record once it stops made the figure jump at completion.
+      // survives the agent finishing and includes nested-child usage.
       const tokens = getLifetimeTotal(a.lifetimeUsage);
       const contextPercent = getSessionContextPercent(bg?.session);
       const tokenText = tokens > 0 ? formatSessionTokens(tokens, contextPercent, theme, a.compactionCount) : "";
@@ -617,9 +700,6 @@ export class AgentWidget {
 
       const parts: string[] = [];
       if (this.showModel()) {
-        // Leading, and paired: a thinking level means nothing without the model
-        // it applies to. The tag is taken from buildInvocationTags rather than
-        // rebuilt so the "(asked X)" annotation survives.
         const { modelName, tags } = buildInvocationTags(a.invocation);
         if (modelName) parts.push(modelName);
         const thinkingTag = tags.find(tag => tag.startsWith("thinking: "));
@@ -632,159 +712,305 @@ export class AgentWidget {
       parts.push(elapsed);
       const statsText = parts.join(" · ");
 
-      const activity = (bg ? describeActivity(bg.activeTools, bg.responseText) : "thinking…").replace(/[\r\n]+/g, " ");
+      const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : "thinking…";
 
-      runningLines.push([
-        truncate(theme.fg("dim", "├─") + ` ${this.selectionBullet(a.id, theme)} ${theme.fg("accent", frame)} ${renderAgentName(a.type, theme, { bold: true })}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${fgPreservingNestedStyles(theme, "dim", statsText)}`),
-        truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
-      ]);
+      const marker = a.id === selectedId ? theme.fg("accent", "●") : theme.fg("dim", "○");
+      runningLines.push({
+        record: a,
+        lines: [
+          truncate(theme.fg("dim", "├─") + ` ${marker} ${theme.fg("accent", frame)} ${renderAgentName(a.type, theme, { bold: true })}${modeTag}  ${theme.fg("muted", truncateLine(a.description))} ${theme.fg("dim", "·")} ${fgPreservingNestedStyles(theme, "dim", statsText)}`),
+          truncate(theme.fg("dim", "│  ") + `   ${theme.fg("dim", `⎿  ${truncateLine(activity)}`)}`),
+        ],
+      });
     }
 
-    const selectedQueued = this.navigationActive && this.selectedAgentId !== undefined && queued.some(agent => agent.id === this.selectedAgentId);
-    const queuedLine = queued.length > 0
-      ? truncate(theme.fg("dim", "├─") + ` ${selectedQueued ? theme.fg("accent", "●") : theme.fg("dim", "○")} ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`)
-      : undefined;
-
-    // Assemble with overflow cap (heading + overflow indicator = 2 reserved lines).
-    const maxBody = Math.max(1, budget - 1); // heading takes 1 line
-    const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
+    const queuedLines: WidgetRow[] = queued.map(a => {
+      const marker = a.id === selectedId ? theme.fg("accent", "●") : theme.fg("dim", "○");
+      return {
+        record: a,
+        lines: [truncate(theme.fg("dim", "├─") + ` ${marker} ${theme.fg("muted", "◦")} ${theme.fg("dim", `${getDisplayName(a.type)}  ${truncateLine(a.description)} · queued`)}`)],
+      };
+    });
 
-    const hint = "↑↓ select · enter view · esc back";
-    const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents") + "  " + theme.fg("dim", hint))];
+    // Keep the idle widget compact: a queue is one logical status line until
+    // navigation starts. While navigating, expand it back to the same per-agent
+    // roster used by key handling so every selected queued record can render.
+    const queuedSummary: WidgetRow[] = queued.length > 0 && !this.navigationActive
+      ? [{
+        record: queued[0],
+        recordCount: queued.length,
+        lines: [truncate(theme.fg("dim", "├─") + ` ${theme.fg("dim", "○")} ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`)],
+      }]
+      : [];
+
+    // Assemble with a responsive cap (heading + overflow indicator = 2
+    // reserved lines when content exceeds the available body budget).
+    const maxBody = maxLines - 1; // heading takes 1 line
+    const rows: WidgetRow[] = [
+      ...runningLines,
+      ...(this.navigationActive ? queuedLines : queuedSummary),
+      ...finishedLines,
+    ];
+    const totalBody = rows.reduce((total, row) => total + row.lines.length, 0);
+
+    const heading = "Agents  ↑↓ select · enter view · esc back";
+    const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, heading))];
+
+    if (maxLines === 1) {
+      // There is room only for the heading; do not consume the editor/input row.
+      return lines;
+    }
 
     if (totalBody <= maxBody) {
-      // Everything fits — add all lines and fix up connectors for the last item.
-      lines.push(...finishedLines);
-      for (const pair of runningLines) lines.push(...pair);
-      if (queuedLine) lines.push(queuedLine);
-
-      // Fix last connector: swap ├─ → └─ and │ → space for activity lines.
-      if (lines.length > 1) {
-        const last = lines.length - 1;
-        lines[last] = lines[last].replace("├─", "└─");
-        // If last item is a running agent activity line, fix indent of that line
-        // and fix the header line above it.
-        if (runningLines.length > 0 && !queuedLine) {
-          // The last two lines are the last running agent's header + activity.
-          if (last >= 2) {
-            lines[last - 1] = lines[last - 1].replace("├─", "└─");
-            lines[last] = lines[last].replace("│  ", "   ");
-          }
+      this.viewportStart = 0;
+      for (const row of rows) lines.push(...row.lines);
+      if (rows.length > 0) {
+        const lastRow = rows[rows.length - 1];
+        const lastStart = lines.length - lastRow.lines.length;
+        // Keep the selected row's bullet adjacent to the normal branch marker.
+        // This makes the active row unambiguous even when it is the last row.
+        const lastRowSelected = this.navigationActive && lastRow.record.id === selectedId;
+        if (!lastRowSelected) lines[lastStart] = lines[lastStart].replace("├─", "└─");
+        if (lastRow.lines.length === 2) {
+          lines[lastStart + 1] = lines[lastStart + 1].replace("│  ", "   ");
         }
       }
-    } else {
-      // Overflow — prioritize: running > queued > finished.
-      // Reserve 1 line for overflow indicator.
-      let budget = maxBody - 1;
-      let hiddenRunning = 0;
-      let hiddenFinished = 0;
-
-      // Reserve the queued line's row up front. It is a single summary of N
-      // waiting agents, so it cannot be folded into the "+N more" count (which
-      // is denominated in agents) without either under-reporting it as 1 or
-      // inflating the total with agents that were never getting their own rows.
-      // Reserving costs at most one running agent — which IS counted below —
-      // and makes the drop unreachable. It matters most exactly when it used to
-      // vanish: the pool is saturated and the queue is what the user needs to see.
-      const queuedReserve = queuedLine ? 1 : 0;
-      budget -= queuedReserve;
-
-      // 1. Running agents (2 lines each)
-      for (const pair of runningLines) {
-        if (budget >= 2) {
-          lines.push(...pair);
-          budget -= 2;
+    } else if (!this.navigationActive && queuedSummary.length > 0) {
+      // In the idle view the queue is deliberately one summary row. Preserve
+      // that row before spending space on terminal history, and account for
+      // the real number of queued records if the summary itself cannot fit.
+      // Navigation expands the queue into per-record rows and uses the full
+      // contiguous viewport below.
+      const visibleRows: WidgetRow[] = [];
+      const hiddenRows: WidgetRow[] = [];
+      let bodyBudget = Math.max(0, maxBody - 1); // reserve the footer
+      let runningBudget = Math.max(0, bodyBudget - 1); // reserve queued summary
+
+      for (const row of runningLines) {
+        const height = row.lines.length;
+        if (height <= runningBudget) {
+          visibleRows.push(row);
+          runningBudget -= height;
+          bodyBudget -= height;
         } else {
-          hiddenRunning++;
+          hiddenRows.push(row);
         }
       }
 
-      // 2. Queued line (always fits — its row was reserved above)
-      if (queuedLine) {
-        budget += queuedReserve;
-        lines.push(queuedLine);
-        budget--;
+      const summaryRow = queuedSummary[0];
+      if (bodyBudget > 0) {
+        visibleRows.push(summaryRow);
+        bodyBudget -= summaryRow.lines.length;
+      } else {
+        hiddenRows.push(summaryRow);
       }
 
-      // 3. Finished agents
-      for (const fl of finishedLines) {
-        if (budget >= 1) {
-          lines.push(fl);
-          budget--;
+      for (const row of finishedLines) {
+        const height = row.lines.length;
+        if (height <= bodyBudget) {
+          visibleRows.push(row);
+          bodyBudget -= height;
         } else {
-          hiddenFinished++;
+          hiddenRows.push(row);
         }
       }
 
-      // Overflow summary
-      // On extremely short terminals the queued summary itself consumes the
-      // last useful row; keep its count in the compact footer. At the normal
-      // 12-line ceiling the summary is a single visible row and must not be
-      // counted as hidden agents.
-      const hiddenQueued = queuedLine && (tui.terminal.rows ?? 24) < 10 ? queued.length : 0;
-      const overflowParts: string[] = [];
-      if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
-      if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
-      if (hiddenQueued > 0) overflowParts.push(`${hiddenQueued} queued`);
-      const hiddenTotal = hiddenRunning + hiddenFinished + hiddenQueued;
-      const overflowText = overflowParts.join(", ");
-      lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("dim", `+${hiddenTotal} more (${overflowText})`)}`)
-      );
-    }
+      for (const row of visibleRows) lines.push(...row.lines);
+      if (visibleRows.length > 0) {
+        const lastRow = visibleRows[visibleRows.length - 1];
+        const lastStart = lines.length - lastRow.lines.length;
+        lines[lastStart] = lines[lastStart].replace("├─", "└─");
+        if (lastRow.lines.length === 2) {
+          lines[lastStart + 1] = lines[lastStart + 1].replace("│  ", "   ");
+        }
+      }
+
+      const hiddenCount = (rows: readonly WidgetRow[]): number =>
+        rows.reduce((total, row) => total + (row.recordCount ?? 1), 0);
+      const categoryCount = (status: string): number => hiddenRows
+        .filter(row => row.record.status === status)
+        .reduce((total, row) => total + (row.recordCount ?? 1), 0);
+      const finishedCount = hiddenRows
+        .filter(row => row.record.status !== "running" && row.record.status !== "queued")
+        .reduce((total, row) => total + (row.recordCount ?? 1), 0);
+      const categoryCounts: string[] = [
+        ["running", categoryCount("running")] as [string, number],
+        ["queued", categoryCount("queued")] as [string, number],
+        ["finished", finishedCount] as [string, number],
+      ].filter(([, count]) => count > 0).map(([label, count]) => `${count} ${label}`);
+      const hidden = hiddenCount(hiddenRows);
+      lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("dim", `+${hidden} more (${categoryCounts.join(", ")})`)}`));
+    } else {
+      // Reserve one line for a directional overflow summary. The viewport is
+      // a contiguous slice in roster order, so the same slice is navigable and
+      // renderable even when the selected row is currently hidden.
+      const baseContentBudget = Math.max(0, maxBody - 1);
+      const heightAt = (index: number) => rows[index]?.lines.length ?? 0;
+      const endFor = (start: number, budget: number): number => {
+        let used = 0;
+        let end = start;
+        while (end < rows.length && used + heightAt(end) <= budget) {
+          used += heightAt(end++);
+        }
+        return end;
+      };
 
-    if (this.navigationActive) {
-      const roster = this.navigationAgents();
-      const selected = roster[this.selectedRosterIndex];
-      const hasSelected = selected ? lines.some(line => line.includes(selected.description.replace(/[\r\n]+/g, " "))) : true;
-      if (selected && !hasSelected) {
-        const selectedLine = truncate(theme.fg("dim", "└─") + ` ${this.selectionBullet(selected.id, theme)} ${selected.status === "queued" ? "◦" : "⠋"} ${theme.fg("muted", selected.description.replace(/[\r\n]+/g, " "))}`);
-        if (lines.length >= budget) lines[lines.length - 1] = selectedLine;
-        else lines.push(selectedLine);
+      let start = Math.max(0, Math.min(this.viewportStart, Math.max(0, rows.length - 1)));
+      const selectedIndex = this.navigationActive && selectedId
+        ? rows.findIndex(row => row.record.id === selectedId)
+        : -1;
+      if (selectedIndex >= 0) {
+        if (selectedIndex < start) start = selectedIndex;
+        if (selectedIndex >= endFor(start, baseContentBudget)) start = selectedIndex;
       }
-      if (this.viewportStart > 0) {
-        if (lines.length >= budget) lines.splice(1, 1, truncate(theme.fg("dim", "↑ more")));
-        else lines.splice(1, 0, truncate(theme.fg("dim", "↑ more")));
+
+      // Keep both directional affordances in the viewport chrome: the top
+      // count sits below the heading and the bottom count sits below the
+      // bounded roster. Each consumes one row when that direction is hidden.
+      let showTopMore = start > 0;
+      let contentBudget = Math.max(0, maxBody - (showTopMore ? 2 : 1));
+      if (selectedIndex >= 0 && selectedIndex >= endFor(start, contentBudget)) {
+        start = selectedIndex;
+        showTopMore = start > 0;
+        contentBudget = Math.max(0, maxBody - (showTopMore ? 2 : 1));
+      }
+      this.viewportStart = start;
+
+      let used = 0;
+      let end = start;
+      const visibleBody: string[] = [];
+      while (end < rows.length && used + heightAt(end) <= contentBudget) {
+        visibleBody.push(...rows[end].lines);
+        used += heightAt(end);
+        end++;
+      }
+      // A selected two-line row must remain addressable even if only one body
+      // line is available. Showing its header is preferable to hiding it.
+      if (end === start && rows[start] && contentBudget > 0) {
+        visibleBody.push(rows[start].lines[0]);
+        end = start + 1;
+      }
+
+      const countRows = (selectedRows: readonly WidgetRow[]): number =>
+        selectedRows.reduce((total, row) => total + (row.recordCount ?? 1), 0);
+      const hiddenBefore = countRows(rows.slice(0, start));
+      const hiddenAfter = countRows(rows.slice(end));
+      const hidden = hiddenBefore + hiddenAfter;
+      const hiddenRows = rows.filter((_row, index) => index < start || index >= end);
+      const categoryCount = (status: string): number => hiddenRows
+        .filter(row => row.record.status === status)
+        .reduce((total, row) => total + (row.recordCount ?? 1), 0);
+      const categoryCounts: string[] = [
+        ["running", categoryCount("running")] as [string, number],
+        ["queued", categoryCount("queued")] as [string, number],
+        ["finished", hiddenRows
+          .filter(row => row.record.status !== "running" && row.record.status !== "queued")
+          .reduce((total, row) => total + (row.recordCount ?? 1), 0)] as [string, number],
+      ].filter(([, count]) => count > 0).map(([label, count]) => `${count} ${label}`);
+      const direction = [
+        ...(hiddenBefore > 0 ? [`↑ ${hiddenBefore} more`] : []),
+        ...(hiddenAfter > 0 ? [`↓ ${hiddenAfter} more`] : []),
+      ].join(" · ");
+      const summary = `+${hidden} more (${direction}${categoryCounts.length > 0 ? `; ${categoryCounts.join(", ")}` : ""})`;
+
+      if (showTopMore) lines.push(truncate(theme.fg("dim", `↑ ${hiddenBefore} more`)));
+
+      // Fill the bounded viewport so the scrollbar track has a stable height.
+      while (visibleBody.length < contentBudget) visibleBody.push("");
+      const totalBody = rows.reduce((total, row) => total + row.lines.length, 0);
+      const startOffset = rows.slice(0, start).reduce((total, row) => total + row.lines.length, 0);
+      const trackHeight = Math.max(0, contentBudget);
+      const minThumbHeight = Math.min(2, trackHeight);
+      const thumbHeight = Math.max(
+        minThumbHeight,
+        Math.min(trackHeight, Math.round((trackHeight * trackHeight) / totalBody)),
+      );
+      const maxScrollTop = Math.max(0, totalBody - trackHeight);
+      const maxThumbTop = Math.max(0, trackHeight - thumbHeight);
+      const thumbOffset = maxScrollTop === 0
+        ? 0
+        : Math.round((startOffset / maxScrollTop) * maxThumbTop);
+      const contentWidth = Math.max(0, w - 1);
+      for (let index = 0; index < visibleBody.length; index++) {
+        const isThumb = index >= thumbOffset && index < thumbOffset + thumbHeight;
+        const scrollbar = isThumb
+          ? theme.fg("scrollbarThumb", this.navigationActive ? "█" : "┃")
+          : theme.fg("scrollbarTrack", "│");
+        const bodyLine = truncate(visibleBody[index] ?? "", contentWidth);
+        lines.push(bodyLine + " ".repeat(Math.max(0, contentWidth - visibleWidth(bodyLine))) + scrollbar);
       }
-      const railStart = this.viewportStart > 0 ? 2 : 1;
-      for (let index = railStart; index < lines.length; index++) {
-        const plain = lines[index] ?? "";
-        lines[index] = truncate(plain + (selected && plain.includes(selected.description.replace(/[\r\n]+/g, " ")) ? "┃" : "│"));
+
+      // The directional count is outside the viewport, like ScrollView's
+      // surrounding chrome, and therefore does not consume scrollbar track.
+      if (hiddenAfter > 0) {
+        lines.push(truncate(theme.fg("dim", `↓ ${hiddenAfter} more · +${hidden} more (${categoryCounts.length > 0 ? categoryCounts.join(", ") : ""})`)));
+      } else if (!showTopMore) {
+        lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("dim", summary)}`));
+      } else {
+        // Keep a stable footer row when the selected viewport reaches the end.
+        lines.push(truncate(theme.fg("dim", "└─")));
       }
-      if (lines.length > budget) lines.length = budget;
     }
+
     return lines;
   }
 
-  /** Force an immediate widget update. */
+  /** Build a render-relevant snapshot without capturing mutable records. */
+  private renderKey(allAgents: ReturnType<AgentManager["listAgents"]>): string {
+    const activities = allAgents.map(a => {
+      const activity = this.agentActivity.get(a.id);
+      return activity ? {
+        id: a.id,
+        activeTools: [...activity.activeTools.entries()],
+        toolUses: activity.toolUses,
+        responseText: activity.responseText,
+        turnCount: activity.turnCount,
+        maxTurns: activity.maxTurns,
+        lifetimeUsage: activity.lifetimeUsage,
+        contextPercent: getSessionContextPercent(activity.session),
+      } : undefined;
+    });
+    return JSON.stringify({
+      frame: this.widgetFrame,
+      agents: allAgents.map(a => ({
+        id: a.id,
+        type: a.type,
+        description: a.description,
+        status: a.status,
+        toolUses: a.toolUses,
+        startedAt: a.startedAt,
+        completedAt: a.completedAt,
+        error: a.error,
+        lifetimeUsage: a.lifetimeUsage,
+        compactionCount: a.compactionCount,
+        isBackground: a.isBackground,
+        hasSession: a.session !== undefined,
+        transcriptPath: a.transcriptPath,
+        openableHistory: this.cachedCanOpenHistory(a),
+      })),
+      activities,
+      navigationActive: this.navigationActive,
+      selectedAgentId: this.selectedAgentId,
+      viewportStart: this.viewportStart,
+    });
+  }
+
+  /** Force an immediate widget update. `advanceSpinner` is reserved for the timer. */
   update(advanceSpinner = false) {
     if (!this.uiCtx) return;
+    // Refresh the manager snapshot once per lifecycle update. Arrow handling
+    // only changes selection and requests a render; it never scans the manager.
+    const roster = this.refreshRoster();
     const allAgents = this.widgetAgents();
-    if (this.navigationActive || this.selectedAgentId) {
-      const roster = this.navigationAgents();
-      const selectedIndex = this.selectedAgentId ? roster.findIndex(agent => agent.id === this.selectedAgentId) : -1;
-      if (selectedIndex >= 0) {
-        this.selectedRosterIndex = selectedIndex;
-      } else if (roster.length > 0 && this.selectedAgentId) {
-        this.selectedRosterIndex = Math.min(this.selectedRosterIndex, roster.length - 1);
-        this.selectedAgentId = roster[this.selectedRosterIndex]?.id;
-      } else if (roster.length === 0) {
-        this.navigationActive = false;
-        this.selectedAgentId = undefined;
-        this.selectedRosterIndex = 0;
-        this.viewportStart = 0;
-      }
-      this.updateViewport(roster);
-    }
 
     // Lightweight existence checks — full categorization happens in renderWidget()
     let runningCount = 0;
     let queuedCount = 0;
-    let hasFinished = false;
-    for (const a of allAgents) {
-      if (a.status === "running") { runningCount++; }
-      else if (a.status === "queued") { queuedCount++; }
-      else if (a.completedAt && this.shouldShowFinished(a.id, a.status, a.transcriptPath !== undefined)) { hasFinished = true; }
+    for (const a of roster) {
+      if (a.status === "running") runningCount++;
+      else if (a.status === "queued") queuedCount++;
     }
+    const hasFinished = roster.some(a => a.status !== "running" && a.status !== "queued");
     const hasActive = runningCount > 0 || queuedCount > 0;
 
     // Nothing to show — clear widget
@@ -798,11 +1024,12 @@ export class AgentWidget {
         this.uiCtx.setStatus("subagents", undefined);
         this.lastStatusText = undefined;
       }
-      if (this.widgetInterval) { clearInterval(this.widgetInterval); this.widgetInterval = undefined; }
-      // Clean up stale entries
-      for (const [id] of this.finishedTurnAge) {
-        if (!allAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
-      }
+      this.lastRenderKey = undefined;
+      this.navigationActive = false;
+      this.selectedAgentId = undefined;
+      this.selectedRosterIndex = 0;
+      this.viewportStart = 0;
+      this.syncTimer(false);
       return;
     }
 
@@ -820,26 +1047,30 @@ export class AgentWidget {
       this.lastStatusText = newStatusText;
     }
 
+    // Spinner animation is driven only by the timer while a visible running
+    // agent exists. Event-driven updates refresh changed stats without making
+    // an otherwise idle widget advance.
     if (advanceSpinner && runningCount > 0) this.widgetFrame++;
-
-    const snapshot = allAgents.map(agent => {
-      const activity = this.agentActivity.get(agent.id);
-      return [
-        agent.id,
-        agent.status,
-        agent.description,
-        agent.toolUses,
-        agent.completedAt ?? "",
-        this.finishedTurnAge.get(agent.id) ?? "",
-        getLifetimeTotal(agent.lifetimeUsage),
-        activity?.toolUses ?? "",
-        activity?.responseText ?? "",
-        Math.floor((Date.now() - agent.startedAt) / 1000),
-      ].join("\u0000");
-    }).join("\u0001");
-    if (this.widgetRegistered && snapshot === this.lastSnapshot && !advanceSpinner) return;
-    this.lastSnapshot = snapshot;
-    if (!advanceSpinner) this.widgetFrame++;
+    this.syncTimer(runningCount > 0);
+    const selectedIndex = this.selectedIndexOf(roster);
+    if (selectedIndex >= 0) {
+      this.selectedRosterIndex = selectedIndex;
+    } else if (this.navigationActive) {
+      if (roster.length === 0) {
+        this.navigationActive = false;
+        this.selectedAgentId = undefined;
+        this.selectedRosterIndex = 0;
+        this.viewportStart = 0;
+      } else {
+        // Keep the selection near the row that disappeared. Both the saved
+        // logical index and viewport are clamped as the roster shrinks.
+        const fallbackIndex = Math.max(0, Math.min(this.selectedRosterIndex, roster.length - 1));
+        this.selectedAgentId = roster[fallbackIndex].id;
+        this.selectedRosterIndex = fallbackIndex;
+        this.viewportStart = Math.min(this.viewportStart, roster.length - 1);
+      }
+    }
+    const renderKey = this.renderKey(allAgents);
 
     // Register widget callback once; subsequent updates use requestRender()
     // which re-invokes render() without replacing the component (avoids layout thrashing).
@@ -852,23 +1083,20 @@ export class AgentWidget {
             // Theme changed — force re-registration so factory captures fresh theme.
             this.widgetRegistered = false;
             this.tui = undefined;
+            this.lastRenderKey = undefined;
           },
         };
       }, { placement: "aboveEditor" });
       this.widgetRegistered = true;
-    } else {
-      // Widget already registered — just request a re-render of existing components.
+    } else if (renderKey !== this.lastRenderKey) {
+      // Widget already registered — request a re-render only when visible state
+      // changed (or the spinner timer advanced).
       this.tui?.requestRender();
     }
+    this.lastRenderKey = renderKey;
   }
 
   dispose() {
-    this.inputCleanup?.();
-    this.inputCleanup = undefined;
-    this.navigationActive = false;
-    this.selectedAgentId = undefined;
-    this.viewportStart = 0;
-    this.selectedRosterIndex = 0;
     if (this.widgetInterval) {
       clearInterval(this.widgetInterval);
       this.widgetInterval = undefined;
@@ -877,9 +1105,22 @@ export class AgentWidget {
       this.uiCtx.setWidget("agents", undefined);
       this.uiCtx.setStatus("subagents", undefined);
     }
+    this.inputUnsub?.();
+    this.inputUnsub = undefined;
     this.widgetRegistered = false;
     this.tui = undefined;
     this.lastStatusText = undefined;
-    this.lastSnapshot = "";
+    this.lastRenderKey = undefined;
+    this.navigationSuspensionDepth = 0;
+    this.navigationActive = false;
+    this.selectedAgentId = undefined;
+    this.selectedRosterIndex = 0;
+    this.viewportStart = 0;
+    this.cachedAgents = [];
+    this.cachedRoster = [];
+    this.rosterCacheKey = undefined;
+    this.rosterCacheInitialized = false;
+    this.historyOpenabilityCache.clear();
+    this.uiCtx = undefined;
   }
 }