Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(mcp-host): never create a database next to an orphan WAL

Alfredo Lopez36ee1986fa95
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 0e6daaf99..f0dd480d9 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.558",
+ "version": "0.1.559",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.558",
+ "version": "0.1.559",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 17bcdd016..c02498c8d 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.558",
+ "version": "0.1.559",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/db/worker/__tests__/openDatabase.test.ts b/mcp-host/src/db/worker/__tests__/openDatabase.test.ts
new file mode 100644
index 000000000..9bd3b740a
--- /dev/null
+++ b/mcp-host/src/db/worker/__tests__/openDatabase.test.ts
@@ -0,0 +1,81 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { DatabaseOpenRefused, openConversationDatabase } from '../openDatabase'
+
+const dirs: string[] = []
+function tempDir(): string {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'open-db-'))
+ dirs.push(dir)
+ return dir
+}
+
+afterEach(() => {
+ for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true })
+})
+
+function refusal(fn: () => unknown): DatabaseOpenRefused {
+ try {
+ fn()
+ } catch (err) {
+ if (err instanceof DatabaseOpenRefused) return err
+ throw err
+ }
+ throw new Error('expected DatabaseOpenRefused, the open succeeded')
+}
+
+describe('openConversationDatabase', () => {
+ it('creates the database and its parent directory when no journal exists', () => {
+ const dir = tempDir()
+ const dbPath = path.join(dir, 'nested', 'state.db')
+ const db = openConversationDatabase(dbPath)
+ db.exec('CREATE TABLE t (x INTEGER)')
+ db.close()
+ expect(fs.existsSync(dbPath)).toBe(true)
+ })
+
+ it('opens an existing database that has its journals', () => {
+ const dir = tempDir()
+ const dbPath = path.join(dir, 'state.db')
+ const writer = openConversationDatabase(dbPath)
+ writer.pragma('journal_mode = WAL')
+ writer.exec('CREATE TABLE t (x INTEGER); INSERT INTO t VALUES (7)')
+ // The WAL exists next to its main file while the writer is open.
+ expect(fs.existsSync(`${dbPath}-wal`)).toBe(true)
+ const reader = openConversationDatabase(dbPath)
+ expect(reader.prepare('SELECT x FROM t').get()).toEqual({ x: 7 })
+ reader.close()
+ writer.close()
+ })
+
+ it('never creates a database next to an orphan WAL and leaves the WAL byte-for-byte', () => {
+ const dir = tempDir()
+ const dbPath = path.join(dir, 'state.db')
+ const wal = Buffer.from('orphan wal bytes that must survive')
+ fs.writeFileSync(`${dbPath}-wal`, wal)
+
+ const err = refusal(() => openConversationDatabase(dbPath))
+ expect(err.code).toBe('ORPHAN_WAL')
+ expect(err.message).toContain(`${dbPath}-wal`)
+ expect(fs.existsSync(dbPath)).toBe(false)
+ expect(fs.readFileSync(`${dbPath}-wal`).equals(wal)).toBe(true)
+ expect(fs.readdirSync(dir)).toEqual(['state.db-wal'])
+ })
+
+ it('treats a lone SHM file as an orphan journal too', () => {
+ const dir = tempDir()
+ const dbPath = path.join(dir, 'state.db')
+ fs.writeFileSync(`${dbPath}-shm`, 'shm')
+ expect(refusal(() => openConversationDatabase(dbPath)).code).toBe('ORPHAN_WAL')
+ expect(fs.readdirSync(dir)).toEqual(['state.db-shm'])
+ })
+
+ it('counts a dangling journal symlink as a journal', () => {
+ const dir = tempDir()
+ const dbPath = path.join(dir, 'state.db')
+ fs.symlinkSync(path.join(dir, 'gone'), `${dbPath}-wal`)
+ expect(refusal(() => openConversationDatabase(dbPath)).code).toBe('ORPHAN_WAL')
+ expect(fs.existsSync(dbPath)).toBe(false)
+ })
+})
diff --git a/mcp-host/src/db/worker/dbWorker.ts b/mcp-host/src/db/worker/dbWorker.ts
index eb247dd95..ce3c57a1c 100644
--- a/mcp-host/src/db/worker/dbWorker.ts
+++ b/mcp-host/src/db/worker/dbWorker.ts
@@ -7,13 +7,13 @@
* blocks the event loop. Pushing all DB work into a worker keeps the main
* thread responsive for HTTP/SSE/timers.
*/
-import Database from 'better-sqlite3'
import * as fs from 'node:fs'
-import * as path from 'node:path'
import { parentPort, workerData } from 'node:worker_threads'
+import { logger } from '../../logger'
import { runMigrations } from '../migrate'
import { applyPragmas } from '../pragmas'
import { createDispatcher, dispatch } from './dispatcher'
+import { openConversationDatabase } from './openDatabase'
import {
HEARTBEAT_ID,
type HeartbeatPayload,
@@ -47,11 +47,7 @@ async function main(): Promise<void> {
throw new Error('dbWorker.ts: workerData.dbPath is required')
}
- // Ensure parent directory exists (tmpdir fallback in dev may need it).
- const dir = path.dirname(data.dbPath)
- fs.mkdirSync(dir, { recursive: true })
-
- const db = new Database(data.dbPath)
+ const db = openConversationDatabase(data.dbPath)
const pragmaResult = applyPragmas(db, { barrierMode: data.barrierMode === true })
if (!pragmaResult.walAvailable) {
parentPort.postMessage({
@@ -79,7 +75,7 @@ async function main(): Promise<void> {
try {
db.pragma('wal_checkpoint(PASSIVE)')
} catch (err) {
- console.warn('[dbWorker] PASSIVE checkpoint failed:', err)
+ logger.warn({ err: (err as Error).message }, '[dbWorker] PASSIVE checkpoint failed')
}
writesSinceCheckpoint = 0
}
@@ -128,6 +124,9 @@ async function main(): Promise<void> {
}
main().catch(err => {
+ // The main thread does not read `__fatal__`; this line is the only record
+ // of why the worker stopped (for example an orphan-WAL refusal).
+ logger.error({ err: (err as Error).message }, '[dbWorker] fatal; exiting with code 1')
if (parentPort) {
parentPort.postMessage({
id: '__fatal__',
diff --git a/mcp-host/src/db/worker/openDatabase.ts b/mcp-host/src/db/worker/openDatabase.ts
new file mode 100644
index 000000000..8486f860c
--- /dev/null
+++ b/mcp-host/src/db/worker/openDatabase.ts
@@ -0,0 +1,46 @@
+/**
+ * Opens the conversation database for the worker thread without creating one
+ * next to a surviving journal.
+ *
+ * A missing `state.db` with a `-wal` or `-shm` file beside it means the main
+ * file was moved or deleted while its journal stayed. Creating a new database
+ * there hides the history the journal belongs to, and SQLite discards that
+ * WAL on the first checkpoint, so the open is refused and the journal is left
+ * untouched.
+ */
+import Database from 'better-sqlite3'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+export class DatabaseOpenRefused extends Error {
+ readonly code = 'ORPHAN_WAL'
+
+ constructor(message: string) {
+ super(message)
+ this.name = 'DatabaseOpenRefused'
+ }
+}
+
+/** `lstat` that reports absence as `false` and every other error as thrown. */
+function entryExists(p: string): boolean {
+ try {
+ fs.lstatSync(p)
+ return true
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') return false
+ throw err
+ }
+}
+
+export function openConversationDatabase(dbPath: string): Database.Database {
+ if (!entryExists(dbPath)) {
+ const journals = ['-wal', '-shm'].map(s => `${dbPath}${s}`).filter(entryExists)
+ if (journals.length > 0) {
+ throw new DatabaseOpenRefused(
+ `refusing to create ${dbPath}: journal files exist without it (${journals.join(', ')})`
+ )
+ }
+ fs.mkdirSync(path.dirname(dbPath), { recursive: true })
+ }
+ return new Database(dbPath)
+}