@tokentop/ttop 0.6.1 → 0.7.0

package/src/storage/persistence-service.ts

@@ -15,6 +15,7 @@
 
 import { isDatabaseInitialized } from "./db.ts";
 import {
+  getLatestSnapshotsForAllSessions,
   getLatestStreamTotalsForAllSessions,
   insertAgentSessionSnapshot,
   upsertAgentSession,
@@ -36,6 +37,12 @@ import { computeStreamDelta } from "./types.ts";
 /** Minimum interval between DB writes for the same session */
 const SNAPSHOT_INTERVAL_MS = 300_000; // 5 minutes
 
+/** Remove tracking entries for sessions not written in this window */
+const STALE_ENTRY_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/** Run eviction at most this often */
+const EVICTION_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes
+
 // ---------------------------------------------------------------------------
 // Global state (survives bun --hot HMR and React remounts)
 // ---------------------------------------------------------------------------
@@ -49,6 +56,8 @@ interface PersistenceState {
   previousStreamTotals: Map<string, StreamTotals>;
   /** Whether startup seeding has completed */
   seeded: boolean;
+  /** Timestamp of last stale entry eviction run */
+  lastEvictionAt: number;
 }
 
 declare global {
@@ -63,6 +72,7 @@ function getState(): PersistenceState {
       sessionFingerprints: new Map(),
       previousStreamTotals: new Map(),
       seeded: false,
+      lastEvictionAt: 0,
     };
   }
   return globalThis.__tokentopPersistence;
@@ -91,6 +101,27 @@ export interface SessionPersistData {
   streams: Omit<AgentSessionStreamSnapshotRow, "agentSessionSnapshotId">[];
 }
 
+function evictStaleEntries(state: PersistenceState, now: number): void {
+  if (now - state.lastEvictionAt < EVICTION_INTERVAL_MS) return;
+  state.lastEvictionAt = now;
+
+  const cutoff = now - STALE_ENTRY_MAX_AGE_MS;
+  for (const [key, ts] of state.lastWriteTimestamps) {
+    if (ts < cutoff) {
+      state.lastWriteTimestamps.delete(key);
+      state.sessionFingerprints.delete(key);
+    }
+  }
+
+  // Evict stream totals whose parent session was evicted
+  for (const streamKey of state.previousStreamTotals.keys()) {
+    const sessionKey = streamKey.slice(0, streamKey.indexOf(":", streamKey.indexOf(":") + 1));
+    if (!state.lastWriteTimestamps.has(sessionKey)) {
+      state.previousStreamTotals.delete(streamKey);
+    }
+  }
+}
+
 /**
  * Persist session data to the database with per-session throttling.
  *
@@ -105,6 +136,7 @@ export function persistSessions(sessions: SessionPersistData[]): number {
 
   const state = getState();
   const now = Date.now();
+  evictStaleEntries(state, now);
   let persistedCount = 0;
 
   for (const { session, snapshot, streams } of sessions) {
@@ -177,11 +209,6 @@ export function persistSessions(sessions: SessionPersistData[]): number {
   return persistedCount;
 }
 
-/**
- * Seed previous stream totals from the database.
- * Called once at startup after DB initialization to ensure
- * accurate delta computation from the first persistence call.
- */
 export function seedPreviousTotals(): void {
   const state = getState();
   if (state.seeded) return;
@@ -199,6 +226,28 @@ export function seedPreviousTotals(): void {
         requestCount: row.requestCount,
       });
     }
+
+    // Seeds Gate 1/2 so the first post-startup tick does not rewrite every
+    // historical session. computeFingerprint only reads cost/count/input/output,
+    // so the other fields are placeholders to satisfy the snapshot shape.
+    const latestSnapshots = getLatestSnapshotsForAllSessions();
+    for (const snap of latestSnapshots) {
+      const sessionKey = `${snap.agentId}:${snap.sessionId}`;
+      const fp = computeFingerprint({
+        timestamp: snap.timestamp,
+        lastActivityAt: snap.timestamp,
+        status: null,
+        totalInputTokens: snap.totalInputTokens,
+        totalOutputTokens: snap.totalOutputTokens,
+        totalCacheReadTokens: 0,
+        totalCacheWriteTokens: 0,
+        totalCostUsd: snap.totalCostUsd,
+        requestCount: snap.requestCount,
+      });
+      state.sessionFingerprints.set(sessionKey, fp);
+      state.lastWriteTimestamps.set(sessionKey, snap.timestamp);
+    }
+
     state.seeded = true;
   } catch (err) {
     console.error("Failed to seed previous totals from DB:", err);

package/src/storage/repos/agentSessions.ts

@@ -172,6 +172,55 @@ export interface LatestStreamTotals {
   requestCount: number;
 }
 
+export interface LatestSessionSnapshot {
+  agentId: string;
+  sessionId: string;
+  timestamp: number;
+  totalCostUsd: number;
+  requestCount: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+}
+
+export function getLatestSnapshotsForAllSessions(): LatestSessionSnapshot[] {
+  const db = getDatabase();
+
+  const rows = db
+    .prepare(`
+    SELECT
+      s.agent_id, s.session_id,
+      snap.timestamp,
+      snap.total_cost_usd, snap.request_count,
+      snap.total_input_tokens, snap.total_output_tokens
+    FROM agent_session_snapshots snap
+    JOIN agent_sessions s ON s.id = snap.agent_session_id
+    WHERE snap.id IN (
+      SELECT MAX(snap2.id)
+      FROM agent_session_snapshots snap2
+      GROUP BY snap2.agent_session_id
+    )
+  `)
+    .all() as Array<{
+    agent_id: string;
+    session_id: string;
+    timestamp: number;
+    total_cost_usd: number;
+    request_count: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+  }>;
+
+  return rows.map((r) => ({
+    agentId: r.agent_id,
+    sessionId: r.session_id,
+    timestamp: r.timestamp,
+    totalCostUsd: r.total_cost_usd,
+    requestCount: r.request_count,
+    totalInputTokens: r.total_input_tokens,
+    totalOutputTokens: r.total_output_tokens,
+  }));
+}
+
 export function getLatestStreamTotalsForAllSessions(): LatestStreamTotals[] {
   const db = getDatabase();
 

package/src/tui/App.tsx

@@ -245,12 +245,12 @@ function AppContent() {
   ]);
 
   useKeyboard((key) => {
-    if (key.ctrl && key.name === "p") {
-      handleCaptureFrame();
+    if ((key.ctrl && key.shift && key.name === "p") || (key.shift && key.name === "p")) {
+      handleBurstRecord();
       return;
     }
-    if (key.ctrl && key.shift && key.name === "p") {
-      handleBurstRecord();
+    if (key.ctrl && key.name === "p") {
+      handleCaptureFrame();
       return;
     }
 

package/src/tui/components/SessionDetailsDrawer.tsx

@@ -158,6 +158,16 @@ export function SessionDetailsDrawer({ session, onClose: _onClose }: SessionDeta
     };
   }, [session.streams]);
 
+  const hasAnyLongContext = session.streams.some((s) => s.hasLongContext);
+  const totalLongContextRequests = session.streams.reduce(
+    (sum, s) => sum + (s.longContextRequestCount ?? 0),
+    0,
+  );
+  const totalLongContextTokens = session.streams.reduce((sum, s) => {
+    if (!s.longContextTokens) return sum;
+    return sum + s.longContextTokens.input + s.longContextTokens.output;
+  }, 0);
+
   const isMultiDay = session.lastActivityAt - session.startedAt > 24 * 60 * 60 * 1000;
   const startTimeStr = formatTimelineLabel(session.startedAt, isMultiDay);
   const endTimeStr = formatTimelineLabel(session.lastActivityAt, isMultiDay);
@@ -338,6 +348,18 @@ export function SessionDetailsDrawer({ session, onClose: _onClose }: SessionDeta
               </text>
             </box>
           )}
+
+          {hasAnyLongContext && (
+            <box flexDirection="row" height={1} marginBottom={0}>
+              <text height={1} overflow="hidden">
+                <span fg={colors.warning}>↑ Long ctx: </span>
+                <span fg={colors.text}>{totalLongContextRequests} reqs</span>
+                <span fg={colors.textMuted}> · </span>
+                <span fg={colors.text}>{formatTokens(totalLongContextTokens)} tokens</span>
+                <span fg={colors.textMuted}> at tiered rate</span>
+              </text>
+            </box>
+          )}
         </box>
 
         <box
@@ -407,11 +429,17 @@ export function SessionDetailsDrawer({ session, onClose: _onClose }: SessionDeta
                   </text>
                   <box width={10} height={1} justifyContent="flex-end">
                     <text fg={colors.textMuted}>
-                      {formatTokens(stream.tokens.input + stream.tokens.output)}
+                      {formatTokens(
+                        stream.tokens.input +
+                          stream.tokens.output +
+                          (stream.longContextTokens?.input ?? 0) +
+                          (stream.longContextTokens?.output ?? 0),
+                      )}
                     </text>
                   </box>
                   <box width={10} height={1} justifyContent="flex-end">
                     <text fg={colors.success}>{formatCost(stream.costUsd)}</text>
+                    <text fg={colors.textMuted}>{stream.hasLongContext ? "↑" : " "}</text>
                   </box>
                 </box>
               );

package/src/tui/components/SessionsTable.tsx

@@ -13,6 +13,8 @@ import { getSortDirectionIndicator, getSortFieldLabel } from "../types/sort.ts";
 interface SessionsTableProps {
   sessions: AgentSessionAggregate[];
   selectedRow: number;
+  scrollOffset: number;
+  visibleRows: number;
   isLoading: boolean;
   isFiltering: boolean;
   filterQuery: string;
@@ -159,6 +161,7 @@ const SessionRow = memo(function SessionRow({
   const cacheRead = session.totals.cacheRead ?? 0;
   const hasCacheData = cacheRead > 0;
   const isEstimated = session.metadata?.isEstimated === true;
+  const hasLongContext = session.streams.some((s) => s.hasLongContext === true);
   const costUsd = session.totalCostUsd ?? 0;
 
   const animatedTokens = useAnimatedValue(effectiveTokens, { durationMs: 300, precision: 0 });
@@ -271,8 +274,9 @@ const SessionRow = memo(function SessionRow({
           </span>
           <span fg={textMutedColor}>{hasCacheData ? ` ↯${formatCacheBadge(cacheRead)}` : ""}</span>
         </text>
-        <text width={8} height={1} fg={costColor} {...bgProp}>
-          {costDisplay.padStart(7)}
+        <text width={8} height={1} {...bgProp}>
+          <span fg={costColor}>{costDisplay.padStart(7)}</span>
+          <span fg={textMutedColor}>{hasLongContext ? "↑" : " "}</span>
         </text>
         <text width={14} height={1} fg={textSubtleColor} {...bgProp}>
           {projectDisplay}
@@ -329,8 +333,9 @@ const SessionRow = memo(function SessionRow({
           {hasCacheData && showCacheBadge ? ` ↯${formatCacheBadge(cacheRead)}` : ""}
         </span>
       </text>
-      <text width={7} height={1} fg={costColor} {...bgProp}>
-        {formatCostVal(costUsd).padStart(6)}
+      <text width={7} height={1} {...bgProp}>
+        <span fg={costColor}>{formatCostVal(costUsd).padStart(6)}</span>
+        <span fg={textMutedColor}>{hasLongContext ? "↑" : " "}</span>
       </text>
       <text flexGrow={1} height={1} fg={textSubtleColor} {...bgProp}>
         {projectDisplay}
@@ -351,6 +356,8 @@ export const SessionsTable = forwardRef(function SessionsTable(
   {
     sessions,
     selectedRow,
+    scrollOffset,
+    visibleRows,
     isLoading,
     isFiltering,
     filterQuery,
@@ -398,10 +405,18 @@ export const SessionsTable = forwardRef(function SessionsTable(
     bulkThreshold: 100,
   });
 
-  let activeIndex = 0;
   const selectedSession = sessions[selectedRow] ?? null;
   const inspector = selectedSession ? getInspectorData(selectedSession) : null;
 
+  // Spacer boxes preserve scrollbox inner height so scrollTo(scrollOffset) still maps correctly.
+  const RENDER_BUFFER = 4;
+  const visibleStart = Math.max(0, scrollOffset - RENDER_BUFFER);
+  const visibleEnd = Math.min(animatedSessions.length, scrollOffset + visibleRows + RENDER_BUFFER);
+  const visibleSlice =
+    animatedSessions.length > 0 ? animatedSessions.slice(visibleStart, visibleEnd) : [];
+  const topSpacer = visibleStart;
+  const bottomSpacer = Math.max(0, animatedSessions.length - visibleEnd);
+
   // Sort indicator helpers for column headers
   const sortIndicator = (field: string) =>
     sortField === field ? (sortDirection === "desc" ? "▼" : "▲") : " ";
@@ -527,8 +542,10 @@ export const SessionsTable = forwardRef(function SessionsTable(
               </text>
             </box>
           )}
-          {animatedSessions.map((entry) => {
-            const isSelectedRow = !entry.isExiting && activeIndex++ === selectedRow;
+          {topSpacer > 0 && <box height={topSpacer} flexShrink={0} />}
+          {visibleSlice.map((entry, i) => {
+            const absIndex = visibleStart + i;
+            const isSelectedRow = !entry.isExiting && absIndex === selectedRow;
             return (
               <SessionRow
                 key={entry.item.sessionId}
@@ -544,6 +561,7 @@ export const SessionsTable = forwardRef(function SessionsTable(
               />
             );
           })}
+          {bottomSpacer > 0 && <box height={bottomSpacer} flexShrink={0} />}
         </box>
       </scrollbox>
       {terminalHeight >= 30 && (

package/src/tui/contexts/AgentSessionContext.tsx

@@ -5,10 +5,17 @@ import {
   useCallback,
   useContext,
   useEffect,
+  useMemo,
   useRef,
   useState,
 } from "react";
-import { aggregateSessionUsage, deduplicateAggregates } from "@/agents/aggregator.ts";
+import {
+  aggregateSessionUsage,
+  deduplicateAggregates,
+  isCrossAgentShadow,
+  markCrossAgentShadows,
+  selectEffectiveSessions,
+} from "@/agents/aggregator.ts";
 import { priceSessions } from "@/agents/costing.ts";
 import type { AgentId, AgentInfo, AgentSessionAggregate } from "@/agents/types.ts";
 import { createPluginContext } from "@/plugins/plugin-context-factory.ts";
@@ -48,10 +55,12 @@ interface AgentSessionProviderProps {
  */
 function computeSessionFingerprint(sessions: AgentSessionAggregate[]): string {
   // Build a compact string from the fields that actually affect the UI.
-  // This is intentionally simple — no crypto hashing needed, just string comparison.
+  // Shadow bit is included so that flipping a session's dedup status
+  // (gaining or losing its cross-agent shadow mark) triggers a re-render.
   let fp = `${sessions.length}:`;
   for (const s of sessions) {
-    fp += `${s.sessionId},${s.status},${s.lastActivityAt},${s.totals.input},${s.totals.output},${s.totalCostUsd ?? 0},${s.requestCount};`;
+    const shadow = isCrossAgentShadow(s) ? "1" : "0";
+    fp += `${s.sessionId},${s.status},${s.lastActivityAt},${s.totals.input},${s.totals.output},${s.totalCostUsd ?? 0},${s.requestCount},${shadow};`;
   }
   return fp;
 }
@@ -68,6 +77,9 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
   const { windowMs } = useTimeWindow();
   const hasBackfilled = useRef(false);
   const isRefreshingRef = useRef(false);
+  // Bugfix: track first completed load separately so an empty 1h window does not
+  // keep re-entering the initial loading state forever.
+  const hasLoadedOnceRef = useRef(false);
   const lastFingerprintRef = useRef<string>("");
 
   const discoverAgents = useCallback(async (): Promise<AgentInfo[]> => {
@@ -110,7 +122,17 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
 
       const http = createSandboxedHttpClient(plugin.id, plugin.permissions);
       const logger = createPluginLogger(plugin.id);
-      const ctx = { http, logger, config: {}, signal: AbortSignal.timeout(60_000) };
+      // Lazy signal: only create the 120s timer if the plugin actually reads ctx.signal.
+      let parseSignal: AbortSignal | undefined;
+      const ctx = {
+        http,
+        logger,
+        config: {},
+        get signal(): AbortSignal {
+          if (!parseSignal) parseSignal = AbortSignal.timeout(120_000);
+          return parseSignal;
+        },
+      };
 
       const rawSessions = await plugin.parseSessions(options, ctx);
 
@@ -134,7 +156,7 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
       if (isRefreshingRef.current) return;
       isRefreshingRef.current = true;
 
-      const isInitialLoad = sessions.length === 0;
+      const isInitialLoad = !hasLoadedOnceRef.current;
       if (isInitialLoad) {
         setIsLoading(true);
       }
@@ -193,7 +215,6 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
           }
         }
 
-        // Deduplicate sessions claimed by multiple agents scanning the same directory.
         const dedupedAggregates = deduplicateAggregates(allAggregates);
         if (dedupedAggregates.length < allAggregates.length) {
           debug(
@@ -203,6 +224,8 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
           );
         }
 
+        markCrossAgentShadows(dedupedAggregates);
+
         const pricedSessions = await priceSessions(dedupedAggregates);
 
         pricedSessions.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
@@ -221,11 +244,13 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
           return;
         }
 
+        const effectiveSessions = selectEffectiveSessions(pricedSessions);
+
         // Persist to storage — the persistence service handles throttling
         // internally (fingerprint gate + 5-minute per-session throttle).
         // Safe to call every tick; state lives on globalThis, survives HMR.
         const now = Date.now();
-        const persistData = pricedSessions.map((session) => ({
+        const persistData = effectiveSessions.map((session) => ({
           session: {
             agentId: session.agentId,
             sessionId: session.sessionId,
@@ -258,7 +283,7 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
         }));
         const persistedCount = persistSessions(persistData);
         debug(
-          `Persisted ${persistedCount}/${pricedSessions.length} sessions to storage`,
+          `Persisted ${persistedCount}/${effectiveSessions.length} sessions to storage`,
           undefined,
           "agent-sessions",
         );
@@ -266,7 +291,11 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
         setSessions(pricedSessions);
         setLastRefreshAt(Date.now());
 
-        debug(`Session refresh complete`, { count: pricedSessions.length }, "agent-sessions");
+        debug(
+          `Session refresh complete`,
+          { count: pricedSessions.length, effective: effectiveSessions.length },
+          "agent-sessions",
+        );
       } catch (err) {
         const errorMsg = err instanceof Error ? err.message : "Unknown error";
         logError(`Session refresh failed: ${errorMsg}`, undefined, "agent-sessions");
@@ -275,15 +304,19 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
         isRefreshingRef.current = false;
         if (isInitialLoad) {
           setIsLoading(false);
+          hasLoadedOnceRef.current = true;
         }
       }
     },
-    [sessions.length, discoverAgents, fetchAgentSessions, debug, warn, logError, demoMode],
+    [discoverAgents, fetchAgentSessions, debug, warn, logError, demoMode, simulator],
   );
 
   const refreshSessionsRef = useRef(refreshSessions);
   refreshSessionsRef.current = refreshSessions;
 
+  const sessionsRef = useRef(sessions);
+  sessionsRef.current = sessions;
+
   useEffect(() => {
     if (!(demoMode || pluginsInitialized)) return;
 
@@ -304,7 +337,7 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
     let timerId: ReturnType<typeof setTimeout> | null = null;
 
     const scheduleNext = () => {
-      const hasActive = sessions.some((s) => s.status === "active");
+      const hasActive = sessionsRef.current.some((s) => s.status === "active");
       const interval = hasActive ? ACTIVE_INTERVAL_MS : IDLE_INTERVAL_MS;
 
       timerId = setTimeout(() => {
@@ -324,16 +357,21 @@ export function AgentSessionProvider({ children, autoRefresh = false }: AgentSes
         clearTimeout(timerId);
       }
     };
-  }, [autoRefresh, sessions, debug]);
-
-  const value: AgentSessionContextValue = {
-    sessions,
-    agents,
-    isLoading,
-    lastRefreshAt,
-    error,
-    refreshSessions,
-  };
+  }, [autoRefresh, debug]);
+
+  const effectiveSessions = useMemo(() => selectEffectiveSessions(sessions), [sessions]);
+
+  const value: AgentSessionContextValue = useMemo(
+    () => ({
+      sessions: effectiveSessions,
+      agents,
+      isLoading,
+      lastRefreshAt,
+      error,
+      refreshSessions,
+    }),
+    [effectiveSessions, agents, isLoading, lastRefreshAt, error, refreshSessions],
+  );
 
   return <AgentSessionContext.Provider value={value}>{children}</AgentSessionContext.Provider>;
 }

package/src/tui/contexts/PluginContext.tsx

@@ -275,7 +275,11 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
         return;
       }
 
-      // Skip providers that are currently rate-limited (backoff)
+      if (state.loading) {
+        debug(`Skipping refresh for ${providerId}: already in flight`, undefined, "refresh");
+        return;
+      }
+
       const now = Date.now();
       if (state.rateLimitUntil > now) {
         const remainingSec = Math.round((state.rateLimitUntil - now) / 1000);
@@ -360,19 +364,25 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
 
         const http = createSandboxedHttpClient(providerId, state.plugin.permissions);
         const logger = createPluginLogger(providerId);
+        // Lazy signal: only create the 30s timer if a plugin actually reads ctx.signal.
+        let fetchSignal: AbortSignal | undefined;
+        const fetchCtx = {
+          credentials: creds,
+          http,
+          logger,
+          config: {},
+          get signal(): AbortSignal {
+            if (!fetchSignal) fetchSignal = AbortSignal.timeout(30_000);
+            return fetchSignal;
+          },
+        };
 
         const fetchResult = await safeInvoke(
           providerId,
           "fetchUsage",
           () =>
             runInPluginGuard(providerId, state.plugin.permissions, () =>
-              state.plugin.fetchUsage({
-                credentials: creds,
-                http,
-                logger,
-                config: {},
-                signal: AbortSignal.timeout(30_000),
-              }),
+              state.plugin.fetchUsage(fetchCtx),
             ),
           {
             // Count non-rate-limit errors as circuit breaker failures.
@@ -513,14 +523,25 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
     await Promise.all(configuredProviders.map(refreshProvider));
   }, [providers, refreshProvider, info]);
 
+  const refreshProviderRef = useRef(refreshProvider);
+  const refreshAllProvidersRef = useRef(refreshAllProviders);
+  refreshProviderRef.current = refreshProvider;
+  refreshAllProvidersRef.current = refreshAllProviders;
+
+  const stableRefreshProvider = useCallback(
+    (providerId: string) => refreshProviderRef.current(providerId),
+    [],
+  );
+  const stableRefreshAllProviders = useCallback(() => refreshAllProvidersRef.current(), []);
+
   const value: PluginContextValue = {
     providers,
     agents,
     themes,
     notifications,
     isInitialized,
-    refreshProvider,
-    refreshAllProviders,
+    refreshProvider: stableRefreshProvider,
+    refreshAllProviders: stableRefreshAllProviders,
   };
 
   return <PluginContext.Provider value={value}>{children}</PluginContext.Provider>;

package/src/tui/utils/scrollFollow.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import { computeScrollOffset } from "./scrollFollow.ts";
+
+describe("computeScrollOffset", () => {
+  test("cursor inside viewport leaves offset unchanged", () => {
+    expect(computeScrollOffset(5, 0, 10, 100)).toBe(0);
+  });
+
+  test("cursor at bottom edge leaves offset unchanged", () => {
+    expect(computeScrollOffset(9, 0, 10, 100)).toBe(0);
+  });
+
+  test("cursor past bottom pulls offset down by one row", () => {
+    expect(computeScrollOffset(10, 0, 10, 100)).toBe(1);
+  });
+
+  test("cursor past top pulls offset up", () => {
+    expect(computeScrollOffset(3, 5, 10, 100)).toBe(3);
+  });
+
+  test("clamps offset to non-negative", () => {
+    expect(computeScrollOffset(0, 0, 10, 100)).toBe(0);
+  });
+
+  test("clamps offset to total - visibleRows", () => {
+    expect(computeScrollOffset(99, 0, 10, 100)).toBe(90);
+  });
+
+  test("offset stays 0 when content fits in viewport", () => {
+    expect(computeScrollOffset(3, 0, 10, 4)).toBe(0);
+  });
+
+  // Regression test for cursor-disappears-then-jump bug: rapid j presses
+  // that React batches into a single render must still land with the cursor
+  // visible at the bottom edge. Simulating N sequential functional updates
+  // (the reducer runs each one in order) verifies the invariant.
+  test("batched rapid j-presses keep cursor at bottom edge each step", () => {
+    const vis = 10;
+    const total = 1000;
+    let state = { row: 0, offset: 0 };
+    for (let i = 0; i < 50; i++) {
+      const nextRow = Math.min(state.row + 1, total - 1);
+      const nextOffset = computeScrollOffset(nextRow, state.offset, vis, total);
+      state = { row: nextRow, offset: nextOffset };
+      expect(state.row).toBeGreaterThanOrEqual(state.offset);
+      expect(state.row).toBeLessThan(state.offset + vis);
+    }
+    expect(state.row).toBe(50);
+    expect(state.offset).toBe(41);
+  });
+
+  test("batched rapid k-presses at top keep cursor at top edge", () => {
+    const vis = 10;
+    const total = 1000;
+    let state = { row: 50, offset: 41 };
+    for (let i = 0; i < 50; i++) {
+      const nextRow = Math.max(state.row - 1, 0);
+      const nextOffset = computeScrollOffset(nextRow, state.offset, vis, total);
+      state = { row: nextRow, offset: nextOffset };
+      expect(state.row).toBeGreaterThanOrEqual(state.offset);
+      expect(state.row).toBeLessThan(state.offset + vis);
+    }
+    expect(state.row).toBe(0);
+    expect(state.offset).toBe(0);
+  });
+
+  test("re-clamp when list shrinks below current offset", () => {
+    expect(computeScrollOffset(5, 50, 10, 20)).toBe(5);
+    expect(computeScrollOffset(19, 50, 10, 20)).toBe(10);
+  });
+});

package/src/tui/utils/scrollFollow.ts

@@ -0,0 +1,12 @@
+export function computeScrollOffset(
+  row: number,
+  prevOffset: number,
+  visibleRows: number,
+  total: number,
+): number {
+  let next = prevOffset;
+  if (row < next) next = row;
+  else if (row >= next + visibleRows) next = row - visibleRows + 1;
+  const max = Math.max(0, total - visibleRows);
+  return Math.max(0, Math.min(next, max));
+}