@cortexkit/opencode-magic-context 0.32.0 → 0.32.2

package/src/shared/rpc-notifications.test.ts

@@ -70,10 +70,25 @@ describe("rpc notifications", () => {
         expect(isTuiConnected()).toBe(false);
     });
 
-    test("a session-less sink counts as connected for any session query", () => {
+    test("a modern session-less sink is global-only", () => {
+        const received: string[] = [];
+        const unregister = registerNotificationSink({
+            sessionId: undefined,
+            protocol: 2,
+            send: (notification) => received.push(notification.type),
+        });
+        expect(isTuiConnected("ses_whatever")).toBe(false);
+        expect(isTuiConnected()).toBe(true);
+
+        pushNotification("scoped", { ok: true }, "ses_whatever");
+        pushNotification("global", { ok: true });
+        expect(received).toEqual(["global"]);
+        unregister();
+    });
+
+    test("a legacy session-less sink retains broad compatibility", () => {
         const unregister = registerNotificationSink({ sessionId: undefined, send: () => {} });
         expect(isTuiConnected("ses_whatever")).toBe(true);
-        expect(isTuiConnected()).toBe(true);
         unregister();
     });
 
@@ -117,14 +132,20 @@ describe("rpc notifications", () => {
 
     test("queue-cap eviction is session-fair: a noisy session cannot evict another session's newest unseen item", () => {
         drainNotifications(Number.MAX_SAFE_INTEGER);
-        // One quiet session with a single pending dialog.
         pushNotification("quiet-dialog", { action: "show-upgrade-dialog" }, "ses_quiet");
-        // A noisy session floods well past the 100 cap.
         for (let i = 0; i < 200; i += 1) {
             pushNotification("noise", { i }, "ses_noisy");
         }
-        // The quiet session's newest item must survive the eviction.
         const quietPoll = drainNotifications(0, "ses_quiet");
         expect(quietPoll.some((m) => m.type === "quiet-dialog")).toBe(true);
+        expect(drainNotifications(0)).toHaveLength(100);
+    });
+
+    test("queue cap remains global across more than one hundred sessions", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        for (let i = 0; i < 250; i += 1) {
+            pushNotification("one-per-session", { i }, `ses_${i}`);
+        }
+        expect(drainNotifications(0)).toHaveLength(100);
     });
 });

package/src/shared/rpc-notifications.ts

@@ -26,6 +26,8 @@ let nextNotificationId = 1;
 export interface NotificationSink {
     /** The TUI's active session at connect time (its hello scope). */
     sessionId?: string;
+    /** Protocol 2 clients use strict session scoping; absent means legacy behavior. */
+    protocol?: number;
     /** Deliver one notification over this sink's live socket. */
     send: (notification: RpcNotification) => void;
 }
@@ -48,23 +50,19 @@ export function registerNotificationSink(sink: NotificationSink): () => void {
     };
 }
 
-/** Whether a given notification may be delivered to a given sink. A global
- *  notification (no sessionId) reaches every sink; a session-scoped one reaches
- *  only sinks for that session (or session-less sinks). Mirrors the drain filter
- *  from the sink's perspective. */
+/** Whether a notification may be delivered to a sink. Protocol 2 makes a
+ * session-less socket global-only; legacy sockets retain broad compatibility. */
 function notificationMatchesSink(notification: RpcNotification, sink: NotificationSink): boolean {
-    return (
-        notification.sessionId === undefined ||
-        sink.sessionId === undefined ||
-        notification.sessionId === sink.sessionId
-    );
+    if (notification.sessionId === undefined) return true;
+    if (sink.sessionId !== undefined) return notification.sessionId === sink.sessionId;
+    return sink.protocol !== 2;
 }
 
 /** Push a notification to the TUI. Fans out to any live WS sink immediately and
  *  also enqueues it so a TUI that is momentarily disconnected (reconnecting, or
  *  not yet connected) still receives it on its next hello via the backlog drain.
  *  At-least-once: a live push that the socket drops is re-delivered from the
- *  queue on reconnect (pruned only when the client acks via `lastReceivedId`). */
+ *  queue on reconnect (pruned only when the client acknowledges it). */
 export function pushNotification(
     type: string,
     payload: Record<string, unknown>,
@@ -83,30 +81,40 @@ export function pushNotification(
             // unregister it, and the queue backlog re-delivers on reconnect.
         }
     }
-    // Cap queue size to prevent unbounded growth if a TUI is not draining.
-    // Session-FAIR eviction: a naive `slice(-50)` drops the globally-oldest
-    // items, so a noisy session could evict ANOTHER session's single unseen
-    // notification. Instead, always retain each session's newest item, then
-    // fill the rest of the budget with the newest overall — no session can
-    // starve another's pending dialog out of the window.
+    // Keep a strict global bound. Reserve the newest item for at most 25 recently
+    // active scopes, then evict the oldest unreserved item. This protects a quiet
+    // session from one noisy peer without allowing one item per session to grow
+    // the queue without limit.
     if (queue.length > 100) {
-        const newestPerSession = new Map<string | undefined, number>();
-        for (const n of queue) {
-            const prev = newestPerSession.get(n.sessionId);
-            if (prev === undefined || n.id > prev) {
-                newestPerSession.set(n.sessionId, n.id);
-            }
+        const reservedIds = new Set<number>();
+        const reservedScopes = new Set<string>();
+        for (let i = queue.length - 1; i >= 0 && reservedScopes.size < 25; i -= 1) {
+            const candidate = queue[i];
+            const scope = candidate.sessionId ?? "\0global";
+            if (reservedScopes.has(scope)) continue;
+            reservedScopes.add(scope);
+            reservedIds.add(candidate.id);
         }
-        const mustKeep = new Set(newestPerSession.values());
-        const byNewest = [...queue].sort((a, b) => b.id - a.id);
-        const kept: RpcNotification[] = [];
-        for (const n of byNewest) {
-            if (kept.length < 50 || mustKeep.has(n.id)) kept.push(n);
-        }
-        queue = kept.sort((a, b) => a.id - b.id);
+        const evictionIndex = queue.findIndex((candidate) => !reservedIds.has(candidate.id));
+        queue.splice(evictionIndex >= 0 ? evictionIndex : 0, 1);
     }
 }
 
+export function acknowledgeNotifications(ids: readonly number[]): void {
+    const acknowledged = new Set(ids.filter((id) => Number.isSafeInteger(id) && id > 0));
+    if (acknowledged.size === 0) return;
+    // Exact removal preserves an earlier notification when a later handler finishes
+    // first or the earlier handler declines to consume its notification.
+    queue = queue.filter((notification) => !acknowledged.has(notification.id));
+}
+
+/** Reset process-local state to simulate a fresh server module in protocol tests. */
+export function __resetNotificationStateForTests(): void {
+    queue = [];
+    nextNotificationId = 1;
+    sinks.clear();
+}
+
 export interface DrainNotificationsOptions {
     /**
      * Cursor for global notifications when a session-scoped client sends separate
@@ -133,8 +141,8 @@ function cursor(value: number | undefined): number {
  *  behavior.
  *
  *  Delivery is at-least-once (non-destructive return + prune-on-ack): a returned
- *  notification stays queued until a later call acks it via the matching scope's
- *  cursor, so a dropped WS socket re-delivers unhandled backlog on reconnect. */
+ *  notification stays queued until an exact acknowledgement or a legacy cursor
+ *  removes it, so a dropped WS socket re-delivers unhandled backlog on reconnect. */
 export function drainNotifications(
     lastReceivedId = 0,
     sessionId?: string,
@@ -200,14 +208,15 @@ export function drainNotifications(
  *  Pass `sessionId` (preferred) to ask whether a TUI is connected FOR THAT
  *  SESSION — this is what producers (`/ctx-status`, `/ctx-recomp`, the upgrade
  *  reminder) must use to decide dialog-vs-message, so a TUI on a different
- *  session in the same process does not misroute their delivery. A session-less
- *  sink (legacy/global) counts for any session query. Omit `sessionId` only for
- *  callers with no session context; they get "any sink connected". */
+ *  session in the same process does not misroute their delivery. A modern
+ *  session-less sink is global-only; a legacy sink retains broad compatibility.
+ *  Omit `sessionId` only for callers with no session context. */
 export function isTuiConnected(sessionId?: string): boolean {
     if (sinks.size === 0) return false;
     if (sessionId === undefined) return true;
     for (const sink of sinks) {
-        if (sink.sessionId === undefined || sink.sessionId === sessionId) return true;
+        if (sink.sessionId === sessionId) return true;
+        if (sink.sessionId === undefined && sink.protocol !== 2) return true;
     }
     return false;
 }

package/src/shared/rpc-server.ts

@@ -13,6 +13,7 @@ import { dirname } from "node:path";
 import type { Server, ServerWebSocket } from "bun";
 import { log } from "./logger";
 import {
+    acknowledgeNotifications,
     drainNotifications,
     type NotificationSink,
     registerNotificationSink,
@@ -57,8 +58,12 @@ function bearerToken(req: Request): string {
     return typeof auth === "string" ? auth.replace(/^Bearer\s+/i, "") : "";
 }
 
-function websocketToken(req: Request, url: URL): string {
-    return bearerToken(req) || url.searchParams.get("token") || "";
+function websocketToken(req: Request): string {
+    const headerToken = bearerToken(req);
+    if (headerToken) return headerToken;
+    // v0.32 TUI clients put the token in the upgrade URL. Keep this fallback only
+    // for the v0.32→v0.32.1 skew window; remove it when v0.32 clients are unsupported.
+    return new URL(req.url).searchParams.get("token") ?? "";
 }
 
 /**
@@ -242,7 +247,7 @@ export class MagicContextRpcServer {
         // WebSocket upgrade — the persistent push channel. Authenticate before
         // `srv.upgrade` so an unauthorized request never becomes a live socket.
         if (url.pathname === "/ws") {
-            if (!tokensMatch(websocketToken(req, url), this.token)) {
+            if (!tokensMatch(websocketToken(req), this.token)) {
                 return new Response("Unauthorized", { status: 401 });
             }
             const ok = srv.upgrade(req, { data: { authed: false } });
@@ -253,7 +258,7 @@ export class MagicContextRpcServer {
         // No wildcard CORS: the only legitimate client is the in-process TUI
         // client, not a browser origin.
         if (req.method === "GET" && url.pathname === "/health") {
-            return json({ ok: true, pid: process.pid });
+            return json({ ok: true, pid: process.pid, instance_id: this.instanceId });
         }
 
         if (req.method !== "POST" || !url.pathname.startsWith("/rpc/")) {
@@ -293,8 +298,8 @@ export class MagicContextRpcServer {
         }
     }
 
-    /** WS message handler: hello (auth + sink registration + backlog drain) and
-     *  ack (cursor advance → queue prune). All other messages are ignored. */
+    /** WS message handler: hello (auth + sink registration + backlog delivery) and
+     *  ack (exact removal or legacy cursor pruning). All other messages are ignored. */
     private handleWsMessage(ws: ServerWebSocket<WsData>, raw: string | Buffer): void {
         let msg: {
             type?: string;
@@ -303,6 +308,10 @@ export class MagicContextRpcServer {
             lastReceivedId?: number;
             globalLastReceivedId?: number;
             ackScope?: string;
+            protocol?: number;
+            instanceId?: string;
+            ids?: unknown;
+            cursor?: number;
         };
         try {
             msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
@@ -336,6 +345,7 @@ export class MagicContextRpcServer {
             // Register a live sink so future pushes reach this socket immediately.
             const sink: NotificationSink = {
                 sessionId: ws.data.sessionId,
+                protocol: msg.protocol,
                 send: (notification) => {
                     ws.send(JSON.stringify({ type: "notification", notification }));
                 },
@@ -343,40 +353,66 @@ export class MagicContextRpcServer {
             ws.data.unregister = registerNotificationSink(sink);
             this.sockets.add(ws);
 
-            // Deliver any backlog the client hasn't seen (at-least-once). Modern
-            // clients send separate session and global cursors; keeping those
-            // watermarks independent prevents a high id in one session from pruning
-            // lower unseen notifications in another session.
-            const lastReceivedId = Number(msg.lastReceivedId ?? 0);
-            const sessionCursor = Number.isFinite(lastReceivedId) ? lastReceivedId : 0;
-            const hasGlobalCursor = typeof msg.globalLastReceivedId === "number";
-            const globalLastReceivedId = hasGlobalCursor
-                ? Number.isFinite(msg.globalLastReceivedId)
-                    ? msg.globalLastReceivedId
-                    : 0
-                : 0;
-            const backlog =
-                ws.data.sessionId === undefined && hasGlobalCursor
-                    ? drainNotifications(globalLastReceivedId, undefined, { globalOnly: true })
-                    : drainNotifications(
-                          sessionCursor,
-                          ws.data.sessionId,
-                          hasGlobalCursor
-                              ? { globalLastReceivedId: globalLastReceivedId }
-                              : undefined,
-                      );
+            const usesExactAcknowledgements = msg.protocol === 2;
+            // The epoch arrives before backlog frames so the client can discard
+            // cursors and deduplication entries from a replaced server first.
+            ws.send(
+                JSON.stringify({
+                    type: "hello-ack",
+                    protocol: 2,
+                    instanceId: this.instanceId,
+                }),
+            );
+
+            let backlog: ReturnType<typeof drainNotifications>;
+            if (usesExactAcknowledgements) {
+                // Protocol 2 never treats a high handled id as proof that lower ids
+                // were consumed. Exact acknowledgements are the only destructive
+                // operation, so declined or interrupted dialogs survive reconnects.
+                backlog =
+                    ws.data.sessionId === undefined
+                        ? drainNotifications(0, undefined, { globalOnly: true })
+                        : drainNotifications(0, ws.data.sessionId, {
+                              globalLastReceivedId: 0,
+                          });
+            } else {
+                // Legacy clients use independent session and global watermarks.
+                const lastReceivedId = Number(msg.lastReceivedId ?? 0);
+                const sessionCursor = Number.isFinite(lastReceivedId) ? lastReceivedId : 0;
+                const hasGlobalCursor = typeof msg.globalLastReceivedId === "number";
+                const globalLastReceivedId = hasGlobalCursor
+                    ? Number.isFinite(msg.globalLastReceivedId)
+                        ? msg.globalLastReceivedId
+                        : 0
+                    : 0;
+                backlog =
+                    ws.data.sessionId === undefined && hasGlobalCursor
+                        ? drainNotifications(globalLastReceivedId, undefined, { globalOnly: true })
+                        : drainNotifications(
+                              sessionCursor,
+                              ws.data.sessionId,
+                              hasGlobalCursor
+                                  ? { globalLastReceivedId: globalLastReceivedId }
+                                  : undefined,
+                          );
+            }
             for (const notification of backlog) {
                 ws.send(JSON.stringify({ type: "notification", notification }));
             }
-            ws.send(JSON.stringify({ type: "hello-ack" }));
             return;
         }
 
         if (msg.type === "ack") {
-            // Advance only the cursor scope the client handled. Acking session A
-            // must not prune session B, and acking a global notification must not
-            // become a session watermark. Cheap, event-driven queue cleanup.
-            const lastReceivedId = Number(msg.lastReceivedId ?? 0);
+            if (Array.isArray(msg.ids)) {
+                acknowledgeNotifications(
+                    msg.ids.filter((id): id is number => typeof id === "number"),
+                );
+                return;
+            }
+
+            // Keep watermark acknowledgements during the one-release skew window.
+            // Scope isolation remains mandatory for these legacy messages.
+            const lastReceivedId = Number(msg.cursor ?? msg.lastReceivedId ?? 0);
             if (Number.isFinite(lastReceivedId) && lastReceivedId > 0) {
                 if (msg.ackScope === "global") {
                     drainNotifications(lastReceivedId, undefined, { globalOnly: true });

package/src/shared/rpc-types.ts

@@ -67,6 +67,9 @@ export interface SidebarSnapshot {
      * scheduler and transform paths.
      */
     executeThreshold: number;
+    /** Rust module cache boundary state, when the session uses Rust authority mode. */
+    boundaryPresent?: boolean;
+    coverageOrdinal?: number | null;
     newWorkTokens?: number | null;
     totalInputTokens?: number | null;
     /**

package/src/shared/sqlite.ts

@@ -137,11 +137,15 @@ function buildNodeSqliteDatabaseClass(DatabaseSync: any): typeof BetterSqlite3 {
         transaction<F extends (...args: any[]) => any>(fn: F): F {
             // biome-ignore lint/suspicious/noExplicitAny: faithful pass-through of this/args to fn.
             const self = this as any;
-            const wrapped = function (this: unknown, ...args: unknown[]): unknown {
+            const execute = (
+                mode: "" | "DEFERRED" | "IMMEDIATE" | "EXCLUSIVE",
+                receiver: unknown,
+                args: unknown[],
+            ) => {
                 const nested = self.isTransaction === true;
-                self.exec(nested ? `SAVEPOINT ${SAVEPOINT}` : "BEGIN");
+                self.exec(nested ? `SAVEPOINT ${SAVEPOINT}` : `BEGIN${mode ? ` ${mode}` : ""}`);
                 try {
-                    const result = fn.apply(this, args);
+                    const result = fn.apply(receiver, args);
                     self.exec(nested ? `RELEASE ${SAVEPOINT}` : "COMMIT");
                     return result;
                 } catch (error) {
@@ -157,6 +161,21 @@ function buildNodeSqliteDatabaseClass(DatabaseSync: any): typeof BetterSqlite3 {
                     throw error;
                 }
             };
+            const wrapped = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("", this, args);
+            };
+            wrapped.default = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("", this, args);
+            };
+            wrapped.deferred = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("DEFERRED", this, args);
+            };
+            wrapped.immediate = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("IMMEDIATE", this, args);
+            };
+            wrapped.exclusive = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("EXCLUSIVE", this, args);
+            };
             return wrapped as unknown as F;
         }
     }

package/src/shared/tui-config.test.ts

@@ -4,11 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 const roots: string[] = [];
-const prevConfigDir = process.env.OPENCODE_CONFIG_DIR;
-
 afterEach(() => {
-    if (prevConfigDir === undefined) delete process.env.OPENCODE_CONFIG_DIR;
-    else process.env.OPENCODE_CONFIG_DIR = prevConfigDir;
     for (const root of roots.splice(0)) {
         rmSync(root, { recursive: true, force: true });
     }
@@ -18,7 +14,6 @@ describe("ensureTuiPluginEntry", () => {
     it("preserves tuple dev-path plugin entry and does not add @latest", async () => {
         const root = mkdtempSync(join(tmpdir(), "mc-tui-"));
         roots.push(root);
-        process.env.OPENCODE_CONFIG_DIR = root;
         const devPath = "/Work/magic-context/packages/plugin";
         const tuiPath = join(root, "tui.json");
         writeFileSync(
@@ -27,7 +22,7 @@ describe("ensureTuiPluginEntry", () => {
         );
 
         const { ensureTuiPluginEntry } = await import("./tui-config");
-        const changed = ensureTuiPluginEntry();
+        const changed = ensureTuiPluginEntry({ configDir: root });
         expect(changed).toBe(false);
         const parsed = JSON.parse(readFileSync(tuiPath, "utf-8")) as { plugin: unknown[] };
         expect(parsed.plugin).toHaveLength(2);
@@ -40,7 +35,6 @@ describe("ensureTuiPluginEntry", () => {
     it("upgrades bare npm name to @latest while preserving tuple options", async () => {
         const root = mkdtempSync(join(tmpdir(), "mc-tui-npm-"));
         roots.push(root);
-        process.env.OPENCODE_CONFIG_DIR = root;
         const tuiPath = join(root, "tui.json");
         writeFileSync(
             tuiPath,
@@ -54,7 +48,7 @@ describe("ensureTuiPluginEntry", () => {
         );
 
         const { ensureTuiPluginEntry } = await import("./tui-config");
-        expect(ensureTuiPluginEntry()).toBe(true);
+        expect(ensureTuiPluginEntry({ configDir: root })).toBe(true);
         const parsed = JSON.parse(readFileSync(tuiPath, "utf-8")) as { plugin: unknown[] };
         const entry = parsed.plugin[0] as unknown[];
         expect(entry[0]).toBe("@cortexkit/opencode-magic-context@latest");
@@ -64,10 +58,9 @@ describe("ensureTuiPluginEntry", () => {
     it("creates tui.jsonc (not tui.json) on a fresh install", async () => {
         const root = mkdtempSync(join(tmpdir(), "mc-tui-fresh-"));
         roots.push(root);
-        process.env.OPENCODE_CONFIG_DIR = root;
 
         const { ensureTuiPluginEntry } = await import("./tui-config");
-        expect(ensureTuiPluginEntry()).toBe(true);
+        expect(ensureTuiPluginEntry({ configDir: root })).toBe(true);
 
         // The new file must be tui.jsonc so a tui.json stub never ends up
         // sitting next to a tui.jsonc the user writes later (#176).
@@ -82,7 +75,6 @@ describe("ensureTuiPluginEntry", () => {
     it("writes into the existing tui.jsonc when both files exist", async () => {
         const root = mkdtempSync(join(tmpdir(), "mc-tui-both-"));
         roots.push(root);
-        process.env.OPENCODE_CONFIG_DIR = root;
         // A real user config in tui.jsonc plus a leftover empty tui.json.
         writeFileSync(
             join(root, "tui.jsonc"),
@@ -91,7 +83,7 @@ describe("ensureTuiPluginEntry", () => {
         writeFileSync(join(root, "tui.json"), "{}\n");
 
         const { ensureTuiPluginEntry } = await import("./tui-config");
-        expect(ensureTuiPluginEntry()).toBe(true);
+        expect(ensureTuiPluginEntry({ configDir: root })).toBe(true);
 
         // The plugin entry must land in tui.jsonc (higher precedence), and the
         // user's keybinds must survive; tui.json must be left untouched.

package/src/shared/tui-config.ts

@@ -62,8 +62,8 @@ function writeTuiConfigAtomic(configPath: string, config: Record<string, unknown
     renameSync(tmpPath, configPath);
 }
 
-function resolveTuiConfigPath(): string {
-    const configDir = getOpenCodeConfigPaths({ binary: "opencode" }).configDir;
+function resolveTuiConfigPath(configDirOverride?: string): string {
+    const configDir = configDirOverride ?? getOpenCodeConfigPaths({ binary: "opencode" }).configDir;
     const jsoncPath = join(configDir, "tui.jsonc");
     const jsonPath = join(configDir, "tui.json");
 
@@ -80,12 +80,12 @@ function resolveTuiConfigPath(): string {
 }
 
 /**
- * Ensure tui.json has the magic-context TUI plugin entry.
- * Creates tui.json if it doesn't exist. Silently skips if already present.
+ * Ensure the selected TUI config has the magic-context plugin entry.
+ * Creates tui.jsonc if neither TUI config exists. Silently skips if already present.
  */
-export function ensureTuiPluginEntry(): boolean {
+export function ensureTuiPluginEntry(options: { configDir?: string } = {}): boolean {
     try {
-        const configPath = resolveTuiConfigPath();
+        const configPath = resolveTuiConfigPath(options.configDir);
 
         let config: Record<string, unknown> = {};
         if (existsSync(configPath)) {

package/src/tui/data/context-db.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MagicContextRpcServer } from "../../shared/rpc-server";
+import type { SidebarSnapshot } from "../../shared/rpc-types";
+import { closeRpc, getCompartmentCount, initRpcClient, loadSidebarSnapshot } from "./context-db";
+
+const originalXdgDataHome = process.env.XDG_DATA_HOME;
+const tempDirs: string[] = [];
+const servers: MagicContextRpcServer[] = [];
+
+afterEach(() => {
+    closeRpc();
+    for (const server of servers.splice(0)) server.stop();
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    }
+    if (originalXdgDataHome === undefined) delete process.env.XDG_DATA_HOME;
+    else process.env.XDG_DATA_HOME = originalXdgDataHome;
+});
+
+function makeDataHome(): string {
+    const dir = mkdtempSync(join(tmpdir(), "mc-context-db-"));
+    tempDirs.push(dir);
+    process.env.XDG_DATA_HOME = dir;
+    return dir;
+}
+
+function snapshot(sessionId: string, inputTokens: number): SidebarSnapshot {
+    return {
+        sessionId,
+        usagePercentage: inputTokens > 0 ? 25 : 0,
+        inputTokens,
+        contextLimit: 1000,
+        systemPromptTokens: 0,
+        compartmentCount: inputTokens > 0 ? 2 : 0,
+        memoryCount: 0,
+        memoryBlockCount: 0,
+        pendingOpsCount: 0,
+        historianRunning: false,
+        compartmentInProgress: false,
+        sessionNoteCount: 0,
+        readySmartNoteCount: 0,
+        cacheTtl: "5m",
+        lastDreamerRunAt: null,
+        projectIdentity: null,
+        compartmentTokens: 0,
+        factTokens: 0,
+        memoryTokens: 0,
+        docsTokens: 0,
+        profileTokens: 0,
+        conversationTokens: inputTokens,
+        toolCallTokens: 0,
+        toolDefinitionTokens: 0,
+        executeThreshold: 65,
+        newWorkTokens: null,
+        totalInputTokens: inputTokens,
+    };
+}
+
+async function startServer(
+    dataHome: string,
+    directory: string,
+    sidebar: () => Record<string, unknown>,
+): Promise<MagicContextRpcServer> {
+    const server = new MagicContextRpcServer(
+        join(dataHome, "cortexkit", "magic-context"),
+        directory,
+    );
+    server.handle("sidebar-snapshot", async () => sidebar());
+    await server.start();
+    servers.push(server);
+    return server;
+}
+
+describe("TUI context RPC data", () => {
+    test("uses an unexpired sticky snapshot only for failed responses", async () => {
+        const dataHome = makeDataHome();
+        const directory = "/repo-sticky";
+        const sessionId = "ses_sticky";
+        let response: Record<string, unknown> = snapshot(sessionId, 250) as unknown as Record<
+            string,
+            unknown
+        >;
+        await startServer(dataHome, directory, () => response);
+        initRpcClient(directory);
+
+        expect((await loadSidebarSnapshot(sessionId, directory)).inputTokens).toBe(250);
+        response = { error: "database busy" };
+        expect((await loadSidebarSnapshot(sessionId, directory)).inputTokens).toBe(250);
+
+        response = snapshot(sessionId, 0) as unknown as Record<string, unknown>;
+        expect((await loadSidebarSnapshot(sessionId, directory)).inputTokens).toBe(0);
+        response = { error: "database busy again" };
+        expect((await loadSidebarSnapshot(sessionId, directory)).inputTokens).toBe(0);
+    });
+
+    test("distinguishes a real zero compartment count from an RPC failure", async () => {
+        const dataHome = makeDataHome();
+        const directory = "/repo-count";
+        const server = await startServer(dataHome, directory, () => ({}));
+        server.handle("compartment-count", async () => ({ count: 0 }));
+        initRpcClient(directory);
+
+        expect(await getCompartmentCount("ses_zero")).toEqual({ ok: true, count: 0 });
+        server.handle("compartment-count", async () => {
+            throw new Error("database unavailable");
+        });
+        const failed = await getCompartmentCount("ses_zero");
+        expect(failed.ok).toBe(false);
+    });
+});