@retaw106/mmc-oc 2.3.0 → 2.5.0

package/src/shared/sqlite.ts

@@ -39,7 +39,7 @@
  * `run()` → {changes,lastInsertRowid}) is identical and was verified directly.
  */
 
-import { AsyncLocalStorage } from "node:async_hooks";
+import { AsyncLocalStorage, AsyncResource } from "node:async_hooks";
 import { statSync } from "node:fs";
 // Type import only — runtime is loaded dynamically below. @types/better-sqlite3
 // has the richest definitions and is a structural superset of the API surface
@@ -47,6 +47,16 @@ import { statSync } from "node:fs";
 // node:sqlite at runtime (both expose prepare/run/get/all/exec/close).
 import type BetterSqlite3 from "better-sqlite3";
 
+// Capture the root before creating request-local AsyncLocalStorage scopes.
+// Shared workers and timers must not inherit callbacks that reject stale
+// database writes: those callbacks can retain an obsolete request's inputs.
+const resourceRoot = new AsyncResource("magic-context:root");
+
+/** Create host-owned resources without inheriting request-local state. */
+export function inRootAsyncContext<T>(operation: () => T): T {
+    return resourceRoot.runInAsyncScope(operation);
+}
+
 /**
  * Slow-write reporting is injected rather than imported: this module is also
  * executed directly by Node (the `node:sqlite` smoke in CI, Pi, Desktop), and
@@ -383,11 +393,187 @@ export function getTagIdentityWriteGeneration(): number {
     return tagIdentityWriteGeneration;
 }
 
-/** Route native Bun and Node transaction entry through the same acquisition retry.
- * Native Bun transaction wrappers execute BEGIN internally, bypassing an exec override,
- * so both runtimes use this small synchronous wrapper instead. Writable handles
- * default to IMMEDIATE; explicit deferred calls and readonly handles keep read
- * snapshots without acquiring the writer lock. */
+/** Only Pi serving connections need a mirror of their native busy handler. */
+const busyTimeoutStates = new WeakMap<Database, { current: number }>();
+const BUSY_TIMEOUT_QUERY =
+    /^\s*PRAGMA\s+(?:(?:\w+|"[^"]+"|`[^`]+`|\[[^\]]+\])\s*\.\s*)?(?:busy_timeout|"busy_timeout"|`busy_timeout`|\[busy_timeout\])\s*;?\s*$/i;
+const BUSY_TIMEOUT_SETTER =
+    /^\s*PRAGMA\s+(?:(?:\w+|"[^"]+"|`[^`]+`|\[[^\]]+\])\s*\.\s*)?(?:busy_timeout|"busy_timeout"|`busy_timeout`|\[busy_timeout\])\s*(?==|\()/i;
+
+function literalBusyTimeout(sql: string): number | undefined {
+    const head = BUSY_TIMEOUT_SETTER.exec(sql);
+    if (!head) return undefined;
+    const match = /^(?:=\s*|\(\s*)(?:'(-?\d+)'|"(-?\d+)"|(-?\d+))\s*\)?\s*;?\s*$/.exec(
+        sql.slice(head[0].length),
+    );
+    if (!match) return undefined;
+    const value = Number(match[1] ?? match[2] ?? match[3]);
+    return value < 0 ? 0 : value <= 0x7fffffff ? value : undefined;
+}
+
+/** Split timeout-setting scripts without mistaking quoted text or comments for pragmas. */
+function busyTimeoutStatements(sql: string): string[] {
+    const statements: string[] = [];
+    let statement = "";
+    let quote = "";
+    for (let i = 0; i < sql.length; i++) {
+        const char = sql[i];
+        if (quote) {
+            statement += char;
+            if (char === quote) {
+                if (sql[i + 1] === quote) statement += sql[++i];
+                else quote = "";
+            }
+        } else if (char === "'" || char === '"' || char === "`" || char === "[") {
+            quote = char === "[" ? "]" : char;
+            statement += char;
+        } else if (char === "-" && sql[i + 1] === "-") {
+            while (i + 1 < sql.length && sql[i + 1] !== "\n") i++;
+            statement += " ";
+        } else if (char === "/" && sql[i + 1] === "*") {
+            i += 2;
+            while (i < sql.length && !(sql[i] === "*" && sql[i + 1] === "/")) i++;
+            i++;
+            statement += " ";
+        } else if (char === ";") {
+            statements.push(statement);
+            statement = "";
+        } else statement += char;
+    }
+    statements.push(statement);
+    return statements.filter((part) => part.trim().length > 0);
+}
+
+/** Install the native deadline layer only on a connection that will serve Pi turns. */
+function installNativeDeadlineRouting(db: BetterSqlite3.Database): void {
+    const rawExec = db.exec.bind(db);
+    const rawPrepare = db.prepare.bind(db);
+    const readTimeout = (): number => {
+        const statement = rawPrepare("PRAGMA busy_timeout");
+        try {
+            return Object.values(statement.get() as Record<string, number>)[0];
+        } finally {
+            (statement as Partial<FinalizableStatement>).finalize?.();
+        }
+    };
+    const timeoutState = { current: readTimeout() };
+    busyTimeoutStates.set(db, timeoutState);
+    const setBusyTimeout = (timeout: number): void => {
+        rawExec(`PRAGMA busy_timeout=${timeout}`);
+        timeoutState.current = timeout;
+    };
+    const withinDeadline = <T>(operation: () => T): T => {
+        const deadline = nativeWaitScope?.getStore();
+        if (!deadline?.active || !deadline.remainingMs) return operation();
+        const remaining = deadline.remainingMs();
+        if (remaining === Infinity) return operation();
+        const previous = timeoutState.current;
+        const timeout = Math.min(previous, Math.max(0, Math.floor(remaining)));
+        if (timeout === previous) return operation();
+        setBusyTimeout(timeout);
+        try {
+            return operation();
+        } finally {
+            setBusyTimeout(previous);
+        }
+    };
+    Object.defineProperty(db, "exec", {
+        configurable: true,
+        writable: true,
+        value: (sql: string) => {
+            const parts = /\bbusy_timeout\b/i.test(sql) ? busyTimeoutStatements(sql) : [];
+            if (parts.length === 1 && BUSY_TIMEOUT_QUERY.test(parts[0])) return rawExec(sql);
+            const singleSetter = parts.length === 1 && BUSY_TIMEOUT_SETTER.test(parts[0]);
+            const setting = singleSetter ? literalBusyTimeout(parts[0]) : undefined;
+            if (singleSetter) {
+                const result = rawExec(sql);
+                timeoutState.current = setting ?? readTimeout();
+                return result;
+            }
+            if (!/\bbusy_timeout\b/i.test(sql)) return withinDeadline(() => rawExec(sql));
+            const setters = parts.filter((part) => BUSY_TIMEOUT_SETTER.test(part));
+            return withinDeadline(() => {
+                try {
+                    const result = rawExec(sql);
+                    if (setters.length)
+                        timeoutState.current =
+                            literalBusyTimeout(setters[setters.length - 1]) ?? readTimeout();
+                    return result;
+                } catch (error) {
+                    // exec can apply a timeout-setting prefix before a later statement
+                    // fails. Only an ambiguous setting needs a native readback.
+                    if (setters.length) timeoutState.current = readTimeout();
+                    throw error;
+                }
+            });
+        },
+    });
+    // Timeout introspection cannot wait on a database lock. Its getter must
+    // report the configured timeout, not a temporary cap that a caller might save.
+    const nativePrepare = (sql: string) =>
+        BUSY_TIMEOUT_QUERY.test(sql) || BUSY_TIMEOUT_SETTER.test(sql)
+            ? rawPrepare(sql)
+            : withinDeadline(() => rawPrepare(sql));
+    Object.defineProperty(db, "prepare", {
+        configurable: true,
+        writable: true,
+        value: (sql: string) => {
+            // biome-ignore lint/suspicious/noExplicitAny: Bun adds values() to the common statement interface.
+            const statement: any = nativePrepare(sql);
+            const normalized = /\bbusy_timeout\b/i.test(sql)
+                ? (busyTimeoutStatements(sql)[0] ?? sql)
+                : sql;
+            const setting = literalBusyTimeout(normalized);
+            const timeoutSetter = BUSY_TIMEOUT_SETTER.test(normalized);
+            const timeoutQuery = BUSY_TIMEOUT_QUERY.test(normalized);
+            // SQLite applies this PRAGMA while preparing it, before get/run.
+            if (timeoutSetter) timeoutState.current = setting ?? readTimeout();
+            for (const method of ["run", "get", "all", "values"] as const) {
+                const execute = statement[method]?.bind(statement);
+                if (!execute) continue;
+                Object.defineProperty(statement, method, {
+                    configurable: true,
+                    // biome-ignore lint/suspicious/noExplicitAny: retain native binding overloads.
+                    value: (...args: any[]) => {
+                        if (timeoutQuery) return execute(...args);
+                        if (!timeoutSetter) return withinDeadline(() => execute(...args));
+                        const result = execute(...args);
+                        timeoutState.current = readTimeout();
+                        return result;
+                    },
+                });
+            }
+            if (typeof statement.iterate === "function") {
+                const iterate = statement.iterate.bind(statement);
+                Object.defineProperty(statement, "iterate", {
+                    configurable: true,
+                    // biome-ignore lint/suspicious/noExplicitAny: retain native binding overloads.
+                    value: (...args: any[]) => {
+                        const iterator =
+                            !timeoutSetter && !timeoutQuery
+                                ? withinDeadline(() => iterate(...args))
+                                : iterate(...args);
+                        const next = iterator.next.bind(iterator);
+                        if (timeoutSetter) timeoutState.current = readTimeout();
+                        iterator.next = () => {
+                            if (timeoutQuery) return next();
+                            if (!timeoutSetter) return withinDeadline(next);
+                            const result = next();
+                            timeoutState.current = readTimeout();
+                            return result;
+                        };
+                        return iterator;
+                    },
+                });
+            }
+            return statement;
+        },
+    });
+}
+
+/** Route native Bun and Node transactions through the same acquisition retry.
+ * Native Bun wrappers execute BEGIN internally, so both runtimes use this wrapper.
+ * Deadline routing, when selected, is installed underneath it at connection open. */
 function installTransactionRouting(db: BetterSqlite3.Database, readonly: boolean): void {
     const nativeExec = db.exec.bind(db);
     Object.defineProperty(db, "exec", {
@@ -419,7 +605,9 @@ function installTransactionRouting(db: BetterSqlite3.Database, readonly: boolean
                 !/^\s*(?:SELECT|EXPLAIN|PRAGMA|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE)\b/i.test(sql)
             ) {
                 try {
-                    return withAutocommitTimeout(db, () => nativeExec(sql));
+                    // exec can commit a script prefix before BUSY. Run it once;
+                    // only prepared statements are safe to probe and retry.
+                    return withAutocommitTimeout(db, () => nativeExec(sql), false);
                 } finally {
                     if (mayChangeTagIdentity(sql)) tagIdentityWriteGeneration += 1;
                 }
@@ -543,6 +731,7 @@ function trackSqliteConnection(
     db: BetterSqlite3.Database,
     filename: unknown,
     options: unknown,
+    turnDeadlines = false,
 ): BetterSqlite3.Database {
     const originalClose = db.close.bind(db) as (...args: unknown[]) => unknown;
     const sequence = nextSqliteConnectionSequence++;
@@ -560,6 +749,7 @@ function trackSqliteConnection(
             ((options as { readonly?: unknown }).readonly === true ||
                 (options as { readOnly?: unknown }).readOnly === true),
     };
+    if (turnDeadlines) installNativeDeadlineRouting(db);
     installTransactionRouting(db, metadata.readonly);
     Object.defineProperty(db, "close", {
         configurable: true,
@@ -586,7 +776,9 @@ function trackSqliteConnection(
 
 const TrackedDatabase = new Proxy(DatabaseImpl, {
     construct(target, args) {
-        const db = Reflect.construct(target, args, target) as BetterSqlite3.Database;
+        const db = inRootAsyncContext(
+            () => Reflect.construct(target, args, target) as BetterSqlite3.Database,
+        );
         return trackSqliteConnection(db, args[0], args[1]);
     },
 }) as typeof BetterSqlite3;
@@ -640,6 +832,18 @@ function buildNodeSqliteDatabaseClass(DatabaseSync: any): typeof BetterSqlite3 {
 
 export const Database: typeof BetterSqlite3 = TrackedDatabase;
 
+/** Open a Pi foreground connection with native-deadline routing before statements are prepared. */
+export function createSqliteTurnDatabase(
+    filename?: string | Buffer,
+    options?: BetterSqlite3.Options,
+): Database {
+    return trackSqliteConnection(new DatabaseImpl(filename, options), filename, options, true);
+}
+
+export function hasSqliteTurnDeadlineRouting(db: Database): boolean {
+    return busyTimeoutStates.has(db);
+}
+
 /** The constructor path, without querying SQLite on the prompt thread. */
 export function getSqliteDatabasePath(db: Database): string | null {
     for (const connection of trackedSqliteConnections.values()) {
@@ -664,6 +868,10 @@ function pragmaValue(db: BetterSqlite3.Database, name: string): unknown {
 }
 
 function pragmaNumber(db: BetterSqlite3.Database, name: string): number | null {
+    if (name === "busy_timeout") {
+        const state = busyTimeoutStates.get(db);
+        if (state) return state.current;
+    }
     try {
         const value = pragmaValue(db, name);
         return typeof value === "number" && Number.isFinite(value) ? value : null;
@@ -870,6 +1078,38 @@ export function prepareCachedStatement(db: Database, sql: string): Statement {
 }
 
 const privilegeDepth = new WeakMap<Database, number>();
+interface NativeWaitLease {
+    active: boolean;
+    remainingMs?: () => number;
+}
+let nativeWaitScope: AsyncLocalStorage<NativeWaitLease | undefined> | undefined;
+
+function releaseNativeWaitLease(lease: NativeWaitLease): void {
+    lease.active = false;
+    // Detached descendants can retain their async-local lease after the turn.
+    // Do not retain the completed request through its deadline callback.
+    lease.remainingMs = undefined;
+}
+
+/** Bound native lock waits for an awaited turn, without changing background timeouts. */
+export function withSqliteTurnDeadline<T>(remainingMs: () => number, operation: () => T): T {
+    const scope = (nativeWaitScope ??= new AsyncLocalStorage<NativeWaitLease | undefined>());
+    const lease: NativeWaitLease = { active: true, remainingMs };
+    return scope.run(lease, () => {
+        try {
+            const result = operation();
+            if (result && typeof (result as { then?: unknown }).then === "function")
+                return Promise.resolve(result).finally(
+                    releaseNativeWaitLease.bind(null, lease),
+                ) as T;
+            releaseNativeWaitLease(lease);
+            return result;
+        } catch (error) {
+            releaseNativeWaitLease(lease);
+            throw error;
+        }
+    });
+}
 const transformPassScope = new AsyncLocalStorage<
     | {
           active: boolean;
@@ -883,7 +1123,8 @@ const backgroundWriterScope = new AsyncLocalStorage<boolean>();
 
 /** Opt in only a writer that can safely defer its work after a busy acquisition. */
 export function withSqliteBackgroundWriter<T>(operation: () => T): T {
-    return backgroundWriterScope.run(true, operation);
+    if (!nativeWaitScope?.getStore()) return backgroundWriterScope.run(true, operation);
+    return nativeWaitScope.run(undefined, () => backgroundWriterScope.run(true, operation));
 }
 
 /** Only an awaited foreground transform may spend the extra acquisition budget.
@@ -920,7 +1161,8 @@ export function withSqliteTransformPass<T>(operation: () => T): T {
 
 /** Start detached maintenance work without borrowing a foreground pass's budget. */
 export function withoutSqliteTransformPass<T>(operation: () => T): T {
-    return transformPassScope.run(undefined, operation);
+    if (!nativeWaitScope?.getStore()) return transformPassScope.run(undefined, operation);
+    return nativeWaitScope.run(undefined, () => transformPassScope.run(undefined, operation));
 }
 
 /** Attach the adapter's existing generation/cancellation/deadline guard to writes. */
@@ -999,33 +1241,60 @@ function foregroundWaitLease() {
         : 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 {
+/** Probe a prepared statement's writer lock without charging uncontended work
+ * against the foreground lock-wait budget. An exec script may commit some of
+ * its statements before failing, so it cannot be retried without duplicating
+ * writes; conservatively charge its single attempt's full execution time. */
+function withAutocommitTimeout<T>(db: Database, operation: () => T, singleStatement = true): T {
     assertTransformWrite();
     const lease = foregroundWaitLease();
     if (isInTransaction(db)) return operation();
     const scoped = lease || backgroundWriterScope.getStore();
     const previous = scoped ? pragmaNumber(db, "busy_timeout") : null;
-    if (scoped)
-        db.exec(
-            `PRAGMA busy_timeout=${lease ? Math.floor(Math.min(lease.remainingWaitMs, lease.guard?.remainingMs() ?? Infinity)) : SHORT_BUSY_TIMEOUT_MS}`,
-        );
     const started = performance.now();
     let completed = false;
-    try {
+    const execute = () => {
         const result = operation();
         completed = true;
         return result;
+    };
+    try {
+        if (!scoped) return execute();
+        if (singleStatement) {
+            db.exec("PRAGMA busy_timeout=0");
+            try {
+                return execute();
+            } catch (error) {
+                if (!isTransientSqliteError(error) || isInTransaction(db)) throw error;
+            }
+            assertTransformWrite();
+        }
+        const timeout = Math.floor(
+            Math.min(
+                lease?.remainingWaitMs ?? SHORT_BUSY_TIMEOUT_MS,
+                lease?.guard?.remainingMs() ?? Infinity,
+            ),
+        );
+        db.exec(`PRAGMA busy_timeout=${timeout}`);
+        const waitStarted = performance.now();
+        try {
+            return execute();
+        } finally {
+            // Deduct the prepared statement's contended retry or the exec
+            // script's execution from the remaining foreground wait budget;
+            // the native API cannot separate lock waiting from execution.
+            if (lease)
+                lease.remainingWaitMs = Math.max(
+                    0,
+                    lease.remainingWaitMs - (performance.now() - waitStarted),
+                );
+        }
     } catch (error) {
         if (lease && isTransientSqliteError(error))
             throw new SqliteAcquisitionBusyError(error, "autocommit");
         throw error;
     } finally {
         const elapsed = performance.now() - started;
-        if (lease) lease.remainingWaitMs = Math.max(0, lease.remainingWaitMs - elapsed);
         if (previous !== null) db.exec(`PRAGMA busy_timeout=${previous}`);
         // Native autocommit does not expose the instant its lock was acquired.
         // Label the upper bound so a waiting statement is not blamed as a holder.
@@ -1192,7 +1461,7 @@ export async function withAsyncPrivilegedWriter<T>(
     operation: () => T,
     options: {
         signal?: AbortSignal;
-        beforeRetry?: (error: SqliteAcquisitionBusyError) => void;
+        beforeRetry?: (error: SqliteAcquisitionBusyError) => void | Promise<void>;
         jitter?: boolean;
         budgetMs?: number;
         assertCurrentPass?: () => void;
@@ -1235,7 +1504,7 @@ export async function withAsyncPrivilegedWriter<T>(
             if (entered || !(error instanceof SqliteAcquisitionBusyError)) throw error;
             // Adapters may serve a validated saved request instead of waiting.
             // This runs only after a failed BEGIN, never after callback writes.
-            options.beforeRetry?.(error);
+            await options.beforeRetry?.(error);
             const elapsed = performance.now() - started;
             if (elapsed >= budgetMs) {
                 reportSqliteDiagnostic(

package/src/shared/stable-json.ts

@@ -22,33 +22,33 @@ export function stableStringify(value: unknown, seen = new WeakSet<object>()): s
     // value's text once per enclosing level, so a large value N levels deep cost
     // N copies of itself.
     const pieces: string[] = [];
-    writeStable(value, seen, pieces);
+    writeStable(value, seen, (piece) => pieces.push(piece));
     return pieces.join("");
 }
 
-function writeStable(value: unknown, seen: WeakSet<object>, pieces: string[]): void {
+function writeStable(value: unknown, seen: WeakSet<object>, write: (piece: string) => void): void {
     if (value === undefined) {
-        pieces.push("undefined");
+        write("undefined");
         return;
     }
     if (value === null || typeof value !== "object") {
-        pieces.push(JSON.stringify(value) ?? String(value));
+        write(JSON.stringify(value) ?? String(value));
         return;
     }
     // Any object met a second time, shared or cyclic, is written as "[Circular]".
     if (seen.has(value)) {
-        pieces.push('"[Circular]"');
+        write('"[Circular]"');
         return;
     }
     seen.add(value);
     if (Array.isArray(value)) {
-        pieces.push("[");
+        write("[");
         for (let index = 0; index < value.length; index += 1) {
-            if (index > 0) pieces.push(",");
+            if (index > 0) write(",");
             // A hole writes nothing between its commas, as joining a mapped array did.
-            if (index in value) writeStable(value[index], seen, pieces);
+            if (index in value) writeStable(value[index], seen, write);
         }
-        pieces.push("]");
+        write("]");
         return;
     }
     // Code-point sort (NOT localeCompare). Stable across runtimes/locales.
@@ -57,11 +57,53 @@ function writeStable(value: unknown, seen: WeakSet<object>, pieces: string[]): v
         if (a > b) return 1;
         return 0;
     });
-    pieces.push("{");
+    // Native JSON can emit a small scalar-only object in one operation. Larger
+    // containers still stream; undefined and integer keys need the writer's
+    // non-native spelling/order. Bound chunks so hashing never builds a large JSON string.
+    if (
+        entries.length > 0 &&
+        entries.length <= 16 &&
+        entries.every(
+            ([key, child]) =>
+                key.length <= 4096 &&
+                !/^(0|[1-9]\d*)$/.test(key) &&
+                (child === null ||
+                    typeof child === "number" ||
+                    typeof child === "boolean" ||
+                    (typeof child === "string" && child.length <= 4096)),
+        )
+    ) {
+        write(JSON.stringify(Object.fromEntries(entries)));
+        return;
+    }
+    write("{");
     entries.forEach(([key, child], index) => {
-        if (index > 0) pieces.push(",");
-        pieces.push(JSON.stringify(key), ":");
-        writeStable(child, seen, pieces);
+        if (index > 0) write(",");
+        write(JSON.stringify(key));
+        write(":");
+        writeStable(child, seen, write);
     });
-    pieces.push("}");
+    write("}");
+}
+
+/** The existing UTF-16 FNV fingerprint, without retaining the serialized JSON. */
+export function stableStringifyHash(value: unknown, prefix = ""): string {
+    const sink = jsonHashSink(prefix);
+    writeStable(value, new WeakSet(), sink.write);
+    return sink.digest();
+}
+
+/** Hash the same code units as the content memo, including lone surrogates. */
+export function jsonHashSink(prefix = ""): {
+    write: (piece: string) => void;
+    digest: () => string;
+} {
+    let hash = 0x811c9dc5;
+    const write = (piece: string): void => {
+        for (let index = 0; index < piece.length; index++) {
+            hash = Math.imul(hash ^ piece.charCodeAt(index), 0x01000193);
+        }
+    };
+    write(prefix);
+    return { write, digest: () => (hash >>> 0).toString(16).padStart(8, "0") };
 }

package/src/shared/storage-file-mutex.test.ts

@@ -1,9 +1,10 @@
-import { afterAll, describe, expect, test } from "bun:test";
+import { afterAll, describe, expect, spyOn, test } from "bun:test";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { withStorageFileMutex } from "./storage-file-mutex";
+import * as permissions from "./storage-permissions";
 
 const directories: string[] = [];
 const newDirectory = () => {
@@ -16,6 +17,54 @@ afterAll(() => {
 });
 
 describe("withStorageFileMutex", () => {
+    for (const removals of [1, 2, 3]) {
+        test(`ticket creation tolerates at most two directory cleanup races (${removals})`, () => {
+            const directory = newDirectory();
+            const write = permissions.writeStorageFileSync;
+            let attempts = 0;
+            let worked = false;
+            const writer = spyOn(permissions, "writeStorageFileSync").mockImplementation(
+                (...args) => {
+                    if (attempts++ < removals) rmdirSync(directory);
+                    return write(...args);
+                },
+            );
+            try {
+                const acquire = () =>
+                    withStorageFileMutex(directory, () => {
+                        worked = true;
+                        return "acquired";
+                    });
+                if (removals <= 2) {
+                    expect(acquire()).toBe("acquired");
+                    // Includes the successful contender's atomic ticket rewrite.
+                    expect(attempts).toBe(removals + 2);
+                    expect(readdirSync(directory)).toEqual([]);
+                } else {
+                    expect(acquire).toThrow("ENOENT");
+                    expect(attempts).toBe(3);
+                }
+                expect(worked).toBe(removals <= 2);
+            } finally {
+                writer.mockRestore();
+            }
+        });
+    }
+
+    test("does not retry other ticket write failures", () => {
+        const directory = newDirectory();
+        const error = Object.assign(new Error("denied"), { code: "EACCES" });
+        const writer = spyOn(permissions, "writeStorageFileSync").mockImplementation(() => {
+            throw error;
+        });
+        try {
+            expect(() => withStorageFileMutex(directory, () => 42)).toThrow(error);
+            expect(writer).toHaveBeenCalledTimes(1);
+        } finally {
+            writer.mockRestore();
+        }
+    });
+
     test("serializes two critical sections", () => {
         const directory = newDirectory();
         const orderPath = join(directory, "order");

package/src/shared/storage-file-mutex.ts

@@ -68,7 +68,17 @@ export function withStorageFileMutex<T>(directory: string, work: () => T, timeou
     const ticket: Ticket = { choosing: true, number: 0, birth, checksum: "" };
     const encodedTicket = () =>
         JSON.stringify({ ...ticket, checksum: ticketChecksum(name, ticket) });
-    writeStorageFileSync(ownPath, encodedTicket(), { flag: "wx", forcePrivate: true });
+    for (let attempt = 0; ; attempt++) {
+        try {
+            writeStorageFileSync(ownPath, encodedTicket(), { flag: "wx", forcePrivate: true });
+            break;
+        } catch (error) {
+            // A session cleanup can remove an empty directory between mkdir and
+            // ticket creation. No ticket exists yet, so retry before contending.
+            if ((error as NodeJS.ErrnoException).code !== "ENOENT" || attempt >= 2) throw error;
+            ensurePrivateStorageDirectorySync(directory);
+        }
+    }
     const deadline = performance.now() + timeoutMs;
     const peers = (): [string, Ticket | null][] => {
         const found: [string, Ticket | null][] = [];

package/src/shared/system-directive.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { removeNestedBlocks, removeSystemReminders } from "./system-directive";
+
+describe("removeSystemReminders", () => {
+    test("removes nested reminders without leaking the outer tail", () => {
+        expect(
+            removeSystemReminders(
+                "before <system-reminder>outer <system-reminder>inner</system-reminder> tail</system-reminder> after",
+            ),
+        ).toBe("before  after");
+    });
+
+    test("removes unclosed reminders through the end", () => {
+        expect(
+            removeSystemReminders(
+                " keep <system-reminder>hidden <system-reminder>nested</system-reminder> tail",
+            ),
+        ).toBe("keep");
+    });
+
+    test("handles attributes, case, self-closing tags and adjacent blocks", () => {
+        expect(
+            removeSystemReminders(
+                'a<SYSTEM-REMINDER id="x">hidden</SYSTEM-REMINDER><system-reminder/>b<system-reminder>hidden</system-reminder>c',
+            ),
+        ).toBe("abc");
+    });
+
+    test("preserves ordinary content and other tags", () => {
+        expect(removeSystemReminders(" <other>visible</other> ")).toBe("<other>visible</other>");
+    });
+});
+
+test("removeNestedBlocks tracks multiple tag names and only closes the matching top", () => {
+    expect(removeNestedBlocks("a<one>x<two>y</one>z</two>tail</one>b", ["one", "two"])).toBe("ab");
+    expect(removeNestedBlocks(" a<one/>b ", ["one"])).toBe(" ab ");
+});