@cortexkit/opencode-magic-context 0.44.3 → 0.45.0

package/src/shared/sqlite-transaction-mode-guard.test.ts

@@ -23,6 +23,10 @@ const READ_ONLY_DEFERRED_TRANSACTIONS: Record<string, string> = {
         "reads the latest compaction and the rows after it as one consistent snapshot of the OpenCode 2 store; never writes",
     "packages/pi-plugin/src/inject-compartments-pi.ts#readFrozenM0InputsPi":
         "reads the m[0] render sources and their watermarks as one consistent snapshot; never writes",
+    "packages/plugin/src/features/magic-context/message-fts-session-filter.ts#withMessageFtsSessionFilter":
+        "pins one read snapshot so the session's rowid coverage proof and the filtered message search see the same rows; never writes (read-only connections use it too)",
+    "packages/plugin/src/hooks/magic-context/lkg-persist.ts#loadPersistedLkgSlot":
+        "reads an LKG slot row and its prefix slices as one consistent snapshot; never writes (a failed verification clears the slot afterwards, outside this transaction)",
 };
 
 const REPOSITORY_ROOT = resolve(import.meta.dir, "../../../..");

package/src/shared/sqlite-writer-diagnostics.test.ts

@@ -0,0 +1,134 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTestTempDirFromPath } from "./test-temp-dir";
+
+// The scenario runs in a child process with NODE_ENV=production because the
+// shared logger is silent under test. It imports storage-db for its side effect
+// of registering the real log sink, then drives three privileged writes and one
+// background writer through two connections on a throwaway database:
+//   wait  - another connection holds the lock for 300 ms, the hold is short
+//   hold  - the lock comes at once, the operation keeps it for 300 ms
+//   fast  - neither crosses the threshold, so nothing is logged
+//   async - beginSqliteWriterAsync acquires at once and holds for 300 ms
+const scenario = `
+    await import(${JSON.stringify(new URL("../features/magic-context/storage-db.ts", import.meta.url).href)});
+    const sqlite = await import(${JSON.stringify(new URL("./sqlite.ts", import.meta.url).href)});
+    const logger = await import(${JSON.stringify(new URL("./logger.ts", import.meta.url).href)});
+    const dbPath = process.env.SCENARIO_DB_PATH;
+    const holder = new sqlite.Database(dbPath);
+    holder.exec("PRAGMA journal_mode=WAL; CREATE TABLE context_privilege_state(id INTEGER PRIMARY KEY, enabled INTEGER)");
+    const writer = new sqlite.Database(dbPath);
+    const spin = (ms) => { const end = performance.now() + ms; while (performance.now() < end) {} };
+
+    holder.exec("BEGIN IMMEDIATE");
+    setTimeout(() => holder.exec("COMMIT"), 300);
+    await sqlite.withAsyncPrivilegedWriter(writer, () => undefined);
+
+    await sqlite.withAsyncPrivilegedWriter(writer, () => spin(300));
+
+    await sqlite.withAsyncPrivilegedWriter(writer, () => undefined);
+
+    await sqlite.beginSqliteWriterAsync(writer, "historian-publish");
+    spin(300);
+    writer.exec("COMMIT");
+
+    logger.flushLogger();
+    writer.close();
+    holder.close();
+`;
+
+let root: string | null = null;
+let logLines: string[] = [];
+let consoleOutput = "";
+
+function field(line: string, name: string): number {
+    const value = new RegExp(`\\b${name}=(\\d+)`).exec(line)?.[1];
+    if (value === undefined) throw new Error(`${name} missing from: ${line}`);
+    return Number(value);
+}
+
+describe("sqlite writer diagnostics", () => {
+    beforeAll(async () => {
+        root = createTestTempDirFromPath(join(tmpdir(), "mc-sqlite-writer-diagnostics-"));
+        const logPath = join(root, "magic-context.log");
+        const env: Record<string, string> = {
+            ...(process.env as Record<string, string>),
+            NODE_ENV: "production",
+            MAGIC_CONTEXT_LOG_PATH: logPath,
+            MAGIC_CONTEXT_STORAGE_DIR: join(root, "storage"),
+            SCENARIO_DB_PATH: join(root, "writer.db"),
+        };
+        for (const key of [
+            "XDG_DATA_HOME",
+            "XDG_CONFIG_HOME",
+            "XDG_STATE_HOME",
+            "XDG_CACHE_HOME",
+        ]) {
+            env[key] = join(root, key);
+            mkdirSync(env[key]);
+        }
+        const child = Bun.spawn({
+            windowsHide: true,
+            cmd: ["bun", "--eval", scenario],
+            cwd: import.meta.dir,
+            env,
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+        const [exitCode, stdout, stderr] = await Promise.all([
+            child.exited,
+            new Response(child.stdout).text(),
+            new Response(child.stderr).text(),
+        ]);
+        expect(exitCode, stderr).toBe(0);
+        consoleOutput = stdout + stderr;
+        logLines = existsSync(logPath)
+            ? readFileSync(logPath, "utf8")
+                  .split("\n")
+                  .filter((line) => line.includes("sqlite writer"))
+            : [];
+    }, 30_000);
+
+    afterAll(() => {
+        if (root) rmSync(root, { recursive: true, force: true });
+        root = null;
+    });
+
+    test("nothing reaches the host console", () => {
+        expect(consoleOutput).not.toContain("[magic-context]");
+        expect(consoleOutput).not.toContain("sqlite writer");
+    });
+
+    test("a writer that waited for the lock reports the wait, not its short hold", () => {
+        const waited = logLines.find((line) => line.includes("attempts=2"));
+        if (!waited) throw new Error(`no retried acquisition logged:\n${logLines.join("\n")}`);
+        expect(waited).toContain("[magic-context] sqlite writer site=privileged_writer");
+        expect(waited).toContain("lane=foreground");
+        expect(waited).toContain("outcome=committed");
+        expect(field(waited, "acquire_ms")).toBeGreaterThanOrEqual(250);
+        expect(field(waited, "hold_ms")).toBeLessThan(250);
+    });
+
+    test("a writer that held the lock reports the hold, not its quick acquisition", () => {
+        const held = logLines.filter(
+            (line) => line.includes("site=privileged_writer") && line.includes("attempts=1"),
+        );
+        expect(held).toHaveLength(1);
+        expect(field(held[0], "acquire_ms")).toBeLessThan(250);
+        expect(field(held[0], "hold_ms")).toBeGreaterThanOrEqual(300);
+    });
+
+    test("an async background writer reports its hold under its own site", () => {
+        const held = logLines.filter((line) => line.includes("site=historian-publish"));
+        expect(held).toHaveLength(1);
+        expect(held[0]).toContain("lane=background");
+        expect(field(held[0], "acquire_ms")).toBeLessThan(250);
+        expect(field(held[0], "hold_ms")).toBeGreaterThanOrEqual(300);
+    });
+
+    test("a fast writer stays out of the log", () => {
+        expect(logLines.filter((line) => line.includes("site=privileged_writer"))).toHaveLength(2);
+    });
+});

package/src/shared/sqlite.ts

@@ -62,6 +62,28 @@ export function registerSlowWriteReporter(reporter: SlowWriteReporter): void {
     reportSlowPrivilegedWrite = reporter;
 }
 
+/**
+ * Writer acquisition and hold diagnostics are injected the same way. They must
+ * reach the Magic Context log file and never the console: OpenCode and Pi pass
+ * plugin stderr straight through to the operator's terminal. The storage
+ * bootstrap registers the shared logger here; until then these lines are
+ * dropped.
+ */
+type SqliteDiagnosticSink = (message: string) => void;
+let sqliteDiagnosticSink: SqliteDiagnosticSink | undefined;
+
+export function registerSqliteDiagnosticSink(sink: SqliteDiagnosticSink): void {
+    sqliteDiagnosticSink = sink;
+}
+
+function reportSqliteDiagnostic(message: string): void {
+    try {
+        sqliteDiagnosticSink?.(`[magic-context] ${message}`);
+    } catch {
+        // Diagnostics must never change the outcome of the write they describe.
+    }
+}
+
 export type SqliteRuntime = "Bun" | "Node.js";
 
 type SqliteModule = {
@@ -224,14 +246,43 @@ function installTransactionRouting(db: BetterSqlite3.Database, readonly: boolean
         writable: true,
         value: (sql: string) => {
             if (/^\s*BEGIN\s+(?:IMMEDIATE|EXCLUSIVE)(?:\s+TRANSACTION)?\s*;?\s*$/i.test(sql)) {
+                // A transaction that ended without passing through exec (for
+                // example an automatic rollback) must not be timed as this one.
+                openWriterTransactions.delete(db);
                 if (transformPassScope.getStore()?.active || backgroundWriterScope.getStore())
                     acquireShort(db, () => nativeExec(sql), sql.trim());
                 else nativeExec(sql);
                 return db;
             }
+            if (WRITER_TRANSACTION_END.test(sql) && openWriterTransactions.has(db))
+                return endWriterTransaction(db, () => nativeExec(sql), sql);
+            if (!/^\s*(?:SELECT|EXPLAIN|PRAGMA|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE)\b/i.test(sql))
+                return withAutocommitTimeout(db, () => nativeExec(sql));
             return nativeExec(sql);
         },
     });
+    const nativePrepare = db.prepare.bind(db);
+    Object.defineProperty(db, "prepare", {
+        configurable: true,
+        writable: true,
+        value: (sql: string) => {
+            const statement = nativePrepare(sql);
+            // SELECT/EXPLAIN cannot acquire a writer. Treat CTEs conservatively:
+            // WITH can introduce INSERT/UPDATE/DELETE as well as a read query.
+            if (!readonly && !/^\s*(?:SELECT|EXPLAIN|PRAGMA)\b/i.test(sql)) {
+                for (const method of ["run", "get", "all"] as const) {
+                    const execute = statement[method].bind(statement);
+                    Object.defineProperty(statement, method, {
+                        configurable: true,
+                        // biome-ignore lint/suspicious/noExplicitAny: retain SQLite's native binding overloads.
+                        value: (...args: any[]) =>
+                            withAutocommitTimeout(db, () => execute(...args)),
+                    });
+                }
+            }
+            return statement;
+        },
+    });
     Object.defineProperty(db, "transaction", {
         configurable: true,
         writable: true,
@@ -490,7 +541,9 @@ export type Database = BetterSqlite3.Database;
 export type Statement = BetterSqlite3.Statement<unknown[], unknown>;
 
 const privilegeDepth = new WeakMap<Database, number>();
-const transformPassScope = new AsyncLocalStorage<{ active: boolean } | undefined>();
+const transformPassScope = new AsyncLocalStorage<
+    { active: boolean; remainingWaitMs: number } | undefined
+>();
 const admissionScope = new AsyncLocalStorage<boolean>();
 const backgroundWriterScope = new AsyncLocalStorage<boolean>();
 
@@ -502,7 +555,9 @@ export function withSqliteBackgroundWriter<T>(operation: () => T): T {
 /** Only an awaited foreground transform may spend the extra acquisition budget.
  * The mutable lease also expires for detached descendants when that pass ends. */
 export function withSqliteTransformPass<T>(operation: () => T): T {
-    const lease = { active: true };
+    const existing = transformPassScope.getStore();
+    if (existing?.active) return operation();
+    const lease = { active: true, remainingWaitMs: FOREGROUND_IN_PASS_BUSY_TIMEOUT_MS };
     return transformPassScope.run(lease, () => {
         try {
             const result = operation();
@@ -548,60 +603,182 @@ export class SqliteAcquisitionBusyError extends Error {
 const SHORT_BUSY_TIMEOUT_MS = 25;
 const FOREGROUND_IN_PASS_BUSY_TIMEOUT_MS = 250;
 const FOREGROUND_ACQUISITION_BUDGET_MS = 16_500;
+/** Waiting this long for the writer lock, or holding it this long, is logged. */
+const SLOW_WRITER_LOG_MS = 250;
+const WRITER_TRANSACTION_END = /^\s*(?:COMMIT|END|ROLLBACK)(?:\s+TRANSACTION)?\s*;?\s*$/i;
+
+type WriterLane = "foreground" | "background";
+
+/**
+ * One attempt of an outer acquisition loop (`beginSqliteWriterAsync`,
+ * `withAsyncPrivilegedWriter`). It names the writer and remembers when the loop
+ * started, so the time spent in earlier busy attempts and the sleeps between
+ * them counts as waiting for the lock. Only the first BEGIN issued inside the
+ * attempt may claim it; a later BEGIN from detached work started inside the
+ * same async scope is timed on its own.
+ */
+interface WriterAcquisition {
+    site: string;
+    lane: WriterLane;
+    startedAt: number;
+    attempts: number;
+    claimed: boolean;
+}
+
+/** A write transaction whose BEGIN went through `acquireShort` and has not ended yet. */
+interface OpenWriterTransaction {
+    site: string;
+    lane: WriterLane;
+    acquireMs: number;
+    attempts: number;
+    acquiredAt: number;
+}
+
+const writerAcquisitionScope = new AsyncLocalStorage<WriterAcquisition | undefined>();
+const openWriterTransactions = new WeakMap<Database, OpenWriterTransaction>();
+
+function foregroundWaitLease() {
+    const lease = transformPassScope.getStore();
+    return lease?.active && !admissionScope.getStore() && !backgroundWriterScope.getStore()
+        ? lease
+        : undefined;
+}
+
+/** Bound implicit writer admission too, including prepared INSERT OR IGNORE and
+ * writes with RETURNING. Charge successful execution time conservatively: the
+ * native API cannot separate lock waiting from statement execution. Exhaustion
+ * switches to zero-wait acquisition, not a refusal when the writer is free. */
+function withAutocommitTimeout<T>(db: Database, operation: () => T): T {
+    const lease = foregroundWaitLease();
+    if (isInTransaction(db) || (!lease && !backgroundWriterScope.getStore())) return operation();
+    const previous = pragmaNumber(db, "busy_timeout");
+    db.exec(
+        `PRAGMA busy_timeout=${lease ? Math.floor(lease.remainingWaitMs) : SHORT_BUSY_TIMEOUT_MS}`,
+    );
+    const started = performance.now();
+    try {
+        return operation();
+    } catch (error) {
+        if (lease && isTransientSqliteError(error))
+            throw new SqliteAcquisitionBusyError(error, "autocommit");
+        throw error;
+    } finally {
+        if (lease)
+            lease.remainingWaitMs = Math.max(
+                0,
+                lease.remainingWaitMs - (performance.now() - started),
+            );
+        if (previous !== null) db.exec(`PRAGMA busy_timeout=${previous}`);
+    }
+}
 
 /** The connection is never handed back to another caller with a shortened timeout. */
 function acquireShort(db: Database, acquire: () => unknown, site: string): void {
     const started = performance.now();
     const previous = pragmaNumber(db, "busy_timeout");
-    let acquired = false;
+    const outer = writerAcquisitionScope.getStore();
+    const owner = outer && !outer.claimed ? outer : undefined;
+    if (owner) owner.claimed = true;
+    const writerSite = owner?.site ?? site;
+    const lane: WriterLane =
+        owner?.lane ?? (transformPassScope.getStore()?.active ? "foreground" : "background");
+    let acquiredAt: number | undefined;
     try {
         // Async admission retries after yielding, so each of its BEGIN attempts
         // stays short. An ordinary BEGIN inside a transform pass cannot yield;
         // give that single attempt enough time for a brief writer to finish.
-        const timeout =
-            transformPassScope.getStore()?.active &&
-            !admissionScope.getStore() &&
-            !backgroundWriterScope.getStore()
-                ? FOREGROUND_IN_PASS_BUSY_TIMEOUT_MS
-                : SHORT_BUSY_TIMEOUT_MS;
+        const lease = foregroundWaitLease();
+        const timeout = lease ? Math.floor(lease.remainingWaitMs) : SHORT_BUSY_TIMEOUT_MS;
         db.exec(`PRAGMA busy_timeout=${timeout}`);
         acquire();
-        acquired = true;
+        acquiredAt = performance.now();
     } catch (error) {
         if (transformPassScope.getStore()?.active && isTransientSqliteError(error))
             throw new SqliteAcquisitionBusyError(error, site);
         throw error;
     } finally {
+        const attemptMs = (acquiredAt ?? performance.now()) - started;
+        const lease = foregroundWaitLease();
+        if (lease) lease.remainingWaitMs = Math.max(0, lease.remainingWaitMs - attemptMs);
         if (previous !== null) db.exec(`PRAGMA busy_timeout=${previous}`);
-        const elapsed = performance.now() - started;
-        if (elapsed >= 250)
-            console.warn(
-                `[${new Date().toISOString()}] [magic-context] sqlite acquisition site=${site} lane=${transformPassScope.getStore()?.active ? "foreground" : "background"} elapsed=${Math.round(elapsed)}ms attempts=1 outcome=${acquired ? "acquired" : "busy"}`,
+        if (acquiredAt !== undefined) {
+            // Reported when the transaction ends, together with how long it held
+            // the lock (see endWriterTransaction).
+            openWriterTransactions.set(db, {
+                site: writerSite,
+                lane,
+                acquireMs: acquiredAt - (owner?.startedAt ?? started),
+                attempts: owner?.attempts ?? 1,
+                acquiredAt,
+            });
+        } else if (attemptMs >= SLOW_WRITER_LOG_MS) {
+            reportSqliteDiagnostic(
+                `sqlite writer site=${writerSite} lane=${lane} acquire_ms=${Math.round(attemptMs)} attempts=${owner?.attempts ?? 1} outcome=busy`,
             );
+        }
+    }
+}
+
+/**
+ * Run the COMMIT, END or ROLLBACK that closes a transaction opened through
+ * `acquireShort`, then report how long the writer waited for the lock
+ * (`acquire_ms`) and how long it then held it (`hold_ms`) when either crosses
+ * the threshold. A long hold blocks every other process's writer, so it is
+ * worth seeing even when the lock itself came quickly.
+ */
+function endWriterTransaction(db: Database, end: () => unknown, sql: string): unknown {
+    let ended = false;
+    try {
+        const result = end();
+        ended = true;
+        return result;
+    } finally {
+        const open = openWriterTransactions.get(db);
+        // A COMMIT that failed with the transaction still open has not ended it.
+        if (open && !isInTransaction(db)) {
+            openWriterTransactions.delete(db);
+            const holdMs = performance.now() - open.acquiredAt;
+            if (open.acquireMs >= SLOW_WRITER_LOG_MS || holdMs >= SLOW_WRITER_LOG_MS) {
+                const outcome = /^\s*ROLLBACK/i.test(sql)
+                    ? "rolled_back"
+                    : ended
+                      ? "committed"
+                      : "failed";
+                reportSqliteDiagnostic(
+                    `sqlite writer site=${open.site} lane=${open.lane} acquire_ms=${Math.round(open.acquireMs)} hold_ms=${Math.round(holdMs)} attempts=${open.attempts} outcome=${outcome}`,
+                );
+            }
+        }
     }
 }
 
 /** Begin an immediate transaction with bounded asynchronous retries on writer contention.
- * Callers must recheck any lease or source snapshot after this function returns. */
-export async function beginSqliteWriterAsync(db: Database, site: string): Promise<void> {
+ * Callers must recheck any lease or source snapshot after this function returns.
+ * Resolves with the `performance.now()` time at which BEGIN IMMEDIATE succeeded,
+ * so a caller timing its transaction measures the hold, not the wait for the lock. */
+export async function beginSqliteWriterAsync(db: Database, site: string): Promise<number> {
     const started = performance.now();
     let attempts = 0;
     for (;;) {
         attempts++;
         try {
-            withSqliteBackgroundWriter(() => db.exec("BEGIN IMMEDIATE"));
-            const elapsed = performance.now() - started;
-            if (elapsed >= 250)
-                console.warn(
-                    `[${new Date().toISOString()}] [magic-context] sqlite acquisition site=${site} lane=background elapsed=${Math.round(elapsed)}ms attempts=${attempts} outcome=acquired`,
-                );
-            return;
+            const acquisition: WriterAcquisition = {
+                site,
+                lane: "background",
+                startedAt: started,
+                attempts,
+                claimed: false,
+            };
+            writerAcquisitionScope.run(acquisition, () =>
+                withSqliteBackgroundWriter(() => db.exec("BEGIN IMMEDIATE")),
+            );
+            return performance.now();
         } catch (error) {
             if (!isTransientSqliteError(error)) throw error;
             const elapsed = performance.now() - started;
             if (elapsed >= FOREGROUND_ACQUISITION_BUDGET_MS) {
-                console.warn(
-                    `[${new Date().toISOString()}] [magic-context] sqlite acquisition site=${site} lane=background elapsed=${Math.round(elapsed)}ms attempts=${attempts} outcome=busy`,
+                reportSqliteDiagnostic(
+                    `sqlite writer site=${site} lane=background acquire_ms=${Math.round(elapsed)} attempts=${attempts} outcome=busy`,
                 );
                 throw error;
             }
@@ -625,27 +802,31 @@ export async function withAsyncPrivilegedWriter<T>(db: Database, operation: () =
     for (;;) {
         attempts++;
         try {
-            const result = admissionScope.run(true, () =>
-                withSqliteTransformPass(() => withPrivilegedWriter(db, operation)),
+            const acquisition: WriterAcquisition = {
+                site: "privileged_writer",
+                lane: "foreground",
+                startedAt: started,
+                attempts,
+                claimed: false,
+            };
+            // The acquisition and hold of this transaction are reported when it
+            // commits or rolls back (see endWriterTransaction).
+            return admissionScope.run(true, () =>
+                withSqliteTransformPass(() =>
+                    writerAcquisitionScope.run(acquisition, () =>
+                        withPrivilegedWriter(db, operation),
+                    ),
+                ),
             );
-            const elapsed = performance.now() - started;
-            if (elapsed >= 250)
-                console.warn(
-                    `[${new Date().toISOString()}] [magic-context] sqlite acquisition site=privileged_writer lane=foreground elapsed=${Math.round(elapsed)}ms attempts=${attempts} outcome=acquired`,
-                );
-            return result;
         } catch (error) {
             // A callback failure can occur after writes; only retry a failed BEGIN.
             if (!(error instanceof SqliteAcquisitionBusyError)) throw error;
             const elapsed = performance.now() - started;
             if (elapsed >= FOREGROUND_ACQUISITION_BUDGET_MS) {
-                if (elapsed >= 250)
-                    console.warn(
-                        `[${new Date().toISOString()}] [magic-context] sqlite acquisition site=privileged_writer lane=foreground elapsed=${Math.round(elapsed)}ms attempts=${attempts} outcome=busy`,
-                    );
-                throw error instanceof SqliteAcquisitionBusyError
-                    ? error
-                    : new SqliteAcquisitionBusyError(error);
+                reportSqliteDiagnostic(
+                    `sqlite writer site=privileged_writer lane=foreground acquire_ms=${Math.round(elapsed)} attempts=${attempts} outcome=busy`,
+                );
+                throw error;
             }
             await new Promise<void>((resolve) =>
                 setTimeout(
@@ -680,7 +861,9 @@ export function withPrivilegedWriter<T>(db: Database, operation: () => T): T {
     const previousDepth = privilegeDepth.get(db) ?? 0;
     const nested = isInTransaction(db);
     const savepoint = "mc_privilege_scope";
-    const transactionStartedAt = nested ? undefined : performance.now();
+    // Timed from the moment the lock is held, so a slow-write report measures
+    // the hold and not the wait for BEGIN IMMEDIATE.
+    let transactionStartedAt: number | undefined;
     if (nested) {
         db.exec(`SAVEPOINT ${savepoint}`);
     } else {
@@ -691,6 +874,7 @@ export function withPrivilegedWriter<T>(db: Database, operation: () => T): T {
                 throw new SqliteAcquisitionBusyError(error);
             throw error;
         }
+        transactionStartedAt = performance.now();
     }
     privilegeDepth.set(db, previousDepth + 1);
     try {

package/src/shared/stale-plugin-build.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { bindStaleBuildNotice } from "../plugin/stale-build-notice";
+import { __resetNotificationStateForTests, drainNotifications } from "./rpc-notifications";
+import {
+    classifyStalePluginBuild,
+    importPluginModule,
+    registerStalePluginBuildHost,
+    StalePluginBuildError,
+    stalePluginBuildDiagnostic,
+} from "./stale-plugin-build";
+
+function reset(): void {
+    delete (globalThis as Record<symbol, unknown>)[Symbol.for("magic-context.stale-plugin-build")];
+    __resetNotificationStateForTests();
+}
+beforeEach(reset);
+afterEach(reset);
+
+const dist = "/tmp/magic-context/fixture/packages/pi-plugin/dist";
+const missing = (path: string) =>
+    new Error(`Cannot find module '${path}' imported from ${dist}/index.js`);
+
+describe("stale plugin build classification", () => {
+    it("recognizes Node, Bun, file URLs and relative imports only inside the loaded package dist", () => {
+        registerStalePluginBuildHost({ moduleUrl: `file://${dist}/index.js`, harness: "pi" });
+        for (const error of [
+            missing(`${dist}/index-old.js`),
+            missing(`file://${dist}/index-old.js`),
+            new Error(`Cannot find module './index-old.js' from '${dist}/index.js'`),
+            `BuildMessage: ENOENT reading "${dist}/index-old.js"`,
+        ]) {
+            expect(classifyStalePluginBuild(error)?.chunk).toBe(`${dist}/index-old.js`);
+        }
+        for (const error of [
+            missing("quickjs-emscripten"),
+            missing(`${dist}-other/index-old.js`),
+            missing(`${dist}/../src/index-old.js`),
+            missing("/another/package/dist/index-old.js"),
+            new Error(`ENOENT: no such file or directory, open '${dist}/note.txt'`),
+            new Error(`network error mentioning ${dist}/index-old.js`),
+            new Error(`Cannot find module '../src/missing.js' from '${dist}/index.js'`),
+        ])
+            expect(classifyStalePluginBuild(error)).toBeNull();
+    });
+
+    it("recognizes Windows paths without confusing an external package for our dist", () => {
+        registerStalePluginBuildHost({
+            moduleUrl: "file:///C:/dev/pi-plugin/dist/index.js",
+            harness: "pi",
+        });
+        expect(
+            classifyStalePluginBuild(missing("C:\\dev\\pi-plugin\\dist\\index-old.js"))?.chunk,
+        ).toBe("c:/dev/pi-plugin/dist/index-old.js");
+        expect(classifyStalePluginBuild(missing("C:\\other\\dist\\index-old.js"))).toBeNull();
+    });
+
+    it("does not classify source-mode missing modules using the error's dist path", () => {
+        registerStalePluginBuildHost({
+            moduleUrl: "file:///tmp/plugin/src/index.ts",
+            harness: "pi",
+        });
+        expect(classifyStalePluginBuild(missing(`${dist}/index-old.js`))).toBeNull();
+    });
+
+    it("warns once per process and logs once per missing chunk across registrations and wakes", () => {
+        const notices: string[] = [];
+        const host = {
+            moduleUrl: `file://${dist}/index.js`,
+            harness: "pi" as const,
+            notify: (message: string) => notices.push(message),
+        };
+        registerStalePluginBuildHost(host);
+        const error = missing(`${dist}/index-first.js`);
+        expect(stalePluginBuildDiagnostic(error)).toContain("stale plugin build");
+        registerStalePluginBuildHost(host); // Another instance or a reload.
+        expect(stalePluginBuildDiagnostic(error)).toBeNull();
+        expect(stalePluginBuildDiagnostic(`dry-run failed: ${error.message}`)).toBeNull();
+        expect(stalePluginBuildDiagnostic(missing(`${dist}/index-second.js`))).toContain(
+            "index-second.js",
+        );
+        expect(notices).toEqual([
+            "Magic Context was rebuilt while this Pi was running; type /reload to load the new build",
+        ]);
+        expect(stalePluginBuildDiagnostic(new Error(notices[0]))).toBeNull();
+    });
+
+    it("delivers an early failure when the Pi UI becomes available, without logging it again", () => {
+        const notices: string[] = [];
+        registerStalePluginBuildHost({ moduleUrl: `file://${dist}/index.js`, harness: "pi" });
+        expect(stalePluginBuildDiagnostic(missing(`${dist}/index-first.js`))).toContain(
+            "stale plugin build",
+        );
+        registerStalePluginBuildHost({
+            moduleUrl: `file://${dist}/index.js`,
+            harness: "pi",
+            notify: (message) => notices.push(message),
+        });
+        expect(stalePluginBuildDiagnostic(missing(`${dist}/index-first.js`))).toBeNull();
+        expect(notices).toHaveLength(1);
+    });
+
+    it("queues useful OpenCode 2 guidance even without the legacy SDK toast API", () => {
+        bindStaleBuildNotice({}, "file:///tmp/plugin/dist/v2/server.js", "opencode2");
+        stalePluginBuildDiagnostic(missing("/tmp/plugin/dist/v2/index-old.js"));
+        stalePluginBuildDiagnostic(missing("/tmp/plugin/dist/v2/index-old.js"));
+        const notifications = drainNotifications();
+        expect(notifications).toHaveLength(1);
+        expect(notifications[0].payload.message).toBe(
+            "Magic Context was rebuilt while this OpenCode host was running; restart the host to load the new build",
+        );
+    });
+
+    it("guards arbitrary lazy imports while preserving unrelated errors", async () => {
+        registerStalePluginBuildHost({ moduleUrl: `file://${dist}/index.js`, harness: "pi" });
+        const error = missing(`${dist}/index-old.js`);
+        await expect(
+            importPluginModule(async () => {
+                throw error;
+            }),
+        ).rejects.toBeInstanceOf(StalePluginBuildError);
+        const unrelated = missing("an-external-dependency");
+        await expect(
+            importPluginModule(async () => {
+                throw unrelated;
+            }),
+        ).rejects.toBe(unrelated);
+        expect(await importPluginModule(async () => 4)).toBe(4);
+    });
+});