@yemi33/minions 0.1.315 → 0.1.317

package/CHANGELOG.md

@@ -1,11 +1,14 @@
 # Changelog
 
-## 0.1.315 (2026-04-03)
+## 0.1.317 (2026-04-03)
 
 ### Fixes
+-  deduplicate PRs in pull-requests.json on write
 -  show reviewer names in dashboard Signed Off By column
 
 ### Other
+- refactor: use constants in lifecycle.js and timeout.js
+- refactor: extract status/type/result constants to shared.js
 - cleanup: remove evaluate.md (re-created by agents), fix stale references
 - perf: CC message handling — debounce localStorage, cap array, batch scroll
 

package/engine/cleanup.js

@@ -433,7 +433,7 @@ function runCleanup(config, verbose = false) {
 
   // 6. Migrate legacy work-item statuses to canonical values
   // in-pr, implemented, complete → done (one-time correction per item)
-  const LEGACY_DONE_STATUSES = new Set(['in-pr', 'implemented', 'complete']);
+  const LEGACY_DONE_STATUSES = shared.DONE_STATUSES;
   for (const project of projects) {
     try {
       const wiPath = projectWorkItemsPath(project);

package/engine/dispatch.js

@@ -10,7 +10,8 @@ const queries = require('./queries');
 const { setCooldownFailure } = require('./cooldown');
 
 const { safeJson, safeWrite, safeReadDir, mutateJsonFileLocked,
-  getProjects, projectWorkItemsPath, log, ts, dateStamp } = shared;
+  getProjects, projectWorkItemsPath, log, ts, dateStamp,
+  WI_STATUS, DISPATCH_RESULT, ENGINE_DEFAULTS } = shared;
 const { getConfig, getDispatch, DISPATCH_PATH, INBOX_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -65,7 +66,7 @@ function isRetryableFailureReason(reason = '') {
 
 // ─── Complete Dispatch ───────────────────────────────────────────────────────
 
-function completeDispatch(id, result = 'success', reason = '', resultSummary = '', opts = {}) {
+function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', resultSummary = '', opts = {}) {
   const { processWorkItemFailure = true } = opts;
   let item = null;
 
@@ -98,9 +99,9 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
 
     // Update source work item status on failure + auto-retry with backoff
     const retryableFailure = isRetryableFailureReason(reason);
-    if (result === 'error' && item.meta?.dispatchKey && retryableFailure) setCooldownFailure(item.meta.dispatchKey);
+    if (result === DISPATCH_RESULT.ERROR && item.meta?.dispatchKey && retryableFailure) setCooldownFailure(item.meta.dispatchKey);
 
-    if (processWorkItemFailure && result === 'error' && item.meta?.item?.id) {
+    if (processWorkItemFailure && result === DISPATCH_RESULT.ERROR && item.meta?.item?.id) {
       let retries = (item.meta.item._retryCount || 0);
       try {
         const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
@@ -112,8 +113,9 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
           if (wi) retries = wi._retryCount || 0;
         }
       } catch (e) { log('warn', 'read retry count: ' + e.message); }
-      if (retryableFailure && retries < 3) {
-        log('info', `Dispatch error for ${item.meta.item.id} — auto-retry ${retries + 1}/3`);
+      const maxRetries = ENGINE_DEFAULTS.maxRetries;
+      if (retryableFailure && retries < maxRetries) {
+        log('info', `Dispatch error for ${item.meta.item.id} — auto-retry ${retries + 1}/${maxRetries}`);
         lifecycle().updateWorkItemStatus(item.meta, 'pending', '');
         // Remove this dispatch key from completed so dedupe doesn't block immediate redispatch.
         if (item.meta?.dispatchKey) {
@@ -132,9 +134,9 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
           if (wiPath) {
             const items = safeJson(wiPath) || [];
             const wi = items.find(i => i.id === item.meta.item.id);
-            if (wi && wi.status !== 'paused') {
+            if (wi && wi.status !== WI_STATUS.PAUSED) {
               wi._retryCount = retries + 1;
-              wi.status = 'pending';
+              wi.status = WI_STATUS.PENDING;
               wi._lastRetryReason = reason || '';
               wi._lastRetryAt = ts();
               delete wi.failReason;
@@ -148,7 +150,7 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
       } else {
         const finalReason = !retryableFailure
           ? `Non-retryable failure: ${reason || 'Unknown error'}`
-          : (reason || 'Failed after 3 retries');
+          : (reason || `Failed after ${maxRetries} retries`);
         lifecycle().updateWorkItemStatus(item.meta, 'failed', finalReason);
         // Alert: find items blocked by this failure and write inbox note
         try {
@@ -157,11 +159,11 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
           const blockedItems = [];
           for (const p of getProjects(config)) {
             const items = safeJson(projectWorkItemsPath(p)) || [];
-            items.filter(w => w.status === 'pending' && (w.depends_on || []).includes(failedId))
+            items.filter(w => w.status === WI_STATUS.PENDING && (w.depends_on || []).includes(failedId))
               .forEach(w => blockedItems.push(`- \`${w.id}\` — ${w.title}`));
           }
           const centralItems = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-          centralItems.filter(w => w.status === 'pending' && (w.depends_on || []).includes(failedId))
+          centralItems.filter(w => w.status === WI_STATUS.PENDING && (w.depends_on || []).includes(failedId))
             .forEach(w => blockedItems.push(`- \`${w.id}\` — ${w.title}`));
 
           writeInboxAlert(`failed-${failedId}`,

package/engine/lifecycle.js

@@ -8,7 +8,8 @@ const path = require('path');
 const os = require('os');
 const shared = require('./shared');
 const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, execSilent, projectPrPath, getPrLinks, addPrLink,
-  log, ts, dateStamp } = shared;
+  log, ts, dateStamp, WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
+  ENGINE_DEFAULTS } = shared;
 const { trackEngineUsage } = require('./llm');
 const queries = require('./queries');
 const { getConfig, getInboxFiles, getNotes, getPrs, getDispatch,
@@ -57,7 +58,7 @@ function checkPlanCompletion(meta, config) {
   const unmaterialized = [...planFeatureIds].filter(id => {
     if (workItemById[id]) return false;
     const prdItem = (plan.missing_features || []).find(f => f.id === id);
-    return !(prdItem && (prdItem.status === 'done' || prdItem.status === 'in-pr'));
+    return !(prdItem && DONE_STATUSES.has(prdItem.status));
   });
   if (unmaterialized.length > 0) {
     log('info', `Plan ${planFile}: ${unmaterialized.length}/${planFeatureIds.size} feature(s) not yet materialized as work items: ${unmaterialized.join(', ')}`);
@@ -67,17 +68,17 @@ function checkPlanCompletion(meta, config) {
   // Check 2: every feature's work item must be done (or PRD item marked done externally)
   const notDone = [...planFeatureIds].filter(id => {
     const w = workItemById[id];
-    if (w && (w.status === 'done' || w.status === 'in-pr')) return false; // in-pr accepted for backward compat
+    if (w && DONE_STATUSES.has(w.status)) return false;
     const prdItem = (plan.missing_features || []).find(f => f.id === id);
-    return !(prdItem && (prdItem.status === 'done' || prdItem.status === 'in-pr'));
+    return !(prdItem && DONE_STATUSES.has(prdItem.status));
   });
   if (notDone.length > 0) {
     log('info', `Plan ${planFile}: waiting for done on ${notDone.length}/${planFeatureIds.size} item(s): ${notDone.join(', ')}`);
     return;
   }
 
-  const doneItems = planItems.filter(w => w.status === 'done' || w.status === 'in-pr');
-  const failedItems = planItems.filter(w => w.status === 'failed');
+  const doneItems = planItems.filter(w => DONE_STATUSES.has(w.status));
+  const failedItems = planItems.filter(w => w.status === WI_STATUS.FAILED);
 
   // 1. Mark plan as completed
   plan.status = 'completed';
@@ -490,20 +491,20 @@ function updateWorkItemStatus(meta, status, reason) {
       target.agentResults[agent] = { status, completedAt: ts(), reason: reason || undefined };
 
       const results = Object.values(target.agentResults);
-      const anySuccess = results.some(r => r.status === 'done');
+      const anySuccess = results.some(r => r.status === WI_STATUS.DONE);
       const allDone = Array.isArray(target.fanOutAgents) && target.fanOutAgents.length > 0 ? results.length >= target.fanOutAgents.length : false;
       const dispatchAge = target.dispatched_at ? Date.now() - new Date(target.dispatched_at).getTime() : 0;
       const timedOut = !allDone && dispatchAge > 6 * 60 * 60 * 1000 && results.length > 0;
 
       if (anySuccess) {
-        target.status = 'done';
+        target.status = WI_STATUS.DONE;
         delete target.failReason;
         delete target.failedAt;
         target.completedAgents = Object.entries(target.agentResults)
-          .filter(([, r]) => r.status === 'done')
+          .filter(([, r]) => r.status === WI_STATUS.DONE)
           .map(([a]) => a);
       } else if (allDone || timedOut) {
-        target.status = 'failed';
+        target.status = WI_STATUS.FAILED;
         target.failReason = timedOut
           ? `Fan-out timed out: ${results.length}/${(target.fanOutAgents || []).length} agents reported (all failed)`
           : 'All fan-out agents failed';
@@ -511,11 +512,11 @@ function updateWorkItemStatus(meta, status, reason) {
       }
     } else {
       target.status = status;
-      if (status === 'done') {
+      if (status === WI_STATUS.DONE) {
         delete target.failReason;
         delete target.failedAt;
         target.completedAt = ts();
-      } else if (status === 'failed') {
+      } else if (status === WI_STATUS.FAILED) {
         if (reason) target.failReason = reason;
         target.failedAt = ts();
       }
@@ -643,6 +644,9 @@ function syncPrsFromOutput(output, agentId, meta, config) {
   for (const [name, { prPath, prIds }] of targetPrIds) {
     mutateJsonFileLocked(prPath, (prs) => {
       if (!Array.isArray(prs)) prs = [];
+      // Deduplicate any existing entries with same id (case-insensitive agent name race)
+      const seen = new Set();
+      prs = prs.filter(p => { const k = String(p.id); if (seen.has(k)) return false; seen.add(k); return true; });
       for (const { prId, fullId } of prIds) {
         if (prs.some(p => p.id === fullId || String(p.id) === String(prId))) continue;
 
@@ -981,7 +985,7 @@ function updateMetrics(agentId, dispatchItem, result, taskUsage, prsCreatedCount
   m.lastTask = dispatchItem.task;
   m.lastCompleted = ts();
   if (model) m.model = model;
-  if (result === 'success') {
+  if (result === DISPATCH_RESULT.SUCCESS) {
     m.tasksCompleted++;
     if (prsCreatedCount > 0) m.prsCreated = (m.prsCreated || 0) + prsCreatedCount;
     if (dispatchItem.type === 'review') m.reviewsDone++;
@@ -1105,7 +1109,7 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
   const type = dispatchItem.type;
   const meta = dispatchItem.meta;
   const isSuccess = code === 0;
-  const result = isSuccess ? 'success' : 'error';
+  const result = isSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR;
   const { resultSummary, taskUsage, sessionId, model } = parseAgentOutput(stdout);
 
   // Save session for potential resume on next dispatch
@@ -1141,9 +1145,10 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
       }
     } catch { /* optional */ }
 
-    if (retries < 3) {
-      log('info', `Agent failed for ${meta.item.id} — auto-retry ${retries + 1}/3`);
-      updateWorkItemStatus(meta, 'pending', '');
+    const maxRetries = ENGINE_DEFAULTS.maxRetries;
+    if (retries < maxRetries) {
+      log('info', `Agent failed for ${meta.item.id} — auto-retry ${retries + 1}/${maxRetries}`);
+      updateWorkItemStatus(meta, WI_STATUS.PENDING, '');
       try {
         const wiPath = meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout'
           ? path.join(MINIONS_DIR, 'work-items.json')
@@ -1152,14 +1157,14 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
           const items = safeJson(wiPath) || [];
           const wi = items.find(i => i.id === meta.item.id);
           if (wi) {
-            wi._retryCount = retries + 1; wi.status = 'pending'; delete wi.dispatched_at; delete wi.dispatched_to;
-            if (type === 'decompose') delete wi._decomposing; // clear so item can retry decomposition
+            wi._retryCount = retries + 1; wi.status = WI_STATUS.PENDING; delete wi.dispatched_at; delete wi.dispatched_to;
+            if (type === WORK_TYPE.DECOMPOSE) delete wi._decomposing;
             shared.safeWrite(wiPath, items);
           }
         }
       } catch (err) { log('warn', `Retry update: ${err.message}`); }
     } else {
-      updateWorkItemStatus(meta, 'failed', 'Agent failed (3 retries exhausted)');
+      updateWorkItemStatus(meta, WI_STATUS.FAILED, `Agent failed (${maxRetries} retries exhausted)`);
     }
     // Clear _decomposing flag on failure so item doesn't get permanently stuck
     if (type === 'decompose') {
@@ -1258,15 +1263,16 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
           wi.noPr = true;
           wi.failReason = 'Completed without creating a pull request';
           const retries = wi._retryCount || 0;
-          if (retries < 3) {
-            wi.status = 'pending';
+          const maxR = ENGINE_DEFAULTS.maxRetries;
+          if (retries < maxR) {
+            wi.status = WI_STATUS.PENDING;
             wi._retryCount = retries + 1;
             delete wi.dispatched_at;
             delete wi.dispatched_to;
-            e.log('info', `Auto-retry ${retries + 1}/3 for ${meta.item.id} (no PR created)`);
+            e.log('info', `Auto-retry ${retries + 1}/${maxR} for ${meta.item.id} (no PR created)`);
           } else {
-            wi.status = 'failed';
-            e.log('warn', `${meta.item.id} failed after 3 retries — no PR created`);
+            wi.status = WI_STATUS.FAILED;
+            e.log('warn', `${meta.item.id} failed after ${maxR} retries — no PR created`);
           }
           shared.safeWrite(wiPath, items);
         }

package/engine/shared.js

@@ -386,8 +386,29 @@ const ENGINE_DEFAULTS = {
   evalLoop: true, // enable review→fix loop after implementation completes
   evalMaxIterations: 3, // max review→fix cycles before escalating to human
   evalMaxCost: null, // USD ceiling per work item across all eval iterations; null = no limit (gather baseline data first)
+  maxRetries: 3, // max dispatch retries before marking work item as failed
 };
 
+// ─── Status & Type Constants ─────────────────────────────────────────────────
+
+const WI_STATUS = {
+  PENDING: 'pending', DISPATCHED: 'dispatched', DONE: 'done', FAILED: 'failed',
+  PAUSED: 'paused', QUEUED: 'queued', NEEDS_REVIEW: 'needs-human-review', DECOMPOSED: 'decomposed',
+};
+const DONE_STATUSES = new Set([WI_STATUS.DONE, 'in-pr', 'implemented', 'complete']); // includes legacy aliases
+const WORK_TYPE = {
+  IMPLEMENT: 'implement', IMPLEMENT_LARGE: 'implement:large', FIX: 'fix', REVIEW: 'review',
+  VERIFY: 'verify', PLAN: 'plan', PLAN_TO_PRD: 'plan-to-prd', DECOMPOSE: 'decompose',
+  MEETING: 'meeting', EXPLORE: 'explore', ASK: 'ask', TEST: 'test', DOCS: 'docs',
+};
+const PLAN_STATUS = {
+  ACTIVE: 'active', AWAITING_APPROVAL: 'awaiting-approval', APPROVED: 'approved',
+  PAUSED: 'paused', REJECTED: 'rejected', COMPLETED: 'completed',
+  REVISION_REQUESTED: 'revision-requested',
+};
+const PR_STATUS = { ACTIVE: 'active', MERGED: 'merged', ABANDONED: 'abandoned', CLOSED: 'closed' };
+const DISPATCH_RESULT = { SUCCESS: 'success', ERROR: 'error', TIMEOUT: 'timeout' };
+
 const DEFAULT_AGENTS = {
   ripley:  { name: 'Ripley',  emoji: '\u{1F3D7}\uFE0F',  role: 'Lead / Explorer', skills: ['architecture', 'codebase-exploration', 'design-review'] },
   dallas:  { name: 'Dallas',  emoji: '\u{1F527}',  role: 'Engineer', skills: ['implementation', 'typescript', 'docker', 'testing'] },
@@ -617,6 +638,7 @@ module.exports = {
   KB_CATEGORIES,
   classifyInboxItem,
   ENGINE_DEFAULTS,
+  WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
   DEFAULT_AGENTS,
   DEFAULT_CLAUDE,
   getProjects,

package/engine/timeout.js

@@ -8,7 +8,8 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeRead, safeWrite, safeJson, getProjects, projectWorkItemsPath, log, ts, ENGINE_DEFAULTS: DEFAULTS } = shared;
+const { safeRead, safeWrite, safeJson, getProjects, projectWorkItemsPath, log, ts,
+  ENGINE_DEFAULTS: DEFAULTS, WI_STATUS, DISPATCH_RESULT } = shared;
 const { getDispatch, getAgentStatus } = queries;
 const AGENTS_DIR = queries.AGENTS_DIR;
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -140,7 +141,7 @@ function checkTimeouts(config) {
           safeWrite(outputLogPath, `# Output for dispatch ${item.id}\n# Exit code: ${isSuccess ? 0 : 1}\n# Completed: ${ts()}\n# Detected via output scan\n\n## Result\n${text || '(no text)'}\n`);
         } catch (e) { log('warn', 'parse output result: ' + e.message); }
 
-        completeDispatch(item.id, isSuccess ? 'success' : 'error', 'Completed (detected from output)');
+        completeDispatch(item.id, isSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR, 'Completed (detected from output)');
 
         // Run post-completion hooks via shared helper
         runPostCompletionHooks(item, item.agent, isSuccess ? 0 : 1, liveLog, config);
@@ -215,7 +216,7 @@ function checkTimeouts(config) {
 
   // Clean up dead items
   for (const { item, reason } of deadItems) {
-    completeDispatch(item.id, 'error', reason);
+    completeDispatch(item.id, DISPATCH_RESULT.ERROR, reason);
   }
 
   // Agent status is now derived from dispatch.json at read time (getAgentStatus).
@@ -232,7 +233,7 @@ function checkTimeouts(config) {
     if (!items || !Array.isArray(items)) continue;
     let changed = false;
     for (const item of items) {
-      if (item.status !== 'dispatched') continue;
+      if (item.status !== WI_STATUS.DISPATCHED) continue;
       // Check if any active dispatch references this item
       // Dispatch keys include project name: work-{project}-{id} or central-work-{id}
       const projectNames = getProjects(config).map(p => p.name);
@@ -244,19 +245,20 @@ function checkTimeouts(config) {
         (dispatchData.active || []).some(d => d.meta?.item?.id === item.id);
       if (!isActive) {
         // Don't revive items that were explicitly failed for non-retryable reasons
-        if (item.status === 'failed' && item.failReason && !item.failReason.includes('Agent died')) continue;
+        if (item.status === WI_STATUS.FAILED && item.failReason && !item.failReason.includes('Agent died')) continue;
         const retries = (item._retryCount || 0);
-        if (retries < 3) {
-          log('info', `Reconcile: work item ${item.id} agent died — auto-retry ${retries + 1}/3`);
-          item.status = 'pending';
+        const maxRetries = DEFAULTS.maxRetries;
+        if (retries < maxRetries) {
+          log('info', `Reconcile: work item ${item.id} agent died — auto-retry ${retries + 1}/${maxRetries}`);
+          item.status = WI_STATUS.PENDING;
           item._retryCount = retries + 1;
           delete item.dispatched_at;
           delete item.dispatched_to;
           delete item._pendingReason;
         } else {
           log('warn', `Reconcile: work item ${item.id} failed after ${retries} retries — marking as failed`);
-          item.status = 'failed';
-          item.failReason = 'Agent died or was killed (3 retries exhausted)';
+          item.status = WI_STATUS.FAILED;
+          item.failReason = `Agent died or was killed (${maxRetries} retries exhausted)`;
           item.failedAt = ts();
           delete item._pendingReason;
         }

package/engine.js

@@ -24,7 +24,8 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./engine/shared');
-const { exec, execSilent, runFile, ENGINE_DEFAULTS: DEFAULTS } = shared;
+const { exec, execSilent, runFile, ENGINE_DEFAULTS: DEFAULTS,
+  WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, DISPATCH_RESULT } = shared;
 const queries = require('./engine/queries');
 
 // ─── Paths ──────────────────────────────────────────────────────────────────
@@ -754,7 +755,7 @@ function areDependenciesMet(item, config) {
     } catch (e) { log('warn', 'read project work items for deps: ' + e.message); }
   }
   // PRD item statuses that count as "done" for dep resolution
-  const PRD_MET_STATUSES = new Set(['done', 'in-pr', 'implemented', 'complete']);
+  const PRD_MET_STATUSES = DONE_STATUSES;
 
   for (const depId of deps) {
     const depItem = allWorkItems.find(w => w.id === depId);

package/package.json

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