@yemi33/minions 0.1.2297 → 0.1.2299

package/dashboard.js

@@ -11444,25 +11444,19 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
   // W-mq03l6zh0006f0a1-d — read-only diagnostics surface for the per-org ADO
   // throttle tracker. Returns { orgs: { [orgBase]: { throttled, retryAfter,
-  // consecutiveHits } } }. Prefers the per-org getter ado.getAdoThrottleStateAll
-  // when present (introduced by W-mq03l6zh0006f0a1-b). Falls back to the
-  // process-global ado.getAdoThrottleState() under the synthetic key `global`
-  // when the per-org getter is not present, so the endpoint stays live across
-  // the staged rollout of the per-org isolation work.
+  // consecutiveHits } } }. Uses getAdoThrottleState().perOrg, the per-org map
+  // exposed by the aggregate getter (W-mq03l6zh0006f0a1-b).
   async function handleDiagnosticsAdoThrottle(req, res) {
     try {
       let orgs = {};
-      if (typeof ado.getAdoThrottleStateAll === 'function') {
-        const all = ado.getAdoThrottleStateAll() || {};
+      if (typeof ado.getAdoThrottleState === 'function') {
+        const all = ado.getAdoThrottleState().perOrg || {};
         // Defensive copy — handler must never expose internal mutable state.
         for (const [k, v] of Object.entries(all)) {
           if (v && typeof v === 'object') {
             orgs[k] = { throttled: !!v.throttled, retryAfter: Number(v.retryAfter) || 0, consecutiveHits: Number(v.consecutiveHits) || 0 };
           }
         }
-      } else if (typeof ado.getAdoThrottleState === 'function') {
-        const v = ado.getAdoThrottleState() || {};
-        orgs.global = { throttled: !!v.throttled, retryAfter: Number(v.retryAfter) || 0, consecutiveHits: Number(v.consecutiveHits) || 0 };
       }
       return jsonReply(res, 200, { orgs });
     } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }

package/docs/completion-reports.md

@@ -81,6 +81,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `noop` | boolean | Canonical no-op signal. See [No-op semantics](#no-op-semantics). |
 | `noopReason` | string | Human-readable rationale shown when `noop: true`. Falls back to `summary` if absent. |
 | `files_changed` | string \| array | Comma-separated list (or array) of key files changed. |
+| `affected_files` | string[] | Optional array of relative file paths this dispatch touched or plans to touch. Used by the dispatcher to emit a conflict warning (`WI <new-id> may conflict with in-progress <existing-id> on files: [list]`) when a new WI's `affected_files` overlaps with an in-progress WI's `affected_files`. Logging-only — dispatch is never blocked. Stored back onto the work item after completion so re-dispatches can also participate in overlap detection. |
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
 | `pending` | string | Any remaining work, or `none`. |
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |

package/engine/ado.js

@@ -2683,14 +2683,6 @@ const getAdoThrottleState = (orgBase) => {
   return { throttled, retryAfter, consecutiveHits, perOrg };
 };
 
-/** Returns the per-org tracker state map keyed by canonical orgBase. */
-const getAdoThrottleStateAll = () => {
-  const out = {};
-  for (const [key, tracker] of _adoThrottlesByOrg) {
-    out[key] = tracker.getState();
-  }
-  return out;
-};
 
 /**
  * Query ADO for an open PR on a specific branch.
@@ -2955,7 +2947,6 @@ module.exports = {
   _setAdoTokenAuthNoteWriterForTest, // exported for testing
   isAdoThrottled,
   getAdoThrottleState,
-  getAdoThrottleStateAll,
   fetchAdoPrMetadata,
   prExists, // issue #246 — confirm a loose ref points at a PR (not a work item) before stamping
   fetchSinglePrBuildStatus,

package/engine/dispatch.js

@@ -166,6 +166,36 @@ function getBranchDispatchLockKey(entry) {
   return `${projectKey}:${normalizedBranch}`;
 }
 
+// ─── File-Overlap Conflict Detection (P-mqyp000ab028c9d0) ───────────────────
+//
+// Logging-only warning surfaced when a new WI declares affected_files that
+// overlap with files declared by a currently in-progress (active) WI. No
+// blocking — dispatch always proceeds. Goal: surface silent parallel edit
+// races before they become merge conflicts.
+
+function _getItemAffectedFiles(dispatchItem) {
+  const files = dispatchItem?.meta?.item?.affected_files;
+  if (!Array.isArray(files) || files.length === 0) return null;
+  const set = new Set(files.filter(f => typeof f === 'string' && f.length > 0));
+  return set.size > 0 ? set : null;
+}
+
+// Called inside addToDispatch (before push) to emit one log line per active
+// dispatch that shares at least one file with the incoming item.
+function _warnFileOverlap(newItem, activeDispatches) {
+  const newFiles = _getItemAffectedFiles(newItem);
+  if (!newFiles) return;
+  const newWiId = newItem.meta?.item?.id || newItem.id;
+  for (const existing of activeDispatches) {
+    const existingFiles = _getItemAffectedFiles(existing);
+    if (!existingFiles) continue;
+    const overlap = [...newFiles].filter(f => existingFiles.has(f));
+    if (overlap.length === 0) continue;
+    const existingWiId = existing.meta?.item?.id || existing.id;
+    log('warn', `WI ${newWiId} may conflict with in-progress ${existingWiId} on files: ${overlap.join(', ')}`);
+  }
+}
+
 function findActivePrOrBranchLock(dispatch, item) {
   const active = dispatch.active || [];
 
@@ -238,6 +268,7 @@ function addToDispatch(item) {
       log('info', `Dedup: skipping ${item.id} — ${activeLock.reason} already in ${activeLock.existing.id}`);
       return dispatch;
     }
+    _warnFileOverlap(item, dispatch.active || []);
     dispatch.pending.push(item);
     added = true;
     return dispatch;

package/engine/lifecycle.js

@@ -495,25 +495,25 @@ function checkPlanCompletion(meta, config) {
 function archivePlan(planFile, plan, projects, config) {
   const planPath = path.join(PRD_DIR, planFile);
 
-  // Archive PRD .json to prd/archive/
-  const prdArchiveDir = path.join(PRD_DIR, 'archive');
-  if (!fs.existsSync(prdArchiveDir)) fs.mkdirSync(prdArchiveDir, { recursive: true });
+  // Phase 10 — archive the PRD IN PLACE: flag it (archived/status/archivedAt)
+  // where it sits, rather than MOVING it to prd/archive/. This matches the
+  // canonical dashboard (_archivePrdPostProcess, #533) + watch-action archive
+  // paths. The legacy move was the LAST path still physically relocating a PRD,
+  // and it reintroduced the live↔archive basename-collision class (footgun #7)
+  // that the in-place flag model retired — plus it needed a .backup neutralize
+  // that is moot now that prd/*.json never gets a .backup sidecar at all (#570).
+  // mutateJsonFileLocked dual-writes the flag into SQL via the chokepoint; the
+  // archived-PRD scanner guards (#530) already treat status:'archived' correctly.
   try {
     if (fs.existsSync(planPath)) {
-      // DATA-LOSS GUARD: moveFileNoClobber dedupes + retries so a same-basename
-      // collision can't silently overwrite a previously-archived PRD (+ its
-      // completed work-item history). renameSync clobbers on Windows.
-      const prdDest = shared.moveFileNoClobber(planPath, prdArchiveDir, planFile);
-      log('info', `Archived completed PRD: prd/archive/${path.basename(prdDest)}`);
-    }
-    // Remove .backup sidecar — if left behind, safeJson() would restore the pre-completion
-    // snapshot (status: approved, no _completionNotified) on engine restart, re-triggering
-    // plan completion and spawning duplicate verify tasks for already-archived plans.
-    // On Windows, the unlink can fail due to file locking; overwrite with archived status
-    // as a fallback so a restored backup is inert even if deletion fails.
-    const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
-    if (!backupCleanup.ok) {
-      log('warn', `Archive backup cleanup failed for ${planFile}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`);
+      mutateJsonFileLocked(planPath, (data) => {
+        if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
+        data.status = 'archived';
+        data.archived = true;
+        data.archivedAt = new Date().toISOString();
+        return data;
+      }, { defaultValue: {} });
+      log('info', `Archived PRD in place: ${planFile} (archived flag set)`);
     }
   } catch (err) {
     log('warn', `Failed to archive PRD ${planFile}: ${err.message}`);
@@ -777,6 +777,27 @@ function updateWorkItemStatus(meta, status, reason) {
   syncPrdItemStatus(itemId, status, meta.item?.sourcePlan);
 }
 
+// P-mqyp000ab028c9d0 — persist affected_files from a completion report onto the
+// work item for future file-overlap checks. Runs only when the completion report
+// declares a non-empty string[] for `affected_files`; no-ops otherwise.
+function storeAffectedFilesFromCompletion(meta, structuredCompletion) {
+  const raw = structuredCompletion?.affected_files;
+  if (!Array.isArray(raw) || raw.length === 0) return;
+  const files = raw.filter(f => typeof f === 'string' && f.length > 0);
+  if (files.length === 0) return;
+  const itemId = meta?.item?.id;
+  if (!itemId) return;
+  const wiPath = resolveWorkItemPath(meta);
+  if (!wiPath) return;
+  mutateJsonFileLocked(wiPath, (items) => {
+    if (!Array.isArray(items)) return items;
+    const target = items.find(i => i.id === itemId);
+    if (!target) return items;
+    target.affected_files = files;
+    return items;
+  }, { skipWriteIfUnchanged: true });
+}
+
 const _VALID_PRD_STATUSES = new Set([...Object.values(WI_STATUS), 'missing']);
 // (#984) PRD statuses that are stale when the work item is actually done
 const _STALE_PRD_STATUSES = new Set([WI_STATUS.DISPATCHED, WI_STATUS.FAILED, WI_STATUS.PENDING]);
@@ -3586,24 +3607,25 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeN
 function updateAgentHistory(agentId, dispatchItem, result) {
 
   const historyPath = path.join(AGENTS_DIR, agentId, 'history.md');
-  let history = safeRead(historyPath) || '# Agent History\n\n';
   const entry = `### ${ts()} — ${result}\n` +
     `- **Task:** ${dispatchItem.task}\n` +
     `- **Type:** ${dispatchItem.type}\n` +
     `- **Project:** ${dispatchItem.meta?.project?.name || 'central'}\n` +
     `- **Branch:** ${dispatchItem.meta?.branch || 'none'}\n` +
     `- **Dispatch ID:** ${dispatchItem.id}\n\n`;
-  const headerEnd = history.indexOf('\n\n');
-  if (headerEnd >= 0) {
-    history = history.slice(0, headerEnd + 2) + entry + history.slice(headerEnd + 2);
-  } else {
-    history += entry;
-  }
-  const entries = history.split('### ').filter(Boolean);
-  const header = entries[0].startsWith('#') ? entries.shift() : '# Agent History\n\n';
-  const trimmed = entries.slice(0, 20);
-  history = header + trimmed.map(e => '### ' + e).join('');
-  shared.safeWrite(historyPath, history);
+  shared.mutateTextFileLocked(historyPath, (history) => {
+    history = history || '# Agent History\n\n';
+    const headerEnd = history.indexOf('\n\n');
+    if (headerEnd >= 0) {
+      history = history.slice(0, headerEnd + 2) + entry + history.slice(headerEnd + 2);
+    } else {
+      history += entry;
+    }
+    const entries = history.split('### ').filter(Boolean);
+    const header = entries[0].startsWith('#') ? entries.shift() : '# Agent History\n\n';
+    const trimmed = entries.slice(0, 20);
+    return header + trimmed.map(e => '### ' + e).join('');
+  }, { defaultValue: '# Agent History\n\n' });
   log('info', `Updated history for ${agentId}`);
 }
 
@@ -5426,6 +5448,10 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       meta._noopReason = noopRationale.slice(0, 500);
     }
     updateWorkItemStatus(meta, WI_STATUS.DONE, '');
+    // P-mqyp000ab028c9d0 — persist affected_files from the completion report
+    // onto the work item so future dispatches of the same WI can participate in
+    // the file-overlap conflict detection in dispatch.js#_warnFileOverlap.
+    try { storeAffectedFilesFromCompletion(meta, structuredCompletion); } catch (err) { log('warn', `storeAffectedFilesFromCompletion: ${err.message}`); }
     // W-mqtplpk6001oe6d5 — back-stamp workItemId onto the PRD item now that WI is done.
     if (meta.item.sourcePlan) {
       try { stampPrdItemWorkItemId(meta.item.id, meta.item.sourcePlan); } catch (err) { log('warn', `stampPrdItemWorkItemId: ${err.message}`); }

package/engine.js

@@ -5661,7 +5661,7 @@ function reconcileItemsWithPrs(items, allPrs, { onlyIds } = {}) {
 // ─── Inbox Consolidation (extracted to engine/consolidation.js) ──────────────
 
 const { consolidateInbox } = require('./engine/consolidation');
-const { pollPrStatus, pollPrHumanComments, reconcilePrs, checkLiveReviewStatus: adoCheckLiveReview, checkLiveBuildAndConflict: adoCheckLiveBuildAndConflict, needsAdoPollRetry, getAdoToken, isAdoThrottled, getAdoThrottleStateAll } = require('./engine/ado');
+const { pollPrStatus, pollPrHumanComments, reconcilePrs, checkLiveReviewStatus: adoCheckLiveReview, checkLiveBuildAndConflict: adoCheckLiveBuildAndConflict, needsAdoPollRetry, getAdoToken, isAdoThrottled, getAdoThrottleState } = require('./engine/ado');
 const { pollPrStatus: ghPollPrStatus, pollPrHumanComments: ghPollPrHumanComments, reconcilePrs: ghReconcilePrs, checkLiveReviewStatus: ghCheckLiveReview, checkLiveBuildAndConflict: ghCheckLiveBuildAndConflict, isGhThrottled } = require('./engine/github');
 const { reconcileSharedBranchPrs } = require('./engine/shared-branch-pr-reconcile');
 
@@ -5762,15 +5762,6 @@ function safePrdProjectSlug(projectName) {
   return slug || 'project';
 }
 
-function safePrdFilenameForProject(projectName, suffix) {
-  const fileName = `${safePrdProjectSlug(projectName)}-${suffix}.json`;
-  const resolved = shared.sanitizePath(fileName, PRD_DIR);
-  if (path.dirname(resolved) !== path.resolve(PRD_DIR)) {
-    throw new Error('invalid PRD filename: nested paths are not allowed');
-  }
-  return path.basename(resolved);
-}
-
 /**
  * Atomically reserve a unique PRD filename in `prdDir` (P-9b7e5d3c).
  *
@@ -9779,7 +9770,7 @@ async function tickInner() {
       // Per-org throttle skip happens inside forEachActivePr (one log line per skipped project).
       // Top-level short-circuit: when every known ADO org is throttled, skip the whole phase
       // with one log line to avoid the per-project iteration cost.
-      const adoThrottleStates = getAdoThrottleStateAll() || {};
+      const adoThrottleStates = getAdoThrottleState().perOrg || {};
       const adoOrgCount = Object.keys(adoThrottleStates).length;
       const allAdoThrottled = adoOrgCount > 0 && Object.values(adoThrottleStates).every(s => s && s.throttled);
       if (allAdoThrottled) {
@@ -9859,7 +9850,7 @@ async function tickInner() {
       // Per-org throttle skip happens inside forEachActivePr (one log line per skipped project).
       // Top-level short-circuit: when every known ADO org is throttled, skip the whole phase
       // with one log line to avoid the per-project iteration cost.
-      const adoThrottleStates = getAdoThrottleStateAll() || {};
+      const adoThrottleStates = getAdoThrottleState().perOrg || {};
       const adoOrgCount = Object.keys(adoThrottleStates).length;
       const allAdoThrottled = adoOrgCount > 0 && Object.values(adoThrottleStates).every(s => s && s.throttled);
       if (allAdoThrottled) {
@@ -10570,7 +10561,7 @@ module.exports = {
 
   // Shared helpers (used by lifecycle.js and tests)
   reconcileItemsWithPrs, detectDependencyCycles,
-  safePrdProjectSlug, safePrdFilenameForProject, // exported for testing (W-mqyn7joo0004079f)
+  safePrdProjectSlug, // exported for testing (W-mqyn7joo0004079f)
   isSoftFixDispatch, // exported for testing (W-mqyn7joo0004079f)
   areDependenciesMet, // exported for testing (P-bf04-decompose-zero-children)
   parseConflictFiles, pruneAncestorDeps, preflightMergeSimulation, // exported for testing

package/package.json

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