create-walle 0.9.23 → 0.9.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-walle",
-  "version": "0.9.23",
+  "version": "0.9.25",
   "description": "CTM + Wall-E \u2014 AI coding dashboard and personal digital twin agent. Multi-agent terminal for Claude Code, Codex, Gemini, Aider, OpenCode, and more, plus prompt editor, task queue, remote phone and tablet access, code/doc review, and an agent that learns from Slack, email & calendar.",
   "bin": {
     "create-walle": "bin/create-walle.js"

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "walle",
-  "version": "0.9.23",
+  "version": "0.9.25",
   "private": true,
   "description": "Wall-E — your personal digital twin",
   "scripts": {

package/template/wall-e/agent.js

@@ -1,21 +1,42 @@
 process.env.WALL_E_PROCESS_ROLE = process.env.WALL_E_PROCESS_ROLE || 'walle-daemon';
+
+function loadOptionalCtmLib(name) {
+  const request = `../claude-task-manager/lib/${name}`;
+  try {
+    return require(request);
+  } catch (err) {
+    if (err && err.code === 'MODULE_NOT_FOUND' && String(err.message || '').includes(request)) {
+      return null;
+    }
+    throw err;
+  }
+}
+
 // Refuse to boot under a Node major that mismatches the pinned one BEFORE brain
-// (and its native better-sqlite3) loads. No-op in shipped installs.
-require('../claude-task-manager/lib/node-pin-guard').assertPinnedNode();
+// (and its native better-sqlite3) loads. No-op in shipped installs and cloud
+// builds where the CTM sibling app is not present.
+const nodePinGuard = loadOptionalCtmLib('node-pin-guard');
+if (nodePinGuard) nodePinGuard.assertPinnedNode();
 try {
   if (process.env.WALL_E_STORAGE_MIGRATION_BYPASS !== '1' && process.env.CTM_STORAGE_MIGRATION_BYPASS !== '1') {
-    const guard = require('../claude-task-manager/lib/storage-migration').startupGuard('Wall-E', process.env);
-    if (!guard.ok) {
-      console.error('[storage-migration] Wall-E startup paused while storage migration is active.');
-      process.exit(75);
-    } else if (guard.stale) {
-      console.warn('[storage-migration] Ignoring stale storage migration lock.');
+    const storageMigration = loadOptionalCtmLib('storage-migration');
+    if (storageMigration) {
+      const guard = storageMigration.startupGuard('Wall-E', process.env);
+      if (!guard.ok) {
+        console.error('[storage-migration] Wall-E startup paused while storage migration is active.');
+        process.exit(75);
+      } else if (guard.stale) {
+        console.warn('[storage-migration] Ignoring stale storage migration lock.');
+      }
     }
   }
 } catch (e) {
   console.warn('[storage-migration] Startup guard failed open:', e.message);
 }
-const { processTitle: formatProcessTitle } = require('../claude-task-manager/lib/process-title');
+const processTitleLib = loadOptionalCtmLib('process-title');
+const formatProcessTitle = processTitleLib
+  ? processTitleLib.processTitle
+  : ((role, tag) => `Wall-E ${role}${tag ? `-${tag}` : ''}`);
 
 const brain = require('./brain'); // brain.js loads .env from project root
 const ingest = require('./loops/ingest');

package/template/wall-e/brain.js

@@ -1,7 +1,7 @@
 // --- WALL-E Brain: SQLite Database Layer (WAL mode, better-sqlite3) ---
 const {
   assertNoForeignSqliteOwner,
-} = require('../shared/sqlite-owner-guard');
+} = require('./shared/sqlite-owner-guard');
 
 assertNoForeignSqliteOwner({
   blockedEnv: 'CTM_PROCESS_ROLE',
@@ -23,13 +23,13 @@ const { findSupportedModel, supportedModelIdsForProvider } = require('./llm/supp
 const { isPortkeyProviderConfig } = require('./llm/portkey');
 const {
   enforceSqliteStoragePolicy,
-} = require('../shared/sqlite-storage-policy');
+} = require('./shared/sqlite-storage-policy');
 const {
   installSqliteWriteLock,
-} = require('../shared/sqlite-write-lock');
+} = require('./shared/sqlite-write-lock');
 const {
   createSqliteOwnerWriteQueue,
-} = require('../shared/sqlite-owner-write-queue');
+} = require('./shared/sqlite-owner-write-queue');
 const _brainEvents = new EventEmitter();
 _brainEvents.setMaxListeners(20);
 let _stripNoise;

package/template/wall-e/shared/sqlite-owner-guard.js

@@ -0,0 +1,30 @@
+'use strict';
+
+function _truthy(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function assertNoForeignSqliteOwner({
+  blockedEnv,
+  overrideEnv,
+  databaseLabel,
+  ownerLabel,
+} = {}) {
+  const blockedRole = blockedEnv ? process.env[blockedEnv] : '';
+  if (!blockedRole || (overrideEnv && _truthy(process.env[overrideEnv]))) return;
+
+  const err = new Error(
+    `${databaseLabel || 'SQLite database'} must be accessed through its ${ownerLabel || 'owner'} API; ` +
+    `refusing direct access inside process role ${blockedEnv}=${blockedRole}.` +
+    (overrideEnv ? ` Set ${overrideEnv}=1 only for explicit standalone repair.` : '')
+  );
+  err.code = 'SQLITE_OWNER_VIOLATION';
+  err.blockedEnv = blockedEnv;
+  err.blockedRole = blockedRole;
+  err.overrideEnv = overrideEnv || '';
+  throw err;
+}
+
+module.exports = {
+  assertNoForeignSqliteOwner,
+};

package/template/wall-e/shared/sqlite-owner-write-queue.js

@@ -0,0 +1,225 @@
+'use strict';
+
+const DEFAULT_MAX_DEPTH = 1000;
+const DEFAULT_DRAIN_TIMEOUT_MS = 5000;
+
+function _durationMs(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.max(0, Math.trunc(n)) : fallback;
+}
+
+function _queueError(code, message, extra = {}) {
+  const err = new Error(message);
+  err.code = code;
+  for (const [key, value] of Object.entries(extra)) err[key] = value;
+  return err;
+}
+
+class SqliteOwnerWriteQueue {
+  constructor(options = {}) {
+    this.name = options.name || options.label || 'sqlite-owner-write-queue';
+    this.maxDepth = Math.max(1, Math.trunc(Number(options.maxDepth) || DEFAULT_MAX_DEPTH));
+    this._queue = [];
+    this._running = false;
+    this._active = null;
+    this._accepting = true;
+    this._closed = false;
+    this._enqueued = 0;
+    this._completed = 0;
+    this._failed = 0;
+    this._idleWaiters = [];
+  }
+
+  enqueue(fn, options = {}) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('SqliteOwnerWriteQueue.enqueue requires a function');
+    }
+    if (!this._accepting || this._closed) {
+      return Promise.reject(_queueError(
+        'SQLITE_OWNER_WRITE_QUEUE_CLOSED',
+        `${this.name} is closed`
+      ));
+    }
+    if (this._queue.length >= this.maxDepth) {
+      return Promise.reject(_queueError(
+        'SQLITE_OWNER_WRITE_QUEUE_FULL',
+        `${this.name} is full`,
+        { pending: this._queue.length, maxDepth: this.maxDepth }
+      ));
+    }
+
+    const signal = options.signal || null;
+    if (signal?.aborted) {
+      return Promise.reject(_queueError(
+        'SQLITE_OWNER_WRITE_QUEUE_ABORTED',
+        `${this.name} task aborted before enqueue`
+      ));
+    }
+
+    const label = options.label || 'write';
+    let task;
+    const promise = new Promise((resolve, reject) => {
+      task = {
+        fn,
+        label,
+        resolve,
+        reject,
+        enqueuedAt: Date.now(),
+        started: false,
+        signal,
+        abortListener: null,
+      };
+    });
+
+    if (signal) {
+      task.abortListener = () => {
+        if (task.started) return;
+        const idx = this._queue.indexOf(task);
+        if (idx >= 0) this._queue.splice(idx, 1);
+        task.reject(_queueError(
+          'SQLITE_OWNER_WRITE_QUEUE_ABORTED',
+          `${this.name} task aborted while queued`,
+          { label }
+        ));
+        this._notifyIdleIfNeeded();
+      };
+      signal.addEventListener('abort', task.abortListener, { once: true });
+    }
+
+    this._enqueued += 1;
+    this._queue.push(task);
+    this._pump();
+    return promise;
+  }
+
+  getStatus() {
+    return {
+      name: this.name,
+      active: this._active,
+      running: this._running,
+      pending: this._queue.length,
+      accepting: this._accepting,
+      closed: this._closed,
+      maxDepth: this.maxDepth,
+      enqueued: this._enqueued,
+      completed: this._completed,
+      failed: this._failed,
+      idle: !this._running && this._queue.length === 0,
+    };
+  }
+
+  async drain(options = {}) {
+    const timeoutMs = _durationMs(options.timeoutMs, DEFAULT_DRAIN_TIMEOUT_MS);
+    if (!this._running && this._queue.length === 0) {
+      return { ok: true, timedOut: false, ...this.getStatus() };
+    }
+
+    if (timeoutMs === 0) {
+      await new Promise((resolve) => this._idleWaiters.push(resolve));
+      return { ok: true, timedOut: false, ...this.getStatus() };
+    }
+
+    let timer = null;
+    let idleWaiter = null;
+    try {
+      return await Promise.race([
+        new Promise((resolve) => {
+          idleWaiter = () => resolve({
+            ok: true,
+            timedOut: false,
+            ...this.getStatus(),
+          });
+          this._idleWaiters.push(idleWaiter);
+        }),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve({
+            ok: false,
+            timedOut: true,
+            ...this.getStatus(),
+          }), timeoutMs);
+          if (typeof timer.unref === 'function') timer.unref();
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+      if (idleWaiter) {
+        const idx = this._idleWaiters.indexOf(idleWaiter);
+        if (idx >= 0) this._idleWaiters.splice(idx, 1);
+      }
+    }
+  }
+
+  async close(options = {}) {
+    const drain = !!options.drain;
+    this._accepting = false;
+    this._closed = true;
+    if (!drain) {
+      this._rejectPending(_queueError(
+        'SQLITE_OWNER_WRITE_QUEUE_CLOSED',
+        `${this.name} closed with pending writes rejected`
+      ));
+      return { ok: true, drained: false, ...this.getStatus() };
+    }
+    const result = await this.drain({ timeoutMs: options.timeoutMs });
+    return { ...result, drained: !result.timedOut };
+  }
+
+  _pump() {
+    if (this._running) return;
+    const task = this._queue.shift();
+    if (!task) {
+      this._notifyIdleIfNeeded();
+      return;
+    }
+
+    this._running = true;
+    this._active = task.label;
+    task.started = true;
+    if (task.signal && task.abortListener) {
+      task.signal.removeEventListener('abort', task.abortListener);
+      task.abortListener = null;
+    }
+
+    Promise.resolve()
+      .then(() => task.fn())
+      .then((value) => {
+        this._completed += 1;
+        task.resolve(value);
+      }, (err) => {
+        this._failed += 1;
+        task.reject(err);
+      })
+      .finally(() => {
+        this._running = false;
+        this._active = null;
+        this._pump();
+      });
+  }
+
+  _rejectPending(err) {
+    const pending = this._queue.splice(0);
+    for (const task of pending) {
+      if (task.signal && task.abortListener) {
+        task.signal.removeEventListener('abort', task.abortListener);
+        task.abortListener = null;
+      }
+      task.reject(err);
+    }
+    this._notifyIdleIfNeeded();
+  }
+
+  _notifyIdleIfNeeded() {
+    if (this._running || this._queue.length > 0) return;
+    const waiters = this._idleWaiters.splice(0);
+    for (const resolve of waiters) resolve();
+  }
+}
+
+function createSqliteOwnerWriteQueue(options = {}) {
+  return new SqliteOwnerWriteQueue(options);
+}
+
+module.exports = {
+  SqliteOwnerWriteQueue,
+  createSqliteOwnerWriteQueue,
+};

package/template/wall-e/shared/sqlite-storage-policy.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CLOUD_STORAGE_PATTERNS = Object.freeze([
+  { id: 'dropbox', label: 'Dropbox', regex: /(^|[\\/])(?:Dropbox|CloudStorage[\\/][^\\/]*Dropbox[^\\/]*)([\\/]|$)/i },
+  { id: 'icloud', label: 'iCloud Drive', regex: /(^|[\\/])(?:Mobile Documents|CloudStorage[\\/][^\\/]*iCloud[^\\/]*)([\\/]|$)/i },
+  { id: 'onedrive', label: 'OneDrive', regex: /(^|[\\/])(?:OneDrive|CloudStorage[\\/][^\\/]*OneDrive[^\\/]*)([\\/]|$)/i },
+  { id: 'google-drive', label: 'Google Drive', regex: /(^|[\\/])(?:Google Drive|CloudStorage[\\/][^\\/]*GoogleDrive[^\\/]*)([\\/]|$)/i },
+  { id: 'box', label: 'Box Drive', regex: /(^|[\\/])(?:Box|CloudStorage[\\/][^\\/]*Box[^\\/]*)([\\/]|$)/i },
+]);
+
+const VALID_POLICY_MODES = new Set(['off', 'warn', 'error']);
+const warnedKeys = new Set();
+
+function _normalizePath(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  try {
+    const dir = path.dirname(raw);
+    const base = path.basename(raw);
+    const realDir = fs.existsSync(dir) ? fs.realpathSync(dir) : path.resolve(dir);
+    return path.join(realDir, base);
+  } catch {
+    return path.resolve(raw);
+  }
+}
+
+function _truthy(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function sqliteStoragePolicyMode({ env = process.env, prefix = '' } = {}) {
+  const normalizedPrefix = String(prefix || '').trim().replace(/[^A-Z0-9_]/gi, '_').toUpperCase();
+  if (normalizedPrefix && _truthy(env[`${normalizedPrefix}_ALLOW_UNSAFE_CLOUD_SQLITE`])) return 'off';
+  if (_truthy(env.ALLOW_UNSAFE_CLOUD_SQLITE)) return 'off';
+
+  const raw = String(
+    (normalizedPrefix && env[`${normalizedPrefix}_SQLITE_STORAGE_POLICY`])
+    || env.SQLITE_STORAGE_POLICY
+    || 'warn'
+  ).trim().toLowerCase();
+  return VALID_POLICY_MODES.has(raw) ? raw : 'warn';
+}
+
+function classifySqlitePathRisk(dbPath) {
+  const normalizedPath = _normalizePath(dbPath);
+  const normalizedForMatch = normalizedPath.replace(/\\/g, '/');
+  const match = CLOUD_STORAGE_PATTERNS.find((candidate) => candidate.regex.test(normalizedForMatch));
+  if (!match) {
+    return {
+      risky: false,
+      reason: '',
+      provider: '',
+      providerLabel: '',
+      dbPath: normalizedPath,
+      message: '',
+    };
+  }
+  return {
+    risky: true,
+    reason: 'cloud_sync_sqlite_wal',
+    provider: match.id,
+    providerLabel: match.label,
+    dbPath: normalizedPath,
+    message:
+      `${match.label} sync storage is unsafe for a live SQLite WAL database. `
+      + 'Move the live DB directory to a local disk path and sync backups/exports instead.',
+  };
+}
+
+function enforceSqliteStoragePolicy(dbPath, {
+  env = process.env,
+  prefix = '',
+  label = 'SQLite database',
+  logger = console,
+} = {}) {
+  const risk = classifySqlitePathRisk(dbPath);
+  const mode = sqliteStoragePolicyMode({ env, prefix });
+  const result = { ...risk, mode, blocked: false, label };
+  if (!risk.risky || mode === 'off') return result;
+
+  const message = `${label}: ${risk.message} Path: ${risk.dbPath}`;
+  if (mode === 'error') {
+    const err = new Error(message);
+    err.code = 'SQLITE_UNSAFE_CLOUD_STORAGE';
+    err.storageRisk = result;
+    throw err;
+  }
+
+  const warnKey = `${label}:${risk.provider}:${risk.dbPath}`;
+  if (!warnedKeys.has(warnKey)) {
+    warnedKeys.add(warnKey);
+    try {
+      logger.warn(`[sqlite-storage] ${message}`);
+    } catch {}
+  }
+  return result;
+}
+
+function resetSqliteStoragePolicyWarnings() {
+  warnedKeys.clear();
+}
+
+module.exports = {
+  classifySqlitePathRisk,
+  enforceSqliteStoragePolicy,
+  resetSqliteStoragePolicyWarnings,
+  sqliteStoragePolicyMode,
+};

package/template/wall-e/shared/sqlite-write-lock.js

@@ -0,0 +1,428 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { threadId } = require('node:worker_threads');
+
+const WRITE_SQL_RE = /^\s*(?:INSERT|UPDATE|DELETE|REPLACE|CREATE|ALTER|DROP|VACUUM|REINDEX|ANALYZE|ATTACH|DETACH|BEGIN|COMMIT|ROLLBACK)\b/i;
+const WRITE_PRAGMA_RE = /^\s*(?:journal_mode|wal_checkpoint|user_version|foreign_keys|synchronous|locking_mode|auto_vacuum|optimize)\b/i;
+const DEFAULT_TIMEOUT_MS = 0;
+const DEFAULT_STALE_MS = 10 * 60 * 1000;
+const DEFAULT_POLL_MS = 25;
+const DEFAULT_CLAIM_STALE_MS = 1000;
+const DEFAULT_STALE_RECOVERY_TIMEOUT_MS = 5000;
+const GLOBAL_STATE_KEY = Symbol.for('ctm.sqliteWriteLockState');
+
+const globalState = globalThis[GLOBAL_STATE_KEY] || (globalThis[GLOBAL_STATE_KEY] = {
+  token: `${process.pid}:${threadId}:${crypto.randomBytes(8).toString('hex')}`,
+  locks: new Map(),
+});
+
+function _sleepSync(ms) {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+
+function _pidAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function _readLock(lockPath) {
+  try {
+    return JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function _inspectLock(lockPath) {
+  let stat = null;
+  try {
+    stat = fs.statSync(lockPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, stat: null, raw: '', info: null, parseError: null };
+    return { exists: true, stat: null, raw: '', info: null, parseError: error };
+  }
+
+  let raw = '';
+  try {
+    raw = fs.readFileSync(lockPath, 'utf8');
+    try {
+      return { exists: true, stat, raw, info: JSON.parse(raw), parseError: null };
+    } catch (parseError) {
+      return { exists: true, stat, raw, info: null, parseError };
+    }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, stat: null, raw: '', info: null, parseError: null };
+    return { exists: true, stat, raw, info: null, parseError: error };
+  }
+}
+
+// Canonical path is stable for the process lifetime (the parent directory's symlink
+// chain doesn't change), so cache it. _acquire runs this on every write — without the
+// cache it pays a realpathSync.native syscall per write, which is pure overhead on the
+// event loop (and worse when the lock file lives on a sync'd filesystem like Dropbox).
+const _canonicalPathCache = new Map();
+function _canonicalLockPath(lockPath) {
+  const resolved = path.resolve(lockPath);
+  const cached = _canonicalPathCache.get(resolved);
+  if (cached !== undefined) return cached;
+  let result;
+  try {
+    result = fs.realpathSync.native(resolved);
+  } catch {
+    try {
+      const dir = fs.realpathSync.native(path.dirname(resolved));
+      result = path.join(dir, path.basename(resolved));
+    } catch {
+      result = resolved;
+    }
+  }
+  _canonicalPathCache.set(resolved, result);
+  return result;
+}
+
+function _releaseLockFile(lockPath, token) {
+  try {
+    const info = _readLock(lockPath);
+    if (info?.token === token) fs.unlinkSync(lockPath);
+  } catch {}
+}
+
+function _lockAgeMs(inspected, now = Date.now()) {
+  const createdAt = Number(inspected?.info?.created_at_ms || 0);
+  const basis = createdAt || Number(inspected?.stat?.mtimeMs || 0);
+  if (!basis) return Number.POSITIVE_INFINITY;
+  return Math.max(0, now - basis);
+}
+
+function _lockUnchanged(a, b) {
+  if (!a?.exists || !b?.exists) return false;
+  if (a.info?.token || b.info?.token) return a.info?.token && a.info.token === b.info?.token;
+  if (!a.stat || !b.stat) return false;
+  if (a.raw || b.raw) return a.raw === b.raw && a.stat.size === b.stat.size && Math.abs(a.stat.mtimeMs - b.stat.mtimeMs) < 1;
+  return a.stat.dev === b.stat.dev &&
+    a.stat.ino === b.stat.ino &&
+    a.stat.size === b.stat.size &&
+    Math.abs(a.stat.mtimeMs - b.stat.mtimeMs) < 1 &&
+    Math.abs(a.stat.ctimeMs - b.stat.ctimeMs) < 1;
+}
+
+function _unlinkIfUnchanged(lockPath, observed) {
+  const current = _inspectLock(lockPath);
+  if (!current.exists) return true;
+  if (!_lockUnchanged(observed, current)) return false;
+  try {
+    fs.unlinkSync(lockPath);
+    return true;
+  } catch (error) {
+    return error?.code === 'ENOENT';
+  }
+}
+
+function _staleReason(inspected, staleMs, claimStaleMs) {
+  if (!inspected?.exists) return 'missing';
+  const ageMs = _lockAgeMs(inspected);
+  if (!inspected.info) {
+    return ageMs > claimStaleMs ? 'orphaned-claim' : '';
+  }
+  if (ageMs > staleMs) return 'expired';
+  return _pidAlive(inspected.info?.pid) ? '' : 'dead-owner';
+}
+
+function _writeLockClaim(lockPath, payload) {
+  const dir = path.dirname(lockPath);
+  const base = path.basename(lockPath);
+  const tempPath = path.join(dir, `.${base}.${process.pid}.${threadId}.${Date.now()}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  const text = JSON.stringify(payload);
+  try {
+    fs.writeFileSync(tempPath, text, { flag: 'wx', mode: 0o600 });
+    fs.linkSync(tempPath, lockPath);
+  } catch (error) {
+    if (error?.code !== 'EEXIST' && ['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EXDEV'].includes(error?.code)) {
+      let fd = null;
+      try {
+        fd = fs.openSync(lockPath, 'wx', 0o600);
+        fs.writeFileSync(fd, text);
+        return;
+      } finally {
+        try { if (fd !== null) fs.closeSync(fd); } catch {}
+      }
+    }
+    throw error;
+  } finally {
+    try { fs.unlinkSync(tempPath); } catch {}
+  }
+}
+
+function _durationMs(value, fallback, min = 0) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.max(min, Math.trunc(n)) : fallback;
+}
+
+function _lockBusyError(lockPath, info) {
+  const owner = info?.pid ? ` pid=${info.pid}` : '';
+  const label = info?.label ? ` label=${info.label}` : '';
+  const err = new Error(`SQLite write lock busy${owner}${label}: ${lockPath}`);
+  err.code = 'SQLITE_WRITE_LOCK_BUSY';
+  err.lockPath = lockPath;
+  err.lockInfo = info || null;
+  return err;
+}
+
+function _stripLeadingSqlComments(sql) {
+  let text = String(sql || '');
+  while (true) {
+    const next = text.replace(/^\s+/, '');
+    if (next.startsWith('--')) {
+      const idx = next.indexOf('\n');
+      text = idx === -1 ? '' : next.slice(idx + 1);
+      continue;
+    }
+    if (next.startsWith('/*')) {
+      const idx = next.indexOf('*/');
+      text = idx === -1 ? '' : next.slice(idx + 2);
+      continue;
+    }
+    return next;
+  }
+}
+
+function _acquire(lockPath, opts = {}) {
+  const timeoutMs = _durationMs(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 0);
+  const staleMs = _durationMs(opts.staleMs ?? DEFAULT_STALE_MS, DEFAULT_STALE_MS, 1000);
+  // Floor of 1ms (not 5) so a background writer can poll tightly and reliably win
+  // the lock in the brief window after the main thread releases — the main thread
+  // can never wait, so the worker winning fast is how we avoid starving it.
+  const pollMs = _durationMs(opts.pollMs ?? DEFAULT_POLL_MS, DEFAULT_POLL_MS, 1);
+  const claimStaleMs = _durationMs(opts.claimStaleMs ?? DEFAULT_CLAIM_STALE_MS, DEFAULT_CLAIM_STALE_MS, 1);
+  const staleRecoveryTimeoutMs = _durationMs(
+    opts.staleRecoveryTimeoutMs ?? DEFAULT_STALE_RECOVERY_TIMEOUT_MS,
+    DEFAULT_STALE_RECOVERY_TIMEOUT_MS,
+    0
+  );
+  const startedAt = Date.now();
+  const deadline = startedAt + timeoutMs;
+  const dir = path.dirname(lockPath);
+  const canonical = _canonicalLockPath(lockPath);
+  let staleRecoveryDeadline = 0;
+  let contended = false;
+  const held = globalState.locks.get(canonical);
+  if (held) {
+    held.depth += 1;
+    return {
+      waitedMs: 0,
+      contended: false,
+      release: () => {
+        held.depth -= 1;
+        if (held.depth <= 0) {
+          globalState.locks.delete(canonical);
+          _releaseLockFile(held.lockPath, held.token);
+        }
+      },
+    };
+  }
+
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+
+  while (true) {
+    try {
+      const token = globalState.token;
+      _writeLockClaim(lockPath, {
+        pid: process.pid,
+        thread_id: threadId,
+        token,
+        created_at_ms: Date.now(),
+        label: opts.label || '',
+      });
+      const entry = { depth: 1, lockPath, token };
+      globalState.locks.set(canonical, entry);
+      return {
+        waitedMs: Date.now() - startedAt,
+        contended,
+        release: () => {
+          entry.depth -= 1;
+          if (entry.depth > 0) return;
+          globalState.locks.delete(canonical);
+          _releaseLockFile(lockPath, token);
+        },
+      };
+    } catch (err) {
+      if (err?.code !== 'EEXIST') throw err;
+      contended = true;
+      const observed = _inspectLock(lockPath);
+      const staleReason = _staleReason(observed, staleMs, claimStaleMs);
+      if (staleReason) {
+        if (_unlinkIfUnchanged(lockPath, observed)) continue;
+        if (!staleRecoveryDeadline) staleRecoveryDeadline = Date.now() + staleRecoveryTimeoutMs;
+        if (Date.now() < staleRecoveryDeadline) {
+          _sleepSync(pollMs);
+          continue;
+        }
+      } else if (!observed.info) {
+        const waitMs = Math.min(pollMs, Math.max(1, claimStaleMs - _lockAgeMs(observed)));
+        _sleepSync(waitMs);
+        continue;
+      } else {
+        staleRecoveryDeadline = 0;
+      }
+      if (Date.now() >= deadline) {
+        throw _lockBusyError(lockPath, observed.info);
+      }
+      _sleepSync(Math.min(pollMs, Math.max(1, deadline - Date.now())));
+    }
+  }
+}
+
+function createSqliteWriteLock(lockPath, opts = {}) {
+  let depth = 0;
+  const onEvent = typeof opts.onEvent === 'function' ? opts.onEvent : null;
+  return function withSqliteWriteLock(fn, label = opts.label || '') {
+    // Reentrant within the same connection: already inside a held write lock, so
+    // no re-acquire and no event (the outer call owns the timing).
+    if (depth > 0) return fn();
+    depth += 1;
+    let acquired = null;
+    const waitStart = onEvent ? Date.now() : 0;
+    try {
+      try {
+        acquired = _acquire(lockPath, { ...opts, label });
+      } catch (err) {
+        // Surface contention to instrumentation even when the acquire fails fast
+        // (e.g. main-thread 0ms timeout) so callers can see busy/starvation.
+        if (onEvent) {
+          try {
+            // Pass the busy error so instrumentation can attribute the lock HOLDER
+            // (the error message carries the holder pid). Extra field; existing
+            // consumers that ignore it are unaffected.
+            onEvent({ label, waitedMs: Date.now() - waitStart, heldMs: 0, contended: true, acquired: false, error: err });
+          } catch {}
+        }
+        throw err;
+      }
+      const heldStart = onEvent ? Date.now() : 0;
+      try {
+        return fn();
+      } finally {
+        try { acquired.release(); } finally {
+          if (onEvent) {
+            try {
+              onEvent({
+                label,
+                waitedMs: acquired.waitedMs,
+                heldMs: Date.now() - heldStart,
+                contended: acquired.contended,
+                acquired: true,
+              });
+            } catch {}
+          }
+        }
+      }
+    } finally {
+      depth -= 1;
+    }
+  };
+}
+
+// Async, bounded retry for SQLITE_WRITE_LOCK_BUSY. Safe because the busy error is
+// always thrown while ACQUIRING the lock — before the wrapped write runs — so the
+// failed write never partially applied. Used by background (worker) write paths so
+// transient contention retries instead of surfacing to the user. Never use this on
+// the main thread's hot path with a blocking sleep; the delay here is async.
+async function retryOnWriteLockBusy(fn, opts = {}) {
+  const retries = Number.isInteger(opts.retries) ? Math.max(0, opts.retries) : 2;
+  const backoffMs = Number.isFinite(opts.backoffMs) ? Math.max(1, opts.backoffMs) : 50;
+  let attempt = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err?.code !== 'SQLITE_WRITE_LOCK_BUSY' || attempt >= retries) throw err;
+      attempt += 1;
+      if (typeof opts.onRetry === 'function') {
+        try { opts.onRetry({ attempt, retries, error: err }); } catch {}
+      }
+      const jitter = Math.floor(Math.random() * backoffMs);
+      await new Promise((resolve) => setTimeout(resolve, backoffMs * attempt + jitter));
+    }
+  }
+}
+
+function isLikelyWriteSql(sql) {
+  return WRITE_SQL_RE.test(_stripLeadingSqlComments(sql));
+}
+
+function isLikelyWritePragma(pragma) {
+  const text = _stripLeadingSqlComments(pragma);
+  if (/^\s*PRAGMA\b/i.test(text)) return WRITE_PRAGMA_RE.test(text.replace(/^\s*PRAGMA\b/i, ''));
+  return WRITE_PRAGMA_RE.test(text);
+}
+
+function containsLikelyWriteSql(sql) {
+  return String(sql || '')
+    .split(';')
+    .some((statement) => {
+      const text = _stripLeadingSqlComments(statement);
+      if (!text) return false;
+      return isLikelyWriteSql(text) || isLikelyWritePragma(text);
+    });
+}
+
+function installSqliteWriteLock(db, dbPath, opts = {}) {
+  if (!db || db.__sqliteWriteLockInstalled) return db;
+  const lockPath = opts.lockPath || `${dbPath}.write-lock`;
+  const withLock = createSqliteWriteLock(lockPath, opts);
+
+  const originalPrepare = db.prepare.bind(db);
+  db.prepare = function prepareWithWriteLock(sql, ...args) {
+    const stmt = originalPrepare(sql, ...args);
+    if (!isLikelyWriteSql(sql) || typeof stmt.run !== 'function') return stmt;
+    const originalRun = stmt.run.bind(stmt);
+    stmt.run = (...runArgs) => withLock(() => originalRun(...runArgs), 'statement');
+    return stmt;
+  };
+
+  const originalExec = db.exec.bind(db);
+  db.exec = function execWithWriteLock(sql, ...args) {
+    if (!containsLikelyWriteSql(sql)) return originalExec(sql, ...args);
+    return withLock(() => originalExec(sql, ...args), 'exec');
+  };
+
+  const originalPragma = db.pragma.bind(db);
+  db.pragma = function pragmaWithWriteLock(pragma, ...args) {
+    if (!isLikelyWritePragma(pragma)) return originalPragma(pragma, ...args);
+    return withLock(() => originalPragma(pragma, ...args), 'pragma');
+  };
+
+  const originalTransaction = db.transaction.bind(db);
+  db.transaction = function transactionWithWriteLock(fn) {
+    const txn = originalTransaction(fn);
+    const wrap = (call, label) => (...args) => withLock(() => call(...args), label);
+    const wrapped = wrap(txn, 'transaction');
+    for (const mode of ['default', 'deferred', 'immediate', 'exclusive']) {
+      if (typeof txn[mode] === 'function') wrapped[mode] = wrap(txn[mode].bind(txn), `transaction:${mode}`);
+    }
+    return wrapped;
+  };
+
+  Object.defineProperty(db, '__sqliteWriteLockInstalled', { value: true });
+  Object.defineProperty(db, '__sqliteWriteLockPath', { value: lockPath });
+  return db;
+}
+
+module.exports = {
+  createSqliteWriteLock,
+  containsLikelyWriteSql,
+  installSqliteWriteLock,
+  isLikelyWritePragma,
+  isLikelyWriteSql,
+  retryOnWriteLockBusy,
+};