@yemi33/minions 0.1.2068 → 0.1.2070

package/engine/db/migrations/004-pull-requests.js

@@ -0,0 +1,129 @@
+// engine/db/migrations/004-pull-requests.js
+//
+// Phase 3: move pull-requests.json (central + per-project) into a
+// `pull_requests` table.
+//
+// Same hybrid schema as `work_items`: typed projection columns for hot
+// filters (scope/status/agent/branch/timestamps), plus a `data` TEXT
+// column holding the full record JSON so future fields land transparently.
+//
+// `scope` keys the file the record came from: 'central' for
+// <MINIONS_DIR>/pull-requests.json, otherwise the project name (matches
+// the directory under projects/<name>/). Per-scope writes diff against
+// that scope's rows so a mutation on one project's file never touches
+// another's.
+//
+// Backfill: walk central + every projects/<name>/pull-requests.json. The
+// JSON files stay on disk as a dual-write mirror so legacy direct-readers
+// continue to function while we migrate them in Phase 3.5.
+
+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 _toMs(v) {
+  if (v == null) return null;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  const parsed = Date.parse(v);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function _readJsonArray(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function _listProjectDirs(minionsDir) {
+  const projectsRoot = path.join(minionsDir, 'projects');
+  let entries;
+  try { entries = fs.readdirSync(projectsRoot, { withFileTypes: true }); }
+  catch { return []; }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (e.name.startsWith('.')) continue;  // .archived + any other hidden sidecars
+    out.push(e.name);
+  }
+  return out;
+}
+
+module.exports = {
+  version: 4,
+  description: 'pull_requests: schema + pull-requests.json backfill (central + per-project)',
+  up(db) {
+    db.exec(`
+      CREATE TABLE pull_requests (
+        id              TEXT NOT NULL,
+        scope           TEXT NOT NULL,
+        status          TEXT NOT NULL,
+        review_status   TEXT,
+        agent           TEXT,
+        branch          TEXT,
+        pr_number       INTEGER,
+        created_at      INTEGER,
+        last_polled_at  INTEGER,
+        data            TEXT NOT NULL,
+        updated_at      INTEGER NOT NULL,
+        PRIMARY KEY (scope, id)
+      );
+      CREATE INDEX idx_pr_status            ON pull_requests(status);
+      CREATE INDEX idx_pr_scope_status      ON pull_requests(scope, status);
+      CREATE INDEX idx_pr_agent             ON pull_requests(agent);
+      CREATE INDEX idx_pr_branch            ON pull_requests(branch);
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+
+    const insert = db.prepare(`
+      INSERT INTO pull_requests (id, scope, status, review_status, agent, branch, pr_number, created_at, last_polled_at, data, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const now = Date.now();
+    let inserted = 0;
+
+    const backfillFile = (scope, filePath) => {
+      const rows = _readJsonArray(filePath);
+      for (const pr of rows) {
+        if (!pr || typeof pr !== 'object' || !pr.id) continue;
+        try {
+          insert.run(
+            String(pr.id),
+            scope,
+            String(pr.status || 'active'),
+            pr.reviewStatus || null,
+            pr.agent || null,
+            pr.branch || null,
+            Number.isFinite(pr.prNumber) ? pr.prNumber : null,
+            _toMs(pr.created),
+            _toMs(pr.lastPolledAt || pr.lastPolled),
+            JSON.stringify(pr),
+            now,
+          );
+          inserted += 1;
+        } catch {
+          // Duplicate (scope, id) — skip. Defensive against malformed files.
+        }
+      }
+    };
+
+    backfillFile('central', path.join(minionsDir, 'pull-requests.json'));
+    for (const projectName of _listProjectDirs(minionsDir)) {
+      backfillFile(projectName, path.join(minionsDir, 'projects', projectName, 'pull-requests.json'));
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(`[db-migrate] v4: backfilled ${inserted} pull requests; pull-requests.json files kept as dual-write mirrors`);
+  },
+};

package/engine/db/migrations/005-logs.js

@@ -0,0 +1,39 @@
+// engine/db/migrations/005-logs.js
+//
+// Phase 4: replace engine/log.json with a `logs` table.
+//
+// Logs are append-only with a 2500-entry ring buffer (the legacy JSON
+// path trimmed to 2000 when length hit 2500). The table preserves that
+// behaviour:
+//   - Each log() emits one row via INSERT.
+//   - After insert, a tail-trim DELETEs everything older than the most
+//     recent N (default 2500, configurable via ENGINE_DEFAULTS.logCapEntries).
+//
+// Schema is intentionally narrow: an auto-incrementing id (preserves
+// insertion order for the ring-buffer trim), the timestamp in ms (so the
+// dashboard can do range queries without a TEXT parse), a level/message
+// pair the dashboard already keys on, and a `meta` JSON blob for any
+// extra fields the caller passed.
+//
+// No backfill — engine/log.json is ephemeral and the next tick will
+// start populating SQL fresh. The legacy file stays on disk as a
+// dual-write mirror (test fixtures + getEngineLog fallback) until
+// Phase 4.5 migrates the readers.
+
+module.exports = {
+  version: 5,
+  description: 'logs: append-only table for engine log entries',
+  up(db) {
+    db.exec(`
+      CREATE TABLE logs (
+        id        INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts_ms     INTEGER NOT NULL,
+        level     TEXT NOT NULL,
+        message   TEXT NOT NULL,
+        meta      TEXT
+      );
+      CREATE INDEX idx_logs_ts        ON logs(ts_ms DESC);
+      CREATE INDEX idx_logs_level_ts  ON logs(level, ts_ms DESC);
+    `);
+  },
+};

package/engine/db/migrations/006-metrics.js

@@ -0,0 +1,106 @@
+// engine/db/migrations/006-metrics.js
+//
+// Phase 5: move engine/metrics.json into a `metrics` table.
+//
+// metrics.json's shape is heterogeneous: a flat object whose top-level
+// keys mix per-agent counters (regular agent ids) with reserved keys
+// (`_engine`, `_daily`, `_contextPressure`). The SQL projection uses a
+// single table with a (kind, key) primary key so each top-level entry
+// becomes one row:
+//
+//   kind                | key                | data (JSON blob)
+//   --------------------+--------------------+-----------------------------
+//   agent               | dallas             | { tasksCompleted, ... }
+//   agent               | ripley             | { ...                 }
+//   engine_category     | command-center     | { calls, costUsd, ... }
+//   engine_category     | doc-chat           | { ...                 }
+//   daily               | 2026-05-28         | { costUsd, tasks, ... }
+//   context_pressure    | current            | { ...                 }
+//
+// Engineless extensions land transparently in `data` — no schema bump
+// required to add a new counter field per category. New top-level kinds
+// (e.g. `pipeline`) only need a new sentinel in the reserved-key list
+// inside the store; the table schema is forward-compatible.
+//
+// Backfill: read metrics.json once, split by reserved-key sentinel,
+// INSERT one row per entry. The JSON file stays on disk as a dual-write
+// mirror so legacy direct-readers (none in engine, a few in tests) keep
+// working.
+
+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; }
+}
+
+const RESERVED_KEYS = new Map([
+  ['_engine', 'engine_category'],
+  ['_daily', 'daily'],
+  ['_contextPressure', 'context_pressure'],
+]);
+
+module.exports = {
+  version: 6,
+  description: 'metrics: schema + metrics.json backfill',
+  up(db) {
+    db.exec(`
+      CREATE TABLE metrics (
+        kind        TEXT NOT NULL,
+        key         TEXT NOT NULL,
+        data        TEXT NOT NULL,
+        updated_at  INTEGER NOT NULL,
+        PRIMARY KEY (kind, key)
+      );
+      CREATE INDEX idx_metrics_kind ON metrics(kind);
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    const metricsPath = path.join(minionsDir, 'engine', 'metrics.json');
+    if (!fs.existsSync(metricsPath)) return;
+
+    let raw;
+    try { raw = JSON.parse(fs.readFileSync(metricsPath, 'utf8')); }
+    catch (e) {
+      throw new Error(`engine/db/006-metrics: cannot parse metrics.json: ${e.message}`);
+    }
+    if (!raw || typeof raw !== 'object') return;
+
+    const insert = db.prepare(`
+      INSERT INTO metrics (kind, key, data, updated_at)
+      VALUES (?, ?, ?, ?)
+    `);
+
+    const now = Date.now();
+    let inserted = 0;
+
+    for (const [topKey, topValue] of Object.entries(raw)) {
+      const reservedKind = RESERVED_KEYS.get(topKey);
+      if (reservedKind) {
+        if (reservedKind === 'context_pressure') {
+          // Single-blob reserved key — store as one row keyed 'current'.
+          insert.run('context_pressure', 'current', JSON.stringify(topValue), now);
+          inserted += 1;
+          continue;
+        }
+        // Nested reserved key (_engine / _daily) — one row per inner key.
+        if (topValue && typeof topValue === 'object') {
+          for (const [innerKey, innerValue] of Object.entries(topValue)) {
+            insert.run(reservedKind, innerKey, JSON.stringify(innerValue), now);
+            inserted += 1;
+          }
+        }
+        continue;
+      }
+      // Regular agent counter row.
+      insert.run('agent', topKey, JSON.stringify(topValue), now);
+      inserted += 1;
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(`[db-migrate] v6: backfilled ${inserted} metrics rows; metrics.json kept as dual-write mirror`);
+  },
+};

package/engine/lifecycle.js

@@ -1788,12 +1788,12 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
   // Track reviewer for metrics purposes (separate file, separate lock)
   const authorAgentId = (reviewPr.agent || '').toLowerCase();
   if (authorAgentId && config.agents?.[authorAgentId]) {
-    shared.mutateJsonFileLocked(path.join(ENGINE_DIR, 'metrics.json'), (metrics) => {
+    shared.mutateMetrics((metrics) => {
       if (!metrics[authorAgentId]) metrics[authorAgentId] = { ...DEFAULT_AGENT_METRICS };
       if (!metrics[agentId]) metrics[agentId] = { ...DEFAULT_AGENT_METRICS };
       metrics[agentId].reviewsDone = (metrics[agentId].reviewsDone || 0) + 1;
       return metrics;
-    }, { defaultValue: {} });
+    });
   }
 
   log('info', `Updated ${reviewPr.id} → minions review: ${postReviewStatus || 'waiting'} by ${reviewerName}`);
@@ -2559,8 +2559,7 @@ async function handlePostMerge(pr, project, config, newStatus) {
 
   const agentId = (pr.agent || '').toLowerCase();
   if (agentId && config.agents?.[agentId]) {
-    const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
-    mutateJsonFileLocked(metricsPath, (metrics) => {
+    shared.mutateMetrics((metrics) => {
       if (!metrics[agentId]) metrics[agentId] = { ...DEFAULT_AGENT_METRICS };
       metrics[agentId].prsMerged = (metrics[agentId].prsMerged || 0) + 1;
       return metrics;

package/engine/llm.js

@@ -103,8 +103,8 @@ function flushMetricsBuffer() {
   _pendingMetrics = { engine: Object.create(null), daily: Object.create(null) };
 
   try {
-    const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
-    mutateJsonFileLocked(metricsPath, (metrics) => {
+    const { mutateMetrics } = require('./shared');
+    mutateMetrics((metrics) => {
       if (!metrics._engine) metrics._engine = {};
       for (const [category, delta] of Object.entries(pending.engine)) {
         if (!metrics._engine[category]) {

package/engine/logs-store.js

@@ -0,0 +1,190 @@
+// engine/logs-store.js — SQL-backed implementation of engine/log.json.
+//
+// Logs differ from work_items / pull_requests / dispatches: they are
+// pure append-only with a tail-cap, so the store exposes a different
+// shape:
+//
+//   appendLogsToDbFile(dbFilePath, entries)
+//     → bulk INSERT into the `logs` table at the given state.db path,
+//       then trim the head if the table exceeded the cap. Routes per
+//       dbFilePath so test isolation (each MINIONS_TEST_DIR has its own
+//       state.db) keeps working — the legacy `_logPath` capture-at-write
+//       pattern was the only correct way to keep test logs out of
+//       production storage, and we preserve the same idea here.
+//
+//   readRecentLogs(n, { level? })
+//     → SELECT ... ORDER BY id DESC LIMIT n against the singleton DB.
+//       Honors MINIONS_TEST_DIR / MINIONS_HOME automatically through
+//       engine/db.getDb().
+//
+// All writes happen through the per-path appender; the singleton is only
+// used for reads. This way a deferred buffer flush after a test ends
+// can't accidentally drop entries into the production state.db.
+
+const fs = require('fs');
+const path = require('path');
+
+// Per-dbPath connection cache. Avoids close+reopen thrash on the
+// singleton when buffered entries are routed to multiple test state.db
+// files in quick succession. Connections are closed via
+// closeAllLogWriterConnections() at process shutdown.
+const _connCache = new Map();
+
+function _ensureDir(filePath) {
+  try { fs.mkdirSync(path.dirname(filePath), { recursive: true }); } catch { /* exists */ }
+}
+
+function _openWriter(dbFilePath) {
+  let conn = _connCache.get(dbFilePath);
+  if (conn) return conn;
+  _ensureDir(dbFilePath);
+  // Use the same migration runner / pragma setup as the singleton, but
+  // against an explicit path. Re-running runMigrations against an
+  // already-migrated DB is a no-op (the version row gates it), so this
+  // is safe regardless of whether the singleton has touched the file.
+  const { DatabaseSync } = require('node:sqlite');
+  const db = new DatabaseSync(dbFilePath);
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA foreign_keys = ON');
+  db.exec('PRAGMA synchronous = NORMAL');
+  db.exec('PRAGMA busy_timeout = 5000');
+  const { runMigrations } = require('./db/migrate');
+  runMigrations(db);
+  conn = {
+    db,
+    insertStmt: db.prepare('INSERT INTO logs (ts_ms, level, message, meta) VALUES (?, ?, ?, ?)'),
+    countStmt: db.prepare('SELECT COUNT(*) AS n FROM logs'),
+  };
+  _connCache.set(dbFilePath, conn);
+  return conn;
+}
+
+function _toMs(v) {
+  if (v == null) return Date.now();
+  if (typeof v === 'number') return Number.isFinite(v) ? v : Date.now();
+  const parsed = Date.parse(v);
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
+
+// Strip the routing-only fields (timestamp, level, message, _logPath,
+// _dbPath) so `meta` only contains caller-provided extras.
+const _BUILTIN_KEYS = new Set(['timestamp', 'level', 'message', '_logPath', '_dbPath']);
+function _extractMeta(entry) {
+  const meta = {};
+  for (const k of Object.keys(entry)) {
+    if (_BUILTIN_KEYS.has(k)) continue;
+    meta[k] = entry[k];
+  }
+  return Object.keys(meta).length > 0 ? JSON.stringify(meta) : null;
+}
+
+// Append a batch of log entries to a specific state.db file.
+//
+// Bulk-wrapped in a transaction so a partial failure rolls back cleanly
+// and disk fsync only fires once per batch (matters at the 50-entry
+// buffer threshold under high load).
+//
+// After insert, if the table exceeds the ring-buffer cap, trim the
+// oldest entries down to logCapTrimTo. Trim is bounded — only runs when
+// we've actually overflowed, not on every batch.
+function appendLogsToDbFile(dbFilePath, entries) {
+  if (!entries || entries.length === 0) return 0;
+  let conn;
+  try { conn = _openWriter(dbFilePath); }
+  catch (e) {
+    // Logging must never crash the caller — swallow and bail.
+    return 0;
+  }
+
+  const shared = require('./shared');
+  const cap = (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.logCapEntries) || 2500;
+  const trimTo = (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.logCapTrimTo) || 2000;
+
+  let inserted = 0;
+  try {
+    conn.db.exec('BEGIN IMMEDIATE');
+    for (const entry of entries) {
+      const tsMs = _toMs(entry.timestamp);
+      const level = String(entry.level || 'info');
+      const message = String(entry.message != null ? entry.message : '');
+      const meta = _extractMeta(entry);
+      conn.insertStmt.run(tsMs, level, message, meta);
+      inserted += 1;
+    }
+    const total = conn.countStmt.get().n;
+    if (total > cap) {
+      // Trim the oldest rows. `id` is monotonic via AUTOINCREMENT, so
+      // ORDER BY id ASC + LIMIT (total - trimTo) deletes exactly the
+      // overflow. Single DELETE; no rowid scan required.
+      const toRemove = total - trimTo;
+      conn.db.prepare(`
+        DELETE FROM logs
+        WHERE id IN (SELECT id FROM logs ORDER BY id ASC LIMIT ?)
+      `).run(toRemove);
+    }
+    conn.db.exec('COMMIT');
+  } catch {
+    try { conn.db.exec('ROLLBACK'); } catch { /* best-effort */ }
+    return 0;
+  }
+
+  // Emit a single events row so dashboards / cache invalidators wake up
+  // once per batch instead of per entry. Routed against the singleton
+  // (not per-dbPath) because events are a cross-cutting concern keyed
+  // off the engine's active state.db.
+  try { require('./db-events').emitStateEvent('logs', { batch: inserted }); } catch { /* optional */ }
+  return inserted;
+}
+
+// Read the most recent N entries from the singleton DB (test-aware
+// because getDb() re-resolves MINIONS_TEST_DIR on every call).
+//
+// Returns entries in NEW-EST-FIRST order — matches what the dashboard
+// expects when slicing the tail of the array. Optional `level` filter
+// uses the level index.
+function readRecentLogs(n, opts) {
+  const limit = Math.max(1, Math.min(10000, Number(n) || 50));
+  const level = opts && opts.level ? String(opts.level) : null;
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return []; }
+  const rows = level
+    ? db.prepare('SELECT ts_ms, level, message, meta FROM logs WHERE level = ? ORDER BY id DESC LIMIT ?').all(level, limit)
+    : db.prepare('SELECT ts_ms, level, message, meta FROM logs ORDER BY id DESC LIMIT ?').all(limit);
+
+  const out = [];
+  for (const row of rows) {
+    const entry = {
+      timestamp: new Date(row.ts_ms).toISOString(),
+      level: row.level,
+      message: row.message,
+    };
+    if (row.meta) {
+      try { Object.assign(entry, JSON.parse(row.meta)); } catch { /* skip malformed meta */ }
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+// Convenience: same shape as the legacy `JSON.parse(log.json).slice(-N)`
+// — chronological order (oldest first). Inverts the readRecentLogs DESC
+// output so existing callers can drop in without re-sorting.
+function readRecentLogsChronological(n, opts) {
+  return readRecentLogs(n, opts).reverse();
+}
+
+function closeAllLogWriterConnections() {
+  for (const [, conn] of _connCache) {
+    try { conn.db.close(); } catch { /* already closed */ }
+  }
+  _connCache.clear();
+}
+
+module.exports = {
+  appendLogsToDbFile,
+  readRecentLogs,
+  readRecentLogsChronological,
+  closeAllLogWriterConnections,
+};

package/engine/pull-requests-store.js

@@ -0,0 +1,296 @@
+// engine/pull-requests-store.js — SQL-backed implementation of the
+// per-file pull-requests array. Same external contract as the legacy
+// JSON-file reader, modeled directly on work-items-store.js.
+//
+//   readPullRequestsForScope(scope)        -> [pr, pr, ...]
+//   applyPullRequestsMutation(scope, fn)   -> diff-then-apply,
+//                                             returns { wrote, result }
+//
+// `scope` is 'central' for the top-level pull-requests.json or a project
+// name for projects/<name>/pull-requests.json.
+//
+// External-edit detection mirrors work-items-store: per-scope last-mirror
+// mtime is recorded after every write; if the JSON file's mtime advances
+// outside our knowledge (test re-seed, operator hand-edit), we treat the
+// JSON as canonical and rebuild SQL before the next read or mutation.
+
+const path = require('path');
+const fs = require('fs');
+
+function _toMs(v) {
+  if (v == null) return null;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  const parsed = Date.parse(v);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function scopeForFilePath(filePath) {
+  const norm = String(filePath).replace(/\\/g, '/');
+  const m = norm.match(/projects\/([^/]+)\/pull-requests\.json$/);
+  if (m) return m[1];
+  return 'central';
+}
+
+function _filePathForScope(scope) {
+  const shared = require('./shared');
+  if (scope === 'central') {
+    return path.join(shared.MINIONS_DIR, 'pull-requests.json');
+  }
+  return path.join(shared.MINIONS_DIR, 'projects', scope, 'pull-requests.json');
+}
+
+function _parseRow(row) {
+  if (!row || !row.data) return null;
+  try { return JSON.parse(row.data); }
+  catch { return null; }
+}
+
+function _readJsonArrayFallback(scope) {
+  const fp = _filePathForScope(scope);
+  let raw;
+  try { raw = fs.readFileSync(fp, 'utf8'); }
+  catch { return []; }
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch (e) {
+    try {
+      // eslint-disable-next-line no-console
+      console.warn(`[pull-requests-store] corrupt JSON in ${fp}: ${e.message}`);
+    } catch { /* console may be wrapped in tests */ }
+    return [];
+  }
+}
+
+// Track (mtime, size) per scope so back-to-back writes inside the same
+// ms tick still get detected as external edits (mtime-only checks miss
+// them on Windows because NTFS reports ms-rounded mtimeMs).
+const _lastMirrorByScope = new Map();
+
+function _statFingerprint(filePath) {
+  try {
+    const st = fs.statSync(filePath);
+    return { mtime: st.mtimeMs, size: st.size };
+  }
+  catch { return null; }
+}
+
+function _hydrateScopeFromJson(db, scope) {
+  const jsonItems = _readJsonArrayFallback(scope);
+  db.prepare('DELETE FROM pull_requests WHERE scope = ?').run(scope);
+  if (jsonItems.length === 0) return;
+  const now = Date.now();
+  const ins = db.prepare(`
+    INSERT INTO pull_requests (id, scope, status, review_status, agent, branch, pr_number, created_at, last_polled_at, data, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(scope, id) DO NOTHING
+  `);
+  for (const pr of jsonItems) {
+    if (!pr || !pr.id) continue;
+    ins.run(
+      String(pr.id),
+      scope,
+      String(pr.status || 'active'),
+      pr.reviewStatus || null,
+      pr.agent || null,
+      pr.branch || null,
+      Number.isFinite(pr.prNumber) ? pr.prNumber : null,
+      _toMs(pr.created),
+      _toMs(pr.lastPolledAt || pr.lastPolled),
+      JSON.stringify(pr),
+      now,
+    );
+  }
+}
+
+function _resyncScopeIfJsonDiverged(db, scope) {
+  const jsonPath = _filePathForScope(scope);
+  const current = _statFingerprint(jsonPath);
+  const lastMirror = _lastMirrorByScope.get(scope);
+  if (current == null) return;
+  // In-sync iff BOTH mtime AND size match. Size catches same-ms-tick
+  // external writes that mtime alone misses. Resync is idempotent.
+  if (lastMirror != null
+    && current.mtime === lastMirror.mtime
+    && current.size === lastMirror.size) return;
+  if (lastMirror == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM pull_requests WHERE scope = ? LIMIT 1').get(scope);
+    if (sqlHas) {
+      _lastMirrorByScope.set(scope, current);
+      return;
+    }
+  }
+  _hydrateScopeFromJson(db, scope);
+  _lastMirrorByScope.set(scope, current);
+}
+
+function readPullRequestsForScope(scope) {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return _readJsonArrayFallback(scope); }
+
+  _resyncScopeIfJsonDiverged(db, scope);
+
+  const rows = db.prepare(`
+    SELECT data FROM pull_requests
+    WHERE scope = ?
+    ORDER BY rowid
+  `).all(scope);
+
+  if (rows.length === 0) {
+    const fallback = _readJsonArrayFallback(scope);
+    if (fallback.length > 0) return fallback;
+    return [];
+  }
+
+  const out = [];
+  for (const row of rows) {
+    const pr = _parseRow(row);
+    if (pr) out.push(pr);
+  }
+  return out;
+}
+
+function readAllPullRequests() {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return null; }
+
+  try { _resyncScopeIfJsonDiverged(db, 'central'); } catch {}
+  const knownScopes = db.prepare('SELECT DISTINCT scope FROM pull_requests').all().map(r => r.scope);
+  for (const s of knownScopes) {
+    if (s === 'central') continue;
+    try { _resyncScopeIfJsonDiverged(db, s); } catch {}
+  }
+
+  const rows = db.prepare('SELECT data, scope FROM pull_requests ORDER BY rowid').all();
+  const out = [];
+  for (const row of rows) {
+    const pr = _parseRow(row);
+    if (!pr) continue;
+    pr._scope = row.scope;
+    out.push(pr);
+  }
+  return out;
+}
+
+function _indexById(arr) {
+  const out = new Map();
+  for (const pr of arr) {
+    if (!pr || !pr.id) continue;
+    out.set(String(pr.id), pr);
+  }
+  return out;
+}
+
+function _computePullRequestsDiff(scope, before, after) {
+  const beforeMap = _indexById(before);
+  const afterMap = _indexById(after);
+  const toUpsert = [];
+  const toDelete = [];
+  for (const [id, pr] of afterMap) {
+    const prev = beforeMap.get(id);
+    if (!prev) { toUpsert.push(pr); continue; }
+    if (JSON.stringify(prev) !== JSON.stringify(pr)) toUpsert.push(pr);
+  }
+  for (const [id] of beforeMap) {
+    if (!afterMap.has(id)) toDelete.push(id);
+  }
+  return { scope, toUpsert, toDelete };
+}
+
+function _applyPullRequestsDiff(db, diff) {
+  if (diff.toUpsert.length === 0 && diff.toDelete.length === 0) return false;
+  const now = Date.now();
+  const upsertStmt = db.prepare(`
+    INSERT INTO pull_requests (id, scope, status, review_status, agent, branch, pr_number, created_at, last_polled_at, data, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(scope, id) DO UPDATE SET
+      status         = excluded.status,
+      review_status  = excluded.review_status,
+      agent          = excluded.agent,
+      branch         = excluded.branch,
+      pr_number      = excluded.pr_number,
+      created_at     = excluded.created_at,
+      last_polled_at = excluded.last_polled_at,
+      data           = excluded.data,
+      updated_at     = excluded.updated_at
+  `);
+  const deleteStmt = db.prepare('DELETE FROM pull_requests WHERE scope = ? AND id = ?');
+
+  for (const pr of diff.toUpsert) {
+    upsertStmt.run(
+      String(pr.id),
+      diff.scope,
+      String(pr.status || 'active'),
+      pr.reviewStatus || null,
+      pr.agent || null,
+      pr.branch || null,
+      Number.isFinite(pr.prNumber) ? pr.prNumber : null,
+      _toMs(pr.created),
+      _toMs(pr.lastPolledAt || pr.lastPolled),
+      JSON.stringify(pr),
+      now,
+    );
+  }
+  for (const id of diff.toDelete) {
+    deleteStmt.run(diff.scope, id);
+  }
+  return true;
+}
+
+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`);
+  }
+
+  return withTransaction(db, () => {
+    _resyncScopeIfJsonDiverged(db, scope);
+    const before = readPullRequestsForScope(scope);
+    // Strip the _scope decoration that readAllPullRequests adds, in case
+    // a caller round-trips records from there back through here.
+    for (const pr of before) { if (pr && pr._scope) delete pr._scope; }
+    const beforeSnapshot = JSON.parse(JSON.stringify(before));
+    const next = mutator(before);
+    const after = (next === undefined || next === null)
+      ? before
+      : (Array.isArray(next) ? next : before);
+    const diff = _computePullRequestsDiff(scope, beforeSnapshot, after);
+    const wrote = _applyPullRequestsDiff(db, diff);
+    return { wrote, result: after };
+  });
+}
+
+function _mirrorJsonFromSql(scope, filePath) {
+  try {
+    const shared = require('./shared');
+    const items = readPullRequestsForScope(scope);
+    for (const pr of items) { if (pr && pr._scope) delete pr._scope; }
+    const target = filePath || _filePathForScope(scope);
+    shared.safeWrite(target, items);
+    const fp = _statFingerprint(target);
+    if (fp != null) _lastMirrorByScope.set(scope, fp);
+  } catch {
+    // Mirror failures are non-fatal — SQL has already committed.
+  }
+}
+
+function _resetPullRequestsTableForTest() {
+  const { getDb } = require('./db');
+  try { getDb().exec('DELETE FROM pull_requests'); } catch { /* not initialized */ }
+}
+
+module.exports = {
+  scopeForFilePath,
+  readPullRequestsForScope,
+  readAllPullRequests,
+  applyPullRequestsMutation,
+  _filePathForScope,
+  _mirrorJsonFromSql,
+  _resetPullRequestsTableForTest,
+};

package/engine/queries.js

@@ -327,8 +327,17 @@ function getNotesWithMeta() {
 }
 
 function getEngineLog() {
-  // Use the lazy log-path resolver so test isolation (MINIONS_TEST_DIR) is
-  // honored even when this module's require cache wasn't busted.
+  // Phase 4: prefer the SQL store. readRecentLogsChronological returns
+  // entries oldest-first (same shape as the legacy `.slice(-50)`), and is
+  // test-aware via engine/db.getDb() which re-resolves MINIONS_TEST_DIR.
+  // Falls back to the JSON mirror on SQL failure or when the table is
+  // empty (fresh install / pre-migration).
+  try {
+    const store = require('./logs-store');
+    const sqlEntries = store.readRecentLogsChronological(50);
+    if (Array.isArray(sqlEntries) && sqlEntries.length > 0) return sqlEntries;
+  } catch { /* fall through to JSON */ }
+
   const logJson = safeRead(shared.currentLogPath());
   if (!logJson) return [];
   try {
@@ -339,7 +348,16 @@ function getEngineLog() {
 }
 
 function getMetrics() {
-  const metrics = readJsonNoRestore(path.join(ENGINE_DIR, 'metrics.json')) || {};
+  // Phase 5: prefer the SQL store. Falls back to the JSON mirror on
+  // SQLite failure or when the table is empty (fresh install /
+  // pre-migration). Returns the legacy flat object shape.
+  let metrics;
+  try {
+    const store = require('./metrics-store');
+    metrics = store.readMetrics() || {};
+  } catch {
+    metrics = readJsonNoRestore(path.join(ENGINE_DIR, 'metrics.json')) || {};
+  }
 
   for (const [agentId, m] of Object.entries(metrics)) {
     if (agentId.startsWith('_')) continue;
@@ -651,45 +669,74 @@ function getPullRequests(config) {
   const projectByName = new Map(projects.map(p => [p.name, p]));
   const allPrs = [];
   const seenIds = new Set();
-  // Single pass over projects/* intersected with the configured project list.
-  // Filesystem dirs not in CONFIG.projects (e.g. a leftover .minions/projects/
-  // <removedName>/ recreated by a stale code path between archive and reload)
-  // are skipped so removed projects can't resurrect themselves through the
-  // status payload. Hidden dirs (.archived sidecar) are also skipped defensively
-  // — they live as siblings under projects/ and would otherwise be enumerated.
-  let projectDirs = [];
+
+  // Phase 3: prefer the SQL store. Returns every scope's PRs tagged with
+  // `_scope`; we re-map to `_project` for backward compatibility with
+  // downstream consumers, intersecting with the configured project list
+  // to suppress orphan/removed projects (matches legacy behaviour).
+  let sqlPrs = null;
   try {
-    projectDirs = fs.readdirSync(path.join(MINIONS_DIR, 'projects'), { withFileTypes: true })
-      .filter(d => d.isDirectory() && !d.name.startsWith('.')).map(d => d.name);
-  } catch { /* projects dir missing */ }
-  for (const dirName of projectDirs) {
-    const project = projectByName.get(dirName);
-    if (!project) continue; // unconfigured/removed — don't surface
-    const prPath = projectPrPath(project);
-    const prs = readJsonNoRestore(prPath);
-    if (!Array.isArray(prs)) continue;
-    shared.normalizePrRecords(prs, project);
-    const base = project.prUrlBase || '';
-    for (const pr of prs) {
+    const store = require('./pull-requests-store');
+    sqlPrs = store.readAllPullRequests();
+  } catch { /* fall through to JSON */ }
+
+  if (Array.isArray(sqlPrs) && sqlPrs.length > 0) {
+    for (const pr of sqlPrs) {
       if (!pr?.id || seenIds.has(pr.id)) continue;
-      if (!pr.url && base) {
-        const prNumber = shared.getPrNumber(pr);
-        if (prNumber != null) pr.url = base + prNumber;
+      const scope = pr._scope;
+      delete pr._scope;
+      if (scope === 'central') {
+        pr._project = 'central';
+      } else {
+        const project = projectByName.get(scope);
+        if (!project) continue;  // orphan/removed project — don't surface
+        const base = project.prUrlBase || '';
+        if (!pr.url && base) {
+          const prNumber = shared.getPrNumber(pr);
+          if (prNumber != null) pr.url = base + prNumber;
+        }
+        shared.normalizePrRecords([pr], project);
+        pr._project = project.name || 'Project';
       }
-      pr._project = project.name || 'Project';
       allPrs.push(pr);
       seenIds.add(pr.id);
     }
-  }
-  // Central pull-requests.json — manually linked PRs without a project
-  const centralPrs = readJsonNoRestore(path.join(MINIONS_DIR, 'pull-requests.json'));
-  if (centralPrs) {
-    shared.normalizePrRecords(centralPrs, null);
-    for (const pr of centralPrs) {
-      if (!pr?.id || seenIds.has(pr.id)) continue;
-      pr._project = 'central';
-      allPrs.push(pr);
-      seenIds.add(pr.id);
+  } else {
+    // SQL empty or unavailable — fall back to per-file JSON read. Matches
+    // the original layout: per-project dirs first, central last.
+    let projectDirs = [];
+    try {
+      projectDirs = fs.readdirSync(path.join(MINIONS_DIR, 'projects'), { withFileTypes: true })
+        .filter(d => d.isDirectory() && !d.name.startsWith('.')).map(d => d.name);
+    } catch { /* projects dir missing */ }
+    for (const dirName of projectDirs) {
+      const project = projectByName.get(dirName);
+      if (!project) continue;
+      const prPath = projectPrPath(project);
+      const prs = readJsonNoRestore(prPath);
+      if (!Array.isArray(prs)) continue;
+      shared.normalizePrRecords(prs, project);
+      const base = project.prUrlBase || '';
+      for (const pr of prs) {
+        if (!pr?.id || seenIds.has(pr.id)) continue;
+        if (!pr.url && base) {
+          const prNumber = shared.getPrNumber(pr);
+          if (prNumber != null) pr.url = base + prNumber;
+        }
+        pr._project = project.name || 'Project';
+        allPrs.push(pr);
+        seenIds.add(pr.id);
+      }
+    }
+    const centralPrs = readJsonNoRestore(path.join(MINIONS_DIR, 'pull-requests.json'));
+    if (centralPrs) {
+      shared.normalizePrRecords(centralPrs, null);
+      for (const pr of centralPrs) {
+        if (!pr?.id || seenIds.has(pr.id)) continue;
+        pr._project = 'central';
+        allPrs.push(pr);
+        seenIds.add(pr.id);
+      }
     }
   }
   allPrs.sort((a, b) => {

package/engine/shared.js

@@ -285,6 +285,17 @@ function log(level, msg, meta = {}) {
     writable: true,
     configurable: true,
   });
+  // Capture the SQL state.db path too — same write-time semantics so a
+  // deferred buffer flush after the test ends still routes the entry to
+  // the test's state.db (not the production one). Path resolution mirrors
+  // engine/db.js but inlined to avoid the require cycle that loading the
+  // db module here would create on module init.
+  Object.defineProperty(entry, '_dbPath', {
+    value: _currentLogDbPath(),
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
 
   _logBuffer.push(entry);
 
@@ -337,6 +348,19 @@ function _currentLogPath() {
   return path.join(root, 'engine', 'log.json');
 }
 
+// Resolve the SQL state.db path at write time — same isolation contract
+// as _currentLogPath. MINIONS_LOG_PATH only redirects the JSON sidecar;
+// the SQL store stays attached to MINIONS_TEST_DIR / MINIONS_HOME because
+// it shares the file with the rest of the engine state (dispatches,
+// work_items, pull_requests).
+function _currentLogDbPath() {
+  if (process.env.MINIONS_TEST_DIR) {
+    return path.join(path.resolve(process.env.MINIONS_TEST_DIR), 'engine', 'state.db');
+  }
+  const root = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : path.resolve(__dirname, '..');
+  return path.join(root, 'engine', 'state.db');
+}
+
 // MINIONS_TEST_DIR-aware engine dir for cache files (runtime caps, models,
 // spawn-debug.log). Returns `<MINIONS_TEST_DIR>/engine` under tests; otherwise
 // the caller's source-adjacent fallback (typically `__dirname`-derived). Never
@@ -366,23 +390,44 @@ function openUrlInBrowser(url) {
 function _flushLogBuffer() {
   if (_logBuffer.length === 0) return;
   const drained = _logBuffer.splice(0);
-  // Group entries by their captured _logPath so test-originated entries always
-  // land in the test dir's log.json even if MINIONS_TEST_DIR has been cleared
-  // by the time we flush. Entries without _logPath fall back to current path
-  // (eg. direct _logBuffer.push() from tests).
-  const fallbackPath = _currentLogPath();
-  const byPath = new Map();
+  // Group entries by their captured (_logPath, _dbPath) so test-originated
+  // entries always land in the test dir's storage even if MINIONS_TEST_DIR
+  // has been cleared by the time we flush. Entries without captured paths
+  // fall back to the current resolved values (eg. direct _logBuffer.push()
+  // from tests).
+  const fallbackJsonPath = _currentLogPath();
+  const fallbackDbPath = _currentLogDbPath();
+  const byJsonPath = new Map();
+  const byDbPath = new Map();
   for (const raw of drained) {
-    const target = raw._logPath || fallbackPath;
+    const jsonTarget = raw._logPath || fallbackJsonPath;
+    const dbTarget = raw._dbPath || fallbackDbPath;
     // SEC-09 defense-in-depth: redact again at flush time so any direct
     // `_logBuffer.push(entry)` callers (tests, future paths) can't leak secrets.
     const entry = redactSecrets(raw);
     // Strip the routing-only metadata before persisting.
     delete entry._logPath;
-    if (!byPath.has(target)) byPath.set(target, []);
-    byPath.get(target).push(entry);
+    delete entry._dbPath;
+    if (!byJsonPath.has(jsonTarget)) byJsonPath.set(jsonTarget, []);
+    byJsonPath.get(jsonTarget).push(entry);
+    if (!byDbPath.has(dbTarget)) byDbPath.set(dbTarget, []);
+    byDbPath.get(dbTarget).push(entry);
   }
-  for (const [target, entries] of byPath) {
+
+  // SQL append (Phase 4 source of truth). Per-path append so test
+  // state.db files stay isolated; logging must never crash the caller, so
+  // appendLogsToDbFile already swallows its own errors.
+  try {
+    const store = require('./logs-store');
+    for (const [dbPath, entries] of byDbPath) {
+      store.appendLogsToDbFile(dbPath, entries);
+    }
+  } catch { /* logs-store unavailable (node<22.5) — JSON mirror still works */ }
+
+  // JSON mirror — kept for backward compat with test fixtures that
+  // safeJson(log.json) directly, and the legacy getEngineLog fallback.
+  // Phase 4.5 will retire this once readers move to readRecentLogs().
+  for (const [target, entries] of byJsonPath) {
     try {
       mutateJsonFileLocked(target, (logData) => {
         if (!Array.isArray(logData)) logData = logData?.entries || [];
@@ -1806,6 +1851,8 @@ const ENGINE_DEFAULTS = {
   versionCheckInterval: 3600000, // 1 hour — how often to check npm for updates (ms)
   logFlushInterval: 5000, // 5s — how often to flush buffered log entries to disk
   logBufferSize: 50, // flush immediately when buffer exceeds this many entries
+  logCapEntries: 2500, // ring-buffer cap on `logs` SQL table; trims to logCapEntries-logCapTrimTo on overflow
+  logCapTrimTo: 2000, // size to trim back to when cap is hit (matches legacy JSON splice 2500→2000)
   lockRetries: 0, // no retries — single 5s timeout window with 25ms polling (200 attempts) is sufficient; stale lock recovery at 60s handles crashes
   lockRetryBackoffMs: 500, // base backoff between lock retries (doubles each attempt: 500ms, 1s, 2s, ...)
   buildFixGracePeriod: 600000, // 10min — wait for CI to run after a verified build-fix push before re-dispatching
@@ -2643,13 +2690,52 @@ const WATCH_ACTION_TYPE = {
   RESUME_PLAN: 'resume-plan',
 };
 
+/**
+ * Route a metrics mutation through the SQL store with a JSON dual-write
+ * 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.
+ */
+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;
+    }
+    // SQLite unavailable — fall through to legacy JSON path.
+  }
+  return mutateJsonFileLocked(metricsPath, (metrics) => {
+    if (!metrics || typeof metrics !== 'object') metrics = {};
+    return mutator(metrics) || metrics;
+  }, {
+    defaultValue: {},
+    onWrote: () => {
+      try { require('./db-events').emitStateEvent('metrics'); } catch { /* optional */ }
+    },
+  });
+}
+
 /** Update per-agent review metrics (prsApproved/prsRejected). Only writes for configured agents. */
 function trackReviewMetric(pr, newReviewStatus, config) {
   if (newReviewStatus !== 'approved' && newReviewStatus !== 'changes-requested') return;
   const authorId = (pr.agent || '').toLowerCase();
   if (!authorId || !config?.agents?.[authorId]) return;
   try {
-    mutateJsonFileLocked(path.join(MINIONS_DIR, 'engine', 'metrics.json'), (metrics) => {
+    mutateMetrics((metrics) => {
       if (!metrics[authorId]) metrics[authorId] = { ...DEFAULT_AGENT_METRICS };
       if (newReviewStatus === 'approved') metrics[authorId].prsApproved = (metrics[authorId].prsApproved || 0) + 1;
       else metrics[authorId].prsRejected = (metrics[authorId].prsRejected || 0) + 1;
@@ -4643,6 +4729,35 @@ function reopenWorkItem(wi) {
  * @param {Function} mutator - Receives the array, mutates in place or returns new value
  */
 function mutatePullRequests(filePath, mutator) {
+  // Phase 3 SQL path. Same shape as Phase 2's mutateWorkItems: route
+  // through the pull-requests-store when filePath sits under MINIONS_DIR,
+  // mirror back to JSON for legacy direct-readers, emit a pull_requests
+  // event only on real writes. Ad-hoc tmp paths (legacy tests using
+  // createTmpDir) and SQLite failures 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 is 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.
+    }
+  }
+
   return mutateJsonFileLocked(filePath, (data) => {
     if (!Array.isArray(data)) data = [];
     return mutator(data) || data;
@@ -5051,7 +5166,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, WORKTREE_REQUIRING_TYPES, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, WORKTREE_REQUIRING_TYPES, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, mutateMetrics, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,

package/engine/work-items-store.js

@@ -116,24 +116,28 @@ function readWorkItemsForScope(scope) {
 // scope is bounded by the JSON's row count.
 function _resyncScopeIfJsonDiverged(db, scope) {
   const jsonPath = _filePathForScope(scope);
-  const currentMtime = _statMtimeMs(jsonPath);
-  const lastMirrorMtime = _lastMirrorMtimeByScope.get(scope);
-  if (currentMtime == null) return;  // JSON absent → nothing to resync
-  if (lastMirrorMtime != null && Math.abs(currentMtime - lastMirrorMtime) <= 1) return;  // in sync
+  const current = _statFingerprint(jsonPath);
+  const lastMirror = _lastMirrorByScope.get(scope);
+  if (current == null) return;  // JSON absent → nothing to resync
+  // In-sync iff BOTH mtime AND size match. Either differing signals an
+  // external write — including the same-ms-tick safeWrite pattern that
+  // mtime-only checks miss on Windows (ms-rounded mtimeMs collides).
+  // Resync is idempotent (DELETE + bulk re-INSERT from JSON).
+  if (lastMirror != null
+    && current.mtime === lastMirror.mtime
+    && current.size === lastMirror.size) return;
   // No mirror record but JSON exists: first-time hydrate iff SQL is empty
   // for this scope (avoid trampling a freshly-backfilled migration state
   // on the very first read).
-  if (lastMirrorMtime == null) {
+  if (lastMirror == null) {
     const sqlHas = db.prepare('SELECT 1 FROM work_items WHERE scope = ? LIMIT 1').get(scope);
     if (sqlHas) {
-      // Record current mtime as the baseline so the next divergence is
-      // detected, but don't rebuild — migration already populated SQL.
-      _lastMirrorMtimeByScope.set(scope, currentMtime);
+      _lastMirrorByScope.set(scope, current);
       return;
     }
   }
   _hydrateScopeFromJson(db, scope);
-  _lastMirrorMtimeByScope.set(scope, currentMtime);
+  _lastMirrorByScope.set(scope, current);
 }
 
 // Read all rows across all scopes — used by queries.getWorkItems which
@@ -239,17 +243,19 @@ function _applyWorkItemsDiff(db, diff) {
 //   wrote  — true iff at least one INSERT/UPDATE/DELETE landed
 //   result — the post-mutation array (legacy return shape of
 //            mutateJsonFileLocked)
-// In-process record of the JSON mirror mtime we last wrote, keyed by
-// scope. Used to detect external JSON edits between mutations — both
-// (a) tests that clean up + re-seed via fs.writeFileSync, and
-// (b) operators that hand-edit work-items.json in production. When the
-// current JSON mtime differs from what we recorded, the JSON has been
-// rewritten outside the store; we treat the JSON as canonical and
-// re-hydrate SQL from it before computing the diff.
-const _lastMirrorMtimeByScope = new Map();
+// In-process record of (mtime, size) of the JSON mirror we last wrote,
+// keyed by scope. Two-field fingerprint catches the same-ms-tick write
+// pattern that mtime-only checks miss on Windows: NTFS reports
+// ms-rounded mtimeMs, so back-to-back writes inside the same tick look
+// identical to "no change" by mtime alone. File size catches the rest
+// — content swaps almost always change byte length.
+const _lastMirrorByScope = new Map();
 
-function _statMtimeMs(filePath) {
-  try { return fs.statSync(filePath).mtimeMs; }
+function _statFingerprint(filePath) {
+  try {
+    const st = fs.statSync(filePath);
+    return { mtime: st.mtimeMs, size: st.size };
+  }
   catch { return null; }
 }
 
@@ -325,10 +331,11 @@ function _mirrorJsonFromSql(scope, filePath) {
     for (const wi of items) { if (wi && wi._source) delete wi._source; }
     const target = filePath || _filePathForScope(scope);
     shared.safeWrite(target, items);
-    // Record the mtime we just wrote so the next mutation can detect
-    // an external edit (mtime advanced while we weren't looking).
-    const m = _statMtimeMs(target);
-    if (m != null) _lastMirrorMtimeByScope.set(scope, m);
+    // Record (mtime, size) we just wrote so the next mutation can detect
+    // an external edit. mtime alone misses same-ms-tick writes; size
+    // catches them.
+    const fp = _statFingerprint(target);
+    if (fp != null) _lastMirrorByScope.set(scope, fp);
   } catch {
     // Mirror failures are non-fatal: SQL has already committed.
   }

package/package.json

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