Session-history pagination + popover/empty-session fixes (v1.4.10)

Author: phuryn

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.4.10 — 2026-06-18
+
+> Session history that stays fast with thousands of sessions.
+
+### Features
+
+- **Session history loads in pages and stays fast at scale.** The history dropdown used to read and parse *every* saved session on each open, which got slow once a project had hundreds or thousands of them. It now loads the **most recent 100** (newest first by last activity) and pulls in older ones as you **scroll to the bottom**. The **search box** filters by name across your **entire** history — not just the loaded page — so you can still find an old session instantly. Behind the scenes it orders sessions with one cheap directory `stat` each (no file reads), reads only the page you're looking at, and caches by file modification time so re-opening the dropdown costs effectively no disk reads. ([src/sessions.ts](src/sessions.ts), [src/sidebar.ts](src/sidebar.ts), [media/chat.js](media/chat.js), [media/chat.css](media/chat.css))
+- **Switching model or reasoning effort on a fresh session no longer clutters history.** Some model and effort changes need the session to restart. If you flip them a few times right after opening a session — before you've actually said anything — each restart used to leave behind an empty, identical session in your history. Now an empty session (one where only the hidden setup has run) restarts cleanly with no "Summarize & Restart vs. Just Restart" prompt, and the throwaway session is removed instead of piling up. If you had renamed that session, the name carries over to the restarted one. ([src/sidebar.ts](src/sidebar.ts), [src/sessions.ts](src/sessions.ts))
+
+### Fixes
+
+- **History dropdown no longer opens clipped off the right edge.** Opening the session-history popover quickly (before its rows had finished loading) could position it too far right, so it spilled past the panel edge and only looked right after closing and reopening. The popover is now right-aligned to the panel (respecting the edge padding) and grows leftward, so it stays fully on-screen no matter how its contents resize as sessions load in. In a narrow panel it also caps its width to fit, so a long session name truncates with an ellipsis instead of pushing the popover off the left edge. Resizing the panel while the dropdown is open now re-fits it live (no need to close and reopen), and switching to another panel tab or extension closes it so it can't reappear mis-sized when you come back. ([media/chat.js](media/chat.js))
+
+### Internal
+
+- **Opt-in performance simulation for the history popover.** A new `npm run test:perf` suite (kept out of `npm test` and CI) builds a 5000-session in-memory store and asserts the access-count improvement: first open drops file reads from 5000 to 100 (~98%), a repeat open does zero reads (modification-time cache), and search warms the catalog once then stays read-free — with a modeled-latency projection and a real in-memory parse-cost wall-clock. ([test/sessions.perf.ts](test/sessions.perf.ts), [vitest.perf.config.ts](vitest.perf.config.ts), [package.json](package.json))
+
+### Docs
+
+- Documented the pagination design in [docs/architecture.md](docs/architecture.md) (§ History at scale) and [CLAUDE.md](CLAUDE.md) (§ History pagination), and updated the *Session history* feature note in the [README](README.md).
+
 ## 1.4.9 — 2026-06-16
 
 > Make the chat bigger — just the chat.

CLAUDE.md

@@ -170,9 +170,9 @@ There's also no longer a long silent pause before that first response. Plan Mode
 </details>
 
 <details>
-<summary><strong>Session history</strong> — resume, rename, or delete any past session</summary>
+<summary><strong>Session history</strong> — resume, rename, delete, or clear past sessions</summary>
 
-The clock icon lists every session the CLI saved for this project. Click a row to resume — Grok replays the conversation, with inline images, plans, and reasoning intact. Hover to rename (pencil) or delete (trash); names default to the first message. Renames are stored by the extension and never touch Grok's own files.
+The clock icon lists the sessions the CLI saved for this project, most recent first. Click a row to resume — Grok replays the conversation, with inline images, plans, and reasoning intact. Hover to rename (pencil) or delete (trash); names default to the first message. The list loads the **most recent 100** and pulls in older ones as you **scroll**, and the **search box** filters by name across your whole history — so it stays fast even with thousands of sessions. **Clear all history** at the bottom of the dropdown removes every session for this project in one step (after a confirm), keeping the one you're currently in. Renames are stored by the extension and never touch Grok's own files.
 
 </details>
 

README.md

@@ -187,7 +187,7 @@ The full pedagogical write-up lives in
 | [src/chips.ts](../src/chips.ts) | File-chip CRUD (pure) |
 | [src/prompt-builder.ts](../src/prompt-builder.ts) | Chip → prompt-string with `@path` refs and fenced blocks (pure) |
 | [src/slash-filter.ts](../src/slash-filter.ts) | Slash-command autocomplete filter (pure) |
-| [src/sessions.ts](../src/sessions.ts) | Disk-driven session listing/delete + name overrides (pure) |
+| [src/sessions.ts](../src/sessions.ts) | Disk-driven session listing/delete + name overrides (pure) — `indexSessions` (stat-only ordering), `readSessionEntries` (windowed read), `listSessions` (whole-list), `clearSessions` |
 | [src/file-ref.ts](../src/file-ref.ts) | Open-file ref parsing + large-file inline-read guard (pure) |
 | [src/plan-review.ts](../src/plan-review.ts) | Plan-snapshot Markdown filename generation (pure) |
 | [src/voice.ts](../src/voice.ts) | Voice-input pure helpers — STT request/response, ffmpeg args, device parsing, key resolution |
@@ -196,6 +196,41 @@ The full pedagogical write-up lives in
 | [media/chat.{js,css}](../media/) | Webview UI |
 | [media/webview-helpers.js](../media/webview-helpers.js) | Pure webview helpers (file-ref detection, relative-time, mic-button state machine, trailing send-phrase highlight, math extraction `splitMath`/`stripUnsupportedTex`, and the deferred subagent classifier `isSubagentToolCall`/`subagentLabel`) — shared between webview and tests |
 
+## History at scale
+
+The history dropdown lists every session the CLI saved for this workspace, and that
+store can grow into the thousands. The old path read and `JSON.parse`d *every*
+`summary.json` on every open, then rendered every row — linear cost that stalled the
+popover at scale. It now loads **one page at a time** (`SESSION_PAGE_SIZE = 100`,
+newest-first), built from two pure primitives in
+[src/sessions.ts](../src/sessions.ts):
+
+- `indexSessions` does **one `stat` per session dir, no reads** — it orders every id
+  newest-first by `summary.json` **mtime**. mtime is the cheap last-activity proxy:
+  grok rewrites that file (it holds `updated_at`) on every turn. We sort by mtime
+  *because the id is a UUIDv7 whose timestamp is creation, not last activity* — an
+  id-sort would order by when the session was first opened, which is wrong.
+- `readSessionEntries` reads + parses `summary.json` for **exactly the visible page's
+  ids** and applies name overrides.
+
+The host (`postSessionsList` in [src/sidebar.ts](../src/sidebar.ts)) orders everything
+cheaply with `indexSessions`, then drives an **mtime-keyed read cache** so a re-open /
+load-more / search only re-reads entries whose `summary.json` actually changed —
+steady-state opens cost ~zero reads. **Search is server-side and complete**: a query
+warms the whole catalog once (cache-backed) and filters by display name across *all*
+sessions, not just the loaded page. One wrinkle the disk scan can't cover on its own:
+a *brand-new* session has no `summary.json` yet, so opening history the instant a
+session goes live would drop the active row until grok flushes the file. The host fixes
+that by synthesizing a top-pinned row from in-memory state for any live session not yet
+on disk (first, unfiltered page only — those ids can't appear on a later page). The
+webview appends pages on scroll-near-bottom (de-duped by id, one request per boundary)
+and debounces the search box. An opt-in
+perf simulation ([test/sessions.perf.ts](../test/sessions.perf.ts) via
+`npm run test:perf`, kept out of `npm test`/CI) asserts the op counts at N=5000: first
+open drops reads 5000→100 (~98%), steady-state re-open is 0 reads, search warms once
+then 0. **Clear all** remains the relief valve for an overgrown store; pagination is
+the steady-state fix.
+
 ## Design choices worth knowing
 
 - **Pure modules split for testability.** Everything tagged "(pure)" above has no
@@ -227,7 +262,13 @@ The full pedagogical write-up lives in
   `grok.defaultModel` and restarts — `newSession` re-applies the model *before* the
   primer runs, while the agent is still rebindable. No history → transparent
   restart; with history → the same Summarize / Just-Restart choice as an effort
-  change.
+  change. A restart on a *primer-only* session (no real conversation — common when
+  you flip models/effort right after opening) takes the no-prompt path **and**
+  discards the abandoned grok session dir afterward, so repeated switches don't pile
+  up identical empty sessions in history; the pure `carrySessionName` moves any user
+  rename onto the fresh session so the chosen name survives. The same cleanup runs on
+  the effort-change empty-session branch, guarded so a dead client on a session *with*
+  history keeps its history.
 - **Generated media is path-based, not an ACP image block.** `/imagine` and
   `/imagine-video` write a file into the session dir and report its *path* as
   JSON-in-text on the completed tool result. The host parses the path, classifies

docs/architecture.md

@@ -1457,6 +1457,36 @@ body.dragging { outline: 2px dashed var(--vscode-focusBorder); outline-offset: -
   font-size: 12px;
   text-align: center;
 }
+.history-more {
+  padding: 8px;
+  color: var(--vscode-descriptionForeground);
+  font-size: 11px;
+  text-align: center;
+  opacity: 0.7;
+}
+.history-footer {
+  padding: 4px;
+  border-top: 1px solid var(--vscode-editorWidget-border, rgba(255,255,255,0.08));
+}
+.history-clear-all {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  width: 100%;
+  padding: 6px 8px;
+  font-size: 12px;
+  font-family: inherit;
+  color: var(--vscode-descriptionForeground);
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+.history-clear-all:hover {
+  color: var(--vscode-errorForeground);
+  background: var(--vscode-toolbar-hoverBackground, rgba(255,255,255,0.08));
+}
 .history-row {
   display: flex;
   align-items: center;