@yemi33/minions 0.1.1613 → 0.1.1615

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1615 (2026-04-29)
+
+### Features
+- harden publish workflow cleanup (#1850)
+- isolate unit test state (#1847)
+- clarify ado tooling guidance (#1838)
+
+### Fixes
+- recover ===ACTIONS=== JSON from fences and trailing prose (#1834) (#1837)
+
 ## 0.1.1613 (2026-04-28)
 
 ### Features

package/README.md

@@ -276,7 +276,7 @@ When you run `minions add <dir>`, it prompts for project details and saves them
 
 **Key fields:**
 - `description` — critical for auto-routing. Agents read this to decide which repo to work in.
-- `repoHost` — `"ado"` (Azure DevOps) or `"github"`. Controls which MCP tools agents use for PR creation, review comments, and status checks. Defaults to `"ado"`.
+- `repoHost` — `"ado"` (Azure DevOps) or `"github"`. Controls which repo-host tooling agents use for PR creation, review comments, and status checks. Defaults to `"ado"`.
 - `repositoryId` — required for ADO (the repo GUID), optional for GitHub.
 - `adoOrg` — ADO organization or GitHub org/user.
 - `adoProject` — ADO project name (leave blank for GitHub).
@@ -302,17 +302,17 @@ All detected values are shown as defaults in the interactive prompts — just pr
 
 When dispatching agents, the engine reads each project's `CLAUDE.md` and injects it into the agent's system prompt as "Project Conventions". This means agents automatically follow repo-specific rules (logging, build commands, coding style, etc.) without needing to discover them each time. Each project can have different conventions.
 
-## MCP Server Integration
+## Repo Host Tooling
 
-Agents need MCP tools to interact with your repo host (create PRs, post review comments, etc.). Agents inherit MCP servers directly from `~/.claude.json` as Claude Code processes — add servers there and they're immediately available to all agents on next spawn.
+Agents need repo-host tooling to create PRs, post review comments, check status, and handle review feedback. GitHub repos use `gh`. Azure DevOps repos should use the `az` CLI first and keep the Azure DevOps MCP server available only as a fallback when `az` is unavailable or does not support the required operation.
 
-**Example:** If you use Azure DevOps, configure the `azure-ado` MCP server in your Claude Code settings. If you use GitHub, configure the `github` MCP server. Agents will discover and use whichever tools are available.
+Agents inherit MCP servers directly from `~/.claude.json` as Claude Code processes — add fallback servers there and they're immediately available to all agents on next spawn.
 
 Manually refresh with `minions mcp-sync`.
 
 ### Azure DevOps Users
 
-For the best experience with ADO repos, install the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) and use the [Azure DevOps MCP server](https://github.com/microsoft/azure-devops-mcp). This gives agents full access to PRs, work items, repos, and pipelines via MCP tools — no `gh` CLI needed.
+For the best experience with ADO repos, install the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) with the Azure DevOps extension. Agents should use the `az` CLI first for Azure DevOps operations such as PR creation, PR lookup, comments, reviewers, work items, and pipelines. Use the Azure DevOps MCP fallback only when `az` is unavailable in the environment or insufficient for a specific action.
 
 ```bash
 # Install Azure CLI
@@ -320,12 +320,13 @@ winget install Microsoft.AzureCLI   # Windows
 brew install azure-cli               # macOS
 curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash  # Linux
 
-# Login and set defaults
+# Install/enable the Azure DevOps extension, then login and set defaults
+az extension add --name azure-devops
 az login
 az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT
 ```
 
-Then add the ADO MCP server to your Claude Code settings (`~/.claude.json`). The engine will auto-sync it to all agents on next start.
+Optionally add the [Azure DevOps MCP server](https://github.com/microsoft/azure-devops-mcp) to your Claude Code settings (`~/.claude.json`) as a fallback. The engine will auto-sync it to all agents on next start.
 
 ## Work Items
 

package/dashboard/js/command-center.js

@@ -623,6 +623,11 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
         if (evt.actions && evt.actions.length > 0) {
           _tagServerExecuted(evt.actions, evt.actionResults);
           for (var ai = 0; ai < evt.actions.length; ai++) { await ccExecuteAction(evt.actions[ai], activeTabId); }
+        } else if (evt.actionParseError) {
+          // Issue #1834: server saw ===ACTIONS=== but couldn't parse the JSON.
+          // Surface as an inline warning so the user knows actions were dropped
+          // (was previously silent — appeared as "actions failed" with no signal).
+          addMsg('system', '<div style="padding:6px 12px;font-size:11px;color:var(--red);background:var(--surface2);border-radius:6px;margin:4px 0">⚠️ Actions block emitted but JSON could not be parsed — no actions were executed. Resend or rephrase. (' + escHtml(String(evt.actionParseError).slice(0, 200)) + ')</div>', false, activeTabId);
         }
       } else if (evt.type === 'error') {
         terminalEventSeen = true;

package/dashboard/js/utils.js

@@ -454,18 +454,51 @@ function _renderMdChunked(fullText) {
 
 function openBugReport() {
   document.getElementById('modal-title').textContent = 'Report a Bug';
-  document.getElementById('modal-body').innerHTML =
-    '<div style="display:flex;flex-direction:column;gap:12px">' +
-      '<p style="color:var(--muted);font-size:12px;margin:0">File a bug on the Minions repo (yemi33/minions).</p>' +
-      '<label style="color:var(--text);font-size:var(--text-md)">Title' +
-        '<input id="bug-title" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text)" placeholder="Short description of the bug"></label>' +
-      '<label style="color:var(--text);font-size:var(--text-md)">Description' +
-        '<textarea id="bug-desc" rows="6" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);resize:vertical;font-family:inherit" placeholder="Steps to reproduce, expected vs actual behavior..."></textarea></label>' +
-      '<div style="display:flex;justify-content:flex-end;gap:8px">' +
-        '<button onclick="closeModal()" class="pr-pager-btn">Cancel</button>' +
-        '<button onclick="submitBugReport()" style="padding:6px 16px;background:var(--red);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer">File Bug</button>' +
-      '</div>' +
-    '</div>';
+  var modalBody = document.getElementById('modal-body');
+  var container = document.createElement('div');
+  container.style.cssText = 'display:flex;flex-direction:column;gap:12px';
+  var intro = document.createElement('p');
+  intro.style.cssText = 'color:var(--muted);font-size:12px;margin:0';
+  intro.textContent = 'File a bug on the Minions repo (yemi33/minions).';
+
+  var titleLabel = document.createElement('label');
+  titleLabel.style.cssText = 'color:var(--text);font-size:var(--text-md)';
+  titleLabel.appendChild(document.createTextNode('Title'));
+  var titleInput = document.createElement('input');
+  titleInput.id = 'bug-title';
+  titleInput.style.cssText = 'display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text)';
+  titleInput.placeholder = 'Short description of the bug';
+  titleLabel.appendChild(titleInput);
+
+  var descLabel = document.createElement('label');
+  descLabel.style.cssText = 'color:var(--text);font-size:var(--text-md)';
+  descLabel.appendChild(document.createTextNode('Description'));
+  var descInput = document.createElement('textarea');
+  descInput.id = 'bug-desc';
+  descInput.rows = 6;
+  descInput.style.cssText = 'display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);resize:vertical;font-family:inherit';
+  descInput.placeholder = 'Steps to reproduce, expected vs actual behavior...';
+  descLabel.appendChild(descInput);
+
+  var actions = document.createElement('div');
+  actions.style.cssText = 'display:flex;justify-content:flex-end;gap:8px';
+  var cancelBtn = document.createElement('button');
+  cancelBtn.className = 'pr-pager-btn';
+  cancelBtn.textContent = 'Cancel';
+  cancelBtn.onclick = closeModal;
+  var submitBtn = document.createElement('button');
+  submitBtn.id = 'bug-submit';
+  submitBtn.style.cssText = 'padding:6px 16px;background:var(--red);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer';
+  submitBtn.textContent = 'File Bug';
+  submitBtn.onclick = submitBugReport;
+  actions.appendChild(cancelBtn);
+  actions.appendChild(submitBtn);
+
+  container.appendChild(intro);
+  container.appendChild(titleLabel);
+  container.appendChild(descLabel);
+  container.appendChild(actions);
+  modalBody.replaceChildren(container);
   document.getElementById('modal').classList.add('open');
 }
 
@@ -475,7 +508,7 @@ async function submitBugReport() {
   if (!title) { alert('Title is required'); return; }
 
   // Show progress inside the modal
-  var btn = document.querySelector('#modal button[onclick="submitBugReport()"]');
+  var btn = document.getElementById('bug-submit') || document.querySelector('#modal button[onclick="submitBugReport()"]');
   if (btn) { btn.disabled = true; btn.textContent = 'Filing...'; }
 
   try {
@@ -487,13 +520,40 @@ async function submitBugReport() {
     if (!res.ok) throw new Error(d.error || 'Failed');
 
     // Show success inside the modal
-    document.getElementById('modal-body').innerHTML =
-      '<div style="padding:24px;text-align:center">' +
-        '<div style="font-size:32px;margin-bottom:12px">&#128027;</div>' +
-        '<div style="color:var(--green);font-weight:600;margin-bottom:8px">Bug filed!</div>' +
-        (d.url ? '<a href="' + escHtml(d.url) + '" target="_blank" style="color:var(--blue);font-size:13px">View issue on GitHub</a>' : '<span style="color:var(--muted);font-size:12px">Issue created on yemi33/minions</span>') +
-        '<div style="margin-top:16px"><button onclick="closeModal()" style="padding:6px 16px;background:var(--surface2);border:1px solid var(--border);border-radius:var(--radius-sm);cursor:pointer;color:var(--text)">Close</button></div>' +
-      '</div>';
+    var modalBody = document.getElementById('modal-body');
+    var container = document.createElement('div');
+    container.style.cssText = 'padding:24px;text-align:center';
+    var icon = document.createElement('div');
+    icon.style.cssText = 'font-size:32px;margin-bottom:12px';
+    icon.textContent = '\u{1F41B}';
+    var heading = document.createElement('div');
+    heading.style.cssText = 'color:var(--green);font-weight:600;margin-bottom:8px';
+    heading.textContent = 'Bug filed!';
+    container.appendChild(icon);
+    container.appendChild(heading);
+    if (d.url) {
+      var link = document.createElement('a');
+      link.href = safeUrl(d.url);
+      link.target = '_blank';
+      link.rel = 'noopener noreferrer';
+      link.style.cssText = 'color:var(--blue);font-size:13px';
+      link.textContent = 'View issue on GitHub';
+      container.appendChild(link);
+    } else {
+      var msg = document.createElement('span');
+      msg.style.cssText = 'color:var(--muted);font-size:12px';
+      msg.textContent = 'Issue created on yemi33/minions';
+      container.appendChild(msg);
+    }
+    var actions = document.createElement('div');
+    actions.style.marginTop = '16px';
+    var closeBtn = document.createElement('button');
+    closeBtn.style.cssText = 'padding:6px 16px;background:var(--surface2);border:1px solid var(--border);border-radius:var(--radius-sm);cursor:pointer;color:var(--text)';
+    closeBtn.textContent = 'Close';
+    closeBtn.onclick = closeModal;
+    actions.appendChild(closeBtn);
+    container.appendChild(actions);
+    modalBody.replaceChildren(container);
   } catch (e) {
     // Show error inside the modal — let user retry
     if (btn) { btn.disabled = false; btn.textContent = 'File Bug'; }

package/dashboard.js

@@ -758,16 +758,68 @@ function findCCActionsDelimiter(text) {
   return match.index + match[0].indexOf('===ACTIONS===');
 }
 
+// Issue #1834: non-Claude runtimes (Copilot/GPT) routinely wrap the action JSON
+// in ```json fences or append trailing prose ("Let me know if that helps!").
+// JSON.parse on the raw segment fails silently → actions dropped, user sees
+// inert text. This extractor pulls out the balanced JSON value (array or
+// object) regardless of fences, leading whitespace, or trailing junk so the
+// downstream parse can succeed. Returns null if no plausible JSON value is
+// present (caller surfaces the failure via _actionParseError).
+function _extractActionsJson(segment) {
+  if (!segment) return null;
+  let body = segment.trim();
+  // Strip ```json / ``` fences (open + close). The model sometimes only emits
+  // an opening fence (truncation), so handle both halves independently.
+  body = body.replace(/^```[a-zA-Z0-9_-]*\s*\r?\n?/, '').replace(/\r?\n?```\s*$/, '').trim();
+  if (!body) return null;
+  const first = body.indexOf('[');
+  const firstObj = body.indexOf('{');
+  let start = -1;
+  let openCh = '';
+  let closeCh = '';
+  if (first >= 0 && (firstObj < 0 || first <= firstObj)) {
+    start = first; openCh = '['; closeCh = ']';
+  } else if (firstObj >= 0) {
+    start = firstObj; openCh = '{'; closeCh = '}';
+  }
+  if (start < 0) return null;
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  for (let i = start; i < body.length; i++) {
+    const ch = body[i];
+    if (escape) { escape = false; continue; }
+    if (ch === '\\') { escape = true; continue; }
+    if (ch === '"') { inString = !inString; continue; }
+    if (inString) continue;
+    if (ch === openCh) depth++;
+    else if (ch === closeCh) {
+      depth--;
+      if (depth === 0) return body.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
 function parseCCActions(text) {
   let actions = [];
   let displayText = text;
+  let parseError = null;
   const delimIdx = findCCActionsDelimiter(text);
   if (delimIdx >= 0) {
     displayText = text.slice(0, delimIdx).trim();
-    try {
-      const parsed = JSON.parse(text.slice(delimIdx + '===ACTIONS==='.length).trim());
-      actions = Array.isArray(parsed) ? parsed : [parsed];
-    } catch {}
+    const segment = text.slice(delimIdx + '===ACTIONS==='.length);
+    const jsonStr = _extractActionsJson(segment);
+    if (jsonStr) {
+      try {
+        const parsed = JSON.parse(jsonStr);
+        actions = Array.isArray(parsed) ? parsed : [parsed];
+      } catch (e) {
+        parseError = e.message || 'invalid JSON';
+      }
+    } else if (segment.trim()) {
+      parseError = 'no JSON value found after ===ACTIONS=== delimiter';
+    }
   }
   if (actions.length === 0) {
     const actionRegex = /`{3,}\s*action\s*\r?\n([\s\S]*?)`{3,}/g;
@@ -775,9 +827,24 @@ function parseCCActions(text) {
     while ((match = actionRegex.exec(displayText)) !== null) {
       try { actions.push(JSON.parse(match[1].trim())); } catch {}
     }
-    if (actions.length > 0) displayText = displayText.replace(/`{3,}\s*action\s*\r?\n[\s\S]*?`{3,}\n?/g, '').trim();
+    if (actions.length > 0) {
+      displayText = displayText.replace(/`{3,}\s*action\s*\r?\n[\s\S]*?`{3,}\n?/g, '').trim();
+      parseError = null; // legacy fallback recovered actions
+    }
   }
-  return { text: displayText, actions };
+  const result = { text: displayText, actions };
+  if (parseError && actions.length === 0) {
+    result._actionParseError = parseError;
+    // Visibility for the engine log — silent failure here previously masked issue #1834.
+    try {
+      const snippet = (text.slice(delimIdx + '===ACTIONS==='.length).trim() || '').slice(0, 200);
+      console.warn(`[CC] action JSON parse failed (${parseError}); raw segment: ${snippet}`);
+      if (typeof shared !== 'undefined' && shared && typeof shared.log === 'function') {
+        shared.log('warn', `CC action JSON parse failed: ${parseError} — segment: ${snippet}`);
+      }
+    } catch { /* logging is best-effort */ }
+  }
+  return result;
 }
 
 // ── /loop → create-watch safety net ──────────────────────────────────────────
@@ -4382,7 +4449,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         if (parsed.actions.length > 0) {
           parsed.actionResults = await executeCCActions(parsed.actions);
         }
-        const reply = { ...parsed, sessionId: ccSession.sessionId, newSession: !wasResume };
+        // Issue #1834: rename _actionParseError → actionParseError (public field)
+        // so the client can surface a warning when the model emitted ===ACTIONS===
+        // but the JSON couldn't be recovered.
+        const { _actionParseError, ...parsedReply } = parsed;
+        const reply = { ...parsedReply, sessionId: ccSession.sessionId, newSession: !wasResume };
+        if (_actionParseError) reply.actionParseError = _actionParseError;
         if (sessionReset) reply.sessionReset = true;
         return jsonReply(res, 200, reply);
       } finally {
@@ -4639,7 +4711,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         }
 
         // Send final result with actions — execute server-side first
-        const { text: displayText, actions } = parseCCActions(result.text);
+        const { text: displayText, actions, _actionParseError } = parseCCActions(result.text);
         // Safety net: detect /loop invocation and convert to create-watch
         const _loopWatch = _detectLoopInvocation(displayText, actions, toolUses);
         if (_loopWatch) {
@@ -4652,6 +4724,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           actionResults = await executeCCActions(actions);
         }
         const donePayload = { type: 'done', text: displayText, actions, actionResults, sessionId: responseSessionId, newSession: !wasResume };
+        // Issue #1834: surface action JSON parse failures so the UI can warn
+        // instead of silently dropping. Client renders this as a small notice.
+        if (_actionParseError) donePayload.actionParseError = _actionParseError;
         if (sessionReset) donePayload.sessionReset = true;
         liveState.donePayload = donePayload;
         if (liveState.writer) liveState.writer(donePayload);

package/engine/copilot-models.json

@@ -0,0 +1,5 @@
+{
+  "runtime": "copilot",
+  "models": null,
+  "cachedAt": "2026-04-29T00:02:27.565Z"
+}

package/engine/pipeline.js

@@ -8,12 +8,22 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
-const { safeJson, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, ENGINE_DEFAULTS } = shared;
+const { safeJson, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, ENGINE_DEFAULTS, MINIONS_DIR } = shared;
 const http = require('http');
 const { parseCronExpr, shouldRunNow } = require('./scheduler');
 
-const PIPELINES_DIR = path.join(__dirname, '..', 'pipelines');
-const PIPELINE_RUNS_PATH = path.join(__dirname, 'pipeline-runs.json');
+// All module-relative paths flow through MINIONS_DIR so MINIONS_TEST_DIR
+// (set by test/unit.test.js createTestMinionsDir) consistently redirects
+// pipeline writes into the temp root instead of the live runtime root.
+const PIPELINES_DIR = path.join(MINIONS_DIR, 'pipelines');
+const PIPELINE_RUNS_PATH = path.join(MINIONS_DIR, 'engine', 'pipeline-runs.json');
+const CENTRAL_WI_PATH = path.join(MINIONS_DIR, 'work-items.json');
+const MEETINGS_DIR = path.join(MINIONS_DIR, 'meetings');
+const PLANS_DIR = path.join(MINIONS_DIR, 'plans');
+const PRD_DIR = path.join(MINIONS_DIR, 'prd');
+const NOTES_INBOX_DIR = path.join(MINIONS_DIR, 'notes', 'inbox');
+const NOTES_ARCHIVE_DIR = path.join(MINIONS_DIR, 'notes', 'archive');
+const CONFIG_PATH = path.join(MINIONS_DIR, 'config.json');
 
 function truncatePipelineContext(text, maxBytes, label) {
   return shared.truncateTextBytes(text, maxBytes, `\n\n_...${label} truncated — inspect the upstream artifacts if needed._`);
@@ -213,7 +223,7 @@ function evaluateCondition(condition, ctx) {
     case 'noFailedItems': {
       // True when all work items created by the pipeline are done (not failed)
       if (!run) return false;
-      const wiPath = path.join(__dirname, '..', 'work-items.json');
+      const wiPath = CENTRAL_WI_PATH;
       const workItems = safeJson(wiPath) || [];
       const allProjectWi = shared.getProjects(config).reduce((acc, p) => {
         return acc.concat(safeJson(shared.projectWorkItemsPath(p)) || []);
@@ -284,7 +294,7 @@ function executeTaskStage(stage, stageState, run, config) {
   // Create work item(s) for the task
   const items = stage.items || [{ title: stage.title, description: stage.description || '', type: stage.taskType || 'explore', agent: stage.agent }];
   const count = stage.count || items.length;
-  const wiPath = path.join(__dirname, '..', 'work-items.json');
+  const wiPath = CENTRAL_WI_PATH;
   const createdIds = [];
 
   mutateWorkItems(wiPath, workItems => {
@@ -352,7 +362,7 @@ function _findExistingPlanForMeeting(meetingIds, plansDir) {
   // Build slug prefixes for both pipeline and dashboard naming conventions
   const slugPrefixes = [];
   for (const mid of meetingIds) {
-    const mtg = safeJson(path.join(__dirname, '..', 'meetings', mid + '.json'));
+    const mtg = safeJson(path.join(MEETINGS_DIR, mid + '.json'));
     if (mtg?.title) {
       // Dashboard convention: "Meeting follow-up: {title}" → slug
       const dashSlug = slugify('meeting-follow-up-' + mtg.title);
@@ -383,11 +393,11 @@ function _findExistingPrdForPlan(planFile, prdDir) {
 }
 
 async function executePlanStage(stage, stageState, run, config) {
-  const plansDir = path.join(__dirname, '..', 'plans');
+  const plansDir = PLANS_DIR;
   if (!fs.existsSync(plansDir)) fs.mkdirSync(plansDir, { recursive: true });
 
   const slug = slugify(stage.title || 'pipeline-plan');
-  const wiPath = path.join(__dirname, '..', 'work-items.json');
+  const wiPath = CENTRAL_WI_PATH;
   const wiId = `PL-${run.runId.slice(4, 12)}-${stage.id}-prd`;
 
   // ── Reconciliation: check if a plan already exists for a meeting in this run ──
@@ -398,7 +408,7 @@ async function executePlanStage(stage, stageState, run, config) {
       log('info', `Pipeline ${run.pipelineId}: reconciling plan stage — adopting existing plan "${existingPlanFile}"`);
 
       // Check if a PRD already exists for this plan (skip plan-to-prd entirely)
-      const prdDir = path.join(__dirname, '..', 'prd');
+      const prdDir = PRD_DIR;
       const existingPrdFile = _findExistingPrdForPlan(existingPlanFile, prdDir);
       if (existingPrdFile) {
         log('info', `Pipeline ${run.pipelineId}: PRD "${existingPrdFile}" already exists for plan "${existingPlanFile}" — skipping plan-to-prd`);
@@ -436,7 +446,7 @@ async function executePlanStage(stage, stageState, run, config) {
   let meetingContext = '';
   for (const mid of meetingIds) {
     try {
-      const mtg = safeJson(path.join(__dirname, '..', 'meetings', mid + '.json'));
+      const mtg = safeJson(path.join(MEETINGS_DIR, mid + '.json'));
       if (mtg) {
         const transcript = truncatePipelineContext(
           (mtg.transcript || []).map(formatTranscriptEntry).join('\n\n---\n\n'),
@@ -586,7 +596,7 @@ function executeScheduleStage(stage, stageState, config) {
       config.schedules.push({ ...sched, enabled: true });
     }
   }
-  safeWrite(path.join(__dirname, '..', 'config.json'), config);
+  safeWrite(CONFIG_PATH, config);
   return { status: PIPELINE_STATUS.COMPLETED, completedAt: ts() };
 }
 
@@ -647,7 +657,7 @@ function isStageComplete(stage, stageState, run, config) {
   switch (stage.type) {
     case STAGE_TYPE.TASK: {
       // Check root + all project work-items.json (WIs may be moved to project paths)
-      const wiPath = path.join(__dirname, '..', 'work-items.json');
+      const wiPath = CENTRAL_WI_PATH;
       const workItems = safeJson(wiPath) || [];
       const allProjectWi = shared.getProjects(config).reduce((acc, p) => {
         return acc.concat(safeJson(shared.projectWorkItemsPath(p)) || []);
@@ -671,7 +681,7 @@ function isStageComplete(stage, stageState, run, config) {
     }
     case STAGE_TYPE.PLAN: {
       // Plan stage completion: PRD conversion done + all materialized work items done
-      const wiPath = path.join(__dirname, '..', 'work-items.json');
+      const wiPath = CENTRAL_WI_PATH;
       const workItems = safeJson(wiPath) || [];
       const allProjectWi = shared.getProjects(config).reduce((acc, p) => {
         return acc.concat(safeJson(shared.projectWorkItemsPath(p)) || []);
@@ -687,7 +697,7 @@ function isStageComplete(stage, stageState, run, config) {
       if (!prdDone) return false;
 
       // Discover PRDs and their work items — collect into local arrays, then merge into artifacts
-      const prdDir = path.join(__dirname, '..', 'prd');
+      const prdDir = PRD_DIR;
       const plans = artifacts.plans || [];
       const discoveredPrds = [];
       const discoveredWiIds = [];
@@ -811,7 +821,7 @@ async function discoverPipelineWork(config) {
           // Collect output
           let output = '';
           if (stage.type === STAGE_TYPE.TASK) {
-            const wiPath = path.join(__dirname, '..', 'work-items.json');
+            const wiPath = CENTRAL_WI_PATH;
             const workItems = safeJson(wiPath) || [];
             const projWi = shared.getProjects(config).reduce((acc, p) => acc.concat(safeJson(shared.projectWorkItemsPath(p)) || []), []);
             const allWi = [...workItems, ...projWi];
@@ -830,8 +840,8 @@ async function discoverPipelineWork(config) {
           // Scan for inbox/archive notes created by this stage's agents
           try {
             const notesDirs = [
-              path.join(__dirname, '..', 'notes', 'inbox'),
-              path.join(__dirname, '..', 'notes', 'archive'),
+              NOTES_INBOX_DIR,
+              NOTES_ARCHIVE_DIR,
             ];
             const stageWiIds = stageState.artifacts?.workItems || [];
             const notes = [];
@@ -871,7 +881,7 @@ async function discoverPipelineWork(config) {
           if (nextPlanStage) {
             const meetingIds = _findMeetingsInRun(activeRun);
             if (meetingIds.length > 0) {
-              const plansDir = path.join(__dirname, '..', 'plans');
+              const plansDir = PLANS_DIR;
               if (fs.existsSync(plansDir)) {
                 const existingPlan = _findExistingPlanForMeeting(meetingIds, plansDir);
                 if (existingPlan) {

package/engine/playbook.js

@@ -12,7 +12,7 @@ const queries = require('./queries');
 const { safeJson, safeRead, getProjects, log, ts, dateStamp, truncateTextBytes, ENGINE_DEFAULTS, WI_STATUS, WORK_TYPE, PR_STATUS, DISPATCH_RESULT } = shared;
 const { getConfig, getDispatch, getNotes, getAgentCharter, getPrs, AGENTS_DIR } = queries;
 
-const MINIONS_DIR = path.resolve(__dirname, '..');
+const MINIONS_DIR = shared.MINIONS_DIR;
 const PLAYBOOKS_DIR = path.join(MINIONS_DIR, 'playbooks');
 
 // Import tempAgents from routing module

package/engine/queries.js

@@ -97,6 +97,10 @@ function timeSince(ms) {
   return `${Math.floor(s / 3600)}h ago`;
 }
 
+function readJsonNoRestore(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
+}
+
 // ── Core State Readers ──────────────────────────────────────────────────────
 
 let _configPollKeyMigrationChecked = false;
@@ -146,7 +150,7 @@ function getConfig() {
 }
 
 function getControl() {
-  return safeJson(CONTROL_PATH) || { state: 'stopped', pid: null };
+  return readJsonNoRestore(CONTROL_PATH) || { state: 'stopped', pid: null };
 }
 
 let _dispatchCache = null;
@@ -155,7 +159,7 @@ function getDispatch() {
   // Short-lived cache — dispatch.json is read 10+ times per tick but only changes on mutateDispatch
   const now = Date.now();
   if (_dispatchCache && (now - _dispatchCacheAt) < 2000) return _dispatchCache;
-  _dispatchCache = safeJson(DISPATCH_PATH) || { pending: [], active: [], completed: [] };
+  _dispatchCache = readJsonNoRestore(DISPATCH_PATH) || { pending: [], active: [], completed: [] };
   _dispatchCacheAt = now;
   return _dispatchCache;
 }
@@ -165,7 +169,7 @@ function getDispatchQueue() {
   const d = getDispatch();
   const allCompleted = d.completed || [];
   // Lifetime total from metrics (dispatch.completed is capped at 100)
-  const metrics = safeJson(path.join(ENGINE_DIR, 'metrics.json')) || {};
+  const metrics = readJsonNoRestore(path.join(ENGINE_DIR, 'metrics.json')) || {};
   d.completedTotal = Object.entries(metrics).filter(([k]) => !k.startsWith('_')).reduce((sum, [, m]) => sum + (m.tasksCompleted || 0) + (m.tasksErrored || 0), 0);
   d.completed = allCompleted.slice(-20);
   return d;
@@ -194,7 +198,7 @@ function getEngineLog() {
 }
 
 function getMetrics() {
-  const metrics = safeJson(path.join(ENGINE_DIR, 'metrics.json')) || {};
+  const metrics = readJsonNoRestore(path.join(ENGINE_DIR, 'metrics.json')) || {};
 
   for (const [agentId, m] of Object.entries(metrics)) {
     if (agentId.startsWith('_')) continue;
@@ -234,8 +238,10 @@ function getMetrics() {
   }
 
   // Apply enrichments to agent metrics
-  for (const [agentId, m] of Object.entries(metrics)) {
+  for (const [agentId, existing] of Object.entries(metrics)) {
     if (agentId.startsWith('_')) continue;
+    const m = { ...DEFAULT_AGENT_METRICS, ...(existing && typeof existing === 'object' ? existing : {}) };
+    metrics[agentId] = m;
     const lower = agentId.toLowerCase();
     if (prCountByAgent[lower] !== undefined) {
       m.prsCreated = prCountByAgent[lower];
@@ -474,7 +480,7 @@ function getAgentDetail(id) {
 
 function getPrs(project) {
   if (project) {
-    const prs = safeJson(projectPrPath(project)) || [];
+    const prs = readJsonNoRestore(projectPrPath(project)) || [];
     shared.normalizePrRecords(prs, project);
     return prs;
   }
@@ -510,7 +516,7 @@ function getPullRequests(config) {
   for (const dirName of projectDirs) {
     const project = projectByName.get(dirName) || null;
     const prPath = project ? projectPrPath(project) : path.join(MINIONS_DIR, 'projects', dirName, 'pull-requests.json');
-    const prs = safeJson(prPath);
+    const prs = readJsonNoRestore(prPath);
     if (!Array.isArray(prs)) continue;
     shared.normalizePrRecords(prs, project);
     const base = project?.prUrlBase || '';
@@ -527,7 +533,7 @@ function getPullRequests(config) {
     }
   }
   // Central pull-requests.json — manually linked PRs without a project
-  const centralPrs = safeJson(path.join(MINIONS_DIR, 'pull-requests.json'));
+  const centralPrs = readJsonNoRestore(path.join(MINIONS_DIR, 'pull-requests.json'));
   if (centralPrs) {
     shared.normalizePrRecords(centralPrs, null);
     for (const pr of centralPrs) {
@@ -1023,7 +1029,7 @@ function getPrdInfo(config) {
           if (cached && cached.mtimeMs === stat.mtimeMs) {
             plan = cached.plan;
           } else {
-            plan = safeJson(filePath);
+            plan = readJsonNoRestore(filePath);
             _prdFileCache.set(filePath, { mtimeMs: stat.mtimeMs, plan });
           }
           if (!plan || !plan.missing_features) continue;
@@ -1068,13 +1074,13 @@ function getPrdInfo(config) {
   const wiById = {};
   for (const project of projects) {
     try {
-      const workItems = safeJson(projectWorkItemsPath(project)) || [];
+      const workItems = readJsonNoRestore(projectWorkItemsPath(project)) || [];
       for (const wi of workItems) { if (!wi?.id) { console.warn(`[queries] Skipping work item without id in ${project.name}:`, JSON.stringify(wi).slice(0, 120)); continue; } if (wi.sourcePlan) wiById[wi.id] = wi; }
     } catch { /* optional */ }
   }
   // Also check central work-items.json
   try {
-    const centralWi = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
+    const centralWi = readJsonNoRestore(path.join(MINIONS_DIR, 'work-items.json')) || [];
     for (const wi of centralWi) { if (!wi?.id) { console.warn('[queries] Skipping central work item without id:', JSON.stringify(wi).slice(0, 120)); continue; } if (wi.sourcePlan && !wiById[wi.id]) wiById[wi.id] = wi; }
   } catch { /* optional */ }
 

package/engine/routing.js

@@ -11,7 +11,7 @@ const queries = require('./queries');
 const { safeJson, safeRead, log, ts } = shared;
 const { ENGINE_DIR, DISPATCH_PATH } = queries;
 
-const MINIONS_DIR = path.resolve(__dirname, '..');
+const MINIONS_DIR = shared.MINIONS_DIR;
 const ROUTING_PATH = path.join(MINIONS_DIR, 'routing.md');
 
 // ─── Temp Agents ─────────────────────────────────────────────────────────────
@@ -117,16 +117,16 @@ function setTempBudget(n) {
 function getTempBudget() { return _tempBudget; }
 
 function normalizeAgentHints(agentHints, authorAgent = null) {
-  const raw = Array.isArray(agentHints) ? agentHints : (agentHints ? [agentHints] : []);
+  const raw = Array.isArray(agentHints) ? agentHints : (agentHints ? String(agentHints).split(',') : []);
   return raw
-    .map(id => id === '_author_' ? authorAgent : id)
-    .map(id => typeof id === 'string' ? id.trim().toLowerCase() : '')
+    .map(id => String(id).trim().toLowerCase())
+    .map(id => id === '_author_' && authorAgent ? String(authorAgent).trim().toLowerCase() : id)
     .filter(Boolean);
 }
 
 function resolveAgent(workType, config, authorAgent = null, agentHints = null) {
   const routes = getRoutingTableCached();
-  const route = routes[workType] || routes['implement'];
+  const route = routes[workType] || routes['implement'] || { preferred: '_any_', fallback: '_any_' };
   const agents = config.agents || {};
 
   // Resolve _author_ token

package/engine/scheduler.js

@@ -26,7 +26,7 @@ const path = require('path');
 const shared = require('./shared');
 const { safeJson, safeWrite, mutateJsonFileLocked, ts, dateStamp, WI_STATUS } = shared;
 
-const SCHEDULE_RUNS_PATH = path.join(__dirname, 'schedule-runs.json');
+const SCHEDULE_RUNS_PATH = path.join(shared.MINIONS_DIR, 'engine', 'schedule-runs.json');
 
 /**
  * Substitute schedule-time template variables in a string.

package/engine/shared.js

@@ -1099,8 +1099,8 @@ function trackReviewMetric(pr, newReviewStatus, config) {
   const authorId = (pr.agent || '').toLowerCase();
   if (!authorId || !config?.agents?.[authorId]) return;
   try {
-    mutateJsonFileLocked(path.join(__dirname, 'metrics.json'), (metrics) => {
-      if (!metrics[authorId]) metrics[authorId] = {};
+    mutateJsonFileLocked(path.join(MINIONS_DIR, 'engine', 'metrics.json'), (metrics) => {
+      if (!metrics[authorId]) metrics[authorId] = { ...DEFAULT_AGENT_METRICS };
       if (newReviewStatus === 'approved') metrics[authorId].prsApproved = (metrics[authorId].prsApproved || 0) + 1;
       else metrics[authorId].prsRejected = (metrics[authorId].prsRejected || 0) + 1;
       return metrics;
@@ -1110,7 +1110,10 @@ function trackReviewMetric(pr, newReviewStatus, config) {
 
 /** Queue a plan-to-prd work item with dedup check inside lock. Returns true if queued. */
 function queuePlanToPrd({ planFile, prdFile, title, description, project, createdBy, extra }) {
-  const centralWiPath = path.join(__dirname, '..', 'work-items.json');
+  // Use MINIONS_DIR (honors MINIONS_TEST_DIR override) instead of resolving from
+  // __dirname — otherwise tests that exercise this helper leak work items into
+  // the real package-root work-items.json even after createTestMinionsDir().
+  const centralWiPath = path.join(MINIONS_DIR, 'work-items.json');
   let queued = false;
   mutateJsonFileLocked(centralWiPath, items => {
     if (!Array.isArray(items)) items = [];

package/minions.js

@@ -462,6 +462,7 @@ async function initMinions({ skipScan = false, scanRoot, scanDepth } = {}) {
   const config = loadConfig();
   if (!config.projects) config.projects = [];
   const removedPlaceholders = cleanupPlaceholderProjects(config);
+  const hadConfiguredDefaultCli = config.engine?.defaultCli !== undefined;
   // Merge defaults — fills in new fields from upgrades while preserving user customizations
   if (!config.engine) config.engine = {};
   for (const [k, v] of Object.entries(ENGINE_DEFAULTS)) {
@@ -479,7 +480,7 @@ async function initMinions({ skipScan = false, scanRoot, scanDepth } = {}) {
   // Auto-detect available runtime CLIs and pin engine.defaultCli to whichever
   // is installed. Only set if the user hasn't already configured one — never
   // overwrite an explicit choice on `init --force` upgrades.
-  if (!config.engine.defaultCli) {
+  if (!hadConfiguredDefaultCli) {
     const detected = _detectAvailableRuntimes();
     if (detected.length === 1) {
       config.engine.defaultCli = detected[0];
@@ -579,4 +580,3 @@ if (cmd && commands[cmd]) {
   console.log('                            cleans worktrees, archives data dir to projects/.archived/');
   console.log('    list                    List linked projects\n');
 }
-

package/package.json

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

package/playbooks/explore.md

@@ -59,7 +59,7 @@ Use subagents only for genuinely parallel, independent tasks. For reading files,
 
 ## Rules
 - Do NOT modify existing code unless the task explicitly asks for it.
-- Use the appropriate MCP tools for PR creation — check available tools before starting.
+- Use the appropriate repo-host tooling for PR creation. For Azure DevOps, prefer the `az` CLI first and use ADO MCP only as a fallback when `az` is unavailable or insufficient.
 - Do NOT checkout branches in the main working tree — use worktrees.
 - Read `notes.md` for all team rules before starting.
 - Only emit a ```skill block if you uncovered a durable reusable workflow that is not already documented and is likely to help future tasks; zero skills is the default, and one-off findings belong in the inbox notes instead.

package/playbooks/fix.md

@@ -72,7 +72,7 @@ After pushing, respond to each review comment/thread:
 - **If you fixed it**: Reply confirming the fix, then resolve the thread
 - **If you chose not to fix it**: Reply with your rationale explaining why the current approach is preferred — leave the thread open for the reviewer to decide
 - **GitHub**: Reply to each review comment, resolve conversations you've fixed
-- **ADO**: Reply to each thread, set status to `fixed` or `closed` for fixes; leave `active` for rationale replies
+- **ADO**: Use `az` CLI first to reply to each thread and update status when supported; use ADO MCP only as a fallback when `az` is unavailable or insufficient. Set status to `fixed` or `closed` for fixes; leave `active` for rationale replies
 
 ## When to Stop
 
@@ -94,4 +94,3 @@ pending: <any remaining work, or none>
 ```
 
 Replace the values with your actual results. This block MUST appear in your final output.
-

package/playbooks/shared-rules.md

@@ -107,3 +107,9 @@ Output is JSON with the same fields. Exit 0 on success, 1 if not found.
 **Never make raw `curl` calls to ADO APIs directly.** Use `node engine/ado-status.js` which routes through `ado.js` — authenticated, retried, circuit-broken. Raw `azureauth` + curl bypasses all of that.
 
 **If you must run `azureauth` directly, ALWAYS include `--timeout 1`.** Without this flag, `azureauth ado token` can hang indefinitely waiting for interactive broker UI that never appears in headless agent sessions. This causes the Claude Code process to silently exit and the engine to declare the agent orphaned. Example: `azureauth ado token --mode iwa --mode broker --output token --timeout 1`.
+
+## Azure DevOps Tooling
+
+For Azure DevOps repo operations, use the `az` CLI first. Prefer commands such as `az repos pr create`, `az repos pr show`, `az repos pr list`, `az repos pr comment`, `az repos pr reviewer`, `az boards work-item`, and `az pipelines` after setting defaults with `az devops configure`.
+
+Use ADO MCP fallback tools (`mcp__azure-ado__*`) only when `az` is unavailable in the environment or insufficient for a specific operation. Do not choose MCP first just because it exists, and do not use `gh` for Azure DevOps repositories.

package/playbooks/verify.md

@@ -111,7 +111,7 @@ For each project worktree:
 
 2. **Check for an existing E2E PR** before creating a new one:
    - For GitHub: `gh pr list --head e2e/{{plan_slug}} --state open`
-   - For ADO: search for PRs with source branch `e2e/{{plan_slug}}`
+   - For ADO: use `az` CLI first to search for PRs with source branch `e2e/{{plan_slug}}`; use ADO MCP only as a fallback when `az` is unavailable or insufficient
    - If found, **update the existing PR** description with latest build/test results. Do NOT create a duplicate.
    - If not found, create a new PR targeting the project's main branch:
      - **Title:** `[E2E] <plan summary>`

package/prompts/cc-system.md

@@ -52,6 +52,8 @@ When in doubt, delegate. You are the dispatcher, not the worker. Agents have iso
 ## Actions
 Append actions at the END of your response. Write your response first, then `===ACTIONS===` on its own line, then a JSON array. No text after the JSON. Omit entirely if no actions needed.
 
+**CRITICAL — emit RAW JSON only.** Do NOT wrap the JSON array in ```json fences, ``` fences, or any other markdown. Do NOT add commentary or "Let me know if that helps" lines after the JSON. The JSON array must start with `[` on the line immediately after `===ACTIONS===` and end with `]` as the very last character of the response. Anything else (fences, prose, trailing commas) breaks server-side action parsing and your actions will be silently dropped.
+
 Example:
 I'll dispatch dallas to fix that bug.