@esso0428/pi-subagents 0.17.0 → 0.17.2

package/src/agent-recovery.ts

@@ -0,0 +1,185 @@
+/** Durable checkpoints for agents that may be interrupted by a catchable lifecycle event. */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureSubagentsGitignore } from "./agent-history.js";
+import type { AgentInvocation } from "./types.js";
+import type { LifetimeUsage } from "./usage.js";
+
+const SUBAGENTS_DIR = ".pi-subagents";
+const CHECKPOINTS_DIR = "agent-checkpoints";
+const CHECKPOINT_VERSION = 1;
+const TERMINAL_STATUSES = new Set(["completed", "steered", "stopped", "aborted", "error"] as const);
+const THINKING_LEVELS = new Set(["minimal", "low", "medium", "high", "xhigh", "max", "off"]);
+
+type ActiveStatus = "running" | "queued";
+type TerminalStatus = "completed" | "steered" | "stopped" | "aborted" | "error";
+export type AgentRecoveryStatus = ActiveStatus | TerminalStatus;
+
+export interface AgentRecoveryCheckpoint {
+  version: 1;
+  id: string;
+  type: string;
+  description: string;
+  status: AgentRecoveryStatus;
+  startedAt: number;
+  completedAt?: number;
+  result?: string;
+  error?: string;
+  toolUses: number;
+  lifetimeUsage: LifetimeUsage;
+  compactionCount: number;
+  transcriptPath?: string;
+  invocation?: AgentInvocation;
+}
+
+function isSafeString(value: unknown, maxLength: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= maxLength && !/[\0\r\n]/.test(value);
+}
+
+function isFiniteTimestamp(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+}
+
+function isUsage(value: unknown): value is LifetimeUsage {
+  if (!value || typeof value !== "object") return false;
+  const usage = value as Record<string, unknown>;
+  return ["input", "output", "cacheWrite"].every((key) => {
+    const n = usage[key];
+    return typeof n === "number" && Number.isFinite(n) && n >= 0;
+  });
+}
+
+function isInvocation(value: unknown): value is AgentInvocation {
+  if (!value || typeof value !== "object") return false;
+  const invocation = value as Record<string, unknown>;
+  for (const key of ["modelName", "effectiveModelName"]) {
+    if (invocation[key] !== undefined && !isSafeString(invocation[key], 512)) return false;
+  }
+  for (const key of ["thinking", "effectiveThinking"]) {
+    if (invocation[key] !== undefined && (typeof invocation[key] !== "string" || !THINKING_LEVELS.has(invocation[key]))) return false;
+  }
+  if (invocation.maxTurns !== undefined && (!Number.isInteger(invocation.maxTurns) || (invocation.maxTurns as number) < 0)) return false;
+  for (const key of ["isolated", "inheritContext", "runInBackground"]) {
+    if (invocation[key] !== undefined && typeof invocation[key] !== "boolean") return false;
+  }
+  return invocation.isolation === undefined || invocation.isolation === "worktree";
+}
+
+function isActiveStatus(value: AgentRecoveryStatus): value is ActiveStatus {
+  return value === "running" || value === "queued";
+}
+
+function isTerminalStatus(value: AgentRecoveryStatus): value is TerminalStatus {
+  return TERMINAL_STATUSES.has(value as TerminalStatus);
+}
+
+function isSafeTranscriptPath(value: unknown): value is string {
+  return typeof value === "string"
+    && /^\.pi-subagents\/agent-transcripts\/[^/]+\.jsonl$/.test(value)
+    && !value.includes("..")
+    && !value.includes("\\")
+    && !value.includes("\0");
+}
+
+/** Validate untrusted JSON before it can enter the manager or UI. */
+export function isAgentRecoveryCheckpoint(value: unknown): value is AgentRecoveryCheckpoint {
+  if (!value || typeof value !== "object") return false;
+  const checkpoint = value as Record<string, unknown>;
+  if (checkpoint.version !== CHECKPOINT_VERSION
+    || !isSafeString(checkpoint.id, 256)
+    || !isSafeString(checkpoint.type, 256)
+    || !isSafeString(checkpoint.description, 4096)
+    || typeof checkpoint.status !== "string"
+    || !isFiniteTimestamp(checkpoint.startedAt)
+    || !Number.isInteger(checkpoint.toolUses)
+    || (checkpoint.toolUses as number) < 0
+    || !isUsage(checkpoint.lifetimeUsage)
+    || !Number.isInteger(checkpoint.compactionCount)
+    || (checkpoint.compactionCount as number) < 0) return false;
+
+  const status = checkpoint.status as AgentRecoveryStatus;
+  if (!isActiveStatus(status) && !isTerminalStatus(status)) return false;
+  if (checkpoint.completedAt !== undefined && !isFiniteTimestamp(checkpoint.completedAt)) return false;
+  if (isTerminalStatus(status)
+    && (checkpoint.completedAt === undefined || checkpoint.completedAt < checkpoint.startedAt)) return false;
+  if (isActiveStatus(status) && checkpoint.completedAt !== undefined) return false;
+  if (checkpoint.result !== undefined && !isSafeString(checkpoint.result, 2_000_000)) return false;
+  if (checkpoint.error !== undefined && !isSafeString(checkpoint.error, 64_000)) return false;
+  if (checkpoint.transcriptPath !== undefined && !isSafeTranscriptPath(checkpoint.transcriptPath)) return false;
+  if (checkpoint.invocation !== undefined && !isInvocation(checkpoint.invocation)) return false;
+  return true;
+}
+
+function checkpointDirectory(cwd: string): string {
+  return join(cwd, SUBAGENTS_DIR, CHECKPOINTS_DIR);
+}
+
+/** Return the on-disk path for an agent's single deduplicated checkpoint. */
+export function agentRecoveryCheckpointPath(cwd: string, agentId: string): string {
+  const safeId = agentId.replace(/[^A-Za-z0-9._-]+/g, "-") || "agent";
+  return join(checkpointDirectory(cwd), `${safeId}.json`);
+}
+
+/**
+ * Atomically write one checkpoint. Repeated writes for the same agent replace
+ * the same file; identical payloads are skipped, so shutdown + abort callbacks
+ * cannot create duplicate recovery records.
+ */
+export function removeAgentRecoveryCheckpoint(cwd: string, agentId: string): boolean {
+  try {
+    unlinkSync(agentRecoveryCheckpointPath(cwd, agentId));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function writeAgentRecoveryCheckpoint(cwd: string, checkpoint: AgentRecoveryCheckpoint): boolean {
+  if (!isAgentRecoveryCheckpoint(checkpoint)) return false;
+  try {
+    ensureSubagentsGitignore(cwd);
+    const directory = checkpointDirectory(cwd);
+    mkdirSync(directory, { recursive: true });
+    const path = agentRecoveryCheckpointPath(cwd, checkpoint.id);
+    const contents = `${JSON.stringify(checkpoint)}\n`;
+    try {
+      if (readFileSync(path, "utf8") === contents) return false;
+    } catch {
+      // The file is new, missing, or unreadable; replace it below.
+    }
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, contents, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporary, path);
+    return true;
+  } catch {
+    // Recovery must never make a spawn or shutdown fail. A later checkpoint
+    // gets another chance to persist if the filesystem becomes available.
+    return false;
+  }
+}
+
+/** Load valid checkpoints, ignoring orphan, malformed, and corrupt files. */
+export function readAgentRecoveryCheckpoints(cwd: string): AgentRecoveryCheckpoint[] {
+  const directory = checkpointDirectory(cwd);
+  if (!existsSync(directory)) return [];
+  let names: string[];
+  try {
+    names = readdirSync(directory).filter((name) => /^[A-Za-z0-9._-]+\.json$/.test(name));
+  } catch {
+    return [];
+  }
+
+  const latest = new Map<string, AgentRecoveryCheckpoint>();
+  for (const name of names) {
+    try {
+      const value: unknown = JSON.parse(readFileSync(join(directory, name), "utf8"));
+      if (!isAgentRecoveryCheckpoint(value)) continue;
+      latest.set(value.id, value);
+    } catch {
+      // Ignore a partially written/corrupt checkpoint and continue indexing.
+    }
+  }
+  return [...latest.values()];
+}

package/src/index.ts

@@ -12,10 +12,10 @@
 
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
-import { Container, Key, matchesKey, type SettingItem, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
+import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir, getSelectListTheme, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Key, matchesKey, SelectList, type SettingItem, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { agentHistoryLocator, createAgentHistoryPath, readAgentHistory } from "./agent-history.js";
+import { agentHistoryLocator, createAgentHistoryPath, readAgentHistory, readAgentHistoryResult } from "./agent-history.js";
 import { buildAgentStatusMenuEntries, canOpenActiveAgent, canOpenAgentHistory, formatAgentHistoryOption, splitAgentRecords } from "./agent-history-list.js";
 import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
@@ -171,8 +171,8 @@ const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "ma
  * surfaces (or "" if the run produced nothing). `record.result` is bounded to
  * the run's own turns, so this is never a stale earlier answer (#144).
  */
-function partialOutputSuffix(record: AgentRecord): string {
-  const partial = record.result?.trim();
+function partialOutputSuffix(record: AgentRecord, fallback?: string): string {
+  const partial = record.result?.trim() || fallback?.trim();
   return partial ? `\n\nPartial output before the failure:\n${partial}` : "";
 }
 
@@ -450,7 +450,12 @@ export default function (pi: ExtensionAPI) {
     // Persist final record for cross-extension history reconstruction
     pi.appendEntry("subagents:record", {
       id: record.id, type: record.type, description: record.description,
-      status: record.status, result: record.result, error: record.error,
+      status: record.status,
+      // Durable transcripts are the source of truth for full output. Avoid
+      // copying a potentially large result into the parent session branch;
+      // get_subagent_result reloads it on demand after cleanup/restart.
+      result: record.transcriptPath ? undefined : record.result,
+      error: record.error,
       startedAt: record.startedAt, completedAt: record.completedAt,
       toolUses: record.toolUses,
       lifetimeUsage: record.lifetimeUsage,
@@ -555,16 +560,35 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
+  type AgentMenuSelection = { id?: string; index: number };
+  let runningAgentSelection: AgentMenuSelection = { index: 0 };
+  let historyAgentSelection: AgentMenuSelection = { index: 0 };
+
+  function resetAgentMenuSelections() {
+    runningAgentSelection = { index: 0 };
+    historyAgentSelection = { index: 0 };
+  }
+
   // Capture ctx from session_start for RPC spawn handler + start the scheduler.
   // This also wires the RPC handlers and broadcasts readiness — on the first
   // bound session_start, so a filtered-out activation never advertises (#142).
   pi.on("session_start", async (_event, ctx) => {
+    resetAgentMenuSelections();
     currentCtx = ctx;
     manager.clearCompleted(true);
     const branch = ctx.sessionManager?.getBranch?.() ?? [];
     manager.restoreCompleted(branch
       .filter((entry: any) => entry?.type === "custom" && entry?.customType === "subagents:record")
       .map((entry: any) => entry.data));
+    // Checkpoint files cover agents whose parent session never got a terminal
+    // branch entry (shutdown, session switch, or a process restart).
+    manager.restoreRecovered(ctx.cwd);
+    // Attach the panel during TUI startup, after restored records are present,
+    // so terminal agents from the session branch are immediately visible.
+    if (ctx.mode === "tui") {
+      widget.setUICtx(ctx.ui as UICtx);
+      widget.update();
+    }
     // Guard mirrors the `!scheduler.isActive()` pattern below: session_start
     // fires once per activation, but a double-bind must not leak listeners.
     if (!rpcHandle) {
@@ -583,6 +607,10 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_before_switch", () => {
+    resetAgentMenuSelections();
+    // A switch is catchable. Stop and checkpoint live/queued agents before the
+    // old session context is discarded, then retain their unread history.
+    manager.abortAll();
     manager.clearCompleted(true);
     scheduler.stop();
   });
@@ -590,6 +618,7 @@ export default function (pi: ExtensionAPI) {
   // On shutdown, abort all agents immediately and clean up.
   // If the session is going down, there's nothing left to consume agent results.
   pi.on("session_shutdown", async () => {
+    resetAgentMenuSelections();
     rpcHandle?.unsubSpawn();
     rpcHandle?.unsubStop();
     rpcHandle?.unsubPing();
@@ -1157,6 +1186,7 @@ Terse command-style prompts produce shallow, generic work.
           rec.historyFile = createAgentHistoryPath(ctx.cwd, agentId);
           rec.transcriptPath = agentHistoryLocator(ctx.cwd, rec.historyFile);
           writeInitialEntry(rec.historyFile, agentId, params.prompt, ctx.cwd);
+          manager.setTranscript(agentId, rec.historyFile, rec.transcriptPath, ctx.cwd);
         } catch (err) {
           rec.historyFile = undefined;
           rec.transcriptPath = undefined;
@@ -1268,9 +1298,10 @@ Terse command-style prompts produce shallow, generic work.
         const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns);
 
         // Wrap onSessionCreated to wire output file streaming.
-        // The callback lazily reads record.outputFile (set right after spawn)
-        // rather than closing over a value that doesn't exist yet.
+        // The callback reads the transcript paths installed synchronously by
+        // onSpawned before the agent can queue or start.
         let id: string;
+        const joinMode = resolveJoinMode(defaultJoinMode, true);
         const origBgOnSession = bgCallbacks.onSessionCreated;
         bgCallbacks.onSessionCreated = (session: any) => {
           origBgOnSession(session);
@@ -1291,20 +1322,21 @@ Terse command-style prompts produce shallow, generic work.
             isBackground: true,
             isolation,
             invocation: agentInvocation,
+            onSpawned: (spawnedId) => {
+              attachTranscript(manager.getRecord(spawnedId), spawnedId);
+            },
             ...bgCallbacks,
           });
         } catch (err) {
           return textResult(err instanceof Error ? err.message : String(err));
         }
 
-        // Set output file + join mode synchronously after spawn, before the
-        // event loop yields — onSessionCreated is async so this is safe.
-        const joinMode = resolveJoinMode(defaultJoinMode, true);
+        // Set join metadata after spawn. Transcript metadata was installed by
+        // the manager's synchronous onSpawned callback before this point.
         const record = manager.getRecord(id);
         if (record && joinMode) {
           record.joinMode = joinMode;
           record.toolCallId = toolCallId;
-          attachTranscript(record, id);
         }
 
         if (joinMode == null || joinMode === 'async') {
@@ -1506,6 +1538,9 @@ Terse command-style prompts produce shallow, generic work.
         if (record.promise) await abortable(record.promise, signal);
       }
 
+      const durableResult = !record.result?.trim() && record.transcriptPath && currentCtx?.cwd
+        ? readAgentHistoryResult(currentCtx.cwd, record.transcriptPath)
+        : undefined;
       const displayName = getDisplayName(record.type);
       const duration = formatDuration(record.startedAt, record.completedAt);
       const tokens = formatLifetimeTokens(record);
@@ -1524,9 +1559,9 @@ Terse command-style prompts produce shallow, generic work.
       if (record.status === "running") {
         output += "Agent is still running. Use wait: true or check back later.";
       } else if (record.status === "error") {
-        output += `Error: ${record.error}${partialOutputSuffix(record)}`;
+        output += `Error: ${record.error}${partialOutputSuffix(record, durableResult)}`;
       } else {
-        output += record.result?.trim() || "No output.";
+        output += durableResult || record.result?.trim() || "No output.";
       }
 
       // Mark result as consumed — suppresses the completion notification
@@ -1783,6 +1818,59 @@ Terse command-style prompts produce shallow, generic work.
     });
   }
 
+  async function selectAgentFromReadOnlyList(
+    ctx: ExtensionCommandContext,
+    title: string,
+    pairs: Array<{ record: AgentRecord; label: string }>,
+    selection: AgentMenuSelection,
+  ): Promise<AgentRecord | undefined> {
+    const options = pairs.map(({ record, label }) => ({ value: record.id, label }));
+    const rememberedIndex = selection.id
+      ? pairs.findIndex(({ record }) => record.id === selection.id)
+      : -1;
+    const initialIndex = rememberedIndex >= 0
+      ? rememberedIndex
+      : Math.max(0, Math.min(selection.index, pairs.length - 1));
+
+    const remember = (id: string) => {
+      const index = pairs.findIndex(({ record }) => record.id === id);
+      if (index >= 0) {
+        selection.id = id;
+        selection.index = index;
+      }
+    };
+
+    const choice = await ctx.ui.custom<string | undefined>((_tui, _theme, _kb, done) => {
+      const list = new SelectList(
+        options,
+        Math.min(options.length, 10),
+        getSelectListTheme(),
+      );
+      list.setSelectedIndex(initialIndex);
+      const initialItem = options[initialIndex];
+      if (initialItem) remember(initialItem.value);
+      list.onSelectionChange = item => remember(item.value);
+      list.onSelect = item => {
+        remember(item.value);
+        done(item.value);
+      };
+      list.onCancel = () => done(undefined);
+
+      const container = new Container();
+      container.addChild(new Text(title, 0, 0));
+      container.addChild(new Spacer(1));
+      container.addChild(list);
+      return {
+        render: (w: number) => container.render(w),
+        invalidate: () => container.invalidate(),
+        handleInput: (data: string) => list.handleInput(data),
+      };
+    });
+
+    if (!choice) return undefined;
+    return pairs.find(({ record }) => record.id === choice)?.record;
+  }
+
   async function showRunningAgents(ctx: ExtensionCommandContext) {
     const { active: agents } = splitAgentRecords(manager.listAgents(), ctx.cwd);
     if (agents.length === 0) {
@@ -1795,15 +1883,13 @@ Terse command-style prompts produce shallow, generic work.
       const dur = formatDuration(record.startedAt, record.completedAt);
       return { record, label: `${dn} (${record.description}) · ${record.toolUses} tools · ${record.status} · ${dur}` };
     });
-    const options = makeUniqueAgentOptionLabels(pairs);
+    makeUniqueAgentOptionLabels(pairs);
 
-    const choice = await ctx.ui.select("Running agents", options);
-    if (!choice) return;
-    const record = pairs.find((pair) => pair.label === choice)?.record;
+    const record = await selectAgentFromReadOnlyList(ctx, "Running agents", pairs, runningAgentSelection);
     if (!record) return;
 
     await viewAgentConversation(ctx, record, "live");
-    // Back-navigation: re-show the list
+    // Back-navigation: re-show the list at the previously selected agent.
     await showRunningAgents(ctx);
   }
 
@@ -1815,13 +1901,13 @@ Terse command-style prompts produce shallow, generic work.
     }
 
     const pairs = history.map((record) => ({ record, label: formatAgentHistoryOption(record, Date.now()) }));
-    const options = makeUniqueAgentOptionLabels(pairs);
-    const choice = await ctx.ui.select("Agent history", options);
-    if (!choice) return;
-    const record = pairs.find((pair) => pair.label === choice)?.record;
+    makeUniqueAgentOptionLabels(pairs);
+    const record = await selectAgentFromReadOnlyList(ctx, "Agent history", pairs, historyAgentSelection);
     if (!record) return;
 
     await viewAgentConversation(ctx, record, "history");
+    // Back-navigation: re-show the list at the previously selected agent.
+    await showAgentHistory(ctx);
   }
 
   async function viewAgentConversation(

package/src/ui/agent-widget.ts

@@ -249,6 +249,8 @@ export class AgentWidget {
   private navigationActive = false;
   /** 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;
 
@@ -307,6 +309,7 @@ export class AgentWidget {
     this.lastRenderKey = undefined;
     this.navigationActive = false;
     this.selectedAgentId = undefined;
+    this.selectedRosterIndex = 0;
     this.viewportStart = 0;
     // Print/RPC tests and lightweight embedders may provide only the widget
     // surface; real interactive contexts always implement this hook.
@@ -382,9 +385,29 @@ export class AgentWidget {
   }
 
   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.selectedAgentId = undefined;
-    this.viewportStart = 0;
+    this.update();
+  }
+
+  /** 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.update();
   }
 
@@ -396,10 +419,7 @@ export class AgentWidget {
 
     if (!this.navigationActive) {
       if (direction !== 1 || !this.editorHasFocus() || (ui.getEditorText?.() ?? "") !== "") return false;
-      this.navigationActive = true;
-      this.selectedAgentId = records[0].id;
-      this.viewportStart = 0;
-      this.update();
+      this.activate(records);
       return true;
     }
 
@@ -410,6 +430,7 @@ export class AgentWidget {
     }
     const nextIndex = Math.max(0, Math.min(records.length - 1, currentIndex + direction));
     this.selectedAgentId = records[nextIndex].id;
+    this.selectedRosterIndex = nextIndex;
     this.update();
     return true;
   }
@@ -431,13 +452,11 @@ export class AgentWidget {
     }
 
     if (!this.navigationActive) {
-      if (!matchesKey(data, "down") || (this.uiCtx.getEditorText?.() ?? "") !== "" || this.roster().length === 0) {
+      const records = this.roster();
+      if (!matchesKey(data, "down") || (this.uiCtx.getEditorText?.() ?? "") !== "" || records.length === 0) {
         return undefined;
       }
-      this.navigationActive = true;
-      this.selectedAgentId = this.roster()[0]?.id;
-      this.viewportStart = 0;
-      this.update();
+      this.activate(records);
       return { consume: true };
     }
 
@@ -729,6 +748,7 @@ export class AgentWidget {
       this.lastRenderKey = undefined;
       this.navigationActive = false;
       this.selectedAgentId = undefined;
+      this.selectedRosterIndex = 0;
       this.viewportStart = 0;
       this.syncTimer(false);
       return;
@@ -753,13 +773,22 @@ export class AgentWidget {
     // an otherwise idle widget advance.
     if (advanceSpinner && runningCount > 0) this.widgetFrame++;
     this.syncTimer(runningCount > 0);
-    if (this.navigationActive) {
+    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 if (this.selectedIndexOf(roster) < 0) {
-        this.selectedAgentId = roster[Math.min(this.viewportStart, roster.length - 1)].id;
+      } 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);
@@ -805,6 +834,7 @@ export class AgentWidget {
     this.lastRenderKey = undefined;
     this.navigationActive = false;
     this.selectedAgentId = undefined;
+    this.selectedRosterIndex = 0;
     this.viewportStart = 0;
     this.uiCtx = undefined;
   }