@yemi33/minions 0.1.2111 → 0.1.2112

package/engine/dispatch.js

@@ -90,11 +90,10 @@ function mutateDispatch(mutator) {
     if (wrote) {
       try { require('./queries').invalidateDispatchCache(); } catch {}
       try { require('./db-events').emitStateEvent('dispatch'); } catch { /* optional */ }
-      // Phase 1 dual-write: mirror the canonical SQL state to dispatch.json
-      // so legacy direct-readers (engine/queries.js fallback, engine/routing.js,
-      // test infrastructure that fs.readFileSync's the file) stay in sync.
-      // SQL is source of truth; the JSON file is regenerated from SQL on
-      // every successful mutation, never independently mutated.
+      // Mirror back to dispatch.json for tests + tools that fs.readFileSync
+      // the file directly. SQL is the source of truth; the JSON file is
+      // regenerated from SQL on every successful mutation, never independently
+      // mutated. Cheap to delete once those direct-JSON readers are gone.
       try { store._mirrorJsonFromSql(); } catch { /* best-effort */ }
     }
     return result;

package/engine/projects.js

@@ -420,6 +420,11 @@ function removeProject(target, options = {}) {
     }
   }
 
+  // 9. Drop SQL rows for the project's scope so safeJson shim reads no longer
+  //    surface the removed project after the JSON file is archived.
+  try { require('./work-items-store').dropScope(project.name); } catch { /* best-effort */ }
+  try { require('./pull-requests-store').dropScope(project.name); } catch { /* best-effort */ }
+
   summary.ok = true;
   return summary;
 }

package/engine/pull-requests-store.js

@@ -293,11 +293,20 @@ function _resetPullRequestsTableForTest() {
   try { getDb().exec('DELETE FROM pull_requests'); } catch { /* not initialized */ }
 }
 
+function dropScope(scope) {
+  try {
+    const { getDb } = require('./db');
+    getDb().prepare('DELETE FROM pull_requests WHERE scope = ?').run(scope);
+    _lastMirrorHashByScope.delete(scope);
+  } catch { /* db unavailable */ }
+}
+
 module.exports = {
   scopeForFilePath,
   readPullRequestsForScope,
   readAllPullRequests,
   applyPullRequestsMutation,
+  dropScope,
   _filePathForScope,
   _mirrorJsonFromSql,
   _resetPullRequestsTableForTest,

package/engine/queries.js

@@ -181,17 +181,9 @@ function getDispatch() {
   // to be when dispatch.json could be 1+ MB.
   const now = Date.now();
   if (_dispatchCache && (now - _dispatchCacheAt) < 2000) return _dispatchCache;
-  // Try SQL first (post-Phase 1). If the table doesn't exist (greenfield
-  // install, Node < 22.5, or DB init failed) fall back to the legacy JSON
-  // reader. The migration leaves dispatch.json.pre-sql-<ts> on disk so
-  // operators rolling back to a pre-migration release can rename it back.
-  try {
-    const store = require('./dispatch-store');
-    const sectioned = store.readDispatchSectioned();
-    _dispatchCache = sectioned;
-  } catch {
-    _dispatchCache = readJsonNoRestore(DISPATCH_PATH) || { pending: [], active: [], completed: [] };
-  }
+  // SQL is the canonical (and only) dispatch store after Phase 9.
+  const store = require('./dispatch-store');
+  _dispatchCache = store.readDispatchSectioned();
   _dispatchCacheAt = now;
   return _dispatchCache;
 }
@@ -361,37 +353,15 @@ function getNotesWithMeta() {
 }
 
 function getEngineLog() {
-  // 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 {
-    const entries = JSON.parse(logJson);
-    const arr = Array.isArray(entries) ? entries : (entries.entries || []);
-    return arr.slice(-50);
-  } catch { return []; }
+  // SQL is the canonical (and only) log store after Phase 9.
+  const store = require('./logs-store');
+  return store.readRecentLogsChronological(50) || [];
 }
 
 function getMetrics() {
-  // 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')) || {};
-  }
+  // SQL is the canonical (and only) metrics store after Phase 9.
+  const store = require('./metrics-store');
+  const metrics = store.readMetrics() || {};
 
   for (const [agentId, m] of Object.entries(metrics)) {
     if (agentId.startsWith('_')) continue;
@@ -704,82 +674,33 @@ function getPullRequests(config) {
   const allPrs = [];
   const seenIds = new Set();
 
-  // 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 {
-    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;
-      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';
-      }
-      // Issue #2969 — surface paused PR-fix causes on the enriched record so
-      // dashboards / API consumers can render a chip without re-parsing
-      // _noOpFixes themselves.
-      pr._pausedCauses = shared.getPrPausedCauses(pr);
-      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);
+  // SQL is the canonical (and only) PR store after Phase 9.
+  const store = require('./pull-requests-store');
+  const sqlPrs = store.readAllPullRequests() || [];
+
+  for (const pr of sqlPrs) {
+    if (!pr?.id || seenIds.has(pr.id)) continue;
+    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 || '';
-      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';
-        // Issue #2969 — surface paused PR-fix causes (see SQL path above).
-        pr._pausedCauses = shared.getPrPausedCauses(pr);
-        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';
-        // Issue #2969 — surface paused PR-fix causes (see SQL path above).
-        pr._pausedCauses = shared.getPrPausedCauses(pr);
-        allPrs.push(pr);
-        seenIds.add(pr.id);
+      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';
     }
+    // Issue #2969 — surface paused PR-fix causes on the enriched record so
+    // dashboards / API consumers can render a chip without re-parsing
+    // _noOpFixes themselves.
+    pr._pausedCauses = shared.getPrPausedCauses(pr);
+    allPrs.push(pr);
+    seenIds.add(pr.id);
   }
   allPrs.sort((a, b) => {
     // W-mpej044m00076d63: sort by the full ISO `created` timestamp DESC so
@@ -1352,43 +1273,9 @@ function getWorkItems(config) {
   const projects = getProjects(config);
   let allItems = [];
 
-  // Phase 2: prefer the SQL store. Returns every scope's items tagged
-  // with `_source = <scope>`, matching the legacy decoration. Empty SQL
-  // table OR a SQLite failure falls through to the JSON path below so a
-  // fresh install + a node:sqlite-broken environment both keep working.
-  try {
-    const store = require('./work-items-store');
-    const sqlItems = store.readAllWorkItems();
-    if (Array.isArray(sqlItems) && sqlItems.length > 0) {
-      allItems = sqlItems;
-    }
-  } catch { /* fall through to JSON */ }
-
-  if (allItems.length === 0) {
-    // Central work items
-    const centralData = safeRead(path.join(MINIONS_DIR, 'work-items.json'));
-    if (centralData) {
-      try {
-        for (const item of JSON.parse(centralData)) {
-          item._source = 'central';
-          allItems.push(item);
-        }
-      } catch {}
-    }
-
-    // Per-project work items
-    for (const project of projects) {
-      const data = safeRead(projectWorkItemsPath(project));
-      if (data) {
-        try {
-          for (const item of JSON.parse(data)) {
-            item._source = project.name || 'project';
-            allItems.push(item);
-          }
-        } catch {}
-      }
-    }
-  }
+  // SQL is the canonical (and only) work-items store after Phase 9.
+  const store = require('./work-items-store');
+  allItems = store.readAllWorkItems() || [];
 
   // Cross-reference with dispatch (fill in agent from active dispatch if missing on work item)
   const dispatch = getDispatch();

package/engine/shared.js

@@ -467,6 +467,107 @@ function safeReadDir(dir) {
   try { return fs.readdirSync(dir); } catch { return []; }
 }
 
+// ── SQL-routing shim for migrated state files ──────────────────────────────
+//
+// Phase 9 (post-Phase 8 cleanup): every state file that has a SQL backing
+// (dispatches, work-items, pull-requests, metrics, watches, schedule-runs,
+// pipeline-runs, managed-processes, worktree-pool, qa-runs, qa-sessions)
+// becomes SQL-only at the read API surface. The JSON sidecar files stop
+// being mirror-written; this shim makes existing `safeJson*` callers
+// transparently read from SQL so we don't have to convert ~40 call sites
+// in engine.js / dashboard.js / cleanup.js / etc.
+//
+// Matching is by path suffix rather than full-prefix against MINIONS_DIR,
+// because tests using MINIONS_TEST_DIR re-resolve the dir but use the same
+// suffix pattern. Returns `{value}` on hit, `null` on miss; callers fall
+// through to the legacy disk read.
+//
+// Per-project work-items / pull-requests need scope extraction from the
+// path. `<MINIONS_DIR>/projects/<name>/work-items.json` → scope `<name>`;
+// `<MINIONS_DIR>/work-items.json` → scope `central`.
+function _routeJsonReadToSql(p) {
+  if (!p || typeof p !== 'string') return null;
+  const norm = p.replace(/\\/g, '/');
+  // Only route reads from paths inside MINIONS_DIR. Tests that use
+  // createTmpDir() write to ad-hoc temp paths that shouldn't be hijacked
+  // by the SQL stores (the path-suffix patterns below would otherwise
+  // match e.g. `<tmp>/pull-requests.json` and return empty SQL data).
+  const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
+  if (!norm.startsWith(minionsNorm + '/') && norm !== minionsNorm) return null;
+  let m;
+  try {
+    if (norm.endsWith('/engine/dispatch.json')) {
+      const store = require('./dispatch-store');
+      return { value: store.readDispatchSectioned() };
+    }
+    if (norm.endsWith('/engine/metrics.json')) {
+      const store = require('./metrics-store');
+      return { value: store.readMetrics() };
+    }
+    if (norm.endsWith('/engine/watches.json')) {
+      const store = require('./watches-store');
+      return { value: store.readWatches() };
+    }
+    if (norm.endsWith('/engine/schedule-runs.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readScheduleRuns() };
+    }
+    if (norm.endsWith('/engine/pipeline-runs.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readPipelineRuns() };
+    }
+    if (norm.endsWith('/engine/managed-processes.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readManagedProcesses() };
+    }
+    if (norm.endsWith('/engine/worktree-pool.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readWorktreePool() };
+    }
+    if (norm.endsWith('/engine/qa-runs.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readQaRuns() };
+    }
+    if (norm.endsWith('/engine/qa-sessions.json')) {
+      const store = require('./small-state-store');
+      return { value: store.readQaSessions() };
+    }
+    // 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
+    // the resurrection-bug regression (engine-helper-coverage.test.js):
+    // safeJson(path-to-removed-project) must return null, not `[]`.
+    if ((m = norm.match(/\/projects\/([^/]+)\/work-items\.json$/))) {
+      const store = require('./work-items-store');
+      const v = store.readWorkItemsForScope(m[1]);
+      if ((!Array.isArray(v) || v.length === 0) && !fs.existsSync(p)) return null;
+      return { value: v };
+    }
+    // Per-project pull-requests.json
+    if ((m = norm.match(/\/projects\/([^/]+)\/pull-requests\.json$/))) {
+      const store = require('./pull-requests-store');
+      const v = store.readPullRequestsForScope(m[1]);
+      if ((!Array.isArray(v) || v.length === 0) && !fs.existsSync(p)) return null;
+      return { value: v };
+    }
+    // Central work-items.json — `<MINIONS_DIR>/work-items.json`. Must not
+    // collide with `/projects/<name>/work-items.json` (handled above).
+    if (/(^|\/)work-items\.json$/.test(norm) && !/\/projects\//.test(norm)) {
+      const store = require('./work-items-store');
+      return { value: store.readWorkItemsForScope('central') };
+    }
+    // Central pull-requests.json
+    if (/(^|\/)pull-requests\.json$/.test(norm) && !/\/projects\//.test(norm)) {
+      const store = require('./pull-requests-store');
+      return { value: store.readPullRequestsForScope('central') };
+    }
+  } catch {
+    // SQLite unavailable / store load failure — fall through to disk read.
+    return null;
+  }
+  return null;
+}
+
 /**
  * Read a JSON file with **automatic restore from `.backup` sidecar** on
  * missing/corrupt primary. Intended for live, mutable state files
@@ -479,11 +580,26 @@ function safeReadDir(dir) {
  * to the primary path (best-effort). This protects live state from torn
  * writes / interrupted saves.
  *
+ * **SQL routing (Phase 9):** when the path matches a migrated state file
+ * (work-items, pull-requests, dispatch, metrics, watches, schedule-runs,
+ * pipeline-runs, managed-processes, worktree-pool, qa-runs, qa-sessions),
+ * the read is served from SQLite via `_routeJsonReadToSql` — the JSON file
+ * on disk is no longer authoritative.
+ *
  * Counterpart: `safeJsonNoRestore` for terminal artifacts and "missing == gone"
  * reads (cooldowns, archived PRDs, ephemeral session state) where reviving a
  * stale `.backup` is actively harmful. See its JSDoc for selection guidance.
  */
 function safeJson(p) {
+  // Internal opt-out (positional second arg from mutateJsonFileLocked):
+  // when truthy, skip the SQL-routing shim and do a raw disk read. Used
+  // when the caller already holds the file lock and needs the on-disk
+  // bytes as the source of truth (so the read+write pair is atomic).
+  const skipSqlRouting = arguments.length > 1 && arguments[1] && arguments[1].skipSqlRouting;
+  if (!skipSqlRouting) {
+    const routed = _routeJsonReadToSql(p);
+    if (routed) return routed.value;
+  }
   // Split the read from the parse so we can distinguish "file missing" (normal
   // pre-create state — silent) from "file present but corrupt JSON" (real
   // integrity failure — must log). Without this split a `JSON.parse(read)` in
@@ -1203,19 +1319,68 @@ function withFileLock(lockPath, fn, {
   throw lastErr;
 }
 
+function _tryRouteMutateToSql(filePath, mutateFn, onWrote) {
+  const baseName = path.basename(filePath);
+  if (baseName !== 'work-items.json' && baseName !== 'pull-requests.json') 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;
+  let result;
+  if (baseName === 'work-items.json') {
+    result = mutateWorkItems(filePath, (arr) => {
+      const out = mutateFn(arr);
+      if (onWrote) onWrote();
+      return out;
+    });
+  } else {
+    // pull-requests.json: preserve legacy-ID normalization the JSON path
+    // applied before invoking the mutator (parity with mutateJsonFileLocked
+    // body at the pull-requests.json normalization site).
+    const project = resolveProjectForPrPath(filePath);
+    result = mutatePullRequests(filePath, (arr) => {
+      if (Array.isArray(arr)) normalizePrRecords(arr, project);
+      const out = mutateFn(arr);
+      if (onWrote) onWrote();
+      return out;
+    });
+  }
+  // SQL-store mirror is gated on `wrote`; an empty-no-op mutator leaves the
+  // JSON file uncreated. The JSON path always wrote (including for empty
+  // arrays via ensureProjectStateFiles), so guarantee a JSON file exists.
+  if (!fs.existsSync(filePath)) {
+    try {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      safeWrite(filePath, Array.isArray(result) ? result : []);
+    } catch { /* best-effort */ }
+  }
+  return { routed: result };
+}
+
 function mutateJsonFileLocked(filePath, mutateFn, {
   defaultValue = {},
   lockRetries,
   lockRetryBackoffMs,
   skipWriteIfUnchanged = false,
   onWrote = null,
+  _skipSqlRouting = false,
 } = {}) {
   const lockPath = `${filePath}.lock`;
   const retries = lockRetries ?? ENGINE_DEFAULTS.lockRetries;
   const retryBackoffMs = lockRetryBackoffMs ?? ENGINE_DEFAULTS.lockRetryBackoffMs;
+  // Phase 9 SQL-routing: when targeting work-items.json or pull-requests.json
+  // under MINIONS_DIR, delegate to the SQL-store wrappers so SQL stays
+  // canonical. Without this, JSON-only edits leak past the SQL mirror and
+  // divergence-detection short-circuits leave SQL readers stale.
+  // `_skipSqlRouting: true` is the internal opt-out used by the SQL store's
+  // own SQLite-failure fallback to avoid recursion.
+  if (!_skipSqlRouting) {
+    const routed = _tryRouteMutateToSql(filePath, mutateFn, onWrote);
+    if (routed) return routed.routed;
+  }
   return withFileLock(lockPath, () => {
     const fileExists = fs.existsSync(filePath);
-    let data = safeJson(filePath);
+    let data = safeJson(filePath, { skipSqlRouting: true });
     const parsedInvalid = fileExists && data === null;
     if (data === null || typeof data !== 'object') data = Array.isArray(defaultValue) ? [...defaultValue] : { ...defaultValue };
     // Normalize BEFORE taking the baseline snapshot so that both `beforeSerialized`
@@ -2935,7 +3100,7 @@ function _smallStateMutator({ filePath, applyMutation, mirror, topic, defaultVal
       const store = require('./small-state-store');
       const { wrote, result } = store[applyMutation]((obj) => mutator(obj) || obj);
       if (wrote) {
-        try { store[mirror](filePath); } catch { /* mirror best-effort */ }
+        try { if (mirror && typeof store[mirror] === 'function') store[mirror](filePath); } catch { /* mirror best-effort */ }
         try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
       }
       return result;
@@ -3005,14 +3170,6 @@ function _qaDualWriteEnabled() {
 
 function _qaMutator({ filePath, applyMutation, mirror, topic }) {
   return (mutator) => {
-    // Cross-process serialization: SQLite's BEGIN IMMEDIATE already
-    // serializes the table write across processes, but the JSON sidecar
-    // mirror is best-effort and can race — two concurrent processes can
-    // each snapshot SQL and write the JSON, and an older snapshot can
-    // overwrite a newer one. Wrap SQL apply + mirror in a single file
-    // lock on the JSON path's .lock file so multi-process writers
-    // serialize through the mirror, matching the legacy fully-locked
-    // semantics that test/unit/qa-runs.test.js asserts.
     return withFileLock(filePath + '.lock', () => {
       try {
         const store = require('./small-state-store');
@@ -3022,7 +3179,7 @@ function _qaMutator({ filePath, applyMutation, mirror, topic }) {
         });
         if (wrote) {
           if (_qaDualWriteEnabled()) {
-            try { store[mirror](filePath); } catch { /* mirror best-effort */ }
+            try { if (mirror && typeof store[mirror] === 'function') store[mirror](filePath); } catch { /* mirror best-effort */ }
           }
           try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
         }
@@ -3081,7 +3238,6 @@ function mutateWatches(mutator) {
     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 = [];
@@ -3120,7 +3276,6 @@ function mutateMetrics(mutator) {
     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 = {};
@@ -5292,8 +5447,9 @@ function listProcessReachable(rootPids, allProcesses = null) {
  * @param {Function} mutator - Receives the array, mutates in place or returns new value
  */
 function mutateWorkItems(filePath, mutator) {
-  // Phase 2 SQL path. Route through work-items-store so SQL is the source
-  // of truth; mirror back to the JSON file for legacy direct-readers.
+  // Phase 2 SQL path → Phase 9 SQL-only. Route through work-items-store so
+  // SQL is the canonical (and only) store; the legacy JSON mirror was
+  // retired in Phase 9.
   //
   // The SQL store identifies records by `scope` (central or project name)
   // derived from the file path's last two segments. Ad-hoc file paths
@@ -5316,7 +5472,7 @@ function mutateWorkItems(filePath, mutator) {
         return mutator(items) || items;
       });
       if (wrote) {
-        try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror is best-effort */ }
+        try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror best-effort */ }
         try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
       }
       try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
@@ -5335,6 +5491,7 @@ function mutateWorkItems(filePath, mutator) {
   }, {
     defaultValue: [],
     skipWriteIfUnchanged: true,
+    _skipSqlRouting: true,
     onWrote: () => {
       try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
     },
@@ -5363,11 +5520,9 @@ 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.
+  // Phase 3 SQL path → Phase 9 SQL-only. Route through pull-requests-store
+  // when filePath sits under MINIONS_DIR. Ad-hoc tmp paths (legacy tests
+  // using createTmpDir) and SQLite failures fall through to the JSON path.
   const fpNorm = String(filePath).replace(/\\/g, '/');
   const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
   const insideMinionsDir = fpNorm.startsWith(minionsNorm + '/') || fpNorm === minionsNorm + '/pull-requests.json';
@@ -5380,7 +5535,7 @@ function mutatePullRequests(filePath, mutator) {
         return mutator(prs) || prs;
       });
       if (wrote) {
-        try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror is best-effort */ }
+        try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror best-effort */ }
         try { require('./db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
       }
       return result;
@@ -5398,9 +5553,7 @@ function mutatePullRequests(filePath, mutator) {
   }, {
     defaultValue: [],
     skipWriteIfUnchanged: true,
-    // Emit only when an actual write happened. skipWriteIfUnchanged can
-    // short-circuit no-op mutations; suppress the event in that case so the
-    // dashboard cache-version doesn't bump for nothing.
+    _skipSqlRouting: true,
     onWrote: () => {
       try { require('./db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
     },

package/engine/work-items-store.js

@@ -127,6 +127,13 @@ function _resyncScopeIfJsonDiverged(db, scope) {
       return;
     }
   }
+  if (lastHash == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM work_items WHERE scope = ? LIMIT 1').get(scope);
+    if (sqlHas) {
+      _lastMirrorHashByScope.set(scope, currentHash);
+      return;
+    }
+  }
   _hydrateScopeFromJson(db, scope);
   _lastMirrorHashByScope.set(scope, currentHash);
 }
@@ -345,11 +352,23 @@ function _resetWorkItemsTableForTest() {
   try { getDb().exec('DELETE FROM work_items'); } catch { /* not initialized */ }
 }
 
+// Drop every SQL row for `scope` and forget its mirror-hash. Called by
+// removeProject after the JSON file is archived so safeJson shim reads no
+// longer surface the removed project's records.
+function dropScope(scope) {
+  try {
+    const { getDb } = require('./db');
+    getDb().prepare('DELETE FROM work_items WHERE scope = ?').run(scope);
+    _lastMirrorHashByScope.delete(scope);
+  } catch { /* db unavailable */ }
+}
+
 module.exports = {
   scopeForFilePath,
   readWorkItemsForScope,
   readAllWorkItems,
   applyWorkItemsMutation,
+  dropScope,
   _filePathForScope,
   _mirrorJsonFromSql,
   _resetWorkItemsTableForTest,

package/package.json

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