From 901f9e17f42a5ad9764dea30adf009c389449966 Mon Sep 17 00:00:00 2001
From: David Antoon <david@frontegg.com>
Date: Mon, 2 Nov 2026 08:39:10 +0200
Subject: [PATCH 1/6] feat(storage): a local SQLite store several processes can
 share

- SqliteStorageAdapter: conditional set, delete, incr, deleteIfEquals and
  expireIfEquals each run in one BEGIN IMMEDIATE transaction, so they are
  atomic across processes; expire and expireIfEquals validate the TTL and
  treat an expired key as missing, like the memory and Redis adapters.
  DistributedSemaphore now works on SQLite.
- One connection per database file per process, shared by every store on
  the file, with a queue that runs the adapter's operations in order and
  waits for another process's lock on a timer instead of blocking the
  event loop.
- createStorage({ type: 'sqlite', sqlite: { path } }) loads
  @frontmcp/storage-sqlite on demand; an invalid sqlite block throws
  StorageConfigError whatever the fallback.
- SDK: sqliteStorageProvider() and SqliteStorageToken give providers and
  tools a SQLite-backed storage, disconnected at shutdown.
- New e2e app demo-e2e-local-runtime: ten processes contend on one file.
---
 .../e2e/dts-consumer.e2e.spec.ts              |   5 +
 .../fixture/sqlite-storage-must-compile.ts    |  43 ++++
 .../fixture/tsconfig.json                     |   1 +
 .../e2e/helpers/workers.ts                    |  83 +++++++
 .../e2e/sqlite-contention.e2e.spec.ts         |  78 ++++++
 .../e2e/sqlite-storage-provider.e2e.spec.ts   |  43 ++++
 .../fixture/container-worker.ts               |  29 +++
 .../fixture/lock-holder.ts                    |  22 ++
 .../fixture/storage-worker.ts                 |  72 ++++++
 .../fixture/worker-protocol.ts                |  50 ++++
 .../demo-e2e-local-runtime/jest.e2e.config.ts |  30 +++
 apps/e2e/demo-e2e-local-runtime/project.json  |  32 +++
 .../demo-e2e-local-runtime/tsconfig.app.json  |  10 +
 .../demo-e2e-local-runtime/tsconfig.e2e.json  |   8 +
 apps/e2e/demo-e2e-local-runtime/tsconfig.json |  15 ++
 libs/guard/src/concurrency/README.md          |   2 +-
 libs/guard/src/errors/errors.ts               |   2 +-
 libs/sdk/src/index.ts                         |   2 +
 .../__tests__/sqlite-storage.provider.spec.ts |  80 ++++++
 .../src/storage/sqlite-storage.provider.ts    |  31 +++
 .../create-tool/references/throttling.md      |   2 +-
 .../references/configure-throttle.md          |  16 +-
 libs/skills/catalog/frontmcp-setup/SKILL.md   |   3 +-
 .../setup-sqlite/basic-sqlite-setup.md        |   3 +-
 .../setup-sqlite/encrypted-sqlite-storage.md  |   1 +
 .../setup-sqlite/multi-process-storage.md     |  81 ++++++
 .../setup-sqlite/unix-socket-daemon.md        |   1 +
 .../frontmcp-setup/references/setup-sqlite.md | 103 ++++++--
 libs/skills/catalog/skills-manifest.json      |  14 +-
 libs/storage-sqlite/jest.config.ts            |   1 +
 .../src/__tests__/sqlite-connection.spec.ts   | 235 ++++++++++++++++++
 .../src/__tests__/sqlite-semaphore.spec.ts    |  67 +++++
 .../__tests__/sqlite-storage.adapter.spec.ts  | 139 +++++++++++
 libs/storage-sqlite/src/index.ts              |   3 +-
 libs/storage-sqlite/src/open-database.ts      |   3 +-
 libs/storage-sqlite/src/sqlite-connection.ts  | 124 +++++++++
 libs/storage-sqlite/src/sqlite-event.store.ts |  14 +-
 libs/storage-sqlite/src/sqlite-kv.store.ts    |  28 ++-
 .../src/sqlite-storage.adapter.ts             |  93 ++++---
 libs/storage-sqlite/src/sqlite-task.store.ts  |  10 +-
 libs/utils/jest.config.ts                     |   6 +
 libs/utils/src/index.ts                       |   1 +
 .../src/storage/__tests__/factory.spec.ts     |  85 +++++++
 libs/utils/src/storage/adapters/base.ts       |   4 +-
 libs/utils/src/storage/factory.ts             |  55 +++-
 libs/utils/src/storage/index.ts               |   1 +
 libs/utils/src/storage/types.ts               |  25 +-
 47 files changed, 1667 insertions(+), 89 deletions(-)
 create mode 100644 apps/e2e/demo-e2e-dts-consumer/fixture/sqlite-storage-must-compile.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/e2e/sqlite-contention.e2e.spec.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/e2e/sqlite-storage-provider.e2e.spec.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/fixture/container-worker.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/fixture/lock-holder.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/fixture/storage-worker.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/fixture/worker-protocol.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/jest.e2e.config.ts
 create mode 100644 apps/e2e/demo-e2e-local-runtime/project.json
 create mode 100644 apps/e2e/demo-e2e-local-runtime/tsconfig.app.json
 create mode 100644 apps/e2e/demo-e2e-local-runtime/tsconfig.e2e.json
 create mode 100644 apps/e2e/demo-e2e-local-runtime/tsconfig.json
 create mode 100644 libs/sdk/src/storage/__tests__/sqlite-storage.provider.spec.ts
 create mode 100644 libs/sdk/src/storage/sqlite-storage.provider.ts
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/multi-process-storage.md
 create mode 100644 libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
 create mode 100644 libs/storage-sqlite/src/__tests__/sqlite-semaphore.spec.ts
 create mode 100644 libs/storage-sqlite/src/sqlite-connection.ts

diff --git a/apps/e2e/demo-e2e-dts-consumer/e2e/dts-consumer.e2e.spec.ts b/apps/e2e/demo-e2e-dts-consumer/e2e/dts-consumer.e2e.spec.ts
index 585e3250e..9b617259b 100644
--- a/apps/e2e/demo-e2e-dts-consumer/e2e/dts-consumer.e2e.spec.ts
+++ b/apps/e2e/demo-e2e-dts-consumer/e2e/dts-consumer.e2e.spec.ts
@@ -26,6 +26,7 @@ function toFixtureDiagnostic(diagnostic: ts.Diagnostic): FixtureDiagnostic {
 
 const fixtureFiles = [
   'provider-lifecycle-must-compile.ts',
+  'sqlite-storage-must-compile.ts',
   'tool-must-fail.ts',
   'prompts-must-compile.ts',
   'hooks-must-compile.ts',
@@ -91,6 +92,10 @@ describe('@frontmcp/sdk declarations in a strict consumer project', () => {
     expect(describeEach(inFixtureFile('provider-lifecycle-must-compile.ts'))).toEqual([]);
   });
 
+  it('types sqliteStorageProvider() and the storage SqliteStorageToken resolves to', () => {
+    expect(describeEach(inFixtureFile('sqlite-storage-must-compile.ts'))).toEqual([]);
+  });
+
   it('accepts the documented @Prompt forms', () => {
     expect(describeEach(inFixtureFile('prompts-must-compile.ts'))).toEqual([]);
   });
diff --git a/apps/e2e/demo-e2e-dts-consumer/fixture/sqlite-storage-must-compile.ts b/apps/e2e/demo-e2e-dts-consumer/fixture/sqlite-storage-must-compile.ts
new file mode 100644
index 000000000..cf5996bb9
--- /dev/null
+++ b/apps/e2e/demo-e2e-dts-consumer/fixture/sqlite-storage-must-compile.ts
@@ -0,0 +1,43 @@
+import 'reflect-metadata';
+
+import {
+  App,
+  createContainer,
+  FrontMcp,
+  sqliteStorageProvider,
+  SqliteStorageToken,
+  type SqliteStorageProviderOptions,
+} from '@frontmcp/sdk';
+
+const options: SqliteStorageProviderOptions = {
+  path: '/var/lib/counter/state.sqlite',
+  walMode: true,
+  busyTimeoutMs: 10_000,
+  prefix: 'counter:',
+};
+
+@App({ name: 'counter' })
+class CounterApp {}
+
+@FrontMcp({
+  info: { name: 'sqlite-storage', version: '1.0.0' },
+  apps: [CounterApp],
+  providers: [sqliteStorageProvider(options)],
+})
+export class SqliteStorageServer {}
+
+// @ts-expect-error the database file's path is required
+sqliteStorageProvider({ walMode: true });
+
+// @ts-expect-error walMode is a boolean
+sqliteStorageProvider({ path: '/var/lib/counter/state.sqlite', walMode: 'yes' });
+
+export async function countVisit(): Promise<number> {
+  const container = await createContainer({ providers: [sqliteStorageProvider(options)] });
+  try {
+    const visits: number = await container.get(SqliteStorageToken).incr('visits');
+    return visits;
+  } finally {
+    await container.dispose();
+  }
+}
diff --git a/apps/e2e/demo-e2e-dts-consumer/fixture/tsconfig.json b/apps/e2e/demo-e2e-dts-consumer/fixture/tsconfig.json
index 200062d44..623d6dfc3 100644
--- a/apps/e2e/demo-e2e-dts-consumer/fixture/tsconfig.json
+++ b/apps/e2e/demo-e2e-dts-consumer/fixture/tsconfig.json
@@ -12,6 +12,7 @@
   },
   "files": [
     "provider-lifecycle-must-compile.ts",
+    "sqlite-storage-must-compile.ts",
     "tool-must-fail.ts",
     "prompts-must-compile.ts",
     "hooks-must-compile.ts",
diff --git a/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts b/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
new file mode 100644
index 000000000..59d896c57
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
@@ -0,0 +1,83 @@
+/**
+ * Start fixture scripts as child processes that follow `fixture/worker-protocol.ts`, and drive them
+ * from a spec: wait for a line a worker prints, send it a line, read the result it reports.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import { join } from 'node:path';
+
+const projectRoot = join(__dirname, '..', '..');
+
+export interface Worker<Result> {
+  readonly child: ChildProcess;
+  /** Resolves when the worker prints `line`; rejects if it exits first. */
+  waitFor(line: string): Promise<void>;
+  send(line: string): void;
+  /** What the worker reported; rejects when it exits with a code other than 0. */
+  readonly result: Promise<Result>;
+}
+
+/** Run `fixture/<script>` with tsx from source, with `env` added to this process's environment. */
+export function spawnWorker<Result>(script: string, env: Record<string, string> = {}): Worker<Result> {
+  const child = spawn(process.execPath, ['--import', 'tsx', join(projectRoot, 'fixture', script)], {
+    cwd: projectRoot,
+    env: { ...process.env, ...env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const lines: string[] = [];
+  const waiters: { line: string; resolve: () => void }[] = [];
+  let pending = '';
+  let stderr = '';
+
+  child.stdin?.on('error', () => undefined);
+  child.stderr?.on('data', (chunk: Buffer) => (stderr += chunk.toString()));
+  child.stdout?.on('data', (chunk: Buffer) => {
+    pending += chunk.toString();
+    const complete = pending.split('\n');
+    pending = complete.pop() ?? '';
+    for (const line of complete) {
+      lines.push(line);
+      for (const waiter of waiters.filter((candidate) => candidate.line === line)) waiter.resolve();
+    }
+  });
+
+  const exited = new Promise<number | null>((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code) => resolve(code));
+  });
+
+  const result = exited.then((code) => {
+    const reported = lines.find((line) => line.startsWith('result '));
+    if (code !== 0 || !reported) {
+      throw new Error(`worker ${script} exited with ${code}${reported ? '' : ' without a result'}:\n${stderr}`);
+    }
+    return JSON.parse(reported.slice('result '.length)) as Result;
+  });
+  result.catch(() => undefined);
+
+  return {
+    child,
+    result,
+    send: (line) => child.stdin?.write(`${line}\n`),
+    waitFor: (line) =>
+      lines.includes(line)
+        ? Promise.resolve()
+        : new Promise<void>((resolve, reject) => {
+            waiters.push({ line, resolve });
+            void exited.then((code) =>
+              reject(new Error(`worker ${script} exited with ${code} before "${line}":\n${stderr}`)),
+            );
+          }),
+  };
+}
+
+/** Wait until every worker is ready, start them all at once, and collect what they report. */
+export async function runTogether<Result>(workers: Worker<Result>[]): Promise<Result[]> {
+  await Promise.all(workers.map((worker) => worker.waitFor('ready')));
+  for (const worker of workers) worker.send('go');
+  return Promise.all(workers.map((worker) => worker.result));
+}
+
+/** Kill the workers still running, so a failed spec does not leave processes behind. */
+export function killAll(workers: Worker<unknown>[]): void {
+  for (const { child } of workers) if (child.exitCode === null) child.kill('SIGKILL');
+}
diff --git a/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-contention.e2e.spec.ts b/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-contention.e2e.spec.ts
new file mode 100644
index 000000000..2b3ed2b2c
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-contention.e2e.spec.ts
@@ -0,0 +1,78 @@
+/**
+ * E2E: ten processes share one SQLite file through `createStorage({ type: 'sqlite' })` while another
+ * process holds the write lock. Every increment is counted once, one process takes the NX lock and the
+ * semaphore slot, no SQLITE_BUSY reaches a caller, and no process's event loop stalls while it waits.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { loadBetterSqlite3 } from '@frontmcp/storage-sqlite';
+
+import type { StorageWorkerResult } from '../fixture/storage-worker';
+import { killAll, runTogether, spawnWorker, type Worker } from './helpers/workers';
+
+const WORKERS = 10;
+const INCREMENTS = 40;
+const HOLD_MS = 1000;
+
+function readCounter(dbPath: string): number {
+  const db = new (loadBetterSqlite3())(dbPath, { readonly: true });
+  try {
+    const row = db.prepare("SELECT value FROM kv WHERE key = 'total'").get() as { value: string } | undefined;
+    return Number(row?.value);
+  } finally {
+    db.close();
+  }
+}
+
+describe.each([
+  ['WAL', true],
+  ['rollback journal', false],
+])('ten processes on one SQLite file (%s)', (_mode, walMode) => {
+  let dir: string;
+  let dbPath: string;
+  let started: Worker<unknown>[] = [];
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'local-runtime-sqlite-'));
+    dbPath = path.join(dir, 'shared.sqlite');
+  });
+
+  afterEach(() => {
+    killAll(started);
+    started = [];
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('counts every increment once, gives the lock to one process, and keeps every event loop running', async () => {
+    const workers = Array.from({ length: WORKERS }, (_, index) =>
+      spawnWorker<StorageWorkerResult>('storage-worker.ts', {
+        DB_PATH: dbPath,
+        WAL_MODE: String(walMode),
+        INCREMENTS: String(INCREMENTS),
+        WORKER_ID: `worker-${index}`,
+      }),
+    );
+    started = workers;
+    await Promise.all(workers.map((worker) => worker.waitFor('ready')));
+
+    const holder = spawnWorker('lock-holder.ts', { DB_PATH: dbPath, HOLD_MS: String(HOLD_MS) });
+    started = [...workers, holder];
+    await holder.waitFor('ready');
+    holder.send('go');
+    await holder.waitFor('locked');
+
+    const results = await runTogether(workers);
+    await holder.result;
+
+    const total = WORKERS * INCREMENTS;
+    const values = results.flatMap((result) => result.incrValues).sort((a, b) => a - b);
+    expect(results.flatMap((result) => result.errors)).toEqual([]);
+    expect(values).toEqual(Array.from({ length: total }, (_, index) => index + 1));
+    expect(readCounter(dbPath)).toBe(total);
+    expect(results.filter((result) => result.holdsNxLock)).toHaveLength(1);
+    expect(results.filter((result) => result.acquiredSlot)).toHaveLength(1);
+    expect(Math.max(...results.map((result) => result.maxTimerGapMs))).toBeLessThan(HOLD_MS / 2);
+  });
+});
diff --git a/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-storage-provider.e2e.spec.ts b/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-storage-provider.e2e.spec.ts
new file mode 100644
index 000000000..ef59d4ac9
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-storage-provider.e2e.spec.ts
@@ -0,0 +1,43 @@
+/**
+ * E2E: scripts read the SQLite storage the SDK provides (`sqliteStorageProvider` under
+ * `SqliteStorageToken`) from `createContainer()`, in several processes on one file at once.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import type { ContainerWorkerResult } from '../fixture/container-worker';
+import { killAll, runTogether, spawnWorker, type Worker } from './helpers/workers';
+
+const WORKERS = 3;
+const INCREMENTS = 20;
+
+describe('SqliteStorageToken in several processes', () => {
+  let dir: string;
+  let started: Worker<unknown>[] = [];
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'local-runtime-provider-'));
+  });
+
+  afterEach(() => {
+    killAll(started);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('shares one counter between the processes, and each one exits after dispose()', async () => {
+    const workers = Array.from({ length: WORKERS }, () =>
+      spawnWorker<ContainerWorkerResult>('container-worker.ts', {
+        DB_PATH: path.join(dir, 'app.sqlite'),
+        INCREMENTS: String(INCREMENTS),
+      }),
+    );
+    started = workers;
+
+    const results = await runTogether(workers);
+
+    const values = results.flatMap((result) => result.incrValues).sort((a, b) => a - b);
+    expect(values).toEqual(Array.from({ length: WORKERS * INCREMENTS }, (_, index) => index + 1));
+    expect(workers.map(({ child }) => child.exitCode)).toEqual(Array(WORKERS).fill(0));
+  });
+});
diff --git a/apps/e2e/demo-e2e-local-runtime/fixture/container-worker.ts b/apps/e2e/demo-e2e-local-runtime/fixture/container-worker.ts
new file mode 100644
index 000000000..e3f02f453
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/fixture/container-worker.ts
@@ -0,0 +1,29 @@
+/**
+ * A script that reads the SQLite storage the SDK provides (`sqliteStorageProvider`, `SqliteStorageToken`)
+ * from `createContainer()`: on "go" it increments a counter shared with the other workers, then disposes
+ * the container and reports the values it got.
+ */
+import 'reflect-metadata';
+
+import { createContainer, LogLevel, sqliteStorageProvider, SqliteStorageToken } from '@frontmcp/sdk';
+
+import { readyThenWaitForGo, report, requiredEnv, runWorker } from './worker-protocol';
+
+export interface ContainerWorkerResult {
+  incrValues: number[];
+}
+
+runWorker(async () => {
+  const container = await createContainer({
+    providers: [sqliteStorageProvider({ path: requiredEnv('DB_PATH'), prefix: 'app:' })],
+    logging: { level: LogLevel.Off, enableConsole: false },
+  });
+  const storage = container.get(SqliteStorageToken);
+  await readyThenWaitForGo();
+
+  const incrValues: number[] = [];
+  for (let i = 0; i < Number(requiredEnv('INCREMENTS')); i++) incrValues.push(await storage.incr('total'));
+
+  await container.dispose();
+  report({ incrValues } satisfies ContainerWorkerResult);
+});
diff --git a/apps/e2e/demo-e2e-local-runtime/fixture/lock-holder.ts b/apps/e2e/demo-e2e-local-runtime/fixture/lock-holder.ts
new file mode 100644
index 000000000..d79e48614
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/fixture/lock-holder.ts
@@ -0,0 +1,22 @@
+/**
+ * Another process holding the SQLite write lock: on "go" it opens a write transaction, prints
+ * "locked", keeps the lock for HOLD_MS, then commits.
+ */
+import { loadBetterSqlite3 } from '@frontmcp/storage-sqlite';
+
+import { readyThenWaitForGo, report, requiredEnv, runWorker, signal } from './worker-protocol';
+
+runWorker(async () => {
+  const BetterSqlite3 = loadBetterSqlite3();
+  const db = new BetterSqlite3(requiredEnv('DB_PATH'));
+  db.pragma('busy_timeout = 5000');
+  await readyThenWaitForGo();
+
+  db.exec('BEGIN IMMEDIATE');
+  db.prepare("INSERT OR REPLACE INTO kv (key, value) VALUES ('held-by', 'lock-holder')").run();
+  signal('locked');
+  await new Promise((resolve) => setTimeout(resolve, Number(requiredEnv('HOLD_MS'))));
+  db.exec('COMMIT');
+  db.close();
+  report({ released: true });
+});
diff --git a/apps/e2e/demo-e2e-local-runtime/fixture/storage-worker.ts b/apps/e2e/demo-e2e-local-runtime/fixture/storage-worker.ts
new file mode 100644
index 000000000..aec9f3c77
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/fixture/storage-worker.ts
@@ -0,0 +1,72 @@
+/**
+ * One of many processes sharing a SQLite file through `createStorage({ type: 'sqlite' })`: on "go" it
+ * increments a shared counter, tries to take an NX lock and a one-slot semaphore, and reports what it
+ * got, the errors that reached it, and the longest its event loop went without running a timer.
+ */
+import { DistributedSemaphore } from '@frontmcp/guard';
+import { createStorage } from '@frontmcp/utils';
+
+import { readyThenWaitForGo, report, requiredEnv, runWorker } from './worker-protocol';
+
+export interface StorageWorkerResult {
+  incrValues: number[];
+  errors: string[];
+  holdsNxLock: boolean;
+  acquiredSlot: boolean;
+  maxTimerGapMs: number;
+}
+
+const TIMER_INTERVAL_MS = 5;
+
+function watchTimerGaps(): { stop(): number } {
+  let last = performance.now();
+  let maxGap = 0;
+  const tick = () => {
+    const now = performance.now();
+    maxGap = Math.max(maxGap, now - last);
+    last = now;
+  };
+  const timer = setInterval(tick, TIMER_INTERVAL_MS);
+  return {
+    stop() {
+      clearInterval(timer);
+      tick();
+      return Math.round(maxGap);
+    },
+  };
+}
+
+function describeError(error: unknown): string {
+  const code = (error as { code?: unknown } | null)?.code;
+  return `${typeof code === 'string' ? `${code}: ` : ''}${error instanceof Error ? error.message : String(error)}`;
+}
+
+runWorker(async () => {
+  const workerId = requiredEnv('WORKER_ID');
+  const increments = Number(requiredEnv('INCREMENTS'));
+  const storage = await createStorage({
+    type: 'sqlite',
+    fallback: 'error',
+    sqlite: { path: requiredEnv('DB_PATH'), walMode: requiredEnv('WAL_MODE') === 'true', ttlCleanupIntervalMs: 0 },
+  });
+  const semaphore = new DistributedSemaphore(storage, 60);
+  await readyThenWaitForGo();
+
+  const timerGaps = watchTimerGaps();
+  const errors: string[] = [];
+  const incrValues: number[] = [];
+  let holdsNxLock = false;
+  let acquiredSlot = false;
+  try {
+    for (let i = 0; i < increments; i++) incrValues.push(await storage.incr('total'));
+    await storage.set('nx-lock', workerId, { ifNotExists: true, ttlSeconds: 60 });
+    holdsNxLock = (await storage.get('nx-lock')) === workerId;
+    acquiredSlot = (await semaphore.acquire('job', 1, 0, 'job')) !== null;
+  } catch (error) {
+    errors.push(describeError(error));
+  }
+  const maxTimerGapMs = timerGaps.stop();
+
+  await storage.disconnect();
+  report({ incrValues, errors, holdsNxLock, acquiredSlot, maxTimerGapMs } satisfies StorageWorkerResult);
+});
diff --git a/apps/e2e/demo-e2e-local-runtime/fixture/worker-protocol.ts b/apps/e2e/demo-e2e-local-runtime/fixture/worker-protocol.ts
new file mode 100644
index 000000000..8805141d4
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/fixture/worker-protocol.ts
@@ -0,0 +1,50 @@
+/**
+ * The worker side of `e2e/helpers/workers.ts`: a worker prints lines on stdout and reads its
+ * instructions from stdin, so a spec can start many workers at once and wait for each one.
+ */
+
+/** Print a line the spec waits for with `worker.waitFor(line)`. */
+export function signal(line: string): void {
+  process.stdout.write(`${line}\n`);
+}
+
+/** Resolve once the spec sends `line` with `worker.send(line)`; stdin keeps the worker alive only meanwhile. */
+export function waitForLine(line: string): Promise<void> {
+  return new Promise((resolve) => {
+    let buffered = '';
+    const onData = (chunk: Buffer) => {
+      buffered += chunk.toString();
+      if (!buffered.split('\n').includes(line)) return;
+      process.stdin.off('data', onData);
+      process.stdin.unref();
+      resolve();
+    };
+    process.stdin.ref();
+    process.stdin.on('data', onData);
+  });
+}
+
+/** Print `ready`, then wait for the spec's `go`, so every worker starts at the same moment. */
+export async function readyThenWaitForGo(): Promise<void> {
+  signal('ready');
+  await waitForLine('go');
+}
+
+/** Print the result the spec reads from `worker.result`. */
+export function report(result: unknown): void {
+  signal(`result ${JSON.stringify(result)}`);
+}
+
+/** Run `main`, and exit with code 1 after printing the error when it fails. */
+export function runWorker(main: () => Promise<void>): void {
+  main().catch((error: unknown) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}
+
+export function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`worker: ${name} is not set`);
+  return value;
+}
diff --git a/apps/e2e/demo-e2e-local-runtime/jest.e2e.config.ts b/apps/e2e/demo-e2e-local-runtime/jest.e2e.config.ts
new file mode 100644
index 000000000..155748660
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/jest.e2e.config.ts
@@ -0,0 +1,30 @@
+import { createRequire } from 'module';
+
+import type { Config } from '@jest/types';
+
+const require = createRequire(import.meta.url);
+const e2eCoveragePreset: Config.InitialOptions = require('../../../jest.e2e.coverage.preset.js');
+
+const config: Config.InitialOptions = {
+  displayName: 'demo-e2e-local-runtime',
+  preset: '../../../jest.preset.js',
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/e2e/**/*.e2e.spec.ts'],
+  testTimeout: 120000,
+  maxWorkers: 1,
+  transform: {
+    '^.+\\.[tj]s$': [
+      '@swc/jest',
+      {
+        jsc: {
+          parser: { syntax: 'typescript' },
+          target: 'es2022',
+        },
+      },
+    ],
+  },
+  ...e2eCoveragePreset,
+  coverageDirectory: '../../../coverage/e2e/demo-e2e-local-runtime',
+};
+
+export default config;
diff --git a/apps/e2e/demo-e2e-local-runtime/project.json b/apps/e2e/demo-e2e-local-runtime/project.json
new file mode 100644
index 000000000..a6eff6bfc
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/project.json
@@ -0,0 +1,32 @@
+{
+  "name": "demo-e2e-local-runtime",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/e2e/demo-e2e-local-runtime/fixture",
+  "projectType": "application",
+  "tags": ["scope:demo", "type:e2e", "feature:local-runtime"],
+  "targets": {
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/apps/e2e/demo-e2e-local-runtime"],
+      "options": {
+        "jestConfig": "apps/e2e/demo-e2e-local-runtime/jest.e2e.config.ts",
+        "runInBand": true
+      }
+    },
+    "test:e2e": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/apps/e2e/demo-e2e-local-runtime-e2e"],
+      "options": {
+        "jestConfig": "apps/e2e/demo-e2e-local-runtime/jest.e2e.config.ts",
+        "runInBand": true
+      }
+    },
+    "typecheck-e2e": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsc --noEmit -p tsconfig.e2e.json",
+        "cwd": "apps/e2e/demo-e2e-local-runtime"
+      }
+    }
+  }
+}
diff --git a/apps/e2e/demo-e2e-local-runtime/tsconfig.app.json b/apps/e2e/demo-e2e-local-runtime/tsconfig.app.json
new file mode 100644
index 000000000..f3e752ab4
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/tsconfig.app.json
@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"]
+  },
+  "include": ["fixture/**/*.ts"]
+}
diff --git a/apps/e2e/demo-e2e-local-runtime/tsconfig.e2e.json b/apps/e2e/demo-e2e-local-runtime/tsconfig.e2e.json
new file mode 100644
index 000000000..c294a4845
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/tsconfig.e2e.json
@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["e2e/**/*.ts"]
+}
diff --git a/apps/e2e/demo-e2e-local-runtime/tsconfig.json b/apps/e2e/demo-e2e-local-runtime/tsconfig.json
new file mode 100644
index 000000000..f2fd67cbf
--- /dev/null
+++ b/apps/e2e/demo-e2e-local-runtime/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    }
+  ],
+  "extends": "../../../tsconfig.base.json"
+}
diff --git a/libs/guard/src/concurrency/README.md b/libs/guard/src/concurrency/README.md
index 29c9de883..dd31d5ebd 100644
--- a/libs/guard/src/concurrency/README.md
+++ b/libs/guard/src/concurrency/README.md
@@ -51,4 +51,4 @@ await semaphore.forceReset('my-tool:global');
 
 ## Storage Requirements
 
-The semaphore calls `mget`, `set` (with TTL and `ifNotExists`), `get`, `deleteIfEquals`, `expireIfEquals`, `keys`, `mdelete`, and optionally `publish`/`subscribe` on the storage adapter. `deleteIfEquals` and `expireIfEquals` must be atomic (memory, Redis, Upstash and Vercel KV); with an adapter that lacks them, `acquire()` throws `GuardStorageUnsupportedError` before it claims a slot.
+The semaphore calls `mget`, `set` (with TTL and `ifNotExists`), `get`, `deleteIfEquals`, `expireIfEquals`, `keys`, `mdelete`, and optionally `publish`/`subscribe` on the storage adapter. `deleteIfEquals` and `expireIfEquals` must be atomic (memory, Redis, Upstash, Vercel KV and SQLite); with an adapter that lacks them, `acquire()` throws `GuardStorageUnsupportedError` before it claims a slot.
diff --git a/libs/guard/src/errors/errors.ts b/libs/guard/src/errors/errors.ts
index 6cf5d2789..b9dae6ae2 100644
--- a/libs/guard/src/errors/errors.ts
+++ b/libs/guard/src/errors/errors.ts
@@ -145,7 +145,7 @@ export class GuardStorageUnsupportedError extends GuardError {
     const reason = cause instanceof Error ? cause.message : 'it has no atomic compare-and-delete';
     super(
       'Concurrency limits need storage with an atomic compare-and-delete and compare-and-expire ' +
-        `(memory, Redis, Upstash or Vercel KV): ${reason}`,
+        `(memory, Redis, Upstash, Vercel KV or SQLite): ${reason}`,
       'GUARD_STORAGE_UNSUPPORTED',
       500,
     );
diff --git a/libs/sdk/src/index.ts b/libs/sdk/src/index.ts
index c06661208..8087d0043 100644
--- a/libs/sdk/src/index.ts
+++ b/libs/sdk/src/index.ts
@@ -150,6 +150,8 @@ export { ToolInstance } from './tool/tool.instance';
 export { default as ProviderRegistry } from './provider/provider.registry';
 export { createContainer } from './provider/create-container';
 export type { CreateContainerOptions, FrontMcpContainer } from './provider/create-container';
+export { sqliteStorageProvider, SqliteStorageToken } from './storage/sqlite-storage.provider';
+export type { SqliteStorageProviderOptions } from './storage/sqlite-storage.provider';
 
 // Job exports - saved, discoverable, triggerable executions
 export { JobRegistry, JobInstance, JobPermissionGuard, JobExecutionManager, JobEmitter } from './job';
diff --git a/libs/sdk/src/storage/__tests__/sqlite-storage.provider.spec.ts b/libs/sdk/src/storage/__tests__/sqlite-storage.provider.spec.ts
new file mode 100644
index 000000000..f236f26f3
--- /dev/null
+++ b/libs/sdk/src/storage/__tests__/sqlite-storage.provider.spec.ts
@@ -0,0 +1,80 @@
+import 'reflect-metadata';
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import type { Token } from '@frontmcp/di';
+import type { RootStorage } from '@frontmcp/utils';
+
+import { LogLevel } from '../../common';
+import { createContainer } from '../../provider/create-container';
+import { sqliteStorageProvider, SqliteStorageToken } from '../sqlite-storage.provider';
+
+const quiet = { level: LogLevel.Off, enableConsole: false };
+
+describe('sqliteStorageProvider', () => {
+  let dir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sdk-sqlite-storage-'));
+    dbPath = path.join(dir, 'app.sqlite');
+  });
+
+  afterEach(() => {
+    jest.dontMock('@frontmcp/storage-sqlite');
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('provides a SQLite storage under SqliteStorageToken, disconnected at shutdown', async () => {
+    const container = await createContainer({ providers: [sqliteStorageProvider({ path: dbPath })], logging: quiet });
+    const storage = container.get(SqliteStorageToken);
+
+    expect(await storage.incr('visits')).toBe(1);
+    await storage.set('lease', 'mine', { ttlSeconds: 30, ifNotExists: true });
+    expect(await storage.deleteIfEquals('lease', 'mine')).toBe(true);
+
+    await container.dispose();
+    expect(await storage.ping()).toBe(false);
+  });
+
+  it('keeps what it stored for the next process that opens the file', async () => {
+    const first = await createContainer({ providers: [sqliteStorageProvider({ path: dbPath })], logging: quiet });
+    await first.get(SqliteStorageToken).set('kept', 'yes');
+    await first.dispose();
+
+    const second = await createContainer({ providers: [sqliteStorageProvider({ path: dbPath })], logging: quiet });
+    expect(await second.get(SqliteStorageToken).get('kept')).toBe('yes');
+    await second.dispose();
+  });
+
+  it('registers under a token of its own, with a key prefix', async () => {
+    const AuditStorage = Symbol('AuditStorage') as Token<RootStorage>;
+    const container = await createContainer({
+      providers: [sqliteStorageProvider({ path: dbPath, prefix: 'audit:', provide: AuditStorage })],
+      logging: quiet,
+    });
+    const audit = container.get(AuditStorage);
+
+    await audit.set('entry', 'v');
+    expect(await audit.root.get('audit:entry')).toBe('v');
+    expect(container.tryGet(SqliteStorageToken)).toBeUndefined();
+    await container.dispose();
+  });
+
+  it('fails the boot on invalid options', async () => {
+    await expect(createContainer({ providers: [sqliteStorageProvider({ path: '' })], logging: quiet })).rejects.toThrow(
+      /sqlite\.path/,
+    );
+  });
+
+  it('fails the boot instead of falling back to memory when the package is missing', async () => {
+    jest.doMock('@frontmcp/storage-sqlite', () => {
+      throw Object.assign(new Error("Cannot find module '@frontmcp/storage-sqlite'"), { code: 'MODULE_NOT_FOUND' });
+    });
+    await expect(
+      createContainer({ providers: [sqliteStorageProvider({ path: dbPath })], logging: quiet }),
+    ).rejects.toThrow('npm install @frontmcp/storage-sqlite');
+  });
+});
diff --git a/libs/sdk/src/storage/sqlite-storage.provider.ts b/libs/sdk/src/storage/sqlite-storage.provider.ts
new file mode 100644
index 000000000..f490f8504
--- /dev/null
+++ b/libs/sdk/src/storage/sqlite-storage.provider.ts
@@ -0,0 +1,31 @@
+import type { Token } from '@frontmcp/di';
+import { createStorage, type RootStorage, type SqliteAdapterOptions } from '@frontmcp/utils';
+
+import { ProviderScope, type OnShutdown, type ProviderFactoryType } from '../common';
+
+/** The SQLite storage `sqliteStorageProvider()` registers by default: `this.get(SqliteStorageToken)`. */
+export const SqliteStorageToken: Token<RootStorage> = Symbol.for('frontmcp:storage.sqlite');
+
+export interface SqliteStorageProviderOptions extends SqliteAdapterOptions {
+  /** Prefix for every key this storage reads and writes. */
+  prefix?: string;
+  /** The token to register it under, to hold more than one. @default SqliteStorageToken */
+  provide?: Token<RootStorage>;
+}
+
+/** A GLOBAL provider of a SQLite-backed storage, opened at boot and disconnected at shutdown. */
+export function sqliteStorageProvider(
+  options: SqliteStorageProviderOptions,
+): ProviderFactoryType<RootStorage & OnShutdown, []> {
+  const { prefix, provide = SqliteStorageToken, ...sqlite } = options;
+  return {
+    name: 'storage.sqlite',
+    scope: ProviderScope.GLOBAL,
+    provide,
+    inject: () => [] as const,
+    useFactory: async () => {
+      const storage = await createStorage({ type: 'sqlite', sqlite, prefix, fallback: 'error' });
+      return Object.assign(storage, { onShutdown: () => storage.disconnect() });
+    },
+  };
+}
diff --git a/libs/skills/catalog/create-tool/references/throttling.md b/libs/skills/catalog/create-tool/references/throttling.md
index 38a29f8f6..449edfffd 100644
--- a/libs/skills/catalog/create-tool/references/throttling.md
+++ b/libs/skills/catalog/create-tool/references/throttling.md
@@ -41,7 +41,7 @@ Cap simultaneous in-flight executions.
 - **Scope**: server-wide by default. Concurrency caps the resource — there's no point in per-session concurrency for shared resources like CPU / GPU / DB connection pools.
 - **Behavior on overflow**: with the default `queueTimeoutMs: 0`, the call is refused at once with `ConcurrencyLimitError` (code `CONCURRENCY_LIMIT`, HTTP 429). Set `queueTimeoutMs` to let it wait that long for a slot; it then fails with `QueueTimeoutError`.
 - **Slot lifetime**: a call holds its slot until `execute()` returns, however long that takes. The slot is stored with a time to live (300 seconds) that the server renews while the call runs, so the TTL only frees the slot of a server that died without releasing it.
-- **Storage**: shared limits (`throttle.storage`) need a backend with an atomic compare-and-delete: memory, Redis, Upstash or Vercel KV. With another backend, global or default concurrency refuses to start, and a tool's own `concurrency` fails its first call, with `GUARD_STORAGE_UNSUPPORTED`.
+- **Storage**: shared limits (`throttle.storage`) need a backend with an atomic compare-and-delete: memory, Redis, Upstash, Vercel KV or SQLite (`{ type: 'sqlite', sqlite: { path } }`, shared by the processes on one machine). With another backend, global or default concurrency refuses to start, and a tool's own `concurrency` fails its first call, with `GUARD_STORAGE_UNSUPPORTED`.
 - **Use for**: tools that hold a real bottleneck — image / PDF rendering, ML inference, DB write transactions.
 
 ## `timeout`
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-throttle.md b/libs/skills/catalog/frontmcp-config/references/configure-throttle.md
index 6b944face..a26ab85c0 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-throttle.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-throttle.md
@@ -247,7 +247,7 @@ throttle: {
 }
 ```
 
-`storage` is a `StorageConfig` from `@frontmcp/utils` -- `type` picks the backend, and its options go under the matching key (`redis: { config }`, `redis: { url }` or `redis: { config: { url } }`, `vercelKv: { url, token }`, `upstash: { url, token }`). Beside a URL, `config` fields only fill in what the URL leaves out (port, password, db, tls); a contradicting field fails at startup. It is NOT the top-level `redis` shape: `{ provider: 'redis', host, port }` has no `type`, so it is auto-detected from `REDIS_URL` / `REDIS_HOST` and otherwise runs in memory.
+`storage` is a `StorageConfig` from `@frontmcp/utils` -- `type` picks the backend, and its options go under the matching key (`redis: { config }`, `redis: { url }` or `redis: { config: { url } }`, `vercelKv: { url, token }`, `upstash: { url, token }`, `sqlite: { path }`). Beside a URL, `config` fields only fill in what the URL leaves out (port, password, db, tls); a contradicting field fails at startup. It is NOT the top-level `redis` shape: `{ provider: 'redis', host, port }` has no `type`, so it is auto-detected from `REDIS_URL` / `REDIS_HOST` and otherwise runs in memory.
 
 **Rate limits fail closed.** If the store is unreachable at startup, the server does not start: startup rejects with `GuardStorageUnavailableError` (`throttle.storage (redis) is unavailable: ...`), the default in production. If the store goes away while the server is running, a limited call is refused with the same error rather than `Internal FrontMCP error` (HTTP 503 from the `global` check; an `isError` result with `_meta.code: 'GUARD_STORAGE_UNAVAILABLE'` from a per-tool limit inside `tools/call`). To use per-instance counters instead (at startup and during a mid-run outage, going back to the store once it answers), opt in:
 
@@ -261,6 +261,20 @@ storage: {
 
 The top-level `redis` and `transport.persistence` behave differently: they fall back to in-memory storage with an error log.
 
+### Several processes on one machine
+
+When the server runs as many local processes (one per agent or terminal, say) with no Redis, share their limits through a SQLite file. Install `@frontmcp/storage-sqlite`; every process that names the same file shares the counters and concurrency slots:
+
+```typescript
+throttle: {
+  enabled: true,
+  storage: { type: 'sqlite', sqlite: { path: '/var/lib/my-server/guard.sqlite' } },
+  defaultConcurrency: { maxConcurrent: 2 },
+}
+```
+
+A missing `sqlite.path` or another invalid `sqlite` option fails at startup, even with `fallback: 'memory'`: `GuardStorageUnavailableError` names the option (`Invalid sqlite configuration: sqlite.path: is required ...`). See `setup-sqlite` for journal modes and busy timeouts.
+
 Keys are `<keyPrefix><entity>:<partition>:<kind>:...` (`mcp:guard:export_tickets:global:rl:...`); a trailing `:` on `keyPrefix` is dropped. Before 1.8.6 the default prefix wrote `mcp:guard::...`, so counters briefly split between versions during a rolling deploy.
 
 ## Verification
diff --git a/libs/skills/catalog/frontmcp-setup/SKILL.md b/libs/skills/catalog/frontmcp-setup/SKILL.md
index 3db8ee33e..89dd709ad 100644
--- a/libs/skills/catalog/frontmcp-setup/SKILL.md
+++ b/libs/skills/catalog/frontmcp-setup/SKILL.md
@@ -58,7 +58,7 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 | Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy                         |
 | Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules                                    |
 | Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for distributed subscriptions (single-server uses in-memory)  |
-| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                                        |
+| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, several processes on one file, app storage, encryption                               |
 | Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers                                  |
 | Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands                               |
 | Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands (search, list, install, read, export, publish), bundles, categories, bulk install |
@@ -200,6 +200,7 @@ Each reference has matching examples under [`examples/<reference>/`](./examples/
 | [`basic-sqlite-setup`](./examples/setup-sqlite/basic-sqlite-setup.md)             | Basic        | Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled.          |
 | [`encrypted-sqlite-storage`](./examples/setup-sqlite/encrypted-sqlite-storage.md) | Intermediate | Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite.                |
 | [`unix-socket-daemon`](./examples/setup-sqlite/unix-socket-daemon.md)             | Advanced     | Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage. |
+| [`multi-process-storage`](./examples/setup-sqlite/multi-process-storage.md)       | Intermediate | Share counters and a lock between several local processes through one SQLite file.                |
 
 ## Accessing This Skill
 
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/basic-sqlite-setup.md b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/basic-sqlite-setup.md
index f6fdd37bb..731c3daea 100644
--- a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/basic-sqlite-setup.md
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/basic-sqlite-setup.md
@@ -29,6 +29,7 @@ node -e "require('better-sqlite3')"
 ```typescript
 // src/main.ts
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
 
 @FrontMcp({
@@ -60,7 +61,7 @@ ls -la ~/.frontmcp/data/sessions.sqlite-shm
 
 # Inspect the database after at least one session
 sqlite3 ~/.frontmcp/data/sessions.sqlite ".tables"
-sqlite3 ~/.frontmcp/data/sessions.sqlite "SELECT key FROM kv_store LIMIT 5;"
+sqlite3 ~/.frontmcp/data/sessions.sqlite "SELECT key FROM kv LIMIT 5;"
 ```
 
 ## What This Demonstrates
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/encrypted-sqlite-storage.md b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/encrypted-sqlite-storage.md
index 03fcb8268..22b72a7df 100644
--- a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/encrypted-sqlite-storage.md
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/encrypted-sqlite-storage.md
@@ -20,6 +20,7 @@ Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLit
 ```typescript
 // src/main.ts
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
 
 @FrontMcp({
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/multi-process-storage.md b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/multi-process-storage.md
new file mode 100644
index 000000000..0db090253
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/multi-process-storage.md
@@ -0,0 +1,81 @@
+---
+name: multi-process-storage
+reference: setup-sqlite
+level: intermediate
+description: 'Share counters and a lock between several local processes through one SQLite file.'
+tags: [setup, sqlite, storage, multi-process, lock, local]
+features:
+  - '`sqliteStorageProvider()` registers a SQLite-backed storage that tools read with `this.get(SqliteStorageToken)`'
+  - '`incr` stays exact and an `ifNotExists` lock has one holder across processes on the same file'
+  - "`createStorage({ type: 'sqlite' })` gives scripts and `throttle.storage` the same file"
+  - "Waiting for another process's lock does not block the event loop"
+---
+
+# Several Processes Sharing One SQLite File
+
+Share counters and a lock between several local processes through one SQLite file.
+
+## Code
+
+```bash
+yarn add @frontmcp/storage-sqlite better-sqlite3
+```
+
+```typescript
+// src/tools/claim-reindex.tool.ts
+import { SqliteStorageToken, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'claim_reindex',
+  description: 'Run the reindex in this process unless another process already holds it',
+  inputSchema: { runId: z.string() },
+})
+export class ClaimReindexTool extends ToolContext {
+  async execute({ runId }: { runId: string }) {
+    const storage = this.get(SqliteStorageToken);
+    await storage.set('lock:reindex', runId, { ifNotExists: true, ttlSeconds: 300 });
+    const holder = await storage.get('lock:reindex');
+    const runs = await storage.incr('reindex:claims');
+    return { claimed: holder === runId, claims: runs };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+
+import { App, FrontMcp, sqliteStorageProvider } from '@frontmcp/sdk';
+
+import { ClaimReindexTool } from './tools/claim-reindex.tool';
+
+@App({ name: 'indexer', tools: [ClaimReindexTool] })
+class IndexerApp {}
+
+@FrontMcp({
+  info: { name: 'indexer', version: '0.1.0' },
+  apps: [IndexerApp],
+  providers: [sqliteStorageProvider({ path: '/var/lib/indexer/state.sqlite', prefix: 'indexer:' })],
+})
+export default class Server {}
+```
+
+```typescript
+// scripts/report.ts: the same file from a script, without a server
+import { createStorage } from '@frontmcp/utils';
+
+const storage = await createStorage({ type: 'sqlite', sqlite: { path: '/var/lib/indexer/state.sqlite' } });
+console.log('claims so far:', await storage.get('indexer:reindex:claims'));
+await storage.disconnect();
+```
+
+## What This Demonstrates
+
+- `sqliteStorageProvider()` registers a SQLite-backed storage that tools read with `this.get(SqliteStorageToken)`
+- `incr` stays exact and an `ifNotExists` lock has one holder across processes on the same file
+- `createStorage({ type: 'sqlite' })` gives scripts and `throttle.storage` the same file
+- Waiting for another process's lock does not block the event loop
+
+## Related
+
+- See `setup-sqlite` for journal modes, busy timeouts and the SDK's own SQLite stores
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/unix-socket-daemon.md b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/unix-socket-daemon.md
index f5cd281c9..68e7546d8 100644
--- a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/unix-socket-daemon.md
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/unix-socket-daemon.md
@@ -20,6 +20,7 @@ Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for pe
 ```typescript
 // src/main.ts
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
 
 @FrontMcp({
diff --git a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
index 85f7bd572..01a46e874 100644
--- a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
+++ b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
@@ -1,6 +1,6 @@
 ---
 name: setup-sqlite
-description: Configure SQLite with WAL mode and optional encryption for local single-instance deployments
+description: Configure SQLite for local deployments, shared by the processes on one machine, with WAL mode and optional encryption
 ---
 
 # Configure SQLite for Local and Single-Instance Deployments
@@ -9,7 +9,8 @@ description: Configure SQLite with WAL mode and optional encryption for local si
 
 ### Must Use
 
-- Your FrontMCP server runs as a single instance with local persistent storage (CLI tools, unix-socket daemons)
+- Your FrontMCP server runs on one machine with local persistent storage (CLI tools, unix-socket daemons)
+- Several processes on one machine (a server per agent or terminal) share state, counters or locks
 - You need session or key-value storage for local development without running external services
 - Your deployment target is a single-process Node.js server on a machine with a local filesystem
 
@@ -22,10 +23,10 @@ description: Configure SQLite with WAL mode and optional encryption for local si
 ### Skip When
 
 - Deploying to serverless (Vercel, Lambda, Cloudflare) where there is no persistent local filesystem -- use `setup-redis` instead
-- Running multiple server instances behind a load balancer -- use `setup-redis` instead
+- Running server instances on more than one machine (behind a load balancer) -- use `setup-redis` instead
 - You need pub/sub for resource subscriptions or real-time event distribution -- use `setup-redis` instead
 
-> **Decision:** Use SQLite for single-instance local storage; switch to `setup-redis` for multi-instance or serverless deployments.
+> **Decision:** Use SQLite for storage on one machine, including several processes sharing a file; switch to `setup-redis` for several machines or serverless deployments.
 
 ## Step 1 -- Install the Native Dependency
 
@@ -197,7 +198,7 @@ sqlite: {
 },
 ```
 
-## Step 3 -- WAL Mode Configuration
+## Step 3 -- Journal Mode, Busy Timeout and Several Processes
 
 WAL (Write-Ahead Logging) mode is enabled by default (`walMode: true`) and is strongly recommended. It provides:
 
@@ -224,6 +225,27 @@ sqlite: {
 },
 ```
 
+### Choosing a journal mode
+
+| Mode                                | Readers and the writer                                                                   | Files                                                                     | Use it for                                                                |
+| ----------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| WAL (`walMode: true`, default)      | Readers never wait for the writer, and the writer never waits for readers                | `-wal` and `-shm` beside the database while it is open; back up all three | Almost everything, and any file several processes write to                |
+| Rollback journal (`walMode: false`) | The writer waits for readers to finish before it commits; readers wait during the commit | A `-journal` file only while a write commits                              | Mostly-read files with rare writes, or a filesystem without shared memory |
+
+WAL needs a local filesystem: never put a WAL database on NFS, SMB or another network mount. A file once switched to WAL stays in WAL for every process that opens it, so `walMode: false` on one process does not switch it back.
+
+### Several processes on one file
+
+Any number of processes on one machine can open the same file. SQLite lets one process write at a time; FrontMCP keeps that cheap:
+
+- **One connection per file per process.** The stores a process opens on one file (sessions, tasks, elicitation, events, and your own SQLite storage) share a single connection, so a process never waits on its own lock.
+- **Short, atomic writes.** Each write is one short `BEGIN IMMEDIATE` transaction. A conditional set (`ifNotExists`/`ifExists`), `incr`, `deleteIfEquals` and `expireIfEquals` read and write in that one transaction, so counters stay exact and an NX lock has one holder across processes.
+- **Waiting without blocking.** Operations through `createStorage({ type: 'sqlite' })`, `sqliteStorageProvider()` or `SqliteStorageAdapter` run one at a time per process and wait for another process's lock on a timer, so the event loop keeps running. The built-in session, task, elicitation and event stores still wait synchronously, for at most `busyTimeoutMs`.
+
+### Busy timeout
+
+`busyTimeoutMs` (default `5000`) is how long an operation waits for another process's write lock before it fails with `SQLITE_BUSY`. Writes hold the lock for one short transaction, so the default covers many writer processes. Raise it when processes hold the lock longer (bulk imports, long transactions) or when dozens of processes write at once; lower it for an interactive tool that should fail fast. When several stores in one process open a file with different values, the longest applies.
+
 ## Step 4 -- How the SDK Builds the SQLite Session Store
 
 You do not call any factory yourself. The SDK constructs the SQLite session store internally from the `sqlite` field on the `@FrontMcp` decorator. The framework handles:
@@ -288,7 +310,53 @@ const sqlite: SqliteOptionsInput = {
 export default class Server {}
 ```
 
-## Step 5 -- Environment Variables
+## Step 5 -- SQLite Storage in Your Own Code
+
+The same file can hold your own keys, counters and locks. Install `@frontmcp/storage-sqlite`, then either register a provider and read it in tools:
+
+```typescript
+import { FrontMcp, sqliteStorageProvider, SqliteStorageToken, Tool, ToolContext } from '@frontmcp/sdk';
+
+@Tool({ name: 'count_visit', description: 'Count a visit across every process on this machine', inputSchema: {} })
+class CountVisitTool extends ToolContext {
+  async execute() {
+    const storage = this.get(SqliteStorageToken);
+    return { visits: await storage.incr('visits') };
+  }
+}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '0.1.0' },
+  apps: [
+    /* ... */
+  ],
+  providers: [sqliteStorageProvider({ path: '/var/lib/my-server/app.sqlite', prefix: 'app:' })],
+})
+export default class Server {}
+```
+
+or create the storage yourself:
+
+```typescript
+import { createStorage } from '@frontmcp/utils';
+
+const storage = await createStorage({ type: 'sqlite', sqlite: { path: '/var/lib/my-server/app.sqlite' } });
+await storage.set('lock:reindex', process.pid.toString(), { ifNotExists: true, ttlSeconds: 60 });
+```
+
+| Option (`sqliteStorageProvider` / `createStorage`'s `sqlite`) | Default              | Description                                                       |
+| ------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- |
+| `path`                                                        | (required)           | The database file; its directory is created if missing            |
+| `walMode`                                                     | `true`               | See [Choosing a journal mode](#choosing-a-journal-mode)           |
+| `busyTimeoutMs`                                               | `5000`               | See [Busy timeout](#busy-timeout)                                 |
+| `ttlCleanupIntervalMs`                                        | `60000`              | How often expired keys are purged; `0` turns the sweep off        |
+| `encryption`                                                  | `undefined`          | `{ secret }` encrypts values at rest (AES-256-GCM)                |
+| `prefix` (provider only)                                      | `''`                 | Prefix for every key the storage reads and writes                 |
+| `provide` (provider only)                                     | `SqliteStorageToken` | Register under another token to hold more than one SQLite storage |
+
+The provider opens the file at boot, fails the boot on an invalid option or a missing `@frontmcp/storage-sqlite` (it never falls back to memory), and disconnects at shutdown; it works in `createContainer()` scripts too. `createStorage` throws `StorageConfigError` for an invalid `sqlite` block whatever its `fallback`; with `fallback: 'memory'` (the default outside production) a missing package falls back to memory with a warning, as the other backends do. The same `{ type: 'sqlite', sqlite: { path } }` works for `throttle.storage` and for plugins that take a `StorageConfig`. SQLite storage has no pub/sub.
+
+## Step 6 -- Environment Variables
 
 Add to your `.env` file:
 
@@ -302,7 +370,7 @@ SQLITE_DB_PATH=~/.frontmcp/data/sessions.sqlite
 
 Confirm `.env` is in `.gitignore`. Never commit credentials.
 
-## Step 6 -- Verify the Setup
+## Step 7 -- Verify the Setup
 
 Start the server:
 
@@ -333,7 +401,7 @@ Inspect the database contents (after at least one session is created):
 
 ```bash
 sqlite3 ~/.frontmcp/data/sessions.sqlite ".tables"
-sqlite3 ~/.frontmcp/data/sessions.sqlite "SELECT key FROM kv_store LIMIT 5;"
+sqlite3 ~/.frontmcp/data/sessions.sqlite "SELECT key FROM kv LIMIT 5;"
 ```
 
 ## Migrating from SQLite to Redis
@@ -409,15 +477,15 @@ The change in `src/main.ts`:
 
 ## Troubleshooting
 
-| Problem                                 | Cause                                                           | Solution                                                                                                                   |
-| --------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                     |
-| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall     |
-| `SQLITE_BUSY` errors                    | Multiple processes accessing the same database file             | Enable WAL mode (`walMode: true`), raise `busyTimeoutMs` (default 5000), or ensure only one process writes to the database |
-| `Failed to persist session to SQLite`   | A session write waited longer than `busyTimeoutMs` for the lock | Raise `busyTimeoutMs`, or use Redis for many writer processes                                                              |
-| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                      |
-| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                  |
-| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated  |
+| Problem                                 | Cause                                                           | Solution                                                                                                                  |
+| --------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                    |
+| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall    |
+| `SQLITE_BUSY` errors                    | Another process held the write lock longer than `busyTimeoutMs` | Keep WAL mode on (`walMode: true`), keep transactions short, and raise `busyTimeoutMs` (default 5000)                     |
+| `Failed to persist session to SQLite`   | A session write waited longer than `busyTimeoutMs` for the lock | Raise `busyTimeoutMs`, or use Redis for many writer processes                                                             |
+| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                     |
+| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                 |
+| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated |
 
 ## Examples
 
@@ -426,6 +494,7 @@ The change in `src/main.ts`:
 | [`basic-sqlite-setup`](../examples/setup-sqlite/basic-sqlite-setup.md)             | Basic        | Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled.          |
 | [`encrypted-sqlite-storage`](../examples/setup-sqlite/encrypted-sqlite-storage.md) | Intermediate | Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite.                |
 | [`unix-socket-daemon`](../examples/setup-sqlite/unix-socket-daemon.md)             | Advanced     | Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage. |
+| [`multi-process-storage`](../examples/setup-sqlite/multi-process-storage.md)       | Intermediate | Share counters and a lock between several local processes through one SQLite file.                |
 
 > See all examples in [`examples/setup-sqlite/`](../examples/setup-sqlite/)
 
diff --git a/libs/skills/catalog/skills-manifest.json b/libs/skills/catalog/skills-manifest.json
index 5d7d9cb88..8cf0c9bec 100644
--- a/libs/skills/catalog/skills-manifest.json
+++ b/libs/skills/catalog/skills-manifest.json
@@ -3577,7 +3577,7 @@
         },
         {
           "name": "setup-sqlite",
-          "description": "Configure SQLite with WAL mode and optional encryption for local single-instance deployments",
+          "description": "Configure SQLite for local deployments, shared by the processes on one machine, with WAL mode and optional encryption",
           "examples": [
             {
               "name": "basic-sqlite-setup",
@@ -3614,6 +3614,18 @@
                 "`ttlCleanupIntervalMs: 15000` for more aggressive cleanup on high-throughput daemons",
                 "Absolute path for the database file in system-level storage (`/var/lib/`)"
               ]
+            },
+            {
+              "name": "multi-process-storage",
+              "description": "Share counters and a lock between several local processes through one SQLite file.",
+              "level": "intermediate",
+              "tags": ["setup", "sqlite", "storage", "multi-process", "lock", "local"],
+              "features": [
+                "`sqliteStorageProvider()` registers a SQLite-backed storage that tools read with `this.get(SqliteStorageToken)`",
+                "`incr` stays exact and an `ifNotExists` lock has one holder across processes on the same file",
+                "`createStorage({ type: 'sqlite' })` gives scripts and `throttle.storage` the same file",
+                "Waiting for another process's lock does not block the event loop"
+              ]
             }
           ]
         }
diff --git a/libs/storage-sqlite/jest.config.ts b/libs/storage-sqlite/jest.config.ts
index 7614e2717..8027b581d 100644
--- a/libs/storage-sqlite/jest.config.ts
+++ b/libs/storage-sqlite/jest.config.ts
@@ -29,6 +29,7 @@ module.exports = {
     ...require('../../jest.imports-mapper'),
     '^@frontmcp/utils$': '<rootDir>/../utils/src/index.ts',
     '^@frontmcp/utils/crypto/node$': '<rootDir>/../utils/src/crypto/node.ts',
+    '^@frontmcp/guard$': '<rootDir>/../guard/src/index.ts',
   },
   coverageDirectory: '../../coverage/unit/storage-sqlite',
   collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts', '!src/**/index.ts'],
diff --git a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
new file mode 100644
index 000000000..a7b792c7b
--- /dev/null
+++ b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
@@ -0,0 +1,235 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import type Database from 'better-sqlite3';
+
+import { loadBetterSqlite3 } from '../better-sqlite3-loader';
+import { acquireConnection } from '../sqlite-connection';
+import { SqliteEventStore } from '../sqlite-event.store';
+import { SqliteKvStore } from '../sqlite-kv.store';
+import { SqliteStorageAdapter } from '../sqlite-storage.adapter';
+import { SqliteTaskStore } from '../sqlite-task.store';
+
+/** A second connection to the file, standing in for another process. */
+function openForeignConnection(dbPath: string): Database.Database {
+  const BetterSqlite3 = loadBetterSqlite3();
+  const db = new BetterSqlite3(dbPath);
+  db.pragma('busy_timeout = 0');
+  return db;
+}
+
+function holdWriteLock(db: Database.Database, holdMs: number): Promise<void> {
+  db.exec('BEGIN IMMEDIATE');
+  db.prepare("INSERT OR REPLACE INTO kv (key, value) VALUES ('foreign', 'x')").run();
+  return new Promise((resolve) =>
+    setTimeout(() => {
+      db.exec('COMMIT');
+      resolve();
+    }, holdMs),
+  );
+}
+
+function countTicks(): { stop(): number } {
+  let ticks = 0;
+  const timer = setInterval(() => ticks++, 10);
+  return {
+    stop() {
+      clearInterval(timer);
+      return ticks;
+    },
+  };
+}
+
+describe('shared SQLite connections', () => {
+  let dir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'sqlite-connection-')));
+    dbPath = path.join(dir, 'shared.sqlite');
+  });
+
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  it('gives every store on one file the same connection', async () => {
+    const kv = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    const events = new SqliteEventStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    const tasks = new SqliteTaskStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    try {
+      expect(events.getDatabase()).toBe(kv.getDatabase());
+      expect(tasks.getDatabase()).toBe(kv.getDatabase());
+    } finally {
+      kv.close();
+      events.close();
+      await tasks.destroy();
+    }
+  });
+
+  it('matches a relative path with the absolute path of the same file', () => {
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      const relative = new SqliteKvStore({ path: 'shared.sqlite', ttlCleanupIntervalMs: 0 });
+      const absolute = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+      expect(absolute.getDatabase()).toBe(relative.getDatabase());
+      relative.close();
+      absolute.close();
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+
+  it('closes the connection when the last store on the file closes', () => {
+    const first = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    const second = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    const db = first.getDatabase();
+
+    first.close();
+    first.close();
+    expect(db.open).toBe(true);
+    second.set('k', 'v');
+    expect(second.get('k')).toBe('v');
+
+    second.close();
+    expect(db.open).toBe(false);
+  });
+
+  it('opens a fresh connection after the last one closed', () => {
+    const first = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    first.set('k', 'v');
+    first.close();
+
+    const reopened = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    expect(reopened.get('k')).toBe('v');
+    reopened.close();
+  });
+
+  it('gives every in-memory store a database of its own', () => {
+    const first = new SqliteKvStore({ path: ':memory:', ttlCleanupIntervalMs: 0 });
+    const second = new SqliteKvStore({ path: ':memory:', ttlCleanupIntervalMs: 0 });
+    first.set('k', 'v');
+    expect(second.getDatabase()).not.toBe(first.getDatabase());
+    expect(second.get('k')).toBeNull();
+    first.close();
+    second.close();
+  });
+
+  it('switches the file to WAL when a later store asks for it', () => {
+    const rollback = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0, walMode: false });
+    expect(rollback.getDatabase().pragma('journal_mode', { simple: true })).toBe('delete');
+
+    const wal = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0, walMode: true });
+    expect(wal.getDatabase().pragma('journal_mode', { simple: true })).toBe('wal');
+    rollback.close();
+    wal.close();
+  });
+
+  it('keeps the longest busy timeout the stores on the file asked for', () => {
+    const short = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0, busyTimeoutMs: 100 });
+    const long = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0, busyTimeoutMs: 2000 });
+    const shorter = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0, busyTimeoutMs: 50 });
+    expect(short.getDatabase().pragma('busy_timeout', { simple: true })).toBe(2000);
+    short.close();
+    long.close();
+    shorter.close();
+  });
+
+  describe('queued operations', () => {
+    it('runs operations in the order they were called', async () => {
+      const connection = acquireConnection(dbPath, 'Test');
+      const order: string[] = [];
+      try {
+        await Promise.all([
+          connection.write(() => order.push('first write')),
+          connection.read(() => order.push('read')),
+          connection.write(() => order.push('second write')),
+        ]);
+        expect(order).toEqual(['first write', 'read', 'second write']);
+      } finally {
+        connection.release();
+      }
+    });
+
+    it('rolls a write back when it throws, and runs the next one', async () => {
+      const kv = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+      const connection = kv.getConnection();
+      try {
+        const failed = connection.write(() => {
+          kv.set('half', 'written');
+          throw new Error('boom');
+        });
+        const next = connection.write(() => kv.set('next', 'written'));
+
+        await expect(failed).rejects.toThrow('boom');
+        await next;
+        expect(kv.get('half')).toBeNull();
+        expect(kv.get('next')).toBe('written');
+      } finally {
+        kv.close();
+      }
+    });
+
+    it('does not retry an error other than SQLITE_BUSY', async () => {
+      const connection = acquireConnection(dbPath, 'Test');
+      let calls = 0;
+      try {
+        await expect(
+          connection.write(() => {
+            calls++;
+            throw Object.assign(new Error('constraint failed'), { code: 'SQLITE_CONSTRAINT' });
+          }),
+        ).rejects.toThrow('constraint failed');
+        expect(calls).toBe(1);
+      } finally {
+        connection.release();
+      }
+    });
+  });
+
+  describe('a lock held by another process', () => {
+    it('waits for it without blocking the event loop', async () => {
+      const adapter = new SqliteStorageAdapter({ path: dbPath, ttlCleanupIntervalMs: 0 });
+      await adapter.connect();
+      const foreign = openForeignConnection(dbPath);
+      try {
+        const released = holdWriteLock(foreign, 300);
+        const ticks = countTicks();
+        const startedAt = Date.now();
+
+        expect(await adapter.incr('counter')).toBe(1);
+
+        expect(Date.now() - startedAt).toBeGreaterThanOrEqual(250);
+        expect(ticks.stop()).toBeGreaterThanOrEqual(10);
+        await released;
+        expect(adapter.getKvStore().getDatabase().pragma('busy_timeout', { simple: true })).toBe(5000);
+      } finally {
+        foreign.close();
+        await adapter.disconnect();
+      }
+    });
+
+    it('gives up with SQLITE_BUSY once busyTimeoutMs has passed', async () => {
+      const adapter = new SqliteStorageAdapter({ path: dbPath, ttlCleanupIntervalMs: 0, busyTimeoutMs: 150 });
+      await adapter.connect();
+      const foreign = openForeignConnection(dbPath);
+      try {
+        const released = holdWriteLock(foreign, 600);
+        const ticks = countTicks();
+        const startedAt = Date.now();
+
+        await expect(adapter.set('k', 'v')).rejects.toMatchObject({ code: 'SQLITE_BUSY' });
+
+        expect(Date.now() - startedAt).toBeGreaterThanOrEqual(140);
+        expect(Date.now() - startedAt).toBeLessThan(550);
+        expect(ticks.stop()).toBeGreaterThanOrEqual(5);
+        await released;
+        await adapter.set('k', 'v');
+        expect(await adapter.get('k')).toBe('v');
+      } finally {
+        foreign.close();
+        await adapter.disconnect();
+      }
+    });
+  });
+});
diff --git a/libs/storage-sqlite/src/__tests__/sqlite-semaphore.spec.ts b/libs/storage-sqlite/src/__tests__/sqlite-semaphore.spec.ts
new file mode 100644
index 000000000..ce242c9b1
--- /dev/null
+++ b/libs/storage-sqlite/src/__tests__/sqlite-semaphore.spec.ts
@@ -0,0 +1,67 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { DistributedSemaphore } from '@frontmcp/guard';
+
+import { SqliteStorageAdapter } from '../sqlite-storage.adapter';
+
+describe('DistributedSemaphore on SQLite', () => {
+  let dir: string;
+  let first: SqliteStorageAdapter;
+  let second: SqliteStorageAdapter;
+
+  beforeEach(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sqlite-semaphore-'));
+    const dbPath = path.join(dir, 'guard.sqlite');
+    first = new SqliteStorageAdapter({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    second = new SqliteStorageAdapter({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    await first.connect();
+    await second.connect();
+  });
+
+  afterEach(async () => {
+    await first.disconnect();
+    await second.disconnect();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('accepts the SQLite adapter as storage for concurrency slots', async () => {
+    await expect(new DistributedSemaphore(first).verifyAtomicSlots()).resolves.toBeUndefined();
+  });
+
+  it('holds a slot for one caller at a time, across adapters on the same file', async () => {
+    const semaphoreA = new DistributedSemaphore(first, 60);
+    const semaphoreB = new DistributedSemaphore(second, 60);
+
+    const ticket = await semaphoreA.acquire('job', 1, 0, 'job');
+    expect(ticket).not.toBeNull();
+    expect(await semaphoreB.acquire('job', 1, 0, 'job')).toBeNull();
+    expect(await semaphoreB.getActiveCount('job')).toBe(1);
+
+    await ticket?.release();
+    const next = await semaphoreB.acquire('job', 1, 0, 'job');
+    expect(next).not.toBeNull();
+    await next?.release();
+    expect(await semaphoreA.getActiveCount('job')).toBe(0);
+  });
+
+  it('lets a queued caller take the slot once it is released', async () => {
+    const semaphore = new DistributedSemaphore(first, 60);
+    const held = await semaphore.acquire('job', 1, 0, 'job');
+    setTimeout(() => void held?.release(), 50);
+
+    const queued = await semaphore.acquire('job', 1, 2000, 'job');
+    expect(queued).not.toBeNull();
+    await queued?.release();
+  });
+
+  it('does not let a stale release free a slot another ticket now holds', async () => {
+    const semaphore = new DistributedSemaphore(first, 60);
+    const stale = await semaphore.acquire('job', 1, 0, 'job');
+    await first.set('job:slot:0', 'someone-else');
+
+    await stale?.release();
+    expect(await first.get('job:slot:0')).toBe('someone-else');
+  });
+});
diff --git a/libs/storage-sqlite/src/__tests__/sqlite-storage.adapter.spec.ts b/libs/storage-sqlite/src/__tests__/sqlite-storage.adapter.spec.ts
index dbbec4774..abaff589c 100644
--- a/libs/storage-sqlite/src/__tests__/sqlite-storage.adapter.spec.ts
+++ b/libs/storage-sqlite/src/__tests__/sqlite-storage.adapter.spec.ts
@@ -2,6 +2,11 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 
+import type Database from 'better-sqlite3';
+
+import { StorageOperationError, StorageTTLError } from '@frontmcp/utils';
+
+import { loadBetterSqlite3 } from '../better-sqlite3-loader';
 import { SqliteKvStore } from '../sqlite-kv.store';
 import { SqliteStorageAdapter } from '../sqlite-storage.adapter';
 
@@ -33,6 +38,15 @@ describe('SqliteStorageAdapter', () => {
     cleanup(dbPath);
   });
 
+  /** A TTL that ran out between two sweeps: the row is still there, past its expiry. */
+  function expireNow(key: string): void {
+    adapter
+      .getKvStore()
+      .getDatabase()
+      .prepare('UPDATE kv SET expires_at = ? WHERE key = ?')
+      .run(Date.now() - 1, key);
+  }
+
   describe('keys() LIKE escaping', () => {
     // The adapter escapes LIKE metacharacters as `\%` / `\_`; this only works
     // if SqliteKvStore's LIKE query declares `ESCAPE '\'`. These cases would
@@ -192,6 +206,123 @@ describe('SqliteStorageAdapter', () => {
       expect(await adapter.exists('k')).toBe(false);
       expect(await adapter.ttl('k')).toBeNull();
     });
+
+    it('expire() returns false for a key whose TTL ran out', async () => {
+      await adapter.set('k', 'v', { ttlSeconds: 1 });
+      expireNow('k');
+      expect(await adapter.expire('k', 50)).toBe(false);
+    });
+
+    it('expire() rejects a TTL that is not a positive integer', async () => {
+      await adapter.set('k', 'v');
+      await expect(adapter.expire('k', 0)).rejects.toBeInstanceOf(StorageTTLError);
+      await expect(adapter.expire('k', 1.5)).rejects.toBeInstanceOf(StorageTTLError);
+    });
+
+    it('ifNotExists sets a key whose TTL ran out', async () => {
+      await adapter.set('k', 'old', { ttlSeconds: 1 });
+      expireNow('k');
+      await adapter.set('k', 'new', { ifNotExists: true });
+      expect(await adapter.get('k')).toBe('new');
+    });
+  });
+
+  describe('compare-and-act', () => {
+    it('deleteIfEquals deletes the key only while it holds the value', async () => {
+      await adapter.set('lease', 'mine');
+      expect(await adapter.deleteIfEquals('lease', 'theirs')).toBe(false);
+      expect(await adapter.get('lease')).toBe('mine');
+      expect(await adapter.deleteIfEquals('lease', 'mine')).toBe(true);
+      expect(await adapter.exists('lease')).toBe(false);
+    });
+
+    it('deleteIfEquals returns false for a missing or expired key', async () => {
+      expect(await adapter.deleteIfEquals('missing', 'x')).toBe(false);
+      await adapter.set('lease', 'mine', { ttlSeconds: 1 });
+      expireNow('lease');
+      expect(await adapter.deleteIfEquals('lease', 'mine')).toBe(false);
+    });
+
+    it('expireIfEquals sets the TTL only while the key holds the value', async () => {
+      await adapter.set('lease', 'mine', { ttlSeconds: 10 });
+      expect(await adapter.expireIfEquals('lease', 'theirs', 100)).toBe(false);
+      expect(await adapter.ttl('lease')).toBeLessThanOrEqual(10);
+      expect(await adapter.expireIfEquals('lease', 'mine', 100)).toBe(true);
+      expect(await adapter.ttl('lease')).toBeGreaterThan(10);
+    });
+
+    it('expireIfEquals returns false for a missing or expired key', async () => {
+      expect(await adapter.expireIfEquals('missing', 'x', 10)).toBe(false);
+      await adapter.set('lease', 'mine', { ttlSeconds: 1 });
+      expireNow('lease');
+      expect(await adapter.expireIfEquals('lease', 'mine', 10)).toBe(false);
+    });
+
+    it('expireIfEquals rejects a TTL that is not a positive integer', async () => {
+      await adapter.set('lease', 'mine');
+      await expect(adapter.expireIfEquals('lease', 'mine', -1)).rejects.toBeInstanceOf(StorageTTLError);
+    });
+
+    it('compares against the decrypted value when values are encrypted', async () => {
+      const encryptedPath = tmpDbPath();
+      const encrypted = new SqliteStorageAdapter({
+        path: encryptedPath,
+        ttlCleanupIntervalMs: 0,
+        encryption: { secret: 'a-secret-that-is-long-enough-for-tests' },
+      });
+      await encrypted.connect();
+      try {
+        await encrypted.set('lease', 'mine', { ttlSeconds: 10 });
+        expect(await encrypted.expireIfEquals('lease', 'mine', 100)).toBe(true);
+        expect(await encrypted.deleteIfEquals('lease', 'mine')).toBe(true);
+        await encrypted.set('n', '41');
+        expect(await encrypted.incr('n')).toBe(42);
+      } finally {
+        await encrypted.disconnect();
+        cleanup(encryptedPath);
+      }
+    });
+  });
+
+  describe('atomic across connections', () => {
+    let foreign: Database.Database;
+
+    beforeEach(() => {
+      foreign = new (loadBetterSqlite3())(dbPath);
+      foreign.pragma('busy_timeout = 0');
+    });
+
+    afterEach(() => foreign.close());
+
+    /** What another process sees when it writes the file between this operation's read and its write. */
+    function foreignWriteDuringRead(read: 'get' | 'has'): { outcome?: string } {
+      const seen: { outcome?: string } = {};
+      const kv = adapter.getKvStore();
+      const original = kv[read].bind(kv);
+      jest.spyOn(kv, read).mockImplementationOnce((key: string) => {
+        try {
+          foreign.prepare("INSERT OR REPLACE INTO kv (key, value) VALUES ('foreign', 'x')").run();
+          seen.outcome = 'wrote';
+        } catch (error) {
+          seen.outcome = (error as { code?: string }).code;
+        }
+        return original(key) as never;
+      });
+      return seen;
+    }
+
+    it.each([
+      ['incr', 'get', () => adapter.incr('n')],
+      ['set with ifNotExists', 'has', () => adapter.set('k', 'v', { ifNotExists: true })],
+      ['set with ifExists', 'has', () => adapter.set('k', 'v', { ifExists: true })],
+      ['delete', 'has', () => adapter.delete('k')],
+      ['deleteIfEquals', 'get', () => adapter.deleteIfEquals('k', 'v')],
+      ['expireIfEquals', 'get', () => adapter.expireIfEquals('k', 'v', 10)],
+    ] as const)('%s holds the write lock from its read to its write', async (_name, read, operation) => {
+      const seen = foreignWriteDuringRead(read);
+      await operation();
+      expect(seen.outcome).toBe('SQLITE_BUSY');
+    });
   });
 
   describe('atomic operations', () => {
@@ -213,6 +344,14 @@ describe('SqliteStorageAdapter', () => {
     it('throws when the existing value is not an integer', async () => {
       await adapter.set('counter', 'not-a-number');
       await expect(adapter.incr('counter')).rejects.toThrow(/is not an integer/);
+      await expect(adapter.incr('counter')).rejects.toBeInstanceOf(StorageOperationError);
+    });
+
+    it('starts an expired counter over, without its old TTL', async () => {
+      await adapter.set('counter', '7', { ttlSeconds: 1 });
+      expireNow('counter');
+      expect(await adapter.incr('counter')).toBe(1);
+      expect(await adapter.ttl('counter')).toBe(-1);
     });
 
     it('preserves an existing TTL across incr', async () => {
diff --git a/libs/storage-sqlite/src/index.ts b/libs/storage-sqlite/src/index.ts
index f896f68cb..269079ab1 100644
--- a/libs/storage-sqlite/src/index.ts
+++ b/libs/storage-sqlite/src/index.ts
@@ -7,7 +7,8 @@
 
 export { SqliteKvStore } from './sqlite-kv.store';
 export { SqliteStorageAdapter } from './sqlite-storage.adapter';
-export { openDatabase, withBusyRetry } from './open-database';
+export { openDatabase, withBusyRetry, isBusyError } from './open-database';
+export { acquireConnection, SqliteConnection } from './sqlite-connection';
 export type { OpenDatabaseOptions, BusyRetryOptions } from './open-database';
 export { loadBetterSqlite3 } from './better-sqlite3-loader';
 export { SqliteSessionStore } from './sqlite-session.store';
diff --git a/libs/storage-sqlite/src/open-database.ts b/libs/storage-sqlite/src/open-database.ts
index 0f4f9544d..fbd295f65 100644
--- a/libs/storage-sqlite/src/open-database.ts
+++ b/libs/storage-sqlite/src/open-database.ts
@@ -36,7 +36,7 @@ export interface BusyRetryOptions {
   delayMs?: number;
 }
 
-function isBusyError(err: unknown): boolean {
+export function isBusyError(err: unknown): boolean {
   const code = (err as { code?: unknown } | null)?.code;
   return code === 'SQLITE_BUSY' || code === 'SQLITE_BUSY_RECOVERY' || code === 'SQLITE_BUSY_SNAPSHOT';
 }
@@ -49,6 +49,7 @@ function sleepSync(ms: number): void {
  * Run a synchronous SQLite operation, retrying while it reports `SQLITE_BUSY`.
  * `busy_timeout` covers ordinary lock waits; a few statements (the WAL switch,
  * schema changes racing another process's first open) can still fail fast.
+ * Blocks the event loop between attempts (750 ms at most by default): only for opening a store.
  */
 export function withBusyRetry<T>(operation: () => T, options: BusyRetryOptions = {}): T {
   const attempts = options.attempts ?? 5;
diff --git a/libs/storage-sqlite/src/sqlite-connection.ts b/libs/storage-sqlite/src/sqlite-connection.ts
new file mode 100644
index 000000000..4f8d216b3
--- /dev/null
+++ b/libs/storage-sqlite/src/sqlite-connection.ts
@@ -0,0 +1,124 @@
+import type Database from 'better-sqlite3';
+
+import { pathResolve } from '@frontmcp/utils';
+
+import {
+  DEFAULT_BUSY_TIMEOUT_MS,
+  isBusyError,
+  openDatabase,
+  withBusyRetry,
+  type OpenDatabaseOptions,
+} from './open-database';
+
+const MIN_BACKOFF_MS = 2;
+const MAX_BACKOFF_MS = 50;
+
+/** Paths that open a new, private database each time, so they are never shared. */
+const PRIVATE_PATHS = new Set([':memory:', '']);
+
+const sharedByPath = new Map<string, SharedDatabase>();
+
+class SharedDatabase {
+  private references = 0;
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(
+    readonly db: Database.Database,
+    private busyTimeoutMs: number,
+    private readonly cacheKey?: string,
+  ) {}
+
+  retain(options: OpenDatabaseOptions): void {
+    this.references++;
+    if (options.walMode && this.db.pragma('journal_mode', { simple: true }) !== 'wal') {
+      withBusyRetry(() => this.db.pragma('journal_mode = WAL'));
+    }
+    const busyTimeoutMs = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+    if (busyTimeoutMs > this.busyTimeoutMs) {
+      this.busyTimeoutMs = busyTimeoutMs;
+      this.db.pragma(`busy_timeout = ${busyTimeoutMs}`);
+    }
+  }
+
+  release(): void {
+    if (--this.references > 0) return;
+    if (this.cacheKey) sharedByPath.delete(this.cacheKey);
+    this.db.close();
+  }
+
+  enqueue<T>(operation: () => T): Promise<T> {
+    const run = this.queue.then(() => this.retryWhileBusy(operation));
+    this.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /** Waits for another process's lock with timers, not inside SQLite, so the event loop keeps running. */
+  private async retryWhileBusy<T>(operation: () => T): Promise<T> {
+    const deadline = Date.now() + this.busyTimeoutMs;
+    for (let backoffMs = MIN_BACKOFF_MS; ; backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS)) {
+      try {
+        return this.withoutBusyWait(operation);
+      } catch (error: unknown) {
+        const remainingMs = deadline - Date.now();
+        if (!isBusyError(error) || remainingMs <= 0) throw error;
+        const jitteredMs = backoffMs / 2 + Math.random() * (backoffMs / 2);
+        await new Promise((wake) => setTimeout(wake, Math.min(jitteredMs, remainingMs)));
+      }
+    }
+  }
+
+  private withoutBusyWait<T>(operation: () => T): T {
+    this.db.pragma('busy_timeout = 0');
+    try {
+      return operation();
+    } finally {
+      this.db.pragma(`busy_timeout = ${this.busyTimeoutMs}`);
+    }
+  }
+}
+
+/** A store's handle on the connection it shares with every store on the same file in this process. */
+export class SqliteConnection {
+  private released = false;
+
+  constructor(private readonly shared: SharedDatabase) {}
+
+  get db(): Database.Database {
+    return this.shared.db;
+  }
+
+  /** Run `operation` in a `BEGIN IMMEDIATE` transaction, after this process's earlier queued operations. */
+  write<T>(operation: () => T): Promise<T> {
+    const transaction = this.shared.db.transaction(operation);
+    return this.shared.enqueue(() => transaction.immediate());
+  }
+
+  /** Run `operation` outside a transaction, after this process's earlier queued operations. */
+  read<T>(operation: () => T): Promise<T> {
+    return this.shared.enqueue(operation);
+  }
+
+  /** The connection closes once every store that acquired it has released it; a second call does nothing. */
+  release(): void {
+    if (this.released) return;
+    this.released = true;
+    this.shared.release();
+  }
+}
+
+/** The connection to `path`, shared by resolved path; a later store can switch it to WAL or lengthen its busy timeout. */
+export function acquireConnection(
+  path: string,
+  storeName: string,
+  options: OpenDatabaseOptions = {},
+): SqliteConnection {
+  const cacheKey = PRIVATE_PATHS.has(path) ? undefined : pathResolve(path);
+  let shared = cacheKey ? sharedByPath.get(cacheKey) : undefined;
+  if (!shared) {
+    const busyTimeoutMs = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+    shared = new SharedDatabase(openDatabase(path, storeName, options), busyTimeoutMs, cacheKey);
+    if (cacheKey) sharedByPath.set(cacheKey, shared);
+  }
+  shared.retain(options);
+  return new SqliteConnection(shared);
+}
diff --git a/libs/storage-sqlite/src/sqlite-event.store.ts b/libs/storage-sqlite/src/sqlite-event.store.ts
index a3fb21704..a5c2db783 100644
--- a/libs/storage-sqlite/src/sqlite-event.store.ts
+++ b/libs/storage-sqlite/src/sqlite-event.store.ts
@@ -7,7 +7,8 @@
 
 import type Database from 'better-sqlite3';
 
-import { openDatabase, withBusyRetry } from './open-database';
+import { withBusyRetry } from './open-database';
+import { acquireConnection, type SqliteConnection } from './sqlite-connection';
 import type { SqliteStorageOptions } from './sqlite.options';
 
 /**
@@ -60,7 +61,8 @@ interface PreparedStatements {
  * ```
  */
 export class SqliteEventStore implements EventStoreInterface {
-  private db: Database.Database;
+  private readonly connection: SqliteConnection;
+  private readonly db: Database.Database;
   private maxEvents: number;
   private ttlMs: number;
   private counters = new Map<string, number>();
@@ -68,11 +70,11 @@ export class SqliteEventStore implements EventStoreInterface {
   private stmts: PreparedStatements | null = null;
 
   constructor(options: SqliteEventStoreOptions) {
-    // Resolve better-sqlite3 (ESM-safe) and ensure the parent dir exists.
-    this.db = openDatabase(options.path, 'SqliteEventStore', {
+    this.connection = acquireConnection(options.path, 'SqliteEventStore', {
       busyTimeoutMs: options.busyTimeoutMs,
       walMode: options.walMode !== false,
     });
+    this.db = this.connection.db;
 
     this.maxEvents = options.maxEvents ?? 10000;
     this.ttlMs = options.ttlMs ?? 300000;
@@ -211,14 +213,14 @@ export class SqliteEventStore implements EventStoreInterface {
   }
 
   /**
-   * Close the database connection and stop cleanup timer.
+   * Stop the cleanup timer and release the connection, which closes once no other store on the file uses it.
    */
   close(): void {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = null;
     }
-    this.db.close();
+    this.connection.release();
   }
 
   /**
diff --git a/libs/storage-sqlite/src/sqlite-kv.store.ts b/libs/storage-sqlite/src/sqlite-kv.store.ts
index ee7ca707e..44f8b68f2 100644
--- a/libs/storage-sqlite/src/sqlite-kv.store.ts
+++ b/libs/storage-sqlite/src/sqlite-kv.store.ts
@@ -8,7 +8,8 @@
 import type Database from 'better-sqlite3';
 
 import { decryptValue, deriveEncryptionKey, encryptValue } from './encryption';
-import { openDatabase, withBusyRetry } from './open-database';
+import { withBusyRetry } from './open-database';
+import { acquireConnection, type SqliteConnection } from './sqlite-connection';
 import type { SqliteStorageOptions } from './sqlite.options';
 
 /** Bundled prepared statements - all-or-nothing initialization. */
@@ -37,17 +38,18 @@ interface KvPreparedStatements {
  * ```
  */
 export class SqliteKvStore {
-  private db: Database.Database;
+  private readonly connection: SqliteConnection;
+  private readonly db: Database.Database;
   private encryptionKey: Uint8Array | null = null;
   private cleanupTimer: ReturnType<typeof setInterval> | null = null;
   private stmts: KvPreparedStatements | null = null;
 
   constructor(options: SqliteStorageOptions) {
-    // Resolve better-sqlite3 (ESM-safe) and ensure the parent dir exists.
-    this.db = openDatabase(options.path, 'SqliteKvStore', {
+    this.connection = acquireConnection(options.path, 'SqliteKvStore', {
       busyTimeoutMs: options.busyTimeoutMs,
       walMode: options.walMode !== false,
     });
+    this.db = this.connection.db;
 
     // Derive encryption key if secret provided
     if (options.encryption?.secret) {
@@ -93,7 +95,7 @@ export class SqliteKvStore {
       ),
       cleanup: this.db.prepare('DELETE FROM kv WHERE expires_at IS NOT NULL AND expires_at <= ?'),
       ttl: this.db.prepare('SELECT expires_at FROM kv WHERE key = ?'),
-      expire: this.db.prepare('UPDATE kv SET expires_at = ? WHERE key = ?'),
+      expire: this.db.prepare('UPDATE kv SET expires_at = ? WHERE key = ? AND (expires_at IS NULL OR expires_at > ?)'),
     };
   }
 
@@ -208,11 +210,11 @@ export class SqliteKvStore {
    *
    * @param key - The key to set expiry on
    * @param ttlMs - Time to live in milliseconds
-   * @returns true if key exists and TTL was set, false if key doesn't exist
+   * @returns true if key exists and TTL was set, false if key doesn't exist or has expired
    */
   expire(key: string, ttlMs: number): boolean {
-    const expiresAt = Date.now() + ttlMs;
-    const result = this.prepared().expire.run(expiresAt, key);
+    const now = Date.now();
+    const result = this.prepared().expire.run(now + ttlMs, key, now);
     return result.changes > 0;
   }
 
@@ -246,20 +248,26 @@ export class SqliteKvStore {
   }
 
   /**
-   * Close the database connection and stop cleanup timer.
+   * Stop the cleanup timer and release the connection, which closes once no other store on the file uses it.
    */
   close(): void {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = null;
     }
-    this.db.close();
+    this.connection.release();
   }
 
   /**
    * Get the underlying database instance (for advanced use cases / testing).
+   * Other stores on the same file share it, so do not close it directly.
    */
   getDatabase(): Database.Database {
     return this.db;
   }
+
+  /** The connection this store shares with the other stores on its file, with its queue of operations. */
+  getConnection(): SqliteConnection {
+    return this.connection;
+  }
 }
diff --git a/libs/storage-sqlite/src/sqlite-storage.adapter.ts b/libs/storage-sqlite/src/sqlite-storage.adapter.ts
index 099848986..3cfba8bc8 100644
--- a/libs/storage-sqlite/src/sqlite-storage.adapter.ts
+++ b/libs/storage-sqlite/src/sqlite-storage.adapter.ts
@@ -11,14 +11,16 @@
  * is implemented here.
  *
  * Notes:
- * - All operations are backed by a single local SQLite file; "async" here just
- *   wraps synchronous better-sqlite3 calls in resolved promises.
- * - Pub/sub is NOT supported (single-process local file). Callers needing
- *   pub/sub must use Redis/Upstash.
+ * - Every operation runs on the connection this process shares for the file, in call
+ *   order. One that reads and then writes (conditional set, incr, compare-and-act) runs
+ *   in a single `BEGIN IMMEDIATE` transaction, so it is atomic across processes too.
+ * - Waiting for another process's lock does not block the event loop (see `SqliteConnection`).
+ * - Pub/sub is NOT supported. Callers needing pub/sub must use Redis/Upstash.
  */
 
-import { BaseStorageAdapter, type SetOptions } from '@frontmcp/utils';
+import { BaseStorageAdapter, StorageOperationError, validateTTL, type SetOptions } from '@frontmcp/utils';
 
+import { type SqliteConnection } from './sqlite-connection';
 import { SqliteKvStore } from './sqlite-kv.store';
 import { type SqliteStorageOptions } from './sqlite.options';
 
@@ -27,6 +29,8 @@ export class SqliteStorageAdapter extends BaseStorageAdapter {
 
   private readonly kv: SqliteKvStore;
 
+  private readonly connection: SqliteConnection;
+
   /**
    * Whether this adapter created (and therefore owns the lifecycle of) `kv`.
    * When the store is passed in by the caller, closing it is the caller's
@@ -39,6 +43,7 @@ export class SqliteStorageAdapter extends BaseStorageAdapter {
     // Accept either raw options (we own the store) or an existing store.
     this.ownsKvStore = !(options instanceof SqliteKvStore);
     this.kv = options instanceof SqliteKvStore ? options : new SqliteKvStore(options);
+    this.connection = this.kv.getConnection();
   }
 
   // ============================================
@@ -78,33 +83,46 @@ export class SqliteStorageAdapter extends BaseStorageAdapter {
 
   async get(key: string): Promise<string | null> {
     this.ensureConnected();
-    return this.kv.get(key);
+    return this.connection.read(() => this.kv.get(key));
   }
 
   protected async doSet(key: string, value: string, options?: SetOptions): Promise<void> {
-    // Honor conditional flags (NX/XX). BaseStorageAdapter.set() already
-    // validated mutual exclusivity.
-    if (options?.ifNotExists && this.kv.has(key)) {
-      return;
-    }
-    if (options?.ifExists && !this.kv.has(key)) {
-      return;
-    }
-
+    // BaseStorageAdapter.set() already validated the TTL and that NX and XX are exclusive.
     const ttlMs = options?.ttlSeconds !== undefined ? options.ttlSeconds * 1000 : undefined;
-    this.kv.set(key, value, ttlMs);
+    return this.connection.write(() => {
+      if (options?.ifNotExists && this.kv.has(key)) return;
+      if (options?.ifExists && !this.kv.has(key)) return;
+      this.kv.set(key, value, ttlMs);
+    });
   }
 
   async delete(key: string): Promise<boolean> {
     this.ensureConnected();
-    const existed = this.kv.has(key);
-    this.kv.del(key);
-    return existed;
+    return this.connection.write(() => {
+      const existed = this.kv.has(key);
+      this.kv.del(key);
+      return existed;
+    });
+  }
+
+  override async deleteIfEquals(key: string, expectedValue: string): Promise<boolean> {
+    this.ensureConnected();
+    return this.connection.write(() => {
+      if (this.kv.get(key) !== expectedValue) return false;
+      this.kv.del(key);
+      return true;
+    });
+  }
+
+  override async expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean> {
+    this.ensureConnected();
+    validateTTL(ttlSeconds);
+    return this.connection.write(() => this.kv.get(key) === expectedValue && this.kv.expire(key, ttlSeconds * 1000));
   }
 
   async exists(key: string): Promise<boolean> {
     this.ensureConnected();
-    return this.kv.has(key);
+    return this.connection.read(() => this.kv.has(key));
   }
 
   // ============================================
@@ -113,13 +131,14 @@ export class SqliteStorageAdapter extends BaseStorageAdapter {
 
   async expire(key: string, ttlSeconds: number): Promise<boolean> {
     this.ensureConnected();
-    return this.kv.expire(key, ttlSeconds * 1000);
+    validateTTL(ttlSeconds);
+    return this.connection.write(() => this.kv.expire(key, ttlSeconds * 1000));
   }
 
   async ttl(key: string): Promise<number | null> {
     this.ensureConnected();
     // SqliteKvStore.ttl returns ms (-1 = no expiry, -2 = missing).
-    const ms = this.kv.ttl(key);
+    const ms = await this.connection.read(() => this.kv.ttl(key));
     if (ms === -2) return null; // key does not exist
     if (ms === -1) return -1; // no expiry
     return Math.max(0, Math.ceil(ms / 1000));
@@ -135,17 +154,17 @@ export class SqliteStorageAdapter extends BaseStorageAdapter {
     // Existing LIKE metacharacters are escaped as `\%`/`\_`; SqliteKvStore's
     // LIKE query declares `ESCAPE '\'` so these are matched literally.
     if (pattern === '*' || pattern === undefined) {
-      return this.kv.keys();
+      return this.connection.read(() => this.kv.keys());
     }
     const like = pattern
       .replace(/[%_]/g, (c) => `\\${c}`)
       .replace(/\*/g, '%')
       .replace(/\?/g, '_');
-    return this.kv.keys(like);
+    return this.connection.read(() => this.kv.keys(like));
   }
 
   // ============================================
-  // Atomic Operations (read-modify-write; single-process local file)
+  // Atomic Operations
   // ============================================
 
   async incr(key: string): Promise<number> {
@@ -158,20 +177,16 @@ export class SqliteStorageAdapter extends BaseStorageAdapter {
 
   async incrBy(key: string, amount: number): Promise<number> {
     this.ensureConnected();
-    const current = this.kv.get(key);
-    let base = 0;
-    if (current !== null) {
-      const parsed = Number.parseInt(current, 10);
-      if (Number.isNaN(parsed)) {
-        throw new Error(`SqliteStorageAdapter: value at "${key}" is not an integer`);
-      }
-      base = parsed;
-    }
-    const next = base + amount;
-    // Preserve any existing TTL.
-    const remainingMs = this.kv.ttl(key);
-    this.kv.set(key, String(next), remainingMs > 0 ? remainingMs : undefined);
-    return next;
+    return this.connection.write(() => {
+      const current = this.kv.get(key);
+      const base = current === null ? 0 : Number.parseInt(current, 10);
+      if (Number.isNaN(base)) throw new StorageOperationError('incrBy', key, 'Value is not an integer');
+      const next = base + amount;
+      // Preserve any existing TTL.
+      const remainingMs = this.kv.ttl(key);
+      this.kv.set(key, String(next), remainingMs > 0 ? remainingMs : undefined);
+      return next;
+    });
   }
 
   /**
diff --git a/libs/storage-sqlite/src/sqlite-task.store.ts b/libs/storage-sqlite/src/sqlite-task.store.ts
index 9b43fb3ec..5f542166c 100644
--- a/libs/storage-sqlite/src/sqlite-task.store.ts
+++ b/libs/storage-sqlite/src/sqlite-task.store.ts
@@ -31,7 +31,8 @@ import type Database from 'better-sqlite3';
 import { getHostname } from '@frontmcp/utils';
 
 import { decryptValue, deriveEncryptionKey, encryptValue } from './encryption';
-import { openDatabase, withBusyRetry } from './open-database';
+import { withBusyRetry } from './open-database';
+import { acquireConnection, type SqliteConnection } from './sqlite-connection';
 import type { SqliteStorageOptions } from './sqlite.options';
 
 // ───────────────────────────────────────────────────────────────
@@ -158,6 +159,7 @@ interface Prepared {
 }
 
 export class SqliteTaskStore implements TaskStoreInterface {
+  private readonly connection: SqliteConnection;
   private readonly db: Database.Database;
   private readonly emitter = new EventEmitter();
   private readonly logger?: SqliteTaskLogger;
@@ -173,11 +175,11 @@ export class SqliteTaskStore implements TaskStoreInterface {
   private stmts: Prepared | null = null;
 
   constructor(options: SqliteTaskStoreOptions) {
-    // Resolve better-sqlite3 (ESM-safe) and ensure the parent dir exists.
-    this.db = openDatabase(options.path, 'SqliteTaskStore', {
+    this.connection = acquireConnection(options.path, 'SqliteTaskStore', {
       busyTimeoutMs: options.busyTimeoutMs,
       walMode: options.walMode !== false,
     });
+    this.db = this.connection.db;
 
     this.logger = options.logger;
     this.liveness = options.livenessProbe ?? defaultLivenessProbe;
@@ -379,7 +381,7 @@ export class SqliteTaskStore implements TaskStoreInterface {
     if (this.cleanupTimer) clearInterval(this.cleanupTimer);
     this.emitter.removeAllListeners();
     try {
-      this.db.close();
+      this.connection.release();
     } catch {
       /* ignore */
     }
diff --git a/libs/utils/jest.config.ts b/libs/utils/jest.config.ts
index ed07aca7a..3cc2d3cd0 100644
--- a/libs/utils/jest.config.ts
+++ b/libs/utils/jest.config.ts
@@ -26,6 +26,12 @@ module.exports = {
     ],
   },
   moduleFileExtensions: ['ts', 'js', 'html'],
+  moduleNameMapper: {
+    ...require('../../jest.imports-mapper'),
+    // The sqlite storage type loads it at runtime; it resolves back to this source tree, not a build.
+    '^@frontmcp/storage-sqlite$': '<rootDir>/../storage-sqlite/src/index.ts',
+    '^@frontmcp/utils$': '<rootDir>/src/index.ts',
+  },
   coverageDirectory: '../../coverage/unit/utils',
   collectCoverageFrom: [
     'src/**/*.ts',
diff --git a/libs/utils/src/index.ts b/libs/utils/src/index.ts
index ab1255ff4..5ef7ad308 100644
--- a/libs/utils/src/index.ts
+++ b/libs/utils/src/index.ts
@@ -336,6 +336,7 @@ export type {
   RedisUrlFillInConfig,
   VercelKvAdapterOptions,
   UpstashAdapterOptions,
+  SqliteAdapterOptions,
   StorageType,
   StorageConfig,
   RedisErrorListenerOptions,
diff --git a/libs/utils/src/storage/__tests__/factory.spec.ts b/libs/utils/src/storage/__tests__/factory.spec.ts
index c4b76ecb6..455c0e7e0 100644
--- a/libs/utils/src/storage/__tests__/factory.spec.ts
+++ b/libs/utils/src/storage/__tests__/factory.spec.ts
@@ -1,6 +1,11 @@
 /**
  * Storage Factory Tests
  */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { StorageConfigError } from '../errors';
 import { createMemoryStorage, createStorage, getDetectedStorageType } from '../factory';
 
 jest.mock('../adapters/redis', () => ({
@@ -117,6 +122,86 @@ describe('Storage Factory', () => {
         await storage.disconnect();
       });
     });
+
+    describe('explicit sqlite type', () => {
+      let dir: string;
+      let dbPath: string;
+
+      beforeEach(() => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), 'storage-factory-sqlite-'));
+        dbPath = path.join(dir, 'app.sqlite');
+      });
+
+      afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+      function failToLoadSqlitePackage(error: Error): void {
+        jest.doMock('@frontmcp/storage-sqlite', () => {
+          throw error;
+        });
+      }
+
+      afterEach(() => jest.dontMock('@frontmcp/storage-sqlite'));
+
+      it('stores keys in the SQLite file, which later storages on the file read', async () => {
+        const storage = await createStorage({ type: 'sqlite', sqlite: { path: dbPath, ttlCleanupIntervalMs: 0 } });
+        expect(storage.supportsPubSub()).toBe(false);
+        await storage.set('key', 'value', { ttlSeconds: 60 });
+        expect(await storage.incr('visits')).toBe(1);
+        await storage.disconnect();
+
+        const reopened = await createStorage({ type: 'sqlite', sqlite: { path: dbPath }, prefix: 'app:' });
+        expect(await reopened.root.get('key')).toBe('value');
+        expect(await reopened.root.deleteIfEquals?.('key', 'value')).toBe(true);
+        await reopened.set('scoped', '1');
+        expect(await reopened.root.get('app:scoped')).toBe('1');
+        await reopened.disconnect();
+      });
+
+      it.each([
+        ['no sqlite block', undefined, /sqlite\.path/],
+        ['an empty path', { path: '' }, /sqlite\.path/],
+        ['a negative busy timeout', { path: 'a.sqlite', busyTimeoutMs: -1 }, /sqlite\.busyTimeoutMs/],
+        ['a non-boolean walMode', { path: 'a.sqlite', walMode: 'yes' }, /sqlite\.walMode/],
+        ['an empty encryption secret', { path: 'a.sqlite', encryption: { secret: '' } }, /sqlite\.encryption\.secret/],
+      ])('rejects %s with StorageConfigError, even with a memory fallback', async (_case, sqlite, message) => {
+        const attempt = createStorage({ type: 'sqlite', sqlite: sqlite as never, fallback: 'memory' });
+        await expect(attempt).rejects.toBeInstanceOf(StorageConfigError);
+        await expect(createStorage({ type: 'sqlite', sqlite: sqlite as never })).rejects.toThrow(message);
+      });
+
+      it('names the package to install when @frontmcp/storage-sqlite is missing', async () => {
+        failToLoadSqlitePackage(
+          Object.assign(new Error("Cannot find module '@frontmcp/storage-sqlite'"), { code: 'MODULE_NOT_FOUND' }),
+        );
+        const attempt = createStorage({ type: 'sqlite', sqlite: { path: dbPath }, fallback: 'error' });
+        await expect(attempt).rejects.toBeInstanceOf(StorageConfigError);
+        await expect(createStorage({ type: 'sqlite', sqlite: { path: dbPath }, fallback: 'error' })).rejects.toThrow(
+          'npm install @frontmcp/storage-sqlite',
+        );
+      });
+
+      it('falls back to memory in development when the package is missing, as other backends do', async () => {
+        const warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+        failToLoadSqlitePackage(
+          Object.assign(new Error("Cannot find module '@frontmcp/storage-sqlite'"), { code: 'MODULE_NOT_FOUND' }),
+        );
+        try {
+          const storage = await createStorage({ type: 'sqlite', sqlite: { path: dbPath } });
+          expect(storage.supportsPubSub()).toBe(true);
+          expect(warn).toHaveBeenCalledWith(expect.stringContaining('@frontmcp/storage-sqlite'));
+          await storage.disconnect();
+        } finally {
+          warn.mockRestore();
+        }
+      });
+
+      it('rethrows a failure other than the package being missing', async () => {
+        failToLoadSqlitePackage(new Error('native module failed to load'));
+        await expect(createStorage({ type: 'sqlite', sqlite: { path: dbPath }, fallback: 'error' })).rejects.toThrow(
+          'native module failed to load',
+        );
+      });
+    });
   });
 
   describe('createMemoryStorage', () => {
diff --git a/libs/utils/src/storage/adapters/base.ts b/libs/utils/src/storage/adapters/base.ts
index e0da12af5..7a4172d42 100644
--- a/libs/utils/src/storage/adapters/base.ts
+++ b/libs/utils/src/storage/adapters/base.ts
@@ -138,7 +138,7 @@ export abstract class BaseStorageAdapter implements StorageAdapter {
     throw new StorageNotSupportedError(
       'deleteIfEquals',
       this.backendName,
-      'Use the memory, Redis, Upstash or Vercel KV adapter for an atomic compare-and-delete.',
+      'Use the memory, Redis, Upstash, Vercel KV or SQLite adapter for an atomic compare-and-delete.',
     );
   }
 
@@ -147,7 +147,7 @@ export abstract class BaseStorageAdapter implements StorageAdapter {
     throw new StorageNotSupportedError(
       'expireIfEquals',
       this.backendName,
-      'Use the memory, Redis, Upstash or Vercel KV adapter for an atomic compare-and-expire.',
+      'Use the memory, Redis, Upstash, Vercel KV or SQLite adapter for an atomic compare-and-expire.',
     );
   }
 
diff --git a/libs/utils/src/storage/factory.ts b/libs/utils/src/storage/factory.ts
index a28149731..27a6db232 100644
--- a/libs/utils/src/storage/factory.ts
+++ b/libs/utils/src/storage/factory.ts
@@ -4,13 +4,53 @@
  * Factory function to create storage adapters with auto-detection.
  */
 
+import { z } from '@frontmcp/lazy-zod';
+
 import { getEnv, isProduction } from '#env';
 import { getRuntimeContext } from '#runtime-context';
 
 import { MemoryStorageAdapter } from './adapters/memory';
 import { StorageConfigError } from './errors';
 import { createNamespacedStorage, createRootStorage } from './namespace';
-import type { RootStorage, StorageAdapter, StorageConfig, StorageType } from './types';
+import type { RootStorage, SqliteAdapterOptions, StorageAdapter, StorageConfig, StorageType } from './types';
+
+/** Required through a variable: it depends on this package, so a literal would make bundlers and Nx see a cycle. */
+const SQLITE_STORAGE_PACKAGE = '@frontmcp/storage-sqlite';
+
+interface SqliteStorageModule {
+  SqliteStorageAdapter: new (options: SqliteAdapterOptions) => StorageAdapter;
+}
+
+const PATH_REQUIRED = { error: 'is required (the path of the database file)' };
+
+const sqliteAdapterOptionsSchema = z.object({
+  path: z.string(PATH_REQUIRED).min(1, PATH_REQUIRED),
+  walMode: z.boolean().optional(),
+  busyTimeoutMs: z.number().int().nonnegative().optional(),
+  ttlCleanupIntervalMs: z.number().int().nonnegative().optional(),
+  encryption: z.object({ secret: z.string().min(1) }).optional(),
+});
+
+/** The `sqlite` block of a config, validated; a mistake in it is the caller's to fix, so no fallback hides it. */
+function parseSqliteOptions(options: SqliteAdapterOptions | undefined): SqliteAdapterOptions {
+  const result = sqliteAdapterOptionsSchema.safeParse(options ?? {});
+  if (result.success) return result.data;
+  const problems = result.error.issues.map((issue) => `sqlite.${issue.path.join('.')}: ${issue.message}`);
+  throw new StorageConfigError('sqlite', problems.join('; '));
+}
+
+function loadSqliteStorage(): SqliteStorageModule {
+  try {
+    return require(SQLITE_STORAGE_PACKAGE) as SqliteStorageModule;
+  } catch (error) {
+    const missing = (error as { code?: unknown }).code === 'MODULE_NOT_FOUND';
+    if (!missing || !String((error as Error).message).includes(SQLITE_STORAGE_PACKAGE)) throw error;
+    throw new StorageConfigError(
+      'sqlite',
+      `the sqlite type needs ${SQLITE_STORAGE_PACKAGE}. Install it with: npm install ${SQLITE_STORAGE_PACKAGE}`,
+    );
+  }
+}
 
 /** Whether this process already printed the no-distributed-storage warning. */
 let noDistributedStorageWarned = false;
@@ -81,6 +121,11 @@ async function createAdapter(type: StorageType, config: StorageConfig): Promise<
       return new UpstashStorageAdapter(config.upstash);
     }
 
+    case 'sqlite': {
+      const { SqliteStorageAdapter } = loadSqliteStorage();
+      return new SqliteStorageAdapter(parseSqliteOptions(config.sqlite));
+    }
+
     case 'cloudflare-kv': {
       if (!config.cloudflareKv) {
         throw new StorageConfigError(
@@ -118,6 +163,12 @@ async function createAdapter(type: StorageType, config: StorageConfig): Promise<
  * await store.connect();
  * ```
  *
+ * @example A SQLite file shared by the processes on one machine (needs `@frontmcp/storage-sqlite`)
+ * ```typescript
+ * const store = await createStorage({ type: 'sqlite', sqlite: { path: '/var/lib/my-app/state.sqlite' } });
+ * await store.incr('runs');
+ * ```
+ *
  * @example With namespaces
  * ```typescript
  * const store = await createStorage({ type: 'memory' });
@@ -147,6 +198,8 @@ export async function createStorage(config: StorageConfig = {}): Promise<RootSto
     if (type === 'memory' && isProduction()) warnNoDistributedStorage();
   }
 
+  if (type === 'sqlite') parseSqliteOptions(config.sqlite);
+
   let adapter: StorageAdapter;
 
   try {
diff --git a/libs/utils/src/storage/index.ts b/libs/utils/src/storage/index.ts
index aa8e8632a..b4e7e81c4 100644
--- a/libs/utils/src/storage/index.ts
+++ b/libs/utils/src/storage/index.ts
@@ -21,6 +21,7 @@ export type {
   RedisUrlFillInConfig,
   VercelKvAdapterOptions,
   UpstashAdapterOptions,
+  SqliteAdapterOptions,
   StorageType,
   StorageConfig,
 } from './types';
diff --git a/libs/utils/src/storage/types.ts b/libs/utils/src/storage/types.ts
index 437c87140..ec374efc9 100644
--- a/libs/utils/src/storage/types.ts
+++ b/libs/utils/src/storage/types.ts
@@ -547,6 +547,23 @@ export interface CloudflareKvAdapterOptions {
   keyPrefix?: string;
 }
 
+/**
+ * SQLite adapter options (when type='sqlite'); the adapter comes from `@frontmcp/storage-sqlite`.
+ * Processes on one machine that open the same file share its keys, counters and locks.
+ */
+export interface SqliteAdapterOptions {
+  /** Path to the database file; its directory is created if missing. */
+  path: string;
+  /** Write-ahead log: readers don't wait for the writer. Needs a local filesystem. @default true */
+  walMode?: boolean;
+  /** How long an operation waits for another process's lock before failing with `SQLITE_BUSY`. @default 5000 */
+  busyTimeoutMs?: number;
+  /** How often expired keys are purged, in milliseconds; 0 turns the sweep off. @default 60000 */
+  ttlCleanupIntervalMs?: number;
+  /** Encrypt values at rest with AES-256-GCM, from a key derived with HKDF-SHA256. */
+  encryption?: { secret: string };
+}
+
 // ============================================
 // Factory Types
 // ============================================
@@ -554,7 +571,7 @@ export interface CloudflareKvAdapterOptions {
 /**
  * Storage backend type.
  */
-export type StorageType = 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'cloudflare-kv' | 'auto';
+export type StorageType = 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'cloudflare-kv' | 'sqlite' | 'auto';
 
 /**
  * Configuration for createStorage factory.
@@ -566,6 +583,7 @@ export interface StorageConfig {
    * - 'redis': Redis (production)
    * - 'vercel-kv': Vercel KV (edge deployment, no pub/sub)
    * - 'upstash': Upstash Redis (edge deployment, with pub/sub)
+   * - 'sqlite': A local SQLite file, shared by the processes on one machine (no pub/sub)
    * - 'auto': Auto-detect based on environment variables
    * @default 'auto'
    */
@@ -596,6 +614,11 @@ export interface StorageConfig {
    */
   upstash?: UpstashAdapterOptions;
 
+  /**
+   * SQLite adapter options (when type='sqlite').
+   */
+  sqlite?: SqliteAdapterOptions;
+
   /**
    * Root namespace prefix for all keys.
    * Applied on top of any adapter-specific prefix.

From 99ea7c62bcae18c316bd4fc2a0848ac21ebfc2be Mon Sep 17 00:00:00 2001
From: David Antoon <david@frontegg.com>
Date: Mon, 2 Nov 2026 08:44:54 +0200
Subject: [PATCH 2/6] fix(storage-sqlite): count a store's reference to a
 shared connection only once it is configured

---
 libs/storage-sqlite/src/sqlite-connection.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libs/storage-sqlite/src/sqlite-connection.ts b/libs/storage-sqlite/src/sqlite-connection.ts
index 4f8d216b3..6935c1515 100644
--- a/libs/storage-sqlite/src/sqlite-connection.ts
+++ b/libs/storage-sqlite/src/sqlite-connection.ts
@@ -29,7 +29,6 @@ class SharedDatabase {
   ) {}
 
   retain(options: OpenDatabaseOptions): void {
-    this.references++;
     if (options.walMode && this.db.pragma('journal_mode', { simple: true }) !== 'wal') {
       withBusyRetry(() => this.db.pragma('journal_mode = WAL'));
     }
@@ -38,6 +37,7 @@ class SharedDatabase {
       this.busyTimeoutMs = busyTimeoutMs;
       this.db.pragma(`busy_timeout = ${busyTimeoutMs}`);
     }
+    this.references++;
   }
 
   release(): void {

From 5c28b20198f00373601a4f1934c9c35d78554700 Mon Sep 17 00:00:00 2001
From: David Antoon <david@frontegg.com>
Date: Mon, 2 Nov 2026 12:03:35 +0200
Subject: [PATCH 3/6] fix(storage-sqlite): bound queued waits, drain on
 disconnect, and queue the expiry sweeps

- A queued operation's busy timeout counts from its call, restarting when an earlier queued
  operation gets the lock, so a held lock no longer makes queued operations time out one after another.
- SqliteStorageAdapter.disconnect() lets the operations already called finish before closing the file.
- The KV and event stores run their periodic sweeps on the connection's queue: no event-loop stall,
  and no SQLITE_BUSY thrown from the timer while another process holds the lock.
- A store whose setup fails releases the shared connection, and a handle closed directly is replaced
  for the stores opened after it.
---
 .../e2e/helpers/workers.ts                    |  5 +-
 .../e2e/sqlite-contention.e2e.spec.ts         |  6 +-
 .../e2e/sqlite-storage-provider.e2e.spec.ts   |  5 +-
 .../fixture/container-worker.ts               |  6 +-
 .../fixture/lock-holder.ts                    |  5 +-
 .../fixture/storage-worker.ts                 |  8 +-
 .../fixture/worker-protocol.ts                |  5 +-
 .../frontmcp-setup/references/setup-sqlite.md |  4 +-
 .../src/__tests__/sqlite-connection.spec.ts   | 91 +++++++++++++++++++
 .../__tests__/sqlite-storage.adapter.spec.ts  |  7 ++
 libs/storage-sqlite/src/sqlite-connection.ts  | 27 ++++--
 libs/storage-sqlite/src/sqlite-event.store.ts | 16 +++-
 libs/storage-sqlite/src/sqlite-kv.store.ts    | 15 ++-
 .../src/sqlite-storage.adapter.ts             |  3 +-
 libs/storage-sqlite/src/sqlite-task.store.ts  |  9 +-
 libs/utils/src/storage/types.ts               |  5 +-
 16 files changed, 162 insertions(+), 55 deletions(-)

diff --git a/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts b/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
index 59d896c57..5bf4c02d3 100644
--- a/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
+++ b/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
@@ -1,7 +1,4 @@
-/**
- * Start fixture scripts as child processes that follow `fixture/worker-protocol.ts`, and drive them
- * from a spec: wait for a line a worker prints, send it a line, read the result it reports.
- */
+/** Start fixture scripts that follow `fixture/worker-protocol.ts` and drive them line by line from a spec. */
 import { spawn, type ChildProcess } from 'node:child_process';
 import { join } from 'node:path';
 
diff --git a/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-contention.e2e.spec.ts b/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-contention.e2e.spec.ts
index 2b3ed2b2c..9d0966407 100644
--- a/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-contention.e2e.spec.ts
+++ b/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-contention.e2e.spec.ts
@@ -1,8 +1,4 @@
-/**
- * E2E: ten processes share one SQLite file through `createStorage({ type: 'sqlite' })` while another
- * process holds the write lock. Every increment is counted once, one process takes the NX lock and the
- * semaphore slot, no SQLITE_BUSY reaches a caller, and no process's event loop stalls while it waits.
- */
+/** E2E: ten processes contend on one SQLite file while another holds its write lock. */
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
diff --git a/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-storage-provider.e2e.spec.ts b/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-storage-provider.e2e.spec.ts
index ef59d4ac9..a08a63880 100644
--- a/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-storage-provider.e2e.spec.ts
+++ b/apps/e2e/demo-e2e-local-runtime/e2e/sqlite-storage-provider.e2e.spec.ts
@@ -1,7 +1,4 @@
-/**
- * E2E: scripts read the SQLite storage the SDK provides (`sqliteStorageProvider` under
- * `SqliteStorageToken`) from `createContainer()`, in several processes on one file at once.
- */
+/** E2E: several processes share the storage `sqliteStorageProvider()` registers, read from `createContainer()`. */
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
diff --git a/apps/e2e/demo-e2e-local-runtime/fixture/container-worker.ts b/apps/e2e/demo-e2e-local-runtime/fixture/container-worker.ts
index e3f02f453..4dffff704 100644
--- a/apps/e2e/demo-e2e-local-runtime/fixture/container-worker.ts
+++ b/apps/e2e/demo-e2e-local-runtime/fixture/container-worker.ts
@@ -1,8 +1,4 @@
-/**
- * A script that reads the SQLite storage the SDK provides (`sqliteStorageProvider`, `SqliteStorageToken`)
- * from `createContainer()`: on "go" it increments a counter shared with the other workers, then disposes
- * the container and reports the values it got.
- */
+/** On "go": increment a shared counter through `SqliteStorageToken`, dispose the container, report the values. */
 import 'reflect-metadata';
 
 import { createContainer, LogLevel, sqliteStorageProvider, SqliteStorageToken } from '@frontmcp/sdk';
diff --git a/apps/e2e/demo-e2e-local-runtime/fixture/lock-holder.ts b/apps/e2e/demo-e2e-local-runtime/fixture/lock-holder.ts
index d79e48614..63e09680c 100644
--- a/apps/e2e/demo-e2e-local-runtime/fixture/lock-holder.ts
+++ b/apps/e2e/demo-e2e-local-runtime/fixture/lock-holder.ts
@@ -1,7 +1,4 @@
-/**
- * Another process holding the SQLite write lock: on "go" it opens a write transaction, prints
- * "locked", keeps the lock for HOLD_MS, then commits.
- */
+/** On "go": hold the SQLite write lock for HOLD_MS, printing "locked" once it has it. */
 import { loadBetterSqlite3 } from '@frontmcp/storage-sqlite';
 
 import { readyThenWaitForGo, report, requiredEnv, runWorker, signal } from './worker-protocol';
diff --git a/apps/e2e/demo-e2e-local-runtime/fixture/storage-worker.ts b/apps/e2e/demo-e2e-local-runtime/fixture/storage-worker.ts
index aec9f3c77..3e6aaf1b9 100644
--- a/apps/e2e/demo-e2e-local-runtime/fixture/storage-worker.ts
+++ b/apps/e2e/demo-e2e-local-runtime/fixture/storage-worker.ts
@@ -1,8 +1,4 @@
-/**
- * One of many processes sharing a SQLite file through `createStorage({ type: 'sqlite' })`: on "go" it
- * increments a shared counter, tries to take an NX lock and a one-slot semaphore, and reports what it
- * got, the errors that reached it, and the longest its event loop went without running a timer.
- */
+/** On "go": increment, take an NX lock and a semaphore slot, and report the errors and longest timer gap seen. */
 import { DistributedSemaphore } from '@frontmcp/guard';
 import { createStorage } from '@frontmcp/utils';
 
@@ -47,7 +43,7 @@ runWorker(async () => {
   const storage = await createStorage({
     type: 'sqlite',
     fallback: 'error',
-    sqlite: { path: requiredEnv('DB_PATH'), walMode: requiredEnv('WAL_MODE') === 'true', ttlCleanupIntervalMs: 0 },
+    sqlite: { path: requiredEnv('DB_PATH'), walMode: requiredEnv('WAL_MODE') === 'true', ttlCleanupIntervalMs: 200 },
   });
   const semaphore = new DistributedSemaphore(storage, 60);
   await readyThenWaitForGo();
diff --git a/apps/e2e/demo-e2e-local-runtime/fixture/worker-protocol.ts b/apps/e2e/demo-e2e-local-runtime/fixture/worker-protocol.ts
index 8805141d4..a4aaf3019 100644
--- a/apps/e2e/demo-e2e-local-runtime/fixture/worker-protocol.ts
+++ b/apps/e2e/demo-e2e-local-runtime/fixture/worker-protocol.ts
@@ -1,7 +1,4 @@
-/**
- * The worker side of `e2e/helpers/workers.ts`: a worker prints lines on stdout and reads its
- * instructions from stdin, so a spec can start many workers at once and wait for each one.
- */
+/** The worker side of `e2e/helpers/workers.ts`: lines on stdout for the spec, instructions on stdin. */
 
 /** Print a line the spec waits for with `worker.waitFor(line)`. */
 export function signal(line: string): void {
diff --git a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
index 01a46e874..44fb79807 100644
--- a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
+++ b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
@@ -240,11 +240,11 @@ Any number of processes on one machine can open the same file. SQLite lets one p
 
 - **One connection per file per process.** The stores a process opens on one file (sessions, tasks, elicitation, events, and your own SQLite storage) share a single connection, so a process never waits on its own lock.
 - **Short, atomic writes.** Each write is one short `BEGIN IMMEDIATE` transaction. A conditional set (`ifNotExists`/`ifExists`), `incr`, `deleteIfEquals` and `expireIfEquals` read and write in that one transaction, so counters stay exact and an NX lock has one holder across processes.
-- **Waiting without blocking.** Operations through `createStorage({ type: 'sqlite' })`, `sqliteStorageProvider()` or `SqliteStorageAdapter` run one at a time per process and wait for another process's lock on a timer, so the event loop keeps running. The built-in session, task, elicitation and event stores still wait synchronously, for at most `busyTimeoutMs`.
+- **Waiting without blocking.** Operations through `createStorage({ type: 'sqlite' })`, `sqliteStorageProvider()` or `SqliteStorageAdapter` run one at a time per process and wait for another process's lock on a timer, so the event loop keeps running; `disconnect()` lets the operations already called finish first. The periodic sweeps of expired keys and events wait the same way. The built-in session, task, elicitation and event stores' own reads and writes still wait synchronously, for at most `busyTimeoutMs`.
 
 ### Busy timeout
 
-`busyTimeoutMs` (default `5000`) is how long an operation waits for another process's write lock before it fails with `SQLITE_BUSY`. Writes hold the lock for one short transaction, so the default covers many writer processes. Raise it when processes hold the lock longer (bulk imports, long transactions) or when dozens of processes write at once; lower it for an interactive tool that should fail fast. When several stores in one process open a file with different values, the longest applies.
+`busyTimeoutMs` (default `5000`) is how long an operation waits for another process's write lock before it fails with `SQLITE_BUSY`. The wait counts from the call, so while the lock stays held every queued operation fails within `busyTimeoutMs` of its call, not one timeout after another; it restarts each time an earlier operation in the queue gets the lock. Writes hold the lock for one short transaction, so the default covers many writer processes. Raise it when processes hold the lock longer (bulk imports, long transactions) or when dozens of processes write at once; lower it for an interactive tool that should fail fast. When several stores in one process open a file with different values, the longest applies.
 
 ## Step 4 -- How the SDK Builds the SQLite Session Store
 
diff --git a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
index a7b792c7b..4fb830ca5 100644
--- a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
+++ b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
@@ -105,6 +105,43 @@ describe('shared SQLite connections', () => {
     reopened.close();
   });
 
+  it.each([
+    ['SqliteKvStore', (dbPath: string) => new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0, walMode: false })],
+    [
+      'SqliteEventStore',
+      (dbPath: string) => new SqliteEventStore({ path: dbPath, ttlCleanupIntervalMs: 0, walMode: false }),
+    ],
+    [
+      'SqliteTaskStore',
+      (dbPath: string) => new SqliteTaskStore({ path: dbPath, ttlCleanupIntervalMs: 0, walMode: false }),
+    ],
+  ])('releases the connection when %s fails to set up the file', (_store, open) => {
+    fs.writeFileSync(dbPath, 'not a SQLite database, and long enough for SQLite to read its header');
+    expect(() => open(dbPath)).toThrow(expect.objectContaining({ code: 'SQLITE_NOTADB' }));
+
+    fs.writeFileSync(dbPath, '');
+    const kv = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    const db = kv.getDatabase();
+    kv.close();
+    expect(db.open).toBe(false);
+  });
+
+  it('opens a new connection when the shared one was closed directly', () => {
+    const first = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    first.getDatabase().close();
+
+    const second = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    second.set('k', 'v');
+    first.close();
+    const third = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    expect(third.getDatabase()).toBe(second.getDatabase());
+    expect(third.get('k')).toBe('v');
+
+    second.close();
+    third.close();
+    expect(third.getDatabase().open).toBe(false);
+  });
+
   it('gives every in-memory store a database of its own', () => {
     const first = new SqliteKvStore({ path: ':memory:', ttlCleanupIntervalMs: 0 });
     const second = new SqliteKvStore({ path: ':memory:', ttlCleanupIntervalMs: 0 });
@@ -209,6 +246,60 @@ describe('shared SQLite connections', () => {
       }
     });
 
+    it('fails every queued operation within busyTimeoutMs of its call, not one timeout after another', async () => {
+      const adapter = new SqliteStorageAdapter({ path: dbPath, ttlCleanupIntervalMs: 0, busyTimeoutMs: 100 });
+      await adapter.connect();
+      const foreign = openForeignConnection(dbPath);
+      try {
+        const released = holdWriteLock(foreign, 600);
+        const startedAt = Date.now();
+
+        const outcomes = await Promise.allSettled(Array.from({ length: 5 }, (_, i) => adapter.set(`k${i}`, 'v')));
+
+        expect(outcomes.map((outcome) => outcome.status)).toEqual(Array(5).fill('rejected'));
+        expect(Date.now() - startedAt).toBeLessThan(300);
+        await released;
+      } finally {
+        foreign.close();
+        await adapter.disconnect();
+      }
+    });
+
+    it.each([
+      [
+        'SqliteKvStore',
+        (dbPath: string) => new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 10, busyTimeoutMs: 200 }),
+      ],
+      [
+        'SqliteEventStore',
+        (dbPath: string) => new SqliteEventStore({ path: dbPath, ttlCleanupIntervalMs: 10, busyTimeoutMs: 200 }),
+      ],
+    ])("runs %s's sweep of expired rows on the queue, so it neither blocks nor throws", async (_store, open) => {
+      const store = open(dbPath);
+      const kv = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+      kv.set('stale', 'v', 1);
+      const foreign = openForeignConnection(dbPath);
+      let longestGapMs = 0;
+      let lastTickAt = Date.now();
+      const timer = setInterval(() => {
+        longestGapMs = Math.max(longestGapMs, Date.now() - lastTickAt);
+        lastTickAt = Date.now();
+      }, 5);
+      try {
+        await holdWriteLock(foreign, 400);
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        expect(longestGapMs).toBeLessThan(150);
+        expect(kv.getDatabase().prepare("SELECT key FROM kv WHERE key = 'stale'").get()).toEqual(
+          store instanceof SqliteKvStore ? undefined : { key: 'stale' },
+        );
+      } finally {
+        clearInterval(timer);
+        foreign.close();
+        kv.close();
+        store.close();
+      }
+    });
+
     it('gives up with SQLITE_BUSY once busyTimeoutMs has passed', async () => {
       const adapter = new SqliteStorageAdapter({ path: dbPath, ttlCleanupIntervalMs: 0, busyTimeoutMs: 150 });
       await adapter.connect();
diff --git a/libs/storage-sqlite/src/__tests__/sqlite-storage.adapter.spec.ts b/libs/storage-sqlite/src/__tests__/sqlite-storage.adapter.spec.ts
index abaff589c..ce88b7d30 100644
--- a/libs/storage-sqlite/src/__tests__/sqlite-storage.adapter.spec.ts
+++ b/libs/storage-sqlite/src/__tests__/sqlite-storage.adapter.spec.ts
@@ -462,6 +462,13 @@ describe('SqliteStorageAdapter', () => {
       cleanup(externalPath);
     });
 
+    it('lets the operations already called finish before it closes the file', async () => {
+      const pending = [adapter.incr('counter'), adapter.set('k', 'v'), adapter.get('k')];
+      await adapter.disconnect();
+      expect(await Promise.all(pending)).toEqual([1, undefined, 'v']);
+      await expect(adapter.get('k')).rejects.toThrow(/not connected/i);
+    });
+
     it('is idempotent (second disconnect is a no-op)', async () => {
       const owned = new SqliteStorageAdapter({ path: tmpDbPath(), ttlCleanupIntervalMs: 0 });
       await owned.connect();
diff --git a/libs/storage-sqlite/src/sqlite-connection.ts b/libs/storage-sqlite/src/sqlite-connection.ts
index 6935c1515..700c0721e 100644
--- a/libs/storage-sqlite/src/sqlite-connection.ts
+++ b/libs/storage-sqlite/src/sqlite-connection.ts
@@ -21,6 +21,7 @@ const sharedByPath = new Map<string, SharedDatabase>();
 class SharedDatabase {
   private references = 0;
   private queue: Promise<unknown> = Promise.resolve();
+  private lastProgressAt = 0;
 
   constructor(
     readonly db: Database.Database,
@@ -42,24 +43,31 @@ class SharedDatabase {
 
   release(): void {
     if (--this.references > 0) return;
-    if (this.cacheKey) sharedByPath.delete(this.cacheKey);
+    if (this.cacheKey && sharedByPath.get(this.cacheKey) === this) sharedByPath.delete(this.cacheKey);
     this.db.close();
   }
 
   enqueue<T>(operation: () => T): Promise<T> {
-    const run = this.queue.then(() => this.retryWhileBusy(operation));
+    const calledAt = Date.now();
+    const run = this.queue.then(() => this.retryWhileBusy(operation, calledAt));
     this.queue = run.catch(() => undefined);
     return run;
   }
 
+  idle(): Promise<void> {
+    return this.queue.then(() => undefined);
+  }
+
   /** Waits for another process's lock with timers, not inside SQLite, so the event loop keeps running. */
-  private async retryWhileBusy<T>(operation: () => T): Promise<T> {
-    const deadline = Date.now() + this.busyTimeoutMs;
+  private async retryWhileBusy<T>(operation: () => T, calledAt: number): Promise<T> {
     for (let backoffMs = MIN_BACKOFF_MS; ; backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS)) {
       try {
-        return this.withoutBusyWait(operation);
+        const result = this.withoutBusyWait(operation);
+        this.lastProgressAt = Date.now();
+        return result;
       } catch (error: unknown) {
-        const remainingMs = deadline - Date.now();
+        // The busy timeout runs from the call, or from the last queued operation that got the lock if later.
+        const remainingMs = Math.max(calledAt, this.lastProgressAt) + this.busyTimeoutMs - Date.now();
         if (!isBusyError(error) || remainingMs <= 0) throw error;
         const jitteredMs = backoffMs / 2 + Math.random() * (backoffMs / 2);
         await new Promise((wake) => setTimeout(wake, Math.min(jitteredMs, remainingMs)));
@@ -98,6 +106,11 @@ export class SqliteConnection {
     return this.shared.enqueue(operation);
   }
 
+  /** Resolves once the operations queued so far have finished. */
+  idle(): Promise<void> {
+    return this.shared.idle();
+  }
+
   /** The connection closes once every store that acquired it has released it; a second call does nothing. */
   release(): void {
     if (this.released) return;
@@ -114,7 +127,7 @@ export function acquireConnection(
 ): SqliteConnection {
   const cacheKey = PRIVATE_PATHS.has(path) ? undefined : pathResolve(path);
   let shared = cacheKey ? sharedByPath.get(cacheKey) : undefined;
-  if (!shared) {
+  if (!shared?.db.open) {
     const busyTimeoutMs = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
     shared = new SharedDatabase(openDatabase(path, storeName, options), busyTimeoutMs, cacheKey);
     if (cacheKey) sharedByPath.set(cacheKey, shared);
diff --git a/libs/storage-sqlite/src/sqlite-event.store.ts b/libs/storage-sqlite/src/sqlite-event.store.ts
index a5c2db783..2ba88c832 100644
--- a/libs/storage-sqlite/src/sqlite-event.store.ts
+++ b/libs/storage-sqlite/src/sqlite-event.store.ts
@@ -79,13 +79,21 @@ export class SqliteEventStore implements EventStoreInterface {
     this.maxEvents = options.maxEvents ?? 10000;
     this.ttlMs = options.ttlMs ?? 300000;
 
-    withBusyRetry(() => this.initSchema());
-    this.prepareStatements();
+    try {
+      withBusyRetry(() => this.initSchema());
+      this.prepareStatements();
+    } catch (error) {
+      this.connection.release();
+      throw error;
+    }
 
-    // Periodic cleanup of expired events
+    // Periodic cleanup of expired events, queued so another process's lock does not block or throw
     const cleanupInterval = options.ttlCleanupIntervalMs ?? 60000;
     if (cleanupInterval > 0) {
-      this.cleanupTimer = setInterval(() => this.evictExpired(), cleanupInterval);
+      this.cleanupTimer = setInterval(
+        () => void this.connection.write(() => this.evictExpired()).catch(() => undefined),
+        cleanupInterval,
+      );
       if (this.cleanupTimer.unref) {
         this.cleanupTimer.unref();
       }
diff --git a/libs/storage-sqlite/src/sqlite-kv.store.ts b/libs/storage-sqlite/src/sqlite-kv.store.ts
index 44f8b68f2..69d01d7aa 100644
--- a/libs/storage-sqlite/src/sqlite-kv.store.ts
+++ b/libs/storage-sqlite/src/sqlite-kv.store.ts
@@ -56,13 +56,22 @@ export class SqliteKvStore {
       this.encryptionKey = deriveEncryptionKey(options.encryption.secret);
     }
 
-    withBusyRetry(() => this.initSchema());
-    this.prepareStatements();
+    try {
+      withBusyRetry(() => this.initSchema());
+      this.prepareStatements();
+    } catch (error) {
+      this.connection.release();
+      throw error;
+    }
 
     // Start periodic TTL cleanup
     const cleanupInterval = options.ttlCleanupIntervalMs ?? 60000;
     if (cleanupInterval > 0) {
-      this.cleanupTimer = setInterval(() => this.purgeExpired(), cleanupInterval);
+      // Queued, so a lock held by another process neither blocks the event loop nor throws from the timer.
+      this.cleanupTimer = setInterval(
+        () => void this.connection.write(() => this.purgeExpired()).catch(() => undefined),
+        cleanupInterval,
+      );
       // Allow the process to exit even if timer is running
       if (this.cleanupTimer.unref) {
         this.cleanupTimer.unref();
diff --git a/libs/storage-sqlite/src/sqlite-storage.adapter.ts b/libs/storage-sqlite/src/sqlite-storage.adapter.ts
index 3cfba8bc8..7f40d5342 100644
--- a/libs/storage-sqlite/src/sqlite-storage.adapter.ts
+++ b/libs/storage-sqlite/src/sqlite-storage.adapter.ts
@@ -61,7 +61,8 @@ export class SqliteStorageAdapter extends BaseStorageAdapter {
     // Only close the KV store if we own it. When an external SqliteKvStore was
     // injected, its owner is responsible for closing it (and may still be using
     // it via another adapter), so we leave the handle open.
-    if (this.ownsKvStore && this.kv) {
+    if (this.ownsKvStore) {
+      await this.connection.idle();
       this.kv.close();
     }
   }
diff --git a/libs/storage-sqlite/src/sqlite-task.store.ts b/libs/storage-sqlite/src/sqlite-task.store.ts
index 5f542166c..0d73d78e9 100644
--- a/libs/storage-sqlite/src/sqlite-task.store.ts
+++ b/libs/storage-sqlite/src/sqlite-task.store.ts
@@ -188,8 +188,13 @@ export class SqliteTaskStore implements TaskStoreInterface {
     }
     this.emitter.setMaxListeners(200);
 
-    withBusyRetry(() => this.initSchema());
-    this.prepareStatements();
+    try {
+      withBusyRetry(() => this.initSchema());
+      this.prepareStatements();
+    } catch (error) {
+      this.connection.release();
+      throw error;
+    }
 
     const cleanupInterval = options.ttlCleanupIntervalMs ?? 60_000;
     if (cleanupInterval > 0) {
diff --git a/libs/utils/src/storage/types.ts b/libs/utils/src/storage/types.ts
index ec374efc9..a095e05e4 100644
--- a/libs/utils/src/storage/types.ts
+++ b/libs/utils/src/storage/types.ts
@@ -547,10 +547,7 @@ export interface CloudflareKvAdapterOptions {
   keyPrefix?: string;
 }
 
-/**
- * SQLite adapter options (when type='sqlite'); the adapter comes from `@frontmcp/storage-sqlite`.
- * Processes on one machine that open the same file share its keys, counters and locks.
- */
+/** SQLite adapter options (type 'sqlite', from `@frontmcp/storage-sqlite`): processes on one file share its keys. */
 export interface SqliteAdapterOptions {
   /** Path to the database file; its directory is created if missing. */
   path: string;

From e8791e00b97e59ca1a58a55f56e154cae445f30c Mon Sep 17 00:00:00 2001
From: David Antoon <david@frontegg.com>
Date: Mon, 2 Nov 2026 12:20:18 +0200
Subject: [PATCH 4/6] fix(storage-sqlite): run ping() on the connection queue

ping() queried the database directly with the full busy timeout, so a commit
from another process in rollback-journal mode blocked the event loop for up
to busyTimeoutMs. It now waits on the queue with timers like every other
operation.

Also: the e2e worker helper resolves on close so the last stdout lines are
read; the lock example takes a unique token and releases it; the createStorage
lock snippets set fallback: 'error'; WAL backups use VACUUM INTO.
---
 .../e2e/helpers/workers.ts                    |  2 +-
 .../setup-sqlite/multi-process-storage.md     | 26 +++++++++++++------
 .../frontmcp-setup/references/setup-sqlite.md | 14 ++++++----
 .../src/__tests__/sqlite-connection.spec.ts   | 18 +++++++++++++
 .../src/sqlite-storage.adapter.ts             |  2 +-
 5 files changed, 47 insertions(+), 15 deletions(-)

diff --git a/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts b/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
index 5bf4c02d3..bb97a0c69 100644
--- a/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
+++ b/apps/e2e/demo-e2e-local-runtime/e2e/helpers/workers.ts
@@ -39,7 +39,7 @@ export function spawnWorker<Result>(script: string, env: Record<string, string>
 
   const exited = new Promise<number | null>((resolve, reject) => {
     child.once('error', reject);
-    child.once('exit', (code) => resolve(code));
+    child.once('close', (code) => resolve(code));
   });
 
   const result = exited.then((code) => {
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/multi-process-storage.md b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/multi-process-storage.md
index 0db090253..3193fd28e 100644
--- a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/multi-process-storage.md
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/multi-process-storage.md
@@ -23,20 +23,26 @@ yarn add @frontmcp/storage-sqlite better-sqlite3
 
 ```typescript
 // src/tools/claim-reindex.tool.ts
-import { SqliteStorageToken, Tool, ToolContext, z } from '@frontmcp/sdk';
+import { SqliteStorageToken, Tool, ToolContext } from '@frontmcp/sdk';
+import { randomUUID } from '@frontmcp/utils';
 
 @Tool({
   name: 'claim_reindex',
   description: 'Run the reindex in this process unless another process already holds it',
-  inputSchema: { runId: z.string() },
+  inputSchema: {},
 })
 export class ClaimReindexTool extends ToolContext {
-  async execute({ runId }: { runId: string }) {
+  async execute() {
     const storage = this.get(SqliteStorageToken);
-    await storage.set('lock:reindex', runId, { ifNotExists: true, ttlSeconds: 300 });
-    const holder = await storage.get('lock:reindex');
-    const runs = await storage.incr('reindex:claims');
-    return { claimed: holder === runId, claims: runs };
+    const token = randomUUID();
+    await storage.set('lock:reindex', token, { ifNotExists: true, ttlSeconds: 300 });
+    if ((await storage.get('lock:reindex')) !== token) return { claimed: false };
+    try {
+      // Reindex here, within the 300 s the lock lasts.
+      return { claimed: true, claims: await storage.incr('reindex:claims') };
+    } finally {
+      await storage.deleteIfEquals('lock:reindex', token);
+    }
   }
 }
 ```
@@ -64,7 +70,11 @@ export default class Server {}
 // scripts/report.ts: the same file from a script, without a server
 import { createStorage } from '@frontmcp/utils';
 
-const storage = await createStorage({ type: 'sqlite', sqlite: { path: '/var/lib/indexer/state.sqlite' } });
+const storage = await createStorage({
+  type: 'sqlite',
+  sqlite: { path: '/var/lib/indexer/state.sqlite' },
+  fallback: 'error',
+});
 console.log('claims so far:', await storage.get('indexer:reindex:claims'));
 await storage.disconnect();
 ```
diff --git a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
index 44fb79807..09571d23f 100644
--- a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
+++ b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
@@ -227,10 +227,10 @@ sqlite: {
 
 ### Choosing a journal mode
 
-| Mode                                | Readers and the writer                                                                   | Files                                                                     | Use it for                                                                |
-| ----------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| WAL (`walMode: true`, default)      | Readers never wait for the writer, and the writer never waits for readers                | `-wal` and `-shm` beside the database while it is open; back up all three | Almost everything, and any file several processes write to                |
-| Rollback journal (`walMode: false`) | The writer waits for readers to finish before it commits; readers wait during the commit | A `-journal` file only while a write commits                              | Mostly-read files with rare writes, or a filesystem without shared memory |
+| Mode                                | Readers and the writer                                                                   | Files                                                                                                  | Use it for                                                                |
+| ----------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| WAL (`walMode: true`, default)      | Readers never wait for the writer, and the writer never waits for readers                | `-wal` and `-shm` beside the database while it is open; back it up with `VACUUM INTO`, not a file copy | Almost everything, and any file several processes write to                |
+| Rollback journal (`walMode: false`) | The writer waits for readers to finish before it commits; readers wait during the commit | A `-journal` file only while a write commits                                                           | Mostly-read files with rare writes, or a filesystem without shared memory |
 
 WAL needs a local filesystem: never put a WAL database on NFS, SMB or another network mount. A file once switched to WAL stays in WAL for every process that opens it, so `walMode: false` on one process does not switch it back.
 
@@ -340,7 +340,11 @@ or create the storage yourself:
 ```typescript
 import { createStorage } from '@frontmcp/utils';
 
-const storage = await createStorage({ type: 'sqlite', sqlite: { path: '/var/lib/my-server/app.sqlite' } });
+const storage = await createStorage({
+  type: 'sqlite',
+  sqlite: { path: '/var/lib/my-server/app.sqlite' },
+  fallback: 'error', // a lock in process memory would not be shared
+});
 await storage.set('lock:reindex', process.pid.toString(), { ifNotExists: true, ttlSeconds: 60 });
 ```
 
diff --git a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
index 4fb830ca5..20d73dc92 100644
--- a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
+++ b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
@@ -322,5 +322,23 @@ describe('shared SQLite connections', () => {
         await adapter.disconnect();
       }
     });
+
+    it('pings without blocking the event loop while a commit locks readers out', async () => {
+      const adapter = new SqliteStorageAdapter({ path: dbPath, ttlCleanupIntervalMs: 0, walMode: false });
+      await adapter.connect();
+      const foreign = openForeignConnection(dbPath);
+      try {
+        foreign.exec('BEGIN EXCLUSIVE');
+        setTimeout(() => foreign.exec('COMMIT'), 100);
+        const startedAt = Date.now();
+
+        expect(await adapter.ping()).toBe(true);
+
+        expect(Date.now() - startedAt).toBeLessThan(1000);
+      } finally {
+        foreign.close();
+        await adapter.disconnect();
+      }
+    });
   });
 });
diff --git a/libs/storage-sqlite/src/sqlite-storage.adapter.ts b/libs/storage-sqlite/src/sqlite-storage.adapter.ts
index 7f40d5342..ffb82a3d8 100644
--- a/libs/storage-sqlite/src/sqlite-storage.adapter.ts
+++ b/libs/storage-sqlite/src/sqlite-storage.adapter.ts
@@ -71,7 +71,7 @@ export class SqliteStorageAdapter extends BaseStorageAdapter {
     if (!this.connected) return false;
     try {
       // A cheap no-op query to confirm the handle is alive.
-      this.kv.has('__frontmcp_ping__');
+      await this.connection.read(() => this.kv.has('__frontmcp_ping__'));
       return true;
     } catch {
       return false;

From 5ea8167a72035285d59fefe7e2834ef3fe3c0bd3 Mon Sep 17 00:00:00 2001
From: David Antoon <david@frontegg.com>
Date: Mon, 2 Nov 2026 13:05:25 +0200
Subject: [PATCH 5/6] fix(storage-sqlite): purge an expired key only while it
 is still expired

get() read an expired row and then deleted the key unconditionally, outside a
transaction, so a value another process wrote between the two statements was
deleted. The purge now deletes the row only if it is still expired.

Also: the WAL troubleshooting row no longer suggests walMode: false for an
existing WAL file.
---
 .../frontmcp-setup/references/setup-sqlite.md | 18 +++++++-------
 .../src/__tests__/sqlite-connection.spec.ts   | 24 +++++++++++++++++++
 libs/storage-sqlite/src/sqlite-kv.store.ts    |  7 ++++--
 3 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
index 09571d23f..97b26e721 100644
--- a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
+++ b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
@@ -481,15 +481,15 @@ The change in `src/main.ts`:
 
 ## Troubleshooting
 
-| Problem                                 | Cause                                                           | Solution                                                                                                                  |
-| --------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                    |
-| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall    |
-| `SQLITE_BUSY` errors                    | Another process held the write lock longer than `busyTimeoutMs` | Keep WAL mode on (`walMode: true`), keep transactions short, and raise `busyTimeoutMs` (default 5000)                     |
-| `Failed to persist session to SQLite`   | A session write waited longer than `busyTimeoutMs` for the lock | Raise `busyTimeoutMs`, or use Redis for many writer processes                                                             |
-| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                     |
-| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                 |
-| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated |
+| Problem                                 | Cause                                                           | Solution                                                                                                                      |
+| --------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                        |
+| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall        |
+| `SQLITE_BUSY` errors                    | Another process held the write lock longer than `busyTimeoutMs` | Keep WAL mode on (`walMode: true`), keep transactions short, and raise `busyTimeoutMs` (default 5000)                         |
+| `Failed to persist session to SQLite`   | A session write waited longer than `busyTimeoutMs` for the lock | Raise `busyTimeoutMs`, or use Redis for many writer processes                                                                 |
+| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                         |
+| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk; `walMode: false` only keeps a new file out of WAL, it does not switch an existing one back |
+| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated     |
 
 ## Examples
 
diff --git a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
index 20d73dc92..2ee5047b8 100644
--- a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
+++ b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
@@ -224,6 +224,30 @@ describe('shared SQLite connections', () => {
     });
   });
 
+  it('keeps the value another process writes between reading an expired key and purging it', () => {
+    const kv = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+    const foreign = openForeignConnection(dbPath);
+    try {
+      kv.set('lock', 'stale', -1);
+      const statements = (kv as unknown as { stmts: { get: Database.Statement } }).stmts;
+      const readRow = statements.get;
+      statements.get = {
+        get: (key: string) => {
+          const row = readRow.get(key);
+          foreign.prepare("INSERT OR REPLACE INTO kv (key, value, expires_at) VALUES (?, 'fresh', NULL)").run(key);
+          return row;
+        },
+      } as unknown as Database.Statement;
+
+      expect(kv.get('lock')).toBeNull();
+
+      expect(foreign.prepare('SELECT value FROM kv WHERE key = ?').get('lock')).toEqual({ value: 'fresh' });
+    } finally {
+      foreign.close();
+      kv.close();
+    }
+  });
+
   describe('a lock held by another process', () => {
     it('waits for it without blocking the event loop', async () => {
       const adapter = new SqliteStorageAdapter({ path: dbPath, ttlCleanupIntervalMs: 0 });
diff --git a/libs/storage-sqlite/src/sqlite-kv.store.ts b/libs/storage-sqlite/src/sqlite-kv.store.ts
index 69d01d7aa..5df090838 100644
--- a/libs/storage-sqlite/src/sqlite-kv.store.ts
+++ b/libs/storage-sqlite/src/sqlite-kv.store.ts
@@ -17,6 +17,7 @@ interface KvPreparedStatements {
   get: Database.Statement;
   set: Database.Statement;
   del: Database.Statement;
+  delExpired: Database.Statement;
   has: Database.Statement;
   keys: Database.Statement;
   keysPattern: Database.Statement;
@@ -95,6 +96,7 @@ export class SqliteKvStore {
       get: this.db.prepare('SELECT value, expires_at FROM kv WHERE key = ?'),
       set: this.db.prepare('INSERT OR REPLACE INTO kv (key, value, expires_at) VALUES (?, ?, ?)'),
       del: this.db.prepare('DELETE FROM kv WHERE key = ?'),
+      delExpired: this.db.prepare('DELETE FROM kv WHERE key = ? AND expires_at IS NOT NULL AND expires_at <= ?'),
       has: this.db.prepare('SELECT 1 FROM kv WHERE key = ? AND (expires_at IS NULL OR expires_at > ?)'),
       keys: this.db.prepare('SELECT key FROM kv WHERE (expires_at IS NULL OR expires_at > ?)'),
       keysPattern: this.db.prepare(
@@ -128,8 +130,9 @@ export class SqliteKvStore {
     if (!row) return null;
 
     // Check TTL
-    if (row.expires_at !== null && row.expires_at <= Date.now()) {
-      stmts.del.run(key);
+    const now = Date.now();
+    if (row.expires_at !== null && row.expires_at <= now) {
+      stmts.delExpired.run(key, now);
       return null;
     }
 

From db4b9bfc4837f9d6247b439053e2e0e8fa66ebe7 Mon Sep 17 00:00:00 2001
From: David Antoon <david@frontegg.com>
Date: Mon, 2 Nov 2026 13:25:17 +0200
Subject: [PATCH 6/6] fix(storage-sqlite): purge an expired key in ttl() only
 while it is still expired

ttl() had the same read-then-delete sequence as get(): a value another process
wrote between the two statements was deleted. It now uses the guarded purge.
---
 .../src/__tests__/sqlite-connection.spec.ts   | 52 +++++++++++--------
 libs/storage-sqlite/src/sqlite-kv.store.ts    |  5 +-
 2 files changed, 32 insertions(+), 25 deletions(-)

diff --git a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
index 2ee5047b8..309969cb5 100644
--- a/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
+++ b/libs/storage-sqlite/src/__tests__/sqlite-connection.spec.ts
@@ -224,29 +224,35 @@ describe('shared SQLite connections', () => {
     });
   });
 
-  it('keeps the value another process writes between reading an expired key and purging it', () => {
-    const kv = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
-    const foreign = openForeignConnection(dbPath);
-    try {
-      kv.set('lock', 'stale', -1);
-      const statements = (kv as unknown as { stmts: { get: Database.Statement } }).stmts;
-      const readRow = statements.get;
-      statements.get = {
-        get: (key: string) => {
-          const row = readRow.get(key);
-          foreign.prepare("INSERT OR REPLACE INTO kv (key, value, expires_at) VALUES (?, 'fresh', NULL)").run(key);
-          return row;
-        },
-      } as unknown as Database.Statement;
-
-      expect(kv.get('lock')).toBeNull();
-
-      expect(foreign.prepare('SELECT value FROM kv WHERE key = ?').get('lock')).toEqual({ value: 'fresh' });
-    } finally {
-      foreign.close();
-      kv.close();
-    }
-  });
+  it.each([
+    ['get', (kv: SqliteKvStore) => kv.get('lock'), null],
+    ['ttl', (kv: SqliteKvStore) => kv.ttl('lock'), -2],
+  ] as const)(
+    'keeps the value another process writes between %s reading an expired key and purging it',
+    (statement, read, expired) => {
+      const kv = new SqliteKvStore({ path: dbPath, ttlCleanupIntervalMs: 0 });
+      const foreign = openForeignConnection(dbPath);
+      try {
+        kv.set('lock', 'stale', -1);
+        const statements = (kv as unknown as { stmts: Record<string, Database.Statement> }).stmts;
+        const readRow = statements[statement];
+        statements[statement] = {
+          get: (key: string) => {
+            const row = readRow.get(key);
+            foreign.prepare("INSERT OR REPLACE INTO kv (key, value, expires_at) VALUES (?, 'fresh', NULL)").run(key);
+            return row;
+          },
+        } as unknown as Database.Statement;
+
+        expect(read(kv)).toBe(expired);
+
+        expect(foreign.prepare('SELECT value FROM kv WHERE key = ?').get('lock')).toEqual({ value: 'fresh' });
+      } finally {
+        foreign.close();
+        kv.close();
+      }
+    },
+  );
 
   describe('a lock held by another process', () => {
     it('waits for it without blocking the event loop', async () => {
diff --git a/libs/storage-sqlite/src/sqlite-kv.store.ts b/libs/storage-sqlite/src/sqlite-kv.store.ts
index 5df090838..1a24bc3b6 100644
--- a/libs/storage-sqlite/src/sqlite-kv.store.ts
+++ b/libs/storage-sqlite/src/sqlite-kv.store.ts
@@ -241,9 +241,10 @@ export class SqliteKvStore {
     if (!row) return -2;
     if (row.expires_at === null) return -1;
 
-    const remaining = row.expires_at - Date.now();
+    const now = Date.now();
+    const remaining = row.expires_at - now;
     if (remaining <= 0) {
-      stmts.del.run(key);
+      stmts.delExpired.run(key, now);
       return -2;
     }