fix: coordinate sqlite index writers

Implement the full ADR-0006 plan: three-layer separation of transaction
correctness, retry policy, and cross-process writer coordination.

Layer 1 — scripts/tx.ts (transaction correctness):
- runWriteTransaction executes work exactly once; no internal retry.
- BEGIN IMMEDIATE takes the write lock up front (avoids SQLITE_BUSY_SNAPSHOT).
- Guarded rollback: checks inTransaction() via adapter before attempting
  ROLLBACK; never masks the primary exception.
- WriteTxDiagnostics attached to errors: phase, code, label,
  rollbackSucceeded, rollbackError, transactionActive.
- Binding adapters (betterSqliteTransactionAdapter, nodeSqliteTransactionAdapter)
  mapping better-sqlite3's `.inTransaction` and node:sqlite's `.isTransaction`.
- configureConnection centralizes WAL + synchronous + busy_timeout.

Layer 2 — scripts/write-coordinator.ts (retry policy):
- runRetryableWriteTransaction: bounded retry with total time budget.
- Only retries when the transaction confirmed ended (transactionActive=false)
  and the error is SQLITE_BUSY during work/commit phase.
- BEGIN-phase BUSY = abort entire build (isBeginBusyFailure); the caller
  returns `{ deferred: true, reason: 'writer_busy' }` instead of waiting.
- hasUnusableTransaction detects a still-active transaction after failure;
  aborts the build immediately, never retries.

Layer 3 — scripts/writer-lease.ts (cross-process coordination):
- acquireWriterLease: dedicated writer.lock.sqlite with busy_timeout=0 +
  BEGIN IMMEDIATE. Non-blocking attempt; bounded wait with retryDelayMs.
- writerLockPathFor derives lock path from the target DB path.
- Lease held for the entire build; released on completion or failure.
- Lock DB uses DELETE journal (not WAL); crash/close auto-releases.
- All consumers obey: skill acquires at build start (returns deferred if
  unavailable); app daemon (via worker) acquires for its build cycle.

Build semantics changes:
- affectedSessionIds updated only after successful commit.
- BuildIndexResult gains skipped/skippedFiles for observability.
- Skill finalize failure now fails the build (was silently warned).
- Checkpoint changed to PASSIVE (TRUNCATE reserved for maintenance/exit).
- Skill buildIndex returns { deferred, reason } on lease contention;
  indexer-service reschedules the build (deferredRetryMs) without publishing
  a heartbeat (so the build-deferred state is visible to cross-process
  arbitration).
- Service publishes heartbeat immediately on start() for correct arbitration.

Tests:
- tests/write-transaction.test.mjs: single-shot execution, diagnostics
  propagation, auto-rolled-back transaction detected, rollback failure
  captured as metadata, BEGIN IMMEDIATE semantics.
- tests/writer-lease.test.mjs: acquire/release, contention returns null,
  bounded wait with release during budget.
- tests/app-writer-lease.test.mjs: better-sqlite3 adapter integration.
- tests/app-rollback-guard.test.mjs: rewritten — transient BUSY recovered
  by coordinator, persistent BUSY skips file, begin-busy aborts build,
  live-transaction aborts build, phantom affectedSessionIds prevented.
- tests/daemon-arbitration.test.mjs: skill defers to fresh app heartbeat,
  builds when heartbeat is stale.
- tests/app-indexer-service.test.mjs: new cases for deferred-retry
  scheduling and immediate heartbeat on start.
- app/tests/electron-concurrency.mjs + child: dual-child IPC structure for
  real better-sqlite3 contention (holder acquires lock → build child starts
  → delayed release → result collected; persistent contention bounded).

ADR-0006 updated to reflect the implemented design.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/app-indexer-service.test.mjs

@@ -73,6 +73,34 @@ test('indexer service runs one pending build after an in-flight build finishes',
   assert.deepEqual(calls, ['first', 'pending']);
 });
 
+test('indexer service reschedules a writer-lease deferral without publishing a heartbeat', async () => {
+  const timers = manualTimers();
+  const calls = [];
+  let heartbeats = 0;
+  const service = createIndexerService({
+    buildIndex: async ({ reason, changedPaths }) => {
+      calls.push({ reason, changedPaths });
+      return calls.length === 1 ? { deferred: true, reason: 'writer_busy' } : { deferred: false };
+    },
+    watchProjects: () => null,
+    writeHeartbeat: () => { heartbeats += 1; },
+    timers,
+    stabilityMs: 0,
+  });
+
+  await service.runBuildNow('watch', ['project/session.jsonl']);
+  assert.equal(heartbeats, 0);
+  assert.equal(calls.length, 1);
+
+  timers.flush();
+  await service.idle();
+  assert.deepEqual(calls, [
+    { reason: 'watch', changedPaths: ['project/session.jsonl'] },
+    { reason: 'writer-lease', changedPaths: ['project/session.jsonl'] },
+  ]);
+  assert.equal(heartbeats, 1);
+});
+
 test('indexer service does not log a build cancelled by a service stop', async () => {
   const timers = manualTimers();
   const warnings = [];
@@ -160,6 +188,22 @@ test('indexer service retries watcher setup when the projects directory is missi
   assert.equal(attempts, 2);
 });
 
+test('indexer service publishes daemon ownership as soon as it starts', () => {
+  const timers = manualTimers();
+  let heartbeats = 0;
+  const service = createIndexerService({
+    buildIndex: async () => ({ deferred: false }),
+    watchProjects: () => null,
+    writeHeartbeat: () => { heartbeats += 1; },
+    timers,
+    stabilityMs: 0,
+  });
+
+  service.start({ buildOnStart: false });
+  assert.equal(heartbeats, 1);
+  service.stop();
+});
+
 test('indexer service watches Claude JSON files through chokidar', async () => {
   const projectsDir = mkdtempSync(join(tmpdir(), 'obelisk-chokidar-projects-'));
   const timers = manualTimers();

tests/app-indexer.test.mjs

@@ -31,7 +31,7 @@ class TestDatabase {
   }
 }
 
-test('app indexer builds the Obelisk database from Claude JSONL and records app heartbeat', () => {
+test('app indexer records build success without claiming daemon ownership', () => {
   const home = mkdtempSync(join(tmpdir(), 'obelisk-app-indexer-'));
   const claudeDir = join(home, '.claude');
   const projectDir = join(claudeDir, 'projects', '-tmp-obelisk-app');
@@ -57,7 +57,7 @@ test('app indexer builds the Obelisk database from Claude JSONL and records app
   assert.deepEqual(firstBuild.affectedSessionIds, [sessionId]);
   assert.equal(firstBuild.ftsRebuilt, true);
   assert.equal(db.prepare("SELECT uuid FROM messages_fts WHERE messages_fts MATCH 'hello'").get().uuid, 'msg-app-1');
-  assert.equal(db.prepare("SELECT jsonl_path FROM index_state WHERE jsonl_path='__app_heartbeat__'").get().jsonl_path, '__app_heartbeat__');
+  assert.equal(db.prepare("SELECT jsonl_path FROM index_state WHERE jsonl_path='__app_heartbeat__'").get(), undefined);
   assert.equal(db.prepare("SELECT jsonl_path FROM index_state WHERE jsonl_path='__app_last_successful_build__'").get().jsonl_path, '__app_last_successful_build__');
   assert.equal(db.prepare('SELECT project_path FROM sessions WHERE id=?').get(sessionId).project_path, '/tmp/obelisk-app');
   db.close();

tests/app-main-settings.test.mjs

@@ -7,7 +7,27 @@ import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+import { acquireWriterLease } from '../scripts/writer-lease.ts';
+
 const require = createRequire(import.meta.url);
+const { DatabaseSync } = require('node:sqlite');
+
+class SqliteCompatDatabase {
+  constructor(dbFile) {
+    this.db = new DatabaseSync(dbFile);
+  }
+  pragma(statement) { this.db.exec(`PRAGMA ${statement}`); }
+  exec(sql) { return this.db.exec(sql); }
+  close() { return this.db.close(); }
+  prepare(sql) {
+    const stmt = this.db.prepare(sql);
+    return {
+      all: (...params) => stmt.all(...params),
+      get: (...params) => stmt.get(...params),
+      run: (...params) => stmt.run(...params),
+    };
+  }
+}
 
 // The app main process is now an ES module. It runs side-effectfully on import
 // (registers ipcMain handlers, opens windows, etc.) and has no exports, so we
@@ -110,6 +130,7 @@ async function loadMainForWindowFlags(flags) {
 
   class FakeDatabase {
     pragma() {}
+    exec() {}
     close() {}
     prepare() {
       return { get: () => null, all: () => [], run: () => ({}) };
@@ -191,6 +212,7 @@ test('main process watches Codex sessions directory instead of Codex root', asyn
 
   class FakeDatabase {
     pragma() {}
+    exec() {}
     close() {}
     prepare() {
       return { get: () => null, all: () => [], run: () => ({}) };
@@ -245,6 +267,77 @@ test('main process watches Codex sessions directory instead of Codex root', asyn
   }
 });
 
+test('main process forwards committed IDs without reopening after a deferred build', async () => {
+  const originalHome = process.env.HOME;
+  const home = join(tmpdir(), `obelisk-main-deferred-build-${Date.now()}`);
+  mkdirSync(join(home, '.claude', 'projects'), { recursive: true });
+  mkdirSync(join(home, '.codex', 'sessions'), { recursive: true });
+  mkdirSync(join(home, '.obelisk'), { recursive: true });
+  writeFileSync(join(home, '.obelisk', 'obelisk.sqlite'), '');
+  process.env.HOME = home;
+
+  let databaseOpens = 0;
+  let serviceOptions;
+  let notifications = 0;
+
+  class FakeDatabase {
+    constructor() { databaseOpens += 1; }
+    pragma() {}
+    exec() {}
+    close() {}
+    prepare() { return { get: () => null, all: () => [], run: () => ({}) }; }
+  }
+
+  class FakeBrowserWindow {
+    constructor() {
+      this.webContents = { on() {}, setZoomLevel() {}, openDevTools() {}, send() { notifications += 1; } };
+    }
+    loadFile() {}
+    loadURL() {}
+    close() {}
+    static getAllWindows() { return [{ webContents: { send() { notifications += 1; } } }]; }
+    static fromWebContents() { return null; }
+  }
+
+  const restore = registerMocks([
+    [ELECTRON_URL, { namedExports: electronNamespace({ BrowserWindow: FakeBrowserWindow }) }],
+    [DATABASE_URL, { defaultExport: FakeDatabase }],
+    [CHOKIDAR_URL, { defaultExport: noopChokidar() }],
+    [INDEXER_URL, { namedExports: { writeHeartbeat() {} } }],
+    [INDEXER_SERVICE_URL, {
+      namedExports: {
+        createIndexerService: (options) => {
+          serviceOptions = options;
+          return { start() {}, stop() {}, idle: async () => {}, runBuildNow() { return Promise.resolve(); } };
+        },
+      },
+    }],
+    [INDEXER_WORKER_URL, {
+      namedExports: {
+        createWorkerBuildIndex: () => ({
+          buildIndex: async () => ({ deferred: true, reason: 'database_busy', affectedSessionIds: ['session-1'] }),
+          stop() {},
+        }),
+      },
+    }],
+  ]);
+
+  try {
+    await importMain();
+    const opensBeforeBuild = databaseOpens;
+    const notificationsBeforeBuild = notifications;
+    const result = await serviceOptions.buildIndex({ reason: 'writer-lease' });
+
+    assert.equal(result.deferred, true);
+    assert.equal(databaseOpens, opensBeforeBuild);
+    assert.equal(notifications, notificationsBeforeBuild + 2);
+  } finally {
+    restore();
+    process.env.HOME = originalHome;
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('session IPC hides Codex rows by default and supports explicit source opt-in', async () => {
   const originalHome = process.env.HOME;
   const home = join(tmpdir(), `obelisk-main-source-filter-${Date.now()}`);
@@ -257,6 +350,7 @@ test('session IPC hides Codex rows by default and supports explicit source opt-i
 
   class FakeDatabase {
     pragma() {}
+    exec() {}
     close() {}
     prepare(sql) {
       return {
@@ -369,31 +463,6 @@ test('main process migrates an existing app database before source-filtered IPC
 
   const ipcHandlers = new Map();
 
-  // better-sqlite3-compatible adapter over node:sqlite so the real migration
-  // logic (ALTER TABLE ADD COLUMN source, etc.) runs against a real database.
-  class SqliteCompatDatabase {
-    constructor(dbFile) {
-      this.db = new DatabaseSync(dbFile);
-    }
-    pragma(statement) {
-      this.db.exec(`PRAGMA ${statement}`);
-    }
-    exec(sql) {
-      return this.db.exec(sql);
-    }
-    close() {
-      return this.db.close();
-    }
-    prepare(sql) {
-      const stmt = this.db.prepare(sql);
-      return {
-        all: (...params) => stmt.all(...params),
-        get: (...params) => stmt.get(...params),
-        run: (...params) => stmt.run(...params),
-      };
-    }
-  }
-
   class FakeBrowserWindow {
     constructor() {
       this.webContents = { on() {}, setZoomLevel() {}, openDevTools() {}, send() {} };
@@ -441,6 +510,70 @@ test('main process migrates an existing app database before source-filtered IPC
   }
 });
 
+test('main process keeps schema and memory mutations behind the writer lease', async () => {
+  const originalHome = process.env.HOME;
+  const home = join(tmpdir(), `obelisk-main-migration-lease-${Date.now()}`);
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+  process.env.HOME = home;
+
+  const legacy = new DatabaseSync(dbPath);
+  legacy.exec('CREATE TABLE sessions (id TEXT PRIMARY KEY)');
+  legacy.close();
+
+  const holder = acquireWriterLease({
+    lockPath: join(obeliskDir, 'writer.lock.sqlite'),
+    openDb: lockPath => new DatabaseSync(lockPath),
+  });
+  assert.ok(holder);
+  const ipcHandlers = new Map();
+
+  class FakeBrowserWindow {
+    constructor() {
+      this.webContents = { on() {}, setZoomLevel() {}, openDevTools() {}, send() {} };
+    }
+    loadFile() {}
+    loadURL() {}
+    close() {}
+    static getAllWindows() { return []; }
+    static fromWebContents() { return null; }
+  }
+
+  const restore = registerMocks([
+    [ELECTRON_URL, {
+      namedExports: electronNamespace({
+        BrowserWindow: FakeBrowserWindow,
+        ipcMain: {
+          handle(channel, handler) { ipcHandlers.set(channel, handler); },
+        },
+      }),
+    }],
+    [DATABASE_URL, { defaultExport: SqliteCompatDatabase }],
+    [CHOKIDAR_URL, { defaultExport: noopChokidar() }],
+    [INDEXER_URL, { namedExports: { writeHeartbeat() {} } }],
+    [INDEXER_SERVICE_URL, { namedExports: defaultIndexerService() }],
+    [INDEXER_WORKER_URL, { namedExports: defaultIndexerWorkerClient() }],
+  ]);
+
+  try {
+    await importMain();
+    const check = new DatabaseSync(dbPath, { readOnly: true });
+    const columns = check.prepare('PRAGMA table_info(sessions)').all().map(column => column.name);
+    check.close();
+    assert.deepEqual(columns, ['id']);
+    assert.throws(
+      () => ipcHandlers.get('db:archiveMemory')(null, 'memory-1', 'test'),
+      /writer is busy/i,
+    );
+  } finally {
+    restore();
+    holder.release();
+    process.env.HOME = originalHome;
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('closing the last macOS window releases background resources until activation', async () => {
   const originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
   const originalHome = process.env.HOME;
@@ -459,6 +592,7 @@ test('closing the last macOS window releases background resources until activati
 
   class FakeDatabase {
     pragma() {}
+    exec() {}
     close() { serviceEvents.push('db-close'); }
     prepare() {
       return { get: () => null, all: () => [], run: () => ({}) };
@@ -575,13 +709,16 @@ test('settings rebuild reopens the database from the configured Claude path', as
   const openedDbPaths = [];
   const buildCalls = [];
   const serviceEvents = [];
+  let competingLeaseDuringBuild;
 
   class FakeDatabase {
     constructor(dbPath) {
+      this.lockDb = dbPath.endsWith('writer.lock.sqlite') ? new DatabaseSync(dbPath) : null;
       openedDbPaths.push(dbPath);
     }
     pragma() {}
-    close() {}
+    exec(sql) { return this.lockDb?.exec(sql); }
+    close() { this.lockDb?.close(); }
     prepare() {
       return { get: () => null, all: () => [], run: () => ({}) };
     }
@@ -628,6 +765,12 @@ test('settings rebuild reopens the database from the configured Claude path', as
           buildIndex: async (args) => {
             serviceEvents.push('build');
             buildCalls.push(args);
+            const competingLease = acquireWriterLease({
+              lockPath: args.writerLeasePath,
+              openDb: lockPath => new DatabaseSync(lockPath),
+            });
+            competingLeaseDuringBuild = Boolean(competingLease);
+            competingLease?.release();
             writeFileSync(args.dbPath, 'rebuilt temp db');
             return { files: 2, affectedSessionIds: ['session-1', 'session-2'] };
           },
@@ -649,12 +792,21 @@ test('settings rebuild reopens the database from the configured Claude path', as
     assert.equal(buildCalls.at(-1).codexDir, customCodexDir);
     assert.notEqual(buildCalls.at(-1).dbPath, join(home, '.obelisk', 'obelisk.sqlite'));
     assert.equal(buildCalls.at(-1).preserveDbPath, join(home, '.obelisk', 'obelisk.sqlite'));
+    assert.equal(buildCalls.at(-1).writerLeasePath, join(home, '.obelisk', 'writer.lock.sqlite'));
+    assert.equal(buildCalls.at(-1).writerLeaseMode, 'caller-held');
+    assert.equal(competingLeaseDuringBuild, false);
     assert.equal(openedDbPaths.at(-1), join(home, '.obelisk', 'obelisk.sqlite'));
     assert.equal(
       require('node:fs').readFileSync(join(home, '.obelisk', 'obelisk.sqlite'), 'utf8'),
       'rebuilt temp db',
     );
     assert.ok(serviceEvents.indexOf('build') > serviceEvents.indexOf('stop'));
+    const postRebuildLease = acquireWriterLease({
+      lockPath: join(home, '.obelisk', 'writer.lock.sqlite'),
+      openDb: lockPath => new DatabaseSync(lockPath),
+    });
+    assert.ok(postRebuildLease);
+    postRebuildLease.release();
   } finally {
     restore();
     process.env.HOME = originalHome;
@@ -686,10 +838,15 @@ test('settings rebuild keeps the existing database after a worker failure', asyn
   class FakeDatabase {
     constructor(dbPath) {
       this.dbPath = dbPath;
-      openedDbPaths.push(dbPath);
+      this.lockDb = dbPath.endsWith('writer.lock.sqlite') ? new DatabaseSync(dbPath) : null;
+      if (!this.lockDb) openedDbPaths.push(dbPath);
     }
     pragma() {}
-    close() { closedDbPaths.push(this.dbPath); }
+    exec(sql) { return this.lockDb?.exec(sql); }
+    close() {
+      if (this.lockDb) this.lockDb.close();
+      else closedDbPaths.push(this.dbPath);
+    }
     prepare() {
       return { get: () => null, all: () => [], run: () => ({}) };
     }
@@ -788,8 +945,12 @@ test('settings rebuild cancels an in-flight background build instead of waiting
   let buildIndexCalls = 0;
 
   class FakeDatabase {
+    constructor(dbPath) {
+      this.lockDb = dbPath.endsWith('writer.lock.sqlite') ? new DatabaseSync(dbPath) : null;
+    }
     pragma() {}
-    close() {}
+    exec(sql) { return this.lockDb?.exec(sql); }
+    close() { this.lockDb?.close(); }
     prepare() {
       return { get: () => null, all: () => [], run: () => ({}) };
     }

tests/app-rollback-guard.test.mjs

@@ -1,9 +1,7 @@
-// Regression test for the "cannot rollback - no transaction is active" crash.
-// SQLite auto-rolls back certain failures (SQLITE_BUSY, disk full, ...). The
-// per-file build loop then ran an explicit ROLLBACK in its catch, which threw a
-// SECOND error over the real one and aborted the whole build instead of skipping
-// just the bad file. buildIndex now uses a guarded rollback; this test injects a
-// DB that faithfully reproduces the condition and asserts the build survives.
+// Regression tests for the write-transaction runner (docs/adr/0006):
+//  - a transient BUSY (auto-rolled-back txn) is retried and recovers;
+//  - a persistent BUSY exhausts retries, and that file is SKIPPED, not fatal;
+//  - the guarded rollback never masks the real error ("cannot rollback ...").
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createRequire } from 'node:module';
@@ -15,78 +13,284 @@ const require = createRequire(import.meta.url);
 import { buildIndex } from '../app/src/main/indexer.ts';
 const { DatabaseSync } = require('node:sqlite');
 
-// Wraps node:sqlite and simulates SQLite's auto-rollback-on-error: the first
-// write inside a transaction throws a BUSY-like error AND ends the real
-// transaction, so a following explicit ROLLBACK errors with "no transaction".
-class AutoRollbackOnceDatabase {
-  constructor(dbPath) {
-    this.db = new DatabaseSync(dbPath);
-    this.inTxn = false;
-    this.fired = false;
-  }
-  pragma(statement) { this.db.exec(`PRAGMA ${statement}`); }
-  exec(sql) {
-    const head = sql.trim().slice(0, 8).toUpperCase();
-    if (head.startsWith('BEGIN')) { this.inTxn = true; return this.db.exec('BEGIN'); }
-    if (head.startsWith('COMMIT')) { this.inTxn = false; return this.db.exec('COMMIT'); }
-    if (head.startsWith('ROLLBACK')) {
-      if (!this.inTxn) throw new Error('cannot rollback - no transaction is active');
+// Wraps node:sqlite and simulates SQLite auto-rollback-on-error: a poisoned write
+// throws a BUSY-like error AND ends the real transaction, so a following explicit
+// ROLLBACK errors with "no transaction is active". `shouldPoison(args)` decides
+// which writes are poisoned.
+function makeDbClass(shouldPoison) {
+  return class PoisonDatabase {
+    constructor(dbPath) {
+      this.db = new DatabaseSync(dbPath);
       this.inTxn = false;
-      return this.db.exec('ROLLBACK');
     }
-    return this.db.exec(sql);
-  }
-  prepare(sql) {
-    const stmt = this.db.prepare(sql);
-    const self = this;
-    return {
-      get: (...args) => stmt.get(...args),
-      all: (...args) => stmt.all(...args),
-      run: (...args) => {
-        if (!self.fired && self.inTxn) {
-          self.fired = true;
-          self.db.exec('ROLLBACK'); // SQLite auto-rolled the txn back on the error
-          self.inTxn = false;
-          throw new Error('SQLITE_BUSY: database is locked');
-        }
-        return stmt.run(...args);
-      },
-    };
-  }
-  close() { return this.db.close(); }
+    get inTransaction() { return this.inTxn; }
+    pragma(statement) { this.db.exec(`PRAGMA ${statement}`); }
+    exec(sql) {
+      const head = sql.trim().slice(0, 8).toUpperCase();
+      if (head.startsWith('BEGIN')) { this.inTxn = true; return this.db.exec('BEGIN'); }
+      if (head.startsWith('COMMIT')) { this.inTxn = false; return this.db.exec('COMMIT'); }
+      if (head.startsWith('ROLLBACK')) {
+        if (!this.inTxn) throw new Error('cannot rollback - no transaction is active');
+        this.inTxn = false;
+        return this.db.exec('ROLLBACK');
+      }
+      return this.db.exec(sql);
+    }
+    prepare(sql) {
+      const stmt = this.db.prepare(sql);
+      const self = this;
+      return {
+        get: (...args) => stmt.get(...args),
+        all: (...args) => stmt.all(...args),
+        run: (...args) => {
+          if (self.inTxn && shouldPoison(args)) {
+            self.db.exec('ROLLBACK'); // SQLite auto-rolled the txn back on the error
+            self.inTxn = false;
+            throw new Error('SQLITE_BUSY: database is locked');
+          }
+          return stmt.run(...args);
+        },
+      };
+    }
+    close() { return this.db.close(); }
+  };
 }
 
-test('a per-file write that auto-rolls-back the transaction is skipped, not fatal', () => {
-  const home = mkdtempSync(join(tmpdir(), 'obelisk-rollback-guard-'));
+function twoFileHome(alphaContent, betaContent) {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-tx-'));
   const projectDir = join(home, '.claude', 'projects', '-tmp-proj');
   mkdirSync(projectDir, { recursive: true });
-  const msg = (uuid) => JSON.stringify({
-    uuid, type: 'user', timestamp: '2026-06-10T10:00:00Z', cwd: '/tmp/proj',
-    message: { role: 'user', content: `hello ${uuid}` },
-  }) + '\n';
-  writeFileSync(join(projectDir, 'alpha.jsonl'), msg('a1'));
-  writeFileSync(join(projectDir, 'beta.jsonl'), msg('b1'));
-
-  const dbPath = join(home, '.obelisk', 'obelisk.sqlite');
   mkdirSync(join(home, '.obelisk'), { recursive: true });
+  const msg = (uuid, content) => JSON.stringify({
+    uuid, type: 'user', timestamp: '2026-06-10T10:00:00Z', cwd: '/tmp/proj',
+    message: { role: 'user', content },
+  }) + '\n';
+  writeFileSync(join(projectDir, 'alpha.jsonl'), msg('a1', alphaContent));
+  writeFileSync(join(projectDir, 'beta.jsonl'), msg('b1', betaContent));
+  return { home, dbPath: join(home, '.obelisk', 'obelisk.sqlite'), projectsDir: join(home, '.claude', 'projects') };
+}
+
+function subagentHome(description = 'first description') {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-meta-tx-'));
+  const projectDir = join(home, '.claude', 'projects', '-tmp-proj');
+  const subagentDir = join(projectDir, 'session', 'subagents');
+  const dbPath = join(home, '.obelisk', 'obelisk.sqlite');
+  mkdirSync(subagentDir, { recursive: true });
+  mkdirSync(join(home, '.obelisk'), { recursive: true });
+  const message = uuid => JSON.stringify({
+    uuid,
+    type: 'user',
+    timestamp: '2026-06-10T10:00:00Z',
+    cwd: '/tmp/proj',
+    message: { role: 'user', content: `message ${uuid}` },
+  }) + '\n';
+  writeFileSync(join(projectDir, 'session.jsonl'), message('main-message'));
+  writeFileSync(join(subagentDir, 'agent.jsonl'), message('agent-message'));
+  const metaPath = join(subagentDir, 'agent.meta.json');
+  writeFileSync(metaPath, JSON.stringify({ agentType: 'Explore', description }));
+  return {
+    home,
+    dbPath,
+    projectsDir: join(home, '.claude', 'projects'),
+    metaPath,
+    changedMetaPath: join('-tmp-proj', 'session', 'subagents', 'agent.meta.json'),
+  };
+}
+
+function run(home, dbPath, projectsDir, DatabaseImpl) {
+  return buildIndex({
+    force: true,
+    claudeDir: join(home, '.claude'),
+    codexDir: join(home, '.codex'),
+    projectsDir,
+    dbPath,
+    DatabaseImpl,
+  });
+}
+
+function makeBeginBusyDbClass(shouldFail) {
+  const Base = makeDbClass(() => false);
+  return class BeginBusyDatabase extends Base {
+    constructor(dbPath) {
+      super(dbPath);
+      this.isWriterLease = dbPath.endsWith('writer.lock.sqlite');
+      this.beginCalls = 0;
+    }
+    exec(sql) {
+      if (!this.isWriterLease && sql.trim().toUpperCase().startsWith('BEGIN')) {
+        this.beginCalls += 1;
+        if (shouldFail(this.beginCalls)) {
+          throw Object.assign(new Error('database is locked'), { code: 'SQLITE_BUSY' });
+        }
+      }
+      return super.exec(sql);
+    }
+  };
+}
+
+test('a failed changed file is not reported as an affected session', () => {
+  const { home, dbPath, projectsDir } = twoFileHome('POISON alpha', 'hello beta');
+  const Db = makeDbClass((args) => args.some(a => typeof a === 'string' && a.includes('POISON')));
+
+  const result = buildIndex({
+    force: false,
+    claudeDir: join(home, '.claude'),
+    codexDir: join(home, '.codex'),
+    projectsDir,
+    dbPath,
+    DatabaseImpl: Db,
+    changedPaths: ['-tmp-proj/alpha.jsonl'],
+  });
+
+  assert.deepEqual(result.affectedSessionIds, []);
+  assert.equal(result.skipped, 1);
+});
+
+test('a transient BUSY during force cleanup is retried and recovers', () => {
+  const { home, dbPath, projectsDir } = twoFileHome('hello alpha', 'hello beta');
+  // Fire exactly once, on the first write inside a transaction, then never again.
+  let fired = false;
+  const Db = makeDbClass(() => (fired ? false : (fired = true)));
 
-  // The unguarded ROLLBACK used to make this throw the masking rollback error.
   let result;
-  assert.doesNotThrow(() => {
-    result = buildIndex({
-      force: true,
-      claudeDir: join(home, '.claude'),
-      codexDir: join(home, '.codex'),
-      projectsDir: join(home, '.claude', 'projects'),
-      dbPath,
-      DatabaseImpl: AutoRollbackOnceDatabase,
-    });
-  }, 'build must not abort on a transaction-aborting per-file error');
+  assert.doesNotThrow(() => { result = run(home, dbPath, projectsDir, Db); });
 
-  // Exactly one file's write was poisoned; the other indexed cleanly.
   const check = new DatabaseSync(dbPath);
   const sessions = check.prepare('SELECT COUNT(*) AS c FROM sessions').get().c;
   check.close();
-  assert.equal(sessions, 1, 'the surviving file is indexed; the poisoned one is skipped');
-  assert.ok(result.files >= 2, 'both files were discovered');
+  assert.equal(sessions, 2, 'the retried file recovered; both files indexed');
+  assert.equal(result.skipped, 0, 'nothing was skipped');
+});
+
+test('a transient BUSY during a file transaction is retried and recovers', () => {
+  const { home, dbPath, projectsDir } = twoFileHome('hello alpha', 'hello beta');
+  let fired = false;
+  const Db = makeDbClass((args) => {
+    const isAlphaWrite = args.some(arg => typeof arg === 'string' && arg.includes('hello alpha'));
+    if (!isAlphaWrite || fired) return false;
+    fired = true;
+    return true;
+  });
+
+  const result = run(home, dbPath, projectsDir, Db);
+  const check = new DatabaseSync(dbPath);
+  const sessions = check.prepare('SELECT COUNT(*) AS c FROM sessions').get().c;
+  check.close();
+  assert.equal(sessions, 2);
+  assert.equal(result.skipped, 0);
+});
+
+test('a persistent BUSY exhausts retries and skips just that file, not the build', () => {
+  const { home, dbPath, projectsDir } = twoFileHome('POISON alpha', 'hello beta');
+  // Always poison writes that carry alpha's marker text; beta is untouched.
+  const Db = makeDbClass((args) => args.some(a => typeof a === 'string' && a.includes('POISON')));
+
+  let result;
+  assert.doesNotThrow(() => { result = run(home, dbPath, projectsDir, Db); });
+
+  const check = new DatabaseSync(dbPath);
+  const sessions = check.prepare('SELECT id FROM sessions ORDER BY id').all().map(r => r.id);
+  check.close();
+  assert.deepEqual(sessions, ['beta'], 'the persistently-failing file is skipped; the other indexes');
+  assert.equal(result.skipped, 1, 'the skipped file is reported in the build result');
+  assert.equal(result.skippedFiles[0].diagnostics?.phase, 'work', 'diagnostics record the failing phase');
+});
+
+test('BEGIN contention during force cleanup defers the build', () => {
+  const { home, dbPath, projectsDir } = twoFileHome('hello alpha', 'hello beta');
+  const Db = makeBeginBusyDbClass(beginCall => beginCall === 1);
+
+  const result = run(home, dbPath, projectsDir, Db);
+  assert.equal(result.deferred, true);
+  assert.equal(result.reason, 'database_busy');
+});
+
+test('BEGIN contention during finalize defers the build', () => {
+  const { home, dbPath, projectsDir } = twoFileHome('hello alpha', 'hello beta');
+  const Db = makeBeginBusyDbClass(beginCall => beginCall === 3);
+
+  const result = buildIndex({
+    force: false,
+    claudeDir: join(home, '.claude'),
+    codexDir: join(home, '.codex'),
+    projectsDir,
+    dbPath,
+    DatabaseImpl: Db,
+  });
+  assert.equal(result.deferred, true);
+  assert.equal(result.reason, 'database_busy');
+});
+
+test('a finalize database error is propagated instead of swallowed as malformed input', () => {
+  const { home, dbPath, projectsDir } = twoFileHome('hello alpha', 'hello beta');
+  const workflowDir = join(projectsDir, '-tmp-proj', 'alpha', 'workflows');
+  mkdirSync(workflowDir, { recursive: true });
+  writeFileSync(join(workflowDir, 'run.json'), JSON.stringify({
+    runId: 'workflow-1',
+    workflowName: 'POISON WORKFLOW',
+  }));
+  const Db = makeDbClass(args => args.some(arg => typeof arg === 'string' && arg.includes('POISON WORKFLOW')));
+
+  assert.throws(() => buildIndex({
+    force: false,
+    claudeDir: join(home, '.claude'),
+    codexDir: join(home, '.codex'),
+    projectsDir,
+    dbPath,
+    DatabaseImpl: Db,
+  }), /SQLITE_BUSY/);
+});
+
+test('a changed subagent meta file is applied and reported only after its file transaction commits', () => {
+  const { home, dbPath, projectsDir, metaPath, changedMetaPath } = subagentHome();
+  const Db = makeDbClass(() => false);
+  buildIndex({
+    force: true,
+    claudeDir: join(home, '.claude'),
+    codexDir: join(home, '.codex'),
+    projectsDir,
+    dbPath,
+    DatabaseImpl: Db,
+  });
+  writeFileSync(metaPath, JSON.stringify({ agentType: 'Explore', description: 'updated description' }));
+
+  const result = buildIndex({
+    force: false,
+    changedPaths: [changedMetaPath],
+    claudeDir: join(home, '.claude'),
+    codexDir: join(home, '.codex'),
+    projectsDir,
+    dbPath,
+    DatabaseImpl: Db,
+  });
+  const check = new DatabaseSync(dbPath, { readOnly: true });
+  assert.equal(check.prepare('SELECT description FROM subagents WHERE agent_id=?').get('agent').description, 'updated description');
+  check.close();
+  assert.deepEqual(result.affectedSessionIds, ['session']);
+});
+
+test('a failed subagent meta transaction does not report its session as affected', () => {
+  const { home, dbPath, projectsDir, metaPath, changedMetaPath } = subagentHome();
+  buildIndex({
+    force: true,
+    claudeDir: join(home, '.claude'),
+    codexDir: join(home, '.codex'),
+    projectsDir,
+    dbPath,
+    DatabaseImpl: makeDbClass(() => false),
+  });
+  writeFileSync(metaPath, JSON.stringify({ agentType: 'Explore', description: 'POISON META' }));
+  const FailingDb = makeDbClass(args => args.some(arg => typeof arg === 'string' && arg.includes('POISON META')));
+
+  const result = buildIndex({
+    force: false,
+    changedPaths: [changedMetaPath],
+    claudeDir: join(home, '.claude'),
+    codexDir: join(home, '.codex'),
+    projectsDir,
+    dbPath,
+    DatabaseImpl: FailingDb,
+  });
+  assert.deepEqual(result.affectedSessionIds, []);
+  assert.equal(result.skipped, 1);
 });

tests/app-writer-lease.test.mjs

@@ -0,0 +1,97 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { buildIndex } from '../app/src/main/indexer.ts';
+import { acquireWriterLease, writerLockPathFor } from '../scripts/writer-lease.ts';
+
+const require = createRequire(import.meta.url);
+const { DatabaseSync } = require('node:sqlite');
+
+class TestDatabase {
+  constructor(dbPath) {
+    this.db = new DatabaseSync(dbPath);
+  }
+  get inTransaction() { return this.db.isTransaction; }
+  exec(sql) { return this.db.exec(sql); }
+  pragma(statement) { return this.db.exec(`PRAGMA ${statement}`); }
+  prepare(sql) { return this.db.prepare(sql); }
+  close() { return this.db.close(); }
+}
+
+test('an app build defers without opening the target database when another writer owns the lease', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-app-writer-lease-'));
+  const claudeDir = join(home, '.claude');
+  const projectsDir = join(claudeDir, 'projects');
+  const projectDir = join(projectsDir, '-tmp-project');
+  const dbPath = join(home, '.obelisk', 'obelisk.sqlite');
+  mkdirSync(projectDir, { recursive: true });
+  mkdirSync(join(home, '.obelisk'), { recursive: true });
+  writeFileSync(join(projectDir, 'session.jsonl'), JSON.stringify({
+    uuid: 'message-1',
+    type: 'user',
+    timestamp: '2026-07-10T00:00:00Z',
+    message: { role: 'user', content: 'hello' },
+  }) + '\n');
+
+  const lease = acquireWriterLease({
+    lockPath: writerLockPathFor(dbPath),
+    openDb: path => new DatabaseSync(path),
+  });
+  assert.ok(lease);
+  try {
+    const result = buildIndex({
+      claudeDir,
+      projectsDir,
+      dbPath,
+      DatabaseImpl: TestDatabase,
+      writerLeaseWaitMs: 0,
+    });
+    assert.equal(result.deferred, true);
+    assert.equal(result.reason, 'writer_busy');
+    assert.equal(existsSync(dbPath), false);
+  } finally {
+    lease.release();
+  }
+});
+
+test('a failed force cleanup leaves the existing index intact', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-app-force-atomic-'));
+  const claudeDir = join(home, '.claude');
+  const projectsDir = join(claudeDir, 'projects');
+  const projectDir = join(projectsDir, '-tmp-project');
+  const dbPath = join(home, '.obelisk', 'obelisk.sqlite');
+  mkdirSync(projectDir, { recursive: true });
+  mkdirSync(join(home, '.obelisk'), { recursive: true });
+  writeFileSync(join(projectDir, 'session.jsonl'), JSON.stringify({
+    uuid: 'message-1',
+    type: 'user',
+    timestamp: '2026-07-10T00:00:00Z',
+    message: { role: 'user', content: 'hello' },
+  }) + '\n');
+  buildIndex({ claudeDir, projectsDir, dbPath, DatabaseImpl: TestDatabase });
+
+  class FailingCleanupDatabase extends TestDatabase {
+    prepare(sql) {
+      const statement = super.prepare(sql);
+      if (!sql.includes('DELETE FROM sessions')) return statement;
+      return {
+        get: (...args) => statement.get(...args),
+        all: (...args) => statement.all(...args),
+        run: () => { throw new Error('cleanup interrupted'); },
+      };
+    }
+  }
+
+  assert.throws(
+    () => buildIndex({ claudeDir, projectsDir, dbPath, DatabaseImpl: FailingCleanupDatabase, force: true }),
+    /cleanup interrupted/,
+  );
+  const check = new DatabaseSync(dbPath, { readOnly: true });
+  assert.equal(check.prepare('SELECT COUNT(*) AS count FROM sessions').get().count, 1);
+  assert.equal(check.prepare('SELECT COUNT(*) AS count FROM messages').get().count, 1);
+  check.close();
+});

tests/daemon-arbitration.test.mjs

@@ -0,0 +1,133 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { acquireWriterLease, writerLockPathFor } from '../scripts/writer-lease.ts';
+
+const require = createRequire(import.meta.url);
+const { DatabaseSync } = require('node:sqlite');
+const repoRoot = resolve(new URL('..', import.meta.url).pathname);
+
+test('a passive query does not mutate the index while a fresh daemon owns writes', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-daemon-arbitration-'));
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+
+  const db = new DatabaseSync(dbPath);
+  db.exec('CREATE TABLE index_state (jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER)');
+  const marker = db.prepare('INSERT INTO index_state (jsonl_path, mtime, lines_processed) VALUES (?, ?, 0)');
+  const now = Date.now();
+  marker.run('__app_heartbeat__', now);
+  db.close();
+
+  const queryPath = join(home, 'query.mjs');
+  writeFileSync(queryPath, "return 'read-only';");
+  const result = spawnSync(process.execPath, ['scripts/runtime.mjs', '--query', queryPath], {
+    cwd: repoRoot,
+    env: { ...process.env, HOME: home },
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.equal(JSON.parse(result.stdout), 'read-only');
+
+  const check = new DatabaseSync(dbPath, { readOnly: true });
+  const tables = check.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all().map(row => row.name);
+  check.close();
+  assert.deepEqual(tables, ['index_state']);
+});
+
+test('attune refuses to mutate the index while a fresh daemon owns writes', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-daemon-attune-'));
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec('CREATE TABLE index_state (jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER)');
+  const marker = db.prepare('INSERT INTO index_state (jsonl_path, mtime, lines_processed) VALUES (?, ?, 0)');
+  const now = Date.now();
+  marker.run('__app_heartbeat__', now);
+  db.close();
+
+  const attunePath = join(home, 'attune.mjs');
+  writeFileSync(attunePath, 'return true;');
+  const result = spawnSync(process.execPath, ['scripts/runtime.mjs', '--attune', attunePath], {
+    cwd: repoRoot,
+    env: { ...process.env, HOME: home },
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 1);
+  assert.match(JSON.parse(result.stdout).error, /daemon owns index writes/i);
+
+  const check = new DatabaseSync(dbPath, { readOnly: true });
+  const tables = check.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all().map(row => row.name);
+  check.close();
+  assert.deepEqual(tables, ['index_state']);
+});
+
+test('a passive query stays read-only when another process holds the writer lease', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-writer-owned-'));
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec('CREATE TABLE index_state (jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER)');
+  db.close();
+
+  const lease = acquireWriterLease({
+    lockPath: writerLockPathFor(dbPath),
+    openDb: path => new DatabaseSync(path),
+  });
+  assert.ok(lease);
+  try {
+    const queryPath = join(home, 'query.mjs');
+    writeFileSync(queryPath, "return 'writer-busy';");
+    const result = spawnSync(process.execPath, ['scripts/runtime.mjs', '--query', queryPath], {
+      cwd: repoRoot,
+      env: { ...process.env, HOME: home },
+      encoding: 'utf8',
+    });
+    assert.equal(result.status, 0, result.stderr || result.stdout);
+    assert.equal(JSON.parse(result.stdout), 'writer-busy');
+  } finally {
+    lease.release();
+  }
+
+  const check = new DatabaseSync(dbPath, { readOnly: true });
+  const tables = check.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all().map(row => row.name);
+  check.close();
+  assert.deepEqual(tables, ['index_state']);
+});
+
+test('a passive query fails closed when daemon ownership cannot be read', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-daemon-ownership-error-'));
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec('CREATE TABLE index_state (jsonl_path TEXT PRIMARY KEY)');
+  db.close();
+
+  const lease = acquireWriterLease({
+    lockPath: writerLockPathFor(dbPath),
+    openDb: path => new DatabaseSync(path),
+  });
+  assert.ok(lease);
+  try {
+    const queryPath = join(home, 'query.mjs');
+    writeFileSync(queryPath, "return 'ownership-unknown';");
+    const result = spawnSync(process.execPath, ['scripts/runtime.mjs', '--query', queryPath], {
+      cwd: repoRoot,
+      env: { ...process.env, HOME: home },
+      encoding: 'utf8',
+    });
+    assert.equal(result.status, 1, result.stderr || result.stdout);
+    assert.match(JSON.parse(result.stdout).error, /no such column: mtime/i);
+  } finally {
+    lease.release();
+  }
+});

tests/indexer.test.mjs

@@ -56,7 +56,7 @@ test('refreshSessionProjectPaths repairs indexed sessions from message cwd', ()
   db.close();
 });
 
-test('shouldSkipBuild requires both fresh app heartbeat and successful app build', () => {
+test('shouldSkipBuild treats a fresh heartbeat alone as daemon write ownership', () => {
   const db = new DatabaseSync(':memory:');
   db.exec(`
     CREATE TABLE index_state (
@@ -68,17 +68,19 @@ test('shouldSkipBuild requires both fresh app heartbeat and successful app build
     100000,
   );
 
-  assert.equal(shouldSkipBuild(db, { now: 110000 }).skip, false);
+  assert.deepEqual(
+    shouldSkipBuild(db, { now: 110000 }),
+    { skip: true, reason: 'daemon_active' },
+  );
+
+  db.prepare('DELETE FROM index_state').run();
 
   db.prepare('INSERT INTO index_state (jsonl_path, mtime, lines_processed) VALUES (?, ?, 0)').run(
     '__app_last_successful_build__',
     100000,
   );
 
-  assert.deepEqual(
-    shouldSkipBuild(db, { now: 110000 }),
-    { skip: true, reason: 'app_successful_build' },
-  );
+  assert.equal(shouldSkipBuild(db, { now: 110000 }).skip, false);
   assert.equal(shouldSkipBuild(db, { now: 200000 }).skip, false);
   db.close();
 });

tests/write-transaction.test.mjs

@@ -0,0 +1,166 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { nodeSqliteTransactionAdapter, runWriteTransaction } from '../scripts/tx.ts';
+import { hasUnusableTransaction, isBeginBusyFailure, isRetryableWriteFailure } from '../scripts/write-coordinator.ts';
+
+const require = createRequire(import.meta.url);
+const { DatabaseSync } = require('node:sqlite');
+
+test('a failed rollback with an active transaction never retries or masks the primary error', () => {
+  const primary = Object.assign(new Error('database is locked'), { code: 'SQLITE_BUSY' });
+  let active = false;
+  let workCalls = 0;
+
+  const db = {
+    exec(sql) {
+      if (sql.startsWith('BEGIN')) {
+        if (active) throw new Error('cannot start a transaction within a transaction');
+        active = true;
+      } else if (sql === 'ROLLBACK') {
+        throw new Error('rollback failed with I/O error');
+      } else if (sql === 'COMMIT') {
+        active = false;
+      }
+    },
+    inTransaction() {
+      return active;
+    },
+  };
+
+  assert.throws(
+    () => runWriteTransaction(db, () => {
+      workCalls += 1;
+      throw primary;
+    }),
+    error => error === primary,
+  );
+  assert.equal(workCalls, 1);
+  assert.equal(active, true);
+});
+
+test('an automatic rollback rethrows the primary error without issuing another rollback', () => {
+  const primary = Object.assign(new Error('database is locked'), { code: 'SQLITE_BUSY' });
+  let active = false;
+  let rollbackCalls = 0;
+  const db = {
+    exec(sql) {
+      if (sql.startsWith('BEGIN')) active = true;
+      if (sql === 'ROLLBACK') rollbackCalls += 1;
+    },
+    inTransaction() {
+      return active;
+    },
+  };
+
+  assert.throws(
+    () => runWriteTransaction(db, () => {
+      active = false;
+      throw primary;
+    }),
+    error => error === primary,
+  );
+  assert.equal(rollbackCalls, 0);
+  assert.equal(primary.obelisk.transactionActive, false);
+});
+
+test('an active transaction is rolled back once before the primary error is rethrown', () => {
+  const primary = new Error('persist failed');
+  let active = false;
+  let rollbackCalls = 0;
+  const db = {
+    exec(sql) {
+      if (sql.startsWith('BEGIN')) active = true;
+      if (sql === 'ROLLBACK') {
+        rollbackCalls += 1;
+        active = false;
+      }
+    },
+    inTransaction() {
+      return active;
+    },
+  };
+
+  assert.throws(() => runWriteTransaction(db, () => { throw primary; }), error => error === primary);
+  assert.equal(rollbackCalls, 1);
+  assert.equal(primary.obelisk.rollbackSucceeded, true);
+  assert.equal(primary.obelisk.transactionActive, false);
+});
+
+test('an unknown post-error transaction state is unsafe for the next file', () => {
+  const primary = new Error('transaction state unavailable');
+  const db = {
+    exec() {},
+    inTransaction() {
+      throw new Error('binding cannot report transaction state');
+    },
+  };
+
+  assert.throws(() => runWriteTransaction(db, () => { throw primary; }), error => error === primary);
+  assert.equal(primary.obelisk.transactionActive, null);
+  assert.equal(hasUnusableTransaction(primary), true);
+});
+
+test('node:sqlite generic error codes preserve BUSY classification from the message', () => {
+  const primary = Object.assign(new Error('database is locked'), { code: 'ERR_SQLITE_ERROR' });
+  let active = false;
+  const db = {
+    exec(sql) {
+      if (sql === 'BEGIN IMMEDIATE') active = true;
+    },
+    inTransaction() { return active; },
+  };
+
+  assert.throws(() => runWriteTransaction(db, () => {
+    active = false;
+    throw primary;
+  }), error => error === primary);
+  assert.equal(primary.obelisk.code, 'SQLITE_BUSY');
+  assert.equal(isRetryableWriteFailure(primary), true);
+});
+
+test('a real node:sqlite BEGIN lock is classified as a deferrable BUSY', () => {
+  const dbPath = join(mkdtempSync(join(tmpdir(), 'obelisk-node-sqlite-busy-')), 'index.sqlite');
+  const holder = new DatabaseSync(dbPath);
+  const contender = new DatabaseSync(dbPath);
+  holder.exec('PRAGMA busy_timeout=0; CREATE TABLE test (value TEXT); BEGIN IMMEDIATE');
+  contender.exec('PRAGMA busy_timeout=0');
+
+  try {
+    assert.throws(
+      () => runWriteTransaction(nodeSqliteTransactionAdapter(contender), () => {}),
+      error => isBeginBusyFailure(error) && error.obelisk.code === 'SQLITE_BUSY',
+    );
+  } finally {
+    holder.exec('ROLLBACK');
+    holder.close();
+    contender.close();
+  }
+});
+
+test('a BEGIN failure with an active transaction is not deferrable', () => {
+  const primary = Object.assign(new Error('database is locked'), { code: 'SQLITE_BUSY' });
+  let rollbackCalls = 0;
+  const db = {
+    exec(sql) {
+      if (sql === 'BEGIN IMMEDIATE') throw primary;
+      if (sql === 'ROLLBACK') {
+        rollbackCalls += 1;
+        throw new Error('rollback failed with I/O error');
+      }
+    },
+    inTransaction() {
+      return true;
+    },
+  };
+
+  assert.throws(() => runWriteTransaction(db, () => {}), error => error === primary);
+  assert.equal(rollbackCalls, 1);
+  assert.equal(primary.obelisk.transactionActive, true);
+  assert.equal(hasUnusableTransaction(primary), true);
+  assert.equal(isBeginBusyFailure(primary), false);
+});

tests/writer-lease.test.mjs

@@ -0,0 +1,25 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { acquireWriterLease } from '../scripts/writer-lease.ts';
+
+const require = createRequire(import.meta.url);
+const { DatabaseSync } = require('node:sqlite');
+
+test('a writer lease excludes another writer until it is released', () => {
+  const lockPath = join(mkdtempSync(join(tmpdir(), 'obelisk-writer-lease-')), 'writer.lock.sqlite');
+  const openDb = path => new DatabaseSync(path);
+
+  const first = acquireWriterLease({ lockPath, openDb });
+  assert.ok(first);
+  assert.equal(acquireWriterLease({ lockPath, openDb }), null);
+
+  first.release();
+  const afterRelease = acquireWriterLease({ lockPath, openDb });
+  assert.ok(afterRelease);
+  afterRelease.release();
+});