@esso0428/pi-subagents 0.15.16 → 0.15.17

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.17] - 2026-09-14
+
+### Fixed
+- **FleetView preserves the selected row while navigating** by maintaining a bounded viewport over the full roster; `j`/`k`, arrow keys, and normalized wheel input share one directional transition and consume handled wheel events without stealing input from other focused components.
+- **Structural Fleet/widget changes refresh the text-input viewport after a short defer** instead of requiring a manual redraw; refreshes coalesce, respect a maximum wait, cancel on session switch, and dispose before shutdown cleanup.
+
 ## [0.15.16] - 2026-09-13
 
 ### Added

package/README.md

@@ -15,7 +15,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`Agent`, `get_subagent_result`, `steer_subagent`) — feels native
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and smart group join (consolidated notifications)
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons. Configurable via `/agents → Settings → Widget`: `all` (every agent), `background` (default — hides foreground runs, which already render inline as the `Agent` tool result), or `off`
-- **FleetView** — Claude Code-style navigable list of `main` + every running subagent rendered below the editor (earliest-launched first). Press `↓` (or `←`) at an empty prompt to jump in, `↑`/`↓` to move the selection, `Enter` to open the selected agent's live, auto-updating conversation, `Esc` to return. Finished agents linger briefly before dropping out, and a viewer stays open through completion so you can read the final output. Toggle via `/agents → Settings → Fleet view`
+- **FleetView** — Claude Code-style navigable list of `main` + every running subagent rendered below the editor (earliest-launched first). Press `↓` (or `←`) at an empty prompt to jump in, `↑`/`↓`/wheel to move the selection, `Enter` to open the selected agent's live, auto-updating conversation, `Esc` to return. The selected row stays visible while the bounded list window moves through the full roster. Finished agents linger briefly before dropping out, and a viewer stays open through completion so you can read the final output. Toggle via `/agents → Settings → Fleet view`
 - **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause). Steer a running agent inline by pressing `Enter` to open a composer, typing, then `Enter` to send (`Esc` or an empty submit returns) — the message appears as a user message and redirects the agent after its current tool. Stop a still-running agent by pressing `x` (then `x` again to confirm) — both work for background agents too
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` or `.agents/agents/<name>.md` (project) or globally, with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.15.16",
+  "version": "0.15.17",
   "description": "A pi extension that brings smart Claude Code-style autonomous sub-agents to pi, with npm:pi-subagents-style JSON agent overrides.",
   "author": "ESSO0428",
   "repository": {

package/src/index.ts

@@ -50,6 +50,7 @@ import {
   type UICtx,
 } from "./ui/agent-widget.js";
 import { FleetList, type FleetUICtx } from "./ui/fleet-list.js";
+import { createDeferredUiRefresh } from "./ui/deferred-ui-refresh.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
 
@@ -374,6 +375,7 @@ export default function (pi: ExtensionAPI) {
     fleet.onAgentFinished(record.id);
     scheduleNudge(record.id, () => emitIndividualNudge(record));
     widget.update();
+    scheduleUiRefresh();
   }
 
   // ---- Group join manager ----
@@ -385,7 +387,11 @@ export default function (pi: ExtensionAPI) {
       scheduleNudge(groupKey, () => {
         // Re-check at send time
         const unconsumed = records.filter(r => !r.resultConsumed);
-        if (unconsumed.length === 0) { widget.update(); return; }
+        if (unconsumed.length === 0) {
+          widget.update();
+          scheduleUiRefresh();
+          return;
+        }
 
         const notifications = unconsumed.map(r => formatTaskNotification(r, 300)).join('\n\n');
         const label = partial
@@ -406,6 +412,7 @@ export default function (pi: ExtensionAPI) {
         }, { deliverAs: "followUp", triggerTurn: true });
       });
       widget.update();
+      scheduleUiRefresh();
     },
     30_000,
   );
@@ -463,6 +470,7 @@ export default function (pi: ExtensionAPI) {
       widget.markFinished(record.id);
       fleet.onAgentFinished(record.id);
       widget.update();
+      scheduleUiRefresh();
       return;
     }
 
@@ -470,6 +478,7 @@ export default function (pi: ExtensionAPI) {
     // don't send an individual nudge — finalizeBatch will pick it up retroactively.
     if (currentBatchAgents.some(a => a.id === record.id)) {
       widget.update();
+      scheduleUiRefresh();
       return;
     }
 
@@ -480,6 +489,7 @@ export default function (pi: ExtensionAPI) {
     // 'held' → do nothing, group will fire later
     // 'delivered' → group callback already fired
     widget.update();
+    scheduleUiRefresh();
   }, undefined, (record) => {
     // Emit started event when agent transitions to running (including from queue)
     pi.events.emit("subagents:started", {
@@ -487,6 +497,11 @@ export default function (pi: ExtensionAPI) {
       type: record.type,
       description: record.description,
     });
+    widget.ensureTimer();
+    widget.update();
+    fleet.ensureTimer();
+    fleet.update();
+    scheduleUiRefresh();
   }, (record, info) => {
     // Emit compacted event when agent's session compacts (preserves count on record).
     pi.events.emit("subagents:compacted", {
@@ -581,6 +596,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_before_switch", () => {
+    deferredUiRefresh.cancel();
     manager.clearCompleted(true);
     scheduler.stop();
   });
@@ -602,6 +618,7 @@ export default function (pi: ExtensionAPI) {
     manager.abortAll();
     for (const timer of pendingNudges.values()) clearTimeout(timer);
     pendingNudges.clear();
+    deferredUiRefresh.dispose();
     fleet.dispose();
     manager.dispose();
   });
@@ -614,13 +631,34 @@ export default function (pi: ExtensionAPI) {
   let widgetMode: WidgetMode = "background";
   function getWidgetMode(): WidgetMode { return widgetMode; }
   const widget = new AgentWidget(manager, agentActivity, getWidgetMode);
-  function setWidgetMode(m: WidgetMode): void { widgetMode = m; widget.update(); }
+  function setWidgetMode(m: WidgetMode): void {
+    const changed = widgetMode !== m;
+    widgetMode = m;
+    widget.update();
+    if (changed) scheduleUiRefresh();
+  }
 
   // Claude Code-style FleetView: navigable list of main + subagents below the editor.
   const fleet = new FleetList(manager, agentActivity, () => currentCtx?.cwd, pi, () => currentCtx);
+
+  // One render-only scheduler is shared by both widgets. The callback resolves
+  // the live TUI target at fire time because session switches invalidate the
+  // previous widget context; both widgets use the same TUI, so one successful
+  // request is sufficient.
+  const deferredUiRefresh = createDeferredUiRefresh(() => {
+    if (widget.requestUiRefresh(true)) return;
+    fleet.requestUiRefresh(true);
+  });
+  const scheduleUiRefresh = (): void => deferredUiRefresh.schedule();
+
   let fleetViewEnabled = true;
   function isFleetViewEnabled(): boolean { return fleetViewEnabled; }
-  function setFleetViewEnabled(b: boolean): void { fleetViewEnabled = b; fleet.setEnabled(b); }
+  function setFleetViewEnabled(b: boolean): void {
+    const changed = fleetViewEnabled !== b;
+    fleetViewEnabled = b;
+    fleet.setEnabled(b);
+    if (changed) scheduleUiRefresh();
+  }
 
   // Project/global default for writing the subagent .output transcript. A custom
   // agent's `output_transcript` frontmatter overrides this per spawn; when the
@@ -720,8 +758,9 @@ export default function (pi: ExtensionAPI) {
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
   pi.on("tool_execution_start", async (_event, ctx) => {
-    widget.setUICtx(ctx.ui as UICtx);
-    fleet.setUICtx(ctx.ui as unknown as FleetUICtx);
+    const widgetContextChanged = widget.setUICtx(ctx.ui as UICtx);
+    const fleetContextChanged = fleet.setUICtx(ctx.ui as unknown as FleetUICtx);
+    if (widgetContextChanged || fleetContextChanged) scheduleUiRefresh();
     widget.onTurnStart();
   });
 
@@ -1319,6 +1358,7 @@ Terse command-style prompts produce shallow, generic work.
         widget.update();
         fleet.ensureTimer();
         fleet.update();
+        scheduleUiRefresh();
 
         // Emit created event
         pi.events.emit("subagents:created", {
@@ -1379,8 +1419,10 @@ Terse command-style prompts produce shallow, generic work.
             fgId = a.id;
             agentActivity.set(a.id, fgState);
             widget.ensureTimer();
+            widget.update();
             fleet.ensureTimer();
             fleet.update();
+            scheduleUiRefresh();
             break;
           }
         }

package/src/ui/agent-widget.ts

@@ -275,16 +275,24 @@ export class AgentWidget {
   }
 
   /** Set the UI context (grabbed from first tool execution). */
-  setUICtx(ctx: UICtx) {
-    if (ctx !== this.uiCtx) {
-      // UICtx changed — the widget registered on the old context is gone.
-      // Force re-registration on next update().
-      this.uiCtx = ctx;
-      this.widgetRegistered = false;
-      this.tui = undefined;
-      this.lastStatusText = undefined;
-      this.lastRenderKey = undefined;
-    }
+  setUICtx(ctx: UICtx): boolean {
+    if (ctx === this.uiCtx) return false;
+
+    // UICtx changed — the widget registered on the old context is gone.
+    // Force re-registration on next update().
+    this.uiCtx = ctx;
+    this.widgetRegistered = false;
+    this.tui = undefined;
+    this.lastStatusText = undefined;
+    this.lastRenderKey = undefined;
+    return true;
+  }
+
+  /** Request a render on the currently registered TUI without touching input. */
+  requestUiRefresh(force = true): boolean {
+    if (!this.tui) return false;
+    this.tui.requestRender(force);
+    return true;
   }
 
   /**

package/src/ui/deferred-ui-refresh.ts

@@ -0,0 +1,72 @@
+/** Coalesced, deferred render requests for structural UI changes. */
+
+const DEFAULT_DELAY_MS = 50;
+const DEFAULT_MAX_WAIT_MS = 200;
+
+export interface DeferredUiRefresh {
+  /** Schedule one render request after the debounce/max-wait window. */
+  schedule(): void;
+  /** Cancel the current pending render request, if any. */
+  cancel(): void;
+  /** Cancel and permanently disable this scheduler. */
+  dispose(): void;
+}
+
+export function createDeferredUiRefresh(
+  requestRender: () => void,
+  options: {
+    delayMs?: number;
+    maxWaitMs?: number;
+    now?: () => number;
+  } = {},
+): DeferredUiRefresh {
+  const delayMs = Math.max(0, options.delayMs ?? DEFAULT_DELAY_MS);
+  const maxWaitMs = Math.max(0, options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS);
+  const now = options.now ?? Date.now;
+
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+  let firstScheduledAt: number | undefined;
+  let disposed = false;
+
+  const clearPendingTimer = () => {
+    if (debounceTimer !== undefined) {
+      clearTimeout(debounceTimer);
+      debounceTimer = undefined;
+    }
+  };
+
+  const flush = () => {
+    // Clear all state before invoking user code. A render callback may schedule
+    // another refresh, which should begin a fresh debounce window.
+    clearPendingTimer();
+    firstScheduledAt = undefined;
+    if (disposed) return;
+    requestRender();
+  };
+
+  const schedule = () => {
+    if (disposed) return;
+
+    const current = now();
+    if (firstScheduledAt === undefined) firstScheduledAt = current;
+
+    clearPendingTimer();
+    const maxDeadline = firstScheduledAt + maxWaitMs;
+    const remainingMaxWait = Math.max(0, maxDeadline - current);
+    const wait = Math.min(delayMs, remainingMaxWait);
+    debounceTimer = setTimeout(flush, wait);
+  };
+
+  const cancel = () => {
+    clearPendingTimer();
+    firstScheduledAt = undefined;
+  };
+
+  const dispose = () => {
+    if (disposed) return;
+    cancel();
+    disposed = true;
+  };
+
+  return { schedule, cancel, dispose };
+}

package/src/ui/fleet-list.ts

@@ -2,7 +2,7 @@
  * fleet-list.ts — Claude Code-style "FleetView" list rendered below the editor.
  *
  * Shows `main` + each running/queued subagent as a navigable list. Pressing ↓ (or
- * ←) at an empty prompt activates the list; ↑/↓ move the selection (filled ● marker),
+ * `j`) at an empty prompt activates the list; ↑/↓ move the selection (filled ● marker),
  * Enter opens the selected agent's live conversation overlay, Esc returns to the prompt.
  * A viewer stays open when its agent finishes so the final output remains readable.
  *
@@ -28,11 +28,23 @@ const FLEET_BASE_ROWS = 2; // hint + main
 const FLEET_BODY_ROWS = FLEET_MAX_RENDER_ROWS - FLEET_BASE_ROWS;
 /** Re-render cadence so elapsed/token stats tick while agents run. */
 const TICK_MS = 200;
+/** Normalized mouse input accepted by FleetView's widget surface. */
+export type FleetMouseEvent = { type: string; wheelDelta?: number };
+
+type FleetMouseResult = { handled: true; render: true };
+
+type FleetWidgetContent = {
+  render(width: number): string[];
+  invalidate(): void;
+  dispose?(): void;
+  handleMouse?(event: FleetMouseEvent): FleetMouseResult | undefined;
+};
+
 /** Minimal UI surface the FleetView needs from `ctx.ui` (structural subset). */
 export type FleetUICtx = {
   setWidget(
     key: string,
-    content: undefined | ((tui: any, theme: Theme) => { render(width: number): string[]; invalidate(): void; dispose?(): void }),
+    content: undefined | ((tui: any, theme: Theme) => FleetWidgetContent),
     options?: { placement?: "aboveEditor" | "belowEditor" },
   ): void;
   onTerminalInput(handler: (data: string) => { consume?: boolean; data?: string } | undefined): () => void;
@@ -62,30 +74,70 @@ export function formatFleetTokens(count: number): string {
   return `↓ ${compact} tokens`;
 }
 
+/** A bounded slice of the agent-only roster rendered by FleetView. */
+export type FleetAgentWindow = {
+  start: number;
+  end: number;
+  hiddenAbove: number;
+  hiddenBelow: number;
+};
+
 /**
- * Calculate a bounded agent slice for the complete logical roster.
- * `selectedRosterIndex` includes main at index 0; `end` is exclusive.
+ * Calculate a bounded agent slice from an agent-only viewport start.
+ * `end` is exclusive; `main` is rendered separately and is not part of this
+ * window. Marker rows are reserved only when the corresponding side is hidden.
  */
 export function calculateFleetAgentWindow(
   agentCount: number,
-  selectedRosterIndex: number,
-): { start: number; end: number; hiddenAbove: number; hiddenBelow: number } {
+  viewportStart: number,
+): FleetAgentWindow {
   const count = Math.max(0, Math.floor(agentCount));
   if (count === 0) return { start: 0, end: 0, hiddenAbove: 0, hiddenBelow: 0 };
 
-  const selectedAgent = Math.min(
+  const maxStart = Math.max(0, count - (FLEET_BODY_ROWS - 1));
+  const start = Math.min(maxStart, Math.max(0, Math.floor(viewportStart)));
+  const hasAbove = start > 0;
+  const agentBudget = Math.max(1, FLEET_BODY_ROWS - (hasAbove ? 1 : 0));
+  let end = Math.min(count, start + agentBudget);
+  if (end < count) end -= 1; // reserve the ↓ marker row
+
+  return {
+    start,
+    end,
+    hiddenAbove: start,
+    hiddenBelow: count - end,
+  };
+}
+
+/**
+ * Return the smallest viewport adjustment that makes an agent visible. The
+ * selected index is 0-based within the agent-only roster; `main` is handled by
+ * FleetList rather than this pure helper.
+ */
+export function ensureFleetSelectionVisible(
+  agentCount: number,
+  selectedAgentIndex: number,
+  viewportStart: number,
+): number {
+  const count = Math.max(0, Math.floor(agentCount));
+  if (count === 0) return 0;
+
+  const selected = Math.min(
     count - 1,
-    Math.max(0, Math.floor(selectedRosterIndex) - 1),
-  );
-  const reserveAbove = selectedAgent > 0 ? 1 : 0;
-  const reserveBelow = selectedAgent < count - 1 ? 1 : 0;
-  const visibleCount = Math.max(1, FLEET_BODY_ROWS - reserveAbove - reserveBelow);
-  const start = Math.min(
-    Math.max(0, selectedAgent - visibleCount + 1),
-    Math.max(0, count - visibleCount),
+    Math.max(0, Math.floor(selectedAgentIndex)),
   );
-  const end = Math.min(count, start + visibleCount);
-  return { start, end, hiddenAbove: start, hiddenBelow: count - end };
+  const maxStart = Math.max(0, count - (FLEET_BODY_ROWS - 1));
+  let start = Math.min(maxStart, Math.max(0, Math.floor(viewportStart)));
+  const current = calculateFleetAgentWindow(count, start);
+
+  if (selected < current.start) {
+    return Math.min(maxStart, selected);
+  }
+  if (selected < current.end) return start;
+
+  // With a possible ↓ marker, selected - 1 is the least forward shift that
+  // exposes the selected row while preserving the marker row budget.
+  return Math.min(maxStart, Math.max(start, selected - 1));
 }
 
 /**
@@ -115,6 +167,8 @@ export class FleetList {
   private active = false;
   /** 0 = `main`, 1..N = subagents. */
   private selectedIndex = 0;
+  /** 0-based start in the agent-only roster; main is rendered separately. */
+  private viewportStart = 0;
   /** Set while a conversation overlay is open; calling it closes the overlay. */
   private viewerClose: (() => void) | undefined;
   private viewingAgentId: string | undefined;
@@ -137,8 +191,8 @@ export class FleetList {
   }
 
   /** Capture the UI context and (re)register the global input handler. */
-  setUICtx(ui: FleetUICtx): void {
-    if (ui === this.ui) return;
+  setUICtx(ui: FleetUICtx): boolean {
+    if (ui === this.ui) return false;
     this.inputUnsub?.();
     this.ui = ui;
     this.widgetRegistered = false;
@@ -146,6 +200,14 @@ export class FleetList {
     this.lastRenderKey = undefined;
     this.tui = undefined;
     this.inputUnsub = ui.onTerminalInput(data => this.handleKey(data));
+    return true;
+  }
+
+  /** Request a render on the currently registered TUI without touching input. */
+  requestUiRefresh(force = true): boolean {
+    if (!this.tui) return false;
+    this.tui.requestRender(force);
+    return true;
   }
 
   /** Ensure the re-render timer is running (called when an agent spawns). */
@@ -173,6 +235,8 @@ export class FleetList {
     this.lastRenderKey = undefined;
     this.tui = undefined;
     this.active = false;
+    this.selectedIndex = 0;
+    this.viewportStart = 0;
     // Null last so a `viewerClose()` microtask above can't re-register the widget.
     this.ui = undefined;
   }
@@ -195,12 +259,14 @@ export class FleetList {
       if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
       this.active = false;
       this.selectedIndex = 0;
+      this.viewportStart = 0;
       this.lastRosterKey = undefined;
       this.lastRenderKey = undefined;
       return;
     }
 
     this.clampSelection();
+    this.ensureSelectionVisible();
     this.ensureTimer(); // keep stats ticking whenever the list is shown (e.g. after a re-enable)
     const renderKey = this.renderKey(records);
 
@@ -210,6 +276,7 @@ export class FleetList {
         return {
           render: (w: number) => this.renderBar(w, theme),
           invalidate: () => { this.widgetRegistered = false; this.tui = undefined; },
+          handleMouse: (event: FleetMouseEvent) => this.handleMouse(event),
         };
       }, { placement: "belowEditor" });
       this.widgetRegistered = true;
@@ -243,7 +310,13 @@ export class FleetList {
         Math.round(((record.completedAt ?? now) - record.startedAt) / 1000),
       ].join("\u001f");
     });
-    return [this.enabled ? "1" : "0", this.active ? "1" : "0", String(this.selectedIndex), ...agentState].join("\u001e");
+    return [
+      this.enabled ? "1" : "0",
+      this.active ? "1" : "0",
+      String(this.selectedIndex),
+      String(this.viewportStart),
+      ...agentState,
+    ].join("\u001e");
   }
 
   // ---- Roster ----
@@ -270,8 +343,84 @@ export class FleetList {
     if (this.selectedIndex < 0) this.selectedIndex = 0;
   }
 
+  /** Keep the selected agent visible without recentering an already-valid window. */
+  private ensureSelectionVisible(): void {
+    const agents = this.agentRecords();
+    if (agents.length === 0) {
+      this.viewportStart = 0;
+      return;
+    }
+    if (this.selectedIndex > 0) {
+      this.viewportStart = ensureFleetSelectionVisible(
+        agents.length,
+        this.selectedIndex - 1,
+        this.viewportStart,
+      );
+      return;
+    }
+    // `main` does not constrain the agent window, but a roster shrink can make
+    // its previous start invalid. Use the same pure clamp as renderBar.
+    this.viewportStart = calculateFleetAgentWindow(agents.length, this.viewportStart).start;
+  }
+
   // ---- Key handling ----
 
+  /**
+   * Move the selection while keeping keyboard and wheel input on one path.
+   * Returns whether the direction was handled; inactive upward input and input
+   * that cannot activate the list are left for the editor/transcript.
+   */
+  private moveSelection(direction: -1 | 1): boolean {
+    const max = this.roster().length - 1;
+    if (max < 0) return false;
+
+    if (!this.active) {
+      // Match ↓ activation: only a downward direction at an empty prompt with
+      // the editor focused enters the list. Upward input remains a no-op.
+      if (direction !== 1 || !this.editorHasFocus() || this.agentRecords().length === 0 || this.ui?.getEditorText() !== "") {
+        return false;
+      }
+      this.active = true;
+      this.selectedIndex = 0;
+      this.viewportStart = 0;
+      this.update();
+      return true;
+    }
+
+    this.clampSelection();
+    if (direction === -1 && this.selectedIndex === 0) {
+      this.deactivate();
+      return true;
+    }
+    this.selectedIndex = direction === 1
+      ? Math.min(max, this.selectedIndex + 1)
+      : Math.max(0, this.selectedIndex - 1);
+    this.ensureSelectionVisible();
+    this.update();
+    return true;
+  }
+
+  /** Handle normalized wheel input from the registered widget. */
+  handleMouse(event: FleetMouseEvent): FleetMouseResult | undefined {
+    if (!this.enabled || !this.ui || this.viewerClose) return undefined;
+    if (event.type !== "wheel") return undefined;
+
+    const wheelDelta = event.wheelDelta;
+    const direction: -1 | 1 | undefined = wheelDelta == null
+      ? undefined
+      : wheelDelta < 0
+        ? -1
+        : wheelDelta > 0
+          ? 1
+          : undefined;
+    if (!direction || !this.moveSelection(direction)) return undefined;
+
+    // The widget handled the normalized wheel, including at selection
+    // boundaries; explicitly request a redraw so it never falls through to
+    // Pi's transcript fallback.
+    return { handled: true, render: true };
+  }
+
   /** Returns `{consume:true}` to swallow a key, or undefined to let it through. */
   handleKey(data: string): { consume?: boolean; data?: string } | undefined {
     if (!this.enabled || !this.ui) return undefined;
@@ -290,31 +439,17 @@ export class FleetList {
       return undefined;
     }
 
-    if (!this.active) {
-      // Activate: ↓ or ← at an empty prompt moves focus into the list.
-      const isActivator = matchesKey(data, "down") || matchesKey(data, "left");
-      if (isActivator && this.agentRecords().length > 0 && this.ui.getEditorText() === "") {
-        this.active = true;
-        this.selectedIndex = 0;
-        this.update();
-        return { consume: true };
-      }
-      return undefined;
-    }
+    const direction: -1 | 1 | undefined = matchesKey(data, "down") || matchesKey(data, "j")
+      || (!this.active && matchesKey(data, "left"))
+      ? 1
+      : matchesKey(data, "up") || matchesKey(data, "k")
+        ? -1
+        : undefined;
+    if (direction && this.moveSelection(direction)) return { consume: true };
 
-    // Active — arrows navigate, Enter opens, Esc / Up-past-top exits.
-    if (matchesKey(data, "down")) {
-      const max = this.roster().length - 1;
-      this.selectedIndex = Math.min(max, this.selectedIndex + 1);
-      this.update();
-      return { consume: true };
-    }
-    if (matchesKey(data, "up")) {
-      if (this.selectedIndex === 0) { this.deactivate(); return { consume: true }; }
-      this.selectedIndex -= 1;
-      this.update();
-      return { consume: true };
-    }
+    if (!this.active) return undefined;
+
+    // Active — Enter opens, Esc / Up-past-top exits.
     if (matchesKey(data, "escape")) { this.deactivate(); return { consume: true }; }
     if (matchesKey(data, Key.enter)) { this.openSelected(); return { consume: true }; }
 
@@ -339,6 +474,7 @@ export class FleetList {
   private deactivate(): void {
     this.active = false;
     this.selectedIndex = 0;
+    this.viewportStart = 0;
     this.update();
   }
 
@@ -416,12 +552,12 @@ export class FleetList {
 
     const hint = this.active
       ? "↑↓ select · enter view · esc back"
-      : "esc to interrupt · ← for agents · ↓ to manage";
+      : "esc to interrupt · ↓ to manage";
     const lines: string[] = [];
     lines.push(truncateToWidth("  " + theme.fg("dim", hint), width));
     lines.push(truncateToWidth(`  ${this.bullet(0, sel, theme)} main`, width));
 
-    const window = calculateFleetAgentWindow(agents.length, sel);
+    const window = calculateFleetAgentWindow(agents.length, this.viewportStart);
     if (window.hiddenAbove > 0) {
       lines.push(rightAlign("", theme.fg("dim", `↑ ${window.hiddenAbove} more`), width));
     }

package/test/ui/agent-widget.test.ts

@@ -158,4 +158,15 @@ describe("AgentWidget live records", () => {
       vi.useRealTimers();
     }
   });
+
+  it("exposes a safe render-only refresh target", () => {
+    const running = makeRecord({ id: "running", status: "running", completedAt: undefined });
+    const { widget, tui } = createWidgetHarness([running]);
+    tui.requestRender.mockClear();
+
+    expect((widget as any).requestUiRefresh(true)).toBe(true);
+    expect(tui.requestRender).toHaveBeenCalledWith(true);
+    widget.dispose();
+    expect((widget as any).requestUiRefresh(true)).toBe(false);
+  });
 });

package/test/ui/deferred-ui-refresh.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDeferredUiRefresh } from "../../src/ui/deferred-ui-refresh.js";
+
+describe("createDeferredUiRefresh", () => {
+  afterEach(() => vi.useRealTimers());
+
+  it("fires once after the debounce delay", () => {
+    vi.useFakeTimers();
+    const requestRender = vi.fn();
+    const refresh = createDeferredUiRefresh(requestRender);
+
+    refresh.schedule();
+    vi.advanceTimersByTime(49);
+    expect(requestRender).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(requestRender).toHaveBeenCalledTimes(1);
+  });
+
+  it("coalesces repeated schedules and respects the max wait", () => {
+    vi.useFakeTimers();
+    const requestRender = vi.fn();
+    const refresh = createDeferredUiRefresh(requestRender);
+
+    refresh.schedule();
+    vi.advanceTimersByTime(40);
+    refresh.schedule();
+    vi.advanceTimersByTime(40);
+    refresh.schedule();
+    vi.advanceTimersByTime(40);
+    refresh.schedule();
+    vi.advanceTimersByTime(40);
+    refresh.schedule();
+    vi.advanceTimersByTime(39);
+    expect(requestRender).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(requestRender).toHaveBeenCalledTimes(1);
+  });
+
+  it("supports cancel and dispose without firing a stale callback", () => {
+    vi.useFakeTimers();
+    const requestRender = vi.fn();
+    const refresh = createDeferredUiRefresh(requestRender);
+
+    refresh.schedule();
+    refresh.cancel();
+    vi.advanceTimersByTime(250);
+    expect(requestRender).not.toHaveBeenCalled();
+
+    refresh.schedule();
+    refresh.dispose();
+    refresh.schedule();
+    vi.advanceTimersByTime(250);
+    expect(requestRender).not.toHaveBeenCalled();
+  });
+});

package/test/ui/fleet-list.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import {
   calculateFleetAgentWindow,
+  ensureFleetSelectionVisible,
   FLEET_MAX_RENDER_ROWS,
   FleetList,
 } from "../../src/ui/fleet-list.js";
@@ -35,6 +36,7 @@ function createFleetHarness(records: any[]) {
   const tui = { terminal: { rows: 24 }, requestRender: vi.fn() } as any;
   let terminalInput: ((data: string) => { consume?: boolean } | undefined) | undefined;
   let factory: any;
+  let widget: any;
   const ui: any = {
     setWidget: vi.fn((_key: string, content: any) => { factory = content; }),
     onTerminalInput: (handler: typeof terminalInput) => {
@@ -48,10 +50,14 @@ function createFleetHarness(records: any[]) {
   const fleet = new FleetList(manager, new Map());
   fleet.setUICtx(ui);
   fleet.update();
-  const render = (width = 120) => factory ? factory(tui, theme).render(width) : [];
+  const render = (width = 120) => {
+    widget = factory ? factory(tui, theme) : undefined;
+    return widget?.render(width) ?? [];
+  };
   const input = (data: string) => terminalInput?.(data);
+  const mouse = (wheelDelta: number) => widget?.handleMouse({ type: "wheel", wheelDelta });
   render(); // The real TUI invokes the widget factory before keyboard input arrives.
-  return { manager, fleet, tui, ui, render, input };
+  return { manager, fleet, tui, ui, render, input, mouse, getWidget: () => widget };
 }
 
 describe("canOpenActiveAgent", () => {
@@ -63,11 +69,68 @@ describe("canOpenActiveAgent", () => {
   });
 });
 
+describe("FleetView focus-preserving window", () => {
+  it("does not move the window while the selected agent is visible", () => {
+    expect(calculateFleetAgentWindow(12, 0)).toMatchObject({
+      start: 0,
+      end: 3,
+      hiddenAbove: 0,
+      hiddenBelow: 9,
+    });
+    expect(ensureFleetSelectionVisible(12, 0, 0)).toBe(0);
+    expect(ensureFleetSelectionVisible(12, 1, 0)).toBe(0);
+    expect(ensureFleetSelectionVisible(12, 2, 0)).toBe(0);
+  });
+
+  it("moves only enough to show a selected agent below the window", () => {
+    const nextStart = ensureFleetSelectionVisible(12, 3, 0);
+    expect(nextStart).toBe(2);
+    const window = calculateFleetAgentWindow(12, nextStart);
+    expect(3).toBeGreaterThanOrEqual(window.start);
+    expect(3).toBeLessThan(window.end);
+  });
+
+  it("moves only enough to show a selected agent above the window", () => {
+    const nextStart = ensureFleetSelectionVisible(12, 3, 4);
+    expect(nextStart).toBe(3);
+    const window = calculateFleetAgentWindow(12, nextStart);
+    expect(3).toBeGreaterThanOrEqual(window.start);
+    expect(3).toBeLessThan(window.end);
+  });
+
+  it("preserves the marker row budget", () => {
+    for (const count of [0, 1, 2, 4, 5, 12]) {
+      for (let start = 0; start < Math.max(1, count); start++) {
+        const window = calculateFleetAgentWindow(count, start);
+        const rows = 2
+          + (window.hiddenAbove > 0 ? 1 : 0)
+          + (window.end - window.start)
+          + (window.hiddenBelow > 0 ? 1 : 0);
+        expect(rows).toBeLessThanOrEqual(FLEET_MAX_RENDER_ROWS);
+      }
+    }
+  });
+
+  it("clamps empty, negative, and oversized inputs", () => {
+    expect(calculateFleetAgentWindow(0, 99)).toEqual({
+      start: 0,
+      end: 0,
+      hiddenAbove: 0,
+      hiddenBelow: 0,
+    });
+    expect(ensureFleetSelectionVisible(12, -1, -4)).toBe(0);
+    expect(ensureFleetSelectionVisible(12, 999, 999)).toBe(9);
+  });
+});
+
 describe("FleetList bounded window", () => {
-  it("keeps every FleetView state within six total rows", () => {
+  it("keeps every FleetView viewport within six total rows", () => {
     for (const agentCount of [0, 1, 2, 4, 5, 12]) {
       for (let selected = 0; selected <= agentCount; selected++) {
-        const window = calculateFleetAgentWindow(agentCount, selected);
+        const viewportStart = agentCount > 0
+          ? ensureFleetSelectionVisible(agentCount, Math.max(0, selected - 1), 0)
+          : 0;
+        const window = calculateFleetAgentWindow(agentCount, viewportStart);
         const rows = 2 + (window.hiddenAbove > 0 ? 1 : 0)
           + (window.end - window.start)
           + (window.hiddenBelow > 0 ? 1 : 0);
@@ -81,13 +144,194 @@ describe("FleetList bounded window", () => {
   });
 
   it("reserves indicator rows while keeping the selected middle agent visible", () => {
-    const window = calculateFleetAgentWindow(12, 6);
+    const viewportStart = ensureFleetSelectionVisible(12, 5, 0);
+    expect(viewportStart).toBe(4);
+    const window = calculateFleetAgentWindow(12, viewportStart);
     expect(window.hiddenAbove).toBeGreaterThan(0);
     expect(window.hiddenBelow).toBeGreaterThan(0);
     expect(5).toBeGreaterThanOrEqual(window.start);
     expect(5).toBeLessThan(window.end);
   });
 
+  it("keeps the rendered window stable while moving inside it", () => {
+    const { render, input } = createFleetHarness(makeAgents(12));
+    input("\u001b[B"); // activate, select main
+    const before = render().join("\n");
+
+    input("\u001b[B"); // select agent 0, still in the first window
+    const afterFirst = render().join("\n");
+    input("\u001b[B"); // select agent 1, still in the first window
+    const afterSecond = render().join("\n");
+
+    expect(afterFirst).toContain("agent 0");
+    expect(afterSecond).toContain("agent 1");
+    expect(afterSecond).toContain("agent 0");
+    expect(afterSecond).toContain("↓ 9 more");
+    expect(afterSecond).not.toContain("↑");
+    expect(before).toContain("↓ 9 more");
+  });
+
+  it("moves the window only when the selected row leaves it", () => {
+    const { render, input } = createFleetHarness(makeAgents(12));
+    input("\u001b[B");
+    input("\u001b[B");
+    input("\u001b[B");
+    const beforeBoundary = render().join("\n");
+    input("\u001b[B");
+    const afterBoundary = render().join("\n");
+
+    expect(beforeBoundary).toContain("agent 1");
+    expect(afterBoundary).toContain("agent 3");
+    expect(afterBoundary).toContain("↑");
+    expect(afterBoundary).not.toEqual(beforeBoundary);
+  });
+
+  it("treats vim and arrow keys as equivalent directional input", () => {
+    const arrows = createFleetHarness(makeAgents(12));
+    const vim = createFleetHarness(makeAgents(12));
+    arrows.input("\u001b[B");
+    vim.input("\u001b[B");
+
+    for (let i = 0; i < 4; i++) {
+      arrows.input("\u001b[B");
+      vim.input("j");
+      expect(vim.render()).toEqual(arrows.render());
+    }
+    for (let i = 0; i < 2; i++) {
+      arrows.input("\u001b[A");
+      vim.input("k");
+      expect(vim.render()).toEqual(arrows.render());
+    }
+  });
+
+  it("activates inactive FleetView equivalently for j, down, and wheel-down", () => {
+    const arrows = createFleetHarness(makeAgents(2));
+    const vim = createFleetHarness(makeAgents(2));
+    const wheel = createFleetHarness(makeAgents(2));
+
+    expect(arrows.input("\u001b[B")).toEqual({ consume: true });
+    expect(vim.input("j")).toEqual({ consume: true });
+    expect(wheel.mouse(1)).toEqual({ handled: true, render: true });
+    expect(vim.render()).toEqual(arrows.render());
+    expect(wheel.render()).toEqual(arrows.render());
+    expect(arrows.render()[0]).toContain("↑↓ select");
+  });
+
+  it("activates inactive FleetView with left at an empty editor", () => {
+    const { render, input } = createFleetHarness(makeAgents(1));
+
+    expect(input("\u001b[D")).toEqual({ consume: true });
+    expect(render()[0]).toContain("↑↓ select");
+    expect(render()[1]).toContain("● main");
+  });
+
+  it("keeps left activation consistent and does not become down when active", () => {
+    const left = createFleetHarness(makeAgents(1));
+    const down = createFleetHarness(makeAgents(1));
+
+    expect(left.render()[0]).toContain("↓ to manage");
+    expect(left.input("\u001b[D")).toEqual({ consume: true });
+    expect(down.input("\u001b[B")).toEqual({ consume: true });
+    expect(left.render()).toEqual(down.render());
+    expect(left.render()[1]).toContain("● main");
+
+    const active = left.render();
+    left.input("\u001b[D");
+    expect(left.render()).toEqual(active);
+    expect(left.render()[1]).toContain("● main");
+  });
+
+  it("keeps the existing left activation contract", () => {
+    const { render, input } = createFleetHarness(makeAgents(2));
+
+    expect(input("\u001b[D")).toEqual({ consume: true });
+    expect(render()[0]).toContain("↑↓ select");
+    expect(render()[1]).toContain("● main");
+
+    input("\u001b[D");
+    expect(render()[1]).toContain("● main");
+  });
+
+  it("exposes normalized wheel input and maps its direction like arrows", () => {
+    const arrows = createFleetHarness(makeAgents(12));
+    const wheel = createFleetHarness(makeAgents(12));
+    expect(typeof wheel.getWidget().handleMouse).toBe("function");
+    arrows.input("\u001b[B");
+    wheel.input("\u001b[B");
+
+    arrows.input("\u001b[B");
+    expect(wheel.mouse(1)).toEqual({ handled: true, render: true });
+    expect(wheel.render()).toEqual(arrows.render());
+    arrows.input("\u001b[B");
+    expect(wheel.mouse(2)).toEqual({ handled: true, render: true });
+    expect(wheel.render()).toEqual(arrows.render());
+
+    arrows.input("\u001b[A");
+    expect(wheel.mouse(-1)).toEqual({ handled: true, render: true });
+    expect(wheel.render()).toEqual(arrows.render());
+    expect(wheel.getWidget().handleMouse({ type: "wheel", wheelDelta: 0 })).toBeUndefined();
+    expect(wheel.getWidget().handleMouse({ type: "wheel" })).toBeUndefined();
+    expect(wheel.getWidget().handleMouse({ type: "mousemove", wheelDelta: 1 })).toBeUndefined();
+  });
+
+  it("activates on downward wheel only when inactive at an empty editor", () => {
+    const { render, mouse } = createFleetHarness(makeAgents(2));
+
+    expect(render()[0]).toContain("↓ to manage");
+    expect(mouse(-1)).toBeUndefined();
+    expect(render()[0]).toContain("↓ to manage");
+
+    expect(mouse(1)).toEqual({ handled: true, render: true });
+    expect(render()[0]).toContain("↑↓ select");
+    expect(render()[1]).toContain("● main");
+  });
+
+  it("keeps vim, arrows, and wheel navigation at roster boundaries", () => {
+    const { render, input, mouse } = createFleetHarness(makeAgents(2));
+    input("\u001b[B"); // activate on main
+    expect(mouse(-1)).toEqual({ handled: true, render: true }); // up from main exits, rather than moving past the top
+    expect(render()[0]).toContain("← for agents");
+
+    input("\u001b[B");
+    input("j");
+    input("j"); // bottom agent
+    const atBottom = render().join("\n");
+    input("\u001b[B");
+    expect(render().join("\n")).toEqual(atBottom);
+    expect(mouse(1)).toEqual({ handled: true, render: true });
+    expect(render().join("\n")).toEqual(atBottom);
+
+    input("k");
+    input("k");
+    expect(render()[1]).toContain("● main");
+    input("\u001b[A"); // up from main deactivates at the top boundary
+    expect(render()[0]).toContain("↓ to manage");
+  });
+
+  it("keeps keyboard and wheel directions equivalent at active boundaries", () => {
+    const arrows = createFleetHarness(makeAgents(2));
+    const vim = createFleetHarness(makeAgents(2));
+    const wheel = createFleetHarness(makeAgents(2));
+    const compare = (arrow: () => unknown, vi: () => unknown, mouse: () => unknown) => {
+      expect(vi()).toEqual(arrow());
+      expect(mouse()).toEqual({ handled: true, render: true });
+      expect(vim.render()).toEqual(arrows.render());
+      expect(wheel.render()).toEqual(arrows.render());
+    };
+
+    compare(() => arrows.input("\u001b[B"), () => vim.input("j"), () => wheel.mouse(1));
+    compare(() => arrows.input("\u001b[B"), () => vim.input("j"), () => wheel.mouse(1));
+    compare(() => arrows.input("\u001b[B"), () => vim.input("j"), () => wheel.mouse(1));
+
+    // Down at the bottom clamps identically, while up eventually deactivates
+    // all three controls at the top boundary.
+    compare(() => arrows.input("\u001b[B"), () => vim.input("j"), () => wheel.mouse(1));
+    compare(() => arrows.input("\u001b[A"), () => vim.input("k"), () => wheel.mouse(-1));
+    compare(() => arrows.input("\u001b[A"), () => vim.input("k"), () => wheel.mouse(-1));
+    compare(() => arrows.input("\u001b[A"), () => vim.input("k"), () => wheel.mouse(-1));
+    expect(arrows.render()[0]).toContain("↓ to manage");
+  });
+
   it("slides the visible window while navigating the full roster", () => {
     const { render, input } = createFleetHarness(makeAgents(12));
     input("\u001b[B");
@@ -132,4 +376,14 @@ describe("FleetList bounded window", () => {
     fleet.update();
     expect(ui.setWidget).toHaveBeenLastCalledWith("fleet", undefined);
   });
+
+  it("refreshes the current TUI without handling keyboard input", () => {
+    const { fleet, tui } = createFleetHarness(makeAgents(1));
+    tui.requestRender.mockClear();
+
+    expect((fleet as any).requestUiRefresh(true)).toBe(true);
+    expect(tui.requestRender).toHaveBeenCalledWith(true);
+    fleet.dispose();
+    expect((fleet as any).requestUiRefresh(true)).toBe(false);
+  });
 });