@yemi33/minions 0.1.2042 → 0.1.2043

package/dashboard/js/refresh.js

@@ -67,7 +67,7 @@ const RENDER_VERSIONS = {
   agents: 1,
   prdProgress: 1,
   prdPrs: 1,
-  inbox: 1,
+  inbox: 2,
   projects: 1,
   notes: 1,
   prd: 1,
@@ -77,8 +77,8 @@ const RENDER_VERSIONS = {
   version: 1,
   adoThrottle: 1,
   ghThrottle: 1,
-  dispatch: 1,
-  engineLog: 1,
+  dispatch: 2,
+  engineLog: 2,
   metrics: 1,
   workItems: 1,
   skills: 1,
@@ -88,6 +88,7 @@ const RENDER_VERSIONS = {
   meetings: 1,
   pipelines: 1,
   pinned: 1,
+  kbPayload: 2,
 };
 const _sectionCache = {};
 const _lastValueByKey = {};

package/dashboard/js/render-dispatch.js

@@ -191,19 +191,24 @@ function renderDispatch(dispatch) {
     '<div class="dispatch-stat"><div class="dispatch-stat-num blue">' + (dispatch.pending || []).length + '</div><div class="dispatch-stat-label">Pending</div></div>' +
     '<div class="dispatch-stat"><div class="dispatch-stat-num green">' + (dispatch.completedTotal || (dispatch.completed || []).length) + '</div><div class="dispatch-stat-label">Completed</div></div>';
 
+  // Shared row markup for the Active and Pending lists. The two differ only in
+  // the trailing chip: Active shows started_at, Pending shows skipReason.
+  const dispatchItemHtml = (d, trailing) =>
+    '<div class="dispatch-item">' +
+      '<span class="dispatch-type ' + (d.type || '') + '">' + escHtml(d.type || '') + '</span>' +
+      '<span class="dispatch-agent">' + escHtml(d.agentName || d.agent || '') + '</span>' +
+      '<span class="dispatch-task" title="' + escHtml(d.task || '') + '">' + escHtml(d.task || '') + '</span>' +
+      renderStuckChip(d) +
+      trailing +
+    '</div>';
+
   // Active
   const activeEl = document.getElementById('dispatch-active');
   if ((dispatch.active || []).length > 0) {
     activeEl.innerHTML = '<div style="font-size:11px;color:var(--green);margin-bottom:6px;font-weight:600">ACTIVE</div><div class="dispatch-list">' +
-      dispatch.active.map(d =>
-        '<div class="dispatch-item">' +
-          '<span class="dispatch-type ' + (d.type || '') + '">' + escHtml(d.type || '') + '</span>' +
-          '<span class="dispatch-agent">' + escHtml(d.agentName || d.agent || '') + '</span>' +
-          '<span class="dispatch-task" title="' + escHtml(d.task || '') + '">' + escHtml(d.task || '') + '</span>' +
-          renderStuckChip(d) +
-          '<span class="dispatch-time">' + shortTime(d.started_at) + '</span>' +
-        '</div>'
-      ).join('') + '</div>';
+      dispatch.active.map(d => dispatchItemHtml(d,
+        '<span class="dispatch-time">' + shortTime(d.started_at) + '</span>'
+      )).join('') + '</div>';
   } else {
     activeEl.innerHTML = '<div style="color:var(--muted);font-size:11px;margin-bottom:8px">No active dispatches</div>';
   }
@@ -212,15 +217,9 @@ function renderDispatch(dispatch) {
   const pendingEl = document.getElementById('dispatch-pending');
   if ((dispatch.pending || []).length > 0) {
     pendingEl.innerHTML = '<div style="font-size:11px;color:var(--yellow);margin:8px 0 6px;font-weight:600">PENDING</div><div class="dispatch-list">' +
-      dispatch.pending.map(d =>
-        '<div class="dispatch-item">' +
-          '<span class="dispatch-type ' + (d.type || '') + '">' + escHtml(d.type || '') + '</span>' +
-          '<span class="dispatch-agent">' + escHtml(d.agentName || d.agent || '') + '</span>' +
-          '<span class="dispatch-task" title="' + escHtml(d.task || '') + '">' + escHtml(d.task || '') + '</span>' +
-          renderStuckChip(d) +
-          (d.skipReason ? '<span style="font-size:9px;color:var(--muted);margin-left:6px" title="' + escHtml(d.skipReason) + '">' + escHtml(d.skipReason.replace(/_/g, ' ')) + '</span>' : '') +
-        '</div>'
-      ).join('') + '</div>';
+      dispatch.pending.map(d => dispatchItemHtml(d,
+        d.skipReason ? '<span style="font-size:9px;color:var(--muted);margin-left:6px" title="' + escHtml(d.skipReason) + '">' + escHtml(d.skipReason.replace(/_/g, ' ')) + '</span>' : ''
+      )).join('') + '</div>';
   } else {
     pendingEl.innerHTML = '';
   }
@@ -254,14 +253,12 @@ function renderDispatch(dispatch) {
           '<td class="pr-date">' + shortTime(d.completed_at) + '</td>' +
         '</tr>';
       }).join('') + '</tbody></table>';
-    if (completed.length > COMPLETED_PER_PAGE) {
-      completedEl.insertAdjacentHTML('beforeend', '<div class="pr-pager">' +
-        '<span class="pr-page-info">Showing ' + (compStart + 1) + ' to ' + Math.min(compStart + COMPLETED_PER_PAGE, completed.length) + ' of ' + completed.length + '</span>' +
-        '<div class="pr-pager-btns">' +
-          '<button class="pr-pager-btn ' + (_completedPage === 0 ? 'disabled' : '') + '" onclick="_completedPrev()">Prev</button>' +
-          '<button class="pr-pager-btn ' + (_completedPage >= totalCompPages - 1 ? 'disabled' : '') + '" onclick="_completedNext()">Next</button>' +
-        '</div></div>');
-    }
+    const compPager = renderPager({
+      start: compStart, perPage: COMPLETED_PER_PAGE, total: completed.length,
+      page: _completedPage, totalPages: totalCompPages,
+      onPrev: '_completedPrev()', onNext: '_completedNext()',
+    });
+    if (compPager) completedEl.insertAdjacentHTML('beforeend', compPager);
   } else {
     completedEl.innerHTML = '<p class="empty">No completed dispatches yet.</p>';
   }
@@ -288,14 +285,12 @@ function renderEngineLog(log) {
       escHtml(e.message || '') +
     '</div>'
   ).join('');
-  if (reversed.length > LOG_PER_PAGE) {
-    el.insertAdjacentHTML('beforeend', '<div class="pr-pager">' +
-      '<span class="pr-page-info">Showing ' + (logStart + 1) + ' to ' + Math.min(logStart + LOG_PER_PAGE, reversed.length) + ' of ' + reversed.length + '</span>' +
-      '<div class="pr-pager-btns">' +
-        '<button class="pr-pager-btn ' + (_logPage === 0 ? 'disabled' : '') + '" onclick="_logPrev()">Prev</button>' +
-        '<button class="pr-pager-btn ' + (_logPage >= totalLogPages - 1 ? 'disabled' : '') + '" onclick="_logNext()">Next</button>' +
-      '</div></div>');
-  }
+  const logPager = renderPager({
+    start: logStart, perPage: LOG_PER_PAGE, total: reversed.length,
+    page: _logPage, totalPages: totalLogPages,
+    onPrev: '_logPrev()', onNext: '_logNext()',
+  });
+  if (logPager) el.insertAdjacentHTML('beforeend', logPager);
 }
 
 function shortTime(t) {

package/dashboard/js/render-inbox.js

@@ -35,21 +35,19 @@ function renderInbox(inbox) {
       </div>
       <div class="inbox-preview" onclick="openModal(${idx})" style="cursor:pointer">${escapeHtml(item.content.slice(0,200))}</div>
       <div style="display:flex;gap:6px;margin-top:6px;align-items:center">
-        <button class="pr-pager-btn pin-btn${pinned ? ' pinned' : ''}" style="font-size:9px;padding:2px 8px" data-pin-key="${escapeHtml(pk)}" onclick="event.stopPropagation();_togglePinAndRefresh(this.dataset.pinKey,'inbox')">${pinned ? 'Unpin' : 'Pin'}</button>
+        ${pinButton(pk, pinned, 'inbox')}
         <button class="pr-pager-btn" style="font-size:9px;padding:2px 8px" data-inbox-name="${escapeHtml(item.name)}" onclick="event.stopPropagation();promoteToKB(this.dataset.inboxName)">Add to Knowledge Base</button>
         <button class="pr-pager-btn" style="font-size:9px;padding:2px 8px" data-inbox-name="${escapeHtml(item.name)}" onclick="event.stopPropagation();openInboxInExplorer(this.dataset.inboxName)">Open in Explorer</button>
         <button class="pr-pager-btn" style="font-size:9px;padding:2px 8px;color:var(--red)" data-inbox-name="${escapeHtml(item.name)}" onclick="event.stopPropagation();deleteInboxItem(this.dataset.inboxName)">Delete</button>
       </div>
     </div>`;
   }).join('');
-  if (inbox.length > INBOX_PER_PAGE) {
-    list.insertAdjacentHTML('beforeend', '<div class="pr-pager">' +
-      '<span class="pr-page-info">Showing ' + (inboxStart + 1) + ' to ' + Math.min(inboxStart + INBOX_PER_PAGE, inbox.length) + ' of ' + inbox.length + '</span>' +
-      '<div class="pr-pager-btns">' +
-        '<button class="pr-pager-btn ' + (_inboxPage === 0 ? 'disabled' : '') + '" onclick="_inboxPrev()">Prev</button>' +
-        '<button class="pr-pager-btn ' + (_inboxPage >= totalInboxPages - 1 ? 'disabled' : '') + '" onclick="_inboxNext()">Next</button>' +
-      '</div></div>');
-  }
+  const inboxPager = renderPager({
+    start: inboxStart, perPage: INBOX_PER_PAGE, total: inbox.length,
+    page: _inboxPage, totalPages: totalInboxPages,
+    onPrev: '_inboxPrev()', onNext: '_inboxNext()',
+  });
+  if (inboxPager) list.insertAdjacentHTML('beforeend', inboxPager);
   restoreNotifBadges();
 }
 

package/dashboard/js/render-kb.js

@@ -142,7 +142,7 @@ function renderKnowledgeBase() {
     return '<div class="kb-item' + (pinned ? ' item-pinned' : '') + '" data-file="knowledge/' + escapeHtml(item.category) + '/' + escapeHtml(item.file) + '" onclick="kbOpenItem(\'' + escapeHtml(item.category) + '\', \'' + escapeHtml(item.file) + '\')">' +
       '<div class="kb-item-body">' +
         '<div class="kb-item-title">' + icon + ' ' + escapeHtml(item.title) +
-          ' <button class="pr-pager-btn pin-btn' + (pinned ? ' pinned' : '') + '" style="font-size:9px;padding:1px 6px;margin-left:6px;vertical-align:middle" data-pin-key="' + escapeHtml(pinKey) + '" onclick="event.stopPropagation();_togglePinAndRefresh(this.dataset.pinKey,\'kb\')">' + (pinned ? 'Unpin' : 'Pin') + '</button>' +
+          ' ' + pinButton(pinKey, pinned, 'kb', { extraStyle: 'padding:1px 6px;margin-left:6px;vertical-align:middle' }) +
         '</div>' +
         '<div class="kb-item-meta">' +
           '<span>' + label + '</span>' +
@@ -154,14 +154,12 @@ function renderKnowledgeBase() {
       '</div>' +
     '</div>';
   }).join('');
-  if (items.length > KB_PER_PAGE) {
-    listEl.insertAdjacentHTML('beforeend', '<div class="pr-pager">' +
-      '<span class="pr-page-info">Showing ' + (kbStart + 1) + ' to ' + Math.min(kbStart + KB_PER_PAGE, items.length) + ' of ' + items.length + '</span>' +
-      '<div class="pr-pager-btns">' +
-        '<button class="pr-pager-btn ' + (_kbPage === 0 ? 'disabled' : '') + '" onclick="_kbPrev()">Prev</button>' +
-        '<button class="pr-pager-btn ' + (_kbPage >= totalKbPages - 1 ? 'disabled' : '') + '" onclick="_kbNext()">Next</button>' +
-      '</div></div>');
-  }
+  const kbPager = renderPager({
+    start: kbStart, perPage: KB_PER_PAGE, total: items.length,
+    page: _kbPage, totalPages: totalKbPages,
+    onPrev: '_kbPrev()', onNext: '_kbNext()',
+  });
+  if (kbPager) listEl.insertAdjacentHTML('beforeend', kbPager);
   restoreNotifBadges();
 }
 

package/dashboard/js/render-utils.js

@@ -352,4 +352,56 @@ function renderAgentOutput(text) {
   return fragments.join('');
 }
 
-window.MinionsRenderUtils = { formatToolSummary, renderAgentOutput };
+/**
+ * Standard "Prev / Next" pager HTML for a paginated list. Used by inbox, KB,
+ * completed dispatches, and engine log. The caller is responsible for the
+ * `onPrev`/`onNext` JS expression strings — they're inlined as `onclick`
+ * attributes, so callers must pass safe identifier-only expressions
+ * (e.g. `'_inboxPrev()'`).
+ *
+ * @param {object} opts
+ * @param {number} opts.start - Zero-based start index of the current page.
+ * @param {number} opts.perPage - Items per page.
+ * @param {number} opts.total - Total items across all pages.
+ * @param {number} opts.page - Zero-based current page index.
+ * @param {number} opts.totalPages - Total page count.
+ * @param {string} opts.onPrev - JS expression for the Prev button's onclick.
+ * @param {string} opts.onNext - JS expression for the Next button's onclick.
+ * @returns {string} HTML string for the pager (empty when total <= perPage).
+ */
+function renderPager(opts) {
+  var start = opts.start, perPage = opts.perPage, total = opts.total;
+  var page = opts.page, totalPages = opts.totalPages;
+  if (total <= perPage) return '';
+  return '<div class="pr-pager">' +
+    '<span class="pr-page-info">Showing ' + (start + 1) + ' to ' + Math.min(start + perPage, total) + ' of ' + total + '</span>' +
+    '<div class="pr-pager-btns">' +
+      '<button class="pr-pager-btn ' + (page === 0 ? 'disabled' : '') + '" onclick="' + opts.onPrev + '">Prev</button>' +
+      '<button class="pr-pager-btn ' + (page >= totalPages - 1 ? 'disabled' : '') + '" onclick="' + opts.onNext + '">Next</button>' +
+    '</div></div>';
+}
+
+/**
+ * Renders the standard Pin/Unpin chip used in the inbox and KB lists. Both
+ * call _togglePinAndRefresh(pinKey, source) on click; the only thing that
+ * varies is the source name. The data-pin-key attribute is escaped via
+ * escHtml; callers must pass the already-computed pin key.
+ *
+ * @param {string} pinKey - The pin storage key (e.g. inboxPinKey(name)).
+ * @param {boolean} pinned - Current pinned state.
+ * @param {string} source - The source name passed to _togglePinAndRefresh
+ *   (e.g. 'inbox', 'kb').
+ * @param {object} [opts]
+ * @param {string} [opts.extraStyle] - Inline CSS appended to the button.
+ * @returns {string} HTML for the pin button.
+ */
+function pinButton(pinKey, pinned, source, opts) {
+  var extraStyle = (opts && opts.extraStyle) || '';
+  return '<button class="pr-pager-btn pin-btn' + (pinned ? ' pinned' : '') +
+    '" style="font-size:9px;padding:2px 8px;' + extraStyle +
+    '" data-pin-key="' + escHtml(pinKey) +
+    '" onclick="event.stopPropagation();_togglePinAndRefresh(this.dataset.pinKey,\'' + source + '\')">' +
+    (pinned ? 'Unpin' : 'Pin') + '</button>';
+}
+
+window.MinionsRenderUtils = { formatToolSummary, renderAgentOutput, renderPager, pinButton };

package/engine/dispatch.js

@@ -9,11 +9,11 @@ const shared = require('./shared');
 const queries = require('./queries');
 const { setCooldown, setCooldownFailure } = require('./cooldown');
 
-const { safeJson, mutateJsonFileLocked, mutateWorkItems,
-  mutatePullRequests, getProjects, projectWorkItemsPath, projectPrPath, log, ts, dateStamp,
+const { safeJsonArr, mutateJsonFileLocked, mutateWorkItems,
+  mutatePullRequests, getProjects, projectPrPath, log, ts, dateStamp,
   sidecarDispatchPrompt, deleteDispatchPromptSidecar,
   WI_STATUS, WORK_TYPE, DISPATCH_RESULT, ENGINE_DEFAULTS, AGENT_STATUS, FAILURE_CLASS, PR_STATUS } = shared;
-const { getConfig, getDispatch, DISPATCH_PATH, INBOX_DIR } = queries;
+const { getConfig, DISPATCH_PATH, INBOX_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
 
@@ -149,10 +149,13 @@ function addToDispatch(item) {
   }
   let added = false;
   mutateDispatch((dispatch) => {
+    // Walked once per addToDispatch — all three dedup checks below find against the same set.
+    const queued = [...dispatch.pending, ...(dispatch.active || [])];
+
     // Dedup: skip if same work item ID is already pending or active
     const wiId = item.meta?.source === 'central-work-item-fanout' ? null : item.meta?.item?.id;
     if (wiId) {
-      const existing = [...dispatch.pending, ...(dispatch.active || [])].find(d => d.meta?.item?.id === wiId);
+      const existing = queued.find(d => d.meta?.item?.id === wiId);
       if (existing) {
         log('info', `Dedup: skipping ${item.id} — work item ${wiId} already in ${existing.id}`);
         return dispatch;
@@ -160,7 +163,7 @@ function addToDispatch(item) {
     }
     // Also dedup by dispatchKey
     if (item.meta?.dispatchKey) {
-      const existing = [...dispatch.pending, ...(dispatch.active || [])].find(d => d.meta?.dispatchKey === item.meta.dispatchKey);
+      const existing = queued.find(d => d.meta?.dispatchKey === item.meta.dispatchKey);
       if (existing) {
         log('info', `Dedup: skipping ${item.id} — dispatchKey ${item.meta.dispatchKey} already in ${existing.id}`);
         return dispatch;
@@ -168,8 +171,7 @@ function addToDispatch(item) {
     }
     const prDedupeKey = getPrDispatchDedupeKey(item);
     if (prDedupeKey) {
-      const existing = [...dispatch.pending, ...(dispatch.active || [])]
-        .find(d => getPrDispatchDedupeKey(d) === prDedupeKey);
+      const existing = queued.find(d => getPrDispatchDedupeKey(d) === prDedupeKey);
       if (existing) {
         log('info', `Dedup: skipping ${item.id} — PR dispatch ${prDedupeKey} already in ${existing.id}`);
         return dispatch;
@@ -453,8 +455,8 @@ function readLiveWorkItem(meta) {
   if (!itemId) return null;
   const wiPath = lifecycle().resolveWorkItemPath(meta);
   if (!wiPath) return null;
-  const items = safeJson(wiPath) || [];
-  return Array.isArray(items) ? items.find(i => i.id === itemId) || null : null;
+  const items = safeJsonArr(wiPath);
+  return items.find(i => i.id === itemId) || null;
 }
 
 function writeFailedAgentReport(item, reason, resultSummary, failureClass) {
@@ -882,14 +884,13 @@ function cancelPendingDispatchesForPr(prId) {
  * @returns {number} count of removed entries
  */
 function cleanDispatchEntries(matchFn) {
-  const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
   const tmpDir = path.join(MINIONS_DIR, 'engine', 'tmp');
   let removed = 0;
   const pidsToKill = [];
   const filesToDelete = [];
   const dispatchDirsToRemove = [];
   try {
-    mutateJsonFileLocked(dispatchPath, (dispatch) => {
+    mutateJsonFileLocked(DISPATCH_PATH, (dispatch) => {
       for (const queue of ['pending', 'active', 'completed']) {
         dispatch[queue] = Array.isArray(dispatch[queue]) ? dispatch[queue] : [];
         const before = dispatch[queue].length;

package/engine/lifecycle.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const shared = require('./shared');
-const { safeRead, safeJson, safeJsonNoRestore, safeWrite, mutateJsonFileLocked, mutateWorkItems, execAsync, projectPrPath, getPrLinks,
+const { safeRead, safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, mutateJsonFileLocked, mutateWorkItems, execAsync, projectPrPath, getPrLinks,
   log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PR_STATUS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { trackEngineUsage } = require('./llm');
@@ -113,7 +113,7 @@ function checkPlanCompletion(meta, config) {
   for (const p of projects) {
     try {
       const prPath = shared.projectPrPath(p);
-      const prs = safeJson(prPath) || [];
+      const prs = safeJsonArr(prPath);
       const prLinks = getPrLinks();
       for (const pr of prs) {
         const linkedItemIds = prLinks[pr.id] || [];
@@ -221,7 +221,7 @@ function checkPlanCompletion(meta, config) {
     const projectPrs = {};
     const prLinks = getPrLinks();
     for (const p of projects) {
-      const prs = (safeJson(shared.projectPrPath(p)) || [])
+      const prs = safeJsonArr(shared.projectPrPath(p))
         .filter(pr => {
           const linkedIds = prLinks[pr.id] || [];
           return pr.status === PR_STATUS.ACTIVE && linkedIds.some(itemId => doneItems.find(w => w.id === itemId));
@@ -498,7 +498,7 @@ function cleanupPlanWorktrees(planFile, plan, projects, config) {
 
     for (const p of projects) {
       try {
-        const prs = safeJson(shared.projectPrPath(p)) || [];
+        const prs = safeJsonArr(shared.projectPrPath(p));
         const prLinks = getPrLinks();
         for (const pr of prs) {
           const linkedIds = prLinks[pr.id] || [];
@@ -1612,7 +1612,7 @@ function resolveReviewPrContext(pr, project, config, structuredCompletion = null
 
   for (const candidateProject of projectCandidates) {
     const prPath = shared.projectPrPath(candidateProject);
-    const prs = safeJson(prPath) || [];
+    const prs = safeJsonArr(prPath);
     for (const ref of refs) {
       const refUrl = typeof ref === 'object' ? ref.url || '' : String(ref || '');
       if (!shared.isPrCompatibleWithProject(candidateProject, ref, refUrl)) continue;
@@ -1622,7 +1622,7 @@ function resolveReviewPrContext(pr, project, config, structuredCompletion = null
   }
 
   const centralPath = centralPrPath();
-  const centralPrs = safeJson(centralPath) || [];
+  const centralPrs = safeJsonArr(centralPath);
   const centralRefs = reportedPr ? [reportedPr] : refs;
   for (const ref of centralRefs) {
     const target = shared.findPrRecord(centralPrs, ref, null);
@@ -2215,7 +2215,7 @@ function findDependentActivePrs(mergedItemId, config) {
 
   const projects = shared.getProjects(config);
   for (const p of projects) {
-    const prs = safeJson(projectPrPath(p)) || [];
+    const prs = safeJsonArr(projectPrPath(p));
     for (const pr of prs) {
       if (!pr.branch || pr.status !== PR_STATUS.ACTIVE) continue;
       const linked = (pr.prdItems || []).some(id => dependentWis.some(wi => wi.id === id));
@@ -4505,12 +4505,12 @@ function syncPrdFromPrs(config) {
     const allProjects = shared.getProjects(config);
 
     // Exact prdItems match only — no fuzzy matching
-    const allPrs = allProjects.flatMap(p => safeJson(shared.projectPrPath(p)) || []);
+    const allPrs = allProjects.flatMap(p => safeJsonArr(shared.projectPrPath(p)));
 
     let totalReconciled = 0;
     for (const project of allProjects) {
       const wiPath = shared.projectWorkItemsPath(project);
-      const items = safeJson(wiPath) || [];
+      const items = safeJsonArr(wiPath);
       const hasReconcilable = items.some(wi =>
         (wi.status === WI_STATUS.PENDING && !wi._pr) || wi.status === WI_STATUS.FAILED);
       if (!hasReconcilable) continue;

package/engine.js

@@ -94,6 +94,8 @@ const { getProjects, projectRoot, projectStateDir, projectWorkItemsPath, project
 // ─── Utilities ──────────────────────────────────────────────────────────────
 
 const safeJson = shared.safeJson;
+const safeJsonArr = shared.safeJsonArr;
+const safeJsonObj = shared.safeJsonObj;
 const safeJsonNoRestore = shared.safeJsonNoRestore;
 const safeRead = shared.safeRead;
 const safeWrite = shared.safeWrite;
@@ -154,8 +156,6 @@ const { renderPlaybook, validatePlaybookVars, PLAYBOOK_REQUIRED_VARS,
 // through to an interactive `gh auth login` device-code flow.
 const ghToken = require('./engine/gh-token');
 
-// sanitizeBranch imported from shared.js
-
 // ─── Lifecycle (extracted to engine/lifecycle.js) ────────────────────────────
 
 const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, reconcilePrdStatuses, handlePostMerge, checkPlanCompletion,
@@ -559,9 +559,9 @@ function resolveDependencyBranches(depIds, sourcePlan, project, config) {
   // Find PR branches for each dependency work item
   for (const p of projects) {
     const prPath = shared.projectPrPath(p);
-    const prs = safeJson(prPath) || [];
+    const prs = safeJsonArr(prPath);
     for (const pr of prs) {
-      if (!pr.branch || pr.status !== 'active') continue;
+      if (!pr.branch || pr.status !== PR_STATUS.ACTIVE) continue;
       const linked = (pr.prdItems || []).some(id =>
         depWorkItems.find(w => w.id === id)
       );
@@ -1463,10 +1463,10 @@ async function spawnAgent(dispatchItem, config) {
           // Fetch all dependency branches in parallel (git fetches are independent)
           const fetchable = depBranches.filter(d => !_failedRefCache.has(d.branch));
           const unfetchable = depBranches.filter(d => _failedRefCache.has(d.branch));
-          const allPrsForDeps = unfetchable.length > 0 ? shared.getProjects(config).reduce((acc, p) => acc.concat(safeJson(shared.projectPrPath(p)) || []), []) : [];
+          const allPrsForDeps = unfetchable.length > 0 ? shared.getProjects(config).reduce((acc, p) => acc.concat(safeJsonArr(shared.projectPrPath(p))), []) : [];
           for (const { branch: depBranch, prId } of unfetchable) {
             const pr = allPrsForDeps.find(p => p.id === prId);
-            if (pr && (pr.status === 'merged' || pr.status === 'closed')) {
+            if (pr && (pr.status === PR_STATUS.MERGED || pr.status === PR_STATUS.CLOSED)) {
               log('info', `Dependency ${depBranch} (${prId}) already merged — skipping, changes already in main`);
               continue;
             }
@@ -1482,7 +1482,7 @@ async function spawnAgent(dispatchItem, config) {
             )
           );
           const hasFetchFailures = fetchResults.some(r => r.status === 'rejected');
-          const allPrsForFetch = hasFetchFailures ? shared.getProjects(config).reduce((acc, p) => acc.concat(safeJson(shared.projectPrPath(p)) || []), []) : [];
+          const allPrsForFetch = hasFetchFailures ? shared.getProjects(config).reduce((acc, p) => acc.concat(safeJsonArr(shared.projectPrPath(p))), []) : [];
           // Track branches recovered by local-only push so they can be merged
           const recoveredBranches = new Set();
           for (let i = 0; i < fetchResults.length; i++) {
@@ -1491,7 +1491,7 @@ async function spawnAgent(dispatchItem, config) {
               const failedPrId = fetchable[i].prId;
               const errMsg = fetchResults[i].reason?.message || '';
               const pr = allPrsForFetch.find(p => p.id === failedPrId);
-              if (pr && (pr.status === 'merged' || pr.status === 'closed')) {
+              if (pr && (pr.status === PR_STATUS.MERGED || pr.status === PR_STATUS.CLOSED)) {
                 log('info', `Dependency ${failedBranch} (${failedPrId}) already merged — skipping, changes already in main`);
                 continue;
               }
@@ -2079,10 +2079,12 @@ async function spawnAgent(dispatchItem, config) {
       // orphan detector's "logSize > stub-only" check can tell this apart from a
       // hung process. Preserves the diagnostic the prior inline catch wrote.
       try { fs.appendFileSync(liveOutputPath, `[${new Date().toISOString()}] spawn-failed: ${spawnErr.message}\n[process-exit] spawn-failed\n`); } catch { /* cleanup-only best effort */ }
-    } else if (proc && typeof proc.kill === 'function') {
+    } else if (proc && proc.pid) {
       // spawn() returned a handle but a later registration step threw —
-      // kill the orphan child so it doesn't run unmonitored.
-      try { proc.kill('SIGKILL'); } catch { /* already exited */ }
+      // kill the orphan child so it doesn't run unmonitored. shared.killImmediate
+      // recurses into the process tree (footgun #4) — plain proc.kill('SIGKILL')
+      // doesn't on Windows.
+      try { shared.killImmediate(proc); } catch { /* already exited */ }
     }
     if (registeredInActiveProcesses) {
       try { activeProcesses.delete(id); } catch { /* map.delete never throws but be defensive */ }
@@ -3271,10 +3273,6 @@ async function spawnAgent(dispatchItem, config) {
   return proc;
 }
 
-// addToDispatch, isRetryableFailureReason — now in engine/dispatch.js
-
-// completeDispatch — now in engine/dispatch.js
-
 // ─── Dependency Gate ─────────────────────────────────────────────────────────
 // Returns: true (deps met), false (deps pending), 'failed' (dep failed — propagate)
 function areDependenciesMet(item, config) {
@@ -3368,9 +3366,6 @@ function detectDependencyCycles(items) {
   return [...cycleIds];
 }
 
-
-// writeInboxAlert — now in engine/dispatch.js
-
 // Reconciles work items against known PRs.
 // Primary linkage comes from prdItems in pull-requests.json; fallback linkage
 // uses engine/pr-links.json so matching does not depend on branch/title parsing.
@@ -3462,10 +3457,6 @@ function updateSnapshot(config) {
   safeWrite(path.join(IDENTITY_DIR, 'now.md'), snapshot);
 }
 
-// checkIdleThreshold, checkSteering, checkTimeouts — now in engine/timeout.js
-
-// runCleanup — now in engine/cleanup.js
-
 // ─── Cooldowns (extracted to engine/cooldown.js) ─────────────────────────────
 
 const { COOLDOWN_PATH, dispatchCooldowns, loadCooldowns, saveCooldowns,
@@ -3473,16 +3464,6 @@ const { COOLDOWN_PATH, dispatchCooldowns, loadCooldowns, saveCooldowns,
   setCooldownFailure, clearCooldown, getPrReviewCooldownKey, clearLegacyPrReviewCooldown,
   isAlreadyDispatched, isBranchActive } = require('./engine/cooldown');
 
-
-
-/**
- * Scan ~/.minions/plans/ for plan-generated PRD files → queue implement tasks.
- * Plans are project-scoped JSON files written by the plan-to-prd playbook.
- */
-/**
- * Convert plan files into project work items (side-effect, like specs).
- * Plans write to the target project's work-items.json — picked up by discoverFromWorkItems next tick.
- */
 // Auto-clean pending/failed work items for a PRD so they re-materialize with updated plan data
 function autoCleanPrdWorkItems(prdFile, config) {
   const allProjects = getProjects(config);
@@ -3928,7 +3909,7 @@ function materializePlansAsWorkItems(config) {
           if (!alreadyExists) {
             for (const p of allProjects) {
               if (String(p.name || '').toLowerCase() === String(projName || '').toLowerCase()) continue;
-              const otherItems = safeJson(projectWorkItemsPath(p)) || [];
+              const otherItems = safeJsonArr(projectWorkItemsPath(p));
               const otherWi = otherItems.find(w => w.id === item.id);
               if (otherWi) {
                 if (DONE_STATUSES.has(otherWi.status) && shouldReopen) {
@@ -3969,7 +3950,7 @@ function materializePlansAsWorkItems(config) {
 
         if (created > 0) {
           // Reconciliation: exact prdItems match only, scoped to newly created items
-          const allPrsForReconcile = allProjects.flatMap(p => safeJson(projectPrPath(p)) || []);
+          const allPrsForReconcile = allProjects.flatMap(p => safeJsonArr(projectPrPath(p)));
           const reconciled = reconcileItemsWithPrs(existingItems, allPrsForReconcile, { onlyIds: newlyCreatedIds });
           if (reconciled > 0) log('info', `Plan reconciliation: marked ${reconciled} item(s) as done → ${projName}`);
 
@@ -4950,7 +4931,7 @@ function resolveWorkItemPrRecord(item, project) {
   if (!project) return null;
   const prRef = getWorkItemPrRef(item);
   if (!prRef) return null;
-  const prs = safeJson(projectPrPath(project)) || [];
+  const prs = safeJsonArr(projectPrPath(project));
   shared.normalizePrRecords(prs, project);
   return shared.findPrRecord(prs, prRef, project);
 }
@@ -5037,7 +5018,7 @@ function discoverFromWorkItems(config, project) {
   }
 
   const root = project?.localPath ? path.resolve(project.localPath) : path.resolve(MINIONS_DIR, '..');
-  const items = safeJson(projectWorkItemsPath(project)) || [];
+  const items = safeJsonArr(projectWorkItemsPath(project));
   const cooldownMs = (src.cooldownMinutes || 0) * 60 * 1000;
   const newWork = [];
   // PRD sync for dispatched status deferred to spawnAgent success (#480)
@@ -5587,7 +5568,7 @@ function extractSpecInfo(filePath, projectRoot_) {
  */
 function discoverCentralWorkItems(config) {
   const centralPath = path.join(MINIONS_DIR, 'work-items.json');
-  const items = safeJson(centralPath) || [];
+  const items = safeJsonArr(centralPath);
   const projects = getProjects(config);
   const dispatchProjects = getCentralDispatchProjects(projects);
   const newWork = [];
@@ -6095,11 +6076,11 @@ async function discoverWork(config) {
           // readdir and read (e.g. concurrent archive), do not resurrect it
           // from a stale .backup sidecar (W-mouptdh1000h9f39).
           const plan = safeJsonNoRestore(path.join(prdDir, f));
-          if (!plan?.missing_features || plan.status === 'completed') {
-            if (plan?.status === 'completed') completedPlanCache.add(f);
+          if (!plan?.missing_features || plan.status === PLAN_STATUS.COMPLETED) {
+            if (plan?.status === PLAN_STATUS.COMPLETED) completedPlanCache.add(f);
             continue;
           }
-          if (plan.status !== 'approved' && plan.status !== 'active') continue;
+          if (plan.status !== PLAN_STATUS.APPROVED && plan.status !== PLAN_STATUS.ACTIVE) continue;
           // Simulate the meta object checkPlanCompletion expects
           const completed = lifecycle.checkPlanCompletion({ item: { sourcePlan: f } }, config);
           if (completed) completedPlanCache.add(f);
@@ -6407,14 +6388,14 @@ async function tickInner() {
       const projects = getProjects(config);
       const pullRequests = projects.flatMap(p => {
         const prPath = path.join(MINIONS_DIR, 'projects', p.name, 'pull-requests.json');
-        return safeJson(prPath) || [];
+        return safeJsonArr(prPath);
       });
       const workItems = projects.flatMap(p => {
         const wiPath = path.join(MINIONS_DIR, 'projects', p.name, 'work-items.json');
-        return safeJson(wiPath) || [];
+        return safeJsonArr(wiPath);
       });
       // Also include central work items
-      const centralWi = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
+      const centralWi = safeJsonArr(path.join(MINIONS_DIR, 'work-items.json'));
 
       // Gather state for the new generalized target types. Each block is
       // best-effort — if a module/file is missing the watch evaluator will
@@ -6438,7 +6419,7 @@ async function tickInner() {
       } catch { /* optional */ }
 
       let scheduleRuns = {};
-      try { scheduleRuns = safeJson(path.join(MINIONS_DIR, 'engine', 'schedule-runs.json')) || {}; } catch { /* optional */ }
+      try { scheduleRuns = safeJsonObj(path.join(MINIONS_DIR, 'engine', 'schedule-runs.json')); } catch { /* optional */ }
 
       let pipelineRuns = {};
       try { pipelineRuns = require('./engine/pipeline').getPipelineRuns(); } catch { /* optional */ }
@@ -6508,10 +6489,10 @@ async function tickInner() {
           continue;
         }
         const plan = safeJson(path.join(PRD_DIR, file));
-        if (plan && plan.missing_features && plan.status !== 'completed') {
+        if (plan && plan.missing_features && plan.status !== PLAN_STATUS.COMPLETED) {
           const completed = checkPlanCompletion({ item: { sourcePlan: file } }, config);
           if (completed) completedPlanCache.add(file);
-        } else if (plan?.status === 'completed') {
+        } else if (plan?.status === PLAN_STATUS.COMPLETED) {
           completedPlanCache.add(file);
         }
       }

package/package.json

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