Multi-session Agent Dashboard + eager non-blocking primer (v1.4.8)

Keeps a pool of live grok sessions instead of one — instant lossless
re-focus (each session buffers its webview posts, so focusing replays
the buffer with no grok reload or kill), status dots in the history
dropdown (a derived, persisted unread badge that survives idle reaping
and a VS Code restart), and silent idle-TTL + LRU reaping that never
touches the focused or a working/needs-you session.

Also fixes the pre-turn primer latency. The hidden plan-mode primer now
fires eagerly + non-blocking the moment a session goes live (new,
restore, post-/compact) instead of in front of the user's first prompt.
The first real send awaits the same in-flight primer turn and is
released the instant it acks; the user's bubble shows immediately with a
"Grokking…" indicator standing in until grok produces content. The
primer was trimmed to v4 — the product-blurb paragraph + repo URL that
tempted agentic grok into a 15–40s pre-turn workspace exploration are
gone, replaced by an explicit do-not-act / "reply with just ok"
constraint. The plan-verdict protocol itself is unchanged.

473 tests (15 new); live gate green (5 passed, image-gen SKIP).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: phuryn

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.4.8 — 2026-06-15
+
+> Run several Grok sessions at once — switch between them instantly, and see at a glance which one needs you.
+
+### Features
+
+- **Multi-session Agent Dashboard.** The sidebar now keeps several sessions *alive* at once instead of one at a time. Switching between them from the history dropdown is **instant and lossless** — the conversation you switch away from keeps running in the background (mid-turn, mid-approval, anything), and switching back replays its exact state with no reload. Picking a session that isn't live anymore loads it from history as before. ([src/sidebar.ts](src/sidebar.ts), [src/session.ts](src/session.ts))
+- **Status dots in the history dropdown.** Every session shows a dot so you can see what each one is doing without opening it. It's **gray** at rest, and only lights up when there's something to know: **blue** = working, **yellow** = needs you (a permission, question, or plan to review), **green** = finished with output you haven't opened yet, **red** = finished with an error you haven't opened. The green/red marker is an *unread* badge — it clears the moment you open the session, and it's **persisted**, so it survives the idle cleanup below and even a VS Code restart. Walk away, come back, and the green sessions are exactly the ones with results waiting. ([media/chat.js](media/chat.js), [media/chat.css](media/chat.css), [src/session-pool.ts](src/session-pool.ts))
+- **Idle sessions are cleaned up automatically.** To keep a pile of background sessions from each holding a live process, a session left untouched for an hour — or beyond a cap of ~8 live — is quietly shut down (never one that's working or waiting on you). It reappears in history and reloads on click, so nothing is lost. ([src/session-pool.ts](src/session-pool.ts))
+- **Updating the Grok Build CLI warns about sessions in progress.** With multiple sessions now able to run at once, the *Update Grok Build CLI* action confirms before it restarts when any session is mid-turn or waiting on you — so an update doesn't silently interrupt work in a background session. ([src/sidebar.ts](src/sidebar.ts))
+- **No more long pause before Grok starts.** Sending your first message used to sit silent for 15–40 seconds before anything appeared. Behind the scenes the extension primes each session with a hidden plan-mode instruction, and that primer was running *in front of* your first message and — because Grok Build is an agentic CLI — was wandering off to read files and search the workspace before your real prompt even ran. The primer now fires **the moment a session goes live**, silently in the background, so it's almost always finished before you hit send; if you're quick, your message shows immediately and is released the instant the primer settles. The primer text itself was also trimmed to just the protocol it needs to teach (the product blurb and repo link that were tempting Grok to go exploring are gone), so it completes in a beat instead of dozens of seconds. ([src/sidebar.ts](src/sidebar.ts), [src/grok-primer.ts](src/grok-primer.ts), [src/session.ts](src/session.ts))
+- **A "Grokking…" indicator while you wait.** Every turn now shows an animated *Grokking…* placeholder the instant you send, so there's immediate feedback that Grok received your message — it's replaced in place the moment the first thought, reply, or tool action arrives. ([media/chat.js](media/chat.js), [media/chat.css](media/chat.css))
+
 ## 1.4.7 — 2026-06-15
 
 > Sharper math, and one-click export for equations and diagrams.

CLAUDE.md

@@ -137,6 +137,36 @@ The active editor is added as an **implicit** chip automatically (toggle with `g
 
 </details>
 
+<details>
+<summary><strong>Agent Dashboard</strong> — run several sessions at once, switch instantly, see which need you</summary>
+
+Keep more than one session **alive at the same time**. Start a new session with **+** while another is mid-turn, and switch between them from the history dropdown — the one you leave keeps running in the background (mid-turn, mid-approval, anything), and switching back replays its exact state with **no reload**. Picking a session that isn't live anymore loads it from history as before.
+
+Each row in the dropdown shows a **status dot** so you can see what every session is doing without opening it. It's **gray** at rest and only lights up when there's something to know:
+
+| Dot | Meaning |
+|---|---|
+| 🔵 Blue | Working — a turn is in flight |
+| 🟡 Yellow | Needs you — a permission, question, or plan is waiting |
+| 🟢 Green | Finished, with output you **haven't opened yet** |
+| 🔴 Red | Finished with an error you haven't opened |
+| ⚪ Gray | At rest — idle, already read, or not loaded |
+
+The green/red dot is an **unread** badge: it appears when a session finishes while you're looking at *another* one, and clears the moment you open it. It's persisted, so it survives idle cleanup **and** a VS Code restart — fire off a few agents, walk away, and the green dots are exactly the sessions with results waiting.
+
+To keep a pile of background sessions from each pinning a live process, a session left untouched for an hour (or beyond ~8 live) is quietly shut down — never one that's working or waiting on you — and reloads from history on click, losing nothing.
+
+</details>
+
+<details>
+<summary><strong>Instant feedback</strong> — a <em>Grokking…</em> indicator the moment you send, with no startup pause</summary>
+
+Every message you send shows an animated **Grokking…** placeholder immediately, so there's always feedback that Grok received it — it's replaced in place the instant the first thought, reply, or tool action streams in.
+
+There's also no longer a long silent pause before that first response. The extension primes each new session with a hidden plan-mode instruction; that primer now runs **eagerly in the background** the moment the session goes live (and on resume, and after `/compact`) instead of sitting in front of your first message — so it's almost always finished before you hit send. If you *are* quick, your message appears right away and is released the instant the primer settles. The primer text was also slimmed down so it completes in a beat rather than wandering off to read your workspace first.
+
+</details>
+
 <details>
 <summary><strong>Session history</strong> — resume, rename, or delete any past session</summary>
 
@@ -261,7 +291,7 @@ Grok's own **slash commands** (`/imagine`, `/compact`, …) autocomplete in the
 
 The extension is intentionally **thin**: it speaks JSON-RPC over `grok agent stdio` and renders the results. Grok owns sessions, memory, MCP, models, and tool execution; the extension mediates file reads/writes, terminal requests, diff previews, the webview UI — and **Plan Mode**.
 
-Plan Mode is the one place the extension is *not* thin. The CLI's `exit_plan_mode` is unreliable (it reports "approved" to any reply), so the extension enforces planning itself: a **gate** blocks workspace writes and non-read-only commands until you approve, and a hidden **primer** message teaches Grok to read your real verdict (`[Plan approved]` / `[Plan rejected]` / `[Plan cancelled]`) from your next message.
+Plan Mode is the one place the extension is *not* thin. The CLI's `exit_plan_mode` is unreliable (it reports "approved" to any reply), so the extension enforces planning itself: a **gate** blocks workspace writes and non-read-only commands until you approve, and a hidden **primer** message teaches Grok to read your real verdict (`[Plan approved]` / `[Plan rejected]` / `[Plan cancelled]`) from your next message. The primer is fired **eagerly and silently** the instant a session goes live (not in front of your first prompt), and is kept lean so it doesn't add a startup pause — your first real message simply waits, in code, for the silent primer turn to finish (Grok runs one turn at a time) and is released the moment it does.
 
 Full diagram, message flow, module map, and design notes: **[docs/architecture.md](docs/architecture.md)**.
 

README.md

@@ -52,8 +52,77 @@ When the panel opens (or you click **+** for a new session):
    permission requests, mode changes) back into the chat.
 
 The composer unlocks as soon as the session is live. The extension's hidden
-"primer" message (below) is **not** sent at startup — it rides along with your
-first real prompt, so there's no startup round-trip to wait on.
+"primer" message (below) fires **eagerly and silently** the moment the session
+goes live — in the background, without blocking the composer — so it's almost
+always finished before you send. Your first real prompt simply `await`s the same
+in-flight primer turn (grok runs one turn at a time) and is released the instant
+it acks. While any user turn is waiting on grok — including that brief held-behind-
+primer gap — the chat shows an animated **Grokking…** placeholder, replaced in
+place by the first thought / message / tool card.
+
+## The session pool (Agent Dashboard)
+
+The sidebar shows one conversation at a time, but it keeps a **pool of live
+sessions** behind it — one spawned `grok agent stdio` process each, with exactly
+one *focused* (the one you see). All the per-session state lives in a
+[`Session`](../src/session.ts) object; the sidebar holds `focused` plus a `Set` of
+every live `Session` (`pool`). The point is **lossless re-focus**: a backgrounded
+session keeps streaming into its own *view buffer* (every webview post that built
+its chat, in order), so re-focusing it is a `clearMessages` + replay of that
+buffer — no grok reload, no process kill, even mid-turn or mid-approval.
+
+Switching focus (`focusSession`) never touches grok: it swaps `this.focused`,
+replays the target's buffer to the webview, and re-pushes the mode/sessions UI.
+Clicking a session that *isn't* live (cold — it was reaped, or predates this
+window) loads it from grok's on-disk history into a fresh pool member instead
+(`openSession`).
+
+Two details make the pool safe:
+
+- **Per-session generation guard.** Each `Session` owns a `gen` counter, bumped
+  only when *its* client is torn down. Handlers capture their session's `gen` when
+  wired, so a backgrounded session's in-flight events are never judged "stale" just
+  because focus moved elsewhere (the old global counter would have done exactly
+  that).
+- **Session-scoped emit.** `emit(session, …)` buffers to that session and only
+  forwards to the webview when it's the focused one; `post(…)` is for UI-wide
+  messages (status dots, the sessions list) that aren't tied to one chat.
+
+**Status dots.** Every row in the history dropdown shows a dot. It's **gray** at
+rest — and "at rest" is deliberately one bucket: idle, already-read, cold, or
+loaded-from-disk all look the same, because the warm-process-vs-cold distinction is
+an implementation detail no user should have to reason about. It lights up only
+when there's something to know: **blue** working, **yellow** needs-you (a pending
+permission / question / plan review), **green** *finished with output you haven't
+opened yet*, **red** *finished with an error you haven't opened*.
+
+The green/red dot is an **unread badge**, not a live state. When a session's turn
+ends while you're looking at a *different* session, a persisted `unread` flag is set
+(in the same `globalState` session-meta that holds rename overrides); opening that
+session clears it. Because the flag lives in metadata rather than the live process,
+the badge **survives both the idle reaping below and a full VS Code restart** — so
+you can fire off several agents, walk away, and come back to find the green dots are
+exactly the sessions with results waiting. There's no timer: a session you never
+open stays green, because it genuinely *is* still unread. The actual color is a pure
+function ([`computeDot`](../src/session-pool.ts)) of `(live status, unread,
+unreadError)`, so the policy is unit-tested without a process pool. The host pushes
+one changed dot at a time (cheap, no disk read) and the full map on each list
+refresh.
+
+**Reaping** ([src/session-pool.ts](../src/session-pool.ts)). A live process per
+session isn't free, so the pool is bounded — silently. The pure `selectReapable`
+picks victims under two rules: an **idle TTL** (a session untouched for an hour is
+torn down, swept every 5 min) and an **LRU cap** (at most ~8 live; the
+least-recently-used eligible sessions are evicted past it). It **never** reaps the
+focused session or a `working`/`needs-you` one — so the cap can be exceeded when
+everything spare is busy, by design. Reaping just kills the process and recomputes
+the dot — a reaped session that's still unread **stays green**, a read one goes
+gray — and re-clicking the row reloads the session from disk.
+
+One safety valve sits next to this: the explicit **Update Grok Build CLI** action
+tears down every live session to swap the binary, so it now confirms first if any
+session is `working` or `needs-you` (the silent startup auto-update runs before
+anything is in flight, so it doesn't ask).
 
 ## Plan Mode — the one part that isn't thin
 
@@ -76,15 +145,26 @@ the extension can't trust the wire verdict. Two mechanisms cover the gap:
   the real decision from the **next** user message instead, as a bracketed
   marker: `[Plan approved]` / `[Plan rejected]` / `[Plan cancelled]` (optionally
   followed by a free-form comment). Approve → drop the gate + send "implement it
-  now"; Keep planning → the gate stays up. The primer is sent **lazily** —
-  prepended as its own hidden turn right before the first real prompt, on both
-  new **and** restored sessions. It is *re-sent* on the first send after a
-  restore: a primer buried in replayed history isn't reliably honored (a
-  `/compact` can drop it from effective context), so the extension re-asserts it
-  rather than trusting the replay. When grok replays an earlier primer as a user
-  message on restore, the pure `isPrimerText()` helper detects it so the bubble
-  is hidden and not counted toward plan positions — but that detection does
-  **not** mark the session primed.
+  now"; Keep planning → the gate stays up. The primer fires **eagerly and
+  non-blocking** (`ensurePrimed`) — its own hidden turn, kicked off the moment a
+  session goes live (new **and** restored, and after `/compact`) rather than in
+  front of the user's first prompt. It returns a reused `session.primingPromise`,
+  so a first send that races the background primer awaits the *same* turn and is
+  released when it acks. It is *re-sent* on go-live after a restore: a primer
+  buried in replayed history isn't reliably honored (a `/compact` can drop it from
+  effective context), so the extension re-asserts it rather than trusting the
+  replay. The silent turn is hidden by a session-level `suppressContent` flag,
+  which deliberately lets `userMessage`/`agentStart` through so a racing user send
+  still paints its own bubble + Grokking indicator. **Primer v4** is kept minimal
+  on purpose: grok-build is agentic, and the old v3 primer's product-blurb
+  paragraph + repo URL + "acknowledge briefly" line were tempting grok into a
+  15–40s pre-turn exploration of the workspace before the user's message even ran
+  — so v4 keeps only the plan protocol and adds an explicit *do not use tools /
+  read files / search the workspace / take any action; reply with just `ok`*
+  constraint. When grok replays an earlier primer as a user message on restore,
+  the pure `isPrimerText()` helper detects it so the bubble is hidden and not
+  counted toward plan positions — but that detection does **not** mark the session
+  primed.
 
 The full pedagogical write-up lives in
 [research/understanding-plan-mode.md](../research/understanding-plan-mode.md).
@@ -96,6 +176,8 @@ The full pedagogical write-up lives in
 | [src/extension.ts](../src/extension.ts) | Entry point — registers commands, keybindings, output channel |
 | [src/sidebar.ts](../src/sidebar.ts) | Webview provider, message routing, fs handlers, diff preview, logout, generated-media serving (`postGeneratedMedia` → `asWebviewUri`, base64 fallback) |
 | [src/acp.ts](../src/acp.ts) | ACP client — spawns CLI, manages session lifecycle, emits events |
+| [src/session.ts](../src/session.ts) | Per-session state bag — one `Session` per live `grok agent stdio` process (the sidebar holds a *pool* of these + one focused) |
+| [src/session-pool.ts](../src/session-pool.ts) | Pure reaping policy (`selectReapable`) — idle-TTL + LRU cap over the live-session pool |
 | [src/acp-dispatch.ts](../src/acp-dispatch.ts) | Pure protocol helpers — line parsing, update routing, response + generated-media extraction (`isMediaGenToolCall`/`extractGeneratedMediaPaths`) |
 | [src/cli-locator.ts](../src/cli-locator.ts) | Locate the `grok` binary; cross-platform |
 | [src/terminal-manager.ts](../src/terminal-manager.ts) | Headless shells for the agent's `terminal/*` calls |

docs/architecture.md

@@ -337,6 +337,19 @@ code {
   word-wrap: break-word;
 }
 
+/* "Grokking…" — the generic waiting placeholder. Matches the Thinking header's
+   muted font + animated loading-dots, but without the expand chevron (it carries
+   no body) and is not interactive. Replaced in place by real content. */
+.grokking {
+  display: inline-flex;
+  align-items: center;
+  color: var(--vscode-descriptionForeground);
+  font-size: 11px;
+  padding: 3px 10px;
+  margin: 2px 0;
+  user-select: none;
+}
+
 /* ---- file chips in user message history ---- */
 
 .msg-chips {
@@ -1447,6 +1460,20 @@ body.dragging { outline: 2px dashed var(--vscode-focusBorder); outline-offset: -
 }
 .history-row:hover { background: var(--vscode-list-hoverBackground); }
 .history-row.active { background: var(--vscode-list-activeSelectionBackground); }
+.history-row-dot {
+  flex: 0 0 auto;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  /* Gray "at rest" is the default — idle, already-read, cold, and loaded-from-disk
+     all look the same; only the states worth knowing about light up. */
+  background: var(--vscode-descriptionForeground);
+}
+.history-row-dot.dot-none { background: var(--vscode-descriptionForeground); }
+.history-row-dot.dot-working { background: var(--vscode-charts-blue); }
+.history-row-dot.dot-needs-you { background: var(--vscode-charts-yellow); }
+.history-row-dot.dot-unread { background: var(--vscode-charts-green); }
+.history-row-dot.dot-error { background: var(--vscode-errorForeground); }
 .history-row-main { flex: 1; min-width: 0; }
 .history-row-name {
   font-size: 13px;