@yemi33/minions 0.1.2116 → 0.1.2117

package/engine/db/index.js

@@ -88,16 +88,45 @@ function getDb() {
   try {
     _installExperimentalWarningFilter();
     const { DatabaseSync } = require('node:sqlite');
-    _db = new DatabaseSync(dbPath);
-    _dbPath = dbPath;
-    // WAL mode lets the engine writer and dashboard reader hit the same
-    // file from two processes without lock contention. NORMAL synchronous
-    // is the recommended WAL pairing (durable enough; one OS-level fsync
-    // per checkpoint instead of per write).
-    _db.exec('PRAGMA journal_mode = WAL');
-    _db.exec('PRAGMA foreign_keys = ON');
-    _db.exec('PRAGMA synchronous = NORMAL');
-    _db.exec('PRAGMA busy_timeout = 5000');
+    // Concurrent cold-openers (parallel child processes in tests; engine
+    // + dashboard cold-starting together) can race on the exclusive lock
+    // that SQLite needs to either create the file or upgrade
+    // journal_mode to WAL on the first connection. `busy_timeout` only
+    // applies to PRAGMAs and queries AFTER the connection is open, so
+    // `new DatabaseSync(dbPath)` itself and the initial WAL PRAGMA can
+    // still return SQLITE_BUSY. Retry the whole open+PRAGMA sequence
+    // with backoff so a brief lock contention isn't a hard failure.
+    // Phase 9.4 removed the JSON fallback that previously hid this
+    // race — without retry, parallel test runs fail intermittently with
+    // "small-state-store: SQLite unavailable (... database is locked)".
+    const maxAttempts = 20;
+    let lastErr = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        _db = new DatabaseSync(dbPath);
+        // busy_timeout MUST be set before any other PRAGMA so subsequent
+        // statements wait instead of failing immediately on contention.
+        _db.exec('PRAGMA busy_timeout = 5000');
+        _db.exec('PRAGMA journal_mode = WAL');
+        _db.exec('PRAGMA foreign_keys = ON');
+        _db.exec('PRAGMA synchronous = NORMAL');
+        _dbPath = dbPath;
+        lastErr = null;
+        break;
+      } catch (e) {
+        lastErr = e;
+        const msg = String(e && e.message || '');
+        const isBusy = /database is locked|SQLITE_BUSY|SQLITE_LOCKED/i.test(msg);
+        if (!isBusy || attempt === maxAttempts - 1) throw e;
+        if (_db) { try { _db.close(); } catch { /* best-effort */ } _db = null; }
+        // Synchronous backoff: 10ms, 20ms, 40ms... capped at 250ms.
+        // Total worst-case wait ~3s, still under the 5s busy_timeout.
+        const delayMs = Math.min(250, 10 * (1 << Math.min(attempt, 5)));
+        const end = Date.now() + delayMs;
+        while (Date.now() < end) { /* busy-wait — sub-300ms total */ }
+      }
+    }
+    if (lastErr) throw lastErr;
     const { runMigrations } = require('./migrate');
     runMigrations(_db);
     return _db;

package/engine/dispatch-store.js

@@ -36,9 +36,7 @@ function _parseRow(row) {
 
 function readDispatchSectioned() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readDispatchJsonFallback(); }  // SQLite unavailable
+  const db = getDb();
 
   // All rows, all statuses. Matches the legacy dispatch.json reader's
   // semantics — returns the complete dispatch state regardless of how old

package/engine/dispatch.js

@@ -10,11 +10,11 @@ const queries = require('./queries');
 const { setCooldown, setCooldownFailure } = require('./cooldown');
 const dispatchEvents = require('./dispatch-events');
 
-const { safeJsonArr, mutateJsonFileLocked, mutateWorkItems,
+const { safeJsonArr, mutateWorkItems,
   mutatePullRequests, getProjects, projectPrPath, log, ts, dateStamp,
   sidecarDispatchPrompt, deleteDispatchPromptSidecar,
   WI_STATUS, WORK_TYPE, DISPATCH_RESULT, ENGINE_DEFAULTS, AGENT_STATUS, FAILURE_CLASS, PR_STATUS } = shared;
-const { getConfig, DISPATCH_PATH, INBOX_DIR } = queries;
+const { getConfig, INBOX_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
 
@@ -58,72 +58,37 @@ function _sidecarChangedPrompts(dispatch, prevSnap) {
   }
 }
 
-// SQL-backed mutator (Phase 1). Same external contract as the legacy
-// JSON path: mutator receives a `{ pending, active, completed, review }`
-// object, mutates in place (or returns a replacement), and the changes
-// land transactionally in the dispatches table. The diff-then-apply trick
-// in dispatch-store preserves every field via the `data` JSON column, so
-// new dispatch fields the engine adds in future commits don't need any
-// migration — they round-trip automatically.
-//
-// Fallback path: if SQLite is unavailable (Node < 22.5, the DB init failed,
-// the table doesn't exist yet because the migration hasn't run) we fall
-// back to the legacy mutateJsonFileLocked flow against dispatch.json.
-// The migration leaves dispatch.json.pre-sql-<ts> on disk, so an operator
-// pinning to an older release can rename it back.
+// SQL-backed mutator (Phase 9.4 SQL-only). mutator receives a
+// `{ pending, active, completed, review }` object, mutates in place
+// (or returns a replacement), and the changes land transactionally in
+// the dispatches table. The diff-then-apply trick in dispatch-store
+// preserves every field via the `data` JSON column, so new dispatch
+// fields the engine adds in future commits don't need any migration —
+// they round-trip automatically. SQLite failures propagate; the CLI
+// shim in bin/minions.js guarantees node:sqlite is loadable.
 function mutateDispatch(mutator) {
-  // Try the SQL path first.
-  try {
-    const store = require('./dispatch-store');
-    const { wrote, result } = store.applyDispatchMutation((dispatch) => {
-      dispatch.pending = Array.isArray(dispatch.pending) ? dispatch.pending : [];
-      dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
-      dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
-      dispatch.review = Array.isArray(dispatch.review) ? dispatch.review : [];
-      const prevSnap = _snapshotPrompts(dispatch);
-      const next = mutator(dispatch) ?? dispatch;
-      // Prompt-size guard: only scan items whose prompt changed (or new items),
-      // so a 100-item status-flip doesn't re-byte-count every prompt.
-      _sidecarChangedPrompts(next, prevSnap);
-      return next;
-    });
-    if (wrote) {
-      try { require('./queries').invalidateDispatchCache(); } catch {}
-      try { require('./db-events').emitStateEvent('dispatch'); } catch { /* optional */ }
-      // Mirror back to dispatch.json for tests + tools that fs.readFileSync
-      // the file directly. SQL is the source of truth; the JSON file is
-      // regenerated from SQL on every successful mutation, never independently
-      // mutated. Cheap to delete once those direct-JSON readers are gone.
-      try { store._mirrorJsonFromSql(); } catch { /* best-effort */ }
-    }
-    return result;
-  } catch (e) {
-    // Only fall back if the failure looks like a "DB not available" case,
-    // not a programming error. Surface mutator exceptions to the caller.
-    if (e && /SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) {
-      // fall through to legacy JSON path below
-    } else {
-      throw e;
-    }
-  }
-
-  // Legacy JSON path (pre-Phase 1 fallback). Same code as before.
-  const defaultDispatch = { pending: [], active: [], completed: [] };
-  const result = mutateJsonFileLocked(DISPATCH_PATH, (dispatch) => {
+  const store = require('./dispatch-store');
+  const { wrote, result } = store.applyDispatchMutation((dispatch) => {
     dispatch.pending = Array.isArray(dispatch.pending) ? dispatch.pending : [];
     dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
     dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
+    dispatch.review = Array.isArray(dispatch.review) ? dispatch.review : [];
     const prevSnap = _snapshotPrompts(dispatch);
     const next = mutator(dispatch) ?? dispatch;
+    // Prompt-size guard: only scan items whose prompt changed (or new items),
+    // so a 100-item status-flip doesn't re-byte-count every prompt.
     _sidecarChangedPrompts(next, prevSnap);
     return next;
-  }, {
-    defaultValue: defaultDispatch,
-    onWrote: () => {
-      try { require('./db-events').emitStateEvent('dispatch'); } catch { /* optional */ }
-    },
   });
-  try { require('./queries').invalidateDispatchCache(); } catch {}
+  if (wrote) {
+    try { require('./queries').invalidateDispatchCache(); } catch {}
+    try { require('./db-events').emitStateEvent('dispatch'); } catch { /* optional */ }
+    // Mirror back to dispatch.json for tests + tools that fs.readFileSync
+    // the file directly. SQL is the source of truth; the JSON file is
+    // regenerated from SQL on every successful mutation, never independently
+    // mutated. Cheap to delete once those direct-JSON readers are gone.
+    try { store._mirrorJsonFromSql(); } catch { /* best-effort */ }
+  }
   return result;
 }
 

package/engine/pull-requests-store.js

@@ -123,9 +123,7 @@ function _resyncScopeIfJsonDiverged(db, scope) {
 
 function readPullRequestsForScope(scope) {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJsonArrayFallback(scope); }
+  const db = getDb();
 
   _resyncScopeIfJsonDiverged(db, scope);
 
@@ -170,23 +168,7 @@ function _enumerateJsonScopes() {
 
 function readAllPullRequests() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch {
-    // Issue #3035: SQLite unavailable (Node 22.x without
-    // --experimental-sqlite) — read every JSON scope on disk so the
-    // aggregate readers (queries.getPullRequests, shared.getPrLinks)
-    // continue to return real data instead of [].
-    const out = [];
-    for (const scope of _enumerateJsonScopes()) {
-      for (const pr of _readJsonArrayFallback(scope)) {
-        if (!pr || typeof pr !== 'object') continue;
-        pr._scope = scope;
-        out.push(pr);
-      }
-    }
-    return out;
-  }
+  const db = getDb();
 
   try { _resyncScopeIfJsonDiverged(db, 'central'); } catch {}
   const knownScopes = db.prepare('SELECT DISTINCT scope FROM pull_requests').all().map(r => r.scope);
@@ -273,11 +255,7 @@ function _applyPullRequestsDiff(db, diff) {
 
 function applyPullRequestsMutation(scope, mutator) {
   const { getDb, withTransaction } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch (e) {
-    throw new Error(`engine/pull-requests-store: SQLite unavailable (${e.message}); cannot mutate pull_requests`);
-  }
+  const db = getDb();
 
   return withTransaction(db, () => {
     _resyncScopeIfJsonDiverged(db, scope);

package/engine/shared.js

@@ -591,9 +591,11 @@ function _routeJsonReadToSql(p) {
       const store = require('./pull-requests-store');
       return { value: store.readPullRequestsForScope('central') };
     }
-  } catch {
-    // SQLite unavailable / store load failure — fall through to disk read.
-    return null;
+  } catch (e) {
+    // Phase 9.4: store/load failures (not SQLite-unavailable — the CLI shim
+    // in bin/minions.js guarantees node:sqlite is loadable) propagate up so
+    // the caller can decide whether to retry or surface.
+    throw e;
   }
   return null;
 }
@@ -1373,34 +1375,38 @@ function _tryRouteMutateToSql(filePath, mutateFn, onWrote) {
   // Don't hijack writes to ad-hoc paths that happen to share the basename.
   if (smallRoute) {
     if (!fpNorm.endsWith('/engine/' + baseName)) return null;
-    let result;
-    try {
-      const store = require('./small-state-store');
+    const store = require('./small-state-store');
+    // Hold the JSON file lock across the SQL transaction AND the mirror
+    // write. The SQL transaction itself is cross-process serialized via
+    // BEGIN IMMEDIATE inside the SQL store, but the JSON mirror is a
+    // separate read-from-SQL → atomic-rename that can race across
+    // processes: an earlier mirror's stale snapshot can land AFTER a
+    // later mirror's complete snapshot and lose committed rows from the
+    // on-disk JSON file. Pre-Phase-9.4 this was masked by the JSON
+    // fallback (concurrent writers serialized through the same lock at
+    // the bottom of mutateJsonFileLocked); after the fallback removal,
+    // the bare mirror races. Locking around the SQL+mirror block puts
+    // those two operations back into one cross-process critical section.
+    const lockPath = `${filePath}.lock`;
+    return withFileLock(lockPath, () => {
       const out = store[smallRoute.fn]((data) => {
         const next = mutateFn(data);
         if (onWrote) onWrote();
         return next;
       });
-      result = out && Object.prototype.hasOwnProperty.call(out, 'result') ? out.result : undefined;
+      const result = out && Object.prototype.hasOwnProperty.call(out, 'result') ? out.result : undefined;
       try { store[smallRoute.mirror](filePath); } catch { /* mirror best-effort */ }
-    } catch (e) {
-      // SQLite unavailable / table missing — fall through to JSON path.
-      const msg = e && e.message ? String(e.message) : '';
-      if (/SQLite unavailable|no such table|not a database|node:sqlite/i.test(msg)) {
-        return null;
+      if (!fs.existsSync(filePath)) {
+        try {
+          fs.mkdirSync(path.dirname(filePath), { recursive: true });
+          const fallback = smallRoute.defaultShape === 'array'
+            ? (Array.isArray(result) ? result : [])
+            : (result && typeof result === 'object' && !Array.isArray(result) ? result : {});
+          safeWrite(filePath, fallback);
+        } catch { /* best-effort */ }
       }
-      throw e;
-    }
-    if (!fs.existsSync(filePath)) {
-      try {
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        const fallback = smallRoute.defaultShape === 'array'
-          ? (Array.isArray(result) ? result : [])
-          : (result && typeof result === 'object' && !Array.isArray(result) ? result : {});
-        safeWrite(filePath, fallback);
-      } catch { /* best-effort */ }
-    }
-    return { routed: result };
+      return { routed: result };
+    });
   }
 
   let result;
@@ -3206,32 +3212,20 @@ const WATCH_ACTION_TYPE = {
 
 /**
  * Phase 7 — small state file mutators. Each routes through the
- * small-state-store, mirrors back to its JSON file, and emits a topic
- * event on real writes. SQLite failure falls through to the legacy
- * mutateJsonFileLocked path.
+ * small-state-store and mirrors back to its JSON file, then emits a topic
+ * event on real writes. SQL-canonical (Phase 9.4): SQLite failures
+ * propagate; the CLI shim in bin/minions.js guarantees `node:sqlite` is
+ * loadable on every supported Node version.
  */
-function _smallStateMutator({ filePath, applyMutation, mirror, topic, defaultValue }) {
+function _smallStateMutator({ filePath, applyMutation, mirror, topic }) {
   return (mutator) => {
-    try {
-      const store = require('./small-state-store');
-      const { wrote, result } = store[applyMutation]((obj) => mutator(obj) || obj);
-      if (wrote) {
-        try { if (mirror && typeof store[mirror] === 'function') store[mirror](filePath); } catch { /* mirror best-effort */ }
-        try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
-      }
-      return result;
-    } catch (e) {
-      if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) throw e;
+    const store = require('./small-state-store');
+    const { wrote, result } = store[applyMutation]((obj) => mutator(obj) || obj);
+    if (wrote) {
+      try { if (mirror && typeof store[mirror] === 'function') store[mirror](filePath); } catch { /* mirror best-effort */ }
+      try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
     }
-    return mutateJsonFileLocked(filePath, (data) => {
-      if (data == null) data = defaultValue();
-      return mutator(data) || data;
-    }, {
-      defaultValue: defaultValue(),
-      onWrote: () => {
-        try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
-      },
-    });
+    return result;
   };
 }
 
@@ -3287,31 +3281,18 @@ function _qaDualWriteEnabled() {
 function _qaMutator({ filePath, applyMutation, mirror, topic }) {
   return (mutator) => {
     return withFileLock(filePath + '.lock', () => {
-      try {
-        const store = require('./small-state-store');
-        const { wrote, result } = store[applyMutation]((arr) => {
-          if (!Array.isArray(arr)) arr = [];
-          return mutator(arr) || arr;
-        });
-        if (wrote) {
-          if (_qaDualWriteEnabled()) {
-            try { if (mirror && typeof store[mirror] === 'function') store[mirror](filePath); } catch { /* mirror best-effort */ }
-          }
-          try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
+      const store = require('./small-state-store');
+      const { wrote, result } = store[applyMutation]((arr) => {
+        if (!Array.isArray(arr)) arr = [];
+        return mutator(arr) || arr;
+      });
+      if (wrote) {
+        if (_qaDualWriteEnabled()) {
+          try { if (mirror && typeof store[mirror] === 'function') store[mirror](filePath); } catch { /* mirror best-effort */ }
         }
-        return result;
-      } catch (e) {
-        if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) throw e;
-        return mutateJsonFileLocked(filePath, (data) => {
-          if (!Array.isArray(data)) data = [];
-          return mutator(data) || data;
-        }, {
-          defaultValue: [],
-          onWrote: () => {
-            try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
-          },
-        });
+        try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
       }
+      return result;
     }, { timeoutMs: 5000, retries: 3 });
   };
 }
@@ -3334,36 +3315,20 @@ const mutateQaSessions = _qaMutator({
  * Route a watches mutation through the SQL store. Same shape as
  * mutateWorkItems / mutatePullRequests: mutator receives the watches
  * array, mutates in place or returns a replacement, and the store
- * diffs by id. Falls back to the legacy mutateJsonFileLocked path on
- * SQLite failure.
+ * diffs by id. SQL-canonical (Phase 9.4); SQLite failures propagate.
  */
 function mutateWatches(mutator) {
   const watchesPath = path.join(MINIONS_DIR, 'engine', 'watches.json');
-  try {
-    const store = require('./watches-store');
-    const { wrote, result } = store.applyWatchesMutation((arr) => {
-      if (!Array.isArray(arr)) arr = [];
-      return mutator(arr) || arr;
-    });
-    if (wrote) {
-      try { store._mirrorJsonFromSql(watchesPath); } catch { /* mirror best-effort */ }
-      try { require('./db-events').emitStateEvent('watches'); } catch { /* optional */ }
-    }
-    return result;
-  } catch (e) {
-    if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) {
-      throw e;
-    }
-  }
-  return mutateJsonFileLocked(watchesPath, (data) => {
-    if (!Array.isArray(data)) data = [];
-    return mutator(data) || data;
-  }, {
-    defaultValue: [],
-    onWrote: () => {
-      try { require('./db-events').emitStateEvent('watches'); } catch { /* optional */ }
-    },
+  const store = require('./watches-store');
+  const { wrote, result } = store.applyWatchesMutation((arr) => {
+    if (!Array.isArray(arr)) arr = [];
+    return mutator(arr) || arr;
   });
+  if (wrote) {
+    try { store._mirrorJsonFromSql(watchesPath); } catch { /* mirror best-effort */ }
+    try { require('./db-events').emitStateEvent('watches'); } catch { /* optional */ }
+  }
+  return result;
 }
 
 /**
@@ -3371,37 +3336,20 @@ function mutateWatches(mutator) {
  * mirror. Same shape as mutateWorkItems / mutatePullRequests: mutator
  * receives the full legacy-shape metrics object, mutates in place or
  * returns a replacement, and the store diffs by (kind, key) row.
- *
- * Falls back to the legacy mutateJsonFileLocked path on SQLite failure
- * so a node:sqlite-broken install keeps recording metrics.
+ * SQL-canonical (Phase 9.4); SQLite failures propagate.
  */
 function mutateMetrics(mutator) {
   const metricsPath = path.join(MINIONS_DIR, 'engine', 'metrics.json');
-  try {
-    const store = require('./metrics-store');
-    const { wrote, result } = store.applyMetricsMutation((m) => {
-      if (!m || typeof m !== 'object') m = {};
-      return mutator(m) || m;
-    });
-    if (wrote) {
-      try { store._mirrorJsonFromSql(metricsPath); } catch { /* mirror best-effort */ }
-      try { require('./db-events').emitStateEvent('metrics'); } catch { /* optional */ }
-    }
-    return result;
-  } catch (e) {
-    if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) {
-      throw e;
-    }
-  }
-  return mutateJsonFileLocked(metricsPath, (metrics) => {
-    if (!metrics || typeof metrics !== 'object') metrics = {};
-    return mutator(metrics) || metrics;
-  }, {
-    defaultValue: {},
-    onWrote: () => {
-      try { require('./db-events').emitStateEvent('metrics'); } catch { /* optional */ }
-    },
+  const store = require('./metrics-store');
+  const { wrote, result } = store.applyMetricsMutation((m) => {
+    if (!m || typeof m !== 'object') m = {};
+    return mutator(m) || m;
   });
+  if (wrote) {
+    try { store._mirrorJsonFromSql(metricsPath); } catch { /* mirror best-effort */ }
+    try { require('./db-events').emitStateEvent('metrics'); } catch { /* optional */ }
+  }
+  return result;
 }
 
 /** Update per-agent review metrics (prsApproved/prsRejected). Only writes for configured agents. */
@@ -5167,23 +5115,11 @@ function addPrLink(prId, itemId, { project = null, url = '', prNumber = null } =
     links[effectivePrId] = [...mergedCurrent];
     return links;
   };
-  // Phase 9.1: pr-links is SQL-canonical via small-state-store; the JSON file
-  // is a dual-write mirror. SQLite failures fall through to the legacy JSON
-  // path so older installs without --experimental-sqlite still work.
-  let routedViaSql = false;
-  try {
-    const store = require('./small-state-store');
-    store.applyPrLinksMutation(mutator);
-    try { store._mirrorPrLinksJson(); } catch { /* mirror best-effort */ }
-    routedViaSql = true;
-  } catch (e) {
-    if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) {
-      throw e;
-    }
-  }
-  if (!routedViaSql) {
-    mutateJsonFileLocked(PR_LINKS_PATH, mutator, { defaultValue: {} });
-  }
+  // Phase 9.4: pr-links is SQL-only via small-state-store; the JSON file
+  // is a write-only mirror artifact for legacy direct-disk readers.
+  const store = require('./small-state-store');
+  store.applyPrLinksMutation(mutator);
+  try { store._mirrorPrLinksJson(); } catch { /* mirror best-effort */ }
 
   if (!project) return;
   const prPath = projectPrPath(project);
@@ -5575,42 +5511,27 @@ function listProcessReachable(rootPids, allProcesses = null) {
  * @param {Function} mutator - Receives the array, mutates in place or returns new value
  */
 function mutateWorkItems(filePath, mutator) {
-  // Phase 2 SQL path → Phase 9 SQL-only. Route through work-items-store so
-  // SQL is the canonical (and only) store; the legacy JSON mirror was
-  // retired in Phase 9.
-  //
-  // The SQL store identifies records by `scope` (central or project name)
-  // derived from the file path's last two segments. Ad-hoc file paths
-  // outside the MINIONS_DIR layout (e.g. tests using createTmpDir()) can't
-  // be mapped to a stable scope, so we short-circuit to the legacy
-  // JSON path for those. Production callers always use
-  // shared.projectWorkItemsPath(p) / MINIONS_DIR/work-items.json.
-  //
-  // SQLite failures fall through to the legacy JSON path below — keeps a
-  // node:sqlite-broken install fully functional.
+  // Phase 9.4 SQL-only. Route through work-items-store; SQL is the canonical
+  // (and only) store. The legacy JSON path below remains ONLY for ad-hoc
+  // file paths outside the MINIONS_DIR layout (e.g. tests using
+  // createTmpDir()) that can't be mapped to a stable scope. Production
+  // callers always use shared.projectWorkItemsPath(p) / MINIONS_DIR/work-items.json.
   const fpNorm = String(filePath).replace(/\\/g, '/');
   const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
   const insideMinionsDir = fpNorm.startsWith(minionsNorm + '/') || fpNorm === minionsNorm + '/work-items.json';
   if (insideMinionsDir) {
-    try {
-      const store = require('./work-items-store');
-      const scope = store.scopeForFilePath(filePath);
-      const { wrote, result } = store.applyWorkItemsMutation(scope, (items) => {
-        if (!Array.isArray(items)) items = [];
-        return mutator(items) || items;
-      });
-      if (wrote) {
-        try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror best-effort */ }
-        try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
-      }
-      try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
-      return result;
-    } catch (e) {
-      if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) {
-        throw e;
-      }
-      // Fall through to the legacy JSON path on SQLite errors only.
+    const store = require('./work-items-store');
+    const scope = store.scopeForFilePath(filePath);
+    const { wrote, result } = store.applyWorkItemsMutation(scope, (items) => {
+      if (!Array.isArray(items)) items = [];
+      return mutator(items) || items;
+    });
+    if (wrote) {
+      try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror best-effort */ }
+      try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
     }
+    try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
+    return result;
   }
 
   const result = mutateJsonFileLocked(filePath, (data) => {
@@ -5648,31 +5569,24 @@ function reopenWorkItem(wi) {
  * @param {Function} mutator - Receives the array, mutates in place or returns new value
  */
 function mutatePullRequests(filePath, mutator) {
-  // Phase 3 SQL path → Phase 9 SQL-only. Route through pull-requests-store
-  // when filePath sits under MINIONS_DIR. Ad-hoc tmp paths (legacy tests
-  // using createTmpDir) and SQLite failures fall through to the JSON path.
+  // Phase 9.4 SQL-only. Route through pull-requests-store when filePath sits
+  // under MINIONS_DIR. Ad-hoc tmp paths (legacy tests using createTmpDir)
+  // still fall through to the JSON path.
   const fpNorm = String(filePath).replace(/\\/g, '/');
   const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
   const insideMinionsDir = fpNorm.startsWith(minionsNorm + '/') || fpNorm === minionsNorm + '/pull-requests.json';
   if (insideMinionsDir) {
-    try {
-      const store = require('./pull-requests-store');
-      const scope = store.scopeForFilePath(filePath);
-      const { wrote, result } = store.applyPullRequestsMutation(scope, (prs) => {
-        if (!Array.isArray(prs)) prs = [];
-        return mutator(prs) || prs;
-      });
-      if (wrote) {
-        try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror best-effort */ }
-        try { require('./db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
-      }
-      return result;
-    } catch (e) {
-      if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) {
-        throw e;
-      }
-      // Fall through to legacy JSON path on SQLite errors only.
+    const store = require('./pull-requests-store');
+    const scope = store.scopeForFilePath(filePath);
+    const { wrote, result } = store.applyPullRequestsMutation(scope, (prs) => {
+      if (!Array.isArray(prs)) prs = [];
+      return mutator(prs) || prs;
+    });
+    if (wrote) {
+      try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror best-effort */ }
+      try { require('./db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
     }
+    return result;
   }
 
   return mutateJsonFileLocked(filePath, (data) => {

package/engine/small-state-store.js

@@ -94,9 +94,7 @@ function _readScheduleRunsFromSql(db) {
 
 function readScheduleRuns() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('schedule-runs.json')) || {}; }
+  const db = getDb();
   _resyncScheduleRunsIfDiverged(db);
   const out = _readScheduleRunsFromSql(db);
   if (Object.keys(out).length === 0) {
@@ -207,9 +205,7 @@ function _readPipelineRunsFromSql(db) {
 
 function readPipelineRuns() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('pipeline-runs.json')) || {}; }
+  const db = getDb();
   _resyncPipelineRunsIfDiverged(db);
   const out = _readPipelineRunsFromSql(db);
   if (Object.keys(out).length === 0) {
@@ -329,9 +325,7 @@ function _readManagedProcessesFromSql(db) {
 
 function readManagedProcesses() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('managed-processes.json')) || { specs: [] }; }
+  const db = getDb();
   _resyncManagedProcessesIfDiverged(db);
   const out = _readManagedProcessesFromSql(db);
   if (out.specs.length === 0) {
@@ -449,9 +443,7 @@ function _readWorktreePoolFromSql(db) {
 
 function readWorktreePool() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('worktree-pool.json')) || { entries: [] }; }
+  const db = getDb();
   _resyncWorktreePoolIfDiverged(db);
   const out = _readWorktreePoolFromSql(db);
   if (out.entries.length === 0) {
@@ -581,9 +573,7 @@ function _readQaRunsFromSqlOnly(db) {
 
 function readQaRuns() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('qa-runs.json')) || []; }
+  const db = getDb();
   _resyncQaRunsIfDiverged(db);
   const out = _readQaRunsFromSqlOnly(db);
   if (out.length === 0) {
@@ -741,9 +731,7 @@ function _readQaSessionsFromSqlOnly(db) {
 
 function readQaSessions() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('qa-sessions.json')) || []; }
+  const db = getDb();
   _resyncQaSessionsIfDiverged(db);
   const out = _readQaSessionsFromSqlOnly(db);
   if (out.length === 0) {
@@ -875,9 +863,7 @@ function _readPrLinksFromSql(db) {
 
 function readPrLinks() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('pr-links.json')) || {}; }
+  const db = getDb();
   try { _resyncPrLinksIfDiverged(db); }
   catch { /* table may be missing on a stale install — fall back to JSON */ }
   let out;
@@ -984,9 +970,7 @@ function _readCooldownsFromSql(db) {
 
 function readCooldowns() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('cooldowns.json')) || {}; }
+  const db = getDb();
   try { _resyncCooldownsIfDiverged(db); }
   catch { /* table may be missing on stale install */ }
   let out;
@@ -1095,9 +1079,7 @@ function _readPendingRebasesFromSql(db) {
 
 function readPendingRebases() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('pending-rebases.json')) || []; }
+  const db = getDb();
   try { _resyncPendingRebasesIfDiverged(db); }
   catch { /* table missing */ }
   let out;
@@ -1197,9 +1179,7 @@ function _readCcSessionsFromSql(db) {
 
 function readCcSessions() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('cc-sessions.json')) || []; }
+  const db = getDb();
   try { _resyncCcSessionsIfDiverged(db); }
   catch { /* table missing */ }
   let out;
@@ -1307,9 +1287,7 @@ function _readDocSessionsFromSql(db) {
 
 function readDocSessions() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJson(_resolveFilePath('doc-sessions.json')) || {}; }
+  const db = getDb();
   try { _resyncDocSessionsIfDiverged(db); }
   catch { /* table missing */ }
   let out;

package/engine/work-items-store.js

@@ -75,9 +75,7 @@ function _readJsonArrayFallback(scope) {
 
 function readWorkItemsForScope(scope) {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch { return _readJsonArrayFallback(scope); }
+  const db = getDb();
 
   _resyncScopeIfJsonDiverged(db, scope);
 
@@ -88,10 +86,9 @@ function readWorkItemsForScope(scope) {
   `).all(scope);
 
   if (rows.length === 0) {
-    // Same fallback shape as dispatch-store: SQL empty AND JSON has
-    // content means a test seeded via fs.writeFileSync (legacy helper)
-    // or a fresh install pre-migration. Returning the JSON keeps those
-    // call sites working without touching every helper.
+    // SQL empty AND JSON has content means a test seeded via fs.writeFileSync
+    // (legacy helper) or a fresh install pre-migration. Returning the JSON
+    // keeps those call sites working without touching every helper.
     const fallback = _readJsonArrayFallback(scope);
     if (fallback.length > 0) return fallback;
     return [];
@@ -161,29 +158,9 @@ function _enumerateJsonScopes() {
 // Read all rows across all scopes — used by queries.getWorkItems which
 // needs to surface central + every project's items in a single shot,
 // tagged with their source scope.
-//
-// Issue #3035: SQL-unavailable installs (Node 22.x without
-// --experimental-sqlite, prior to v0.1.2113) returned [] from this path
-// because `getDb()` throws and the legacy `return null` signal was
-// swallowed by `queries.getWorkItems`'s `|| []`. Mirror the per-scope
-// reader's JSON-fallback shape so the aggregate API stays useful on
-// Node versions that don't have node:sqlite enabled.
 function readAllWorkItems() {
   const { getDb } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch {
-    // SQLite unavailable — read every JSON scope on disk directly.
-    const out = [];
-    for (const scope of _enumerateJsonScopes()) {
-      for (const wi of _readJsonArrayFallback(scope)) {
-        if (!wi || typeof wi !== 'object') continue;
-        wi._source = scope;
-        out.push(wi);
-      }
-    }
-    return out;
-  }
+  const db = getDb();
 
   // Pick up any external JSON edits for every scope SQL knows about.
   // Also resync 'central' explicitly so first-time reads on a JSON-only
@@ -326,11 +303,7 @@ function _hydrateScopeFromJson(db, scope) {
 
 function applyWorkItemsMutation(scope, mutator) {
   const { getDb, withTransaction } = require('./db');
-  let db;
-  try { db = getDb(); }
-  catch (e) {
-    throw new Error(`engine/work-items-store: SQLite unavailable (${e.message}); cannot mutate work_items`);
-  }
+  const db = getDb();
 
   return withTransaction(db, () => {
     // Re-hydrate SQL from JSON if the file was touched outside the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2116",
+  "version": "0.1.2117",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"