chore(audit-polish): optional improvements from verification audit

Verification audit of the previous audit-fixes commit (be1a68a) passed with
no blocking issues. Applying the 3 optional low-priority suggestions from
council synthesis:

- `messages-transform.ts`: treat SQLITE_LOCKED as transient alongside
  SQLITE_BUSY (shared-cache conflicts are rare in our setup but covered
  defensively). Add write-if-changed guard for `lastTransformError`:
  persistent errors repeating on every transform pass no longer cause
  redundant WAL writes — we only persist when the summary changes.

- `inject-compartments.ts`: update stale comment on the memory-token
  estimate. Old comment referenced the pre-tokenizer "22-char overhead"
  formula; new comment explains the real tokenizer pipeline and why the
  `+ 6` XML-tag allowance keeps sidebar math consistent.

- `clear-message-tokens-cache.test.ts`: new focused tests covering the
  per-message cache invalidation path (previously only the session-wide
  path had test coverage). Exercises per-message delete, session-wide
  clear, no-op behavior on uncached sessions, and per-session isolation.
  Adds a test-only `__getMessageTokensCacheForTest` accessor on
  transform.ts (not exported from any barrel).

Verified: 540 tests pass (up from 535 — 5 new), typecheck clean, build
clean, lint clean.

Author: ualtinok

packages/plugin/src/hooks/magic-context/clear-message-tokens-cache.test.ts

@@ -0,0 +1,72 @@
+/// <reference types="bun-types" />
+
+/**
+ * Focused tests for clearMessageTokensCache. The cache is consumed by the
+ * transform path (see transform.ts) and invalidated from event-handler.ts on
+ * message.removed / message.updated / session.compacted / session.deleted.
+ *
+ * These tests exercise the two invalidation modes directly so the per-message
+ * path has coverage separate from the session-wide clear path.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { __getMessageTokensCacheForTest, clearMessageTokensCache } from "./transform";
+
+describe("clearMessageTokensCache", () => {
+    describe("#given cached tokens for two messages in one session", () => {
+        it("#when called with a messageId, then only that entry is removed", () => {
+            const sessionId = "ses-clear-per-message";
+            const cache = __getMessageTokensCacheForTest(sessionId);
+            cache.set("msg-a", { conversation: 100, toolCall: 0 });
+            cache.set("msg-b", { conversation: 50, toolCall: 25 });
+
+            clearMessageTokensCache(sessionId, "msg-a");
+
+            expect(cache.has("msg-a")).toBe(false);
+            expect(cache.has("msg-b")).toBe(true);
+            expect(cache.get("msg-b")).toEqual({ conversation: 50, toolCall: 25 });
+        });
+
+        it("#when called without a messageId, then the entire session cache is cleared", () => {
+            const sessionId = "ses-clear-session-wide";
+            const cache = __getMessageTokensCacheForTest(sessionId);
+            cache.set("msg-a", { conversation: 100, toolCall: 0 });
+            cache.set("msg-b", { conversation: 50, toolCall: 25 });
+
+            clearMessageTokensCache(sessionId);
+
+            const after = __getMessageTokensCacheForTest(sessionId);
+            expect(after.size).toBe(0);
+        });
+    });
+
+    describe("#given no cached tokens for a session", () => {
+        it("#when called with a messageId, then it is a no-op (no throw)", () => {
+            expect(() => clearMessageTokensCache("ses-never-cached", "msg-x")).not.toThrow();
+        });
+
+        it("#when called without a messageId, then it is a no-op (no throw)", () => {
+            expect(() => clearMessageTokensCache("ses-never-cached")).not.toThrow();
+        });
+    });
+
+    describe("#given cached tokens for two sessions", () => {
+        it("#when one session is cleared, then the other session's cache is untouched", () => {
+            const s1 = "ses-isolation-1";
+            const s2 = "ses-isolation-2";
+            const c1 = __getMessageTokensCacheForTest(s1);
+            const c2 = __getMessageTokensCacheForTest(s2);
+            c1.set("m1", { conversation: 10, toolCall: 0 });
+            c2.set("m2", { conversation: 20, toolCall: 0 });
+
+            clearMessageTokensCache(s1);
+
+            expect(__getMessageTokensCacheForTest(s1).size).toBe(0);
+            expect(__getMessageTokensCacheForTest(s2).size).toBe(1);
+            expect(__getMessageTokensCacheForTest(s2).get("m2")).toEqual({
+                conversation: 20,
+                toolCall: 0,
+            });
+        });
+    });
+});

packages/plugin/src/hooks/magic-context/inject-compartments.ts

@@ -131,9 +131,12 @@ function trimMemoriesToBudget(
     let usedTokens = 0;
 
     for (const memory of sorted) {
-        // Estimate the rendered memory line ("- {content}") plus category-tag
-        // overhead using the real tokenizer. The 22-char overhead models the
-        // opening/closing XML tags amortized per item.
+        // Estimate the rendered memory line ("- {content}") with the real
+        // Claude tokenizer, plus a fixed ~6-token allowance for opening and
+        // closing XML category tags amortized per item. Keeps units
+        // consistent with rpc-handlers.ts / transform.ts / system-prompt-hash.ts
+        // so the sidebar's "Memories" segment matches what actually lands in
+        // the injection block.
         const memoryTokens = estimateTokens(`- ${memory.content}`) + 6;
         if (usedTokens + memoryTokens > budgetTokens) {
             break;

packages/plugin/src/hooks/magic-context/transform.ts

@@ -85,6 +85,17 @@ export function clearMessageTokensCache(sessionId: string, messageId?: string):
     if (cache) cache.delete(messageId);
 }
 
+/**
+ * Test-only accessor that returns (and lazily creates) the per-session token
+ * cache map so tests can seed and inspect entries without running the full
+ * transform pipeline. Not exported from any barrel.
+ */
+export function __getMessageTokensCacheForTest(
+    sessionId: string,
+): Map<string, { conversation: number; toolCall: number }> {
+    return getMessageTokensCache(sessionId);
+}
+
 /**
  * Extract the provider/model from the last assistant message in the array.
  * Used for early model-change detection before loadContextUsage.

packages/plugin/src/plugin/messages-transform.ts

@@ -1,7 +1,14 @@
-import { openDatabase } from "../features/magic-context/storage";
+import { getOrCreateSessionMeta, openDatabase } from "../features/magic-context/storage";
 import { updateSessionMeta } from "../features/magic-context/storage-meta-session";
 import { log } from "../shared/logger";
 
+// Error codes that SQLite raises for transient contention — should be retried
+// on next transform pass rather than surfaced as persistent failures. BUSY is
+// by far the most common in WAL mode; LOCKED is theoretically possible when a
+// shared-cache conflict occurs (extremely rare in our single-DB setup but
+// covered defensively).
+const TRANSIENT_SQLITE_CODES = new Set(["SQLITE_BUSY", "SQLITE_LOCKED"]);
+
 type MessageWithParts = {
     info: import("@opencode-ai/sdk").Message;
     parts: import("@opencode-ai/sdk").Part[];
@@ -56,20 +63,20 @@ export function createMessagesTransformHandler(args: {
             const code = (error as { code?: string } | null)?.code;
             const name = (error as { name?: string } | null)?.name;
             const message = error instanceof Error ? error.message : String(error);
-            const isBusy = code === "SQLITE_BUSY";
+            const isTransient = typeof code === "string" && TRANSIENT_SQLITE_CODES.has(code);
 
-            if (isBusy) {
+            if (isTransient) {
                 log(
-                    `[magic-context] transform skipped this pass — SQLITE_BUSY (another writer holds lock, retrying next pass): ${message}`,
+                    `[magic-context] transform skipped this pass — ${code} (transient; retrying next pass): ${message}`,
                 );
                 return;
             }
 
-            // Persistent non-BUSY errors are the real risk: silent forever
+            // Persistent non-transient errors are the real risk: silent forever
             // disable unless we surface them. Persist to session_meta so the
             // sidebar shows an obvious failure indicator.
             log(
-                `[magic-context] transform FAILED (non-BUSY) code=${code ?? "none"} name=${name ?? "none"}: ${message}. Continuing with unmodified messages for this pass.`,
+                `[magic-context] transform FAILED code=${code ?? "none"} name=${name ?? "none"}: ${message}. Continuing with unmodified messages for this pass.`,
                 error,
             );
 
@@ -81,7 +88,14 @@ export function createMessagesTransformHandler(args: {
                 try {
                     const db = openDatabase();
                     const summary = truncateError(name, code, message);
-                    updateSessionMeta(db, sessionId, { lastTransformError: summary });
+                    // Write-if-changed guard: when the same error repeats on
+                    // every transform pass (e.g. persistent schema corruption),
+                    // skip the DB write if lastTransformError already matches.
+                    // Prevents needless WAL churn during degraded operation.
+                    const current = getOrCreateSessionMeta(db, sessionId).lastTransformError;
+                    if (current !== summary) {
+                        updateSessionMeta(db, sessionId, { lastTransformError: summary });
+                    }
                 } catch (persistError) {
                     // Swallow — if we can't even write the error, we definitely
                     // can't recover. Next pass may succeed.