@yemi33/minions 0.1.2277 → 0.1.2279

package/dashboard.js

@@ -588,10 +588,18 @@ let _prRefVerifierOverride = null;   // test seam
 
 // Evict stale entries when the cache exceeds _PR_REF_VERIFY_CACHE_MAX to prevent
 // unbounded growth. Called after every Map.set() in verifyLoosePrRefIsPr.
+// Two-pass strategy: (1) evict TTL-expired entries; (2) if still over cap,
+// evict the oldest entries (LRU) until the cache is back within bounds.
 function _evictPrRefVerifyCacheIfNeeded() {
   if (_prRefVerifyCache.size <= _PR_REF_VERIFY_CACHE_MAX) return;
+  // Pass 1: evict TTL-expired entries.
   const cutoff = Date.now() - _PR_REF_VERIFY_TTL_MS;
   for (const [k, v] of _prRefVerifyCache) if (v.at < cutoff) _prRefVerifyCache.delete(k);
+  // Pass 2: LRU fallback — evict oldest entries if still over cap (e.g. burst of fresh entries).
+  if (_prRefVerifyCache.size <= _PR_REF_VERIFY_CACHE_MAX) return;
+  const toEvict = _prRefVerifyCache.size - _PR_REF_VERIFY_CACHE_MAX;
+  const sorted = [..._prRefVerifyCache.entries()].sort((a, b) => a[1].at - b[1].at);
+  for (let i = 0; i < toEvict; i++) _prRefVerifyCache.delete(sorted[i][0]);
 }
 
 // Test seam (issue #246) — inject a fake verifier so handler tests can assert

package/docs/deprecated.json

@@ -223,6 +223,8 @@
     "id": "ado-throttle-arg-less-shim",
     "description": "Arg-less form of isAdoThrottled() in engine/ado.js. Introduced by W-mq03l6zh0006f0a1-b as a back-compat shim during the per-org ADO throttle isolation rollout: pre-rollout, isAdoThrottled() collapsed the single process-global tracker to one boolean; post-rollout, the canonical form is isAdoThrottled(orgBase) against the per-org Map. The arg-less call site is preserved transiently so engine code (and any in-process callers) that haven't yet been threaded through with a per-org `orgBase` keep returning the safe global-OR (true if ANY org is currently throttled) — preventing a regression where new poll work bypasses a still-warm throttle backoff on an unrelated noisy org.",
     "deprecated": "2026-06-04",
+    "status": "removed",
+    "removedDate": "2026-06-25",
     "code": [
       {
         "file": "engine/ado.js",

package/engine/ado.js

@@ -2630,18 +2630,13 @@ async function fetchSinglePrBuildStatus(project, prNumber) {
 
 // ─── ADO Throttle Queries ────────────────────────────────────────────────────
 
-/** Returns true if ADO is throttled. If orgBase is provided, checks that org's
- *  tracker only; if omitted, returns true when ANY tracked org is throttled
- *  (back-compat OR semantics for existing call sites). Auto-clears stale state. */
+/** Returns true if the given org is currently throttled. Auto-clears stale state.
+ *  orgBase is required — callers must pass shared.getAdoOrgBase(project).
+ *  (The arg-less back-compat OR shim was removed: docs/deprecated.json id: ado-throttle-arg-less-shim) */
 const isAdoThrottled = (orgBase) => {
-  if (orgBase != null) {
-    const tracker = _adoThrottlesByOrg.get(canonicalAdoOrgKey(orgBase));
-    return tracker ? tracker.isThrottled() : false;
-  }
-  for (const tracker of _adoThrottlesByOrg.values()) {
-    if (tracker.isThrottled()) return true;
-  }
-  return false;
+  if (orgBase == null) throw new TypeError('isAdoThrottled requires an orgBase argument');
+  const tracker = _adoThrottlesByOrg.get(canonicalAdoOrgKey(orgBase));
+  return tracker ? tracker.isThrottled() : false;
 };
 
 /** Returns a snapshot of the throttle state.

package/engine/lifecycle.js

@@ -5353,6 +5353,8 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       try { stampPrdItemWorkItemId(meta.item.id, meta.item.sourcePlan); } catch (err) { log('warn', `stampPrdItemWorkItemId: ${err.message}`); }
     }
     promoteCompletionArtifacts(meta, agentId, dispatchItem.id, structuredCompletion, { resultSummary });
+    // M003 — auto-dispatch a live-validation WI when a coding WI completes.
+    try { autoDispatchLiveValidationWi(meta, config); } catch (err) { log('warn', `autoDispatchLiveValidationWi: ${err.message}`); }
   }
   // Failure retry is handled by completeDispatch in dispatch.js — not duplicated here.
   // Only clear _decomposing flag on failure so decompose items don't get permanently stuck.
@@ -6124,6 +6126,78 @@ function pruneScopeMismatchDuplicatePrs(config) {
   return { pruned, scanned };
 }
 
+// M003 — After a coding WI completes successfully, auto-dispatch a live-validation
+// WI when project.liveValidation.autoDispatch === true and the completed item is
+// a coding WI (not the validation type itself). Skips if the coding WI has no PR.
+// Deduplicates: a non-terminal WI with meta.liveValidationFor === codingWiId
+// blocks a second dispatch.
+function autoDispatchLiveValidationWi(meta, config) {
+  const item = meta?.item;
+  if (!item?.id || !item?.type) return;
+
+  const projectName = meta?.project?.name;
+  if (!projectName) return;
+
+  // Look up the full project config (which carries liveValidation) from config.
+  const projects = shared.getProjects(config || {});
+  const project = projects.find(p => p && p.name === projectName);
+  if (!project) return;
+
+  const lv = project.liveValidation;
+  if (!lv || lv.autoDispatch !== true || !lv.type) return;
+
+  // Only auto-dispatch for coding WIs — skip if this IS the validation type.
+  if (item.type === lv.type) return;
+
+  // Resolve PR reference: prefer the canonical stamped _pr field (set by
+  // stampWiPrRef which runs earlier in runPostCompletionHooks), then fall
+  // back to extractWorkItemPrRef for structured fields / references[].
+  const prRef = item._pr || item._prUrl || shared.extractWorkItemPrRef(item) || null;
+  if (!prRef) return;
+
+  const codingWiId = item.id;
+  const wiPath = resolveWorkItemPath(meta);
+  if (!wiPath) return;
+
+  try {
+    mutateWorkItems(wiPath, items => {
+      if (!Array.isArray(items)) return items;
+
+      // Dedup: skip if a non-terminal WI already tracks this coding WI.
+      const existing = items.find(i =>
+        i &&
+        i.meta &&
+        i.meta.liveValidationFor === codingWiId &&
+        !PLAN_TERMINAL_STATUSES.has(i.status)
+      );
+      if (existing) {
+        log('info', `liveValidation: dedup — non-terminal validation WI ${existing.id} already exists for ${codingWiId}`);
+        return items;
+      }
+
+      const validationWi = {
+        id: 'W-' + shared.uid(),
+        title: 'Validate: ' + (item.title || codingWiId),
+        type: lv.type,
+        status: WI_STATUS.PENDING,
+        depends_on: [codingWiId],
+        references: [prRef],
+        meta: { liveValidationFor: codingWiId },
+        project: projectName,
+        priority: item.priority || 'medium',
+        created: ts(),
+        createdBy: 'lifecycle:live-validation-auto-dispatch',
+      };
+
+      items.push(validationWi);
+      log('info', `liveValidation: auto-dispatched validation WI ${validationWi.id} (type=${lv.type}) for coding WI ${codingWiId}`);
+      return items;
+    });
+  } catch (err) {
+    log('warn', `autoDispatchLiveValidationWi for ${codingWiId}: ${err.message}`);
+  }
+}
+
 module.exports = {
   checkPlanCompletion,
   archivePlan,
@@ -6198,4 +6272,6 @@ module.exports = {
   // W-mqtplpk6001oe6d5 — stamp PR ref + workItemId onto WI and PRD item at completion time.
   stampWiPrRef,
   stampPrdItemWorkItemId,
+  // M003 — auto-dispatch live-validation WI after coding WI completion.
+  autoDispatchLiveValidationWi,
 };

package/engine/preflight.js

@@ -626,14 +626,18 @@ function doctor(minionsHome) {
     runtimeResults.push({ name: 'Engine', ok: 'warn', message: 'not started — run: minions start (see docs/engine-restart.md)' });
   }
 
-  // Check dashboard (try HTTP)
+  // Check dashboard (try HTTP). Read the actual bound port from the
+  // dashboard-port.json beacon so the probe works when the dashboard falls
+  // back to a non-default port after EADDRINUSE scanning.
   const http = require('http');
+  const beaconData = shared.readDashboardPortFile(minionsHome);
+  const dashPort = (beaconData && beaconData.port) || shared.DEFAULT_DASHBOARD_PORT;
   const dashCheck = new Promise(resolve => {
-    const req = http.get('http://localhost:7331/api/health', { timeout: 2000 }, res => {
-      resolve({ name: 'Dashboard', ok: true, message: 'running on http://localhost:7331' });
+    const req = http.get(`http://localhost:${dashPort}/api/health`, { timeout: 2000 }, res => {
+      resolve({ name: 'Dashboard', ok: true, message: `running on http://localhost:${dashPort}` });
     });
-    req.on('error', () => resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash (see docs/engine-restart.md)' }));
-    req.on('timeout', () => { req.destroy(); resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash (see docs/engine-restart.md)' }); });
+    req.on('error', () => resolve({ name: 'Dashboard', ok: 'warn', message: `not reachable on :${dashPort} — run: minions dash (see docs/engine-restart.md)` }));
+    req.on('timeout', () => { req.destroy(); resolve({ name: 'Dashboard', ok: 'warn', message: `not reachable on :${dashPort} — run: minions dash (see docs/engine-restart.md)` }); });
   });
 
   return dashCheck.then(async dashResult => {
@@ -649,9 +653,9 @@ function doctor(minionsHome) {
       runtimeResults.push({ name: 'Playbooks', ok: false, message: 'no playbooks found in playbooks/ — run: minions init --force (see docs/distribution.md)' });
     }
 
-    // Check port 7331 availability (only if dashboard isn't running)
+    // Check port availability (only if dashboard isn't running)
     if (dashResult.ok !== true) {
-      runtimeResults.push({ name: 'Port 7331', ok: 'warn', message: 'dashboard not running — port status unknown (see docs/engine-restart.md)' });
+      runtimeResults.push({ name: `Port ${dashPort}`, ok: 'warn', message: `dashboard not running — port status unknown (see docs/engine-restart.md)` });
     }
 
     // Self-check the out-of-process recovery net. A registered-but-broken

package/engine/restart-health.js

@@ -15,7 +15,7 @@ const shared = require('./shared');
 // the literal is only a fallback if shared somehow failed to load.
 const DEFAULT_RESTART_HEALTH_TIMEOUT_MS =
   (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.restartHealthTimeoutMs) || 60000;
-const DEFAULT_RESTART_HEALTH_INTERVAL_MS = 250;
+const DEFAULT_RESTART_HEALTH_INTERVAL_MS = 100;
 // Consecutive dead-PID reads tolerated before fail-fast. A small guard avoids
 // a single flaky tasklist / kill(0) false-negative aborting a healthy boot.
 const DEFAULT_DEAD_POLLS_BEFORE_FAST_FAIL = 2;
@@ -45,7 +45,7 @@ function isProcessAlive(pid) {
       const out = execSync(`tasklist /FI "PID eq ${n}" /NH`, {
         encoding: 'utf8',
         windowsHide: true,
-        timeout: 3000,
+        timeout: 1000,
       });
       return new RegExp(`\\b${n}\\b`).test(out) && out.toLowerCase().includes('node');
     }
@@ -61,8 +61,8 @@ function isPortListening(port) {
   if (!Number.isInteger(n) || n <= 0) return false;
   try {
     if (process.platform === 'win32') {
-      const out = execSync(`netstat -ano -p TCP`, {
-        encoding: 'utf8', windowsHide: true, timeout: 3000, maxBuffer: 4 * 1024 * 1024,
+      const out = execSync(`netstat -ano | findstr ":${n} "`, {
+        encoding: 'utf8', windowsHide: true, timeout: 1000, maxBuffer: 64 * 1024, shell: true,
       });
       const re = new RegExp(`\\s127\\.0\\.0\\.1:${n}\\s+\\S+\\s+LISTENING`, 'i');
       const re6 = new RegExp(`\\s\\[::1?\\]:${n}\\s+\\S+\\s+LISTENING`, 'i');
@@ -70,12 +70,12 @@ function isPortListening(port) {
     }
     try {
       const out = execSync(`lsof -nP -iTCP:${n} -sTCP:LISTEN`, {
-        encoding: 'utf8', timeout: 3000,
+        encoding: 'utf8', timeout: 1000,
       });
       if (/\bLISTEN\b/i.test(out)) return true;
     } catch {}
     const out = execSync(`ss -ltn 'sport = :${n}' 2>/dev/null || netstat -ltn 2>/dev/null || netstat -an -p tcp 2>/dev/null`, {
-      encoding: 'utf8', timeout: 3000, shell: true,
+      encoding: 'utf8', timeout: 1000, shell: true,
     });
     return new RegExp(`(?:[:.])${n}\\b[^\\n]*\\b(?:LISTEN|LISTENING)\\b`, 'i').test(out);
   } catch { return false; }
@@ -152,7 +152,6 @@ async function checkRestartHealth(options = {}) {
     dashboardKind = 'process';
     const dpid = normalizePid(dashboardPid);
     const dashAlive = dpid ? isAlive(dpid) : false;
-    const portOpen = portCheck(dashboardPort);
     // Ownership gate (opt-in via requireBeaconOwner). "PID alive + port
     // listening" is NOT sufficient: a stale pre-restart dashboard still holding
     // the port satisfies the listening probe, so the verifier used to report
@@ -174,6 +173,10 @@ async function checkRestartHealth(options = {}) {
       beaconPid = beacon && normalizePid(beacon.pid);
       beaconOwned = !!(beacon && beaconPid === dpid && Number(beacon.port) === Number(dashboardPort));
     }
+    // If the beacon already confirms this PID owns the port, skip the expensive
+    // netstat — the dashboard writes dashboard-port.json in its listen() callback,
+    // so beacon.pid === dpid IS the port-bind signal.
+    const portOpen = (options.requireBeaconOwner && beaconOwned) ? true : portCheck(dashboardPort);
     dashboardOk = !!(dashAlive && portOpen && beaconOwned);
     dashboardDetail = `pid=${dpid || 'none'} alive=${dashAlive ? 'yes' : 'no'} port=${dashboardPort} listening=${portOpen ? 'yes' : 'no'}`
       + (options.requireBeaconOwner ? ` beaconPid=${beaconPid || 'none'} owned=${beaconOwned ? 'yes' : 'no'}` : '');

package/engine/shared.js

@@ -975,6 +975,19 @@ function _routeJsonReadToSql(p) {
  * reads (cooldowns, archived PRDs, ephemeral session state) where reviving a
  * stale `.backup` is actively harmful. See its JSDoc for selection guidance.
  */
+
+// PL-prd-no-backup (W-mqub65ez0004b3bd) — archived PRDs under prd/archive/ are
+// permanently removed terminal artifacts. They must NOT auto-restore from a
+// stale `.backup` sidecar (W-mouptdh1000h9f39: archived PRD came back and
+// re-dispatched work). Intentionally NARROW to prd/archive/ only:
+//   - prd/archive/*.json → no backup write + no safeJson restore
+//   - prd/*.json (root-level canonical)  → normal backup/restore lifecycle
+//     preserved so concurrent-sweep loss is recoverable (prd-rename-race.test.js).
+const _NO_BACKUP_JSON_RE = /(?:^|[\\/])prd[\\/]archive[\\/][^\\/]+\.json$/i;
+function _isNoBackupJsonPath(p) {
+  return typeof p === 'string' && _NO_BACKUP_JSON_RE.test(p);
+}
+
 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
@@ -1008,6 +1021,8 @@ function safeJson(p) {
       console.error(`[safeJson] parse failure for ${path.basename(p)}: ${parseErr.message}`);
     }
   }
+  // Archived PRDs (prd/archive/) are permanently gone — skip .backup restore.
+  if (_isNoBackupJsonPath(p)) return null;
   // Primary missing or corrupted — try restoring from .backup sidecar.
   const backupPath = p + '.backup';
   try {
@@ -1837,9 +1852,14 @@ function mutateJsonFileLocked(filePath, mutateFn, {
     const finalData = next === undefined ? data : next;
     const shouldWrite = !skipWriteIfUnchanged || parsedInvalid || JSON.stringify(finalData) !== beforeSerialized;
     if (shouldWrite) {
-      // Back up last-known-good state before mutation (best-effort)
-      const backupPath = filePath + '.backup';
-      try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
+      // Back up last-known-good state before mutation (best-effort). SKIP for
+      // archived PRDs under prd/archive/: a .backup there is resurrection fuel
+      // (PL-prd-no-backup, W-mqub65ez0004b3bd). Root-level prd/*.json retains
+      // the backup lifecycle — concurrent-sweep loss must be recoverable.
+      if (!_isNoBackupJsonPath(filePath)) {
+        const backupPath = filePath + '.backup';
+        try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
+      }
       safeWrite(filePath, finalData);
       // Side-effect hook fired only when an actual write happened. Callers
       // use this to emit cache-invalidation signals (events table row) so

package/engine.js

@@ -6121,8 +6121,9 @@ function materializePlansAsWorkItems(config) {
         continue; // Skip — waiting for human approval
       }
     }
-    if (planStatus === PLAN_STATUS.PAUSED || planStatus === PLAN_STATUS.REJECTED || planStatus === PLAN_STATUS.REVISION_REQUESTED) {
-      continue; // Skip — paused or revision requested
+    if (planStatus === PLAN_STATUS.PAUSED || planStatus === PLAN_STATUS.REJECTED ||
+        planStatus === PLAN_STATUS.REVISION_REQUESTED || planStatus === PLAN_STATUS.COMPLETED) {
+      continue; // Skip — paused, rejected, revision-requested, or completed
     }
     // Stale PRDs: source plan was revised — don't materialize NEW items until user regenerates
     if (plan.planStale) {
@@ -6700,7 +6701,7 @@ async function discoverFromPrs(config, project) {
     ? (config.engine?.adoPollEnabled ?? ENGINE_DEFAULTS.adoPollEnabled)
     : (config.engine?.ghPollEnabled ?? ENGINE_DEFAULTS.ghPollEnabled));
   const evalLoopEnabled = config.engine?.evalLoop !== false;
-  const fixThrottled = isAdoProject ? isAdoThrottled() : isGhThrottled();
+  const fixThrottled = isAdoProject ? isAdoThrottled(shared.getAdoOrgBase(project)) : isGhThrottled();
   const autoReviewPrs = config.engine?.autoReviewPrs ?? ENGINE_DEFAULTS.autoReviewPrs;
   const autoReReviewPrs = config.engine?.autoReReviewPrs ?? ENGINE_DEFAULTS.autoReReviewPrs;
   // P-b2e5d8c7: engine.autoFixPaused is a hard-stop master switch over every

package/package.json

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