auto-model-router 0.30.3 → 0.32.0

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.30.3",
+    "version": "0.32.0",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.30.3",
+      "version": "0.32.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -888,7 +888,9 @@ disk and back up the previous file to a timestamped `.bak`.
 ### Configuration file location
 
 - Router config: `$AUTO_MODEL_ROUTER_HOME/config.yml` (default `~/.auto-model-router/config.yml`).
-- Ledger DB: `$AUTO_MODEL_ROUTER_HOME/router.db` (SQLite, WAL).
+- Ledger DB: `$AUTO_MODEL_ROUTER_HOME/router.db` (SQLite, WAL), or a
+  `postgres://` URL in `ledger.path` when two replicas must share one store —
+  see [Sharing the store](#sharing-the-store).
 
 ### Environment variables
 
@@ -1158,13 +1160,41 @@ task needed, and `digest.maxOutputTokens` or `digest.model` is the lever.
 
 | Key | Default | Meaning |
 | --- | --- | --- |
-| `path` | `$AUTO_MODEL_ROUTER_HOME/router.db` | SQLite ledger path. |
+| `path` | `$AUTO_MODEL_ROUTER_HOME/router.db` | SQLite ledger path, or a `postgres://` URL. See [Sharing the store](#sharing-the-store). |
 | `blendWindowDays` | `7` | Window for the blended cost rate. |
 | `blendMinSamples` | `25` | Turns before the measured blend replaces the fallback. |
 | `fallbackBlend` | input `1.5`, output `7.5` | Pre-measurement blend (USD/Mtok) for omp's cost display. |
 | `conversationTtlMs` | `604800000` (7 d) | Drop conversation state untouched this long. |
 | `retentionDays` | `null` | Delete ledger rows — and the feedback keyed to them — older than this many days, checked at most hourly; `null` (the default) and `0` keep everything. The ledger grows about 2.5 MB a day under steady use. See [Data governance](#data-governance). |
 
+#### Sharing the store
+
+`ledger.path` accepts a `postgres://` URL as well as a SQLite path. One
+implementation serves both (`src/cost/ledger-sql.ts` over the dialect shim in
+`src/util/sql.ts`), and `tools/ledger-parity.ts` compares every signal and
+every report engine-against-engine on real rows.
+
+What moves to the shared store is what a second replica must see one copy of:
+
+- the turn rows a budget cap is counted from,
+- conversation routing memory (held tier, warm prompt-cache model, spend),
+- the agentdox context blocks.
+
+What stays local is the cache layer — the catalog payload, the benchmark
+feeds, the local eval scores, the once-a-day summary marker. With a Postgres
+ledger those live in `$AUTO_MODEL_ROUTER_HOME/cache.db`. A cache shared
+between replicas buys contention and nothing else, and `local_scores` belongs
+to the machine that measured it.
+
+Two replicas on one Postgres were verified end to end: a turn served by one
+replica leaves the next turn of that conversation on the same warm model when
+it lands on the other (`cache: keeping warm …`), and a replica that has served
+nothing refuses with `402 budget_exceeded` once the shared spend is past its
+cap — where the same cap against an empty store serves.
+
+A SQLite deployment is unchanged: the file is still migrated in place through
+the nineteen shipped versions, and both halves live in the one file.
+
 ### `redaction` — keep configured strings out of every request
 
 | Key | Default | Meaning |

package/omp-extension/router-configure.ts

@@ -51,7 +51,7 @@ import { loadConfig } from "../src/config/load.ts";
 import type { RouterConfig } from "../src/config/types.ts";
 import { buildUsageReport, renderUsageReport, type UsageReport } from "../src/cost/report.ts";
 import { buildDailySummary, renderDailySummary } from "../src/cost/summary.ts";
-import { openDb } from "../src/util/sqlite.ts";
+import { openSqlDb } from "../src/util/sql.ts";
 
 import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
 
@@ -180,11 +180,13 @@ async function loadReport(req: ReportRequest): Promise<UsageReport> {
 		if (!existsSync(cfg.ledger.path)) {
 			throw new Error(`router unreachable (${err instanceof Error ? err.message : String(err)}) and no ledger at ${cfg.ledger.path}`);
 		}
-		const db = openDb(cfg.ledger.path);
+		// Fallback read when the router is unreachable: straight at the ledger,
+		// through the handle that works whichever engine holds it.
+		const db = openSqlDb(cfg.ledger.path);
 		try {
-			return buildUsageReport(db, req);
+			return await buildUsageReport(db, req);
 		} finally {
-			db.close();
+			await db.close();
 		}
 	}
 }
@@ -343,11 +345,11 @@ async function summary(pi: ExtensionAPI, ctx: ExtensionContext, argText: string)
 		ctx.ui.notify(`router unreachable at ${routerBaseUrl()} and no ledger at ${cfg.ledger.path}`, "error");
 		return;
 	}
-	const db = openDb(cfg.ledger.path);
+	const db = openSqlDb(cfg.ledger.path);
 	try {
-		post(pi, `${renderDailySummary(buildDailySummary(db, { harnessId }))}\n(router unreachable: read from the ledger; spikes and the Ollama meter need the router)`);
+		post(pi, `${renderDailySummary(await buildDailySummary(db, { harnessId }))}\n(router unreachable: read from the ledger; spikes and the Ollama meter need the router)`);
 	} finally {
-		db.close();
+		await db.close();
 	}
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.30.3",
+  "version": "0.32.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/cli/config-cmd.ts

@@ -24,9 +24,9 @@ import { parse as parseYaml, stringify } from "yaml";
 import { loadConfig, resolveTilde } from "../config/load.ts";
 import { configInputSchema } from "../config/schema.ts";
 import type { RouterConfig } from "../config/types.ts";
-import { createLedger } from "../cost/ledger.ts";
+import { createSqlLedger } from "../cost/ledger-sql.ts";
+import { dialectOf, openSqlDb } from "../util/sql.ts";
 import type { BlendedRate } from "../cost/types.ts";
-import { openDb } from "../util/sqlite.ts";
 import { configOpts, flagString, type CliArgs } from "./args.ts";
 import {
 	mergeConfigPartial,
@@ -330,14 +330,15 @@ export function ompModelsPath(): string {
 export async function configCommand(args: CliArgs): Promise<void> {
 	const cfg = loadConfig(configOpts(args));
 
-	// Reading a blend must not create a database just by asking.
+	// Reading a blend must not create a store just by asking. A Postgres URL is
+	// always there to be asked; a file has to exist first.
 	let blend: BlendedRate | null = null;
-	if (existsSync(cfg.ledger.path)) {
-		const db = openDb(cfg.ledger.path);
+	if (dialectOf(cfg.ledger.path) === "postgres" || existsSync(cfg.ledger.path)) {
+		const db = openSqlDb(cfg.ledger.path);
 		try {
-			blend = createLedger(db, cfg).blendedRate(cfg.ledger.blendWindowDays);
+			blend = await createSqlLedger(db, cfg, { findModel: () => null }).blendedRate(cfg.ledger.blendWindowDays);
 		} finally {
-			db.close();
+			await db.close();
 		}
 	}
 

package/src/cli/explain.ts

@@ -12,11 +12,12 @@ import { existsSync } from "node:fs";
 
 import { createProviders } from "../server/providers.ts";
 import { loadConfig } from "../config/load.ts";
-import { createLedger } from "../cost/ledger.ts";
+import { createSqlLedger } from "../cost/ledger-sql.ts";
 import { createRouter } from "../router/index.ts";
 import { createConversationStore } from "../router/state.ts";
 import type { Candidate, Decision, Features, Rejection } from "../router/types.ts";
 import { openDb } from "../util/sqlite.ts";
+import { openSqlDb } from "../util/sql.ts";
 import { parseChatRequest } from "../wire/openai/request.ts";
 import { configOpts, flagString, type CliArgs } from "./args.ts";
 
@@ -130,10 +131,13 @@ export async function explainCommand(args: CliArgs): Promise<void> {
 	const req = parseChatRequest(body, new Headers());
 
 	const db = openDb(cfg.ledger.path);
+	// The conversation store reads through the engine-agnostic handle; the
+	// catalog and the ledger still use the bun:sqlite one. Same store.
+	const sdb = openSqlDb(cfg.ledger.path);
 	try {
-		const ledger = createLedger(db, cfg);
-		const { upstream, catalog } = createProviders(cfg, db);
-		const conversations = createConversationStore(db);
+		const ledger = createSqlLedger(sdb, cfg, { findModel: (slug: string) => catalog.find(slug) });
+		const { upstream, catalog } = createProviders(cfg, db, sdb);
+		const conversations = createConversationStore(sdb);
 		const router = createRouter({ config: cfg, catalog, ledger, conversations, upstream });
 
 		const decision = await router.route(req, { attempt: 0 });
@@ -143,7 +147,7 @@ export async function explainCommand(args: CliArgs): Promise<void> {
 			return;
 		}
 
-		const state = conversations.get(req.conversationKey);
+		const state = await conversations.get(req.conversationKey);
 		console.log(`request: ${req.messages.length} messages, ${req.tools.length} tools, model "${req.requestedModel}"`);
 		console.log(`conversation: ${req.conversationKey} (turn ${state?.turn ?? 0}, prior model ${state?.currentSlug ?? "none"})`);
 		console.log(
@@ -161,6 +165,7 @@ export async function explainCommand(args: CliArgs): Promise<void> {
 		renderDecision(decision);
 		console.log("\n(no completion was dispatched; nothing was billed)");
 	} finally {
+		await sdb.close();
 		db.close();
 	}
 }

package/src/cli/export.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync } from "node:fs";
-import { Database } from "bun:sqlite";
+import { openSqlDb } from "../util/sql.ts";
 import { loadConfig } from "../config/load.ts";
 import { exportCsv, exportRows } from "../cost/views.ts";
 import { configOpts, flagInt, flagString, type CliArgs } from "./args.ts";
@@ -18,12 +18,13 @@ export async function exportCommand(args: CliArgs): Promise<void> {
 		process.stdout.write(args.flags.has("json") ? "[]\n" : exportCsv([]));
 		return;
 	}
-	// Read-only: an export must never create or migrate the ledger.
-	const db = new Database(cfg.ledger.path, { readonly: true });
+	// The shim opens the ledger wherever it lives; an export must never create
+	// or migrate it, so nothing here calls migrateLedger.
+	const db = openSqlDb(cfg.ledger.path);
 	try {
-		const rows = exportRows(db, Date.now() - days * 86_400_000, harness === "" ? null : harness.split(",").map((s) => s.trim()).filter((s) => s !== ""));
+		const rows = await exportRows(db, Date.now() - days * 86_400_000, harness === "" ? null : harness.split(",").map((s) => s.trim()).filter((s) => s !== ""));
 		process.stdout.write(args.flags.has("json") ? `${JSON.stringify(rows, null, 2)}\n` : exportCsv(rows));
 	} finally {
-		db.close();
+		await db.close();
 	}
 }

package/src/cli/models.ts

@@ -7,21 +7,19 @@
  * command's whole value is that it cannot lie about what would be chosen.
  */
 
-import { existsSync } from "node:fs";
 import type { Database } from "bun:sqlite";
 
 import { createProviders } from "../server/providers.ts";
 import { effectiveQualityFloor, tierPlanFor } from "../router/tier-plan.ts";
 import { loadConfig } from "../config/load.ts";
 import type { QualityAxis, RouterConfig } from "../config/types.ts";
-import { createLedger } from "../cost/ledger.ts";
-import type { Ledger } from "../cost/types.ts";
 import { buildCandidates } from "../router/candidates.ts";
 import { classifyTask } from "../router/classify.ts";
 import { extractFeatures } from "../router/features.ts";
 import { TIER_ORDER, type Candidate, type Rejection, type Tier } from "../router/types.ts";
 import { estimatePromptTokens } from "../tokens/estimate.ts";
 import { openDb } from "../util/sqlite.ts";
+import { openSqlDb } from "../util/sql.ts";
 import { parseChatRequest } from "../wire/openai/request.ts";
 import { configOpts, flagInt, flagString, type CliArgs } from "./args.ts";
 
@@ -153,13 +151,18 @@ export async function modelsCommand(args: CliArgs): Promise<void> {
 
 	// Reuse the on-disk catalog cache when present so a survey costs no network.
 	const db: Database = openDb(cfg.ledger.path);
-	const ledger: Ledger | null = existsSync(cfg.ledger.path) ? createLedger(db, cfg) : null;
+	// The engine-agnostic handle exists only to satisfy the providers' calibration
+	// store; a survey reads the catalog and nothing else.
+	const sqlDb = openSqlDb(cfg.ledger.path);
+	// A measured token ratio would change the estimate by a few percent and cost a
+	// read per survey; the family default is what a cold router uses anyway.
+	const ledgerRatio = null;
 	try {
-		const { catalog } = createProviders(cfg, db);
+		const { catalog } = createProviders(cfg, db, sqlDb);
 		const snapshot = await catalog.get();
 
 		const req = syntheticRequest();
-		const promptTokens = estimatePromptTokens(req, "gpt", ledger);
+		const promptTokens = estimatePromptTokens(req, "gpt", ledgerRatio);
 		const features = extractFeatures(req, promptTokens);
 
 		const reports: TierReport[] = tiers.map((tier) => {
@@ -172,7 +175,6 @@ export async function modelsCommand(args: CliArgs): Promise<void> {
 				tier,
 				task,
 				snapshot,
-				ledger,
 				cfg,
 				expectedCompletionTokens: EXPECTED_COMPLETION_TOKENS,
 				warmSlug: null,
@@ -233,6 +235,7 @@ export async function modelsCommand(args: CliArgs): Promise<void> {
 		console.log(`survey request: ${promptTokens} estimated prompt tokens, ${req.tools.length} tools offered`);
 		for (const report of reports) renderTier(report, limit);
 	} finally {
+		await sqlDb.close();
 		db.close();
 	}
 }

package/src/cli/report.ts

@@ -10,6 +10,7 @@ import { loadConfig } from "../config/load.ts";
 import { createCatalog } from "../catalog/openrouter-catalog.ts";
 import { baselinePrices, buildUsageReport, renderUsageReport } from "../cost/report.ts";
 import { openDb } from "../util/sqlite.ts";
+import { openSqlDb } from "../util/sql.ts";
 import { configOpts, flagInt, flagString, type CliArgs } from "./args.ts";
 
 export async function reportCommand(args: CliArgs): Promise<void> {
@@ -28,15 +29,19 @@ export async function reportCommand(args: CliArgs): Promise<void> {
 	}
 
 	const db = openDb(cfg.ledger.path);
+	// The catalog cache is read through the bun:sqlite handle; the report reads
+	// through the engine-agnostic one. Same store, two readers.
+	const sdb = openSqlDb(cfg.ledger.path);
 	try {
 		// Baseline prices from the cached catalog: no network for a report.
 		const dead = { dispatch: () => Promise.reject(new Error("offline")), complete: () => Promise.reject(new Error("offline")), fetchModels: () => Promise.reject(new Error("offline")), fetchModelsForUser: () => Promise.reject(new Error("offline")) };
 		const snapshot = createCatalog(cfg, dead, db).peek();
 		const baselines = baselinePrices(cfg.report.baselines, (s) => snapshot?.models.find((m) => m.slug === s));
-		const report = buildUsageReport(db, { windowDays: days, harnessId, baselines });
+		const report = await buildUsageReport(sdb, { windowDays: days, harnessId, baselines });
 		if (args.flags.has("json")) console.log(JSON.stringify(report, null, 2));
 		else console.log(renderUsageReport(report));
 	} finally {
+		await sdb.close();
 		db.close();
 	}
 }

package/src/cli/stats.ts

@@ -1,9 +1,8 @@
 import { existsSync } from "node:fs";
-import type { Database } from "bun:sqlite";
 import { loadConfig } from "../config/load.ts";
-import { createLedger } from "../cost/ledger.ts";
+import { createSqlLedger } from "../cost/ledger-sql.ts";
 import { computeStats, type RouterStats } from "../server/http.ts";
-import { openDb } from "../util/sqlite.ts";
+import { openSqlDb, type SqlDb } from "../util/sql.ts";
 import { configOpts, flagInt, type CliArgs } from "./args.ts";
 
 function usd(v: number): string {
@@ -38,11 +37,12 @@ export async function statsCommand(args: CliArgs): Promise<void> {
 	const cfg = loadConfig(configOpts(args));
 
 	// A stats query must not create the ledger file just by looking.
-	let db: Database | null = null;
+	let db: SqlDb | null = null;
 	let stats: RouterStats;
 	if (existsSync(cfg.ledger.path)) {
-		db = openDb(cfg.ledger.path);
-		stats = computeStats(createLedger(db, cfg), { windowDays: days });
+		db = openSqlDb(cfg.ledger.path);
+		// No catalog here, so rows cannot be re-priced; stats only read.
+		stats = await computeStats(createSqlLedger(db, cfg, { findModel: () => null }), { windowDays: days });
 	} else {
 		stats = {
 			generatedAtMs: Date.now(),
@@ -64,6 +64,6 @@ export async function statsCommand(args: CliArgs): Promise<void> {
 		if (args.flags.has("json")) console.log(JSON.stringify(stats, null, 2));
 		else renderStats(stats);
 	} finally {
-		db?.close();
+		await db?.close();
 	}
 }

package/src/config/load.ts

@@ -17,6 +17,15 @@ export function resolveTilde(p: string): string {
 	return p;
 }
 
+/**
+ * The router's own directory: config, the local cache database, and the
+ * default ledger file. One resolver so a caller that needs a sibling file
+ * lands in the same place `loadConfig` reads from.
+ */
+export function routerHome(): string {
+	return resolveTilde(process.env.AUTO_MODEL_ROUTER_HOME ?? "~/.auto-model-router");
+}
+
 function isPlainObject(v: unknown): v is Record<string, unknown> {
 	return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -68,7 +77,7 @@ export type DeepPartial<T> = T extends readonly unknown[] | Date | RegExp
  * fail at dispatch time.
  */
 export function loadConfig(opts?: { path?: string; overrides?: DeepPartial<RouterConfig> }): RouterConfig {
-	const home = resolveTilde(process.env.AUTO_MODEL_ROUTER_HOME ?? "~/.auto-model-router");
+	const home = routerHome();
 
 	// Config file, when present.
 	const filePath = opts?.path !== undefined

package/src/config/types.ts

@@ -719,7 +719,16 @@ export interface ProfileConfig {
 }
 
 export interface LedgerConfig {
-	/** SQLite path. Defaults to `$AUTO_MODEL_ROUTER_HOME/router.db`. */
+	/**
+	 * Where the ledger lives: a SQLite path (default
+	 * `$AUTO_MODEL_ROUTER_HOME/router.db`), or a `postgres://` URL for a store
+	 * two replicas share. The shared store holds what correctness depends on
+	 * being one copy — the turn rows a cap is counted from, conversation
+	 * routing memory, and the context blocks. The local caches (catalog
+	 * payloads, benchmark feeds, the summary marker) stay in a SQLite file
+	 * beside the config either way: a cache is a per-process convenience, and
+	 * sharing one would only add contention.
+	 */
 	path: string;
 	/** Window for the blended rate published to omp, days. */
 	blendWindowDays: number;

package/src/context/bridge.ts

@@ -119,7 +119,7 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 		async resolve(input) {
 			if (input.scope === "") return null;
 
-			const pinned = input.pinnedVersion === null ? null : store.get(input.pinnedVersion);
+			const pinned = input.pinnedVersion === null ? null : await store.get(input.pinnedVersion);
 			if (!shouldRefresh(input, pinned) && pinned !== null) {
 				// Carry the conversation's own pin time forward, so the TTL keeps
 				// counting from its last real refresh rather than resetting to
@@ -163,7 +163,7 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 			const version = sha256Hex(block).slice(0, 32);
 			const pin: ContextPin = { version, block, fetchedAtMs: Date.now() };
 			try {
-				store.put(input.scope, pin);
+				await store.put(input.scope, pin);
 			} catch (err) {
 				log.debug("context block persist failed", { error: err instanceof Error ? err.message : String(err) });
 			}
@@ -215,11 +215,11 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 			queued++;
 			queue = queue
 				.then(async () => {
-					let sessionId = store.sessionFor(rec.conversationKey);
+					let sessionId = await store.sessionFor(rec.conversationKey);
 					if (sessionId === null) {
 						sessionId = await client.createSession(rec.scope, rec.title);
 						if (sessionId === null) return;
-						store.bindSession(rec.conversationKey, rec.scope, sessionId);
+						await store.bindSession(rec.conversationKey, rec.scope, sessionId);
 					}
 					// Model attribution rides on refs, which agentdox already carries
 					// per message. This is what makes the transcript newly useful:
@@ -245,8 +245,8 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 			await queue;
 		},
 
-		pruneBlocks(maxAgeMs: number) {
-			return store.prune(maxAgeMs);
+		async pruneBlocks(maxAgeMs: number) {
+			return await store.prune(maxAgeMs);
 		},
 
 		close() {
@@ -263,7 +263,7 @@ export function createDisabledBridge(): ContextBridge {
 		resolve: async () => null,
 		recordTurn: () => {},
 		flush: async () => {},
-		pruneBlocks: () => 0,
+		pruneBlocks: async () => 0,
 		close: () => {},
 	};
 }

package/src/context/index.ts

@@ -4,7 +4,7 @@
  * reconfigurable, so those settings can change while the router runs.
  */
 
-import type { Database } from "bun:sqlite";
+import type { SqlDb } from "../util/sql.ts";
 
 import type { RouterConfig } from "../config/types.ts";
 import { createLogger } from "../util/log.ts";
@@ -35,7 +35,7 @@ export interface ReloadableContextBridge extends ContextBridge {
  * restart. The block store is the database, not the bridge, so a rebuild keeps
  * every pinned block and session binding.
  */
-export function createBridgeFromConfig(cfg: RouterConfig, db: Database): ReloadableContextBridge {
+export function createBridgeFromConfig(cfg: RouterConfig, db: SqlDb): ReloadableContextBridge {
 	let inner = buildBridge(cfg, db);
 	return {
 		get enabled() {
@@ -58,7 +58,7 @@ export function createBridgeFromConfig(cfg: RouterConfig, db: Database): Reloada
 	};
 }
 
-function buildBridge(cfg: RouterConfig, db: Database): ContextBridge {
+function buildBridge(cfg: RouterConfig, db: SqlDb): ContextBridge {
 	const c = cfg.context;
 	if (!c.enabled || c.baseUrl === "" || c.token === "") return createDisabledBridge();
 	const log = createLogger(cfg.logLevel);

package/src/context/store.ts

@@ -7,85 +7,68 @@
  * a conversation was already using — OpenRouter's prompt cache outlives our
  * process, and re-fetching would needlessly change the prefix.
  *
- * Tables are created by `util/sqlite.ts`, the single migration path.
+ * Tables are created by the store's migration (`util/schema.ts`).
  */
 
-import type { Database, Statement } from "bun:sqlite";
+import { num, type SqlDb } from "../util/sql.ts";
 
 import type { ContextBlockStore, ContextPin } from "./types.ts";
 
 interface BlockRow {
 	version: string;
 	block: string;
-	fetched_at_ms: number;
+	fetched_at_ms: unknown;
 }
 
-interface SessionRow {
-	session_id: string;
-}
 
-export function createContextStore(db: Database): ContextBlockStore {
-	// Hoisted: these run on the turn hot path.
-	const selectBlock: Statement<BlockRow, [string]> = db.query(
-		"SELECT version, block, fetched_at_ms FROM context_blocks WHERE version = ?",
-	);
-	const insertBlock = db.query(`
-		INSERT INTO context_blocks (version, scope, block, fetched_at_ms)
-		VALUES ($version, $scope, $block, $fetchedAtMs)
-		ON CONFLICT(version) DO UPDATE SET fetched_at_ms = excluded.fetched_at_ms
-	`);
-	const selectSession: Statement<SessionRow, [string]> = db.query(
-		"SELECT session_id FROM agentdox_sessions WHERE conversation_key = ?",
-	);
-	const insertSession = db.query(`
-		INSERT INTO agentdox_sessions (conversation_key, scope, session_id, created_at_ms)
-		VALUES ($key, $scope, $sessionId, $createdAtMs)
-		ON CONFLICT(conversation_key) DO UPDATE SET session_id = excluded.session_id
-	`);
-	// Age alone is the wrong test: a block older than the staleness TTL may still
-	// be PINNED by a live conversation, and deleting it forces that conversation
-	// to refetch and re-inject different bytes — a prompt-cache miss caused by
-	// housekeeping. Blocks are content-addressed and shared, so the safe set is
-	// "old AND referenced by no conversation".
-	const deleteStale: Statement<unknown, [number]> = db.query(`
-		DELETE FROM context_blocks
-		WHERE fetched_at_ms < ?
-		  AND version NOT IN (SELECT context_version FROM conversations WHERE context_version IS NOT NULL)
-	`);
+export function createContextStore(db: SqlDb): ContextBlockStore {
+	const { sql } = db;
 
 	return {
-		get(version) {
-			const row = selectBlock.get(version);
+		async get(version) {
+			const row = await db.one<BlockRow>(
+				"SELECT version, block, fetched_at_ms FROM context_blocks WHERE version = $version",
+				{ version },
+			);
 			if (row === null) return null;
-			return { version: row.version, block: row.block, fetchedAtMs: row.fetched_at_ms };
+			return { version: row.version, block: row.block, fetchedAtMs: num(row.fetched_at_ms) };
 		},
 
-		put(scope, pin: ContextPin) {
-			insertBlock.run({
-				$version: pin.version,
-				$scope: scope,
-				$block: pin.block,
-				$fetchedAtMs: pin.fetchedAtMs,
-			});
+		async put(scope, pin: ContextPin) {
+			await sql`
+				INSERT INTO context_blocks (version, scope, block, fetched_at_ms)
+				VALUES (${pin.version}, ${scope}, ${pin.block}, ${pin.fetchedAtMs})
+				ON CONFLICT (version) DO UPDATE SET fetched_at_ms = excluded.fetched_at_ms`;
 		},
 
-		sessionFor(conversationKey) {
-			const row = selectSession.get(conversationKey);
+		async sessionFor(conversationKey) {
+			const row = await db.one<{ session_id: string }>(
+				"SELECT session_id FROM agentdox_sessions WHERE conversation_key = $key",
+				{ key: conversationKey },
+			);
 			return row === null ? null : row.session_id;
 		},
 
-		bindSession(conversationKey, scope, sessionId) {
-			insertSession.run({
-				$key: conversationKey,
-				$scope: scope,
-				$sessionId: sessionId,
-				$createdAtMs: Date.now(),
-			});
+		async bindSession(conversationKey, scope, sessionId) {
+			await sql`
+				INSERT INTO agentdox_sessions (conversation_key, scope, session_id, created_at_ms)
+				VALUES (${conversationKey}, ${scope}, ${sessionId}, ${Date.now()})
+				ON CONFLICT (conversation_key) DO UPDATE SET session_id = excluded.session_id`;
 		},
 
-		prune(maxAgeMs) {
-			const res = deleteStale.run(Date.now() - maxAgeMs) as unknown as { changes?: number };
-			return res.changes ?? 0;
+		async prune(maxAgeMs) {
+			// Age alone is the wrong test: a block older than the staleness TTL may
+			// still be PINNED by a live conversation, and deleting it forces that
+			// conversation to refetch and re-inject different bytes — a prompt-cache
+			// miss caused by housekeeping. Blocks are content-addressed and shared,
+			// so the safe set is "old AND referenced by no conversation". With a
+			// shared store that now means no conversation on ANY replica.
+			const deleted = (await sql`
+				DELETE FROM context_blocks
+				WHERE fetched_at_ms < ${Date.now() - maxAgeMs}
+				  AND version NOT IN (SELECT context_version FROM conversations WHERE context_version IS NOT NULL)
+				RETURNING version`) as { version: string }[];
+			return deleted.length;
 		},
 	};
 }

package/src/context/types.ts

@@ -110,22 +110,23 @@ export interface ContextBridge {
 	 * content-addressed and shared, so nothing else reclaims them — without this
 	 * the table grows for the life of the install.
 	 */
-	pruneBlocks(maxAgeMs: number): number;
+	pruneBlocks(maxAgeMs: number): Promise<number>;
 	close(): void;
 }
 
 /** Content-addressed store of fetched blocks, so a restart keeps a warm prefix. */
+/** Asynchronous throughout: the store may be a shared database, not a file. */
 export interface ContextBlockStore {
-	get(version: string): ContextPin | null;
-	put(scope: string, pin: ContextPin): void;
+	get(version: string): Promise<ContextPin | null>;
+	put(scope: string, pin: ContextPin): Promise<void>;
 	/** agentdox session id previously opened for a conversation. */
-	sessionFor(conversationKey: string): string | null;
-	bindSession(conversationKey: string, scope: string, sessionId: string): void;
+	sessionFor(conversationKey: string): Promise<string | null>;
+	bindSession(conversationKey: string, scope: string, sessionId: string): Promise<void>;
 	/**
 	 * Drops blocks older than `maxAgeMs` that NO conversation still pins.
 	 * Returns the number removed. Referenced blocks are kept regardless of age:
 	 * deleting one would force a live conversation to refetch and re-inject
 	 * different bytes, turning housekeeping into a prompt-cache miss.
 	 */
-	prune(maxAgeMs: number): number;
+	prune(maxAgeMs: number): Promise<number>;
 }