@yemi33/minions 0.1.2379 → 0.1.2381

package/engine/db/migrations/021-archived-work-items.js

@@ -0,0 +1,72 @@
+const path = require('path');
+const fs = require('fs');
+
+function _resolveMinionsDir() {
+  const envHome = process.env.MINIONS_TEST_DIR || process.env.MINIONS_HOME;
+  if (envHome) return envHome;
+  try { return require('../../shared').MINIONS_DIR; } catch { return null; }
+}
+
+function _toMs(value) {
+  if (value == null) return null;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function _readArray(filePath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return Array.isArray(value) ? value : [];
+  } catch {
+    return [];
+  }
+}
+
+module.exports = {
+  version: 21,
+  description: 'store archived work items in SQLite',
+  up(db) {
+    db.exec(`
+      ALTER TABLE work_items ADD COLUMN archived INTEGER NOT NULL DEFAULT 0;
+      CREATE INDEX idx_wi_scope_archived ON work_items(scope, archived);
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    const insert = db.prepare(`
+      INSERT OR IGNORE INTO work_items
+        (id, scope, status, type, agent, parent_id, created_at, completed_at, data, updated_at, archived)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)
+    `);
+    const now = Date.now();
+    const importFile = (scope, filePath) => {
+      for (const raw of _readArray(filePath)) {
+        if (!raw || typeof raw !== 'object' || !raw.id) continue;
+        const item = { ...raw, _archived: true };
+        item.archivedAt = item.archivedAt || new Date(now).toISOString();
+        insert.run(
+          String(item.id),
+          scope,
+          String(item.status || 'done'),
+          item.type || null,
+          item.dispatched_to || item.agent || null,
+          item.parent_id || null,
+          _toMs(item.created_at || item.created),
+          _toMs(item.completed_at || item.completedAt),
+          JSON.stringify(item),
+          now,
+        );
+      }
+    };
+
+    importFile('central', path.join(minionsDir, 'work-items-archive.json'));
+    let projects = [];
+    try { projects = fs.readdirSync(path.join(minionsDir, 'projects'), { withFileTypes: true }); }
+    catch { /* optional */ }
+    for (const project of projects) {
+      if (!project.isDirectory() || project.name === '.archived') continue;
+      importFile(project.name, path.join(minionsDir, 'projects', project.name, 'work-items-archive.json'));
+    }
+  },
+};

package/engine/db/migrations/022-global-cc-session.js

@@ -0,0 +1,31 @@
+const fs = require('fs');
+const path = require('path');
+
+const CC_GLOBAL_SESSION_ID = '__global__';
+
+function _resolveMinionsDir() {
+  const envHome = process.env.MINIONS_TEST_DIR || process.env.MINIONS_HOME;
+  if (envHome) return envHome;
+  try { return require('../../shared').MINIONS_DIR; } catch { return null; }
+}
+
+module.exports = {
+  version: 22,
+  description: 'global Command Center session',
+  up(db) {
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    const legacyPath = path.join(minionsDir, 'engine', 'cc-session.json');
+    let session;
+    try {
+      session = JSON.parse(fs.readFileSync(legacyPath, 'utf8'));
+    } catch {
+      return;
+    }
+    if (!session || typeof session !== 'object' || Array.isArray(session) || !session.sessionId) return;
+    db.prepare(`
+      INSERT OR IGNORE INTO cc_sessions (id, data, updated_at)
+      VALUES (?, ?, ?)
+    `).run(CC_GLOBAL_SESSION_ID, JSON.stringify(session), Date.now());
+  },
+};

package/engine/db/migrations/023-engine-state.js

@@ -0,0 +1,30 @@
+const fs = require('fs');
+const path = require('path');
+
+const ENGINE_STATE_MARKER = 'engine_state';
+
+function _resolveMinionsDir() {
+  const envHome = process.env.MINIONS_TEST_DIR || process.env.MINIONS_HOME;
+  if (envHome) return envHome;
+  try { return require('../../shared').MINIONS_DIR; } catch { return null; }
+}
+
+module.exports = {
+  version: 23,
+  description: 'engine state marker',
+  up(db) {
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    let state;
+    try {
+      state = JSON.parse(fs.readFileSync(path.join(minionsDir, 'engine', 'state.json'), 'utf8'));
+    } catch {
+      return;
+    }
+    if (!state || typeof state !== 'object' || Array.isArray(state)) return;
+    db.prepare(`
+      INSERT OR IGNORE INTO state_markers (key, value, updated_at)
+      VALUES (?, ?, ?)
+    `).run(ENGINE_STATE_MARKER, JSON.stringify(state), Date.now());
+  },
+};

package/engine/db/migrations/024-prd-ghost-collisions.js

@@ -0,0 +1,53 @@
+function _parseObject(raw) {
+  try {
+    const value = JSON.parse(raw);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function _isArchivedEcho(live, archived) {
+  if (!live || !archived) return true;
+  const liveSource = live.source_plan || live.sourcePlan;
+  const archivedSource = archived.source_plan || archived.sourcePlan;
+  if (liveSource && archivedSource && liveSource !== archivedSource) return false;
+  const archivedIds = new Set(
+    (archived.missing_features || []).map(feature => feature && feature.id).filter(Boolean),
+  );
+  return !(live.missing_features || []).some(
+    feature => feature && feature.id && !archivedIds.has(feature.id),
+  );
+}
+
+function _deletePrdRow(db, prdId) {
+  db.prepare(`
+    UPDATE work_items SET prd_item_id=NULL
+    WHERE prd_item_id IN (SELECT id FROM prd_items WHERE prd_id=?)
+  `).run(prdId);
+  db.prepare('DELETE FROM prd_items WHERE prd_id=?').run(prdId);
+  db.prepare('DELETE FROM prd_verify_prs WHERE prd_id=?').run(prdId);
+  db.prepare('DELETE FROM prds WHERE id=?').run(prdId);
+}
+
+module.exports = {
+  version: 24,
+  description: 'remove duplicate live PRD echoes of archived imports',
+  up(db) {
+    const rows = db.prepare(`
+      SELECT id, filename, archived, data
+      FROM prds
+      WHERE filename IN (SELECT filename FROM prds GROUP BY filename HAVING COUNT(DISTINCT archived) > 1)
+      ORDER BY filename, archived, id
+    `).all();
+    const archivedByFilename = new Map();
+    for (const row of rows) {
+      if (row.archived) archivedByFilename.set(row.filename, _parseObject(row.data));
+    }
+    for (const row of rows) {
+      if (row.archived) continue;
+      const archived = archivedByFilename.get(row.filename);
+      if (_isArchivedEcho(_parseObject(row.data), archived)) _deletePrdRow(db, row.id);
+    }
+  },
+};

package/engine/db/migrations/025-malformed-work-item-phantoms.js

@@ -0,0 +1,33 @@
+const { isMalformedPhantomWorkItem } = require('../../work-item-validation');
+
+module.exports = {
+  version: 25,
+  description: 'archive failed contentless work-item phantoms',
+  up(db) {
+    const rows = db.prepare(`
+      SELECT id, scope, data
+      FROM work_items
+      WHERE archived=0 AND status='failed'
+    `).all();
+    const update = db.prepare(`
+      UPDATE work_items
+      SET archived=1, data=?, updated_at=?
+      WHERE scope=? AND id=? AND archived=0
+    `);
+    const reconciledAt = new Date().toISOString();
+    for (const row of rows) {
+      let item;
+      try { item = JSON.parse(row.data); } catch { continue; }
+      if (!isMalformedPhantomWorkItem(item)) continue;
+      const preservedFields = Object.keys(item).sort();
+      item._archived = true;
+      item.archivedAt = item.archivedAt || reconciledAt;
+      item._corruption = {
+        kind: 'malformed-phantom',
+        reconciledAt,
+        preservedFields,
+      };
+      update.run(JSON.stringify(item), Date.now(), row.scope, row.id);
+    }
+  },
+};

package/engine/dispatch-store.js

@@ -1,6 +1,4 @@
-// engine/dispatch-store.js — SQL-backed implementation of the
-// section-shaped dispatch object. Same external contract as the legacy
-// dispatch.json reader:
+// engine/dispatch-store.js — SQL-backed section-shaped dispatch state:
 //
 //   readDispatchSectioned()   -> { pending, active, completed, review }
 //   applyDispatchMutation(fn) -> runs fn against the section object,
@@ -38,8 +36,7 @@ function readDispatchSectioned() {
   const { getDb } = require('./db');
   const db = getDb();
 
-  // All rows, all statuses. Matches the legacy dispatch.json reader's
-  // semantics — returns the complete dispatch state regardless of how old
+  // Return the complete dispatch state regardless of how old
   // completed entries are. Cross-reference consumers like state-integrity
   // need the full completed list to match against work-items, and the
   // dashboard's slim slice handles its own payload sizing downstream.
@@ -200,8 +197,6 @@ function applyDispatchMutation(mutator) {
     }
     const diff = _computeDispatchDiff(beforeSnapshot, after);
     const wrote = _applyDispatchDiff(db, diff);
-    // First-touch guard: record that SQL was written this process so a later
-    // empty read won't resurrect a stale dispatch.json (see readDispatchSectioned).
     return { wrote, result: after };
   });
 }

package/engine/dispatch.js

@@ -24,8 +24,8 @@ const queries = require('./queries');
 const { setCooldown, setCooldownFailure } = require('./cooldown');
 const dispatchEvents = require('./dispatch-events');
 
-const { safeJsonArr, mutateWorkItems,
-  mutatePullRequests, getProjects, projectPrPath, log, ts, dateStamp,
+const { readWorkItems, mutateWorkItems,
+  mutatePullRequests, getProjects, log, ts, dateStamp,
   sidecarDispatchPrompt, deleteDispatchPromptSidecar, DONE_STATUSES,
   WI_STATUS, WORK_TYPE, DISPATCH_RESULT, ENGINE_DEFAULTS, AGENT_STATUS, FAILURE_CLASS, PR_STATUS } = shared;
 const { getConfig, INBOX_DIR } = queries;
@@ -53,6 +53,8 @@ const NON_MUTATING_DISPATCH_TYPES = new Set([
 // PR source branch always differs and causes phantom auto-cancellation (#369).
 const PR_BRANCH_TARGETED_TYPES = new Set([
   WORK_TYPE.FIX,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
+  WORK_TYPE.TEST,
   WORK_TYPE.VERIFY,
   WORK_TYPE.DECOMPOSE,
 ]);
@@ -81,7 +83,7 @@ function _snapshotPrompts(dispatch) {
 
 /**
  * Sidecar oversized prompts only for items the mutator added or modified.
- * Keeps dispatch.json safe from bloat (#1167) without paying O(n) on every
+ * Keeps dispatch state compact (#1167) without paying O(n) on every
  * unrelated mutation (e.g. status flips, completion-marking).
  */
 function _sidecarChangedPrompts(dispatch, prevSnap) {
@@ -148,7 +150,7 @@ function getPrDispatchDedupeKey(entry) {
   if (!entry?.type) return null;
   const targetKey = getPrDispatchTargetKey(entry);
   if (!targetKey) return null;
-  const type = entry.type === WORK_TYPE.FIX ? WORK_TYPE.FIX : entry.type;
+  const type = shared.isFixLikeWorkType(entry.type) ? WORK_TYPE.FIX : entry.type;
   return `${targetKey}:${type}`;
 }
 
@@ -197,7 +199,7 @@ function findActivePrOrBranchLock(dispatch, item) {
   // PR-target dedup is FIX-only: a FIX shouldn't stack on top of another FIX
   // for the same PR, but a REVIEW + FIX pair targeting the same PR is the
   // normal review-then-fix flow and must not be dedup'd here.
-  if (item?.type === WORK_TYPE.FIX) {
+  if (shared.isFixLikeWorkType(item?.type)) {
     const prTargetKey = getPrDispatchTargetKey(item);
     if (prTargetKey) {
       const existing = active.find(d => getPrDispatchTargetKey(d) === prTargetKey);
@@ -306,9 +308,9 @@ function _persistInvalidWorkItem(item, evaluation) {
   const meta = item?.meta;
   const itemId = meta?.item?.id;
   if (!itemId) return { stuck: false };
-  let wiPath;
-  try { wiPath = lifecycle().resolveWorkItemPath(meta); } catch { wiPath = null; }
-  if (!wiPath) return { stuck: false };
+  let wiScope;
+  try { wiScope = lifecycle().resolveWorkItemScope(meta); } catch { wiScope = null; }
+  if (!wiScope) return { stuck: false };
   // W-mrcrh5hj0017d22f — repeat-rejection cap. Compare against the
   // description snapshot from the LAST rejection so an operator edit to the
   // WI resets the counter (it deserves a fresh evaluation), while an
@@ -319,7 +321,7 @@ function _persistInvalidWorkItem(item, evaluation) {
   const currentDescription = String((meta.item && meta.item.description) || '');
   let stuck = false;
   try {
-    mutateWorkItems(wiPath, (items) => {
+    mutateWorkItems(wiScope, (items) => {
       if (!Array.isArray(items)) return items;
       const idx = items.findIndex(w => w && w.id === itemId);
       if (idx === -1) return items;
@@ -393,8 +395,7 @@ function _isPrdSourcedAndVetted(wi) {
   const sourcePlan = wi && wi.sourcePlan;
   if (!sourcePlan || typeof sourcePlan !== 'string') return false;
   try {
-    const prdPath = path.join(queries.PRD_DIR, sourcePlan);
-    const plan = shared.safeJsonNoRestore(prdPath);
+    const plan = require('./prd-store').readPrd(sourcePlan);
     if (!plan || !plan.missing_features) return false;
     const status = plan.status || shared.PLAN_STATUS.ACTIVE;
     return status === shared.PLAN_STATUS.APPROVED || status === shared.PLAN_STATUS.ACTIVE;
@@ -454,7 +455,7 @@ async function addToDispatchWithValidation(item, opts = {}) {
       : _isPrdSourcedAndVetted;
     if (isPrdVetted(wi)) {
       // Stamp the skip marker on the dispatch item so the entry that lands
-      // in dispatch.json carries observability — operators can spot which
+      // in dispatch state carries observability — operators can spot which
       // items the validator skipped vs which it ran.
       item._preDispatchEvalSkipped = 'prd-sourced';
       return addToDispatch(item);
@@ -569,17 +570,17 @@ function getStalePrDispatchReason(entry, config) {
 function cancelSourceWorkItemForPrunedDispatch(entry, reason) {
   const itemId = entry?.meta?.item?.id;
   if (!itemId) return false;
-  let wiPath;
-  try { wiPath = lifecycle().resolveWorkItemPath(entry.meta); }
+  let wiScope;
+  try { wiScope = lifecycle().resolveWorkItemScope(entry.meta); }
   catch (e) {
     log('warn', `Failed to resolve source work item for pruned dispatch ${entry.id}: ${e.message}`);
     return false;
   }
-  if (!wiPath) return false;
+  if (!wiScope) return false;
 
   let cancelled = false;
   try {
-    mutateWorkItems(wiPath, (items) => {
+    mutateWorkItems(wiScope, (items) => {
       if (!Array.isArray(items)) return items;
       const wi = items.find(w => w && w.id === itemId);
       if (!wi) return items;
@@ -608,9 +609,9 @@ function _resolveWorkItemForPrunedEntry(entry) {
   const itemId = entry?.meta?.item?.id;
   if (!itemId) return null;
   try {
-    const wiPath = lifecycle().resolveWorkItemPath(entry.meta);
-    if (!wiPath) return null;
-    const items = safeJsonArr(wiPath);
+    const wiScope = lifecycle().resolveWorkItemScope(entry.meta);
+    if (!wiScope) return null;
+    const items = readWorkItems(wiScope);
     return items.find(w => w && w.id === itemId) || null;
   } catch {
     return null;
@@ -704,7 +705,7 @@ async function pruneStalePrDispatchesAsync(config = queries.getConfig()) {
   for (const entry of pending) {
     const reason = reasonsById.get(entry.id);
     if (!reason) continue;
-    if (entry.type !== WORK_TYPE.FIX || !_MERGED_OR_ABANDONED_REASON_RE.test(reason)) continue;
+    if (!shared.isFixLikeWorkType(entry.type) || !_MERGED_OR_ABANDONED_REASON_RE.test(reason)) continue;
     try {
       const wi = _resolveWorkItemForPrunedEntry(entry);
       const scopePaths = shared.extractScopeFilePathsFromWorkItem(wi);
@@ -851,9 +852,9 @@ const FORCE_DEMOTE_FAILURE_CLASSES = new Set([
 function readLiveWorkItem(meta) {
   const itemId = meta?.item?.id;
   if (!itemId) return null;
-  const wiPath = lifecycle().resolveWorkItemPath(meta);
-  if (!wiPath) return null;
-  const items = safeJsonArr(wiPath);
+  const wiScope = lifecycle().resolveWorkItemScope(meta);
+  if (!wiScope) return null;
+  const items = readWorkItems(wiScope);
   return items.find(i => i.id === itemId) || null;
 }
 
@@ -894,11 +895,11 @@ function markCompletedSourceWorkItem(item) {
   const meta = item?.meta;
   const itemId = meta?.item?.id;
   if (!itemId) return false;
-  const wiPath = lifecycle().resolveWorkItemPath(meta);
-  if (!wiPath) return false;
+  const wiScope = lifecycle().resolveWorkItemScope(meta);
+  if (!wiScope) return false;
   let found = false;
   let terminal = false;
-  mutateWorkItems(wiPath, items => {
+  mutateWorkItems(wiScope, items => {
     if (!Array.isArray(items)) return items;
     const wi = items.find(i => i.id === itemId);
     if (!wi) return items;
@@ -985,7 +986,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
   if (item) {
     log('info', `Completed dispatch: ${id} (${result}${reason ? ': ' + reason : ''})`);
     // W-mpob4nyk0006580e — broadcast terminal state immediately after the
-    // `result` field is committed to dispatch.json. This is the single
+    // `result` field is committed to dispatch state. This is the single
     // source of truth for the live-view banner; subscribers (dashboard SSE
     // handler at handleAgentLiveStream) push it to clients so the banner
     // mirrors `dispatch.result` exactly — no log-parsing heuristics that can
@@ -1046,11 +1047,11 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
         const isForceDemote = failureClass && FORCE_DEMOTE_FAILURE_CLASSES.has(failureClass) && !isPrShipped;
         if (isForceDemote) {
           try {
-            const wiPath = lifecycle().resolveWorkItemPath(item.meta);
-            if (wiPath) {
+            const wiScope = lifecycle().resolveWorkItemScope(item.meta);
+            if (wiScope) {
               const classSuffix = ` [${failureClass.toUpperCase().replace(/-/g, '_')}]`;
               const demoteReason = `Non-retryable failure: ${reason || failureClass}${classSuffix}`;
-              mutateWorkItems(wiPath, items => {
+              mutateWorkItems(wiScope, items => {
                 const wi = items.find(i => i.id === item.meta.item.id);
                 if (wi) {
                   wi.status = WI_STATUS.FAILED;
@@ -1093,7 +1094,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
       } else {
         let retries = (item.meta.item._retryCount || 0);
         try {
-          const wi = queries.getWorkItems().find(i => i.id === item.meta.item.id);
+          const wi = liveWi || readLiveWorkItem(item.meta);
           if (wi) retries = wi._retryCount || 0;
         } catch (e) { log('warn', 'read retry count: ' + e.message); }
         const maxRetries = ENGINE_DEFAULTS.maxRetries;
@@ -1112,9 +1113,9 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
           }
           // Increment retry counter on the source work item
           try {
-            const wiPath = lifecycle().resolveWorkItemPath(item.meta);
-            if (wiPath) {
-              mutateWorkItems(wiPath, items => {
+            const wiScope = lifecycle().resolveWorkItemScope(item.meta);
+            if (wiScope) {
+              mutateWorkItems(wiScope, items => {
                 const wi = items.find(i => i.id === item.meta.item.id);
                 if (wi && wi.status !== WI_STATUS.PAUSED && wi.status !== WI_STATUS.DONE && !wi.completedAt) {
                   wi._retryCount = retries + 1;
@@ -1229,10 +1230,9 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
       const isTransientPreflight = TRANSIENT_PREFLIGHT_CLASSES.has(failureClass);
       if (prId && project) {
         try {
-          const prsPath = projectPrPath(project);
           let restored = false;
           let gaveUp = false;
-          mutatePullRequests(prsPath, prs => {
+          mutatePullRequests(project, prs => {
             const target = shared.findPrRecord(prs, { id: prId }, project);
             if (!target?.humanFeedback) return;
             if (isTransientPreflight) {
@@ -1383,12 +1383,7 @@ function cleanDispatchEntries(matchFn) {
   const filesToDelete = [];
   const dispatchDirsToRemove = [];
   try {
-    // Route through mutateDispatch so the SQL-backed store (Phase 1) and the
-    // dispatch.json mirror stay coherent. Writing dispatch.json directly with
-    // mutateJsonFileLocked here would leave stale rows in the `dispatches`
-    // table; the very next mutateDispatch call (e.g. removeProject's
-    // step 7.5 orphan-tagging pass) would then mirror SQL back to JSON and
-    // resurrect the entries we just drained.
+    // Keep the drain and orphan-tagging passes atomic in the dispatch store.
     mutateDispatch((dispatch) => {
       for (const queue of ['pending', 'active', 'completed']) {
         dispatch[queue] = Array.isArray(dispatch[queue]) ? dispatch[queue] : [];
@@ -1449,10 +1444,10 @@ function cleanDispatchEntries(matchFn) {
  * Cancel pending/queued work items matching a predicate. Done items pass through.
  * Sets status=CANCELLED + _cancelledBy=reason. Returns count cancelled.
  */
-function cancelPendingWorkItems(wiPath, matchFn, reason) {
+function cancelPendingWorkItems(scope, matchFn, reason) {
   let cancelled = 0;
   try {
-    mutateWorkItems(wiPath, items => {
+    mutateWorkItems(scope, items => {
       for (const w of items) {
         if (!matchFn(w)) continue;
         if (w.status !== WI_STATUS.PENDING && w.status !== WI_STATUS.QUEUED) continue;

package/engine/github.js

@@ -5,7 +5,7 @@
  */
 
 const shared = require('./shared');
-const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeJsonArr, safeWrite, mutateJsonFileLocked, mutatePullRequests, MINIONS_DIR, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, ENGINE_DEFAULTS, createThrottleTracker, getProjectOrg } = shared;
+const { exec, execAsync, getProjects, readWorkItems, readPullRequests, safeJson, safeJsonArr, safeWrite, mutateMetrics, mutatePullRequests, MINIONS_DIR, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, ENGINE_DEFAULTS, createThrottleTracker, getProjectOrg } = shared;
 const { getPrs } = require('./queries');
 const { isPreviewStatusBody, hasMinionsMarker, hasVerdictPrefix } = require('./comment-classifier');
 const { wrapUntrusted, buildSource } = require('./untrusted-fence');
@@ -291,8 +291,7 @@ async function _resolveViewerLogin(slug) {
 // engine metrics aggregation (`getMetrics()` in `engine/queries.js`).
 function _incrementViewerLoginResolutionFailures() {
   try {
-    const metricsPath = path.join(MINIONS_DIR, 'engine', 'metrics.json');
-    mutateJsonFileLocked(metricsPath, (metrics) => {
+    mutateMetrics((metrics) => {
       metrics = metrics || {};
       if (!metrics._engine) metrics._engine = {};
       metrics._engine.viewerLoginResolutionFailures =
@@ -590,7 +589,7 @@ async function forEachActiveGhPr(config, callback) {
     }
 
     if (projectUpdated > 0) {
-      mutateJsonFileLocked(projectPrPath(project), (currentPrs) => {
+      mutatePullRequests(project, (currentPrs) => {
         // Merge back only fields changed by callbacks; preserve concurrent disk updates.
         for (const { before, after } of updatedRecords) {
           const idx = currentPrs.findIndex(p => p.id === after.id);
@@ -601,7 +600,7 @@ async function forEachActiveGhPr(config, callback) {
             }
             // W-mp5trwh60008386d: never downgrade `status: merged` — terminal state. A stale
             // 404 reaching `prAbandonConfirmCount` could otherwise overwrite a concurrent
-            // success/merge poll. Keeps the central pull-requests.json status invariants
+            // success/merge poll. Keeps the central PR status invariants
             // intact even under multi-writer races.
             if (currentPrs[idx].status === PR_STATUS.MERGED && after.status !== PR_STATUS.MERGED) {
               after.status = PR_STATUS.MERGED;
@@ -629,9 +628,8 @@ async function forEachActiveGhPr(config, callback) {
     }
   }
 
-  // Also poll manually-linked PRs from central pull-requests.json (extract slug from URL)
-  const centralPath = path.join(MINIONS_DIR, 'pull-requests.json');
-  const centralPrs = safeJsonArr(centralPath);
+  // Also poll manually-linked PRs from central state (extract slug from URL).
+  const centralPrs = readPullRequests('central');
   // Build a slug→project map for configured GitHub projects so we can detect
   // PRs that are actually owned by the project loop (present in per-project file).
   const configuredGhProjectsBySlug = new Map();
@@ -648,7 +646,7 @@ async function forEachActiveGhPr(config, callback) {
     if (ghMatch) {
       const owningProject = configuredGhProjectsBySlug.get(ghMatch[1].toLowerCase());
       if (owningProject) {
-        const projectPrs = safeJsonArr(projectPrPath(owningProject));
+        const projectPrs = readPullRequests(owningProject);
         if (projectPrs.some(p => p.id === pr.id)) return false; // present → project loop handles it
       }
     }
@@ -726,7 +724,7 @@ async function forEachActiveGhPr(config, callback) {
     }
   }
   if (centralUpdated > 0) {
-    mutateJsonFileLocked(centralPath, (currentPrs) => {
+    mutatePullRequests('central', (currentPrs) => {
       // Only merge back central PRs that the callback actually modified
       for (const { before, after } of updatedCentralRecords) {
         const idx = currentPrs.findIndex(p => p.id === after.id);
@@ -1004,7 +1002,7 @@ async function pollPrStatus(config) {
         }
         // F6 (P-f6commentedit): drop the comment-edit dedup map on merge/abandon
         // — no further re-dispatch path can fire from this PR, so keeping it
-        // around would only bloat pull-requests.json.
+        // around would only bloat the PR store.
         if (pr.humanFeedback && pr.humanFeedback.editsSeen) {
           delete pr.humanFeedback.editsSeen;
         }
@@ -1204,7 +1202,7 @@ async function pollPrStatus(config) {
     // review status flipped, etc.) is dropped via clearPrNoOpFixAttempt. The
     // dispatch gate already ignores these stale records (isPrNoOpFixCausePaused
     // re-validates the fingerprint), but without this sweep they linger in
-    // pull-requests.json forever — bloating the file and confusing the
+    // PR store forever — bloating the registry and confusing the
     // dashboard `pr-paused-chip`. Runs AFTER all live-field updates so the
     // fingerprint comparison uses post-poll PR state.
     try {
@@ -1454,8 +1452,7 @@ async function reconcilePrs(config) {
     const existingPrs = getPrs(project);
     if (existingPrs.length === 0) {
       try {
-        const wiPath = projectWorkItemsPath(project);
-        const wis = safeJsonArr(wiPath);
+        const wis = readWorkItems(project);
         if (wis.length === 0) continue;
       } catch { continue; }
     }
@@ -1478,18 +1475,15 @@ async function reconcilePrs(config) {
 
     if (ghPrs.length === 0) continue;
 
-    const prPath = projectPrPath(project);
-    const currentPrs = safeJsonArr(prPath);
+    const currentPrs = readPullRequests(project);
     shared.normalizePrRecords(currentPrs, project);
     const existingIds = new Set(currentPrs.map(p => p.id));
     let metadataUpdated = 0;
     let projectAdded = 0;
 
     // Load work items to match branches
-    const wiPath = projectWorkItemsPath(project);
-    const workItems = safeJsonArr(wiPath);
-    const centralWiPath = path.join(MINIONS_DIR, 'work-items.json');
-    const centralItems = safeJsonArr(centralWiPath);
+    const workItems = readWorkItems(project);
+    const centralItems = readWorkItems('central');
     const allItems = [...workItems, ...centralItems];
 
     for (const { pr: ghPr, slug } of ghPrs) {
@@ -1528,7 +1522,7 @@ async function reconcilePrs(config) {
           metadataUpdated++;
         }
         if (confirmedItemId) {
-          shared.upsertPullRequestRecord(prPath, existing || {
+          shared.upsertPullRequestRecord(project, existing || {
             id: prId,
             prNumber: ghPr.number,
             title: (ghPr.title || `PR #${ghPr.number}`).slice(0, 120),
@@ -1587,7 +1581,7 @@ async function reconcilePrs(config) {
         sourcePlan: linkedItem?.sourcePlan || '',
         itemType: linkedItem?.itemType || '',
       };
-      const upserted = shared.upsertPullRequestRecord(prPath, entry, { project, itemId: confirmedItemId });
+      const upserted = shared.upsertPullRequestRecord(project, entry, { project, itemId: confirmedItemId });
       currentPrs.push(upserted.record || entry);
       existingIds.add(prId);
       projectAdded++;
@@ -1607,14 +1601,14 @@ async function reconcilePrs(config) {
     const backfilled = backfillPrPrdItems(currentPrs, getPrLinks());
 
     if (projectAdded > 0 || backfilled > 0 || metadataUpdated > 0) {
-      mutateJsonFileLocked(prPath, (lockedPrs) => {
+      mutatePullRequests(project, (lockedPrs) => {
         for (const pr of currentPrs) {
           const idx = lockedPrs.findIndex(p => p.id === pr.id);
           if (idx >= 0) lockedPrs[idx] = pr;
           else lockedPrs.push(pr);
         }
         return lockedPrs;
-      }, { defaultValue: [] });
+      });
       totalAdded += projectAdded;
     }
   }
@@ -1872,8 +1866,7 @@ async function reconcileAbandonedPrs(config) {
   const slugProbeCache = new Map(); // slug → 'ok' | 'fail'
 
   for (const project of projects) {
-    const prPath = projectPrPath(project);
-    const prs = safeJsonArr(prPath);
+    const prs = readPullRequests(project);
     // Filter: only abandoned PRs that don't already have the confirmed-404
     // marker from a previous reconciliation pass. Marker means "we already
     // verified this PR is genuinely deleted on the server" — no point
@@ -1958,7 +1951,7 @@ async function reconcileAbandonedPrs(config) {
 
     if (updates.length > 0) {
       const reconciledAt = ts();
-      mutatePullRequests(prPath, (currentPrs) => {
+      mutatePullRequests(project, (currentPrs) => {
         for (const upd of updates) {
           const pr = currentPrs.find(p =>
             shared.getCanonicalPrId(project, p, p.url || '') === upd.prId