@yemi33/minions 0.1.2072 → 0.1.2073

package/docs/README.md

@@ -23,6 +23,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [pr-comment-followup.md](pr-comment-followup.md) — PR-comment follow-up dispatch contract: fix/review agents may spin off a new WI via `POST /api/work-items` with `meta.pr_followup` instead of broadening the current PR or rebutting the comment.
 - [pr-review-fix-loop.md](pr-review-fix-loop.md) — How the engine moves a PR from creation through review, fix dispatch, and re-review, including stale-status guards.
+- [qa-runbook-lifecycle.md](qa-runbook-lifecycle.md) — End-to-end QA runbook lifecycle (W-mpeiwz6k0005bf34): runbook + run-record storage, `POST /api/qa/runbooks/run` dispatch into the `qa-validate` playbook, artifact contract, and how the `/qa` page mirrors managed-spawn observability.
 - [qa-runbooks.md](qa-runbooks.md) — Per-project QA runbook schema, storage layout (`projects/<name>/runbooks/<id>.json`), CRUD endpoints, run-record lifecycle, and the `qa-validate` agent sidecar contract.
 - [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
 - [runtime-adapters.md](runtime-adapters.md) — Runtime adapter contract (`engine/runtimes/*`): how the engine talks to Claude Code, Copilot CLI, and future CLIs through a single capability-flagged interface.

package/docs/auto-discovery.md

@@ -1,6 +1,6 @@
 # Auto-Discovery & Execution Pipeline
 
-> Last verified: 2026-05-25 against `engine.js` `tickInner()` (lines 6293-6947) and `routing.md`.
+> Last verified: 2026-05-28 against `engine.js` `tickInner()` and `routing.md`.
 
 How the minions engine finds work and dispatches agents automatically.
 
@@ -15,6 +15,7 @@ tick()
   1b. checkIdleThreshold()       Notify on excessive agent idleness
   1c. meetingTimeouts()          Advance round-based meetings whose timer fired
   2.  consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
+  2.1 autoSweepKb()              Periodic KB sweep (opt-in via engine.autoConsolidateMemory, 4h cadence)
   2.5 runCleanup()               Periodic cleanup (every 10 ticks ≈ 10min)
   2.52 sweepKeepProcesses()      keep_processes TTL/dead-PID sweep (every 30 ticks)
   2.53 sweepManagedSpawn()       managed_spawn TTL/dead-PID/log-rotate sweep (every 30 ticks)

package/docs/kb-sweep.md

@@ -114,6 +114,14 @@ Sweep state is mirrored to `engine/kb-sweep-state.json` so the dashboard can rec
 
 Memory still wins when present; the disk file is a fallback (source: [`engine/kb-sweep.js:298-320`](../engine/kb-sweep.js#L298), [`dashboard.js:4296-4354`](../dashboard.js#L4296)). A separate `engine/kb-swept.json` is written after each successful sweep with the human-readable summary line shown by the dashboard's "swept N days ago" badge (source: [`engine/kb-sweep.js:407`](../engine/kb-sweep.js#L407)).
 
+## Automatic Periodic Sweep (opt-in)
+
+The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `false` — source: [`engine/shared.js:1835`](../engine/shared.js#L1835)):
+
+- When `engine.autoConsolidateMemory: true`, every tick the engine consults `shouldAutoSweep()` from [`engine/kb-sweep.js`](../engine/kb-sweep.js) and, when the 4-hour cadence has elapsed since the last completion, calls `spawnSweepRunnerDetached()` to fire-and-forget a fresh `engine/kb-sweep-runner.js` process (source: [`engine.js`](../engine.js) tick step 2.1).
+- The inbox→`notes.md` consolidation runs every tick *regardless* of this flag via `consolidateInbox()`; `autoConsolidateMemory` controls **only** the heavier `knowledge/` sweep.
+- The detached runner survives `minions restart` (same pattern used by the manual trigger), and the in-flight guard above prevents overlap with manual sweeps.
+
 ## Dashboard UI
 
 The KB page surfaces sweep state in two places:

package/engine/db/migrations/007-watches.js

@@ -0,0 +1,95 @@
+// engine/db/migrations/007-watches.js
+//
+// Phase 6: move engine/watches.json into a `watches` table.
+//
+// watches.json is an array of watch jobs polled every 3 ticks. Most
+// installs carry only a handful (operator-defined notifications, plan-
+// completion gates, etc), but the table is still indexed by status +
+// target_type so dashboards / future filters can do "show active PR
+// watches" without pulling the whole array.
+//
+// Schema is the same hybrid pattern Phases 2/3/5 use: typed projection
+// columns for the hot filters, a `data` TEXT blob for everything else.
+
+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;
+}
+
+module.exports = {
+  version: 7,
+  description: 'watches: schema + watches.json backfill',
+  up(db) {
+    db.exec(`
+      CREATE TABLE watches (
+        id              TEXT PRIMARY KEY,
+        target          TEXT,
+        target_type     TEXT,
+        condition       TEXT,
+        status          TEXT NOT NULL,
+        owner           TEXT,
+        created_at      INTEGER,
+        last_checked    INTEGER,
+        last_triggered  INTEGER,
+        data            TEXT NOT NULL,
+        updated_at      INTEGER NOT NULL
+      );
+      CREATE INDEX idx_watches_status       ON watches(status);
+      CREATE INDEX idx_watches_target_type  ON watches(target_type);
+      CREATE INDEX idx_watches_target       ON watches(target);
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    const watchesPath = path.join(minionsDir, 'engine', 'watches.json');
+    if (!fs.existsSync(watchesPath)) return;
+
+    let raw;
+    try { raw = JSON.parse(fs.readFileSync(watchesPath, 'utf8')); }
+    catch (e) {
+      throw new Error(`engine/db/007-watches: cannot parse watches.json: ${e.message}`);
+    }
+    if (!Array.isArray(raw)) return;
+
+    const now = Date.now();
+    const insert = db.prepare(`
+      INSERT INTO watches (id, target, target_type, condition, status, owner, created_at, last_checked, last_triggered, data, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    let inserted = 0;
+    for (const w of raw) {
+      if (!w || typeof w !== 'object' || !w.id) continue;
+      try {
+        insert.run(
+          String(w.id),
+          typeof w.target === 'string' ? w.target : (w.target == null ? null : JSON.stringify(w.target)),
+          w.targetType || null,
+          w.condition || null,
+          String(w.status || 'active'),
+          w.owner || null,
+          _toMs(w.created_at),
+          _toMs(w.last_checked),
+          _toMs(w.last_triggered),
+          JSON.stringify(w),
+          now,
+        );
+        inserted += 1;
+      } catch { /* duplicate id — skip defensively */ }
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(`[db-migrate] v7: backfilled ${inserted} watches; watches.json kept as dual-write mirror`);
+  },
+};

package/engine/pull-requests-store.js

@@ -62,15 +62,16 @@ function _readJsonArrayFallback(scope) {
   }
 }
 
-// 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();
+// Content-hash fingerprint per scope: same-length swaps (timestamps,
+// reviewStatus enums) collide on (mtime, size) but never on SHA-1.
+const _lastMirrorHashByScope = new Map();
 
-function _statFingerprint(filePath) {
+const crypto = require('crypto');
+
+function _fileContentHash(filePath) {
   try {
-    const st = fs.statSync(filePath);
-    return { mtime: st.mtimeMs, size: st.size };
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha1').update(buf).digest('hex');
   }
   catch { return null; }
 }
@@ -105,23 +106,19 @@ function _hydrateScopeFromJson(db, scope) {
 
 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 currentHash = _fileContentHash(jsonPath);
+  const lastHash = _lastMirrorHashByScope.get(scope);
+  if (currentHash == null) return;
+  if (lastHash != null && currentHash === lastHash) return;
+  if (lastHash == null) {
     const sqlHas = db.prepare('SELECT 1 FROM pull_requests WHERE scope = ? LIMIT 1').get(scope);
     if (sqlHas) {
-      _lastMirrorByScope.set(scope, current);
+      _lastMirrorHashByScope.set(scope, currentHash);
       return;
     }
   }
   _hydrateScopeFromJson(db, scope);
-  _lastMirrorByScope.set(scope, current);
+  _lastMirrorHashByScope.set(scope, currentHash);
 }
 
 function readPullRequestsForScope(scope) {
@@ -269,12 +266,23 @@ function applyPullRequestsMutation(scope, mutator) {
 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 { getDb } = require('./db');
+    // Read SQL directly for this scope — bypass JSON fallback so a
+    // mutation that empties SQL for the scope doesn't resurrect stale
+    // JSON content.
+    const db = getDb();
+    const rows = db.prepare('SELECT data FROM pull_requests WHERE scope = ? ORDER BY rowid').all(scope);
+    const items = [];
+    for (const row of rows) {
+      const pr = _parseRow(row);
+      if (!pr) continue;
+      if (pr._scope) delete pr._scope;
+      items.push(pr);
+    }
     const target = filePath || _filePathForScope(scope);
     shared.safeWrite(target, items);
-    const fp = _statFingerprint(target);
-    if (fp != null) _lastMirrorByScope.set(scope, fp);
+    const h = _fileContentHash(target);
+    if (h != null) _lastMirrorHashByScope.set(scope, h);
   } catch {
     // Mirror failures are non-fatal — SQL has already committed.
   }

package/engine/shared.js

@@ -2744,6 +2744,43 @@ const WATCH_ACTION_TYPE = {
   RESUME_PLAN: 'resume-plan',
 };
 
+/**
+ * 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.
+ */
+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;
+    }
+    // SQLite unavailable — fall through to legacy JSON path.
+  }
+  return mutateJsonFileLocked(watchesPath, (data) => {
+    if (!Array.isArray(data)) data = [];
+    return mutator(data) || data;
+  }, {
+    defaultValue: [],
+    onWrote: () => {
+      try { require('./db-events').emitStateEvent('watches'); } catch { /* optional */ }
+    },
+  });
+}
+
 /**
  * Route a metrics mutation through the SQL store with a JSON dual-write
  * mirror. Same shape as mutateWorkItems / mutatePullRequests: mutator
@@ -5225,7 +5262,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, mutateMetrics, 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, mutateWatches, 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/watches-store.js

@@ -0,0 +1,259 @@
+// engine/watches-store.js — SQL-backed implementation of engine/watches.json.
+//
+// Mirrors the Phase 2/3 work_items / pull_requests stores: a single
+// table (no per-scope split — watches.json is a flat array, not
+// per-project), diff-then-apply mutator, JSON dual-write mirror with
+// (mtime, size) fingerprint for external-edit detection.
+//
+//   readWatches()           -> [watch, watch, ...]
+//   applyWatchesMutation(fn) -> diff-then-apply, returns { wrote, result }
+
+const fs = require('fs');
+const path = require('path');
+
+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 _watchesFilePath() {
+  const shared = require('./shared');
+  return path.join(shared.MINIONS_DIR, 'engine', 'watches.json');
+}
+
+function _parseRow(row) {
+  if (!row || !row.data) return null;
+  try { return JSON.parse(row.data); }
+  catch { return null; }
+}
+
+function _readJsonArrayFallback() {
+  const fp = _watchesFilePath();
+  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(`[watches-store] corrupt JSON in ${fp}: ${e.message}`);
+    } catch { /* console may be wrapped */ }
+    return [];
+  }
+}
+
+// Content-hash fingerprint — (mtime, size) is too coarse: same-size
+// content swaps (e.g. last_checked timestamps that always have the same
+// byte length) inside the same ms tick collide on both axes. Hashing the
+// bytes is the unambiguous signal. SHA-1 on a few-KB file is sub-ms.
+let _lastMirrorHash = null;
+
+const crypto = require('crypto');
+
+function _fileContentHash(filePath) {
+  try {
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha1').update(buf).digest('hex');
+  }
+  catch { return null; }
+}
+
+function _hydrateFromJson(db) {
+  const items = _readJsonArrayFallback();
+  db.prepare('DELETE FROM watches').run();
+  if (items.length === 0) return;
+  const now = Date.now();
+  const ins = db.prepare(`
+    INSERT INTO watches (id, target, target_type, condition, status, owner, created_at, last_checked, last_triggered, data, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO NOTHING
+  `);
+  for (const w of items) {
+    if (!w || !w.id) continue;
+    ins.run(
+      String(w.id),
+      typeof w.target === 'string' ? w.target : (w.target == null ? null : JSON.stringify(w.target)),
+      w.targetType || null,
+      w.condition || null,
+      String(w.status || 'active'),
+      w.owner || null,
+      _toMs(w.created_at),
+      _toMs(w.last_checked),
+      _toMs(w.last_triggered),
+      JSON.stringify(w),
+      now,
+    );
+  }
+}
+
+function _resyncIfJsonDiverged(db) {
+  const jsonPath = _watchesFilePath();
+  const currentHash = _fileContentHash(jsonPath);
+  if (currentHash == null) return;
+  if (_lastMirrorHash != null && currentHash === _lastMirrorHash) return;
+  if (_lastMirrorHash == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM watches LIMIT 1').get();
+    if (sqlHas) {
+      _lastMirrorHash = currentHash;
+      return;
+    }
+  }
+  _hydrateFromJson(db);
+  _lastMirrorHash = currentHash;
+}
+
+// Read all watch rows from SQL only. No JSON fallback — used by the
+// mirror writer to avoid resurrecting deleted rows: after the mutation
+// deletes a watch from SQL but BEFORE the mirror lands, the JSON still
+// holds the pre-mutation content, so a fallback read would round-trip
+// the deleted row right back into JSON.
+function _readWatchesFromSqlOnly(db) {
+  const rows = db.prepare('SELECT data FROM watches ORDER BY rowid').all();
+  const out = [];
+  for (const row of rows) {
+    const w = _parseRow(row);
+    if (w) out.push(w);
+  }
+  return out;
+}
+
+function readWatches() {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return _readJsonArrayFallback(); }
+
+  _resyncIfJsonDiverged(db);
+
+  const out = _readWatchesFromSqlOnly(db);
+  if (out.length === 0) {
+    // SQL is empty for first-time hydrate: trust the JSON if it has
+    // content. After hydrate ran, SQL is empty iff the user really has
+    // no watches.
+    const fallback = _readJsonArrayFallback();
+    if (fallback.length > 0) return fallback;
+    return [];
+  }
+  return out;
+}
+
+function _indexById(arr) {
+  const out = new Map();
+  for (const w of arr) {
+    if (!w || !w.id) continue;
+    out.set(String(w.id), w);
+  }
+  return out;
+}
+
+function _computeWatchesDiff(before, after) {
+  const beforeMap = _indexById(before);
+  const afterMap = _indexById(after);
+  const toUpsert = [];
+  const toDelete = [];
+  for (const [id, w] of afterMap) {
+    const prev = beforeMap.get(id);
+    if (!prev) { toUpsert.push(w); continue; }
+    if (JSON.stringify(prev) !== JSON.stringify(w)) toUpsert.push(w);
+  }
+  for (const [id] of beforeMap) {
+    if (!afterMap.has(id)) toDelete.push(id);
+  }
+  return { toUpsert, toDelete };
+}
+
+function _applyWatchesDiff(db, diff) {
+  if (diff.toUpsert.length === 0 && diff.toDelete.length === 0) return false;
+  const now = Date.now();
+  const upsertStmt = db.prepare(`
+    INSERT INTO watches (id, target, target_type, condition, status, owner, created_at, last_checked, last_triggered, data, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      target         = excluded.target,
+      target_type    = excluded.target_type,
+      condition      = excluded.condition,
+      status         = excluded.status,
+      owner          = excluded.owner,
+      created_at     = excluded.created_at,
+      last_checked   = excluded.last_checked,
+      last_triggered = excluded.last_triggered,
+      data           = excluded.data,
+      updated_at     = excluded.updated_at
+  `);
+  const deleteStmt = db.prepare('DELETE FROM watches WHERE id = ?');
+
+  for (const w of diff.toUpsert) {
+    upsertStmt.run(
+      String(w.id),
+      typeof w.target === 'string' ? w.target : (w.target == null ? null : JSON.stringify(w.target)),
+      w.targetType || null,
+      w.condition || null,
+      String(w.status || 'active'),
+      w.owner || null,
+      _toMs(w.created_at),
+      _toMs(w.last_checked),
+      _toMs(w.last_triggered),
+      JSON.stringify(w),
+      now,
+    );
+  }
+  for (const id of diff.toDelete) {
+    deleteStmt.run(id);
+  }
+  return true;
+}
+
+function applyWatchesMutation(mutator) {
+  const { getDb, withTransaction } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch (e) {
+    throw new Error(`engine/watches-store: SQLite unavailable (${e.message}); cannot mutate watches`);
+  }
+
+  return withTransaction(db, () => {
+    _resyncIfJsonDiverged(db);
+    const before = readWatches();
+    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 = _computeWatchesDiff(beforeSnapshot, after);
+    const wrote = _applyWatchesDiff(db, diff);
+    return { wrote, result: after };
+  });
+}
+
+function _mirrorJsonFromSql(filePath) {
+  try {
+    const shared = require('./shared');
+    const { getDb } = require('./db');
+    // Read SQL directly — bypass the JSON fallback so a deletion that
+    // leaves SQL empty doesn't resurrect from the stale JSON content.
+    const items = _readWatchesFromSqlOnly(getDb());
+    const target = filePath || _watchesFilePath();
+    shared.safeWrite(target, items);
+    const h = _fileContentHash(target);
+    if (h != null) _lastMirrorHash = h;
+  } catch {
+    // Mirror failures are non-fatal — SQL has already committed.
+  }
+}
+
+function _resetWatchesTableForTest() {
+  const { getDb } = require('./db');
+  try { getDb().exec('DELETE FROM watches'); } catch { /* not initialized */ }
+  _lastMirrorHash = null;
+}
+
+module.exports = {
+  readWatches,
+  applyWatchesMutation,
+  _mirrorJsonFromSql,
+  _resetWatchesTableForTest,
+};

package/engine/watches.js

@@ -67,7 +67,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeJsonArr, mutateJsonFileLocked, ts, uid, log, writeToInbox,
+const { safeJsonArr, mutateJsonFileLocked, mutateWatches, ts, uid, log, writeToInbox,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS } = shared;
 const watchActions = require('./watch-actions');
 
@@ -230,11 +230,10 @@ function createWatch({ target, targetType, condition, interval, owner, descripti
     _history: [],
   };
 
-  mutateJsonFileLocked(_watchesPath(), (watches) => {
-    if (!Array.isArray(watches)) watches = [];
+  mutateWatches((watches) => {
     watches.push(watch);
     return watches;
-  }, { defaultValue: [] });
+  });
 
   log('info', `Watch created: ${watch.id} → ${watch.target} (${watch.condition})`);
   return watch;
@@ -264,8 +263,7 @@ function updateWatch(id, updates) {
     if (reqErr) throw new Error(reqErr);
   }
   let found = null;
-  mutateJsonFileLocked(_watchesPath(), (watches) => {
-    if (!Array.isArray(watches)) return watches;
+  mutateWatches((watches) => {
     const watch = watches.find(w => w.id === id);
     if (!watch) return watches;
     // Only allow safe field updates
@@ -275,7 +273,7 @@ function updateWatch(id, updates) {
     }
     found = { ...watch };
     return watches;
-  }, { defaultValue: [] });
+  });
   return found;
 }
 
@@ -287,15 +285,14 @@ function updateWatch(id, updates) {
 function deleteWatch(id) {
   if (!id) return false;
   let deleted = false;
-  mutateJsonFileLocked(_watchesPath(), (watches) => {
-    if (!Array.isArray(watches)) return watches;
+  mutateWatches((watches) => {
     const idx = watches.findIndex(w => w.id === id);
     if (idx >= 0) {
       watches.splice(idx, 1);
       deleted = true;
     }
     return watches;
-  }, { defaultValue: [] });
+  });
   if (deleted) log('info', `Watch deleted: ${id}`);
   return deleted;
 }
@@ -413,8 +410,8 @@ function checkWatches(config, state) {
   const notifications = [];
   const actionsToRun = [];
 
-  mutateJsonFileLocked(_watchesPath(), (watches) => {
-    if (!Array.isArray(watches) || watches.length === 0) return watches;
+  mutateWatches((watches) => {
+    if (watches.length === 0) return watches;
 
     for (const watch of watches) {
       try {
@@ -539,7 +536,7 @@ function checkWatches(config, state) {
     }
 
     return watches;
-  }, { defaultValue: [] });
+  });
 
   // Fire notifications outside the lock — writeToInbox does disk I/O
   for (const n of notifications) {
@@ -591,8 +588,7 @@ async function _runActionTask(task) {
   // can inspect each step's result. Single-action watches keep the legacy
   // `dispatchedItemId` shortcut for back-compat.
   try {
-    mutateJsonFileLocked(_watchesPath(), (watches) => {
-      if (!Array.isArray(watches)) return watches;
+    mutateWatches((watches) => {
       const w = watches.find(x => x.id === task.watchId);
       if (w) {
         if (isChain) {
@@ -639,7 +635,7 @@ async function _runActionTask(task) {
         }
       }
       return watches;
-    }, { defaultValue: [] });
+    });
   } catch (err) {
     log('warn', `Watch ${task.watchId} action result persist failed: ${err.message}`);
   }

package/engine/work-items-store.js

@@ -116,28 +116,19 @@ function readWorkItemsForScope(scope) {
 // scope is bounded by the JSON's row count.
 function _resyncScopeIfJsonDiverged(db, scope) {
   const jsonPath = _filePathForScope(scope);
-  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 (lastMirror == null) {
+  const currentHash = _fileContentHash(jsonPath);
+  const lastHash = _lastMirrorHashByScope.get(scope);
+  if (currentHash == null) return;
+  if (lastHash != null && currentHash === lastHash) return;
+  if (lastHash == null) {
     const sqlHas = db.prepare('SELECT 1 FROM work_items WHERE scope = ? LIMIT 1').get(scope);
     if (sqlHas) {
-      _lastMirrorByScope.set(scope, current);
+      _lastMirrorHashByScope.set(scope, currentHash);
       return;
     }
   }
   _hydrateScopeFromJson(db, scope);
-  _lastMirrorByScope.set(scope, current);
+  _lastMirrorHashByScope.set(scope, currentHash);
 }
 
 // Read all rows across all scopes — used by queries.getWorkItems which
@@ -243,18 +234,18 @@ 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 (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();
+// Content-hash fingerprint of the JSON mirror per scope, so external
+// edits are detected unambiguously. (mtime, size) is too coarse: same-
+// length timestamp swaps (last_checked / last_triggered / completed_at)
+// preserve both axes. SHA-1 is sub-ms on a few-hundred-KB file.
+const _lastMirrorHashByScope = new Map();
 
-function _statFingerprint(filePath) {
+const crypto = require('crypto');
+
+function _fileContentHash(filePath) {
   try {
-    const st = fs.statSync(filePath);
-    return { mtime: st.mtimeMs, size: st.size };
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha1').update(buf).digest('hex');
   }
   catch { return null; }
 }
@@ -325,17 +316,24 @@ function applyWorkItemsMutation(scope, mutator) {
 function _mirrorJsonFromSql(scope, filePath) {
   try {
     const shared = require('./shared');
-    const items = readWorkItemsForScope(scope);
-    // Strip _source if present — only added by readAllWorkItems, but
-    // belt-and-suspenders since the mirror is observable.
-    for (const wi of items) { if (wi && wi._source) delete wi._source; }
+    const { getDb } = require('./db');
+    // Read SQL directly for this scope — bypass the JSON fallback so a
+    // mutation that empties SQL for the scope doesn't resurrect stale
+    // JSON content. (See pull-requests-store and watches-store for the
+    // same defense.)
+    const db = getDb();
+    const rows = db.prepare('SELECT data FROM work_items WHERE scope = ? ORDER BY rowid').all(scope);
+    const items = [];
+    for (const row of rows) {
+      const wi = _parseRow(row);
+      if (!wi) continue;
+      if (wi._source) delete wi._source;
+      items.push(wi);
+    }
     const target = filePath || _filePathForScope(scope);
     shared.safeWrite(target, items);
-    // 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);
+    const h = _fileContentHash(target);
+    if (h != null) _lastMirrorHashByScope.set(scope, h);
   } catch {
     // Mirror failures are non-fatal: SQL has already committed.
   }

package/package.json

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