@yemi33/minions 0.1.2115 → 0.1.2116

package/bin/minions.js

@@ -34,6 +34,27 @@
  *   minions uninstall --confirm      Remove Minions and uninstall package
  */
 
+// Phase 9.4 (issue #3035 hardening): self-reexec on Node 22.x without
+// --experimental-sqlite so the CLI PARENT process can load `node:sqlite`
+// for in-process store reads (status, doctor, etc.). On Node 24+ this is a
+// no-op (sqlite is unflagged). Must run BEFORE any `require('engine/*')` —
+// engine modules pull in `node:sqlite` transitively via `engine/db`.
+(function _ensureSqliteFlagSelfReexec() {
+  const major = parseInt(String(process.versions.node).split('.')[0], 10);
+  if (!Number.isFinite(major) || major < 22 || major >= 24) return;
+  const opts = String(process.env.NODE_OPTIONS || '');
+  if (opts.includes('--experimental-sqlite')) return;
+  if (process.env.MINIONS_FORCE_JSON === '1') return; // explicit opt-out
+  const { spawnSync } = require('child_process');
+  const nextOpts = (opts + ' --experimental-sqlite').trim();
+  const res = spawnSync(
+    process.execPath,
+    ['--experimental-sqlite', __filename, ...process.argv.slice(2)],
+    { stdio: 'inherit', env: { ...process.env, NODE_OPTIONS: nextOpts } }
+  );
+  process.exit(res.status == null ? 1 : res.status);
+})();
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');

package/engine/cleanup.js

@@ -1410,12 +1410,19 @@ async function runCleanup(config, verbose = false) {
   } catch (e) { log('warn', 'clean stale PID files: ' + e.message); }
 
   // 13. Prune test-results.json — keep last 200 entries
+  // Phase 9.3: route through shared.mutateTestResults so the read+trim+write
+  // is atomic under the file lock (previously a safeJsonArr → safeWrite race).
   try {
     const testResultsPath = path.join(ENGINE_DIR, 'test-results.json');
-    const results = shared.safeJsonArr(testResultsPath);
     const TEST_RESULTS_CAP = 200;
-    if (results.length > TEST_RESULTS_CAP) {
-      safeWrite(testResultsPath, results.slice(-TEST_RESULTS_CAP));
+    // Fast path: skip lock acquisition entirely when the file is already
+    // under cap. The atomic re-check inside the mutator handles the race.
+    const probe = shared.safeJsonArr(testResultsPath);
+    if (probe.length > TEST_RESULTS_CAP) {
+      shared.mutateTestResults((curr) => {
+        if (curr.length > TEST_RESULTS_CAP) return curr.slice(-TEST_RESULTS_CAP);
+        return undefined; // already trimmed by a concurrent writer
+      });
     }
   } catch { /* optional — file may not exist */ }
 

package/engine/consolidation.js

@@ -849,7 +849,7 @@ function classifyToKnowledgeBase(items, config) {
       const dir = path.join(KNOWLEDGE_DIR, cat);
       if (fs.existsSync(dir)) count += fs.readdirSync(dir).length;
     }
-    safeWrite(path.join(ENGINE_DIR, 'kb-checkpoint.json'), JSON.stringify({ count, updatedAt: ts() }));
+    shared.mutateKbCheckpoint(() => ({ count, updatedAt: ts() }));
   } catch (err) { log('warn', `KB checkpoint: ${err.message}`); }
 }
 

package/engine/db/migrate.js

@@ -35,17 +35,24 @@ function runMigrations(db) {
     )
   `);
 
-  const currentRow = db.prepare('SELECT COALESCE(MAX(version), 0) AS v FROM schema_version').get();
-  const current = Number(currentRow.v) || 0;
   const migrations = _loadMigrations();
 
   for (const m of migrations) {
     if (typeof m.version !== 'number' || typeof m.up !== 'function') {
       throw new Error(`engine/db/migrate: migration missing { version, up }: ${JSON.stringify(Object.keys(m))}`);
     }
-    if (m.version <= current) continue;
-    db.exec('BEGIN');
+    // Concurrent-startup safety: take the SQLite write lock BEFORE re-reading
+    // schema_version. With plain `BEGIN` (deferred), two processes booting at
+    // the same time can both observe schema_version=N, both decide to apply
+    // N+1, and one then fails with "table already exists" while the other
+    // succeeds — leaving the loser stuck on `_dbInitError` for the lifetime
+    // of its process. `BEGIN IMMEDIATE` serializes the version check itself
+    // so the second arrival simply sees the updated schema_version and skips.
+    db.exec('BEGIN IMMEDIATE');
     try {
+      const currentRow = db.prepare('SELECT COALESCE(MAX(version), 0) AS v FROM schema_version').get();
+      const current = Number(currentRow.v) || 0;
+      if (m.version <= current) { db.exec('COMMIT'); continue; }
       // eslint-disable-next-line no-console
       console.log(`[db-migrate] Applying v${m.version}: ${m.description || '(no description)'}`);
       m.up(db, { fs, path });

package/engine/db/migrations/011-remaining-state.js

@@ -0,0 +1,116 @@
+// engine/db/migrations/011-remaining-state.js
+//
+// Phase 9.2: finish the JSON→SQL migration. Four remaining engine state
+// files move into their own tables; the JSON files are kept as dual-write
+// mirrors for back-compat.
+//
+//   engine/cooldowns.json        -> cooldowns
+//   engine/pending-rebases.json  -> pending_rebases
+//   engine/cc-sessions.json      -> cc_sessions
+//   engine/doc-sessions.json     -> doc_sessions
+
+const path = require('path');
+const fs = require('fs');
+
+function _resolveMinionsDir() {
+  const envHome = process.env.MINIONS_HOME || process.env.MINIONS_TEST_DIR;
+  if (envHome) return envHome;
+  try { return require('../../shared').MINIONS_DIR; } catch { return null; }
+}
+
+function _readJsonOr(filePath, fallback) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch { return fallback; }
+}
+
+module.exports = {
+  version: 11,
+  description: 'cooldowns + pending_rebases + cc_sessions + doc_sessions',
+  up(db) {
+    db.exec(`
+      CREATE TABLE cooldowns (
+        key         TEXT PRIMARY KEY,
+        data        TEXT NOT NULL,
+        updated_at  INTEGER NOT NULL
+      );
+
+      CREATE TABLE pending_rebases (
+        seq         INTEGER PRIMARY KEY AUTOINCREMENT,
+        data        TEXT NOT NULL,
+        updated_at  INTEGER NOT NULL
+      );
+
+      CREATE TABLE cc_sessions (
+        id          TEXT PRIMARY KEY,
+        data        TEXT NOT NULL,
+        updated_at  INTEGER NOT NULL
+      );
+
+      CREATE TABLE doc_sessions (
+        key         TEXT PRIMARY KEY,
+        data        TEXT NOT NULL,
+        updated_at  INTEGER NOT NULL
+      );
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    const now = Date.now();
+    let inserted = 0;
+
+    // ── cooldowns ──────────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'cooldowns.json'), null);
+      if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        const ins = db.prepare(`INSERT INTO cooldowns (key, data, updated_at) VALUES (?, ?, ?)`);
+        for (const [k, v] of Object.entries(raw)) {
+          try { ins.run(String(k), JSON.stringify(v), now); inserted += 1; }
+          catch { /* duplicate / corrupt — skip */ }
+        }
+      }
+    }
+
+    // ── pending_rebases ────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'pending-rebases.json'), null);
+      if (Array.isArray(raw)) {
+        const ins = db.prepare(`INSERT INTO pending_rebases (data, updated_at) VALUES (?, ?)`);
+        for (const entry of raw) {
+          if (!entry || typeof entry !== 'object') continue;
+          try { ins.run(JSON.stringify(entry), now); inserted += 1; }
+          catch { /* corrupt — skip */ }
+        }
+      }
+    }
+
+    // ── cc_sessions ────────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'cc-sessions.json'), null);
+      if (Array.isArray(raw)) {
+        const ins = db.prepare(`INSERT INTO cc_sessions (id, data, updated_at) VALUES (?, ?, ?)`);
+        for (const entry of raw) {
+          if (!entry || typeof entry !== 'object' || !entry.id) continue;
+          try { ins.run(String(entry.id), JSON.stringify(entry), now); inserted += 1; }
+          catch { /* duplicate id — skip */ }
+        }
+      }
+    }
+
+    // ── doc_sessions ───────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'doc-sessions.json'), null);
+      if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        const ins = db.prepare(`INSERT INTO doc_sessions (key, data, updated_at) VALUES (?, ?, ?)`);
+        for (const [k, v] of Object.entries(raw)) {
+          try { ins.run(String(k), JSON.stringify(v), now); inserted += 1; }
+          catch { /* duplicate / corrupt — skip */ }
+        }
+      }
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(`[db-migrate] v11: backfilled ${inserted} small-state rows; JSON files kept as dual-write mirrors`);
+  },
+};

package/engine/kb-sweep.js

@@ -288,8 +288,10 @@ function _writeSweepState(state) {
   // can distinguish "still running" from "runner crashed". When this module is
   // imported by the detached runner, process.pid is the runner's pid — which
   // is exactly what we want.
+  // Phase 9.3: route through shared.mutateKbSweepState (file-locked RMW) so
+  // the dashboard process + the detached runner can't race each other.
   const augmented = { pid: process.pid, ...state };
-  try { safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify(augmented)); } catch { /* ignore */ }
+  try { shared.mutateKbSweepState(() => augmented); } catch { /* ignore */ }
 }
 
 /**
@@ -416,10 +418,10 @@ function reconcileSweepStateOnBoot(opts = {}) {
     error: `sweep abandoned: ${reason}`,
     reconciliationReason: reason,
   };
-  // Direct safeWrite (NOT _writeSweepState) so the original pid is preserved
-  // for forensics — _writeSweepState would overwrite it with this process's
-  // pid, destroying the diagnostic value of the record.
-  try { safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify(failedState)); } catch { /* ignore */ }
+  // Direct mutateKbSweepState (NOT _writeSweepState) so the original pid is
+  // preserved for forensics — _writeSweepState would overwrite it with this
+  // process's pid, destroying the diagnostic value of the record.
+  try { shared.mutateKbSweepState(() => failedState); } catch { /* ignore */ }
   return {
     scanned: 1, released: 1, reason,
     prevStatus: state.status, prevPid: pid,
@@ -551,7 +553,7 @@ async function _runKbSweepImpl(opts = {}) {
   summary.summary = `${summary.hashDuplicatesArchived} hash-dup, ${summary.llmDuplicatesArchived} llm-dup, ${summary.staleRemoved} stale, ${summary.reclassified} reclassified, ${summary.rewritten} rewritten (${(summary.bytesBefore - summary.bytesAfter).toLocaleString()} bytes saved)`;
 
   if (!opts.dryRun) {
-    try { safeWrite(path.join(ENGINE_DIR, 'kb-swept.json'), JSON.stringify({ timestamp: ts(), summary: summary.summary, detail: summary })); } catch { /* ignore */ }
+    try { shared.mutateKbSwept(() => ({ timestamp: ts(), summary: summary.summary, detail: summary })); } catch { /* ignore */ }
     try { queries.invalidateKnowledgeBaseCache(); } catch { /* ignore */ }
   }
   return summary;
@@ -587,7 +589,7 @@ function spawnSweepRunnerDetached(opts = {}) {
   const sweepToken = `${startedAt}-${Math.random().toString(36).slice(2, 8)}`;
 
   try {
-    safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify({
+    shared.mutateKbSweepState(() => ({
       status: 'starting', startedAt, startedAtIso: new Date().toISOString(),
       sweepToken, pid: null,
     }));
@@ -637,14 +639,18 @@ function spawnSweepRunnerDetached(opts = {}) {
   }
   if (logFdNum != null) try { fsLocal.closeSync(logFdNum); } catch { /* ignore */ }
 
+  // Phase 9.3: atomic starting→in-flight transition under the file lock
+  // (was previously a safeJson→safeWrite race).
   try {
-    const current = safeJson(KB_SWEEP_STATE_PATH);
-    if (current && current.status === 'starting' && current.sweepToken === sweepToken) {
-      safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify({
-        status: 'in-flight', startedAt, startedAtIso: new Date().toISOString(),
-        sweepToken, pid: proc.pid,
-      }));
-    }
+    shared.mutateKbSweepState((current) => {
+      if (current && current.status === 'starting' && current.sweepToken === sweepToken) {
+        return {
+          status: 'in-flight', startedAt, startedAtIso: new Date().toISOString(),
+          sweepToken, pid: proc.pid,
+        };
+      }
+      return undefined; // unchanged → skipWriteIfUnchanged suppresses the write
+    });
   } catch { /* best-effort */ }
 
   proc.unref();

package/engine/shared.js

@@ -65,6 +65,16 @@ const COOLDOWNS_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 // process-lifetime (state/pid/ownerToken). See ENGINE_DEFAULTS.abandonedReconciliationVersion
 // for the first consumer.
 const ENGINE_STATE_PATH = path.join(ENGINE_DIR, 'state.json');
+// Phase 9.3: wrap raw safeWrite callers for kb-checkpoint, kb-swept,
+// kb-sweep-state, and test-results so they go through mutateJsonFileLocked
+// (the same path mutateControl / mutateEngineState / mutateCooldowns use).
+// This sets them up for SQL routing via _SMALL_STATE_MUTATE_ROUTES later, and
+// in the case of kb-sweep-state.json closes a real cross-process race (the
+// dashboard process and the detached kb-sweep-runner child both write it).
+const KB_CHECKPOINT_PATH = path.join(ENGINE_DIR, 'kb-checkpoint.json');
+const KB_SWEPT_PATH = path.join(ENGINE_DIR, 'kb-swept.json');
+const KB_SWEEP_STATE_PATH = path.join(ENGINE_DIR, 'kb-sweep-state.json');
+const TEST_RESULTS_PATH = path.join(ENGINE_DIR, 'test-results.json');
 const PR_LINKS_PATH = path.join(MINIONS_DIR, 'engine', 'pr-links.json');
 const PINNED_ITEMS_PATH = path.join(MINIONS_DIR, 'engine', 'kb-pins.json');
 const LOG_PATH = path.join(MINIONS_DIR, 'engine', 'log.json');
@@ -536,6 +546,22 @@ function _routeJsonReadToSql(p) {
       const store = require('./small-state-store');
       return { value: store.readPrLinks() };
     }
+    if (norm.endsWith('/engine/cooldowns.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readCooldowns() };
+    }
+    if (norm.endsWith('/engine/pending-rebases.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readPendingRebases() };
+    }
+    if (norm.endsWith('/engine/cc-sessions.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readCcSessions() };
+    }
+    if (norm.endsWith('/engine/doc-sessions.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readDocSessions() };
+    }
     // Per-project work-items.json — match `/projects/<name>/work-items.json`.
     // When SQL has no rows for the scope AND the JSON file is absent on
     // disk, preserve the legacy "file missing → null" semantic. This guards
@@ -1323,13 +1349,60 @@ function withFileLock(lockPath, fn, {
   throw lastErr;
 }
 
+// Route table for small-state files migrated to SQL stores. Each entry
+// declares the SQL store function to invoke and the expected default JSON
+// shape (for the "ensure file exists" fallback below).
+const _SMALL_STATE_MUTATE_ROUTES = {
+  'cooldowns.json':       { fn: 'applyCooldownsMutation',       mirror: '_mirrorCooldownsJson',       defaultShape: 'object' },
+  'pending-rebases.json': { fn: 'applyPendingRebasesMutation',  mirror: '_mirrorPendingRebasesJson',  defaultShape: 'array'  },
+  'cc-sessions.json':     { fn: 'applyCcSessionsMutation',      mirror: '_mirrorCcSessionsJson',      defaultShape: 'array'  },
+  'doc-sessions.json':    { fn: 'applyDocSessionsMutation',     mirror: '_mirrorDocSessionsJson',     defaultShape: 'object' },
+  'pr-links.json':        { fn: 'applyPrLinksMutation',         mirror: '_mirrorPrLinksJson',         defaultShape: 'object' },
+};
+
 function _tryRouteMutateToSql(filePath, mutateFn, onWrote) {
   const baseName = path.basename(filePath);
-  if (baseName !== 'work-items.json' && baseName !== 'pull-requests.json') return null;
+  const smallRoute = _SMALL_STATE_MUTATE_ROUTES[baseName];
+  if (baseName !== 'work-items.json' && baseName !== 'pull-requests.json' && !smallRoute) return null;
   const fpNorm = String(filePath).replace(/\\/g, '/');
   const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
   const insideMinionsDir = fpNorm.startsWith(minionsNorm + '/') || fpNorm === minionsNorm + '/' + baseName;
   if (!insideMinionsDir) return null;
+
+  // Small-state files live exclusively under <MINIONS_DIR>/engine/<baseName>.
+  // 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 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;
+      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;
+      }
+      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 };
+  }
+
   let result;
   if (baseName === 'work-items.json') {
     result = mutateWorkItems(filePath, (arr) => {
@@ -1451,6 +1524,45 @@ function mutateCooldowns(mutator) {
   }, { defaultValue: {}, skipWriteIfUnchanged: true });
 }
 
+// Phase 9.3 (W-mp48wxqw / SQL-canonicalization prep): lock-safe RMW wrappers
+// for the small JSON state files that were still going through raw safeWrite.
+// Pattern mirrors mutateControl / mutateEngineState / mutateCooldowns — so a
+// future SQL migration is a mechanical _SMALL_STATE_MUTATE_ROUTES addition.
+
+// KB classification checkpoint counter (consolidation.js post-classify).
+function mutateKbCheckpoint(mutator) {
+  return mutateJsonFileLocked(KB_CHECKPOINT_PATH, (data) => {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+    return mutator(data) || data;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+}
+
+// KB last-sweep summary (kb-sweep.js post-sweep, dashboard reader).
+function mutateKbSwept(mutator) {
+  return mutateJsonFileLocked(KB_SWEPT_PATH, (data) => {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+    return mutator(data) || data;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+}
+
+// KB sweep state machine. Written by BOTH the dashboard process AND the
+// detached kb-sweep-runner child — wrapping under mutateJsonFileLocked makes
+// cross-process writes file-locked (previously a real race via raw safeWrite).
+function mutateKbSweepState(mutator) {
+  return mutateJsonFileLocked(KB_SWEEP_STATE_PATH, (data) => {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+    return mutator(data) || data;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+}
+
+// Test results history (capped at TEST_RESULTS_CAP by cleanup.js).
+function mutateTestResults(mutator) {
+  return mutateJsonFileLocked(TEST_RESULTS_PATH, (data) => {
+    if (!Array.isArray(data)) data = [];
+    return mutator(data) || data;
+  }, { defaultValue: [], skipWriteIfUnchanged: true });
+}
+
 let _uidCounter = 0;
 
 /**
@@ -5975,6 +6087,10 @@ module.exports = {
   mutateEngineState, // W-mp60tw0u000j3931
   readEngineState,   // W-mp60tw0u000j3931
   mutateCooldowns,
+  mutateKbCheckpoint,   // Phase 9.3
+  mutateKbSwept,        // Phase 9.3
+  mutateKbSweepState,   // Phase 9.3
+  mutateTestResults,    // Phase 9.3
   mutateWorkItems,
   reopenWorkItem,
   mutatePullRequests,

package/engine/small-state-store.js

@@ -941,6 +941,438 @@ function _mirrorPrLinksJson(filePath) {
   } catch { /* mirror best-effort */ }
 }
 
+// ─── cooldowns ─────────────────────────────────────────────────────────────
+// Shape: { [key]: { timestamp, failures, ... } }
+// SQL:   row per key.
+
+let _cooldownsHash = null;
+
+function _hydrateCooldowns(db) {
+  const fp = _resolveFilePath('cooldowns.json');
+  const raw = _readJson(fp) || {};
+  db.prepare('DELETE FROM cooldowns').run();
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return;
+  const now = Date.now();
+  const ins = db.prepare('INSERT INTO cooldowns (key, data, updated_at) VALUES (?, ?, ?) ON CONFLICT(key) DO NOTHING');
+  for (const [key, value] of Object.entries(raw)) {
+    ins.run(String(key), JSON.stringify(value), now);
+  }
+}
+
+function _resyncCooldownsIfDiverged(db) {
+  const fp = _resolveFilePath('cooldowns.json');
+  const currentHash = _fileContentHash(fp);
+  if (currentHash == null) return;
+  if (_cooldownsHash != null && currentHash === _cooldownsHash) return;
+  if (_cooldownsHash == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM cooldowns LIMIT 1').get();
+    if (sqlHas) { _cooldownsHash = currentHash; return; }
+  }
+  _hydrateCooldowns(db);
+  _cooldownsHash = currentHash;
+}
+
+function _readCooldownsFromSql(db) {
+  const rows = db.prepare('SELECT key, data FROM cooldowns').all();
+  const out = {};
+  for (const row of rows) {
+    try { out[row.key] = JSON.parse(row.data); }
+    catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+function readCooldowns() {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return _readJson(_resolveFilePath('cooldowns.json')) || {}; }
+  try { _resyncCooldownsIfDiverged(db); }
+  catch { /* table may be missing on stale install */ }
+  let out;
+  try { out = _readCooldownsFromSql(db); }
+  catch { return _readJson(_resolveFilePath('cooldowns.json')) || {}; }
+  if (Object.keys(out).length === 0) {
+    const fallback = _readJson(_resolveFilePath('cooldowns.json'));
+    if (fallback && Object.keys(fallback).length > 0) return fallback;
+    return {};
+  }
+  return out;
+}
+
+function applyCooldownsMutation(mutator) {
+  const { getDb, withTransaction } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`small-state-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    _resyncCooldownsIfDiverged(db);
+    const before = _readCooldownsFromSql(db);
+    const beforeSnap = JSON.parse(JSON.stringify(before));
+    const next = mutator(before);
+    const after = (next === undefined || next === null) ? before : next;
+    if (!after || typeof after !== 'object' || Array.isArray(after)) {
+      return { wrote: false, result: beforeSnap };
+    }
+    const afterIds = new Set(Object.keys(after));
+    const beforeIds = new Set(Object.keys(beforeSnap));
+    let wrote = false;
+    const now = Date.now();
+    const upsert = db.prepare(`
+      INSERT INTO cooldowns (key, data, updated_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(key) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at
+    `);
+    const del = db.prepare('DELETE FROM cooldowns WHERE key = ?');
+    for (const id of afterIds) {
+      if (!beforeIds.has(id) || JSON.stringify(beforeSnap[id]) !== JSON.stringify(after[id])) {
+        upsert.run(id, JSON.stringify(after[id]), now);
+        wrote = true;
+      }
+    }
+    for (const id of beforeIds) {
+      if (!afterIds.has(id)) { del.run(id); wrote = true; }
+    }
+    return { wrote, result: after };
+  });
+}
+
+function _mirrorCooldownsJson(filePath) {
+  try {
+    const shared = require('./shared');
+    const { getDb } = require('./db');
+    const obj = _readCooldownsFromSql(getDb());
+    const target = filePath || _resolveFilePath('cooldowns.json');
+    shared.safeWrite(target, obj);
+    const h = _fileContentHash(target);
+    if (h != null) _cooldownsHash = h;
+  } catch { /* mirror best-effort */ }
+}
+
+// ─── pending_rebases ───────────────────────────────────────────────────────
+// Shape: [ { prId, branch, projectName, mergedItemId, queuedAt, attempts, ... }, ... ]
+// SQL:   row per array entry (rowid auto-increment preserves insertion order).
+//        No stable natural key, so mutations are full clear+insert.
+
+let _pendingRebasesHash = null;
+
+function _hydratePendingRebases(db) {
+  const fp = _resolveFilePath('pending-rebases.json');
+  const raw = _readJson(fp) || [];
+  db.prepare('DELETE FROM pending_rebases').run();
+  if (!Array.isArray(raw)) return;
+  const now = Date.now();
+  const ins = db.prepare('INSERT INTO pending_rebases (data, updated_at) VALUES (?, ?)');
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue;
+    ins.run(JSON.stringify(entry), now);
+  }
+}
+
+function _resyncPendingRebasesIfDiverged(db) {
+  const fp = _resolveFilePath('pending-rebases.json');
+  const currentHash = _fileContentHash(fp);
+  if (currentHash == null) return;
+  if (_pendingRebasesHash != null && currentHash === _pendingRebasesHash) return;
+  if (_pendingRebasesHash == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM pending_rebases LIMIT 1').get();
+    if (sqlHas) { _pendingRebasesHash = currentHash; return; }
+  }
+  _hydratePendingRebases(db);
+  _pendingRebasesHash = currentHash;
+}
+
+function _readPendingRebasesFromSql(db) {
+  const rows = db.prepare('SELECT data FROM pending_rebases ORDER BY seq').all();
+  const out = [];
+  for (const row of rows) {
+    try { out.push(JSON.parse(row.data)); }
+    catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+function readPendingRebases() {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return _readJson(_resolveFilePath('pending-rebases.json')) || []; }
+  try { _resyncPendingRebasesIfDiverged(db); }
+  catch { /* table missing */ }
+  let out;
+  try { out = _readPendingRebasesFromSql(db); }
+  catch { return _readJson(_resolveFilePath('pending-rebases.json')) || []; }
+  if (out.length === 0) {
+    const fallback = _readJson(_resolveFilePath('pending-rebases.json'));
+    if (Array.isArray(fallback) && fallback.length > 0) return fallback;
+    return [];
+  }
+  return out;
+}
+
+function applyPendingRebasesMutation(mutator) {
+  const { getDb, withTransaction } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`small-state-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    _resyncPendingRebasesIfDiverged(db);
+    const before = _readPendingRebasesFromSql(db);
+    const beforeSnap = JSON.parse(JSON.stringify(before));
+    const next = mutator(before);
+    const after = (next === undefined || next === null) ? before : next;
+    if (!Array.isArray(after)) {
+      return { wrote: false, result: beforeSnap };
+    }
+    let wrote = false;
+    if (JSON.stringify(before) !== JSON.stringify(after)) {
+      const now = Date.now();
+      db.prepare('DELETE FROM pending_rebases').run();
+      const ins = db.prepare('INSERT INTO pending_rebases (data, updated_at) VALUES (?, ?)');
+      for (const entry of after) {
+        if (!entry || typeof entry !== 'object') continue;
+        ins.run(JSON.stringify(entry), now);
+      }
+      wrote = true;
+    }
+    return { wrote, result: after };
+  });
+}
+
+function _mirrorPendingRebasesJson(filePath) {
+  try {
+    const shared = require('./shared');
+    const { getDb } = require('./db');
+    const arr = _readPendingRebasesFromSql(getDb());
+    const target = filePath || _resolveFilePath('pending-rebases.json');
+    shared.safeWrite(target, arr);
+    const h = _fileContentHash(target);
+    if (h != null) _pendingRebasesHash = h;
+  } catch { /* mirror best-effort */ }
+}
+
+// ─── cc_sessions ───────────────────────────────────────────────────────────
+// Shape: [ { id, sessionId, title, _promptHash, lastActiveAt, ... }, ... ]
+// SQL:   row per id (each entry has a unique `id` tab key).
+
+let _ccSessionsHash = null;
+
+function _hydrateCcSessions(db) {
+  const fp = _resolveFilePath('cc-sessions.json');
+  const raw = _readJson(fp) || [];
+  db.prepare('DELETE FROM cc_sessions').run();
+  if (!Array.isArray(raw)) return;
+  const now = Date.now();
+  const ins = db.prepare('INSERT INTO cc_sessions (id, data, updated_at) VALUES (?, ?, ?) ON CONFLICT(id) DO NOTHING');
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object' || !entry.id) continue;
+    ins.run(String(entry.id), JSON.stringify(entry), now);
+  }
+}
+
+function _resyncCcSessionsIfDiverged(db) {
+  const fp = _resolveFilePath('cc-sessions.json');
+  const currentHash = _fileContentHash(fp);
+  if (currentHash == null) return;
+  if (_ccSessionsHash != null && currentHash === _ccSessionsHash) return;
+  if (_ccSessionsHash == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM cc_sessions LIMIT 1').get();
+    if (sqlHas) { _ccSessionsHash = currentHash; return; }
+  }
+  _hydrateCcSessions(db);
+  _ccSessionsHash = currentHash;
+}
+
+function _readCcSessionsFromSql(db) {
+  const rows = db.prepare('SELECT data FROM cc_sessions ORDER BY updated_at, id').all();
+  const out = [];
+  for (const row of rows) {
+    try { out.push(JSON.parse(row.data)); }
+    catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+function readCcSessions() {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return _readJson(_resolveFilePath('cc-sessions.json')) || []; }
+  try { _resyncCcSessionsIfDiverged(db); }
+  catch { /* table missing */ }
+  let out;
+  try { out = _readCcSessionsFromSql(db); }
+  catch { return _readJson(_resolveFilePath('cc-sessions.json')) || []; }
+  if (out.length === 0) {
+    const fallback = _readJson(_resolveFilePath('cc-sessions.json'));
+    if (Array.isArray(fallback) && fallback.length > 0) return fallback;
+    return [];
+  }
+  return out;
+}
+
+function applyCcSessionsMutation(mutator) {
+  const { getDb, withTransaction } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`small-state-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    _resyncCcSessionsIfDiverged(db);
+    const before = _readCcSessionsFromSql(db);
+    const beforeSnap = JSON.parse(JSON.stringify(before));
+    const next = mutator(before);
+    const after = (next === undefined || next === null) ? before : next;
+    if (!Array.isArray(after)) {
+      return { wrote: false, result: beforeSnap };
+    }
+    const beforeById = new Map(beforeSnap.filter(e => e && e.id).map(e => [String(e.id), e]));
+    const afterById = new Map(after.filter(e => e && e.id).map(e => [String(e.id), e]));
+    let wrote = false;
+    const now = Date.now();
+    const upsert = db.prepare(`
+      INSERT INTO cc_sessions (id, data, updated_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at
+    `);
+    const del = db.prepare('DELETE FROM cc_sessions WHERE id = ?');
+    for (const [id, entry] of afterById) {
+      const prior = beforeById.get(id);
+      if (!prior || JSON.stringify(prior) !== JSON.stringify(entry)) {
+        upsert.run(id, JSON.stringify(entry), now);
+        wrote = true;
+      }
+    }
+    for (const id of beforeById.keys()) {
+      if (!afterById.has(id)) { del.run(id); wrote = true; }
+    }
+    return { wrote, result: after };
+  });
+}
+
+function _mirrorCcSessionsJson(filePath) {
+  try {
+    const shared = require('./shared');
+    const { getDb } = require('./db');
+    const arr = _readCcSessionsFromSql(getDb());
+    const target = filePath || _resolveFilePath('cc-sessions.json');
+    shared.safeWrite(target, arr);
+    const h = _fileContentHash(target);
+    if (h != null) _ccSessionsHash = h;
+  } catch { /* mirror best-effort */ }
+}
+
+// ─── doc_sessions ──────────────────────────────────────────────────────────
+// Shape: { [filePath]: { sessionId, lastActiveAt, turnCount, ... } }
+// SQL:   row per filePath key.
+
+let _docSessionsHash = null;
+
+function _hydrateDocSessions(db) {
+  const fp = _resolveFilePath('doc-sessions.json');
+  const raw = _readJson(fp) || {};
+  db.prepare('DELETE FROM doc_sessions').run();
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return;
+  const now = Date.now();
+  const ins = db.prepare('INSERT INTO doc_sessions (key, data, updated_at) VALUES (?, ?, ?) ON CONFLICT(key) DO NOTHING');
+  for (const [key, value] of Object.entries(raw)) {
+    ins.run(String(key), JSON.stringify(value), now);
+  }
+}
+
+function _resyncDocSessionsIfDiverged(db) {
+  const fp = _resolveFilePath('doc-sessions.json');
+  const currentHash = _fileContentHash(fp);
+  if (currentHash == null) return;
+  if (_docSessionsHash != null && currentHash === _docSessionsHash) return;
+  if (_docSessionsHash == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM doc_sessions LIMIT 1').get();
+    if (sqlHas) { _docSessionsHash = currentHash; return; }
+  }
+  _hydrateDocSessions(db);
+  _docSessionsHash = currentHash;
+}
+
+function _readDocSessionsFromSql(db) {
+  const rows = db.prepare('SELECT key, data FROM doc_sessions').all();
+  const out = {};
+  for (const row of rows) {
+    try { out[row.key] = JSON.parse(row.data); }
+    catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+function readDocSessions() {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return _readJson(_resolveFilePath('doc-sessions.json')) || {}; }
+  try { _resyncDocSessionsIfDiverged(db); }
+  catch { /* table missing */ }
+  let out;
+  try { out = _readDocSessionsFromSql(db); }
+  catch { return _readJson(_resolveFilePath('doc-sessions.json')) || {}; }
+  if (Object.keys(out).length === 0) {
+    const fallback = _readJson(_resolveFilePath('doc-sessions.json'));
+    if (fallback && Object.keys(fallback).length > 0) return fallback;
+    return {};
+  }
+  return out;
+}
+
+function applyDocSessionsMutation(mutator) {
+  const { getDb, withTransaction } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`small-state-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    _resyncDocSessionsIfDiverged(db);
+    const before = _readDocSessionsFromSql(db);
+    const beforeSnap = JSON.parse(JSON.stringify(before));
+    const next = mutator(before);
+    const after = (next === undefined || next === null) ? before : next;
+    if (!after || typeof after !== 'object' || Array.isArray(after)) {
+      return { wrote: false, result: beforeSnap };
+    }
+    const afterIds = new Set(Object.keys(after));
+    const beforeIds = new Set(Object.keys(beforeSnap));
+    let wrote = false;
+    const now = Date.now();
+    const upsert = db.prepare(`
+      INSERT INTO doc_sessions (key, data, updated_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(key) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at
+    `);
+    const del = db.prepare('DELETE FROM doc_sessions WHERE key = ?');
+    for (const id of afterIds) {
+      if (!beforeIds.has(id) || JSON.stringify(beforeSnap[id]) !== JSON.stringify(after[id])) {
+        upsert.run(id, JSON.stringify(after[id]), now);
+        wrote = true;
+      }
+    }
+    for (const id of beforeIds) {
+      if (!afterIds.has(id)) { del.run(id); wrote = true; }
+    }
+    return { wrote, result: after };
+  });
+}
+
+function _mirrorDocSessionsJson(filePath) {
+  try {
+    const shared = require('./shared');
+    const { getDb } = require('./db');
+    const obj = _readDocSessionsFromSql(getDb());
+    const target = filePath || _resolveFilePath('doc-sessions.json');
+    shared.safeWrite(target, obj);
+    const h = _fileContentHash(target);
+    if (h != null) _docSessionsHash = h;
+  } catch { /* mirror best-effort */ }
+}
+
 // ─── Test seam ─────────────────────────────────────────────────────────────
 
 function _resetAllForTest() {
@@ -954,6 +1386,10 @@ function _resetAllForTest() {
     try { db.exec('DELETE FROM qa_runs'); } catch { /* migration not applied */ }
     try { db.exec('DELETE FROM qa_sessions'); } catch { /* migration not applied */ }
     try { db.exec('DELETE FROM pr_links'); } catch { /* migration not applied */ }
+    try { db.exec('DELETE FROM cooldowns'); } catch { /* migration not applied */ }
+    try { db.exec('DELETE FROM pending_rebases'); } catch { /* migration not applied */ }
+    try { db.exec('DELETE FROM cc_sessions'); } catch { /* migration not applied */ }
+    try { db.exec('DELETE FROM doc_sessions'); } catch { /* migration not applied */ }
   } catch { /* not initialized */ }
   _scheduleRunsHash = null;
   _pipelineRunsHash = null;
@@ -962,6 +1398,10 @@ function _resetAllForTest() {
   _qaRunsHash = null;
   _qaSessionsHash = null;
   _prLinksHash = null;
+  _cooldownsHash = null;
+  _pendingRebasesHash = null;
+  _ccSessionsHash = null;
+  _docSessionsHash = null;
 }
 
 module.exports = {
@@ -993,6 +1433,22 @@ module.exports = {
   readPrLinks,
   applyPrLinksMutation,
   _mirrorPrLinksJson,
+  // cooldowns
+  readCooldowns,
+  applyCooldownsMutation,
+  _mirrorCooldownsJson,
+  // pending_rebases
+  readPendingRebases,
+  applyPendingRebasesMutation,
+  _mirrorPendingRebasesJson,
+  // cc_sessions
+  readCcSessions,
+  applyCcSessionsMutation,
+  _mirrorCcSessionsJson,
+  // doc_sessions
+  readDocSessions,
+  applyDocSessionsMutation,
+  _mirrorDocSessionsJson,
   // test seam
   _resetAllForTest,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2115",
+  "version": "0.1.2116",
   "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"