@cortexkit/opencode-magic-context 0.44.1 → 0.44.2

package/src/shared/rpc-utils.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -118,12 +118,13 @@ const RPC_IDENTITY_SKEW_TOLERANCE_MS = 120_000;
 const LINUX_CLOCK_TICKS_PER_SECOND = 100;
 const PS_PROBE_TIMEOUT_MS = 1_000;
 const WINDOWS_CIM_PROBE_TIMEOUT_MS = 5_000;
+const WINDOWS_PROCESS_SNAPSHOT_TTL_MS = 2_000;
 const MAX_ANCESTOR_WALK_DEPTH = 16;
 const OPEN_CODE_COMMAND_MARKERS = ["opencode", "node", "bun", "electron"];
 const TASKLIST_NO_TASKS_PATTERN =
     /^INFO:\s+No tasks are running which match the specified criteria\.?$/im;
 const WINDOWS_CIM_COMMAND =
-    "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress";
+    "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,CommandLine,CreationDate | ConvertTo-Json -Compress";
 const PI_HARNESS_ARC_MARKERS = [
     "pi-coding-agent",
     "oh-my-pi",
@@ -184,6 +185,7 @@ function readPsProcessStartTime(pid: number): number | null {
             encoding: "utf8",
             timeout: PS_PROBE_TIMEOUT_MS,
             stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
         });
         const processStartTime = Date.parse(String(output).trim());
         return Number.isFinite(processStartTime) ? processStartTime : null;
@@ -232,6 +234,7 @@ interface ProcessSnapshot {
 }
 
 let windowsProcessFactsCache: Map<number, ProcessFacts> | null = null;
+let windowsProcessSnapshotCache: { snapshot: ProcessSnapshot; at: number } | null = null;
 
 function rememberWindowsProcessFacts(facts: ProcessFacts[]): void {
     windowsProcessFactsCache = new Map(facts.map((fact) => [fact.pid, fact]));
@@ -239,6 +242,7 @@ function rememberWindowsProcessFacts(facts: ProcessFacts[]): void {
 
 function clearWindowsProcessFactsCache(): void {
     windowsProcessFactsCache = null;
+    windowsProcessSnapshotCache = null;
 }
 
 function parseCsvLine(line: string): string[] | null {
@@ -292,6 +296,7 @@ function readWindowsProcess(pid: number): { state: PidLiveness; command?: string
             encoding: "utf8",
             timeout: PS_PROBE_TIMEOUT_MS,
             stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
         });
         const entries = parseTasklistOutput(String(output));
         if (entries === null) return { state: "inconclusive" };
@@ -325,6 +330,7 @@ function readPsProcessCommand(pid: number): string | null {
             encoding: "utf8",
             timeout: PS_PROBE_TIMEOUT_MS,
             stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
         });
         return String(output);
     } catch {
@@ -521,6 +527,7 @@ function execProcessList(
             encoding: "utf8",
             timeout,
             stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
         }),
     );
 }
@@ -588,7 +595,12 @@ function parseWindowsCimOutput(output: string): ProcessFacts[] | null {
             pid,
             parentPid: Number.isInteger(parentPid) && parentPid > 0 ? parentPid : null,
             commandLine,
-            imageName: commandLine ? executableName(commandTokens(commandLine)[0]) : null,
+            imageName:
+                typeof record.Name === "string"
+                    ? record.Name
+                    : commandLine
+                      ? executableName(commandTokens(commandLine)[0])
+                      : null,
             startTime: parseWindowsCreationDate(record.CreationDate),
         });
     }
@@ -679,14 +691,18 @@ function readPosixParentPid(pid: number): number | null {
  * plugin runs. Bound the walk and stop on cycles so a broken parent map
  * cannot loop.
  */
-function collectAncestorPids(selfPid: number, parentByPid: Map<number, number>): Set<number> {
+function collectAncestorPids(
+    selfPid: number,
+    parentByPid: Map<number, number>,
+    probeParents = true,
+): Set<number> {
     const ancestors = new Set<number>();
     let current = selfPid;
     for (let depth = 0; depth < MAX_ANCESTOR_WALK_DEPTH; depth += 1) {
         let ppid: number | null = null;
         if (parentByPid.has(current)) {
             ppid = parentByPid.get(current) ?? null;
-        } else if (rpcIdentityPlatform !== "win32") {
+        } else if (rpcIdentityPlatform !== "win32" && probeParents) {
             ppid = readPosixParentPid(current);
             if (ppid == null && current === process.pid && process.ppid > 0) {
                 ppid = process.ppid;
@@ -703,8 +719,11 @@ function collectAncestorPids(selfPid: number, parentByPid: Map<number, number>):
     return ancestors;
 }
 
-function classifyLivePiSnapshot(snapshot: ProcessSnapshot): PiProcessDiscovery {
-    const ancestors = collectAncestorPids(process.pid, snapshot.parentByPid);
+function classifyLivePiSnapshot(
+    snapshot: ProcessSnapshot,
+    probeParents = true,
+): PiProcessDiscovery {
+    const ancestors = collectAncestorPids(process.pid, snapshot.parentByPid, probeParents);
     const processIds = new Set<number>();
     const inconclusivePids = new Set<number>();
     const skippedAncestorPids: number[] = [];
@@ -773,8 +792,14 @@ export function inspectLivePiProcesses(): PiProcessDiscovery {
             // Prefer one CIM query (pid, parent, command line, start time).
             // tasklist is image-name-only, so it is a fallback and never a
             // verified live-harness source.
-            const cim = tryReadWindowsCimSnapshot(rpcProcessListExecFileSync);
-            const snapshot = cim ?? tryReadWindowsTasklistSnapshot();
+            const now = rpcIdentityNowMs();
+            const cached = windowsProcessSnapshotCache;
+            // A brief reuse avoids spawning PowerShell on every blocker scan.
+            const snapshot =
+                cached && now >= cached.at && now - cached.at < WINDOWS_PROCESS_SNAPSHOT_TTL_MS
+                    ? cached.snapshot
+                    : (tryReadWindowsCimSnapshot(rpcProcessListExecFileSync) ??
+                      tryReadWindowsTasklistSnapshot());
             if (!snapshot) {
                 return {
                     state: "unreadable",
@@ -782,6 +807,7 @@ export function inspectLivePiProcesses(): PiProcessDiscovery {
                     error: "process list unavailable",
                 };
             }
+            if (snapshot !== cached?.snapshot) windowsProcessSnapshotCache = { snapshot, at: now };
             rememberWindowsProcessFacts(snapshot.facts);
             return classifyLivePiSnapshot(snapshot);
         }
@@ -834,3 +860,129 @@ export function parseRpcPortFile(content: string, fallbackPid = 0): RpcPortFileR
 function isValidPort(port: number): boolean {
     return Number.isInteger(port) && port > 0 && port <= 65535;
 }
+
+/** One bounded, shared process scan for asynchronous storage opens. */
+export interface AsyncProcessInspection {
+    pi: PiProcessDiscovery;
+    /** Includes process names and commands so offline maintenance can rule out live store users. */
+    processSnapshot?: {
+        source: ProcessSnapshotSource;
+        facts: Array<{ pid: number; imageName: string | null; commandLine: string | null }>;
+    };
+    evidence(pid: number): ProcessProbeEvidence;
+    liveness(pid: number): PidLiveness;
+}
+
+function execProcessListAsync(file: string, args: string[], timeout: number): Promise<string> {
+    return new Promise((resolve, reject) => {
+        execFile(
+            file,
+            args,
+            { encoding: "utf8", timeout, windowsHide: true, maxBuffer: 8 * 1024 * 1024 },
+            (error, stdout) => {
+                if (error) reject(error);
+                else resolve(stdout);
+            },
+        );
+    });
+}
+
+let asyncProcessExec = execProcessListAsync;
+let asyncInspection: Promise<AsyncProcessInspection> | undefined;
+let asyncInspectionExpires = 0;
+let lastAsyncSnapshot: ProcessSnapshot | null = null;
+
+/** Inject only the asynchronous transport; legacy synchronous probes stay isolated. */
+export function __setAsyncProcessProbeForTests(probe?: typeof execProcessListAsync): void {
+    asyncProcessExec = probe ?? execProcessListAsync;
+    asyncInspection = undefined;
+    asyncInspectionExpires = 0;
+    lastAsyncSnapshot = null;
+}
+
+export function inspectProcessesAsync(forceFresh = false): Promise<AsyncProcessInspection> {
+    if (!forceFresh && asyncInspection && rpcIdentityNowMs() < asyncInspectionExpires)
+        return asyncInspection;
+    asyncInspectionExpires = Number.POSITIVE_INFINITY;
+    asyncInspection = (async () => {
+        let snapshot: ProcessSnapshot | null = null;
+        try {
+            if (rpcIdentityPlatform === "win32") {
+                try {
+                    const output = await asyncProcessExec(
+                        "powershell",
+                        ["-NoProfile", "-Command", WINDOWS_CIM_COMMAND],
+                        WINDOWS_CIM_PROBE_TIMEOUT_MS,
+                    );
+                    const facts = parseWindowsCimOutput(output);
+                    if (facts) snapshot = snapshotFromFacts(facts, "cim");
+                } catch {
+                    /* tasklist is the bounded fallback when CIM is unavailable. */
+                }
+                if (!snapshot) {
+                    const entries = parseTasklistOutput(
+                        await asyncProcessExec("tasklist", ["/FO", "CSV"], PS_PROBE_TIMEOUT_MS),
+                    );
+                    if (entries)
+                        snapshot = snapshotFromFacts(
+                            entries.map(({ pid, command }) => ({
+                                pid,
+                                parentPid: null,
+                                commandLine: null,
+                                imageName: command,
+                                startTime: null,
+                            })),
+                            "tasklist",
+                        );
+                }
+            } else {
+                const output = await asyncProcessExec(
+                    "ps",
+                    ["-axo", "pid=,ppid=,lstart=,command="],
+                    PS_PROBE_TIMEOUT_MS,
+                );
+                const facts: ProcessFacts[] = [];
+                for (const line of output.split(/\r?\n/)) {
+                    const match =
+                        /^\s*(\d+)\s+(\d+)\s+(\S+\s+\S+\s+\d+\s+\d+:\d+:\d+\s+\d+)\s+(.+)$/.exec(
+                            line,
+                        );
+                    if (!match) continue;
+                    const startTime = Date.parse(match[3]);
+                    facts.push({
+                        pid: Number(match[1]),
+                        parentPid: Number(match[2]),
+                        commandLine: match[4],
+                        imageName: null,
+                        startTime: Number.isFinite(startTime) ? startTime : null,
+                    });
+                }
+                snapshot = facts.length > 0 ? snapshotFromFacts(facts, "ps") : null;
+            }
+        } catch {
+            /* Missing process evidence is inconclusive, never proof of death. */
+        }
+        // A timed-out refresh cannot prove that a process blocking migration has
+        // exited. Keep its evidence until a successful scan can establish death.
+        const fresh = snapshot !== null;
+        if (snapshot) lastAsyncSnapshot = snapshot;
+        else snapshot = lastAsyncSnapshot;
+        const byPid = new Map(snapshot?.facts.map((fact) => [fact.pid, fact]));
+        return {
+            pi: snapshot
+                ? classifyLivePiSnapshot(snapshot, false)
+                : { state: "unreadable", processIds: [] },
+            ...(fresh && snapshot
+                ? { processSnapshot: { source: snapshot.source, facts: snapshot.facts } }
+                : {}),
+            evidence: (pid: number) => ({
+                startTime: byPid.get(pid)?.startTime ?? null,
+                commandLine: byPid.get(pid)?.commandLine ?? byPid.get(pid)?.imageName ?? null,
+            }),
+            liveness: (pid: number) => (byPid.has(pid) ? "alive" : fresh ? "dead" : "inconclusive"),
+        } satisfies AsyncProcessInspection;
+    })().finally(() => {
+        asyncInspectionExpires = rpcIdentityNowMs() + WINDOWS_PROCESS_SNAPSHOT_TTL_MS;
+    });
+    return asyncInspection;
+}

package/src/shared/sqlite-acquisition-fence.test.ts

@@ -0,0 +1,132 @@
+import { expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import ts from "typescript";
+
+const root = resolve(import.meta.dir, "../../../..");
+const shared = "packages/plugin/src/shared/sqlite.ts";
+function files(dir: string): string[] {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) return files(path);
+        return /\.tsx?$/.test(path) && !/\.test\.|test-support|\.d\.ts$/.test(path) ? [path] : [];
+    });
+}
+
+function scan(
+    path: string,
+    text: string,
+): { violations: string[]; transactions: number; literals: number } {
+    const violations: string[] = [];
+    let transactions = 0;
+    let literals = 0;
+    const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true);
+    const visit = (node: ts.Node) => {
+        if (
+            ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === "transaction"
+        )
+            transactions++;
+        if (
+            path !== shared &&
+            ts.isImportDeclaration(node) &&
+            ts.isStringLiteral(node.moduleSpecifier) &&
+            !node.importClause?.isTypeOnly &&
+            /^(bun:sqlite|node:sqlite|better-sqlite3)$/.test(node.moduleSpecifier.text)
+        ) {
+            violations.push(`${path}: native SQLite import bypasses shared acquisition`);
+        }
+        if (
+            path !== shared &&
+            ts.isExportDeclaration(node) &&
+            !node.isTypeOnly &&
+            node.moduleSpecifier &&
+            ts.isStringLiteral(node.moduleSpecifier) &&
+            /^(bun:sqlite|node:sqlite|better-sqlite3)$/.test(node.moduleSpecifier.text)
+        ) {
+            violations.push(`${path}: native SQLite re-export bypasses shared acquisition`);
+        }
+        if (
+            path !== shared &&
+            ts.isCallExpression(node) &&
+            (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+                (ts.isIdentifier(node.expression) && node.expression.text === "require")) &&
+            /(?:bun:sqlite|node:sqlite|better-sqlite3)/.test(
+                node.arguments.map((arg) => arg.getText(source)).join(""),
+            )
+        ) {
+            violations.push(`${path}: dynamic native SQLite import bypasses shared acquisition`);
+        }
+        const sqlText = ts.isStringLiteralLike(node)
+            ? node.text
+            : ts.isTemplateExpression(node)
+              ? node.head.text + node.templateSpans.map((span) => span.literal.text).join("")
+              : undefined;
+        if (
+            sqlText !== undefined &&
+            /\bBEGIN\s+(?:IMMEDIATE|EXCLUSIVE)(?:\s+TRANSACTION)?\s*(?:;|$)/i.test(sqlText)
+        ) {
+            literals++;
+            if (path !== shared) {
+                const call = node.parent;
+                const routed =
+                    !ts.isTemplateExpression(node) &&
+                    ts.isCallExpression(call) &&
+                    ts.isPropertyAccessExpression(call.expression) &&
+                    call.expression.name.text === "exec" &&
+                    /^\s*BEGIN\s+(IMMEDIATE|EXCLUSIVE)(?:\s+TRANSACTION)?\s*;?\s*$/i.test(sqlText);
+                if (!routed)
+                    violations.push(
+                        `${path}:${source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1}: BEGIN acquisition must be a standalone shared Database.exec call`,
+                    );
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return { violations, transactions, literals };
+}
+
+test("all production transaction acquisition routes through the shared SQLite runtime", () => {
+    const scans = ["packages/plugin/src", "packages/pi-plugin/src", "packages/cli/src"]
+        .flatMap((directory) => files(join(root, directory)))
+        .map((path) => scan(relative(root, path), readFileSync(path, "utf8")));
+    expect(scans.reduce((sum, scan) => sum + scan.transactions, 0)).toBeGreaterThan(50);
+    expect(scans.reduce((sum, scan) => sum + scan.literals, 0)).toBeGreaterThan(20);
+    expect(scans.flatMap((scan) => scan.violations)).toEqual([]);
+});
+
+test("acquisition fence rejects raw native transactions and unrouted BEGIN shapes", () => {
+    expect(
+        scan(
+            "new-writer.ts",
+            'import { Database } from "bun:sqlite"; new Database(":memory:").transaction(() => write())();',
+        ).violations,
+    ).toHaveLength(1);
+    expect(
+        scan(
+            "new-writer.ts",
+            'const { DatabaseSync } = require("node:sqlite"); new DatabaseSync(":memory:").transaction(() => write())();',
+        ).violations,
+    ).toHaveLength(1);
+    expect(scan("new-writer.ts", 'export { Database } from "bun:sqlite";').violations).toHaveLength(
+        1,
+    );
+    expect(scan("new-writer.ts", 'db.prepare("BEGIN IMMEDIATE").run();').violations).toHaveLength(
+        1,
+    );
+    expect(
+        scan("new-writer.ts", 'db.exec("BEGIN IMMEDIATE; INSERT INTO result VALUES (1)");')
+            .violations,
+    ).toHaveLength(1);
+    expect(scan("new-writer.ts", "db.exec(`BEGIN IMMEDIATE; ${extra}`);").violations).toHaveLength(
+        1,
+    );
+    expect(
+        scan(
+            "new-writer.ts",
+            'import { Database } from "./shared/sqlite"; db.exec("BEGIN IMMEDIATE"); db.transaction(() => write()).immediate();',
+        ).violations,
+    ).toEqual([]);
+});

package/src/shared/sqlite-acquisition-routing.test.ts

@@ -0,0 +1,94 @@
+import { expect, spyOn, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Database, withPrivilegedWriter, withSqliteTransformPass } from "./sqlite";
+import { startSqliteWriteLocker } from "./sqlite-write-locker-test-support";
+
+for (const mode of ["default", "immediate", "exclusive", "literal"] as const) {
+    test(`shared SQLite retries ${mode} acquisition before running any writes`, async () => {
+        const dir = mkdtempSync(join(tmpdir(), "mc-routed-acquisition-"));
+        const path = join(dir, "context.db");
+        const db = new Database(path);
+        db.exec("PRAGMA journal_mode=WAL; PRAGMA busy_timeout=50; CREATE TABLE result(value TEXT)");
+        const locker = await startSqliteWriteLocker(path, 650);
+        let calls = 0;
+        const write = () => {
+            calls++;
+            db.prepare("INSERT INTO result VALUES (?)").run("once");
+            return "managed";
+        };
+        try {
+            withSqliteTransformPass(() => {
+                if (mode === "literal") {
+                    db.exec("BEGIN IMMEDIATE");
+                    write();
+                    db.exec("COMMIT");
+                } else {
+                    const transaction = db.transaction(write);
+                    expect(mode === "default" ? transaction() : transaction[mode]()).toBe(
+                        "managed",
+                    );
+                }
+            });
+            expect(calls).toBe(1);
+            expect(db.prepare("SELECT * FROM result").all()).toEqual([{ value: "once" }]);
+        } finally {
+            await locker.exited;
+            db.close();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }, 30000);
+}
+
+test("routed transactions preserve nesting, receiver, arguments and rollback without callback retries", () => {
+    const db = new Database(":memory:");
+    db.exec("CREATE TABLE result(value TEXT)");
+    let calls = 0;
+    const transaction = db.transaction(function (this: { prefix: string }, value: string) {
+        calls++;
+        db.prepare("INSERT INTO result VALUES (?)").run(this.prefix + value);
+        db.transaction(() => {
+            db.exec("INSERT INTO result VALUES ('inner')");
+        }).immediate();
+        throw Object.assign(new Error("busy after writes"), { code: "SQLITE_BUSY" });
+    });
+    try {
+        expect(() =>
+            withSqliteTransformPass(() => transaction.call({ prefix: "outer-" }, "value")),
+        ).toThrow("busy after writes");
+        expect(calls).toBe(1);
+        expect(db.prepare("SELECT * FROM result").all()).toEqual([]);
+    } finally {
+        db.close();
+    }
+});
+
+test("exhausted routed acquisition never enters the callback or multiplies privileged retries", () => {
+    const dir = mkdtempSync(join(tmpdir(), "mc-routed-exhaustion-"));
+    const path = join(dir, "context.db");
+    const blocker = new Database(path);
+    const db = new Database(path);
+    blocker.exec("PRAGMA journal_mode=WAL; CREATE TABLE result(value TEXT)");
+    db.exec("PRAGMA busy_timeout=0");
+    blocker.exec("BEGIN IMMEDIATE");
+    const wait = spyOn(Atomics, "wait").mockReturnValue("timed-out");
+    let callbacks = 0;
+    try {
+        for (const run of [
+            () => db.transaction(() => callbacks++)(),
+            () => withPrivilegedWriter(db, () => callbacks++),
+        ]) {
+            wait.mockClear();
+            expect(() => withSqliteTransformPass(run)).toThrow("after 3 attempts");
+            expect(wait).toHaveBeenCalledTimes(2);
+            expect(callbacks).toBe(0);
+        }
+    } finally {
+        wait.mockRestore();
+        blocker.exec("ROLLBACK");
+        blocker.close();
+        db.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/src/shared/sqlite-pass-scope.test.ts

@@ -0,0 +1,182 @@
+import { expect, spyOn, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+    Database,
+    withoutSqliteTransformPass,
+    withPrivilegedWriter,
+    withSqliteTransformPass,
+} from "./sqlite";
+
+test("background privileged acquisition attempts once without backoff", () => {
+    const db = new Database(":memory:");
+    const error = Object.assign(new Error("original busy"), { code: "SQLITE_BUSY" });
+    const exec = spyOn(db, "exec").mockImplementation(() => {
+        throw error;
+    });
+    const wait = spyOn(Atomics, "wait").mockReturnValue("timed-out");
+    let callbacks = 0;
+    try {
+        expect(() => withPrivilegedWriter(db, () => callbacks++)).toThrow("original busy");
+        expect(exec).toHaveBeenCalledTimes(1);
+        expect(wait).not.toHaveBeenCalled();
+        expect(callbacks).toBe(0);
+    } finally {
+        exec.mockRestore();
+        wait.mockRestore();
+        db.close();
+    }
+});
+
+test("background transaction exhausts one five-second busy timeout", () => {
+    const dir = mkdtempSync(join(tmpdir(), "mc-background-busy-"));
+    const path = join(dir, "context.db");
+    const blocker = new Database(path);
+    const writer = new Database(path);
+    blocker.exec("PRAGMA journal_mode=WAL; CREATE TABLE result(value TEXT)");
+    writer.exec("PRAGMA busy_timeout=5000");
+    blocker.exec("BEGIN IMMEDIATE");
+    let callbacks = 0;
+    try {
+        const start = performance.now();
+        expect(() => writer.transaction(() => callbacks++)()).toThrow();
+        const elapsed = performance.now() - start;
+        expect(callbacks).toBe(0);
+        expect(elapsed).toBeGreaterThanOrEqual(4500);
+        expect(elapsed).toBeLessThan(7500);
+    } finally {
+        blocker.exec("ROLLBACK");
+        blocker.close();
+        writer.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+}, 30000);
+
+test("foreground retry scope crosses awaits, nests and excludes detached maintenance", async () => {
+    const db = new Database(":memory:");
+    const error = Object.assign(new Error("busy"), { code: "SQLITE_BUSY" });
+    const exec = spyOn(db, "exec").mockImplementation(() => {
+        throw error;
+    });
+    const wait = spyOn(Atomics, "wait").mockReturnValue("timed-out");
+    const acquire = () =>
+        withPrivilegedWriter(db, () => {
+            throw new Error("callback must not run");
+        });
+    let late: Promise<void> | undefined;
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+        release = resolve;
+    });
+    try {
+        await withSqliteTransformPass(async () => {
+            await Promise.resolve();
+            expect(() => withSqliteTransformPass(acquire)).toThrow("after 3 attempts");
+            expect(exec).toHaveBeenCalledTimes(3);
+            exec.mockClear();
+            wait.mockClear();
+            withoutSqliteTransformPass(() => {
+                expect(acquire).toThrow("busy");
+                expect(exec).toHaveBeenCalledTimes(1);
+                expect(wait).not.toHaveBeenCalled();
+            });
+            exec.mockClear();
+            expect(acquire).toThrow("after 3 attempts");
+            expect(exec).toHaveBeenCalledTimes(3);
+            late = (async () => {
+                await gate;
+                exec.mockClear();
+                wait.mockClear();
+                expect(acquire).toThrow("busy");
+                expect(exec).toHaveBeenCalledTimes(1);
+                expect(wait).not.toHaveBeenCalled();
+            })();
+        });
+        release();
+        await late;
+        exec.mockClear();
+        expect(acquire).toThrow("busy");
+        expect(exec).toHaveBeenCalledTimes(1);
+    } finally {
+        release();
+        exec.mockRestore();
+        wait.mockRestore();
+        db.close();
+    }
+});
+
+test("throwing foreground passes cannot leak retry policy to later work", async () => {
+    const db = new Database(":memory:");
+    const exec = spyOn(db, "exec").mockImplementation(() => {
+        throw Object.assign(new Error("busy"), { code: "SQLITE_BUSY" });
+    });
+    const wait = spyOn(Atomics, "wait").mockReturnValue("timed-out");
+    try {
+        await expect(
+            withSqliteTransformPass(async () => {
+                throw new Error("pass failed");
+            }),
+        ).rejects.toThrow("pass failed");
+        expect(() => withPrivilegedWriter(db, () => undefined)).toThrow("busy");
+        expect(exec).toHaveBeenCalledTimes(1);
+        expect(wait).not.toHaveBeenCalled();
+    } finally {
+        exec.mockRestore();
+        wait.mockRestore();
+        db.close();
+    }
+});
+
+test("explicit deferred reads on a writable handle do not contend with the writer", () => {
+    const dir = mkdtempSync(join(tmpdir(), "mc-deferred-read-"));
+    const path = join(dir, "context.db");
+    const writer = new Database(path);
+    const reader = new Database(path);
+    writer.exec(
+        "PRAGMA journal_mode=WAL; CREATE TABLE result(value TEXT); INSERT INTO result VALUES ('committed')",
+    );
+    reader.exec("PRAGMA busy_timeout=0");
+    writer.exec("BEGIN IMMEDIATE");
+    writer.exec("INSERT INTO result VALUES ('uncommitted')");
+    try {
+        const rows = withSqliteTransformPass(() =>
+            reader.transaction(() => reader.prepare("SELECT value FROM result").all()).deferred(),
+        );
+        expect(rows).toEqual([{ value: "committed" }]);
+    } finally {
+        writer.exec("ROLLBACK");
+        writer.close();
+        reader.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+
+test("an explicitly started foreground pass owns its lifetime independently", async () => {
+    const db = new Database(":memory:");
+    const exec = spyOn(db, "exec").mockImplementation(() => {
+        throw Object.assign(new Error("busy"), { code: "SQLITE_BUSY" });
+    });
+    const wait = spyOn(Atomics, "wait").mockReturnValue("timed-out");
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+        release = resolve;
+    });
+    let child!: Promise<void>;
+    try {
+        await withSqliteTransformPass(async () => {
+            child = withSqliteTransformPass(async () => {
+                await gate;
+                expect(() => withPrivilegedWriter(db, () => undefined)).toThrow("after 3 attempts");
+                expect(exec).toHaveBeenCalledTimes(3);
+            });
+        });
+        release();
+        await child;
+    } finally {
+        release();
+        exec.mockRestore();
+        wait.mockRestore();
+        db.close();
+    }
+});