fix(transform): handle SQLITE_BUSY without crashing user prompt (#23)

A Discord user reported SQLITE_BUSY crashing their turn:

  SQLiteError: database is locked
      errno: 5, code: SQLITE_BUSY
  at prepareCompartmentInjection (inject-compartments.ts:215)

## Root cause

The DB is configured with busy_timeout=5000 (5s) and WAL mode, which
should handle concurrent access. SQLITE_BUSY surfaces only when
another writer holds the lock longer than 5 seconds — typically a
dreamer or historian child session, a second OpenCode process, or a
slow WAL checkpoint.

When the failing statement is a write inside transform, the thrown
error propagates all the way up through OpenCode's Effect pipeline
and crashes the user's turn. That's the actual user-visible damage;
the DB contention itself is recoverable.

## Fix — two layers

1. **Swallow BUSY on the failing write specifically.** The
   memory_block_cache UPDATE in prepareCompartmentInjection is a pure
   optimization — the block itself is computed and returned regardless
   of whether the cache row writes. On SQLITE_BUSY we log and
   continue; next turn will retry naturally. Non-BUSY errors still
   propagate so real bugs aren't hidden.

2. **Top-level try/catch in messages-transform.ts.** Any unexpected
   error inside the plugin transform is now caught at the OpenCode
   boundary and logged instead of thrown. On failure the messages
   array is returned unmodified (no injection, no drops, no tagging
   for this pass only), and OpenCode's prompt loop proceeds normally.
   Next transform pass retries with full behavior. Correctness is
   preserved because all persistent mutations are idempotent.

## Why both layers

The surgical fix (layer 1) is preferred because losing ONE optional
cache write is cheaper than losing the whole transform pass. The
broad guard (layer 2) is defense-in-depth for writes we haven't
specifically hardened yet (tagger, apply-operations, heuristic
cleanup, etc.). Users get a degraded pass instead of a dead prompt
if any of those hit BUSY next.

## Tests

- 505 plugin tests pass (+6 new targeting this issue).
- inject-compartments.test.ts: SQLITE_BUSY is swallowed; non-BUSY
  SQLite errors still rethrow.
- messages-transform.test.ts: SQLITE_BUSY, TypeError, and null-plugin
  cases all resolve without throwing; normal transforms pass through.

Closes #23

Author: ualtinok

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

@@ -243,3 +243,95 @@ describe("prepareCompartmentInjection — transition from empty to compartment",
         expect(deferMessages.length).toBe(2);
     });
 });
+
+describe("prepareCompartmentInjection — SQLITE_BUSY handling (issue #23)", () => {
+    it("swallows SQLITE_BUSY on memory_block_cache UPDATE and returns computed block anyway", () => {
+        db = makeDb();
+        insertMemory(db, {
+            projectPath: PROJECT_PATH,
+            category: "USER_DIRECTIVES",
+            content: "never run migrations manually",
+        });
+
+        // Proxy the db to throw SQLITE_BUSY specifically on the UPDATE statement
+        // used by memory_block_cache. Other prepares pass through unchanged so
+        // the rest of prepareCompartmentInjection can complete normally.
+        const busyProxy: Database = new Proxy(db, {
+            get(target, prop, receiver) {
+                if (prop === "prepare") {
+                    return (sql: string) => {
+                        if (sql.includes("UPDATE session_meta SET memory_block_cache")) {
+                            return {
+                                run: () => {
+                                    const err = new Error("database is locked") as Error & {
+                                        code: string;
+                                        errno: number;
+                                    };
+                                    err.code = "SQLITE_BUSY";
+                                    err.errno = 5;
+                                    throw err;
+                                },
+                                get: () => null,
+                                all: () => [],
+                            };
+                        }
+                        return target.prepare(sql);
+                    };
+                }
+                return Reflect.get(target, prop, receiver);
+            },
+        });
+
+        const messages: MessageLike[] = [userMessage("m1", "hello")];
+        // Should not throw — the BUSY on the optional cache write must be swallowed.
+        const result = prepareCompartmentInjection(
+            busyProxy,
+            SESSION_ID,
+            messages,
+            true,
+            PROJECT_PATH,
+        );
+
+        expect(result).not.toBeNull();
+        expect(result?.memoryCount).toBe(1);
+        expect(result?.block).toContain("never run migrations manually");
+    });
+
+    it("rethrows non-BUSY errors from memory_block_cache UPDATE", () => {
+        db = makeDb();
+        insertMemory(db, {
+            projectPath: PROJECT_PATH,
+            category: "USER_DIRECTIVES",
+            content: "test directive",
+        });
+
+        const errorProxy: Database = new Proxy(db, {
+            get(target, prop, receiver) {
+                if (prop === "prepare") {
+                    return (sql: string) => {
+                        if (sql.includes("UPDATE session_meta SET memory_block_cache")) {
+                            return {
+                                run: () => {
+                                    const err = new Error("schema mismatch") as Error & {
+                                        code: string;
+                                    };
+                                    err.code = "SQLITE_CORRUPT";
+                                    throw err;
+                                },
+                                get: () => null,
+                                all: () => [],
+                            };
+                        }
+                        return target.prepare(sql);
+                    };
+                }
+                return Reflect.get(target, prop, receiver);
+            },
+        });
+
+        const messages: MessageLike[] = [userMessage("m1", "hello")];
+        expect(() =>
+            prepareCompartmentInjection(errorProxy, SESSION_ID, messages, true, PROJECT_PATH),
+        ).toThrow("schema mismatch");
+    });
+});

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

@@ -211,10 +211,28 @@ export function prepareCompartmentInjection(
             memoryCount = memories.length;
             memoryBlock = renderMemoryBlock(memories) ?? undefined;
 
-            // Snapshot so subsequent turns reuse the same block without cache bust
-            db.prepare(
-                "UPDATE session_meta SET memory_block_cache = ?, memory_block_count = ? WHERE session_id = ?",
-            ).run(memoryBlock ?? "", memoryCount, sessionId);
+            // Snapshot so subsequent turns reuse the same block without cache bust.
+            // Swallow SQLITE_BUSY: the cache is a pure optimization (the block itself
+            // is already computed and returned below). If another writer holds the DB
+            // past busy_timeout=5s — typically a concurrent dreamer/historian child
+            // session or a second OpenCode process — we'd rather let the transform
+            // proceed with a one-turn cache miss than crash the user's prompt.
+            // Issue: https://github.com/cortexkit/opencode-magic-context/issues/23
+            try {
+                db.prepare(
+                    "UPDATE session_meta SET memory_block_cache = ?, memory_block_count = ? WHERE session_id = ?",
+                ).run(memoryBlock ?? "", memoryCount, sessionId);
+            } catch (error) {
+                const code = (error as { code?: string } | null)?.code;
+                if (code === "SQLITE_BUSY") {
+                    sessionLog(
+                        sessionId,
+                        "memory_block_cache UPDATE hit SQLITE_BUSY, skipping snapshot for this turn",
+                    );
+                } else {
+                    throw error;
+                }
+            }
         }
     }
 

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

@@ -0,0 +1,84 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, it } from "bun:test";
+import { createMessagesTransformHandler } from "./messages-transform";
+
+// Minimal fake message shape — just needs info + parts.
+// biome-ignore lint/suspicious/noExplicitAny: test fixture does not need full SDK types
+function makeOutput(): any {
+    return {
+        messages: [
+            {
+                info: { id: "m1", role: "user", sessionID: "ses_test" },
+                parts: [{ type: "text", text: "hello" }],
+            },
+        ],
+    };
+}
+
+describe("createMessagesTransformHandler — error boundary (issue #23)", () => {
+    it("swallows SQLITE_BUSY from inner transform so prompt loop proceeds", async () => {
+        const handler = createMessagesTransformHandler({
+            magicContext: {
+                "experimental.chat.messages.transform": async () => {
+                    const err = new Error("database is locked") as Error & {
+                        code: string;
+                        errno: number;
+                    };
+                    err.code = "SQLITE_BUSY";
+                    err.errno = 5;
+                    throw err;
+                },
+            },
+        });
+
+        const output = makeOutput();
+        // Should NOT throw — wrapper catches all errors.
+        await expect(handler({}, output)).resolves.toBeUndefined();
+
+        // Messages are left untouched when transform fails.
+        expect(output.messages).toHaveLength(1);
+        expect(output.messages[0].info.id).toBe("m1");
+    });
+
+    it("swallows unexpected non-SQLITE errors too", async () => {
+        const handler = createMessagesTransformHandler({
+            magicContext: {
+                "experimental.chat.messages.transform": async () => {
+                    throw new TypeError("unexpected undefined access");
+                },
+            },
+        });
+
+        const output = makeOutput();
+        await expect(handler({}, output)).resolves.toBeUndefined();
+    });
+
+    it("passes through non-error transforms normally", async () => {
+        let called = false;
+        const handler = createMessagesTransformHandler({
+            magicContext: {
+                "experimental.chat.messages.transform": async (_input, out) => {
+                    called = true;
+                    // biome-ignore lint/suspicious/noExplicitAny: test fixture — real shape irrelevant
+                    (out.messages as any).push({
+                        info: { id: "injected", role: "user", sessionID: "ses_test" },
+                        parts: [{ type: "text", text: "injected" }],
+                    });
+                },
+            },
+        });
+
+        const output = makeOutput();
+        await handler({}, output);
+        expect(called).toBe(true);
+        expect(output.messages).toHaveLength(2);
+    });
+
+    it("no-ops when magicContext is null (disabled plugin path)", async () => {
+        const handler = createMessagesTransformHandler({ magicContext: null });
+        const output = makeOutput();
+        await expect(handler({}, output)).resolves.toBeUndefined();
+        expect(output.messages).toHaveLength(1);
+    });
+});

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

@@ -1,10 +1,24 @@
+import { log } from "../shared/logger";
+
 type MessageWithParts = {
     info: import("@opencode-ai/sdk").Message;
     parts: import("@opencode-ai/sdk").Part[];
 };
 
 type MessagesTransformOutput = { messages: MessageWithParts[] };
 
+/**
+ * Top-level transform wrapper. Swallows any unexpected error (typically
+ * SQLITE_BUSY from concurrent plugin processes) so OpenCode's prompt loop
+ * always proceeds. Without this guard, a transient DB contention event can
+ * crash the user's turn through OpenCode's Effect pipeline — see issue #23
+ * https://github.com/cortexkit/opencode-magic-context/issues/23
+ *
+ * On failure, the messages array is returned unmodified (i.e., magic-context
+ * manipulation is skipped for this pass). The next transform pass will
+ * retry with normal behavior. Correctness is preserved because all
+ * persistent state mutations are idempotent across passes.
+ */
 export function createMessagesTransformHandler(args: {
     magicContext: {
         "experimental.chat.messages.transform"?: (
@@ -14,6 +28,19 @@ export function createMessagesTransformHandler(args: {
     } | null;
 }): (input: Record<string, never>, output: MessagesTransformOutput) => Promise<void> {
     return async (input, output): Promise<void> => {
-        await args.magicContext?.["experimental.chat.messages.transform"]?.(input, output);
+        try {
+            await args.magicContext?.["experimental.chat.messages.transform"]?.(input, output);
+        } catch (error) {
+            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);
+            log(
+                `[magic-context] transform failed (code=${code ?? "none"} name=${name ?? "none"}): ${message}. Continuing with unmodified messages for this pass.`,
+                error,
+            );
+            // Do NOT rethrow — OpenCode's Effect pipeline turns thrown errors into
+            // user-visible prompt failures. We accept degraded behavior (no
+            // injection / no drops this turn) rather than blocking the user.
+        }
     };
 }